symmetrize_pymatgen.py 技術ドキュメント

プログラムの動作

symmetrize_pymatgen.py は、Pythonで記述されたスクリプトであり、pymatgen ライブラリの機能を利用して結晶構造の対称性を解析し、対称化された構造を新しいCIFファイルとして出力します。

  • 目的: 密度汎関数理論 (DFT) 計算や実験 (例: X線回折) から得られた結晶構造が、数値的な誤差や測定限界によって理想的な空間群対称性からわずかにずれている場合に、それを理想的な対称性を持つ構造に変換することを目的としています。

  • 主な機能:

    • pymatgen がサポートする多様なファイル形式（CIF、POSCARなど）から結晶構造を読み込みます。

    • 指定された許容誤差（symprec）に基づいて構造の空間群を特定し、その空間群の対称操作を適用して原子位置を調整します。

    • 標準出力に、入力構造と対称化後の構造の概要を表示します。

    • 対称化された構造を新しいCIFファイルとして保存します。

  • 解決する課題: 実際の計算や測定で得られる結晶構造は、理想的な結晶構造とはわずかに異なる原子座標や格子パラメータを持つことがあります。このずれは、その構造の真の対称性を曖昧にし、後続の物性計算やデータベース登録において問題を引き起こす可能性があります。本プログラムは、このような構造を厳密な対称性を持つ形に「修正」することで、これらの課題を解決します。

原理

symmetrize_pymatgen.py は、pymatgen ライブラリの SpacegroupAnalyzer クラスを核として、結晶構造の対称化を行います。このプロセスは、以下の主要なステップとアルゴリズムに基づいています。

  1. 構造の読み込み: プログラムは、入力ファイルから結晶構造を pymatgen.core.structure.Structure オブジェクトとして読み込みます。このオブジェクトには、単位格子の情報（格子ベクトル、角度）と、単位格子内の原子の種類およびその分数座標などが含まれます。

  2. 空間群の特定: SpacegroupAnalyzer は、読み込まれた構造に対して、指定された許容誤差 symprec を用いて、その構造が属する空間群を特定します。

    • 許容誤差 symprec: この浮動小数点数値は、原子が対称操作によってどれだけ「ずれていても」同じ位置と見なされるかを決定する閾値です。例えば、2つの原子間の距離が symprec 未満である場合、それらは同じ対称位置にあると見なされることがあります。また、原子の座標が対称操作によって変換された後の位置と、元の構造内の他の原子の位置との距離が symprec 未満であれば、その原子は対称操作の対称位置に存在すると判断されます。

    • アルゴリズム: SpacegroupAnalyzer は、原子の配置、格子パラメータ、単位格子の角度などを分析し、これらの情報と symprec に基づいて、結晶学的に可能な230の空間群のうち、最も適した空間群を探索・同定します。これは、国際結晶学テーブルに記載されている対称操作を仮定し、入力構造がそれらの操作に対してどの程度整合的であるかを評価するプロセスです。

  3. 構造の対称化: 空間群が特定された後、SpacegroupAnalyzer.get_symmetrized_structure() メソッドが呼び出され、構造が対称化されます。

    • 対称操作の適用: 特定された空間群の対称操作（回転、反転、並進など）が構造内のすべての原子に適用されます。

    • 原子位置の調整: 各原子は、その空間群が定義する対称位置の中で、最も近い理想的な位置に微調整（スナップ）されます。これにより、構造全体が厳密な空間群対称性を満たすように再構築されます。例えば、わずかにずれた複数の等価な原子は、一つの理想的な位置に平均化されるか、最も近い理想位置に移動されます。格子パラメータや角度も、その空間群が許容する範囲内で最も対称性の高い値に調整されます（例：立方晶であれば \(a=b=c\)、\(\alpha=\beta=\gamma=90^\circ\)）。

このプロセスにより、入力された構造の数値的な誤差が取り除かれ、結晶学的に厳密な対称性を持つ構造が得られます。

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

このプログラムの実行には、pymatgen ライブラリが必須です。

インストール方法:

Pythonのパッケージ管理ツール pip を使用してインストールできます。

pip install pymatgen

必要な入力ファイル

