Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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):

estimatorheavy-atom bondstree bondssystems where tree bonds did better
split (default)0.372.007 of 23
split, MIST0.692.148 of 23
BQH1.783.359 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 --jacobian gives 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 type torsion off 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.