stochkin.workflows

High-level, one-call wrappers for the most common stochastic-kinetics pipelines.

stochkin.workflows

High-level, one-call wrappers for the most common stochastic-kinetics pipelines. Each function bundles loading, basin detection, and CTMC generator construction into a single call and returns a uniform result dictionary.

Result dictionary keys

s 1-D grid (CV values) F Free energy at grid points [kJ/mol] D_used Diffusion coefficient used on the grid [CV²/time_unit] kT Thermal energy at the requested temperature [kJ/mol] K Rate matrix in the input time_unit [1/time_unit] K_ps Rate matrix in picoseconds [1/ps] exit_mean Mean exit time per basin [time_unit] exit_ps Mean exit time per basin [ps] k_out Total exit rate per basin [1/time_unit] k_out_ps Total exit rate per basin [1/ps] p_branch Branching-probability matrix [dimensionless] labels_full Integer label per grid point (basin id, or -1) basin_ids Sorted array of integer basin ids

stochkin.workflows.run_1d_ctmc(s, F, D, T=300.0, time_unit='ps', max_basins=None, core_fraction=0.05, init_weight='boltzmann', resample_n=500, verbose=True)[source]

Compute 1D CTMC kinetics from arrays s, F, D.

This is the lowest-level workflow: it accepts the free-energy profile and diffusion coefficient directly as arrays and handles everything else (basin detection, core labelling, BVP solve, result packing).

Parameters:

  • s (array (N,)) – Uniform grid of CV values.

  • F (array (N,)) – Free energy in kJ/mol at each grid point.

  • D (float or array (N,)) – Diffusion coefficient in CV²/time_unit. Scalar = constant D; array = position-dependent D(s).

  • T (float) – Temperature in Kelvin. Default 300 K.

  • time_unit (str) – Time unit of D (and of the returned K / exit_mean). One of 'fs', 'ps' (default), 'ns', 'us'.

  • max_basins (int, optional) – Cap the number of detected basins.

  • core_fraction (float, optional) – Fraction of each basin (ranked by proximity to the minimum) that counts as the “core” for CTMC entry/exit averaging. 0.05 = 5 %. Use None to use the full basin.

  • init_weight ({'boltzmann', 'uniform'}) – Weight for basin averages of exit times.

  • verbose (bool)

  • resample_n (int)

Returns:

See module-level docstring for key descriptions.

Return type:

dict

stochkin.workflows.run_1d_ctmc_from_plumed(fes_path, D, T=300.0, time_unit='ps', crop=None, resample_n=None, s_col=0, F_col=1, max_basins=None, core_fraction=0.05, init_weight='boltzmann', verbose=True)[source]

Load a 1D PLUMED FES and compute CTMC kinetics with a constant D.

