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

プログラムの動作

xyz2cif.py は、化学構造や結晶構造のデータを記述するために広く用いられるXYZ形式の原子座標ファイルと、格子ベクトル情報を定義するCFGファイルを読み込み、Crystallographic Information File (CIF) 形式のファイルを出力するPythonスクリプトです。

このプログラムの主な機能は以下の通りです。

入力ファイルの読み込み: XYZファイルから原子の種類とデカルト座標を、CFGファイルからサンプル名と格子ベクトル（単位胞の基底ベクトル）を読み込みます。
座標変換: 読み込んだデカルト座標を、CFGファイルで定義された格子ベクトルに基づく分数座標に変換します。
座標の正規化: オプションとして、分数座標を $[0, 1)$ の範囲に正規化します。
結晶オブジェクトの構築: 変換された原子座標と格子ベクトル情報を用いて、結晶構造を表す内部オブジェクトを構築します。
CIFファイルの生成: 構築された結晶オブジェクトの情報に基づき、CIFファイルを生成し、ディスクに保存します。

このプログラムは、XYZ形式で記述された構造情報（特に分子動力学シミュレーションの出力など）を、結晶構造解析ソフトウェアやデータベースで広く利用されるCIF形式に変換するという課題を解決します。

原理

xyz2cif.py の中心的な処理は、デカルト座標から分数座標への変換です。

格子ベクトルの読み込み: CFGファイルから3つの格子ベクトル $\vec{a}_1, \vec{a}_2, \vec{a}_3$ が読み込まれます。これらのベクトルは、単位胞の基底を定義します。
デカルト座標から分数座標への変換: 原子のデカルト座標 $\vec{P}_c = (x_c, y_c, z_c)^T$ が与えられたとき、分数座標 $\vec{P}_f = (x_f, y_f, z_f)^T$ は以下の線形変換によって定義されます。 $$ \vec{P}_c = x_f \vec{a}_1 + y_f \vec{a}_2 + z_f \vec{a}_3 $$ これを行列形式で表すと、格子ベクトルを列ベクトルとする行列 $A = [\vec{a}_1 \quad \vec{a}_2 \quad \vec{a}_3]$ を用いて、以下のようになります。 $$ \vec{P}_c = A \vec{P}_f $$ したがって、分数座標 $\vec{P}_f$ は、行列 $A$ の逆行列 $A^{-1}$ を用いて次のように計算されます。 $$ \vec{P}_f = A^{-1} \vec{P}_c $$ この計算は、内部で利用される tkCrystal オブジェクトの CartesianToFractional メソッドによって実行されます。
分数座標の正規化: 変換された分数座標 $(x_f, y_f, z_f)$ は、単位胞の外側にある場合もあります。プログラムは、オプションとして reduce01 引数が 1 に設定されている場合、Reduce01 関数を用いて各分数座標成分を $[0, 1)$ の範囲に正規化します。これは、各成分 $u$ に対して $u \pmod 1$ の操作を行うことに相当します（ただし、$u=1$ の場合は $0$ となります）。

最終的に、これらの情報が tkCrystal オブジェクトに集約され、tkCIFData オブジェクトを通じてCIF形式で出力されます。

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

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

numpy: 数値計算、特に配列操作や行列演算に使用されます。
scipy: 科学技術計算ライブラリ。本プログラムでは interp1d がインポートされていますが、直接使用されていないようです。しかし、tksciなどのカスタムライブラリが内部で利用している可能性があります。
matplotlib: グラフ描画ライブラリ。本プログラムでは pyplot がインポートされていますが、直接使用されていません。

これらのライブラリは、通常 pip を使ってインストールできます。

pip install numpy scipy matplotlib

また、以下のカスタムライブラリが使用されています。

tkfile
tkutils
tksci (特に tksci.tksci, tksci.tkmatrix)
tkcrystal (特に tkcrystal.tkcif, tkcrystal.tkcrystal, tkcrystal.tkatomtype)

これらのカスタムライブラリは、標準のPyPIリポジトリでは提供されていません。スクリプト内の sys.path.append の記述から、これらのライブラリは特定のパス（c:/Programs/python/lib および d:/Programs/python/lib）に配置されていることを想定しています。したがって、これらのライブラリはスクリプトの実行環境に導入され、上記のパスからアクセス可能である必要があります。具体的なインストール方法は、これらのライブラリの提供元に依存しますが、通常は手動で指定されたディレクトリに配置するか、環境変数 PYTHONPATH を設定することで利用可能になります。

必要な入力ファイル

xyz2cif.py は、以下の2種類の入力ファイルを必要とします。ファイル名はコマンドライン引数で指定できますが、指定がない場合はデフォルト名が使用されます。

