cfg2cif.py 技術ドキュメント

プログラムの動作

cfg2cif.py は、特定の .cfg 形式の結晶構造ファイルを国際標準である CIF (Crystallographic Information File) 形式に変換するためのPythonスクリプトです。このプログラムは、DL_POLYなどの分子動力学シミュレーションソフトウェアが出力するCFG形式のファイルに特化しており、そこから格子情報、原子のタイプ、原子の座標を抽出し、CIFファイルとして再構築します。

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

CFGファイルからサンプル名、総原子数、各原子タイプの数、格子ベクトル、および原子の直交座標を読み取ります。
読み取られた格子ベクトルから、プログラム独自の規則に基づいて直交格子を構築します。
読み取られた直交座標を、構築された格子に基づいて分数座標に変換します。
必要に応じて、分数座標を $[0, 1)$ の範囲に正規化します。
ユーザーが指定した座標範囲（xlim, ylim, zlim）を超える原子を結果のCIFファイルから除外します。
処理された結晶構造データを tkCrystal オブジェクトとして構築し、最終的に tkCIF ライブラリを使用して標準的なCIFファイルを生成します。

このプログラムは、特定のCFG形式の構造データを、他の結晶構造解析・可視化ソフトウェアで利用可能なCIF形式に変換することで、異種ソフトウェア間の連携を可能にします。

原理

cfg2cif.py は、入力されたCFGファイルから以下の情報を抽出し、CIFファイル形式に変換します。

格子ベクトルの解釈: CFGファイル内の Defining vectors 行の直後に続く1行から格子ベクトルを読み取ります。このプログラムは、この1行が直交格子の辺長の半分の値（例えば $L/2~0~0$）を示しているという、特殊な慣習を前提としています。具体的には、CFGファイルから読み込んだ1行目のベクトル成分を全て2倍し、その最初の成分 aij[0][0] を直交格子の各辺の長さ $L$ とします。これにより、格子ベクトル $\vec{a}$, $\vec{b}$, $\vec{c}$ は以下のように構築されます。

\[\begin{split} \begin{align*} \vec{a} &= [2 \cdot \text{CFG_val}_x, 0, 0] \\ \vec{b} &= [0, 2 \cdot \text{CFG_val}_x, 0] \\ \vec{c} &= [0, 0, 2 \cdot \text{CFG_val}_x] \end{align*} \end{split}\]

ここで $\text{CFG_val}_x$ はCFGファイルの Defining vectors の次の行の最初の数値です。この設定により、読み込まれたCFGの1行目 A B C が例えば 5.0 0.0 0.0 であった場合、aij[0][0] は 5.0 * 2.0 = 10.0 となり、最終的な格子ベクトルは $[10.0, 0.0, 0.0]$, $[0.0, 10.0, 0.0]$, $[0.0, 0.0, 10.0]$ と解釈され、10Åの立方晶系が構築されます。これは一般的なCFGファイルにおける3つの格子ベクトルがそれぞれ独立した行に記述される形式とは異なる、このプログラムに特化した解釈です。
原子座標の変換と正規化: CFGファイルから読み込まれた原子の直交座標 $(x_c, y_c, z_c)$ は、上記で構築された格子ベクトルに基づいて分数座標 $(x_f, y_f, z_f)$ に変換されます。オプション freduce01 が 1 の場合、これらの分数座標は $[0, 1)$ の範囲に正規化されます。これは、各座標からその床関数（floor function）を引くことで実現されます。 $$ x_{\text{reduced}} = x_f - \lfloor x_f \rfloor $$ 同様に $y$ と $z$ 座標も処理されます。
原子のフィルタリング: 正規化された（または正規化されていない）分数座標が、コマンドライン引数で指定された xlim, ylim, zlim の値を超える場合、その原子はCIFファイルから除外されます。具体的には、 $$ x_f > \text{xlim} \quad \text{or} \quad y_f > \text{ylim} \quad \text{or} \quad z_f > \text{zlim} $$ の条件を満たす原子は破棄されます。これにより、スーパーセルなどの大規模な構造から特定の単位セル領域の原子のみを抽出することが可能になります。

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

cfg2cif.py は、以下の非標準ライブラリに依存しています。

