laser.cohorts

cohorts

Cohort-based compartmental disease modelling for the LASER framework.

Provides composable epidemiological compartments and transmission components for constructing SI, SIR, SEIR, SIS, SIRS, SEI, SEIS, and SEIRS models.

Campaign

Campaign(model, source, start_date=None)

Intervention scheduling component.

Loads a campaign schedule and fires named interventions at the specified ticks, nodes, and compartment states.

Intervention classes are registered on the class-level registry with Campaign.register and looked up by name at each tick.

Example

Campaign.register(Vaccination) schedule = [ ... {"who": "", "what": "Vaccination", "when": 30, ... "where": [0, 1], "parameters": {"coverage": 0.8}, "notes": ""}, ... {"who": ["S"], "what": "Vaccination", "when": [60, 90, 120], ... "where": "", "parameters": {"coverage": 0.6}, "notes": "boosters"}, ... ] campaign = Campaign(model, schedule) model.components = [..., campaign]

Initialize the Campaign component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required
source	dict | list | str | Path	Campaign schedule. One of: a single entry dict a list of entry dicts a file path (str or Path) to a .json or .csv file containing the schedule	required
start_date	str | date | None	Simulation start date in "YYYY-MM-DD" format or as a datetime.date object. Required when any when value is a date string.	None

Raises:

Type	Description
ValueError	If the source path has an unsupported suffix.
ValueError	If any schedule entry omits the required who or where field. Use "*" explicitly to target all states or all nodes.
ValueError	If any what value names an intervention class that has not been registered with Campaign.register.
ValueError	If when values mix integer ticks and date strings (across entries or within a single list).
ValueError	If date-valued when entries are present but start_date is not provided.
ValueError	If a when date is earlier than start_date.

properties property

properties

Return node properties required by this component and its interventions.

Iterates over the unique intervention class names referenced in the schedule, instantiates each registered class with the model, and accumulates their properties declarations into a set so duplicates are dropped automatically.

Returns:

Type	Description
'list[PropertyType]'	list[PropertyType]: Union of all property declarations from interventions used in this campaign's schedule. Order is unspecified.

states property

states

Return compartment states required by this component and its interventions.

Iterates over the unique intervention class names referenced in the schedule, instantiates each registered class with the model, and accumulates their states declarations into a set so duplicates are dropped automatically.

Returns:

Type	Description
'list[str]'	list[str]: Union of all state declarations from interventions used in this campaign's schedule. Order is unspecified.

add_entry

add_entry(entry)

Schedule a ScheduledEntry for dispatch later in the running simulation.

Designed to be called at simulation time — typically from inside another intervention's execute() to add a follow-up dispatch. The entry is routed to self._every_tick if entry.tick is None, otherwise to the appropriate self._at_tick bucket so that the next call to Campaign.step will pick it up.

Parameters:

Name	Type	Description	Default
entry	ScheduledEntry	Fully-formed entry. entry.tick is the absolute simulation tick at which to dispatch (or None for every-tick firing); entry.what must be a registered intervention class name.	required

Raises:

Type	Description
TypeError	If entry is not a ScheduledEntry.
ValueError	If entry.what is not a registered intervention.

end_step

end_step(tick)

No-op end-of-step hook.

Parameters:

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

register classmethod

register(intervention_cls)

Register an intervention class using its __name__ as the schedule key.

Parameters:

Name	Type	Description	Default
intervention_cls	type	Subclass of Intervention to register. The class name becomes the value expected in what fields.	required

setup

setup()

Build the tick-indexed schedule from parsed entries.

start_step

start_step(tick)

No-op start-of-step hook.

Parameters:

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

step

step(tick)

Dispatch all interventions scheduled for this tick.

Fires every-tick interventions first, then tick-specific ones, in the order they appear in the schedule. All what names are validated against the registry at construction time, so the lookup here is unconditional.

Parameters:

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

ConstantPopBirths

ConstantPopBirths(model)

Constant-population birth component.

Reads the per-node death count recorded by NonDiseaseMortality at each tick and adds the same number of individuals back into the S compartment, keeping the total population constant across ticks.

