firebench.ros_models

Urban rate of spread models

class firebench.ros_models.surface_for_urban.Hamada_1

Bases: RateOfSpreadModel

A class to represent the Hamada’s model for urban fire spread rate calculation in its version 1.

This class provides metadata for various fuel properties and a static method to compute the rate of spread (ROS) of fire using the Hamada’s model. The metadata includes descriptions, units, and acceptable ranges for each property.

Metadata

The model uses the following fuel parameters:

• side_length

  • Standard name: BUILDING_LENGTH_SIDE

  • Units: meter

  • Range: 0 to inf

  • Type: input

• separation

  • Standard name: BUILDING_LENGTH_SEPARATION

  • Units: meter

  • Range: 0 to inf

  • Type: input

• wind_u

  • Standard name: WIND_SPEED_U

  • Units: meter / second

  • Range: -inf to inf

  • Type: input

• wind_v

  • Standard name: WIND_SPEED_V

  • Units: meter / second

  • Range: -inf to inf

  • Type: input

• normal_vector_x

  • Standard name: NORMAL_SPREAD_DIR_X

  • Units: dimensionless

  • Range: -1 to 1

  • Type: input

• normal_vector_y

  • Standard name: NORMAL_SPREAD_DIR_Y

  • Units: dimensionless

  • Range: -1 to 1

  • Type: input

• fire_resistant_ratio

  • Standard name: BUILDING_RATIO_FIRE_RESISTANT

  • Units: dimensionless

  • Range: 0 to 1

  • Type: optional

  • Default: 0.6

• rate_of_spread

  • Standard name: RATE_OF_SPREAD

  • Units: meter / second

  • Range: 0 to inf

  • Type: output

static compute_ros(input_dict: dict[str, float | int | list[float] | list[int]], fuel_cat: int = 0, **opt) → float

Compute the rate of spread of fire using the Hamada’s model.

This function processes input fuel properties, optionally selects a specific fuel category, and calculates the rate of spread (ROS) of fire using the hamada_1 method. Missing keys in the input dictionary are replaced with their default values, as specified in Hamada_1.metadata. Input data must be provided in standard units without pint.Quantity objects. For unit-aware calculations, use compute_ros_with_units.

Parameters:

• input_dict (dict) – Dictionary containing the input data for various fuel properties. The keys should match the standard variable names as defined in Hamada_1.metadata. Each value can be a single float/int or a list/array of floats/ints.

• fuel_cat (int, optional) – Fuel category index (one-based). If provided, fuel properties are expected to be lists or arrays, and the function will extract the properties corresponding to the specified fuel category. If not provided, fuel properties are expected to be scalar values.

Returns:

The computed rate of spread of fire.

Return type:

float

Notes

• fuel_cat uses one-based indexing to align with natural fuel category numbering. When accessing lists or arrays in input_dict, the index is adjusted accordingly (i.e., index = fuel_cat - 1).

• This function assumes input_dict contains values in standard units (e.g., no pint.Quantity objects), compliant with units specified in the metadata dictionary.

static compute_ros_with_units(input_dict: dict[str, float | int | list[float] | list[int] | Quantity], fuel_cat: int = 0, **opt) → Quantity

Compute the rate of spread (ROS) of fire using modified Hamada’s model with unit handling.

This function extracts magnitudes from input data (removing pint.Quantity wrappers), computes the ROS using compute_ros, and attaches the appropriate unit to the result.

Parameters:

• input_dict (dict) – Dictionary containing input fuel properties as pint.Quantity objects or standard values. Keys should match the variable names defined in Hamada_1.metadata.

• fuel_cat (int, optional) – One-based index for selecting a specific fuel category from lists in input_dict. Defaults to 0, indicating scalar inputs.

• **opt (dict) – Additional optional parameters passed to compute_ros.

Returns:

Computed rate of spread (ROS) with units (e.g., meters per second).

Return type:

ureg.Quantity

Notes

• Use this function when working with pint.Quantity objects in input_dict.

• Units for the ROS are defined in Hamada_1.metadata[“rate_of_spread”][“units”].

static hamada_1(side_length: float, separation: float, wind_u: float, wind_v: float, normal_vector_x: float, normal_vector_y: float, fire_resistant_ratio: float) → float

Compute the urban rate of spread using the Hamada model.

Parameters:

• side_length (float) – Building side length [m].

• separation (float) – Buildings separation [m].

• wind_u (float) – The U component of the wind speed [m s-1].

• wind_v (float) – The V component of the wind speed [m s-1].

• normal_vector_x (float) – The X component of the normalized spread direction vector [-].

• wind_direction_y (float) – The Y component of the normalized spread direction vector [-].

• fire_resistant_ratio (float) – The ratio of fire-resistant buildings [-].

Returns:

The computed urban rate of spread in meters per second.

Return type:

float

