tkcif 生成AI投入用コンテキスト

このファイルは tkcif を使うコード生成のため、マニュアルとAPIリファレンスを1ファイルへ統合したものです。API名・引数は下記APIリファレンスを優先し、存在しないAPIを推測で作らないでください。ソースコードが同時に与えられた場合はソースコードを最優先します。

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の属性名を推測で決めない。対象実装を確認してから変更する。

tkcif APIリファレンス

対象ソース: tklib2.zip（解析日: 2026-08-03）。この文書はソースコードを静的解析して生成しています。

APIの読み方

  • パッケージ公開APIは、原則としてトップレベルの __all__ に含まれる名前です。

  • モジュールAPIには、公開名（先頭が _ でない関数・クラス・メソッド）を列挙しています。

  • docstringがないAPIでは、シグネチャとソースパスを一次情報として扱ってください。

  • 生成AIは、この文書に存在しない引数・戻り値・メソッドを推測で追加しないでください。

パッケージ公開API

tkcif/__init__.py に __all__ は定義されていません。推奨import経路はマニュアルを参照してください。

モジュール一覧

モジュール

ソース

関数

クラス

tkcif

tkcif/__init__.py

0

0

tkcif.cif_inf_reader

tkcif/cif_inf_reader.py

1

0

tkcif.tkcif_normalize

tkcif/tkcif_normalize.py

25

6

tkcif.tkcif_reader

tkcif/tkcif_reader.py

10

2

tkcif

ソース: tkcif/__init__.py

このモジュールには静的解析で検出された公開関数・クラス・定数はありません。

tkcif.cif_inf_reader

ソース: tkcif/cif_inf_reader.py

cif_inf_reader.py

Console checker for tkcif_reader.py.

Usage: python cif_inf_reader.py sample.cif

Default: use read_structure(), i.e. pymatgen Structure with fallback order: pymatgen -> tkcif_base+pymatgen -> tkcif_legacy+pymatgen

Emergency tkCrystal path: python cif_inf_reader.py sample.cif --reader tkcrystal

function main

def main() -> int

ソース内docstringはありません。シグネチャと実装を参照してください。

tkcif.tkcif_normalize

ソース: tkcif/tkcif_normalize.py

tkcif_normalize.py

A small, dependency-free CIF normalizer/tester intended as the first step of "tkcif_base". It is deliberately a syntax-level normalizer, not a crystal structure interpreter.

Default behavior under main: - recursively search *.cif below the current directory - read each CIF - parse and normalize it in memory - re-parse the normalized text as a self-check - print failed paths only, plus a summary - do not write any output files

The parser is lenient for common broken CIFs: - key without inline value followed by unquoted continuation lines - semicolon text fields - quoted values - loops with quoted values - missing initial data_ header, which is repaired in memory

Author: tkCIF cleanup helper

class CIFNormalizeError — bases: Exception

Raised when CIF normalization fails.

class CIFValue

ソース内docstringはありません。シグネチャと実装を参照してください。

データクラス相当の初期化フィールド

CIFValue(raw: str, value: str, compact: str, source: str = 'normal', multiline: bool = False, warnings: list[str])

フィールド

名前

型

既定値

raw

str

必須

value

str

必須

compact

str

必須

source

str

'normal'

multiline

bool

False

warnings

list[str]

必須

class CIFLoop

ソース内docstringはありません。シグネチャと実装を参照してください。

データクラス相当の初期化フィールド

CIFLoop(keys: list[str], rows: list[list[CIFValue]], warnings: list[str])

フィールド

名前

型

既定値

keys

list[str]

必須

rows

list[list[CIFValue]]

必須

warnings

list[str]

必須

class CIFItem

ソース内docstringはありません。シグネチャと実装を参照してください。

データクラス相当の初期化フィールド

CIFItem(kind: ItemKind, key: str | None = None, value: CIFValue | None = None, loop: CIFLoop | None = None, text: str | None = None)

フィールド

名前

型

既定値

kind

ItemKind

必須

key

`str

None`

value

`CIFValue

None`

loop

`CIFLoop

None`

text

`str

None`

class CIFBlock

ソース内docstringはありません。シグネチャと実装を参照してください。

データクラス相当の初期化フィールド

CIFBlock(name: str, items: list[CIFItem], warnings: list[str])

フィールド

名前

型

既定値

name

str

必須

items

list[CIFItem]

必須

warnings

list[str]

必須

class CIFDocument

ソース内docstringはありません。シグネチャと実装を参照してください。

データクラス相当の初期化フィールド

CIFDocument(blocks: list[CIFBlock], warnings: list[str])

フィールド

名前

型

既定値

blocks

list[CIFBlock]

必須

warnings

list[str]

必須

メソッド／プロパティ

method CIFDocument.to_canonical_text

def to_canonical_text(self, *, compact_multiline: bool = True) -> str

ソース内docstringはありません。シグネチャと実装を参照してください。

function normalize_whitespace

