# ABM Framework - Executive Summary

## Project Overview

The ABM Framework is a Python-based platform for building sophisticated agent-based models (ABMs) with a focus on social systems and public health applications. The framework is designed to support medium-scale simulations (1,000 to 1 million agents) and is specifically tailored for academic researchers in epidemiology and public health.

**Core Strengths:**
- Flexible representation of heterogeneous agents with diverse attributes and behaviors
- Network-based modeling of complex social interactions and relationships
- Event-driven simulation architecture for computational efficiency
- Integrated support for parameter exploration, calibration, and scenario analysis
- Extensible design that allows researchers to define custom agent types and behaviors

## System Architecture

The framework follows a layered architecture that separates concerns at different scales:

### Layer 1: Core Management (Agents, Relationships, Events)
At the foundation, the framework provides base classes for entities (agents, relationships/edges) and a scheduling system. Agents represent any entity (individuals, diseases, institutions), edges represent connections between agents, and the scheduler manages discrete time stepping and event execution.

### Layer 2: Simulation Coordination
The Simulation layer orchestrates a single model run, using a WorldBuilder to configure the initial state, then managing the collectives, networks, and time progression while collecting data throughout execution.

### Layer 3: Parallel Execution
The Batch layer enables running multiple simulations in parallel with different parameter configurations, leveraging multi-core processors for efficiency.

### Layer 4: Workflow & Analysis
The Workflow layer provides high-level tools for complex analyses: parameter sweeps for exploration, calibration for fitting to observed data, experiments for scenario comparison, and analysis utilities for post-processing results.

## Key Design Decisions

1. **Generic Collective Abstraction**: Rather than just "populations," agents are organized into `Collectives` — a flexible base class that can be subclassed to create domain-specific groupings (age groups, health status, risk levels, etc.). `Population` is a simple subclass that includes all agents.

2. **Network-Centric Modeling**: Rather than explicit spatial representation, agents interact through multiple typed networks (friendship, contact, work, etc.). Each network type is maintained separately to avoid complexity while maintaining clear separation of concerns.

3. **Event-Driven Architecture**: Agents don't execute synchronous step() methods. Instead, behaviors are defined through events scheduled for specific times, making the framework computationally efficient for sparse activity patterns.

4. **WorldBuilder for Initialization**: The `WorldBuilder` class provides a clean, domain-specific way to configure collectives, networks, and initial relationships for a simulation run.

5. **Pluggable Graph Backends**: The framework abstracts away direct graph library manipulation, supporting NetworkX by default with optional igraph backend for performance-critical scenarios.

6. **Calibration-Ready Workflow**: The framework integrates statistical inference capabilities, enabling researchers to calibrate model parameters against observed data and run subsequent experiments with calibrated parameters.

## Primary Use Cases

- **Epidemic Modeling**: Simulating disease spread through contact networks with intervention analysis
- **Public Health Interventions**: Evaluating vaccination strategies, resource allocation, and policy impacts
- **Social Dynamics**: Opinion formation, polarization, information spread on social networks
- **Network Evolution**: Understanding how relationships form and change over time

## Open Questions for Feedback

Before proceeding with implementation, we need clarification on:

1. **Graph Backend Priority**: Should we prioritize NetworkX for breadth or igraph for dense networks? Are there specific network densities or sizes you anticipate?

2. **Calibration Method**: Which statistical inference approaches are most important to support initially (e.g., Approximate Bayesian Computation, traditional Bayesian calibration, emulator-based approaches)?

3. **HPC Integration**: What job scheduler systems should we target for distributed execution (SLURM, others)?

4. **Data Collection Scope**: Are there specific metrics or data types beyond agent/network statistics that should be built-in vs. left as user extensions?

5. **API Stability**: Should we prioritize ease of initial use or advanced extensibility features in the first release?

## Next Steps

**Immediate**: Clarify the open questions above to guide implementation priorities.

**Short-term**:
- Build core layer (Agent, Edge, Population, NetworkManager, Scheduler)
- Implement Simulation and Batch layers
- Create basic example models

**Medium-term**:
- Develop workflow layer (ParameterSweep, Experiment, Calibrator)
- Integrate statistical inference capabilities
- Add comprehensive documentation and tutorials

**Long-term**:
- Optimize for large-scale (1M+) agent simulations
- Expand HPC support and distributed computing capabilities
- Build community around domain-specific extensions