metadata = {'fire_resistant_ratio': {'default': 0.6, 'range': (0, 1), 'std_name': StandardVariableNames.BUILDING_RATIO_FIRE_RESISTANT, 'type': ParameterType.optional, 'units': <Unit('dimensionless')>}, 'normal_vector_x': {'range': (-1, 1), 'std_name': StandardVariableNames.NORMAL_SPREAD_DIR_X, 'type': ParameterType.input, 'units': <Unit('dimensionless')>}, 'normal_vector_y': {'range': (-1, 1), 'std_name': StandardVariableNames.NORMAL_SPREAD_DIR_Y, 'type': ParameterType.input, 'units': <Unit('dimensionless')>}, 'rate_of_spread': {'range': (0, inf), 'std_name': StandardVariableNames.RATE_OF_SPREAD, 'type': ParameterType.output, 'units': <Unit('meter / second')>}, 'separation': {'range': (0, inf), 'std_name': StandardVariableNames.BUILDING_LENGTH_SEPARATION, 'type': ParameterType.input, 'units': <Unit('meter')>}, 'side_length': {'range': (0, inf), 'std_name': StandardVariableNames.BUILDING_LENGTH_SIDE, 'type': ParameterType.input, 'units': <Unit('meter')>}, 'wind_u': {'range': (-inf, inf), 'std_name': StandardVariableNames.WIND_SPEED_U, 'type': ParameterType.input, 'units': <Unit('meter / second')>}, 'wind_v': {'range': (-inf, inf), 'std_name': StandardVariableNames.WIND_SPEED_V, 'type': ParameterType.input, 'units': <Unit('meter / second')>}}

class firebench.ros_models.surface_for_urban.Hamada_2

Bases: RateOfSpreadModel

A class to represent the Hamada’s model for urban fire spread rate calculation in its version 2.

This class provides metadata for various fuel properties and a static method to compute the rate of spread (ROS) of fire using the Hamada’s model. The metadata includes descriptions, units, and acceptable ranges for each property.

Metadata

The model uses the following fuel parameters:

• side_length

  • Standard name: BUILDING_LENGTH_SIDE

  • Units: meter

  • Range: 0 to inf

  • Type: input

• separation

  • Standard name: BUILDING_LENGTH_SEPARATION

  • Units: meter

  • Range: 0 to inf

  • Type: input

• wind_u

  • Standard name: WIND_SPEED_U

  • Units: meter / second

  • Range: -inf to inf

  • Type: input

• wind_v

  • Standard name: WIND_SPEED_V

  • Units: meter / second

  • Range: -inf to inf

  • Type: input

• normal_vector_x

  • Standard name: NORMAL_SPREAD_DIR_X

  • Units: dimensionless

  • Range: -1 to 1

  • Type: input

• normal_vector_y

  • Standard name: NORMAL_SPREAD_DIR_Y

  • Units: dimensionless

  • Range: -1 to 1

  • Type: input

• fire_resistant_ratio

  • Standard name: BUILDING_RATIO_FIRE_RESISTANT

  • Units: dimensionless

  • Range: 0 to 1

  • Type: optional

  • Default: 0.6

• bare_structure_ratio

  • Standard name: BUILDING_RATIO_STRUCTURE_WOOD_BARE

  • Units: dimensionless

  • Range: 0 to 1

  • Type: optional

  • Default: 0.2

• mortar_structure_ratio

  • Standard name: BUILDING_RATIO_STRUCTURE_WOOD_MORTAR

  • Units: dimensionless

  • Range: 0 to 1

  • Type: optional

  • Default: 0.2

• beta

  • Standard name: BETA

  • Units: dimensionless

  • Range: 2 to inf

  • Type: optional

  • Default: 5

• rate_of_spread

  • Standard name: RATE_OF_SPREAD

  • Units: meter / second

  • Range: 0 to inf

  • Type: output

static compute_ros(input_dict: dict[str, float | int | list[float] | list[int]], fuel_cat: int = 0, **opt) → float

Compute the rate of spread of fire using the Hamada’s model.

This function processes input fuel properties, optionally selects a specific fuel category, and calculates the rate of spread (ROS) of fire using the hamada_2 method. Missing keys in the input dictionary are replaced with their default values, as specified in Hamada_2.metadata. Input data must be provided in standard units without pint.Quantity objects. For unit-aware calculations, use compute_ros_with_units.

Parameters:

• input_dict (dict) – Dictionary containing the input data for various fuel properties. The keys should match the standard variable names as defined in Hamada_2.metadata. Each value can be a single float/int or a list/array of floats/ints.

• fuel_cat (int, optional) – Fuel category index (one-based). If provided, fuel properties are expected to be lists or arrays, and the function will extract the properties corresponding to the specified fuel category. If not provided, fuel properties are expected to be scalar values.

Returns:

The computed rate of spread of fire.

Return type:

float

Notes

• fuel_cat uses one-based indexing to align with natural fuel category numbering. When accessing lists or arrays in input_dict, the index is adjusted accordingly (i.e., index = fuel_cat - 1).

• This function assumes input_dict contains values in standard units (e.g., no pint.Quantity objects), compliant with units specified in the metadata dictionary.

static compute_ros_with_units(input_dict: dict[str, float | int | list[float] | list[int] | Quantity], fuel_cat: int = 0, **opt) → Quantity

Compute the rate of spread (ROS) of fire using modified Hamada’s model with unit handling.

This function extracts magnitudes from input data (removing pint.Quantity wrappers), computes the ROS using compute_ros, and attaches the appropriate unit to the result.

Parameters:

• input_dict (dict) – Dictionary containing input fuel properties as pint.Quantity objects or standard values. Keys should match the variable names defined in Hamada_2.metadata.

• fuel_cat (int, optional) – One-based index for selecting a specific fuel category from lists in input_dict. Defaults to 0, indicating scalar inputs.

• **opt (dict) – Additional optional parameters passed to compute_ros.

