Skip to content

Reference

quicfire_tools.inputs

QUIC-Fire Tools Simulation Input Module

SimulationInputs

Class representing a QUIC-Fire input file deck. This class is the primary interface for building a QUIC-Fire input file deck and saving the input files to a directory for running a simulation.

Attributes:

Name Type Description
rasterorigin RasterOrigin

Object representing the rasterorigin.txt file.

qu_buildings QU_Buildings

Object representing the QU_buildings.inp file.

qu_fileoptions QU_Fileoptions

Object representing the QU_fileoptions.inp file.

qfire_advanced_user_inputs QFire_Advanced_User_Inputs

Object representing the qfire_advanced_user_inputs.inp file.

qfire_bldg_advanced_user_inputs QFire_Bldg_Advanced_User_Inputs

Object representing the qfire_bldg_advanced_user_inputs.inp file.

qfire_plume_advanced_user_inputs QFire_Plume_Advanced_User_Inputs

Object representing the qfire_plume_advanced_user_inputs.inp file.

runtime_advanced_user_inputs RuntimeAdvancedUserInputs

Object representing the runtime_advanced_user_inputs.inp file.

qu_movingcoords QU_movingcoords

Object representing the QU_movingcoords.inp file.

qp_buildout QP_buildout

Object representing the qp_buildout.inp file.

quic_fire QUIC_fire

Object representing the QUIC_fire.inp file.

wind_sensors dict[str, WindSensor]

Object representing the all wind sensor input files, e.g. sensor1.inp.

qu_topoinputs QU_TopoInputs

Object representing the QU_topoinputs.inp file.

qu_simparams QU_Simparams

Object representing the QU_simparams.inp file.

create_simulation classmethod

create_simulation(
    nx: int,
    ny: int,
    fire_nz: int,
    wind_speed: float,
    wind_direction: int,
    simulation_time: int,
) -> SimulationInputs

Creates a SimulationInputs object by taking in the mimum required information to build a QUIC-Fire input file deck. Returns a SimulationInputs object representing the complete state of the QUIC-Fire simulation.

Parameters:

Name Type Description Default
nx int

Number of cells in the x-direction [-]. Default cell size is 2m.

required
ny int

Number of cells in the y-direction [-]. Default cell size is 2m.

required
fire_nz int

Number of cells in the z-direction for the fire grid [-]. Default cell size is 1m.

required
wind_speed float

Wind speed [m/s].

required
wind_direction int

Wind direction [deg]. 0 deg is north, 90 deg is east, etc. Must be in range [0, 360).

required
simulation_time int

Number of seconds to run the simulation for [s].

required

Returns:

Type Description
SimulationInputs

Class containing the data to build a QUIC-Fire input file deck and run a simulation using default parameters.

Examples:

>>> from quicfire_tools import SimulationInputs
>>> sim_inputs = SimulationInputs.create_simulation(nx=100, ny=100, fire_nz=26, wind_speed=1.8, wind_direction=90, simulation_time=600)

from_directory classmethod

from_directory(
    directory: str | Path, version: str = "latest"
) -> SimulationInputs

Initializes a SimulationInputs object from a directory containing a QUIC-Fire input file deck. The function looks for each input file in the QUIC-Fire input file deck, reads in the file to an object, and compiles the objects to a SimulationInputs object that represents the complete state of the QUIC-Fire simulation.

Parameters:

Name Type Description Default
directory str | Path

Directory containing a QUIC-Fire input file deck.

required
version str

QUIC-Fire version of the input files to read. Currently supported versions are "v5", "v6", and "latest". Default is "latest".

'latest'

Returns:

Type Description
SimulationInputs

Class containing the input files in the QUIC-Fire input file deck.

Examples:

>>> from quicfire_tools import SimulationInputs
>>> simulation_path = "path/to/simulation/directory"
>>> sim_inputs = SimulationInputs.from_directory(simulation_path)

from_dict classmethod

from_dict(data: dict) -> SimulationInputs

Initializes a SimulationInputs object from a dictionary.

Parameters:

Name Type Description Default
data dict

Dictionary containing input file data.

required

Examples:

>>> from quicfire_tools import SimulationInputs
>>> json_path = "path/to/json/object"
>>> sim_inputs = SimulationInputs.from_json(json_path)
>>> sim_dict = sim_inputs.to_dict()
>>> new_sim_inputs = SimulationInputs.from_dict(sim_dict)

from_json classmethod

from_json(path: str | Path) -> SimulationInputs

Initializes a SimulationInputs object from a JSON file.

Parameters:

Name Type Description Default
path str | Path

Path to the JSON file.

required

Examples:

>>> from quicfire_tools import SimulationInputs
>>> json_path = "path/to/json/object"
>>> sim_inputs = SimulationInputs.from_json(json_path)

write_inputs

write_inputs(
    directory: str | Path, version: str = "latest"
) -> None

Write all input files in the SimulationInputs object to a specified directory.

This method is a core method of the SimulationInputs class. It is the principle way to translate a SimulationInputs object into a QUIC-Fire input file deck.

Parameters:

Name Type Description Default
directory str | Path

Directory to write the input files to.

required
version str

Version of the input files to write. Default is "latest".

'latest'

Examples:

>>> from quicfire_tools import SimulationInputs
>>> sim_inputs = SimulationInputs.create_simulation(nx=100, ny=100, fire_nz=26, wind_speed=1.8, wind_direction=90, simulation_time=600)
>>> sim_inputs.write_inputs("path/to/simulation/directory")

to_dict

to_dict() -> dict

Convert the state of the SimulationInputs object to a dictionary. The name of each input file in the SimulationInputs object is a key to that input file's dictionary form.

Returns:

Type Description
dict

Dictionary representation of the object.

Examples:

>>> from quicfire_tools import SimulationInputs
>>> sim_inputs = SimulationInputs.create_simulation(nx=100, ny=100, fire_nz=26, wind_speed=1.8, wind_direction=90, simulation_time=600)
>>> sim_dict = sim_inputs.to_dict()

to_json

to_json(path: str | Path) -> None

Write the SimulationInputs object to a JSON file.

Parameters:

Name Type Description Default
path str | Path

Path to write the JSON file to.

required

Examples:

>>> from quicfire_tools import SimulationInputs
>>> sim_inputs = SimulationInputs.create_simulation(nx=100, ny=100, fire_nz=26, wind_speed=1.8, wind_direction=90, simulation_time=600)
>>> sim_inputs.to_json("path/to/json/object")

set_custom_simulation

set_custom_simulation(
    fuel_density: bool = True,
    fuel_moisture: bool = True,
    fuel_height: bool = True,
    size_scale: bool = False,
    patch_and_gap: bool = False,
    ignition: bool = True,
    topo: bool = True,
    interpolate: bool = False,
) -> None

Sets the simulation to use custom fuel, ignition, and topography settings.

This function can be useful for setting up simulations that use .dat files to define custom fuel, topography, or ignition inputs.

Parameters:

Name Type Description Default
fuel_density bool

If True, sets the simulation to use fuel density information from a treesrhof.dat file (fuel density flag 3). Default is True.

True
fuel_moisture bool

If True, sets the simulation to use fuel moisture information from a treesmoist.dat file (fuel moisture flag 3). Default is True.

True
fuel_height bool

If True, sets the simulation to use fuel height information from a treesdepth.dat file (fuel height flag 3). Default is True.

True
size_scale bool

If True, sets the simulation to use size scale information from a treesss.dat file (size scale flag 3). Defaults to False as this is a new feature.

False
patch_and_gap bool

If True, sets the simulation to use patch and gap information from patch.dat and gap.dat files (patch and gap flag 2). Defaults to False as this is a new feature.

