molentropy
molentropy estimates the configurational entropy of a molecule from a molecular dynamics trajectory. It reads Amber topologies (.parm7) and NetCDF trajectories (.nc), converts every frame to internal coordinates (bond lengths, bond angles and torsions), and estimates the entropy of those coordinates. The same estimators are available from the command line, from Python and as a Rust library.
Choosing an estimator
- Boltzmann quasi-harmonic (BQH) takes each coordinate's own entropy from its actual distribution and adds a Gaussian estimate of the correlations between coordinates. It is the most accurate estimator in the crate on the systems tested so far; see Validation. Use it unless you have a reason not to:
--estimator bqh. - The nearest-neighbor mutual information expansion (NN MIE) combines nearest-neighbor entropies of single coordinates and of pairs (up to sets of four). It makes no assumption about the shape of any distribution, but the sum of many pairwise terms is noisy. It is the CLI's default estimator. See Nearest-neighbor MIE.
- The split estimator treats soft torsions (those about rotatable bonds) non-parametrically and the stiff coordinates with a Gaussian, plus a coupling term. It is meant for molecules with several coupled rotatable bonds:
--estimator split. See Split estimator. - Quasi-harmonic (QH) fits a Gaussian to every coordinate. It is fast but overestimates the entropy of multiwell torsions. See Quasi-harmonic estimators.
Every estimator returns a differential entropy in natural-log units (units of k_B) of the internal coordinates as sampled. It does not include the BAT Jacobian, momentum, or a standard state, so it is meaningful as a difference between ensembles of the same molecule rather than as an absolute thermodynamic entropy. See Interpretation and limitations.
Installation
Python wheels from a release
Each release has prebuilt wheels for Python 3.10 to 3.14 (3.10 to 3.12 for v0.1.0) on Linux (x86_64, aarch64), macOS (arm64, x86_64) and Windows (x86_64). pip can pick the right one from the release page:
pip install molentropy --find-links https://github.com/helmutcarter/molentropy/releases/expanded_assets/v0.1.1
or download the wheel for your Python and platform and pip install the file.
No Rust toolchain is needed. Building from source, below, gives the command-line program as well.
Building from source
Requirements
- Rust 1.94 or newer.
- For Python bindings: a Python environment with build tooling for
pyo3(see below).
Command line and Rust library
cargo build --release
The program is then at target/release/molentropy, or run it through cargo as cargo run --release <path_to_parm7> <path_to_nc>.
Python bindings
The Python module is built with maturin:
maturin develop --release # into the active environment
maturin build --release --out dist # or as a wheel
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>
Options
- For most molecules
--estimator bqhis the most accurate choice; see Validation. The default estimator is the NN MIE. --torsions-onlydrops the bonds and angles and estimates the entropy of the torsions alone.--stoplimits the number of frames read to N.--startskips the first N frames.--strideretains every Nth frame after--start(default: 1). Choose a stride based on a separate correlation-time analysis; the crate does not estimate an effective sample size automatically.--mie-orderselects the expansion order of the NN MIE. The default is 2.--no-periodicforces every coordinate to use an ordinary linear metric. This produces a significant speedup, but the torsion entropy contribution loses some correctness.--theiler-window Wexcludes temporally adjacent frames from the nearest-neighbor search: frame i's neighbor must satisfy |i - j| > W, counted in frames after--startand--stride. The default, 0, is the plain estimator. See Correlated frames.--exact-constantuses the exact finite-sample termpsi(N) - psi(1) = H_(N-1). The default is the common approximationln(N) + EulerGamma.--tree-bondsuses the bonds of the BAT spanning tree, including bonds to hydrogen and excluding ring closures, in place of every heavy-atom bond. Use it only for trajectories without constrained bonds to hydrogen, or with--drop-constrained; see Choosing the bond set.--drop-constraineddrops every bond and angle the trajectory shows to be constrained (relative standard deviation below 10⁻³ over the frames read) and printsConstrained coordinates dropped = Nfirst. With the default bonds, bonds to hydrogen are then kept unless constrained; with--tree-bonds, the constrained tree bonds go but still count in--jacobian. See Constrained coordinates.--no-phase-anglesuses the raw torsions. By default each torsion that shares its central bond with an earlier torsion is replaced by its offset from that torsion. See Coordinate sets.--jacobianalso printsMean ln J = ..., the mean of the log BAT Jacobian over the frames used, on the line before the entropy. It requires--tree-bondsand cannot be combined with--torsions-only.- With
--estimator qhorbqh, two lines before the total give the terms it is the sum of:First-order entropy = ...andCorrelation term = .... --estimatorchooses the estimator:nn(the default) is the nearest-neighbor MIE,qhis quasi-harmonic,bqhis Boltzmann quasi-harmonic, andsplittreats soft torsions non-parametrically and the rest with a Gaussian (see Split estimator). See Quasi-harmonic estimators.--mie-orderapplies only tonn.--histogram-bins Nmakesbqhestimate each coordinate's first-order entropy from an N-bin histogram instead of nearest neighbors.--per-coordinatealso prints a tab-separated table of each coordinate's share of the entropy before the total: its number, type (bond,angle,torsionorphase angle), atoms (numbered from 1, as in Amber and cpptraj), and entropy. The shares sum to the total. It works with--estimator nnat every--mie-order; withqhandbqh, for which the table has two more columns,first_orderandcorrelation, the two terms each coordinate's entropy is the sum of; and withsplit, for which it hasset(softorhard),ownandcoupling. It cannot be combined with--soft-estimator joint. See Per-coordinate entropies.--mutual-informationalso prints a tab-separated table of the mutual information of every pair of coordinates, numbered as in--per-coordinate. It applies only to--estimator nn.- With
--estimator split:--soft topology|detect|LISTchooses the soft coordinates (defaulttopology; LIST counts from 1),--soft-estimator mie|mist|network|joint(with--network-parents N, default 5, fornetwork) and--hard-estimator qh|bqh|qh-mie1|qh-mie2the estimators for each set,--coupling gaussian|states|nonethe coupling term,--soft-features complex|cossin|harmonicsand--harmonics Nhow soft torsions enter the Gaussian coupling (default: 3 harmonics), and--state-torsions auto|LISTand--min-state-frames Nthe states of the per-state coupling.--mie-order,--histogram-binsand--periodic-correlationapply to the matching part. The output lists the soft coordinates, the states, andSoft entropy,Hard entropyandCoupling termbefore the total. See Split estimator. --periodic-correlation complex|centeredsets how torsions enter the quasi-harmonic correlation term;complex, the default forqhandbqh, is Harpole and Sharp'se^{iφ};centeredis the default for the hard set ofsplit. See Quasi-harmonic estimators.
Python
Functions
The molentropy module provides:
load_system(top_path, traj_path, start=None, stop=None, torsions_only=None, stride=None, tree_bonds=False, phase_angles=True, drop_constrained=False). See Coordinates.estimate_entropy(data_or_system, mie_order=None, periods=None, periodic=True, exact_constant=False, theiler_window=0).mie_orderdefaults to 2;mie_order=1gives the sum of the marginal entropies.estimate_coordinate_entropy(data_or_system, mie_order=None, periods=None, periodic=True, exact_constant=False, theiler_window=0). Returns each coordinate's share of the entropy;mie_orderdefaults to 2. The values sum toestimate_entropyat the same order. See Per-coordinate entropies.estimate_coordinate_mutual_information(data_or_system, periods=None, periodic=True, exact_constant=False, theiler_window=0). Returns the mutual information of each coordinate pair.estimate_quasi_harmonic_entropy(data_or_system, periods=None, periodic=True, histogram_bins=None, periodic_correlation="complex", exact_constant=False, theiler_window=0). Returns a dict withquasi_harmonic,boltzmann_quasi_harmonic,first_order_gaussian,first_order_boltzmannandcorrelation. See Quasi-harmonic estimators.estimate_coordinate_quasi_harmonic_entropy(data_or_system, periods=None, periodic=True, histogram_bins=None, periodic_correlation="complex", exact_constant=False, theiler_window=0). Each coordinate's share of the QH and BQH entropy: a dict with the same keys, each a list with one value per coordinate that sums to the matching total. See Quasi-harmonic estimators.estimate_split_entropy(data_or_system, soft=None, soft_estimator="mie", mie_order=2, hard_estimator="qh", coupling="gaussian", soft_features="harmonics", harmonics=None, state_coordinates=None, state_labels=None, min_state_frames=300, histogram_bins=None, periodic_correlation="centered", periods=None, periodic=True, exact_constant=False, theiler_window=0, per_coordinate=False, network_parents=5). Returns a dict withtotal,soft,hard,coupling,soft_coordinates,hard_coordinates,basin_countsandstates; withper_coordinate=True, alsocoordinates, a dict of liststotal,ownandcouplingwith one value per coordinate (see Per-coordinate entropies).softisNone,"topology","detect"or a list of coordinate indices from 0;Nonemeans"topology"for aSystemand"detect"for an array.soft_estimatoris"mie","mist","network"(withnetwork_parentsparents per coordinate) or"joint";hard_estimatoris"qh","bqh","qh-mie1"or"qh-mie2";soft_featuresis"harmonics"(3 unlessharmonicssays otherwise),"cossin"or"complex". See Split estimator.detect_basins(values, period=2π, bins=72, smoothing=2.0, saddle_fraction=0.5, min_population=0.02, free_rotor_resultant=0.3). Returns a dict withcount,labels,boundaries,populations,resultantandsoft.Systemhas the same six estimators as methods, each takingperiodic,exact_constantandtheiler_window(andmie_orderfor the two MIE entropy estimators,histogram_binsandperiodic_correlationfor the quasi-harmonic ones). Itssoft_torsions,symmetric_rotor_torsionsandring_torsionsproperties give the split estimator's topological classes. Itsinternal_coordinatesproperty holds the coordinate values of the selected frames as a list of lists, one per coordinate (np.array(system.internal_coordinates)has shape coordinates × frames), andperiodsgives each coordinate's period, orNonefor a linear one. Itsatoms,kindsandphase_referencesproperties describe the coordinates, in the order of every per-coordinate result: the topology atom indices of each (counted from 0), its kind ("bond","angle","torsion"or"phase angle"), and for a phase angle the index of its reference torsion, otherwiseNone. Itsconstrained_atomsproperty lists the atoms of each bond and angle dropped bydrop_constrained=True(empty otherwise). Itsmean_log_jacobianproperty is the mean log BAT Jacobian over the selected frames. It raisesValueErrorunless the system was loaded withtree_bonds=Trueand withouttorsions_only.- To start from an Amber topology and trajectory, call
load_system(...)once and use theSystemmethods or pass theSystemto any estimator. The coordinate metrics come from the generated BAT coordinates automatically, and the trajectory is only read once no matter how many quantities you compute.
exact_constant=True uses the exact finite-sample term, like the CLI's --exact-constant, and theiler_window matches the CLI's --theiler-window. periodic=False measures every coordinate linearly for that calculation, like the CLI's --no-periodic; a System keeps its own periods. For a raw array it cannot be combined with periods.
For a raw array, periods is a sequence with one entry per coordinate. Use None for a linear dimension and a positive period for a periodic dimension. Omitting periods preserves the linear behavior of the original raw-array API.
Example
import molentropy
system = molentropy.load_system("system.parm7", "trajectory.nc")
bqh = system.estimate_quasi_harmonic_entropy()["boltzmann_quasi_harmonic"]
entropy = molentropy.estimate_entropy(system, mie_order=2) # NN MIE
coordinate_entropy = system.estimate_coordinate_entropy() # order 2, sums to `entropy`
marginal_entropy = system.estimate_coordinate_entropy(mie_order=1)
See Installation for building the module.
Threads
- The Python wrappers release the GIL while loading trajectories and running entropy calculations, so multiple Python threads can call into
molentropyconcurrently. - Internal parallelism is handled in Rust with Rayon. Set
RAYON_NUM_THREADS=Nif you want to cap or tune the Rust worker pool.
Rust
The crate is not on crates.io; depend on a release tag through git, so the estimates do not change under you:
[dependencies]
molentropy = { git = "https://github.com/helmutcarter/molentropy", tag = "v0.1.1" }
Every public item has API documentation, with examples that are compiled and tested:
cargo doc --no-deps --open
Overview
#![allow(unused)] fn main() { use molentropy::{CoordinateMetric, EntropyOptions, FiniteSampleConstant, calculate_entropy}; // one_d_data is Vec<Vec<f64>> with shape [n_coords][n_frames] let entropy = calculate_entropy(&one_d_data, frames_end, 2, &EntropyOptions::default())?; // Periodic torsions and the exact finite-sample constant let options = EntropyOptions { metrics: Some(&metrics), // one CoordinateMetric per coordinate constant: FiniteSampleConstant::Exact, ..Default::default() }; let entropy = calculate_entropy(&one_d_data, frames_end, 2, &options)?; }
The NN MIE functions all take an EntropyOptions, described under Nearest-neighbor MIE:
calculate_entropy(data, frames_end, mie_order, &options)returns the total entropy at MIE order 1, 2, 3 or 4.estimate_coordinate_entropy(data, frames_end, mie_order, &options)returns each coordinate's share of the entropy at MIE order 1 to 4, so the values sum tocalculate_entropyat the same order and with the same options. Order 1 gives the marginal entropies; higher orders split each interaction term evenly among its coordinates. See Per-coordinate entropies.estimate_coordinate_mutual_information(data, frames_end, &options)returns the mutual information of each coordinate pair.estimate_mist_entropy(data, frames_end, &options)returns the mutual information spanning tree (MIST) entropy; see NN MIE.estimate_coordinate_mist_entropytakes the same arguments and returns each coordinate's share.estimate_network_entropy(data, frames_end, parents, &options)returns the Bayesian network entropy, MIST with up toparents(1 to 7;DEFAULT_NETWORK_PARENTSis 5) parents per coordinate; see NN MIE.estimate_coordinate_network_entropytakes the same arguments and returns each coordinate's share.calc_joint_nn([&x, &y, ...], metrics)is the underlying nearest-neighbor sum,sum over frames of ln(nearest-neighbor distance), in any number of dimensions; the MIE uses 1 to 4.calc_joint_nn_with_window(coordinates, metrics, w)is the same sum with a Theiler window.
To build coordinates from files, use bat_library::InternalCoordinates:
#![allow(unused)] fn main() { use molentropy::bat_library::{BondSet, CoordinateOptions, InternalCoordinates}; let options = CoordinateOptions { bonds: BondSet::Tree, ..Default::default() }; // phase angles by default let mut internal = InternalCoordinates::with_options(&top, options)?; // ::new(&top) for the defaults internal.calculate_internal_coords(&traj, usize::MAX, false)?; let metrics = internal.coordinate_metrics(); // one per coordinate let atoms = internal.coordinate_atoms(); // topology atom indices of each coordinate let references = internal.phase_references(); // Some(i) for a phase angle of torsion i let log_jacobian = internal.log_jacobian()?; // per frame; tree bonds only }
internal.int_coords holds the values with shape [n_frames][n_coords]. The estimators take [n_coords][n_frames], which internal.columns(start, stride) returns for the frames start, start + stride, ..., the same selection as the CLI's --start and --stride. internal.coordinate_kinds() gives each coordinate's kind (Bond, Angle, Torsion, or PhaseAngle { reference }).
The quasi-harmonic estimators take the same data and options, plus their own settings:
#![allow(unused)] fn main() { use molentropy::quasi_harmonic::{ MarginalEstimator, PeriodicCorrelation, QuasiHarmonicOptions, estimate_quasi_harmonic_entropy, }; let quasi_harmonic = QuasiHarmonicOptions::default(); // NN marginals, complex torsions // or QuasiHarmonicOptions { marginals: MarginalEstimator::Histogram { bins: 100 }, periodic: PeriodicCorrelation::Centered } let entropy = estimate_quasi_harmonic_entropy(&one_d_data, frames_end, &quasi_harmonic, &options)?; println!("QH {} BQH {}", entropy.quasi_harmonic, entropy.boltzmann_quasi_harmonic); }
The result also carries the terms the totals are built from: first_order_gaussian, first_order_boltzmann and correlation. estimate_coordinate_quasi_harmonic_entropy takes the same arguments and returns each coordinate's share of every one of them.
The split estimator takes the soft set from the coordinates' topology:
#![allow(unused)] fn main() { use molentropy::split::{SoftSelection, SplitOptions, estimate_split_entropy}; let soft = internal.soft_torsions(); // primary torsions about rotatable bonds let split = SplitOptions::new(SoftSelection::Indices(&soft)); // validated defaults let result = estimate_split_entropy(&data, frames, &split, &options)?; println!("{} = {} + {} + {}", result.total, result.soft, result.hard, result.coupling); }
SoftSelection::Detect finds soft coordinates from their basins (basins::detect_basins), and estimate_joint_entropy gives a joint nearest-neighbor estimate over up to 8 coordinates. estimate_coordinate_split_entropy takes the same arguments and returns each coordinate's own and coupling shares and their total, with the split they divide.
Coordinates
By default, file-based calculations use every bond between two heavy atoms (ring closures included), plus the BAT tree's angles and torsions, with phase angles in place of redundant torsions. Bonds to hydrogen are left out because they are usually constrained.
Tree bonds (--tree-bonds, tree_bonds=True, BondSet::Tree) use the bonds of the BAT spanning tree: the two root bonds and the bond that places each later atom, with hydrogens included and ring closures left out. Together with the angles and torsions, this gives exactly 3N - 6 non-redundant coordinates per molecule (one bond for a diatomic, including one with hydrogen). This is the coordinate set the BAT Jacobian is defined for. With constrained bonds to hydrogen, keep the default; see Choosing the bond set.
Phase angles (on by default; --no-phase-angles, phase_angles=False or CoordinateOptions::phase_angles turn them off) group the torsions by central bond. The first torsion about each bond, in coordinate order, keeps its value. Every later torsion about that bond is replaced by its offset from the first one, wrapped to (-π, π]. The offset is still a 2π-periodic coordinate. Because the map is a shear with unit Jacobian, the joint entropy of the full coordinate set is unchanged. A truncated MIE is not invariant, though. The raw torsions of atoms that rotate together, such as the three hydrogens of a methyl group, are strongly correlated, and a second-order expansion misses part of that correlation. Their offsets are stiff and nearly independent of the reference torsion, so less correlation is left beyond second order. Every estimator in the crate does better with them; see Validation. Phase angles work with either bond set and with --torsions-only.
The BAT Jacobian (--jacobian, System.mean_log_jacobian, InternalCoordinates::log_jacobian) is ln J = Σ 2 ln b + Σ ln sin θ over the tree's bonds and angles. Adding its mean to the BAT entropy gives the entropy of the internal motion measured in Cartesian coordinates. Bond lengths are in the trajectory's units (Å for Amber), so ln J depends on that choice, just as the bond-length entropies do. Phase angles do not change it.
Choosing the bond set
Keep the default heavy-atom bonds for trajectories with constrained bonds to hydrogen (SHAKE, RATTLE, LINCS), which most production simulations use. Use tree bonds only for unconstrained simulations, or to compute the Jacobian.
A constrained bond does not fluctuate, so as a coordinate it contributes only the noise of the constraint solver and of the stored precision. That noise differs between ensembles, so it does not cancel in a difference. Tree bonds add one such coordinate per hydrogen. On the 23 small molecules and alanine dipeptide of the validation, all run with X-H bonds constrained, tree bonds made every estimator worse. The table gives the RMS error in S0 − S1 against the HREX/MBAR references (nats, means of three replicates, the Jacobian included in both):
| estimator | heavy-atom bonds | tree bonds | systems where tree bonds did better |
|---|---|---|---|
| split (default) | 0.37 | 2.00 | 7 of 23 |
| split, MIST | 0.69 | 2.14 | 8 of 23 |
| BQH | 1.78 | 3.35 | 9 of 23 |
The largest changes were in the alkanes, whose hydrogens make up most of the extra coordinates. For hexane, the split estimator's error went from +0.12 to −7.7 nats and BQH's from +0.06 to +10.7. For butane, the split estimator's went from +0.08 to −3.8. Without butane and hexane, the split estimator's RMS error was still 0.39 with heavy-atom bonds against 0.92 with tree bonds.
The Jacobian is defined only for the tree set, so --jacobian and mean_log_jacobian need tree bonds. With constraints, compute the entropy with the default bonds and take the Jacobian from a second load with tree bonds. The constrained bonds' 2 ln b terms are then constant and cancel in a difference between ensembles. With --drop-constrained, one run does both: see below.
Constrained coordinates
--drop-constrained (drop_constrained=True in load_system, CoordinateOptions::drop_constrained) finds the constrained coordinates from the trajectory instead of assuming them from the atom types. A bond or angle is dropped when its standard deviation over the frames read is below 10⁻³ of its mean (CONSTRAINT_TOLERANCE). Torsions are never dropped. The two kinds are far apart: constrained bonds to hydrogen spread by at most about 10⁻⁵ of their length (Amber SHAKE, OpenMM constraints, single-precision trajectories), and free bonds and angles by about 2 × 10⁻² at 300 K, which scales with √T.
- Default bonds: bonds to hydrogen are included and kept unless constrained. A SHAKE trajectory gives exactly the default set; an unconstrained one keeps its X-H bonds.
- Tree bonds: the constrained tree bonds are dropped, and their 2 ln b terms still enter ln J, so
--tree-bonds --drop-constrained --jacobiangives the default-bond entropy and the full Jacobian in one run. - Angles: SHAKE on bonds to hydrogen leaves every angle free; H-X-H angles fluctuate as much as heavy-atom ones. An angle is dropped only if it really is fixed, for example when all three distances of a triangle are constrained.
The CLI prints the number dropped; System.constrained_atoms and InternalCoordinates::constrained_coordinates list their atoms. On butane (Amber, SHAKE) and alanine dipeptide (OpenMM, constrained X-H bonds), it dropped the 10 and 12 bonds to hydrogen and nothing else, and both the entropy and the mean ln J matched the two separate runs.
Rotatable, ring and rotor torsions
Each torsion is also classified by the bond it turns about, for the split estimator:
- Soft torsions (
soft_torsions): the primary torsion about each bond that is not on a ring. With phase angles these are the coordinates of typetorsionoff rings. - Symmetric rotor torsions (
symmetric_rotor_torsions): soft torsions about a bond one end of which carries only two or more terminal atoms of one element, as in CH3, NH3+ and CF3. Their basins are equivalent. - Ring torsions (
ring_torsions): torsions about a bond that lies on a ring, found as the bonds that are not bridges of the molecule's bond graph.
In Rust these are methods of InternalCoordinates; in Python, properties of a System. They depend only on the topology, and --torsions-only keeps them.
Which atoms are used
- File-based calculations select the solute automatically. Water is excluded when its atom type is an Amber water type (
OW,HW,EP,EPW) or its residue is a water name (WAT,HOH,SOL,TIP3,SPCE,OPC, and similar), so four-point models and non-Amber water types are handled. Massless virtual sites are excluded because they carry no degrees of freedom. Monatomic species such as counter-ions contribute nothing, since they have no internal coordinates, and a diatomic contributes only its bond length (with the default bond set, only when both atoms are heavy). Solute atoms may appear anywhere in the topology. - The trajectory must have exactly as many atoms as the topology. A stripped topology paired with a solvated trajectory is rejected rather than read on the assumption that atoms line up.
Nearest-neighbor MIE
The nearest-neighbor estimator of Kozachenko and Leonenko estimates the entropy of a set of coordinates from the distance from each frame to its nearest neighbor among the other frames. The mutual information expansion (MIE) combines such estimates for single coordinates, pairs, and optionally triples and quadruples into an estimate for the whole molecule: order 1 is the sum of the single-coordinate entropies, order 2 also subtracts the mutual information of every pair, and so on. Select the order with --mie-order (default 2), mie_order= in Python, or the mie_order argument in Rust.
Periodic coordinates use the distance around the circle. --no-periodic treats every coordinate as linear, which is faster but loses some correctness for torsions.
Options
In Rust these are the fields of EntropyOptions. The CLI and Python have matching settings: --exact-constant or exact_constant=True, and --theiler-window or theiler_window=. For file-based calculations the metrics come from the coordinates; for a raw array in Python, pass periods=.
metrics: per-coordinateCoordinateMetric::LinearorCoordinateMetric::Periodic { period }. The default,None, treats every coordinate as linear.constant:FiniteSampleConstant::Asymptotic(the default) orFiniteSampleConstant::Exact.theiler_window: frames j with |i - j| <=theiler_windoware never frame i's nearest neighbor. The default, 0, excludes only frame i itself.
Joint estimate
The MIE builds the entropy from estimates in one to four dimensions. A single nearest-neighbor estimate over a whole set of coordinates is also available, with no expansion: estimate_joint_entropy in Rust, for up to 8 coordinates (MAX_JOINT_DIMENSION), and the split estimator's --soft-estimator joint. It has no truncation error, but its bias grows quickly with the number of coordinates, so it suits small sets such as the soft torsions of a ligand. On a periodic box the nearest-neighbor search skips the periodic images that cannot hold a closer neighbor, which keeps it fast in higher dimensions.
The mutual information spanning tree (MIST; King, Killian and Tidor, J. Phys. Chem. B 116, 2891, 2012) uses the same one- and two-dimensional terms as MIE-2, but keeps only the pairwise mutual information along the maximum spanning tree of the coordinates: the sum of the marginal entropies minus one mutual information per coordinate after the first. With exact terms it is an upper bound on the joint entropy. MIE-2 subtracts every pair, so when many coordinates are coupled, as in a folded chain, it can count the same dependence several times and fall far below the joint entropy. MIST cannot. It is estimate_mist_entropy in Rust and the split estimator's --soft-estimator mist.
A tree of pairs still misses dependence among three or more coordinates, such as the backbone and side-chain torsions of a structured peptide moving together. The Bayesian network estimator extends MIST by the chain rule: it takes the coordinates in the order the spanning tree adds them and conditions each on up to p earlier ones (its parents), H = H(X1) + Σ H(Xi | parents of Xi). Each coordinate's first parent is its tree link, so with p = 1 it is MIST. Further parents are added greedily from the 10 earlier coordinates of highest pairwise mutual information with it, each time the one that lowers the conditional entropy most, while any does. The conditional entropies are differences of joint nearest-neighbor entropies of up to p + 1 coordinates, so p is at most 7. With exact terms it is still an upper bound on the joint entropy, and never above MIST. It is estimate_network_entropy(data, frames_end, parents, &options) in Rust and the split estimator's --soft-estimator network (--network-parents, default 5). On peptides it roughly halves MIST's error; see Validation.
Notes
- The default second-order mutual-information expansion is a truncation and can omit higher-order correlations.
- Following the historical Python implementation, the default nearest-neighbor constant uses the large-sample approximation
ln(N) + EulerGammain place of the exact finite-sample termpsi(N) - psi(1) = H_(N-1). Their per-entropy difference is approximately1/(2N)and is negligible for the intended 50,000-frame calculations, but it can accumulate across MIE terms or become important for very small samples. The convention is a property of the estimator, not of the total alone: pairwise mutual information shifts by exactlyH_(N-1) - (ln(N) + EulerGamma)per pair when it changes, so per-coordinate results must be computed under the same convention as the total they are compared against. The Python implementation truncated EulerGamma to0.57721566490153; this crate uses the full double-precision value, so results can differ from it by roughly 1e-14. - Exact duplicate samples use the nearest distinct coordinate point. Many ties usually indicate inadequate coordinate precision or sampling and should be investigated.
For correlated frames, see Correlated frames.
Quasi-harmonic estimators
Both quasi-harmonic estimators describe correlations with the correlation matrix C of the coordinates, C_ij = σ_ij / √(σ_ii σ_jj), which contributes ½ ln|C| ≤ 0. They differ in the first-order term:
- QH (
--estimator qh, Karplus and Kushick 1981) fits a Gaussian to each coordinate:S = Σ ½ ln(2πe σ_ii) + ½ ln|C|, which is½ ln((2πe)^n |σ|)when no coordinate is periodic. - BQH (
--estimator bqh, Harpole and Sharp, J. Phys. Chem. B 2011) keeps the correlation term but takes each coordinate's first-order entropy,-∫ p ln p, from its actual distribution, so multimodal coordinates are not treated as one wide well.
The BQH first-order term uses the one-dimensional nearest-neighbor estimate by default, the same first-order term as the MIE, so BQH and the NN MIE differ only in how they treat correlations; --exact-constant and --theiler-window apply to it. --histogram-bins N uses N equal bins instead: linear coordinates are binned over their observed range, periodic ones over a full period. The histogram gives the differential entropy -Σ p_k ln(p_k / Δ), Harpole and Sharp's eq 9, comparable with the other estimators. Some later BQH work reports the discrete -Σ p_k ln p_k, which is this value minus ln Δ per coordinate, a difference that cancels in entropy changes computed with the same bins. Harpole and Sharp choose bins by width (3-5° for angles, 0.1 Å for lengths) rather than by count. All values are differential entropies in k_B, like the nearest-neighbor results.
The covariance is the population covariance over the selected frames, so there must be more frames than coordinates, and no coordinate can be a linear combination of others.
Torsions. By default (--periodic-correlation complex), each periodic coordinate enters the correlation matrix as z = e^{iφ} (for period P, e^{2πiq/P}), following Harpole and Sharp, which makes C Hermitian; C_ij = ⟨δa_i δa_j*⟩ / √(⟨|δa_i|²⟩⟨|δa_j|²⟩) with δa = a - ⟨a⟩, and linear coordinates stay real. This captures correlations on the circle whatever the angles' spread, such as the fixed 120° offsets between the three hydrogen torsions of a rotating methyl group. The first-order Gaussian term of QH uses each torsion's variance after rotating its circular mean to 0 and wrapping to (-π, π].
--periodic-correlation centered puts the centered and wrapped torsions into C as real coordinates instead. That is adequate for torsions confined to one narrow well, where both treatments agree, but a correlation between torsions that sweep the circle looks like a weak sawtooth after wrapping and is largely missed.
Per-coordinate entropies
--per-coordinate, estimate_coordinate_quasi_harmonic_entropy in Python and Rust, gives each coordinate's share of the QH and BQH entropy. The first-order terms belong to single coordinates already. The correlation term ½ ln|C| belongs to the whole set and is shared out using ln|C| = tr(log C): coordinate i receives ½ (log C)_ii, computed from the eigendecomposition of C. The shares
- sum to the correlation term exactly,
- do not depend on the order of the coordinates,
- are each at most 0, because C has a unit diagonal, and are about 0 for a coordinate independent of the others,
- split the correlation of two coordinates evenly: each receives
¼ ln(1 - |ρ|²).
Like the NN MIE's even split of pairwise mutual information, this is one convention for dividing a quantity that belongs to the whole set; its advantage is that it involves no further choices, such as an ordering of the coordinates. Per-coordinate entropies compares the conventions of every estimator.
The split estimator combines both approaches: QH or BQH for the stiff coordinates, a nearest-neighbor estimate for the soft torsions, and the Gaussian correlation term of this page for the coupling between them.
See Validation for how the estimators compare with thermodynamic reference values.
Split estimator
Multi-basin torsions are poorly described by a Gaussian, while bonds, angles and phase angles are close to harmonic, and a Gaussian captures all of their correlations at once. The split estimator (--estimator split, estimate_split_entropy) uses each where it fits. It divides the coordinates into a soft set S and a hard set H and writes
S = Ssoft + Shard + coupling
- Ssoft: the nearest-neighbor MIE over the soft coordinates (
--soft-estimator mie, the default;--mie-ordersets the order), the mutual information spanning tree (mist), MIST extended to several parents per coordinate (network;--network-parentssets how many, default 5; see NN MIE), or one joint nearest-neighbor estimate over all of them (joint, up to 8 soft coordinates). MIST uses the same single and pairwise nearest-neighbor entropies as MIE-2, but subtracts only the pairwise mutual information along the maximum spanning tree of the soft coordinates: one dependence per coordinate, the strongest that keeps the tree connected. With exact terms it is an upper bound on the joint entropy, while MIE-2 can fall far below it when many torsions are coupled. - Shard: the quasi-harmonic entropy of the hard coordinates over all frames (
--hard-estimator qh, the default), BQH (bqh), or QH truncated at first (qh-mie1) or second order (qh-mie2) in the mutual information expansion (see below). Hard phase angles are centered on their circular mean (--periodic-correlation centered, the split default). - Coupling: the dependence between the two sets, at most 0 up to sampling error. See Coupling.
The output lists each term before the total. Add ⟨ln J⟩ for a Cartesian entropy, as for every estimator.
Which coordinates are soft
--soft (soft= in Python) chooses the soft set:
topology(the default for files and for a PythonSystem): the primary torsion about each rotatable bond, that is, about every bond not on a ring. With phase angles, the default, these are the coordinates of typetorsion; methyl rotors count. Torsions about ring bonds, and every phase angle, bond and angle, are hard. This needs phase angles, because the raw secondary torsions of a rotor are as multimodal as the primary one.detect(the default for a raw array in Python): every periodic coordinate whose distribution has more than one basin, or is a free rotor (mean resultant length below 0.3), as found by basin detection.- a list of coordinate numbers, counted from 1 on the command line (as printed by
--per-coordinate) and from 0 in Python and Rust.
In Rust, InternalCoordinates::soft_torsions() gives the topological set; in Python, System.soft_torsions. symmetric_rotor_torsions lists the soft torsions about symmetric rotors (one end carries only two or more terminal atoms of one element, as in CH3, NH3+ and CF3), and ring_torsions those about ring bonds.
Coupling
--coupling (coupling=) chooses how the dependence between the sets is accounted for:
gaussian(the default): the Gaussian mutual information between the sets,½ [ln|C(S∪H)| − ln|C(S)| − ln|C(H)|]. Soft torsions enter the correlation matrix as cos kφ and sin kφ for k = 1 to 3 (--soft-features harmonics, the default;--harmonics Nsets the number), as cos φ and sin φ only (cossin, the same as--harmonics 1), or ase^{iφ}(complex). As separate real columns, cos φ and sin φ can correlate with a hard coordinate separately: a bond angle that responds to trans against gauche but not to which gauche correlates with cos φ alone, which the single complex entry partly averages away. Higher harmonics catch dependences that are not linear in cos φ and sin φ, such as an angle that follows cos 3φ, strained at every eclipsed position. Each harmonic adds two columns per soft torsion, and the frames must outnumber all the columns.states: the hard entropy is computed within each conformational state of the soft torsions, the states' entropies are averaged with their populations, and the coupling is the difference from the hard entropy over all frames. A state is the combination of basins of the state-defining torsions: by default (--state-torsions auto) the soft torsions with more than one basin, excluding symmetric rotors, whose basins are equivalent; or a list. States with fewer than--min-state-framesframes (300 by default) or than the number of hard coordinates plus 2 are dropped and the others' populations renormalized; the output lists every state and the dropped frames, and warns when more than 5% are dropped. In Python,state_labelsgives each frame's state directly.none: the sets are treated as independent.
No mixing term is added: the entropy of moving between states is already part of Ssoft.
Basin detection
detect_basins (Rust basins::detect_basins, Python molentropy.detect_basins) finds the basins of a periodic coordinate:
- Histogram the values over one period (72 bins, fewer for small samples) and smooth with a wrapped Gaussian (standard deviation 2 bins).
- Take every circular local maximum as a peak.
- Merge neighboring peaks whose separating minimum is at least half the lower peak.
- Put the basin boundaries at the remaining minima.
- Merge basins holding less than 2% of the frames into a neighbor.
The result is deterministic and does not depend on where the period starts.
Truncated Gaussian hard entropy
--hard-estimator qh-mie1 (hard_estimator="qh-mie1", HardEstimator::QuasiHarmonicMie1) keeps only QH's first-order term, the Gaussian entropy of each hard coordinate, Σi ½ ln(2πe σi²): the hard coordinates as independent Gaussians, with no correlation term. It is an upper bound on the QH hard entropy, since ½ ln|C| ≤ 0. It shows how much the hard correlations contribute; it is not a more accurate hard entropy. On alanine dipeptide ½ ln|C| was −1.68 nats at λ = 0 and −2.04 at λ = 1, so dropping it lowers S0 − S1 by 0.36 nats.
--hard-estimator qh-mie2 (hard_estimator="qh-mie2", HardEstimator::QuasiHarmonicMie2) keeps QH's Gaussian entropy of each hard coordinate but replaces its correlation term ½ ln|C| with the second-order mutual information expansion, the Gaussian mutual information of each pair subtracted once:
Shard = Σi ½ ln(2πe σi²) + ½ Σi<j ln(1 − ρij²)
where ρij is the correlation of hard coordinates i and j (its modulus with --periodic-correlation complex). This is the MIE-2 of the soft set with Gaussian terms. For Gaussian coordinates the full ½ ln|C| is exact, and the pairwise sum is an approximation to it: it agrees when the dependences are weak or confined to separate pairs, and misses the dependence shared among three or more coordinates. That error has either sign: the pairwise sum overcounts redundant dependences (three coordinates all correlated with one another) and undercounts synergistic ones (two independent coordinates that together determine a third). On butane the pairwise term was 0.03–0.06 nats more negative than ½ ln|C|; on alanine dipeptide (ff14SB, 41 hard coordinates) it was 0.01–0.02 less negative, and S0 − S1 moved by 0.005 nats. Use it to compare with the MIE-2 treatment of the soft set, not as a more accurate hard entropy. The coupling term is unchanged: it still uses ln|C(H)| of the whole hard set. With --per-coordinate, each pair's term is shared equally between its two coordinates; with qh-mie1 each hard coordinate takes its first-order term.
Choosing settings
The defaults (topological soft set, MIE-2 soft, centered QH hard, Gaussian coupling with three harmonics) were chosen on 18 small molecules and 4 peptide systems with MBAR references, and checked on 8 more small molecules and a held-out folded peptide (Trp-cage); see Validation, which also lists the best estimator for each system.
Why these defaults
Each default is the setting with the lowest error on small flexible molecules that also works on every system. A simpler setting was preferred when errors were within about 0.05 nats. The numbers are RMSEs in nats over the 15 molecules used to choose the defaults, and over the 8 held out.
-
Topological soft set, not detection. Detection was a little better on the first 15 molecules (0.59 against 0.70 with cos/sin coupling) but worse on the held-out 8 (0.66 against 0.61). It also makes ring torsions soft, which put a puckering cyclohexane 8–10 nats off with MIE-2. Topology is deterministic, needs no sampling to classify a torsion, and treats a rotatable bond the same whether or not it crossed a barrier in the trajectory.
-
MIE-2 soft entropy, not MIST or the joint estimate. MIE-2 had an RMSE of 0.38 on the 23 small molecules, against 0.61 for MIST. The joint estimate was no better (0.69 on the 13 molecules where it ran, against 0.70), its bias grows with the number of soft torsions, and it stops at 8, so it failed on decane and longer. MIST is an option because it is far better on folded peptides, where MIE-2 overcounts the dependence between many coupled torsions; see below.
-
QH for the hard set, with phase angles centered on their circular mean. BQH hard entropies were within 0.02 nats of QH on the first 15 molecules and worse on the held-out 8 (0.71 against 0.61). QH is also faster, and the hard coordinates are close to Gaussian by construction. On butane, centered phase angles beat complex ones by 0.02 nats; on the 15 molecules the difference was 0.01.
-
Gaussian coupling, not per-state. No coupling at all left S0 − S1 too low (1.16 and 1.01). Per-state coupling was the most accurate on the first 15 molecules where it ran (0.33), but it fails when no state has enough frames (decane, hexadecane, both peptides in GBn2), and it was worse on the held-out 8 (0.66). Gaussian coupling always runs.
-
Three harmonics of each soft torsion in the coupling. The error fell with each harmonic: 0.70, 0.55 and 0.36 for one, two and three on the first 15 molecules, and 0.61, 0.54 and 0.41 on the held-out 8. One-hot basin indicators added to cos/sin did about as well as two harmonics (0.55 and 0.56). More harmonics were not tested; each adds two correlation columns per soft torsion and needs more frames. Three harmonics are slightly worse than cos/sin on butane and hexane (by 0.05–0.09 nats), where cos/sin was already within 0.04.
-
Small flexible molecules (up to about 15 soft torsions): on 23 such molecules the defaults were within 0.5 nats on 20 and 0.84 at worst, and beat both QH and BQH on all but hexane, where BQH was 0.06 nats closer. (With a benzamide's ring torsions switched off as well, QH was better.) With one multi-basin torsion, as in butane, plain BQH is about as good.
-
Per-state coupling (
--coupling states) is more accurate when there are a few well-sampled conformers: about 4 or fewer state-defining torsions and plenty of frames in each state. It cut the error from 0.31 to 0.02 nats on biphenyl and from 1.6 to 0.3 on a nitrobenzamide. With more states it drops frames or fails, and on hexane it was 0.5 nats worse than Gaussian coupling. -
Peptides and other large molecules: use
--soft-estimator network. It was stable across strides and roughly halved MIST's error on every peptide tested, to 4–12 nats in S0 − S1 (1.5–5% of the entropy change), and to 4 nats on the solvation entropy of the GS chain (Validation). With BQH for the hard set (--hard-estimator bqh) it was 5.6 nats off on Trp-cage. No estimator was reliable to a few nats on peptides, and all of them overestimated the entropy of the more structured state. With the MIE-2 default, the split estimator overestimated the entropy loss of a folded β-hairpin (chignolin) by 30–165 nats, because MIE-2 subtracts every pairwise dependence among its 50 soft torsions, and on Trp-cage (99 soft torsions) its error jumped by up to 10 nats between strides. MIST was within 3.6 nats on chignolin in implicit solvent but 17 nats low on Trp-cage; BQH was 5.3 and 25 off. Check any result on every 2nd and 4th frame (Finite-sampling bias). Above 20 soft coordinates the CLI and Python warn (LARGE_SOFT_SETin Rust). -
Compact small molecules: a zwitterion collapsed into a salt bridge was off by 1.0 nats with only 4 soft torsions.
-
Flexible rings: torsions about ring bonds are hard under the topological rule, so a puckering ring falls to the Gaussian; on cyclohexane this was within 0.6 nats. Do not combine
--soft detectwith MIE-2 there: detection makes the ring torsions soft, and the pairwise MIE cannot represent the ring closure that couples them (8–10 nats off). The joint soft estimator handled it (0.14 nats). -
The joint soft estimator has no truncation error but its bias grows with the number of soft torsions, and it is limited to 8.
-
Detection can call a rotatable bond stuck in one well hard, and a stiff torsion that samples two wells soft; the topological rule cannot.
--per-coordinate (per_coordinate=True in Python, estimate_coordinate_split_entropy in Rust) gives each coordinate's share of the soft or hard entropy and of the coupling, except with the joint soft estimator; see Per-coordinate entropies. --mutual-information does not apply to the split estimator.
Per-coordinate entropies
--per-coordinate on the command line, and the estimate_coordinate_* functions and per_coordinate=True in Python and Rust, divide an entropy among the coordinates. A joint entropy belongs to the whole set, so any such division is a convention. The conventions below share three properties:
- the shares sum to the total, up to rounding;
- they do not depend on the order of the coordinates;
- a coordinate independent of all the others keeps its own entropy.
Use them to compare the same coordinate between two ensembles under the same estimator: which bonds, angles or torsions carry an entropy change. Shares from different estimators divide different quantities and are not comparable.
By estimator
| estimator | each coordinate's share | where |
|---|---|---|
| NN MIE, order 1 | its marginal entropy | estimate_coordinate_entropy |
| NN MIE, orders 2 to 4 | its marginal entropy, plus an equal part of every interaction term it is part of | estimate_coordinate_entropy |
| MIST | its marginal entropy, minus half the mutual information of each spanning-tree link it is part of | estimate_coordinate_mist_entropy (Rust); the split estimator's soft set |
| Bayesian network | its marginal entropy, minus half the mutual information between it and its parents, minus an equal part of the other half for each coordinate it is a parent of (with one parent, the MIST share) | estimate_coordinate_network_entropy (Rust); the split estimator's soft set |
| QH, BQH | its first-order term, plus ½ (log C)ii | estimate_coordinate_quasi_harmonic_entropy; see Quasi-harmonic estimators |
| split | its share of the soft or hard entropy as above, plus its share of the coupling | estimate_coordinate_split_entropy (Rust), estimate_split_entropy(..., per_coordinate=True) (Python) |
| joint NN | not available |
The MIE at higher orders
The MIE truncated at order k is a sum of interaction terms: the marginal entropies, minus the pairwise mutual informations, plus the three-way co-informations, and so on up to k coordinates at a time. Each term is split evenly among the coordinates it involves. At order 2 this splits each mutual information evenly between its two coordinates. At every order it is the Shapley value of the truncated expansion, the unique split that treats all coordinates alike and gives an independent coordinate nothing from the others. The shares cost no more than the total. They are computed from the same joint entropies, summed per coordinate.
The split estimator
- Soft coordinates take their shares of the soft entropy: MIE at its order, or MIST. The joint soft estimate has no split, so
--per-coordinaterefuses it. - Hard coordinates take their shares of the QH or BQH entropy.
- Gaussian coupling
½ [ln|C(S∪H)| − ln|C(S)| − ln|C(H)|]is shared like the QH correlation term. A soft coordinate receives½ [(log C(S∪H))ᵢᵢ − (log C(S))ᵢᵢ], a hard one the same with C(H). A soft torsion's share is summed over its columns, two per harmonic. Two coordinates coupled only to each other share their coupling evenly. Unlike a QH correlation share, one coordinate's coupling share can be positive; the sum cannot. - Per-state coupling gives each hard coordinate its population-weighted share of the hard entropy within the states, minus its share over all frames. Soft coordinates get no coupling share, because conditioning on the states changes only the hard entropy.
The command line prints the split shares as coordinate, type, atoms, entropy, set (soft or hard), own and coupling, where entropy = own + coupling.
The shares come from an eigendecomposition, which is stricter about nearly singular matrices than the Cholesky factor behind the totals. Soft torsions that barely move make their harmonics nearly collinear (sin kφ is about kφ for small φ), so a coupling that the total can still compute may be refused for shares. Use the cos/sin features (--soft-features cossin) or fewer harmonics there. The peptides and small molecules of the validation had no such problem.
Correlated frames and the Theiler window
The Kozachenko-Leonenko estimator assumes independent samples. When frames are saved faster than a coordinate decorrelates, a frame's nearest neighbor is usually the frame before or after it. That distance measures how far the system moves in one output interval, not the density of states, so entropies come out low. The error grows with the number of dimensions, so it does not cancel in the MIE: oversampled independent coordinates show spurious positive mutual information.
A Theiler window of W frames keeps every frame as a query point but takes its nearest neighbor only from frames more than W away in time. Each frame's finite-sample term uses the number of frames it can actually compete against, so the window does not bias the estimate for independent samples. Unlike --stride, it discards no data. Frames are counted after --start and --stride, and the series must have at least 2W + 2 frames.
What the tests show (tests/theiler.rs):
- On an AR(1) series with lag-one correlation 0.99, the mutual information of two independent coordinates is +0.044 at
W = 0and about 0 atW = 5. - On mildly correlated series (lag-one correlation 0.95), any
Wof a few frames or more removes the bias and leaves the estimate on a plateau. RMSE is lower than with any stride. - On strongly oversampled series the window over-corrects as
Wgrows. The frames that remain eligible come in clusters, one per visit to a region, which lengthens nearest-neighbor distances. Mutual information then turns negative, about -0.04 atW >= 50in the example above. A window is not a substitute for adequate sampling.
Outside the test suite, on 100 ns production runs of three small solvated ligands saved every 2 ps (50,000 frames), the order-2 total changes by at most about 0.4 k_B across W = 0 to 250, while striding moves it by 10-20 k_B. At that spacing the frames are already effectively decorrelated, so the plain estimator is fine there.
Use a window when output is dense compared with the coordinates' correlation times. Choose W from a sweep: plot the entropy against W and take a value where the curve has stopped moving for the fast coordinates. Prefer a window to a stride when the goal is only to remove temporal neighbors.
Validation
This page records tests of the estimators against entropies computed without any density estimate, so their accuracy can be judged on real molecular data rather than only on the closed-form distributions of the test suite.
Butane end states
Reference
Two states of butane differ only in their bonded potential: state 0 has the torsion terms switched off, state 1 is ordinary butane. Both were simulated with OpenMM 8.5 in the gas phase (no cutoff) at 320 K with a Langevin integrator (2 fs, friction 1/ps) and the X-H bonds constrained.
Thermodynamic integration and MBAR over the linear path U(λ) = (1 - λ) U0 + λ U1, in 21 windows of 10 ns each, give the free energy difference ΔA. The mean potential energies of the end states give ΔU, and T ΔS = ΔU - ΔA. Because the masses do not change, the momentum entropy cancels, and ΔS is the difference in configurational entropy. The metric term of the constraints is -0.0003 nats, negligible. Three replicates started from independent frames with independent random seeds:
| replicate | ΔA (kcal/mol) | ΔU (kcal/mol) | S0 - S1 (nats) |
|---|---|---|---|
| 1 | 10.592 ± 0.006 | 1.550 ± 0.051 | 14.219 ± 0.080 |
| 2 | 10.613 ± 0.006 | 1.438 ± 0.051 | 14.429 ± 0.081 |
| 3 | 10.619 ± 0.006 | 1.509 ± 0.059 | 14.325 ± 0.093 |
| mean ± sd | 14.32 ± 0.11 |
Estimates
Each estimate uses the 10,000 frames (one per ps) of the λ = 0 and λ = 1
windows of the same replicate. With the X-H bonds constrained, the default
CoordinateOptions give exactly
the 26 unconstrained, nonredundant coordinates of butane: 3 C-C bonds, 12
angles and 11 torsions. The reference is a Cartesian entropy, so every
estimate below includes the change in the mean log BAT Jacobian,
Δ⟨Σ 2 ln b + Σ ln sin θ⟩ over the unconstrained bonds and the angles, about
-0.06 nats; the constrained bonds contribute a constant that cancels.
S0 - S1 in nats. Mean error and RMSE are against each replicate's own
reference.
| coordinates | estimator | rep 1 | rep 2 | rep 3 | mean error | sd | RMSE |
|---|---|---|---|---|---|---|---|
| reference | 14.219 | 14.429 | 14.325 | ||||
| phase angles | BQH | 14.238 | 14.480 | 14.348 | +0.031 | 0.017 | 0.034 |
| phase angles | BQH, centered torsions | 14.214 | 14.459 | 14.327 | +0.009 | 0.019 | 0.018 |
| phase angles | BQH, 100-bin histogram | 14.165 | 14.340 | 14.226 | -0.081 | 0.024 | 0.083 |
| phase angles | NN MIE-2 | 14.541 | 13.950 | 14.160 | -0.107 | 0.403 | 0.346 |
| phase angles | QH | 13.388 | 13.505 | 13.408 | -0.891 | 0.051 | 0.892 |
| raw torsions | QH | 13.730 | 13.651 | 13.620 | -0.657 | 0.150 | 0.669 |
| raw torsions | NN MIE-2 | 16.315 | 15.446 | 17.879 | +2.222 | 1.273 | 2.453 |
| raw torsions | BQH, 100-bin histogram | 17.132 | 17.331 | 17.167 | +2.886 | 0.038 | 2.886 |
| raw torsions | BQH | 17.189 | 17.446 | 17.147 | +2.936 | 0.102 | 2.938 |
| raw torsions | BQH, centered torsions | 20.175 | 16.012 | 15.787 | +3.000 | 2.560 | 3.657 |
BQH is estimate_quasi_harmonic_entropy
with the default options (nearest-neighbor marginals, complex torsions);
"centered torsions" is PeriodicCorrelation::Centered
and the histogram is MarginalEstimator::Histogram.
NN MIE-2 is calculate_entropy at order 2.
"Raw torsions" sets CoordinateOptions::phase_angles
to false.
Split estimator
The split estimator with the topological soft set, on the same trajectories (S0 - S1 in nats). 96 configurations were scored: soft estimator {MIE-2, joint with either finite-sample constant} × hard estimator {QH, BQH} × hard phase angles {centered, complex} × coupling {per-state, Gaussian e^{iφ}, Gaussian cos/sin, none} × soft set {topology, detected}.
| estimator | rep 1 | rep 2 | rep 3 | mean error | RMSE |
|---|---|---|---|---|---|
| split (MIE-2 soft, QH hard, Gaussian coupling with three harmonics) | 14.296 | 14.565 | 14.482 | +0.123 | 0.128 |
| split, cos/sin coupling | 14.216 | 14.499 | 14.408 | +0.050 | 0.063 |
| split, per-state coupling | 14.246 | 14.529 | 14.440 | +0.081 | 0.089 |
| split, joint soft, BQH hard, no coupling | 14.220 | 14.557 | 14.368 | +0.057 | 0.078 |
On butane the coupling between soft and hard coordinates is small (with cos/sin or e^{iφ} soft features, Gaussian and no coupling differ by 0.001 nats), detection chooses the same soft set as topology, and the finite-sample constant cancels in the difference. Centered hard phase angles beat complex ones by about 0.02 nats, and per-state coupling is about 0.03 nats worse than Gaussian coupling, from the bias of a Gaussian fitted within each state. The split estimator improves on an earlier hand-tuned version of the same decomposition (soft torsions by a joint estimate or MIE-2, hard Gaussian within hand-binned states: +0.06 and +0.14 nats), but plain BQH is better on butane, whose single multi-basin torsion BQH's nearest-neighbor marginals already describe. The default's three harmonics, chosen on the molecules below, add about 0.07 nats here, as they do at 300 K.
What it shows
- BQH with phase angles agrees with the reference within the reference's own uncertainty (about 0.08 nats per replicate), and follows its variation from replicate to replicate. The centered and complex torsion treatments are indistinguishable here: with phase angles only four torsions remain free, and their correlations are weak.
- QH misses by 0.9 nats. It shares BQH's correlation term, so the difference is its Gaussian first-order term, which cannot represent the multiwell torsions of state 1.
- NN MIE-2 is right on average but noisy, ±0.4 nats between replicates: the pairwise mutual informations it sums each carry estimator error.
- Phase angles matter for every estimator. With the raw torsions, the three hydrogen torsions of each methyl group are redundant; every estimator is off by 0.7 to 3.7 nats.
These are estimates for one small molecule. They show which estimators work on it, not an error bar for other systems.
Reproducing
examples/butane_validation.rs computes every estimate in the table from
the end-state trajectories of each replicate:
cargo run --release --example butane_validation -- \
rep1/endpoints 14.219 rep2/endpoints 14.429 rep3/endpoints 14.325
Each directory holds 0.0.top, 0.0.nc, 1.0.top and 1.0.nc; the number
after it is that replicate's reference S0 - S1.
Small molecules and peptides at 300 K
Butane has one multi-basin torsion. To set the split estimator's defaults and find where it fails, the same comparison was repeated on 18 small molecules and two peptides in two environments, all at 300 K. The defaults were then checked on 8 more small molecules and a third peptide, Trp-cage, that played no part in choosing them.
Systems and end states
- Small molecules, GAFF2 with AM1-BCC charges, gas phase: alkanes (butane, hexane, decane, hexadecane), molecules from the FreeSolv set, and others chosen as edge cases: a linear group (1-butyne), an intramolecular hydrogen bond (ethylene glycol), a flat double well (biphenyl), a puckering ring (cyclohexane) and a gas-phase zwitterion (GABA). Held out (‡): 3-amino-1-propanol, 1,2-dimethoxyethane, 2,3-dimethylbutane, ethyl acetate, N-ethylacetamide, 1-pentanol, butylbenzene and alanine dipeptide (Ace-Ala-Nme, with GAFF2 like the others).
- Peptides, ff14SB: chignolin (CLN025), a folded β-hairpin, and Ace-(GS)5-Nme, a disordered chain, each in vacuum and in GBn2 implicit solvent (mbondi3 radii). Held out (‡): Trp-cage (TC5b, model 1 of PDB 1L2Y), a 20-residue folded mini-protein, in GBn2 only.
- State 1 is the molecule with its full force field. State 0 keeps bonds and angles but has every dihedral term, charge and Lennard-Jones parameter switched off, and in GBn2 the solvation term too. For the molecules marked † state 0 keeps impropers and the torsions about ring bonds, so rings stay planar and only rotatable bonds become free; for the two marked "ring torsions off" the ring is floppy in state 0.
Reference
Hamiltonian replica exchange over λ windows (neighbor swaps every ps) with MBAR, along a path that scales the torsions linearly and the nonbonded terms with a soft core (Beutler, α = 0.5), on λk = sin²(πk/2(K−1)). Small molecules: 21 windows of 10 ns, 2 fs steps, X-H bonds constrained; butane and hexane used independent windows and thermodynamic integration instead. Peptides: 32 (GS), 40 (chignolin) or 56 (Trp-cage) windows of 30 ns, 4 fs steps with hydrogen mass repartitioning. T ΔS = ΔU − ΔA as for butane. Three replicates each; the table gives the mean and standard deviation of S0 − S1.
Checks on the references:
- Replicates agree to 0.01–0.12 nats for the small molecules and 0.04–0.4 for the GS chain. Chignolin's differ by up to 6 nats: its folding equilibrium is not converged, so its errors below are good to about ±3 nats. Trp-cage's agree to 1.0 nats (326.80, 325.76, 325.89).
- Hysteresis: every peptide replicate above started from the folded structure, so the replicates' agreement could hide a shared bias. Three more replicates of each folded peptide in GBn2 started from structures unfolded at 500 K (Cα RMSD 3–6 Å). For Trp-cage two agreed with the folded starts (327.0 and 327.0 nats); the third was still refolding after 30 ns (322.7, 30% folded against 56–72%), so its reference is good to about ±1 nat. For chignolin the unfolded starts gave 189.8 nats against 194.6 from the folded starts, with the folded fraction drifting toward the middle from both sides: the true value is near 192 ± 3.
- Finite differences: for three molecules simulated identically at 300 and 320 K, −∂ΔA/∂T from the two free energies agreed with (ΔU − ΔA)/T within its error (0.03–0.41 nats against errors of 0.2–0.3), which rules out a problem in the mean energies.
- Constraints: four molecules rerun without constraints (1 fs) gave references 0.03–0.07 nats higher. This is within the noise of the comparisons below.
References are therefore good to about ±0.1 nats for the small molecules; differences between estimators smaller than that are not resolved.
Estimates
Each estimate uses the end-state frames (one per ps) of the same replicate, phase angles and the change in ⟨ln J⟩, as for butane. RMSE in nats over the three replicates against each replicate's own reference; "soft" is the number of topological soft torsions. "Split" is the default (MIE-2 soft, centered QH hard, Gaussian coupling with three harmonics of each soft torsion); "cos/sin" uses only the first harmonic in the coupling (the default before the held-out check), "MIST" replaces MIE-2 for the soft set, and "per-state" replaces the coupling. The best estimate in each row is in bold. "Fails" means no state had enough frames.
| system | soft | reference | QH | BQH | split | split mean error | split, cos/sin | split, MIST | split, per-state |
|---|---|---|---|---|---|---|---|---|---|
| butane | 3 | 14.51 ± 0.03 | 1.03 | 0.11 | 0.09 | +0.08 | 0.04 | 0.09 | 0.06 |
| hexane | 5 | 22.01 ± 0.12 | 1.67 | 0.07 | 0.13 | +0.12 | 0.04 | 0.12 | 0.50 |
| decane | 9 | 12.17 ± 0.11 | 7.43 | 1.95 | 0.73 | -0.34 | 1.30 | 0.66 | fails |
| hexadecane | 15 | 21.22 ± 0.12 | 13.13 | 4.34 | 0.40 | +0.18 | 1.22 | 1.52 | fails |
| 1-butyne | 3 | 0.98 ± 0.02 | 0.69 | 0.11 | 0.05 | +0.01 | 0.07 | 0.04 | 0.07 |
| dichloropropane | 2 | 2.58 ± 0.03 | 1.79 | 0.54 | 0.06 | -0.06 | 0.22 | 0.06 | 0.15 |
| ethylene glycol | 3 | 2.96 ± 0.01 | 2.29 | 1.42 | 0.43 | -0.43 | 0.56 | 0.66 | 0.48 |
| isoflurane | 3 | 4.33 ± 0.08 | 3.21 | 1.50 | 0.14 | -0.13 | 0.29 | 0.21 | 0.27 |
| butylamine | 4 | 4.19 ± 0.05 | 2.77 | 0.55 | 0.06 | -0.05 | 0.30 | 0.08 | 0.18 |
| trimethyl phosphate | 6 | 3.77 ± 0.07 | 2.68 | 0.72 | 0.22 | -0.12 | 0.38 | 0.29 | 0.41 |
| methylpentanol | 6 | 7.48 ± 0.07 | 4.40 | 1.17 | 0.20 | -0.12 | 0.60 | 0.37 | 0.49 |
| trimethoxyethane | 7 | 9.61 ± 0.03 | 8.13 | 3.27 | 0.33 | +0.26 | 0.20 | 1.22 | 0.22 |
| trifluoroethylaniline | 4 | 3.31 ± 0.09 | 1.82 | 1.14 | 0.23 | -0.21 | 0.61 | 0.34 | 0.49 |
| biphenyl † | 1 | 1.40 ± 0.06 | 0.70 | 0.30 | 0.17 | -0.17 | 0.31 | 0.17 | 0.02 |
| N,N-dimethyl-4-nitrobenzamide † | 5 | 6.90 ± 0.11 | 5.80 | 3.50 | 0.84 | -0.84 | 1.63 | 1.03 | 0.34 |
| N,N-dimethyl-4-nitrobenzamide, ring torsions off | 5 | 20.11 ± 0.11 | 0.24 | 2.28 | 3.75 | +3.74 | 2.96 | 3.50 | 4.28 |
| cyclohexane, ring torsions off | 0 | 4.53 ± 0.10 | 0.72 | 6.77 | 0.61 | +0.61 | 0.61 | 0.61 | 0.61 |
| GABA zwitterion | 4 | 9.58 ± 0.06 | 6.58 | 2.73 | 1.00 | -0.99 | 1.81 | 1.78 | 3.67 |
| 3-amino-1-propanol ‡ | 4 | 6.98 ± 0.04 | 4.74 | 2.36 | 0.46 | -0.44 | 0.79 | 1.22 | 0.83 |
| 1,2-dimethoxyethane ‡ | 5 | 4.94 ± 0.04 | 3.78 | 1.21 | 0.41 | -0.41 | 0.66 | 0.59 | 0.52 |
| 2,3-dimethylbutane ‡ | 5 | 6.75 ± 0.06 | 4.78 | 1.22 | 0.43 | -0.40 | 0.92 | 0.47 | 0.86 |
| ethyl acetate ‡ | 4 | 5.16 ± 0.04 | 1.40 | 1.00 | 0.17 | +0.16 | 0.25 | 0.10 | 0.73 |
| N-ethylacetamide ‡ | 4 | 5.96 ± 0.11 | 2.70 | 0.65 | 0.34 | +0.32 | 0.30 | 0.25 | 0.56 |
| 1-pentanol ‡ | 5 | 5.11 ± 0.06 | 3.01 | 0.85 | 0.22 | -0.15 | 0.49 | 0.21 | 0.11 |
| butylbenzene † ‡ | 4 | 4.66 ± 0.04 | 2.98 | 1.07 | 0.22 | -0.22 | 0.57 | 0.28 | 0.28 |
| alanine dipeptide (Ace-Ala-Nme) ‡ | 7 | 14.28 ± 0.02 | 5.19 | 2.06 | 0.75 | +0.60 | 0.55 | 0.08 | 0.94 |
| Ace-(GS)5-Nme, GBn2 | 43 | 104.02 ± 0.04 | 31.09 | 22.35 | 7.04 | -5.55 | 9.38 | 14.16 | fails |
| Ace-(GS)5-Nme, vacuum | 43 | 136.86 ± 0.37 | 50.05 | 40.55 | 57.28 | +56.95 | 53.37 | 28.93 | 63.66 |
| chignolin CLN025, GBn2 | 50 | 194.59 ± 3.00 | 21.45 | 5.30 | 30.34 | +29.46 | 26.98 | 3.61 | fails |
| chignolin CLN025, vacuum | 50 | 231.73 ± 3.31 | 53.44 | 35.00 | 164.76 | +163.98 | 158.41 | 28.13 | 193.72 |
| Trp-cage TC5b, GBn2 ‡ | 99 | 326.15 ± 0.57 | 48.66 | 24.66 | 6.27 | -3.29 | 10.38 | 16.89 | fails |
QH and BQH are estimate_quasi_harmonic_entropy with complex torsions.
What it shows
- On small flexible molecules the split estimator is the best general choice. On the 23 small molecules with only rotatable bonds free in state 0 (all but the two "ring torsions off" rows and GABA), the default was within 0.5 nats on 20, with an RMSE of 0.38 and 0.84 at worst. It beat BQH on all but hexane. QH misses multi-basin torsions by up to 13 nats.
- Three harmonics in the coupling held up on new molecules. On the 15 molecules used to choose it, three harmonics instead of cos/sin cut the RMSE from 0.70 to 0.36 nats. On the 8 held-out ones it cut it from 0.61 to 0.41, improving 6 of the 8. Higher harmonics let a hard coordinate depend on which well a torsion is in, or on cos 3φ as an eclipsed bond angle does. Cos/sin alone left S0 − S1 too low on almost every molecule. It is still better on butane, hexane and trimethoxyethane, by up to 0.13 nats, and on alanine dipeptide, where three harmonics overshoot by 0.6. On each end state alone the coupling is biased downward by about (soft features × hard coordinates) / 2n, as for any Gaussian mutual information. That bias is the same in both end states and cancels in S0 − S1, which was unchanged from 1,250 to 30,000 frames.
- No estimator is reliable to a few nats on peptides, though the Bayesian network soft estimator (below) halves MIST's error. MIST (
--soft-estimator mist) was within 3.6 nats on chignolin in GBn2 (BQH 5.3) and 28 in vacuum (BQH 35), roughly halved the error on the GS chain in vacuum, and nailed alanine dipeptide (0.08). But on the held-out Trp-cage it underestimated the entropy change by 17 nats (5%), so its chignolin result does not carry over. MIE-2 subtracts every pairwise mutual information and so overcounts dependence when many torsions are coupled, which is why the default overestimated the entropy change of chignolin by 30–165 nats. On Trp-cage the default had the lowest RMSE (6.3), but its error ranged from −7 to +4 across replicates and jumped between strides (below), so that was luck. MIST and BQH were stable across strides on both folded peptides, which makes them the safer choice, but they can be stably wrong by 5–10% of the entropy change. On small molecules MIST was worse than MIE-2 (RMSE 0.61 against 0.38), most of all with hydrogen bonds (aminopropanol 1.2, trimethoxyethane 1.2). On the disordered GS chain in GBn2 it was worse too (14 against 7). - Per-state coupling is better when there are few, well-sampled states (biphenyl 0.02, the ring-kept benzamide 0.34), and worse or impossible with many (hexane, decane and longer).
- Compact molecules are hardest. The GABA zwitterion, which folds into a salt bridge, was off by 1.0 nats with only 4 soft torsions.
- Rings: with the topological soft set a puckering cyclohexane falls to QH (0.6 nats); BQH was off by 6.8 there. Soft-set detection with MIE-2 was off by 8–10 nats, because the pairwise MIE cannot represent the ring closure; the joint soft estimator was within 0.14. With a benzamide's ring torsions off, plain QH was best.
- Linear groups (1-butyne) need nothing special.
Peptides across strides
An estimate that changes direction when frames are dropped is dominated by noise; see Finite-sampling bias. For the held-out Trp-cage, the error in S0 − S1 (mean of three replicates, nats) from every Nth frame:
| every Nth frame | split (default) | split, MIST | BQH |
|---|---|---|---|
| 1 | −3.3 | −16.7 | −24.6 |
| 2 | −9.8 | −17.6 | −24.4 |
| 4 | −4.0 | −18.2 | −24.4 |
| 8 | −6.7 | −18.9 | −24.0 |
| 16 | +0.3 | −18.6 | −23.6 |
The default moved by up to 10 nats from one stride to the next and changed direction, as it did on chignolin (+44.5, +27.4, +32.8, +28.4 and +29.5 from 1,875 to 30,000 frames). MIST and BQH moved by 2 nats or less: they converged, to values 17 and 24 nats too low.
Bayesian network soft estimator
MIST keeps one dependence per soft torsion. On the peptides it was stable across strides but consistently overestimated the entropy of the folded or collapsed state 1, leaving S0 − S1 too low. Splitting each error into its two end states showed where. For the GS chain, which has no rings, the state-0 entropy can be computed exactly: state 0 has only bonds and angles, so its density factorizes into one-dimensional integrals. MIST was within 1 nat of it in state 0, but 15–30 nats high in state 1. The coupling term grew from about −1 nat in state 0 to −9 to −39 in state 1. The missing dependence is many-body: torsions that move together in threes and fours, which a tree of pairs cannot represent. The Bayesian network (--soft-estimator network, see NN MIE) conditions each soft torsion on up to 5 earlier ones. Error in S0 − S1, mean over three replicates (RMSE in brackets), nats:
| system | soft | split, MIST | split, network | split, network, BQH hard |
|---|---|---|---|---|
| Ace-(GS)5-Nme, GBn2 | 43 | −14.2 (14.2) | −8.3 (8.4) | −9.1 (9.1) |
| Ace-(GS)5-Nme, vacuum | 43 | −28.8 (28.9) | −12.4 (12.6) | −14.2 (14.3) |
| chignolin CLN025, GBn2 (reference ±3) | 50 | −3.3 (3.6) | +3.8 (4.0) | +3.4 (3.7) |
| chignolin CLN025, vacuum | 50 | −28.1 (28.1) | −11.6 (11.6) | −11.6 (11.6) |
| Trp-cage TC5b, GBn2 | 99 | −16.7 (16.9) | −9.1 (9.3) | −5.6 (5.9) |
- It halved MIST's error on every peptide with a trustworthy reference. In the GS chain's state 0, where the torsions are independent, it changed the soft entropy by less than 0.1 nats, so the extra parents did not fit noise. Five parents captured almost all of the gain: three gave about 80% of it, and six or seven added 0.2 nats or less.
- On a difference between two physical states it did better still. The change in conformational entropy on solvation, S1(GBn2) − S1(vacuum), is the difference of the two references (32.8 nats for the GS chain), and the state-0 terms cancel. The default was off by +62.5 nats, MIST by −14.7 and the network by −4.1. For chignolin, whose references are less certain, the errors were +135, −25 and −15.
- It was stable across strides. For Trp-cage (network soft, BQH hard), the error was −9.5, −8.2, −7.1 and −5.6 nats from every 8th, 4th, 2nd and every frame: it shrinks steadily with more data and never changes direction, unlike the default (table above). Part of the remaining error is therefore finite sampling, which longer runs would reduce.
- On small molecules it was close to the default. On the 22 small molecules with only rotatable bonds free in state 0, its RMSE was 0.37 nats, against 0.32 for the default and 0.60 for MIST. It fixed MIST's misses on molecules with intramolecular hydrogen bonds (trimethoxyethane 1.22 to 0.39, ethylene glycol 0.66 to 0.08).
- BQH for the hard set helped on Trp-cage (−9.1 to −5.6) and slightly hurt on the GS chain (by 0.8–1.8 nats).
- Cost: for Trp-cage (99 soft torsions, 30,000 frames) the network took 16 s per end state on 32 cores.
Best estimator for each system
The lowest RMSE in each row of the table above, and the default's where it was not the best.
| system | best | RMSE | default | notes |
|---|---|---|---|---|
| butane, hexane | split, cos/sin | 0.04 | 0.09, 0.13 | one or two multi-basin torsions; BQH also within 0.11 |
| decane | split, MIST | 0.66 | 0.73 | |
| hexadecane | split (default) | 0.40 | ||
| 1-butyne, dichloropropane | split, MIST or default | 0.04–0.06 | 0.05, 0.06 | |
| ethylene glycol, isoflurane, butylamine, trimethyl phosphate, methylpentanol, trifluoroethylaniline | split (default) | 0.06–0.43 | ||
| trimethoxyethane | split, cos/sin | 0.20 | 0.33 | |
| biphenyl †, nitrobenzamide † | split, per-state | 0.02, 0.34 | 0.17, 0.84 | one or two state-defining torsions with well-sampled states |
| nitrobenzamide, ring torsions off | QH | 0.24 | 3.75 | every split variant is 3–4 nats off |
| cyclohexane, ring torsions off | split (any) | 0.61 | no soft torsions, so the split is QH on centered coordinates; BQH 6.8 | |
| GABA zwitterion | split (default) | 1.00 | next best MIST, 1.8 | |
| aminopropanol ‡, dimethoxyethane ‡, 2,3-dimethylbutane ‡, butylbenzene † ‡ | split (default) | 0.22–0.46 | ||
| ethyl acetate ‡, N-ethylacetamide ‡ | split, MIST | 0.10, 0.25 | 0.17, 0.34 | |
| 1-pentanol ‡ | split, per-state | 0.11 | 0.22 | |
| alanine dipeptide ‡ | split, MIST | 0.08 | 0.75 | the default overshoots by 0.6 |
| Ace-(GS)5-Nme, GBn2 | split (default) | 7.0 | MIST 14, BQH 22 | |
| Ace-(GS)5-Nme, vacuum | split, MIST | 29 | 57 | BQH 41 |
| chignolin, GBn2 | split, MIST | 3.6 | 30 | BQH 5.3 |
| chignolin, vacuum | split, MIST | 28 | 165 | BQH 35 |
| Trp-cage, GBn2 ‡ | split (default) | 6.3 | unstable across replicates and strides; MIST 17 and BQH 25, both stable |
The default was the best, or within 0.15 nats of the best, on 22 of the 26 small molecules. The exceptions were biphenyl and the ring-kept nitrobenzamide, where per-state coupling was better; the nitrobenzamide with ring torsions off, where QH was better; and alanine dipeptide, where MIST was better. On the five peptide systems MIST was best in three. The default was best on the disordered chain in implicit solvent and on Trp-cage, but on Trp-cage only by chance; see Peptides across strides.
These results set the defaults and the warning above 20 soft coordinates. They are estimates for these molecules, not error bars for others.
Interpretation and limitations
- Results are differential internal-coordinate entropies in natural-log units (equivalently, units of
k_B), not kcal mol⁻¹ K⁻¹. - The reported value does not include a BAT-to-Cartesian Jacobian correction, momentum entropy, or a standard-state term, and must not be described as an absolute thermodynamic entropy.
--jacobianreports the Jacobian term separately, for the tree bond set, but does not add it to the total. - MD frames are generally correlated, which biases nearest-neighbor estimates; see Correlated frames.
- Every estimate is biased at a finite number of frames, often by many nats for one ensemble. Most of the bias cancels in a difference between ensembles with the same coordinates and number of frames, but not for the default split estimator on molecules with many coupled soft torsions. See Finite-sampling bias.
- The quasi-harmonic correlation term is a Gaussian approximation: it captures correlations in the second moments of the coordinates (for torsions, of
e^{iφ}), not nonlinear dependence. See Quasi-harmonic estimators. - The MIE is truncated; see Nearest-neighbor MIE.
- The split estimator's topological soft set misses rotors that the bond graph cannot identify as symmetric, such as t-butyl (whose methyls are not terminal atoms), so their basins can define states; detection can call a rotatable bond stuck in one well hard. Its per-state coupling fragments the frames and fits a Gaussian within each state, which is biased for small states. See Split estimator.
- The split estimator was validated on small, flexible molecules, where it was within 0.5 nats on 20 of 23 and 0.84 nats at worst, with up to 15 soft torsions. On folded peptides its default was off by tens of nats or unstable from one stride to the next. MIST soft entropies were stable and within 3.6 nats on chignolin in implicit solvent, but 17 nats (5%) low on the held-out Trp-cage, so no estimator here is reliable to a few nats on peptides. Compact molecules such as a gas-phase zwitterion are less accurate even when small. It warns above 20 soft coordinates. See Validation.
Finite-sampling bias
Every estimator in the crate is biased at a finite number of frames:
- Nearest-neighbor terms (NN MIE, MIST, the Bayesian network, the joint estimate, BQH’s marginals): the bias grows with the dimension of each term, so it is small for MIE-2's one- and two-dimensional terms and larger for the joint estimate over many coordinates.
- Gaussian terms (QH, the correlation term of BQH, the split estimator's hard set and coupling): a mutual information between p and q correlated columns estimated from n frames is biased downward by about pq/2n. For the split estimator's coupling term on chignolin (50 soft torsions with three harmonics each, and about 375 hard coordinates), this was 1.9 nats at 30,000 frames and 15 nats at 3,750.
The entropy of one ensemble is therefore rarely converged in the number of frames. On chignolin with MIST soft entropies, each end state's estimate rose by about 57 nats between 1,875 and 30,000 frames.
It cancels in differences
What is usually reported is a difference between two ensembles of the same molecule, and there most of the bias cancels. It depends mainly on the number of frames and coordinates, which are the same in both, and much less on the ensemble. In the chignolin example, the two end states' 57 nats of drift left their difference changed by 1.4 nats. In the coupling term alone, the difference between end states stayed within 0.04 nats from 3,750 to 30,000 frames for chignolin in GBn2 (0.65 in vacuum), and within 0.04 nats from 1,250 to 10,000 frames for the small molecules tested.
The table gives the error in S0 − S1 against the HREX/MBAR references of the validation, from a sixteenth of the frames and from all of them (means of three replicates, nats). Most entries barely move: what remains with all frames is the estimator's own error, not too few frames.
| system | frames | split (default) | split, MIST | BQH | QH |
|---|---|---|---|---|---|
| butane | 625 → 10,000 | +0.16 → +0.08 | +0.14 → +0.08 | −0.12 → +0.00 | −1.09 → −1.03 |
| hexane | 625 → 10,000 | +0.83 → +0.12 | +0.31 → +0.12 | +0.01 → +0.06 | −1.69 → −1.67 |
| 1-pentanol | 625 → 10,000 | +0.54 → −0.15 | +0.01 → −0.20 | −0.82 → −0.84 | −3.30 → −3.01 |
| methylpentanol | 625 → 10,000 | −0.74 → −0.13 | −0.54 → −0.36 | −1.22 → −1.16 | −4.52 → −4.40 |
| 3-amino-1-propanol | 625 → 10,000 | −0.21 → −0.44 | −1.20 → −1.22 | −2.46 → −2.36 | −4.78 → −4.74 |
| biphenyl | 625 → 10,000 | −0.08 → −0.17 | −0.08 → −0.17 | −0.02 → −0.29 | −0.50 → −0.70 |
| alanine dipeptide | 625 → 10,000 | +0.03 → +0.60 | +0.28 → +0.04 | −1.43 → −2.05 | −4.89 → −5.19 |
| hexadecane | 625 → 10,000 | +4.13 → +0.18 | −1.77 → −1.49 | −4.46 → −4.34 | −13.56 → −13.13 |
| Ace-(GS)5-Nme, GBn2 | 1,875 → 30,000 | −6.37 → −5.55 | −15.36 → −14.15 | −22.59 → −22.35 | −31.13 → −31.07 |
| Ace-(GS)5-Nme, vacuum | 1,875 → 30,000 | +53.83 → +56.95 | −30.76 → −28.84 | −40.83 → −40.53 | −50.36 → −50.02 |
| chignolin, GBn2 | 1,875 → 30,000 | +44.52 → +29.46 | −4.77 → −3.32 | −4.56 → −5.04 | −21.39 → −21.41 |
| chignolin, vacuum | 1,875 → 30,000 | +163.39 → +163.98 | −29.99 → −28.08 | −34.66 → −34.90 | −53.75 → −53.38 |
Where it does not cancel
Cancellation needs the bias to be about the same in both ensembles. It was not for the default split estimator on molecules with many coupled soft torsions, whose MIE-2 soft entropy subtracts a pairwise mutual information for every pair of torsions:
- Hexadecane (15 soft torsions): the error fell from +4.13 to +0.18 nats between 625 and 10,000 frames. The two end states drifted by 10.4 and 14.4 nats, so 3.9 nats did not cancel.
- Chignolin in GBn2 (50 soft torsions): the end states drifted by 50 and 65 nats, so 15 nats did not cancel, and the error jumped between strides (+44.5, +27.4, +32.8, +28.4, +29.5 from 1,875 to 30,000 frames) rather than settling.
- Trp-cage in GBn2 (99 soft torsions, held out): the error went −3.3, −9.8, −4.0, −6.7 and +0.3 nats at every 1st, 2nd, 4th, 8th and 16th frame, while MIST stayed between −16.7 and −18.9; see Validation.
- Alanine dipeptide: the default's overshoot grew from +0.03 to +0.60 nats with more frames. With fewer frames it was right only by chance.
With MIST soft entropies the same molecules converged: the difference moved by 0.3 nats on hexadecane and 1.4 on chignolin. Cancellation also needs the two ensembles to have the same coordinates and about the same number of frames. A Gaussian term's bias scales as 1/n, so comparing 5,000 frames with 50,000 leaves most of the smaller run's bias in the difference.
Checking a result
To check a difference, estimate both ensembles again on every 2nd and every 4th frame (--stride 2, --stride 4, or stride= in load_system) and compare the differences, not the separate estimates. Thinning keeps the span of each trajectory, so the conformations sampled stay the same and only the number of frames changes. A difference that moves steadily toward a value is converging; if it moves by less than the differences you want to resolve, it has converged for that purpose. If it changes direction from one stride to the next, as the default split estimator did on chignolin, the estimate is dominated by noise or by an estimator that does not suit the system.
On densely saved trajectories, thinning also moves nearest neighbors apart in time, which changes the bias from correlated frames. Use a Theiler window, scaled to the same span in time (W / stride frames), or check that the frames are decorrelated, before reading a change between strides as finite-sample bias.
None of this detects states the trajectory never visited. A peptide that stays folded for the whole run gives the same answer at every stride. Only independent replicates or enhanced sampling reveal that.
References
- Grid inhomogeneous solvation theory: Hydration structure and thermodynamics of the miniature receptor cucurbit[7]uril - Uses nearest neighbor method to calculate first-order estimate of solvent entropy
- Extraction of configurational entropy from molecular simulations via an expansion approximation - Uses mutual information expansion to increase accuracy of entropy estimation of highly correlated systems like molecules
- Sample Estimate of the Entropy of a Random Vector - First introduction of nearest neighbors entropy estimation
- Calculation of Configurational Entropy with a Boltzmann-Quasiharmonic Model: The Origin of High-Affinity Protein-Ligand Binding - Harpole and Sharp's BQH method, including the
e^{iφ}treatment of torsion correlations - Developing end-point methods for absolute binding free energy calculation using the Boltzmann-quasiharmonic model - BQH and QH compared for host-guest binding
- Method for estimating the configurational entropy of macromolecules - Karplus and Kushick's quasi-harmonic approximation