API Reference

This section contains the complete API reference for all modules in mlfsm.

Core Modules

FreezingString (mlfsm.cos)

The main driver class that orchestrates string growth, interpolation, and node optimization throughout the FSM calculation.

Freezing String Method driver for reaction pathway construction.

class mlfsm.cos.FreezingString(reactant, product, nnodes_min=10, interp_method='ric', ninterp=100, stepsize=0.0, raise_on_backtransf_fail=True, output=None)[source]

Bases: object

Implements the Freezing String Method (FSM) for transition state guess generation.

The FSM grows two strings from the reactant and product endpoints toward each other. At each iteration a new frontier node is placed by taking a step along an interpolated path, optimized perpendicular to the local tangent direction, and then frozen. The highest-energy node at convergence serves as the TS guess.

Parameters:

  • reactant (ase.Atoms) – Reactant geometry with an attached ASE calculator (optional at construction; required before calling optimize()).

  • product (ase.Atoms) – Product geometry. Must have the same atom ordering as reactant.

  • nnodes_min (int, optional) – Nominal number of string nodes used to determine the interpolation step size. The actual node count may differ slightly depending on the path arc length. Default is 10.

  • interp_method ({"ric", "lst", "cart"}) –

    Interpolation scheme used to generate new frontier nodes:

    • "ric" — redundant internal coordinates (recommended).

    • "lst" — linear synchronous transit.

    • "cart" — plain Cartesian linear interpolation.

  • ninterp (int, optional) – Number of points used to discretize the dense interpolated path from which frontier nodes are selected. Default is 100.

  • stepsize (float, optional) – If > 0, sets the Cartesian step size (Å) explicitly and ignores nnodes_min. The step size is measured along the Cartesian arc length of the initial linear interpolation. Default is 0.0 (derive step size from nnodes_min).

  • raise_on_backtransf_fail (bool, optional) – If True, raise a RuntimeError if the RIC back transformation fails to converge during interpolation or node growth. Default is True.

  • output (FSMOutput | None)

r_string, p_string

Growing strings from the reactant and product ends.

Type:

list[ase.Atoms]

r_energy, p_energy

Energies at each node (None until evaluated).

Type:

list[float or None]

growing

True while the two string ends have not yet converged.

Type:

bool

ngrad

Total number of gradient evaluations performed so far.

Type:

int

__init__(reactant, product, nnodes_min=10, interp_method='ric', ninterp=100, stepsize=0.0, raise_on_backtransf_fail=True, output=None)[source]
Parameters:

  • reactant (Atoms)

  • product (Atoms)

  • nnodes_min (int)

  • interp_method (str)

  • ninterp (int)

  • stepsize (float)

  • raise_on_backtransf_fail (bool)

  • output (FSMOutput | None)

Return type:

None

interpolate(outdir)[source]

Generate and write the dense interpolated path between current frontier nodes.

Writes a single XYZ file named interp_<iteration>.xyz to outdir. Each frame comment line contains the cumulative arc-length value.

Parameters:

outdir (path-like) – Directory in which to write the interpolated path XYZ file.

Return type:

None

grow()[source]

Grow the string by adding one new frontier node to each end.

Interpolates between the current frontier nodes, selects positions one step-size inward from each end, and appends those nodes to r_string and p_string with fix=False. Sets self.growing = False when the two frontiers are within one step-size of each other.

Return type:

None

optimize(optimizer)[source]

Relax all unfixed frontier nodes perpendicular to the local tangent.

Evaluates energies for endpoint nodes that have not yet been computed, then runs the optimizer on every unfixed node. After optimization each node is frozen (fix=True) so it will not move in subsequent iterations.

Parameters:

optimizer (CartesianOptimizer or InternalsOptimizer) – Optimizer instance whose calc attribute provides energies and gradients via the ASE calculator interface.

Return type:

None

write(outdir)[source]

Write the current string geometries and relative energies to an XYZ file.

Writes vfile_<iteration>.xyz to outdir. Frame comment lines contain the cumulative arc-length and relative energy (eV). On the final iteration (growing=False) also writes the total gradient count to ngrad.txt.

Parameters:

outdir (path-like) – Directory in which to write output files.

Return type:

None

Interpolation (mlfsm.interp)

Provides Linear, LST, and RIC interpolation schemes for generating reaction path nodes between endpoint geometries.

Interpolation methods for constructing paths between endpoint geometries.