False
ignition bool

If True, sets the simulation to use a custom ignition source (ignition flag 6). Default is True.

True
topo bool

If True, sets the simulation to use custom topography settings (topography flag 5). Default is True.

True
interpolate bool

If True, sets the simulation to interpolate the custom fuel inputs to the fire grid (fuel flag 4). Default is False. This is also useful as it addresses a bug in versions of QUIC-Fire ≤ v6.0.0 where custom fuels don't work without the interpolation flag set. Interpolation only applies to fuel density, fuel moisture, fuel height, and size scale. Patch and gap, ignition, and topography are not interpolated.

False

Examples:

>>> from quicfire_tools import SimulationInputs
>>> sim_inputs = SimulationInputs.create_simulation(nx=100, ny=100, fire_nz=26, wind_speed=1.8, wind_direction=90, simulation_time=600)
>>> sim_inputs.set_custom_simulation(fuel=True, ignition=True, topo=True)
>>> sim_inputs.quic_fire.fuel_flag
3

set_uniform_fuels

set_uniform_fuels(
    fuel_density: float,
    fuel_moisture: float,
    fuel_height: float,
    size_scale: float = 0.0005,
    patch_size: float = 0.0,
    gap_size: float = 0.0,
) -> None

Sets the simulation to use uniform fuel settings. This function updates the fuel flag to 1 and sets the fuel density, fuel moisture, and fuel height to the specified values.

Parameters:

Name Type Description Default
fuel_density float

Fuel bulk density [kg/m^3]. Note: This is the fuel bulk density, so the fuel load should be normalized by the height of the fuel bed.

required
fuel_moisture float

Fuel moisture content [%].

required
fuel_height float

Fuel bed height [m].

required
size_scale float

Size scale [m]. Default is 0.0005.

0.0005
patch_size float

Patch size [m]. Default is 0.0.

0.0
gap_size float

Gap size [m]. Default is 0.0.

0.0

Examples:

>>> from quicfire_tools import SimulationInputs
>>> sim_inputs = SimulationInputs.create_simulation(nx=100, ny=100, fire_nz=26, wind_speed=1.8, wind_direction=90, simulation_time=600)
>>> sim_inputs.set_uniform_fuels(fuel_density=0.5, fuel_moisture=25, fuel_height=1)
>>> sim_inputs.quic_fire.fuel_density_flag
1
>>> sim_inputs.quic_fire.fuel_density
0.5

set_rectangle_ignition

set_rectangle_ignition(
    x_min: float,
    y_min: float,
    x_length: float,
    y_length: float,
) -> None

Sets the simulation to use a rectangle ignition source. This function updates the ignition flag to 1 and sets the ignition source to the specified rectangle.

Parameters:

Name Type Description Default
x_min float

South-west corner in the x-direction [m]

required
y_min float

South-west corner in the y-direction [m]

required
x_length float

Length in the x-direction [m]

required
y_length float

Length in the y-direction [m]

required

Examples:

>>> from quicfire_tools import SimulationInputs
>>> sim_inputs = SimulationInputs.create_simulation(nx=100, ny=100, fire_nz=26, wind_speed=1.8, wind_direction=90, simulation_time=600)
>>> sim_inputs.set_rectangle_ignition(x_min=0, y_min=0, x_length=10, y_length=10)

set_output_files

set_output_files(
    eng_to_atm: bool = False,
    react_rate: bool = False,
    fuel_dens: bool = False,
    qf_wind: bool = False,
    qu_wind_inst: bool = False,
    qu_wind_avg: bool = False,
    fuel_moist: bool = False,
    mass_burnt: bool = False,
    emissions: bool = False,
    radiation: bool = False,
    surf_eng: bool = False,
) -> None

Sets the simulation to output the specified files. Files set to True will be output by the simulation, and files set to False will not be output.

Parameters:

Name Type Description Default
eng_to_atm bool

If True, output the fire-energy_to_atmos.bin file. Default is False.

False
react_rate bool

If True, output the fire-reaction_rate.bin file. Default is False.

False
fuel_dens bool

If True, output the fuels-dens.bin file. Default is False.

False
qf_wind bool

If True, output the windu, windv, and windw .bin files. Default is False.

False
qu_wind_inst bool

If True, output the quic_wind_inst.bin file. Default is False.

False
qu_wind_avg bool

If True, output the quic_wind_avg.bin file. Default is False.

False
fuel_moist bool

If True, output the fuels-moist.bin file. Default is False.

False
mass_burnt bool

If True, output the mburnt_integ.bin file. Default is False.

False
emissions bool

If True, output the co-emissions and pm-emissions .bin files. Default is False.

False
radiation bool

If True, output the thermaldose and thermalradiation .bin files. Default is False.

False
surf_eng bool

If True, output the surf_eng.bin file. Default is False.

False

Examples:

>>> from quicfire_tools import SimulationInputs
>>> sim_inputs = SimulationInputs.create_simulation(nx=100, ny=100, fire_nz=26, wind_speed=1.8, wind_direction=90, simulation_time=600)
>>> sim_inputs.set_output_files(fuel_dens=True, mass_burnt=True)

set_output_interval

set_output_interval(interval: int)

Sets the interval, in seconds, at which the simulation will write .bin files to disk. This function sets the same interval for all output files.

Parameters:

Name Type Description Default
interval int

Interval in seconds at which to write .bin files to disk.

required

Examples:

>>> from quicfire_tools import SimulationInputs
>>> sim_inputs = SimulationInputs.create_simulation(nx=100, ny=100, fire_nz=26, wind_speed=1.8, wind_direction=90, simulation_time=600)
>>> sim_inputs.set_output_interval(60)

add_wind_sensor

add_wind_sensor(
    wind_speeds: Union[float, List[float]],
    wind_directions: Union[int, List[int]],
    wind_times: Union[int, List[int]],
    sensor_height: float = 6.1,
    x_location: float = 1.0,
    y_location: float = 1.0,
    sensor_name: str = None,
    wind_update_frequency: int = 300,
) -> None

Adds a new wind sensor to the simulation with specified wind conditions. This method handles the coordination between multiple QUIC-Fire input files that contain wind information and ensures they stay synchronized.

Parameters:

Name Type Description Default
wind_speeds float or List[float]

Wind speed(s) in meters per second. Can be a single value for constant wind or a list of values for varying wind conditions.

required
wind_directions int or List[int]

Wind direction(s) in degrees, where 0° is North and degrees increase clockwise (90° is East). Can be a single value or a list matching wind_speeds.

required
wind_times int or List[int]

Time(s) in seconds relative to simulation start (t=0) when each wind condition begins. For constant wind, use 0. For varying winds, provide a list of times corresponding to each speed/direction pair (e.g., [0, 600, 1200] for changes at 0, 10, and 20 minutes).

required
sensor_height float

Height of the sensor in meters. Defaults to 6.1m (20 feet), which is standard weather station height.

6.1
x_location float

X-coordinate position of the sensor in meters. Defaults to 1.0.

1.0
y_location float

Y-coordinate position of the sensor in meters. Defaults to 1.0.

1.0
sensor_name str

Custom name for the sensor. If not provided, will be automatically generated as "sensorN" where N is the next available number.

None
wind_update_frequency int

Minimum time in seconds between wind field updates. Defaults to 300 seconds (5 minutes). Smaller values increase computation time but may improve accuracy.

300

Examples:

Adding a sensor with constant wind:

>>> sim_inputs.add_wind_sensor(
...     wind_speeds=5.0,
...     wind_directions=90,
...     wind_times=0
... )

Adding a sensor with varying wind conditions starting at t=0 and changing every 10 minutes:

