laser.cohorts.components

components

Epidemiological compartment components for cohort-based simulation.

Each class represents one compartment or transition rule that can be composed into a complete compartmental model (SI, SIR, SEIR, etc.). Components are registered on a Model instance and invoked each tick via setup, start_step, step, and end_step.

Exposed

Exposed(model, r_progression, validating=False)

Exposed (E) compartment component.

Tracks individuals who are infected but not yet infectious. Applies non-disease mortality and progression from E to I each time step. Initial E counts are read from the scenario at setup.

Initialize the Exposed component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required
r_progression	ValuesMap	Per-tick, per-node rate of progression from E to I.	required
validating	bool	Enable validation checks during simulation.	False

properties property

properties

Return node properties required by this component.

Returns:

Type	Description
list[PropertyType]	list[PropertyType]: [("newly_infectious", nticks, np.int32, 0)]

states property

states

Return the compartment state names managed by this component.

Returns:

Type	Description
list[str]	list[str]: ["E", "I"]

end_step

end_step(tick)

No-op end-of-step hook for the E compartment.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

setup

setup()

Initialize state E at tick 0 from the scenario E column.

start_step

start_step(tick)

No-op start-of-step hook; carry-forward is handled by the Model.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

step

step(tick)

Apply disease progression to exposed individuals.

Draws newly infectious individuals from a binomial using r_progression, moving them from E to I and recording the flow in nodes.newly_infectious.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

Infectious

Infectious(model, validating=False)

Infectious (I) compartment component.

Tracks the infectious population and applies non-disease mortality each time step. Initial I counts are read from the scenario at setup.

Initialize the Infectious component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required
validating	bool	Enable validation checks during simulation.	False

properties property

properties

Return node properties required by this component.

Returns:

Type	Description
list[PropertyType]	list[PropertyType]: Empty list; mortality tracking belongs to NonDiseaseMortality.

states property

states

Return the compartment state names managed by this component.

Returns:

Type	Description
list[str]	list[str]: ["I"]

end_step

end_step(tick)

No-op end-of-step hook for the I compartment.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

setup

setup()

Initialize state I at tick 0 from the scenario I column.

start_step

start_step(tick)

No-op start-of-step hook; carry-forward is handled by the Model.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

step

step(tick)

No-op step hook for the I compartment.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

InfectiousToRecovered

InfectiousToRecovered(
    model, r_recovery=None, validating=False
)

Bases: Infectious

Infectious (I) compartment with recovery to R.

Extends Infectious by drawing newly recovered individuals each tick and moving them from I to R. Used in SIR and SEIR model configurations.

Initialize the InfectiousToRecovered component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required
r_recovery	ValuesMap | None	Per-tick, per-node recovery rate (I → R). Defaults to zero if not provided.	None
validating	bool	Enable validation checks during simulation.	False

properties property

properties

Return node properties required by this component.

Returns:

Type	Description
list[PropertyType]	list[PropertyType]: Parent properties plus ("newly_recovered", nticks, np.int32, 0).

states property

states

Return the compartment state names managed by this component.

Returns:

Type	Description
list[str]	list[str]: Parent states plus ["R"].

step

step(tick)

Apply recovery (I → R) to infectious individuals.

Draws newly recovered individuals from a binomial using r_recovery, moving them from I to R and recording the flow in nodes.newly_recovered.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

InfectiousToSusceptible

InfectiousToSusceptible(
    model, r_recovery=None, validating=False
)

Bases: Infectious

Infectious (I) compartment with recovery back to S.

Extends Infectious by drawing newly recovered-susceptible individuals each tick and moving them from I to S. Used in SIS model configurations where immunity is not retained after infection.

Initialize the InfectiousToSusceptible component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required
r_recovery	ValuesMap | None	Per-tick, per-node rate of recovery to S (I → S). Defaults to zero if not provided.	None
validating	bool	Enable validation checks during simulation.	False

properties property

properties

Return node properties required by this component.

Returns:

Type	Description
list[PropertyType]	list[PropertyType]: Parent properties plus ("newly_susceptible", nticks, np.int32, 0).

states property

states

Return the compartment state names managed by this component.

Returns:

Type	Description
list[str]	list[str]: Parent states plus ["S"].

step

step(tick)

Apply I → S recovery to infectious individuals.

Draws newly susceptible individuals from a binomial using r_recovery, moving them from I to S and recording the flow in nodes.newly_susceptible.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

Recovered

Recovered(model, validating=False)

Recovered (R) compartment component.

Tracks the recovered population and applies non-disease mortality each time step. Initial R counts are read from the scenario at setup.

Initialize the Recovered component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required
validating	bool	Enable validation checks during simulation.	False

properties property

properties

Return node properties required by this component.

Returns:

Type	Description
list[PropertyType]	list[PropertyType]: Empty list; mortality tracking belongs to NonDiseaseMortality.

states property

states

Return the compartment state names managed by this component.

Returns:

Type	Description
list[str]	list[str]: ["R"]

end_step

end_step(tick)

No-op end-of-step hook for the R compartment.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

setup

setup()

Initialize state R at tick 0 from the scenario R column.

start_step

start_step(tick)

No-op start-of-step hook; carry-forward is handled by the Model.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

