seird-simulator

Epidemiological modeling system based on SEIRD differential equations with extensions for vaccination, immunity waning, asymptomatic fraction, hospitalization, and differential mortality. Modular architecture supporting individual and batch simulations parallelized with OpenMP, including prevention of division by zero, clipping of negative values, and error control in adaptive integrators.

Implements three numerical methods: explicit Euler, 4th-order Runge-Kutta (RK4), and Runge-Kutta-Fehlberg 4-5 (Dormand-Prince), adaptive and optimal for systems with variable or potentially stiff dynamics, with automatic step size adjustment and integration statistics.

Exports results to CSV with derived metrics (effective R₀, active population) and ASCII visualization.

📂 Project Structure

seird-simulator/
│   CMakeLists.txt           # Build configuration for CMake
│   docker-compose.yml       # Docker Compose setup
│   Dockerfile               # Docker image build instructions
│   ford.yml                 # Project-specific configuration (custom)
│   LICENSE                  # License file
│   Makefile                 # Traditional build system
│   README.md                # Project README
│
├───build-cmake              # CMake build output directory (generated after build)
├───data                     # Output data for simulations (generated during runtime)
├───doc                      # Documentation files (generated)
├───src                      # Source code modules
│       io_mod.f90               # Input/Output module
│       main.f90                 # Main program
│       numerics_mod.f90         # Numerical methods module
│       parameters_mod.f90       # Model parameters module
│       precision_mod.f90        # Precision and numerical constants module
│       seird_model_mod.f90      # SEIRD model equations module
│       visualization_mod.f90    # Visualization module (ASCII)
│
└───test                     # Unit and integration tests
        test_io.pf                # Tests for I/O module
        test_main.pf              # Tests for main program
        test_numerics.pf          # Tests for numerical methods
        test_parameters.pf        # Tests for parameters module
        test_precision.pf         # Tests for precision module
        test_seird_model.pf       # Tests for SEIRD model module
        test_visualization.pf     # Tests for visualization module

⚙️ Installation & Usage

🐳 Using Docker (recommended)

# 1. Build the Docker image
docker-compose build

# 2. Start the container
docker-compose up -d

Access the running container:

docker exec -it seird_fortran bash

Inside the container:

# Clean previous builds
make clean

# Run tests (unit + integration)
make test

# Run a simulation (example command)
make run ARGS="40 RK45 1000 20 5 0 0 0.6 0.25 0.12 0.015 1000 0.05 1.2 0.01 0.2 0.05 0.01"

Results are stored in /app/data (mapped to ./data on the host). During execution, the program prints an ASCII visualization of compartment evolution and integration statistics.

---

🧩 Command-line Arguments

The executable accepts 18 positional arguments defining simulation time, numerical method, initial conditions, and epidemiological parameters.

Position	Parameter	Example Value	Description
1	DAYS	40	Duration of the simulation in days
2	METHOD	RK45	Numerical method (EULER, RK4, or RK45)
3	S0	1000	Initial number of susceptible individuals
4	E0	20	Initial number of exposed individuals
5	I0	5	Initial number of infected individuals
6	R0	0	Initial number of recovered individuals
7	D0	0	Initial number of deceased individuals
8	BETA	0.6	Transmission rate (probability of infection per contact)
9	SIGMA	0.25	Incubation rate (1/incubation period)
10	GAMMA	0.12	Recovery rate (1/infectious period)
11	MU	0.015	Baseline mortality rate
12	N	1000	Total population
13	VACCINATION_RATE	0.05	Fraction of population vaccinated per day
14	CONTACT_RATE	1.2	Average number of daily contacts per person
15	WANING_IMMUNITY_RATE	0.01	Rate of immunity loss (vaccinated or recovered)
16	ASYMPTOMATIC_FRACTION	0.2	Fraction of infected individuals that are asymptomatic
17	HOSPITALIZATION_RATE	0.05	Fraction of symptomatic cases that require hospitalization
18	MORTALITY_RATE_SEVERE	0.01	Mortality among hospitalized (severe) cases

---

📊 Output

CSV Output (stored in ./data/):

Day,Susceptibles,Expuestos,Infectados,Recuperados,Muertos,Vacunacion,Activos,RatioInfectados,ContactRate,WaningImmunity

Includes derived metrics such as effective R₀ and active population fraction.

Terminal Output:

• ASCII time-series visualization of compartment evolution.
• Integration statistics (accepted/rejected steps, max error, step-size adaptation).

Documentation:

• Automatically generated by FORD at container startup → stored in /app/doc (or ./doc/ on the host).