propagator.core

High-level simulation primitives and facades for running PROPAGATOR from Python. The sections below cover the public API exposed by propagator.core along with the supporting data models and scheduling helpers.

Public Facade

propagator.core

Package init for the wildfire propagator core.

BoundaryConditions(time, moisture=None, wind_dir=None, wind_speed=None, ignitions=None, additional_moisture=None, vegetation_changes=None) dataclass

Boundary conditions applied at or after a given simulation time.

Attributes:

Name	Type	Description
time	int	Simulation time the conditions refer to (seconds from simulation start).
moisture	Optional[NDArray[floating]]	Fuel moisture map (%).
wind_dir	Optional[NDArray[floating]]	Wind direction map (weather convention, degrees clockwise, north is 0).
wind_speed	Optional[NDArray[floating]]	Wind speed map (km/h).
ignitions	Optional[	npt.NDArray[np.bool_] | list[tuple[int, int] | tuple[int, int, int]]
]		Ignitions to enqueue. Accepts either a boolean raster (2D applies to every realization; 3D maps explicit realization planes) or a list of (row, col) / (row, col, realization) tuples.
additional_moisture	Optional[NDArray[floating]]	Extra moisture to add to fuel (%), can be sparse.
vegetation_changes	Optional[NDArray[floating]]	Raster of vegetation type overrides (NaN to skip).

PropagatorStats(n_active, area_mean, area_50, area_75, area_90) dataclass

Summary statistics for the current simulation state.

to_dict(c_time, ref_date)

Serialize stats with the current simulation time expressed in seconds.

Propagator(veg, dem, fuels=(lambda: FUEL_SYSTEM_LEGACY)(), cellsize=CELLSIZE, do_spotting=False, realizations=REALIZATIONS, p_time_fn=get_p_time_fn(ROS_DEFAULT), p_moist_fn=get_p_moisture_fn(MOISTURE_MODEL_DEFAULT), out_of_bounds_mode='raise') dataclass

Stochastic cellular wildfire spread simulator.

PROPAGATOR evolves a binary fire state over a regular grid for a configurable number of realizations. Spread depends on vegetation, topography and environmental drivers (wind, moisture) through pluggable probability and travel-time functions.

Attributes:

Name	Type	Description
veg	ndarray	2D array of vegetation codes as defined in the provided FuelSystem
dem	ndarray	2D array of elevation values (meters above sea level).
fuels	(FuelSystem, optional)	Object defining fuels types and fire propagation probability between fuel types
cellsize	(float, optional)	The size of lattice (meters).
do_spotting	(bool, optional)	Whether to enable fire-spotting in the model.
realizations	(int, optional)	Number of stochastic realizations to simulate.
p_time_fn	(Any, optional)	The function to compute the spread time (must be jit-compiled). Units are compliant with other functions. signature: (v0: float, dh: float, angle_to: float, dist: float, moist: float, w_dir: float, w_speed: float) -> tuple[float, float]
p_moist_fn	(Any, optional)	The function to compute the moisture probability (must be jit-compiled) Units are compliant with other functions. signature: (moist: float) -> float
out_of_bounds_mode	(Literal['ignore', 'error'], optional)	Whether to raise an error if out-of-bounds updates are detected. Default is "error".

compute_fire_probability()

Return mean burn probability across realizations for each cell.

Returns:

Type	Description
ndarray	2D array with values in [0, 1].

compute_ros_max()

Return per-cell maximum Rate of Spread across realizations.

Returns:

Type	Description
ndarray	2D array with max RoS per cell.

compute_ros_mean()

Return per-cell mean Rate of Spread, ignoring zeros as no-spread.

Returns:

Type	Description
ndarray	2D array with mean RoS per cell.

compute_fireline_int_max()

Return per-cell maximum fireline intensity across realizations.

Returns:

Type	Description
ndarray	2D array of max intensity values.

compute_fireline_int_mean()

Return per-cell mean fireline intensity, ignoring zeros as no-spread.

Returns:

Type	Description
ndarray	2D array of mean intensity values.