Returns:

Computed rate of spread (ROS) with units (e.g., meters per second).

Return type:

ureg.Quantity

Notes

• Use this function when working with pint.Quantity objects in input_dict.

• Units for the ROS are defined in Hamada_2.metadata[“rate_of_spread”][“units”].

static hamada_2(side_length: float, separation: float, wind_u: float, wind_v: float, normal_vector_x: float, normal_vector_y: float, fire_resistant_ratio: float, bare_structure_ratio: float, mortar_structure_ratio: float, beta: float) → float

Compute the urban rate of spread using the Hamada model.

Parameters:

• side_length (float) – Building side length [m].

• separation (float) – Buildings separation distance [m].

• wind_u (float) – The U component of the wind speed [m s-1].

• wind_v (float) – The V component of the wind speed [m s-1].

• normal_vector_x (float) – The X component of the normalized spread direction vector [-].

• wind_direction_y (float) – The Y component of the normalized spread direction vector [-].

• fire_resistant_ratio (float) – The ratio of fire-resistant buildings [-].

• bare_structure_ratio (float) – The ratio of buildings with bare structural materials [-].

• mortar_structure_ratio (float) – The ratio of buildings with mortar [-].

• beta (float) – The beta parameter for the model (>2 for stability) [-].

Returns:

The computed urban rate of spread in meters per second.

Return type:

float

metadata = {'bare_structure_ratio': {'default': 0.2, 'range': (0, 1), 'std_name': StandardVariableNames.BUILDING_RATIO_STRUCTURE_WOOD_BARE, 'type': ParameterType.optional, 'units': <Unit('dimensionless')>}, 'beta': {'default': 5, 'range': (2, inf), 'std_name': StandardVariableNames.BETA, 'type': ParameterType.optional, 'units': <Unit('dimensionless')>}, 'fire_resistant_ratio': {'default': 0.6, 'range': (0, 1), 'std_name': StandardVariableNames.BUILDING_RATIO_FIRE_RESISTANT, 'type': ParameterType.optional, 'units': <Unit('dimensionless')>}, 'mortar_structure_ratio': {'default': 0.2, 'range': (0, 1), 'std_name': StandardVariableNames.BUILDING_RATIO_STRUCTURE_WOOD_MORTAR, 'type': ParameterType.optional, 'units': <Unit('dimensionless')>}, 'normal_vector_x': {'range': (-1, 1), 'std_name': StandardVariableNames.NORMAL_SPREAD_DIR_X, 'type': ParameterType.input, 'units': <Unit('dimensionless')>}, 'normal_vector_y': {'range': (-1, 1), 'std_name': StandardVariableNames.NORMAL_SPREAD_DIR_Y, 'type': ParameterType.input, 'units': <Unit('dimensionless')>}, 'rate_of_spread': {'range': (0, inf), 'std_name': StandardVariableNames.RATE_OF_SPREAD, 'type': ParameterType.output, 'units': <Unit('meter / second')>}, 'separation': {'range': (0, inf), 'std_name': StandardVariableNames.BUILDING_LENGTH_SEPARATION, 'type': ParameterType.input, 'units': <Unit('meter')>}, 'side_length': {'range': (0, inf), 'std_name': StandardVariableNames.BUILDING_LENGTH_SIDE, 'type': ParameterType.input, 'units': <Unit('meter')>}, 'wind_u': {'range': (-inf, inf), 'std_name': StandardVariableNames.WIND_SPEED_U, 'type': ParameterType.input, 'units': <Unit('meter / second')>}, 'wind_v': {'range': (-inf, inf), 'std_name': StandardVariableNames.WIND_SPEED_V, 'type': ParameterType.input, 'units': <Unit('meter / second')>}}

Vegetation rate of spread models

class firebench.ros_models.surface_for_vegetation.Balbi_2022_fixed_SFIRE

Bases: RateOfSpreadModel

A class to represent the Balbi’s model for fire spread rate calculation used in SFIRE code.

This version is based on Chatelon et al. 2022. To prevent negative value of rate of spread, the following modifications have been applied: - the tile angle gamma is bouded to 0 - the radiative contribution to ros Rc is bounded to 0

Metadata

The model uses the following fuel parameters:

• dead_fuel_ratio

  • Standard name: FUEL_LOAD_DEAD_RATIO

  • Units: dimensionless

  • Range: 0 to 1

  • Type: input

• fgi

  • Standard name: FUEL_LOAD_DRY_TOTAL

  • Units: kilogram / meter ** 2

  • Range: 0 to inf

  • Type: input

• fueldepthm

  • Standard name: FUEL_HEIGHT

  • Units: meter

  • Range: 0 to inf

  • Type: input

• fueldens

  • Standard name: FUEL_DENSITY

  • Units: kilogram / meter ** 3

  • Range: 0 to inf

  • Type: input

• savr

  • Standard name: FUEL_SURFACE_AREA_VOLUME_RATIO

  • Units: 1 / meter

  • Range: 0 to inf

  • Type: input

• w0

  • Standard name: IGNITION_LENGTH

  • Units: meter

  • Range: 0 to inf

  • Type: optional

  • Default: 50

• temp_ign

  • Standard name: FUEL_TEMPERATURE_IGNITION

  • Units: kelvin

  • Range: 0 to inf

  • Type: optional

  • Default: 600

