# ``symmetrize_tklib.py`` ドキュメント

## 概要

``symmetrize_tklib.py`` は、``pymatgen`` と ``tklib`` という2つのPythonライブラリを組み合わせて使用し、結晶構造データを含むCIFファイルを対称化し、その結果を新しいCIFファイルとして保存するスクリプトです。

このスクリプトは、入力されたCIFファイルを読み込み、``pymatgen`` の ``SpacegroupAnalyzer`` を利用して結晶構造の対称性を解析します。対称化された構造からは、空間群情報、格子定数、原子サイトの情報が抽出されます。その後、抽出された情報は ``tklib`` の ``tkFile`` モジュールを用いて、特定のフォーマットで新しいCIFファイル (``{filebody}-symmetrized.cif``) として出力されます。

``pymatgen`` の強力な対称性解析機能を活用しつつ、``tklib`` のデータ構造と連携して出力を生成するハイブリッドなアプローチを採用しており、材料科学分野での結晶構造解析ワークフローに貢献することを目的としています。

## 非標準ライブラリ

このスクリプトは以下の非標準ライブラリに依存しています。

*   ``pymatgen``
    *   ``pymatgen.io.cif.CifParser``
    *   ``pymatgen.symmetry.analyzer.SpacegroupAnalyzer``
    *   ``pymatgen.core.structure.Structure``
    *   ``pymatgen.core.lattice.Lattice``
    *   ``pymatgen.core.periodic_table.Element``
*   ``tklib``
    *   ``tklib.tkapplication.tkApplication``
    *   ``tklib.tkutils`` (``terminate``, ``pint``, ``pfloat``, ``getarg``, ``getintarg``, ``getfloatarg`` などの関数がインポートされているが、本スクリプトでは ``getarg`` 系の関数は使用されていない。)
    *   ``tklib.tkfile.tkFile``
    *   ``tklib.tkcrystal.tkcif.tkCIF``

## コマンドライン引数

スクリプトは、コマンドライン引数として入力CIFファイル名を1つ受け付けることができます。

*   第一引数: 入力するCIFファイルのパス。

引数が指定されない場合、デフォルトの入力ファイル名である ``SrTiO3.cif`` が使用されます。

