API Reference

API Reference

ノート

FBTK では、全ての原子 ID や SMILES 内の重原子番号などのインデックスは、Python の流儀に従い 0 からカウントが始まります (0-indexed)。

Molecule クラス

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

from_smiles(smiles, name=None)

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

• smiles: SMILES 文字列。接続点として * を含むことができます。
• name: 分子名。省略時は “MOL”。

from_rdkit(mol, name=None)

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

from_file(path, name=None, format=None)

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

get_positions()

原子座標を (N, 3) の NumPy 配列として取得します。ASE の get_positions() API と同様の使い勝手です。

relax(steps=1000, threshold=1.0, verbose=True, num_threads=0, cutoff=6.0, history_size=10)

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

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

to_file(path)

Molecule のテンプレートをファイルに保存します。現在は .mol2 形式のみサポートしています。

---

Builder クラス

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

Builder(box_size=None, density=None)

• box_size: [Lx, Ly, Lz] のリスト (Å)。
• density: 目標密度 (g/cm³)。指定した場合、全分子量から箱のサイズが逆算されます。

add_molecule(molecule, count)

fbtk.Molecule オブジェクトを指定した数だけ追加します。

add_molecule_smiles(name, count, smiles)

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

add_polymer(name, count, degree, smiles, head=None, tail=None, ...)

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

• degree: 重合度。
• count: 鎖の数。
• smiles: モノマーの SMILES。
• head: [オプション] 重合点（頭）の重原子インデックス（0始まり）。
• tail: [オプション] 重合点（尾）の重原子インデックス（0始まり）。

load_recipe(path)

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

build()

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

relax(steps=1000, threshold=1.0, verbose=True, num_threads=0, cutoff=6.0, history_size=10)

構築された系に対して構造緩和を実行します。

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

---

System クラス

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

from_file(path, format=None)

ファイルから系全体（座標、結合、ユニットセル情報）を読み込みます。現在は .mol2 形式のみサポートしています。

get_positions()

系に含まれる全原子の座標を (N, 3) の NumPy 配列として取得します。ASE の Atoms.get_positions() と互換性があります。

relax(steps=1000, threshold=1.0, verbose=True, num_threads=0, cutoff=6.0, history_size=10)

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

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

to_ase() / to_rdkit()

それぞれ ASE Atoms オブジェクト、RDKit Mol オブジェクトに変換します。

to_file(path)

構築された系をファイルに保存します。現在は .mol2 形式をサポートしており、ユニットセル情報（CRYSIN）も書き出されます。

get_all_distances(mic=True)

全原子間の距離行列を取得します。mic=True で周期境界 (PBC) を考慮した最短距離を計算します。 注: 極端に小さなユニットセル（一辺が距離の2倍以下）では、ASE の厳密な計算結果と異なる場合があります。

get_neighbor_list(cutoff)

指定したカットオフ以内の近傍リストを返します。

• 返り値: (atom_i, atom_j, distance) のリスト。atom_i, atom_j は 0 始まりの原子 ID です。

get_volume()

ユニットセルの体積 (ų) を返します。

get_total_mass()

系に含まれる全原子の総質量 (amu) を返します。

get_density()

系の現在の密度 (g/cm³) を返します。

---

解析関数 (Global Functions)

from_ase(atoms)

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

compute_rdf(input, query, r_max=10.0, n_bins=200)

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

• input: System, Atoms, または List[Atoms]。
• query: スマートクエリ文字列。

compute_msd(input, query, dt=1.0)

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

• input: System, Atoms, または List[Atoms]。
• query: 対象を選択するスマートクエリ。
• dt: フレーム間の時間間隔（デフォルト: 1.0）。結果の time 軸のスケールに使用されます。

---

スマートクエリ記法

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

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

---

技術ノート: 並列化バックエンド

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

• 初期化: 最初に FBTK モジュールが Python にインポートされた際にスレッドプールが作成されます。
• デフォルト値: 4 (環境変数 RAYON_NUM_THREADS が未設定の場合)。
• 適用範囲: relax, compute_rdf, compute_msd, get_all_distances, get_neighbor_list など。