def normalize_whitespace(value: str) -> str

Compact any whitespace sequence to a single space.

function safe_data_name

def safe_data_name(name: str) -> str

Make a simple data_ block name.

function is_reserved_word

def is_reserved_word(token: str) -> bool

ソース内docstringはありません。シグネチャと実装を参照してください。

function quote_cif_value

def quote_cif_value(value: str | None) -> str

Quote a value so that the result can be written as CIF-like text.

This is conservative. It does not attempt semantic repairs; it only makes scalar tokens safe for later parsers such as pymatgen.

function read_text_guess

def read_text_guess(path: Path) -> tuple[str, str]

Read a text file with a few practical encodings.

function normalize_newlines

def normalize_newlines(text: str) -> str

ソース内docstringはありません。シグネチャと実装を参照してください。

function split_key_value_line

def split_key_value_line(line: str) -> tuple[str, str]

Split a CIF scalar line into key and rest.

Example: _cell_length_a 4.0 -> ('_cell_length_a', '4.0') _key -> ('_key', '')

function line_starts_text_field

def line_starts_text_field(line: str) -> bool

ソース内docstringはありません。シグネチャと実装を参照してください。

function is_comment_line

def is_comment_line(line: str) -> bool

ソース内docstringはありません。シグネチャと実装を参照してください。

function is_blank_line

def is_blank_line(line: str) -> bool

ソース内docstringはありません。シグネチャと実装を参照してください。

function is_data_line

def is_data_line(line: str) -> bool

ソース内docstringはありません。シグネチャと実装を参照してください。

function is_loop_line

def is_loop_line(line: str) -> bool

ソース内docstringはありません。シグネチャと実装を参照してください。

function is_key_line

def is_key_line(line: str) -> bool

ソース内docstringはありません。シグネチャと実装を参照してください。

function is_new_item_line

def is_new_item_line(line: str) -> bool

ソース内docstringはありません。シグネチャと実装を参照してください。

function strip_inline_comment_unquoted

def strip_inline_comment_unquoted(rest: str) -> str

Strip an inline comment from an unquoted scalar value.

We only treat ' #' or leading '#' as comment start. This avoids damaging tokens that contain # without whitespace.

function parse_quoted_or_token_line

def parse_quoted_or_token_line(line: str) -> tuple[list[CIFValue], list[str]]

Tokenize one CIF data line for loop rows.

This is intentionally lenient. It understands single/double quoted values and treats '#' outside quotes as comment start. It does not implement the full CIF grammar; semicolon text fields are handled outside this function.

function parse_scalar_inline_value

def parse_scalar_inline_value(rest: str) -> CIFValue

ソース内docstringはありません。シグネチャと実装を参照してください。

function read_text_field

def read_text_field(lines: list[str], i: int) -> tuple[CIFValue, int, list[str]]

Read a semicolon-delimited CIF text field starting at line i.

function read_inferred_continuation

def read_inferred_continuation(lines: list[str], i: int) -> tuple[CIFValue, int, list[str]]

Read non-standard unquoted continuation lines until the next CIF item.

This reproduces the useful tkCIF behavior: if a key has no inline value and the next line is not clearly another key, read lines as the value until the next key/loop/data line.

function parse_loop

def parse_loop(lines: list[str], i: int) -> tuple[CIFItem, int, list[str]]

Parse loop_ beginning at line i.

function parse_cif_text

def parse_cif_text(text: str, *, source: str = '<string>') -> CIFDocument

Parse CIF text into a lenient normalized document model.

function collect_warnings

def collect_warnings(doc: CIFDocument) -> list[str]

ソース内docstringはありません。シグネチャと実装を参照してください。

function normalize_cif_file

def normalize_cif_file(path: Path, *, self_check: bool = True) -> tuple[str, CIFDocument, list[str], str]

ソース内docstringはありません。シグネチャと実装を参照してください。

function iter_cif_paths

def iter_cif_paths(root: Path, patterns: Iterable[str]) -> list[Path]

ソース内docstringはありません。シグネチャと実装を参照してください。

function main

def main() -> int

ソース内docstringはありません。シグネチャと実装を参照してください。

tkcif.tkcif_reader

ソース: tkcif/tkcif_reader.py

tkcif_reader.py

Thin compatibility layer for CIF reading.

Public API

read_structure(path) Return a pymatgen Structure object.

read_structure(path, return_info=True) Return (Structure, CIFReadInfo).

read_ase_atoms(path) Return an ASE Atoms object using ase.io.read.

read_ase_atoms(path, return_info=True) Return (ase.Atoms, CIFReadInfo).

read_tkcrystal(path) Return a legacy tkCrystal object using tkCIF.

read_tkcrystal(path, return_info=True) Return (tkCrystal, CIFReadInfo).

Backend order for read_structure()

  1. pymatgen direct CIF reading

  2. tkcif_base normalization by tkcif_normalize.py, then pymatgen

  3. ASE -> pymatgen Structure

  4. legacy tkCIF -> tkCrystal -> pymatgen Structure

