`cif_read.py` ドキュメント

本ドキュメントは、Pythonスクリプト cif_read.py の機能、利用方法、および内部構造について説明します。

概要

cif_read.py は、CIF (Crystallographic Information File) 形式のファイルを読み込み、その結晶構造情報を解析し、標準出力に表示するためのスクリプトです。このスクリプトは、 tklib ライブラリの一部である tkCIF クラスを利用してファイルのパースを行います。パース後、得られた結晶オブジェクトから単位胞情報、原子座標、密度などの主要なデータを計算し、出力します。

スクリプトの元々のdocstringには ``:doc:`cif_read_usage``` と記載がありますが、これはSphinx reStructuredTextのドキュメント間リンクであり、このMyST Markdownドキュメントではリンクとして機能しません。

実行方法

スクリプトはPythonインタープリタを使用してコマンドラインから実行します。

python cif_read.py <infile> [debug_level]

例:

python cif_read.py test.cif

コマンドライン引数

引数の位置	名前	説明	型	デフォルト値
1	`infile`	処理対象となるCIFファイルのパス。	文字列	`test.cif`
2	`debug`	デバッグ情報の詳細レベルを設定する整数値。	整数	`0`

入出力ファイル

入力ファイル

CIFファイル: コマンドライン引数 infile で指定されたCIFファイル (例: test.cif) を読み込み、結晶構造データを抽出します。

出力ファイル

標準出力: 解析された結晶構造データ、単位胞情報、原子座標、密度などが表示されます。
ログファイル: infile と同じディレクトリに、 {filebody}-out.txt の形式でログファイルが生成されます（例: test-out.txt）。標準出力の内容は、このログファイルにもリダイレクトされます。

依存ライブラリ

標準ライブラリ

os: オペレーティングシステム機能へのインターフェース。
sys: Pythonインタープリタが使用する変数や関数へのアクセス。
shutil: 高レベルなファイル操作。
glob: Unixスタイルパス名のパターンマッチング。
csv: CSVファイル読み書きサポート。
pprint: データのきれいな出力。

非標準ライブラリ

numpy: 数値計算のためのライブラリ。スクリプト内で np としてインポートされ、 sin, cos, tan, pi が直接インポートされています。
tklib: 以下のモジュールがインポートされています。
- tklib.tkfile: ファイル操作に関するユーティリティ。
- tklib.tkutils: 一般的なユーティリティ関数群 (terminate, pint, pfloat, getarg, getintarg, getfloatarg など)。
- tklib.tkapplication: アプリケーション管理クラス (tkApplication)。
- tklib.tkcrystal.tkcif: CIFファイルの読み書きと解析を行うクラス (tkCIF)。
- tklib.tkcrystal.tkcrystal: 結晶構造データを扱うクラス (tkCrystal)。
- tklib.tkcrystal.tkatomtype: 原子型に関するクラス (tkAtomType)。

グローバル変数

スクリプトのトップレベルで定義されている変数です。

debug:
- 説明: デバッグ情報の出力レベルを制御する整数値。コマンドライン引数で上書きされない場合、この値が使用されます。
- デフォルト値: 0
infile:
- 説明: 入力CIFファイルのデフォルトパス。コマンドライン引数で上書きされない場合、この値が使用されます。
- デフォルト値: 'test.cif'
single:
- 説明: コード内で初期値が設定されていますが、その後の処理で利用されたり変更されたりすることはありません。
- デフォルト値: 1
findvalidstructure:
- 説明: tkCIF.ReadCIF() メソッドに渡され、妥当な構造を検索するかどうかを制御します。
- デフォルト値: 1

関数詳細

`usage()`

目的: スクリプトの利用方法とコマンド実行例を標準出力に表示します。
引数: なし。
戻り値: なし。

`terminate(message = None)`