Must be ordered after NonDiseaseMortality in the component list so that non_disease_mortality is populated before births are applied.

Example

ndm = NonDiseaseMortality(model, r_mortality=1/365/70) cpb = ConstantPopBirths(model) model.components = [Susceptible(model), ndm, cpb]

Initialize the ConstantPopBirths component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required

properties property

properties

Return the node properties required by this component.

Returns:

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

states property

states

Return the compartment states used by this component.

Returns:

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

end_step

end_step(tick)

No-op end-of-step hook.

Parameters:

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

setup

setup()

No-op setup hook.

start_step

start_step(tick)

No-op start-of-step hook.

Parameters:

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

step

step(tick)

Add births equal to deaths recorded this tick into the S compartment.

Reads nodes.non_disease_mortality[tick] — the deaths accumulated by NonDiseaseMortality during the current tick — and adds that count to states.S[tick+1], replacing every death with one new susceptible.

Parameters:

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

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

Intervention

Intervention(model)

Base class for all campaign interventions.

Subclass this, implement execute, and register with Campaign.register(MyClass).

Example

class Vaccination(Intervention): ... def execute(self, tick, who, where, params, notes): ... coverage = params.get("coverage", 0.5) ... # move fraction of S to R in the target nodes ... pass Campaign.register("Vaccination", Vaccination)

Initialize the Intervention.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required

properties property

properties

Return node properties required by this intervention.

Override in subclasses to declare per-tick, per-node arrays for recording intervention outputs. These properties are surfaced through Campaign.properties so the model allocates them before the simulation runs.

Returns:

Type	Description
list[PropertyType]	list[PropertyType]: Empty list; subclasses override as needed.

states property

states

Return compartment states required by this intervention.

Override in subclasses to declare any new states the intervention needs (e.g. ["V"] for a vaccination intervention). These states are surfaced through Campaign.states so the model allocates them before the simulation runs.

Returns:

Type	Description
list[str]	list[str]: Empty list; subclasses override as needed.

execute

execute(tick, who, where, params, notes)

Execute the intervention.

Parameters:

Name	Type	Description	Default
tick	int	Current simulation tick (0-indexed).	required
who	list[str] | None	Target state names; None means all states.	required
where	list[int] | None	Target node IDs; None means all nodes.	required
params	dict[str, Any]	Arbitrary parameters from the schedule entry.	required
notes	str	Free-text annotation from the schedule entry.	required

Raises:

Type	Description
NotImplementedError	Subclasses must implement this method.

Migration

Migration(model, r_migration, routing)

Stochastic inter-node migration component with time-varying routing.

Each tick, applies a per-node emigration rate (converted to probability) uniformly across every compartment state. For each source node the total number of emigrants per compartment is drawn from a binomial distribution, then those emigrants are distributed to destination nodes via a sequential- binomial decomposition of the multinomial.

The routing tensor is 3-D so connectivity can vary tick-by-tick. Pass a np.broadcast_to view to represent static routing without copying:

routing_3d = np.broadcast_to(routing_2d[None], (nticks, n, n))

Population is conserved: every emigrant from node i is assigned to exactly one destination node j (including possibly i itself if the routing diagonal is non-zero, which has no net effect).

Attributes:

Name	Type	Description
model	Model	The parent model instance.
r_migration	ValuesMap	Per-tick, per-node emigration rate.
routing	ndarray	Row-normalised routing tensor of shape (nticks, nnodes, nnodes); entry [t, i, j] is the fraction of emigrants from node i going to node j on tick t.

Raises:

Type	Description
ValueError	If routing.ndim != 3 or routing.shape != (nticks, nnodes, nnodes).

Initialize the Migration component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required
r_migration	int | float | ValuesMap | ndarray	Per-tick, per-node emigration rate. Scalars are broadcast to all ticks and nodes via ValuesMap.from_scalar.	required
routing	ndarray	Shape (nticks, nnodes, nnodes) tensor where routing[t, i, j] is the unnormalised weight of migration from node i to node j on tick t. Each row is normalised internally. Rows summing to zero do not emigrate on that tick. For static routing pass a np.broadcast_to view: np.broadcast_to(routing_2d[None], (nticks, n, n))	required

