template_tklib プログラム仕様
tklib連携構造解析プログラム
概要: このスクリプトは、tklibライブラリ（tkCIF, tkCrystal, tkAtomType）とPymatgenライブラリを連携させ、 CIFファイルの読み込み、構造情報の表示、密度計算、結合価数和（BVS）計算、 動径分布関数（RDF）/累積配位数（RCN）計算、Ewald法によるマデルングポテンシャル計算、 構造因子計算、Pymatgenによる対称化構造のCIF出力など、一連の構造解析機能を提供します。
詳細説明: コマンドライン引数としてCIFファイルパスを受け取り、指定されたCIFファイルに対して様々な解析機能を実施します。 各機能ブロックは独立しており、構造解析のステップバイステップの実行例として設計されています。 tklibとPymatgenの機能比較や連携のデモンストレーションとしても利用できます。
関連リンク: tklib機能解析プログラム: template_tklib.py (もし関連する外部ドキュメントがあればここに記述)
- crystal.template_tklib.CalRDFi(cry: tkCrystal, Rmin: float, Rmax: float, nR: int, atom0, iSite: int, normalize: bool = True)[ソース]
単一の非対称サイト atom0 から見た全原子に対するタイプ別RDF（動径分布関数）を計算します。
詳細説明: 指定された中心原子 atom0 から、結晶内の全ての展開された原子サイトまでの距離を計算します。 周期境界条件を考慮し、距離範囲 Rmin から Rmax を nR 個のビンに分割し、 各ビンの原子数（占有率を考慮）を原子タイプ別に集計します。 normalize がTrueの場合、結果は距離ビン幅で規格化され、RDF(r) = dN/dr となります。
:param : param cry: tkCrystal: 計算対象のtkCrystalオブジェクト。 :param : param Rmin: float: 距離計算の最小値（Å単位）。 :param : param Rmax: float: 距離計算の最大値（Å単位）。 :param : param nR: int: 距離ビンの数。 :param : param atom0: tkAtomSite: 中心となる非対称サイトオブジェクト。 :param : param iSite: int: atom0 の非対称サイトリストにおけるインデックス。 :param : param normalize: bool: 結果を距離ビン幅で規格化するかどうか。Trueの場合、RDF(r)として機能します。
- 戻り値:
- returns: Tuple[List[float], List[List[float]]]:
xR (距離配列、各ビンの中心距離のリスト) と RDF (タイプ別のRDFヒストグラム、RDF[iAtomType1][iR] の形式)。
- crystal.template_tklib.CalculateRDFs(cry: tkCrystal, Rmin: float, Rmax: float, nR: int)[ソース]
全非対称サイトに対するRDFを計算し、それを原子種ベースで平均化してRDF/RCNを求めます。
詳細説明: まず、CalRDFi を使用して、結晶内の全ての非対称サイトをそれぞれ中心としたタイプ別RDFを個別に計算します。 次に、同じ原子種タイプに属する非対称サイトのRDFを平均化し、原子種別平均RDF (RDFs) を算出します。 最後に、RDFs を累積積分することで原子種別累積配位数 (RCNs) を計算します。
:param : param cry: tkCrystal: 計算対象のtkCrystalオブジェクト。 :param : param Rmin: float: 距離計算の最小値（Å単位）。 :param : param Rmax: float: 距離計算の最大値（Å単位）。 :param : param nR: int: 距離ビンの数。
- 戻り値:
- returns: Tuple[List[float], np.ndarray, np.ndarray]:
xR (距離配列)、 RDFs (原子種別平均RDF、RDFs[iType][iR] の形式)、 RCNs (原子種別RCN、RCNs[iType][iR] の形式)。
- crystal.template_tklib.analyze_tkcif_basic(filepath: str) tkCrystal | None[ソース]
tkCIFを使用してCIFファイルを読み込み、基本情報を表示し、tkCrystalオブジェクトを返します。
詳細説明: 指定されたパスのCIFファイルを tkCIF.ReadCIF メソッドで読み込みます。 読み込みに成功した場合、cifdata.Print() でCIFデータの内容をコンソールに出力し、 そのデータから tkCrystal オブジェクトを取得して返します。 ファイル読み込みや tkCrystal オブジェクト取得に失敗した場合はエラーメッセージを表示しNoneを返します。
:param : param filepath: str: 読み込むCIFファイルへのパス。
- 戻り値:
- returns: Optional[tkCrystal]: 読み込まれた構造を表すtkCrystalオブジェクト、
またはエラーが発生した場合にNone。
- crystal.template_tklib.analyze_tkcrystal_structure(cry: tkCrystal)[ソース]
tkCrystalオブジェクトを用いて構造情報（格子、サイト）と密度を計算し表示します。
詳細説明: tkCrystal.PrintInf() を呼び出して構造の概要情報を出力します。 その後、cry.Density() と cry.AtomDensity() を用いて質量密度と原子密度を計算し、 その結果を表示するとともに、一般的な密度の範囲内にあるかどうかの簡単な検証を行います。
:param : param cry: tkCrystal: 解析対象のtkCrystalオブジェクト。
- 戻り値:
returns: None
- crystal.template_tklib.calculate_bond_valence_sums(cry: tkCrystal, max_r: float = 2.7)[ソース]
tkCrystalのサイト情報と自作のBVSパラメータを用いて結合価数和を計算します。
詳細説明: 環境変数 'tkProg_Root' からBVSパラメータファイルのパスを構築し、ファイルを読み込みます。 読み込まれたパラメータと結晶構造情報（非対称サイト、展開サイト）を使用して、 各非対称サイトからの最短原子間距離と結合価数（Bond Valence）を計算し、 その合計である結合価数和（Bond Valence Sum, BVS）を出力します。 結合距離が max_r を超える結合は無視されます。
:param : param cry: tkCrystal: BVS計算の対象となるtkCrystalオブジェクト。 :param : param max_r: float: 結合と見なす最大原子間距離（Å単位）。
- 戻り値:
returns: None
- crystal.template_tklib.calculate_cn_rdfs(cry: tkCrystal, Rmin: float, Rmax: int, nR: int, nCN: int)[ソース]
CN（配位数）に基づいた累積配位数分布（RCN）とRDFを計算します。
詳細説明: まず、各非対称サイトからの総原子数（raw count）のRDFとRCNを計算します。 次に、各サイトのRCNに基づき、特定の配位数 nCN 以上となる距離範囲で、 原子タイプ別に累積されたRDF (CNRDFs) とRCN (CNRCNs) を計算します。 CNRDFs はCNが icn 以上となる距離ビンにおける原子数、CNRCNs はその累積積分です。
:param : param cry: tkCrystal: 計算対象のtkCrystalオブジェクト。 :param : param Rmin: float: 距離計算の最小値（Å単位）。 :param : param Rmax: float: 距離計算の最大値（Å単位）。 :param : param nR: int: 距離ビンの数。 :param : param nCN: int: 計算する最大配位数。iCN は 1 から nCN まで使用されます。
- 戻り値:
- returns: Tuple[List[float], List[List[List[float]]], List[List[List[float]]]]:
xR_cn (距離配列)、 CNRDFs (CNベースのRDF、CNRDFs[iType][iCN][iR] の形式)、 CNRCNs (CNベースのRCN、CNRCNs[iType][iCN][iR] の形式)。
- crystal.template_tklib.calculate_madelung_potential(cry: tkCrystal, ew_alpha: float = 0.3, prec: float = 1e-05)[ソース]
Ewald法を用いて、単位格子内の最初の非対称サイトにおけるマデルングポテンシャルを計算します。
詳細説明: Ewald法は、クーロン相互作用の実空間項、逆空間項、自己項の3つの部分に分けて計算することで、 無限に広がる結晶の静電ポテンシャルを収束させます。 この関数では、ターゲットとなる最初の非対称サイトに対してこれらの項を計算し、合計してマデルングポテンシャル （Joule単位およびeV単位）とマデルング定数を出力します。 実空間および逆空間のカットオフは、指定された精度 prec に基づいて決定されます。
:param : param cry: tkCrystal: 計算対象のtkCrystalオブジェクト。 :param : param ew_alpha: float: Ewaldパラメータ $lpha$。実空間と逆空間の寄与のバランスを制御します。 :param : param prec: float: 計算の目標精度。結果の相対誤差に影響します。
- 戻り値:
returns: None
- crystal.template_tklib.calculate_structure_factor(cry: tkCrystal, xray_source_key: str = 'CuKa1', hkl_test: List[int] = [1, 0, 0])[ソース]
指定されたX線波長と$hkl$での構造因子 $|F_{hkl}|$ と原子散乱因子を計算・表示します。
詳細説明: まず、X線源キーから波長を取得し、指定されたミラー指数 (hkl) と波長に基づいて 面間隔 $d_{hkl}$、散乱ベクトル $s = sin heta/lambda$、および回折角 $2 heta$ を計算します。 次に、結晶内の各原子タイプについて、散乱ベクトル $s$ に応じた原子散乱因子 $f(s)$ を tkAtomType.asf() で求め、 最後に tkCrystal.Fhkl() を用いて結晶構造因子 $F_{hkl}$ の複素数とその絶対値を計算し、出力します。
:param : param cry: tkCrystal: 構造因子計算の対象となるtkCrystalオブジェクト。 :param : param xray_source_key: str: 使用するX線源のキー（例: 'CuKa1'）。wavelength 辞書に定義されている必要があります。 :param : param hkl_test: List[int]: 計算するミラー指数 [h, k, l] のリスト。
- 戻り値:
returns: None
- crystal.template_tklib.change_basis_preserving_geometry(structure: Structure, T: ndarray, t: ndarray | None = None, xyz_tol: float = 1e-06) Structure[ソース]
Pymatgen Structureオブジェクトの基底を変換し、重複サイトをマージします。
詳細説明: 指定された変換行列 T と並進ベクトル t を用いて、格子ベクトルと原子の分率座標を変換します。 変換後の座標は周期境界条件を考慮して [0, 1) の範囲に正規化されます。 その後、xyz_tol の許容誤差内で同一と見なされるサイトはマージされ、新しいStructureオブジェクトが生成されます。
:param : param structure: Structure: 基底変換を行う元のPymatgen Structureオブジェクト。 :param : param T: np.ndarray: 3x3の変換行列。新しい基底ベクトルを定義します。 :param : param t: Optional[np.ndarray]: 変換後の座標に適用する並進ベクトル (1x3)。デフォルトはNone (並進なし)。 :param : param xyz_tol: float: サイトの重複を判定するための座標許容誤差。
- 戻り値:
returns: Structure: 変換され、重複がマージされた新しいPymatgen Structureオブジェクト。
- Raises:
raises ValueError: 変換行列 T が特異である (行列式がゼロに近い) 場合。
- crystal.template_tklib.main()[ソース]
CLI引数からCIFファイルを受け取り、tkcif, tkcrystalの機能を順次実行します。
詳細説明: コマンドライン引数としてCIFファイルのパスを受け取ります。 引数が指定されない場合は、デフォルトの 'ZnO.cif' を使用します。 その後、以下の構造解析機能ブロックを順番に実行します。 1. tkCIFによるCIF読み込みと基本情報表示 2. tkCrystalによる構造情報と密度計算 3. tkAtomTypeによる原子情報テスト 4. Pymatgen連携による単位格子変換と密度検証 5. 結合価数和（BVS）計算 6. 動径分布関数（RDF）/累積配位数（RCN）計算 7. Ewald法によるマデルングポテンシャル計算 8. 構造因子（Fhkl）と原子散乱因子の計算 9. Pymatgen対称化後の結果をtkFileでCIF出力
:param : param : なし
- 戻り値:
returns: None
- crystal.template_tklib.make_matrix_of_size(dims: ~typing.List[int], dtype=<class 'float'>, defval=0.0)[ソース]
指定された次元の行列（リストのリスト）を作成するヘルパー関数。 numpy.zerosの代替として、ネストされたPythonリストで初期化された行列を生成します。
:param : param dims: List[int]: 行列の次元を指定する整数のリスト (例: [dim1, dim2, ...])。 :param : param dtype: type: 要素のデータ型（この実装では直接は使用されませんが、Docstringには含めます）。 :param : param defval: Any: 各要素の初期値。
- 戻り値:
returns: Any: 指定された次元と初期値で作成された行列（リストのリスト）。
- crystal.template_tklib.output_symmetrized_cif(cif_filepath: str, cry_source: tkCrystal, sym_tol: float = 0.001)[ソース]
tkCrystalをPymatgenで対称化し、その結果をtkFileを使ってCIF形式で保存します。
詳細説明: tkCrystal オブジェクトをPymatgenの Structure に変換し、SpacegroupAnalyzer を用いて 対称化された構造 (symmetrized_structure) を取得します。 対称化された構造から空間群情報、格子パラメータ、対称操作、非等価サイト情報を抽出し、 新しいCIFファイルに整形して書き出します。対称操作のXYZ表現の生成にはヘルパー関数が使用されます。
:param : param cif_filepath: str: 元のCIFファイルのパス。出力ファイル名の生成に使用されます。 :param : param cry_source: tkCrystal: 対称化の対象となるtkCrystalオブジェクト。 :param : param sym_tol: float: PymatgenのSpacegroupAnalyzerが対称性を検出する際の許容誤差（Å単位）。
- 戻り値:
returns: Optional[str]: 出力されたCIFファイルのパス、またはエラーが発生した場合にNone。
- crystal.template_tklib.perform_pmg_conversion_on_tkcrystal(cry: tkCrystal, sym_tol: float = 0.01, density_eps: float = 0.0001)[ソース]
tkCrystalをPymatgen Structureに変換し、Primitive Cellへの変換と密度検証を実行します。
詳細説明: まず tkCrystal オブジェクトを tkcrystal_to_pmg_structure を使ってPymatgenの Structure オブジェクトに変換します。 次に、元の構造と SpacegroupAnalyzer を用いて原始（Primitive Standard）構造に変換された後の構造の密度を計算し、 両者の原子密度と質量密度が density_eps で指定された許容誤差内で一致するかどうかを検証します。
:param : param cry: tkCrystal: 変換および検証の対象となるtkCrystalオブジェクト。 :param : param sym_tol: float: SpacegroupAnalyzerが対称性を検出する際の許容誤差（Å単位）。 :param : param density_eps: float: 密度比較における相対許容誤差。
- 戻り値:
returns: None
- crystal.template_tklib.print_matrix(m)[ソース]
3x3行列を見やすいフォーマットで出力します。
:param : param m: np.ndarray: 出力する3x3のNumPy行列。
- 戻り値:
returns: None
- crystal.template_tklib.read_bv_params(path: str) Dict[str, Any] | None[ソース]
指定されたパスからBVSパラメータファイルを読み込み、辞書として返します。
詳細説明: ファイルが存在しない場合はエラーメッセージを表示しNoneを返します。 ファイル内の '_valence_param_details' セクション以降の行をパースし、 原子ペア (例: 'Atom1:Atom2') をキーとして 'r0', 'B', 'ref' のパラメータを辞書に格納します。 行が '#' で始まる場合はセクションの終わりとみなします。
:param : param path: str: BVSパラメータファイルへのパス。
- 戻り値:
returns: Optional[Dict[str, Any]]: BVSパラメータの辞書、またはファイルが見つからない場合にNone。
- crystal.template_tklib.report_pmg_structure_density(struct: Structure, label: str) Tuple[float, float][ソース]
Pymatgen Structureの密度を計算し、その結果をレポートとして表示します。
詳細説明: 構造の体積、有効原子数、総質量（amuからgに変換）を計算し、 原子密度（atoms/ų）と質量密度（g/cm³）を算出して出力します。
:param : param struct: Structure: 計算対象のPymatgen Structureオブジェクト。 :param : param label: str: 出力メッセージのラベルとして使用される文字列。
- 戻り値:
returns: Tuple[float, float]: 原子密度 (atoms/ų) と質量密度 (g/cm³) のタプル。
- crystal.template_tklib.site_effective_occupancy_and_mass_amu(site) Tuple[float, float][ソース]
Pymatgen Siteの有効占有数と総質量を計算します。
詳細説明: サイト内の各原子種の占有数と原子質量を合算し、サイト全体の有効占有数と総質量（amu単位）を計算します。
:param : param site: pymatgen.core.Site: 計算対象のPymatgen Siteオブジェクト。
- 戻り値:
returns: Tuple[float, float]: 有効占有数と総質量 (amu単位) のタプル。
- crystal.template_tklib.structure_effective_counts(struct: Structure) Tuple[float, float, int][ソース]
Pymatgen Structureの有効原子数、総質量、サイト数を計算します。
詳細説明: 構造内の全てのサイトについて、site_effective_occupancy_and_mass_amu を用いて 有効占有数と総質量を合算し、さらにサイトの総数も返します。
:param : param struct: Structure: 計算対象のPymatgen Structureオブジェクト。
- 戻り値:
returns: Tuple[float, float, int]: 有効原子数、総質量 (amu単位)、サイト数のタプル。