Python API Reference

API Reference

Note

In FBTK, all indices—including atom IDs, heavy atom indices in SMILES, and residues—are 0-indexed following standard Python/Rust conventions.

Molecule Class

A class that holds templates for molecular topology and coordinates.

from_smiles(smiles, name=None)

Generates a molecule from a SMILES string.

• smiles: SMILES string. Can include * as connection points.
• name: Name of the molecule. Defaults to “MOL”.

from_rdkit(mol, name=None)

Creates a Molecule from an RDKit Mol object, preserving coordinates and bonding.

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

Creates a Molecule from a file. Currently supports .mol (V2000) and .mol2 (with connectivity).

get_positions()

Returns the atomic coordinates as a (N, 3) NumPy array. This is consistent with the ASE get_positions() API.

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

Performs standalone structural optimization on the molecule. This is particularly effective for refining non-ideal coordinates imported from external files.

• steps: Maximum number of steps.
• threshold: Convergence threshold (approximate target for $F_{max}$, in kcal/mol/Å).
• verbose: If True, prints relaxation progress (default: True).
• num_threads: Number of threads to use (0: Auto).
• cutoff: Cutoff radius for non-bonded interactions (Å).
• history_size: Number of previous steps used for convergence check.

to_file(path)

Saves the Molecule template to a file (currently .mol2 only).

---

Builder Class

The central class for constructing unit cells.

Builder(box_size=None, density=None)

• box_size: List of [Lx, Ly, Lz] in Å.
• density: Target density in g/cm³. If specified, the box size is calculated based on total molecular weight.

add_molecule(molecule, count)

Adds the specified number of fbtk.Molecule objects.

add_molecule_smiles(name, count, smiles)

Adds small molecules directly from a SMILES string.

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

Generates and adds polymer chains.

• degree: Degree of polymerization (DP).
• count: Number of chains.
• smiles: Monomer SMILES string.
• head: [Optional] Heavy atom index (0-indexed) for the polymerization start site.
• tail: [Optional] Heavy atom index (0-indexed) for the polymerization end site.

load_recipe(path)

Loads a configuration from a YAML recipe file.

build()

Executes the placement algorithm and returns a System object.

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

Performs structural relaxation on the constructed system.

• steps: Maximum number of steps.
• threshold: Convergence threshold (approximate target for $F_{max}$, in kcal/mol/Å).
• verbose: If True, prints relaxation progress (default: True).
• num_threads: Number of threads to use (0: Auto).
• cutoff: Cutoff radius for non-bonded interactions (Å).
• history_size: Number of previous steps used for convergence check.

---

System Class

Represents and manipulates the constructed or loaded molecular system.

from_file(path, format=None)

Loads an entire system (coords, bonds, cell info) from a file (currently .mol2 only).

get_positions()

Returns all atomic coordinates in the system as a (N, 3) NumPy array. Consistent with ASE Atoms.get_positions().

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

Performs structural relaxation using the UFF-FIRE algorithm.

• steps: Maximum number of steps.
• threshold: Convergence threshold (approximate target for $F_{max}$, in kcal/mol/Å).
• verbose: If True, prints relaxation progress (default: True).
• num_threads: Number of threads to use (0: Auto).
• cutoff: Cutoff radius for non-bonded interactions (Å).
• history_size: Number of previous steps used for convergence check.

to_ase() / to_rdkit()

Converts the system to an ASE Atoms object or an RDKit Mol object.

to_file(path)

Saves the system to a file. Supports .mol2, including unit cell information (CRYSIN section).

get_all_distances(mic=True)

Computes the all-atom distance matrix. mic=True applies the Minimum Image Convention (PBC). Note: For extremely small unit cells, results may differ slightly from ASE’s exhaustive search.

get_neighbor_list(cutoff)

Returns a neighbor list within the specified cutoff.

• Returns: A list of (atom_i, atom_j, distance). Atom IDs are 0-indexed.

get_volume()

Returns the volume of the unit cell in ų.

get_total_mass()

Returns the total mass of all atoms in the system in amu.

get_density()

Returns the current density of the system in g/cm³.

---

Analysis Functions (Global)

from_ase(atoms)

Converts an ASE Atoms object to an FBTK System.

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

Computes the Radial Distribution Function (RDF).

• input: System, Atoms, or a List[Atoms] (trajectory).
• query: Selection string (e.g., “element C with element O”).

compute_msd(input, query, dt=1.0, max_lag=None)

Computes the Mean Squared Displacement (MSD) for a trajectory.

• input: A list of frames or a trajectory object.
• dt: Time step in fs.
• max_lag: Maximum lag time to compute.