Metadata-Version: 2.4
Name: committor-kmc
Version: 0.1.0
Summary: Variational committor, MFPT, rate-matrix, and KMC utilities for weighted trajectory data
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: matplotlib>=3.8
Requires-Dist: networkx>=3.2
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.12
Provides-Extra: notebooks
Requires-Dist: ipykernel>=6; extra == "notebooks"
Requires-Dist: nbformat>=5; extra == "notebooks"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: publish
Requires-Dist: build>=1.2; extra == "publish"
Requires-Dist: twine>=5.1; extra == "publish"

# 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:

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

For notebooks:

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

## Minimal Example

```python
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

```python
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:

```text
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:

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

Muller-Brown / double well:

```bash
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:

```text
.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:

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