tkcifobject.py ライブラリ技術ドキュメント
ライブラリの機能や目的
tkcifobject.py は、CIF (Crystallographic Information File) 形式のデータをPythonで扱うためのライブラリです。結晶学における標準的なデータ交換フォーマットであるCIFファイルの読み込み、解析、そして別の形式（tklib.tkcrystal.tkcrystal.tkCrystal オブジェクト）への変換、またはCIF形式での書き出し機能を提供します。
このライブラリの主な目的は以下の通りです。
CIFデータの解析: CIFファイルから、格子定数、空間群情報、原子サイト座標、原子タイプなどの結晶学関連情報を効率的に抽出します。
結晶構造の抽象化: 抽出したCIFデータを、より高レベルな結晶構造オブジェクト (
tkCrystal) に変換し、他の結晶学計算やシミュレーションで利用しやすくします。CIFファイルの生成: プログラム内で構築された結晶構造データから、新しいCIFファイルを生成する機能を提供します。
これにより、研究者や開発者はCIFファイルの手動解析の手間を省き、Pythonプログラム内で結晶構造データをシームレスに利用・操作できるようになります。
importする方法
tkcifobject.py ライブラリは、Pythonプログラム内で以下のようにインポートして使用できます。
from tkcifobject import tkCIFObject, tkCIFData
または、特定のクラスのみをインポートする場合：
from tkcifobject import tkCIFData
必要な非標準ライブラリとインストール方法
tkcifobject.py は、多くの機能が tklib というモジュールに依存しています。
tklib は、このライブラリと同じプロジェクトの一部であるか、または特定の環境で利用されるカスタムライブラリである可能性が高いです。標準的なPythonパッケージインデックス (PyPI) に登録されている一般的なライブラリではないため、pip install tklib のようなコマンドで直接インストールすることはできないかもしれません。
tklib モジュールは、別途プロジェクトの指示に従ってインストールまたは配置する必要があります。通常、以下のいずれかの方法で入手・設定します。
tkcifobject.pyが含まれるプロジェクトのルートディレクトリにtklibサブディレクトリが存在する。PYTHONPATH環境変数にtklibモジュールへのパスが設定されている。プロジェクトのセットアップスクリプト (
setup.pyなど) でtklibがインストールされる。
具体的なインストール方法は、このライブラリが属する上位プロジェクトのドキュメントを参照してください。
importできる変数と関数
クラス
class tkCIFObject(tkFile)
CIF処理のルートクラスであり、tklib.tkfile.tkFile を継承しています。主に基底クラスとしての役割を果たし、直接的なCIFデータ解析機能は tkCIFData クラスに委譲しています。
__init__(self, path = None, mode = 'r', **args)コンストラクタ。
pathとmodeを引数として受け取りますが、内部では特に使用せず、__crystalnameと__samplenameを空文字列で初期化します。引数:
path(str, optional): ファイルパス。デフォルトはNone。mode(str, optional): ファイルオープンモード。デフォルトは'r'(読み込み)。**args: その他のキーワード引数。
戻り値: なし
__del__(self)デストラクタ。特に何も処理しません。
引数: なし
戻り値: なし
__str__(self)オブジェクトの文字列表現を返します。
self.ClassPath()の結果を返します。引数: なし
戻り値: (str) クラスパス文字列
class tkCIFData(tkCrystalObject)
CIFファイルの具体的なデータを保持し、解析・操作する主要なクラスです。tklib.tkcrystal.tkcrystalobject.tkCrystalObject を継承しています。
__init__(self, **args)コンストラクタ。親クラス
tkCrystalObjectのコンストラクタを呼び出した後、debugフラグ、path、CIFデータ辞書data、CIF入力行リストlines、結晶名、サンプル名を初期化します。引数:
**args: 親クラスや自身の初期化に使用されるキーワード引数。
戻り値: なし
__del__(self)デストラクタ。親クラス
tkCrystalObjectのデストラクタを呼び出します。引数: なし
戻り値: なし
__str__(self)オブジェクトの文字列表現を返します。
self.ClassPath()の結果を返します。引数: なし
戻り値: (str) クラスパス文字列
get(self, key, i = None, defval = None)CIFデータ辞書
self.dataから、指定されたキーkeyの値を取得します。keyがリストの場合、リスト内のキーを順に試し、最初に見つかった値を返します。keyが整数の場合、入力行リストself.linesから指定インデックスの行を返します。iが指定された場合、key[i]の形式で辞書を検索します。値が見つからない場合は
defvalを返します。引数:
key(str or list of str or int): 検索するCIFタグ名、タグ名のリスト、または行番号。i(int, optional): タグが配列形式の場合のインデックス。例:_atom_site_fract_x[0]の0。デフォルトはNone。defval(any, optional): キーが見つからなかった場合に返すデフォルト値。デフォルトはNone。
戻り値: (any) 取得した値、または
defval。
geterrorf(self, key, i = None, defval = None)getメソッドで取得した値を浮動小数点数に変換して返します。値に
(エラー値)のような表記が含まれる場合、正規表現r'\(.*\)'でエラー部分を除去してから変換を試みます。変換に失敗した場合は
defvalを返します。引数:
key(str or list of str or int):getメソッドに渡すキー。i(int, optional):getメソッドに渡すインデックス。defval(float, optional): 変換または取得に失敗した場合のデフォルト浮動小数点数値。デフォルトはNone。
戻り値: (float) 変換された浮動小数点数値、または
defval。
getf(self, key, i = None, defval = None)getメソッドで取得した値を単純に浮動小数点数に変換して返します。変換に失敗した場合は
defvalを返します。引数:
key(str or list of str or int):getメソッドに渡すキー。i(int, optional):getメソッドに渡すインデックス。defval(float, optional): 変換または取得に失敗した場合のデフォルト浮動小数点数値。デフォルトはNone。
戻り値: (float) 変換された浮動小数点数値、または
defval。
geti(self, key, i = None, defval = None)getメソッドで取得した値を整数に変換して返します。直接整数に変換できない場合、浮動小数点数に変換してから整数に丸めることを試みます。
変換に失敗した場合は
defvalを返します。引数:
key(str or list of str or int):getメソッドに渡すキー。i(int, optional):getメソッドに渡すインデックス。defval(int, optional): 変換または取得に失敗した場合のデフォルト整数値。デフォルトはNone。
戻り値: (int) 変換された整数値、または
defval。
CheckCIF1(self, key)指定されたCIFキー (
key) がデータに存在し、geterrorfで有効な値として取得できるかを確認します。存在しない場合はエラーメッセージを標準出力に出力します。
引数:
key(str): チェックするCIFタグ名。
戻り値: (int) キーが存在し値が取得できれば
1、そうでなければ0。
CheckCIF(self)CIFデータに含まれるべき必須の結晶学パラメータ（格子定数: a, b, c, alpha, beta, gamma; 原子サイト座標: x, y, z）の存在をまとめてチェックします。
いずれかの必須キーが見つからない場合、エラーメッセージを出力しプログラムを終了します (
exit())。引数: なし
戻り値: (int) 全ての必須キーが存在すれば
1。そうでなければプログラムが終了するため、0は返りません。
LatticeParameters(self)CIFデータから格子定数 (
_cell_length_aから_cell_angle_gamma) の値を取得し、タプルとして返します。値は
geterrorfを使用して浮動小数点数として取得されます。引数: なし
戻り値: (tuple of float) (a, b, c, alpha, beta, gamma) の順で格子定数のタプル。
dataprint(self, key, i = None)指定されたCIFキー
keyの値を取得し、"{key}: {value}"の形式で標準出力に表示します。keyがリストの場合、リスト内のキーを順に試して最初に見つかった値を表示します。キーが見つからない場合はエラーメッセージを出力します。
引数:
key(str or list of str): 表示するCIFタグ名、またはタグ名のリスト。i(int, optional): タグが配列形式の場合のインデックス。デフォルトはNone。
戻り値: (int) 値が表示できれば
1、そうでなければ0。
InsertSpaceToSPGName(self, SPGName)空間群名
SPGNameに特定のルールに基づいてスペースを挿入する処理を行います。この関数には多数の正規表現置換が含まれており、空間群の表記規則に沿ってフォーマットを調整します。
引数:
SPGName(str): 空間群名文字列。
戻り値: (str) スペースが挿入された後の空間群名文字列。
FillCIFData(self)tkCrystalオブジェクトを初期化し、CIFデータに基づいて結晶名や格子定数などを設定しようとする意図を持つ関数です。現在の実装では、一部の行がコメントアウトされており、限られた機能しか実行しません。具体的には、
tkCrystalオブジェクトを作成し、結晶名を設定しますが、格子パラメータや体積などの設定はコメントアウトされています。引数: なし
戻り値: なし
GetCrystal(self)tkCIFDataオブジェクトが保持するCIF情報から、tklib.tkcrystal.tkcrystal.tkCrystalオブジェクトを生成して返します。化学名、化学式、体積、単位式量Z、空間群名とその番号、格子定数、対称操作、原子タイプ、原子サイトなどの情報をCIFデータから抽出し、
tkCrystalオブジェクトに設定します。引数: なし
戻り値: (
tklib.tkcrystal.tkcrystal.tkCrystal) 生成された結晶オブジェクト。
Print(self, PrintLines = 0)printメソッドのラッパー。引数:
PrintLines(int, optional): 入力行も表示するかどうか。1なら表示。デフォルトは0。
戻り値: なし
print(self, PrintLines = 0)CIFデータの内容を標準出力に詳細に表示します。
結晶名、化学式、単位胞情報、空間群、対称操作、原子タイプ、原子サイトの情報を整形して出力します。
PrintLinesが1の場合、元のCIF入力行も表示します。引数:
PrintLines(int, optional): 入力行も表示するかどうか。1なら表示。デフォルトは0。
戻り値: なし
nSymmetryOperation(self)CIFデータに登録されている対称操作 (
_symmetry_equiv_pos_as_xyz) の数を数えて返します。引数: なし
戻り値: (int) 対称操作の数。
SymmetryOperation(self, i)指定されたインデックス
iの対称操作文字列をCIFデータから取得して返します。取得した文字列から引用符を除去する処理 (
DelQuote) が行われます。引数:
i(int): 取得する対称操作のインデックス。
戻り値: (str) 指定されたインデックスの対称操作文字列。見つからない場合は
None。
WriteKeyVal(self, out, key, defval = None, i = None)指定されたファイルオブジェクト
outに、CIFキーkeyとその値 (self.get(key, i, defval)) を書き込みます。値が
Noneの場合は書き込みません。引数:
out(tklib.tkfile.tkFileobject): 書き込み先のファイルオブジェクト。key(str): 書き込むCIFタグ名。defval(any, optional): キーが見つからなかった場合のデフォルト値。デフォルトはNone。i(int, optional): タグが配列形式の場合のインデックス。デフォルトはNone。
戻り値: (int) 書き込みが成功すれば
1、値が見つからなければ0。
WriteSimpleCIFFile(self, NewFile, WritePublication = 1)現在の
tkCIFDataオブジェクトの内容に基づいて、簡易的なCIFファイルをNewFileで指定されたパスに書き出します。ファイル作成日、メソッド、化学情報、格子定数、空間群、対称操作、原子タイプ、原子サイトなどの情報を書き込みます。
WritePublicationが1の場合、出版物関連のタグも書き込みます。引数:
NewFile(str): 新しく作成するCIFファイルのパス。WritePublication(int, optional): 出版物関連の情報を書き込むかどうか。1なら書き込む。デフォルトは1。
戻り値: (int) ファイルの作成が成功すれば
1、失敗すれば0。
CreateCIFFileFromCCrystal(self, cry, NewFile, IsChooseRandomly = 0, IsPrint = 1)tklib.tkcrystal.tkcrystal.tkCrystalオブジェクトcryの内容からCIFファイルを生成し、NewFileで指定されたパスに書き出します。結晶の化学式、格子定数、空間群情報、対称操作、原子タイプ、原子サイトなどの情報をCIF形式で出力します。
IsChooseRandomlyとIsPrint引数は現在の実装では使用されていません。引数:
cry(tklib.tkcrystal.tkcrystal.tkCrystalobject): CIFファイルに書き出す元となる結晶オブジェクト。NewFile(str): 新しく作成するCIFファイルのパス。IsChooseRandomly(int, optional): 現在のところ未使用。デフォルトは0。IsPrint(int, optional): 現在のところ未使用。デフォルトは1。
戻り値: (int) ファイルの作成が成功すれば
1、失敗すれば0。
main scriptとして実行したときの動作
tkcifobject.py のソースコードには、if __name__ == '__main__': ブロックが存在しません。
したがって、このスクリプトをPythonインタープリタで直接実行しても、特別な処理や出力は行われません。本ライブラリは、他のPythonプログラムからインポートされ、その機能を利用されることを前提として設計されています。