CIFファイル解析ツール cif.py

プログラムの動作

'cif.py' は、Crystallographic Information File (CIF) 形式の結晶構造データを解析し、その健全性を検証し、必要な情報を抽出・再出力するためのPythonスクリプトです。このプログラムは、特に多数のCIFファイルを扱う研究者やデータベース管理者が、結晶構造データの品質管理、検証、および標準化された形式での再利用を行う際に役立ちます。

主な機能:

CIFファイルの読み込みと解析: 指定されたCIFファイル、またはパターンに一致する複数のCIFファイルを読み込み、内部のデータ構造に変換します。
結晶情報の抽出: 読み込んだCIFデータから、格子定数、空間群、原子の種類と座標などの結晶学的基本情報を抽出します。
密度計算と検証: 単位胞の体積と内部の原子の質量から結晶の密度（g/cm$^3$）および原子密度（原子数/cm$^3$）を計算します。
データ健全性チェック: 計算された密度と原子密度が、それぞれ設定された妥当な範囲内にあるかを確認します。範囲外の場合、プログラムはエラーを出力して終了します。これにより、物理的に不合理なデータや誤った入力データを持つCIFファイルを早期に特定できます。
CIFファイルの再出力: 解析された結晶構造データから、新しいシンプルなCIFファイル（'a.cif'）および'tkCrystal'オブジェクトに基づいた詳細なCIFファイル（'b.cif'）を生成します。これにより、データ形式の標準化や、特定目的のためのデータのサブセット化が可能です。
ファイル管理: 処理が成功した入力CIFファイルを、指定されたディレクトリに移動する機能を提供します。
処理ログの記録: 処理されたすべての入力ファイル名を 'cifcheck.txt' に記録します。

解決する課題:

このプログラムは、大量のCIFファイルから有効で信頼性の高い結晶構造データを選別し、データの品質を保証するための前処理ステップを提供します。例えば、広範なデータベースからダウンロードした結晶構造データの中から、物理的に妥当なものだけをフィルタリングする際に特に有効です。

原理

'cif.py' は、主に'tklib'ライブラリの'tkCIF'と'tkCrystal'オブジェクトを用いて、CIFファイルの解析と結晶学的な計算を行います。

CIFファイルの解析: CIFファイルは、結晶構造情報を記述するための標準的なテキストファイル形式です。'tkCIF'オブジェクトは、このテキストデータから格子定数、原子座標、空間群などの結晶学的なデータアイテムを読み込み、Pythonオブジェクトとして扱える形式に変換します。
結晶構造の表現: 'tkCrystal'オブジェクトは、読み込まれた結晶構造データをカプセル化します。これには以下の情報が含まれます。
- 格子定数: $a, b, c$ (長さ) および $\alpha, \beta, \gamma$ (角度)。
- 原子情報: 各原子の種類、分数座標 $(x, y, z)$。
- 空間群: 結晶の対称性を記述する情報。
密度の計算: プログラムは、'tkCrystal'オブジェクトのメソッドを通じて、結晶の密度 ($\rho$) と原子密度 ($N_{atom\_density}$) を計算します。
- 結晶密度 ($\rho$): 単位胞あたりの総質量を単位胞の体積で割ることで計算されます。 $$\rho = \frac{\sum_{i} (\text{原子種類 } i \text{ の原子数}) \times (\text{原子種類 } i \text{ の原子量})}{\text{単位胞体積}}$$ 単位は g/cm$^3$ です。
- 原子密度 ($N_{atom\_density}$): 単位胞あたりの総原子数を単位胞の体積で割ることで計算されます。 $$N_{atom\_density} = \frac{\text{単位胞内の総原子数}}{\text{単位胞体積}}$$ 単位は /cm$^3$ です。
これらの計算は、'tkCrystal'内部で正確な物理定数と原子量を使用して実行されます。
妥当性チェック: 計算された密度は、物理的に妥当な範囲内にあるかチェックされます。
- 結晶密度: '0.8 < d < 20.0' g/cm$^3$
- 原子密度: '1.0e22 < ad < 10.0e23' /cm$^3$ これらの閾値は、一般的な結晶性物質の密度に基づいて設定されており、この範囲を外れる場合は、入力データに問題があるか、非物理的な構造を示している可能性が高いと判断され、プログラムはそこで処理を停止します。

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

