bond_valence_sum_BVAnalyzer.py 技術ドキュメント

プログラムの動作

bond_valence_sum_BVAnalyzer.py は、結晶構造情報ファイル（CIFファイル）を読み込み、pymatgen ライブラリの BVAnalyzer を使用して、各原子サイトのボンド価数和 (Bond Valence Sum, BVS) を計算するPythonスクリプトです。このプログラムの主な目的は、結晶構造内の原子の酸化状態を推定するための基礎となるBVS分析をユーザーに提供することです。

主な機能は以下の通りです。

  1. CIFファイルの読み込み: 指定されたCIFファイルから結晶構造データを読み込みます。

  2. BVAnalyzer の初期化と設定表示: pymatgen の BVAnalyzer オブジェクトを初期化し、その主要な設定パラメータ（例: max_radius, distance_scale_factor など）を表示します。

  3. パラメータファイル情報の表示: BVAnalyzer が利用するボンド価数パラメータ（O’Keefe & Brese, 1991）が格納されているYAMLファイルのパスと、特定の元素ペア（例: Zn-O）のパラメータ例を表示します。

  4. サイトごとのBVS計算: 構造内の各原子サイトについて、指定された最大半径内の最近傍原子との結合に基づき、calculate_bv_sum 関数を使用してBVSを計算し、表示します。

  5. 異なる距離カットオフでのBVS試行計算: 複数の異なる距離カットオフ値 (rcut) を使用してBVS計算を繰り返し行い、その結果を比較表示します。これにより、近傍の取り方の違いがBVSに与える影響を確認できます。

  6. BVAnalyzer による酸化状態デコレート: 可能であれば、BVAnalyzer の get_valences メソッドを呼び出し、構造全体の電荷中性度を考慮したBVS（および推定された酸化状態）を表示します。

原理

このプログラムは、化学結合の概念を定量的に扱うボンド価数理論（Bond Valence Theory）に基づいています。ボンド価数理論では、各結合に特定の価数（ボンド価数）が割り当てられ、ある原子に集まるすべてのボンド価数の合計がその原子の酸化状態（ボンド価数和）にほぼ等しいとされます。

ボンド価数 \(s_{ij}\) は、原子 \(i\) と \(j\) 間の結合距離 \(R_{ij}\) を用いて、経験的な式で計算されます。一般的に用いられる式は次の通りです。

\[s_{ij} = \exp\left(\frac{R_0 - R_{ij}}{B}\right)\]

ここで、

  • \(R_{ij}\) は原子 \(i\) と \(j\) 間の結合距離です。

  • \(R_0\) は理想的な結合距離であり、ボンド価数 \(s_{ij}=1\) となる距離です。これは結合する元素の組み合わせ（例: Na-Cl, Mg-Oなど）に依存するパラメータです。

  • \(B\) は経験的な定数で、通常は 0.37 Å とされますが、このプログラムで利用されるO’Keefe & Brese (1991) のパラメータセットでは \(B=0.31\) Å が採用されています。

pymatgen の BVAnalyzer は、内部的に bvparam_1991.yaml ファイルから、\(R_0\) を導出するための各元素のパラメータ（\(r, c\)）を読み込みます。例えば、ZnとOの場合、\(R_0\) はこれらの元素固有のパラメータから計算されます。

ある原子サイト \(i\) のボンド価数和 \(V_i\) は、その原子に結合しているすべての最近傍原子 \(j\) とのボンド価数を合計したものです。

\[V_i = \sum_j s_{ij} = \sum_j \exp\left(\frac{R_0 - R_{ij}}{B}\right)\]

この合計 \(V_i\) が、原子 \(i\) の形式的な酸化状態に近い値を示すことが期待されます。プログラムは、pymatgen.analysis.bond_valence.calculate_bv_sum 関数と pymatgen.analysis.bond_valence.BVAnalyzer クラスを使用してこれらの計算を実行します。BVAnalyzer は、構造内のすべてのサイトのBVSを計算し、場合によっては可能な酸化状態のリストや電荷中性度の制約を用いて、各原子の酸化状態を推定しようと試みます。

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

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

  • pymatgen: 物質科学のためのPythonパッケージ。結晶構造の読み込み、処理、ボンド価数分析などに使用されます。

