stochkin.replicas

Parallel replica dynamics for sampling free-energy landscapes.

stochkin.replicas

Parallel replica dynamics for sampling free-energy landscapes.

This module runs M independent short simulations (“replicas”) in parallel and accumulates position- and energy-histograms. The averaged histograms approximate the canonical (Boltzmann) distribution and can be compared with the analytic free-energy surface.

All replica functions are multiprocessing-safe (top-level, picklable).

stochkin.replicas.single_replica(args)[source]

Run a single 2D replica and return position/energy histograms.

This is a top-level, picklable worker for multiprocessing.Pool.

Parameters:

args (tuple) –

Packed fields:

0. potential, 1. max_time, 2. dt, 3. gamma, 4. kT, 5. initial_position, 6. initial_velocity, 7. save_frequency, 8. bins2d, 9. binsE, 10. m, 11. pos_range, 12. energy_range, 13. regime ('underdamped' or 'overdamped'), 14. diffusion, 15. burn_in_steps, 16. bounds, 17. boundary, 18. seed.

Returns:

  • Hpos (ndarray, shape (nx, ny)) – 2D position histogram.

  • HE (ndarray, shape (binsE,)) – 1D energy histogram.

stochkin.replicas.run_replicas(potential, M=10, max_time=200, dt=0.01, gamma=10.0, kT=0.05, initial_position=(0.0, -0.7), initial_velocity=(0.0, 0.05), save_frequency=10, bins=100, m=1.0, x_range=((-2.0, 2.0), (-2.0, 2.0)), energy_range=(-2.0, 5.0), regime='underdamped', diffusion=None, processes=None, bins_energy=None, burn_in_fraction=0.0, bounds=None, boundary='reflect', base_seed=None, plot=True)[source]

Run M independent 2D replicas in parallel and average histograms.

Each replica is a short simulation (underdamped Langevin or overdamped BD) with slightly perturbed initial conditions. Histograms of position and energy are accumulated and averaged.

Parameters:

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

  • M (int) – Number of replicas.

  • max_time (float) – Integration time per replica.

  • dt (float) – Time step.

  • gamma (float) – Friction coefficient.

  • kT (float) – Thermal energy.

  • initial_position (array_like) – Nominal starting position (slightly perturbed per replica).

  • initial_velocity (array_like) – Nominal starting velocity.

  • save_frequency (int) – Steps between saved frames.

  • bins (int or (int, int)) – Histogram bins for position (nx or (nx, ny)).

  • m (float) – Mass.

  • x_range (((xmin, xmax), (ymin, ymax))) – Position histogram range.

  • energy_range ((emin, emax)) – Energy histogram range.

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

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

  • processes (int or None) – Worker processes (None or 1 = serial).

  • bins_energy (int or None) – Separate energy-histogram bin count (defaults to bins).

  • burn_in_fraction (float) – Fraction of initial trajectory to discard before histogramming.

  • bounds (sequence of (lo, hi) or None) – Domain bounds (overdamped only).

  • boundary (str) – Bound enforcement mode (default 'reflect').

  • base_seed (int or None) – Master seed for reproducibility.

  • plot (bool) – If True (default), show diagnostic position and energy plots.

Returns:

  • hist2d_avg (ndarray) – Averaged 2D position histogram.

  • histE_avg (ndarray) – Averaged 1D energy histogram.

stochkin.replicas.single_replica_1d(args)[source]

Run a single 1D replica and return position/energy histograms.

This is a top-level, picklable worker for multiprocessing.Pool.

Parameters:

args (tuple) –

Packed fields:

0. potential, 1. max_time, 2. dt, 3. gamma, 4. kT, 5. initial_position, 6. initial_velocity, 7. save_frequency, 8. bins, 9. m, 10. pos_range, 11. energy_range, 12. regime ('underdamped' or 'overdamped'), 13. diffusion.

Returns:

  • Hx (ndarray, shape (bins,)) – 1D position histogram.

  • HE (ndarray, shape (bins,)) – 1D energy histogram.

stochkin.replicas.run_replicas_1d(potential, M=10, max_time=200, dt=0.01, gamma=10.0, kT=0.05, initial_position=(0.0,), initial_velocity=(0.0,), save_frequency=10, bins=100, m=1.0, x_range=(-2.0, 2.0), energy_range=(-2.0, 5.0), plot=True, regime='underdamped', diffusion=None, processes=None)[source]

Run M independent 1D replicas in parallel and average histograms.

1D analogue of run_replicas(). Each replica is slightly perturbed in initial conditions. Position and energy histograms are averaged over all replicas.

Parameters:

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

  • M (int) – Number of replicas.

  • max_time (float) – Integration time per replica.

  • dt (float) – Time step.

  • gamma (float) – Friction.

  • kT (float) – Thermal energy.

  • initial_position (array_like) – Nominal starting position.

  • initial_velocity (array_like) – Nominal starting velocity.

  • save_frequency (int) – Steps between saved frames.

  • bins (int) – Number of histogram bins.

  • m (float) – Mass.

  • x_range ((xmin, xmax)) – Position histogram range.

  • energy_range ((emin, emax)) – Energy histogram range.

  • plot (bool) – Show diagnostic plots.

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

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

  • processes (int or None) – Worker processes (None = all CPUs).

Returns:

  • Hx_avg (ndarray) – Averaged 1D position histogram.

  • HE_avg (ndarray) – Averaged 1D energy histogram.