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

# Benchmark

> Every method run on ideal hydrate and ice crystals whose answer is known by construction

# Benchmark

No shared benchmark for hydrate cage detection has been published, so ClavisCage keeps its own. Every method in the engine runs on the same ideal crystals, and wherever the right answer is known by construction, the result is compared with it. The table is produced by an engine test (`tests/benchmark_table.rs`), written to `web-app/wasm-engine/benchmarks/results.json`, and fails if a result changes without being declared.

## Crystals

All five were generated with GenIce2 2.2.13.1 (seed 1000, TIP3P water). The commands are in `tests/fixtures/benchmark/PROVENANCE.md`.

| Fixture | Structure | Waters | Cages known by construction |
| - | - | - | - |
| `sI_222` | sI hydrate, 2×2×2 | 368 | 16 × 5¹², 48 × 5¹²6² |
| `sII_222` | sII hydrate, 2×2×2 | 1,088 | 128 × 5¹², 64 × 5¹²6⁴ |
| `sH_222` | sH hydrate, 2×2×2 (hexagonal cell) | 544 | 48 × 5¹², 32 × 4³5⁶6³, 16 × 5¹²6⁸ |
| `Ih_332` | hexagonal ice | 288 | none; every water is Ih |
| `Ic_222` | cubic ice | 64 | none; every water is Ic |

## What each method should give

| Method | Exact on | Notes |
| - | - | - |
| TRACE | sI, sII, sH (its three cage types) | No cages in either ice. |
| HTR | sI, sII, sH including 4³5⁶6³ and 5¹²6⁸ | No cages in either ice. |
| GRADE | — | See the known mismatch below. |
| CHILL+ | every water classed hydrate in sI and sII, Ih in Ih, Ic in Ic | sH is recorded, not asserted. |
| F3/F4, averaged q4/q6 | recorded values | Order parameters have no count to be exact against; their numbers are checked against open implementations instead (see [Adding a Method](https://docs.claviscage.app/contributing/methods.md)). |
| Tetrahedral order | recorded values | q is 0.97–0.99 on the hydrates and 0.998 on both ices; on four of these frames it matches GROMACS `gmx order` within 2×10⁻⁶. |
| MCG | 64 guests in CH₄-filled sI, 192 in CH₄-filled sII | Reports a missing input on the water-only crystals. |

## Known mismatch: GRADE on periodic crystals

GRADE v1.00 tests whether a ring is planar using raw coordinates, without the minimum image. A ring that crosses the box edge is therefore dropped, and the cage count depends on where the box edge happens to fall: shifting and re-wrapping the same sI crystal gives between 2 and 9 of its 16 small cages. ClavisCage's GRADE matches the authors' program, so it keeps this behaviour, and these rows are listed as known mismatches rather than hidden by a looser tolerance. Use TRACE or HTR to count cages in a periodic crystal.

## Running it

```bash theme={null}
cd web-app/wasm-engine
cargo test --release --test benchmark_table
```

The run takes several minutes and rewrites `benchmarks/results.json`; two runs give the same file byte for byte.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.