propagator.core.numba

Numba-accelerated kernels, models, and helper functions backing the simulation engine. Use these interfaces when you need to customise the low-level spread behaviour or integrate new stochastic components.

Public Facade

propagator.core.numba

FuelSystem(n_fuels)

add_fuel(fuel_id, name, v0, d0, hhv, d1=0.0, humidity=-9999.0, spotting=False, prob_ign_by_embers=0.0, burn=True)

Adds a Fuel object to the FuelSystem.

Parameters:

Name	Type	Description	Default
fuel_id	int	The unique identifier for the fuel type	required
name	str	The name of the fuel type	required
v0	float	The initial spread rate (m/min)	required
d0	float	The dead fuel density (kg/m^2)	required
hhv	float	The higher heating value (KJ/kg)	required
d1	float	The live fuel density (kg/m^2)	0.0
humidity	float	The fuel moisture content (fraction)	-9999.0
spotting	bool	Whether the fuel type is prone to spotting (default is False)	False
prob_ign_by_embers	float	The probability of ignition by embers (default is 0.0)	0.0
burn	bool	Whether the fuel type is combustible (default is True)	True

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).

next_updates_fn(rows, cols, realizations, cellsize, time, veg, dem, fire, moisture, wind_dir, wind_speed, fuels, p_time_fn, p_moist_fn)

Compute the next updates for the fire spread simulation.

Parameters:

Name	Type	Description	Default
rows	NDArray[integer]	The row indices of the fire spread updates.	required
cols	NDArray[integer]	The column indices of the fire spread updates.	required
realizations	NDArray[integer]	The realization indices of the fire spread updates.	required
cellsize	float	The size of each cell (in meters)	required
time	int	The current time step.	required
veg	NDArray[integer]	The 2D vegetation array	required
dem	NDArray[floating]	The 2D digital elevation model array	required
fire	NDArray[int8]	The 3D current fire state	required
moisture	NDArray[floating]	The 2D moisture array (units: fraction [0, 1])	required
wind_dir	NDArray[floating]	The 2D wind direction array (units: radians between [-π, π], 0 is east->west)	required
wind_speed	NDArray[floating]	The 2D wind speed array (units: km/h)	required
fuels	FuelSystem	The fuel system	required
p_time_fn	Any	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]	required
p_moist_fn	Any	The function to compute the moisture probability (must be jit-compiled). Units are compliant with other functions. signature: (moist: float) -> float	required

Returns:

Type	Description
UpdateBatchTuple	A tuple containing the arrays for the next updates. (next_times, next_rows, next_cols, next_realizations, next_ros, next_fireline_intensities)

Fuel and Model Definitions

propagator.core.numba.models

Models and data structures for the Numba JIT-compiled wildfire propagation engine.

This file defines the data structures used in the Numba JIT-compiled wildfire propagation engine.

Fuel(name, v0, d0, hhv, d1=0.0, humidity=-9999.0, spotting=False, prob_ign_by_embers=0.0, burn=True)

Initialize a Fuel object.

Parameters:

Name	Type	Description	Default
name	str	The name of the fuel type	required
v0	float	The initial spread rate (m/min)	required
d0	float	The dead fuel density (kg/m^2)	required
hhv	float	The higher heating value (KJ/kg)	required
d1	float	The live fuel density (kg/m^2)	0.0
humidity	float	The fuel moisture content (fraction)	-9999.0
spotting	bool	Whether the fuel type is prone to spotting (default is False)	False
prob_ign_by_embers	float	The probability of ignition by embers (default is 0.0)	0.0
burn	bool	Whether the fuel type is combustible (default is True)	True

FuelSystem(n_fuels)

add_fuel(fuel_id, name, v0, d0, hhv, d1=0.0, humidity=-9999.0, spotting=False, prob_ign_by_embers=0.0, burn=True)

Adds a Fuel object to the FuelSystem.

Parameters:

Name	Type	Description	Default
fuel_id	int	The unique identifier for the fuel type	required
name	str	The name of the fuel type	required
v0	float	The initial spread rate (m/min)	required
d0	float	The dead fuel density (kg/m^2)	required
hhv	float	The higher heating value (KJ/kg)	required
d1	float	The live fuel density (kg/m^2)	0.0
humidity	float	The fuel moisture content (fraction)	-9999.0
spotting	bool	Whether the fuel type is prone to spotting (default is False)	False
prob_ign_by_embers	float	The probability of ignition by embers (default is 0.0)	0.0
burn	bool	Whether the fuel type is combustible (default is True)	True

Probability and Rate Functions

propagator.core.numba.functions

Spread, probability, and intensity model functions.

This module contains pluggable formulations for rate-of-spread, probability modulators for wind/slope/moisture, fire spotting distance, and fireline intensity utilities used by the core propagator.

clip(x, min, max)

Clip x to the range [min, max].

Parameters:

Name	Type	Description	Default
x	float	Value to clip.	required
min	float	Minimum value.	required
max	float	Maximum value.	required

Returns:

Type	Description
float	Clipped value.

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).

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.

p_time_rothermel(v0, dh, angle, dist, moist, w_dir, w_speed)

Propagation time and ROS according to Rothermel-like scaling.

Parameters:

Name	Type	Description	Default
v0	float	Base Rate of Spread for the cell vegetation (m/min)	required
dh	float	Elevation difference between source and neighbor cells. (m)	required
angle	float	Direction to neighbor (clockwise radians, 0 is north -> south)	required
dist	float	Distance between cells (m).	required
moist	float	Moisture values (fraction).	required
w_dir	float	Wind direction (clockwise radians, 0 is north -> south).	required
w_speed	float	Wind speed (km/h).	required

Returns:

Type	Description
tuple[float, float]	(transition time [s], ROS [m/min]).

p_time_wang(v0, dh, angle, dist, moist, w_dir, w_speed)

Propagation time and ROS according to Wang et al.

Parameters:

Name	Type	Description	Default
v0	float	Base ROS vector per vegetation type.	required
dh	float	Elevation at source and neighbor cells.	required
angle	float	Direction to neighbor (clockwise radians, 0 is north -> south).	required
dist	float	Distance to neighbour cell (m).	required
moist	float	Moisture values (fractional).	required
w_dir	float	Wind direction (clockwise radians, 0 is north -> south).	required
w_speed	float	Wind speed (km/h).	required

Returns:

Type	Description
tuple[ndarray, ndarray]	(transition time [s], ROS [m/min]).

p_time_standard(v0, dh, angle, dist, moist, w_dir, w_speed)

Baseline propagation time and ROS with combined wind-slope factor.

Parameters:

Name	Type	Description	Default
v0	float	Base ROS vector per vegetation type.	required
dh	float	Elevation difference between source and neighbor cells.	required
angle	float	Direction to neighbor (clockwise radians, 0 is north -> south).	required
dist	float	Distance to neighbor (m).	required
moist	float	Moisture values (%).	required
w_dir	float	Wind direction (clockwise radians, 0 is north -> south).	required
w_speed	float	Wind speed (km/h).	required

Returns:

Type	Description
tuple[float, float]	(transition time [s], ROS [m/min]).

w_h_effect(angle, w_speed, w_dir, dh, dist)

Scale factor taking into account wind, slope and aspect effects on propagation rate of spread.

Parameters:

Name	Type	Description	Default
angle	float	The angle to the neighboring pixel (clockwise radians, 0 is north -> south).	required
w_speed	float	The wind speed (km/h).	required
w_dir	float	The wind direction (clockwise radians, 0 is north -> south).	required
dh	float	The elevation difference between source and neighbor cells (meters).	required
dist	float	The distance to the neighbor (meters).	required

Returns:

Type	Description
float	Scale factor for wind, slope, and aspect effects on propagation rate of spread.

w_h_effect_on_probability(angle, w_speed, w_dir, dh, dist)

Scale factor taking into account wind, slope and aspect effects on probability. This is derived from w_h_effect by scaling the output non linearly.

