`symmetrize_tklib.py` 技術ドキュメント

プログラムの動作

このプログラム symmetrize_tklib.py は、Crystallographic Information File (CIF) 形式で記述された結晶構造データを受け取り、その構造の持つ対称性を解析し、対称化された結晶構造情報を新しいCIFファイルとして出力します。

主な機能:

指定されたCIFファイルを読み込みます（tklib と pymatgen ライブラリを使用）。
pymatgen.symmetry.analyzer.SpacegroupAnalyzer を用いて、入力構造の空間群を特定し、関連するすべての対称操作を導出します。
特定された空間群に基づいて、原子位置を等価なサイトの平均として調整し、格子定数を対称性に合わせて修正することで、構造を対称化します。
解析結果の詳細（特定された空間群の名前と番号、格子定数、単位胞の体積、導出された対称操作の数、等価サイトの原子情報、すべての原子サイト情報）を標準出力およびログファイルに出力します。
対称化された結晶構造情報を、CIF形式で新しいファイルに保存します。

解決する課題: 実験的なノイズや計算上の微小なずれにより、理想的な結晶構造の対称性からわずかに逸脱したデータに対して、その構造を理想的な対称性を持つ形に「対称化」します。これにより、結晶構造データの整合性を高め、後の詳細な解析、視覚化、またはデータベースへの登録を容易にします。

原理

プログラムは、物質科学計算のための強力なPythonライブラリである pymatgen の SpacegroupAnalyzer クラスを核心的なツールとして利用しています。

空間群の特定: SpacegroupAnalyzer は、入力された結晶構造（pymatgen.core.structure.Structure オブジェクト）を解析し、設定された許容誤差の範囲内でその構造が持つ最も適切な空間群を特定します。空間群は、結晶が持つ並進、回転、鏡映などのすべての対称操作の集合を指します。
対称化された構造の生成: SpacegroupAnalyzer.get_symmetrized_structure() メソッドは、特定された空間群の対称要素に基づいて、入力構造を対称化します。このプロセスには以下のステップが含まれます。
1. 等価サイトの同定: 空間群の対称操作によって互いに変換可能な原子サイトを特定し、これらを「等価サイトのグループ」として分類します。
2. 原子位置の平均化: 各等価サイトグループ内で、原子の分数座標を平均化します。これにより、原子は理想的な対称位置に配置され、微小な非対称性が除去されます。
3. 格子定数の調整: 空間群の対称性が格子定数に特定の制約を課す場合（例：立方晶では $a=b=c$、直交晶では $\alpha=\beta=\gamma=90^\circ$）、これらの制約に合わせて格子定数も調整されることがあります。
対称操作の表現: pymatgen における対称操作は、3x3の回転行列 $M$ と3x1の並進ベクトル $\mathbf{t}$ からなるアフィン変換として内部的に表現されます。これにより、結晶学的なサイト $\mathbf{r}$ は新しいサイト $T(\mathbf{r})$ に変換されます。 $$T(\mathbf{r}) = M\mathbf{r} + \mathbf{t}$$ プログラムでは、これらの対称操作をCIFファイルに記述する際に、例えば $(x, y, z)$ が $(x+1/2, y-1/4, -z)$ に変換されるような形式の文字列に変換するカスタム関数（to_str, vector_to_str, matrix_to_str）が実装されています。これにより、CIFの _symmetry_equiv_pos_as_xyz 項目に人間が読みやすい表記で出力されます。

必要な非標準ライブラリとインストール方法

このプログラムの実行には、以下の非標準Pythonライブラリが必要です。

pymatgen: 物質科学計算のためのオープンソースライブラリ。
tklib: このプログラムが利用しているカスタムライブラリ（tklib.tkapplication, tklib.tkutils, tklib.tkfile, tklib.tkcrystal.tkcif など）。

pymatgen は pip コマンドでインストールできます。

pip install pymatgen

