# tkcrystal マニュアル

## 1. 役割

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

## 2. 推奨import

```python
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から構造情報を得る例

```python
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です。

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

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

## 6. 構造概要

```python
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. 対称性

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

座標展開:

```python
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

```python
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` を再現可能性のため明示・保存する。