API Reference

Molecule クラス

分子のトポロジと座標のテンプレートを保持するクラスです。

`from_smiles(smiles: str, name: str = None) -> Molecule`

SMILES 文字列から分子を生成します。

引数	型	デフォルト	説明
smiles	`str`	(必須)	SMILES 文字列。接続点として `*` を含むことができます。
name	`str`	`"MOL"`	分子名。

`from_rdkit(mol: rdkit.Chem.Mol, name: str = None) -> Molecule`

RDKit の Mol オブジェクトから Molecule を生成します。座標と結合情報が維持されます。

`from_openff(obj: Union[Molecule, Topology, Interchange]) -> Molecule`

OpenFF の Molecule, Topology, または Interchange オブジェクトから Molecule を生成（インポート）します。AM1-BCC 等で計算された電荷情報も維持されます。

`from_polymer(monomer: Molecule, degree: int, head: int = None, tail: int = None, h_leaving: int = None, t_leaving: int = None, tacticity: str = None, name: str = None) -> Molecule`

モノマー Molecule からポリマー鎖の Molecule を生成します。

引数	型	デフォルト	説明
monomer	`Molecule`	(必須)	繰り返し単位となる `fbtk.Molecule`。
degree	`int`	(必須)	重合度。
head	`int`	`None`	重合点（頭）の重原子インデックス（0始まり）。省略時は `*` から自動解決。
tail	`int`	`None`	重合点（尾）の重原子インデックス（0始まり）。省略時は `*` から自動解決。
h_leaving	`int`	`None`	頭側の脱離原子（水素など）のインデックス。
t_leaving	`int`	`None`	尾側の脱離原子（水素など）のインデックス。
tacticity	`str`	`None`	`"isotactic"`, `"syndiotactic"`, `"atactic"` のいずれか。
name	`str`	`None`	生成されるポリマー鎖の名前。

`from_file(path: str, name: str = None, format: str = None) -> Molecule`

ファイルから Molecule を生成します。現在、.mol および .mol2 形式をネイティブサポートしています。

`get_positions() -> np.ndarray`

原子座標を (N, 3) の NumPy 配列として取得します。

`get_bonds() -> List[Tuple[int, int, float]]`

分子内の全結合リストを取得します。返り値は (atom_i, atom_j, bond_order) のタプルリストです。

`get_charges() -> List[float]`

分子内の全原子の部分電荷をリストとして取得します。

`get_elements() -> List[str]`

分子内の全原子の元素記号をリストとして取得します。

`assign_partial_charges()`

Gasteiger 法を用いて部分電荷を計算・割り当てます。

`relax(steps: int = 1000, threshold: float = 1.0, verbose: bool = True, num_threads: int = 0, cutoff: float = 6.0, history_size: int = 10)`

分子単体に対して構造最適化を実行します。外部ファイルから読み込んだ不自然な座標の整形に特に有効です。

引数	型	デフォルト	説明
steps	`int`	`1000`	最大ステップ数。
threshold	`float`	`1.0`	収束判定しきい値 ($F_{max}$ の目安, kcal/mol/Å)。
verbose	`bool`	`True`	`True` で緩和ログを表示。
num_threads	`int`	`0`	並列計算に使用するスレッド数 (0: 自動設定)。
cutoff	`float`	`6.0`	非結合相互作用のカットオフ半径 (Å)。
history_size	`int`	`10`	収束判定に使用する履歴のステップ数（L-BFGS 用）。

`to_file(path: str)`

Molecule のテンプレートをファイルに保存します（.mol2）。

`to_rdkit() -> rdkit.Chem.Mol`

RDKit の Mol オブジェクトに変換します。

`to_openff(forcefield: str = None) -> Union[openff.toolkit.Molecule, openff.interchange.Interchange]`

OpenFF のオブジェクトに変換します。

Builder クラス

ユニットセルを構築するための中心的なクラスです。

`Builder(box_size: List[float] = None, density: float = None)`

Builder を初期化します。構築中、2000原子ごとに進捗が標準出力に表示されます。

`add_molecule(molecule: Molecule, count: int)`

fbtk.Molecule オブジェクトを追加します。

`add_molecule_smiles(name: str, count: int, smiles: str)`

SMILES から直接低分子を追加します。

`add_polymer(name: str, count: int, degree: int, smiles: str, ...)`

高分子鎖を生成して追加します。

`load_recipe(path: str)`

