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

# GRADE Cage Detection

> Native detection of 5^12, 5^12·6^2, and 5^12·6^4 hydrate cages

# GRADE Cage Detection

GRADE is a native cage detector with a deliberately narrow output contract. It finds only three cage families:

| Machine label | Face signature |
| ------------- | -------------- |
| `512`         | `5^12`         |
| `51262`       | `5^12·6^2`     |
| `51264`       | `5^12·6^4`     |

GRADE does not run TRACE internally, does not return arbitrary face signatures, and does not infer an sI, sII, sH, mixed, or amorphous structure verdict. It also does not return a confidence score.

## Detection Contract

GRADE builds an oxygen-distance graph, identifies planar 5- and 6-membered rings, assembles cups, and pairs compatible cups into the three supported cage families.

| Parameter                          | Default   |
| ---------------------------------- | --------- |
| O–O cutoff                         | `0.35 nm` |
| Ring-planarity threshold           | `45°`     |
| Pentagon diagonal tolerance (`d1`) | `0.18 nm` |
| Hexagon diagonal tolerance (`d2`)  | `0.26 nm` |

When guest sites are supplied, GRADE also reports `filled_512`, `filled_51262`, and `filled_51264`. These are native filled-cage counts, not a crystal-structure confidence metric.

## Running GRADE

1. Upload a supported structure or trajectory containing cage-forming waters.
2. Open **ANALYZE** and select **GRADE**.
3. Run the selected frame, or choose a sampled range for normal GRO, large streamed GRO, or mapped LAMMPS trajectories.
4. Review the three cage totals and their filled counts.

Normal GRO, streamed GRO, mapped LAMMPS, and native XTC/TRR sessions support selected GRADE ranges.

<Warning>
  A result such as `4^3·5^6·6^3` belongs to TRACE or generalized HTR reporting. If it appears under GRADE, the result is stale, mislabeled, or from an older implementation.
</Warning>

## Validation

Reference parity is checked against the six native `.xvg` values for every frame: total and filled counts for each of the three cage families. Visualization files are secondary evidence.