numpy: 数値計算全般に利用されます。
scipy: 科学技術計算ライブラリ。interp1d がインポートされていますが、cfg2cif 関数内で直接使用されているわけではありません。
matplotlib: グラフ描画ライブラリ。pyplot がインポートされていますが、cfg2cif 関数内で直接使用されているわけではありません。

これらのライブラリは pip コマンドでインストールできます。

pip install numpy scipy matplotlib

また、このスクリプトは以下のカスタムライブラリに依存しています。

tkfile
tkutils (関数: IsDir, IsFile, SplitFilePath, terminate, pint, pfloat, getarg, getintarg, getfloatarg)
tksci.tksci (関数: Reduce01, Round)
tksci.tkmatrix (関数: make_matrix1, make_matrix2, make_matrix3)
tkcrystal.tkcif (クラス: tkCIF, tkCIFData)
tkcrystal.tkcrystal (クラス: tkCrystal)
tkcrystal.tkatomtype (クラス: tkAtomType)

これらのカスタムライブラリは、スクリプトの冒頭で sys.path.append を用いて指定されたパス (c:/Programs/python/lib および d:/Programs/python/lib) からインポートされます。これらのライブラリは通常 pip ではインストールできないため、ユーザーは別途これらのライブラリのソースコードを入手し、指定されたパスに配置する必要があります。

必要な入力ファイル

入力ファイルは .cfg 拡張子を持つテキストファイルで、特定の書式に従っている必要があります。デフォルトのファイル名は STD0.cfg です。

ファイル形式の要件:

ヘッダー: 最初の2行は任意のコメントまたは情報行です。プログラムは2行目をサンプル名として読み込みます。
総原子数: molecules of all という文字列を含む行があり、その行から総原子数が数値として抽出されます。
格子ベクトル: Defining vectors という文字列を含む行の直後に1行だけ読み込まれます。この行は3つの浮動小数点数（例: 5.0000000000000000 0.0000000000000000 0.0000000000000000）で構成され、上述の「原理」セクションで説明した特殊な方法で格子ベクトルが構築されます。
原子タイプの数: molecules of type という文字列を含む行が原子タイプごとに現れ、その行からそのタイプの原子数が抽出されます。
原子座標: 各 molecules of type 行の2行下から、そのタイプの原子の直交座標が1行に1つの原子につき x y z の形式で記述されます。空白行はスキップされます。
原子タイプマッピング: プログラム内のグローバル変数 atomtypes = ['O', 'Zn', 'Ga', 'In'] に定義されている順序で、CFGファイル中の原子タイプがマッピングされます。これはCFGファイル自体に原子タイプ名が明示的に書かれていない場合に重要です。

入力ファイルの例 (`example.cfg`):

# This is a comment line
MySample
Comment line for atom type 1
molecules of all     100 atoms
   0.0000000000000000   0.0000000000000000   0.0000000000000000
   0.0000000000000000   0.0000000000000000   0.0000000000000000
   0.0000000000000000   0.0000000000000000   0.0000000000000000
   0.0000000000000000   0.0000000000000000   0.0000000000000000
Defining vectors
 5.0000000000000000   0.0000000000000000   0.0000000000000000
   0.0000000000000000   0.0000000000000000   0.0000000000000000
   0.0000000000000000   0.0000000000000000   0.0000000000000000
   0.0000000000000000   0.0000000000000000   0.0000000000000000
molecules of type     50 atoms
# This line is skipped
# This line is skipped
 0.100000   0.200000   0.300000
 0.150000   0.250000   0.350000
 ... (残り48原子の座標) ...
molecules of type     50 atoms
# This line is skipped
# This line is skipped
 0.400000   0.500000   0.600000
 0.450000   0.550000   0.650000
 ... (残り48原子の座標) ...

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

出力ファイルは、入力CFGファイルと同じベース名を持ち、拡張子が .cif になります。例えば、入力が STD0.cfg であれば、出力は STD0.cif となります。

ファイル内容:

CIFファイルは、結晶構造情報を記述するための標準的なテキストベースのフォーマットです。生成されるCIFファイルには以下の情報が含まれます。

