firebench.tools

firebench.tools.check_data_quality.check_data_quality_ros_model(input_dict: dict[str, Quantity], ros_model: RateOfSpreadModel) → dict[source]

Check and process the input data quality for a Rate of Spread (ROS) model.

This function performs the following checks and conversions on the input data: - Completeness: Ensures all necessary inputs for the ROS model are present in the input dictionary. - Unit Conversion: Converts units of input data to match the units specified in the ROS model’s metadata. - Validity Range: Verifies that the input data values are within the valid ranges specified by the model’s metadata.

Parameters:

  • input_dict (dict) – Dictionary containing the input data for the ROS model. The keys are the standard names of the variables, and the values are quantities with units.

  • ros_model (RateOfSpreadModel) – An instance of a subclass of RateOfSpreadModel that provides the metadata for the ROS model.

Returns:

A new dictionary with the input data checked for completeness, units converted, and values verified to be within valid ranges. The values are converted to their magnitude (unitless).

Return type:

dict

firebench.tools.check_data_quality.check_input_completeness(input_data: dict, metadata_dict: dict)[source]

Check the completeness of the input data against the metadata dictionary.

Parameters:

  • input_data (dict) – Dictionary containing the input data.

  • metadata_dict (dict) – Dictionary containing metadata, where each key is a metadata item and each value is a dictionary with at least the key “std_name” representing the standard name of the data item.

Raises:

KeyError – If any standard name specified in the metadata is missing in the input data.

firebench.tools.check_data_quality.check_validity_range(input_data: dict, metadata_dict: dict)[source]

Check if the input data values fall within the specified validity range in the metadata dictionary.

Parameters:

  • input_data (dict) – Dictionary containing the input data with units.

  • metadata_dict (dict) – Dictionary containing metadata, where each key is a metadata item and each value is a dictionary with at least the key “std_name” representing the standard name of the data item, “units” specifying the units, and “range” specifying the valid range as a tuple (min, max).

Raises:

ValueError – If any value in the input data is outside the specified validity range in the metadata.

firebench.tools.check_data_quality.convert_input_data_units(input_data: dict, metadata_dict: dict) → dict[source]

Convert the units of input data based on the metadata dictionary.

Parameters:

  • input_data (dict) – Dictionary containing the input data with units.

  • metadata_dict (dict) – Dictionary containing metadata, where each key is a metadata item and each value is a dictionary with at least the key “std_name” representing the standard name of the data item and “units” specifying the target units.

Returns:

A dictionary where the keys are standard variable names (as per metadata) and the values are quantities converted to the target units.

Return type:

dict

Raises:

KeyError – If any standard name specified in the metadata is missing in the input data.

firebench.tools.check_data_quality.extract_magnitudes(input_dict)[source]

Extract magnitudes from a dictionary of quantities.

Parameters:

input_dict (dict) – A dictionary where each value is expected to have a ‘magnitude’ attribute (from pint.Quantity).

Returns:

A new dictionary with the same keys as input_dict, where each value is the ‘magnitude’ attribute of the corresponding value in input_dict.

Return type:

dict

Notes

If accessing ‘value.magnitude’ raises an exception, a warning is logged, and the key is kept identical.

firebench.tools.fuel_models_utils.add_anderson_dead_fuel_ratio(fuel_data_dict, overwrite=False, use_1h_only=False)[source]

Calculate and add the dead fuel load ratio to a fuel data dictionary based on the Anderson 13 fuel model.

The dead fuel load ratio represents the fraction of the total fuel load that is attributed to dead fuels. It is calculated as the ratio of the sum of specific dead fuel loads to the sum of all fuel loads (dead and live).

Dead fuel loads considered

  • FUEL_LOAD_DRY_1H

  • FUEL_LOAD_DRY_10H

  • FUEL_LOAD_DRY_100H

Live fuel loads considered

  • FUEL_LOAD_DRY_LIVE

The result is stored under the key FUEL_LOAD_DEAD_RATIO in fuel_data_dict.

Parameters:

  • fuel_data_dict (dict) – Dictionary containing individual fuel load values with specific keys.

  • overwrite (bool, optional) – If True, overwrites the existing dead fuel ratio if it exists. If False and the value already exists, raises a ValueError. Default is False.

  • use_1h_only (bool, optional) – If True, use only FUEL_LOAD_DRY_1H for dead fuel load. If False, use all dead fuel load keys. Default is False.

Raises:

  • ValueError – If FUEL_LOAD_DEAD_RATIO already exists in fuel_data_dict and overwrite is False.

  • KeyError – If any required individual fuel load keys are missing from fuel_data_dict.