>>> sim_inputs.add_wind_sensor(
...     wind_speeds=[5.0, 7.0, 6.0],
...     wind_directions=[90, 180, 135],
...     wind_times=[0, 600, 1200],  # Changes at 0, 10, and 20 minutes
...     sensor_height=10.0,
...     x_location=50.0,
...     y_location=50.0,
...     sensor_name="custom_sensor"
... )
Notes
  • Wind times must be provided relative to simulation start (t=0), not as absolute times.
  • Wind lists must have equal lengths and correspond to each other (i.e., wind_times[0] corresponds to wind_speeds[0] and wind_directions[0]).
  • Wind times must be in ascending order.
  • Wind directions must be in degrees from 0 to 360.
  • Multiple sensors can be added to the same simulation to represent spatial variation in wind conditions.

add_wind_sensor_from_dataframe

add_wind_sensor_from_dataframe(
    df: DataFrame,
    x_location: float,
    y_location: float,
    sensor_height: float,
    time_column: str = "wind_times",
    speed_column: str = "wind_speeds",
    direction_column: str = "wind_directions",
    sensor_name: Optional[str] = None,
    wind_update_frequency: int = 300,
) -> None

Adds a wind sensor to the simulation using wind data from a pandas DataFrame. This is particularly useful when importing wind data from CSV files or other tabular data sources.

Parameters:

Name Type Description Default
df DataFrame

DataFrame containing wind data. Must include columns for times, speeds, and directions (column names can be specified using the column parameters).

required
x_location float

X-coordinate position of the sensor in meters.

required
y_location float

Y-coordinate position of the sensor in meters.

required
sensor_height float

Height of the sensor in meters (typically 6.1m/20ft for standard weather stations).

required
time_column str

Name of the DataFrame column containing wind times in seconds relative to simulation start (t=0). Defaults to "wind_times".

'wind_times'
speed_column str

Name of the DataFrame column containing wind speeds in meters per second. Defaults to "wind_speeds".

'wind_speeds'
direction_column str

Name of the DataFrame column containing wind directions in degrees (0° = North, 90° = East). Defaults to "wind_directions".

'wind_directions'
sensor_name str

Custom name for the sensor. If not provided, will be automatically generated as "sensorN" where N is the next available number.

None
wind_update_frequency int

Minimum time in seconds between wind field updates. Defaults to 300 seconds (5 minutes).

300

Examples:

Using default column names:

>>> import pandas as pd
>>> wind_data = pd.DataFrame({
...     'wind_times': [0, 600, 1200],      # Times at 0, 10, and 20 minutes
...     'wind_speeds': [5.0, 7.0, 6.0],    # Wind speeds in m/s
...     'wind_directions': [90, 180, 135]   # Wind directions in degrees
... })
>>> sim_inputs.add_wind_sensor_from_dataframe(
...     df=wind_data,
...     x_location=50.0,
...     y_location=50.0,
...     sensor_height=6.1
... )

Using custom column names:

>>> weather_data = pd.DataFrame({
...     'time_s': [0, 300, 600],           # Times in seconds from start
...     'speed_ms': [4.0, 5.0, 4.5],       # Speeds in m/s
...     'direction_deg': [45, 90, 75]      # Directions in degrees
... })
>>> sim_inputs.add_wind_sensor_from_dataframe(
...     df=weather_data,
...     x_location=100.0,
...     y_location=100.0,
...     sensor_height=10.0,
...     time_column='time_s',
...     speed_column='speed_ms',
...     direction_column='direction_deg',
...     sensor_name='weather_station_1'
... )
Notes
  • Wind times in the DataFrame must be relative to simulation start (t=0), not absolute times.
  • Times must be in ascending order.
  • Wind directions must be in degrees from 0 to 360.
  • All columns must contain numeric data in the correct units (seconds, m/s, degrees).
  • Multiple sensors can be added to represent spatial variation in wind conditions.
See Also

add_wind_sensor : Add a wind sensor using direct parameter inputs

remove_wind_sensor

remove_wind_sensor(
    sensor_name: str, wind_update_frequency: int = 300
) -> None

Removes a wind sensor from the simulation by its name and updates the simulation's wind timing parameters accordingly.

Parameters:

Name Type Description Default
sensor_name str

Name of the wind sensor to remove. Must match exactly the name of an existing sensor in the simulation.

required
wind_update_frequency int

Minimum time in seconds between wind field updates after sensor removal. Defaults to 300 seconds (5 minutes). This parameter is used to recalculate wind update times for remaining sensors.

300

Raises:

Type Description
ValueError

If the specified sensor_name is not found in the simulation.

Examples:

>>> # Add two wind sensors
>>> sim_inputs.add_wind_sensor(
...     wind_speeds=5.0,
...     wind_directions=90,
...     wind_times=0,
...     sensor_name="sensor1"
... )
>>> sim_inputs.add_wind_sensor(
...     wind_speeds=6.0,
...     wind_directions=180,
...     wind_times=0,
...     sensor_name="sensor2"
... )
>>>
>>> # Remove the first sensor
>>> sim_inputs.remove_wind_sensor("sensor1")
Notes
  • After removing a sensor, the simulation's wind update times are automatically recalculated based on the remaining sensors.
  • Make sure at least one wind sensor remains in the simulation for valid results.
  • Sensor names are case-sensitive.
See Also

add_wind_sensor : Add a wind sensor using direct parameter inputs add_wind_sensor_from_dataframe : Add a wind sensor using data from a DataFrame

InputFile

Bases: BaseModel

Base class representing an input file.

This base class provides a common interface for all input files in order to accomplish two main goals:

1) Return documentation for each parameter in the input file.

2) Provide a method to write the input file to a directory.

list_parameters

list_parameters() -> list[str]

Get a list of the names of all parameters in the input file.

get_documentation

get_documentation(parameter: str = None) -> dict

Retrieve documentation for a parameter. If no parameter is specified, return documentation for all parameters.

print_documentation_table

print_documentation_table(parameter: str = None) -> None

Print documentation for a parameter. If no parameter is specified, print documentation for all parameters.

to_dict

to_dict(include_private: bool = False) -> dict

Convert the object to a dictionary, excluding attributes that start with an underscore.

Returns:

Type Description
dict

Dictionary representation of the object.

to_file

to_file(directory: Path, version: str = 'latest')

Write the input file to a specified directory.

Attributes:

Name Type Description
directory Path

Directory to write the input file to.

version str

Version of the input file to write. Default is "latest".

Gridlist

Bases: InputFile

Class representing the gridlist.txt file. This file contains the grid information for the QUIC-Fire simulation when canopies are present.

Attributes:

Name Type Description
n int

Number of cells in the x-direction [-]

m int

Number of cells in the y-direction [-]

l 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]

aa1 float

Stretching factor for the vertical grid spacing [-]

from_file classmethod

from_file(directory: str | Path, **kwargs)

Initializes a Gridlist object from a directory containing a gridlist.txt file.

RasterOrigin

Bases: InputFile

Class representing the rasterorigin.txt file. This file contains the coordinates of the south-west corner of the domain in UTM coordinates.

Attributes:

Name Type Description
utm_x float

UTM-x coordinates of the south-west corner of domain [m]

utm_y float

UTM-y coordinates of the south-west corner of domain [m]

from_file classmethod

from_file(directory: str | Path, **kwargs)

Initializes a RasterOrigin object from a directory containing a rasterorigin.txt file.

QU_Buildings

Bases: InputFile

Class representing the QU_buildings.inp file. This file contains the building-related data for the QUIC-Fire simulation. This class is not currently used in QUIC-Fire.

Attributes:

Name Type Description
wall_roughness_length float

Wall roughness length [m]. Must be greater than 0. Default is 0.1.

number_of_buildings int

