stochkin.mfep

Minimum free-energy path search (grid Dijkstra + NEB refinement).

MFEP utilities for 2D free-energy surfaces.

This submodule provides:

  1. Grid-based MFEP search (Dijkstra/minimax)

  2. NEB-style path refinement

  3. Export of a 1D profile s -> F(s) compatible with 1D CTMC workflows

class stochkin.mfep.MFEPPath(x, y, s, F, method, objective, indices=None, metadata=<factory>)[source]

Bases: object

MFEP trajectory and projected 1D free-energy profile.

Parameters:
x, y

MFEP coordinates in the original CV space.

Type:

1D arrays

s

Curvilinear coordinate along the path (same length as x/y).

Type:

1D array

F

Free energy sampled along the path (same length as x/y).

Type:

1D array

method

Path construction method, e.g. “grid” or “neb”.

Type:

str

objective

Optimization objective, e.g. “integral”, “barrier”, “refined”.

Type:

str

indices

Optional grid indices (available for grid paths).

Type:

list[(ix,iy)] or None

metadata

Additional run details.

Type:

dict

x: ndarray
y: ndarray
s: ndarray
F: ndarray
method: str
objective: str
indices: List[Tuple[int, int]] | None = None
metadata: Dict[str, Any]
as_xy()[source]

Return path as shape (N,2) array.

Return type:

ndarray

save_profile_1d(filename, *, subtract_min=True, fmt='%.10f')[source]

Save 1D profile for CTMC scripts as two columns: s, F.

Output format is PLUMED-like and compatible with loaders that read the first two numeric columns as (coordinate, free energy).

Parameters:
Return type:

Path

save_path_xyf(filename, *, subtract_min=False, fmt='%.10f')[source]

Save full path as four columns: s, x, y, F.

Parameters:
Return type:

Path

class stochkin.mfep.GridMFEP(x_grid, y_grid, fes_grid)[source]

Bases: object

Grid-based MFEP finder on a 2D FES.

Supports two objectives:

  • “integral”: minimum integrated free energy along the path

  • “barrier”: minimax barrier path (minimum maximum encountered F)

Parameters:

  • x_grid (np.ndarray)

  • y_grid (np.ndarray)

  • fes_grid (np.ndarray)

classmethod from_plumed(filename, *, x_col=0, y_col=1, fes_col=2, subtract_min=True, verbose=False)[source]
Parameters:
Return type:

GridMFEP

coordinate_to_index(point)[source]
Parameters:

point (Sequence[float])

Return type:

Tuple[int, int]

find_path(start, end, *, objective='integral', connectivity=8, f_threshold=None, project_to_finite=True)[source]

Compute a grid MFEP between start and end points.

Parameters:

  • start (sequence[float]) – Start/end coordinates [x, y].

  • end (sequence[float]) – Start/end coordinates [x, y].

  • objective ({"integral", "barrier"}) – integral -> minimum integrated F(s) barrier -> minimax path (minimum maximum F)

  • connectivity ({4, 8}) – Grid connectivity.

  • f_threshold (float or None) – Optional hard mask: allow only cells with F <= f_threshold (start/end are always allowed).

  • project_to_finite (bool) – If True, snap start/end to nearest finite cell if needed.

Return type:

MFEPPath

class stochkin.mfep.NEBMFEP(x_grid, y_grid, fes_grid, *, fill_value=None)[source]

Bases: object

NEB-style path refiner on a 2D FES grid.

Intended as a refinement step starting from a grid MFEP.

Parameters:

  • x_grid (np.ndarray)

  • y_grid (np.ndarray)

  • fes_grid (np.ndarray)

  • fill_value (Optional[float])

refine(initial_path, *, n_images=120, k_spring=1.0, step_size=0.01, max_iter=8000, tol=1.0, smooth=0.0, clip_to_bounds=True, max_step=None, adaptive_step=True, step_shrink=0.5, step_grow=1.02, step_min=None, reparam_every=10)[source]

Refine an initial path with a simple NEB-style iterative scheme.

Parameters:
Return type:

MFEPPath

refine_between(start, end, *, initializer=None, initializer_objective='integral', initializer_connectivity=8, initializer_f_threshold=None, **neb_kwargs)[source]

Build an initial grid path between start/end, then refine with NEB.

Parameters:
Return type:

MFEPPath

refine_fire(initial_path, *, n_images=120, k_spring=1.0, dt_start=0.005, dt_max=0.05, max_iter=8000, tol=1.0, n_min=5, f_inc=1.1, f_dec=0.5, alpha_start=0.1, f_alpha=0.99, smooth=0.0, clip_to_bounds=True, reparam_every=200)[source]

Refine an NEB path using the FIRE algorithm (Bitzek et al. 2006).

FIRE (Fast Inertial Relaxation Engine) uses velocity-based dynamics with adaptive time-stepping. It converges much faster than steepest descent for NEB optimisation.

Parameters:

  • initial_path ((N, 2) array)

  • n_images (NEB parameters)

  • k_spring (NEB parameters)

  • dt_start (initial time step)

  • dt_max (maximum allowed time step)

  • max_iter (iteration cap)

  • tol (force convergence tolerance (kJ mol⁻¹ per CV-unit))

  • n_min (FIRE delay before acceleration)

  • f_inc (time-step scale factors)

  • f_dec (time-step scale factors)

  • alpha_start (FIRE mixing parameters)

  • f_alpha (FIRE mixing parameters)

  • smooth (smoothing factor ∈ [0, 1])

  • clip_to_bounds (clip images to grid domain)

  • reparam_every (reparametrize path every N steps)

Return type:

MFEPPath

stochkin.mfep.compute_mfep_profile_1d(x_grid, y_grid, fes_grid, start, end, *, objective='integral', connectivity=8, f_threshold=None, use_neb=True, neb_images=120, neb_k_spring=1.0, neb_step_size=0.01, neb_max_iter=8000, neb_tol=1.0, neb_smooth=0.0, neb_max_step=None, neb_adaptive_step=True, neb_reparam_every=None, neb_optimizer='sd')[source]
Convenience wrapper:

  1. grid MFEP between start/end

  2. optional NEB refinement

  3. return MFEPPath containing s,F(s)

Parameters:
Return type:

MFEPPath