Notes

This function assumes that fuel_data_dict contains the required keys defined in the Anderson 13 fuel model constants.

Examples

Example 1: Basic usage

from firebench import svn
fuel_data = {
    svn.FUEL_LOAD_DRY_1H: 0.1,
    svn.FUEL_LOAD_DRY_10H: 0.2,
    svn.FUEL_LOAD_DRY_100H: 0.3,
    svn.FUEL_LOAD_DRY_LIVE: 0.6,
}
add_anderson_dead_fuel_ratio(fuel_data)
print(fuel_data[svn.FUEL_LOAD_DEAD_RATIO])  # Outputs: 0.4
firebench.tools.fuel_models_utils.add_scott_and_burgan_dead_fuel_ratio(fuel_data_dict, overwrite=False)[source]

Calculate and add the dead fuel load ratio to a fuel data dictionary based on the Anderson 13 or Scott and Burgan 40 fuel model.

The dead fuel load ratio represents the fraction of the total fuel load that is attributed to dead fuels. It is calculated as the ratio of the sum of specific dead fuel loads to the sum of all fuel loads (dead and live).

Dead fuel loads considered

  • FUEL_LOAD_DRY_1H

  • FUEL_LOAD_DRY_10H

  • FUEL_LOAD_DRY_100H

Live fuel loads considered

  • FUEL_LOAD_DRY_LIVE_HERB

  • FUEL_LOAD_DRY_LIVE_WOODY

The result is stored under the key FUEL_LOAD_DEAD_RATIO in fuel_data_dict.

Parameters:

  • fuel_data_dict (dict) – Dictionary containing individual fuel load values with specific keys.

  • overwrite (bool, optional) – If True, overwrites the existing dead fuel ratio if it exists. If False and the value already exists, raises a ValueError. Default is False.

Raises:

  • ValueError – If FUEL_LOAD_DEAD_RATIO already exists in fuel_data_dict and overwrite is False.

  • KeyError – If any required individual fuel load keys are missing from fuel_data_dict.

Notes

This function assumes that fuel_data_dict contains the required keys defined in the Anderson 13 or Scott and Burgan 40 fuel model constants.

Examples

Example 1: Basic usage

from firebench import svn
fuel_data = {
    svn.FUEL_LOAD_DRY_1H: 0.1,
    svn.FUEL_LOAD_DRY_10H: 0.2,
    svn.FUEL_LOAD_DRY_100H: 0.3,
    svn.FUEL_LOAD_DRY_LIVE_HERB: 0.4,
    svn.FUEL_LOAD_DRY_LIVE_WOODY: 0.5,
}
add_anderson_dead_fuel_ratio(fuel_data)
print(fuel_data[svn.FUEL_LOAD_DEAD_RATIO])  # Outputs: 0.4
firebench.tools.fuel_models_utils.add_scott_and_burgan_total_fuel_load(fuel_data_dict, overwrite=False)[source]

Add the total dry fuel load to the fuel data dictionary by summing individual dry fuel loads according to the Scott and Burgan 40 fuel model.

The total dry fuel load is calculated as the sum of the following individual fuel loads:

  • FUEL_LOAD_DRY_1H

  • FUEL_LOAD_DRY_10H

  • FUEL_LOAD_DRY_100H

  • FUEL_LOAD_DRY_LIVE_HERB

  • FUEL_LOAD_DRY_LIVE_WOODY

The result is stored under the key FUEL_LOAD_DRY_TOTAL in fuel_data_dict.

Parameters:

  • fuel_data_dict (dict) – Dictionary containing individual fuel load values with specific keys.

  • overwrite (bool, optional) – If True, overwrites the existing total fuel load if it exists. If False and the total fuel load already exists, raises a ValueError. Default is False.

Raises:

  • ValueError – If FUEL_LOAD_DRY_TOTAL already exists in fuel_data_dict and overwrite is False.

  • KeyError – If any required individual fuel load keys are missing from fuel_data_dict.

Notes

This function assumes that fuel_data_dict contains the required keys defined in the Scott and Burgan 40 fuel model constants.

Examples

Example 1: Basic usage

from firebench import svn
fuel_data = {
    svn.FUEL_LOAD_DRY_1H: 0.1,
    svn.FUEL_LOAD_DRY_10H: 0.2,
    svn.FUEL_LOAD_DRY_100H: 0.3,
    svn.FUEL_LOAD_DRY_LIVE_HERB: 0.4,
    svn.FUEL_LOAD_DRY_LIVE_WOODY: 0.5,
}
add_scott_and_burgan_total_fuel_load(fuel_data)
print(fuel_data[svn.FUEL_LOAD_DRY_TOTAL])  # Outputs: 1.5
firebench.tools.fuel_models_utils.add_scott_and_burgan_total_savr(fuel_data_dict, overwrite=False)[source]

