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

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

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向けコード生成ルール

通常は tkcrystal トップレベル公開関数を使う。
構造入力は pymatgen.Structure とし、CIFパスを直接渡さない。CIFは先に tkcif.read_structure() 相当で読む。
戻り値は辞書であり、属性アクセスではなくキーアクセスを使う。
symmetrize_structure() だけは構造オブジェクトを返すAPIとして区別する。
XRD計算結果を測定強度や定量相分析結果と同一視しない。
symprec と angle_tolerance を再現可能性のため明示・保存する。

tkcrystal APIリファレンス

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

APIの読み方

パッケージ公開APIは、原則としてトップレベルの __all__ に含まれる名前です。
モジュールAPIには、公開名（先頭が _ でない関数・クラス・メソッド）を列挙しています。
docstringがないAPIでは、シグネチャとソースパスを一次情報として扱ってください。
生成AIは、この文書に存在しない引数・戻り値・メソッドを推測で追加しないでください。

パッケージ公開API

from tkcrystal import (
    get_atom_inf,
    get_composition_inf_from_formula,
    get_xrd_inf,
    get_available_xray_wavelengths,
    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,
)

名前	推奨用途
`get_atom_inf`	トップレベルから安定してimportできる公開API
`get_composition_inf_from_formula`	トップレベルから安定してimportできる公開API
`get_xrd_inf`	トップレベルから安定してimportできる公開API
`get_available_xray_wavelengths`	トップレベルから安定してimportできる公開API
`get_crystal_inf`	トップレベルから安定してimportできる公開API
`get_lattice_inf`	トップレベルから安定してimportできる公開API
`get_composition_inf`	トップレベルから安定してimportできる公開API
`get_density_inf`	トップレベルから安定してimportできる公開API
`get_site_inf`	トップレベルから安定してimportできる公開API
`get_neighbor_inf`	トップレベルから安定してimportできる公開API
`get_spg_inf`	トップレベルから安定してimportできる公開API
`get_symmetry_operations_inf`	トップレベルから安定してimportできる公開API
`expand_coordinates_spg`	トップレベルから安定してimportできる公開API
`symmetrize_structure`	トップレベルから安定してimportできる公開API

モジュール一覧

モジュール	ソース	関数	クラス
`tkcrystal`	`tkcrystal/__init__.py`	0	0
`tkcrystal.atom`	`tkcrystal/atom.py`	2	0
`tkcrystal.backends`	`tkcrystal/backends.py`	6	2
`tkcrystal.diffraction`	`tkcrystal/diffraction.py`	2	0
`tkcrystal.info`	`tkcrystal/info.py`	6	0
`tkcrystal.printer`	`tkcrystal/printer.py`	3	0
`tkcrystal.symmetry`	`tkcrystal/symmetry.py`	6	0

`tkcrystal`

ソース: tkcrystal/__init__.py

tkcrystal: simple dictionary wrappers for crystal-structure information.

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

`tkcrystal.atom`

ソース: tkcrystal/atom.py

function `get_atom_inf`

def get_atom_inf(atom: str | int | Any, *, backend: str = 'pymatgen') -> dict[str, Any]

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

function `get_composition_inf_from_formula`

def get_composition_inf_from_formula(formula: str, *, backend: str = 'pymatgen') -> dict[str, Any]

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

`tkcrystal.backends`

ソース: tkcrystal/backends.py

class `BackendError` — bases: `RuntimeError`

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

class `BackendNotAvailableError` — bases: `BackendError`

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

function `normalize_backend`

def normalize_backend(backend: str | None = 'auto') -> str

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

function `require_pymatgen`

def require_pymatgen() -> None

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

function `is_pymatgen_structure`

def is_pymatgen_structure(obj: Any) -> bool

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

function `dispatch_structure_backend`

def dispatch_structure_backend(structure: Any, backend: str | None = 'auto') -> str

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

function `safe_float`

def safe_float(x: Any, default = None)

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

function `to_builtin`

def to_builtin(obj: Any) -> Any

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

`tkcrystal.diffraction`

ソース: tkcrystal/diffraction.py

function `get_available_xray_wavelengths`

def get_available_xray_wavelengths(*, backend: str = 'pymatgen') -> dict[str, Any]

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

function `get_xrd_inf`

def get_xrd_inf(structure: Any, *, backend: str = 'auto', wavelength: str | float = 'CuKa1', two_theta_range = (10.0, 80.0), symprec: float = 0.0, max_peaks: int | None = None) -> dict[str, Any]

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

`tkcrystal.info`

ソース: tkcrystal/info.py

公開定数・モジュール変数

名前	型/値
`AMU_TO_G`	`1.6605390666e-24`
`ANG3_TO_CM3`	`1e-24`

function `get_lattice_inf`

