FB-ENM Calculators

class dmf.fbenm.FB_ENM(d_min, d_max, delta_min=None, delta_max=None, delta_scale=0.2)

Bases: Calculator

ASE calculator for the Flat-bottom Elastic Network Model (FB-ENM).

A lightweight structure-based potential for generating collision-free plausible paths used in combination with the direct MaxFlux method. Each pair interaction has a flat bottom defined by (d_min, d_max). This class implements the general pairwise model.

This implementation follows the model introduced in:

Koda & Saito, J. Chem. Theory Comput. 2024, 20, 7176–7187.

See the original paper for theoretical details.

Parameters:

  • d_min (ndarray of shape (N, N)) – Lower bounds of the flat-bottom region for each atom pair. Here, N must match the number of atoms in the Atoms object to which this calculator is attached.

  • d_max (ndarray of shape (N, N)) – Upper bounds of the flat-bottom region for each atom pair. Must have the same shape and atom ordering as d_min.

  • delta_min (ndarray of shape (N, N) or None) – Width parameters for the quadratic walls. If None, they are set to delta_scale * d_min and delta_scale * d_max, respectively. Default: None.

  • delta_max (ndarray of shape (N, N) or None) – Width parameters for the quadratic walls. If None, they are set to delta_scale * d_min and delta_scale * d_max, respectively. Default: None.

  • delta_scale (float) – Scale factor used when delta_min/max are autogenerated. Default: 0.2.

Notes

  • Energy is zero when all distances lie within [d_min, d_max].

  • Forces derive from quadratic penalties outside the flat bottom.

  • This class does not determine d_min/d_max from structures; see FB_ENM_Bonds for the bond-aware construction.

class dmf.fbenm.FB_ENM_Bonds(images, addA=None, delA=None, delta_scale=0.2, bond_scale=1.25, fix_planes=True, d_min_overwrite=None, d_max_overwrite=None, A_overwrite=None)

Bases: FB_ENM

ASE calculator for bond-aware FB-ENM.

Builds an FB-ENM automatically from multiple reference images. Bond lengths and bond angles preserved across all images are strongly constrained, while other distances receive weak bounds.

Also supports optional planar constraints for π-like fragments. For details on how these constraints are defined, refer to:

Koda & Saito, J. Chem. Theory Comput. 2024, 20, 7176–7187.

Parameters:

  • images (list of ase.Atoms) – Reference structures. Here, natoms = len(images[0]).

  • addA (boolean ndarray of shape (natoms, natoms), optional) – Manually add strong constraints. Pairs marked True are added. Default: None.

  • delA (boolean ndarray of shape (natoms, natoms), optional) – Manually remove strong constraints. Pairs marked True are removed. If both addA and delA are provided, delA takes precedence. Default: None.

  • delta_scale (float, optional) – Scale for delta_min/max in the parent FB_ENM. Default: 0.2.

  • bond_scale (float, optional) – Threshold for bond detection (bond is detected when d_ij < bond_scale × (r_cov[i] + r_cov[j])). Default: 1.25.

  • fix_planes (bool, optional) – Whether to add additional constraints to preserve planar groups. Default: True.

  • d_min_overwrite (float or ndarray of shape (natoms, natoms), optional) – Values used to overwrite selected entries of d_min. Only pairs where A_overwrite is True are replaced. Default: None.

  • d_max_overwrite (float or ndarray of shape (natoms, natoms), optional) – Values used to overwrite selected entries of d_max. Only pairs where A_overwrite is True are replaced. Default: None.

  • A_overwrite (boolean ndarray of shape (natoms, natoms), optional) –

    Boolean mask specifying which atom pairs should be overwritten. For any (i, j) where A_overwrite[i, j] == True, the following assignments are applied:

    d_min[A_overwrite] = d_min_overwrite[A_overwrite]
d_max[A_overwrite] = d_max_overwrite[A_overwrite]

    Must be supplied when using either overwrite option. Default: None.

Notes

  • Weak constraints follow van der Waals and system-size bounds.

class dmf.fbenm.CFB_ENM(images, bond_scale=1.25, d_corr0=None, corr0_scale=1.1, d_corr1=None, corr1_scale=1.5, d_corr2=None, corr2_scale=1.6, eps=0.05, pivotal=True, single=True, remove_fourmembered=True)

Bases: Calculator

Correlated Flat-Bottom ENM (CFB-ENM).

Extends FB-ENM by adding correlation terms between bond-breaking and bond-forming atom pairs. This enforces coordinated structural changes that FB-ENM cannot capture alone.

The correlation model and selection of correlated quartets follow the formulation described in the companion paper:

Koda & Saito, J. Chem. Theory Comput. 21, 3513-3522 (2025).

See the original paper for the mathematical definitions.

Parameters:

  • images (list of ase.Atoms) – Reference structures. Here, natoms = len(images[0]).

  • bond_scale (float) – Threshold to detect bonds from distances. Default: 1.25.

  • d_corr0 (ndarray of shape (natoms, natoms) or None, optional) – Flat-bottom thresholds for the correlated pair-pair potential. See the original paper for their definitions. If None, they are generated by scaling the largest bond length. Default: None.

  • d_corr1 (ndarray of shape (natoms, natoms) or None, optional) – Flat-bottom thresholds for the correlated pair-pair potential. See the original paper for their definitions. If None, they are generated by scaling the largest bond length. Default: None.

  • d_corr2 (ndarray of shape (natoms, natoms) or None, optional) – Flat-bottom thresholds for the correlated pair-pair potential. See the original paper for their definitions. If None, they are generated by scaling the largest bond length. Default: None.

  • corr0_scale (float) – Scaling factors used when d_corr arrays are not provided. See the original paper for their definitions. Default: 1.10.

  • corr1_scale (float) – Scaling factors used when d_corr arrays are not provided. See the original paper for their definitions. Default: 1.50.

  • corr2_scale (float) – Scaling factors used when d_corr arrays are not provided. See the original paper for their definitions. Default: 1.60.

  • eps (float) – Small value added for numerical stability in the correlation term. See the original paper for their definitions. Default: 0.05.

  • pivotal (bool) – If True, restrict correlation to pivot-based patterns. See the original paper for the definition of “pivot”. Default: True.

  • single (bool) – If True, require exactly one breaking and one forming bond at pivot. See the original paper for the definition of “single pivot”. Default: True.

  • remove_fourmembered (bool) – Exclude quasi-four-membered-ring patterns that lead to artifacts. See the original paper for the definition of “quasi-four-membered ring”. Default: True.

Notes

  • CFB-ENM adds only correlation energy; FB-ENM must be used together if flat-bottom bond/angle constraints are required. That is, use CFB_ENM alongside FB_ENM_Bonds in a SumCalculator as:

    from ase.calculators.mixing import SumCalculator
calc = SumCalculator([
         FB_ENM_Bonds(...),
         CFB_ENM(...)])