Add the total Surface Area to Volume Ratio (SAVR) to the fuel data dictionary by computing the weighted average of individual SAVRs according to the Scott and Burgan 40 fuel model.

The total SAVR is calculated using the weighted average formula:

\[\text{total\_SAVR} = \frac{\sum_i \left( \text{fuel\_load}_i \cdot \text{SAVR}_i \right)}{\sum_i \text{fuel\_load}_i}\]

where:

  • fuel_load_i is the fuel load of the i-th component.

  • SAVR_i is the surface area to volume ratio of the i-th component.

The components considered are:

  • FUEL_LOAD_DRY_1H with FUEL_SURFACE_AREA_VOLUME_RATIO_DEAD_1H

  • FUEL_LOAD_DRY_LIVE_HERB with FUEL_SURFACE_AREA_VOLUME_RATIO_LIVE_HERB

  • FUEL_LOAD_DRY_LIVE_WOODY with FUEL_SURFACE_AREA_VOLUME_RATIO_LIVE_WOODY

The result is stored under the key FUEL_SURFACE_AREA_VOLUME_RATIO in fuel_data_dict.

Parameters:

  • fuel_data_dict (dict) – Dictionary containing individual fuel load and SAVR values with specific keys.

  • overwrite (bool, optional) – If True, overwrites the existing total SAVR if it exists. If False and the total SAVR already exists, raises a ValueError. Default is False.

Raises:

  • ValueError – If FUEL_SURFACE_AREA_VOLUME_RATIO already exists in fuel_data_dict and overwrite is False.

  • KeyError – If any required keys are missing from fuel_data_dict.

Notes

This function assumes that fuel_data_dict contains the required keys defined in the Scott and Burgan 40 fuel model constants.

Examples

Example 1: Compute total SAVR from basic components

from firebench import svn
fuel_data = {
    svn.FUEL_LOAD_DRY_1H: 0.1,
    svn.FUEL_LOAD_DRY_LIVE_HERB: 0.2,
    svn.FUEL_LOAD_DRY_LIVE_WOODY: 0.3,
    svn.FUEL_SURFACE_AREA_VOLUME_RATIO_DEAD_1H: 2000,
    svn.FUEL_SURFACE_AREA_VOLUME_RATIO_LIVE_HERB: 1500,
    svn.FUEL_SURFACE_AREA_VOLUME_RATIO_LIVE_WOODY: 1800,
}
add_scott_and_burgan_total_savr(fuel_data)
print(fuel_data[svn.FUEL_SURFACE_AREA_VOLUME_RATIO])  # Outputs the total SAVR
firebench.tools.fuel_models_utils.find_closest_fuel_class_by_properties(fuel_model_dict: dict[str, Quantity], properties_to_test: dict[str, Quantity], weights: dict[str, float] | None = None) → int[source]

Find the fuel class index that has the closest properties to the given set of properties.

This function compares a set of fuel classes defined in fuel_model_dict with a target set of properties provided in properties_to_test. It calculates a weighted L1 distance between the properties of each fuel class and the target properties, returning the index (1-based) of the fuel class that is closest.

Parameters:

  • fuel_model_dict (dict[str, Quantity]) – A dictionary where each key is a property name and each value is a list of Quantity objects representing that property for each fuel class.

  • properties_to_test (dict[str, Quantity]) – A dictionary where each key is a property name and each value is a Quantity object representing the target value for that property.

  • weights (dict[str, float], optional) – A dictionary of weights for the different properties. Must have the same keys as properties_to_test. If not provided, weights are set to the inverse of the target property values (if non-zero) to balance the error between properties.

Returns:

The one-based index of the fuel class with the closest properties to the target properties.

Return type:

int

Raises:

  • KeyError – If a property key in properties_to_test is not found in fuel_model_dict.

  • ValueError – If units cannot be converted between the fuel model and the properties to test.

firebench.tools.fuel_models_utils.import_anderson_13_fuel_model(add_complementary_fields=True, use_1h_only=False)[source]

Import and return the Anderson 13 fuel model data.

This function reads the Anderson 13 fuel model dataset from a file and returns it as a dictionary. The Anderson 13 fuel models are a standardized set of fuel types widely referenced in fire behavior modeling. Each fuel model in this set characterizes a specific configuration of fuel loads, sizes, and other parameters essential for fire behavior prediction.

