pyrolib.fuelmap package

Submodules

pyrolib.fuelmap.fuel_database module

Fuel Database utilities

class pyrolib.fuelmap.fuel_database.FuelDatabase

Bases: object

dump_database(filename, info, compact=True)

save the current fuel database in a yml file.

Parameters:

• filename (str) – name of the database (database.yml)

• info (str) – information about the database

• compact (bool, optional) – writting format. Defaults to True.

load_fuel_database(filename)

load a fuel database in the current fuel database

The database can be search in the package data/fuel_database or locally

Parameters:

filename (str) – name of the database (database.yml)

pyrolib.fuelmap.fuelmap module

FuelMap file building tools

class pyrolib.fuelmap.fuelmap.FuelMap(fuel_db: FuelDatabase, namelistname: str = 'EXSEG1.nam', MesoNHversion: str = '5.6.0', workdir: str = '')

Bases: object

Class for fuel map construction

This FuelMap class allows to create a fuel map object and save it to netcdf format to be an input for a MesoNH-Blaze simulation.

In order to build a fuel map the following file tree is needed:

my_project/
├─ create_my_fuelmap.py
├─ EXSEG1.nam
├─ inifile_MesoNH.des
├─ inifile_MesoNH.nc

The MesoNH namelist EXSEG1.nam is used to retrieved information about fire mesh, fire rate of spread parameterization and MesoNH initialization files. The initialization file (here inifile_MesoNH.nc) is used to get atmopsheric mesh information. The MesoNH file inifile_MesoNH.des will be duplicated to FuelMap.des in order to match MesoNH file reader requirements.

After having set all patches and data treatments to the FuelMap.fuelmaparray, the write() method can be called to save the file FuelMap.nc. After this operation, the project folder should be:

my_project/
├─ create_my_fuelmap.py
├─ EXSEG1.nam
├─ FuelMap.des
├─ FuelMap.nc
├─ FuelMap2d.nc
├─ inifile_MesoNH.des
├─ inifile_MesoNH.nc

The file FuelMap2d.nc is optionnaly created through the write() method. It contains the same information that FuelMap.nc but conserves the 2d format of data to be more readable for error checking. It is recommended to use this file to check your set up.

Parameters:

• fuel_db (pyrolib.FuelDatabase) – fuel database containing fuel data.

• namelistname (str, optional) – MesoNH namelist name (default: ‘EXSEG1.nam’).

• MesoNHversion (str, optional) – Version of MesoNH needed (>=5.6.0) (default: ‘5.6.0’)

add_fuel_line_patch(pos1: tuple, pos2: tuple, fuel_key: str, is_cartesian: bool = True)

Add line patch between (pos1[0], pos2[0]) and (pos1[1], pos2[1]).

This method first sets the mask corresponding to the following scheme, then assigns the needed data in the appropriated array.

It assigns a fuel type in the masked area through its index. The fuel assigned depends on its index and the selected rate of spread parameterization.

The mask is determined by a bresenham algorithm.

Parameters:

• pos1 (tuple) – Position of west and east boundaries of the patch

• pos2 (tuple) – Position of south and north boundaries of the patch

• fuel_key (str) – Key of Fuel in fuel database to place in the patch

• is_cartesian (bool, optional) – pos1 and pos2 are given with (x, y) instead of (lon, lat) (default: True)

add_fuel_rectangle_patch(pos1: tuple, pos2: tuple, fuel_key: str, is_cartesian: bool = True)

Add rectangle fuel patch between (pos1[0], pos2[0]) and (pos1[1], pos2[1]).

This method first sets the mask corresponding to the following scheme, then assigns the needed data in the appropriated array.

It assigns a fuel type in the masked area through its index. The fuel assigned depends on its index and the selected rate of spread parameterization in the Méso-NH namelist.

Parameters:

• pos1 (tuple) – Position of west and east boundaries of the patch

• pos2 (tuple) – Position of south and north boundaries of the patch

• fuel_key (str) – key of Fuel in fuel database to place in the patch