class mlfsm.interp.Interpolate(atoms1, atoms2, ninterp, gtol=0.0001, return_q=False, raise_on_backtransf_fail=True)[source]

Bases: object

Abstract base class for interpolation schemes between molecular geometries.

Parameters:

  • atoms1 (ase.Atoms) – Starting (reactant-side) geometry.

  • atoms2 (ase.Atoms) – Ending (product-side) geometry.

  • ninterp (int) – Number of discrete frames to generate along the interpolated path.

  • gtol (float, optional) – Gradient tolerance passed to the L-BFGS-B minimizer (used by LST). Default is 1e-4.

  • return_q (bool, optional) – If True, return interpolated internal coordinate vectors instead of Cartesian positions. Only meaningful for RIC. Default is False.

  • raise_on_backtransf_fail (bool, optional) – If True, raise a RuntimeError if the RIC back transformation fails to converge during interpolation or node growth. Only meaningful for RIC. Default is True.

atoms1: Atoms
atoms2: Atoms
ninterp: int
gtol: float = 0.0001
return_q: bool = False
raise_on_backtransf_fail: bool = True
interpolate()[source]

Abstract interpolation routine — must be overridden by subclasses.

Return type:

ndarray[tuple[Any, …], dtype[float32]]

__init__(atoms1, atoms2, ninterp, gtol=0.0001, return_q=False, raise_on_backtransf_fail=True)
Parameters:
Return type:

None

class mlfsm.interp.Linear(atoms1, atoms2, ninterp, gtol=0.0001, return_q=False, raise_on_backtransf_fail=True)[source]

Bases: Interpolate

Linear interpolation of Cartesian coordinates.

Generates a reaction path by linearly blending the Cartesian positions of two endpoint geometries: (1-f)*xyz1 + f*xyz2 for f in [0, 1]. Fast but may produce unphysical geometries for large conformational changes.

Parameters:
interpolate()[source]

Return linearly interpolated Cartesian path.

Returns:

Array of shape (ninterp, natoms*3) with flattened Cartesian coordinates for each interpolated frame.

Return type:

NDArray[np.float32]

class mlfsm.interp.LST(atoms1, atoms2, ninterp, gtol=0.0001, return_q=False, raise_on_backtransf_fail=True)[source]

Bases: Interpolate

Linear Synchronous Transit (LST) interpolation.

At each interpolation point f, minimizes the deviation from linearly interpolated pairwise interatomic distances while remaining close to the Cartesian linear blend. Produces more chemically realistic geometries than plain Cartesian interpolation at moderate extra cost.

References

Halgren, T. A.; Lipscomb, W. N. Chem. Phys. Lett. 1977, 49, 225-232.

Parameters:
obj(x_c, f, rab, xab)[source]

Objective function minimized at each interpolation point.

Computes the weighted sum of squared deviations of pairwise distances from their linearly interpolated target values, plus a small Cartesian restraint to prevent rigid-body drift.

Parameters:

  • x_c (NDArray) – Flattened trial Cartesian coordinates.

  • f (float) – Interpolation parameter in [0, 1].

  • rab (callable) – Returns linearly interpolated pairwise distances at parameter f.

  • xab (callable) – Returns linearly interpolated Cartesian coordinates at parameter f.

Returns:

Scalar objective value.

Return type:

float

interpolate()[source]

Return LST-interpolated path.

Returns:

Array of shape (ninterp, natoms*3) with flattened Cartesian coordinates for each frame.

Return type:

NDArray[np.float32]

class mlfsm.interp.RIC(atoms1, atoms2, ninterp, gtol=0.0001, return_q=False, raise_on_backtransf_fail=True)[source]

Bases: Interpolate

Redundant internal coordinate (RIC) interpolation.

Linearly interpolates between the reactant and product geometries in the space of delocalized redundant internal coordinates (bonds, angles, torsions, out-of-plane bends). The interpolated frames are then back-transformed to Cartesian coordinates via iterative application of the Wilson B-matrix. This scheme avoids the unphysical bond compressions that can occur with Cartesian interpolation for large conformational changes.

Parameters:
coords

The redundant internal coordinate system built from both endpoints.

Type:

Redundant

interpolate()[source]

Return RIC-interpolated path in Cartesian (or internal) coordinates.

Torsion periodicity wrapping is applied automatically when the interpolation crosses the ±π boundary.

