laser.cohorts.migration

migration

Stochastic migration component for cohort-based simulation.

Moves individuals between nodes each tick by drawing emigrants from each compartment via a binomial draw and then routing them to destination nodes via a sequential-binomial decomposition of the multinomial.

The routing matrix is 3-D with shape (nticks, nnodes, nnodes) so that connectivity can vary over time. For static connectivity, use np.broadcast_to(routing_2d[None], (nticks, nnodes, nnodes)) to obtain a read-only 3-D view without copying data.

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