プログラムは、pymatgen が読み込み可能な結晶構造ファイルを必要とします。

  • ファイル形式: CIF (Crystallographic Information File)、POSCAR (VASP input file)、XYZ、PDBなど、pymatgen がサポートする任意の形式。

  • データ構造: 結晶構造を記述する標準的な形式であれば問題ありません。通常、単位格子の情報（格子定数、角度）と、単位格子内の原子の種類およびその分数座標（または直交座標）が含まれます。

  • 指定方法: コマンドライン引数の最初の要素として、入力ファイルのパスを指定します。

生成される出力ファイル

プログラムは、対称化された結晶構造を記述したCIFファイルを生成します。

  • ファイル名:

    • コマンドライン引数で出力ファイル名を明示的に指定した場合：指定されたファイル名。

    • 出力ファイル名が省略された場合：入力ファイルのパスとファイル名を基に、元のファイル名に -symmetrized.cif を追加した名前になります。 例：入力ファイルが input.cif の場合、出力ファイル名は input-symmetrized.cif。 入力ファイルが /path/to/my_data/structure.poscar の場合、出力ファイル名は /path/to/my_data/structure-symmetrized.cif。

  • 内容:

    • _symmetry_space_group_name_H-M など、空間群に関する情報が追加または更新されます。

    • 原子の座標は、対称化処理によって微調整され、空間群対称性に従った理想的な位置に設定されます。

    • 格子定数や角度も、対称化された空間群に適合するように調整されます。

    • pymatgen の CifWriter によって標準的なCIF形式で記述されます。

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

基本的な実行コマンドと引数の説明は以下の通りです。

python symmetrize_pymatgen.py <input_file> [output_file] [symprec] [pause]

  • <input_file> (必須):

    • 入力とする結晶構造ファイルのパス。CIF、POSCARなどの形式をサポートします。

  • [output_file] (任意):

    • 対称化された構造を保存する出力CIFファイルのパス。

    • 省略した場合、入力ファイル名に基づいて自動的に生成されます（例: input.cif -> input-symmetrized.cif）。

  • [symprec] (任意):

    • 対称性解析に使用する許容誤差（tolerance）。浮動小数点数で指定します。

    • この値が大きいほど、より多くの対称性が（わずかなずれがあっても）許容されやすくなります。

    • デフォルト値は 1.0e-3 (0.001)。

  • [pause] (任意):

    • プログラム終了時に一時停止するかどうかを指定します。整数で指定します。

    • 0 を指定すると、プログラムは処理終了後すぐに終了します（デフォルト）。

    • 1 を指定すると、Press ENTER to terminate>> というメッセージが表示され、Enterキーが押されるまでプログラムが終了しません。

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

ここでは、架空の入力ファイル example.cif を使用した具体的な実行例を示します。

まず、example.cif という名前で以下の内容のファイルを作成します。これは、わずかに歪んだ立方晶の構造を想定しています。

# example.cif
data_example
_symmetry_space_group_name_H-M   'P 1'
_cell_length_a                   3.001
_cell_length_b                   3.002
_cell_length_c                   3.003
_cell_angle_alpha                89.9
_cell_angle_beta                 90.1
_cell_angle_gamma                90.0
_chemical_formula_sum            'Si2'
_chemical_formula_structural     'Si'
loop_
_atom_site_label
_atom_site_type_symbol
_atom_site_fract_x
_atom_site_fract_y
_atom_site_fract_z
Si1 Si 0.001 0.002 0.003
Si2 Si 0.501 0.502 0.503

1. 基本的な使用例 (出力ファイル名とsymprecをデフォルトで実行)

example.cif を読み込み、デフォルトの許容誤差 1.0e-3 で対称化し、example-symmetrized.cif という名前で出力します。

python symmetrize_pymatgen.py example.cif

実行結果のコンソール出力例:

infile: example.cif
outfile: example-symmetrized.cif
prec: 0.001

input structure:
Full Formula (Si2)
Reduced Formula: Si
abc   :   3.0010   3.0020   3.0030
angles:  89.9000  90.1000  90.0000
pbc   :        T        T        T
density: 2.327
source  : example.cif
bytes   : 236

symmetrized_structure:
Full Formula (Si2)
Reduced Formula: Si
abc   :   3.0020   3.0020   3.0020
angles:  90.0000  90.0000  90.0000
pbc   :        T        T        T
density: 2.327
source  : example.cif
bytes   : 236
Spacegroup: Pm-3m (221)