目的: 指定されたメッセージを表示し、 usage() 関数を呼び出して利用方法を示した後、ユーザーの入力を待ってスクリプトを終了します。
- 注: この関数は tklib.tkutils から terminate という名前の関数がインポートされた後に、同じ名前でローカルに再定義されています。したがって、スクリプト内で実際に呼び出されるのはこのローカルに定義された terminate() 関数です。
引数:
- message (str, optional): 終了時に表示するメッセージ。デフォルトは None です。
戻り値: なし (プログラムを終了するため、実際の戻り値はありません)。

`main()`

目的: スクリプトのメイン処理を実行します。アプリケーションの初期設定、CIFファイルの読み込み、データ解析、結果の表示、およびログファイルへの出力リダイレクトを行います。
引数: なし。
戻り値: なし。

クラス詳細

このスクリプトは、 tklib ライブラリからインポートした以下のクラスのインスタンスを生成し、そのメソッドを利用します。これらのクラス自体の定義は cif_read.py には含まれていません。

tkApplication:
- 説明: アプリケーションの管理やログファイルへの出力リダイレクトなどの機能を提供します。
- 利用箇所: main() 関数でインスタンス化され、ログファイルパスの生成や出力リダイレクトに使用されます。
tkCIF:
- 説明: CIFファイルの読み込み、パース、およびデータ抽出を行います。
- 利用箇所: main() 関数でインスタンス化され、入力CIFファイルの読み込みに使用されます。
tkCrystal:
- 説明: 結晶構造のデータ (単位胞、原子座標など) を保持し、密度計算などの機能を提供します。
- 利用箇所: tkCIF オブジェクトから得られたCIFデータオブジェクトの GetCrystal() メソッドを介して取得され、結晶情報の表示や密度計算に使用されます。
tkAtomType:
- 説明: 原子型に関する情報を提供します。
- 利用箇所: スクリプト内でインポートされていますが、直接インスタンス化されたり利用されたりすることはありません。

処理フロー

main() 関数における処理フローは以下の通りです。

tkApplication クラスのインスタンス app を作成します。
入力ファイル infile のパスを基に、ログファイルのパス (例: test-out.txt) を生成します。
app.redirect() メソッドを呼び出し、標準出力と生成されたログファイルの両方に出力をリダイレクトするように設定します。
スクリプトの実行パラメータ (infile, single, findvalidstructure, debug) を標準出力に表示します。
tkCIF クラスのインスタンス cif を作成し、グローバル変数 debug の値を cif.debug に設定します。
cif.ReadCIF() メソッドを呼び出し、指定された infile を読み込み、その内容を cifdata に格納します。 find_valid_structure オプションにグローバル変数 findvalidstructure の値が渡されます。
cif.Close() メソッドを呼び出し、CIFファイルの処理を終了します。
cifdata の取得に失敗した場合、エラーメッセージを表示してスクリプトを終了します。
取得した cifdata オブジェクトの Print() メソッドを呼び出し、CIFファイルの生データを表示します。
cifdata.GetCrystal() メソッドを呼び出し、結晶オブジェクト cry を取得します。
cry.PrintInf() メソッドを呼び出し、結晶の基本情報を表示します。
cry.Density() メソッドを呼び出し、結晶の密度を計算します (結果は変数 d に格納されますが、表示はされません)。
cry.AtomDensity() メソッドを呼び出し、結晶の原子密度を計算します (結果は変数 ad に格納されますが、表示はされません)。
terminate() 関数を呼び出してスクリプトを終了します。

使用例

CIFファイル test.cif を読み込む最も基本的な実行例です。

python cif_read.py test.cif

デバッグレベルを 1 に設定して実行する場合の例です。

python cif_read.py test.cif 1

注意事項

このスクリプトは、 tklib と numpy ライブラリに依存しています。これらのライブラリがPython環境にインストールされていない場合、スクリプトは正しく動作しません。
グローバル変数 single はスクリプト内で定義されていますが、どの処理にも利用されていません。
tklib.tkcrystal.tkatomtype.tkAtomType クラスはインポートされていますが、スクリプト内で直接インスタンス化されたり、そのメソッドが呼び出されたりすることはありません。
スクリプトは terminate() 関数でユーザー入力を待って終了するため、バッチ処理や非対話型環境での利用には適していません。

cif_read.py ドキュメント

概要