Epimodels

Epimodels is a Python library of mathematical models for epidemiology, designed for simulation studies and parameter inference. It contains deterministic models in both continuous (ODE-based) and discrete (difference equation) time, stochastic CTMC and network models, SDE extensions, a comprehensive fitting and Bayesian inference framework, symbolic analysis tools, Rt estimation, and multiple solver backends.

Note

This library is under active development. Contributions are welcome.

Installation

pip install epimodels

Optional extras:

pip install epimodels[plot]       # matplotlib plotting
pip install epimodels[dataframe]  # pandas DataFrame support
pip install epimodels[jax]        # diffrax/JAX GPU solvers and SDEs
pip install epimodels[network]    # network models (networkx)
pip install epimodels[yaml]       # YAML model files

Quick Start

from epimodels.continuous import SIR

model = SIR()
model([1000, 1, 0], [0, 50], 1001, {'beta': 0.3, 'gamma': 0.1})

print(f"R0 = {model.R0}")  # Basic reproduction number
print(model.summary())      # Epidemic statistics
model.plot_traces()         # Plot results

Parameter Fitting

The sugar API fits any model in one call, either by maximum likelihood or Bayesian inference:

from epimodels.continuous import SIR

model = SIR()
result = model.fit(
    {"I": [1, 3, 8, 20, 50, 80, 60]},
    times=[0, 1, 2, 3, 5, 7, 10],
    params_to_fit={"beta": (0.1, 5.0), "gamma": (0.01, 1.0)},
    total_population=10000,
)
print(result.best_params)

Contents

Getting Started:

• Getting Started
  • Continuous models
  • Discrete models
• Model Overview
  • Discrete models
  • Specialized Models
  • References
• Custom Models
  • Choosing a model family
  • A custom ODE model
  • Symbolic analysis of your model
  • A custom discrete-time model
  • A custom stochastic (CTMC) model
  • A custom network model
  • A custom SDE
  • Registering and sharing custom models
  • Rich validation for custom models
  • Analyses on your custom model
  • Pitfalls and tips
  • References
• Solvers
  • ODE Solvers
  • Available Solvers
  • Performance Benchmarks
  • When to Use Each Solver
  • CTMC Solvers (Stochastic)
  • ODE Solver API Reference
  • CTMC Solver API Reference
  • References
• Parameter Validation System Implementation Guide
  • Overview
  • Architecture
  • Core Components
  • Migration Guide
  • Constraint Language
  • Validation Process
  • Best Practices
  • Testing
  • Available Symbolic Analysis
  • Examples
  • Troubleshooting
  • API Reference
  • Additional Examples
• Model Fitting
  • Quick Start
  • Dataset Management
  • Loss Functions
  • Optimizers
  • Advanced Usage
  • Examples
  • API Reference
  • References
• Bayesian Inference
  • Quick start with the sugar API
  • Using the full API
  • Observation models
  • ArviZ integration
  • References
• Stochastic CTMC Models
  • Available Models
  • Quick Start
  • Simulation Parameters
  • Accessing Results
  • The Gillespie Solver
  • When to Use CTMC Models
  • API Reference
  • References
• Stochastic Differential Equation Models
  • Basic usage
  • Noise magnitude
  • Custom diffusion
  • Limitations
  • References
• Network Models
  • SIR on a network
  • SIS on a network
  • Targeting specific nodes
  • Working without networkx
  • References
• Scenario Analysis: Interventions and Ensembles
  • Intervention scenarios
  • Uncertainty ensembles
• Rt Estimation
  • Basic usage
  • Interpretation
  • Tuning
  • Validation against a simulated epidemic
• Phase Space Analysis
  • Quick Start
  • Time Delay Embedding
  • Phase Portraits
  • API Reference
  • References
• Model Registry
  • Looking up models
  • Registering custom models
• Saving and Loading Models
  • Saving and loading
  • Dict-based API
• VFGen XML Exporter
  • Quick Start
  • Export Options
  • Advanced: Custom Expressions and Functions
  • Supported Models
  • API Reference

Examples:

• Simulating Continuous models
  • SIR model
  • SIR1D
  • SIS model
  • SIRS model
  • SEIR model
  • SEQIAHR model
  • Dengue 4-strain model
  • SIR-SEI model
• Stochastic CTMC Models
  • 1. Running a Single Replicate
  • 2. Multiple Replicates and Uncertainty Quantification
  • 3. Accessing Results
  • 4. Summary Statistics
  • 5. Quantiles and Variance
  • 6. Event Tracking
  • 7. Comparison with Deterministic ODE Model
  • 8. Other Stochastic Models
  • 9. Exporting Results
  • 10. Reproducibility
  • 11. Model Properties
• Simulating Discrete models
  • SIS model
  • SIR Model
  • SEIS Model
  • SEIR Model
  • SIRS Model
  • SIpRpS model
  • SEIpRpS model
  • SIpR model
  • SEIpR model
  • SEQIAHR model
  • Influenza model
• API Features
  • Basic Reproduction Number (R0)
  • Summary Statistics
  • Export to DataFrame
  • Copy and Reset
  • Parameter Validation
  • Complete Example
• Phase Space Analysis Tools
  • Overview
  • 1. Basic Phase Portraits
  • 2. Time Delay Embedding
  • 3. Finding Optimal Time Delay (τ)
  • 4. Finding Optimal Embedding Dimension
  • 5. Automatic Parameter Selection
  • 6. Comparing Different Epidemic Dynamics
  • 7. Analyzing Recurrent Epidemics (SIRS Model)
  • Summary