データブロックヘッダー: data_MySample のような形式で、入力ファイルから読み取られたサンプル名が使用されます。
セル情報: 変換された格子定数 _cell_length_a, _cell_length_b, _cell_length_c と、セル角度 _cell_angle_alpha, _cell_angle_beta, _cell_angle_gamma が（通常は90度）記述されます。
対称性情報: 空間群名 (_symmetry_space_group_name_H-M) と国際表番号 (_symmetry_Int_Tables_number) は、デフォルトで P 1 と 1 が設定されます。
原子サイト情報: 各原子のタイプ (_atom_site_type_symbol、atomtypes グローバル変数からマッピング)、サイトラベル (_atom_site_label)、および分数座標 (_atom_site_fract_x, _atom_site_fract_y, _atom_site_fract_z) がリスト形式で記述されます。B因子や占有率などの情報は、このプログラムではデフォルト値が使用されるか、含まれません。

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

プログラムの基本的な使用方法は以下の通りです。

python cfg2cif.py [cfgfile] [reduce01] [xlim] [ylim] [zlim]

引数の説明:

cfgfile: 入力するCFGファイルのパス。省略した場合、デフォルトで STD0.cfg が使用されます。
reduce01: 整数値。
- 1: 原子座標を [0, 1) の範囲に正規化します（デフォルト）。
- 0: 原子座標の正規化を行いません。
xlim: 浮動小数点数。x座標がこの値より大きい原子は出力から除外されます。デフォルトは 1.0。
ylim: 浮動小数点数。y座標がこの値より大きい原子は出力から除外されます。デフォルトは 1.0。
zlim: 浮動小数点数。z座標がこの値より大きい原子は出力から除外されます。デフォルトは 1.0。

例:

python cfg2cif.py STD0.cfg 1 1.0 1.0 1.0

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

例1: デフォルト設定での変換

STD0.cfg ファイルを読み込み、デフォルト設定で STD0.cif を生成します。分数座標は [0, 1) に正規化され、すべての座標が $1.0$ 以下の原子が含められます。

python cfg2cif.py

実行結果の説明: プログラムは STD0.cfg を読み込み、その内容（サンプル名、格子ベクトル、原子座標）を基に tkCrystal オブジェクトを構築します。この際、座標は [0, 1) に正規化され、x, y, z 座標が $1.0$ を超える原子は除外されます。最終的に、これらの情報が記述された STD0.cif ファイルが同じディレクトリに生成されます。コンソールには、処理の進捗、読み込まれた情報、生成されるCIFファイル名が表示されます。

例2: 特定のCFGファイルを指定し、座標の正規化を無効にする

my_structure.cfg ファイルを読み込み、分数座標の [0, 1) への正規化を行わずに my_structure.cif を生成します。座標の除外範囲はデフォルトの 1.0 です。

python cfg2cif.py my_structure.cfg 0

実行結果の説明: my_structure.cfg からデータが読み込まれ、tkCrystal オブジェクトが構築されます。この際、reduce01 引数が 0 であるため、原子の分数座標は [0, 1) への正規化が行われません。x, y, z 座標が $1.0$ を超える原子は除外されます。結果として my_structure.cif が生成され、分数座標は元の（正規化されていない）範囲を保持します。

例3: スーパーセルから特定の単位セル領域を抽出する

supercell.cfg ファイルを読み込み、分数座標を [0, 1) に正規化した上で、$x, y, z$ 座標のいずれかが $0.5$ を超える原子は除外し、supercell.cif を生成します。これにより、スーパーセルの中心にある $0 \le x < 0.5$, $0 \le y < 0.5$, $0 \le z < 0.5$ の領域内の原子のみを抽出できます。

python cfg2cif.py supercell.cfg 1 0.5 0.5 0.5

実行結果の説明: supercell.cfg が読み込まれ、分数座標は [0, 1) に正規化されます。さらに、xlim=0.5, ylim=0.5, zlim=0.5 が指定されているため、$x, y, z$ のいずれかの座標が $0.5$ を超える原子はすべて破棄されます。これにより、元のスーパーセルから、分数座標が [0, 0.5) の範囲に収まる原子だけが抽出され、新しい supercell.cif ファイルとして保存されます。この機能は、大規模なシミュレーション構造から、より小さな単位構造を解析する際に特に有用です。