Save the symmetrized structure to [example-symmetrized.cif]

生成されるファイル (example-symmetrized.cif) の内容例:

# This CIF file was generated by pymatgen.
# Pymatgen was written by Shyue Ping Ong and resides at https://pymatgen.org/.
# If you use this code, please cite the following article:
# S. P. Ong, W. D. Richards, Y. Wang, G. W. Burton, S. Han, I. Scheidemantel,
# J. He, A. Gamst, M. Auddy, S. Friese, F. B. Cambria, and G. Ceder,
# Comput. Mater. Sci., 68, 314-319 (2013).
data_example
_symmetry_space_group_name_H-M   'P m -3 m'
_symmetry_Int_Tables_number      221
_chemical_formula_structural     Si
_chemical_formula_sum            Si2
_cell_length_a                   3.002
_cell_length_b                   3.002
_cell_length_c                   3.002
_cell_angle_alpha                90.0
_cell_angle_beta                 90.0
_cell_angle_gamma                90.0
_cell_volume                     27.054008
_cell_formula_units_Z            2
loop_
 _atom_site_label
 _atom_site_type_symbol
 _atom_site_fract_x
 _atom_site_fract_y
 _atom_site_fract_z
 _atom_site_occupancy
Si1 Si 0.0 0.0 0.0 1.0
Si2 Si 0.5 0.5 0.5 1.0

この例では、わずかに歪んでいた格子定数と角度が、それぞれ 3.002 と 90.0 に調整され、空間群が Pm-3m (221) と特定され、原子座標も理想的な位置 (0.0 0.0 0.0, 0.5 0.5 0.5) に修正されていることがわかります。

2. 出力ファイル名と許容誤差を指定する例

example.cif を読み込み、出力ファイル名を my_symmetrized.cif とし、許容誤差を 0.01 に設定して実行します。

python symmetrize_pymatgen.py example.cif my_symmetrized.cif 0.01

実行結果のコンソール出力例:

infile: example.cif
outfile: my_symmetrized.cif
prec: 0.01

input structure:
Full Formula (Si2)
Reduced Formula: Si
abc   :   3.0010   3.0020   3.0030
angles:  89.9000  90.1000  90.0000
pbc   :        T        T        T
density: 2.327
source  : example.cif
bytes   : 236

symmetrized_structure:
Full Formula (Si2)
Reduced Formula: Si
abc   :   3.0020   3.0020   3.0020
angles:  90.0000  90.0000  90.0000
pbc   :        T        T        T
density: 2.327
source  : example.cif
bytes   : 236
Spacegroup: Pm-3m (221)

Save the symmetrized structure to [my_symmetrized.cif]

この場合、my_symmetrized.cif という名前のファイルが生成され、その内容は上記の example-symmetrized.cif と同様に、対称化された構造情報が含まれます。許容誤差を大きくすることで、わずかなずれがより「対称的」と見なされやすくなりますが、あまり大きくしすぎると、本来の構造とは異なる空間群が誤って適用される可能性があるので注意が必要です。

3. 終了時に一時停止する例

すべての引数を指定し、プログラム終了時に一時停止する設定で実行します。

python symmetrize_pymatgen.py example.cif final_symm.cif 0.0001 1

実行結果のコンソール出力例:

infile: example.cif
outfile: final_symm.cif
prec: 0.0001

input structure:
Full Formula (Si2)
Reduced Formula: Si
abc   :   3.0010   3.0020   3.0030
angles:  89.9000  90.1000  90.0000
pbc   :        T        T        T
density: 2.327
source  : example.cif
bytes   : 236

symmetrized_structure:
Full Formula (Si2)
Reduced Formula: Si
abc   :   3.0010   3.0020   3.0030
angles:  89.9000  90.1000  90.0000
pbc   :        T        T        T
density: 2.327
source  : example.cif
bytes   : 236
Spacegroup: P 1 (1)

Save the symmetrized structure to [final_symm.cif]

Press ENTER to terminate>>

この例では、symprec を 0.0001 と非常に小さくしたため、example.cif のわずかなずれも対称と見なされず、空間群が最も対称性の低い P 1 (1) となっています。これは、許容誤差が厳しすぎると、目的の対称化が達成されない場合があることを示しています。また、最後に Press ENTER to terminate>> が表示され、ユーザーがEnterキーを押すまでプログラムは終了しません。