Skip to content

laser.generic.SIR

laser.generic.SIR

Export required components for an SIR model.

Agents transition from Susceptible to Infectious upon infection and are infectious for a duration. Agents transition from Infectious to Recovered upon recovery. Agents remain in the Recovered state indefinitely (no waning immunity).

Infectious(model, infdurdist, infdurmin=1, validating=False)

Infectious Component for SIR/SEIR Models (With Recovery to Immune)

This component manages agents in the infectious state for models where infected individuals recover permanently (i.e., transition to a RECOVERED state without waning). It supports agent-level infection durations and patch-level tracking of recoveries over time.

Infectious component for an SIR/SEIR model - includes infectious duration, no waning immunity in newly_recovered state.

Agents transition from Infectious to Recovered after the infectious period (itimer). Tracks number of agents recovering each tick in model.nodes.newly_recovered.

Responsibilities
  • Initializes infected agents and their infection timers (itimer) based on scenario input
  • Decrements itimer daily for infectious agents
  • Transitions agents from INFECTIOUS to RECOVERED when itimer == 0
  • Updates patch-level state variables:
    • I[t, i]: infectious count at tick t in node i
    • R[t, i]: recovered count
    • recovered[t, i]: number of recoveries during tick t
Required Inputs
  • model.scenario.I: number of initially infected individuals per patch
  • infdurdist: function returning infection durations
  • infdurmin: minimum infectious period (default = 1 day)
Outputs
  • model.people.itimer: countdown timers per agent
  • model.nodes.I[t], .R[t]: infectious and recovered counts per patch
  • model.nodes.recovered[t]: daily recoveries per patch
Step Behavior
  • Infectious agents decrement itimer
  • When itimer == 0, agent state is set to RECOVERED
  • Patch-level I and R are updated; recovered logs today's transitions
Validation
  • Ensures internal consistency between agent state and timer
  • Confirms agents with itimer == 1 recover exactly one day later
  • Validates population conservation (S + I + R = N)
Plotting

The plot() method shows per-node and total infectious counts across time.

Examples:

1
2
3
4
5
6
model.components = [
    SIR.Susceptible(model),
    InfectiousIR(model, infdurdist),
    SIR.Recovered(model),
    ...
]

step(tick)

Step function for the Infected component.

Parameters:

Name Type Description Default
tick int

The current tick of the simulation.

 required

Recovered(model, validating=False)

Recovered Component for SIR/SEIR Models (Permanent Immunity)

This component manages agents in the recovered state in models where immunity does not wane (i.e., once recovered, agents stay recovered permanently). It tracks the number of recovered individuals over time at the patch level, but performs no active transitions itself — recovery transitions must be handled by upstream components.

Responsibilities
  • Initializes agents as recovered if specified in model.scenario.R
  • Tracks per-patch recovered counts over time in model.nodes.R
  • Verifies consistency between agent state and aggregate recovered counts
  • Propagates recovered totals forward unchanged (unless modified by other components)
Required Inputs
  • model.scenario.R: number of initially recovered individuals per node
Outputs
  • model.nodes.R[t, i]: number of recovered individuals at tick t in node i
Step Behavior
  • At each tick, carries forward: R[t+1] = R[t]
  • This component does not change any agent's state or internal timers
Validation
  • Ensures per-agent state matches aggregate R counts before and after each step
  • Detects accidental changes to recovered counts not explained by upstream logic
Plotting

The plot() method shows per-node and total recovered counts over time.

Examples:

1
2
3
4
5
model.components = [
    SIR.Susceptible(model),
    InfectiousIR(model, infdurdist),
    Recovered(model),  # passive tracker, assumes recovery handled upstream
]

Susceptible(model, validating=False)

Susceptible Component for Patch-Based Agent-Based Models (S, SI, SIS, SIR, SEIR, etc.)

This component initializes and tracks the count of susceptible individuals (S) in a spatially structured agent-based model. It is compatible with all standard LASER disease progression models that include a "susceptible" state.