compute_stats(values)

Compute simple area-based stats and number of active cells.

Parameters:

Name	Type	Description	Default
values	ndarray	Fire probability map in [0, 1].	required

Returns:

Type	Description
PropagatorStats	Dataclass with counters and area summaries.

set_boundary_conditions(boundary_condition)

Externally set boundary conditions at desired time in the scheduler.

Parameters:

Name	Type	Description	Default
boundary_condition	BoundaryConditions	Conditions to apply.	required

step()

Advance the simulation to the next scheduled time and update state.

get_output()

Assemble the current outputs and summary stats into a dataclass.

Returns: PropagatorOutput: Snapshot of fire probability, RoS, intensity, stats.

next_time()

Get the next time step.

Returns: int | None: 0 at initialization; None if no more events; otherwise the next scheduled simulation time.

PropagatorOutOfBoundsError

Bases: Exception

Custom error for out-of-bounds updates in the Propagator.

get_p_moisture_fn(moist_model_code)

Select a moisture probability correction by code.

Parameters:

Name	Type	Description	Default
moist_model_code	MoistureModel	The code of the moisture model to select.	required

Returns:

Type	Description
function with signature	(moist: float) -> float.

get_p_time_fn(ros_model_code)

Select a rate-of-spread model by code.

Parameters:

Name	Type	Description	Default
ros_model_code	RateOfSpreadModel	The code of the rate-of-spread model to select.	required

Returns:

Type	Description
function with signature	(v0, dem_from, dem_to, angle_to, dist, moist, w_dir, w_speed) -> (time_seconds, ros).

Data Models

propagator.core.models

Core wildfire propagation engine.

This module defines the main simulation primitives and the Propagator class that evolves a fire state over a grid using wind, slope, vegetation, and moisture inputs. Public dataclasses capture boundary conditions, actions, summary statistics, and output snapshots suitable for CLI and IO layers.

PropagatorError

Bases: Exception

Domain-specific error raised by PROPAGATOR.

BoundaryConditions(time, moisture=None, wind_dir=None, wind_speed=None, ignitions=None, additional_moisture=None, vegetation_changes=None) dataclass

Boundary conditions applied at or after a given simulation time.

Attributes:

Name	Type	Description
time	int	Simulation time the conditions refer to (seconds from simulation start).
moisture	Optional[NDArray[floating]]	Fuel moisture map (%).
wind_dir	Optional[NDArray[floating]]	Wind direction map (weather convention, degrees clockwise, north is 0).
wind_speed	Optional[NDArray[floating]]	Wind speed map (km/h).
ignitions	Optional[	npt.NDArray[np.bool_] | list[tuple[int, int] | tuple[int, int, int]]
]		Ignitions to enqueue. Accepts either a boolean raster (2D applies to every realization; 3D maps explicit realization planes) or a list of (row, col) / (row, col, realization) tuples.
additional_moisture	Optional[NDArray[floating]]	Extra moisture to add to fuel (%), can be sparse.
vegetation_changes	Optional[NDArray[floating]]	Raster of vegetation type overrides (NaN to skip).

PropagatorStats(n_active, area_mean, area_50, area_75, area_90) dataclass

Summary statistics for the current simulation state.

to_dict(c_time, ref_date)

Serialize stats with the current simulation time expressed in seconds.

PropagatorOutput(time, fire_probability, ros_mean, ros_max, fli_mean, fli_max, stats) dataclass

Snapshot of simulation outputs at a given time step.

Simulator Implementation

propagator.core.propagator

Core wildfire propagation engine.

This module defines the main simulation primitives and the Propagator class that evolves a fire state over a grid using wind, slope, vegetation, and moisture inputs. Public dataclasses capture boundary conditions, actions, summary statistics, and output snapshots suitable for CLI and IO layers.

PropagatorOutOfBoundsError

Bases: Exception

Custom error for out-of-bounds updates in the Propagator.

