Reference

duet_tools.calibration

DUET Tools Calibration module

DuetRun

Class containing all arrays for a DUET run.

Attributes:

Name	Type	Description
loading	ndarray	3D Array of fuel loading (bulk density in kg/m^3) values in the format exported by DUET: Grass fuel load in first layer, litter fuel load for each tree species in subsequent layers.
moisture	ndarray	3D Array of fuel moisture content (%) values in the format exported by DUET: Grass moisture content in first layer, litter moisture content for each tree species in subsequent layers.
depth	ndarray	3D Array of fuelbd depth (m) values in the format exported by DUET: Grass height in first layer, litter depth for each tree species in subsequent layers.
duet_version	str	DUET version. Must be one of "v1" or "v2".

to_quicfire

to_quicfire(
    directory: str | Path,
    loading: bool = True,
    moisture: bool = True,
    depth: bool = True,
    overwrite: bool = False,
) -> None

Writes a DuetRun object to QUIC-fire fuel .dat inputs to a directory: treesrhof.dat, treesmoist.dat, treesfueldepth.dat

Parameters:

Name	Type	Description	Default
directory	str | Path	Path to directory for writing QUIC-fire files	required
loading	bool	Whether to export the fuel loading array. Defaults to True.	True
moisture	bool	Whether to export the moisture content array. Defaults to True.	True
depth	bool	Whether to export the fuelbed depth array. Defaults to True.	True
overwrite	bool	Whether to overwrite trees*.dat files already present in the directory. If files exist, raises an error if True, warning if False. Defaults to False.	False

Returns:

Name	Type	Description
None	None	Writes QUIC-Fire .dat files to the provided directory.

to_numpy

to_numpy(fuel_type: str, fuel_parameter: str) -> np.ndarray

Returns a numpy array of the provided fuel type and parameter.

Parameters:

Name	Type	Description	Default
fuel_type	str	Fuel type of desired array. Must be one of "integrated, "separated", "grass", "litter", "deciduous", or "coniferous. "integrated" : returns a vertically-integrated array of all fuel types. Array remains 3D, with shape (1,ny,nx). Integration method depends on fuel parameter. "separated" : returns a 3D array of shape (nlitter,ny,nx), where the first layer is grass, and the subsequent layers are litter. If using DUET v1, nlitter = 1; if using DUET v2, nlitter is 2 (deciduous and coniferous). "grass" : returns a 3D array of the chosen parameter for grass, with shape (1,ny,nx) "litter" : returns a 3D array of integrated litter values for all tree species, with shape (1,ny,nx). "coniferous" : returns a 3D array of litter values for coniferous tree species, with shape (1,ny,nx). "deciduous" : returns a 3D array of litter values for deciduous tree species, with shape (1,ny,nx).	required
fuel_parameter	str	Fuel parameter of desired array. Must be one of "loading", "moisture", or "depth".	required

Returns:

Type	Description
np.ndarray :	Numpy array of the provided fuel type and parameter.

Targets

Class containing and validating target methods and values for fuel parameters. Should be instantiated using assign_targets.

Attributes:

Name	Type	Description
method	str	Method by which to calibrate to the target values. Must be one of "maxmin", "meansd", or "constant".
args	list[str]	Sting(s) to be used as keyword arguments for calibration, which correspond to the calibration method. For maxmin calibration, use ["max","min"]; for meansd calibration, use ["mean","sd"]; for constant calibration, use []"value"].
targets	list	Calibration targets, which correspond to the elements of Targets.args.

FuelParameter

Class containing and validating calibration targets for a single fuel parameter. A single Target object can be set for multiple fuel types. Should be instantiated using set_fuel_parameter

Attributes:

Name	Type	Description
parameter	str	Fuel parameter for which targets should be set. Must be one of "loading", "moisture", or "depth".
fuel_types	list[str]	Fuel type(s) to which targets should be set. May be any of "grass", "litter", "coniferous", "deciduous", or "all".
targets	list[Targets]	Targets to be set to the provided parameter and fuel types.

import_duet_manual

import_duet_manual(
    directory: str | Path,
    loading_grid_name: str,
    moisture_grid_name: str,
    depth_grid_name: str,
    nx: int,
    ny: int,
    nsp: int,
    version: str,
) -> DuetRun

Creates a DuetRun object from DUET output files

