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, along with a comprehensive fitting framework, symbolic analysis tools, and multiple solver backends.

Note

This library is under active development. Contributions are welcome.

Installation

pip install epimodels

For pandas DataFrame support:

pip install epimodels[dataframe]

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

from epimodels.continuous import SIR
from epimodels.fitting import fit_model, Dataset

model = SIR()
dataset = Dataset()
dataset.add_series("I", times=[0, 1, 2, 3, 5, 7, 10], values=[1, 3, 8, 20, 50, 80, 60])

result = fit_model(
    model, dataset,
    params={"beta": (0.1, 5.0), "gamma": (0.01, 1.0)},
    initial_conditions=[1000, 1, 0],
    time_range=[0, 10],
)
print(result.best_params)

Contents

Getting Started:

• Getting Started
  • Continuous models
  • Discrete models
• Model Overview
  • Discrete models
• Solvers
  • ODE Solvers
  • Available Solvers
  • Performance Benchmarks
  • When to Use Each Solver
  • CTMC Solvers (Stochastic)
  • ODE Solver API Reference
  • CTMC Solver API Reference
• 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
• Stochastic CTMC Models
  • Available Models
  • Quick Start
  • Simulation Parameters
  • Accessing Results
  • The Gillespie Solver
  • When to Use CTMC Models
  • API Reference
• Phase Space Analysis
  • Quick Start
  • Time Delay Embedding
  • Phase Portraits
  • API Reference
• 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.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

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

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)

Fitting Module

• ModelFitter - Full-featured parameter fitter

• fit_model() - Convenience fitting function

• Dataset - Observed data container

• ScipyOptimizer - Scipy-based optimizer

• JAXOptimizer - JAX/GPU 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