The returned dataset includes key-value pairs following a Standard Variable Namespace (SVN) convention, ensuring consistency with other fuel data representations in the codebase.

When add_complementary_fields is True, the following additional fields are computed and included in the returned dictionary: - Dead Fuel Ratio: The fraction of the total fuel load that is attributable to dead fuels stored under svn.FUEL_LOAD_DEAD_RATIO.

Parameters:

  • add_complementary_fields (bool, optional) – If True (default), computes and adds complementary fields to the returned fuel data dictionary. If False, the function returns only the raw fuel data as read from the file.

  • use_1h_only (bool, optional) – If True, use only FUEL_LOAD_DRY_1H for dead fuel load for dead fuel ratio calculation. If False use all dead fuel load keys. Default is False.

Returns:

A dictionary containing the Anderson 13 fuel model data. Keys follow the SVN convention.

Return type:

dict

Raises:

FileNotFoundError – If the Anderson13 data file cannot be found or accessed.

Examples

fuel_data = import_anderson_13_fuel_model()
firebench.tools.fuel_models_utils.import_scott_burgan_40_fuel_model(add_complementary_fields=True)[source]

Import and return the Scott and Burgan 40 fuel model data, with optional complementary computations.

This function serves as a convenient wrapper to read the Scott and Burgan 40 fuel model data from a file and optionally compute additional derived fields. The base dataset contains a set of standard fuel load parameters defined by the Scott and Burgan 40 model. By default, this function also adds complementary fields that summarize or characterize the data, if requested.

When add_complementary_fields is True, the following additional fields are computed and included in the returned dictionary:

  • Total Fuel Load: The sum of all fuel load values (dead and live) stored under svn.FUEL_LOAD_DRY_TOTAL.

  • Total SAVR (Surface-Area-to-Volume Ratio): An aggregated value of surface-area-to-volume ratios for the various fuel classes stored under svn.FUEL_SURFACE_AREA_VOLUME_RATIO.

  • Dead Fuel Ratio: The fraction of the total fuel load that is attributable to dead fuels stored under svn.FUEL_LOAD_DEAD_RATIO.

Parameters:

add_complementary_fields (bool, optional) – If True (default), computes and adds complementary fields (total fuel load, total SAVR, and dead fuel ratio) to the returned fuel data dictionary. If False, the function returns only the raw fuel data as read from the file.

Returns:

A dictionary containing the Scott and Burgan 40 fuel model data with keys following the Standard Variable Namespace (svn) convention. If add_complementary_fields is True, it will also include svn.FUEL_LOAD_DRY_TOTAL, svn.FUEL_SURFACE_AREA_VOLUME_RATIO, and svn.FUEL_LOAD_DEAD_RATIO.

Return type:

dict

Raises:

  • FileNotFoundError – If the “ScottandBurgan40” data file cannot be found.

  • KeyError – If required keys are missing when computing the complementary fields.

Examples

Example 1: Import with complementary fields

from firebench import svn
fuel_data = import_scott_burgan_40()
print(svn.FUEL_LOAD_DRY_TOTAL in fuel_data)  # True
print(svn.FUEL_SURFACE_AREA_VOLUME_RATIO in fuel_data)  # True
print(svn.FUEL_LOAD_DEAD_RATIO in fuel_data)  # True

Example 2: Import raw data without complementary fields

from firebench import svn
raw_fuel_data = import_scott_burgan_40(add_complementary_fields=False)
print(svn.FUEL_LOAD_DRY_TOTAL in raw_fuel_data)  # False
print(svn.FUEL_SURFACE_AREA_VOLUME_RATIO in raw_fuel_data)  # False
print(svn.FUEL_LOAD_DEAD_RATIO in raw_fuel_data)  # False
firebench.tools.fuel_models_utils.import_wudapt_fuel_model()[source]

Import and return the WUDAPT urban fuel model data.

This function reads the Anderson 13 fuel model dataset from a file and returns it as a dictionary. The Anderson 13 fuel models are a standardized set of fuel types widely referenced in fire behavior modeling. Each fuel model in this set characterizes a specific configuration of fuel loads, sizes, and other parameters essential for fire behavior prediction.

The returned dataset includes key-value pairs following a Standard Variable Namespace (SVN) convention, ensuring consistency with other fuel data representations in the codebase.

Returns:

A dictionary containing the Anderson 13 fuel model data. Keys follow the SVN convention.

Return type:

dict

Raises:

FileNotFoundError – If the “Anderson13” data file cannot be found or accessed.

Examples

>>> fuel_data = import_anderson_13_fuel_model()
class firebench.tools.input_info.ParameterType(value)[source]

