API Reference

Molecule Class

A class that holds the topology and coordinate template of a molecule.

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

Generates a molecule from a SMILES string.

Argument	Type	Default	Description
smiles	`str`	(Required)	SMILES string. Connection points can be marked with `*`.
name	`str`	`"MOL"`	Name of the molecule.

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

Generates a Molecule from an RDKit Mol object. Coordinates and connectivity are preserved.

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

Imports a Molecule from an OpenFF Molecule, Topology, or Interchange object. Partial charges (e.g., AM1-BCC) and connectivity are preserved.

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

Generates a polymer chain Molecule from a monomer Molecule.

Argument	Type	Default	Description
monomer	`Molecule`	(Required)	The repeating unit as an `fbtk.Molecule`.
degree	`int`	(Required)	Degree of polymerization.
head	`int`	`None`	Heavy atom index for the head connection. Auto-resolved from `*` if omitted.
tail	`int`	`None`	Heavy atom index for the tail connection. Auto-resolved from `*` if omitted.
h_leaving	`int`	`None`	Index of the leaving atom at the head side.
t_leaving	`int`	`None`	Index of the leaving atom at the tail side.
tacticity	`str`	`None`	One of `"isotactic"`, `"syndiotactic"`, or `"atactic"`.
name	`str`	`None`	Name of the generated chain.

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

Generates a Molecule from a file. Supports .mol and .mol2 natively.

Argument	Type	Default	Description
path	`str`	(Required)	Path to the file.
name	`str`	`"MOL"`	Name of the molecule.
format	`str`	`None`	`"mol"` or `"mol2"`. Auto-detected from extension if omitted.

`get_positions() -> np.ndarray`

Returns atom coordinates as an (N, 3) NumPy array.

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

Returns a list of all bonds in the molecule as (atom_i, atom_j, bond_order).

`get_charges() -> List[float]`

Returns a list of partial charges for all atoms in the molecule.

`get_elements() -> List[str]`

Returns a list of chemical symbols for all atoms in the molecule.

`assign_partial_charges()`

Calculates and assigns Gasteiger partial charges.

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

Performs structural optimization on the single molecule template.

Argument	Type	Default	Description
steps	`int`	`1000`	Maximum optimization steps.
threshold	`float`	`1.0`	Convergence threshold ($F_{max}$, kcal/mol/Å).
verbose	`bool`	`True`	Show optimization logs.
num_threads	`int`	`0`	Threads for parallel computation (0 for auto).
cutoff	`float`	`6.0`	Cutoff radius for non-bonded interactions (Å).
history_size	`int`	`10`	History size for L-BFGS convergence.

`to_file(path: str)`

Saves the Molecule template to a file (default .mol2).

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

Converts to an RDKit Mol object.

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

Converts to an OpenFF object. Returns a Molecule if forcefield is None, or an Interchange if provided.

Builder Class

The central class for constructing unit cells and bulk systems.

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

Initializes the Builder. Progress is reported every 2000 atoms during construction.

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

Adds a specified count of an fbtk.Molecule template.

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

Adds small molecules directly from SMILES.

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

Generates and adds polymer chains.

`load_recipe(path: str)`

Loads a configuration from a YAML recipe file.

`build() -> System`

Executes the packing algorithm and returns a System object.

`relax(...)`

Performs structural relaxation on the constructed bulk system. Arguments are the same as Molecule.relax().

System Class

A class for operating on constructed or loaded bulk systems.

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

Loads a system from a file (currently .mol2 only).

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

Imports a System from an OpenFF object. Box vectors and partial charges are automatically synchronized and converted to FBTK units (Å).

`get_positions() -> np.ndarray`

Returns coordinates of all atoms as an (N, 3) NumPy array.

`get_charges() -> List[float]`

Returns a list of partial charges for all atoms in the system.

`get_elements() -> List[str]`

Returns a list of chemical symbols for all atoms in the system.

`assign_partial_charges()`

Calculates Gasteiger partial charges for the entire system.

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

Performs structural relaxation using the UFF-MD (FIRE) algorithm.

Argument	Type	Default	Description
steps	`int`	`1000`	Maximum optimization steps.
threshold	`float`	`1.0`	Convergence threshold. `1.0` is recommended for bulk systems.
verbose	`bool`	`True`	Log energy and $F_{max}$ progress.
num_threads	`int`	`0`	Threads for computation (0 for auto).
cutoff	`float`	`6.0`	Cutoff radius for non-bonded (Van der Waals) interactions (Å).
history_size	`int`	`10`	History size for convergence tracking.

`to_ase() -> ase.Atoms`

Converts to an ASE Atoms object.

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

Converts to an RDKit Mol object.

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

Converts to an OpenFF object. Box vectors are automatically converted to nm and synchronized.

`to_file(path: str)`

Saves the bulk system to a file (default .mol2).

Global Functions

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

Creates an FBTK System from an ASE Atoms object.

`compute_rdf(...) -> Tuple[np.ndarray, np.ndarray]`

Computes the Radial Distribution Function (RDF).

`compute_msd(...) -> Tuple[np.ndarray, np.ndarray]`

Computes the Mean Squared Displacement (MSD).

Smart Query Syntax

Selectors used in analysis functions.

Syntax	Description
`element {Sym}`	Select specific element (e.g., `element C`).
`resname {Name}`	Select specific residue name.
`index {Start} to {End}`	Select atom ID range (inclusive, 0-indexed).
`A and B`	Intersection of conditions.
`A with B` / `A - B`	Pair separation for RDF.
`not {Query}`	Negation of condition.

Technical Details

Internal SMILES Parser

FBTK features a high-speed native SMILES parser based on the purr crate, allowing 3D structure generation without RDKit.

Capabilities:
- Aliphatic/aromatic, branched, and cyclic structures.
- Formal charges (e.g., [NH4+], [O-]).
- Explicit hydrogen counts within brackets.
Limitations:
- Strict stereochemistry (Cis/Trans, R/S) resolution is currently in development.
Recommendation: For complex stereochemical requirements, use Molecule.from_rdkit(mol).

Parallel Backend

FBTK utilizes Rayon as a global thread pool.

Applied to: relax, compute_rdf, compute_msd, get_all_distances, get_neighbor_list.