Number of buildings [-]. Default is 0. Not currently used in QUIC-Fire.

number_of_polygon_nodes int

Number of polygon building nodes [-]. Default is 0. Not currently used in QUIC-Fire.

from_file classmethod

from_file(directory: str | Path, **kwargs)

Initializes a QU_Buildings object from a directory containing a QU_buildings.inp file.

QU_Fileoptions

Bases: InputFile

Class representing the QU_fileoptions.inp file. This file contains file output-related options for the QUIC-Fire simulation.

Attributes:

Name Type Description
output_data_file_format_flag int

Output data file format flag. Values accepted are [1, 2, 3]. Recommended value 2. 1 - binary, 2 - ASCII, 3 - both.

non_mass_conserved_initial_field_flag int

Flag to write out non-mass conserved initial field file uofield.dat. Values accepted are [0, 1]. Recommended value 0. 0 - off, 1 - on.

initial_sensor_velocity_field_flag int

Flag to write out the file uosensorfield.dat. Values accepted are [0, 1]. Recommended value 0. 0 - off, 1 - on.

qu_staggered_velocity_file_flag int

Flag to write out the file QU_staggered_velocity.bin. Values accepted are [0, 1]. Recommended value 0. 0 - off, 1 - on.

generate_wind_startup_files_flag int

Generate wind startup files for ensemble simulations. Values accepted are [0, 1]. Recommended value 0. 0 - off, 1 - on.

from_file classmethod

from_file(directory: str | Path, **kwargs)

Initializes a QU_Fileoptions object from a directory containing a QU_fileoptions.inp file.

QU_Simparams

Bases: InputFile

Class representing the QU_simparams.inp file. This file contains the simulation parameters for the QUIC-Fire simulation.

Attributes:

Name Type Description
nx int

Number of cells in the x-direction [-]. Recommended value: > 100

ny int

Number of cells in the y-direction [-]. Recommended value: > 100

nz int

Number of cells in the z-direction [-].

dx float

Cell size in the x-direction [m]. Recommended value: 2 m

dy float

Cell size in the y-direction [m]. Recommended value: 2 m

quic_domain_height float

QUIC domain height [m]. Recommended value: 300 m

surface_vertical_cell_size float

Surface vertical cell size [m].

number_surface_cells int

Number of uniform surface cells [-].

stretch_grid_flag int

Vertical grid stretching flag, values accepted [0, 1, 3]. Default is 3. 0 - uniform, 1 - custom, 3 - parabolic. If stretch_grid_flag is 0 or 3 dz_array is computed from nz, surface_vertical_cell_size, and number_surface_cells. If stretch_grid_flag is 1, custom_dz_array must be provided.

custom_dz_array list[float]

Vertical grid spacing array [m]. Must be provided if stretch_grid_flag is 1. If stretch_grid_flag is 0 or 3, dz_array is computed from nz, surface_vertical_cell_size, and number_surface_cells.

utc_offset int

Hours difference from UTC (aka UTM) [h]

wind_times list[int]

List of times at which the winds are available in Unix Epoch time (integer seconds since 1970/1/1 00:00:00). These are UTC times. Defaults to [int(time.time())] if not provided.

sor_iter_max int

Maximum number of iterations of the SOR wind solver. Recommended value: 10. Default is 10.

sor_residual_reduction int

Residual reduction to assess convergence of the SOR solver (orders of magnitude). Recommended value: 3. Default is 3.

use_diffusion_flag int

Use diffusion algorithm: 0 = off, 1 = on. Recommended value: 0. Default is 0.

number_diffusion_iterations int

Number of diffusion iterations. Recommended value: 10. Default is 10.

domain_rotation float

Domain rotation relative to true north (clockwise is positive) [degrees]. Recommended value: 0 deg. Default is 0.

utm_x float

UTM-x coordinates of the south-west corner of domain [m]. Default is 0.

utm_y float

UTM-y coordinates of the south-west corner of domain [m]. Default is 0.

utm_zone_number int

UTM zone number [-]. Default is 1.

utm_zone_letter int

UTM zone letter (A=1, B=2, ...) [-]. Default is 1.

quic_cfd_flag int

QUIC-CFD flag: 0 = off, 1 = on. Recommended value: 0. Default is 0.

explosive_bldg_flag int

Explosive building damage flag: 0 = off, 1 = on. Recommended value: 0. Default is 0.

bldg_array_flag int

Building array flag. 0 = off, 1 = on. Recommended value: 0. Default is 0.

from_file classmethod

from_file(directory: str | Path, **kwargs)

Initializes a QU_Simparams object from a directory containing a QU_simparams.inp file.

QFire_Advanced_User_Inputs

Bases: InputFile

Class representing the QFire_Advanced_User_Inputs.inp input file. This file contains advanced parameters related to firebrands.

Attributes:

Name Type Description
fraction_cells_launch_firebrands PositiveFloat

Fraction of cells that could launch firebrand tracers from which firebrand tracers will actually be launched [-]. Higher value = more firebrand tracers. Recommended value: 0.05

firebrand_radius_scale_factor PositiveFloat

Multiplicative factor used to relate the length scale of the mixing (firebrand distribution entrainment length scale) to the initial size of the distribution [-]. Higher value = higher growth rate or RT (firebrand distribution) with flight time. Recommended value: 40

firebrand_trajectory_time_step PositiveInt

Time step used to determine the firebrand tracer trajectory [s]. Higher value = less accurate trajectory. Recommended value: 1 s

firebrand_launch_interval PositiveInt

Time interval between launching of firebrand tracers [s]. Higher value = less firebrand tracers launched. Recommended value: 10 s

firebrands_per_deposition PositiveInt

Number of firebrand tracers that one firebrand tracer launched represents [-]. Recommended value: 500

firebrand_area_ratio PositiveFloat

Multiplicative factor used to relate the cell area and fraction of cells from which tracers are launched to initial area represented by one firebrand [-].

minimum_burn_rate_coefficient PositiveFloat

Multiplicative factor relating the minimum mass-loss rate that a firebrand tracer needs to have to justify continuing to track its trajectory to the energy associated with a new ignition [-].

max_firebrand_thickness_fraction PositiveFloat

Multiplicative factor relating the thickness of launched firebrand tracer to maximum loftable firebrand thickness [-].

firebrand_germination_delay PositiveInt

Time after a firebrand has landed at which a fire is started [s]

vertical_velocity_scale_factor PositiveFloat

Maximum value of the multiplicative factor of the vertical velocity experienced by a firebrand = 1/(fraction of the QUIC-URB on fire) [-]

minimum_firebrand_ignitions PositiveInt

Minimum number of ignitions to be sampled in a position where a firebrand lands [-]

maximum_firebrand_ignitions PositiveInt

Maximum number of ignitions sampled at positions distributed within RT around where a firebrand tracer lands [-]

minimum_landing_angle PositiveFloat

Minimum value considered for the angle between the trajectory of the firebrand when it hits the ground and horizontal [rad]

maximum_firebrand_thickness PositiveFloat

Maximum firebrand's thickness [m]

from_file classmethod

from_file(directory: str | Path, **kwargs)

Initializes a QFire_Advanced_User_Inputs object from a directory containing a QFire_Advanced_User_Inputs.inp file.

QUIC_fire

Bases: InputFile

Class representing the QUIC_fire.inp input file. This file contains the parameters relating to the fire simulation and outputs.

Attributes:

Name Type Description
fire_flag Literal[0, 1]

Fire flag, 1 = run fire; 0 = no fire

random_seed int

Random number generator, -1: use time and date, any other integer > 0

time_now PositiveInt

When the fire is ignited in Unix Epoch time (integer seconds since 1970/1/1 00:00:00). Must be greater or equal to the time of the first wind

