RT-PDTG Documentation
The Real-Time Patient Digital Twin Generator is an AI-driven clinical simulation engine that creates a dynamic, physiology-based virtual replica of a patient. This wiki covers everything you need to understand how the system works.
01 Overview
The Real-Time Patient Digital Twin Generator is an AI-driven clinical simulation engine that creates a dynamic, physiology-based virtual replica of a patient.
RT-PDTG is designed for medical education — students, residents, and healthcare professionals can practice clinical decision-making in a safe, interactive environment. Unlike text-based case studies, the system simulates real-time physiological responses to disease progression and clinical interventions.
Key Principle
This is not a chatbot case generator. The system behaves causally — outputs are derived from modeled physiology rather than static scripts. Every vital sign, lab value, and system status is computed from interconnected physiological equations.
The platform covers 7 medical specialties with 90+ enriched patient cases, simulates 13 real-time vitals with live trend charts, tracks 5 physiological systems, renders 15 dynamic ECG waveform patterns, and provides comprehensive post-simulation evaluation with in-app adaptive learning.
02 How It Works
The simulation engine operates on a continuous 1-second tick cycle. Each tick, the physiology engine:
- Calculates disease progression — the underlying condition advances based on time and severity
- Applies intervention effects — any medications, fluids, or procedures modify physiological variables
- Computes interdependencies — changes cascade across interconnected systems (e.g., hypotension → renal failure)
- Updates vitals — all 13 monitored parameters are recalculated and displayed
- Evaluates system status — each of the 5 physiological systems is classified as Normal, Stressed, or Critical
Simulation Speed
The simulation runs in real-time by default (1 second = 1 simulated second). You can activate 5x fast-forward mode to accelerate disease progression and see the effects of your interventions more quickly.
03 User Flow
04 Physiology Engine
The physiology engine is the heart of RT-PDTG. It uses a deterministic + probabilistic modeling approach, functioning as a state machine where each patient state is computed from the previous state plus environmental changes.
- Structured Patient State Object — All data stored in a JSON-based state object with vitals, system statuses, active medications, and history
- Parametrized Disease Models — Each specialty case has modeled progression rates, severity curves, and expected physiological impacts
- Continuous Time Simulation — 1-second simulation ticks ensure smooth, realistic vital sign changes
- Event-Driven Architecture — State changes emit events that trigger UI updates, log entries, and cascade effects
05 Vitals & Parameters
The system monitors 13 physiological parameters in real time:
| Vital | Key | Unit | Description |
|---|---|---|---|
| Heart Rate | hr | bpm | Cardiac rhythm frequency |
| Blood Pressure | sbp/dbp | mmHg | Systolic/diastolic arterial pressure |
| Mean Arterial Pressure | map | mmHg | Average pressure during cardiac cycle |
| Cardiac Output | co | L/min | Volume of blood pumped per minute |
| SpO₂ | spo2 | % | Peripheral oxygen saturation |
| PaO₂ | pao2 | mmHg | Partial pressure of arterial oxygen |
| PaCO₂ | paco2 | mmHg | Partial pressure of arterial CO₂ |
| Respiratory Rate | rr | /min | Breaths per minute |
| Temperature | temp | °C | Core body temperature |
| GCS | gcs | 3–15 | Glasgow Coma Scale |
| Lactate | lactate | mmol/L | Tissue hypoperfusion marker |
| Creatinine | creatinine | mg/dL | Renal function marker |
| Glucose | glucose | mg/dL | Blood glucose level |
06 Interdependency Modeling
The engine models causal relationships between physiological variables. When one parameter changes, it cascades to affect others:
- Hypotension → Renal Failure — MAP below 65 mmHg reduces renal perfusion, causing creatinine to rise
- Hypoxia → Tachycardia — SpO₂ below 90% triggers compensatory heart rate increase and metabolic acidosis
- Insulin → Glucose + Potassium — Insulin administration drops glucose and shifts potassium intracellularly
- Rising Creatinine → Hyperkalemia — Renal failure prevents potassium excretion
- Low GCS → Respiratory Instability — Decreased consciousness impairs respiratory drive
Clinical Significance
These cascades mirror real clinical scenarios. For example, in sepsis: infection → vasodilation → hypotension → renal hypoperfusion → rising lactate + creatinine → multi-organ dysfunction.
07 Physiological Systems
Five organ systems are continuously monitored and classified into three states:
- 🟢 Normal — Parameters within acceptable range
- 🟡 Stressed — Compensatory mechanisms active, early warning
- 🔴 Critical — System failure imminent, requires immediate intervention
Cardiovascular
Monitors HR, BP, MAP, and cardiac output. Detects arrhythmias, shock states, and hemodynamic instability.
Respiratory
Tracks SpO₂, PaO₂, PaCO₂, and RR. Detects hypoxemia, hypercapnia, and respiratory failure.
Renal
Monitors creatinine and urine output. Detects acute kidney injury and electrolyte disturbances.
Endocrine
Tracks glucose and metabolic markers. Detects DKA, hypoglycemia, and metabolic derangements.
Neurological
Monitors GCS and mental status. Detects altered consciousness, seizure risk, and herniation.
08 Medical Specialties
Each specialty features unique case presentations, pathology models, and expected management protocols:
Example Cases
- Cardiology — STEMI: ST-elevation MI with chest pain, ECG changes, troponin elevation
- Pulmonology — Pulmonary Embolism: Acute dyspnea, hypoxemia, tachycardia
- Endocrinology — DKA: Diabetic ketoacidosis with hyperglycemia, metabolic acidosis
- Sepsis — Septic Shock: Systemic infection with SIRS criteria, organ dysfunction cascade
- Emergency — Hemorrhagic Shock: Trauma with blood loss, tachycardia, hypotension
- Neurology — Stroke: Acute focal deficit with altered GCS, BP management
- Nephrology — AKI: Acute kidney injury with rising creatinine, hyperkalemia
09 Intervention Engine
The intervention engine allows users to manage the virtual patient through 6 categories:
- Medications — Dose-based drugs with onset delay, peak effects, and duration
- IV Fluids — Crystalloids and colloids affecting intravascular volume
- Procedures — Intubation, chest tube, CPR, defibrillation
- Oxygen Therapy — Nasal cannula, face mask, non-rebreather, BiPAP
- Imaging — X-Ray, CT, MRI, Ultrasound with case-specific findings
- Lab Orders — CBC, BMP, ABG, Troponin, Blood Culture, etc.
10 Medications
Each medication has a modeled pharmacological profile:
| Medication | Route | Primary Effect | Key Consideration |
|---|---|---|---|
| Aspirin | PO | Antiplatelet, reduces clot propagation | First-line for ACS |
| Nitroglycerin | SL | Vasodilation, reduces BP and preload | Contraindicated in RV infarct |
| Morphine | IV | Analgesic, reduces HR and preload | Risk of respiratory depression |
| Heparin | IV | Anticoagulation | Dose-dependent bleeding risk |
| Insulin Regular | IV | Glucose reduction, K⁺ shift | Risk of hypoglycemia |
| Epinephrine | IV | Vasopressor, increases HR/BP | Arrhythmia risk at high doses |
| Atropine | IV | Increases heart rate (vagolytic) | First-line for bradycardia |
| Amiodarone | IV | Anti-arrhythmic | Risk of hypotension with bolus |
11 Adverse Events
The system simulates adverse events when medications are mismanaged:
- Morphine Overdose — Respiratory depression (RR drops significantly, SpO₂ falls)
- Insulin-Induced Hypoglycemia — Glucose drops below 60 mg/dL, altered consciousness
- Epinephrine Arrhythmia — Excessive catecholamine causes tachyarrhythmia
- Nitroglycerin Hypotension — Over-vasodilation causing dangerous BP drop
- Heparin Bleeding — Excessive anticoagulation risk
Learning Opportunity
Adverse events are displayed as red overlay alerts. They teach students about medication safety, dose-response relationships, and the consequences of clinical errors — all without harming real patients.
12 Lab & Imaging Orders
Users can order diagnostic tests that produce case-specific results after a realistic processing delay:
Laboratory Tests
- CBC — Complete Blood Count (WBC, Hgb, Platelets)
- BMP — Basic Metabolic Panel (Na, K, BUN, Creatinine, Glucose)
- Troponin — Cardiac biomarker (elevated in MI)
- ABG — Arterial Blood Gas (pH, PaO₂, PaCO₂, HCO₃⁻)
- D-Dimer — Coagulation marker (elevated in PE, DVT)
- Blood Culture — Microbiological culture for sepsis workup
Imaging Studies
- Chest X-Ray — PA & lateral views for pulmonary/cardiac pathology
- CT Scan — Computed tomography for detailed cross-sectional imaging
- CT Pulmonary Angiography — CTPA for pulmonary embolism diagnosis
- MRI — Magnetic resonance for soft tissue detail
- Ultrasound / FAST — Focused assessment for trauma and effusions
- 12-Lead ECG — Electrocardiogram for rhythm and ischemia analysis
13 Dynamic ECG Monitor
The ECG monitor renders diagnosis-specific waveforms in real time using Gaussian pulse synthesis. Each patient case has a mapped ECG pattern.
ECG Pattern Types (15 total)
| Pattern | Condition | Key Visual Features |
|---|---|---|
| Normal Sinus | Healthy rhythm | Regular P-QRS-T complexes |
| STEMI (Inferior) | Inferior MI | ST elevation leads II, III, aVF |
| STEMI (Anterior) | Anterior MI | Large ST elevation V1-V4 |
| ST Depression | NSTEMI / Ischemia | Downsloping ST depression |
| Atrial Fibrillation | AF with RVR | No P waves, irregular R-R intervals |
| Ventricular Fibrillation | Cardiac arrest | Chaotic, no identifiable waves |
| LBBB | STEMI equivalent | Wide QRS, inverted T wave |
| Ventricular Tachycardia | Wide complex tachy | Wide bizarre QRS, regular |
| Atrial Flutter | Sawtooth pattern | Sawtooth baseline, regular QRS |
| Diffuse ST Elevation | Pericarditis | Concave-up ST in all leads |
Dynamic Features
- Heart Rate Response — Waveform speed scales with live HR
- R-R Irregularity — AFib shows truly irregular beat spacing (35% variability)
- Baseline Wander — VFib/AFib patterns include fibrillatory noise
- QRS Width Variation — LBBB and VT patterns show widened QRS complexes
- Leading Dot Glow — Green glow dot follows the current trace position
14 Vitals Trend Charts
The dashboard includes real-time trend charts for four critical vitals, rendered using HTML Canvas:
- Heart Rate (HR) — Red line chart with alert zones at <50 and >120 bpm
- Blood Pressure (BP) — Dual orange lines showing systolic + diastolic
- SpO₂ — Cyan line chart with alert zone below 92%
- Respiratory Rate (RR) — Green line chart with alert zones at <10 or >28/min
Technical Details
- Rolling Window — Shows the last 60 data points
- Gradient Fill — Translucent gradient beneath each line
- Threshold Zones — Dashed red lines mark danger thresholds
- High-DPI Rendering — Canvas scales to device pixel ratio
15 AI Clinical Assistant
The floating AI assistant provides context-aware clinical support during simulations:
- "What is the diagnosis?" — Provides differential diagnosis based on current vitals
- "Treatment guidelines" — Evidence-based management protocols (ACC/AHA, GOLD, ADA, etc.)
- "Current vitals" — Summarizes the patient's current physiological state
- "Explain the pathophysiology" — Describes the mechanism of disease
- "How are the organ systems?" — Reports status of all 5 physiological systems
AI Design Principle
The LLM does not generate physiology freely — it reads from structured patient state variables. This ensures accuracy and prevents hallucination.
16 Evaluation & Clinical Reasoning
After ending a simulation, users receive a comprehensive Simulation Debrief:
Management Score
A 0–100 score with letter grade (A+ through F) based on clinical actions, timing, and appropriateness.
Actions Timeline
Chronological listing of every medication, procedure, and order with timestamps.
Clinical Feedback
Item-by-item assessment — marked as correct (✓), incorrect (✗), or cautionary (⚠). Each item explains why.
Clinical Reasoning Analysis
- Reasoning Score — Measures diagnostic thinking quality
- Time to First Intervention — How quickly the student began treating
- Diagnosis Identified — Whether the student's actions suggest correct diagnosis
- Physiological Outcome — Start vs. end vital comparison
- Evidence-Based Guidelines — Links actions to published clinical practice guidelines