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). Defaults to 2m.
dx	float	The grid spacing in the x-direction (m). Defaults to 2m.
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