sim_time PositiveInt

Total simulation time for the fire [s]

fire_time_step PositiveInt

Time step for the fire simulation [s]

quic_time_step PositiveInt

Number of fire time steps done before updating the quic wind field (integer, >= 1)

out_time_fire PositiveInt

After how many fire time steps to print out fire-related files (excluding emissions and radiation)

out_time_wind PositiveInt

After how many quic updates to print out wind-related files

out_time_emis_rad PositiveInt

After how many fire time steps to average emissions and radiation

out_time_wind_avg PositiveInt

After how many quic updates to print out averaged wind-related files

nz PositiveInt

Number of fire grid cells in the z-direction.

stretch_grid_flag Literal[0, 1]

Vertical stretching flag: 0 = uniform dz, 1 = custom

dz PositiveFloat

Cell size in the z-direction [m] of the fire grid. Recommended value: 1m

dz_array List[PositiveFloat]

Custom dz, one dz per line must be specified, from the ground to the top of the domain

fuel_density_flag Literal[1, 2, 3, 4, 5]

Fuel density flag (defaults to 1): 1 = density is uniform over the domain, 2 = density is provided through QF_FuelDensity.inp, 3 = density is provided through Firetec file (treesrhof.dat) matching QUIC-Fire grid, 4 = density is provided through Firetec files for an arbitrary grid, 5 = FastFuels input (assuming uniform dz of 1m)

fuel_density PositiveFloat

Fuel density (kg/m3)

fuel_moisture_flag Literal[1, 2, 3, 4, 5]

Fuel moisture flag (defaults to 1): 1 = moisture is uniform over the domain, 2 = moisture is provided through QF_FuelMoisture.inp, 3 = moisture is provided through Firetec file (treesmoist.dat) matching QUIC-Fire grid, 4 = moisture is provided through Firetec files for an arbitrary grid, 5 = FastFuels input (assuming uniform dz of 1m)

fuel_moisture PositiveFloat

Fuel moisture = mass of water/mass of dry fuel (kg/kg). Must be between 0 and 1.

fuel_height_flag Literal[1, 2, 3, 4]

Fuel height flag (defaults to 1): 1 = height is uniform over the domain, 2 = height is provided through QF_FuelHeight.inp, 3 = height is provided through Firetec file (treesheight.dat) matching QUIC-Fire grid, 4 = height is provided through Firetec files for an arbitrary grid, 5 = FastFuels input (assuming uniform dz of 1m)

fuel_height PositiveFloat

Fuel height of surface layer (m)

size_scale_flag Literal[0, 1, 2, 3, 4, 5]

Size scale flag (defaults to 0): 0 = Default value (0.0005) over entire domain, 1 = custom uniform value over the domain, 2 = custom value provided through QF_SizeScale.inp, 3 = custom value provided through Firetec file (treesss.dat) matching QUIC-Fire grid, 4 = custom value provided through Firetec files for an arbitrary grid, 5 = FastFuels input (assuming uniform dz of 1m)

size_scale PositiveFloat

Size scale (m). Defaults to 0.0005.

patch_and_gap_flag Literal[0, 1, 2]

Patch and gap flag (defaults to 0): 0 = Default values (0, 0) over entire domain, 1 = custom uniform values over the domain, 2 = custom values provided by patch.dat and gap.dat

ignition Ignition

Ignition type specified as an IgnitionsType class from ignitions.py 1 = rectangle 2 = square ring 3 = circular ring 6 = ignite.dat (Firetec file)

ignitions_per_cell PositiveInt

Number of ignition per cell of the fire model. Recommended max value of 100

firebrand_flag Literal[0, 1]

Firebrand flag, 0 = off; 1 = on. Recommended value = 0; firebrands are untested for small scale problems

auto_kill Literal[0, 1]

Kill if the fire is out and there are no more ignitions or firebrands (0 = no, 1 = yes)

eng_to_atm_out Literal[0, 1]

Output flag [0, 1]: gridded energy-to-atmosphere (3D fire grid + extra layers)

react_rate_out Literal[0, 1]

Output flag [0, 1]: compressed array reaction rate (fire grid)

fuel_dens_out Literal[0, 1]

Output flag [0, 1]: compressed array fuel density (fire grid)

qf_wind_out Literal[0, 1]

Output flag [0, 1]: gridded wind (u,v,w,sigma) (3D fire grid)

qu_wind_inst_out Literal[0, 1]

Output flag [0, 1]: gridded QU winds with fire effects, instantaneous (QUIC-URB grid)

qu_wind_avg_out Literal[0, 1]

Output flag [0, 1]: gridded QU winds with fire effects, averaged (QUIC-URB grid)

fuel_moist_out Literal[0, 1]

Output flag [0, 1]: compressed array fuel moisture (fire grid)

mass_burnt_out Literal[0, 1]

Output flag [0, 1]: vertically-integrated % mass burnt (fire grid)

firebrand_out Literal[0, 1]

Output flag [0, 1]: firebrand trajectories. Must be 0 when firebrand flag is 0

emissions_out Literal[0, 1, 2, 3, 4, 5]

Output flag [0, 5]: compressed array emissions (fire grid): 0 = do not output any emission related variables 1 = output emissions files and simulate CO in QUIC-SMOKE 2 = output emissions files and simulate PM2.5 in QUIC- SMOKE 3 = output emissions files and simulate both CO and PM2.5 in QUIC-SMOKE 4 = output emissions files but use library approach in QUIC-SMOKE 5 = output emissions files and simulate both water in QUIC-SMOKE

radiation_out Literal[0, 1]

Output flag [0, 1]: gridded thermal radiation (fire grid)

surf_eng_out Literal[0, 1]

Output flag [0, 1]: surface fire intensity at every fire time step

from_file classmethod

from_file(directory: str | Path, **kwargs)

Initializes a QUIC_fire object from a directory containing a QUIC_Fire.inp file.

QFire_Bldg_Advanced_User_Inputs

Bases: InputFile

Class representing the QFire_Bldg_Advanced_User_Inputs.inp input file. This file contains advanced parameters related to buildings and fuel.

Attributes:

Name Type Description
convert_buildings_to_fuel_flag int

Flag to convert QUIC-URB buildings to fuel. 0 = do not convert, 1 = convert. Recommended value: 0.

building_fuel_density PositiveFloat

Thin fuel density within buildings if no fuel is specified and buildings are converted to fuel. Higher value = more fuel. Recommended value: 0.5. Units: [kg/m^3]

building_attenuation_coefficient PositiveFloat

Attenuation coefficient within buildings if buildings are converted to fuel. Higher value = more drag. Recommended value: 2.

building_surface_roughness PositiveFloat

Surface roughness within buildings if buildings are converted to fuel. Higher value = lower wind speed. Recommended value: 0.01 m. Units: [m]

convert_fuel_to_canopy_flag int

Flag to convert fuel to canopy for winds. 0 = do not convert, 1 = convert. Recommended value: 1.

update_canopy_winds_flag int

Flag to update canopy winds when fuel is consumed. 0 = do not update, 1 = update. Recommended value: 1.

fuel_attenuation_coefficient PositiveFloat

Attenuation coefficient within fuel for the wind profile. Higher value = more drag. Recommended value: 1.

fuel_surface_roughness PositiveFloat

Surface roughness within fuel. Higher value = lower wind speed. Recommended value: 0.1 m. Units: [m]

from_file classmethod

from_file(directory: str | Path, **kwargs)

Initializes a QFire_Bldg_Advanced_User_Inputs object from a directory containing a QFire_Bldg_Advanced_User_Inputs.inp file.

QFire_Plume_Advanced_User_Inputs

Bases: InputFile

