BaseLaserModel

class BaseLaserModel(scenario, params, name)

Bases: ABC

Base class for laser-measles simulation models.

Provides common functionality for model initialization, component management, timing, metrics collection, and execution loops.

Initialize the model with common attributes.

Parameters:

• scenario (DataFrame | BaseScenario) – Scenario data (type varies by model).

• params (BaseModelParams) – Model parameters (type varies by model).

• name (str) – Model name.

abstractmethod __call__(model, tick)

Hook for subclasses to update the model for a given tick.

Parameters:

• model (BaseLaserModel) – The model instance.

• tick (int) – The current time step or tick.

Return type:

None

property components: PrettyComponentsList

Retrieve the list of model components.

Returns:

A PrettyComponentsList containing the components with enhanced formatting.

add_component(component)

Add the component class and an instance in model.instances.

Note that this does not create new instances of other components.

Parameters:

component (type[BaseComponent]) – A component class to be initialized and integrated into the model.

Return type:

None

prepend_component(component)

Add a component to the beginning of the component list.

Parameters:

component (type[BaseComponent]) – A component class to be initialized and integrated into the model.

Return type:

None

run()

Execute the model for a specified number of ticks, recording timing metrics.

Return type:

None

time_elapsed(units='days')

Return time elapsed since the start of the model.

Parameters:

units (str) – Time units to return. Currently only supports “days” and “ticks”.

Return type:

int | float

Returns:

Time elapsed in the specified units.

Raises:

ValueError – If invalid time units are specified.

get_tick_date(tick)

Return the date for a given tick.

Return type:

datetime

cleanup()

Clean up model resources to prevent memory leaks.

This method should be called when the model is no longer needed to free up memory from LaserFrame objects and other large data structures.

Return type:

None

get_instance(cls)

Get all instances of a specific component class.

Parameters:

cls (type | str) – The component class to search for.

Return type:

list

Returns:

List of instances of the specified class, or [None] if none found. Works with inheritance - subclasses will match parent class searches.

Example

state_trackers = model.get_instance(StateTracker) if state_trackers:

state_tracker = state_trackers[0] # Get first instance

get_component(cls)

Alias for get_instance (instances are instantiated, components are not).

Parameters:

cls (type | str) – The component class to search for.

Return type:

list

Returns:

List of instances of the specified class, or [None] if none found.

visualize(pdf=True)

Visualize each component instances either by displaying plots or saving them to a PDF file.

Parameters:

pdf (bool) – If True, save the plots to a PDF file. If False, display the plots interactively. Defaults to True.

Return type:

None

Returns:

None

plot(fig=None)

Placeholder for plotting method.

Parameters:

fig (Figure | None) – Optional matplotlib figure to plot on.

Raises:

NotImplementedError – Subclasses must implement this method.