Simulation Config Module

Simulation configuration management.

This module handles the configuration of simulation runs, including parameter validation, protocol integration, and resource management. It ensures all simulation parameters are properly validated before being used in a simulation run.

Classes

SimulationConfig: Main configuration class that encapsulates all simulation parameters

Key Features

Parameter validation for all configuration sections
Protocol integration with validation
Resource management
Default value handling
Type checking and range validation

Configuration Structure

Example YAML configuration structure:

simulation:
  type: "des"
  num_patients: 1000
  duration_days: 365
  random_seed: 42
  verbose: true
  start_date: "2023-01-01"
  resources:
    capacity:
      doctors: 5
      nurses: 10
      oct_machines: 3

clinical_model:
  disease_states: ["NAIVE", "STABLE", "ACTIVE", "HIGHLY_ACTIVE"]
  transition_probabilities:
    NAIVE:
      STABLE: 0.3
      ACTIVE: 0.6
      HIGHLY_ACTIVE: 0.1
    STABLE:
      STABLE: 0.7
      ACTIVE: 0.3
  vision_change:
    base_change:
      NAIVE:
        injection: [5, 2]
        no_injection: [0, 1]
      STABLE:
        injection: [2, 1]
        no_injection: [-1, 0.5]
    time_factor:
      max_weeks: 52
    ceiling_factor:
      max_vision: 100
    measurement_noise: [0, 0.5]

Notes

All numeric parameters are validated against expected ranges
Probability parameters must sum to 1 where applicable
Dates must be in YYYY-MM-DD format
Missing parameters will use sensible defaults where possible

class simulation.config.SimulationConfig(parameters, protocol, simulation_type, num_patients, duration_days, random_seed, verbose, start_date, resources=None, sensitivity_analysis=None)[source]

Bases: object

Configuration for a simulation run with protocol objects.

Added direct initialization support for testing purposes.

This class encapsulates all configuration parameters needed to run a simulation, including treatment protocols, patient parameters, and resource constraints. Provides validation methods for all configuration sections.

Parameters:

parameters (Dict[str, Any]) – Dictionary of simulation parameters
protocol (TreatmentProtocol) – Treatment protocol to use in simulation
simulation_type (str) – Type of simulation (‘abs’ or ‘des’)
num_patients (int) – Number of patients to simulate
duration_days (int) – Duration of simulation in days
random_seed (int) – Random seed for reproducibility
verbose (bool) – Whether to enable verbose logging
start_date (datetime) – Simulation start date
resources (Optional[Dict[str, Any]], optional) – Resource configuration dictionary
sensitivity_analysis (Optional[Dict[str, Any]], optional) – Sensitivity analysis configuration

Variables:

parameters (Dict[str, Any]) – Raw simulation parameters
protocol (TreatmentProtocol) – Treatment protocol instance
simulation_type (str) – Simulation type identifier
num_patients (int) – Number of simulated patients
duration_days (int) – Simulation duration
random_seed (int) – Random seed value
verbose (bool) – Verbosity flag
start_date (datetime) – Simulation start date
resources (Optional[Dict[str, Any]]) – Resource configuration
sensitivity_analysis (Optional[Dict[str, Any]]) – Sensitivity analysis configuration

parameters: Dict[str, Any]

protocol: TreatmentProtocol

simulation_type: str

num_patients: int

duration_days: int

random_seed: int

verbose: bool

start_date: datetime

resources: Optional[Dict[str, Any]] = None

sensitivity_analysis: Optional[Dict[str, Any]] = None

get_vision_params()[source]

Get validated vision-related parameters.

Returns:: Validated vision parameters
Return type:: Dict[str, Any]
Raises:: ValueError – If required parameters are missing or invalid

Notes

Validates the following parameters: - baseline_mean: Valid ETDRS letter range (30-85) - measurement_noise_sd: Reasonable measurement noise (0-5) - max_letters: ETDRS maximum (0-100) - min_letters: ETDRS minimum (0-30) - headroom_factor: Must be between 0 and 1

get_maintenance_params()[source]

Get validated maintenance phase parameters.

Returns:: Validated maintenance phase parameters
Return type:: Dict[str, Any]
Raises:: ValueError – If required parameters are missing or invalid

Notes

Validates the following parameters: - memory_factor: Must be between 0 and 1 - base_effect_ceiling: Maximum reasonable improvement (0-15) - regression_factor: Must be between 0 and 1 - random_effect_mean: Reasonable range for log-normal mean (-2 to 2) - random_effect_sd: Reasonable range for log-normal SD (0 to 1) - decline_probability: Must be probability (0 to 1) - decline_effect_mean: Reasonable vision loss range (-5 to 0) - decline_effect_sd: Reasonable variation in loss (0 to 2)