Parameters:

Name	Type	Description	Default
angle	float	The angle to the neighboring pixel (clockwise radians, 0 is north -> south).	required
w_speed	float	The wind speed (km/h).	required
w_dir	float	The wind direction (clockwise radians, 0 is north -> south).	required
dh	float	The elevation difference between source and neighbor cells (meters).	required
dist	float	The distance to the neighbor (meters).	required

Returns:

Type	Description
float	Scale factor for wind, slope, and aspect effects on probability.

p_moisture_trucchia(moist)

Moisture correction to the transition probability p_{i,j}.

Uses a 5th-degree polynomial in x = moist/Mx, with Mx = 0.3 (Trucchia et al., Fire 2020).

Parameters:

Name	Type	Description	Default
moist	float	Moisture content (fractional).	required

Returns:

Type	Description
float	Moisture correction factor (p_{i,j}).

p_moisture_baghino(moist)

Moisture correction to p_{i,j}. Older formulation, Baghino; Trucchia et al., 2020). Parameters come from constants.

Parameters:

Name	Type	Description	Default
moist	float	Moisture content (fractional).	required

Returns:

Type	Description
float	Moisture correction factor (p_{i,j}).

lhv_fuel(hhv, moisture)

Lower heating value of fuels given higher heating value and FFMC.

Parameters:

Name	Type	Description	Default
hhv	float	Higher heating value of dead fuel (kJ/kg).	required
moisture	float	fuel moisture content (fractional).	required

fireline_intensity(d0, d1, ros, lhv_dead_fuel, lhv_canopy)

Estimate fireline intensity (kW/m) from fuel loads and Rate of spread.

Parameters:

Name	Type	Description	Default
d0	float	Dead fuel density (kg/m^2).	required
d1	float	Canopy fuel density (kg/m^2).	required
ros	float	Rate of spread (m/min).	required
lhv_dead_fuel	float	Lower heating value of dead fuel (kJ/kg).	required
lhv_canopy	float	Lower heating value of canopy fuel (kJ/kg).	required

Returns:

Type	Description
float	Fireline intensity (kW/m).

get_probability_to_neighbour(angle, dist, w_dir, w_speed, moisture, dh, transition_probability, p_moist_fn)

Get the probability of fire spread to a neighboring pixel.

Parameters:

Name	Type	Description	Default
angle	float	The angle to the neighboring pixel (clockwise radians, 0 is north -> south).	required
dist	float	The distance to the neighboring pixel (meters).	required
w_dir	float	The wind direction (clockwise radians, 0 is north -> south).	required
w_speed	float	The wind speed (km/h).	required
moisture	float	The moisture content (fraction).	required
dh	float	The difference in height (meters).	required
transition_probability	float	The base transition probability.	required
p_moist_fn	Any	The function to compute the moisture probability (must be jit-compiled). Units are compliant with other functions. signature: (moist: float) -> float	required

Returns:

Type	Description
float	The probability of fire spread to the neighboring pixel.

Propagation Kernels

propagator.core.numba.propagation

Propagation functions for fire spread simulation.

This module contains functions for simulating fire spread in a grid environment, including ember spotting and cell updates.

fire_spotting(angle, w_dir, w_speed)

Evaluate spotting distance using Alexandridis' formulation.

Parameters:

Name	Type	Description	Default
angle	float	The angle of the ember's trajectory (clockwise radians, 0 is north -> south)	required
w_dir	float	The wind direction (clockwise radians, 0 is north -> south)	required
w_speed	float	The wind speed (km/h)	required

Returns:

Type	Description
tuple[float, float]	The spotting distance (meters) and the landing time (seconds)

compute_spotting(row, col, cellsize, veg, fire, wind_dir, wind_speed, fuels)

Compute ember spotting updates for a given cell.

Parameters:

Name	Type	Description	Default
row	int	The row index of the current cell	required
col	int	The column index of the current cell	required
cellsize	float	The size of each cell (m)	required
veg	NDArray[integer]	The vegetation type array	required
fire	NDArray[int8]	The fire state array	required
wind_dir	float	The wind direction (clockwise radians, 0 is north -> south)	required
wind_speed	float	The wind speed (km/h)	required
fuels	FuelSystem	The fuel system object	required