Class representing the QFire_Plume_Advanced_User_Inputs.inp input file. This file contains advanced parameters related to modeling buoyant plumes.

Attributes:

Name Type Description
max_plumes_per_timestep PositiveInt

Maximum number of plumes allowed at each time step. Higher values slow down the simulation. Default value: 150,000. Recommended range: 50,000 - 500,000.

min_plume_updraft_velocity PositiveFloat

Minimum plume updraft velocity [m/s]. If plume velocity drops below this value, the plume is removed. Higher values reduce number of plumes. Default value: 0.1 m/s.

max_plume_updraft_velocity PositiveFloat

Maximum allowed plume updraft velocity [m/s]. Default value: 100 m/s.

min_velocity_ratio PositiveFloat

Minimum ratio between plume updraft velocity and wind speed. If ratio drops below this value, plume is removed. Higher values reduce plumes. Default value: 0.1.

brunt_vaisala_freq_squared NonNegativeFloat

Inverse of the Brunt-Vaisala frequency squared [1/s^2], a measure of atmospheric stability. Default value: 0 1/s^2.

creeping_flag Literal[0, 1]

Flag to enable (1) or disable (0) fire spread by creeping. Default value: 1.

adaptive_timestep_flag Literal[0, 1]

Enable (1) or disable (0) adaptive time stepping. Adaptive time stepping improves accuracy but increases simulation time. Default value: 0.

plume_timestep PositiveFloat

Time step [s] used to compute buoyant plume trajectories. Higher values reduce accuracy. Default value: 1s.

sor_option_flag Literal[0, 1]

SOR solver option. 0 = standard SOR, 1 = memory SOR. Default value: 1.

sor_alpha_plume_center PositiveFloat

SOR alpha value at plume centerline. Higher values reduce influence of plumes on winds. Default value: 10.

sor_alpha_plume_edge PositiveFloat

SOR alpha value at plume edge. Higher values reduce influence of plumes on winds. Default value: 1. max_plume_merging_angle : PositiveFloat Maximum angle [degrees] between plumes to determine merging eligibility. Higher values increase plume merging. Default value: 30 degrees.

max_plume_overlap_fraction PositiveFloat

Maximum fraction of smaller plume trajectory overlapped by larger plume to be considered for merging. Higher values increase merging.

plume_to_grid_updrafts_flag Literal[0, 1]

Method to map plume updrafts to grid. 0 = new method, 1 = old method. New method improves accuracy. Default value: 1. New method takes longer, but is needed if smoke is simulated afterwards.

max_points_along_plume_edge PositiveInt

Maximum points to sample along grid cell edge for new plume-to-grid method. Default value: 10.

plume_to_grid_intersection_flag Literal[0, 1]

Scheme to sum plume-to-grid updrafts when multiple plumes intersect a grid cell. 0 = cube method, 1 = max value method. Default value: 1.

QU_TopoInputs

Bases: InputFile

Class representing the QU_TopoInputs.inp input file. This file contains advanced data pertaining to topography.

Attributes:

Name Type Description
filename str

Path to the custom topo file (only used with option 5). Cannot be .bin. Use .dat or .inp

topography Topography

Topography type specified as a TopoType class from topography.py 0 = no terrain file provided, QUIC-Fire is run with flat terrain 1 = Gaussian hill 2 = hill pass 3 = slope mesa 4 = canyon 5 = custom 6 = half circle 7 = sinusoid 8 = cos hill 9 = terrain is provided via QP_elevation.bin (see Section 2.7) 10 = terrain is provided via terrainOutput.txt 11 = terrain.dat (firetec)

smoothing_method Literal[0, 1, 2]

0 = none (default for idealized topo) 1 = Blur 2 = David Robinson’s method based on second derivative

smoothing_passes NonNegativeInt

Number of smoothing passes. Real terrain MUST be smoothed

sor_iterations PositiveInt

Number of SOR iteration to define background winds before starting the fire

sor_cycles Literal[0, 1, 2, 3, 4]

Number of times the SOR solver initial fields is reset to define background winds before starting the fire

sor_relax PositiveFloat

SOR overrelaxation coefficient. Only used if there is topo.

RuntimeAdvancedUserInputs

Bases: InputFile

Class representing the Runtime_Advanced_User_Inputs.inp input file. This file contains advanced parameters related to computer memory usage.

Attributes:

Name Type Description
num_cpus PositiveInt

Maximum number of CPU to use. Do not exceed 8. Use 1 for ensemble simulations. Defaults to 1.

use_acw Literal[0, 1]

Use Adaptive Computation Window (0=Disabled 1=Enabled). Defaults to 0.

QU_movingcoords

Bases: InputFile

Class representing the QU_movingcoords.inp input file. This is a QUIC legacy file that is not modified for QUIC-Fire use.

QP_buildout

Bases: InputFile

Class representing the QU_buildout.inp input file. This is a QUIC legacy file that is not modified for QUIC-Fire use.

QU_metparams

Bases: InputFile

Class representing the QU_metparams.inp input file. This file contains information about wind profiles.

Attributes:

Name Type Description
site_names list[str]

List of site names. Must be the same length as file_names.

file_names list[str]

List of file names. Must be the same length as site_names.

from_file classmethod

from_file(directory: str | Path, **kwargs)

Initializes a QU_metparams object from a directory containing a QU_metparams.inp file.

Parameters:

Name Type Description Default
directory str | Path

Directory containing the QU_metparams.inp file

required

Returns:

Type Description
QU_metparams

Initialized QU_metparams object

Raises:

Type Description
ValueError

If the file cannot be parsed correctly

WindSensor

Bases: InputFile

Class representing a sensor.inp input file. This file contains information on winds, and serves as the primary source for wind speed(s) and direction(s). Multiple sensor.inp files may be created.

Attributes:

Name Type Description
wind_times NonNegativeFloat | list(NonNegativeFloat)

Time in seconds since the start of the fire for each wind shift.

wind_speeds PositiveFloat | list(PositiveFloat)

Wind speed or list of wind speeds (m/s)

wind_directions NonNegativeInt < 360 | list(NonNegativeInt < 360)

Wind direction or list of directions (degrees). Use 0° for North

sensor_heights PositiveFloat | list(PositiveFloat)

Wind measurement height (m). Default is 6.1m (20ft). If a scalar is provided, it will be used for all wind_times.

x_location PositiveInt

Location of the sensor in the x-direction

y_location PositiveInt

Location of the sensor in the y-direction

validate_wind_inputs

validate_wind_inputs()

Validate wind inputs: 1. Ensure wind_times, wind_speeds, and wind_directions are lists. 2. Ensure all wind-related lists have equal lengths.

from_file classmethod

from_file(directory: str | Path, sensor_name: str)

Initializes a WindSensor object from a directory containing a sensor .inp file.

Parameters:

Name Type Description Default
directory str | Path

Directory containing the sensor .inp file.

required
sensor_name str

Name of the sensor to read. A ".inp" string is appended to the name to get the file name.

required

Returns:

Type Description
WindSensor

Initialized WindSensor object.

from_dataframe classmethod

from_dataframe(
    df: DataFrame,
    name: str,
    x_location: float,
    y_location: float,
    sensor_height: float,
    time_column_name: str = "wind_times",
    speed_column_name: str = "wind_speeds",
    direction_column_name: str = "wind_directions",
) -> "WindSensor"

Creates a WindSensor object from a pandas DataFrame containing wind data.

Parameters:

Name Type Description Default
df DataFrame

Pandas DataFrame containing wind data with columns for times, speeds, and directions.

required
name str

Name to assign to the sensor.

required
x_location float

Location of the wind sensor in the x-direction in meters

required
y_location float

Location of the wind sensor in the y-direction in meters