Bases: Enum

List of parameter types for metadata dictionaries of models in FireBench.

input = 'input'
optional = 'optional'
output = 'output'
firebench.tools.local_db_management.copy_file_to_workflow_record(workflow_record_name: str, file_path: str, overwrite: bool = False)[source]

Copy a file to the specified workflow record directory.

Parameters:

  • workflow_record_name (str) – The name of the workflow record directory where the file will be copied.

  • file_path (str) – The path to the file that needs to be copied.

  • overwrite (bool, optional) – Whether to overwrite the file if it already exists in the destination directory. Defaults to False.

Raises:

  • FileNotFoundError – If the file does not exist.

  • OSError – If the workflow record directory does not exist or if the file already exists and overwrite is False.

firebench.tools.local_db_management.create_record_directory(workflow_record_name: str)[source]

Create a workflow record directory.

This function creates a new directory for storing workflow records. If the directory already exists, it will not raise an error and will simply return. Additionally, it creates a log file named ‘firebench.log’ in the created directory.

Parameters:

workflow_record_name (str) – The name of the directory to be created.

firebench.tools.local_db_management.generate_file_path_in_record(new_file_name: str, record_name: str, overwrite: bool = False) → str[source]

Get the file path for a new file in the specified workflow record directory.

Parameters:

  • new_file_name (str) – The name of the new file to be created.

  • record_name (str) – The name of the workflow record directory where the file will be located.

  • overwrite (bool, optional) – Whether to overwrite the file if it already exists. Defaults to False.

Returns:

The full path to the new file in the workflow record directory.

Return type:

str

Raises:

OSError – If the file already exists and overwrite is set to False.

firebench.tools.local_db_management.get_file_path_in_record(file_name: str, record_name: str) → str[source]

Get the file path for an existing file in the specified workflow record directory.

Parameters:

  • file_name (str) – The name of the existing file.

  • record_name (str) – The name of the workflow record directory where the file will be located.

Returns:

The full path to the file in the workflow record directory.

Return type:

str

Raises:

OSError – If the file does not exist.

firebench.tools.local_db_management.get_local_db_path()[source]

Retrieve the local database path from the environment variable FIREBENCH_LOCAL_DB.

This function checks for the presence of the environment variable FIREBENCH_LOCAL_DB, which should contain the path to the local FireBench database. If the environment variable is not set, an exception is raised with a message instructing the user to set the variable.

Returns:

The path to the local FireBench database.

Return type:

str

Raises:

EnvironmentError – If the FIREBENCH_LOCAL_DB environment variable is not set.

firebench.tools.local_db_management.update_date_in_markdown(markdown_path, date)[source]

Updates the “Date of record creation” line in the markdown file with the given date.

Parameters:

markdown_pathstr

Path to the markdown file to be updated.

datestr

The date string to add to the line.

firebench.tools.local_db_management.update_markdown_with_hashes(markdown_path, hash_dict)[source]

Updates the ‘firebench-hash-list’ section of a markdown file with file names and their hashes.

Parameters:

markdown_pathstr

Path to the markdown file to be updated.

hash_dictdict

Dictionary where keys are filenames and values are their hashes.

firebench.tools.logging_config.create_file_handler(log_path: str, level=30)[source]

Create a file handler for logging.

Parameters:

log_path (str) – The path to the log file.

firebench.tools.logging_config.set_logging_level(level)[source]

Set the logging level for both the logger and all its handlers.

Parameters:

level (int) – The logging level to set (e.g., logging.DEBUG, logging.INFO).

class firebench.tools.namespace.StandardVariableNames(value)[source]

Bases: Enum

Enum class for standard variable names used in the firebench project.

This enumeration defines standard names for various physical and model variables related to fire modeling. These names are used to ensure consistency and clarity across the codebase and related data files.