step

step(tick)

No-op step hook for the R compartment.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

RecoveredToSusceptible

RecoveredToSusceptible(
    model, r_waning=None, validating=False
)

Bases: Recovered

Recovered (R) compartment with waning immunity back to S.

Extends Recovered by drawing individuals with waned immunity each tick and moving them from R to S. Used in SIRS model configurations.

Initialize the RecoveredToSusceptible component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required
r_waning	ValuesMap | None	Per-tick, per-node rate of waning immunity (R → S). Defaults to zero if not provided.	None
validating	bool	Enable validation checks during simulation.	False

properties property

properties

Return node properties required by this component.

Returns:

Type	Description
list[PropertyType]	list[PropertyType]: Parent properties plus ("newly_susceptible", nticks, np.int32, 0).

states property

states

Return the compartment state names managed by this component.

Returns:

Type	Description
list[str]	list[str]: Parent states plus ["S"].

step

step(tick)

Apply waning immunity (R → S) to recovered individuals.

Draws individuals with waned immunity from a binomial using r_waning, moving them from R to S and recording the flow in nodes.newly_susceptible.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

Susceptible

Susceptible(model, validating=False)

Susceptible (S) compartment component.

Tracks the susceptible population and applies non-disease mortality each time step. Initial S counts are read from the scenario at setup.

Initialize the Susceptible component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required
validating	bool	Enable validation checks during simulation.	False

properties property

properties

Return node properties required by this component.

Returns:

Type	Description
list[PropertyType]	list[PropertyType]: Empty list; mortality tracking belongs to NonDiseaseMortality.

states property

states

Return the compartment state names managed by this component.

Returns:

Type	Description
list[str]	list[str]: ["S"]

end_step

end_step(tick)

No-op end-of-step hook for the S compartment.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

setup

setup()

Initialize state S at tick 0 from the scenario S column.

start_step

start_step(tick)

No-op start-of-step hook; carry-forward is handled by the Model.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

step

step(tick)

No-op step hook for the S compartment.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

TransmissionCommon

TransmissionCommon(
    model,
    beta,
    sink_name,
    flow_name,
    seasonality=None,
    validating=False,
)

Base class for stochastic transmission dynamics.

Computes a frequency-dependent force of infection from the current I and N counts, draws newly infected individuals from a binomial distribution, moves them from S into a configurable sink compartment, and records the flow in a named node property.

Initialize the transmission component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required
beta	ValuesMap	Per-tick, per-node transmission rate.	required
sink_name	str	Name of the destination state for newly infected individuals (e.g., "I" or "E").	required
flow_name	str	Name of the node property that accumulates the newly infected flow count each tick.	required
seasonality	ValuesMap	seasonal transmission factor by time (tick) and location (node)	None
validating	bool	Enable validation checks during simulation.	False

properties property

properties

Return node properties required by this component.

Returns:

Type	Description
list[PropertyType]	list[PropertyType]: Empty list; subclasses add the flow property.

states property

states

Return the compartment state names required by this component.

Returns:

Type	Description
list[str]	list[str]: ["S"]; subclasses add the sink state name.

end_step

end_step(tick)

No-op end-of-step hook for the transmission component.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

setup

setup()

Cache references to the sink state and flow node property arrays.

start_step

start_step(tick)

No-op start-of-step hook for the transmission component.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

step

step(tick)

Apply stochastic transmission, moving individuals from S to the sink state.

Computes the per-node force of infection as beta * I / N, converts to per-tick infection probability, draws newly infected individuals from a binomial distribution, and moves them from S into the sink compartment.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required

TransmissionSE

TransmissionSE(
    model, beta, seasonality=None, validating=False
)

Bases: TransmissionCommon

Transmission component that moves individuals from S to E.

Specialises TransmissionCommon for models with an exposed/latent period (SEI, SEIR, SEIS, SEIRS). Newly infected individuals enter the E compartment before becoming infectious.

Initialize the S → E transmission component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required
beta	ValuesMap	Per-tick, per-node transmission rate.	required
validating	bool	Enable validation checks during simulation.	False

properties property

properties

Return node properties required by this component.

Returns:

Type	Description
list[PropertyType]	list[PropertyType]: Parent properties plus ("newly_infected", nticks, np.int32, 0).

states property

states

Return the compartment state names managed by this component.

Returns:

Type	Description
list[str]	list[str]: Parent states plus ["E"].

TransmissionSI

TransmissionSI(
    model, beta, seasonality=None, validating=False
)

Bases: TransmissionCommon

Transmission component that moves individuals directly from S to I.

Specialises TransmissionCommon for models without an exposed period (SI, SIR, SIS, SIRS). Newly infected individuals enter the I compartment immediately.

Initialize the S → I transmission component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required
beta	ValuesMap	Per-tick, per-node transmission rate.	required
validating	bool	Enable validation checks during simulation.	False

properties property

properties

Return node properties required by this component.

Returns:

Type	Description
list[PropertyType]	list[PropertyType]: Parent properties plus ("newly_infectious", nticks, np.int32, 0).

states property

states

Return the compartment state names managed by this component.

Returns:

Type	Description
list[str]	list[str]: Parent states plus ["I"].