required
sensor_height float

Height of the wind sensor in meters

required
time_column_name str

Name of column containing wind times. Defaults to "wind_times"

'wind_times'
speed_column_name str

Name of column containing wind speeds. Defaults to "wind_speeds"

'wind_speeds'
direction_column_name str

Name of column containing wind directions. Defaults to "wind_directions"

'wind_directions'

Returns:

Type Description
WindSensor

Initialized WindSensor object with data from the DataFrame

Examples:

>>> import pandas as pd
>>> winds_df = pd.read_csv("winds.csv")
>>> sensor = WindSensor.from_dataframe(
...     df, sensor_name="sensor_csv", x_location=50, y_location=50, sensor_height=6.1
... )

WindSensorArray

Bases: BaseModel

Class containing all WindSensor input files and shared attributes.

Attributes:

Name Type Description
sensor_array list(WindSensor)

List of all WindSensor input files managed by the WindSensorArray.

wind_times property

wind_times: list

Creates a global wind times list by combining the wind times lists of each sensor.

validate_unique_sensor_names

validate_unique_sensor_names()

Validate that all sensor names are unique.

from_file classmethod

from_file(directory: str | Path)

Initializes a WindSensorArray object from a directory by reading sensor names and files from QU_metparams.inp.

Parameters:

Name Type Description Default
directory str | Path

Directory containing the QU_metparams.inp and sensor files

required

Returns:

Type Description
WindSensorArray

Initialized WindSensorArray object containing all wind sensors

Raises:

Type Description
FileNotFoundError

If QU_metparams.inp or any sensor file is not found

ValueError

If there is an error parsing the sensor files

to_dict

to_dict()

Convert the object to a dictionary, excluding attributes that start with an underscore.

Returns:

Type Description
dict

Dictionary representation of the object.

quicfire_tools.ignitions

QUIC-Fire Tools Ignitions Module

IgnitionFlags

Bases: int, Enum

Enum class for all valid ignition source options in QUIC-Fire.

Ignition

Bases: BaseModel

Base class for all ignition types in QUIC-Fire. This class is used to provide a common string representation for all ignition types.

RectangleIgnition

Bases: Ignition

Represents a rectangle ignition source in QUIC-Fire.

Attributes:

Name Type Description
x_min float

South-west corner in the x-direction [m]

y_min float

South-west corner in the y-direction [m]

x_length float

Length in the x-direction [m]

y_length float

Length in the y-direction [m]

SquareRingIgnition

Bases: Ignition

Represents a square ring ignition source in QUIC-Fire.

Attributes:

Name Type Description
x_min float

South-west corner in the x-direction [m]

y_min float

South-west corner in the y-direction [m]

x_length float

Length in the x-direction [m]

y_length float

Length in the y-direction [m]

x_width float

Width in the x-direction [m]

y_width float

Width in the y-direction [m]

CircularRingIgnition

Bases: Ignition

Represents a circular ring ignition source in QUIC-Fire.

Attributes:

Name Type Description
x_min float

South-west corner in the x-direction [m]

y_min float

South-west corner in the y-direction [m]

x_length float

Length in the x-direction [m]

y_length float

Length in the y-direction [m]

ring_width float

Width of the ring [m]

quicfire_tools.topography

QUIC-Fire Tools Topography Model

TopoFlags

Bases: int, Enum

Enum class for all valid topography source options in QUIC-Fire.

Topography

Bases: BaseModel

Base class for all topography types in QUIC-Fire. This class is used to provide a common string representation for all topography types.

GaussianHillTopo

Bases: Topography

Creates a Gaussian hill topography in QUIC-Fire.

Attributes:

Name Type Description
x_hilltop PositiveFloat

Gaussian hill top location x-direction [m]

y_hilltop PositiveFloat

Gaussian hill top location y-direction [m]

elevation_max PositiveFloat

Maximum elevation of the Gaussian hill [m]

elevation_std PositiveFloat

Standard deviation of the Gaussian hill [m]

HillPassTopo

Bases: Topography

Creates a hill pass topography in QUIC-Fire.

Attributes:

Name Type Description
max_height PositiveFloat

Maximum elevation of the hill pass [m]

location_param PositiveFloat

Location parameter of the hill pass [m]

SlopeMesaTopo

Bases: Topography

Creates a slope mesa topography in QUIC-Fire.

Attributes:

Name Type Description
slope_axis Literal[0, 1]

Slope axis (0 = x, 1 = y)

slope_value float

Slope in dh/dx or dh/dy

CanyonTopo

Bases: Topography

Creates a canyon topography in QUIC-Fire.

Attributes:

Name Type Description
x_location PositiveFloat

Canyon location in x-dir [m].

y_location PositiveFloat

Canyon location in y-dir [m].

slope_value PositiveFloat

Slope in dh/dx or dy/dy [-].

canyon_std PositiveFloat

Canyon function standard deviation [m].

vertical_offset PositiveFloat

Canyon vertical offset [m].

HalfCircleTopo

Bases: Topography

Creates a half-circle topography in QUIC-Fire.

Attributes:

Name Type Description
x_location PositiveFloat

The x-coordinate of the center of the half-circle topography [m].

y_location PositiveFloat

The y-coordinate of the center of the half-circle topography [m].

radius PositiveFloat

The radius of the half-circle topography [m].

SinusoidTopo

Bases: Topography

Creates a sinusoidal topography in QUIC-Fire.

Attributes:

Name Type Description
period PositiveFloat

The period of the sinusoidal wave [m].

amplitude PositiveFloat

The amplitude of the sinusoidal wave [m].

CosHillTopo

Bases: Topography

Creates a cosine-shaped hill topography in QUIC-Fire.

Attributes:

Name Type Description
aspect PositiveFloat

The aspect (or orientation) of the hill [-].

height PositiveFloat

The height of the hill [m].

quicfire_tools.outputs

Module for converting QUIC-Fire output files to duck array data formats.

OutputFile

A class representing a single output file. This class provides a common interface for processing and retrieving data from output files.

Attributes:

Name Type Description
name str

The name of the output file this object represents.

file_format str

The format of the output file. Valid options are "gridded" and "compressed".

dimensions list[str]

The dimensions of the output file as ["z", "y", "x"] or ["y", "x"].

shape tuple

The shape of the output file array data as (nz, ny, nx).

grid str

The grid type of the output file. Valid options are "fire" and "quic".

x_coords list[float]

The x coordinates of the output file. Coordinates are in the UTM coordinate system with the origin at the southwest corner of the domain.

y_coords list[float]

The y coordinates of the output file. Coordinates are in the UTM coordinate system with the origin at the southwest corner of the domain.

z_coords list[float]

The z coordinates of the output file. Coordinates are in meters above the ground level.

delimiter str

The delimiter used in the output file name.

extension str

The file extension of the output file.

description str

A description of the output file.

units str

The units of the output file.

filepaths list[Path]

A list of file paths for each timestep.

times list[int]

A list of times corresponding to the timesteps.

to_numpy

to_numpy(
    timestep: int | list[int] | range = None,
) -> np.ndarray

Return a numpy array for the given output and timestep(s) with shape (time, nz, ny, nx). If timestep is None, then all timesteps are returned.

Parameters:

Name Type Description Default
timestep int | list[int] | range

The timestep(s) to return. If None, then all timesteps are returned.

None

Returns:

Type Description
ndarray

A 4D numpy array with shape (time, nz, ny, nx) containing the output data.

Examples:

>>> import quicfire_tools as qft
>>> outputs = qft.SimulationOutputs("path/to/outputs", 50, 100, 100)
>>> fire_energy = outputs.get_output("fire-energy_to_atmos")
>>> # Get all timesteps for the fire-energy_to_atmos output
>>> fire_energy_all = fire_energy.to_numpy()
>>> # Get the first timestep for the fire-energy_to_atmos output
>>> fire_energy_slice = fire_energy.to_numpy(timestep=0)