Notes

  • This module intentionally catches ImportError/Exception for optional backends.

  • Legacy tkCIF support is a best-effort scaffold. You may need to adjust tkcrystal_to_pymatgen_structure() for your exact tkCrystal API.

class CIFReadError — bases: RuntimeError

Raised when all CIF reading backends fail.

class CIFReadInfo

ソース内docstringはありません。シグネチャと実装を参照してください。

データクラス相当の初期化フィールド

CIFReadInfo(path: str, backend: str = '', attempted_backends: list[str], unavailable_backends: list[str], errors: list[str], warnings: list[str], normalized: bool = False, encoding: str | None = None, fallback_object: Any | None = None)

フィールド

名前

型

既定値

path

str

必須

backend

str

''

attempted_backends

list[str]

必須

unavailable_backends

list[str]

必須

errors

list[str]

必須

warnings

list[str]

必須

normalized

bool

False

encoding

`str

None`

fallback_object

`Any

None`

メソッド／プロパティ

method CIFReadInfo.add_error

def add_error(self, backend: str, exc: BaseException) -> None

ソース内docstringはありません。シグネチャと実装を参照してください。

method CIFReadInfo.add_unavailable

def add_unavailable(self, backend: str, reason: str) -> None

ソース内docstringはありません。シグネチャと実装を参照してください。

method CIFReadInfo.short_report

def short_report(self) -> str

ソース内docstringはありません。シグネチャと実装を参照してください。

function read_structure

def read_structure(path: str | Path, *, primitive: bool = False, return_info: bool = False, backend_order: Iterable[str] | None = None) -> Any

Read one CIF file and return a pymatgen Structure object.

Parameters

path: CIF path. primitive: Passed to pymatgen parser. False preserves the CIF cell. return_info: If True, return (structure, CIFReadInfo). If False, return structure only. backend_order: Optional backend names. Available names: "pymatgen" "tkcif_base+pymatgen" "ase+pymatgen" "tkcif_legacy+pymatgen"

function read_ase_atoms

def read_ase_atoms(path: str | Path, *, return_info: bool = False, index: int | str | None = None, format: str | None = None) -> Any

Read one CIF file using ASE and return an ase.Atoms object.

This function is independent of pymatgen. It can be used as a diagnostic or as a fallback source for read_structure() through ase+pymatgen.

Parameters

path: CIF path. return_info: If True, return (ase.Atoms, CIFReadInfo). index: Passed to ase.io.read. Default None usually means the first readable configuration. Use ":" if you want to experiment with all structures outside this wrapper. format: Optional ASE format. If omitted, ASE guesses from the file name.

function read_tkcrystal

def read_tkcrystal(path: str | Path, *, return_info: bool = False, module_candidates: Iterable[str] | None = None) -> Any

Read one CIF file using legacy tkCIF and return a tkCrystal object.

This function is independent of pymatgen. It is the emergency path when pymatgen cannot be used at all.

function normalize_cif

def normalize_cif(path: str | Path) -> tuple[str, Any, list[str], str]

Normalize one CIF by tkcif_normalize.py.

Returns

normalized_text, document, warnings, encoding

function ase_atoms_to_pymatgen_structure

def ase_atoms_to_pymatgen_structure(atoms: Any) -> Any

Convert ASE Atoms to pymatgen Structure.

Preferred path: pymatgen.io.ase.AseAtomsAdaptor.get_structure(atoms)

Fallback path: manually construct Structure from atoms.cell, atoms.get_chemical_symbols(), atoms.get_scaled_positions(), and periodic boundary flags.

Notes

  • CIF occupancy/disorder information may already be simplified by ASE.

  • If the ASE Atoms object is not 3D periodic, this function still tries to create a Structure, but appends a warning only at the read_ase_atoms() stage. For molecules or clusters, pymatgen Molecule may be more suitable.

function tkcrystal_to_pymatgen_structure

def tkcrystal_to_pymatgen_structure(cry: Any) -> Any

Convert legacy tkCrystal to pymatgen Structure.

This is intentionally written as an adapter function so that you can adjust it to the exact tkCrystal API without touching read_structure().

Expected tkCrystal-like methods: cry.LatticeParameters() cry.AtomSiteList()

Expected atom-site-like methods: site.AtomNameOnly() site.Position() site.Occupancy()

function structure_summary_text

def structure_summary_text(structure: Any, *, symprec: float = 0.001) -> str

Return a human-readable summary for a pymatgen Structure.

function species_string

def species_string(site: Any) -> str

ソース内docstringはありません。シグネチャと実装を参照してください。

function ase_atoms_summary_text

def ase_atoms_summary_text(atoms: Any) -> str

Best-effort summary for ASE Atoms.

function tkcrystal_summary_text

def tkcrystal_summary_text(cry: Any) -> str

Best-effort summary for legacy tkCrystal.