Responsibilities
  • Initializes agent-level properties:
    • nodeid: Patch ID of each agent (uint16)
    • state: Infection state (int8), defaulting to State.SUSCEPTIBLE
  • Initializes node-level property:
    • S[t, i]: Susceptible count in node i at time t
  • At each timestep, propagates the susceptible count forward (S[t+1] = S[t]), unless modified by other components (e.g., exposure, births).
  • Validates consistency between patch-level susceptible counts and agent-level state.
Usage

Add this component early in the component list for any model with SUSCEPTIBLE agents, typically before transmission or exposure components. Compatible with:

  • SIR.Transmission
  • SIR.Exposure
  • SIR.Infectious
  • SIR.Recovered
  • Custom SEIRS extensions
Requires
  • model.people: A LaserFrame for all agents
  • model.nodes: Patch-level state
  • model.scenario: Input DataFrame with population and optionally S columns
  • model.params.nticks: Number of simulation ticks
Validation
  • Ensures consistency of susceptible counts before and after each step
  • Prevents unintentional state drift by validating against agent state values
Output
  • model.nodes.S: A (nticks+1, num_nodes) array of susceptible counts
  • Optional plotting via plot() for visual inspection of per-node and total S
Step Behavior

For tick t: S[t+1] = S[t] # Unless explicitly modified by other components

This component does not alter agent states directly but serves as a synchronized counter and validator of susceptible individuals.

Examples:

1
2
3
4
5
6
7
model.components = [
    SIR.Susceptible(model),
    SIR.Transmission(model, ...),
    SIR.Exposure(model),
    SIR.Infectious(model, ...),
    SIR.Recovered(model),
]

Transmission(model, infdurdist, infdurmin=1, seasonality=None, validating=False)

Transmission Component for SIS/SIR/SIRS Models (S → I with Duration)

This component simulates the transition from SUSCEPTIBLE to INFECTIOUS in models where infectious individuals have a finite infection duration (itimer). It supports full spatial coupling and allows infection durations to vary by node and tick.

Agents transition from Susceptible to Infectious based on force of infection. Sets newly infectious agents' infection timers (itimer) based on infdurdist and infdurmin. Tracks number of new infections each tick in model.nodes.newly_infected.

Responsibilities
  • Computes force of infection (FOI) λ = β * (I / N) per patch each tick
  • Applies optional spatial coupling via model.network (infection pressure transfer)
  • Converts FOI into Bernoulli probabilities using p = 1 - exp(-λ)
  • Infects susceptible agents stochastically, assigning per-agent itimer
  • Updates patch-level susceptible (S) and infectious (I) counts
  • Records number of new infections per tick in model.nodes.newly_infected
Required Inputs
  • model.params.beta: transmission rate (global)
  • model.network: [n x n] matrix of transmission coupling
  • infdurdist(tick, node): callable sampling the infectious duration distribution
  • model.people.itimer: preallocated per-agent infection timer
Outputs
  • model.nodes.forces[t, i]: computed FOI in node i at time t
  • model.nodes.newly_infected[t, i]: new infections in node i on time step t
Step Behavior
  • Computes FOI (λ) for each node
  • Applies inter-node infection pressure via model.network
  • Converts FOI into a Bernoulli probability using: p = 1 - exp(-λ)
  • Infects susceptible agents probabilistically
  • Updates state and records incidence
Validation
  • Ensures consistency between incidence and change in I
  • Checks for correct state and population accounting before and after tick
Plotting

The plot() method visualizes per-node FOI (λ) over simulation time.

Examples:

1
2
3
4
5
model.components = [
    SIR.Susceptible(model),
    TransmissionSI(model, infdurdist),
    InfectiousIR(model, infdurdist),
]

Initializes the TransmissionSI component.

Parameters:

Name Type Description Default
model Model

The epidemiological model instance.

 required
infdurdist Callable[[int, int], float]

A function that returns the infectious duration for a given tick and node.

 required
infdurmin int

Minimum infectious duration.

 1
seasonality Union[ValuesMap, ndarray]

Seasonality modifier for transmission rate. Defaults to None.

 None
validating bool

Enable component-level validation. Defaults to False.

 False