tklib は一般的に公開されているPyPIパッケージではないため、通常はプロジェクトに同梱されているか、開発元から別途提供される必要があります。もし tklib が通常の pip install でインストールできない場合は、開発元から提供される指示に従ってください。例えば、Gitリポジトリからクローンして手動でインストールする、あるいはPythonのパスを通じてモジュールを認識させる必要があるかもしれません。

必要な入力ファイル

ファイル名: プログラムの最初のコマンドライン引数で指定されたCIFファイル。引数が省略された場合、デフォルトで SrTiO3.cif が使用されます。
形式: Crystallographic Information File (CIF) 形式。
- 結晶構造情報（格子定数、原子のタイプ、分数座標、占有率など）が記述されている必要があります。
- 最低限、_cell_length_a から _cell_angle_gamma までのセル情報と、_atom_site_type_symbol, _atom_site_fract_x, _atom_site_fract_y, _atom_site_fract_z などを含む原子サイト情報が必要です。

CIFファイルの例 (SrTiO3.cif の一部):

data_SrTiO3
_audit_creation_date              2023-01-01
_chemical_formula_structural      'SrTiO3'
_chemical_formula_sum             'Sr1 Ti1 O3'
_cell_formula_units_Z             1

_cell_length_a                    3.905
_cell_length_b                    3.905
_cell_length_c                    3.905
_cell_angle_alpha                 90.000
_cell_angle_beta                  90.000
_cell_angle_gamma                 90.000

loop_
 _atom_site_label
 _atom_site_type_symbol
 _atom_site_fract_x
 _atom_site_fract_y
 _atom_site_fract_z
 _atom_site_occupancy
Sr1 Sr 0.00000 0.00000 0.00000 1.00000
Ti1 Ti 0.50000 0.50000 0.50000 1.00000
O1  O  0.50000 0.50000 0.00000 1.00000

生成される出力ファイル

プログラムは以下の2種類のファイルを生成します。

ログファイル:
- ファイル名: 入力CIFファイル名が filename.cif の場合、filename-out.txt となります。
- 内容: プログラムの実行中に標準出力に表示されるすべての情報が記録されます。これには、入力ファイル名、出力ファイル名、pymatgen による構造解析の詳細、特定された空間群情報、対称化後の格子情報、対称操作の数、等価サイトおよびすべての原子サイトの座標などが含まれます。
対称化されたCIFファイル:
- ファイル名: 入力CIFファイル名が filename.cif の場合、filename-symmetrized.cif となります。
- 内容: pymatgen によって対称化された結晶構造の情報がCIF形式で記述されます。具体的には以下の情報が含まれます。
  - data_ ブロック名（元のファイル名に由来）。
  - 対称化された構造から得られた格子定数 (_cell_length_a から _cell_angle_gamma) と単位胞の体積 (_cell_volume)。
  - 特定された空間群の名前 (_symmetry_space_group_name_H-M) と国際表番号 (_symmetry_Int_Tables_number)。
  - 元の構造から引き継がれる化学式 (_chemical_formula_structural, _chemical_formula_sum) と単位胞あたりの化学式単位数 (_cell_formula_units_Z)。
  - pymatgen が特定した空間群のすべての対称操作のリスト (loop_, _symmetry_equiv_pos_site_id, _symmetry_equiv_pos_as_xyz)。
  - 対称化された構造の非等価な原子サイトのリスト (loop_, _atom_site_type_symbol, _atom_site_fract_x, _atom_site_fract_y, _atom_site_fract_z, _atom_site_occupancy)。原子位置は等価サイトの平均化によって調整されています。

コマンドラインでの使用例 (Usage)

プログラムは、Pythonインタープリタを使用して実行されます。入力CIFファイル名をコマンドライン引数として指定できます。

基本形式:

python symmetrize_tklib.py [input_cif_file]

[input_cif_file]: 解析対象のCIFファイルのパス。省略した場合、デフォルトで SrTiO3.cif が使用されます。

コマンドラインでの具体的な使用例

ここでは、SrTiO3.cif というファイルが現在のディレクトリに存在することを前提とします。

例1: デフォルトの入力ファイルを使用する場合

