> ## 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.

# TRACE Algorithm

> General face-signature cage detection with SEC, nSEC, and IC quality

# TRACE Analysis

TRACE is Clavis's general hydrogen-bond topology path for finding hydrate cages with canonical or unusual face signatures.

## How It Works

1. Build a PBC-aware hydrogen-bond graph from O–O distance and donor-angle criteria.
2. Enumerate and geometrically validate 4-, 5-, and 6-membered rings.
3. Assemble closed polyhedra from shared ring edges.
4. Classify complete and incomplete candidates by topology and face signature.

The current default thresholds are **0.36 nm** for O–O distance and **35°** for the donor-angle criterion. These are TRACE settings; HTR and GRADE have different contracts.

## Cage and Quality Labels

TRACE can return canonical cages such as `5^12`, `5^12·6^2`, and `5^12·6^4`, as well as arbitrary signatures such as `4^3·5^6·6^3`.

| Quality  | Meaning                                |
| -------- | -------------------------------------- |
| **SEC**  | Complete standard edge-saturated cage  |
| **nSEC** | Closed cage with non-standard topology |
| **IC**   | Incomplete cage candidate              |

An arbitrary signature is valid TRACE output. It must not be presented as native GRADE output.

## Running TRACE

1. Upload a supported structure or trajectory containing cage-forming waters.
2. Open **ANALYZE**, select **TRACE**, and run the selected frame or sampled range.
3. Inspect per-type counts and SEC/nSEC/IC totals before interpreting occupancy.

Normal GRO, large streamed GRO, mapped LAMMPS, and native XTC/TRR trajectories support algorithm-owned TRACE range results. Each row records `algorithm`, zero-based `frameIndex`, and one-based display frame. Native ranges decode the selected frame indices before running the same algorithm dispatcher.

The bundled `example_H2O` regression now matches native TRACE exactly: **SEC 10, nSEC 0, IC 12**. The port follows the native 4–10-member ring walk and two-pass cup state machine. New fixtures still require independent reference comparison; this one golden does not validate unrelated inputs automatically.

## Reference

Hsu, Y.-C. & Lin, S.-T. TRACE. *Journal of Chemical Theory and Computation*.
[DOI: 10.1021/acs.jctc.5c01459](https://doi.org/10.1021/acs.jctc.5c01459)