• is_cartesian (bool, optional) – pos1 and pos2 are given with (x, y) instead of (lon, lat) (default: True)

add_ignition_line_patch(pos1: tuple, pos2: tuple, ignition_time: float, is_cartesian: bool = True)

Add line patch between (pos1[0], pos2[0]) and (pos1[1], pos2[1]).

This method first sets the mask corresponding to the following scheme, then assigns the needed data in the appropriated array.

It specifies an ignition time for the whole patch.

The mask is determined by a bresenham algorithm.

Parameters:

• pos1 (tuple) – Position of west and east boundaries of the patch

• pos2 (tuple) – Position of south and north boundaries of the patch

• ignition_time (float) – Ignition time of patch

• is_cartesian (bool, optional) – pos1 and pos2 are given with (x, y) instead of (lon, lat) (default: True)

add_ignition_rectangle_patch(pos1: tuple, pos2: tuple, ignition_time: float, is_cartesian: bool = True)

Add rectangle patch between (pos1[0], pos2[0]) and (pos1[1], pos2[1]).

This method first sets the mask corresponding to the following scheme, then assigns the needed data in the appropriated array.

It specifies an ignition time for the whole patch.

Parameters:

• pos1 (tuple) – Position of west and east boundaries of the patch

• pos2 (tuple) – Position of south and north boundaries of the patch

• ignition_time (float) – Ignition time of patch

• is_cartesian (bool, optional) – pos1 and pos2 are given with (x, y) instead of (lon, lat) (default: True)

add_unburnable_line_patch(pos1: tuple, pos2: tuple, is_cartesian: bool = True)

Add line patch between (pos1[0], pos2[0]) and (pos1[1], pos2[1]).

This method first sets the mask corresponding to the following scheme, then assigns the needed data in the appropriated array.

It Specifies that the patch can not burn (ROS = 0 m s-1 in that area).

The mask is determined by a bresenham algorithm.

Parameters:

• pos1 (tuple) – Position of west and east boundaries of the patch

• pos2 (tuple) – Position of south and north boundaries of the patch

• is_cartesian (bool, optional) – pos1 and pos2 are given with (x, y) instead of (lon, lat) (default: True)

add_unburnable_rectangle_patch(pos1: tuple, pos2: tuple, is_cartesian: bool = True)

Add rectangle unburnable patch between (pos1[0], pos2[0]) and (pos1[1], pos2[1]).

This method first sets the mask corresponding to the following scheme, then assigns the needed data in the appropriated array.

It specifies that the patch can not burn (ROS = 0 m s-1 in that area).

Parameters:

• pos1 (tuple) – Position of west and east boundaries of the patch

• pos2 (tuple) – Position of south and north boundaries of the patch

• is_cartesian (bool, optional) – pos1 and pos2 are given with (x, y) instead of (lon, lat) (default: True)

add_walking_ignition_line_patch(pos1: tuple, pos2: tuple, walking_ignition_times: list, is_cartesian: bool = True)

Add line patch between (pos1[0], pos2[0]) and (pos1[1], pos2[1]).

This method first sets the mask corresponding to the following scheme, then assigns the needed data in the appropriated array.

It specifies an ignition time t_a for point A (x0, y0)

and t_b for point B (x1, y1) where t_b > t_a.

The mask is determined by a bresenham algorithm.

Parameters:

• pos1 (tuple) – Position of west and east boundaries of the patch

• pos2 (tuple) – Position of south and north boundaries of the patch

• walking_ignition_times (list) – Ignition times of points A and B of the ignition line, respectively

• is_cartesian (bool, optional) – pos1 and pos2 are given with (x, y) instead of (lon, lat) (default: True)

dump(verbose: int = 0)

Write 2D Fuel map as netCFD file named FuelMap2d.nc

Parameters:

verbose (int, optional) – verbose level (0: no prints, 1: low verbosity, 2: high verbosity) (default: 0)

dump_mesonh(verbose: int = 0)

Write Fuel map as netCFD file named FuelMap.nc for Méso-NH

Parameters:

verbose (int, optional) – verbose level (0: no prints, 1: low verbosity, 2: high verbosity) (default: 0)

pyrolib.fuelmap.fuels module

Fuel classes

class pyrolib.fuelmap.fuels.BalbiFuel(**opts)

Bases: BaseFuel

Class of fuel for Balbi rate of spread model [1].

New fuel class is set with default value. Any fuel property can be passed explicitely to the constructor to set a different vaklue than the default one.

Parameters:

• rhod (float, optional) – Dead fuel density (default: 400 kg m-3)

• rhol (float, optional) – Living fuel density (default: 400 kg m-3)

• Md (float, optional) – Dead fuel moisture (default: 0.1 -)

• Ml (float, optional) – Living fuel moisture (default: 1.0 -)

• sd (float, optional) – Dead SAV ratio (default: 5000 m-1)

• sl (float, optional) – Living SAV ratio (default: 5000 m-1)

• e (float, optional) – Fuel height (default: 1.0 m)

• sigmad (float, optional) – Dead fuel load (default: 0.95 kg m-2)

• sigmal (float, optional) – Living fuel load (default: 0.05 kg m-2)

• Ti (float, optional) – Ignition temperature (default: 500 K)

• Ta (float, optional) – Air temperature (default: 300 K)

• DeltaH (float, optional) – Combustion enthalpy (default: 15.43 MJ kg-1)

• cp (float, optional) – Fuel calorific capacity (default: 1912 J K-1 kg-1)

• Deltah (float, optional) – Water evaporation enthalpy (default: 2.3 MJ kg-1)

• tau0 (float, optional) – Model constant (default: 75590 s m-1)

• rhoa (float, optional) – Air density (default: 1.2 kg m-3)

• X0 (float, optional) – Fraction of radiant energy (default: 0.3 -)

• r00 (float, optional) – Model constant (default: 2.5e-5 -)

• LAI (float, optional) – Leaf Area Index (default: 4 -)

• cpa (float, optional) – Air calorific capacity (default: 1004 J K-1 kg-1)

• stoch (float, optional) – Stochiometry (default: 8.3 -)

• wind (float, optional) – Wind at mid-flame (default 0 m s-1)

• slope (float, optional) – Slope (default: 0 deg)

References

[1] (1,2)

Santoni, P. A., Filippi, J. B., Balbi, J. H., & Bosseur, F. (2011). Wildland fire behaviour case studies and fuel models for landscape-scale fire modeling. Journal of Combustion, 2011. https://doi.org/10.1155/2011/613424

Examples

>>> import pyrolib.fuels as pyf
>>> # create a new fuel class with default value.
>>> F1 = pyf.BalbiFuel()
>>> # create a new fuel class with default value
>>> # except for `e` and `Md` where a new value is set.
>>> F2 = pyf.BalbiFuel(e=2, Md=0.1)

copy(**opts)

Copy fuel class to a new fuel class object.

Parameters:

**opts (optional) – Any valid property can be passed to change its value for the new object

Return type:

NewFuel as BalbiFuel

Examples

>>> import pyrolib.fuels as pyf
>>> # create a new fuel class with default value.
>>> F1 = pyf.BalbiFuel()
>>> # copy the fuel class with default value
>>> # except for `e` and `Md` where a new value is set.
>>> F2 = F1.copy(e=2, Md=0.1)

getR()

Compute rate of spread according to Balbi’s parameterization ([1], [2]).

Returns:

R – rate of spread for current fuel properties.

Return type:

float

References

[2]

Costes, A., Rochoux, M. C., Lac, C., & Masson, V. (2021). Subgrid-scale fire front reconstruction for ensemble coupled atmosphere-fire simulations of the FireFlux I experiment. Fire Safety Journal, 126, 103475. https://doi.org/10.1016/j.firesaf.2021.103475

class pyrolib.fuelmap.fuels.BaseFuel

Bases: ABC

Asbtract class for fuel classes.