def get_lattice_inf(structure: Any, *, backend: str = 'auto') -> dict[str, Any]

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

function `get_site_inf`

def get_site_inf(structure: Any, *, backend: str = 'auto', max_sites: int | None = None, include_cartesian = True) -> dict[str, Any]

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

function `get_composition_inf`

def get_composition_inf(structure: Any, *, backend: str = 'auto') -> dict[str, Any]

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

function `get_density_inf`

def get_density_inf(structure: Any, *, backend: str = 'auto') -> dict[str, Any]

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

function `get_crystal_inf`

def get_crystal_inf(structure: Any, *, backend: str = 'auto', include_sites = True, max_sites: int | None = None, include_symmetry = True, symprec: float = 0.001) -> dict[str, Any]

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

function `get_neighbor_inf`

def get_neighbor_inf(structure: Any, *, site_index: int = 0, radius: float = 5.0, backend: str = 'auto') -> dict[str, Any]

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

`tkcrystal.printer`

ソース: tkcrystal/printer.py

function `print_inf`

def print_inf(data: dict[str, Any], *, mode: str = 'pprint') -> None

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

function `crystal_inf_to_text`

def crystal_inf_to_text(data: dict[str, Any]) -> str

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

function `print_crystal_inf`

def print_crystal_inf(data: dict[str, Any]) -> None

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

`tkcrystal.symmetry`

ソース: tkcrystal/symmetry.py

function `get_spg_inf`

def get_spg_inf(structure: Any, *, backend: str = 'auto', symprec: float = 0.001, angle_tolerance: float = 5.0) -> dict[str, Any]

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

function `classify_symop`

def classify_symop(op: Any, tol: float = 1e-05) -> str

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

function `format_symop_xyz`

def format_symop_xyz(op: Any) -> str

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

function `get_symmetry_operations_inf`

def get_symmetry_operations_inf(structure: Any, *, backend: str = 'auto', symprec: float = 0.001, angle_tolerance: float = 5.0, max_ops: int | None = None) -> dict[str, Any]

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

function `symmetrize_structure`

def symmetrize_structure(structure: Any, *, backend: str = 'auto', symprec: float = 0.001, angle_tolerance: float = 5.0, mode: str = 'symmetrized') -> Any

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

function `expand_coordinates_spg`

def expand_coordinates_spg(ispg: int, xyz: str | list[float] | tuple[float, float, float], *, backend: str = 'pymatgen', rmin: float = 1e-05, max_ops: int | None = None) -> dict[str, Any]

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

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

tkcrystal マニュアル

1. 役割

2. 推奨import

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

4. 機能分類

5. backend

6. 構造概要

7. 対称性

8. XRD

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

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

tkcrystal APIリファレンス

APIの読み方

パッケージ公開API

モジュール一覧

tkcrystal

tkcrystal.atom

function get_atom_inf

function get_composition_inf_from_formula

tkcrystal.backends

class BackendError — bases: RuntimeError

class BackendNotAvailableError — bases: BackendError

function normalize_backend

function require_pymatgen

function is_pymatgen_structure

function dispatch_structure_backend

function safe_float

function to_builtin

tkcrystal.diffraction

function get_available_xray_wavelengths

function get_xrd_inf

tkcrystal.info

公開定数・モジュール変数

function get_lattice_inf

function get_site_inf

function get_composition_inf

function get_density_inf

function get_crystal_inf

function get_neighbor_inf

tkcrystal.printer

function print_inf

function crystal_inf_to_text

function print_crystal_inf

tkcrystal.symmetry

function get_spg_inf

function classify_symop

function format_symop_xyz

function get_symmetry_operations_inf

function symmetrize_structure

function expand_coordinates_spg

`tkcrystal`

`tkcrystal.atom`

function `get_atom_inf`

function `get_composition_inf_from_formula`

`tkcrystal.backends`

class `BackendError` — bases: `RuntimeError`

class `BackendNotAvailableError` — bases: `BackendError`

function `normalize_backend`

function `require_pymatgen`

function `is_pymatgen_structure`

function `dispatch_structure_backend`

function `safe_float`

function `to_builtin`

`tkcrystal.diffraction`

function `get_available_xray_wavelengths`

function `get_xrd_inf`

`tkcrystal.info`

function `get_lattice_inf`

function `get_site_inf`

function `get_composition_inf`

function `get_density_inf`

function `get_crystal_inf`

function `get_neighbor_inf`

`tkcrystal.printer`

function `print_inf`

function `crystal_inf_to_text`

function `print_crystal_inf`

`tkcrystal.symmetry`

function `get_spg_inf`

function `classify_symop`

function `format_symop_xyz`

function `get_symmetry_operations_inf`

function `symmetrize_structure`

function `expand_coordinates_spg`