Skip to content

Architecture

Stable center, replaceable physics

The code is divided by the rate and reason it changes.

recipe ──> DeviceCase ──> geometry / resonance / observables / FDTD
   │             │
   │             └──── produces common EvaluationRecord objects
   │
   └──> iteration policy ──> DirectionGate ──> accept or rollback
                                  │
                                  └──> calibration and validation evidence

The contracts in src/cavitygrad are deliberately small:

  • GeometryVector gives every parameter a stable name, unit, order, and optional bound. Its digest prevents comparisons across mismatched geometry.
  • Pole fixes the time convention, passivity requirement, branch label, and Q identity.
  • ObservableSet distinguishes mode volumes, channel decay fractions, and external quality factors. Missing quantities are absent rather than guessed.
  • EvaluationRecord joins one immutable geometry to one fidelity, recipe version, iteration, numerical result, and provenance record.
  • DirectionGate compares the identical before/after pair at both fidelities.
  • CostLedger reserves the maximum estimated cloud cost before a job starts and settles conservatively if actual billing is unavailable.

Device boundary

A device case supplies four implementations:

Contract Responsibility
GeometryModel constraints, transforms, symmetry, and backend-neutral geometry
ResonanceEngine nonlinear pole solve, branch continuation, residual, and pole gradient
ObservableEvaluator analytical Q, volume, and named decay channels
FDTDBackend simulation construction, cost estimate, explicit submission, and monitor analysis

The current historical runners predate these contracts. Their recipes point to the frozen implementations. The read-only legacy adapter translates their run_state.json ledgers into the common records without importing the runner or contacting Tidy3D. New device work should implement the contracts directly; established numerical kernels can be imported behind them without changing their equations.

Dependency direction

Core models use only the Python standard library. Analytical implementations may depend on NumPy/SciPy. FDTD implementations alone may import Tidy3D. Docs, tests, and recipe discovery must work without an API key. This keeps local iteration fast and prevents an innocent import from becoming a cloud action.

Data is part of the API

Every run should be reconstructible from:

  • recipe file and package revision;
  • canonical geometry vector and units;
  • analytical truncation, contour, and pole seed;
  • serialized Tidy3D simulation and installed Tidy3D version;
  • raw monitor data or immutable task ID;
  • extracted observable record and diagnostic plots;
  • gate decision, trust-radius change, and cost ledger entry.

Generated plots and reports are views. JSON records and raw simulation data are the evidence.