Propagator(veg, dem, fuels=(lambda: FUEL_SYSTEM_LEGACY)(), cellsize=CELLSIZE, do_spotting=False, realizations=REALIZATIONS, p_time_fn=get_p_time_fn(ROS_DEFAULT), p_moist_fn=get_p_moisture_fn(MOISTURE_MODEL_DEFAULT), out_of_bounds_mode='raise') dataclass

Stochastic cellular wildfire spread simulator.

PROPAGATOR evolves a binary fire state over a regular grid for a configurable number of realizations. Spread depends on vegetation, topography and environmental drivers (wind, moisture) through pluggable probability and travel-time functions.

Attributes:

Name	Type	Description
veg	ndarray	2D array of vegetation codes as defined in the provided FuelSystem
dem	ndarray	2D array of elevation values (meters above sea level).
fuels	(FuelSystem, optional)	Object defining fuels types and fire propagation probability between fuel types
cellsize	(float, optional)	The size of lattice (meters).
do_spotting	(bool, optional)	Whether to enable fire-spotting in the model.
realizations	(int, optional)	Number of stochastic realizations to simulate.
p_time_fn	(Any, optional)	The function to compute the spread time (must be jit-compiled). Units are compliant with other functions. signature: (v0: float, dh: float, angle_to: float, dist: float, moist: float, w_dir: float, w_speed: float) -> tuple[float, float]
p_moist_fn	(Any, optional)	The function to compute the moisture probability (must be jit-compiled) Units are compliant with other functions. signature: (moist: float) -> float
out_of_bounds_mode	(Literal['ignore', 'error'], optional)	Whether to raise an error if out-of-bounds updates are detected. Default is "error".

compute_fire_probability()

Return mean burn probability across realizations for each cell.

Returns:

Type	Description
ndarray	2D array with values in [0, 1].

compute_ros_max()

Return per-cell maximum Rate of Spread across realizations.

Returns:

Type	Description
ndarray	2D array with max RoS per cell.

compute_ros_mean()

Return per-cell mean Rate of Spread, ignoring zeros as no-spread.

Returns:

Type	Description
ndarray	2D array with mean RoS per cell.

compute_fireline_int_max()

Return per-cell maximum fireline intensity across realizations.

Returns:

Type	Description
ndarray	2D array of max intensity values.

compute_fireline_int_mean()

Return per-cell mean fireline intensity, ignoring zeros as no-spread.

Returns:

Type	Description
ndarray	2D array of mean intensity values.

compute_stats(values)

Compute simple area-based stats and number of active cells.

Parameters:

Name	Type	Description	Default
values	ndarray	Fire probability map in [0, 1].	required

Returns:

Type	Description
PropagatorStats	Dataclass with counters and area summaries.

set_boundary_conditions(boundary_condition)

Externally set boundary conditions at desired time in the scheduler.

Parameters:

Name	Type	Description	Default
boundary_condition	BoundaryConditions	Conditions to apply.	required

step()

Advance the simulation to the next scheduled time and update state.

get_output()

Assemble the current outputs and summary stats into a dataclass.

Returns: PropagatorOutput: Snapshot of fire probability, RoS, intensity, stats.

next_time()

Get the next time step.

Returns: int | None: 0 at initialization; None if no more events; otherwise the next scheduled simulation time.

Scheduler Helpers

propagator.core.scheduler

Lightweight event scheduler for propagation updates.

Stores future updates grouped by simulation time and exposes utilities to push events, pop the earliest batch, and inspect active realizations.

SchedulerEvent(updates=UpdateBatch(), moisture=None, wind_dir=None, wind_speed=None, additional_moisture=None, vegetation_changes=None) dataclass

Represents a scheduled event in the simulation.

SortedDict() dataclass

Represents a sorted dictionary for scheduling events.

Scheduler(realizations) dataclass

Lightweight event scheduler for propagation updates.

Generic over the time key type (int or float), so your inputs and outputs stay consistent.

add_event(time, event)

Adds an event to the scheduler.

Parameters:

Name	Type	Description	Default
time	int	Time for the event	required
event	SchedulerEvent	New event structure	required