Skip to main content

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: 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: 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 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).