AIR_DENSITY = 'air_density'
AIR_TEMPERATURE = 'air_temperature'
ALPHA = 'alpha'
BETA = 'beta'
BUILDING_LENGTH_SEPARATION = 'building_length_separation'
BUILDING_LENGTH_SIDE = 'building_length_side'
BUILDING_RATIO_FIRE_RESISTANT = 'building_ratio_fire_resistant'
BUILDING_RATIO_STRUCTURE_WOOD_BARE = 'building_ratio_structure_wood_bare'
BUILDING_RATIO_STRUCTURE_WOOD_MORTAR = 'building_ratio_structure_wood_mortar'
CANOPY_DENSITY_BULK = 'canopy_density_bulk'
CANOPY_HEIGHT_BOTTOM = 'canopy_height_bottom'
CANOPY_HEIGHT_TOP = 'canopy_height_top'
DIRECTION = 'direction'
FIRE_ARRIVAL_TIME = 'fire_arrival_time'
FUEL_CHAPARRAL_FLAG = 'fuel_chaparral_flag'
FUEL_CLASS = 'fuel_class'
FUEL_COVER = 'fuel_cover'
FUEL_DENSITY = 'fuel_density'
FUEL_DENSITY_BULK = 'fuel_density_bulk'
FUEL_DENSITY_DEAD = 'fuel_density_dead'
FUEL_DENSITY_LIVE = 'fuel_density_live'
FUEL_FRACTION_CONSUMED_FLAME_ZONE = 'fuel_fraction_consumed_flame_zone'
FUEL_HEAT_CONTENT = 'fuel_heat_content'
FUEL_HEIGHT = 'fuel_height'
FUEL_LOAD_DEAD_RATIO = 'fuel_load_dead_ratio'
FUEL_LOAD_DRY_1000H = 'fuel_load_dry_1000h'
FUEL_LOAD_DRY_100H = 'fuel_load_dry_100h'
FUEL_LOAD_DRY_10H = 'fuel_load_dry_10h'
FUEL_LOAD_DRY_1H = 'fuel_load_dry_1h'
FUEL_LOAD_DRY_LIVE = 'fuel_load_dry_live'
FUEL_LOAD_DRY_LIVE_HERB = 'fuel_load_dry_live_herb'
FUEL_LOAD_DRY_LIVE_WOODY = 'fuel_load_dry_live_woody'
FUEL_LOAD_DRY_TOTAL = 'fuel_load_dry_total'
FUEL_LOAD_FINE = 'fuel_load_fine'
FUEL_LOAD_FINE_DEAD = 'fuel_load_fine_dead'
FUEL_LOAD_FINE_LIVE = 'fuel_load_fine_live'
FUEL_MINERAL_CONTENT_EFFECTIVE = 'fuel_mineral_content_effective'
FUEL_MINERAL_CONTENT_TOTAL = 'fuel_mineral_content_total'
FUEL_MOISTURE_CONTENT = 'fuel_moisture_content'
FUEL_MOISTURE_CONTENT_1000H = 'fuel_moisture_content_1000h'
FUEL_MOISTURE_CONTENT_100H = 'fuel_moisture_content_100h'
FUEL_MOISTURE_CONTENT_10H = 'fuel_moisture_content_10h'
FUEL_MOISTURE_CONTENT_1H = 'fuel_moisture_content_1h'
FUEL_MOISTURE_CONTENT_DEAD = 'fuel_moisture_content_dead'
FUEL_MOISTURE_CONTENT_ELEVATED_DEAD = 'fuel_moisture_content_elevated_dead'
FUEL_MOISTURE_CONTENT_FINE_DEAD = 'fuel_moisture_content_fine_dead'
FUEL_MOISTURE_CONTENT_LIVE = 'fuel_moisture_content_live'
FUEL_MOISTURE_EXTINCTION = 'fuel_moisture_extinction'
FUEL_ROUGHNESS_HEIGHT = 'fuel_roughness_height'
FUEL_SFIREBURNUP_CONSUMPTION_CST = 'fuel_sfireburnup_consumption_cst'
FUEL_SURFACE_AREA_VOLUME_RATIO = 'fuel_surface_area_volume_ratio'
FUEL_SURFACE_AREA_VOLUME_RATIO_DEAD = 'fuel_surface_area_volume_ratio_dead'
FUEL_SURFACE_AREA_VOLUME_RATIO_DEAD_1H = 'fuel_surface_area_volume_ratio_dead_1h'
FUEL_SURFACE_AREA_VOLUME_RATIO_LIVE = 'fuel_surface_area_volume_ratio_live'
FUEL_SURFACE_AREA_VOLUME_RATIO_LIVE_HERB = 'fuel_surface_area_volume_ratio_live_herb'
FUEL_SURFACE_AREA_VOLUME_RATIO_LIVE_WOODY = 'fuel_surface_area_volume_ratio_live_woody'
FUEL_TEMPERATURE_IGNITION = 'fuel_temperature_ignition'
FUEL_THERMAL_CONDUCTIVITY = 'fuel_thermal_conductivity'
FUEL_TREE_CLASS = 'fuel_tree_class'
FUEL_WIND_HEIGHT = 'fuel_wind_height'
FUEL_WIND_REDUCTION_FACTOR = 'fuel_wind_reduction_factor'
IGNITION_LENGTH = 'ignition_length'
LATITUDE = 'latitude'
LENGTH = 'length'
LONGITUDE = 'longitude'
MAGNITUDE = 'magnitude'
NORMAL_SPREAD_DIR_X = 'normal_spread_dir_x'
NORMAL_SPREAD_DIR_Y = 'normal_spread_dir_y'
RATE_OF_SPREAD = 'rate_of_spread'
RELATIVE_HUMIDITY = 'relative_humidity'
SLOPE_ANGLE = 'slope_angle'
TEMPERATURE = 'temperature'
TIME = 'time'
WIND_DIRECTION = 'wind_direction'
WIND_SPEED = 'wind_speed'
WIND_SPEED_U = 'wind_speed_u'
WIND_SPEED_V = 'wind_speed_v'
WIND_SPEED_W = 'wind_speed_w'
X = 'x'
Y = 'y'
Z = 'z'
firebench.tools.raster_to_perimeters.array_to_geopolygons(field: ndarray, lon: ndarray, lat: ndarray, iso_value: float, original_crs: str | dict = 'EPSG:4326', smooth_sigma: float = 0) → GeoDataFrame[source]