Returns:

Type	Description
list[tuple[int, int, int, float, float]]	A list of spotting updates, each represented as a tuple (transition_times, rows, cols, rates_of_spread, fireline_intensities)

calculate_fire_behavior(fuel_from, fuel_to, dh, dist, angle, moisture, w_dir, w_speed, p_time_fn)

Calculate fire behaviour during propagation between cells

Parameters:

Name	Type	Description	Default
fuel_from	Fuel	The fuel object for the source cell.	required
fuel_to	Fuel	The fuel object for the target cell.	required
dh	float	The elevation difference between the source and target cells (m).	required
dist	float	The distance to the target cell (m).	required
angle	float	The angle to the target cell (clockwise radians, 0 is north -> south).	required
moisture	float	The moisture content of the fuel (fraction).	required
w_dir	float	The wind direction (clockwise radians, 0 is north -> south).	required
w_speed	float	The wind speed (km/h).	required
p_time_fn	Any	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]	required

Returns:

Type	Description
tuple[int, float, float]	A tuple containing the transition time, rate of spread, and fireline intensity.

single_cell_updates(row, col, cellsize, veg, dem, fire, moisture, wind_dir, wind_speed, fuels, p_time_fn, p_moist_fn)

Apply fire spread to a single cell and get the next spread updates.

Parameters:

Name	Type	Description	Default
row	int	The row index of the current cell	required
col	int	The column index of the current cell	required
cellsize	float	The size of each cell (in meters)	required
veg	NDArray[integer]	The 2D vegetation array	required
dem	NDArray[floating]	The 2D digital elevation model array	required
fire	NDArray[int8]	The 2D current fire state	required
moisture	NDArray[floating]	The 2D moisture array (units: fraction [0, 1])	required
wind_dir	NDArray[floating]	The 2D wind direction array (units: radians between [-π, π], 0 is east->west)	required
wind_speed	NDArray[floating]	The 2D wind speed array (units: km/h)	required
fuels	FuelSystem	The fuel system	required
p_time_fn	Any	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]	required
p_moist_fn	Any	The function to compute the moisture probability (must be jit-compiled). Units are compliant with other functions. signature: (moist: float) -> float	required

Returns:

Type	Description
list[tuple[int, int, int, float, float]]	A list of fire spread updates (transition_times, rows, cols, rates_of_spread, fireline_intensities)

next_updates_fn(rows, cols, realizations, cellsize, time, veg, dem, fire, moisture, wind_dir, wind_speed, fuels, p_time_fn, p_moist_fn)

Compute the next updates for the fire spread simulation.

Parameters:

Name	Type	Description	Default
rows	NDArray[integer]	The row indices of the fire spread updates.	required
cols	NDArray[integer]	The column indices of the fire spread updates.	required
realizations	NDArray[integer]	The realization indices of the fire spread updates.	required
cellsize	float	The size of each cell (in meters)	required
time	int	The current time step.	required
veg	NDArray[integer]	The 2D vegetation array	required
dem	NDArray[floating]	The 2D digital elevation model array	required
fire	NDArray[int8]	The 3D current fire state	required
moisture	NDArray[floating]	The 2D moisture array (units: fraction [0, 1])	required
wind_dir	NDArray[floating]	The 2D wind direction array (units: radians between [-π, π], 0 is east->west)	required
wind_speed	NDArray[floating]	The 2D wind speed array (units: km/h)	required
fuels	FuelSystem	The fuel system	required
p_time_fn	Any	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]	required
p_moist_fn	Any	The function to compute the moisture probability (must be jit-compiled). Units are compliant with other functions. signature: (moist: float) -> float	required

Returns:

Type	Description
UpdateBatchTuple	A tuple containing the arrays for the next updates. (next_times, next_rows, next_cols, next_realizations, next_ros, next_fireline_intensities)