tkcif マニュアル

1. 役割

tkcif は、CIFを単一のreaderに固定せず、複数backendを順番に試して可能な限り pymatgen.Structure を得るための互換・正規化レイヤーです。壊れ気味のCIFに対しては、構文正規化、ASE経由、旧 tkCIF 経由をfallbackとして使います。

2. 推奨import

現在の tkcif/__init__.py は公開関数を再exportしていません。次のモジュールimportを使ってください。

from tkcif.tkcif_reader import (
    CIFReadError,
    CIFReadInfo,
    read_structure,
    read_ase_atoms,
    read_tkcrystal,
    normalize_cif,
)

from tkcif import read_structure は現状のソースでは使えません。

3. 最小例

from tkcif.tkcif_reader import read_structure

structure, info = read_structure("sample.cif", return_info=True)
print(structure.formula)
print(info.backend)
print(info.short_report())

通常は primitive=False のままにして、CIFに書かれたセルを保持します。

4. read_structure() のfallback順序

既定順序は次です。

  1. pymatgen: pymatgenで直接読む

  2. tkcif_base+pymatgen: tkcif_normalize.py で正規化してからpymatgenで読む

  3. ase+pymatgen: ASEで読み、pymatgen.Structureへ変換

  4. tkcif_legacy+pymatgen: 旧 tkCIF → tkCrystal → pymatgen.Structure

特定backendだけを試す場合:

structure, info = read_structure(
    "sample.cif",
    return_info=True,
    backend_order=["tkcif_base+pymatgen", "ase+pymatgen"],
)

すべて失敗すると CIFReadError が発生し、試行backendと各エラーがメッセージに含まれます。

5. 診断情報 CIFReadInfo

主要フィールド:

フィールド

内容

path

入力CIFパス

backend

成功したbackend

attempted_backends

試行したbackend一覧

unavailable_backends

未導入・利用不能backend

errors

読み込み失敗の要約

warnings

parser警告

normalized

正規化を経由したか

encoding

推定された文字コード

fallback_object

ASE Atomsまたは旧tkCrystalの参照

return_info=True は、研究データの再現性確保や大量処理時のログ保存に推奨です。

6. ASEまたは旧tkCrystalを直接得る

from tkcif.tkcif_reader import read_ase_atoms, read_tkcrystal

atoms = read_ase_atoms("sample.cif")
legacy_crystal = read_tkcrystal("sample.cif")

これらはpymatgenに依存しない診断経路です。read_tkcrystal() のlegacy module候補は module_candidates= で上書きできます。

7. CIF正規化

from tkcif.tkcif_reader import normalize_cif

normalized_text, document, warnings, encoding = normalize_cif("broken.cif")

ファイルとして正規化する低レベルAPIは tkcif.tkcif_normalize.normalize_cif_file() です。正規化層は、空白・改行・引用・loop・複数行text fieldなどをlenientに処理しますが、結晶学的妥当性を保証するものではありません。

8. 構造変換ヘルパー

  • ase_atoms_to_pymatgen_structure(atoms)

  • tkcrystal_to_pymatgen_structure(cry)

旧 tkCrystal の具体的な属性構造が環境ごとに異なる場合、後者のadapter調整が必要です。

9. サマリー生成

from tkcif.tkcif_reader import structure_summary_text

print(structure_summary_text(structure, symprec=1.0e-3))

ASEと旧tkCrystalにも、それぞれbest-effortのサマリー関数があります。

10. CLI

python -m tkcif.cif_inf_reader sample.cif
python -m tkcif.cif_inf_reader sample.cif --reader ase
python -m tkcif.cif_inf_reader sample.cif --reader tkcrystal

11. 依存関係

  • 主backend: pymatgen

  • optional fallback: ase

  • legacy fallback: 旧 tkCIF / tkCrystal 実装

  • 正規化コア: 標準ライブラリ中心

12. 生成AI向けコード生成ルール

  1. 既定の戻り値は pymatgen.Structure とし、辞書やASE Atomsと誤認しない。

  2. 読み込み経路を記録する必要があるコードでは必ず return_info=True を使う。

  3. tkcif トップレベルから関数をimportせず、tkcif.tkcif_reader を使う。

  4. CIF読込失敗を単純な FileNotFoundError だけと仮定せず、CIFReadError を扱う。

  5. 正規化は構文補正であり、占有率、空間群、組成、密度の物理的妥当性検証とは分ける。

  6. 旧tkCrystal adapterの属性名を推測で決めない。対象実装を確認してから変更する。