# ABM Framework Workflow Sequence Diagram

This document illustrates the complete workflow of the ABM Framework using a sequence diagram that shows the interactions between components across all four layers.

## Overview

The workflow progresses through four main stages:
1. **Parameter Sweep** - Explore parameter space
2. **Calibration** - Select realistic parameter configurations
3. **Experiment** - Run scenarios with calibrated parameters
4. **Analysis** - Compare and visualize results

## High-Level Workflow Diagram

This flowchart shows the overall workflow with key sub-components and decision points.

```mermaid
flowchart TD
    Start([User Defines Parameters & Priors]) --> PS[ParameterSweep: Generate Configs]

    PS --> Parallel1{{Run N Simulations<br/>in Parallel}}

    Parallel1 --> Cal[Calibrator: Compare to Targets<br/>Calculate Weights & Resample]

    Cal --> Review{User Reviews<br/>Calibrated Results}

    Review -->|Not Satisfactory| Adjust[Adjust Priors]
    Adjust --> PS

    Review -->|Approved| Exp[Experiment: Receive<br/>Calibrated Configs]

    Exp --> DefScen[User Defines Scenarios]

    DefScen --> ScenLoop{{For Each Scenario}}

    ScenLoop --> Parallel2{{Run N Simulations<br/>in Parallel}}

    Parallel2 --> Sim2[For each Simulation:<br/>WorldBuilder → Core → SingleRunner → Core<br/> w/ scenario-specific behavior]

    Sim2 --> NextScen{More<br/>Scenarios?}

    NextScen -->|Yes| ScenLoop
    NextScen -->|No| Ana[Analysis: Combine All<br/>Scenario Results]

    Ana --> Weight[Apply Calibration Weights]

    Weight --> Metrics[Calculate Metrics &<br/>Generate Visualizations]

    Metrics --> Results([Present Results to User])

    style PS fill:#ffe6cc
    style Cal fill:#d4f1d4
    style Exp fill:#cce0ff
    style Ana fill:#fff9cc
    style Parallel1 fill:#ffcccc
    style Parallel2 fill:#ffcccc
    style ScenLoop fill:#e6ccff
```

## Sequence Diagrams

### Stage 1: Parameter Sweep

Explores the parameter space by running multiple simulations with different parameter configurations.

```mermaid
sequenceDiagram
    autonumber

    participant User
    participant PS as ParameterSweep<br/>(Layer 4)
    participant Batch as Batch<br/>(Layer 3)
    participant Sim as Simulation<br/>(Layer 2)
    participant WB as WorldBuilder<br/>(Layer 2)
    participant SR as SingleRunner<br/>(Layer 2)
    participant Core as Core Layer<br/>(Schedule, Observer,<br/>Entities, Networks)

    User->>PS: Define parameters, priors, sweep size
    PS->>PS: Generate parameter configurations<br/>(List of Dicts)
    PS->>Batch: Pass parameter configs

    loop For each configuration (parallel)
        Batch->>Sim: Assign single ParamDict
        Sim->>WB: Initialize with ParamDict
        WB->>WB: Create Schedule and Observer
        WB->>Core: Create entities, networks, managers
        Core-->>WB: Initialized components
        WB->>WB: Populate Schedule with initial events
        WB-->>Sim: Initialized world
        Sim->>SR: Execute simulation

        loop Until stopping condition
            SR->>Core: Schedule executes next event
            Core->>Core: Agents perform actions
            Core->>Core: Generate new events → Schedule
            Core->>Core: Observer collects data
        end

        SR-->>Sim: Simulation complete
        Sim-->>Batch: Return data (.csv location)
    end

    Batch->>Batch: Concatenate all .csv files<br/>(with header handling)
    Batch-->>PS: Return pooled sweep data
```

### Stage 2: Calibration (Bayesian Melding)

Compares sweep results to calibration targets and selects realistic parameter configurations.

```mermaid
sequenceDiagram
    autonumber

    participant PS as ParameterSweep<br/>(Layer 4)
    participant Cal as Calibrator<br/>(Layer 4)
    participant User

    PS->>Cal: Pass sweep results
    User->>Cal: Define calibration targets
    Cal->>Cal: Compare outputs to targets
    Cal->>Cal: Calculate likelihood weights
    Cal->>Cal: Resample trajectories
    Cal->>Cal: Extract calibrated ParamDicts
    Cal-->>User: Visualization for approval
    User->>Cal: Approve calibrated trajectories
```

### Stage 3: Experiment (Scenario Comparison)

Runs multiple scenarios using calibrated parameters to compare interventions or policies.

