このドキュメントは、Pythonスクリプト guess_free_parameters.py の使用方法と内部構造を解説します。このスクリプトは、pymatgen ライブラリを使用して、CIF（Crystallographic Information File）から結晶構造の格子および原子座標の自由度を推測することを目的としています。

はじめに

このドキュメントは、Pythonスクリプト guess_free_parameters.py の機能、依存関係、使用方法、および主要な関数について説明します。本プログラムは、結晶学情報ファイル（CIF）から結晶構造を分析し、格子定数と原子位置の独立な自由度を推定します。

概要

guess_free_parameters.py は、与えられたCIFファイルから結晶構造を読み込み、その対称性を解析します。具体的には、空間群、結晶系、ワイコフサイト情報などを特定します。そして、以下の自由度を推定します。

• 格子自由度: 結晶系に基づいて格子定数（a, b, c, alpha, beta, gamma）のうち、独立なパラメータと固定されている拘束条件をリストアップします。

• 原子座標の自由度: 独立な原子サイトごとに、その分数座標 (x, y, z) が以下によって固定または自由であるかを判断します。

  • 値に基づく固定: 座標値が 0.0, 0.25, 1/3, 0.5, 2/3, 0.75 などの特定の既知の値に固定されているか、または座標同士が等しいか。

  • 摂動に基づく自由度: 代表サイトの座標を微小に変位させても空間群対称性が維持されるかどうかをチェックすることで、その座標が自由であるか固定されているかを判断します。

最終的に、これらの分析結果が標準出力に整形されて表示されます。

インストール

このプログラムを実行するには、Python 3 といくつかの非標準ライブラリが必要です。必要なライブラリは numpy と pymatgen です。これらは pip を使用してインストールできます。

pip install numpy pymatgen

依存関係

このプログラムは以下のライブラリに依存しています。

• 標準ライブラリ:

  • argparse: コマンドライン引数の解析に使用されます。

• 非標準ライブラリ:

  • numpy: 数値計算、特に配列操作やノルム計算に使用されます。

  • pymatgen.core.Structure: CIFファイルから結晶構造を読み込み、操作するためのクラスです。

  • pymatgen.symmetry.analyzer.SpacegroupAnalyzer: 結晶構造の空間群対称性を解析するためのクラスです。

  • pymatgen.symmetry.groups.SpaceGroup: 空間群の対称操作を取得するためのクラスです。

使用方法

コマンドライン引数

guess_free_parameters.py は以下のコマンドライン引数を取ります。

python guess_free_parameters.py <cif_file> [OPTIONS]

• 位置引数:

  • cif: (必須) 入力となるCIFファイルのパス。

• オプション引数:

  • --symprec: 型は float, デフォルト値は 1e-4。対称性を判断するための許容誤差（距離）。

  • --angle-tolerance: 型は float, デフォルト値は 5.0。対称性を判断するための角度の許容誤差（度）。

  • --tol: 型は float, デフォルト値は 1e-6。分数座標の比較などで使用される一般的な許容誤差。

  • --delta: 型は float, デフォルト値は 1e-3。座標を摂動させる際の微小変位量。この値は通常、--symprec よりも大きい必要があります。プログラムは delta <= symprec の場合に警告を出力します。

  • --print-expanded: 型は int, デフォルト値は 1。空間群によって展開された等価座標を出力するかどうかを制御します。 0 で出力しない、 1 で出力する。

実行例

仮に example.cif というCIFファイルが存在する場合、以下のコマンドで実行できます。

python guess_free_parameters.py example.cif

より詳細な出力のために、--print-expanded 1 を明示的に指定することもできます（デフォルト値のため効果は同じです）。

python guess_free_parameters.py example.cif --print-expanded 1

許容誤差を調整する例:

python guess_free_parameters.py example.cif --symprec 1e-3 --tol 1e-5 --delta 1e-2

出力例

出力は、まず対称性の概要、次に格子自由度、最後に独立な原子サイトごとの自由度の詳細が順に表示されます。