Convert an array field into geospatial polygons at a given iso-value, preserving holes.

Parameters:

  • field (np.ndarray) – 2D array of physical values (e.g., level-set or arrival time).

  • lon (np.ndarray) – 2D array of longitudes matching field.

  • lat (np.ndarray) – 2D array of latitudes matching field.

  • iso_value (float) – Value at which to extract the contour.

  • original_crs (str or dict, optional) – CRS of the input coordinate grid. If not specified, defaults to “EPSG:4326” (WGS84), which is suitable for most WRF output over the continental United States and supports area-preserving polygon construction.

  • smooth_sigma (float, optional) – Standard deviation for optional Gaussian smoothing.

Returns:

GeoDataFrame with valid polygons (including holes) representing the iso-contour.

Return type:

geopandas.GeoDataFrame

firebench.tools.read_data.get_firebench_data_directory()[source]

Retrieve the absolute path of the firebench data directory.

This function checks for the environment variable ‘FIREBENCH_DATA_PATH’ to retrieve the path of the firebench data directory. If the environment variable is not set, it raises an EnvironmentError with a message indicating the need to define the path.

Returns:

The absolute path of the firebench data directory.

Return type:

str

Raises:

EnvironmentError – If the ‘FIREBENCH_DATA_PATH’ environment variable is not set.

firebench.tools.read_data.read_data_file(dataset_name: str, path_within_firebench: str, local_json_path: str | None = None)[source]

Reads a CSV data file and its corresponding metadata JSON file to produce a dictionary of data with Pint quantities.

Parameters:

  • dataset_name (str) – The name of the dataset to retrieve.

  • path_within_firebench (str) – Path leading to the data within firebench from the data directory.

  • local_json_path (str, optional) – The local path to the JSON fuel database. If not provided, the function will use the default package path.

Returns:

A dictionary where the keys are standard variable names (Enum members) and the values are numpy arrays with Pint quantities.

Return type:

dict

Raises:

ValueError – If there is an issue with the variable name in the metadata.

firebench.tools.read_data.read_fuel_data_file(fuel_model_name: str, local_path_json_fuel_db: str | None = None)[source]

Reads a CSV fuel data file and its corresponding metadata JSON file to produce a dictionary of data with Pint quantities.

Parameters:

  • fuel_model_name (str) – The name of the fuel model.

  • local_path_json_fuel_db (str, optional) – The local path to the JSON fuel database. If not provided, the function will use the default package path.

Returns:

A dictionary where the keys are standard variable names (Enum members) and the values are numpy arrays with Pint quantities.

Return type:

dict

Raises:

ValueError – If there is an issue with the variable name in the metadata.

firebench.tools.sensitivity_doe.merge_dictionaries(dict1: dict, dict2: dict, prefer: int = 0) → dict[source]

Merge two dictionaries, resolving key conflicts by favoring one dictionary.

Parameters:

  • dict1 (dict) – The first dictionary.

  • dict2 (dict) – The second dictionary.

  • prefer (int, optional) – Which dictionary to prefer in case of key conflict (0: raise error if conflicts, 1:’dict1’ or 2:’dict2’). Default is 0.

Returns:

The merged dictionary with conflicts resolved based on the ‘prefer’ setting.

Return type:

dict

Raises:

KeyError – If there is a key conflict between the dictionaries and prefer is set to 0.

firebench.tools.sensitivity_doe.sobol_seq(N: int, variables_info: dict, scramble: bool = True, seed: int = 0)[source]