• temp_air

  • Standard name: AIR_TEMPERATURE

  • Units: kelvin

  • Range: 0 to inf

  • Type: optional

  • Default: 300

• dens_air

  • Standard name: AIR_DENSITY

  • Units: kilogram / meter ** 3

  • Range: 0 to inf

  • Type: optional

  • Default: 1.125

• wind

  • Standard name: WIND_SPEED

  • Units: meter / second

  • Range: -inf to inf

  • Type: input

• slope

  • Standard name: SLOPE_ANGLE

  • Units: degree

  • Range: -90 to 90

  • Type: input

• fmc

  • Standard name: FUEL_MOISTURE_CONTENT

  • Units: percent

  • Range: 0 to 200

  • Type: input

• rate_of_spread

  • Standard name: RATE_OF_SPREAD

  • Units: meter / second

  • Range: 0 to inf

  • Type: output

static balbi_2022_fixed(dead_fuel_ratio: float, fgi: float, fueldepthm: float, fueldens: float, temp_ign: float, temp_air: float, dens_air: float, savr: float, w0: float, wind: float, slope: float, fmc: float, **opt) → float

Compute the rate of spread using the Balbi’s model from SFIRE code.

Parameters:

• wind (float) – Wind speed in the normal direction at 6.1m (20ft) [m/s].

• slope (float) – Slope angle [degrees].

• fmc (float) – Fuel moisture content [%].

• w0 (float) – Ignition line width [m].

• Parameters (Optional)

• -------------------

• max_ite (int, optional) – maximum number of iteration for the fixed point method.

Returns:

Rate of spread [m/s]

Return type:

float

static compute_ros(input_dict: dict[str, float | int | list[float] | list[int]], fuel_cat: int = 0, **opt) → float

Compute the rate of spread of fire using the Balbi's 2022 model.

This function processes input fuel properties, optionally selects a specific fuel category, and calculates the rate of spread (ROS) of fire using the balbi_2022_fixed method. Input data must be provided in standard units without pint.Quantity objects. For unit-aware calculations, use compute_ros_with_units.

Parameters:

• input_dict (dict) – Dictionary containing the input data for various fuel properties. The keys should be the standard variable names as defined in Balbi_2022_fixed_SFIRE.metadata. Each value can be a single float/int or a list/array of floats/ints.

• fuel_cat (int, optional) – Fuel category index (one-based). If provided, fuel properties are expected to be lists or arrays, and the function will extract the properties corresponding to the specified fuel category. If not provided, fuel properties are expected to be scalar values.

• **opt (dict) – Additional optional parameters to be passed to the balbi_2022_fixed method.

Returns:

The computed rate of spread of fire.

Return type:

float

Notes

• fuel_cat uses one-based indexing to align with natural fuel category numbering. When accessing lists or arrays in input_dict, the index is adjusted accordingly (i.e., index = fuel_cat - 1).

• This function assumes input_dict contains values in standard units (e.g., no pint.Quantity objects), compliant with units specified in the metadata dictionary.

static compute_ros_with_units(input_dict: dict[str, float | int | list[float] | list[int] | Quantity], fuel_cat: int = 0, **opt) → Quantity

Compute the rate of spread (ROS) of fire using Balbi’s 2022 model with unit handling.

This function extracts magnitudes from input data (removing pint.Quantity wrappers), computes the ROS using compute_ros, and attaches the appropriate unit to the result.

Parameters:

• input_dict (dict) – Dictionary containing input fuel properties as pint.Quantity objects or standard values. Keys should match the variable names defined in Balbi_2022_fixed_SFIRE.metadata.

• fuel_cat (int, optional) – One-based index for selecting a specific fuel category from lists in input_dict. Defaults to 0, indicating scalar inputs.

• **opt (dict) – Additional optional parameters passed to compute_ros.

Returns:

Computed rate of spread (ROS) with units (e.g., meters per second).

Return type:

ureg.Quantity

Notes

• Use this function when working with pint.Quantity objects in input_dict.

• Units for the ROS are defined in Balbi_2022_fixed_SFIRE.metadata[“rate_of_spread”][“units”].

metadata = {'dead_fuel_ratio': {'range': (0, 1), 'std_name': StandardVariableNames.FUEL_LOAD_DEAD_RATIO, 'type': ParameterType.input, 'units': <Unit('dimensionless')>}, 'dens_air': {'default': 1.125, 'range': (0, inf), 'std_name': StandardVariableNames.AIR_DENSITY, 'type': ParameterType.optional, 'units': <Unit('kilogram / meter ** 3')>}, 'fgi': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_LOAD_DRY_TOTAL, 'type': ParameterType.input, 'units': <Unit('kilogram / meter ** 2')>}, 'fmc': {'range': (0, 200), 'std_name': StandardVariableNames.FUEL_MOISTURE_CONTENT, 'type': ParameterType.input, 'units': <Unit('percent')>}, 'fueldens': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_DENSITY, 'type': ParameterType.input, 'units': <Unit('kilogram / meter ** 3')>}, 'fueldepthm': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_HEIGHT, 'type': ParameterType.input, 'units': <Unit('meter')>}, 'rate_of_spread': {'range': (0, inf), 'std_name': StandardVariableNames.RATE_OF_SPREAD, 'type': ParameterType.output, 'units': <Unit('meter / second')>}, 'savr': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_SURFACE_AREA_VOLUME_RATIO, 'type': ParameterType.input, 'units': <Quantity(1, '1 / meter')>}, 'slope': {'range': (-90, 90), 'std_name': StandardVariableNames.SLOPE_ANGLE, 'type': ParameterType.input, 'units': <Unit('degree')>}, 'temp_air': {'default': 300, 'range': (0, inf), 'std_name': StandardVariableNames.AIR_TEMPERATURE, 'type': ParameterType.optional, 'units': <Unit('kelvin')>}, 'temp_ign': {'default': 600, 'range': (0, inf), 'std_name': StandardVariableNames.FUEL_TEMPERATURE_IGNITION, 'type': ParameterType.optional, 'units': <Unit('kelvin')>}, 'w0': {'default': 50, 'range': (0, inf), 'std_name': StandardVariableNames.IGNITION_LENGTH, 'type': ParameterType.optional, 'units': <Unit('meter')>}, 'wind': {'range': (-inf, inf), 'std_name': StandardVariableNames.WIND_SPEED, 'type': ParameterType.input, 'units': <Unit('meter / second')>}}

