Experimental Phase 1 research software. Not for diagnosis, treatment selection, or patient-specific prediction. No patient data are used. Numerical simulation is deterministic and requires no LLM or network connection after installation.
All physiological numeric defaults are exploratory, not fitted literature parameters. The baseline is elevated-pressure and must not be described as a healthy adult reference. Structural equations were informed by inspected sources, but this simplified model does not replicate a published reference trajectory.
Prerequisites: Python 3.11+ and uv, or an equivalent Python virtual-environment/pip workflow. Commands below were exercised using Python 3.11.15 on macOS ARM64. Run from this directory:
uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python -r requirements.lock -e .
.venv/bin/python -m physiosim --config experiments/phase1.json --output results/phase1
.venv/bin/python -m pytest -q --junitxml=results/tests.xml
Once installed, physiosim --config experiments/phase1.json --output results/phase1 is the equivalent console command when the virtual environment is activated. Dependencies are pinned in requirements.lock; automatic downloads are only needed during installation.
Open results/phase1/index.html locally in a browser. No web server is needed. On macOS:
open results/phase1/index.html
Output files:
comparison.png: last three beats of pressure, flow, ventricular volume and an LV pressure-volume loop.transients.png: full-run pulmonary venous pressure and cycle-integrated cardiac output.{baseline,reduced_contractility,partial_contractility_restoration}.csv: time in seconds; six volumes in mL; six pressures in mmHg; six directed flows in mL/s. Samples include the initialization transient. These are uniformly sampled solver outputs, not native adaptive solver steps.summary.json: exact parameters, perturbations, solver settings, final-beat metrics and audits.variables.json, annotations.trig: machine-readable variable metadata and RDF named graphs.semantic_benchmark.json: every synthetic connection fixture, decisions and confusion counts, including a known false acceptance.manifest.json: dependency/platform information, configuration hash, implementation hashes and output checksums.Exit status 0 means all scenarios passed the runtime conservation/positivity/valve audit and the declared sampled periodicity gate. Status 2 preserves output but marks at least one scenario as transient/nonperiodic. Status 1 indicates an execution/configuration error. Passing these checks is not biological validation.
The canonical experiment uses 60 cycles, 400 samples/cycle, DOP853, rtol=1e-9, atol=1e-10 mL and maximum step T/200. Its periodicity gate is a maximum six-volume last/prior-beat waveform difference of 0.1 mL. This is a modest software milestone gate, not the stricter prospective multi-beat convergence protocol in docs/verification_protocol.md.
uv build --wheel
uv venv --python 3.11 .clean-venv
uv pip install --python .clean-venv/bin/python -r requirements.lock dist/ontology_physiosim-0.1.0-py3-none-any.whl
.clean-venv/bin/python scripts/verify_reproducibility.py
.clean-venv/bin/python scripts/verify_independent.py
.clean-venv/bin/python -I -m pytest -q --junitxml=results/tests.xml
.clean-venv/bin/python scripts/generate_report.py
The reproducibility script invokes the installed wheel twice in isolated Python mode, checks numerical CSV byte identity and summary equality, and writes results/reproducibility.json. It also verifies that the import came from site-packages, not an editable source checkout. This demonstrates same-host/same-dependency replay, not cross-platform bitwise identity. RDF serialization ordering is not used as a numerical reproducibility criterion.
from dataclasses import replace
from physiosim.models import Parameters
from physiosim.simulation import simulate
from physiosim.ontology import cardiovascular_registry, UnitConversion
from physiosim.ontology.bindings import connect_value
p = Parameters()
result = simulate(replace(p, emax_lv=p.emax_lv * 0.5),
cycles=60, rtol=1e-9, atol=1e-10,
max_step=p.period / 200)
print(result.metrics())
registry = cardiovascular_registry()
target = replace(registry['CO'], name='consumer_CO', unit='L/min')
co = connect_value(result, 'CO', target,
conversion=UnitConversion('mL/s', 'L/min'))
validate_connection checks direct variable equivalence, not causal adjacency. A pressure port cannot be directly equated to a flow port; the component's mathematical resistance law must implement that relationship. connect_value actually applies the checked conversion. The topology is still statically implemented; this is not an automatic multi-model ODE composer.
ParameterChange.apply makes an immutable dataclass replacement and an audit record. Its time_s is recorded metadata, not a scheduler. The canonical runs apply changes at time zero. No drug-dose or PK/PD model is included.
docs/physiology.md: adopted/modified equations, every parameter, assumptions, units, source evidence and core API.docs/ontology.md: exact concept URIs, provenance, local concepts, connection rules and limitations.docs/ecosystem.md: inspected existing repository and Physiome/CellML, OpenCOR, SemSim/SemGen, CircAdapt and Pulse access/license findings. No external simulation code was executed or incorporated into the numerical engine.docs/verification_protocol.md: broader prospective scientific verification plan; not every proposed gate is implemented.docs/independent_verification.md: independent executed checks and remaining gaps.docs/research_report.md: generated current results, failures, claim boundaries and next steps.docs/decisions.md: concise architecture/scientific decision record.docs/evidence/: retained retrieval evidence, citation ledgers, parameter provenance and verification records.docs/evidence_review/: 2026-11-01 literature evidence review for the Smith 2004 semantic layer: evidence cards with quotations, a 76-variable/32-equation dictionary of the canonical CellML, candidate concepts, unresolved conflicts (including the kPa/mmHg label question) and rejected connection cases. Review only; no OWL, model or registry change. Earlier development outputs are historical; results/phase1/ is the canonical current experiment.The model omits separate atria, septal/pericardial interactions, valve inertia, nonlinear passive ventricular mechanics, reflexes, renal regulation, respiration, oxygen transport and pharmacology. Positive parameter values are only a mathematical-domain check, not validated physiological ranges. Pulmonary venous pressure is a lumped reservoir pressure, not a measured atrial pressure or evidence of pulmonary edema.
The semantic benchmark is a small hand-designed synthetic fault-injection experiment. Its unassisted condition accepts submitted mappings without checking; no human productivity study was conducted. Correct-looking metadata attached to the wrong numerical data remain a deliberately demonstrated failure. Ontology-guided reliable model composition remains a research hypothesis.
Before cardiorenal coupling, prioritize a licensed reference-model reproduction with parameter-level provenance, better pressure/flow waveform calibration, stronger periodicity and sampling checks, and uncertainty/sensitivity analysis. A subsequent renal research spike should define an explicit renal perfusion-flow port and an external fluid-balance source/sink contract, then test conservation with those sources/sinks. GFR, sodium balance, RAAS and drug predictions remain unimplemented. No Streamlit service, deployment, remote push or clinical model has been created.
Passive atrial extension: four_chamber_m1 provides a separate eight-volume explicit-parameter engine and a synthetic demo; the six-compartment API remains available.