laser.core.laserframe

laser.core.laserframe

laserframe.py

This module defines the LaserFrame class, which is used to manage dynamically allocated data for agents or nodes/patches. The LaserFrame class is similar to a database table or a Pandas DataFrame and supports scalar and vector properties.

Classes:

Name	Description
LaserFrame	A class to manage dynamically allocated data for agents or nodes/patches.

Usage Example

laser_frame = LaserFrame(capacity=100)
laser_frame.add_scalar_property('age', dtype=np.int32, default=0)
laser_frame.add_vector_property('position', length=3, dtype=np.float32, default=0.0)
start, end = laser_frame.add(10)
laser_frame.sort(np.arange(10)[::-1])
laser_frame.squash(np.array([True, False, True, False, True, False, True, False, True, False]))

Attributes:

Name	Type	Description
count	int	The current count of active elements.
capacity	int	The maximum capacity of the frame.

Note

Since count can be less than capacity, properties return slices of the underlying arrays up to count by default so users do not have to include the slice themselves. I.e., if lf is a LaserFrame, then lf.age returns lf._age[0:lf.count] automatically. The full underlying array is always available as lf._age (or whatever the property name is). The slice returned is valid for all NumPy operations, including assignment, as well as for use with Numba compiled functions.

laser.core.laserframe.LaserFrame(capacity, initial_count=-1, **kwargs)

The LaserFrame class, similar to a db table or a Pandas DataFrame, holds dynamically allocated data for agents (generally 1-D or scalar) or for nodes|patches (e.g., 1-D for scalar value per patch or 2-D for time-varying per patch).

Initialize a LaserFrame object.

Parameters:

Name	Type	Description	Default
capacity	int	The maximum capacity of the frame. Must be a positive integer.	required
initial_count	int	The initial number of active elements in the frame. Must be a positive integer <= capacity.	-1
**kwargs	dict	Additional keyword arguments to set as attributes of the object.	{}

Raises:

Type	Description
ValueError	If capacity or initial_count is not a positive integer, or if initial_count is greater than capacity.

laser.core.laserframe.LaserFrame.capacity property

Returns the capacity of the laser frame (total possible entries for dynamic properties).

Returns:

Name	Type	Description
int	int	The capacity of the laser frame.

laser.core.laserframe.LaserFrame.count property

Returns the current count (equivalent to len()).

Returns:

Name	Type	Description
int	int	The current count value.

laser.core.laserframe.LaserFrame.add(count)

Adds the specified count to the current count of the LaserFrame.

This method increments the internal count by the given count, ensuring that the total does not exceed the frame's capacity. If the addition would exceed the capacity, an assertion error is raised. This method is typically used to add new births during the simulation.

Parameters:

Name	Type	Description	Default
count	int	The number to add to the current count.	required

Returns:

Type	Description
tuple[int, int]	tuple[int, int]: A tuple containing the [start index, end index) after the addition.

Raises:

Type	Description
AssertionError	If the resulting count exceeds the frame's capacity.

laser.core.laserframe.LaserFrame.add_array_property(name, shape, dtype=np.uint32, default=0)

Adds an array property to the object.

This method initializes a new property with the given name as a multi-dimensional NumPy array.

The array will have the given shape (note that there is no implied dimension of size self._capacity), datatype (default is np.uint32), and default value (default is 0).

Parameters:

Name	Type	Description	Default
name	str	The name of the property to be added.	required
shape	tuple	The shape of the array.	required
dtype	data - type	The desired data-type for the array, default is np.uint32.	uint32
default	scalar	The default value to fill the array with, default is 0.	0

Returns:

Type	Description
None	None

laser.core.laserframe.LaserFrame.add_scalar_property(name, dtype=np.uint32, default=0)

Add a scalar property to the class.

This method initializes a new scalar property for the class instance. The property is stored as a 1-D NumPy array (scalar / entry) with a specified data type and default value.

Parameters:

Name	Type	Description	Default
name	str	The name of the scalar property to be added.	required
dtype	data - type	The desired data type for the property. Default is np.uint32.	uint32
default	scalar	The default value for the property. Default is 0.	0

Returns:

Type	Description
None	None

laser.core.laserframe.LaserFrame.add_vector_property(name, length, dtype=np.uint32, default=0)

Adds a vector property to the object.

This method initializes a new property with the given name as a 2-D NumPy array (vector per entry).

The array will have a shape of (length, self._capacity) and will be filled with the specified default value. The data type of the array elements is determined by the dtype parameter.

Parameters:

Name	Type	Description	Default
name	str	The name of the property to be added.	required
length	int	The length of the vector.	required
dtype	data - type	The desired data-type for the array, default is np.uint32.	uint32
default	scalar	The default value to fill the array with, default is 0.	0

Returns:

Type	Description
None	None

laser.core.laserframe.LaserFrame.describe(target=None)

Return a formatted string description of the laserframe object, including its attributes and their values.

Parameters:

Name	Type	Description	Default
target	string	Optional string for the report header (generally the name of the LaserFrame variable, e.g., "People". Unlike functions, we can't get the name of a variable automatically).	None

Returns:

Name	Type	Description
str	str	A formatted string describing the laserframe object, including its capacity, count, and details of its scalar, vector, and other properties.

laser.core.laserframe.LaserFrame.load_snapshot(path, cbr, nt) classmethod

Load a LaserFrame and optional extras from an HDF5 snapshot file.

Parameters:

Name	Type	Description	Default
path	str	Path to the HDF5 snapshot file.	required
cbr	ndarray	A 2D NumPy array of crude birth rates with shape (num_timesteps, num_nodes), in units of births per 1000 individuals per year. If provided, nt must also be provided, and capacity will be estimated to accommodate projected population growth. If None, capacity is set to the current count only.	required
nt	int	Number of timesteps (days). Must be provided together with cbr, or both must be None.	required

Returns:

Name	Type	Description
frame	LaserFrame	The loaded LaserFrame object.
results_r	ndarray or None	A 2D array of recovered counts with shape (time, nodes), or None if not present in the snapshot.
pars	dict	Dictionary of model parameters stored in the snapshot, or empty if none are found.

Raises:

Type	Description
ValueError	If only one of cbr or nt is provided.
ValueError	If required fields (like 'node_id') are missing.
ValueError	If array shapes do not align across cbr, recovered, and node_id.

Notes

• Snapshots must contain a per-agent 'node_id' property.
• The recovered array is assumed to be in (time, node) layout.
• The capacity estimate includes both current and recovered agents at t=0.

laser.core.laserframe.LaserFrame.save_snapshot(path, results_r=None, pars=None)

Save this LaserFrame and optional extras to an HDF5 snapshot file.

Parameters:

Name	Type	Description	Default
path	Path	Destination file path	required
results_r	ndarray	Optional 2D numpy array of recovered counts	None
pars	PropertySet or dict	Optional PropertySet or dict of parameters	None

laser.core.laserframe.LaserFrame.sort(indices, verbose=False)

Sorts the elements of the object's numpy arrays based on the provided indices.

Parameters:

Name	Type	Description	Default
indices	ndarray	An array of indices used to sort the numpy arrays. Must be of integer type and have the same length as the frame count (self._count).	required
verbose	bool	If True, prints the sorting progress for each numpy array attribute. Defaults to False.	False

Raises:

Type	Description
AssertionError	If indices is not an integer array or if its length does not match the frame count of active elements.

laser.core.laserframe.LaserFrame.squash(indices, verbose=False)

Reduces the active count of the internal numpy arrays keeping only elements True in the provided boolean indices.

Parameters:

Name	Type	Description	Default
indices	ndarray	A boolean array indicating which elements to keep. Must have the same length as the current frame active element count.	required
verbose	bool	If True, prints detailed information about the squashing process. Defaults to False.	False

Raises:

Type	Description
AssertionError	If indices is not a boolean array or if its length does not match the current frame active element count.

Returns:

Type	Description
None	None