SIR

The Susceptible-Infected-Recovered model. A basic epidemic model where recovered individuals gain permanent immunity.

Compartments

• Susceptible: individuals who can be infected
• Infected: individuals who are currently infectious
• Recovered: individuals who have recovered and are immune

Transitions

• Susceptible → Infected: mediated by transmission_rate and the number of Infected individuals
• Infected → Recovered: spontaneous at recovery_rate

Parameters

Some parameters can be provided in multiple forms. For example, you can pass transmission_rate directly instead of the default R0, or infectious_period instead of recovery_rate, which is converted automatically. If both forms are supplied, the rate form is used and the response includes a warning. See Preset conversions and precedence for details.

Parameter	Status	Default	Description
R0	Default	2.5	Basic reproduction number.
transmission_rate	Alternative to R0	derived	$\beta$. Per-contact transmission rate. Default: R0 * recovery_rate / CONTACT_MATRIX_EIGENVALUE_ALL.
recovery_rate	Default	0.1	I → R rate.
infectious_period	Alternative to recovery_rate	unset	Days infectious. When passed, recovery_rate = 1 / infectious_period.

CONTACT_MATRIX_EIGENVALUE_ALL is the dominant eigenvalue of the chosen population's contact matrix, summed over layers. With the defaults, R0 stays at 2.5 and $\beta$ depends on the population: about 0.0178 for United_States and 0.0181 for United_States__Vermont. If you pass transmission_rate, it is used as given, so R0 is no longer fixed at 2.5. To see the effective transmission_rate, set output.include_parameters.

Examples

Rate form

curl -X POST https://epyscenario-api.isi.it/api/v1/simulations \
-H "Content-Type: application/json" \
-d '{
  "model": {
    "preset": "SIR",
    "parameters": {"transmission_rate": 0.3, "recovery_rate": 0.1}
  },
  "population": {"name": "United_States"},
  "simulation": {"start_date": "2024-01-01", "end_date": "2024-04-01", "Nsim": 10}
}'

Using R0 and infectious_period

curl -X POST https://epyscenario-api.isi.it/api/v1/simulations \
-H "Content-Type: application/json" \
-d '{
  "model": {
    "preset": "SIR",
    "parameters": {"R0": 2.5, "infectious_period": 10.0}
  },
  "population": {"name": "United_States"},
  "simulation": {"start_date": "2024-01-01", "end_date": "2024-04-01", "Nsim": 10}
}'

Seeding initial conditions (percentage)

Seed 0.1% of the population as Infected. The remainder goes to the first compartment (Susceptible). Values in initial_percentages are percentages, not fractions.

curl -X POST https://epyscenario-api.isi.it/api/v1/simulations \
-H "Content-Type: application/json" \
-d '{
  "model": {
    "preset": "SIR",
    "parameters": {"R0": 2.5, "infectious_period": 10.0}
  },
  "population": {"name": "United_States"},
  "simulation": {"start_date": "2024-01-01", "end_date": "2024-04-01", "Nsim": 10},
  "initial_conditions": {
    "method": "percentage",
    "initial_percentages": {"Infected": 0.1}
  }
}'