'cif.py' を実行するには、以下の非標準ライブラリが必要です。

NumPy: 高度な数値計算機能を提供します。
- インストール方法: '''bash pip install numpy '''
tklib: プログラムの主要な機能であるCIFファイルの解析、結晶構造の表現、および関連する計算を行うカスタムライブラリです。
- インストール方法: このプログラムでは、'sys.path.append("d:/git/tkProg/tklib/python")' という行により、特定のローカルパスに'tklib'パッケージが存在することを前提としています。これは一般的な 'pip' によるインストールではなく、ユーザーが自身の環境に合わせて'tklib'のソースコードを配置し、パスを適切に設定する必要があります。一般的な使用のためには、'tklib'パッケージをPythonの標準的なサイトパッケージディレクトリにインストールするか、この'sys.path.append'の行を自身の'tklib'パッケージのルートディレクトリのパスに修正する必要があります。'tklib'のソースコードが公開されている場合は、その指示に従ってください。

必要な入力ファイル

プログラムは、Crystallographic Information File (CIF) 形式のファイルを入力として期待します。

ファイル形式: '.cif' 拡張子を持つテキストファイル。
データ構造: CIF形式の規約に従い、'data_' ブロックで始まり、格子定数 ('_cell_length_a', '_cell_angle_alpha' など)、空間群 ('_symmetry_space_group_name_H-M' など)、原子の種類と分数座標 ('_atom_site_type_symbol', '_atom_site_fract_x' など) を含む必要があります。

例: デフォルトでは 'COD/*.cif' というパターンが設定されており、'COD' ディレクトリ内のすべてのCIFファイルが対象となります。

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

プログラムは以下のファイルを生成します。

'cifcheck.txt':
- 内容: 処理された各入力CIFファイルのパスを1行に1つずつ記録します。これは、どのファイルが処理対象となったかを追跡するためのログファイルです。
- 例: ''' COD/example_crystal_001.cif COD/example_crystal_002.cif '''
'a.cif':
- 内容: 入力CIFファイルから抽出された主要な結晶構造データを、'tkCIF'ライブラリの'WriteSimpleCIFFile'メソッドによって、よりシンプルなCIF形式で再構成して保存されます。これは、データ検証後に基本情報のみを抽出したい場合に有用です。
- 注意: 複数の入力ファイルを処理する場合、このファイルは常に上書きされ、最後に処理されたファイルのシンプルなCIFデータが保存されます。
'b.cif':
- 内容: 'tkCrystal'オブジェクトから取得された結晶構造データを基に、'tkCIF'ライブラリの'CreateCIFFileFromCCrystal'メソッドによって、より詳細なCIF形式で再構成して保存されます。これは、内部で管理されている結晶データモデルから標準的なCIFファイルを生成する際に使用されます。
- 注意: 'a.cif'と同様に、複数の入力ファイルを処理する場合、このファイルも常に上書きされ、最後に処理されたファイルの結晶情報が保存されます。
'cif/ok/' ディレクトリ (オプション):
- 'okdir' 変数が空でない文字列に設定されている場合（デフォルトでは 'cif/ok'）、すべてのチェックに合格し、正常に処理された入力CIFファイルがこのディレクトリに移動されます。これにより、処理済みで検証済みのファイルを元の場所から分離し、整理することができます。ファイルの内容は移動前と同じです。

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

'cif.py' は、以下の形式でコマンドラインから実行できます。

'''bash python cif.py [infile_pattern] [debug_mode] '''

'infile_pattern': (オプション) 処理対象となるCIFファイルのパスまたはファイル名のパターン。ワイルドカード ('') を使用できます。省略した場合、デフォルトで 'COD/.cif' が使用されます。
'debug_mode': (オプション) デバッグレベルを示す整数。'0' はデバッグなし（デフォルト）、'1' 以上の値はより詳細なデバッグ情報を表示します。

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

