committor-kmc 0.1.0

Variational committor, MFPT, rate-matrix, and KMC utilities for weighted trajectory data

committor-kmc

committor-kmc is a small Python library for estimating committors, MFPTs, rate matrices, and kinetic Monte Carlo trajectories from weighted trajectory data in collective-variable space.

The core workflow is:

1. load weighted trajectory segments;
2. estimate a local Kramers-Moyal diffusion tensor from short increments;
3. build a variational Dirichlet form in a chosen basis;
4. solve committor and MFPT boundary-value problems;
5. assemble a CTMC rate matrix and run KMC/TPT diagnostics.

Install

Editable install from this repository:

cd committor_kmc
python -m pip install -e ".[test]"

For notebooks:

python -m pip install -e ".[notebooks,test]"

Minimal Example

import numpy as np
from committor_kmc import (
    BoxState,
    CosineTensorBasis,
    build_dirichlet_model,
    empirical_quadrature,
    estimate_binned_diffusion,
    load_lineage_dat_segments,
    solve_committor,
    transition_pairs,
)

domain = np.array([[-2.0, 2.0], [-1.5, 2.5]])
segments = load_lineage_dat_segments(
    ["lineage_0.dat", "lineage_1.dat", "lineage_2.dat", "lineage_3.dat"]
)
pairs = transition_pairs(segments, lag_steps=1, domain=domain)
diffusion = estimate_binned_diffusion(
    pairs,
    frame_interval=1.0,
    bins=(64, 64),
    domain=domain,
)
quad_points, quad_weights = empirical_quadrature(pairs, size=100_000, seed=0)
basis = CosineTensorBasis(domain, (12, 10))
model = build_dirichlet_model(quad_points, quad_weights, basis, diffusion)

A = BoxState([-1.2, -0.2], [-0.8, 0.2], name="A")
B = BoxState([-0.1, 1.4], [0.1, 1.6], name="B")
q = solve_committor(model, basis, A, B)
values = q.evaluate(basis, quad_points)

KMC Example

import numpy as np
from committor_kmc import (
    gillespie,
    mfpt_matrix,
    sample_first_passage_times,
    stationary_distribution,
    tpt_reactive_flux,
)

K = np.array([
    [-0.21, 0.10, 0.11],
    [0.41, -0.81, 0.40],
    [0.11, 0.10, -0.21],
])

pi = stationary_distribution(K)
tau = mfpt_matrix(K)
trajectory = gillespie(K, start_state=0, t_max=50_000, rng=np.random.default_rng(0))
fpts = sample_first_passage_times(K, 0, 1, n_samples=20_000)
tpt = tpt_reactive_flux(K, pi, source_state=0, sink_state=1)

The diagonal entries of K are negative by construction:

K[i, i] = -sum(K[i, j] for j != i)

Only off-diagonal entries are physical transition rates.

Repository Layout

• src/committor_kmc/: reusable package code.
• scripts/alanine_dipeptide/: final alanine dipeptide analysis scripts.
• scripts/double_well/: final Muller-Brown/double-well analysis and KMC scripts.
• notebooks/: example notebooks.
• tests/: package tests.
• docs/: extended usage notes.

Large trajectory inputs and generated paper figures are kept outside the PyPI package.

Final Analysis Scripts

Alanine dipeptide:

python scripts/alanine_dipeptide/compute_committor.py
python scripts/alanine_dipeptide/compute_rates.py

Muller-Brown / double well:

python scripts/double_well/compute_committor.py
python scripts/double_well/compute_rates.py
python scripts/double_well/run_kmc.py

The rate scripts produce rate matrices and summaries. The double-well KMC script uses the learned calibrated rate matrix produced by compute_rates.py.

Publishing

Publishing is handled by GitHub Actions:

.github/workflows/publish-pypi.yml

On every push to main, the workflow:

1. installs the package with test dependencies;
2. runs pytest;
3. builds the source distribution and wheel;
4. checks the distributions with Twine;
5. publishes to PyPI via trusted publishing.

Configure PyPI trusted publishing for this repository and the pypi environment in GitHub. PyPI does not allow re-uploading the same version, so bump version in pyproject.toml before merging a new release to main.

For a local build/check without publishing:

python -m pip install -e ".[publish,test]"
python -m pytest
python -m build
python -m twine check dist/*