Skip to main content

​
HTR Analysis

HTR identifies primitive 4-, 5-, and 6-membered rings and assembles generalized hydrate cages from the oxygen topology. It is a separate algorithm from TRACE; equal counts on an ideal crystal do not establish that the algorithms are equivalent.

​
Topology Contract

Clavis follows the bundled HTR reference contract:
  1. Build an oxygen-only proximity graph using minimum-image O–O distances.
  2. Connect oxygens at or below the fixed 0.35 nm (3.5 Å) cutoff.
  3. Keep at most six neighbors per oxygen, matching the reference data structure.
  4. Enumerate primitive 4-, 5-, and 6-membered rings.
  5. Assemble cages and report their face counts as n4-n5-n6.
HTR does not use hydrogen donor orientation or the TRACE H-bond angle threshold. Changing a TRACE angle setting therefore must not change HTR topology.

​
Output

For example, 0-12-0 is a 5^12 cage and 0-12-2 is a 5^12·6^2 cage. HTR is not restricted to those canonical labels.

​
Running HTR

  1. Upload a supported structure or trajectory containing cage-forming waters.
  2. Open ANALYZE and select HTR.
  3. Run the selected frame, or choose a sampled range for normal GRO, large streamed GRO, or mapped LAMMPS trajectories.
Trajectory results carry algorithm: htr, a zero-based frameIndex, and a one-based display frame. Normal GRO, streamed GRO, mapped LAMMPS, and native XTC/TRR sessions support selected HTR ranges.

​
Visualization and Validation

Ring and cage overlays are built from the same HTR result used for the reported counts. Ring colors distinguish 4-, 5-, and 6-membered rings. Occupancy uses complete HTR cages only. Reference validation compares the full per-frame n4-n5-n6 count map, not only the total number of cages. A missing reference numOfCages/<frame>.txt file is an empty map only when the manifest declares that convention. The committed 1,242-water oracle pins 216 cages, the full 4/5/6-ring tuple, and the displayed H-bond count. This proves the corrected topology and this canonical fixture; it does not by itself prove generalized traversal parity for every noncanonical cage. The original 1,001-frame input is unavailable, so Clavis does not claim an exact full-trajectory HTR reproduction until that input or an equivalent provenance manifest is recovered.