PhysioTwin

An interactive 3D human physiological digital twin, with real equations in place of canned animations

▶ Try it in your browser (nothing to install) · ⬇ Download for Windows · 📖 User manual

PhysioTwin connects a clickable 3D human body to a mechanistic physiology engine: a coupled system of differential equations for the heart and circulation, breathing and gas exchange, oxygen transport, fluid balance and acid–base chemistry. Start an exercise test, cause a haemorrhage or make someone anaemic, and watch heart rate, blood pressure, ventilation, oxygen saturation, lactate and pH respond. Every number on screen is computed by the model, every equation is documented, and every parameter states where it comes from.

⚠️ Educational and research prototype, not a medical device. Results come from simplified models with partly assumed parameters; they are not clinical predictions.

Features

• Live physiology engine: 15-state ODE model (SciPy LSODA), about 690× faster than real time, bitwise reproducible.
• 12 scenarios: rest, moderate and heavy exercise, anaemia, haemorrhage, fluid deficit, IV fluids, weak heart, respiratory impairment, low-oxygen air, hypoventilation, and more.
• Guided lessons: the simulation pauses at key moments, explains what is happening with its live values, highlights the organ, sets the graphs and asks a quick-check question.
• 3D anatomy from the Human Reference Atlas (heart chambers and valves, lungs and airways, kidneys, liver, brain, vessels). Click any part to inspect it. The heart beats at the simulated heart rate and the lungs breathe at the simulated rate and depth.
• Experiments: change parameters live, save and reload runs, compare two runs, and export CSV/JSON with full metadata.
• Runs anywhere: in the browser (the Python engine runs locally via WebAssembly/Pyodide), as a Windows download, or from source on Windows, macOS and Linux.
• Honest science: 61 machine-checked acceptance criteria, a numerical verification report, and a comparison with published data that includes where the model fails.

Quick start

No install: open the web version. The first visit downloads about 30–40 MB (Godot runtime, plus Python, NumPy and SciPy for WebAssembly) and may take a minute; later visits use the browser cache. The physiology runs on your own computer, inside the browser tab.

Windows app: download the zip from Releases, unzip it and double-click PhysioTwin.exe. The bundled engine starts automatically.

From source (Python ≥ 3.10 and Godot 4.7):

git clone https://github.com/salmand-dev/PhysioTwin.git
cd PhysioTwin
bash tools/setup/start_engine.sh                            # Windows: powershell -ExecutionPolicy Bypass -File tools/setup/start_engine.ps1
GODOT_EXE=/path/to/godot bash tools/setup/start_godot.sh    # or open godot_app/project.godot in Godot and press F5

Headless, without Godot: cd physiology_engine && .venv/bin/python -m app.cli run exercise_heavy

Screenshots

Guided lesson: haemorrhage and the baroreflex	Heavy exercise: lactate, pH and ventilation
Scenario selection with an explicit "not applied" state	Parameters show the engine's current values

How it works

Godot 4.7 app (3D body, dashboard, lessons)
      │   desktop: REST + WebSocket on 127.0.0.1      browser: JavaScript bridge to Pyodide
      ▼
Physiology engine (Python): circulation ─ fluid balance ─ ventilation ─ gas exchange ─ metabolism ─ acid–base
      one coupled ODE system, evaluated in a fixed order in every right-hand-side call (no stale coupling)

• Architecture · Equations · Parameters and sources · API · Web version
• Validation results · Reference comparison · Assumptions and limitations
• Future AI plan (Google Colab): designed and specified; no AI is implemented yet.

Scientific status

Check	Result
Software tests (engine, API, browser engine, lessons, Godot app)	✅ passing (see CI)
Numerical verification (solver agreement, conservation, reproducibility)	✅
Qualitative scenario criteria	✅ 61/61
Exercise cardiac output vs O2 uptake (Siebenmann 2015)	✅ within the 95 % CI
Severe anaemia response (Weiskopf 1998)	✅ 7/7 directions
Haemorrhage vs ATLS classes	❌ heart rate too low and BP fall too large (details)
Clinical validation	Not performed (and not claimed)

Contributing

Scenarios and lessons are plain data, which makes them a good first contribution. See CONTRIBUTING.md and the issues labelled good first issue. Scientific corrections with references are especially welcome.

Citation

If PhysioTwin helps your teaching or research, please cite it (see CITATION.cff).

Licences and attribution

• Code: MIT (LICENSE).
• Anatomy: Human Reference Atlas 3D Reference Organs (HuBMAP / CNS, Indiana University; derived from the NLM Visible Human Project), CC BY 4.0, modified (merged, decimated, recoloured).
• Font: Figtree, SIL Open Font License 1.1.
• Web runtime: Pyodide (MPL-2.0), loaded from the jsDelivr CDN; Godot Engine (MIT).