====================================
Symmetry
====================================
Space group    : P1 (1)
Crystal system : triclinic

====================================
Lattice degrees of freedom
====================================
Free lattice parameters:
  a, b, c, alpha, beta, gamma
Constraints: none

====================================
Independent atomic sites
====================================
[0] species      : Fe
    site indices : [0]
    Wyckoff      : a
    multiplicity : 1
    frac coords  : (0.00000000, 0.00000000, 0.00000000)
    fixed by value : x=0, y=0, z=0
    equal by value : none
    free by perturbation  : none
    fixed by perturbation : x, y, z
    estimated coordinate dof : 0
    expanded coords by space group:
        op[00] : (0.00000000, 0.00000000, 0.00000000)

[1] species      : O
    site indices : [1]
    Wyckoff      : a
    multiplicity : 1
    frac coords  : (0.12345000, 0.67890000, 0.24680000)
    fixed by value : none
    equal by value : none
    free by perturbation  : x, y, z
    fixed by perturbation : none
    estimated coordinate dof : 3
    expanded coords by space group:
        op[00] : (0.12345000, 0.67890000, 0.24680000)

... （他のサイトの情報が続く）

delta <= symprec の場合は、以下のような警告メッセージが表示されます。

WARNING: delta should usually be larger than symprec.
         symprec = 1e-04
         delta   = 1e-05
         recommended: delta >= 10 * symprec

主要な関数

このセクションでは、プログラムの主要な処理フローを担う関数について説明します。

• main()

  • 説明: プログラムのエントリーポイントです。コマンドライン引数を解析し、構造解析を実行し、結果を整形して標準出力に出力します。

  • 引数: なし（argparse を介してコマンドライン引数を受け取ります）。

  • 戻り値: なし。

• analyze_independent_sites(structure, symprec, angle_tolerance, tol, delta)

  • 説明: 与えられた結晶構造の独立な原子サイトについて、その座標の自由度を分析します。これは、空間群対称性の情報と、摂動テストを組み合わせて行われます。

  • 引数:

    • structure: pymatgen.core.Structure オブジェクト。解析対象の結晶構造。

    • symprec: float。空間群解析における距離の許容誤差。

    • angle_tolerance: float。空間群解析における角度の許容誤差（度）。

    • tol: float。分数座標比較の一般的な許容誤差。

    • delta: float。摂動テストにおける微小変位量。

  • 戻り値:

    • tuple:

      • 第1要素: dict。構造全体の対称性シグネチャ（空間群シンボル、番号、結晶系、サイト情報）。

      • 第2要素: list。各独立サイトグループの解析結果の辞書リスト。各辞書には、種（species）、ワイコフ記号、多重度、分数座標、値によって固定された座標、値によって等しいとされた座標、摂動によって自由とされた座標、摂動によって固定された座標、空間群によって展開された座標などが含まれます。

• get_symmetry_signature(structure, symprec, angle_tolerance)

  • 説明: 結晶構造の対称性情報を抽出し、比較可能な「対称性シグネチャ」を生成します。空間群情報と等価サイトごとの種、ワイコフ記号、多重度のリストが含まれます。

  • 引数:

    • structure: pymatgen.core.Structure オブジェクト。

    • symprec: float。空間群解析における距離の許容誤差。

    • angle_tolerance: float。空間群解析における角度の許容誤差（度）。

  • 戻り値:

    • dict: 空間群シンボル、空間群番号、結晶系、および各独立サイトグループの詳細（種、ワイコフ記号、多重度、代表サイトの分数座標）を含む辞書。

• get_lattice_dof_from_crystal_system(crystal_system)

  • 説明: 指定された結晶系に基づいて、独立な格子パラメータと拘束条件を決定します。

  • 引数:

    • crystal_system: str。結晶系の名前（例: "triclinic", "monoclinic", "cubic" など）。

  • 戻り値:

    • dict: 自由な格子パラメータのリスト ("free" キー) と、拘束条件の文字列リスト ("constraints" キー) を含む辞書。

  • 例外:

    • ValueError: 未知の結晶系が与えられた場合に発生します。

