anasim-simulator 1.0__tar.gz

anasim_simulator-1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

anasim_simulator-1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: anasim-simulator
+Version: 1.0
+Summary: Real-time anesthesia and physiology simulator for medical education
+Author-email: Robert Chen <robert.chen@icahn.mssm.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/robchiral/AnaSim
+Project-URL: Changelog, https://github.com/robchiral/AnaSim/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/robchiral/AnaSim#readme
+Project-URL: Issues, https://github.com/robchiral/AnaSim/issues
+Project-URL: Releases, https://github.com/robchiral/AnaSim/releases
+Project-URL: Source, https://github.com/robchiral/AnaSim
+Keywords: anesthesia,medical education,physiology,pharmacokinetics,simulation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: PySide6
+Requires-Dist: pyqtgraph
+Requires-Dist: scipy
+Requires-Dist: pandas
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# AnaSim
+
+Real-time anesthesia and physiology simulation for medical education.
+
+[![CI](https://github.com/robchiral/AnaSim/actions/workflows/ci.yml/badge.svg)](https://github.com/robchiral/AnaSim/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/robchiral/AnaSim/blob/main/LICENSE)
+
+![AnaSim Induction Window](https://raw.githubusercontent.com/robchiral/AnaSim/main/docs/images/induction_full_window.png)
+
+> [!WARNING]
+> **For educational use only**
+>
+> AnaSim is not a medical device. Do not use it for clinical care or patient-specific
+> prediction.
+
+## Installation
+
+AnaSim requires Python 3.10 or newer. Install the published package in a virtual
+environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install anasim-simulator
+```
+
+On Windows, activate the environment with `.venv\Scripts\activate`.
+
+The package is distributed as `anasim-simulator`; the command and Python import
+are `anasim`.
+
+## Quick start
+
+Launch the interactive operating-room monitor:
+
+```bash
+anasim
+```
+
+Run a headless simulation:
+
+```bash
+anasim --mode headless --duration 10
+```
+
+See the [CLI guide](https://github.com/robchiral/AnaSim/blob/main/docs/CLI_USAGE.md)
+for configuration files, recording, and additional examples.
+
+## Features
+
+- Cardiovascular and respiratory physiology responding to drugs, ventilation,
+  fluids, and surgical stimulation
+- PK/PD models for propofol, remifentanil, sevoflurane, rocuronium, and
+  vasoactive agents
+- VCV, PCV, PSV, CPAP, and manual bag-mask ventilation
+- ECG, pulse oximetry, capnography, NIBP, and depth-of-anesthesia monitoring
+- Guided induction, hemorrhage, anaphylaxis, septic shock, and emergence scenarios
+- Headless execution and CSV recording for reproducible teaching exercises
+
+## Model scope and calibration
+
+AnaSim uses published models where they behave coherently in the integrated
+simulation and documents calibrated deviations where literal parameters produce
+implausible managed intraoperative states. See the
+[model references and deviations](https://github.com/robchiral/AnaSim/blob/main/docs/REFERENCES.md)
+for citations and details.
+
+Examples of calibration choices and deliberate deviations:
+
+- hemodynamics uses plasma propofol/remifentanil concentrations in line with Su et al. 2023, while CNS depth, tolerance, BIS, and respiratory depression use effect-site concentrations
+- rocuronium spontaneous recovery uses a faster runtime `ke0` than pure literature modeling so recovery timing stays in the clinical range
+- maintenance startup adds visible norepinephrine support only when the selected anesthetic state would otherwise begin below MAP 65 mmHg
+
+AnaSim currently accepts adult patients aged 18–70 years. The upper bound avoids unsupported extrapolation of the strongly age-dependent Su et al. hemodynamic term beyond the population used to develop and illustrate that model.
+
+## Development
+
+```bash
+git clone https://github.com/robchiral/AnaSim.git
+cd AnaSim
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+QT_QPA_PLATFORM=offscreen python -m pytest -q
+```
+
+See the [contribution guide](https://github.com/robchiral/AnaSim/blob/main/CONTRIBUTING.md)
+and [changelog](https://github.com/robchiral/AnaSim/blob/main/CHANGELOG.md).
+
+Initial TIVA implementations were derived from
+[Python Anesthesia Simulator](https://github.com/AnesthesiaSimulation/Python_Anesthesia_Simulator).
+
+## License
+
+AnaSim is released under the
+[MIT License](https://github.com/robchiral/AnaSim/blob/main/LICENSE).

anasim_simulator-1.0/README.md

@@ -0,0 +1,97 @@
+# AnaSim
+
+Real-time anesthesia and physiology simulation for medical education.
+
+[![CI](https://github.com/robchiral/AnaSim/actions/workflows/ci.yml/badge.svg)](https://github.com/robchiral/AnaSim/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/robchiral/AnaSim/blob/main/LICENSE)
+
+![AnaSim Induction Window](https://raw.githubusercontent.com/robchiral/AnaSim/main/docs/images/induction_full_window.png)
+
+> [!WARNING]
+> **For educational use only**
+>
+> AnaSim is not a medical device. Do not use it for clinical care or patient-specific
+> prediction.
+
+## Installation
+
+AnaSim requires Python 3.10 or newer. Install the published package in a virtual
+environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install anasim-simulator
+```
+
+On Windows, activate the environment with `.venv\Scripts\activate`.
+
+The package is distributed as `anasim-simulator`; the command and Python import
+are `anasim`.
+
+## Quick start
+
+Launch the interactive operating-room monitor:
+
+```bash
+anasim
+```
+
+Run a headless simulation:
+
+```bash
+anasim --mode headless --duration 10
+```
+
+See the [CLI guide](https://github.com/robchiral/AnaSim/blob/main/docs/CLI_USAGE.md)
+for configuration files, recording, and additional examples.
+
+## Features
+
+- Cardiovascular and respiratory physiology responding to drugs, ventilation,
+  fluids, and surgical stimulation
+- PK/PD models for propofol, remifentanil, sevoflurane, rocuronium, and
+  vasoactive agents
+- VCV, PCV, PSV, CPAP, and manual bag-mask ventilation
+- ECG, pulse oximetry, capnography, NIBP, and depth-of-anesthesia monitoring
+- Guided induction, hemorrhage, anaphylaxis, septic shock, and emergence scenarios
+- Headless execution and CSV recording for reproducible teaching exercises
+
+## Model scope and calibration
+
+AnaSim uses published models where they behave coherently in the integrated
+simulation and documents calibrated deviations where literal parameters produce
+implausible managed intraoperative states. See the
+[model references and deviations](https://github.com/robchiral/AnaSim/blob/main/docs/REFERENCES.md)
+for citations and details.
+
+Examples of calibration choices and deliberate deviations:
+
+- hemodynamics uses plasma propofol/remifentanil concentrations in line with Su et al. 2023, while CNS depth, tolerance, BIS, and respiratory depression use effect-site concentrations
+- rocuronium spontaneous recovery uses a faster runtime `ke0` than pure literature modeling so recovery timing stays in the clinical range
+- maintenance startup adds visible norepinephrine support only when the selected anesthetic state would otherwise begin below MAP 65 mmHg
+
+AnaSim currently accepts adult patients aged 18–70 years. The upper bound avoids unsupported extrapolation of the strongly age-dependent Su et al. hemodynamic term beyond the population used to develop and illustrate that model.
+
+## Development
+
+```bash
+git clone https://github.com/robchiral/AnaSim.git
+cd AnaSim
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+QT_QPA_PLATFORM=offscreen python -m pytest -q
+```
+
+See the [contribution guide](https://github.com/robchiral/AnaSim/blob/main/CONTRIBUTING.md)
+and [changelog](https://github.com/robchiral/AnaSim/blob/main/CHANGELOG.md).
+
+Initial TIVA implementations were derived from
+[Python Anesthesia Simulator](https://github.com/AnesthesiaSimulation/Python_Anesthesia_Simulator).
+
+## License
+
+AnaSim is released under the
+[MIT License](https://github.com/robchiral/AnaSim/blob/main/LICENSE).

anasim_simulator-1.0/anasim/__init__.py

@@ -0,0 +1,3 @@
+"""AnaSim anesthesia simulator."""
+
+__version__ = "1.0"

anasim_simulator-1.0/anasim/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

anasim_simulator-1.0/anasim/cli.py

@@ -0,0 +1,107 @@
+import argparse
+import json
+import sys
+import time
+from dataclasses import fields
+from pathlib import Path
+
+from anasim.core.engine import SimulationEngine, SimulationConfig
+from anasim.patient.patient import Patient
+
+
+PATIENT_CONFIG_FIELDS = {
+    field.name for field in fields(Patient)
+    if field.name not in {"lbm", "bmi", "bsa"}
+}
+SIMULATION_CONFIG_FIELDS = {field.name for field in fields(SimulationConfig)}
+CONFIG_FIELDS = PATIENT_CONFIG_FIELDS | SIMULATION_CONFIG_FIELDS
+
+
+def build_models_from_config(config_data: dict) -> tuple[Patient, SimulationConfig]:
+    """Build typed inputs and reject misspelled or obsolete keys."""
+    unknown = set(config_data) - CONFIG_FIELDS
+    if unknown:
+        names = ", ".join(sorted(unknown))
+        raise ValueError(f"Unknown configuration key(s): {names}")
+
+    patient_kwargs = {
+        key: value for key, value in config_data.items()
+        if key in PATIENT_CONFIG_FIELDS
+    }
+    simulation_kwargs = {
+        key: value for key, value in config_data.items()
+        if key in SIMULATION_CONFIG_FIELDS
+    }
+    return Patient(**patient_kwargs), SimulationConfig(**simulation_kwargs)
+
+
+def run_headless(args):
+    """Run simulation in headless mode."""
+    print(f"Starting Headless Simulation (Duration: {args.duration}s)...")
+    
+    # Simple default config or load from file
+    config_data = {}
+    if args.config:
+        try:
+            config_data = json.loads(Path(args.config).read_text())
+        except (OSError, json.JSONDecodeError) as e:
+            print(f"Error loading config: {e}")
+            raise SystemExit(1) from e
+    try:
+        patient, sim_config = build_models_from_config(config_data)
+    except ValueError as e:
+        print(f"Error loading config: {e}")
+        raise SystemExit(1) from e
+    
+    engine = SimulationEngine(patient, sim_config)
+    if args.record:
+        engine.start_recording(output_dir=args.record_dir, sample_interval_sec=args.record_interval)
+    engine.start()
+    
+    # Run loop
+    start_real = time.perf_counter()
+    steps = int(args.duration / sim_config.dt)
+    
+    for i in range(steps):
+        engine.step(sim_config.dt)
+        if i % 100 == 0:
+            state = engine.get_latest_state()
+            hr = state.display_value("hr")
+            map_val = state.display_value("map")
+            spo2 = state.display_value("spo2")
+            print(f"Time: {state.time:.2f}s | HR: {hr:.1f} | MAP: {map_val:.1f} | SpO2: {spo2:.1f}")
+            
+    end_real = time.perf_counter()
+    print(f"Simulation completed in {end_real - start_real:.2f}s real time.")
+
+def run_ui():
+    """Run simulation with UI."""
+    from PySide6.QtWidgets import QApplication
+    from anasim.ui.main_window import MainWindow
+
+    app = QApplication.instance()
+    if app is None:
+        app = QApplication(sys.argv)
+        
+    window = MainWindow()
+    window.show()
+    sys.exit(app.exec())
+
+def main():
+    parser = argparse.ArgumentParser(description="AnaSim - Anesthesia Simulator")
+    parser.add_argument("--mode", choices=["ui", "headless"], default="ui", help="Run mode (default: ui)")
+    parser.add_argument("--duration", type=float, default=10.0, help="Duration for headless mode in seconds")
+    parser.add_argument("--config", type=str, help="Path to JSON configuration file")
+    parser.add_argument("--record", action="store_true", help="Enable CSV recording (headless only)")
+    parser.add_argument("--record-dir", type=str, default="recordings", help="Output directory for recordings")
+    parser.add_argument("--record-interval", type=float, default=1.0, help="Sample interval in seconds for CSV")
+    
+    args = parser.parse_args()
+    
+    if args.mode == "headless":
+        run_headless(args)
+    else:
+        run_ui()
+
+if __name__ == "__main__":
+    main()

anasim_simulator-1.0/anasim/core/constants.py

@@ -0,0 +1,151 @@
+"""
+Physiological and Numerical Constants for AnaSim.
+
+This module centralizes magic numbers used throughout the simulation.
+
+NOTE: Only add constants here that are ACTIVELY IMPORTED elsewhere.
+"""
+
+from dataclasses import dataclass
+
+# Physiological bounds (used in hemodynamics.py).
+
+# Heart Rate Bounds (bpm)
+HR_MIN = 10.0  # Below this, functional asystole
+HR_MAX = 220.0  # Maximum physiological HR 
+
+# Blood Pressure Bounds (mmHg) - imported but available for bounds checking
+MAP_MAX = 200.0  # Severe hypertensive crisis
+SBP_MAX = 260.0  # Extreme hypertension
+DBP_MAX = 160.0  # Extreme diastolic hypertension
+
+# Total Peripheral Resistance minimum (Wood Units)
+TPR_MIN = 0.006  # Minimum physiologically reasonable (severe vasodilation)
+
+# Blood Volume (mL)
+BLOOD_VOLUME_MIN = 500.0  # Below this, effectively exsanguinated
+
+# Respiratory constants (used in respiration.py).
+
+# Respiratory Rate Thresholds (bpm)
+RR_APNEA_THRESHOLD = 2.0  # Below this, complete apnea
+RR_BRADYPNEA_THRESHOLD = 4.0  # 2-4 bpm = severe bradypnea with irregular breathing
+
+# Tidal Volume Minimum (mL)
+VT_MIN = 50.0  # Threshold for functional apnea
+
+# Pharmacokinetic constants (used in utils.py hill_function).
+
+# Epsilon for preventing division by zero in Hill functions
+HILL_EPSILON = 1e-12
+
+# Maximum Hill coefficient (gamma) to prevent numerical overflow
+GAMMA_MAX = 20.0
+
+# Concentration ratio above which Hill function returns near-saturation
+CONCENTRATION_RATIO_SATURATION = 100.0
+
+# TCI controller constants (used in tci.py).
+
+# Minimum interval between target changes (seconds)
+TCI_MIN_TARGET_CHANGE_INTERVAL = 5.0
+
+# Maximum TCI peak time search (seconds)
+TCI_PEAK_TIME_MAX = 600.0
+
+# Thermoregulation constants (used in respiration.py, hemodynamics.py).
+
+# Temperature coefficient for metabolic rate (Q10 effect)
+# VCO2 decreases ~7% per °C below 37°C (Q10 ≈ 2.0)
+# Reference: Sessler. Anesthesiology. 2000.
+TEMP_METABOLIC_COEFFICIENT = 0.93
+
+# Thermoregulation effect on TPR per degree deviation from 37°C
+# TPR increases ~10% per °C below normal (vasoconstriction)
+# Reference: Frank et al. JAMA. 1997.
+TEMP_TPR_COEFFICIENT = 0.10
+
+# Shivering model constants (used in runtime.py, respiration.py).
+# Clinically, shivering appears near 36.5°C in awake patients and is
+# suppressed by anesthetics/opioids; maximal shivering can raise
+# metabolic rate ~3-5x baseline.
+SHIVER_BASE_THRESHOLD = 36.5
+SHIVER_DEPTH_DROP_MAX = 2.0
+SHIVER_REMI_DROP_MAX = 0.8
+SHIVER_DELTA_FULL = 1.5
+SHIVER_BIS_ON = 60.0
+SHIVER_BIS_FULL = 80.0
+SHIVER_MAX_MULTIPLIER = 3.0
+SHIVER_TAU_ON = 30.0
+SHIVER_TAU_OFF = 90.0
+
+# Apnea PaCO2 rise rates (mmHg/min) and fast-phase duration.
+APNEA_PACO2_RISE_FAST_MMHG_MIN = 10.0
+APNEA_PACO2_RISE_SLOW_MMHG_MIN = 3.6
+APNEA_PACO2_RISE_FAST_DURATION_SEC = 60.0
+
+
+@dataclass(frozen=True)
+class AirwayTuning:
+    """Centralized airway tuning parameters."""
+    # Laryngospasm dynamics (seconds)
+    laryngospasm_tau_on: float = 1.0
+    laryngospasm_tau_off: float = 8.0
+
+    # Resistance impact (cmH2O/(L/s))
+    upper_resistance_gain: float = 40.0
+    bronch_resistance_gain: float = 20.0
+
+    # Ventilation efficiency weighting
+    vent_efficiency_bronch_weight: float = 0.5
+    vent_efficiency_upper_weight: float = 0.2
+    vent_efficiency_min: float = 0.1
+
+    # Capnography obstruction weighting
+    capno_obstruction_upper_weight: float = 1.0
+    capno_obstruction_bronch_weight: float = 0.7
+
+    # V/Q mismatch weighting
+    vq_mismatch_bronch_weight: float = 0.85
+    vq_mismatch_upper_weight: float = 0.25
+
+
+@dataclass(frozen=True)
+class ThermalTuning:
+    """Centralized thermal model tuning parameters."""
+    ambient_temp_c: float = 20.0
+    base_conductance_w_per_c: float = 3.0
+    anesthetic_conductance_gain: float = 0.5
+    redistribution_gain_w_per_depth: float = 50000.0
+    bair_hugger_gain_w_per_c: float = 7.0
+    metabolic_reduction_max: float = 0.2
+    depth_propofol_scale: float = 4.0
+    metabolic_temp_threshold_c: float = 0.5
+    specific_heat_j_kg_k: float = 3470.0
+    temp_min_c: float = 25.0
+    temp_max_c: float = 42.0
+
+# Centralized tuple configurations for Engine state models
+PK_HEMODYNAMIC_MODEL_ATTRS = (
+    ("propofol", "pk_prop"),
+    ("remi", "pk_remi"),
+    ("nore", "pk_nore"),
+    ("roc", "pk_roc"),
+    ("epi", "pk_epi"),
+    ("phenyl", "pk_phenyl"),
+    ("vaso", "pk_vaso"),
+    ("dobu", "pk_dobu"),
+    ("milri", "pk_mil"),
+)
+
+BOLUS_TARGETS = (
+    ("prop", "pk_prop"),
+    ("remi", "pk_remi"),
+    ("nore", "pk_nore"),
+    ("epi", "pk_epi"),
+    ("phenyl", "pk_phenyl"),
+    ("vaso", "pk_vaso"),
+    ("dobu", "pk_dobu"),
+    ("milri", "pk_mil"),
+    ("roc", "pk_roc"),
+)