A fuel class contains every fuel property of a given fuel type. These properties can depend on the rate of spread parameterization used. Therefore, the properties are locally defined for each fuel class type (Balbi, Rothermel, …). The rate of spread corresponding the the physical properties and numerical parameters of the model can be directly computed in the class by getR(). This method is redefined for each fuel class type.

abstract copy()

Copy current fuel class.

It is possible to change any property of the new fuel class.

Raises:

NotImplementedError – if not defined in the inherited fuel class.

copy_from_sequence(sequence, index)

Copy fuel with changes from given sequence containing properties ensemble.

sequence is pandas.DataFrame array with each column corresponding to a property value.

The column name shall be the property name.

Parameters:

• sequence (pandas.DataFrame) –

  Sequence of properties to modify in the new fuel class.

  Each column must correspond to a property of the fuel class.

• index (int) – Index in sequence to use.

Returns:

NewFuel – New FuelClass with modified properties according to sequence.

Return type:

same FuelClass as self

abstract getR()

Compute rate of spread for current fuel.

Raises:

NotImplementedError – if not defined in the inherited fuel class.

get_property_vector(fuelindex, nbofproperties)

Construct the array of fuel properties value.

The fuel index is an identifier of the fuel, the following content is the value of each fuel property. Corresponding index in the array is the propertyindex of the FuelProperty.

Parameters:

• fuelindex (int) – Index of fuel to store

• nbofproperties (int) – number

Returns:

out – array of [fuel index, *properties_value]

Return type:

numpy.ndarray

minimal_dict(compact: bool)

Construct the minimal dictionnary of the class.

The minimal dictionnay contains the class name (key: class) and the dictionnary of minimal dictionnaries of each FuelProperty attributes (key: properties). If compact is True then the dictionnary of FuelProperty attributes value are stored instead of minimal dicctionnaries.

Parameters:

compact (bool) – If True, return

Returns:

out – class name and minimal dictionnaries of class FuelProperty attributes.

Return type:

dict

class pyrolib.fuelmap.fuels.FuelProperty(name, value, unit, description, propertyindex=None)

Bases: object

Represents a property for a fuel.

Store property name, description and value.

name

Short name of the property.

Type:

str

value

Value of the property.

Type:

float

unit

Unit of the property in SI (International System of Units).

Type:

str

description

Short description of the property.

Type:

str

propertyindex

Index of the property in fuel type class to be correctly read in MesoNH, default is None. If the propertyindex is None, the property will not be stored in FuelMap file.

Note

It needs to be compliant with the current version of Blaze.

Type:

int, optional

minimal_dict()

Construct the minimal dictionnary of the class.

The minimal dictionnay contains the value, the unit and the descrition of the class.

Returns:

out – dictionnary of value, unit and description

Return type:

dict

set(value)

Set value of the property

Parameters:

value (float) – new value of the property

pyrolib.fuelmap.fuels.show_fuel_classes(show_fuel_properties=True)

Print fuel classes available in pyrolib and default parameters values

pyrolib.fuelmap.patch module

Patch classes

class pyrolib.fuelmap.patch.DataPatch(fuelmaparray)

Bases: ABC

Asbtract class for data patch to build fuel map

Parameters:

fuelmaparray (numpy.ndarray) – Array of acual fuel data (fuel_dim, nyf, nxf)

abstract getmask()

class pyrolib.fuelmap.patch.LinePatch(FuelMapArray, xpos, ypos, xfiremesh, yfiremesh, XFIREMESHSIZE)

Bases: DataPatch

Class of a rectangle patch of data for fuel map construction

Parameters:

• fuelmaparray (numpy.ndarray) – Array of acual fuel data (fuel_dim, nyf, nxf)

• xpos (tuple) – Position on x axis of boundary points (x0, x1)

• ypos (tuple) – Position on y axis of boundary points (y0, y1)

• xfiremesh (numpy.ndarray) – Fire mesh on x direction (nxf)

• yfiremesh (numpy.ndarray) – Fire mesh on y direction (nyf)

• XFIREMESHSIZE (numpy.ndarray) – Array of fire mesh sizes : [dxf, dyf]

getmask(xfiremesh, yfiremesh, XFIREMESHSIZE)