内部関数

このセクションでは、プログラムの内部で利用されるユーティリティ関数や補助関数について説明します。

• wrap01(x)

  • 説明: 配列または単一の浮動小数点数を [0.0, 1.0) の範囲にラップします。これは分数座標の周期性を扱うためによく使用されます。

  • 引数:

    • x: numpy.ndarray または float。ラップする値。

  • 戻り値:

    • numpy.ndarray または float。 [0.0, 1.0) にラップされた値。

• frac_dist(a, b)

  • 説明: 2つの分数座標 a と b の間の周期境界条件を考慮した距離を計算します。

  • 引数:

    • a: numpy.ndarray。第1の分数座標。

    • b: numpy.ndarray。第2の分数座標。

  • 戻り値:

    • float。周期境界条件下の距離。

• close_frac(a, b, tol=1e-5)

  • 説明: 2つの分数座標 a と b が、指定された許容誤差 tol 内で周期的に等しいかどうかを判断します。

  • 引数:

    • a: numpy.ndarray。第1の分数座標。

    • b: numpy.ndarray。第2の分数座標。

    • tol: float。許容誤差。

  • 戻り値:

    • bool。近い場合は True, そうでない場合は False。

• close_mod1(a, b, tol=1e-5)

  • 説明: 2つの浮動小数点数 a と b が、指定された許容誤差 tol 内でモジュロ1で等しいかどうかを判断します。これは単一の座標値の比較に特化しています。

  • 引数:

    • a: float。第1の数値。

    • b: float。第2の数値。

    • tol: float。許容誤差。

  • 戻り値:

    • bool。近い場合は True, そうでない場合は False。

• is_fixed_value(v, values=(0.0, 0.25, 1/3, 0.5, 2/3, 0.75), tol=1e-5)

  • 説明: 与えられた数値 v が、定義された固定値のリスト（デフォルトは 0.0, 0.25, 1/3, 0.5, 2/3, 0.75）のいずれかに tol の範囲内で一致するかどうかをチェックします。

  • 引数:

    • v: float。チェックする数値。

    • values: tuple (オプション)。比較対象の固定値のリスト。

    • tol: float。許容誤差。

  • 戻り値:

    • tuple:

      • 第1要素: bool。一致する値が見つかった場合は True, そうでない場合は False。

      • 第2要素: float または None。一致した固定値（見つからなかった場合は None）。

• unique_frac_coords(coords, tol=1e-8)

  • 説明: 与えられた分数座標のリストから、周期境界条件を考慮して重複する座標を除外し、一意な座標のリストを返します。

  • 引数:

    • coords: list of numpy.ndarray。分数座標のリスト。

    • tol: float。一意性を判断する際の許容誤差。

  • 戻り値:

    • list of numpy.ndarray。一意な分数座標のリスト。

• expand_site_by_spacegroup(site_frac, sg_symbol, tol=1e-8)

  • 説明: 指定された空間群シンボル (sg_symbol) を使用して、単一の代表サイト (site_frac) をすべての等価なサイトに展開します。

  • 引数:

    • site_frac: numpy.ndarray。代表サイトの分数座標。

    • sg_symbol: str。空間群のシンボル（例: "P1", "Fm-3m"）。

    • tol: float。一意なサイトを決定する際の許容誤差。

  • 戻り値:

    • list of numpy.ndarray。展開された等価サイトの分数座標のリスト。

• same_symmetry_signature(ref, test)

  • 説明: 2つの対称性シグネチャ (ref と test) が等しいかどうかを比較します。空間群番号と、ソートされたサイト情報（種、ワイコフ記号、多重度）のリストを比較します。

  • 引数:

    • ref: dict。基準となる対称性シグネチャ。

    • test: dict。比較対象の対称性シグネチャ。

  • 戻り値:

    • bool。両方のシグネチャが同じであれば True, そうでなければ False。