Generate a Sobol sequence for the given variables with specified units and ranges.

This function generates a Sobol sequence and scales it to the ranges specified for each variable. The result is a dictionary where each variable’s values are given as a pint.Quantity with the appropriate unit.

Parameters:

  • N (int) – The number of points in the Sobol sequence.

  • variables_info (dict) – A dictionary where each key is the name of a variable, and the value is a dictionary containing a pint.Unit (key: unit) and a list of two floats representing the range of the variable (key: range).

  • scramble (bool, optional) – If True, applies scrambling to the Sobol sequence for better uniformity. Defaults to True.

  • seed (int, optional) – Seed for the random number generator for reproducibility. Defaults to 0.

Returns:

  • dict – A dictionary where each key is a variable name, and the value is a pint.Quantity array with the specified unit and range.

  • sobol_problem (dict) – A dictionary defining the Sobol problem with keys ‘num_vars’, ‘names’, and ‘bounds’.

  • N_sobol (int) – The number of points in the generated Sobol sequence.

firebench.tools.utils.calculate_sha256(file_path)[source]

Calculate the SHA-256 hash of a file’s contents.

Parameters:

file_pathstr

The path to the file for which the SHA-256 hash is to be calculated.

Returns:

str

The SHA-256 hash as a hexadecimal string if the file is successfully processed, and an empty string if not.

firebench.tools.utils.get_value_by_category(x: any, category_index: int)[source]

Retrieve a value from x based on the specified category index.

Parameters:

  • x (scalar or array-like) – The input value, which can be a scalar or an array-like object (e.g., list, NumPy array, or pint.Quantity).

  • category_index (int) – The one-based category index to select from x if x is array-like. If x is scalar, this parameter is ignored.

Returns:

The scalar value from x: either x itself if scalar, or x[category_index - 1] if array-like.

Return type:

value

Raises:

  • ValueError – If category_index is less than 1.

  • IndexError – If category_index is out of bounds for x.

Notes

  • If x is scalar, category_index is ignored.

  • The category_index is one-based; to select the first element, use category_index=1.

firebench.tools.utils.is_scalar_quantity(x: any)[source]

Determine if the input is a scalar or a pint.Quantity with a scalar magnitude.

Parameters:

x (Any) – The value to check. Can be a scalar, array-like, or a pint.Quantity object.

Returns:

True if the input or its magnitude is scalar, False otherwise.

Return type:

bool

Rate of Spread Base Class

class firebench.tools.rate_of_spread_model.RateOfSpreadModel[source]

Bases: object

A base class for fire spread rate models.

This class provides common functionalities and attributes for different fire spread rate models.

Metadata

The metadata dictionary defines the required fuel parameters for the model.

Each key in the dictionary represents a model variable (e.g., side_length, wind_u, etc.). Each value is a dictionary with:

  • std_name: standardized variable name (used in input dicts)

  • units: pint-compatible physical units

  • range: a (min, max) tuple indicating valid value range

  • type: input, output, or optional

  • default (optional): default value, used only if type == optional

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

Compute the rate of spread of fire using the specific model.

This method should be overridden by subclasses.

Parameters:

  • input_dict (dict[str, float | int | list[float] | list[int]]) – Dictionary containing the input data for various fuel properties.

  • Parameters (Optional)

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

  • **opt (dict) – Optional parameters for the fire spread rate model.

Returns:

The computed rate of spread of fire [m/s].

Return type:

float

static compute_ros_with_units(input_dict: dict[str, float | int | list[float] | list[int]], **opt) → float[source]

Compute the rate of spread of fire using the specific model.

This function handles unit dictionary with pint.Quantity objects and return a pint.Quantity object with the model output unit.

This method should be overridden by subclasses.

Parameters:

  • input_dict (dict[str, float | int | list[float] | list[int]]) – Dictionary containing the input data for various fuel properties.

  • Parameters (Optional)

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

  • **opt (dict) – Optional parameters for the fire spread rate model.

Returns:

The computed rate of spread of fire.

Return type:

pint.Quantity

metadata = {}
static prepare_fuel_properties(input_dict, metadata, fuel_cat: int = 0)[source]

Prepare the fuel properties dictionary for the rate of spread computation.

Parameters:

  • input_dict (dict) – Dictionary containing the input data for various fuel properties.

  • metadata (dict) – Dictionary containing metadata for the variables (e.g., std_name, default values).

  • fuel_cat (int, optional) – The fuel category index (one-based). If provided, the function will extract the property of the specified fuel category.

Returns:

The fuel properties dictionary prepared for the rate of spread computation.

Return type:

dict