Parameters:

Name	Type	Description	Default
directory	str | Path	Path to directory storing the DUET output files surface_rhof.dat and surface_depth.dat	required
loading_grid_name	str	File name of fuel loading (bulk density) DUET output.	required
moisture_grid_name	str	File name of fuel moisture DUET output.	required
depth_grid_name	str	File name of fuelbed depth DUET output.	required
nx	int	Number of DUET domain cells in the x-direction.	required
ny	int	Number of DUET domain cells in the y-direction.	required
nsp	int	Number of vegetation species (tree species + grass) in the DUET outputs. Must be 2 (grass and litter) for DUET v1.	required
version	str	DUET version that produced the outputs. Must be one of ["v1","v2"].	required

Returns:

Type	Description
Instance of class DuetRun

import_duet

import_duet(
    directory: Path | str, version: str = "v2"
) -> DuetRun

Creates a DuetRun object from DUET input and output files. Assumes all files from a DUET run are present and unaltered. To import a DUET run manually, use import_duet_manual.

Parameters:

Name	Type	Description	Default
directory	str | Path	Path to directory storing the DUET output files surface_rhof.dat and surface_depth.dat and the DUET input files duet.in and treesspcd.dat	required
version	str	DUET version that produced the outputs. Must be one of ["v1","v2"]. Defaults to "v2".	'v2'

Returns:

Type	Description
Instance of class DuetRun

assign_targets

assign_targets(method: str, **kwargs: float) -> Targets

Assigns target values and calculation method for exactly one fuel type and parameter

Parameters:

Name	Type	Description	Default
method	str	Calibration method for the target values provided. Must be one of: "constant", "maxmin", "meansd", "sb40".	required
**kwargs	float	Keyword arguments correspond to the calibration method. For "maxmin" method, kwargs keys must be max and min. For "meansd" method, kwargs keys must be mean and sd. For "constant" method, **kwargs key must be value.	{}

Returns:

Type	Description
Instance of class Targets

set_fuel_parameter

set_fuel_parameter(parameter: str, **kwargs: Targets)

Sets calibration targets for grass, litter, both separately, or all fuel types together, for a single fuel parameter.

Parameters:

Name	Type	Description	Default
parameter	str	Fuel parameter for which to set targets	required
**kwargs	Targets	grass : Targets Grass calibration targets. Only the grass layer of the DUET parameter array will be calibrated. litter : Targets Litter calibration targets. Only the litter layer(s) of the DUET parameter array will be calibrated. Coniferous and deciduous litter will be calibrated together. coniferous : Targets Coniferous litter calibration targets. Only the coniferous litter layer of the DUET parameter array will be calibrated. deciduous : Targets Deciduous litter calibration targets. Only the deciduous litter layer of the DUET parameter array will be calibrated. all : Targets Calibration targets for all (both) fuel types. All layers of the DUET parameter array will be calibrated together.	{}

Returns:

Name	Type	Description
FuelParameter		Object representing targets for the given fuel parameter, for each provided fuel type

set_loading

set_loading(**kwargs: Targets)

Sets fuel loading calibration targets for grass, litter, both separately, or all fuel types together.

Parameters:

Name	Type	Description	Default
grass	Targets | None	Grass calibration targets. Only the grass layer of the DUET fuel loading array will be calibrated.	required
litter	Targets | None	Litter calibration targets. Only the litter layer(s) of the DUET fuel loading array will be calibrated. Coniferous and deciduous litter will be calibrated together.	required
coniferous	Targets | None	Coniferous litter calibration targets. Only the coniferous litter layer of the DUET parameter array will be calibrated.	required
deciduous	Targets | None	Deciduous litter calibration targets. Only the deciduous litter layer of the DUET fuel loading array will be calibrated.	required
all	Targets | None	Calibration targets for all (both) fuel types. All layers of the DUET fuel loading array will be calibrated together.	required

Returns:

Name	Type	Description
FuelParameter		Object representing fuel loading targets for each provided fuel type

set_moisture

set_moisture(**kwargs: Targets)

Sets moisture calibration targets for grass, litter, both separately, or all fuel types together.

Parameters:

Name	Type	Description	Default
grass	Targets | None	Grass calibration targets. Only the grass layer of the DUET moisture array will be calibrated.	required
litter	Targets | None	Litter calibration targets. Only the litter layer(s) of the DUET moisture array will be calibrated. Coniferous and deciduous litter will be calibrated together.	required
coniferous	Targets | None	Coniferous litter calibration targets. Only the coniferous litter layer of the DUET parameter array will be calibrated.	required
deciduous	Targets | None	Deciduous litter calibration targets. Only the deciduous litter layer of the DUET moisture array will be calibrated.	required
all	Targets | None	Calibration targets for all (both) fuel types. All layers of the DUET moisture array will be calibrated together.	required

Returns:

Name	Type	Description
FuelParameter		Object representing moisture targets for each provided fuel type

set_depth

set_depth(**kwargs: Targets)

Sets fuelbed depth calibration targets for grass, litter, both separately, or all fuel types together.

Parameters:

Name	Type	Description	Default
grass	Targets | None	Grass calibration targets. Only the grass layer of the DUET depth array will be calibrated.	required
litter	Targets | None	Litter calibration targets. Only the litter layer(s) of the DUET depth array will be calibrated. Coniferous and deciduous litter will be calibrated together.	required
coniferous	Targets | None	Coniferous litter calibration targets. Only the coniferous litter layer of the DUET parameter array will be calibrated.	required
deciduous	Targets | None	Deciduous litter calibration targets. Only the deciduous litter layer of the DUET depth array will be calibrated.	required
all	Targets | None	Calibration targets for all (both) fuel types. All layers of the DUET depth array will be calibrated together.	required

Returns:

Name	Type	Description
FuelParameter		Object representing depth targets for each provided fuel type

calibrate

calibrate(
    duet_run: DuetRun,
    fuel_parameter_targets: (
        list[FuelParameter] | FuelParameter
    ),
) -> DuetRun

Calibrates the arrays in a DuetRun object using the provided targets and methods for one or more fuel types.

Parameters:

Name	Type	Description	Default
duet_run	DuetRun	The DUET run to calibrate	required
fuel_type_targets	FuelParameters | list(FuelParameters)	FuelParameters object or list of FuelParameters objects for the fuel types to be calibrated.	required

Returns:

Type	Description
Instance of class DuetRun with calibrated fuel arrays

get_unit_from_fastfuels

get_unit_from_fastfuels(zroot)

Creates a geojson bounding box of a fastfuels domain.

Returns:

Type	Description
geojson

get_unit_from_shapefile

get_unit_from_shapefile(directory: str | Path)

Reads in a shapefile and returns a geojson bounding box.

Returns:

Type	Description
geojson

write_numpy_to_quicfire

write_numpy_to_quicfire(
    array: ndarray, directory: str | Path, filename: str
)

Writes a numpy array to a QUIC-Fire fuel input (.dat) in the chosen directory.

Parameters:

Name	Type	Description	Default
array	ndarray	The numpy array to be written. Must be 3D.	required
directory	str | Path	The directory where the file will be written.	required
filename	str	The name of the file to be written. Must end in ".dat".	required

Returns:

Type	Description
None	File is written to disk.

duet_tools.inputs

DUET inputs module

InputFile

Class representing a DUET input file.

Attributes:

Name	Type	Description
nx	int	Number of cells in the x-direction.
ny	int	Number of cells in the y-direction.
nz	int	Number of cells in the z-direction.
dx	float	Cell size in the x-direction (m)
dy	float	Cell size in the y-direction (m)
dz	float	Cell size in the z-direction (m)
random_seed	int	Random number seed.
wind_direction	float	Wind direction (degrees).
wind_variability	float	Wind direction variability (degrees).
duration		Duration of simulation (years).

to_file

to_file(directory: Path | str)

Writes a DUET input file to the specified path

Parameters:

Name	Type	Description	Default
directory	Path | str	Directory for writing DUET input file	required

Returns:

Name	Type	Description
None		Writes duet.in to directory

from_directory classmethod

from_directory(dir: Path | str)

Creates an instance of class InputFile from a directory with a DUET input deck

Parameters:

Name	Type	Description	Default
dir	Path | str	Path to the directory containing the DUET input deck.	required

Returns:

Type	Description
InputFile

duet_tools.landfire

Functions for interfacing with the LandFire API and processing the outputs

LandfireQuery

Class containing the information from a LandFire query, to be passed to assign_targets()

query_landfire

