Architecture Decision Records (ADRs)¶
These records capture load-bearing decisions — the ones where the non-obvious choice is the rejected alternative, and where a future contributor (or a future us) might otherwise re-litigate a question that was already settled, sometimes expensively.
aeolus1d has a bus factor of ~1; much of the design rationale lived only in an out-of-repo working memory. These ADRs port the most consequential of those decisions back into the repository so the why travels with the code (plan MR-9 / 4.2).
What is and isn't an ADR here¶
An ADR records a decision that:
- changed (or deliberately didn't change) the architecture or numerics, and
- has a rationale that isn't recoverable by reading the code alone — usually because the interesting part is the alternative we ruled out and why.
Routine fixes, feature additions, and anything fully explained by the code +
its tests do not get an ADR. The changelog and docs/phase-log.md cover
those.
Format¶
Each record is NNNN-short-slug.md with: Status, Context,
Decision, Consequences, and (where useful) Alternatives
considered. Numbers are monotonic and never reused; a superseded ADR keeps
its file and gains a Superseded by ADR-XXXX status line rather than being
deleted.
Index¶
| ADR | Title | Status |
|---|---|---|
| 0001 | Operator-split stiff chemistry (LSODA + Bulirsch–Stoer), not folded into the advection Newton matrix | Accepted |
| 0002 | Direct block-Thomas implicit solve; matrix-free JFNK removed | Accepted |
| 0003 | Canonical species Y_extras layout at the kernel boundary |
Accepted |
| 0004 | Implicit-upwind transport for quasi-steady species | Accepted |
| 0005 | Semi-implicit catalyst reaction-heat coupling | Accepted |
| 0006 | HLLC-core allocation micro-opt rejected; dev box is not a benchmark host | Accepted |
| 0007 | Versioned TOML case format with a named upgrade path | Accepted |
| 0008 | Compressible-orifice cylinder-valve coupling (mass-conserving) | Accepted |
| 0009 | Inflow-ghost composition for species mass conservation (flush products absent from the feed) | Accepted |
| 0010 | Verification & Validation strategy: order/MMS/conservation verification + calibration-vs-prediction + GCI/V&V-20 uncertainty | Accepted |
| 0011 | Non-positive density is a hard error, not a value to floor | Accepted |
| 0012 | The plenum port is a reservoir mouth, not a piston face | Accepted |
| 0013 | Cross a component boundary in conserved form, not primitives-plus-a-γ | Accepted |
| 0014 | Degenerate-composition γ policy | Accepted |
| 0015 | Struct-of-arrays network state, so a whole step can be compiled | Proposed |