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

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

---

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


---

# tkcrystal APIリファレンス

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

## APIの読み方

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

## パッケージ公開API

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

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

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

### function `get_composition_inf_from_formula`

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

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

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

### function `require_pymatgen`

```python
def require_pymatgen() -> None
```

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

### function `is_pymatgen_structure`

```python
def is_pymatgen_structure(obj: Any) -> bool
```

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

### function `dispatch_structure_backend`

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

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

### function `safe_float`

```python
def safe_float(x: Any, default = None)
```

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

### function `to_builtin`

```python
def to_builtin(obj: Any) -> Any
```

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

## `tkcrystal.diffraction`

ソース: `tkcrystal/diffraction.py`

### function `get_available_xray_wavelengths`

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

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

### function `get_xrd_inf`

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

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

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

### function `get_site_inf`

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

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

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

### function `get_density_inf`

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

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

### function `get_crystal_inf`

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

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

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

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

### function `crystal_inf_to_text`

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

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

### function `print_crystal_inf`

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

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

## `tkcrystal.symmetry`

ソース: `tkcrystal/symmetry.py`

### function `get_spg_inf`

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

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

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

### function `format_symop_xyz`

```python
def format_symop_xyz(op: Any) -> str
```

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

### function `get_symmetry_operations_inf`

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

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

```python
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はありません。シグネチャと実装を参照してください。_