API Reference

Coordinate generation and transformation tools for FSM optimization.

class mlfsm.coords.Cartesian(atoms1: Atoms, atoms2: Atoms | None = None, verbose: bool = False)

Bases: Coordinates

Cartesian coordinate system used for atoms.

construct() → Dict[str, Any]: Build Cartesian coordinate representation.

class mlfsm.coords.Coordinates(atoms1: Atoms, atoms2: Atoms | None = None, verbose: bool = False)

Bases: object

Base class for internal coordinate systems used in FSM.

b_matrix(xyz: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]: Construct the B-matrix for internal coordinates.

construct() → Dict[str, Any]: Construct the coordinate representation for a given atom set.

dqprint(atoms1: Atoms, atoms2: Atoms) → None: Print differences in internal coordinates between two structures.

q(xyz: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]: Return coordinate values in from Cartesian positions.

qprint(atoms: Atoms) → None: Print coordinate values in human-readable format for a given ASE atoms object.

u_matrix(Bprim: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]: Compute projection matrix U from the B-matrix.

x(xyz: ndarray[tuple[Any, ...], dtype[float64]], qtarget: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]: Back-transform internal coordinate displacements to Cartesian updates.

class mlfsm.coords.Redundant(atoms1: Atoms, atoms2: Atoms | None = None, verbose: bool = False)

Bases: Coordinates

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

atoms_to_ric(atoms: Atoms) → Dict[str, Any]: Generate a redundant internal coordinate (RIC) set from ASE.Atoms object.

checkangle(A: ndarray[tuple[Any, ...], dtype[float64]], B: ndarray[tuple[Any, ...], dtype[float64]], C: ndarray[tuple[Any, ...], dtype[float64]]) → bool: Check if angle defined by three atoms is physically valid.

checkstre(A: ndarray[tuple[Any, ...], dtype[float64]], B: ndarray[tuple[Any, ...], dtype[float64]], eps: float = 1e-08) → bool: Check if distance between two atoms is significant (non-zero within tolerance).

checktors(A: ndarray[tuple[Any, ...], dtype[float64]], B: ndarray[tuple[Any, ...], dtype[float64]], C: ndarray[tuple[Any, ...], dtype[float64]], D: ndarray[tuple[Any, ...], dtype[float64]]) → bool: Check if torsion angle defined by four atoms is physically valid.

connectivity(atoms: Atoms) → 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]]]: Compute connectivity matrices from atomic positions.

construct() → Dict[str, Any]: Construct the full set of internal coordinates based on input atoms.

get_fragments(A: ndarray[tuple[Any, ...], dtype[int64]]) → List[ndarray[tuple[Any, ...], dtype[int64]]]: Return list of fragments as connected components in adjacency matrix.

Freezing String Method driver for reaction pathway construction.

class mlfsm.cos.FreezingString(reactant: Atoms, product: Atoms, nnodes_min: int = 10, interp_method: str = 'ric', ninterp: int = 100)

Bases: object

Implements the Freezing String Method.

grow() → None: Grow the string by adding nodes from each end.

interpolate(outdir: Path | str) → None: Generate and write interpolated string between current endpoints.

optimize(optimizer: Any) → None: Relax unfixed nodes on the hyperplane orthogonal to the local tangent direction.

write(outdir: Path | str) → None: Write current string geometries and relative energies to an XYZ file.

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

mlfsm.geom.calculate_arc_length(string: ndarray[tuple[Any, ...], dtype[floating]]) → ndarray[tuple[Any, ...], dtype[floating]]: Compute cumulative arc length along a string of molecular geometries.

mlfsm.geom.distance(v1: ndarray[tuple[Any, ...], dtype[floating]], v2: ndarray[tuple[Any, ...], dtype[floating]]) → float: Return the Euclidean distance between two vectors v1 and v2.

mlfsm.geom.generate_inertia_I(X: ndarray[tuple[Any, ...], dtype[floating]]) → ndarray[tuple[Any, ...], dtype[floating]]: Compute the moment of inertia tensor for a set of 3D coordinates X.

mlfsm.geom.generate_project_rt(X: ndarray[tuple[Any, ...], dtype[floating]]) → ndarray[tuple[Any, ...], dtype[floating]]: Construct a projection operator that removes rigid translations and rotations from X.

mlfsm.geom.generate_project_rt_tan(structure: ndarray[tuple[Any, ...], dtype[floating]], tangent: ndarray[tuple[Any, ...], dtype[floating]]) → ndarray[tuple[Any, ...], dtype[floating]]: Construct a projection operator orthogonal to translations, rotations, and the tangent vector.

mlfsm.geom.magnitude(v: ndarray[tuple[Any, ...], dtype[floating]]) → float: Return the magnitude (L2 norm) of a vector with floor for stability.

mlfsm.geom.normalize(v: ndarray[tuple[Any, ...], dtype[floating]]) → ndarray[tuple[Any, ...], dtype[floating]]: Return the normalized version of a vector.

mlfsm.geom.project_trans_rot(a: ndarray[tuple[Any, ...], dtype[floating]], b: ndarray[tuple[Any, ...], dtype[floating]]) → tuple[ndarray[tuple[Any, ...], dtype[floating]], ndarray[tuple[Any, ...], dtype[floating]]]: Minimizes distance between structures a and b by minimizing rotation and translation.

