iints-sdk-python35 0.0.18__py3-none-any.whl

iints/core/patient/patient_factory.py

@@ -0,0 +1,117 @@
+import numpy as np
+from typing import Dict, Any, Optional
+from .models import CustomPatientModel
+
+try:
+    from simglucose.simulation.env import T1DSimEnv
+    from simglucose.patient.t1dpatient import T1DPatient
+    from simglucose.sensor.cgm import CGMSensor
+    from simglucose.actuator.pump import InsulinPump
+    from simglucose.controller.base import Action
+    SIMGLUCOSE_AVAILABLE = True
+except ImportError:
+    SIMGLUCOSE_AVAILABLE = False
+
+class PatientFactory:
+    """Factory for creating different types of patient models."""
+    
+    SIMGLUCOSE_PATIENTS = [
+        'adolescent#001', 'adolescent#002', 'adolescent#003', 'adolescent#004', 'adolescent#005',
+        'adolescent#006', 'adolescent#007', 'adolescent#008', 'adolescent#009', 'adolescent#010',
+        'adult#001', 'adult#002', 'adult#003', 'adult#004', 'adult#005',
+        'adult#006', 'adult#007', 'adult#008', 'adult#009', 'adult#010',
+        'child#001', 'child#002', 'child#003', 'child#004', 'child#005',
+        'child#006', 'child#007', 'child#008', 'child#009', 'child#010'
+    ]
+    
+    @staticmethod
+    def create_patient(patient_type='custom', patient_id=None, initial_glucose=120.0, **kwargs):
+        """Create a patient model based on type."""
+        if patient_type == 'custom':
+            return CustomPatientModel(initial_glucose=initial_glucose, **kwargs)
+        elif patient_type == 'simglucose':
+            if not SIMGLUCOSE_AVAILABLE:
+                print("Warning: Simglucose not available, falling back to custom model")
+                return CustomPatientModel(initial_glucose=initial_glucose, **kwargs)
+            
+            patient_name = patient_id or PatientFactory.SIMGLUCOSE_PATIENTS[0]
+            return SimglucosePatientWrapper(patient_name, initial_glucose)
+        else:
+            raise ValueError(f"Unknown patient type: {patient_type}")
+    
+    @staticmethod
+    def get_patient_diversity_set():
+        """Get a diverse set of patients for population studies."""
+        if not SIMGLUCOSE_AVAILABLE:
+            # Create diverse custom patients with different parameters
+            return [
+                CustomPatientModel(initial_glucose=120, insulin_sensitivity=40),  # High sensitivity
+                CustomPatientModel(initial_glucose=120, insulin_sensitivity=60),  # Low sensitivity
+                CustomPatientModel(initial_glucose=120, carb_factor=8),          # Fast carb absorption
+                CustomPatientModel(initial_glucose=120, carb_factor=12),         # Slow carb absorption
+                CustomPatientModel(initial_glucose=120, glucose_decay_rate=0.0015), # Slow metabolism
+                CustomPatientModel(initial_glucose=120, glucose_decay_rate=0.0035), # Fast metabolism
+            ]
+        else:
+            # Use FDA-approved virtual patients
+            selected_patients = [
+                'adolescent#001', 'adolescent#005', 'adult#001', 
+                'adult#005', 'child#001', 'child#005'
+            ]
+            return [SimglucosePatientWrapper(name) for name in selected_patients]
+
+class SimglucosePatientWrapper:
+    """Wrapper for simglucose patients to match CustomPatientModel interface."""
+    
+    def __init__(self, patient_name='adolescent#001', initial_glucose=120.0):
+        if not SIMGLUCOSE_AVAILABLE:
+            raise ImportError("Simglucose not available")
+            
+        self.patient = T1DPatient.make(patient_name)
+        self.sensor = CGMSensor.make()
+        self.pump = InsulinPump.make()
+        self.env = T1DSimEnv(patient=self.patient, sensor=self.sensor, pump=self.pump)
+        self.patient_name = patient_name
+        self.reset()
+    
+    def reset(self):
+        """Reset the simglucose environment."""
+        self.env.reset()
+    
+    def get_current_glucose(self):
+        """Get current glucose in mg/dL."""
+        return self.env.patient.BG * 18.0156
+    
+    def update(self, time_step, delivered_insulin, carb_intake=0.0, **kwargs):
+        """Update patient state."""
+        action = Action(basal=0.0, bolus=delivered_insulin, carb=carb_intake)
+        obs, reward, done, info = self.env.step(action)
+        self._last_info = info
+        return obs[0] * 18.0156
+    
+    @property
+    def insulin_on_board(self):
+        """Get insulin on board."""
+        if hasattr(self, '_last_info') and 'IOB' in self._last_info:
+            return self._last_info['IOB']
+        return getattr(self.env.patient, 'IOB', 0.0)
+    
+    @property
+    def carbs_on_board(self):
+        """Get carbs on board."""
+        if hasattr(self, '_last_info') and 'COB' in self._last_info:
+            return self._last_info['COB']
+        return getattr(self.env.patient, 'COB', 0.0)
+    
+    def trigger_event(self, event_type, value):
+        """Trigger stress events."""
+        print(f"SimglucosePatient {self.patient_name}: {event_type} = {value}")
+    
+    def get_patient_state(self):
+        """Get patient state for logging."""
+        return {
+            "current_glucose": self.get_current_glucose(),
+            "insulin_on_board": self.insulin_on_board,
+            "carbs_on_board": self.carbs_on_board,
+            "patient_name": self.patient_name
+        }