XYZファイル (.xyz): 原子の種類とデカルト座標が記述されたファイルです。
- デフォルト名: STD0.xyz
- 形式: 最初の行に原子の総数が記述されます。 2行目はコメント行（任意）。 3行目以降は、各行に 原子名 x座標 y座標 z座標 の形式で原子の情報が記述されます。
例 (my_structure.xyz):
```
3
My awesome molecule
C    0.000    0.000    0.000
H    1.090    0.000    0.000
O    0.000    1.210    0.000
```
CFGファイル (.cfg): 結晶の格子ベクトル情報とサンプル名が記述されたファイルです。
- デフォルト名: STD0.cfg
- 形式: 最初の行は任意のコメント行。 2行目にサンプル名が記述されます。その後の数行は任意のコメント行。 Defining vectors というマーカー行の後に、3行にわたって3つの格子ベクトルが記述されます。各行は ax ay az の形式で3つの浮動小数点数を含みます。
例 (my_structure.cfg):
```
Configuration for my_structure
MyCrystalSample
Lattice parameter settings
Defining vectors
10.000000000000    0.000000000000    0.000000000000
0.000000000000   10.000000000000    0.000000000000
0.000000000000    0.000000000000   10.000000000000
```
注意: CFGファイルのファイル名は、XYZファイルと同じボディ名である必要があります。例えば、my_structure.xyz を入力とする場合、自動的に my_structure.cfg が検索されます。

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

プログラムの実行により、以下のファイルが生成されます。

CIFファイル (.cif): Crystallographic Information File 形式のファイルです。これは結晶構造情報を記述するための標準的な形式であり、国際結晶学連合 (IUCr) によって定義されています。
- ファイル名: 入力XYZファイルと同じボディ名と .cif 拡張子を持つファイルが生成されます（例: my_structure.cif）。
- 内容:
  - _audit_creation_date や _audit_creation_method などの監査情報。
  - _chemical_name_common (サンプル名)。
  - _cell_length_a, _cell_length_b, _cell_length_c (格子定数 $a, b, c$)。
  - _cell_angle_alpha, _cell_angle_beta, _cell_angle_gamma (格子角 $\alpha, \beta, \gamma$)。
  - _cell_volume (単位胞の体積)。
  - _symmetry_space_group_name_H-M (P1空間群として記述されます)。
  - _atom_site_type_symbol, _atom_site_fract_x, _atom_site_fract_y, _atom_site_fract_z (各原子の記号と分数座標)。
このファイルは、VESTAやMercuryのような結晶構造可視化ソフトウェアで開いたり、結晶学関連のデータベースに登録したりするために使用できます。

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

xyz2cif.py は以下の形式でコマンドラインから実行します。

python xyz2cif.py xyzfile (reduce01)

xyzfile: 変換するXYZファイルのパスと名前を指定します。このファイル名に基づいて、同名のCFGファイルが自動的に検索されます。
(reduce01): オプションの引数です。
- 1 を指定すると、生成されるCIFファイル内の分数座標は $[0, 1)$ の範囲に正規化されます。
- 0 (または省略) を指定すると、分数座標の正規化は行われません。

例:

python xyz2cif.py STD0.xyz 1

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

ここでは、my_structure.xyz と my_structure.cfg というファイルがカレントディレクトリにあると仮定して、具体的な使用例を示します。

例1: 基本的な変換と分数座標の正規化

分数座標を $[0, 1)$ の範囲に正規化してCIFファイルを生成する場合。

python xyz2cif.py my_structure.xyz 1

実行結果の説明: プログラムはまず、my_structure.xyz と my_structure.cfg を読み込みます。 my_structure.cfg からサンプル名 (MyCrystalSample) と格子ベクトル情報が読み込まれ、my_structure.xyz から原子数と各原子のデカルト座標が読み込まれます。これらの情報に基づき、デカルト座標は分数座標に変換され、reduce01 引数が 1 であるため、すべての分数座標が $[0, 1)$ の範囲に正規化されます。最終的に、my_structure.cif という名前のCIFファイルが生成され、カレントディレクトリに保存されます。このファイルには、MyCrystalSample という名前、格子定数、および正規化された原子の分数座標が含まれます。

例2: 分数座標の正規化を行わない変換

分数座標の正規化を行わずにCIFファイルを生成する場合（reduce01 を省略または 0 を指定）。

python xyz2cif.py my_structure.xyz

または

python xyz2cif.py my_structure.xyz 0

実行結果の説明: my_structure.cif が生成される点は例1と同じですが、reduce01 引数が省略または 0 であるため、原子の分数座標は $[0, 1)$ の範囲に強制的に正規化されません。座標が単位胞の外側にある場合、そのままの値がCIFファイルに記述されます。これは、特定のシミュレーション結果など、元の相対位置を保持したい場合に有用です。