```mermaid
sequenceDiagram
    autonumber

    participant Cal as Calibrator<br/>(Layer 4)
    participant Exp as Experiment<br/>(Layer 4)
    participant User
    participant Batch as Batch<br/>(Layer 3)
    participant Sim as Simulation<br/>(Layer 2)
    participant WB as WorldBuilder<br/>(Layer 2)
    participant SR as SingleRunner<br/>(Layer 2)
    participant Core as Core Layer<br/>(Schedule, Observer,<br/>Entities, Networks)

    Cal->>Exp: Pass calibrated parameter configs
    User->>Exp: Define scenarios (A, B, ...)

    loop For each scenario (sequential)
        Exp->>Batch: Pass scenario-specific param configs

        loop For each configuration (parallel)
            Batch->>Sim: Assign ParamDict with scenario tag
            Sim->>WB: Initialize with ParamDict
            WB->>WB: Create Schedule and Observer
            WB->>Core: Create entities, networks, managers<br/>(scenario configures behavior)
            Core-->>WB: Initialized components
            WB->>WB: Populate Schedule with initial events
            WB-->>Sim: Initialized world
            Sim->>SR: Execute simulation

            loop Until stopping condition
                SR->>Core: Schedule executes next event
                Core->>Core: Agents perform actions<br/>(scenario-specific behavior)
                Core->>Core: Generate new events → Schedule
                Core->>Core: Observer collects data
            end

            SR-->>Sim: Simulation complete
            Sim-->>Batch: Return data (.csv location)
        end

        Batch->>Batch: Concatenate scenario .csv files<br/>(with header handling)
        Batch-->>Exp: Return scenario results (.csv)
    end
```

### Stage 4: Analysis & Visualization

Compares scenario results and produces final visualizations and metrics.

```mermaid
sequenceDiagram
    autonumber

    participant Exp as Experiment<br/>(Layer 4)
    participant Ana as Analysis<br/>(Layer 4)
    participant User

    Exp->>Ana: Pass all scenario outputs
    User->>Ana: Define research questions
    Ana->>Ana: Combine scenario .csvs
    Ana->>Ana: Apply resampling weights
    Ana->>Ana: Calculate metrics
    Ana->>Ana: Generate visualizations
    Ana-->>User: Results, plots, comparisons
```

## Key Interactions by Layer

### Layer 4: Workflow & Analysis
- **ParameterSweep**: Generates parameter configurations from prior distributions
- **Calibrator**: Performs Bayesian inference to identify realistic parameter combinations
- **Experiment**: Orchestrates multiple scenario runs using calibrated parameters
- **Analysis**: Compares scenarios and produces final visualizations

### Layer 3: Batch
- Receives parameter configurations (List of Dicts)
- Distributes individual configurations to parallel Simulation instances
- Pools results from all simulations
- Returns aggregated data to caller

### Layer 2: Simulation
- **Simulation**: Receives single ParamDict, coordinates initialization and execution
- **WorldBuilder**: Creates Schedule and Observer, then uses ParamDict to initialize entities, networks, and managers; populates Schedule with initial events for SingleRunner to execute
- **SingleRunner**: Executes simulation loop until stopping condition

### Layer 1: Core
- **Schedule**: Manages event queue and discrete time progression
- **Entities** (Agent, EdgeAgent): Execute actions that generate new events
- **NetworkManager**: Maintains multiple typed networks for agent interactions
- **Observer**: Collects and persists simulation data

## Example: Gonorrhea Screening Model

Using the gonorrhea transmission example from the documentation:

1. **Parameter Sweep**: Tests SymptomProportion ∈ [0.1, 0.8] across 5 runs
2. **Calibration**: Compares prevalence to empirical data (93/2075 positive tests), selects 3 realistic trajectories
3. **Experiment**: Runs two scenarios with calibrated parameters:
   - Scenario A: Monthly screening for asymptomatic individuals
   - Scenario B: No screening for asymptomatic individuals
4. **Analysis**: Compares incidence, healthcare costs, and cost-effectiveness between scenarios

## Data Flow

```
User Input
   ↓
Parameter Configurations (List of Dicts)
   ↓
Batch → Simulations (parallel) → Core (events/data)
   ↓
Pooled Sweep Results (.csv)
   ↓
Calibrator → Calibrated Parameters
   ↓
Experiment → Scenario Batches → Simulations (parallel) → Core
   ↓
Scenario Results (.csv files)
   ↓
Analysis → Weighted Comparisons & Visualizations
   ↓
User Output
```

## Notes

- **Parallelization**: Simulations within a Batch run in parallel. The framework should support flexible parallel execution backends (threads, processes, or distributed systems like Ray/Dask) to enable scaling
- **Sequential Execution**: Scenarios within an Experiment run sequentially (one Scenario/Batch at a time)
- **Data Persistence**: Each simulation writes to .csv; Batch concatenates all .csv files into single file per batch (with appropriate header handling)
- **Initial Events**: WorldBuilder must populate Schedule with initial events, otherwise SingleRunner would have nothing to execute
- **Scenario Implementation**: Scenario parameters (passed through ParamDict) configure specific Core components to behave differently. For example, a "screening frequency" parameter might control how a Screener component schedules testing events
- **Calibration Feedback**: If calibrated trajectories are unsatisfactory, the user manually adjusts prior distributions and re-runs ParameterSweep (not automated)
- **Calibration Weights**: Resampling weights from Calibrator are used in final Analysis for weighted statistics and visualization (e.g., line thickness in plots)