to_netcdf

to_netcdf(
    directory: str | Path, timestep: int | list[int] = None
)

Write a netCDF file for the given output and timestep(s) with dimensions (time, nz, ny, nx). If timestep is None, then all timesteps are returned.

Parameters:

Name Type Description Default
directory str | Path

The path to the folder where netCDF file will be written.

required
timestep int | list[int]

The timestep(s) to write. If None, then all timesteps are written.

None
Builds

netCDF file to disk

Examples:

>>> import quicfire_tools as qft
>>> outputs = qft.SimulationOutputs("path/to/outputs", 50, 100, 100)
>>> fire_energy = outputs.get_output("fire-energy_to_atmos")
>>> out_dir = Path(path/to/output/dir)
>>> # Get all timesteps for the fire-energy_to_atmos output
>>> fire_energy_all = fire_energy.to_netcdf(directory = out_dir)
>>> # Get the first timestep for the fire-energy_to_atmos output
>>> fire_energy_slice = fire_energy.to_netcdf(directory = out_dir, timestep=0)

to_zarr

to_zarr(
    fpath: str | Path,
    chunk_size: dict[str, int] = None,
    **kwargs
) -> zarr.Group

Write the outputs to a zarr file.

Parameters:

Name Type Description Default
fpath str | Path

The path to the folder where zarr files are written to be written.

required
chunk_size dict[str, int]

The chunk size for the zarr array. The dictionary may contain keys "time", "z", "y", and "x" with integer values for the chunk size in each dimension. The default chunk size is (1, nz, ny, nx). If a key is not present, then the chunk size defaults to the size of the dimension.

None
**kwargs

Additional keyword arguments to pass to the zarr array creation function.

{}

Returns:

Type Description
Group

The zarr group containing the output data.

Examples:

>>> import quicfire_tools as qft
>>> outputs = qft.SimulationOutputs("path/to/outputs", 50, 100, 100)
>>> fire_energy = outputs.get_output("fire-energy_to_atmos")
>>> # Write fire-energy_to_atmos output to zarr
>>> zarr_group = fire_energy.to_zarr("path/to/zarr")
>>> zarr_group["fuels-dens"]
<zarr.core.Array '/fuels-dens' (2, 1, 200, 200) float64 read-only>
>>> # Write multiple timesteps to each zarr chunk to improve I/O
>>> zarr_group = fire_energy.to_zarr("path/to/zarr", chunk_size={"time": 100})
>>> zarr_group["fuels-dens"].chunks
(100, 1, 200, 200)

SimulationOutputs

A class responsible for managing and processing simulation outputs, including validation, extraction, and organization of data from output files. This class facilitates the retrieval of data in various formats and can return a numpy array for a specific output, or write the data to a zarr file.

Attributes:

Name Type Description
output_directory Path

The path to the directory containing the simulation outputs. QUIC-Fire defaults this to the "Output" directory in the same directory as the simulation input files, but that does not have to be the case for quicfire-tools. The directory must contain the "fire_indexes.bin" and "grid.bin" files.

fire_nz int

The number of vertical cells in the fire grid.

ny int

The number of cells in the y-direction.

nx int

The number of cells in the x-direction.

dy float

The grid spacing in the y-direction (m).

dx float

The grid spacing in the x-direction (m).

utm_x float

UTM-x coordinates of the south-west corner of domain [m]. Default is 0.

utm_y float

UTM-y coordinates of the south-west corner of domain [m]. Default is 0.

utm_zone int

UTM zone of the domain. Default is None. If None, the coordinates are considered not to be georeferenced.

crs str

EPSG code for the coordinate reference system. If the UTM zone is provided, the crs is set to the UTM zone. If the UTM zone is not provided, the crs is set to None.

__iter__

__iter__()

Return an iterator for the object.

__next__

__next__()

Return the next item in the iterator.

from_simulation_inputs classmethod

from_simulation_inputs(
    output_directory: Path | str,
    simulation_inputs: SimulationInputs,
) -> SimulationOutputs

Create a SimulationOutputs object from a path to a QUIC-Fire "Output" directory and a SimulationInputs object.

Parameters:

Name Type Description Default
output_directory Path | str

The path to the directory containing the simulation outputs. The directory must contain the "fire_indexes.bin" and "grid.bin" files. This is typically the "Output" directory in the same directory as the simulation input files, but that does not have to be the case for quicfire-tools.

required
simulation_inputs SimulationInputs

The SimulationInputs object containing the simulation input data.

required

Returns:

Type Description
SimulationOutputs

A SimulationOutputs object.

Examples:

>>> import quicfire_tools as qft
>>> inputs = qft.SimulationInputs.from_directory("path/to/inputs")
>>> outputs = qft.SimulationOutputs.from_simulation_inputs("path/to/outputs", inputs)

list_outputs

list_outputs() -> list[str]

Return a list of available output names.

Returns:

Type Description
list[str]

A list of available output names.

Examples:

>>> import quicfire_tools as qft
>>> outputs = qft.SimulationOutputs("path/to/outputs")
>>> outputs.list_outputs()
['fire-energy_to_atmos', 'fuels-dens', 'groundfuelheight', 'mburnt_integ']

get_output

get_output(key) -> OutputFile

Return the OutputFile object for the given output name.

Parameters:

Name Type Description Default
key

The name of the output to return.

required

Returns:

Type Description
OutputFile

The OutputFile object for the given output name.

Raises:

Type Description
ValueError

If the output name is not valid.

Examples:

>>> import quicfire_tools as qft
>>> outputs = qft.SimulationOutputs("path/to/outputs")
>>> fire_energy = outputs.get_output("fire-energy_to_atmos")
>>> fire_energy
<quicfire_tools.outputs.OutputFile object at 0x7f8b1c2b6d90>

to_numpy

to_numpy(
    key: str,
    timestep: None | int | list[int] | range = None,
) -> np.ndarray

Returns a 4D numpy array for the given output and timestep(s) with shape (time, nz, ny, nx). If timestep is None, then all timesteps are returned.

Parameters:

Name Type Description Default
key str

The name of the output to return.

required
timestep None | int | list[int] | range

The timestep(s) to return. If None, then all timesteps are returned.

None

Returns:

Type Description
ndarray

A 4D numpy array with shape (time, nz, ny, nx) containing the output data.

Examples:

>>> import quicfire_tools as qft
>>> outputs = qft.SimulationOutputs("path/to/outputs", 50, 100, 100)
>>> output_name = "fire-energy_to_atmos"
>>>
>>> # Get all timesteps for the fire-energy_to_atmos output
>>> fire_energy_all = outputs.to_numpy(output_name)
>>>
>>> # Get the first timestep for the fire-energy_to_atmos output
>>> fire_energy_first_time_step = outputs.to_numpy(output_name, timestep=0)

to_dask

to_dask(key: str) -> da.Array

Returns a dask array for the given output with shape (time, nz, ny, nx).

Parameters:

Name Type Description Default
key str

The name of the output to return.

required

Returns:

Type Description
Array

A dask array with shape (time, nz, ny, nx) containing the output data with chunks of size (1, nz, ny, nx). The dask array is lazily evaluated, so users must call .compute() to retrieve the data.

Examples:

>>> import quicfire_tools as qft
>>> outputs = qft.SimulationOutputs("path/to/outputs", 50, 100, 100)
>>> fire_energy_da = outputs.to_dask("fire-energy_to_atmos")
>>> fire_energy_np = fire_energy_da.compute()  # Retrieve the data