iints/core/patient/profile.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Any, Optional
+
+
+@dataclass
+class PatientProfile:
+    """
+    User-facing patient profile that maps to the simulator config.
+    """
+    isf: float = 50.0  # Insulin Sensitivity Factor (mg/dL per unit)
+    icr: float = 10.0  # Insulin-to-carb ratio (grams per unit)
+    basal_rate: float = 0.8  # U/hr
+    initial_glucose: float = 120.0
+    dawn_phenomenon_strength: float = 0.0  # mg/dL per hour
+    dawn_start_hour: float = 4.0
+    dawn_end_hour: float = 8.0
+
+    # Advanced knobs (optional)
+    glucose_decay_rate: float = 0.002
+    glucose_absorption_rate: float = 0.03
+    insulin_action_duration: float = 300.0
+    insulin_peak_time: float = 75.0
+    meal_mismatch_epsilon: float = 1.0
+
+    def to_patient_config(self) -> Dict[str, Any]:
+        return {
+            "basal_insulin_rate": self.basal_rate,
+            "insulin_sensitivity": self.isf,
+            "carb_factor": self.icr,
+            "initial_glucose": self.initial_glucose,
+            "dawn_phenomenon_strength": self.dawn_phenomenon_strength,
+            "dawn_start_hour": self.dawn_start_hour,
+            "dawn_end_hour": self.dawn_end_hour,
+            "glucose_decay_rate": self.glucose_decay_rate,
+            "glucose_absorption_rate": self.glucose_absorption_rate,
+            "insulin_action_duration": self.insulin_action_duration,
+            "insulin_peak_time": self.insulin_peak_time,
+            "meal_mismatch_epsilon": self.meal_mismatch_epsilon,
+        }

iints/core/safety/__init__.py

@@ -0,0 +1,12 @@
+from .config import SafetyConfig
+from .input_validator import InputValidator
+
+__all__ = ["SafetyConfig", "SafetySupervisor", "InputValidator"]
+
+
+def __getattr__(name: str):
+    if name == "SafetySupervisor":
+        from .supervisor import SafetySupervisor
+
+        return SafetySupervisor
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

