Estimate the configurational entropy of a molecular system, with a Rust library, CLI, and Python bindings.
The package converts Amber trajectories to internal coordinates (bond lengths, bond angles, and torsions) and provides several entropy estimators to apply.
- Estimators: the nearest-neighbor mutual information expansion (NN MIE) up to fourth order, with pairwise mutual information; the mutual information spanning tree (MIST) and its extension to a Bayesian network; quasi-harmonic (QH) and Boltzmann quasi-harmonic (BQH) entropy; and a split estimator that treats soft torsions non-parametrically and stiff coordinates with a Gaussian. Every estimator but the joint nearest-neighbor estimate can also report each coordinate's share of the entropy.
- Validated against thermodynamic reference entropies; see Validation.
- A CLI that reads
.parm7+.nc, a Rust library, and Python bindings viapyo3for in-memory arrays or file-based calculation. - A user guide covering the CLI, Python and Rust interfaces and the methods.
- Calculations parallelized with
rayon.
- Rust 1.94 or newer.
- For Python bindings: a Python environment with build tooling for
pyo3(see below).
Prebuilt Python wheels are attached to each release; see Installation. To build from source:
cargo build --releaseFor the Python module, use maturin: maturin develop --release.
From the command line:
cargo run --release <path_to_parm7> <path_to_nc> [--torsions-only] [--no-periodic] [--exact-constant] [--start N] [--stop N] [--stride N] [--mie-order 1|2|3|4] [--theiler-window W] [--tree-bonds] [--drop-constrained] [--no-phase-angles] [--jacobian] [--estimator nn|qh|bqh|split] [--histogram-bins N] [--periodic-correlation complex|centered] [--per-coordinate] [--mutual-information] [--soft topology|detect|LIST] [--soft-estimator mie|mist|network|joint] [--network-parents N] [--hard-estimator qh|bqh|qh-mie1|qh-mie2] [--coupling gaussian|states|none] [--soft-features complex|cossin|harmonics] [--harmonics N] [--state-torsions auto|LIST] [--min-state-frames N]Example:
cargo run --release <path_to_parm7> <path_to_nc>For example, Boltzmann quasi-harmonic entropy, the most accurate estimator here:
cargo run --release system.parm7 trajectory.nc --estimator bqhFrom Python:
import molentropy
system = molentropy.load_system("system.parm7", "trajectory.nc")
entropy = system.estimate_quasi_harmonic_entropy()["boltzmann_quasi_harmonic"]The user guide documents every option, the Python and Rust interfaces, and the methods.
Results are differential entropies of the internal coordinates in units of k_B, meaningful as differences between ensembles of the same molecule, not absolute thermodynamic entropies; see Interpretation and limitations.
On the butane end states of an alchemical transformation, BQH with phase angles agrees with thermodynamic integration within the reference's uncertainty. The validation page has the results for every estimator and an example program that reproduces them.
The user guide is an mdBook in docs/, published at https://helmutcarter.github.io/molentropy/ from the main branch. To read it locally, run mdbook serve docs. The Rust API documentation is built with cargo doc --no-deps --open.
See CONTRIBUTING.md for the test suite, CI, and the layout of the code.
If you use molentropy in published work, please cite the release you used. Major releases will eventually be archived on Zenodo with their own DOIs; CITATION.cff has the citation metadata, and GitHub's "Cite this repository" button formats it. Changes between releases are listed in CHANGELOG.md.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.