Raises:

Type	Description
ValueError	If routing.shape is not (nticks, nnodes, nnodes).

properties property

properties

Return node properties required by this component.

Returns:

Type	Description
list[PropertyType]	list[PropertyType]: Empty list; migration requires no extra node properties.

states property

states

Return compartment state names required by this component.

Returns:

Type	Description
list[str]	list[str]: Empty list; migration operates on all existing states without declaring new ones.

end_step

end_step(tick)

No-op end-of-step hook.

Parameters:

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

setup

setup()

No-op; migration requires no additional initialisation.

start_step

start_step(tick)

No-op start-of-step hook.

Parameters:

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

step

step(tick)

Move individuals between nodes according to r_migration and routing.

Steps:

1. Convert emigration rate to probability via -expm1(-r).
2. Zero out probability for nodes with no routing row this tick.
3. Draw total emigrants per compartment via a single vectorised binomial over (nstates, nnodes).
4. Distribute emigrants to destinations using a sequential-binomial decomposition of the multinomial: for each destination j, draw binomial(remaining, conditional_fraction) over all sources simultaneously, accumulate inflow, and reduce remaining. The last destination receives whatever is left over, preserving the exact population count.

Parameters:

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

Model

Model(scenario, params=None, carry_forward_states=None)

Compartmental disease model that orchestrates cohort-based simulation components.

Manages a population scenario, a set of epidemiological components, and the discrete-time simulation loop.

Attributes:

Name	Type	Description
scenario	GeoDataFrame	Geographic/demographic scenario defining nodes.
params	PropertySet | None	Model parameters, including nticks.
nodes	LaserFrame	Per-node property storage.
states	StateArray	Compartment state array of shape (nticks+1, n_states, n_nodes).
network	ndarray	2-D inter-node mixing matrix of shape (nnodes, nnodes). Defaults to a uniform-zero scalar set at initialisation.

Initialize the Model.

Parameters:

Name	Type	Description	Default
scenario	GeoDataFrame	Geographic/demographic scenario; each row is a node.	required
params	PropertySet | None	Named model parameters. Must contain nticks before components is assigned.	None
carry_forward_states	Iterable[str] | None	Names of compartment states to carry forward at the start of each tick. None (default) carries forward every state. Pass an explicit iterable to restrict carry-forward to a subset. Unknown state names raise ValueError when components is assigned.	None

components property writable

components

Return the list of registered simulation components.

Returns:

Name	Type	Description
list	list	Ordered list of component instances.

network property writable

network

Return the inter-node mixing matrix.

Returns:

Type	Description
ndarray	np.ndarray: 2-D array of shape (nnodes, nnodes) whose entry [i, j] gives the connectivity weight from node i to node j.

run

run()

Execute the simulation for params.nticks time steps.

At the start of each tick, carries forward the selected compartment states from tick to tick+1, then calls start_step, step, and end_step on every registered component in order.

NonDiseaseMortality

NonDiseaseMortality(model, r_mortality, states=None)

Background (non-disease) mortality component.

Applies a binomial mortality draw each tick to the specified compartment states, removing individuals and recording the deaths in nodes.non_disease_mortality.

By default acts on every state in model.states. Passing states restricts mortality to only the named compartments, creating an implicit mask over the state axis.

Example

ndm = NonDiseaseMortality(model, r_mortality=1/365/70) # ~70-year life expectancy ndm_s_only = NonDiseaseMortality(model, r_mortality=1/365/70, states=["S"])

Initialize the NonDiseaseMortality component.

Parameters:

Name	Type	Description	Default
model	Model	The parent model instance.	required
r_mortality	int | float | ValuesMap | ndarray	Per-tick, per-node crude mortality rate. A scalar is broadcast to all ticks and nodes via ValuesMap.from_scalar; a ValuesMap or 2-D array of shape (nticks, nnodes) is used directly.	required
states	Iterable[str] | None	Names of compartment states to apply mortality to. Accepts any iterable (list, tuple, set, generator, etc.). None applies mortality to every state in model.states.	None