class firebench.ros_models.surface_for_vegetation.Rothermel_SFIRE

Bases: RateOfSpreadModel

A class to represent the Rothermel’s model for fire spread rate calculation used in SFIRE code.

This class provides metadata for various fuel properties and a static method to compute the rate of spread (ROS). The metadata includes descriptions, units, and acceptable ranges for each property.

Metadata

The model uses the following fuel parameters:

• fgi

  • Standard name: FUEL_LOAD_DRY_TOTAL

  • Units: kilogram / meter ** 2

  • Range: 0 to inf

  • Type: input

• fueldepthm

  • Standard name: FUEL_HEIGHT

  • Units: meter

  • Range: 0 to inf

  • Type: input

• fueldens

  • Standard name: FUEL_DENSITY

  • Units: pound / foot ** 3

  • Range: 0 to inf

  • Type: input

• savr

  • Standard name: FUEL_SURFACE_AREA_VOLUME_RATIO

  • Units: 1 / foot

  • Range: 0 to inf

  • Type: input

• fuelmce

  • Standard name: FUEL_MOISTURE_EXTINCTION

  • Units: percent

  • Range: 0 to inf

  • Type: input

• st

  • Standard name: FUEL_MINERAL_CONTENT_TOTAL

  • Units: dimensionless

  • Range: 0 to 1

  • Type: input

• se

  • Standard name: FUEL_MINERAL_CONTENT_EFFECTIVE

  • Units: dimensionless

  • Range: 0 to 1

  • Type: input

• ichap

  • Standard name: FUEL_CHAPARRAL_FLAG

  • Units: dimensionless

  • Range: 0 to 1

  • Type: input

• wind

  • Standard name: WIND_SPEED

  • Units: meter / second

  • Range: -inf to inf

  • Type: input

• slope

  • Standard name: SLOPE_ANGLE

  • Units: degree

  • Range: -90 to 90

  • Type: input

• fmc

  • Standard name: FUEL_MOISTURE_CONTENT

  • Units: percent

  • Range: 0 to 200

  • Type: input

• rate_of_spread

  • Standard name: RATE_OF_SPREAD

  • Units: meter / second

  • Range: 0 to inf

  • Type: output

static compute_ros(input_dict: dict[str, float | int | list[float] | list[int]], fuel_cat: int = 0, **opt) → float

Compute the rate of spread of fire using Rothermel’s model.

This function processes input fuel properties, optionally selects a specific fuel category, and calculates the ROS. Input data must be provided in standard units without pint.Quantity objects. For unit-aware calculations, use compute_ros_with_units.

Parameters:

• input_dict (dict) – Dictionary containing the input data for various fuel properties. The keys should be the standard variable names as defined in Rothermel_SFIRE.metadata. Each value can be a single float/int or a list/array of floats/ints.

• fuel_cat (int, optional) – Fuel category index (one-based). If provided, fuel properties are expected to be lists or arrays, and the function will extract the properties corresponding to the specified fuel category. If not provided, fuel properties are expected to be scalar values.

• **opt (dict) – Additional optional parameters to be passed to the rothermel method.

Returns:

The computed rate of spread of fire.

Return type:

float

Notes

• fuel_cat uses one-based indexing to align with natural fuel category numbering. When accessing lists or arrays in input_dict, the index is adjusted accordingly (i.e., index = fuel_cat - 1).

• This function assumes input_dict contains values in standard units (e.g., no pint.Quantity objects), compliant with units specified in the metadata dictionary.

Examples

Example with scalar fuel properties:

input_data = {
    svn.FUEL_LOAD_DRY_TOTAL: 0.5,           # fgi
    svn.FUEL_HEIGHT: 0.3,                   # fueldepthm
    svn.FUEL_DENSITY: 32.0,                 # fueldens
    svn.FUEL_SURFACE_AREA_VOLUME_RATIO: 2000.0,  # savr
    svn.FUEL_MOISTURE_EXTINCTION: 30.0,     # fuelmce
    svn.FUEL_MINERAL_CONTENT_TOTAL: 0.0555, # st
    svn.FUEL_MINERAL_CONTENT_EFFECTIVE: 0.01,    # se
    svn.FUEL_CHAPARRAL_FLAG: 0,             # ichap
    svn.WIND_SPEED: 2.0,
    svn.SLOPE_ANGLE: 15.0,
    svn.FUEL_MOISTURE_CONTENT: 10.0,
}
ros = Rothermel_SFIRE.compute_ros(input_data)
print(f"The rate of spread is {ros:.4f}")