iints/core/safety/config.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class SafetyConfig:
+    """
+    Central safety configuration for simulator, input validation, and supervisor.
+    """
+    # Input validation limits
+    min_glucose: float = 20.0
+    max_glucose: float = 600.0
+    max_glucose_delta_per_5_min: float = 35.0
+
+    # Supervisor thresholds
+    hypoglycemia_threshold: float = 70.0
+    severe_hypoglycemia_threshold: float = 54.0
+    hyperglycemia_threshold: float = 250.0
+    max_insulin_per_bolus: float = 5.0
+    glucose_rate_alarm: float = 5.0
+    max_insulin_per_hour: float = 3.0
+    max_iob: float = 4.0
+    trend_stop: float = -2.0
+    hypo_cutoff: float = 70.0
+    max_basal_multiplier: float = 3.0
+    predicted_hypoglycemia_threshold: float = 60.0
+    predicted_hypoglycemia_horizon_minutes: int = 30
+
+    # Formal safety contract (logic validation)
+    contract_enabled: bool = True
+    contract_glucose_threshold: float = 90.0
+    contract_trend_threshold_mgdl_min: float = -1.0  # -5 mg/dL per 5 minutes
+
+    # Simulation termination limits
+    critical_glucose_threshold: float = 40.0
+    critical_glucose_duration_minutes: int = 30

iints/core/safety/input_validator.py

@@ -0,0 +1,95 @@
+from typing import Optional
+
+from iints.core.safety.config import SafetyConfig
+
+class InputValidator:
+    """
+    A biological validation filter for sensor inputs to ensure they are
+    physiologically plausible before being used by an algorithm.
+    This component makes the system robust against common sensor errors.
+    """
+    def __init__(self,
+                 min_glucose: float = 20.0,
+                 max_glucose: float = 600.0,
+                 max_glucose_delta_per_5_min: float = 35.0,
+                 safety_config: Optional[SafetyConfig] = None):
+        """
+        Initializes the validator with plausible biological limits.
+
+        Args:
+            min_glucose (float): The absolute minimum plausible glucose value (mg/dL).
+            max_glucose (float): The absolute maximum plausible glucose value (mg/dL).
+            max_glucose_delta_per_5_min (float): The maximum plausible change in glucose
+                                                 over a 5-minute period (mg/dL).
+        """
+        if safety_config is not None:
+            min_glucose = safety_config.min_glucose
+            max_glucose = safety_config.max_glucose
+            max_glucose_delta_per_5_min = safety_config.max_glucose_delta_per_5_min
+
+        self.min_glucose = min_glucose
+        self.max_glucose = max_glucose
+        self.max_glucose_delta_per_5_min = max_glucose_delta_per_5_min
+        self.last_valid_glucose: Optional[float] = None
+        self.last_validation_time: Optional[float] = None
+
+    def reset(self):
+        """Resets the state of the validator for a new simulation."""
+        self.last_valid_glucose = None
+        self.last_validation_time = None
+
+    def get_state(self) -> dict:
+        return {
+            "last_valid_glucose": self.last_valid_glucose,
+            "last_validation_time": self.last_validation_time,
+        }
+
+    def set_state(self, state: dict) -> None:
+        self.last_valid_glucose = state.get("last_valid_glucose")
+        self.last_validation_time = state.get("last_validation_time")
+
+    def validate_glucose(self, glucose_value: float, current_time: float) -> float:
+        """
+        Validates a glucose reading against absolute and rate-of-change limits.
+
+        Args:
+            glucose_value (float): The incoming glucose reading from the sensor.
+            current_time (float): The current simulation time in minutes.
+
+        Returns:
+            float: The validated glucose value.
+
+        Raises:
+            ValueError: If the value is outside biological plausibility limits.
+        """
+        # 1. Absolute biological plausibility check
+        if not (self.min_glucose <= glucose_value <= self.max_glucose):
+            raise ValueError(
+                f"BIOLOGICAL_PLAUSIBILITY_ERROR: Glucose {glucose_value} mg/dL is outside the "
+                f"valid range [{self.min_glucose}, {self.max_glucose}]."
+            )
+
+        # 2. Rate-of-change check for unrealistic jumps
+        if self.last_valid_glucose is not None and self.last_validation_time is not None:
+            time_delta = current_time - self.last_validation_time
+            if time_delta > 0:
+                # Normalize the max allowed delta to the actual time step
+                allowed_delta = self.max_glucose_delta_per_5_min * (time_delta / 5.0)
+                glucose_delta = abs(glucose_value - self.last_valid_glucose)
+
+                if glucose_delta > allowed_delta:
+                    raise ValueError(
+                        f"RATE_OF_CHANGE_ERROR: Glucose jump of {glucose_delta:.1f} mg/dL over "
+                        f"{time_delta:.1f} min is unrealistic (max allowed: {allowed_delta:.1f} mg/dL)."
+                    )
+
+        # If all checks pass, update state and return the value
+        self.last_valid_glucose = glucose_value
+        self.last_validation_time = current_time
+        return glucose_value
+
+    def validate_insulin(self, dose: float) -> float:
+        """Validates that a proposed insulin dose is non-negative."""
+        if dose < 0:
+            return 0.0
+        return dose

