> ## Documentation Index
> Fetch the complete documentation index at: https://docs.claviscage.app/llms.txt
> Use this file to discover all available pages before exploring further.

# HTR Algorithm

> Oxygen-topology ring and generalized hydrate cage analysis

# 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

| Field                           | Meaning                                                             |
| ------------------------------- | ------------------------------------------------------------------- |
| `n_4ring`, `n_5ring`, `n_6ring` | Primitive ring counts                                               |
| `rings`                         | Ring vertices, positions, centers, and edges used for visualization |
| `cages`                         | Complete HTR cage geometry                                          |
| `cage_types`                    | Generalized `n4-n5-n6` cage counts                                  |
| `incomplete_cages`              | Visual candidates that are not treated as occupiable complete cages |

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.