tkcrystal マニュアル

1. 役割

tkcrystal は、結晶構造・元素・対称性・XRD情報を、後段で扱いやすい組み込み型中心の辞書として返す薄いwrapperです。現在の実装では主に pymatgen.Structure を入力し、pymatgen backendを利用します。

2. 推奨import

from tkcrystal import (
    get_crystal_inf,
    get_lattice_inf,
    get_composition_inf,
    get_density_inf,
    get_site_inf,
    get_neighbor_inf,
    get_spg_inf,
    get_symmetry_operations_inf,
    get_xrd_inf,
    get_atom_inf,
)

3. CIFから構造情報を得る例

from tkcif.tkcif_reader import read_structure
from tkcrystal import get_crystal_inf, get_xrd_inf

structure = read_structure("sample.cif")
info = get_crystal_inf(structure, include_sites=True, max_sites=100)
xrd = get_xrd_inf(
    structure,
    wavelength="CuKa1",
    two_theta_range=(10.0, 80.0),
)

戻り値は辞書なので、JSON化・Markdownレポート化・GUI表示に向きます。

4. 機能分類

分類

API

元素・組成式

get_atom_inf, get_composition_inf_from_formula

構造概要

get_crystal_inf, get_lattice_inf, get_composition_inf, get_density_inf, get_site_inf

近接原子

get_neighbor_inf

空間群

get_spg_inf

対称操作

get_symmetry_operations_inf, expand_coordinates_spg

構造標準化

symmetrize_structure

粉末XRD

get_xrd_inf, get_available_xray_wavelengths

5. backend

多くの構造APIは backend="auto" を受け取ります。現状、実用実装はpymatgenです。

info = get_lattice_inf(structure, backend="pymatgen")

未実装backendを指定すると BackendNotAvailableError または RuntimeError になります。生成コードでは、存在しないASE専用backend等を仮定しないでください。

6. 構造概要

info = get_crystal_inf(
    structure,
    include_sites=True,
    max_sites=50,
    include_symmetry=True,
    symprec=1.0e-3,
)

include_sites=False は大きなsupercellで出力を抑える場合に有効です。max_sites は返却するsite情報数を制限しますが、元構造は変更しません。

7. 対称性

spg = get_spg_inf(structure, symprec=1.0e-3, angle_tolerance=5.0)
ops = get_symmetry_operations_inf(structure, max_ops=100)

座標展開:

from tkcrystal import expand_coordinates_spg

expanded = expand_coordinates_spg(221, "0.0,0.0,0.0")

expand_coordinates_spg() はfractional coordinateを [0, 1) に折り返し、rmin 以内の重複を除きます。

symmetrize_structure() の mode は次です。

  • symmetrized

  • refined

  • conventional_standard

  • primitive_standard

8. XRD

pattern = get_xrd_inf(
    structure,
    wavelength="CuKa1",
    two_theta_range=(5.0, 90.0),
    symprec=0.0,
    max_peaks=None,
)

各peakは two_theta, intensity, d_hkl, hkl, multiplicity, hkls を含む辞書です。強度はpymatgen XRDCalculator の規格化強度です。

9. エラーと精度上の注意

  • symprec により空間群判定や等価siteが変わります。解析目的に合わせて値を記録してください。

  • 部分占有、disorder、酸化状態推定は入力情報とpymatgenの挙動に依存します。

  • XRDは理想構造からの計算patternであり、装置分解能、配向、吸収、サイズ・歪み broadeningは含みません。

  • 辞書化のため一部オブジェクトは文字列・list・floatへ変換されます。厳密なpymatgen操作が必要な場合は元Structureを保持してください。

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

  1. 通常は tkcrystal トップレベル公開関数を使う。

  2. 構造入力は pymatgen.Structure とし、CIFパスを直接渡さない。CIFは先に tkcif.read_structure() 相当で読む。

  3. 戻り値は辞書であり、属性アクセスではなくキーアクセスを使う。

  4. symmetrize_structure() だけは構造オブジェクトを返すAPIとして区別する。

  5. XRD計算結果を測定強度や定量相分析結果と同一視しない。

  6. symprec と angle_tolerance を再現可能性のため明示・保存する。