• Model Fitting Tutorial
  • Overview
  • 1. Setup and Imports
  • 2. Generating Synthetic Data
  • 3. Basic Fitting Workflow
  • 4. Data Registration and Validation
  • 5. Loss Functions
  • 6. Optimizers
  • 7. Advanced Features
  • 8. Practical Example: Handling Noisy and Missing Data
  • 9. Convenience Function
  • 10. Summary and Best Practices
• Parameter Inference for Time-Dependent SIRS Model
  • Model
  • Goal
  • Least Squares Fitting
  • Bayesian Inference (MCMC)
  • Interpretation
• SIRS Autonomous Model with Time-Dependent Parameters
  • Interpretation
• Neipel Heterogeneous SIR Model Example
  • Import Libraries
  • Define Parameters
  • Run Classical SIR Model
  • Run Neipel Heterogeneous SIR Model
  • Plot Comparison: Infected
  • Plot Comparison: Susceptible
  • Plot Comparison: Recovered
  • Summary
• Validation Framework Tutorial
  • Overview
  • 1. Parameter Specifications
  • 2. Creating a Model with Rich Validation
  • 3. Parameter Validation
  • 4. Initial Condition Validation
  • 5. Constraint Language
  • 6. More Complex Model Example
  • 7. Backward Compatibility
  • 8. Generating Documentation
  • Summary
• Advanced Analytical Features
  • Important Note on Endemic Equilibria
  • 1. Basic SIR Model (No Endemic Equilibrium)
  • 2. SIR Model with Vital Dynamics (Has Endemic Equilibrium)
  • 3. Basic Reproduction Number (R0)
  • 4. Equilibrium Analysis
  • 5. Stability Analysis
  • 6. Sensitivity Analysis
  • 7. Visualization
  • 8. Complete Analysis Pipeline
  • Summary

Reference:

• epimodels
  • epimodels package

About:

• License
• Authors
• Changelog
• Version 1.4.0 (2026-09-17)
• Version 1.3.0 (2026-06-14)
• Version 1.2.0 (2026-05-13)
• Version 1.1.0 (2026-04-11)
• Version 1.0.2
• Version 1.0.1
• Version 1.0.0
• Version 0.5.2
• Version 0.5.1
• Version 0.5.0
• Version 0.4.3
• Version 0.4.2
• Version 0.4.1
• Version 0.4.0
• Version 0.1
• References

API Overview

Solvers

ODE Solvers (Unified interface)

• ScipySolver - Scipy-based solver (CPU)

• DiffraxSolver - JAX-accelerated solver (GPU)

CTMC Solvers (Stochastic simulation)

• GillespieSolver - Gillespie Direct Method (SSA)

Model Classes

Continuous Models (ODE-based)

• SIR - Susceptible-Infectious-Removed

• SIS - Susceptible-Infectious-Susceptible

• SIRS - Susceptible-Infectious-Removed-Susceptible

• SEIR - Susceptible-Exposed-Infectious-Removed

• SEQIAHR - COVID-19 model with quarantine

• Dengue4Strain - 4-strain dengue model

• SIRSEI - Malaria vector-host with climate forcing

• SIRSEIData - Malaria with real climate data

• SEIRS_SEI - Vector-borne with environmental effects

• SIR2Strain - Two-strain SIR with cross-immunity

• SIR1D - 1D reduced SIR (beta/gamma tracking)

• SISLogistic - SIS with logistic population growth

• SIRSNonAutonomous - SIRS with time-dependent parameters

• NeipelHeterogeneousSIR - Heterogeneous susceptibility

• EbolaSEIHFRV - Ebola with hospital and funeral transmission

Discrete Models (Difference equations)

• SIR - Susceptible-Infectious-Removed

• SIS - Susceptible-Infectious-Susceptible

• SEIR - Susceptible-Exposed-Infectious-Removed

• SEIS - Susceptible-Exposed-Infectious-Susceptible

• SIRS - Susceptible-Infectious-Removed-Susceptible

• SEQIAHR - COVID-19 model with quarantine

• Influenza - Age-structured influenza model

• SIpRpS - Partial immunity waning

• SEIpRpS - Exposed + partial immunity

• SIpR - Secondary infections from recovered

• SEIpR - Exposed + secondary infections from R

Stochastic Models (CTMC / Gillespie SSA)

• SIR - Stochastic SIR

• SIS - Stochastic SIS

• SIRS - Stochastic SIRS (waning immunity)

• SEIR - Stochastic SEIR (with latent period)

Network Models (event-driven, graph-based)

• NetworkSIR - SIR on networkx graphs, adjacency dicts or matrices

• NetworkSIS - SIS on networks (infection can become endemic)

Stochastic Differential Equations

• SDEModel - Demographic-noise SDE wrapper for any continuous model

Analysis and Inference Tools

• estimate_rt() - Time-varying reproduction number from incidence (Cori/EpiEstim)

• SDEModel - SDE simulation

• simulate_ensemble() - Parameter-uncertainty ensembles

• TraceEnsemble - Ensemble results with quantile bands

• Intervention - Time-bounded parameter change

• Scenario - Model + parameters + interventions

• ScenarioComparison - Side-by-side scenario runs

• fit_model_bayesian() - Bayesian (DE-MCMC) inference

• BayesianFitResult - Posterior samples, credible intervals, ArviZ export

Registry and Serialization

• get_model() - Look up models by name and family

• list_models() - List registered models

• save_model() / load_model() - JSON/YAML model files

Fitting Module

• ModelFitter - Full-featured parameter fitter

• fit_model() - Convenience fitting function

• Dataset - Observed data container

• ScipyOptimizer - Scipy-based optimizer

• JAXOptimizer - Projected gradient optimizer

• MultiStartOptimizer - Multi-start optimizer

Common Methods

All models inherit from BaseModel and share these methods:

Stochastic models (CTMC) also provide:

Indices and tables

• Index

• Module Index

• Search Page