Example with fuel categories:

input_data = {
    svn.FUEL_LOAD_DRY_TOTAL: [0.4, 0.5, 0.6],           # fgi
    svn.FUEL_HEIGHT: [0.2, 0.3, 0.4],                   # fueldepthm
    svn.FUEL_DENSITY: [30.0, 32.0, 34.0],               # fueldens
    svn.FUEL_SURFACE_AREA_VOLUME_RATIO: [1800.0, 2000.0, 2200.0],  # savr
    svn.FUEL_MOISTURE_EXTINCTION: [25.0, 30.0, 35.0],   # fuelmce
    svn.FUEL_MINERAL_CONTENT_TOTAL: [0.05, 0.0555, 0.06],     # st
    svn.FUEL_MINERAL_CONTENT_EFFECTIVE: [0.009, 0.01, 0.011],  # se
    svn.FUEL_CHAPARRAL_FLAG: [0, 0, 1],                 # ichap
    svn.WIND_SPEED: 2.0,
    svn.SLOPE_ANGLE: 15.0,
    svn.FUEL_MOISTURE_CONTENT: 10.0,
}
fuel_category = 2  # One-based index
ros = Rothermel_SFIRE.compute_ros(input_data, fuel_cat=fuel_category)
print(f"The rate of spread for fuel category {fuel_category} is {ros:.4f}")

static compute_ros_with_units(input_dict: dict[str, float | int | list[float] | list[int] | Quantity], fuel_cat: int = 0, **opt) → Quantity

Compute the rate of spread (ROS) of fire using Rothermel’s model with unit handling.

This function extracts magnitudes from input data (removing pint.Quantity wrappers), computes the ROS using compute_ros, and attaches the appropriate unit to the result.

Parameters:

• input_dict (dict) – Dictionary containing input fuel properties as pint.Quantity objects or standard values. Keys should match the variable names defined in Rothermel_SFIRE.metadata.

• fuel_cat (int, optional) – One-based index for selecting a specific fuel category from lists in input_dict. Defaults to 0, indicating scalar inputs.

• **opt (dict) – Additional optional parameters passed to compute_ros.

Returns:

Computed rate of spread (ROS) with units (e.g., meters per second).

Return type:

ureg.Quantity

Notes

• Use this function when working with pint.Quantity objects in input_dict.

• Units for the ROS are defined in Rothermel_SFIRE.metadata[“rate_of_spread”][“units”].

metadata = {'fgi': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_LOAD_DRY_TOTAL, 'type': ParameterType.input, 'units': <Unit('kilogram / meter ** 2')>}, 'fmc': {'range': (0, 200), 'std_name': StandardVariableNames.FUEL_MOISTURE_CONTENT, 'type': ParameterType.input, 'units': <Unit('percent')>}, 'fueldens': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_DENSITY, 'type': ParameterType.input, 'units': <Unit('pound / foot ** 3')>}, 'fueldepthm': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_HEIGHT, 'type': ParameterType.input, 'units': <Unit('meter')>}, 'fuelmce': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_MOISTURE_EXTINCTION, 'type': ParameterType.input, 'units': <Unit('percent')>}, 'ichap': {'range': (0, 1), 'std_name': StandardVariableNames.FUEL_CHAPARRAL_FLAG, 'type': ParameterType.input, 'units': <Unit('dimensionless')>}, 'rate_of_spread': {'range': (0, inf), 'std_name': StandardVariableNames.RATE_OF_SPREAD, 'type': ParameterType.output, 'units': <Unit('meter / second')>}, 'savr': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_SURFACE_AREA_VOLUME_RATIO, 'type': ParameterType.input, 'units': <Quantity(1, '1 / foot')>}, 'se': {'range': (0, 1), 'std_name': StandardVariableNames.FUEL_MINERAL_CONTENT_EFFECTIVE, 'type': ParameterType.input, 'units': <Unit('dimensionless')>}, 'slope': {'range': (-90, 90), 'std_name': StandardVariableNames.SLOPE_ANGLE, 'type': ParameterType.input, 'units': <Unit('degree')>}, 'st': {'range': (0, 1), 'std_name': StandardVariableNames.FUEL_MINERAL_CONTENT_TOTAL, 'type': ParameterType.input, 'units': <Unit('dimensionless')>}, 'wind': {'range': (-inf, inf), 'std_name': StandardVariableNames.WIND_SPEED, 'type': ParameterType.input, 'units': <Unit('meter / second')>}}

static rothermel(fgi: float, fueldepthm: float, fueldens: float, savr: float, fuelmce: float, st: float, se: float, ichap: int, wind: float, slope: float, fmc: float) → float

Compute the rate of spread using Rothermel’s model.

This function calculates the forward rate of spread of a fire in a uniform fuel bed using Rothermel’s (1972) fire spread model. The model considers fuel properties, wind speed, slope, and fuel moisture content to estimate the rate at which a fire will spread through wildland fuels.

Parameters:

• fgi (float) – Total fuel load (dry weight) per unit area [kg m-2]. Represents the total mass of combustible material available to the fire.

• fueldepthm (float) – Fuel bed depth [m]. The vertical depth of the fuel bed perpendicular to the ground surface.