これらのライブラリは、Pythonのパッケージインストーラー pip を使用してインストールできます。

pip install pymatgen

必要な入力ファイル

プログラムは、以下の形式の入力ファイルを必要とします。

  • CIF (Crystallographic Information File):

    • 結晶構造の幾何学的情報（格子定数、空間群、原子の種類、原子位置など）を記述した標準的なテキストファイル形式です。

    • ファイル名はコマンドライン引数として指定します。

例 (CIFファイルの断片):

#_CELL_LENGTH_A    5.640
#_CELL_LENGTH_B    5.640
#_CELL_LENGTH_C    5.640
#_CELL_ANGLE_ALPHA 90.000
#_CELL_ANGLE_BETA  90.000
#_CELL_ANGLE_GAMMA 90.000
#_SYMMETRY_SPACE_GROUP_NAME_H-M 'F m -3 m'
#_SYMMETRY_INT_TABLE_NUMBER 225
#
loop_
_atom_site_type_symbol
_atom_site_label
_atom_site_fract_x
_atom_site_fract_y
_atom_site_fract_z
Na Na1 0.0000 0.0000 0.0000
Cl Cl1 0.5000 0.0000 0.0000

生成される出力ファイル

bond_valence_sum_BVAnalyzer.py は、実行によっていかなるファイルも生成しません。 すべての計算結果およびプログラムの動作に関する情報は、標準出力（コンソール）に表示されます。

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

プログラムはコマンドラインから実行され、CIFファイルのパスを必須引数として受け取ります。オプションで、最大原子間距離を指定できます。

python bond_valence_sum_BVAnalyzer.py <cif_file> [--max_r <radius>]

  • <cif_file>: ボンド価数和を計算したい結晶構造が記述されたCIFファイルへのパスです。これは必須引数です。

  • --max_r <radius>: 最近傍原子を探索する際の最大原子間距離をÅ単位で指定します。この距離を超える原子は結合相手として考慮されません。省略した場合のデフォルト値は 2.8 Å です。

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

ここでは、架空の NaCl.cif というCIFファイルを用いて、具体的な実行例とその出力について説明します。 NaCl.cif ファイルの内容は、例えば以下の通りとします。

# generated using pymatgen
data_NaCl
_symmetry_space_group_name_H-M   'F m -3 m'
_symmetry_Int_Tables_number   225
_cell_length_a   5.640
_cell_length_b   5.640
_cell_length_c   5.640
_cell_angle_alpha   90.000
_cell_angle_beta   90.000
_cell_angle_gamma   90.000
_chemical_formula_structural   NaCl
_chemical_formula_sum   'Na1 Cl1'
_cell_volume   179.410
_cell_formula_units_Z   4
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'
  5 '-x, y, z'
  6 'x, -y, -z'
  7 'x, -y, z'
  8 'x, y, -z'
  9 'z, x, y'
 10 '-z, -x, -y'
 11 '-z, -x, y'
 12 '-z, x, -y'
 13 '-z, x, y'
 14 'z, -x, -y'
 15 'z, -x, y'
 16 'z, x, -y'
 17 'y, z, x'
 18 '-y, -z, -x'
 19 '-y, -z, x'
 20 '-y, z, -x'
 21 '-y, z, x'
 22 'y, -z, -x'
 23 'y, -z, x'
 24 'y, z, -x'
loop_
 _atom_site_type_symbol
 _atom_site_label
 _atom_site_symmetry_multiplicity
 _atom_site_fract_x
 _atom_site_fract_y
 _atom_site_fract_z
 _atom_site_occupancy
  Na Na1 4 0.00000 0.00000 0.00000 1
  Cl Cl1 4 0.50000 0.00000 0.00000 1

実行コマンド

NaCl.cif ファイルを読み込み、最大半径を 3.0 Å として分析を実行します。

python bond_valence_sum_BVAnalyzer.py NaCl.cif --max_r 3.0

