ADR 0003: SI units at interfaces, scaled variables inside integrators

• Status: Accepted (2026-11-10)
• Date: 2026-11-10
• Deciders: Vincent Mader
• Related: Finding F5; notation.md

Context

The thesis uses SI, Dullemond’s code uses cgs. N_k spans many decades (about 3·10² m⁻³ for monomers at 10 au, far less for large bins) and time spans 1 s to 10¹¹ s. scipy defaults (rtol 10⁻³, atol 10⁻⁶) were used without scaling, so small bins were not error controlled.

Decision

All public APIs, configs, and outputs use SI units (kg, m, s, K), with documented convenience units only in config input (au, solar mass, year), converted at parse time. Integrators work on scaled variables: y_k = N_k m_k / ρ₀ (mass fractions per bin) by default, time in units of a reference collision time; tolerances are given in scaled form (rtol, atol_scaled). Conversions live in coag-core and are tested for round trips. Comparisons with coag_py convert cgs at the fixture boundary.

Alternatives considered

• cgs throughout (astro convention): conflicts with the thesis and its figures, invites mixed-unit bugs at the thesis parity boundary.
• A typed units crate (uom): strong guarantees but heavy generics in hot loops and awkward in wasm/PyO3 interfaces; reconsider if unit bugs appear.
• Unscaled N_k in the integrator: reproduces the thesis tolerance problem.

Consequences

• Error control becomes meaningful for every bin (mass-weighted).
• Every interface must say its unit; doc comments state units for each quantity.
• Parity tests with the thesis must use the thesis’ unscaled tolerances when reproducing its behavior.