ADR 0001: Runtime and numerical contracts

ADR 0001: Runtime and numerical contracts#

Context#

waxMorph exposes a prescribed forward simulator, a learned emulator, and Torch and JAX learning backends. These paths share state abstractions and provide purpose-built kernels, constants, interfaces, and runtime contracts. Cross-cutting numerical and acceptance contracts define how they compose.

Decision#

  1. Coordinates, radii, timesteps, and coefficients use nondimensional model units. External calibration maps them to SI or biological scales.

  2. Physical radii below their growth target increase up to that target. Radii at or above target pass through unchanged. Mesenchymal equilibrium radii are capped at R_max; epithelial equilibrium radii copy through while physical radii approach R_ref.

  3. Chamfer loss is the sum of Euclidean directional means:

    \[ \frac{1}{N}\sum_i\min_j\lVert x_i-y_j\rVert_2+ \frac{1}{M}\sum_j\min_i\lVert x_i-y_j\rVert_2. \]

    Inputs are nonempty rank-2 arrays with equal feature width. Nearest-neighbor ties remain nonsmooth and follow backend-specific gradient conventions.

  4. n_epochs counts optimizer updates. Histories and model selection describe the resulting models, requiring one extra evaluation. The returned model, best loss, epoch, and trajectory refer to the same post-update state.

  5. Top-level imports eagerly expose the default Torch API. NumPy, SciPy, Torch, tqdm, and Warp are core dependencies; JAX, GeomLoss, and rendering stacks remain optional.

  6. Polarity vectors supplied to graph construction must have unit norm. Edge features clamp their raw supplied dot product before acos.

  7. Forward evolution rebuilds contact topology. Each differentiated graph or physics operation holds that topology fixed while gradients cover continuous state arithmetic; neighbor search and edge updates define the discrete topology input.

  8. Numerical acceptance requires CPU and CUDA verification. CUDA checks must prove Torch, JAX, and Warp device placement and record execution of GPU atomics and both Torch/Warp and JAX/Warp gradient paths.

Consequences#

  • External calibration supplies physical interpretation for model values.

  • Growth passes through incoming radii at or above their targets.

  • The initial model evaluation supplies the first gradient. The updated models form the selection candidates, and evaluation cost is one rollout greater than the update count.

  • Differentiation follows a piecewise-smooth surrogate within each fixed topology.

  • Eager imports provide an unconditional default API with its core dependency closure.

  • Release acceptance combines CPU CI and CUDA verification. JAX/Warp mechanics and diffusion run on a CUDA-backed JAX device.