Interpolation methods for constructing paths between endpoint geometries.

class mlfsm.interp.Interpolate(atoms1: Atoms, atoms2: Atoms, ninterp: int, gtol: float = 0.0001)

Bases: object

Abstract base class for interpolation schemes between molecular geometries.

atoms1: Atoms

atoms2: Atoms

gtol: float = 0.0001

interpolate() → ndarray[tuple[Any, ...], dtype[float32]]: Abstract interpolationn routine-must be overridden.

ninterp: int

class mlfsm.interp.LST(atoms1: Atoms, atoms2: Atoms, ninterp: int, gtol: float = 0.0001)

Bases: Interpolate

Linear Synchronous Transit (LST) interpolation method.

Halgren, Thomas A., and William N. Lipscomb. “The synchronous transit method for determining reaction pathways and locating molecular transition states.” Chemical Physics Letters 49.2 (1977): 225 to 232.

interpolate() → ndarray[tuple[Any, ...], dtype[float32]]: Generate interpolated structures using LST.

obj(x_c: ndarray[tuple[Any, ...], dtype[floating]], f: float, rab: Callable[[float], ndarray[tuple[Any, ...], dtype[floating]]], xab: Callable[[float], ndarray[tuple[Any, ...], dtype[floating]]]) → float: Objective function for LST interpolation.

class mlfsm.interp.Linear(atoms1: Atoms, atoms2: Atoms, ninterp: int, gtol: float = 0.0001)

Bases: Interpolate

Linear interpolation of Cartesian coordinates.

Generates a reaction path by linearly interpolating Cartesian coordinates between two endpoint geometries.

interpolate() → ndarray[tuple[Any, ...], dtype[float32]]: Compute linear interpolated path between two geometries.

class mlfsm.interp.RIC(atoms1: Atoms, atoms2: Atoms, ninterp: int, gtol: float = 0.0001)

Bases: Interpolate

Interpolates in redundant internal coordinates (RIC).

interpolate() → ndarray[tuple[Any, ...], dtype[float32]]: Generate interpolated structures using linear interpolation in RIC.

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.CartesianOptimizer(calc: Any, method: str = 'L-BFGS-B', maxiter: int = 3, maxls: int = 2, dmax: float = 0.3)

Bases: Optimizer

Performs optimization in Cartesian coordinates using projected gradients.

obj(xyz: ndarray[tuple[Any, ...], dtype[Any]], tangent: ndarray[tuple[Any, ...], dtype[Any]], atoms: Atoms) → tuple[float, ndarray[tuple[Any, ...], dtype[Any]]]

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: Atoms, tangent: ndarray[tuple[Any, ...], dtype[Any]]) → tuple[Atoms, float, int]

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] (ASE.Atoms with final positions, energy of final structure, and number)
of gradient calculations used by optimization.

class mlfsm.opt.InternalsOptimizer(calc: Any, method: str = 'L-BFGS-B', maxiter: int = 3, maxls: int = 6, dmax: float = 0.05)

Bases: Optimizer

Performs projected optimization in internal coordinates.

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

compute_bounds(q: ndarray[tuple[Any, ...], dtype[Any]]) → list[tuple[float, float]]

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.

dmax: float = 0.05

maxls: int = 6

obj(q: ndarray[tuple[Any, ...], dtype[Any]], xyzref: ndarray[tuple[Any, ...], dtype[Any]], tangent: ndarray[tuple[Any, ...], dtype[Any]], atoms: Atoms) → tuple[float, ndarray[tuple[Any, ...], dtype[Any]]]

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: Atoms, tangent: ndarray[tuple[Any, ...], dtype[Any]]) → tuple[Atoms, float, int]

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] (ASE.Atoms with final positions, energy of final structure, and number)
of gradient calculations used by optimization.

class mlfsm.opt.Optimizer(calc: Any, method: str = 'L-BFGS-B', maxiter: int = 3, maxls: int = 2, dmax: float = 0.3)

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.

calc: Any

dmax: float = 0.3

maxiter: int = 3

maxls: int = 2

method: str = 'L-BFGS-B'

obj(*args: Any, **kwargs: Any) → Any

Objective function to be implemented by subclasses.

Parameters:

xyz (ndarray) – Cartesian coordinates (flattened).
tangent (ndarray) – Tangent vector used for projection.

Raises:

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

optimizeobj(*args: Any, **kwargs: Any) → Any

Optimization method to be implemented by subclasses.

Parameters:

xyz (ndarray) – Cartesian coordinates (flattened).
tangent (ndarray) – Tangent vector used for projection.

Raises:

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

Utility functions for reading input and checking numeric types.

mlfsm.utils.float_check(x: float) → float

Convert scalars, 0D arrays, or single element containers to a float.

Leaves floats alone. Raises an error for anything else.

mlfsm.utils.load_xyz(reaction_dir: Path | str) → tuple[Atoms, Atoms]

Load reactant and product geometries from a directory.

Assumes a file named initial.xyz containing the reactant and product geometries.