# Architectural and scientific decision record

- Scope: Phase 1 six-compartment, closed-loop, deterministic ODE prototype. No patient data, remote deployment, or clinical prediction.
- Independently developed model and annotations. External source code is not executed. Source/license review is delegated separately.
- Compartment volumes are state variables; pressure and flow are algebraic observables. This permits direct conservation auditing.
- Ontology annotations describe mathematical variables; annotations alone do not establish biological compatibility or model validity.
- Local concepts must be explicitly distinguished from verified external ontology concepts.
- Baseline and reduced-contractility experiments use the same numerical engine, not adjusted outputs.
- Mechanistic intervention effects are parameter changes, not drug-dose predictions.
- Verification distinguishes implementation correctness, broad plausibility, and external biological validation. The latter is not established by this milestone.
- Renal feedback and clinical therapy models are deferred until the cardiovascular core passes verification.
- Roles: Agent A model/equation implementation; Agent B semantic implementation; Agent C independent scientific source review, followed by independent code verification; parent integration and reproducibility.
- Canonical experiment: 60 cycles, DOP853 rtol=1e-9, atol=1e-10 mL, max step T/200, 400 output samples/cycle. This is tighter than the core API defaults; full default-tolerance transients showed a non-negligible refinement difference.
- Milestone periodicity gate: <=0.1 mL last/prior-beat six-volume waveform difference. The broader prospective 1e-4 mL for multiple successive beats is not silently substituted or claimed complete.
- Integration review corrected SV annotation to the actual flow-integrated metric, added executable numeric bindings, and limited gauge-pressure references to pressure variables.
- Synthetic benchmark deliberately retains a false acceptance: actual RV output with falsely assigned LV metadata. Metadata validation is not numerical provenance validation.
- Package was built as a wheel, installed in a separate environment, and executed twice in isolated Python mode. Numerical CSV replay and parsed summaries matched exactly on this host; no cross-platform identity claim.
- Smith 2004 OpenCOR reference run (2026-11-01, user-approved): fixed-step RK4 replaces CVODE only, because the default run failed with a KINSOL iteration-limit error. KINSOL, model, parameters and units are unchanged; results are labelled RK4 and do not explain the CVODE failure.
- Smith 2004 run comparison (2026-11-01, user-approved): output times are treated as equal when |dt| <= 1e-9 s (far below the 5e-6 s smaller step). Applies to the time axis only; raw CSVs are not altered, and the tolerance was fixed before inspecting value differences.
- Smith 2004 RK4 value comparison (2026-11-01, user-approved): report-only, no pass/fail line. The literature read (Pathmanathan & Gray 2013 and 2014, Erdemir 2020, Santiago 2022, Mulugeta 2018) prescribes a verification procedure but no universal numeric acceptance threshold; the level is set by context of use, and this project is an exploratory prototype. Step-halving results (observed order and error per quantity of interest) are reported without being declared passed or failed. A passing result would still not establish scientific validity.
- Smith 2004 time-stamp tolerance (2026-11-01, user-approved, supersedes the 1e-9 s entry above): the 1e-9 s value was chosen by the assistant, not taken from literature. Output times count as equal when |dt| <= N_steps * eps(2.22e-16) * t_max (about 1.0e-10 s for 3.0e5 steps to 1.5 s). It rests on IEEE 754 double arithmetic, not on biomedical literature.
- Smith 2004 step sizes (2026-11-01, user-approved): a third RK4 step size, 2.5e-6 s (run C), is added to 1e-5 s and 5e-6 s so an observed order of convergence can be computed; two sizes cannot give one.
- Smith 2004 run C and scalar definitions (2026-11-01, user-approved, fixed before run C results exist): run C changes only the integration step (2.5e-6 s); the output interval stays 0.001 s as in A and B (1,501 rows each, not one row per integration step). A, B and C are compared by the same output index, with time-stamp equality checked by the derived bound above and N_steps = 1.5 / the run's integration step. Scalars: stroke volume per beat = trapezoidal integral of max(Q_av, 0) over the CSV samples; valve opening = first sample with Q_av > 0, closing = first later sample with Q_av <= 0, no interpolation; beats are 0-0.75 s and 0.75-1.5 s, with the 0.75 s sample in both. Valve times therefore have 1 ms resolution and are reported, not used as a convergence measure. The optional negative-flow integral (min(Q_av, 0)) was not adopted; negative Q_av values and their sample-time spans are only recorded. Adding it after run C results exist would no longer be fixed in advance.
- UI sample data (2026-11-01, user-approved): sample values, graphs and relations hard-coded in the separate React UI repository (read-only check of main 6433bf5, mainly `src/lib/evidence.ts` and `src/lib/ontology.ts`, reported by another agent and not seen here) are excluded from all research evidence and calculations. When real results are connected, the UI must label sample and real outputs distinctly and must not fill missing data with sample values.
- Current numerical baseline is elevated-pressure and all default values remain exploratory; no tuning was performed to manufacture normality or positive findings.
- Evidence review before any OWL (2026-11-01, per the user's brief): candidate concepts and relations for the Smith 2004 model are proposed only with a quoted source location (`docs/evidence_review/`); abstract-only sources fix no relation direction or mapping; unresolved points stay `UNKNOWN`. Numeric cross-model comparison with the CellML is blocked until the kPa-versus-mmHg label conflict (C1) is settled from the 2004 paper. The SemSim reference annotation of the model (PMR workspace 267) is treated as evidence of practice, not authority; its defects are recorded, not copied. A manual comparison group receiving the same material is designed before any ontology benefit is claimed.
- C5 bearer form (2026-11-01, user decision): adopt `Portion of blood part_of cavity/lumen` over organ-only anatomy (for example, fma9670 part_of fma9466 for the LV cavity; S9 PMR workspace 267 annotation, S11 FMA 5.1.0, `docs/evidence_review/evidence_review.md` Q1/C5). This is a project decision, not a new scientific finding or a claim of physical equivalence between lumped compartments and named lumens. Registry implementation remains unchanged (LV fma7101, RV fma7098) and deferred.
- Pressure reference (2026-11-01, user decision): pressure reference is expressed as the sink of an energy differential, following OMEX metadata specification v1.2 §2.3.7.3 and SemGen annotation protocol step 5 (`docs/evidence_review/evidence_cards.md` S16 item 9, S21). Chamber pressures P_lv, P_rv, P_ao, P_vc, P_pa, P_pu have an unspecified sink, that is the model's common ground; free-wall pressures P_lvf, P_rvf have the contents of the pericardial space as sink. The external-pressure terms in each pressure law (none for P_ao, P_vc; P_th for P_pa, P_pu; P_peri = P_pcd + P_th for P_lv, P_rv) are dependency structure, not reference points, and are recorded under Q2. Whether the common ground equals atmospheric pressure is UNKNOWN from the CellML. The FMA entity for "contents of the pericardial space" is not yet selected (fma9887 is the candidate used in S9). Documentation only; the registry `reference` string is unchanged. This supersedes the four-value vocabulary proposed earlier the same day, which classified external-pressure terms rather than reference points.
- C1 units and the R13 numeric block (2026-11-01, user decision): the canonical CellML's pressure, elastance, resistance and inertance values are read in mmHg-based units (mmHg, mmHg/mL, mmHg·s/mL, mmHg·s²/mL); its kPa labels are treated as mislabels and no conversion factor is applied. This lifts the block on numeric comparison with the CellML set in the evidence-review entry above (R13). Basis: the 2004 author manuscript uses mmHg, ml and s throughout and never kPa, including the inertance unit "L = 10^-6 mmHg s^2/ml" (`docs/evidence_review/evidence_cards.md` S6P); Paeme 2011 Tables 1-3 give the same numerals with mmHg-based units and P_th = -4 mmHg (S17); the six CellML initial volumes sum exactly to the manuscript's 1500 mL stressed volume; and the unmodified CellML run C gives P_ao 79-116, matching the manuscript's target of about 120/80 mmHg, whereas a kPa reading would mean about 590-870 mmHg. Remaining uncertainty: the manuscript tabulates no parameter values, so no individual numeral's unit is stated by the authors; values Paeme does not tabulate (R_sys, R_pul, and E_ao, which Paeme prints as 0.0) rest on the unit system and magnitudes alone. The CellML file and the OpenCOR outputs are not edited; existing outputs labelled kPa are read as mmHg. Every numeric comparison cites this entry. The structural differences C3, C7, C9 and C10 are not affected, and comparison results stay report-only under the value-comparison entry above.
- Correction to the Smith 2004 OpenCOR reference run entry (2026-11-01, user-approved): its phrase "the default run failed with a KINSOL iteration-limit error" is an inference from the error wording. The recorded error, "std::runtime_error: the maximum number of iterations was reached before convergence", does not name a solver, so whether CVODE or KINSOL failed is UNKNOWN (`docs/evidence_review/prov/smith2004_opencor_runs.ttl`, solverAttributionStatus; `docs/orchestration_state.md`, "Cause not established"). The RK4 decision does not depend on the attribution and stands: RK4 replaced CVODE only, KINSOL stayed in use, and runs A, B and C completed.
- Anatomical structures as nodes (2026-11-01, user decision): every anatomical structure that a variable, process or equation of the model refers to is an explicit FMA node in the annotation graph, not only text. For the Smith model this adds the four valves: each valve flow's process is linked to its valve with bqbiol:occursIn ("physically limited to a location", BioModels.net qualifiers 1.1; `docs/evidence_review/evidence_cards.md` S22): Q_mt -> Mitral valve fma7235, Q_av -> Aortic valve fma7236, Q_tc -> Tricuspid valve fma7234, Q_pv -> Pulmonary valve fma7246 (OLS FMA 5.1.0). The inventory of structures and their node status is in `docs/evidence_review/evidence_review.md` (Q1). Not yet decided: how to represent structures the model lumps (the atria, merged into the venous compartments) and whether structures the model omits get nodes. Documentation and SHACL only; the registry is unchanged.
- Atria as separate nodes (2026-11-01, user decision, completing the previous entry): the left and right atrial cavities are explicit FMA nodes (Cavity of left atrium fma9465, Cavity of right atrium fma11359). Each Smith venous compartment is a composite portion of blood with bqbiol:hasPart parts ("includes ... either physically or logically", BioModels.net qualifiers 1.1, S22): the pulmonary venous compartment = blood in Lumen of pulmonary venous tree organ fma52455 + blood in Cavity of left atrium; the vena cava compartment = blood in Set of lumens of vena cava trunks fma280059 + blood in Cavity of right atrium. Basis and status: the manuscript says "The atria have not been added as they contribute only minimally to main cardiac trends" (S6P p. 6); that their volume sits in the venous compartments is an interpretation, supported by Pironet 2013 for the pulmonary side ("they are merged with the pulmonary vein compartment", S19) and by the Figure 1 pressure points "P.la" and "P.ra" at the mitral and tricuspid inlets (S6P). This makes the mitral and tricuspid flows start from blood that includes the atrium their valve opens from. Whether structures the model omits entirely (for example the valve of the inferior vena cava) get nodes is still open. Documentation and SHACL only; the registry is unchanged.
- Anatomical node specification v2 (2026-11-01, user directive that nodes be established from the latest knowledge): `docs/evidence_review/anatomy_nodes_v2.md` is the current node list. Identifier rule: the Uberon term when Uberon has the same structure (matched by its FMA cross-reference), otherwise the FMA term, with the other identifier recorded on every node; vessel lumens therefore stay FMA. Basis: SPARC, SCKAN and HRA practice (evidence_cards.md S23), Uberon actively released (2026-10-01, CC BY 3.0) while FMA is listed inactive (5.1.0, 2026-05-15, CC BY 4.0); OMEX metadata v1.2 still recommends FMA (S16). The peripheral compartments are read as lumped arterial and venous beds per the manuscript ("elastic chambers, simulating the arteries and veins", S6P), so the "aorta" and "vena cava" compartments map to the systemic arterial and venous tree lumens, and P_pa and V_pa share the pulmonary arterial tree lumen. The minor heart valves, the venae cavae and the coronary sinus are catalogue nodes (S24). Not yet propagated to the SHACL shapes, fixtures, ws267 translation or registry.
- Node specification v2 propagated (2026-11-01, user-approved): the SHACL shapes, fixtures and dependency file use the v2 primary identifiers; a new rule S7 checks each Smith compartment volume against its v2 container; the ws267 translation rewrites FMA identifiers to Uberon only where the Uberon term carries the same FMA cross-reference and keeps all others; the runner rejects any anatomical identifier that is not a v2 primary identifier. The registry is unchanged.
- Node specification v2 applied to the registry (2026-11-01, user decisions: apply only the changes the recorded sources cover, "A1–A9만 먼저"; use the standard bqbiol predicates, "표준 bqbiol 사용"): `src/physiosim/ontology` now uses the v2 identifiers (Uberon primary, FMA cross-reference kept as `Concept.xref`) for every node it refers to: blood UBERON:0000178 (FMA:9670), heart UBERON:0000948 (FMA:7088), heart left/right ventricle UBERON:0002084/0002080 (FMA:7101/7098), cavity of left/right ventricle UBERON:0016514/0016509 (FMA:9466/9291), and the aortic, mitral, tricuspid and pulmonary valves UBERON:0002137/0002135/0002134/0002146 (FMA:7236/7235/7234/7246), all from `docs/evidence_review/anatomy_nodes_v2.json`. Following C5, V_lv, P_lv, V_rv and P_rv are properties of blood that is `bqbiol:isPartOf` the ventricular cavity, and the cavities are the LV and RV flow endpoints. Following "Anatomical structures as nodes", Q_aortic, Q_mitral, Q_tricuspid and Q_pulmonary_valve carry `bqbiol:occursIn` their valve, and the connection validator compares that location. E_lv, E_rv, CO and SV keep the organ-level ventricle and HR the heart, with v2 identifiers only. C1 needs no change: registry units are already mmHg-based and no conversion factor is added. Not decided and left unchanged: (G1) whether the project's local `sa`, `sv`, `pa`, `pv` compartments map to the v2 vessel-lumen nodes, which describe the Smith compartments (`evidence_review.md` R6, R8 require a human-asserted mapping); (G2) whether the project's venous compartments include the atria, which conflicts with `independent_verification.md` and `tests/test_independent_verification.py` (P_pv local, not atrial); (G3) whether E_lv/E_rv belong on the v2 ventricular-wall nodes, which are Smith's free walls, and which node bears the vessel compliances C_sa..C_pv (v2 has no vessel-wall node); (G4) whether the valve resistances are located at their valve; (G5) the systemic and pulmonary bed flows and resistances and V_total, which have no v2 node and stay local; (G6) the pressure `reference` string, still "model gauge pressure; fixed external pressure zero", since the energy-differential entry above leaves the registry string unchanged and whether the common ground is atmospheric is UNKNOWN. Decided (G7, RDF vocabulary): the standard `bqbiol:isPartOf` and `bqbiol:occursIn` are used for these two relations, all other relations stay project-local, and no conformance to the qualifier vocabulary as a whole is claimed. The committed `results/phase1/` and `results/replay/` exports were not regenerated and still show v1 identifiers. Physical equations, parameters, solver settings and test tolerances are unchanged.
- M1 passive atria (2026-11-01, owner-authorized software milestone): add versioned `four_chamber_m1` with separate LA/RA blood volumes and constant positive atrial elastances. An explicit named eight-edge incidence matrix connects four ideal diodes and four signed resistors. Reuse the legacy ventricular activation without changing the six-compartment implementation or existing identities. All atrial/venous-inflow inputs and eight initial/unstressed volumes are mandatory; new fixture values are synthetic test-design choices, not literature-derived physiology. Total volume is declared by caller initialization, never normalized. All pressures use one fixed external-zero mathematical gauge; no atmospheric-reference assertion. The offline v2 anatomy nodes are checked under a new model-specific contract with cavity containment, vascular context and valve-location relations; the v2 Smith lumped-atria interpretation is recorded as a source/model difference, and the old registry is untouched. Cumulative flows are run-integrated volumes, SV is beat-integrated, CO is beat-mean. Event-aware integration and preregistered software bounds are documented in `docs/physiology_four_chamber_m1.md`. No active atria/AV delay, inertance, FSI, regurgitation, calibration or clinical-validation claim is introduced.