Getting Started

Installation

From the repository root:

pip install -e .

This installs stochkin in editable mode with the core dependencies (NumPy, SciPy, Matplotlib, tqdm, pandas). Optional extras are available for notebook usage, development tooling, and the FiPy-based 2-D Fokker– Planck backend:

pip install -e ".[notebooks]"   # Jupyter + ipykernel
pip install -e ".[dev]"         # pytest, black, ruff, pre-commit
pip install -e ".[fipy]"        # optional 2-D FPE backend

If you only need notebooks without editable install extras, a minimal alternative is:

pip install jupyter ipykernel

Bundled examples and notebooks

The repository includes both script and notebook versions of the main worked examples:

• examples/generate_synthetic_data.py plus notebooks/00_generate_synthetic_data.ipynb

• examples/01_analytic_doublewell.py plus notebooks/01_analytic_doublewell.ipynb

• examples/02_1d_plumed_fes_ctmc.py plus notebooks/02_1d_plumed_fes_ctmc.ipynb

• examples/03_1d_hummer_D_ctmc.py plus notebooks/03_1d_hummer_D_ctmc.ipynb

• examples/04_mfep_ctmc.py plus notebooks/04_mfep_ctmc.ipynb

• examples/05_pairwise_mfep_paths.py plus notebooks/05_pairwise_mfep_paths.ipynb

• examples/06_uncertainty.py plus notebooks/06_uncertainty.ipynb

The notebooks are generated from the template builder:

python tools/build_example_notebooks.py

Most examples use the bundled synthetic datasets in examples/data/. If you want to regenerate those files first, run:

python examples/generate_synthetic_data.py --plot

Minimal example

Compute CTMC rates along a 1-D free-energy profile loaded from a PLUMED sum_hills output file:

from stochkin.workflows import run_1d_ctmc_from_plumed

result = run_1d_ctmc_from_plumed(
    fes_path="fes_1d.dat",
    D=0.05,          # diffusion coefficient [CV²/ps]
    T=300.0,         # temperature [K]
    time_unit="ps",
)

print("Rate matrix [1/ps]:")
print(result["K_ps"])
print("Mean exit times [ps]:", result["exit_ps"])

Key concepts

Potential callable

Every potential in stochkin is a callable with signature:

U, F = potential(x)

where x is a position vector (ndarray), U is the scalar energy, and F = −∇U is the force vector. All analytic potentials in stochkin.potentials and the FES interpolators in stochkin.fes follow this convention.

Basin network

A BasinNetwork (or its 1-D counterpart BasinNetwork1D) groups the grid into metastable basins separated by barriers. It is the input to MFPT network estimation, CTMC construction, and committor analysis.

CTMC generator

The continuous-time Markov chain (CTMC) generator \(K\) is an \(n \times n\) matrix whose off-diagonal element \(K_{ij}\) is the rate of transition from basin i to basin j, and the diagonal satisfies \(K_{ii} = -\sum_{j \neq i} K_{ij}\) so that rows sum to zero.

Uncertainty propagation

The stochkin.uncertainty module propagates credible intervals on F(s) and D(s) through the CTMC pipeline via Monte Carlo bootstrap. Each replicate perturbs the inputs (Gaussian for F, log-normal for D), re-runs the full BVP solver, and the resulting rates / exit times are collected into confidence intervals.

import stochkin as sk

res = sk.bootstrap_ctmc_1d(
    s, F, D,
    D_lo=D_lo_grid, D_hi=D_hi_grid,
    n_bootstrap=200,
    seed=42,
    T=300.0,
    time_unit="ps",
)
print(res.summary("ps"))
# Access: res.K_ps_ci_lo, res.K_ps_ci_hi, res.exit_mean_ci_lo, ...

See stochkin.uncertainty for the full API and examples/06_uncertainty.py for a complete worked example.

Dependencies

Package	Required?	Used for
NumPy	yes	arrays, linear algebra
SciPy	yes	interpolation, sparse/numerical utilities
Matplotlib	yes	plotting
tqdm	yes	progress bars
pandas	yes	CSV loading in workflows
FiPy	optional	2-D Fokker–Planck PDE solves
jupyter, ipykernel	optional	running the bundled example notebooks