query_landfire(
    area_of_interest: Polygon | Polygon,
    year: str,
    directory: str | Path,
    input_epsg: int,
    delete_files: bool = True,
) -> LandfireQuery

Creates and submits a LANDFIRE query for a specified area of interest.

Parameters:

Name	Type	Description	Default
area_of_interest	Polygon | Polygon	Area in which to query LANDFIRE data. For best results, dimensions in meters should match (nxdx, nydy) of DUET domain.	required
year	int	Year of LANDFIRE data to query. Must be one of [2019, 2020, 2022].	required
directory	Path | str	Directory where files associated with the LANDFIRE query will be saved.	required
input_epsg	int	EPSG number for CRS of area_of_interest polygon	required
delete_files	bool = True	Whether to delete intermediate files created in the process of querying LANDFIRE data. Defaults to True	True

Returns:

Type	Description
LandfireQuery

assign_targets_from_sb40

assign_targets_from_sb40(
    query: LandfireQuery,
    fuel_type: str,
    parameter: str,
    method: str = "maxmin",
) -> Targets

Assign a calibration target and method for a given fuel type and parameter.

Parameters:

Name	Type	Description	Default
query	LandfireQuery	An object of class LandfireQuery created with query_landfire. Calibration targets will be calculated from these values.	required
fuel_type	str	The fuel type to obtain target values for. Must be one of "grass", "litter", or "all".	required
parameter	str	The fuel parameter to obtain target values for. Must be one of "loading", "moisture", or "depth".	required
method	str	The desired calibration method for the sb40-derived targets. Must be one of "maxmin", "meandsd", or "constant". Default is "maxmin". "constant" is only recommended if only one parameter value is present for the given fuel type. "meansd" is not recommended since values often do not follow a normal distribution.	'maxmin'

Returns:

Name	Type	Description
Targets	Targets	A Targets object with values derived from Landfire and SB40 fuel models

duet_tools.utils

Utility functions for DUET tools modules

read_dat_to_array

read_dat_to_array(
    directory: str | Path,
    filename: str,
    nx: int,
    ny: int,
    nz: int = None,
    nsp: int = None,
    order: str = "F",
    dtype: type = np.float32,
) -> np.ndarray

Reads a fortran binary file (.dat) to a numpy array

Parameters:

Name	Type	Description	Default
directory	str | Path	Path to directory of the .dat file.	required
filename	str	Name of the .dat file	required
nx	int	Number of cells in the x-direction	required
ny	int	Number of cells in the y-direction	required
nz	int	Number of cells in the z-direction	None
nsp	int	Number of species	None
order	str	Order of the .dat file. Must be one of "C" or "F". Defaults to "F".	'F'
dtype	type	Data type of the array. Defaults to np.float32	float32

Returns:

Type	Description
A numpy array with shape (nz, ny, nx).

write_array_to_dat

write_array_to_dat(
    array: ndarray,
    dat_name: str,
    output_dir: Path | str,
    dtype: type = np.float32,
    reshape: bool = False,
) -> None

Write a numpy array to a fortran binary file (.dat).

Parameters:

Name	Type	Description	Default
array	ndarray	numpy array to be written to a file	required
dat_name	str	Filename ending with .dat	required
output_dir	Path | str	Directory where file will be written	required
dtype	type	Data type of the array. Defaults to np.float32	float32
reshape	bool	Whether to reshape the array. Array dimensions in duet-tools are either (nz,ny,nx) or (nsp,ny,nx) and will be written in row-major order, meaning that with column-major order (default for fortran), they will be (nx, ny, nz). Reshaping (nsp, ny, nx) arrays to (ny, nx, nsp) will result in the column-major order of (nsp, nx, ny), which is expected by DUET and LANL Trees. If True, reshaping will only be applied to 3D arrays. Defaults to False.	False

read_shapefile_to_geojson

read_shapefile_to_geojson(path: Path) -> geojson.Polygon

Read a shapefile and convert to a geojson polygon. May be used to query LANDFIRE data. Assumes the shapefile has Polygon geometry. Only the first feature is converted to a geojson.

Parameters:

Name	Type	Description	Default
path	str	Path to shapefile. File may be compressed (.zip), or uncompressed (.shp) with constituent files in the same directory.	required

Returns:

Type	Description
A geojson Polygon object.

duet_tools.example