iints/core/safety/supervisor.py

@@ -0,0 +1,39 @@
+from typing import Optional
+
+from iints.core.safety.config import SafetyConfig
+from iints.core.supervisor import IndependentSupervisor as FullSupervisor
+
+class IndependentSupervisor(FullSupervisor):
+    """
+    Safety supervisor that operates independently to validate insulin delivery.
+    Enforces hard constraints on insulin delivery to prevent hypoglycemia and other hazards.
+    """
+    def __init__(self, safety_config: Optional[SafetyConfig] = None):
+        super().__init__(safety_config=safety_config)
+
+    def validate_insulin_dose(
+        self,
+        proposed_dose: float,
+        current_glucose: float,
+        active_insulin: float,
+        time_since_last_dose: float,
+    ) -> float:
+        """
+        Backward-compatible API that routes through the full supervisor.
+        """
+        result = self.evaluate_safety(
+            current_glucose=current_glucose,
+            proposed_insulin=proposed_dose,
+            current_time=0.0,
+            current_iob=active_insulin,
+        )
+        return result["approved_insulin"]
+
+# Alias for backward compatibility as the codebase migrates
+SafetySupervisor = IndependentSupervisor
+
+class InputValidator:
+    """
+    Validates simulation inputs.
+    """
+    pass

iints/core/simulation/scenario_parser.py

@@ -0,0 +1,61 @@
+# src/simulation/scenario_parser.py
+
+from typing import List, Dict, Any, Tuple
+
+from iints.core.simulator import StressEvent
+from iints.validation import load_scenario, scenario_to_payloads, build_stress_events
+
+def parse_scenario(file_path: str) -> Tuple[Dict[str, Any], List[StressEvent]]:
+    """
+    Parses a scenario from a JSON file.
+
+    Args:
+        file_path: The path to the scenario JSON file.
+
+    Returns:
+        A tuple containing:
+        - A dictionary with scenario metadata (name, description).
+        - A list of StressEvent objects.
+        
+    Raises:
+        ValueError: If the file format or content is invalid.
+    """
+    try:
+        scenario = load_scenario(file_path)
+    except Exception as e:
+        raise ValueError(f"Invalid scenario file {file_path}: {e}")
+
+    metadata = {
+        "name": scenario.scenario_name,
+        "description": scenario.description or "",
+        "version": scenario.scenario_version,
+        "source_file": file_path,
+    }
+
+    payloads = scenario_to_payloads(scenario)
+    events: List[StressEvent] = build_stress_events(payloads)
+    return metadata, events
+
+if __name__ == '__main__':
+    # A simple test to demonstrate the scenario parser
+    print("--- Testing Scenario Parser ---")
+    
+    # Use the example scenario created earlier
+    example_path = "scenarios/example_scenario.json"
+    
+    try:
+        print(f"Parsing scenario file: {example_path}")
+        scenario_metadata, scenario_events = parse_scenario(example_path)
+        
+        print("\nSuccessfully parsed scenario:")
+        print(f"  Name: {scenario_metadata['name']}")
+        print(f"  Description: {scenario_metadata['description']}")
+        
+        print("\nEvents:")
+        for ev in scenario_events:
+            print(f"  - {ev}")
+            
+    except ValueError as e:
+        print(f"\nError parsing scenario: {e}")
+    except Exception as e:
+        print(f"\nAn unexpected error occurred: {e}")