Parameters:

  • fes_path (str or Path) – Path to a PLUMED-style 1D FES file (comments start with #).

  • D (float) – Diffusion coefficient in CV²/time_unit.

  • T (float) – Temperature in K.

  • time_unit (str) – Time unit for D and for the returned rates.

  • crop ((s_lo, s_hi), optional) – Restrict the FES to this CV range before analysis.

  • resample_n (int) – Resample to this many uniform points (useful after cropping).

  • s_col (int) – Column indices for CV and free energy in the FES file.

  • F_col (int) – Column indices for CV and free energy in the FES file.

  • resample_n – Resample the MFEP arc-length profile to this many uniform points before running the FPE solver (which requires a uniform grid). Default 500.

  • max_basins (int | None) – Forwarded to run_1d_ctmc().

  • core_fraction (float | None) – Forwarded to run_1d_ctmc().

  • init_weight (str) – Forwarded to run_1d_ctmc().

  • verbose (bool) – Forwarded to run_1d_ctmc().

Return type:

dict (same keys as run_1d_ctmc())

stochkin.workflows.run_1d_ctmc_with_hummer_D(fes_path, d_csv, T=300.0, time_unit='ps', d_xcol='x_interface', d_col='D_med', d_grid='interface', d_interface_mode='harmonic', d_time_unit='ps', d_interp_method='linear', crop=None, resample_n=500, s_col=0, F_col=1, max_basins=None, core_fraction=0.05, init_weight='boltzmann', verbose=True)[source]

Load a 1D PLUMED FES and a Hummer-style D(s) profile; compute CTMC.

This is the standard workflow when D(s) has been estimated from short MD runs using the Hummer (2005) Bayesian inference.

Parameters:

  • fes_path (str or Path) – PLUMED 1D FES file.

  • d_csv (str or Path) – CSV file with the diffusion profile. Must contain at least two columns named d_xcol and d_col.

  • T (float) – Temperature in K.

  • time_unit (str) – Time unit for the returned rates.

  • d_xcol (str) – Column name for CV positions in the CSV (default 'x_interface').

  • d_col (str) – Column name for D values in the CSV (default 'D_med').

  • d_grid ({'interface', 'center'}) – 'interface': the CSV positions are internal bin interfaces and D values are face-centred (Hummer-style). They will be converted to bin-centre values via interface_to_centers(). 'center': D values are already at bin centres; no conversion.

  • d_interface_mode ({'harmonic', 'avg'}) – Conversion method when d_grid='interface'.

  • d_time_unit (str) – Time unit of the raw D values in the CSV (default 'ps').

  • d_interp_method ({'linear', 'pchip'}) – How to interpolate D onto the FES grid.

  • crop ((s_lo, s_hi), optional) – CV range to retain from the FES.

  • resample_n (int) – Resample the FES to this many uniform points before interpolating D. Required because the FPE solver needs a uniform grid. Default 500.

  • s_col (int) – Column indices in the FES file.

  • F_col (int) – Column indices in the FES file.

  • resample_n – Resample the MFEP arc-length profile to this many uniform points before running the FPE solver (which requires a uniform grid). Default 500.

  • max_basins (int | None) – Forwarded to run_1d_ctmc().

  • core_fraction (float | None) – Forwarded to run_1d_ctmc().

  • init_weight (str) – Forwarded to run_1d_ctmc().

  • verbose (bool) – Forwarded to run_1d_ctmc().

Return type:

dict (same keys as run_1d_ctmc())

stochkin.workflows.run_mfep_ctmc(fes2d_path, start, end, D_s, T=300.0, time_unit='ps', neb_images=120, neb_steps=3000, neb_spring=1.0, use_neb=True, max_basins=None, core_fraction=0.05, init_weight='boltzmann', resample_n=500, verbose=True)[source]

Find the MFEP on a 2D FES and compute 1D CTMC kinetics along it.

Workflow:

  1. Load the 2D PLUMED FES.

  2. Find the minimum free-energy path (MFEP) from start to end using a grid-Dijkstra seed followed by NEB refinement.

  3. Extract the 1D free-energy profile F(s) along the arc-length s.

  4. Run run_1d_ctmc() on F(s) with the supplied constant D_s.

Parameters:

  • fes2d_path (str or Path) – Path to a 2D PLUMED FES file.

  • start ((x, y)) – Start and end points for the MFEP in CV space.

  • end ((x, y)) – Start and end points for the MFEP in CV space.

  • D_s (float) – Diffusion coefficient along the arc-length s [arc-length²/time_unit].

  • T (float) – Temperature in K.

  • time_unit (str) – Time unit for D_s and the returned rates.

  • neb_images (int) – Number of NEB images (controls resolution of the 1D profile).

  • neb_steps (int) – Maximum NEB optimisation steps.

  • neb_spring (float) – NEB spring constant (kJ/mol per CV² or compatible units).

  • use_neb (bool) – If False, skip NEB refinement and use the raw grid path.

  • resample_n (int) – Resample the MFEP arc-length profile to this many uniform points before running the FPE solver (which requires a uniform grid). Default 500.

  • max_basins (int | None) – Forwarded to run_1d_ctmc().

  • core_fraction (float | None) – Forwarded to run_1d_ctmc().

  • init_weight (str) – Forwarded to run_1d_ctmc().

  • verbose (bool) – Forwarded to run_1d_ctmc().

Returns:

Same keys as run_1d_ctmc() plus 'mfep_path' (MFEPPath).

Return type:

dict

stochkin.workflows.run_multi_mfep_ctmc(fes2d_path, D_s, T=300.0, time_unit='ps', neb_images=8120, neb_steps=3000, neb_spring=1.0, use_neb=True, max_basins=None, core_fraction=0.05, init_weight='boltzmann', resample_n=500, verbose=True)[source]

Detect all basins on a 2D FES and compute pairwise MFEP-based CTMC rates.

Workflow:

  1. Load the 2D PLUMED FES and build an interpolated potential.

  2. Detect all basins on the 2D surface.

  3. For every pair of basins (i, j), compute the MFEP connecting their minima and run the 1D CTMC pipeline on the resulting F(s) profile.

  4. Assemble a full N×N rate matrix from the pairwise 2-basin results.

Parameters:

  • fes2d_path (str or Path) – Path to a 2D PLUMED FES file.

  • D_s (float) – Constant diffusion coefficient along the arc-length [arc-length² / time_unit].

  • T (float) – Temperature in K.

  • time_unit (str) – Time unit for rates ('ps', 'ns', …).

  • neb_images (int) – NEB parameters forwarded to compute_mfep_profile_1d().

  • neb_steps (int) – NEB parameters forwarded to compute_mfep_profile_1d().

  • neb_spring (float) – NEB parameters forwarded to compute_mfep_profile_1d().

  • use_neb (bool) – NEB parameters forwarded to compute_mfep_profile_1d().

  • max_basins (int or None) – Keep only the max_basins deepest minima.

  • core_fraction (float | None) – Forwarded to run_1d_ctmc().

  • init_weight (str) – Forwarded to run_1d_ctmc().

  • resample_n (int) – Uniform resampling density for F(s) before the FPE solve.

  • verbose (bool) – Print progress information.

Returns:

basin_networkBasinNetwork

The detected 2D basins.

basin_idsnp.ndarray

Sorted array of basin indices.

Knp.ndarray, shape (N, N)

Full rate matrix [1/time_unit].

K_psnp.ndarray

Rate matrix in ps⁻¹.

exit_timesnp.ndarray

Mean exit time from each basin [time_unit].

exit_psnp.ndarray

Mean exit time in ps.

kTfloat

Thermal energy [kJ/mol].

legsdict

legs[(i, j)] is the full result dict from run_mfep_ctmc for the directed MFEP leg from basin i to basin j.

Return type:

dict with keys

stochkin.workflows.interface_to_centers(x_interface, D_interface, method='harmonic')[source]

Convert Hummer-style interface diffusion values to bin-center values.

Hummer’s Bayesian estimator places D_{i+1/2} at internal bin interfaces. This routine reconstructs bin-center D_i by extrapolating one bin to each edge and then averaging (or taking harmonic means) of adjacent interface values.

Parameters:

  • x_interface (array (M,)) – CV positions of the M internal interfaces.

  • D_interface (array (M,)) – D values at those interfaces.

  • method ({'harmonic', 'avg'}) – 'harmonic' (default) gives a better approximation for barriers (avoids over-estimating D at low-D regions); 'avg' is simpler.

Returns:

  • x_center (array (M+1,))

  • D_center (array (M+1,))

  • edges (array (M+2,) full edge positions used internally)

Return type:

Tuple[ndarray, ndarray, ndarray]

stochkin.workflows.interpolate_D_to_grid(s_grid, x_D, D_vals, method='linear')[source]

Interpolate a D(s) profile onto s_grid, clamping outside the range.

Parameters:

  • s_grid (array (N,)) – Target uniform grid.

  • x_D (array (M,)) – CV positions of the diffusion profile.

  • D_vals (array (M,)) – Diffusion values at those positions.

  • method ({'linear', 'pchip'}) – Interpolation method. 'pchip' requires SciPy.

Returns:

D_grid

Return type:

array (N,) non-negative finite diffusion values on s_grid.