get_loading_phase_params()[source]

Get validated loading phase parameters.

Returns:: Validated loading phase parameters
Return type:: Dict[str, Any]
Raises:: ValueError – If required parameters are missing, invalid, or probabilities don’t sum to 1

Notes

Validates the following parameters: - vision_improvement_mean: Reasonable letter improvement (0-15) - vision_improvement_sd: Reasonable variation (0-5) - improve_probability: Must be probability (0-1) - stable_probability: Must be probability (0-1) - decline_probability: Must be probability (0-1)

get_resource_params()[source]

Get resource configuration parameters.

Returns:: Resource parameters with defaults: - doctors: 5 - nurses: 5 - oct_machines: 5
Return type:: Dict[str, Any]

Notes

First checks simulation.resources.capacity if it exists, otherwise falls back to default values.

get_simulation_params()[source]

Get general simulation parameters.

Returns:: Simulation parameters including: - end_date: datetime (calculated from start_date + duration_days)
Return type:: Dict[str, Any]

get_des_params()[source]

Get DES-specific parameters.

Returns:

DES parameters with defaults:

daily_capacity: 20 patients
days_per_week: 5 days
patient_generation: - rate_per_week: 3 patients - random_seed: None (use simulation seed)

Return type:

Dict[str, Any]

get_output_params()[source]

Get output configuration parameters.

Returns:: Output parameters with defaults: - save_results: True - database: ‘simulations.db’ - plots: True - verbose: False
Return type:: Dict[str, Any]

get_clinical_model_params()[source]

Get validated clinical model parameters.

Returns:: Validated clinical model parameters
Return type:: Dict[str, Any]
Raises:: ValueError – If required sections or parameters are missing

Notes

Validates the following required sections: - disease_states - transition_probabilities - vision_change

For vision_change, validates: - base_change - time_factor - ceiling_factor - measurement_noise

load_parameter_file(file_path)[source]

Load parameters from an external YAML file.

Parameters:

file_path (str) – Path to the parameter file

Returns:

Dictionary containing the loaded parameters

Return type:

Dict[str, Any]

Raises:

FileNotFoundError – If the parameter file cannot be found
ValueError – If the parameter file is invalid

get_treatment_discontinuation_params()[source]

Get treatment discontinuation parameters.

Returns:: Treatment discontinuation parameters including: - enabled: Whether discontinuation is enabled - criteria: Discontinuation criteria configuration - monitoring: Post-discontinuation monitoring configuration - retreatment: Treatment re-entry configuration
Return type:: Dict[str, Any]

Notes

If a parameter_file is specified in the discontinuation configuration, loads the parameters from that file. Otherwise, falls back to the parameters in the clinical model.

get_sensitivity_analysis_params()[source]

Get sensitivity analysis parameters if enabled.

Returns:: Dictionary containing sensitivity analysis parameters: - enabled: Whether sensitivity analysis is enabled - parameter_file: Path to sensitivity parameter file - selected_variation: Name of selected parameter variation - variations: Dictionary of parameter variations if loaded
Return type:: Dict[str, Any]

Notes

If sensitivity analysis is enabled, loads the parameter variations from the specified file and applies the selected variation.

apply_sensitivity_variation(variation_name)[source]

Apply a sensitivity analysis variation to the parameters.

Parameters:: variation_name (str) – Name of the variation to apply
Raises:: ValueError – If the variation does not exist
Return type:: None

Notes

This method modifies the parameters in place by applying the specified variation from the sensitivity analysis file.

get_cost_parameters()[source]

Get cost parameters if enabled.

Returns:: Dictionary containing cost parameters or empty dict if not enabled
Return type:: Dict[str, Any]

classmethod from_yaml(config_name)[source]

Create configuration from YAML with protocol objects.

Parameters:: config_name (str) – Name of the configuration to load
Returns:: New SimulationConfig instance
Return type:: SimulationConfig
Raises:: ValueError – If protocol is invalid or required parameters are missing

Notes

Uses ProtocolParser to load and validate the full configuration, including protocol definitions and parameter validation.

__init__(parameters, protocol, simulation_type, num_patients, duration_days, random_seed, verbose, start_date, resources=None, sensitivity_analysis=None)

Parameters:

parameters (Dict[str, Any])
protocol (TreatmentProtocol)
simulation_type (str)
num_patients (int)
duration_days (int)
random_seed (int)
verbose (bool)
start_date (datetime)
resources (Dict[str, Any] | None)
sensitivity_analysis (Dict[str, Any] | None)

Return type:

None