• fueldens (float) – Oven-dry fuel particle density [lb ft-3]. The density of individual fuel particles when completely dry.

• savr (float) – Surface-area-to-volume ratio [ft-1]. A measure of the fineness of the fuel particles; higher values indicate finer fuels.

• fuelmce (float) – Moisture content of extinction [%]. The fuel moisture content at which a fire will no longer spread.

• st (float) – Total mineral content [unitless, between 0 and 1]. The proportion of the fuel that is composed of mineral (inorganic) material.

• se (float) – Effective mineral content [unitless, between 0 and 1]. The proportion of mineral content that effectively absorbs heat.

• ichap (int) – Chaparral flag (0 or 1). Indicator for chaparral fuel type: set to 1 if the fuel is chaparral, otherwise 0.

• wind (float) – Wind speed at midflame height or average wind over flame height [m s-1]. The wind speed influencing the fire spread at the height of the flames.

• slope (float) – Slope steepness [degrees]. The angle of the terrain slope; positive for uphill, negative for downhill.

• fmc (float) – Fuel moisture content [%]. The actual moisture content of the fuel affecting combustion.

• **opt (dict, optional) – Additional optional parameters.

Returns:

Rate of spread [m/s]. The estimated forward rate of spread of the fire.

Return type:

float

References

Rothermel, R. C. (1972). A mathematical model for predicting fire spread in wildland fuels. USDA Forest Service Research Paper INT-115. Ogden, UT.

class firebench.ros_models.surface_for_vegetation.Santoni_2011

Bases: RateOfSpreadModel

A class to represent the Santoni’s model for fire spread rate calculation.

This version is based on Santoni et al. 2011.

Metadata

The model uses the following fuel parameters:

• fuel_load_dry_total

  • Standard name: FUEL_LOAD_DRY_TOTAL

  • Units: kilogram / meter ** 2

  • Range: 0 to inf

  • Type: input

• dead_fuel_ratio

  • Standard name: FUEL_LOAD_DEAD_RATIO

  • Units: dimensionless

  • Range: 0 to 1

  • Type: input

• fueldepth

  • Standard name: FUEL_HEIGHT

  • Units: meter

  • Range: 0 to inf

  • Type: input

• fuel_dens_dead

  • Standard name: FUEL_DENSITY_DEAD

  • Units: kilogram / meter ** 3

  • Range: 0 to inf

  • Type: input

• fuel_dens_live

  • Standard name: FUEL_DENSITY_LIVE

  • Units: kilogram / meter ** 3

  • Range: 0 to inf

  • Type: input

• temp_ign

  • Standard name: FUEL_TEMPERATURE_IGNITION

  • Units: kelvin

  • Range: 0 to inf

  • Type: optional

  • Default: 600

• temp_air

  • Standard name: AIR_TEMPERATURE

  • Units: kelvin

  • Range: 0 to inf

  • Type: optional

  • Default: 300

• dens_air

  • Standard name: AIR_DENSITY

  • Units: kilogram / meter ** 3

  • Range: 0 to inf

  • Type: optional

  • Default: 1.125

• savr_dead

  • Standard name: FUEL_SURFACE_AREA_VOLUME_RATIO_DEAD

  • Units: 1 / meter

  • Range: 0 to inf

  • Type: input

• savr_live

  • Standard name: FUEL_SURFACE_AREA_VOLUME_RATIO_LIVE

  • Units: 1 / meter

  • Range: 0 to inf

  • Type: input

• wind

  • Standard name: WIND_SPEED

  • Units: meter / second

  • Range: -inf to inf

  • Type: input

• slope

  • Standard name: SLOPE_ANGLE

  • Units: degree

  • Range: -90 to 90

  • Type: input

• fmc_dead

  • Standard name: FUEL_MOISTURE_CONTENT_DEAD

  • Units: percent

  • Range: 0 to 200

  • Type: input

• fmc_live

  • Standard name: FUEL_MOISTURE_CONTENT_LIVE

  • Units: percent

  • Range: 0 to 500

  • Type: input

• rate_of_spread

  • Standard name: RATE_OF_SPREAD

  • Units: meter / second

  • Range: 0 to inf

  • Type: output

static compute_ros(input_dict: dict[str, float | int | list[float] | list[int]], fuel_cat: int = 0, **opt) → float

Compute the rate of spread of fire using the Santoni's 2011 model.

This function processes input fuel properties, optionally selects a specific fuel category, and calculates the rate of spread (ROS) of fire using the santoni_2011 method. Input data must be provided in standard units without pint.Quantity objects. For unit-aware calculations, use compute_ros_with_units.

Parameters:

• input_dict (dict) – Dictionary containing the input data for various fuel properties. The keys should be the standard variable names as defined in santoni_2011.metadata. Each value can be a single float/int or a list/array of floats/ints.

• fuel_cat (int, optional) – Fuel category index (one-based). If provided, fuel properties are expected to be lists or arrays, and the function will extract the properties corresponding to the specified fuel category. If not provided, fuel properties are expected to be scalar values.

• **opt (dict) – Additional optional parameters to be passed to the santoni_2011 method.

Returns:

The computed rate of spread of fire.

Return type:

float

Notes

• fuel_cat uses one-based indexing to align with natural fuel category numbering. When accessing lists or arrays in input_dict, the index is adjusted accordingly (i.e., index = fuel_cat - 1).

