System Building

System Building

FBTK automates the creation of initial structures (unit cells), which is often the first bottleneck in molecular simulation.

Built-in 3D Structure Generation (SMILES to 3D)

FBTK features a native Rust engine to generate 3D coordinates directly from SMILES strings. It produces chemically reasonable initial structures in two steps without requiring RDKit:

1. VSEPR Theory: Determines initial bond angles and stereochemistry based on Valence Shell Electron Pair Repulsion theory.
2. UFF Optimization: Rapidly relaxes bond lengths and strain using the Universal Force Field (UFF).

This allows you to create 3D templates ready for MD simulation from just a single line of text.

---

Basic Usage

The standard workflow for building a unit cell with a target density using SMILES strings.

import fbtk

# 1. Initialize the builder
builder = fbtk.Builder(density=0.8)

# 2. Create a molecule template from SMILES and add it with a count
# (3D generation via VSEPR + UFF is executed automatically)
water = fbtk.Molecule.from_smiles("O", name="WAT")
builder.add_molecule(water, count=500)

# 3. Build the system
system = builder.build()

# 4. Global relaxation to resolve overlaps (verbose=True by default)
system.relax()

# 5. Save the result
system.to_file("system.mol2")

---

Molecule Beautify (Relaxation)

When importing molecules from files (.mol or .mol2), the coordinates may not be ideal. You can refine the geometry of a single molecule before adding it to the system.

# Load from a file (which may have unoptimized coordinates)
mol = fbtk.Molecule.from_file("raw_structure.mol")

# Refine the structure standalone to ensure chemical correctness
mol.relax()

# Add the refined molecule to the builder
builder.add_molecule(mol, count=100)

---

Mixing Multiple Components

You can easily build systems containing multiple types of molecules, such as solvents and solutes.

import fbtk

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

# Add multiple types of small molecules
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()

---

Polymer Generation

FBTK provides high-speed generation of polymer chains from monomer SMILES strings.

1. RadonPy-style SMILES (Recommended)

Include * (asterisk) in the SMILES string to automatically specify connection sites.

# '*' are connection sites. Adjacent hydrogens are automatically removed.
builder.add_polymer(
    name="PS",
    smiles="*C(C*)c1ccccc1",
    count=10,
    degree=20
)

2. Explicit Specification via Indices

Specify the indices of the heavy atoms involved in polymerization (0-indexed).

# Use the 0th Carbon (Head) and 1st Carbon (Tail) as connection sites
builder.add_polymer(
    name="PS",
    smiles="CCc1ccccc1",
    count=10,
    degree=20,
    head=0,
    tail=1
)

---

Placement Mechanism (Grid-based Placement)

The FBTK Builder defines a 3D grid based on the box size while accounting for the gyration radius of the molecules. Using spatial hashing on the Rust side, it completes packing for large systems in O(N) complexity. Each molecule is assigned a random 3D rotation during placement to ensure an isotropic bulk structure.