laser.generic.SI

laser.generic.SI

Components for an SI model.

Agents transition from Susceptible to Infectious upon infection. Agents remain in the Infectious state indefinitely (no recovery).

Infectious(model, validating=False)

Infectious Component for SI Models (No Recovery)

This component manages the infectious state in SI-style epidemic models where agents remain infectious indefinitely. It is appropriate for use in models without a recovered or removed state (i.e., no R compartment).

Responsibilities

• Initializes agents as infectious based on model.scenario.I
• Tracks the number of infectious individuals (I) in each patch over time
• Maintains per-tick, per-node counts in model.nodes.I
• Validates consistency between agent states and patch-level totals

Required Inputs

• model.scenario.I: array of initial infected counts per patch
• model.people.state: infection state per agent
• model.people.nodeid: patch assignment per agent
• model.params.nticks: number of timesteps to simulate

Outputs

• model.nodes.I[t, i]: number of infectious individuals in node i at time t

Step Behavior

For each timestep t, this component copies: I[t+1] = I[t] (No recovery or removal; new infections may be added externally.)

Validation

• Ensures that patch-level infectious counts (model.nodes.I) match the agent-level state
• Asserts that the sum of S and I matches total population at initialization
• Validates that infected counts do not change unexpectedly (unless altered by another component)

Plotting

The plot() method shows the number of infectious agents per patch and in total across time.

Examples:

model.components = [
    SIR.Susceptible(model),
    InfectiousSI(model),
    SIR.Transmission(model, ...),
]

step(tick)

Step function for the Infected component.

Parameters:

Name	Type	Description	Default
tick	int	The current tick of the simulation.	required

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:

model.components = [
    SIR.Susceptible(model),
    SIR.Transmission(model, ...),
    SIR.Exposure(model),
    SIR.Infectious(model, ...),
    SIR.Recovered(model),
]

Transmission(model, seasonality=None, validating=False)

Transmission Component for SI-Style Models (S → I Only, No Recovery)

This component simulates the transmission process in simple epidemic models where agents move from the SUSCEPTIBLE to INFECTIOUS state and remain infectious indefinitely. It computes the force of infection (FOI) for each patch and applies it stochastically to susceptible agents.

Agents transition from Susceptible to Infectious based on force of infection. Tracks number of new infections each tick in model.nodes.newly_infected.

Responsibilities

• Computes per-node force of infection (λ) at each tick: λ = β * (I / N), with spatial coupling via a migration matrix
• Applies probabilistic infection to susceptible agents using nb_transmission_step
• Updates per-node S and I counts accordingly
• Tracks new infections (incidence) and FOI values per node and tick

Required Inputs

• model.nodes.I[t]: number of infectious agents per node at tick t
• model.nodes.S[t]: number of susceptible agents per node at tick t
• model.params.beta: transmission rate (global)
• model.network: matrix of spatial coupling between nodes

Outputs

• model.nodes.forces[t, i]: force of infection in node i at tick t
• model.nodes.newly_infected[t, i]: number of new infections in node i at tick 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 state transitions and incidence records
• Checks conservation of population in S and I states
• Validates newly_infected[t] == I[t+1] - I[t]

Plotting

The plot() method displays the force of infection over time per node.

Examples:

model.components = [
    SIR.Susceptible(model),
    TransmissionSIx(model),
    InfectiousSI(model),
]

Transmission Component for SI-Style Models (S → I Only, No Recovery)

Parameters:

Name	Type	Description	Default
model	Model	The epidemic model instance.	required
seasonality	Union[ValuesMap, ndarray]	Seasonality modifier for transmission rate. Can be a ValuesMap or a precomputed array. Defaults to None.	None
validating	bool	Enable component-level validation. Defaults to False.	False