• infer_value_based_constraints(frac, tol=1e-5)

  • 説明: 単一の分数座標 (frac) に対して、値に基づく拘束条件（特定の固定値への一致や座標間の等価性）を推測します。

  • 引数:

    • frac: numpy.ndarray。対象の分数座標 ([x, y, z])。

    • tol: float。比較の許容誤差。

  • 戻り値:

    • tuple:

      • 第1要素: dict。固定された座標軸とその値（例: {"x": 0.0, "z": 0.25}）。

      • 第2要素: list of tuple。等しいと見なされる座標軸のペア（例: [("x", "y")]）。

• find_site_indices_for_group(structure, group_sites, tol=1e-5)

  • 説明: pymatgen.symmetrized_structure から取得された等価サイトのリスト (group_sites) に対応する、元の pymatgen.core.Structure オブジェクト内のサイトインデックスを見つけます。

  • 引数:

    • structure: pymatgen.core.Structure オブジェクト。元の結晶構造。

    • group_sites: list of pymatgen.core.Site。等価サイトのリスト。

    • tol: float。サイトの近さを判断する際の許容誤差。

  • 戻り値:

    • list of int。対応するサイトインデックスのリスト。

  • 例外:

    • RuntimeError: 等価サイトが元の構造内で見つからなかった場合に発生します。

• match_coords_to_indices(structure, indices, new_coords, tol=1e-4)

  • 説明: 元の構造における等価サイトのインデックス (indices) と、摂動後に空間群で展開された新しい座標 (new_coords) を対応付けます。元の座標に最も近い新しい座標を貪欲に割り当てます。

  • 引数:

    • structure: pymatgen.core.Structure オブジェクト。元の結晶構造。

    • indices: list of int。元の構造における等価サイトのインデックス。

    • new_coords: list of numpy.ndarray。摂動後に展開された新しい分数座標。

    • tol: float。距離を判断する際の許容誤差。（注: この tol は、コード内で frac_dist の結果を直接比較するのではなく、np.argmin で最小距離のインデックスを選択するためにのみ使用されます。）

  • 戻り値:

    • list of numpy.ndarray。 indices と同じ順序で対応付けられた新しい分数座標のリスト。

• perturb_equivalent_group_coordinate(structure, group_indices, representative_frac, coord_index, delta, sg_symbol, tol=1e-8)

  • 説明: 等価サイト群の代表サイトの特定の座標軸を微小量 delta だけ変位させ、その新しい代表サイトから空間群操作で等価サイト群全体を再構築します。その後、元の等価サイト群全体をこの新しい座標群で置き換えた新しい構造を生成します。

  • 引数:

    • structure: pymatgen.core.Structure オブジェクト。元の結晶構造。

    • group_indices: list of int。対象となる等価サイト群の元の構造インデックス。

    • representative_frac: numpy.ndarray。等価サイト群の代表サイトの分数座標。

    • coord_index: int (0, 1, 2)。摂動させる座標軸のインデックス (x, y, z)。

    • delta: float。座標の微小変位量。

    • sg_symbol: str。空間群のシンボル。

    • tol: float。座標の比較に使用される許容誤差。

  • 戻り値:

    • pymatgen.core.Structure オブジェクトまたは None。摂動された新しい構造。展開されたサイトの数が元のグループと異なる場合（つまり摂動により対称性が壊れた場合）、またはその他のエラーが発生した場合は None を返します。

• print_coords(coords, indent="        ")

  • 説明: 分数座標のリストを整形された形式で標準出力に出力します。

  • 引数:

    • coords: list of numpy.ndarray。出力する分数座標のリスト。

    • indent: str (オプション)。各行の先頭に追加するインデント文字列。

  • 戻り値: なし。

変更履歴

このプログラムのソースコードからは変更履歴を確認できません。

ライセンス

このプログラムのソースコードからはライセンス情報を確認できません。

著作権

このプログラムのソースコードからは著作権情報を確認できません。