Returns:

If return_q is False (default): array of shape (ninterp, natoms*3) with flattened Cartesian coordinates. If return_q is True: array of shape (ninterp, n_ics) with internal coordinate values.

Return type:

NDArray[np.float32]

__init__(atoms1, atoms2, ninterp, gtol=0.0001, return_q=False, raise_on_backtransf_fail=True)
Parameters:
Return type:

None

Coordinates (mlfsm.coords)

Cartesian and redundant internal coordinate systems used during interpolation and back-transformation to Cartesian coordinates.

Coordinate generation and transformation tools for FSM optimization.

class mlfsm.coords.Coordinates(atoms1, atoms2=None, verbose=False, raise_on_backtransf_fail=True)[source]

Bases: object

Base class for internal coordinate systems used in FSM.

Parameters:
__init__(atoms1, atoms2=None, verbose=False, raise_on_backtransf_fail=True)[source]
Parameters:
Return type:

None

construct()[source]

Construct the coordinate representation for a given atom set.

Return type:

Dict[str, Any]

qprint(atoms)[source]

Print coordinate values in human-readable format for a given ASE atoms object.

Parameters:

atoms (Atoms)

Return type:

None

q(xyz)[source]

Return internal coordinate values from Cartesian positions.

Parameters:

xyz (ndarray[tuple[Any, ...], dtype[float64]])

Return type:

ndarray[tuple[Any, …], dtype[float64]]

dqprint(atoms1, atoms2)[source]

Print differences in internal coordinates between two structures.

Parameters:
Return type:

None

b_matrix(xyz)[source]

Construct the B-matrix for internal coordinates.

Parameters:

xyz (ndarray[tuple[Any, ...], dtype[float64]])

Return type:

ndarray[tuple[Any, …], dtype[float64]]

u_matrix(Bprim)[source]

Compute projection matrix U from the B-matrix.

Parameters:

Bprim (ndarray[tuple[Any, ...], dtype[float64]])

Return type:

ndarray[tuple[Any, …], dtype[float64]]

x(xyz, qtarget)[source]

Back-transform internal coordinate displacements to Cartesian updates.

Parameters:
Return type:

ndarray[tuple[Any, …], dtype[float64]]

class mlfsm.coords.Cartesian(atoms1, atoms2=None, verbose=False, raise_on_backtransf_fail=True)[source]

Bases: Coordinates

Cartesian coordinate system used for atoms.

Parameters:
construct()[source]

Build Cartesian coordinate representation.

Return type:

Dict[str, Any]

class mlfsm.coords.Redundant(atoms1, atoms2=None, verbose=False, raise_on_backtransf_fail=True)[source]

Bases: Coordinates

Redundant internal coordinate system including bond, angle, torsion, etc.

Parameters:
checkstre(A, B, eps=1e-08)[source]

Check if distance between two atoms is significant (non-zero within tolerance).

Parameters:
Return type:

bool

checkangle(A, B, C)[source]

Check if angle defined by three atoms is physically valid.

Parameters:
Return type:

bool

checktors(A, B, C, D)[source]

Check if torsion angle defined by four atoms is physically valid.

Parameters:
Return type:

bool

get_fragments(A)[source]

Return list of fragments as connected components in adjacency matrix.

Parameters:

A (ndarray[tuple[Any, ...], dtype[int64]])

Return type:

list[ndarray[tuple[Any, …], dtype[int64]]]

connectivity(atoms)[source]

Compute connectivity matrices from atomic positions.

Parameters:

atoms (Atoms)

Return type:

tuple[list[ndarray[tuple[Any, …], dtype[int64]]], ndarray[tuple[Any, …], dtype[int64]], ndarray[tuple[Any, …], dtype[int64]], ndarray[tuple[Any, …], dtype[int64]], ndarray[tuple[Any, …], dtype[int64]]]

atoms_to_ric(atoms)[source]

Generate a redundant internal coordinate (RIC) set from ASE.Atoms object.

Parameters:

atoms (Atoms)

Return type:

Dict[str, Any]

construct()[source]

Construct the full set of internal coordinates based on input atoms.

Return type:

Dict[str, Any]

Optimization (mlfsm.opt)

Node-level optimizers that relax FSM images perpendicular to the current tangent direction using L-BFGS-B with explicit line search.

Optimization routines for FSM nodes.