ここでは、いくつかの具体的な使用例とその実行結果を説明します。事前に、テスト用のCIFファイル 'test_sample.cif' と 'test_error.cif' を準備していると仮定します。

準備: まず、'test_sample.cif' という名前で以下の内容を持つファイルを作成します。

'''cif data_example_structure _cell_length_a 5.0 _cell_length_b 5.0 _cell_length_c 5.0 _cell_angle_alpha 90.0 _cell_angle_beta 90.0 _cell_angle_gamma 90.0 symmetry_space_group_name_H-M 'P 1' loop _atom_site_type_symbol _atom_site_fract_x _atom_site_fract_y _atom_site_fract_z C 0.0 0.0 0.0 O 0.5 0.5 0.5 '''

そして、密度チェックに引っかかるような、異常に大きなセルを持つ 'test_error.cif' も作成します。

'''cif data_error_structure _cell_length_a 100.0 _cell_length_b 100.0 _cell_length_c 100.0 _cell_angle_alpha 90.0 _cell_angle_beta 90.0 _cell_angle_gamma 90.0 symmetry_space_group_name_H-M 'P 1' loop _atom_site_type_symbol _atom_site_fract_x _atom_site_fract_y _atom_site_fract_z C 0.0 0.0 0.0 O 0.5 0.5 0.5 '''

また、プログラムのデフォルト設定では、成功したファイルは 'cif/ok' ディレクトリに移動されます。事前に 'cif' ディレクトリを作成しておくと良いでしょう。

'''bash mkdir cif mkdir cif/ok '''

例 1: 単一のCIFファイルを処理する

'test_sample.cif' というファイルが現在のディレクトリに存在する場合。

'''bash python cif.py test_sample.cif '''

実行結果の説明:

プログラムは 'test_sample.cif' を読み込みます。
CIFデータおよび抽出された結晶構造情報（格子定数、原子座標など）が標準出力に表示されます。
計算された密度（例えば、'Density: 0.177 g/cm3', 'Atom Density: 2.408e+21 /cm3' のような値が表示されるでしょう。これらの値は妥当な範囲内と判断されます。）
'a.cif' と 'b.cif' というファイルが生成され、解析された結晶データがそれぞれの形式で保存されます。
'cifcheck.txt' に 'test_sample.cif' が追記されます。
'test_sample.cif' は 'cif/ok/' ディレクトリに移動されます。

例 2: 複数のCIFファイルをワイルドカードで指定し、デバッグモードを有効にする

現在のディレクトリに 'test_sample.cif' と 'test_error.cif' があると仮定します。

'''bash python cif.py test_*.cif 1 '''

実行結果の説明:

プログラムは 'test_sample.cif' を読み込みます。
- 例1と同様に、ファイルの内容、結晶情報、密度などが表示されます。
- デバッグモード ('1') のため、'tkCIF' 内部からの追加のデバッグメッセージが表示される場合があります。
- 'a.cif' と 'b.cif' が生成され、'cifcheck.txt' に 'test_sample.cif' が追記されます。
- 'test_sample.cif' は 'cif/ok/' に移動されます。
次に、'test_error.cif' を読み込みます。
- ファイルの内容、結晶情報が表示されます。
- このファイルは異常に大きなセルを持つため、計算される密度や原子密度が妥当性の閾値（'0.8 < d < 20.0' g/cm$^3$ または '1.0e22 < ad < 10.0e23' /cm$^3$）を外れます。
- プログラムはエラーメッセージ（例: 'Error in [test_error.cif]: Too low or large density ...'）を表示し、そこで終了します。
- このため、'test_error.cif' については 'a.cif' や 'b.cif' の生成は行われず、'cifcheck.txt' にも記録されず、'cif/ok/' ディレクトリにも移動されません。
- 'a.cif' と 'b.cif' は 'test_sample.cif' の内容で上書きされたままです。