Stop guessing how long your simulation should run.
kim-convergence auto-detects equilibration and stops precisely when your data
is statistically reliable.
Manual estimation of simulation length is unreliable and wasteful. Different observables converge at different rates, and visual inspection can't guarantee statistical reliability. This package automates it all using proven methods like MSER-m for equilibration and adaptive confidence intervals for precision.
 |
 |
 |
 |
 |
 |
Top row: 10 ps simulation | Bottom row: 50 ps simulation
Key observations:
- Different properties (e.g., temperature, pressure, volume) converge at varying speeds.
- Visual checks alone can't ensure statistical reliability. Where running too short biases results and too long wastes resources.
kim-convergencesolves this by detecting equilibration and controlling run length based on your accuracy needs.
Jump to Quick Start or docs for theory and examples.
It is desirable to simulate the minimum amount of time necessary to reach an acceptable amount of uncertainty in the quantity of interest.
The first place you save time is by cutting the warm-up correctly.
 |
Equilibration = the transient stretch until your sim forgets its starting point.
- Cut too early -> biased averages
- Cut too late -> wasted cycles
kim-convergence runs MSER-m automatically: it scans truncation points and
picks the one that minimizes the batch-means standard error.
- Auto equilibration detection – MSER-m + autocorrelation refinement
- Adaptive run length – quits the instant every observable hits your accuracy target
- Proven CI engines – MSER-m, Heidelberger-Welch, N-SKART, uncorrelated samples
- Time-series toolkit – statistical inefficiency, autocorrelation, effective sample size, uncorrelated subsampling
- Zero-friction integration – callbacks for LAMMPS & OpenMM using one-function API for custom codes
- Multi-observable – per-variable accuracy. The run ends only when all converge
Install with one command:
pip install kim-convergence
# or:
conda install -c conda-forge kim-convergenceimport numpy as np
import kim_convergence as cr
def trajectory(nstep):
# Fake temperature data from a simulation (in K)
return np.random.normal(300, 5, nstep) # Mean 300 K, std 5 K
if __name__ == "__main__":
result = cr.run_length_control(
get_trajectory=trajectory,
relative_accuracy=0.01, # Target ±1 % precision on the mean
maximum_run_length=200_000,
fp="return",
)
print(result)That's it—head to the docs for platform notes, developer install, LAMMPS/OpenMM integration, multi-observable examples, etc.
For installation instructions, usage examples, theoretical background, best practices, troubleshooting tips, and the full API reference, see the documentation.
Bug reports, feature requests, pull requests: GitHub Issues
Guidelines: Contributing Guide
LGPL-2.1-or-later — see LICENSE.