例:
```bash
python symmetrize_tklib.py my_structure.cif

入出力ファイル

入力

入力CIFファイル:
- 変数名: infile
- デフォルト値: SrTiO3.cif
- コマンドライン引数で指定可能。
- tkCIF.ReadCIF() および Structure.from_file() メソッドによって読み込まれます。

出力

ログファイル:
- ファイル名: 入力CIFファイル名から {filebody}-out.txt の形式で生成されます。例えば、SrTiO3.cif の場合は SrTiO3-out.txt。
- 生成場所: 入力CIFファイルと同じディレクトリ。
- 内容: スクリプトの実行中に標準出力に出力されるすべてのメッセージがこのファイルにも書き込まれます。
対称化されたCIFファイル:
- ファイル名: 入力CIFファイル名から {filebody}-symmetrized.cif の形式で生成されます。例えば、SrTiO3.cif の場合は SrTiO3-symmetrized.cif。
- 生成場所: 入力CIFファイルと同じディレクトリ。
- 内容: pymatgen によって対称化された結晶構造の空間群情報、格子定数、原子サイト情報がCIF形式で記述されます。

主要な関数

`main()`

メインプログラムのエントリーポイントです。CIFファイルを読み込み、対称化し、結果を出力する一連の処理を実行します。

詳細説明:
1. ログファイルパスと出力CIFファイルパスを決定し、標準出力とログファイルへの出力リダイレクトを設定します。
2. tkCIF を使用して入力CIFファイルを読み込み、基本的な結晶情報を取得します。読み込みに失敗した場合はスクリプトを終了します。
3. pymatgen.Structure.from_file() メソッドを使用して、再度入力CIFファイルを読み込み、pymatgen.Structure オブジェクトを生成します。
4. 生成された pymatgen.Structure オブジェクトを pymatgen.symmetry.analyzer.SpacegroupAnalyzer に渡し、結晶構造の対称性を解析します。
5. 解析結果から、対称化された Structure オブジェクト、空間群名、空間群番号、対称操作行列、格子パラメータ (a, b, c, alpha, beta, gamma)、体積、および等価サイトの情報を抽出します。
6. 抽出された情報（格子定数、空間群情報、原子サイトの分数座標と占有率）を基に、手動でCIF形式のテキストを構築し、新しいCIFファイル ({filebody}-symmetrized.cif) に保存します。
7. ファイル書き込み後、スクリプトは一時停止して終了します。
引数: なし
戻り値: None

内部関数

`to_str(v)`

浮動小数点数をCIF形式の分数の文字列に変換するヘルパー関数です。

詳細説明:
- 入力された浮動小数点数 v を評価し、特定の分数表現（例: 1/2, -1/3）に変換します。
- 0.0 の場合は None を返します。
- 1.0 や -1.0 の場合は + や - を返します。
- 0.5, -0.5, 0.25, -0.25, 1/3, -1/3, 2/3, -2/3, 1/6, -1/6, 5/6, -5/6 に近い値は、それぞれ対応する分数文字列に変換されます。
- 上記のいずれにも該当しない場合、または特定の条件を満たさない場合は、入力値をそのまま文字列として返します。
引数:
- v (float): 変換する浮動小数点数。
戻り値:
- Optional[str]: 変換された文字列、または 0.0 の場合は None、変換できない場合は元の値。

`vector_to_str(v)`

3DベクトルをCIF形式の対称操作文字列（例: 'x', 'x+y', '-x+z'）に変換するヘルパー関数です。

詳細説明:
- 入力された3要素の浮動小数点数ベクトル v の各要素を to_str() 関数で変換します。
- 変換された各要素に対応する 'x', 'y', 'z' を連結し、対称操作を表す文字列を生成します。
- 例えば、ベクトル [1, 0, 0] は 'x' に、[0, 1, 0] は 'y' に、[0, 0, -1] は '-z' に、[1, 1, 0] は 'x+y' に変換されます。
- 先頭に付く '+' 記号は除去されます。
引数:
- v (List[float]): 3要素の浮動小数点数ベクトル。
戻り値:
- str: 対称操作を表す文字列。

`matrix_to_str(m)`

3x3行列をCIF形式の対称操作文字列のタプル（'x'成分、'y'成分、'z'成分）に変換するヘルパー関数です。

詳細説明:
- 入力された3x3の浮動小数点数行列 m の各行（3Dベクトル）を vector_to_str() 関数に渡します。
- それぞれの変換結果をタプル (x, y, z) として返します。
- この関数は、CIFファイルの _symmetry_equiv_pos_as_xyz エントリの 'x, y, z' 部分を生成するために使用されます。
引数:
- m (List[List[float]]): 3x3の浮動小数点数行列。
戻り値:
- Tuple[str, str, str]: 'x'、'y'、'z'成分を表す文字列のタプル。

処理フロー

symmetrize_tklib.py の主な処理フローは以下の通りです。

スクリプト起動時、コマンドライン引数 (sys.argv) から入力CIFファイル名を取得します。引数が与えられなかった場合、デフォルト値 SrTiO3.cif が使用されます。
tklib.tkapplication.tkApplication のインスタンス app を初期化します。
ログファイルのパス ({filebody}-out.txt) を決定し、標準出力とログファイルへ出力をリダイレクトします。
出力用の対称化CIFファイルのパス ({filebody}-symmetrized.cif) を決定します。
tklib.tkcrystal.tkcif.tkCIF を使用して入力CIFファイルを読み込み、tkCrystal のデータ構造を取得します。読み込みに失敗した場合は、エラーメッセージを出力しスクリプトを終了します。
pymatgen.core.structure.Structure.from_file() を使用して、同じ入力CIFファイルから pymatgen の Structure オブジェクトを生成します。
生成した pymatgen.Structure オブジェクトを用いて pymatgen.symmetry.analyzer.SpacegroupAnalyzer を初期化し、結晶構造の対称性を解析します。
analyzer.get_symmetrized_structure() メソッドで対称化された Structure オブジェクトを取得し、そのオブジェクトから空間群名、空間群番号、対称操作のリスト、格子パラメータ (a, b, c, alpha, beta, gamma)、体積、および等価サイトの情報を抽出します。
tklib.tkfile.tkFile を使用して、新しい対称化CIFファイル ({filebody}-symmetrized.cif) を書き込みモードで開きます。ファイルオープンに失敗した場合は、エラーメッセージを出力しスクリプトを終了します。
抽出した格子定数、空間群情報、化学式などのヘッダ情報をCIF形式で出力ファイルに書き込みます。
抽出した対称操作のリストに対し、matrix_to_str() を用いてCIF形式の _symmetry_equiv_pos_as_xyz エントリとして出力ファイルに書き込みます。
抽出した等価サイトの原子情報（元素記号、分数座標、占有率）をCIF形式の _atom_site_type_symbol, _atom_site_fract_x, _atom_site_fract_y, _atom_site_fract_z, _atom_site_occupancy エントリとして出力ファイルに書き込みます。
出力ファイルを閉じます。
最終的に app.terminate(pause = True) を呼び出し、スクリプトの実行を一時停止してから終了します。

エラーハンドリング

このスクリプトは以下のエラーハンドリングを含みます。

入力CIFファイルの読み込み失敗:
- tkCIF.ReadCIF() が None を返した場合、app.terminate() を呼び出してエラーメッセージを表示し、exit() でスクリプトを終了します。
出力CIFファイルの書き込み失敗:
- tkFile() で出力ファイルをオープンできなかった場合、app.terminate() を呼び出してエラーメッセージを表示し、スクリプトを終了します。
スクリプト終了時の一時停止:
- スクリプトの実行終了時に、app.terminate(pause = True) が呼び出されます。これにより、プログラムの実行が一時停止し、ユーザーがコンソール出力やエラーメッセージを確認できるようになります。

制限事項

to_str() 関数は、限られた特定の浮動小数点値（0, ±1, ±0.5, ±0.25, ±1/3, ±2/3, ±1/6, ±5/6など）のみを明示的に分数表現に変換します。これら以外の値については、そのまま浮動小数点数の文字列として扱われるか、特定の変換ロジックが適用されない場合があります。
pymatgen の Structure.to() メソッドはコメントアウトされており、このスクリプトでは使用されていません。CIFファイルの出力は tklib のファイル書き込み機能と手動でのCIF形式文字列の構築によって行われています。このため、標準的な pymatgen のCIF出力機能が提供するすべてのメタデータや詳細なフォーマットオプションが網羅されているかはコードからは確認できません。
コードからは、tkCrytal と pymatgen の間でデータ構造の相互変換や同期に関する詳細な制限は確認できません。pymatgen で対称化を行い、その結果を tklib のファイル出力機能でフォーマットして書き出しているため、tklib の内部データ構造が pymatgen の対称化結果と完全に同期しているかはコードからは直接読み取れません。

入出力ファイル

入力

出力

主要な関数

main()

内部関数

to_str(v)

vector_to_str(v)

matrix_to_str(m)