anasim-simulator 1.0__py3-none-any.whl

anasim/__init__.py

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

anasim/__main__.py

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

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/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"),
+)

anasim/core/drug_api.py

@@ -0,0 +1,371 @@
+"""
+Drug Controller API Mixin for SimulationEngine.
+
+This module contains drug control interface methods extracted from engine.py
+for better maintainability while preserving the SimulationEngine API.
+"""
+
+from typing import TYPE_CHECKING
+
+from .units import convert_rate
+
+if TYPE_CHECKING:
+    from .engine import SimulationEngine
+    from .tci import TCIController
+
+
+class DrugControllerMixin:
+    """
+    Mixin providing drug control interface for SimulationEngine.
+    
+    Provides methods for:
+    - Setting drug infusion rates
+    - Enabling/disabling TCI (Target Controlled Infusion)
+    - Getting drug metadata and state for UI
+    """
+
+    _DRUG_ORDER = (
+        "propofol",
+        "remi",
+        "nore",
+        "vaso",
+        "phenyl",
+        "epi",
+        "dobu",
+        "milri",
+        "roc",
+    )
+    _DRUG_SPECS = {
+        "propofol": {
+            "name": "Propofol 1%",
+            "rate_attr": "propofol_rate_mg_sec",
+            "rate_unit": "mg/hr",
+            "rate_unit_internal": "mg/sec",
+            "tci_attr": "tci_prop",
+            "tci_name": "Propofol",
+            "tci_unit": "ug/mL",
+            "tci_mode": None,
+            "tci_range": (0.0, 10.0),
+            "pk_attr": "pk_prop",
+            "max_rate": ("mg_kg_min", 0.3),
+            "default_bolus": 150,
+            "bolus_unit": "mg",
+        },
+        "remi": {
+            "name": "Remifentanil 50mcg/mL",
+            "rate_attr": "remi_rate_ug_sec",
+            "rate_unit": "ug/min",
+            "rate_unit_internal": "ug/sec",
+            "tci_attr": "tci_remi",
+            "tci_name": "Remifentanil",
+            "tci_unit": "ng/mL",
+            "tci_mode": None,
+            "tci_range": (0.0, 10.0),
+            "pk_attr": "pk_remi",
+            "max_rate": ("ug_kg_min", 0.5),
+            "default_bolus": 10,
+            "bolus_unit": "mcg",
+        },
+        "nore": {
+            "name": "Norepinephrine 16mcg/mL",
+            "rate_attr": "nore_rate_ug_sec",
+            "rate_unit": "ug/min",
+            "rate_unit_internal": "ug/sec",
+            "tci_attr": "tci_nore",
+            "tci_name": "Norepinephrine",
+            "tci_unit": "ng/mL",
+            "tci_mode": "plasma",
+            "tci_range": (0.0, 30.0),
+            "pk_attr": "pk_nore",
+            "max_rate": ("ug_kg_min", 1.0),
+            "default_bolus": 10,
+            "bolus_unit": "mcg",
+        },
+        "vaso": {
+            "name": "Vasopressin 20U/mL",
+            "rate_attr": "vaso_rate_mu_sec",
+            "rate_unit": "U/min",
+            "rate_unit_internal": "mU/sec",
+            "tci_attr": "tci_vaso",
+            "tci_name": "Vasopressin",
+            "tci_unit": "mU/L",
+            "tci_mode": "plasma",
+            "tci_range": (0.0, 80.0),
+            "pk_attr": "pk_vaso",
+            "max_rate": ("u_min", 0.1),
+            "default_bolus": 1.0,
+            "bolus_unit": "U",
+        },
+        "epi": {
+            "name": "Epinephrine 100mcg/mL",
+            "rate_attr": "epi_rate_ug_sec",
+            "rate_unit": "ug/min",
+            "rate_unit_internal": "ug/sec",
+            "tci_attr": "tci_epi",
+            "tci_name": "Epinephrine",
+            "tci_unit": "ng/mL",
+            "tci_mode": "plasma",
+            "tci_range": (0.0, 20.0),
+            "pk_attr": "pk_epi",
+            "max_rate": ("ug_kg_min", 0.5),
+            "default_bolus": 10,
+            "bolus_unit": "mcg",
+        },
+        "phenyl": {
+            "name": "Phenylephrine 100mcg/mL",
+            "rate_attr": "phenyl_rate_ug_sec",
+            "rate_unit": "ug/min",
+            "rate_unit_internal": "ug/sec",
+            "tci_attr": "tci_phenyl",
+            "tci_name": "Phenylephrine",
+            "tci_unit": "ng/mL",
+            "tci_mode": "plasma",
+            "tci_range": (0.0, 120.0),
+            "pk_attr": "pk_phenyl",
+            "max_rate": ("ug_kg_min", 2.0),
+            "default_bolus": 100,
+            "bolus_unit": "mcg",
+        },
+        "dobu": {
+            "name": "Dobutamine 1mg/mL",
+            "rate_attr": "dobu_rate_ug_sec",
+            "rate_unit": "ug/min",
+            "rate_unit_internal": "ug/sec",
+            "tci_attr": "tci_dobu",
+            "tci_name": "Dobutamine",
+            "tci_unit": "ng/mL",
+            "tci_mode": "plasma",
+            "tci_range": (0.0, 500.0),
+            "pk_attr": "pk_dobu",
+            "max_rate": ("ug_kg_min", 20.0),
+            "default_bolus": 0.0,
+            "bolus_unit": "mcg",
+        },
+        "milri": {
+            "name": "Milrinone 200mcg/mL",
+            "rate_attr": "mil_rate_ug_sec",
+            "rate_unit": "ug/min",
+            "rate_unit_internal": "ug/sec",
+            "tci_attr": "tci_mil",
+            "tci_name": "Milrinone",
+            "tci_unit": "ng/mL",
+            "tci_mode": "plasma",
+            "tci_range": (0.0, 500.0),
+            "pk_attr": "pk_mil",
+            "max_rate": ("ug_kg_min", 0.75),
+            "default_bolus": 0.0,
+            "bolus_unit": "mcg",
+        },
+        "roc": {
+            "name": "Rocuronium 10mg/mL",
+            "rate_attr": "roc_rate_mg_sec",
+            "rate_unit": "mg/hr",
+            "rate_unit_internal": "mg/sec",
+            "tci_attr": "tci_roc",
+            "tci_name": "Rocuronium",
+            "tci_unit": "ug/mL",
+            "tci_mode": None,
+            "tci_range": (0.0, 10.0),
+            "pk_attr": "pk_roc",
+            "max_rate": ("mg_kg_hr", 1.0),
+            "default_bolus": 50,
+            "bolus_unit": "mg",
+        },
+    }
+    
+    def set_propofol_rate(self: "SimulationEngine", mg_per_hr: float):
+        self._set_rate_from_user("propofol", mg_per_hr)
+
+    def set_remi_rate(self: "SimulationEngine", ug_per_min: float):
+        self._set_rate_from_user("remi", ug_per_min)
+
+    def set_nore_rate(self: "SimulationEngine", ug_per_min: float):
+        self._set_rate_from_user("nore", ug_per_min)
+    
+    def set_epi_rate(self: "SimulationEngine", ug_per_min: float):
+        self._set_rate_from_user("epi", ug_per_min)
+    
+    def set_phenyl_rate(self: "SimulationEngine", ug_per_min: float):
+        self._set_rate_from_user("phenyl", ug_per_min)
+
+    def set_vaso_rate(self: "SimulationEngine", u_per_min: float):
+        self._set_rate_from_user("vaso", u_per_min)
+
+    def set_dobu_rate(self: "SimulationEngine", ug_per_min: float):
+        self._set_rate_from_user("dobu", ug_per_min)
+
+    def set_milri_rate(self: "SimulationEngine", ug_per_min: float):
+        self._set_rate_from_user("milri", ug_per_min)
+        
+    def set_rocuronium_rate(self: "SimulationEngine", mg_per_hr: float):
+        self._set_rate_from_user("roc", mg_per_hr)
+
+    def enable_tci(self: "SimulationEngine", drug: str, target: float, mode: str = 'effect_site'):
+        """
+        Enable TCI for a drug.
+        
+        Args:
+            drug: 'propofol', 'remi', 'nore', 'vaso', 'epi', 'dobu', 'milri', 'phenyl', 'roc'
+            target: Target concentration
+            mode: 'plasma' or 'effect_site' (ignored for nore/epi/phenyl which use plasma)
+        """
+        from .tci import TCIController
+
+        sampling_time = 1.0
+        if hasattr(self, "config") and getattr(self.config, "dt", None):
+            # TCI control does not benefit from waveform-rate updates. A 100 ms
+            # floor avoids excessive controller iterations and coarse-step
+            # oscillation while remaining much faster than infusion-pump updates.
+            sampling_time = max(self.config.dt, 0.1)
+        control_time = max(10.0, sampling_time)
+        
+        drug = drug.lower()
+        spec = self._DRUG_SPECS.get(drug)
+        if not spec:
+            return
+
+        max_rate = self._tci_max_rate(spec)
+        tci_attr = spec["tci_attr"]
+        pk_attr = spec["pk_attr"]
+        controller = getattr(self, tci_attr, None)
+        tci_mode = spec["tci_mode"] if spec["tci_mode"] else mode
+
+        if not controller:
+            controller = TCIController(
+                getattr(self, pk_attr),
+                spec["tci_name"],
+                tci_mode,
+                max_rate=max_rate,
+                sampling_time=sampling_time,
+                control_time=control_time,
+            )
+            setattr(self, tci_attr, controller)
+
+        controller.max_rate = max_rate
+        self._seed_tci_state(controller, getattr(self, pk_attr))
+        controller.target = target
+
+    def _seed_tci_state(self: "SimulationEngine", controller, pk_model):
+        """Seed TCI state from current PK concentrations to avoid bolus overshoot."""
+        if not controller or not pk_model or not hasattr(pk_model, "state"):
+            return
+        if hasattr(controller, "sync_state_estimate"):
+            controller.sync_state_estimate(pk_model)
+            return
+        state = pk_model.state
+        c1 = getattr(state, "c1", 0.0)
+        c2 = getattr(state, "c2", 0.0)
+        c3 = getattr(state, "c3", 0.0)
+        ce = getattr(state, "ce", 0.0)
+        if controller.n_state == 1:
+            controller.set_state(c1)
+        elif controller.n_state == 2:
+            controller.set_state(c1, c2)
+        elif controller.n_state == 3:
+            controller.set_state(c1, c2, ce)
+        else:
+            controller.set_state(c1, c2, c3, ce)
+
+    def sync_active_tci_from_pk(self: "SimulationEngine", *drug_keys: str):
+        """Resynchronize active TCI controllers with the live PK model state."""
+        keys = drug_keys or tuple(self._DRUG_ORDER)
+        for key in keys:
+            spec = self._DRUG_SPECS.get(key)
+            if not spec:
+                continue
+            controller = getattr(self, spec["tci_attr"], None)
+            pk_model = getattr(self, spec["pk_attr"], None)
+            if not controller or not pk_model:
+                continue
+            if hasattr(controller, "sync_from_pk_model"):
+                controller.sync_from_pk_model(pk_model)
+            else:
+                self._seed_tci_state(controller, pk_model)
+
+    def _tci_max_rate(self: "SimulationEngine", spec: dict) -> float:
+        """Return a clinically realistic max infusion rate for a drug."""
+        weight = max(0.0, getattr(self.patient, "weight", 0.0))
+        if weight <= 0.0:
+            return 0.0
+        unit, value = spec["max_rate"]
+        if unit == "mg_kg_min" or unit == "ug_kg_min":
+            return weight * value / 60.0
+        if unit == "mg_kg_hr":
+            return weight * value / 3600.0
+        if unit == "u_min":
+            # Vasopressin: return mU/sec (model units)
+            return (value * 1000.0) / 60.0
+        return 0.0
+
+    def disable_tci(self: "SimulationEngine", drug: str):
+        """Disable TCI for a drug and reset infusion rate to zero."""
+        drug = drug.lower()
+        spec = self._DRUG_SPECS.get(drug)
+        if not spec:
+            return
+        setattr(self, spec["tci_attr"], None)
+        setattr(self, spec["rate_attr"], 0.0)
+
+    def get_controllable_drugs(self: "SimulationEngine"):
+        """
+        Return metadata for all controllable drugs.
+        Used by UI to build controls dynamically.
+        """
+        drugs = []
+        for key in self._DRUG_ORDER:
+            spec = self._DRUG_SPECS[key]
+            drugs.append({
+                "key": key,
+                "name": spec["name"],
+                "rate_unit": spec["rate_unit"],
+                "tci_unit": spec["tci_unit"],
+                "can_tci": True,
+                "default_bolus": spec["default_bolus"],
+                "bolus_unit": spec.get("bolus_unit"),
+                "tci_range": spec.get("tci_range"),
+            })
+        return drugs
+
+    def set_drug_rate(self: "SimulationEngine", key: str, rate_user_unit: float):
+        """Generic setter for drug infusion rate."""
+        self._set_rate_from_user(key, rate_user_unit)
+
+    def set_drug_target(self: "SimulationEngine", key: str, target: float):
+        """Generic setter for TCI target. None/Negative disables TCI."""
+        if target is None or target < 0:
+            self.disable_tci(key)
+        else:
+            self.enable_tci(key, target)
+
+    def get_drug_state(self: "SimulationEngine", key: str):
+        """Return current state generic dict."""
+        state = {'rate': 0.0, 'target': 0.0, 'is_tci': False}
+        
+        spec = self._DRUG_SPECS.get(key)
+        if not spec:
+            return state
+
+        state["rate"] = self._get_rate_to_user(key)
+        controller = getattr(self, spec["tci_attr"], None)
+        if controller:
+            state["is_tci"] = True
+            state["target"] = controller.target
+                 
+        return state
+
+    def _set_rate_from_user(self: "SimulationEngine", key: str, rate_user_unit: float):
+        spec = self._DRUG_SPECS.get(key)
+        if not spec:
+            return
+        if rate_user_unit is None:
+            return
+        rate_internal = convert_rate(rate_user_unit, spec["rate_unit"], spec["rate_unit_internal"])
+        rate_internal = max(0.0, rate_internal)
+        setattr(self, spec["rate_attr"], rate_internal)
+
+    def _get_rate_to_user(self: "SimulationEngine", key: str) -> float:
+        spec = self._DRUG_SPECS.get(key)
+        if not spec:
+            return 0.0
+        rate_internal = getattr(self, spec["rate_attr"], 0.0)
+        return convert_rate(rate_internal, spec["rate_unit_internal"], spec["rate_unit"])