Contains Cartesian and internal coordinate optimizers using projected gradients and scipy-based minimization. Optimizers are used to refine node geometries along a reaction path subject to constraints imposed by the FSM.

class mlfsm.opt.Optimizer(calc, method='L-BFGS-B', maxiter=3, maxls=2, dmax=0.3)[source]

Bases: object

Base optimizer class for use with FSM node optimization.

This abstract class provides an interface for optimizer implementations, requiring subclasses to define obj and optimize methods.

Parameters:
calc: Any
method: str = 'L-BFGS-B'
maxiter: int = 3
maxls: int = 2
dmax: float = 0.3
obj(*args, **kwargs)[source]

Objective function to be implemented by subclasses.

Parameters:

  • xyz (ndarray) – Cartesian coordinates (flattened).

  • tangent (ndarray) – Tangent vector used for projection.

  • args (Any)

  • kwargs (Any)

Raises:

NotImplementedError – Always, since this is an abstract method.:

Return type:

Any

optimizeobj(*args, **kwargs)[source]

Optimization method to be implemented by subclasses.

Parameters:

  • xyz (ndarray) – Cartesian coordinates (flattened).

  • tangent (ndarray) – Tangent vector used for projection.

  • args (Any)

  • kwargs (Any)

Raises:

NotImplementedError – Always, since this is an abstract method.:

Return type:

Any

__init__(calc, method='L-BFGS-B', maxiter=3, maxls=2, dmax=0.3)
Parameters:
Return type:

None

class mlfsm.opt.CartesianOptimizer(calc, method='L-BFGS-B', maxiter=3, maxls=2, dmax=0.3)[source]

Bases: Optimizer

Performs optimization in Cartesian coordinates using projected gradients.

Parameters:
obj(xyz, tangent, atoms)[source]

Objective function for cartesian coordinate optimization.

Computes energy and projected gradient given a position and tangent vector.

Parameters:

  • xyz (ndarray) – Cartesian coordinates.

  • tangent (ndarray) – Tangent vector in Cartesian space.

  • atoms (ase.Atoms) – ASE atoms object with calculator.

Returns:

tuple[float, ndarray]

Return type:

Energy and projected gradient.

optimize(atoms, tangent)[source]

Run optimization in Cartesian coordinates using user specified method.

Parameters:

  • atoms (ASE.Atoms) – ASE atoms object with calculator.

  • tangent (ndarray) – Tangent vector used for projection.

Returns:

  • tuple[ASE.Atoms,float,int,int] (ASE.Atoms with final positions, energy, total function)

  • evaluations (nfev), and number of optimizer iterations (nit).

Return type:

tuple[Atoms, float, int, int]

class mlfsm.opt.InternalsOptimizer(calc, method='L-BFGS-B', maxiter=3, maxls=6, dmax=0.05)[source]

Bases: Optimizer

Performs projected optimization in internal coordinates.

NOTE: This optimizer is currently under development and may not work as expected.

Parameters:
maxls: int = 6
dmax: float = 0.05
compute_bounds(q)[source]

Compute optimization bounds for each internal coordinate.

Bounds are computed based on the coordinate type (e.g., bend, torsion), ensuring constraints appropriate to their periodicity and domain.

Parameters:

q (ndarray) – Internal coordinate values.

Returns:

list[tuple[float, float]]

Return type:

List of bounds for each coordinate.

obj(q, xyzref, tangent, atoms)[source]

Objective function for internal coordinate optimization.

Computes the energy and projected gradient given internal coordinates and a tangent direction.

Parameters:

  • q (ndarray) – Internal coordinates.

  • xyzref (ndarray) – Reference Cartesian coordinates.

  • tangent (ndarray) – Tangent vector in Cartesian space.

  • atoms (ASE.Atoms) – ASE atoms object with calculator.

Returns:

tuple[float, ndarray]

Return type:

Energy and projected gradient.

optimize(atoms, tangent)[source]

Run optimization in internal coordinates using user specified method.

Parameters:

  • atoms (ASE.Atoms) – ASE atoms object with calculator.

  • tangent (ndarray) – Tangent vector used for projection.

Returns:

  • tuple[ASE.Atoms,float,int,int] (ASE.Atoms with final positions, energy, total function)

  • evaluations (nfev), and number of optimizer iterations (nit).

Return type:

tuple[Atoms, float, int, int]

__init__(calc, method='L-BFGS-B', maxiter=3, maxls=6, dmax=0.05)
Parameters:
Return type:

None

Geometry Utilities (mlfsm.geom)

Low-level vector operations and projection operators used throughout the FSM, including rigid-body alignment and translation/rotation projection.

Geometry utilities for vector operations in FSM-based reaction path methods.

mlfsm.geom.distance(v1, v2)[source]

Return the Euclidean distance between two vectors v1 and v2.

Parameters:
Return type:

float

mlfsm.geom.magnitude(v)[source]

Return the magnitude (L2 norm) of a vector with floor for stability.

Parameters:

v (ndarray[tuple[Any, ...], dtype[floating]])

Return type:

float

mlfsm.geom.normalize(v)[source]

Return the normalized version of a vector.

Parameters:

v (ndarray[tuple[Any, ...], dtype[floating]])

Return type:

ndarray[tuple[Any, …], dtype[floating]]

mlfsm.geom.calculate_arc_length(string)[source]

Compute cumulative arc length along a string of molecular geometries.

Parameters:

string (ndarray[tuple[Any, ...], dtype[floating]])

Return type:

ndarray[tuple[Any, …], dtype[floating]]

mlfsm.geom.project_trans_rot(a, b)[source]

Minimizes distance between structures a and b by minimizing rotation and translation.

Parameters:
Return type:

tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]]]

mlfsm.geom.project_trans_rot_fixed(a, b, fixed)[source]

Minimizes distance between structures a and b by minimizing rotation and translation.

Parameters:
Return type:

tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]]]

mlfsm.geom.generate_inertia_I(X)[source]

Compute the moment of inertia tensor for a set of 3D coordinates X.

Parameters:

X (ndarray[tuple[Any, ...], dtype[floating]])

Return type:

ndarray[tuple[Any, …], dtype[floating]]

mlfsm.geom.generate_project_rt(X)[source]

Construct a projection operator that removes rigid translations and rotations from X.

Parameters:

X (ndarray[tuple[Any, ...], dtype[floating]])

Return type:

ndarray[tuple[Any, …], dtype[floating]]

mlfsm.geom.generate_project_rt_tan(structure, tangent)[source]

Construct a projection operator orthogonal to translations, rotations, and the tangent vector.

Parameters:
Return type:

ndarray[tuple[Any, …], dtype[floating]]

Utilities (mlfsm.utils)

Input/output helpers for loading reactant and product geometries and handling fixed-atom constraints.

Utility functions for reading input and checking numeric types.

mlfsm.utils.load_xyz(reaction_dir)[source]

Load reactant and product geometries from a reaction directory.

Reads the first and last frames of initial.xyz and aligns them by minimizing rigid-body rotation and translation via the Kabsch algorithm.

Parameters:

reaction_dir (path-like) – Directory containing initial.xyz. The file must have at least two XYZ frames: the reactant (first) and the product (last).

Returns:

  • reactant (ase.Atoms) – Reactant geometry after alignment.

  • product (ase.Atoms) – Product geometry after alignment to the reactant.

Raises:

Exception – If initial.xyz does not exist in reaction_dir.

Return type:

tuple[Atoms, Atoms]

mlfsm.utils.load_xyz_fixed(reaction_dir, fixed)[source]

Load reactant and product geometries with fixed-atom constraints applied.

Reads initial.xyz, aligns the structures, and attaches an ASE FixAtoms constraint to both atoms objects so that the specified atoms are held stationary during FSM optimization. When fixed is empty the behaviour is identical to load_xyz().

Parameters:

  • reaction_dir (path-like) – Directory containing initial.xyz.

  • fixed (NDArray[int]) – Zero-indexed array of atom indices to freeze. Pass an empty array (np.array([], dtype=int)) to apply no constraints.

Returns:

  • reactant (ase.Atoms) – Reactant geometry with FixAtoms applied.

  • product (ase.Atoms) – Product geometry with FixAtoms applied.

Raises:

Exception – If initial.xyz does not exist in reaction_dir.

Return type:

tuple[Atoms, Atoms]

mlfsm.utils.float_check(x)[source]

Convert a scalar, 0-D array, or single-element container to a Python float.

Parameters:

x (float, ndarray, list, or tuple) – Value to convert. Must be a plain float, a 0-D NumPy array, or a length-1 sequence.

Returns:

The converted value.

Return type:

float

Raises:

TypeError – If x is a multi-element container or an unsupported type.