Structure Relaxation

Structure Relaxation

FBTK includes a built-in structural relaxation engine based on the Universal Force Field (UFF), implemented in Rust.

Atomic “clashes” (overlaps) immediately after random placement are the primary cause of instability in MD simulations. Relaxation minimizes the potential energy to provide a stable starting configuration. It employs the FIRE (Fast Inertial Relaxation Engine) algorithm, ensuring rapid convergence even for steep gradients.

In FBTK, you can call the relax() method on both the entire unit cell (System) and individual molecules (Molecule).

---

Unit Cell Relaxation (System Relaxation)

This resolves overlaps within the entire unit cell generated by builder.build(). This is the most common use case.

# Build the unit cell
system = builder.build()

# Perform global relaxation (verbose=True by default)
system.relax(steps=1000)

Specifications and Notes

• Fixed Cell Dimensions: The simulation box size and shape remain constant during relaxation.
• Periodic Boundary Conditions (PBC): Optimization is always performed under active PBC.
• Automatic Unwrapping: After optimization, coordinates are automatically “unwrapped” to ensure that molecules are not fragmented across periodic boundaries.

---

Molecule Beautify (Standalone Relaxation)

You can refine the geometry of a single molecule template before adding it to a system. This is particularly effective for molecules imported from external files with non-ideal coordinates.

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

# Refine the structure standalone before adding to the builder
mol.relax(steps=500)

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

---

Common relax() Arguments

Both System.relax() and Molecule.relax() share the same set of arguments.

Argument	Type	Description
steps	int	Maximum number of steps (default: 1000).
threshold	float	Convergence threshold (approximate target for $F_{max}$ in kcal/mol/Å) (default: 1.0).
verbose	bool	If True, prints relaxation progress (default: True).
num_threads	int	Number of threads to use (0: Auto).
cutoff	float	Cutoff radius for non-bonded interactions [Å] (default: 6.0).
history_size	int	Number of previous steps used for convergence check (default: 10).

Output Example (verbose=True)

=============================== uff-relax v1.0.0 ===============================
Atoms:     900        | Bonds:     800
Cutoff:    6.0        | Threshold: 1.0000     kcal/mol/Å
Max Iter:  200        | Threads:   Auto
--------------------------------------------------------------------------------
       | Fmax           | FRMS           | Total E          |
Iter   | (kcal/mol/Å)   | (kcal/mol/Å)   | (kcal/mol)       | Status
--------------------------------------------------------------------------------
     0 |      1559.6175 |       283.7289 |      305566.6245 |
    10 |       556.1727 |        42.1182 |        7805.1322 |
    ...
   187 |         1.9478 |         0.2722 |        -234.8426 | FRMS-Conv
--------------------------------------------------------------------------------
=== Optimization Finished ===
Reason: FRMS-Conv
Total Time: 1.451s     (Avg: 7.720ms / step)
Final Energy: -234.8426       kcal/mol
Final Fmax:   1.9478          kcal/mol/Å
Final FRMS:   0.2722          kcal/mol/Å
                                                       (c) 2026 Forblaze Project
--------------------------------------------------------------------------------