実行結果の説明

上記のコマンドを実行すると、以下のような情報が標準出力に表示されます。BVS値は計算の精度やパラメータによって若干異なる場合があります。

cif_file: NaCl.cif
max_r: 3.0

=== BVAnalyzer settings ===
symm_tol                 = 0.1
max_radius               = 3.0
distance_scale_factor    = 0.31
max_permutations         = 100000
charge_neutrality_tol    = 0.001

=== Default parameter file ===
C:\Users\...\Python\Python312\Lib\site-packages\pymatgen\analysis\bvparam_1991.yaml

=== Example: Zn–O parameters ===
{'B': 0.31, 'c': 1.13, 'r': 1.63}

Calculate BVS:
site Na nn_count=6 BVS=1.000
site Cl nn_count=6 BVS=0.999

=== calculate_bv_sum で距離を変えてみる ===
rcut=0.0 Å, site=Na, nn=0, BVS=0.000
rcut=0.0 Å, site=Cl, nn=0, BVS=0.000
----------------------------------------
rcut=1.5 Å, site=Na, nn=0, BVS=0.000
rcut=1.5 Å, site=Cl, nn=0, BVS=0.000
----------------------------------------
rcut=2.0 Å, site=Na, nn=0, BVS=0.000
rcut=2.0 Å, site=Cl, nn=0, BVS=0.000
----------------------------------------
rcut=2.5 Å, site=Na, nn=0, BVS=0.000
rcut=2.5 Å, site=Cl, nn=0, BVS=0.000
----------------------------------------
rcut=3.0 Å, site=Na, nn=6, BVS=1.000
rcut=3.0 Å, site=Cl, nn=6, BVS=0.999
----------------------------------------
BVAnalyzer result:
 0: Na at [0. 0. 0.]  →  BVS = 1.000
 1: Cl at [0.5 0.  0. ]  →  BVS = 0.999

Press ENTER to terminate>>

出力内容の詳細:

  • 入力情報: 最初に、使用されたCIFファイル名と max_r の値が表示されます。

  • BVAnalyzer 設定: pymatgen.analysis.bond_valence.BVAnalyzer オブジェクトの内部設定パラメータが一覧表示されます。これには、対称性の許容誤差 (symm_tol)、最大半径 (max_radius)、距離スケールファクター (distance_scale_factor = 定数 \(B\))、最大置換数 (max_permutations)、電荷中性度の許容誤差 (charge_neutrality_tolerance) などが含まれます。

  • デフォルトパラメータファイル: BVAnalyzer がボンド価数パラメータを読み込むためのデフォルトのYAMLファイル（bvparam_1991.yaml）のパスが表示されます。このファイルは pymatgen ライブラリのインストールディレクトリ内にあります。

  • Zn-O パラメータ例: BV_PARAMS ディクショナリから、例としてZnとOの組み合わせに対するパラメータ（r, c, B）が表示されます。これらは \(R_0\) の計算に使用される値です。

  • BVS 計算結果 (初期 max_r): 読み込まれた構造の各サイト（この例ではNaとCl）について、原子種、最近傍原子の数 (nn_count)、および計算されたBVS (BVS) が表示されます。NaClではNaとClはそれぞれ+1と-1の酸化状態を持つため、BVS値が1.000に近い値を示していることがわかります。

  • 異なる距離カットオフでのBVS試行: プログラムは、0.0, 1.5, 2.0, 2.5, 3.0 Å の異なる rcut 値でBVS計算を再試行します。rcut が短い場合（例えば 2.5 Å 以下）、最近傍原子が検出されないため nn=0, BVS=0.000 となります。3.0 Å になると6つの最近傍原子が検出され、適切なBVSが計算されます。

  • BVAnalyzer 結果: 最後に、bva.get_valences(structure) が成功した場合、各サイトのインデックス、原子種、分数座標、および BVAnalyzer によって決定されたBVS値が表示されます。

  • プログラム終了指示: ユーザーがENTERキーを押すまでプログラムが終了しないようにするプロンプトが表示されます。