Compute mask for rectangle patch

Use breseham algorithm to find all point on fire grid between points A (x0, y0) and B (x1, y1).

Parameters:

• xfiremesh (numpy.ndarray) – Fire mesh on x direction (nxf)

• yfiremesh (numpy.ndarray) – Fire mesh on y direction (nyf)

• XFIREMESHSIZE (numpy.ndarray) – Array of fire mesh sizes : [dxf, dyf]

class pyrolib.fuelmap.patch.RectanglePatch(fuelmaparray, xpos, ypos, xfiremesh, yfiremesh, XFIREMESHSIZE)

Bases: DataPatch

Class of a rectangle patch of data for fuel map construction

Parameters:

• fuelmaparray (numpy.ndarray) – Array of acual fuel data (fuel_dim, nyf, nxf)

• xpos (tuple) – Position on x axis of rectangle corners (x0, x1)

• ypos (tuple) – Position on y axis of rectangle corners (y0, y1)

• xfiremesh (numpy.ndarray) – Fire mesh on x direction (nxf)

• yfiremesh (numpy.ndarray) – Fire mesh on y direction (nyf)

• XFIREMESHSIZE (numpy.ndarray) – Array of fire mesh sizes : [dxf, dyf]

getmask(xfiremesh, yfiremesh, XFIREMESHSIZE)

Compute mask for rectangle patch

Parameters:

• xfiremesh (numpy.ndarray) – Fire mesh on x direction (nxf)

• yfiremesh (numpy.ndarray) – Fire mesh on y direction (nyf)

• XFIREMESHSIZE (numpy.ndarray) – Array of fire mesh sizes : [dxf, dyf]

pyrolib.fuelmap.utility module

FuelMap utility tools

pyrolib.fuelmap.utility.convert_lon_lat_to_x_y(confproj: dict, lat: tuple, lon: tuple)

Convert a point (lon, lat) into (x,y)

Parameters:

• confproj – dict conformal projection parameters

• lat – tuple latitude position (deg)

• lon – tuple longitude position (deg)

pyrolib.fuelmap.utility.cosd(degrees)

pyrolib.fuelmap.utility.fill_fuel_array_from_patch(fuelarray, patchmask, propertyvector, np, nx, ny)

Fill fuel array considering a mask

Parameters:

• fuelarray (numpy.ndarray) – Array to modify according to propertyvector and patchmask.

• patchmask (numpy.ndarray) – Mask array.

• propertyvector (numpy.ndarray) – Vector of properties to fill in the fuel array.

• np (int) – Property vector size

• nx (int) – Fire mesh size on x axis

• ny (int) – Fire mesh size on y axis

Returns:

fuelarray – Modified array according to propertyvector and patchmask.

Return type:

numpy.ndarray

pyrolib.fuelmap.utility.fire_array_2d_to_3d(firearray2d, nx, ny, gammax, gammay)

Reshape 2d fire array into 3d fire array readable by MesoNH

Parameters:

• firearray2d (numpy.ndarray) – 2d array to reshape

• nx (int) – Fire mesh size on x axis

• ny (int) – Fire mesh size on y axis

• gammax (int) – Fire mesh refinement on x axis

• gammay (int) – Fire mesh refinement on x axis

Returns:

firearray3d – Reshaped 3d array

Return type:

numpy.ndarray

pyrolib.fuelmap.utility.fire_array_3d_to_2d(firearray3d, nx, ny, gammax, gammay)

Reshape 3d fire array readable by MesoNH to 2d fire array

Parameters:

• firearray3d (numpy.ndarray) – 3d array to reshape

• nx (int) – Fire mesh size on x axis

• ny (int) – Fire mesh size on y axis

• gammax (int) – Fire mesh refinement on x axis

• gammay (int) – Fire mesh refinement on x axis

Returns:

firearray2d – Reshaped 2d array

Return type:

numpy.ndarray

pyrolib.fuelmap.utility.njit_wrapper(function)

pyrolib.fuelmap.utility.sind(degrees)