laser.core.utils

`laser.core.utils`

This module provides utility functions for the laser-measles project.

Functions:

Name	Description
`calc_capacity`	np.ndarray, initial_pop: np.ndarray, safety_factor: float = 1.0) -> np.ndarray: Calculate the population capacity after a given number of ticks based on a constant birth rate.
`grid`	Tuple[int, int], fill_value: float = 0.0) -> np.ndarray: Create a 2D grid (numpy array) of the specified shape, filled with the given value.

`laser.core.utils.calc_capacity(birthrates, initial_pop, safety_factor=1.0)`

Estimate the required capacity (number of agents) to model a population given birthrates over time.

Args:

birthrates (np.ndarray): 2D array of shape (nsteps, nnodes) representing birthrates (CBR) per 1,000 individuals per year.
initial_pop (np.ndarray): 1D array of length nnodes representing the initial population at each node.
safety_factor (float): Safety factor to account for variability in population growth. Default is 1.0.

Returns:

np.ndarray: 1D array of length nnodes representing the estimated required capacity (number of agents) at each node.

`laser.core.utils.grid(M=5, N=5, node_size_degs=0.08983, population_fn=None, origin_x=0, origin_y=0, states=None)`

Create an MxN grid of cells anchored at (lat, long) with populations and geometries.

By default all nodes are initialized with the full population in the first state (e.g., "S" for susceptible).

Parameters:

Name	Type	Description	Default
`M`	`int`	Number of rows (north-south).	`5`
`N`	`int`	Number of columns (east-west).	`5`
`node_size_degs`	`float`	Size of each cell in decimal degrees (default 0.08983 ≈ 10km at the equator).	`0.08983`
`population_fn`	`callable`	Function(row, col) returning population for a cell. Default is uniform random between 1,000 and 100,000.	`None`
`origin_x`	`float`	longitude of the origin in decimal degrees (bottom-left corner) -180 <= origin_x < 180.	`0`
`origin_y`	`float`	latitude of the origin in decimal degrees (bottom-left corner) -90 <= origin_y < 90.	`0`
`states`	`list`	List of state names to initialize in the GeoDataFrame. Default is ["S", "E", "I", "R"].	`None`

Returns:

Name	Type	Description
`scenario`	`GeoDataFrame`	Columns are nodeid, population, geometry.

`laser.core.utils.initialize_population(grid, initial, states=None)`

Initialize the population states in the grid based on the initial state counts provided.

Provide integer values to set the exact counts for each state at each node. Alternatively, provide fractional values between 0.0 and 1.0 to set proportions of the population for each state at each node. In the latter case, the first state in the states list will be computed as the remainder of the population after assigning the other states.

Parameters:

Name	Type	Description	Default
`grid`	`GeoDataFrame`	The grid GeoDataFrame with population and state columns.	required
`initial`	`list or ndarray`	A list or array of shape (1\|nnodes, nstates) representing the initial counts for each state at each node. If the shape is (1, nstates), the same initial state distribution will be applied to all nodes.	required
`states`	`list`	List of state names corresponding to the columns in the grid. Default is ["S", "E", "I", "R"].	`None`

Returns:

Name	Type	Description
`GeoDataFrame`		The updated grid with initialized population states.