• This function assumes input_dict contains values in standard units (e.g., no pint.Quantity objects), compliant with units specified in the metadata dictionary.

static compute_ros_with_units(input_dict: dict[str, float | int | list[float] | list[int] | Quantity], fuel_cat: int = 0, **opt) → Quantity

Compute the rate of spread (ROS) of fire using Santoni’s 2011 model with unit handling.

This function extracts magnitudes from input data (removing pint.Quantity wrappers), computes the ROS using compute_ros, and attaches the appropriate unit to the result.

Parameters:

• input_dict (dict) – Dictionary containing input fuel properties as pint.Quantity objects or standard values. Keys should match the variable names defined in Santoni_2011.metadata.

• fuel_cat (int, optional) – One-based index for selecting a specific fuel category from lists in input_dict. Defaults to 0, indicating scalar inputs.

• **opt (dict) – Additional optional parameters passed to compute_ros.

Returns:

Computed rate of spread (ROS) with units (e.g., meters per second).

Return type:

ureg.Quantity

Notes

• Use this function when working with pint.Quantity objects in input_dict.

• Units for the ROS are defined in Balbi_2022_fixed_SFIRE.metadata[“rate_of_spread”][“units”].

metadata = {'dead_fuel_ratio': {'range': (0, 1), 'std_name': StandardVariableNames.FUEL_LOAD_DEAD_RATIO, 'type': ParameterType.input, 'units': <Unit('dimensionless')>}, 'dens_air': {'default': 1.125, 'range': (0, inf), 'std_name': StandardVariableNames.AIR_DENSITY, 'type': ParameterType.optional, 'units': <Unit('kilogram / meter ** 3')>}, 'fmc_dead': {'range': (0, 200), 'std_name': StandardVariableNames.FUEL_MOISTURE_CONTENT_DEAD, 'type': ParameterType.input, 'units': <Unit('percent')>}, 'fmc_live': {'range': (0, 500), 'std_name': StandardVariableNames.FUEL_MOISTURE_CONTENT_LIVE, 'type': ParameterType.input, 'units': <Unit('percent')>}, 'fuel_dens_dead': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_DENSITY_DEAD, 'type': ParameterType.input, 'units': <Unit('kilogram / meter ** 3')>}, 'fuel_dens_live': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_DENSITY_LIVE, 'type': ParameterType.input, 'units': <Unit('kilogram / meter ** 3')>}, 'fuel_load_dry_total': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_LOAD_DRY_TOTAL, 'type': ParameterType.input, 'units': <Unit('kilogram / meter ** 2')>}, 'fueldepth': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_HEIGHT, 'type': ParameterType.input, 'units': <Unit('meter')>}, 'rate_of_spread': {'range': (0, inf), 'std_name': StandardVariableNames.RATE_OF_SPREAD, 'type': ParameterType.output, 'units': <Unit('meter / second')>}, 'savr_dead': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_SURFACE_AREA_VOLUME_RATIO_DEAD, 'type': ParameterType.input, 'units': <Quantity(1, '1 / meter')>}, 'savr_live': {'range': (0, inf), 'std_name': StandardVariableNames.FUEL_SURFACE_AREA_VOLUME_RATIO_LIVE, 'type': ParameterType.input, 'units': <Quantity(1, '1 / meter')>}, 'slope': {'range': (-90, 90), 'std_name': StandardVariableNames.SLOPE_ANGLE, 'type': ParameterType.input, 'units': <Unit('degree')>}, 'temp_air': {'default': 300, 'range': (0, inf), 'std_name': StandardVariableNames.AIR_TEMPERATURE, 'type': ParameterType.optional, 'units': <Unit('kelvin')>}, 'temp_ign': {'default': 600, 'range': (0, inf), 'std_name': StandardVariableNames.FUEL_TEMPERATURE_IGNITION, 'type': ParameterType.optional, 'units': <Unit('kelvin')>}, 'wind': {'range': (-inf, inf), 'std_name': StandardVariableNames.WIND_SPEED, 'type': ParameterType.input, 'units': <Unit('meter / second')>}}

static santoni_2011(fuel_load_dry_total: float, dead_fuel_ratio: float, fueldepth: float, fuel_dens_dead: float, fuel_dens_live: float, temp_ign: float, temp_air: float, dens_air: float, savr_dead: float, savr_live: float, wind: float, slope: float, fmc_dead: float, fmc_live: float) → float

Compute the rate of spread using the Santoni’s model.

Parameters:

• fuel_load_dry_total (float) – total dry fuel load [kg m-2]

• dead_fuel_ratio (float) – ratio of dead fuel load to total fuel load [-]

• fuel_dens_dead (float) – dead fuel density [kg m-3]

• fuel_dens_live (float) – live fuel density [kg m-3]

• temp_ign (float) – fuel ignition temperature [K]

• temp_air (float) – ambiant air temperature [K]

• dens_air (float) – ambiant air density [kg m-3]

• savr_dead (float) – dead fuel surface area to volume ratio [m-1]

• savr_live (float) – live fuel surface area to volume ratio [m-1]

• wind (float) – midflame wind speed [m s-1]

• slope (float) – slope angle [degrees]

• fmc_dead (float) – dead fuel moisture content [%]

• fmc_live (float) – live fuel moisture content [%]

Returns:

Rate of spread [m s-1]

Return type:

float