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