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

# Adding a Method

> What a method request needs, how methods are verified, and which code can be used

# Adding a Method

ClavisCage aims to offer every published method for finding hydrate cages and classifying water structure, each one verified. Every method lives in the engine (`web-app/wasm-engine`), so the web app and the Python package run the same code. A method describes itself to the app: its parameters, what it returns, and how it can be shown. A new method therefore appears on the BLOCKS shelf, in LIBRARY, in Results, in CSV export and in recipes without app-specific code. Tetrahedral order was added this way.

## Requesting a method

Open an issue titled `Method request: <name>` with:

| Field | What to give |
| - | - |
| Paper | Full reference and DOI. If the method was refined later, give the version you want. |
| Inputs | What the method reads: oxygens only, hydrogens, guests, a trajectory rather than one frame. |
| Outputs | Per-frame numbers, per-water values or classes, or cages. |
| A fixture with its expected output | A small structure and the answer the method must give on it, ideally one that does not depend on any program (an ideal crystal, a hand-built cluster). |
| Code, if any | Repository URL and its licence. Say if there is no public code. |

A request is easier to accept when the expected output comes from the authors' own program or from an established open implementation, because that sets the verification tier.

## Verification tiers

Each method carries a level, shown in LIBRARY and on its result block:

| Level | Meaning |
| - | - |
| **T3** | Matches the authors' own program on reference inputs (TRACE, HTR, GRADE). |
| **T2** | Matches an established open implementation within a stated tolerance (averaged Steinhardt vs freud; tetrahedral order vs GROMACS `gmx order`). |
| **T1** | Implemented from the paper and checked on cases whose answer is known by construction (CHILL+, F3/F4, MCG). |
| **T0** | Implemented from the paper only. |

A method's level never rests on a claim. It rests on the fixtures listed in its descriptor and on the engine tests that check them. The [benchmark](https://docs.claviscage.app/analysis/benchmark.md) runs every method on ideal GenIce2 crystals and shows where each one stands.

## The spec-gap rule

Papers often leave details open: which neighbours count, how ties are broken, how a sum is normalised. Before a paper-only method is written, its spec lists each open detail and the choice made for it. These are the descriptor's `spec_gaps`, and they appear in LIBRARY. **A method with more than two open details is not shipped** until the authors' code, an open reference or a correspondence with the authors closes them. Two guessed details can still be checked; more cannot.

## The licence rule

The engine is GPL-3.0-or-later.

* Code under GPL, LGPL, MIT, BSD or Apache licences may be ported into the engine. Its notice is kept in the source file and listed in `NOTICE`.
* Code with no licence, or with a licence that forbids it, is **never ported or redistributed**. It may be cited, and its published outputs may serve as reference values with their source named. HTR's public code, for example, declares no licence. ClavisCage's HTR is checked against the authors' published program and does not include its code.
* Model weights follow the same rule as code.

## What a method needs to land

1. A descriptor in `src/methods.rs` with the citation, DOI, tier, inputs, parameters with ranges, series, views, fixtures and spec gaps.
2. The implementation, exposed through `run_method`, with Rust tests on its fixtures.
3. Reference data under `tests/fixtures/reference/<method>/` with a provenance note (program, version, command).
4. A row in the benchmark table.
5. Python parity in `pytests/`, and the descriptor snapshot regenerated (`UPDATE_DESCRIPTOR_SNAPSHOT=1 cargo test --lib descriptor_snapshot`).


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