ユニットセル作成

Unit Cell Creation

FBTKは、分子シミュレーションの最初の難関である「初期構造（ユニットセル）の作成」を自動化します。

独自の立体構造生成エンジン (SMILES to 3D)

FBTK は、SMILES 文字列から 3D 構造を生成するための Rust ネイティブエンジンを搭載しています。RDKit 等の外部ライブラリに依存せず、以下のステップで妥当な座標を自動生成します。

1. VSEPR 理論: 原子価殻電子対反発則に基づき、結合角や立体配置の初期値を決定します。
2. UFF 最適化: ユニバーサル力場 (UFF) を用いて、結合距離や歪みを高速に緩和します。

これにより、テキスト 1 行から MD 計算に即座に使用可能な 3D テンプレートが作成されます。

---

基本的な使い方 (Basic Usage)

SMILES 文字列を指定して、特定の密度のユニットセルを構築する標準的なフローです。

import fbtk

# 1. ビルダーの初期化
builder = fbtk.Builder(density=0.8)

# 2. SMILES から分子テンプレートを作成し、個数を指定して追加
# (内部で VSEPR + UFF による 3D 構造生成が自動実行されます)
water = fbtk.Molecule.from_smiles("O", name="WAT")
builder.add_molecule(water, count=500)

# 3. システムの構築
system = builder.build()

# 4. 構築後の全体緩和 (重なりの解消)
system.relax()

# 5. 保存
system.to_file("system.mol2")

---

分子の整形 (Beautify / Relaxation)

ファイルから読み込んだ分子（.mol や .mol2）の座標が不自然な場合、システムに追加する前に単体で構造最適化を行うことができます。

# 外部ファイルから読み込み（座標が未最適化の可能性がある）
mol = fbtk.Molecule.from_file("raw_structure.mol")

# 分子単体で構造緩和を実行し、幾何構造を整える
mol.relax()

# 整形した分子をビルダーに追加
builder.add_molecule(mol, count=100)

---

複数成分の混合系 (Mixing Small Molecules)

溶媒と溶質、あるいは異なる種類の分子を混ぜた系を簡単に構築できます。

import fbtk

builder = fbtk.Builder(box_size=[40, 40, 40])

# 複数種類の低分子を異なる個数で追加
water = fbtk.Molecule.from_smiles("O", name="WAT")
ethanol = fbtk.Molecule.from_smiles("CCO", name="EtOH")

builder.add_molecule(water, count=800)
builder.add_molecule(ethanol, count=200)

system = builder.build()

---

ポリマー作成 (Polymerization)

FBTK は、モノマーの SMILES からポリマー鎖を高速に生成する機能を備えています。

1. RadonPy 形式の SMILES (推奨)

SMILES 内に *（アスタリスク）を含めることで、重合時の接続点を自動的に指定できます。

# * が接続点。隣接水素は自動で除去されます
builder.add_polymer(
    name="PS",
    smiles="*C(C*)c1ccccc1",
    count=10,
    degree=20
)

2. インデックスによる明示的指定

* を含まない通常の SMILES を使用する場合、重合に関与する原子のインデックス（0始まり）を指定します。

# 0番目のC (Head) と 1番目のC (Tail) を接続点にする
builder.add_polymer(
    name="PS",
    smiles="CCc1ccccc1",
    count=10,
    degree=20,
    head=0,
    tail=1
)

3. タクティシティの制御 (Tacticity Control)

ポリマー鎖の立体規則性（タクティシティ）を、tacticity パラメータで制御できます。FBTK は重心解析に基づき側鎖の方向を自動的に判別し、ユニットのミラー反転を適用します。

指定可能な値:

• "isotactic" (デフォルト): 全てのユニットが同じ向き。
• "syndiotactic": 隣接するユニットが交互に反転。
• "atactic": ランダムに反転。

# 間規（Syndiotactic）のポリスチレンを生成
builder.add_polymer(
    name="PS-syn",
    smiles="*C(C*)c1ccccc1",
    count=10,
    degree=50,
    tacticity="syndiotactic"
)

4. ポリマー鎖の単体生成

単一のポリマー鎖を Molecule オブジェクトとして作成したい場合（例：単体で .mol 保存したい場合）は、Molecule.from_polymer() を使用します。

monomer = fbtk.Molecule.from_smiles("*C(C*)c1ccccc1", name="PS")

# 20量体の無規（Atactic）鎖を作成
chain = fbtk.Molecule.from_polymer(monomer, degree=20, tacticity="atactic")

# ユニットセル情報なしでファイル保存
chain.to_file("ps_chain.mol")

---

配置アルゴリズム (Collision-aware Placement)

FBTK の Builder は、初期配置時の原子の重なりを最小限に抑えるため、堅牢なグリッドベースの配置アルゴリズムを採用しています。これは、ベンゼン環などの剛直な構造が互いに貫通して「知恵の輪」状態になるのを防ぎ、構造緩和（Relaxation）を安定して開始するために極めて重要です。

アルゴリズムの詳細：

1. グリッド生成: セルサイズと分子数に基づき、最適な 3D グリッド（格子点）を算出します。
2. 空間探索: 各分子について、候補となる格子点を選択します。他の分子との衝突が検知された場合、最大 15 箇所の異なる格子点 を探索します。
3. 回転探索: 各格子点において、ランダムな向きを試行します。衝突が検知された場合、最大 8 通りの異なる回転 を試行します。
4. 衝突判定: 重原子（水素以外）同士の距離をチェックします。周期境界条件（PBC）を考慮した上で、2.5 Å を衝突のしきい値として使用します。
5. フォールバック: 合計 120 通り（15 地点 × 8 回転）の試行で衝突が解消できない場合、その時点で最も空いている格子点に強制配置し、警告を表示します。

配置時の警告（Warning）への対処

Warning: Possible overlap detected for molecule X (Name) というメッセージが表示された場合、系が非常に高密度であるため、その分子を完全に衝突なしで配置できなかったことを意味します。

その後の system.relax()（UFF最適化）はこのような重なりを解消するのに非常に強力ですが、極端に高密度な系では計算が不安定になる可能性があります。緩和が収束しない場合や、最終的なエネルギーが異常に高い場合は、以下の対策を検討してください：

• 設定密度を下げる
• セルサイズを大きくする
• 緩和ステップ数を増やす (system.relax(steps=2000))