入力ファイル名を指定せずに実行すると、プログラムはデフォルトで SrTiO3.cif を読み込みます。

python symmetrize_tklib.py

実行結果の説明:

このコマンドを実行すると、以下のような動作をします。

現在のディレクトリにある SrTiO3.cif が入力ファイルとして使用されます。
SrTiO3-out.txt というログファイルが生成され、標準出力と同じ内容が記録されます。
SrTiO3-symmetrized.cif というファイルが生成され、SrTiO3.cif の構造が pymatgen によって対称化された結果がCIF形式で保存されます。
標準出力には、入力ファイル名、ログファイル名、出力ファイル名、pymatgen による構造解析結果（空間群情報、格子定数、体積、対称操作の数、等価サイトの原子情報、すべてのサイトの原子情報）が表示されます。

標準出力の例（一部）:

Open logfile [./SrTiO3-out.txt]

input : SrTiO3.cif
log file: ./SrTiO3-out.txt
output symmetrized CIF file: ./SrTiO3-symmetrized.cif

Read [SrTiO3.cif] for tkCIF
... (tkCIFによる読み込み結果の表示) ...

Read [SrTiO3.cif] for pymatgen
Structure: Full Formula (Sr1 Ti1 O3)
Reduced Formula: SrTiO3
abc: 3.905 3.905 3.905
angles: 90.0 90.0 90.0
volume: 59.489125
Sites: (5)
  Sr @ [0, 0, 0]
  Ti @ [0.5, 0.5, 0.5]
  O @ [0.5, 0.5, 0]
  O @ [0.5, 0, 0.5]
  O @ [0, 0.5, 0.5]

Symmetrized:
Space group:  Pm-3m 221
Number of symmetry options: 48

Lattice: 
  Lattice parameters: 3.905 3.905 3.905 90.0 90.0 90.0
  Matrix:  [[3.905 0.0 0.0] [0.0 3.905 0.0] [0.0 0.0 3.905]]
  Volume:  59.489125

Equivalent sites:
   Sr [0.0, 0.0, 0.0]   occ= 1.0
   Ti [0.5, 0.5, 0.5]   occ= 1.0
   O [0.5, 0.5, 0.0]   occ= 1.0

All sites:
   Sr [0.0, 0.0, 0.0]   occ= 1.0
   Ti [0.5, 0.5, 0.5]   occ= 1.0
   O [0.5, 0.5, 0.0]   occ= 1.0
   O [0.5, 0.0, 0.5]   occ= 1.0
   O [0.0, 0.5, 0.5]   occ= 1.0

Save the symmetrized structure to [./SrTiO3-symmetrized.cif]
Press any key to terminate...

生成される SrTiO3-symmetrized.cif の例（一部）:

data_SrTiO3.cif
_cell_length_a     3.90500000
_cell_length_b     3.90500000
_cell_length_c     3.90500000
_cell_angle_alpha  90.00000000
_cell_angle_beta   90.00000000
_cell_angle_gamma  90.00000000
_cell_volume       59.48912500

_symmetry_space_group_name_H-M  'Pm-3m'
_symmetry_Int_Tables_number     221
_chemical_formula_structural  SrTiO3
_chemical_formula_sum         Sr1 Ti1 O3
_cell_formula_units_Z   1

loop_
 _symmetry_equiv_pos_site_id
 _symmetry_equiv_pos_as_xyz
  1  'x, y, z'
  2  '-x, -y, -z'
  3  '-x, y, -z'
  4  'x, -y, z'
... (48個の対称操作が続く) ...

loop_
 _atom_site_type_symbol
 _atom_site_fract_x
 _atom_site_fract_y
 _atom_site_fract_z
 _atom_site_occupancy
 Sr    0.00000000  0.00000000  0.00000000  1.0
 Ti    0.50000000  0.50000000  0.50000000  1.0
 O     0.50000000  0.50000000  0.00000000  1.0

例2: 別の入力ファイル名を指定する場合

例えば、my_crystal.cif というファイルがある場合。

python symmetrize_tklib.py my_crystal.cif