properties property

properties

Return the node properties required by this component.

Returns:

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

states property

states

Return the compartment states created by this component.

Returns:

Type	Description
list[str]	list[str]: Empty list; this component acts on existing states but does not create any new ones.

end_step

end_step(tick)

No-op end-of-step hook.

Parameters:

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

setup

setup()

Build a boolean state mask for the target compartment states.

Resolves which states to apply mortality to — all states when states was None, or the requested subset — then builds a boolean mask over the state axis using get_state_index so that step can select all target states in one vectorised operation.

start_step

start_step(tick)

No-op start-of-step hook.

Parameters:

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

step

step(tick)

Apply binomial mortality draws to all target states in one operation.

Selects all target compartments at tick+1 via the boolean state mask, draws deaths from a binomial distribution for all of them at once, subtracts the deaths back via boolean-index assignment, and accumulates per-node totals in nodes.non_disease_mortality.

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

ScheduledEntry dataclass

ScheduledEntry(what, who, where, params, notes, tick)

A single fully-parsed schedule entry — one intervention dispatch.

Each instance corresponds to one (tick, intervention) pair after the raw schedule has been validated and expanded — when lists are flattened into individual entries, who/where are normalised to lists or None, and date strings are converted to integer tick offsets.

Attributes:

Name	Type	Description
what	str	Name of the registered intervention class.
who	list[str] | None	Target compartment states, or None (all).
where	list[int] | None	Target node IDs, or None (all).
params	dict[str, Any]	Arbitrary parameters forwarded to execute.
notes	str	Free-text annotation forwarded to execute.
tick	int | None	Tick on which to fire, or None to fire on every tick.

StateArray

Bases: ndarray

A numpy array wrapper that provides attribute access to state compartments.

This class allows accessing state compartments by name (e.g., states.S, states.I, states.R) while maintaining full numpy array functionality and backward compatibility with numeric indexing (e.g., states[0], states[1]).

Example

states = StateArray(source_array=np.zeros((3, 100)), state_names=["S", "I", "R"], state_axis=0) states.S[0] = 1000 # Set susceptible population in patch 0 prevalence = states.I / states.sum(axis=0) # Calculate prevalence states[0] += births # Numeric indexing still works N = states.sum(axis=states.state_axis) # Sum over state axis to get total population per patch

state_axis property

state_axis

Return the axis index along which state compartments are stored.

Returns:

Name	Type	Description
int	int	Zero-based axis index for the state dimension.

Raises:

Type	Description
RuntimeError	If _state_axis is None, which occurs when the instance was created via view casting without metadata.

state_names property

state_names

Return the tuple of registered state compartment names.

Returns:

Type	Description
tuple[str, ...] | None	tuple[str, ...] | None: Compartment names in axis order, or None if the instance was created via view casting without metadata.

get_state_index

get_state_index(name)

Return the numeric axis index for a named state compartment.

Parameters:

Name	Type	Description	Default
name	str	State compartment name to look up.	required

Returns:

Type	Description
int | None	int | None: Zero-based index of name along the state axis, or None if name is not registered or state metadata is absent.

get_state_mask

get_state_mask(states)

Return a boolean mask selecting the specified state compartments.

The returned array has length equal to the number of registered states and is True at each position corresponding to a named state in states. Useful for vectorised operations that apply to a subset of compartments (e.g. mortality restricted to ["S", "I"]).

Parameters:

Name	Type	Description	Default
states	str | list[str]	A single state name or a list of state names to include in the mask.	required

Returns:

Type	Description
ndarray	np.ndarray: Boolean array of length n_states (the size of the state axis) with True at each index corresponding to a state in states and False elsewhere.

Raises:

Type	Description
ValueError	If states is neither a string nor a list.
ValueError	If any name in states is not a registered state.

Example

sa = StateArray(["S", "I", "R"], 0, shape=(3, 10)) sa.get_state_mask("S") array([ True, False, False]) sa.get_state_mask(["S", "R"]) array([ True, False, True])

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

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"].