stochkin.committor

Committor (splitting probability) analysis.

stochkin.committor

Committor (splitting probability) analysis.

The committor \(q(x)\) is the probability that a trajectory started at x reaches basin B before basin A. This module provides two complementary approaches:

1. Trajectory-based (shooting) committor – launch many short trajectories from each grid point and count outcomes. Works for both underdamped (Langevin) and overdamped (Brownian) dynamics. Suitable for 1D and 2D grids.

   • run_short_trajectory() – single trajectory worker.

   • committor_point() – estimate q at one point (many trials).

   • committor_map_parallel() – 2D grid committor with multiprocessing.

   • committor_profile_1d() – 1D committor profile.

2. FPE-based (grid) committor – solve the backward Fokker–Planck equation \(L q = 0\) with Dirichlet boundary conditions on a discrete grid built from a BasinNetwork.

   • committor_map_fpe() – solve for q(x, y) via sparse linear algebra.

Example basin functions (basinA(), basinB()) for the central-well / ring potential are included for quick prototyping.

stochkin.committor.run_short_trajectory(potential, x0, v0, max_time, dt, gamma, kT, basinA, basinB, m=1.0, regime='underdamped', diffusion=None, overdamped_eps=1e-06, bounds=None, boundary=None)

Run a single short trajectory and report which basin is hit first.

This is the inner workhorse of the shooting-committor algorithm. Starting from (x0, v0), the trajectory is integrated until it enters basinA (returns 'A'), basinB (returns 'B'), or max_time is exceeded (returns None).

Parameters:

• potential (callable) – potential(x) -> (U, F) with F = −∇U.

• x0 (array_like) – Initial position.

• v0 (array_like) – Initial velocity (ignored for overdamped dynamics).

• max_time (float) – Maximum simulation time.

• dt (float) – Integration time step.

• gamma (float) – Friction coefficient.

• kT (float) – Thermal energy.

• basinA (callable) – basin(x) -> bool indicating membership.

• basinB (callable) – basin(x) -> bool indicating membership.

• m (float) – Mass (default 1).

• regime ({'underdamped', 'overdamped'}) – Dynamics type.

• diffusion (scalar, callable, or None) – Diffusion coefficient for overdamped mode.

• overdamped_eps (float) – Finite-difference step for ∇D.

• bounds (sequence of (lo, hi) or None) – Bounding box for position enforcement.

• boundary ({'reflect', 'clip'} or None) – How to enforce bounds.

Returns:

'A', 'B', or None if neither basin was reached.

Return type:

str or None

stochkin.committor.committor_point(args)

Estimate the committor at a single grid point via trajectory shooting.

Runs n_trials short trajectories from (x0, v0) and returns the fraction that reach basin B first: \(q = n_B / (n_A + n_B)\). Returns NaN if no trajectory reached either basin.

Parameters:

args (tuple) –

Positional arguments packed as a tuple for compatibility with multiprocessing.Pool.map. Fields (by index):

0  potential      5  n_trials     10  m
1  x0             6  max_time     11  regime (optional)
2  v0             7  dt           12  diffusion (optional)
3  basinA         8  gamma        13  overdamped_eps (optional)
4  basinB         9  kT           14  bounds (optional)
                                  15  boundary (optional)
                                  16  seed (optional)

Returns:

Estimated committor q ∈ [0, 1] (or NaN).

Return type:

float

stochkin.committor.committor_map_parallel(potential, basinA, basinB, xlim=(-1.5, 1.5), ylim=(-1.5, 1.5), grid_size=50, n_trials=100, max_time=50.0, dt=0.01, gamma=10.0, kT=0.05, m=1.0, processes=None, regime='underdamped', diffusion=None, overdamped_eps=1e-06, bounds=None, boundary=None, base_seed=None)

Compute a 2D committor map using parallel trajectory shooting.

For each point on a grid_size × grid_size grid, n_trials short trajectories are launched and the fraction reaching basin B first is recorded.

Parameters:

• potential (callable) – potential(x) -> (U, F).

• basinA (callable) – basin(x) -> bool.

• basinB (callable) – basin(x) -> bool.

• xlim (tuple) – Grid bounds.

• ylim (tuple) – Grid bounds.

• grid_size (int) – Number of grid points per axis.

• n_trials (int) – Shooting trials per grid point.

• max_time (float) – Maximum trajectory time.

• dt (float) – Time step.

• gamma (float) – Friction.

• kT (float) – Thermal energy.

• m (float) – Mass (default 1).

• processes (int or None) – Number of worker processes (None = all CPUs).

• regime ({'underdamped', 'overdamped'}) – Dynamics type.

• diffusion (scalar, callable, or None) – Diffusion for overdamped mode.

• overdamped_eps (float) – FD step for ∇D.

• bounds (sequence of (lo, hi) or None) – Bounding box.

• boundary ({'reflect', 'clip'} or None) – Bound enforcement mode.

• base_seed (int or None) – Base seed for reproducible per-point seeds.

Returns:

• xs (ndarray) – x-axis grid.

• ys (ndarray) – y-axis grid.

• Q (ndarray, shape (grid_size, grid_size)) – Committor values q(x, y) ∈ [0, 1].

stochkin.committor.committor_profile_1d(potential, basinA, basinB, xlim=(-1.5, 1.5), grid_size=50, n_trials=100, max_time=50.0, dt=0.01, gamma=10.0, kT=0.05, m=1.0)

Compute the committor q(x) on a 1D grid via short trajectory shooting.

This is the 1D analogue of committor_map_parallel().

Parameters are the same as in committor_map_parallel(), but with a 1D grid.

Returns:

• xs ((grid_size,) ndarray) – Grid points.

• q_vals ((grid_size,) ndarray) – Committor values in [0, 1].

stochkin.committor.basinA(x, rA=0.1)

Basin A: central well around the origin.

stochkin.committor.basinB(x, r_inner=0.9, r_outer=1.0)

Basin B: circular corona (ring) between r_inner and r_outer.

stochkin.committor.committor_map_fpe(basin_network, D, beta, basinA_id, basinB_id, sparse=True, energy_buffer_kT=None)

Compute the committor q(x, y) by solving the backward FPE on a grid.

Solves \(L q = 0\) with Dirichlet conditions \(q = 0\) on basin A and \(q = 1\) on basin B, where L is the detailed-balance-preserving discrete Fokker–Planck generator built from the free-energy surface.

Parameters:

• basin_network (BasinNetwork) – Must provide xs, ys, U, and labels.

• D (float or ndarray, shape (nx, ny)) – Diffusion coefficient (scalar or field).

• beta (float) – Inverse temperature \(1/(k_BT)\).

• basinA_id (int) – Integer basin labels for the two absorbing states.

• basinB_id (int) – Integer basin labels for the two absorbing states.

• sparse (bool) – Use sparse linear algebra (default True).

• energy_buffer_kT (float or None) – If given, restrict A and B to low-energy cores within energy_buffer_kT of the basin minimum (in kT units). The remainder of each basin becomes part of the solved domain.

Returns:

• xs, ys (ndarray) – Grid coordinate arrays.

• q_grid (ndarray, shape (nx, ny)) – Committor values in [0, 1].

Raises:

ImportError – If SciPy sparse is not available.