YAML レシピファイルを読み込みます。

`build() -> System`

配置アルゴリズムを実行し、System オブジェクトを返します。

`relax(...)`

構築された系に対して構造緩和を実行します。引数は Molecule.relax() と共通です。

System クラス

構築された系、あるいは読み込まれた系を操作するクラスです。

`from_file(path: str, format: str = None) -> System`

ファイルから系全体を読み込みます（.mol2 形式のみ）。

`from_openff(obj: Union[Molecule, Topology, Interchange]) -> System`

OpenFF のオブジェクトから System を生成します。セル（Box）情報や電荷情報が自動的に引き継がれます。

`get_positions() -> np.ndarray`

系に含まれる全原子の座標を (N, 3) の NumPy 配列として取得します。

`get_charges() -> List[float]`

システム内の全原子の部分電荷をリストとして取得します。

`get_elements() -> List[str]`

システム内の全原子の元素記号をリストとして取得します。

`assign_partial_charges()`

システム全体の全原子に対して Gasteiger 部分電荷を一括計算し、割り当てます。

`relax(steps: int = 1000, threshold: float = 1.0, verbose: bool = True, num_threads: int = 0, cutoff: float = 6.0, history_size: int = 10)`

UFF-MD (FIRE) アルゴリズムによる構造緩和を実行します。

引数	型	デフォルト	説明
steps	`int`	`1000`	最大ステップ数。
threshold	`float`	`1.0`	収束判定しきい値。バルク系では `1.0` 程度が推奨されます。
verbose	`bool`	`True`	`True` でエネルギーや $F_{max}$ の推移をログ出力。
num_threads	`int`	`0`	計算に使用するスレッド数 (0: 自動)。
cutoff	`float`	`6.0`	非結合相互作用（Van der Waals）のカットオフ半径 (Å)。
history_size	`int`	`10`	収束判定に使用する履歴のステップ数。

`to_ase() -> ase.Atoms`

ASE Atoms オブジェクトに変換します。

`to_rdkit() -> rdkit.Chem.Mol`

RDKit Mol オブジェクトに変換します。

`to_openff(forcefield: str = None) -> Union[openff.toolkit.Topology, openff.interchange.Interchange]`

OpenFF のオブジェクトに変換します。セル情報（Box Vectors）は自動的に Å から nm へ変換され同期されます。

`to_file(path: str)`

系を MOL2 形式でファイルに保存します。

解析関数 (Global Functions)

`from_ase(atoms: ase.Atoms) -> System`

ASE の Atoms オブジェクトから FBTK の System オブジェクトを生成します。

`compute_rdf(input: Union[System, Atoms, List[Atoms]], query: str, r_max: float = 10.0, n_bins: int = 200) -> Tuple[np.ndarray, np.ndarray]`

動径分布関数 (RDF) を計算します。

`compute_msd(input: Union[System, List[Atoms]], query: str, dt: float = 1.0) -> Tuple[np.ndarray, np.ndarray]`

平均二乗変位 (MSD) を計算します。

スマートクエリ記法

解析関数で共通して使用できるセレクタです。

記法	説明
`element {Sym}`	特定の元素を選択（例: `element C`）。
`resname {Name}`	特定の残基名を選択。
`index {Start} to {End}`	原子 ID の範囲を選択（0始まり。End を含む）。
`A and B`	条件の積。
`A with B` / `A - B`	動径分布関数のペア分離。
`not {Query}`	条件の否定。

技術情報

内蔵 SMILES パーサーの仕様

FBTK は purr クレートをベースとした高速なネイティブ SMILES パーサーを搭載しており、RDKit への依存なしに 3D 構造を生成できます。

サポート範囲:
- 一般的な脂肪族・芳香族、分岐、環構造（単環・多環）。
- 形式電荷 ([NH4+], [O-] など) の正確な処理。
- SMILES ブラケット内の明示的な水素数 ([NH4+] の H4 など) の認識。
制限事項:
- ステレオ化学（Cis/Trans, R/S）の厳密な判定は現在開発中です。
使い分け: 複雑な立体配置の制御が必要な場合は、RDKit で生成したオブジェクトを Molecule.from_rdkit(mol) で読み込むことを推奨します。

並列化バックエンド

FBTK は Rust 側のグローバルなスレッドプールとして Rayon を使用します。

適用範囲: relax, compute_rdf, compute_msd, get_all_distances, get_neighbor_list など。