Computational Guide
Introduction
Installation
This guide will go through the steps of installing ELMFIRE to a linux system. Windows users can use ELMFIRE by using a WSL installation, allowing the use of a linux subsystem within windows. More details on installing WSL can be found in https://www.geeksforgeeks.org/installation-guide/how-to-install-wsl2-windows-subsystem-for-linux-2-on-windows-10/ (make sure to stop at step 7, before the virtual machine section). This installation guide was tested on a clean install of Ubuntu 24.04
Install Prerequisites:
The following commands will install packages needed to build and run ELMFIRE:
sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install -y bc csvkit gdal-bin gfortran git jq libopenmpi-dev openmpi-bin pigz python3 python3-pip unzip wget zip
Several Python libraries / packages, including three related to Google Remote Proecedure Call (gRPC), are needed to run the CloudFire microservices that provide ELMFIRE with fuel, weather, and ignition geospatial data. These can be installed system-wide as follows:
sudo pip3 install google-api-python-client grpcio grpcio-tools python-dateutil --break-system-packages
Alternatively, virtualenv can be used to prevent forcing a system-wide install as follows:
sudo apt-get install python3-virtualenv
virtualenv $HOME/virtualenv/elmfire
source $HOME/virtualenv/elmfire/bin/activate/
$HOME/virtualenv/elmfire/bin/pip3 install google-api-python-client grpcio grpcio-tools python-dateutil
Clone ELMFIRE Github repository:
The current ELMFIRE repository can be cloned as follows:
git clone https://github.com/lautenberger/elmfire.git
Since this will clone the current repository, including all recent commits, for use in production environments a user may want to clone the latest stable release / branch instead, i.e.:
git clone --branch 2025.1002 --single-branch https://github.com/lautenberger/elmfire.git
Set environment variables
ELMFIRE uses four environment variables:
The easiest way to specify these variables is by exporting them from your `` /.bashrc`` file. For example, one could pico `` /.bashrc`` and then add the following lines (replacing /scratch/clauten, /home/clauten/elmfire, etc.):
export ELMFIRE_SCRATCH_BASE=/scratch/clauten
export ELMFIRE_BASE_DIR=/home/clauten/elmfire
export ELMFIRE_INSTALL_DIR=$ELMFIRE_BASE_DIR/build/linux/bin
export CLOUDFIRE_SERVER=worldgen.cloudfire.io
export PATH=$PATH:$ELMFIRE_INSTALL_DIR:$ELMFIRE_BASE_DIR/cloudfire
These environment variables will be set on the next login or after sourcing the newly-edited file (`` /.bashrc``).
Build ELMFIRE executables:
ELMFIRE and its postprocessing tool can be built as follows:
cd $ELMFIRE_BASE_DIR/build/linux
./make_gnu.sh
Unless an error occurs, this will build the executables elmfire_VERSION and elmfire_post_VERSION (where version is, for example, 1.1) and copy them to $ELMFIRE_INSTALL_DIR. If this directory is not in the user’s $PATH it should be added at this time. Note that two debug executables are also built.
At this point ELMFIRE has been installed in your local machine. Run the tutorial cases in elmfire/tutorials/ to get started and verify everything was installed correctly.
First Run
ELMFIRE models the spread of a wildfire across a landscape and provides insightful outputs regarding the spread of the fire itself, the computation process or other post-processed results. The minimum information required to run an ELMFIRE simulation are:
Topography Rasters (Elevation, Slope, Aspect)
Fuel Raster
Fuel Dictionary
Canopy Values (Canopy Height, Canopy Base Height, Canopy Bulk Density, Canopy Cover)
Ignition Location
Transient Weather Values (Wind Magnitude, Wind Direction, 1-hour Fuel Moisture, 10-hour Fuel Moisture, 100-hour Fuel Moisture, Live Herbaceous Fuel Moisture, Live Woody Fuel moisture).
Geospatial Domain Information (projection, cell size, lower-left X and Y coordinates).
The details of an ELMFIRE simulation, and the main way of using ELMFIRE, is through a .data text file, editable with a standard text editor program. For this guide, we will be naming this file elmfire.data . Below is the minimum required elmfire.data file to start an ELMFIRE simulation. Inputs are dictated through namelists (such as &INPUTS) and inputs (such as ASP_FILENAME). All inputs must be within their appropriate namelist. The order of inputs or namelists is not important.
! Denotes a comment, everything after ! is ignored
!The inputs namelist contains parameters relating to parsing input data and setting
!relevant parameters. *_DIRECTORY inputs denote parent folders, and *_FILENAME (for
!weather, fuel and topography) refers to filename.tif. So, LANDSCAPE_FILENAME = 'landscape' means
!the aspect raster is /inputs/landscape.tif.
&INPUTS / Define all the input locations and parameters
FUELS_AND_TOPOGRAPHY_DIRECTORY = './inputs'
LANDSCAPE_FILENAME = 'landscape'
ADJ_FILENAME = 'adj'
PHI_FILENAME = 'phi'
WEATHER_DIRECTORY = './inputs'
WS_FILENAME = 'ws'
WD_FILENAME = 'wd'
M1_FILENAME = 'm1'
M10_FILENAME = 'm10'
M100_FILENAME = 'm100'
LH_MOISTURE_CONTENT = 60
LW_MOISTURE_CONTENT = 90
FOLIAR_MOISTURE_CONTENT = 80
/
!The outputs namelist specifies details around the data and format that are going to
!be returned. In the example here, we only want the spread rate of the fire and the
!time of arrival. All other outputs (other than general statistics) are assumed false.
&OUTPUTS
OUTPUTS_DIRECTORY = './outputs'
DUMP_SPREAD_RATE = .TRUE.
DUMP_TIME_OF_ARRIVAL = .TRUE.
CONVERT_TO_GEOTIFF = .TRUE.
/
!The time control namelist dictates everything about the duration, step size and
!temporal fidelity of the simulation. For now the only thing that needs to be specified
!is the duration of the simulation.
&TIME_CONTROL
SIMULATION_TSTOP = 36000
/
! The simulator namelist contains adjustment parameters, constants and other variables
!around the ELMFIRE solver itself. It is also where the ignition spots are specified.
&SIMULATOR
NUM_IGNITIONS = 1
X_IGN(1) = 0.0
Y_IGN(1) = 3000.0
T_IGN(1) = 3000.0
/
! The miscellaneous namelist contains other important parameters, most critically the
!path to GDAL in the user's computer, and a scratch directory for intermediate file
!saves.
&MISCELLANEOUS
PATH_TO_GDAL = '/usr/bin'
SCRATCH = './scratch'
/
Then, this file is saved as elmfire.data in the same directory as the /inputs folder (containing out fuel, topography and weather information), the /scratch temporary file folder, and the /outputs folder. These folders are not automatically created by ELMFIRE and should be created by the user.
Once all the files and folders are in place, the user can start ELMFIRE using the command (in a terminal in the main folder with the inputs/ , scratch/ and outputs/ folders):
elmfire inputs/elmfire.data
ELMFIRE will then start processing the input rasters, and then will run the main ELMFIRE routine. The expected output for the input file above would look like:
ELMFIRE 1.1
Reading &MISCELLANEOUS namelist group
Reading &INPUTS namelist group
Reading &OUTPUTS namelist group
Reading &COMPUTATIONAL_DOMAIN namelist group
Reading &TIME_CONTROL namelist group
Reading &SIMULATOR namelist group
Reading &WUI namelist group
Reading &CALIBRATION namelist group
Reading &SUPPRESSION namelist group
Reading &SPOTTING namelist group
Reading &SMOKE namelist group
Reading &MONTE_CARLO namelist group
Reading headers for fuels/topography and weather rasters
Setting up shared memory, part 1
Reading weather, fuel, and topography rasters
Reading fuel and topography rasters
Using input Phi grid as ignition source
Determining number of cases to run
Allocating additional rasters
Setting up shared memory, part 2
Setting up statistics arrays
ELMFIRE is running each ensemble member
/usr/bin/gdal_translate -ot Float32 -co "COMPRESS=DEFLATE" -co "ZLEVEL=9" -a_srs "+proj=utm +zone=35 +datum=WGS84 +units=m +no_defs" ./scratch/vs_0000001_0259832.bil ./outputs/vs_0000001_0259832.tif
Input file size is 126, 126
0...10...20...30...40...50...60...70...80...90...100 - done.
/bin/rm -f ./scratch/vs_0000001_0259832.bil
/bin/rm -f ./scratch/vs_0000001_0259832.hdr
/usr/bin/gdal_translate -ot Float32 -co "COMPRESS=DEFLATE" -co "ZLEVEL=9" -a_srs "+proj=utm +zone=35 +datum=WGS84 +units=m +no_defs" ./scratch/time_of_arrival_0000001_0259832.bil ./outputs/time_of_arrival_0000001_0259832.tif
Input file size is 126, 126
0...10...20...30...40...50...60...70...80...90...100 - done.
/bin/rm -f ./scratch/time_of_arrival_0000001_0259832.bil
/bin/rm -f ./scratch/time_of_arrival_0000001_0259832.hdr
Meteorology band 1: Case # 1 complete. Fire area: 3310.3 acres.
End of simulation reached successfully. Shutting down.
The above output shows an ELMFIRE simulation completed with no errors. Tutorial 1 contains a shell file that creates all the necessary files and folders for a simple simulation, and runs elmfire.
The following sections will go into depth of the different variables, options and switches within ELMFIRE.
Surface Fire Spread
Surface fire spread is the default fire spread mode of ELMFIRE, and will always run when the minimum inputs are provided. The default surface fire rate of spread model is the Rothermel model [23]. Alternative spread models will be described in following sections.
The first step in setting up ELMFIRE is to specify the geospatial input files. A distinction is made between weather files, and fuel and topography files. If the user sources a landscape files, which contains the 8 landscape and fuel rasters as separate bands (the standard that Farsite and Flammap use, and that can be directly obtained from LANDFIRE), it can be used directly in ELMFIRE. Older versions of the landscape files were provided in .lcp format, this format is slowly being deprecated and ELMFIRE does not support it. Flammap does contain tools to convert .lcp landscape files to .tif multiband raster files. To use landscape files, you will just require:
LANDSCAPE_FILENAME: Multiband geotiff landscape file (16-bit integers)ADJ_FILENAME: Surface spread rate adjustment factor (32-bit float)PHI_FILENAME: Initial (level set variable) field (32-bit float)
Filenames should be specified without a suffix (e.g., ’lcp’, not ’lcp.tif’ because ELMFIRE automatically appends the .tif suffix to filenames (if they are virtual raster (.vrt) files, this behavior can be changed by setting VRT_INSTEAD_OF_TIF = .TRUE.). Some checks are implemented to ensure that all the rasters are consistent in terms of cellsize, overall extent and projection. The weather inputs and the landscape inputs should be consistent amongst each other, but the weather inputs can be coarser than the landscape inputs.
Users can also specify specific geotiff files for each fuel and landscape raster instead of specifying a combined landscape file. The required files then become:
ASP_FILENAME: Topographic aspect in degrees (16-bit integer)CBD_FILENAME: Canopy bulk density in units of 100 kg per meter cubed (16-bit integer)CBH_FILENAME: Canopy base height in units of 10 meters (16-bit integer)CC_FILENAME: Canopy cover in units of percent (16-bit integer)CH_FILENAME: Canopy height in units of 10 meters (16-bit integer)DEM_FILENAME: Digital elevation model data in units of meters (16-bit integer)FBFM_FILENAME: Fire behavior fuel model file (16-bit integer)SLP_FILENAME: Topographic slope in degrees (16-bit integer)ADJ_FILENAME: Surface spread rate adjustment factor (32-bit float)PHI_FILENAME: Initial (level set variable) field (32-bit float)
All of the above rasters, except for Phi and Adjustment, need to be Int16 variable data type. Phi and Adjustment must be Float32. The canopy parameters CBH and CH are in units of 10 meters, and CBD is in 100 kg per meter cubed. This is consistent with how these values are provided and reported in the US LANDFIRE database. If the input data of these files are in meters and kg per meter cubed respectively, the switches CBD_TIMES_100, CBH_TIMES_10 and CH_TIMES_10 can be set to .FALSE.. Note that the input rasters would then have to change change variable type from Int16 to Float32. Similarly, CC is read in percent as standard, but this can be changed by setting CC_IN_PERCENT = .FALSE.. Similar switches exist for DEAD_MC_IN_PERCENT and LIVE_MC_IN_PERCENT.
All the above is also true for the weather rasters, all of which need to be Float32. The weather values are specifically:
WS_FILENAME: 20-ft wind speed in mphWD_FILENAME: 20-ft wind direction in degreesM1_FILENAME: 1-hour dead fuel moisture content in %M10_FILENAME: 10-hour dead fuel moisture content in %M100_FILENAME: 100-hour dead fuel moisture content in %
If the rasters specified above are single-band, then wind/weather conditions are assumed to be unchanging for the duration of the simulation. Transient wind/weather streams can be provided as input by using multi-band, or “stacked”, rasters. In that case, the parameter DT_METEOROLOGY should be specified on the &INPUT line. DT_METEOROLOGY is the time interval (in seconds) between bands in the weather rasters. DT_METEOROLOGY is commonly set to 3600 seconds due to the use of hourly reanalysis or forecast products to drive fire spread simulation. If wind speed is provided at 10 meters instead of 20 feet, the parameter WS_AT_10M = .TRUE. should be set to .TRUE.. Similarly, if the wind speed is provided in kph instead of mph, the parameter WS_IN_KPH = .TRUE. should be set to .TRUE.. Note that neither of these options affect the output format of the results.
By default, live fuel moisture content (herbaceous, woody, and foliar) are spatially uniform and temporally unchanging. They are specified in the &INPUTS namelist group via the keywords LH_MOISTURE_CONTENT, LW_MOISTURE_CONTENT, and FOLIAR_MOISTURE_CONTENT, respectively. Spatially varying live fuel moisture content can be specified by setting USE_CONSTANT_LH = .FALSE., USE_CONSTANT_LW = .FALSE., and USE_CONSTANT_FMC = .FALSE.. This directs ELMFIRE to read live fuel moisture from the rasters specified by MLH_FILENAME, MLW_FILENAME, FMC_FILENAME (live herbaceous, live woody, and foliar, respectively). Even though live fuel moistures will typically change very little during a fire forecast (or hindcast), ELMFIRE expects the live fuel moisture rasters to have the same number of bands as the weather rasters, with the time interval between bands specified by DT_METEOROLOGY.
ELMFIRE automatically interpolates between specific weather parameter steps, during the level set mode. The default behavior is a simple linear interpolation. Bilinear interpolation can also be used by turning WX_BILINEAR_INTERPOLATION = .TRUE. in the &SIMULATOR namelist.
The Rothermel model requires midflame windspeed for its calculation. A wind adjustment factor is automatically calculated based on the algorithms in BEHAVE and Farsite. FARSITE and ELMFIRE assume a crown ratio of 1 for their calculation. This can be manually changed if needed through CROWN_RATIO.
Alternative Spread Models
While the standard model to estimate the rate of spread of the simulated wildfire is the Rothermel model [23][5], alternative models can be integrated into ELMFIRE. A surface rate of spread model that has been integrated to ELMFIRE is the Canadian Fire Behavior Prediction model (FBP), part of the Canadian Forest Fire Danger Rating System (CFFDRS). The FBP is based on a series of developments and submodels developed by the Canadian Forestry Service, including the Forest Fire Weather Index system (FWI) [30], the Fire Behavior Prediction system (FBP) [1], and the 2009 corrections and updates [32]. The model has been implemented operationally to the now deprecated Prometheus software [28] and the new WISE software.
To activate the canadian model in ELMFIRE, specify SURFACE_SPREAD_MODEL = ’CFFDRS’ in the &INPUTS namelist. By default, SURFACE_SPREAD_MODEL is set to ’ROTHERMEL’. The model then replaces the Rothermel maximum rate of spread calculation with the one specified in the FBP, including prolonged drought effects represented by the Build-Up Index (BUI). Calculating the BUI requires the Drought Code (DC) and Duff Moisture Code (DMC), both of which are sub-indices of the Fire Weather Index (FWI). These two indices are continuously updated (meaning each new measurement requires the previous measurement), and require daily weather data, specifically midday Temperature and Humidity, and 24h precipitation. As such, ELMFIRE requires additional inputs for the CFFDRS model to function.
The additional inputs are all in the &INPUTS namelist. The first is START_DC, the Drought Code at the closest midday before the fire ignition. This means that if the fire starts at 16:00, the START_DC should be specified at 12:00 of the same day. If the fire starts at 09:00, the START_DC should be specified at 12:00 of the previous day. The second new input is the starting Duff Moisture Code, START_DMC, that functions similarly to START_DC. The third input is DAILY_WEATHER_FILENAME, which specifies the full name of the file containing the daily midday weather stream, and should be within the WEATHER_DIRECTORY folder. The structure of the weather stream is shown below:
DAILY,TEMP,RH,PRECIP
01/01/2025,30.2,25.4,0
02/01/2025,28.2,22.3,0
03/01/2025,28.8,31.5,0
04/01/2025,26.5,39.8,3
05/01/2025,29.4,35.1,0
...
The temperature is specified in Celsius, and the precipitation in mm. The date of each weather reading is specified in DD/MM/YYYY and is important, as the exact month of each measurement affects parameters within the DMC and DC calculations. Note that the dates that are specified in the weather file do not, as of yet, overwrite or affect CURRENT_YEAR and HOUR_OF_YEAR parameters in the &TIME_CONTROL namelist. HOUR_OF_YEAR must be set as an input, so the rest of the program has a measure of the current simulation hour.
Also note that the standard Canadian FBP fuels are interpreted from the FBFM_FILENAME file, so no change is needed. One change that might be desirable is the omission of Canopy Bulk Density and Canopy Base Height inputs, as the FBP has hardcoded these values as surface fuel parameters. If CH_FILENAME and CBD_FILENAME are not specified, the standard values found in [28] will be used.
All other parts of ELMFIRE, including Crown Fire, Suppression, and Spotting, will work with the CFFDRS with no changes required.
Grid Declination
In rare cases, direction rasters (specifically wind direction (WD) and aspect (ASP)) may have absolute north different from the absolute north of the domain. If this is the case, the difference between the true north of the simulation and the north of the wind direction and aspect measurements is called the grid declination. This can be accounted for in ELMFIRE, by setting the GRID_DECLINATION float variable. Then the user should also set ROTATE_WD to .TRUE. if the WD grid needs adjustment, and ROTATE_ASP to .TRUE. if the Aspect grid needs adjustment.
Computational domain size, extents, and resolution
Older versions of ELMFIRE required that the computational domain parameters be explicitly set in the input file via the &COMPUTATIONAL_DOMAIN namelist group. This group has been removed in newer versions of ELMFIRE, and the parameters below are determined automatically using GDAL. The parameters have been kept here for clarity. The computational domain is specified by the following parameters:
A_SRS: Projection of output files. Typically, a proj string would be used, i.e. A_SRS = ’EPSG:32610’.
COMPUTATIONAL_DOMAIN_CELLSIZE: spatial resolution of the computational domain, uniform in the x and y directions. This is commonly set to the spatial resolution of the input fuels layers (often 30 m) but can be set to a smaller value (e.g., 10 m) if a more highly resolved simulation is desired.
COMPUTATIONAL_DOMAIN_XLLCORNER: x-coordinate of the lower left corner of the fuels inputs.
COMPUTATIONAL_DOMAIN_YLLCORNER: y-coordinate of the lower left corner of the fuels inputs.
Time
Parameters related to time (simulation duration, computational timestep, etc.) are specified via the &TIME_CONTROL namelist group. A sample &TIME_CONTROL namelist group with key inputs is shown below:
&TIME_CONTROL
SIMULATION_TSTART = 0.0
SIMULATION_TSTOP = 3600.0
SIMULATION_DT = 5.0
SIMULATION_DTMAX = 600.0
TARGET_CFL = 0.4
DT_INTERPOLATE_M1 = 300.0
DT_INTERPOLATE_M10 = 3000.0
DT_INTERPOLATE_M100 = 30000.0
DT_INTERPOLATE_MLH = 9E8
DT_INTERPOLATE_MLW = 9E8
DT_INTERPOLATE_FMC = 9E8
DT_INTERPOLATE_WIND = 300.0
/
Simulation start and stop times are specified via the keywords SIMULATION_TSTART and SIMULATION_TSTOP, respectively. These parameters have units of seconds, so a 12-hour simulation corresponds to SIMULATION_TSTOP = 43200. The default value of SIMULATION_TSTART is 0 seconds, meaning computations start at \(t = 0\) seconds. This is generally appropriate for simulations driven by idealized or synthetic weather data. For transient wind/weather/fuel moisture multi-band rasters, Band 1 always corresponds to \(t = 0\) seconds in ELMFIRE. The duration of an ELMFIRE simulation, while explicitly dictated, can be randomized between the start and stop times, through RANDOMIZE_SIMULATION_TSTOP.
When simulating real fires driven by transient, often hourly, weather streams it is usually desirable to start a fire spread simulation at a time > 0 seconds. Assuming that hourly weather fields are provided as input and fire’s time of ignition is 14:20, SIMULATION_TSTART should be set to 1200.0, i.e., 20 minutes after the hour. In this particular case, Band 1 in all transient raster inputs should correspond to 14:00 and Band 2 should correspond to 15:00. The output files will contain rasters representing the unused weather bands, so some of the beginning or ending bands might be empty (or uniform). To crop the output rasters and only use the required weather bands, set ONLY_READ_NEEDED_WX_BANDS = .TRUE. in the &INPUTS namelist.
The initial timestep is specified with the SIMULATION_DT keyword. The timestep is automatically adjusted at runtime based on the Courant-Friedrichs-Lewy (CFL) conditions. The target CFL number can be specified by TARGET_CFL. Since the internal timestep will change during a simulation, an upper limit on the allowable timestep can be specified with the SIMULATION_DTMAX keyword.
Since wind/weather fields are often provided at hourly intervals but ELMFIRE’s computational timestep is usually on the order of a few to at most tens of seconds, ELMFIRE uses linear interpolation to determine wind/weather/fuel moisture conditions at intermediate times. This interpolation can be computationally expensive, so the user is provided with some control over the interpolation frequency. The keywords DT_INTERPOLATE_M1, DT_INTERPOLATE_M10, and DT_INTERPOLATE_M100 control the time between interpolations for 1-hour, 10-hour, and 100-hour fuel moistures. Wind speed and wind direction are controlled by DT_INTERPOLATE_WS and DT_INTERPOLATE_WD. As with other temporal inputs, units are seconds. The values quoted in the example &TIME namelist above correspond to the standard values of ELMFIRE.
The start of each ELMFIRE simulation, or equivalently the specific hour of the first weather band, is assumed to be midnight. This can be changed (primarily for writing outputs) by changing the value of BAND_ONE_HOUR_OF_YEAR.
Overnight Adjustment
The Rothermel model is well known to overpredict the rate of spread at night times, even when accounting for changes in dead fuel moisture content. ELMFIRE can account for this by multiplying its predicted rates of spread by an OVERNIGHT_ADJUSTMENT_FACTOR, set at 0.1 by default. This adjustment factor can be activated by setting USE_DIURNAL_ADJUSTMENT_FACTOR to .TRUE.. ELMFIRE then internally estimates the sunset and sunrise hours, applying the diurnal adjustment factor between those two times. SUNRISE_HOUR and SUNSET_HOUR can be set directly if known.
With the above parameters, the sunrise and sunset times are known either by input or calculation. The start time of the simulation (note the difference between start time of simulation and ignition start time) can then be set by FORECAST_START_HOUR.
Empirical evidence exists that dictates the main wildfire activity escalates some hours after sunrise and subsides some hours after sunset. To allow the user to include this observation to ELMFIRE, the overnight adjustment factor is not applied strictly between sunset and sunrise. Instead, the user must specify a BURN_PERIOD_LENGTH in hours for the total fire duration, and a BURN_PERIOD_CENTER_FRAC, a fraction denoting whether the fire activity is concentrated in the early or late hours of the day.
All the above is best explained with an example. Assume that for a specific fire the sunrise and sunset hours are 07:00 and 21:00 respectively. With a BURN_PERIOD_LENGTH of 12 hours, and a BURN_PERIOD_CENTER_FRAC of 0.5, the mean hour of fire activity is \(7+0.5\times (21-7)=14\). The diurnal adjustment factor then takes effect between \(14 +0.5\times 12 = 20\) and \(14-0.5\times 12 = 8\). Note how this result is antithetical to the initial empirical assumption this function was designed for. With a BURN_PERIOD_CENTER_FRAC of 0.7, the mean hour of fire activity is \(7+0.7\times (21-7)=16.8\). The diurnal adjustment factor then takes effect between \(16.8 +0.5\times 12 = 22.8\) and \(16.8-0.5\times 12 = 10.8\), which follows our observation. Expert judgement is required to fine tune these parameters for an accurate result.
Fire Initialization
The two primary methods to initialize a fire spread simulation include point source ignitions and active fire perimeter initialization. These methods can be used concurrently, e.g. to simulate an active fire perimeter with additional point ignitions or spot fire initiation outside of the fire perimeter.
Point source ignitions
One or more point source ignitions can be specified on the &SIMULATOR namelist group via the keywords X_IGN(:), Y_IGN(:), and T_IGN(:) which respectively control point ignitions’ x- and y-coordinates, and time of ignitions. As an example, the following lines specify two separate point source ignitions:
&SIMULATOR
NUM_IGNITIONS = 2
X_IGN(1) = 1000.0
Y_IGN(1) = 1000.0
T_IGN(1) = 0.0
X_IGN(2) = 2000.0
Y_IGN(2) = 2000.0
T_IGN(2) = 7200.0
The first ignition occurs at (x,y) = (1000.0, 1000.0) at simulation time 0.0 seconds and the second occurs at (x,y) = (2000.0, 2000.0) at simulation time = 7200.0 seconds. The keyword NUM_IGNITIONS specifies the total number of point source ignitions. Ignitions should be numbered sequentially starting at 1 and ending at NUM_IGNITIONS. The number of point source ignitions is currently limited to 100.
Line source ignitions
Line ignitions can be included in ELMFIRE by specifying the start and end point of each line segment, along with its ignition time. Similarly to the point ignition parameters, multiple line ignitions can be specified, each with its own ignition time. To do this:
&SIMULATOR
X_LINE_IGN_START(1) = 1000.0
Y_LINE_IGN_START(1) = 1000.0
X_LINE_IGN_END(1) = 2000.0
Y_LINE_IGN_END(1) = 2000.0
T_LINE_IGN(1) = 7200.0
Note how the input NUM_IGNITIONS is no longer necessary. The above block creates a diagonal ignition starting from (1000, 1000) and extending to (2000, 2000), igniting all points inbetween starting at t = 7200 seconds.
Active fire perimeters
The fire front position is tracked by solving a conservation equation for the level set variable \(\phi\) where unburned areas correspond to \(\phi > 0\), burned areas correspond to \(\phi < 0\), and the fire front position is the level set corresponding to \(\phi = 0\). At the start of a simulation ELMFIRE reads the initial field from a 32-bit floating point raster with filename PHI_FILENAME as specified in the &INPUTS namelist group.
If there is no active fire at the start of a simulation, then all pixels in the PHI_FILENAME raster should be initialized with a single start value greater than 0 (usually 1.0). An initial fire front position can be specified by burning a value less than 0 (usually -1.0) into the PHI_FILENAME raster. All pixels with an initial value less than 0 will be marked as burned and fire spread will be initiated from those pixels.
Extinguished or “cold” segments of the fire perimeter can be simulated by modifying the fuel model raster to have a non-burnable fuel model in extinguished segments of the fire perimeter.
Outputs
A sample &OUTPUTS namelist group is shown below:
&OUTPUTS
OUTPUTS_DIRECTORY = './outputs'
DTDUMP = 3600.
DUMP_FLIN = .TRUE.
DUMP_SPREAD_RATE = .TRUE.
DUMP_SURFACE_FIRE = .TRUE.
DUMP_TIME_OF_ARRIVAL = .TRUE.
/
The keyword OUTPUTS_DIRECTORY specifies the directory to which ELMFIRE will write its output files. This output directory must exist at run-time; it will not be automatically created. Transient outputs, such as DUMP_SURFACE_FIRE, are written at intervals specified by DTDUMP. For diagnostic purposes, these outputs can instead be written at every computational time step by setting DUMP_EVERY_STEP = .TRUE. in the &OUTPUT namelist. The available rasterized outputs are summarized in Table Table 1; transient outputs are identified by Transient in the Output column. The corresponding dump times are saved to a CSV file named dump_times_CASENUMBER.csv in OUTPUTS_DIRECTORY. Rate of spread outputs are in units of ft/min as standard, but can be converted to m/min by setting SPREAD_RATE_IN_M = .TRUE. in the &OUTPUTS namelist.
In general, outputs to be dumped are specified using a logical keyword that begins with DUMP_*. The following is a full list of raster outputs and the logical keywords that control whether they are written to disk.
Most output parameters are written as standard during or after an ELMFIRE simulation. These parameters are given below. Outputs could be rasters of CSV files, showing either the final parameters or transient steps through the simulation, with intervals dictated by DTDUMP.
MAIN DUMP ROUTINE |
||||
Option |
Description |
Units |
Type |
Output |
DUMP_TRANSIENT_ACREAGE |
Total fire scar size over time |
acres |
CSV |
Final |
DUMP_SURFACE_FIRE |
Status of surface fire (1 = burned, 0 = unburned) |
Categorical |
Raster |
Transient |
DUMP_CROWN_FIRE |
Status of crown fire (0 = none, 1 = passive, 2 = active) |
Categorical |
Raster |
Transient |
DUMP_CRITICAL_FLIN |
Surface Fireline intensity required for crown fire ignition |
kW/m |
Raster |
Final |
DUMP_SPREAD_RATE |
Rate of Spread Magnitude |
ft/min |
Raster |
Final |
DUMP_SPREAD_DIRECTION |
Rate of Spread Direction |
degrees |
Raster |
Final |
DUMP_HPUA |
Heat per unit area |
kJ/\(m^2\) |
Raster |
Final |
DUMP_FLIN |
Fireline Intensity |
kW/m |
Raster |
Final |
DUMP_FLAME_LENGTH |
Flame Length |
ft |
Raster |
Final |
DUMP_REACTION_INTENSITY |
Reaction intensity |
kW/\(m^2\) |
Raster |
Final |
DUMP_WS20 |
Wind speed |
Raster |
Transient |
|
DUMP_WD20 |
Wind direction |
degrees |
Raster |
Transient |
DUMP_VELOCITY |
Rate of Spread |
ft/min |
Raster |
Final |
DUMP_TIME_OF_ARRIVAL |
Fire arrival time |
s |
Raster |
Final |
DUMP_TOTAL_DFC_RECEIVED |
Accumulated heat flux due to direct flame contact (WU-E) |
kJ/\(m^2\) |
Raster |
Final |
DUMP_TOTAL_RAD_RECEIVED |
Accumulated heat flux due to radiation (WU-E) |
kJ/\(m^2\) |
Raster |
Final |
DUMP_TRANSIENT_DFC |
Transient DFC heat flux (WU-E) |
kW/\(m^2\) |
Raster |
Transient |
DUMP_TRANSIENT_RAD |
Transient radiation heat flux (WU-E) |
kW/\(m^2\) |
Raster |
Transient |
DUMP_HRR_TRANSIENT |
Transient heat release rate per unit area |
kW/\(m^2\) |
Raster |
Transient |
DUMP_TAGGED |
Show currently ’Tagged’ Cells (1 = Tagged) |
Categorical |
Raster |
Transient |
DUMP_PHI |
Level set phi variable |
Raster |
Transient |
|
DUMP_EMBER_FLUX |
Accumulated ember flux per Monte-Carlo ensemble |
pieces/\(m^2\) |
Raster |
Final |
DUMP_EMBER_FLUX_TRANSIENT |
Transient ember flux at the moment |
pieces/\(m^2\) |
Raster |
Transient |
DUMP_SPOTTING_OUTPUTS |
Ember spatial and temporal travel data |
coordinates, s |
CSV |
Final |
Output filenames are hardcoded but should be readily discernable, e.g. fireline intensity outputs begin with flin_, time of arrival outputs begin with toa_, etc. Since ELMFIRE is sometimes used to run multiple cases as part of a Monte Carlo analysis or sensitivity analysis, a seven-digit sequential identifier is prepended to the name of each output raster, and the time at which the raster was dumped is appended to the filename.
If a monte carlo simulation set is done, especially with random or multiple ignitions, it is useful to plot the scalar outputs on a map, depending on their ignition locations. Each run can be given an initial RUN_ID string, to differentiate it from potential other monte-carlo runs. The outputs that are possible in this case are given in the postprocessing table below.
POSTPROCESS |
||
Switch |
Description |
Units |
CALCULATE_TIMES_BURNED |
sims |
|
CALCULATE_FLAME_LENGTH_STATS |
Output maximum and average flame length |
ft |
USE_FLAME_LENGTH_BINS |
Split the flame length occurrence in bins |
bin number |
USE_EMBER_COUNT_BINS |
Split the firebrand count occurrence in bins |
bin number |
DUMP_SURFACE_FIRE_AREA |
Surface fire area occurring from each ignition spot |
acres |
DUMP_CROWN_FIRE_AREA |
Crown fire area occurring from each ignition spot |
acres |
DUMP_FIRE_VOLUME |
Fire volume occurring from each ignition spot |
ac-ft |
DUMP_AFFECTED_POPULATION |
Affected population occurring from each ignition spot |
input dependent |
DUMP_AFFECTED_REAL_ESTATE_VALUE |
Affected real estate value occurring from each ignition spot |
input dependent |
DUMP_AFFECTED_LAND_VALUE |
Affected land value occurring from each ignition spot |
input dependent |
ACCUMULATE_EMBER_FLUX |
Accumulated number of firebrand per unit area across all ensembles |
pieces/\(m^2\) |
The flame length and ember count bins are specified manually. That is, following the example below (same for the FLAME parameters).
USE_EMBER_COUNT_BINS = .TRUE.
NUM_EMBER_COUNT_BINS = 3
EMBER_COUNT_BIN_LO(1) = 0
EMBER_COUNT_BIN_HI(1) = 10
EMBER_COUNT_BIN_LO(2) = 11
EMBER_COUNT_BIN_HI(2) = 25
EMBER_COUNT_BIN_LO(3) = 26
EMBER_COUNT_BIN_HI(3) = 50
Some additional output switches that might work different from the ones listed above are:
TIME_AT_BURNED_ACRES(:): Output the time (mins) and runtime (s) taken for the fire to reach some amount of acres. Multiple acre values can be tracked, by including, for example, TIME_AT_BURNED_ACRES(1) = 500 and at another line TIME_AT_BURNED_ACRES(2) = 1000.
DUMP_HOURLY_RASTERS:
DUMP_BINARY_OUTPUTS: Save some outputs (ignition x, y) and additional parameters ifFULL_BINARY_OUTPUTS = .TRUE.(time of arrival, flame length, velocity, crown fire) in binary format. Only for fire areas larger thanMINIMUM_AREA_FOR_BINARY_OUTPUTS = 0(standard). To save on space a limited, randomised percentage of timesteps can be written to the binary file by specifyingBINARY_OUTPUTS_DUMP_FRACTION = 1.00(default).DUMP_SPOTTING_IGNITION_TIME: (deactivated)DUMP_TIMINGS: Show individual processor timingsIf a
TIMED_LOCATIONS_CSVfile is provided in the&INPUTSnamelist, then for all points specified in the csv (rows of point ID, X dimension, Y dimension), the arrival time of the fire will be saved in a newTIMED_LOCATION_TRACKER_1.csv.
ELMFIRE initially outputs all raster data as BIL rasters, a line-separated raster data type easy to use with FORTRAN. Then ELMFIRE converts these BIL rasters (along with their associated HDR header files) to geoTIFF files. In doing so, the BIL and HDR files are permanently deleted. This behavior can be changed by setting CONVERT_TO_GEOTIFF to .FALSE..
Virtual Weather Stations
Virtual weather stations can be specified by setting NUM_VIRTUAL_STATIONS to an integer greater than zero, and then specifying x and y coordinates of each station. As a simple example, data from two virtual stations would be written to disk by adding the following lines to the &OUTPUTS namelist group:
NUM_VIRTUAL_STATIONS = 2
VIRTUAL_STATION_X(1) = 12345.0
VIRTUAL_STATION_Y(1) = 67890.0
VIRTUAL_STATION_X(2) = 98765.0
VIRTUAL_STATION_Y(2) = 43210.0
The index inside the parentheses denotes the station number. For each virtual station a separate .csv file will be written that includes transient and fixed quantities as a function of time. These quantities are currently:
Elevation
Slope
Aspect
Canopy Bulk Density
Canopy Base Height
Canopy Cover
Canopy Height
Fuel model
1-hour dead fuel moisture
10-hour dead fuel moisture
100-hour dead fuel moisture
Live herbaceous fuel moisture
Live woody fuel moisture
Foliar fuel moisture
20-ft wind speed
20-ft wind direction
Phi (level set variable)
Note that virtual stations have been temporarily disabled.
Miscellaneous
Custom fuel models, of either vegetated or building fuels, can be specified by including related .csv files, following from fuel_models.csv. The csv files contain a series of fuel parameters. The location of these files is in the folder MISCELLANEOUS_INPUTS_DIRECTORY, and named FUEL_MODEL_FILE.csv and BUILDING_FUEL_MODEL_FILE.csv. The FUEL_MODEL_FILE.csv has the following structure:
1,FBFM01,.FALSE.,0.034,0,0,0,0,3500,9999,9999,1,12,8000
Corresponding to:
Fuel Number: 1
Fuel Name: FBFM01
Dynamic Fuel: No
1h Fuel Load: 0.034 \(lb\; ft^{-2}\)
10h Duel Load: 0 \(lb\; ft^{-2}\)
100h Fuel Load: 0 \(lb\; ft^{-2}\)
Live Herbaceous Fuel Load: 0 \(lb\; ft^{-2}\)
Live woody Fuel Load: 0 \(lb\; ft^{-2}\)
1h Surface Area to Volume Ratio (SAV): 3500 \(ft^2 ft^{-3}\)
Live and Dead Herbaceous SAV: 9999 \(ft^2 ft^{-3}\)
Live Woody SAV: 9999 \(ft^2 ft^{-3}\)
Fuel Load Depth: 1.0 ft
Dead Fuel Moisture of Extinction: 12 %
Heat Content: 8000 \(BTU\;lb^{-1}\)
Hardcoded values within ELMFIRE are the same for all fuel models:
10h SAV: 109 \(ft^2 ft^{-3}\)
100h SAV: 30 \(ft^2 ft^{-3}\)
Particle Density: 32 \(lb\;ft^{-3}\)
Total Mineral Content: 0.055
Effective Mineral Content: 0.01
A building fuel model would look like:
1,ST01,300,400,10080,14400,360,25,10500,9,0.89,8,0.5,100,0.0,20
Corresponding to:
Fuel Number: 1
Fuel Name: ST01
Time to HRR of 1 MW: 300 s
HRR Rise Time: 400 s
HRR Peak Time: 10080 s
FRR Decay Time: 14400 s
Fuel Load: 360
Peak HRR Per Unit Area: 25 \(kW/m^2\)
Critical FTP: 10500
Q Critical: 9
Absorptivity: 0.89
Building Height: 8 m
Nonburnable fraction: 0.5
Probability of ignition from firebrands: 100 %
Ember Ignition Hardening Factor: 0
Time to ignition from Embers: 20 s
For temporary file storage and intermediate saves, ELMFIRE can use a scratch directory instead of the output directory. This folder can be specified using the SCRATCH variable. By default, this folder is used to store intermediate geospatial files. ELMFIRE converts the input geoTIFF files to binary, easier-to-process BSQ files. BSQ files come with associated XML or HDR files containing their metadata. If, for any reason, the BSQ files can be provided directly instead of the geoTIFF files (which would slightly speed up the initial data processing step), they can be used in ELMFIRE by setting USE_EXISTING_BSQS = .TRUE. in the &INPUT namelist. ELMFIRE will then search for associated XML metadata files, but this can be switched to HDR files through USE_BSQ_XML_HEADER = .FALSE.. If you want to clear out the scratch directory after the simulation is finished, set CLEAN_SCRATCH = .TRUE. in the &SIMULATOR namelist.
In some use cases of ELMFIRE, the fire domain may be split into multiple files. Specifically, there are cases where the ignition is within the landscape of one geotiff file, but the overall burn area is extended to eight additional, neighboring rasters. Should this be the case, USE_TILED_IO can be set to .TRUE., and ELMFIRE will combine the fire landscape from the eight input files. These files should be named, using aspect as an example, asp_1_2.tif, where 1 and 2 refer to the rasters position in space. In this case, this raster would be the top-middle part of the landscape. The files should range from asp_1_1.tif to asp_3_3.tif.
The location that contains gdal functions and programs is assumed to be usr/bin/. If that is not the case, the location can be changed through PATH_TO_GDAL.
Parallelisation and MPI
ELMFIRE has been constructed from the ground up with the primary purpose of being used with multiple cores in local or distributed computing systems. To this end, if ELMFIRE is given multiple cores to use, the reading of input files is parallellized and, should multiple cases be specified, those cases run parallel with a shared internal memory. This is particularly useful with input raster pertrubation, probabilistic averaging (in the case of firebrands and initial attack probability) and multiple weather band combinations. The use of parallelisation substantially decreases computational time with a little extra memory overhead (as each case requires its own output rasters in memory). Theoretically as all the cases are near-independent of each other, there should not be a decrease in marginal gain per core used (although any excess cores in relation to total number of cases will not be contributing to the computational time). Memory is shared between all cores in a host (i.e. physical machine / server rack), but some extra work is required if the cores are distributed between hosts. ELMFIRE offers the MULTIPLE_HOSTS input in the &SIMULATOR namelist (.FALSE. by default) that can be set to .TRUE. to deal with memory sharing across hosts.
All examples below apply to single-host instances. To run ELMFIRE in parallel you can and should use MPI through:
mpiexec -n 48 elmfire elmfire.data
The above script will run ELMFIRE with the input script elmfire.data and 48 allocated cores.
MPI has many options and input arguments you can play around with to change the behavior of the distributed cores. Though no other settings or inputs are needed to run an ELMFIRE simulation, one useful one is the oversubscribe option that allows physical (hardware) cores to act as multiple computational nodes. This might be a worthwhile addition it for example, you have a simulation with 1000’s of simple/fast simulations and only 16 cores in your system. If you try to specify more cores than are available in the system, MPI will throw an error.
mpiexec --oversubscribe -n 48 elmfire elmfire.data
For a robust, boilerplate MPI command that you can use with ELMFIRE, the following one helps avoid any dynamic reallocation of cores, distribution of cores, and add data transfer protocols. More details about these options can be found online. Note that mpirun and mpiexec are essentially identical and interchangeable in running ELMFIRE. The below command also reroutes the console output of elmfire to a file called elmfire.out.
mpirun --mca btl tcp,self,vader --map-by core --bind-to core --oversubscribe -np 48 elmfire elmfire.data >& elmfire.out
Physics and Numerics options
Runtime options are specified via the &SIMULATOR namelist group. Brief descriptions of how various parameters influence physics options are presented below.
Feedback level
The verbosity level of ELMFIRE can be controlled by the option FEEDBACK_LEVEL (Formerly DEBUG_LEVEL). It can be set to any integer level between 0 and 3. Feedback level 0 only returns the bare necessary outputs to show that ELMFIRE is progressing. Feedback level 1 introduces live updates of the progress of the cases, particularly when each one starts (when multiple cases are ran in parallel) and the current timestep of a case (when only one is run serially). Feedback level 2 adds some statements that describe the progression of fire potential mode (MODE = 2 or 3). Feedback level 3 adds all print statements, including status updates for all concurrent cases running in level set. Feedback level 3 is usually piped to a file instead of the terminal, that helper scripts (not provided as of yet) can use to keep track of the progression of multiple level set cases.
Elliptical dimensions
In ELMFIRE, every point along the fire front behaves as an independent elliptical wavelet (Huygens principle). However, since the underlying surface fire spread model only provides the rate of spread in the head fire direction, the assumed elliptical fire shape is used to calculate spread rates in other directions. A key parameter is the ellipse’s length to width ratio, which is estimated as a function of wind speed from an empirical correlation. The maximum allowable value of the length to width ratio is specified with the keyword MAX_LOW (default value of 8). Setting this to a lower value can prevent cigar shaped fires under high winds. The midflame windspeed, calculated internally in ELMFIRE, is first calculated in ft/min, but must be converted to m/s for the LOW calculation. The conversion is done through the WSMFEFF_LOW_MULT multiplier in the &SIMULATOR namelist, equal to 0.00507955 as standard. The user can change this for calibration or optimization.
In calculating the elliptical dimensions of fire spread, the individual wind and slope components of fire spread influence need to be calculated. A factor is included in each one to enhance or reduce the influence of wind and slope on the final rate of spread magnitude and direction, PHIW_ADJ and PHIS_ADJ respectively. Both are set to 1 as standard, in the &SIMULATOR namelist.
Crown fire
The keyword CROWN_FIRE_MODEL can be used to enable or disable crown fire initiation and spread. By default, CROWN_FIRE_MODEL=1 and crown fire spread rate is calculated from Cruz et al. 2005. Crown fire can be disabled by setting CROWN_FIRE_MODEL=0. In certain cases, crown fire spread rates may be over-predicted, so an upper limit on spread rate can be specified via CROWN_FIRE_SPREAD_RATE_LIMIT, which has a default value of 250 ft/min. Since crown fire may not always propagate in discontinuous canopies, the keyword CRITICAL_CANOPY_COVER is used to specify the minimum canopy cover at which crown fire occurs. The default value is 0.39 (note that this is a fraction, not a percent). The overall calculated crown fire rate of spread can be manually adjusted through the CROWN_FIRE_ADJ variable, as standard set to 1.0.
Wind fluctuations
Wind fluctuations, disabled by default, can be enabled by setting WIND_FLUCTUATIONS = .TRUE.. Doing so directs ELMFIRE to perturb the wind field (speed and direction) in every cell in the computational domain every DT_WIND_FLUCTUATIONS seconds, 15 as standard. The wind speed perturbation is the current wind speed multiplied by WIND_SPEED_FLUCTUATION_INTENSITY multiplied by a randomly generated floating point number between -0.5 and +0.5. As an example, if the current wind speed is 10 mph and WIND_SPEED_FLUCTUATION_INTENSITY is 0.2, then the perturbed (post-fluctuation) wind speed will be between 9.0 mph and 11.0 mph. Wind direction fluctuations are implemented similarly, except that WIND_DIRECTION_FLUCTUATION_INTENSITY specifies the maximum magnitude of the wind direction fluctuation in degrees. For example, if the current wind direction is 90 degrees and WIND_DIRECTION_FLUCTUATION_INTENSITY = 20.0, then the perturbed (post-fluctuation) wind speed would be between 80-100 degrees. Essentially, WIND_SPEED_FLUCTUATION_INTENSITY is a relative value whereas WIND_DIRECTION_FLUCTUATION_INTENSITY is an absolute value in degrees.
Miscellaneous inputs
Fire front expansion calculations are performed only in voxels/grid cells surrounding the fire front (narrow band level set method). The number of voxels on either side of the fire front is controlled by the parameter BANDTHICKNESS (default value of 2). It is normally unnecessary to adjust this parameter.
The parameter RANDOMIZE_RANDOM_SEED controls the seed used to initialize the random number generator. By default, RANDOMIZE_RANDOM_SEED = .FALSE. and the random number generator is initialized using the SEED value as specified in the &MONTE_CARLO namelist group. If RANDOMIZE_RANDOM_SEED = .TRUE., then the random number seed is generated from the system clock.
A maximum wall runtime can be setup in ELMFIRE to stop simulations that take excessively long to complete through the MAX_RUNTIME option.
A DEBUG_LEVEL option is available, that, if set to an appropriately high level, provides extra information during the simulation. Right now its only function is to provide some additional information while reading BSQ rasters, if set to a value above 100.
Cell Untagging
ELMFIRE keeps track of and checks all the cells that are currently burning. This can create a large array of cells that need to be checked, especially in larger rasters. To decrease the computational load, a maximum of 100 cells are retained at a time. At simulation intervals of UNTAG_CELLS_TIMESTEP_INTERVAL (10 iterations as standard, not seconds), the total number of burning cells is checked, and if more than 100 are tracked, an untagging method is called. This method untags cells if any of the following are true:
They have been tagged for more than 1 week
They are an isolated cell with no tagged neighbors
They are surrounded by cells within the fire area
Their arrival time is greater than 20 hours (Activated by UNTAG_TYPE_2 = .TRUE.)
They are classified as burned and have a \(\phi\) value equal to -1 (Activated by UNTAG_TYPE_3 = .TRUE.)
End Conditions
An ELMFIRE simulation can stop for a variety of reasons. Some of the reasons are straightforward (like reaching a time limit), some are safeguards to prevent cases taking up resources for too long, and some are smart conditions aimed at automatically haulting a stalled fire front. The following list outlines all the ways that an ELMFIRE level set simulation is halted (without an error):
Elapsed time reaches SIMULATION_TSTOP: The standard way a level set simulation ends is by reaching its allocated elapsed time.
Simulation starts on a nonburnable cell: The ignition cell must be on a cell that can sustan fire spread, otherwise the simulation quits on startup.
Initial attack containment successful: If suppression is turned on, and initial attack is turned on, a random number is used along with the calculated chance of successful containment upon initial attack. That randon number can then reflect the containment of the fire, haulting the simulation.
Less than 2 nodes tagged for fire spread: If there are no firebrands currently in motion, and less than two pixels on the landscape are currently candidates to sustain fire spread, the simulation halts.
Burned acreage reaches total acreage limit: Users can specify an upper burned area limit that gets checked each timestep. The simulation stops when this area limit is reached.
Elapsed wall time reaches MAX_RUNTIME: To ensure that a stuck or really slow simulation does not hog computational resources, a MAX_RUNTIME argument is used that compares the elapsed wall (real) time of the simulation to the set maximum. The simulation stops if the elapsed time crosses this maximum limit.
Stalled fire front: If all ignitions have been applied and there are no firebrands in flight, and the phi-field does not change between timesteps, the fire spread is considered stalled. This can happen if the fire is bound on all sides by the simulation domain or nonburnable cells and barriers. If this occurs, the simulation is stopped early. This feature can be used with single-band weather inputs and a really large simulation time (automatically capped at the largest int32 value internally) to emulate a Minimum Travel Time algorithm.
Barriers and Breaching
Unburnable fire breaks such as roads, rivers, railroad lines and others can stop the spread of wildfires. Sometimes these landscape features are wide enough to be represented in the fuel raster, but most of the times they are too small compared to the fuel raster cell size and effectively disappear. This is especially important with flank- and backfire spread, where even narrow fire breaks can be enough to stop the fire spread. ELMFIRE uses the same models as Prometheus [28], using expert opinion and empirical evidence. The main breaching rule is that fire stops spreading when it encounters a barrier with width more than 1.5 times the flame length.
Barriers are read by ELMFIRE as a raster file, with each pixel of the raster having a value equal to the width of the barrier that crosses it. This file is usually generated by rasterizing an equivalent line vector files of roads, rivers, fuel breaks etc. To enable the use of barriers, set USE_BARRIERS = .TRUE. in the &INPUTS group, along with the BARRIER_FILENAME (again omitting the .tif ending).
Note that this setting only applies to surface fire spread. Barriers can still be breached by firebrands if their landing distance is high enough. Right now, the barrier part of ELMFIRE has no effect on the spotting calculations. Also note that enabling spotting forces BANDTHICKNESS = 1, which does not affect the rate of spread of the fire, but does tend to produce more polygonal fire isochrones.
Spotting
Spotting is a major, often dominant, mode of fire propagation particularly under hot, dry, windy conditions. Parameters that control spotting are specified on the &SPOTTING namelist group. Note that the current spotting model is different from the spotting model described in the original ELMFIRE paper. Make sure to include USE_SUPERCEDED_SPOTTING = .FALSE. to use the spotting methods in this guide. Spotting is disabled by default and can be enabled by setting ENABLE_SPOTTING = .TRUE. in the &SPOTTING namelist group. For the purposes or debugging or isolating the spotting model of ELMFIRE, NO_SURFACE_FIRE = .TRUE. can be set to disable surface fire spread, and (by setting an initial \(\phi\) input representing a burning area) the spotting model can be tested without fire spread.
ELMFIRE breaks down the spotting procedure into its subsequent steps, namely generation, transport, accumulation and ignition. Each of these four parts has configurable models and options that will be summarized and expanded upon in the next sections.
Generation
By default, when ENABLE_SPOTTING= .TRUE., only pixels that burn as passive or active crown fire trigger the spotting algorithm. The keyword controls spotting initiation from passive/active crown fire pixels, meaning if it is set to 1.0 then 1 out of every 100 pixels that burn as crown fire will initiate the spotting algorithm. Surface fire spotting may be enabled by setting ENABLE_SURFACE_FIRE_SPOTTING = .TRUE.. Ember generation is treated analogously to crown fire ember generation, except that the surface fire ember generation probability is controlled by the keyword SURFACE_FIRE_SPOTTING_PERCENT(:). The index for the array SURFACE_FIRE_SPOTTING_PERCENT(:) is fuel model number so that surface fire spotting initiation can be controlled by fuel model. As an example, the following lines would disable surface fire spotting for all fuel types except for fuel models 141 - 149 (shrub fuel models in the conventional US system):
SURFACE_FIRE_SPOTTING_PERCENT( 1:140) = 0.0
SURFACE_FIRE_SPOTTING_PERCENT(141:149) = 1.0
SURFACE_FIRE_SPOTTING_PERCENT(150:256) = 1.0
A global parameter can also be set to set all the fuels to a specific value via GLOBAL_SURFACE_FIRE_SPOTTING_PERCENT. The keyword CRITICAL_SPOTTING_FIRELINE_INTENSITY (default value of 0.0) is the fireline intensity in units of kW/m below which surface fire spotting does not occur. This parameter has no impact on crown fire spotting.
Note that another set of parameters controls spotting behavior for different fuels. GLOBAL_SURFACE_FIRE_SPOTTING_PERCENT_MAX and GLOBAL_SURFACE_FIRE_SPOTTING_PERCENT_MIN define the probability of emitting firebrands from all cells as a percentage. The two parameters set the upper and lower bounds of the probability. The simulator selects a random value within these bounds during simulation to introduce perturbations.
Another parameter that may affect the simulation is EMBER_SAMPLING_FACTOR. This is the number of real firebrands represented by each individual numerical particle. This option should be used with the first version of the transport algorithm, which traces the trajectory of each particle generated from a cell. By default, EMBER_SAMPLING_FACTOR = 1, meaning the simulator traces every generated firebrand. However, because each cell may generate a significant number of real firebrands, by setting EMBER_SAMPLING_FACTOR = 10, for example, one numerical particle represents 10 real firebrands. This method is valid when the number of firebrands is large enough that fewer particles can still approximate the ground-level distribution of the firebrands. If the second version of the firebrand transport algorithm is adopted, typically EMBER_SAMPLING_FACTOR should not be specified.
The number of embers generated in every selected cell per timestep can be controlled through three available models. The first model is activated via GENERATION_MODEL = ’RANDOM’. The number of embers that is generated is determined randomly as constrained by the keywords NEMBERS_MIN and NEMBERS_MAX. More specifically, the number of embers generated will be uniformly sampled from a distribution bounded by NEMBERS_MIN and NEMBERS_MAX.
&SPOTTING
ENABLE_SPOTTING = .TRUE.
USE_SUPERSEDED_SPOTTING = .FALSE.
GENERATION_MODEL = 'RANDOM'
CROWN_FIRE_SPOTTING_PERCENT = 100
ENABLE_SURFACE_FIRE_SPOTTING = .FALSE.
NEMBERS_MIN = 1
NEMBERS_MAX = 10
...
/
A more physical ember generation option is available in ELMFIRE. By setting GENERATION_MODEL = ’PER-AREA’, the number of generated firebrands will no longer be controlled by prescribed maximum and minimum values. Instead, spotting generation is controlled by an ember generation rate, EMBER_GR (= 0.001 \(\text{embers}\:m^{-2}\:s^{-1}\) as default) and the total time that a cell emits firebrands for after ignition TAU_EMBERGEN (= 6 s as default).
&SPOTTING
ENABLE_SPOTTING = .TRUE.
USE_SUPERSEDED_SPOTTING = .FALSE.
GENERATION_MODEL = 'PER-AREA'
CROWN_FIRE_SPOTTING_PERCENT = 100
ENABLE_SURFACE_FIRE_SPOTTING = .FALSE.
EMBER_GR = 0.1
TAU_EMBERGEN = 5
...
/
The following parameters define a firebrand generation scenario with a customized firebrand generation duration (1 hour=3600 seconds) and rate \((10 pcs/s/m^2)\). EMBER_SAMPLING_FACTOR is set to 1, which is the default value. To illustrate, we also enable surface fire spotting, with spotting probability between 80% and 100% for all fuels except 91 (1%) and 102 (0%), after surpassing the fireline intensity threshold of 0 \(kw/m^2\):
&SPOTTING
ENABLE_SPOTTING = .TRUE.
USE_SUPERSEDED_SPOTTING = .FALSE.
GENERATION_MODEL = 'PER-AREA'
CROWN_FIRE_SPOTTING_PERCENT = 100
TAU_EMBERGEN = 3600.0
EMBER_GR = 10
EMBER_SAMPLING_FACTOR = 1.0
ENABLE_SURFACE_FIRE_SPOTTING = .TRUE.
GLOBAL_SURFACE_FIRE_SPOTTING_PERCENT_MAX = 80.0
GLOBAL_SURFACE_FIRE_SPOTTING_PERCENT_MIN = 100.0
SURFACE_FIRE_SPOTTING_PERCENT_MULT(91) = 1.0
SURFACE_FIRE_SPOTTING_PERCENT_MULT(102) = 0.0
CRITICAL_SPOTTING_FIRELINE_INTENSITY(:) = 0.
...
/
As an alternative, GENERATION_MODEL can be set to ’PER-MW’, and then EMBER_GR will be calculated automatically, based on a customized value for ember generation per MW of the fire. The default value is 33.3 for vegetated fuels, and 10 for building fuels. These two values can be modified by the user through EMBER_GR_PER_MW_VEGE and EMBER_GR_PER_MW_BLDG.
&SPOTTING
ENABLE_SPOTTING = .TRUE.
USE_SUPERSEDED_SPOTTING = .FALSE.
GENERATION_MODEL = 'PER-MW'
CROWN_FIRE_SPOTTING_PERCENT = 100
...
/
The total time that a burning cell will be emitting embers for is set through TAU_EMBERGEN (=6 seconds by default). The switch USE_PHYSICAL_SPOTTING_DURATION can be set to .TRUE. to calculate a more physical total emission value, especially for the building models. For vegetated models, the burn duration is dictated by the rate of spread of the fire and the dimension of computational cell.
Transport
Currently there is a variety of methods that can be used to simulate ember transport. The simplest one can be called with SPOTTING_DISTANCE_MODEL = ’UNIFORM’, using the example below. We varied some other parameters as an example as well.
&SPOTTING
ENABLE_SPOTTING = .TRUE.
USE_SUPERCEDED_SPOTTING = .FALSE.
CROWN_FIRE_SPOTTING_PERCENT = 1.0
ENABLE_SURFACE_FIRE_SPOTTING = .TRUE.
SURFACE_FIRE_SPOTTING_PERCENT(:) = 1.0
CRITICAL_SPOTTING_FIRELINE_INTENSITY = 2000.0
GENERATION_MODEL = 'RANDOM'
SPOTTING_DISTANCE_MODEL = 'UNIFORM'
MIN_SPOTTING_DISTANCE = 60
MAX_SPOTTING_DISTANCE = 90
NEMBERS_MIN = 1
NEMBERS_MAX = 1
...
/
With the Uniform option, the spotting distance will be determined as a random number between, and including MIN_SPOTTING_DISTANCE and MAX_SPOTTING_DISTANCE.
Another option for the spotting distance calculation is with SPOTTING_DISTANCE_MODEL = ’LOGNORMAL’, which treats firebrand landing as a lognormal probabilistic density function. Spotting distance is modeled as a lognormal distribution with the mean value determined semi-empirically as a function of an empirical value MEAN_SPOTTING_DISTANCE, ambient wind speed and fireline intensity. The standard deviation is calculated using the NORMALIZED_SPOTTING_DIST_VARIANCE parameter. Shown below is a sample spotting configuration:
&SPOTTING
ENABLE_SPOTTING = .TRUE.
USE_SUPERCEDED_SPOTTING = .FALSE.
CROWN_FIRE_SPOTTING_PERCENT = 1.0
ENABLE_SURFACE_FIRE_SPOTTING = .TRUE.
SURFACE_FIRE_SPOTTING_PERCENT(:) = 1.0
CRITICAL_SPOTTING_FIRELINE_INTENSITY = 2000.0
GENERATION_MODEL = 'RANDOM'
SPOTTING_DISTANCE_MODEL = 'UNIFORM'
NEMBERS_MIN = 1
NEMBERS_MAX = 1
MEAN_SPOTTING_DIST = 5.0
NORMALIZED_SPOTTING_DIST_VARIANCE = 250.0
...
/
In this case, the one firebrand generated in potential cells will travel a random distance dictated by a lognormal PDF with some mean value and a variance of 250. The actual mean value is dependent on the wind speed and fireline intensity. Refer to the mathematical section User-Defined Lognormal Distribution. To provide an example, with with of 6 \(m/s\) and fireline intensity of 300 \(kw/m\), the resulting mean spotting distance is 87m. The correlation factors SPOT_WS_EXP and SPOT_FLIN_EXP can be changed from their standard values of 0.9 and 0.5 respectively if needed. Of course, both this and the UNIFORM option require the user to make assumptions regarding the distribution of firebrand landings.
A third option exists for estimating spotting travel distance, activated through SPOTTING_DISTANCE_MODEL = ’EMPIRICAL’. This activates the spotting model developed by UMD, which uses the pre-configured lognormal PDFs developed by Sardoy et al. [24] for vegetative fuels and by Himoto et. al. [12] for structural fuels. Both models use the 10 m wind speed, fireline intensity and Froude number to calculate PDF parameters. The user needs to input minimal new information for this spotting function. Parameters of the PDF in this mode is not editable by the users, but the users have the option to define the maximum travel distance of the firebrands by the parameter P_EPS. This value is the top 0.1% value of the PDF, i.e., the (1-P_EPS)’th percentile of the prescribed PDF. The default value of P_EPS is 0.01, i.e., the 99th percentile of the prescribed PDF.
&SPOTTING
ENABLE_SPOTTING = .TRUE.
USE_SUPERSEDED_SPOTTING = .FALSE.
GENERATION_MODEL = 'PER-MW'
SPOTTING_DISTANCE_MODEL = 'EMPIRICAL'
...
/
To test whether the ’EMPIRICAL’ mode is properly coupled with the other spotting functionalities, a fixed set of lognormal distribution parameters can be specified for diagnostic purposes. This avoids the effects of variable heat release rate (HRR) and wind speed on the ember deposition distribution. To do so, set USE_CUSTOMIZED_PDF = .TRUE. and select SPOTTING_DISTANCE_MODEL = ’EMPIRICAL’. The parameters MU_CROSSWIND and SIGMA_CROSSWIND specify the mean and standard deviation of the crosswind ember distribution, while MU_DOWNWIND and SIGMA_DOWNWIND specify the logarithm of the corresponding values for the downwind ember deposition distribution. An example namelist is shown below:
&SPOTTING
ENABLE_SPOTTING = .TRUE.
USE_SUPERSEDED_SPOTTING = .FALSE.
GENERATION_MODEL = 'PER-MW'
SPOTTING_DISTANCE_MODEL = 'EMPIRICAL'
P_EPS = 0.01
USE_CUSTOMIZED_PDF = .TRUE.
MU_CROSSWIND = 0.0
SIGMA_CROSSWIND = 0.0
MU_DOWNWIND = 0.0
SIGMA_DOWNWIND = 0.0
/
There is an additional option to disable firebrand dispersion in the crosswind direction. In some applications, crosswind spreading is negligible, or it may be desirable to simplify diagnostic or verification cases focusing on downwind transport only. This option can be enabled by specifying CROSSWIND_DISPERSION = .FALSE..
Accumulation
The user can also choose the way in which the landing of firebrands is calculated. The two options are Lagrangian (treating each generated firebrand as one explicitly solved particle) and Eulerian (treating the firebrands as a flux, that is deposited in separate cells). The user can specify which one to use through ACCUMULATION_MODEL = ’LAGRANGIAN’ or ’EULERIAN’.
The Lagrangian model solves the flight path of each individual generated firebrand. The path follows the streakline of a particle originated from the firebrand-emission source and has a probabilistic length determined by the PDF. It is then allowed to land to a cell and has a subsequent chance to start a new spot fire.
An alternative, and more numerically robust method (that later relies less on user-determined ignition probability) uses the Eulerian model, which does not track individual firebrands for ignition, but rather keeps track of the ember flux into each area.
As the choice of accumulation model is a critical part of the entire spotting submodule, there are parts of the spotting model that only work with the Lagrangian or the Eulerian model. There are ongoing efforts to make all the spotting submodels interoperable. Until then there are some limitations of the combinations of models that can be used. Right now, the most notable limitation is that SPOTTING_DISTANCE_MODEL = ’UNIFORM’ only works with ACCUMULATION_MODEL = ’LAGRANGIAN’. Other than this, all other combinations are valid.
&SPOTTING
ENABLE_SPOTTING = .TRUE.
USE_SUPERSEDED_SPOTTING = .FALSE.
GENERATION_MODEL = 'PER-MW'
SPOTTING_DISTANCE_MODEL = 'EMPIRICAL'
ACCUMULATION_MODEL = 'EULERIAN'
...
/
Ignition
ELMFIRE provides three methods of calculating if and when a landed firebrand (or total firebrand flux) will result in ignition.
The simplest model can be set through IGNITION_MODEL = ’DIRECT’. Once the particle has landed, the ignition probability (probability of setting \(\phi\) to -1 upon landing) is controlled by the keyword PIGN (%), with no delay. To avoid allocating computational time to tracking embers that don’t initiate spot fire, it is most computationally efficient to set PIGN to 100% and then set CROWN_FIRE_SPOTTING_PERCENT to a small number. As an example, CROWN_FIRE_SPOTTING_PERCENT = 50.0 and PIGN = 10.0 will produce comparable results to CROWN_FIRE_SPOTTING_PERCENT = 5.0 and PIGN = 100.0, but the computational expense of the spotting algorithm is reduced by a factor of approximately 10x in the latter case. An additional multiplier can be added to this calculation, SURFACE_FIRE_SPOTTING_PERCENT_MULT(:), for optimization or calibration.
An entry like the one below is a complete, valid spotting input:
&SPOTTING
ENABLE_SPOTTING = .TRUE.
USE_SUPERSEDED_SPOTTING = .FALSE.
GENERATION_MODEL = 'PER-MW'
SPOTTING_DISTANCE_MODEL = 'EMPIRICAL'
ACCUMULATION_MODEL = 'EULERIAN'
IGNITION_MODEL = 'DIRECT'
PIGN = 100
/
A more advanced model can be activated through IGNITION_MODEL = ’SIMPLE’. The simple model relies on a simple relation that requires the PIGN input, the local ignition time, LOCAL_IGNITION_TIME, and the firebrand ignition delay CELL_IGNITION_DELAY. To physically understand these parameters, once a firebrand flux arrives at a specific cell, PIGN is defined by the probability of a successful transition from smoldering to flaming within the time interval defined by LOCAL_IGNITION_TIME. Once the smoldering-to-flaming igntion is achieved, additional CELL_IGNITION_DELAY seconds will be required to effectively ignite the target cell (set \(\phi\) to -1), which tries to represent the development of fire to a self-sustaining scale. Both LOCAL_IGNITION_TIME and CELL_IGNITION_DELAY have preset values in ELMFIRE of 30 s and 100 s respectively.
&SPOTTING
ENABLE_SPOTTING = .TRUE.
USE_SUPERSEDED_SPOTTING = .FALSE.
GENERATION_MODEL = 'PER-MW'
SPOTTING_DISTANCE_MODEL = 'EMPIRICAL'
ACCUMULATION_MODEL = 'EULERIAN'
IGNITION_MODEL = 'SIMPLE'
PIGN = 100
/
A more complex ignition model, IGNITION_MODEL = ’PHYSICAL’, is based on physical observations of the ignition chances of firebrands. Smoldering-to-framing transition probability and time are automatically calculated and parameterized as a function of local wind speed and accumulated firebrand flux. This model reduces the need for PIGN to be specified. Note that this mode has been developed for building fuels; the vegetative fuels can be differentiated by setting DIFF_WILDLAND_IGNITION = .TRUE. in which case the vegetative fuels will definitely ignite after a delay defined by (LOCAL_IGNITION_TIME + CELL_IGNITION_DELAY) when the accumulated firebrand flux is larger than 0.
An example is given below. Note how using the options below does not require any numerical input from the user. This is the great advantage of the physical and empirical firebrand models. The user can edit any of the standard values if they so wish. Note that, although these setting have the great benefit of not requiring any user input, they greatly increase the required computational time.
&SPOTTING
ENABLE_SPOTTING = .TRUE.
USE_SUPERSEDED_SPOTTING = .FALSE.
GENERATION_MODEL = 'PER-MW'
SPOTTING_DISTANCE_MODEL = 'EMPIRICAL'
ACCUMULATION_MODEL = 'EULERIAN'
IGNITION_MODEL = 'PHYSICAL'
/
Consumption (under development)
The current version of ELMFIRE implements a simplified ember-consumption model to account for firebrand burnout after deposition. In the default configuration, firebrands are assumed to remain burning for the entire simulation duration, which may lead to unrealistic ignition behavior in some cases.
To address this limitation, a consumption model (currently under development and testing) has been introduced. This feature can be enabled by setting USE_EMBER_CONSUMPTION = .TRUE.. However, it should be noted that the present implementation may overestimate ember consumption rates, which can suppress ignition and lead to reduced or even zero effective ignition in some simulations.
Submodel Cheat Sheet
To keep track of all the available models, and the input parameters that control them, we have produced a cheat sheet that should make selection of parameters easier. Refer to Table 3 for this.
GENERATION_MODEL |
||
|---|---|---|
RANDOM* |
PER-AREA |
PER-MW |
NUMBERS_MIN |
EMBER_GR |
EMBER_GR_PER_MW_BLDG |
NUMBERS_MAX |
EMBER_GR_PER_MW_VEGE |
|
Generation time control |
||
USE_PHYSICAL_SPOTTING_DURATION |
||
TAU_EMBERGEN |
||
SPOTTING_DISTANCE_MODEL |
||
L: Available when ACCUMULATION_MODEL=LAGRANGIAN |
||
E: Available when ACCUMULATION_MODEL=EULERIAN |
||
UNIFORM (L) |
LOGNORMAL(L,E) |
EMPIRICAL**(L,E) |
MAX_SPOTTING_DISTANCE |
MEAN_SPOTTING_DIST |
P_EPS |
MIN_SPOTTING_DISTANCE |
NORMALIZED_SPOTTING_DIST_VARIANCE |
USE_CUSTOMIZED_PDF |
SPOT_FLIN_EXP |
MU_CROSSWIND |
|
SPOT_WS_EXP |
SIGMA_CROSSWIND |
|
MU_DOWNWIND |
||
SIGMA_DOWNWIND |
||
ACCUMULATION_MODEL |
||
LAGRANGIAN |
EULERIAN |
|
EMBER_SAMPLING_FACTOR |
||
IGNITION_MODEL |
||
DIRECT |
SIMPLE |
PHYSICAL |
PIGN |
PIGN |
LOCAL_IGNITION_TIME |
LOCAL_IGNITION_TIME |
CELL_IGNITION_DELAY |
|
CELL_IGNITION_DELAY |
DIFF_WILDLAND_IGNITION |
|
Stochastic Parameters
Particularly under high winds, the parameters that control spotting exert a significant influence on overall fire progression. For that reason, it is often desirable to treat these parameters stochastically and, for fire hindcasts, as calibration coefficients. Setting the parameter STOCHASTIC_SPOTTING = .TRUE. directs ELMFIRE to treat the parameters that control spotting stochastically. When STOCHASTIC_SPOTTING = .TRUE., the following eight parameters are randomly generated within a user-specified range as will be described later:
CROWN_FIRE_SPOTTING_PERCENT
GLOBAL_SURFACE_FIRE_SPOTTING_PERCENT
MEAN_SPOTTING_DIST
NEMBERS_MAX
NEMBERS_MIN
NORMALIZED_SPOTTING_DIST_VARIANCE
PIGN
SPOT_FLIN_EXP
SPOT_WS_EXP
Note that GLOBAL_SURFACE_FIRE_SPOTTING_PERCENT is applied to all fuel models. Shown below is a &SPOTTING configuration with stochastic spotting enabled and the 16 parameters that constrain the allowable range of the eight spotting parameters described above.
&SPOTTING
ENABLE_SPOTTING = .TRUE.
STOCHASTIC_SPOTTING = .TRUE.
IGNITION_MODEL = 'RANDOM'
SPOTTING_DISTANCE_MODEL = 'LOGNORMAL'
ACCUMULATION_MODEL = 'LAGRANGIAN'
IGNITION_MODEL = 'DIRECT'
CROWN_FIRE_SPOTTING_PERCENT_MIN = 0.2
CROWN_FIRE_SPOTTING_PERCENT_MAX = 0.8
ENABLE_SURFACE_FIRE_SPOTTING = .TRUE.
GLOBAL_SURFACE_FIRE_SPOTTING_PERCENT_MIN = 0.2
GLOBAL_SURFACE_FIRE_SPOTTING_PERCENT_MAX = 0.8
CRITICAL_SPOTTING_FIRELINE_INTENSITY = 2000.0
SPOTTING_DISTRIBUTION_TYPE = 'LOGNORMAL'
MEAN_SPOTTING_DIST_MIN = 5.0
MEAN_SPOTTING_DIST_MAX = 10.0
NORMALIZED_SPOTTING_DIST_VARIANCE_MIN = 250.0
NORMALIZED_SPOTTING_DIST_VARIANCE_MAX = 600.0
SPOT_WS_EXP_LO = 0.4
SPOT_WS_EXP_HI = 0.7
SPOT_FLIN_EXP_LO = 0.2
SPOT_FLIN_EXP_HI = 0.4
NEMBERS_MIN = 1
NEMBERS_MAX_LO = 1
NEMBERS_MAX_HI = 1
PIGN_MIN = 100.0
PIGN_MAX = 100.0
/
Spotting Outputs
ELMFIRE provides several output options for diagnosing spotting, ember deposition, and spot ignitions. When DUMP_SPOTTING_OUTPUTS = .TRUE., ELMFIRE writes a CSV file named spotting_stats_<case>.csv for each simulation case. Each record includes the source and destination grid cells, launch time, ignition or arrival time, and spotting distance for an explicitly tracked firebrand. This output is intended primarily for debugging the spotting trajectory model, validating spotting-distance distributions, and examining individual long-range spotting events. It is implemented for the newer Lagrangian spotting model, in which individual firebrands are explicitly tracked, and is not a useful diagnostic for the Eulerian model, which transports a spatial distribution rather than individual particles. Because the CSV files can become very large, this option should normally be enabled only for small verification cases or short simulations. When EMBER_SAMPLING_FACTOR is greater than one, the records may represent sampled firebrands rather than the full physical population.
When DUMP_EMBER_FLUX_TRANSIENT = .TRUE., ELMFIRE writes an ember_flux_transient raster at each regular output time. This raster contains the number, or expected number, of firebrands deposited in each cell since the preceding output. After the raster is written, the transient array is reset to zero; therefore, the output interval is controlled by DTDUMP. This output is useful for examining when and where firebrands arrive during a simulation, rather than only their total deposition over the complete case. Eulerian values may be fractional because they represent probability-weighted expected numbers of deposited firebrands, and small values should not be interpreted as individually resolved particles. Frequent output intervals can generate many large raster files and increase both storage and I/O costs.
When DUMP_EMBER_FLUX = .TRUE., ELMFIRE writes the cumulative number, or expected number, of firebrands deposited in each grid cell during a simulation case. This output is cumulative over simulation time, unlike DUMP_EMBER_FLUX_TRANSIENT. Lagrangian calculations generally add discrete or sampling-weighted firebrand counts, whereas Eulerian calculations add probability-weighted expected counts. This output is appropriate for identifying locations exposed to concentrated firebrand deposition and for comparing spotting exposure among cases. If ACCUMULATE_EMBER_FLUX = .TRUE., a separate accumulated raster can be used to sum deposition across Monte Carlo cases and MPI ranks. The per-case working raster must still be reset at the start of each case so that ember deposition from one ensemble member does not affect the ignition calculation of another ensemble member.
When DUMP_EMBER_IGNITION = .TRUE., ELMFIRE writes an ember_ignition_<case>_<time> raster at the final output time. Cells assigned a value of one indicate locations ignited by the spotting algorithm. This output distinguishes successful spot ignitions from cells that only received deposited firebrands. A cell with nonzero ember flux does not necessarily appear in the ember-ignition raster, because ignition also depends on the selected IGNITION_MODEL, fuel burnability, ignition probability or physical criterion, and any ignition-development delay. The ember-ignition raster should be initialized or reset for every simulation case to prevent ignition markers from an earlier Monte Carlo case from appearing in a later per-case output.
ELMFIRE can also produce Monte Carlo summaries of deposited ember counts using ember-count bins. The valid namelist parameter is NUM_EMBER_COUNT_BINS. Setting USE_EMBER_COUNT_BINS = .TRUE. enables the summary, and NUM_EMBER_COUNT_BINS specifies the number of bands in the resulting ember_bin_counts raster. The lower and upper limits of each band are specified using EMBER_COUNT_BIN_LO(i) and EMBER_COUNT_BIN_HI(i). For bin \(i\), a case is counted when its deposited firebrand count satisfies
Each output band therefore reports how many Monte Carlo cases placed that cell’s ember count within the specified interval. For example:
USE_EMBER_COUNT_BINS = .TRUE.
NUM_EMBER_COUNT_BINS = 3
EMBER_COUNT_BIN_LO(1) = 0
EMBER_COUNT_BIN_HI(1) = 10
EMBER_COUNT_BIN_LO(2) = 10
EMBER_COUNT_BIN_HI(2) = 100
EMBER_COUNT_BIN_LO(3) = 100
EMBER_COUNT_BIN_HI(3) = 32767
The bin count must be positive and cannot exceed the source-code capacity of 100. Bin intervals should be ordered, non-overlapping, and wide enough to cover the expected counts. The current counting implementation is based on explicitly landed particles and is therefore most appropriate for Lagrangian or legacy spotting. It should not be assumed to provide equivalent statistics for fractional Eulerian deposition. Enabling this option also increases memory use and MPI communication, particularly when many firebrands are tracked.
Monte Carlo Analysis
Keywords controlling Monte Carlo parameters are specified in the &MONTE_CARLO namelist group. Several types of Monte Carlo simulations can be performed with ELMFIRE. Point source ignitions may be placed randomly across the landscape, wind and weather inputs may be varied stochastically, and input rasters may be spatially and temporally perturbed. The randomisation seed can be set manually through the SEED input, if the user wants to control for randomness.
Randomized ignition locations
Setting RANDOM_IGNITIONS = .TRUE. directs ELMFIRE to conduct a Monte Carlo analysis with ignition locations distributed randomly within the computational domain. Allowable locations of those ignitions are constrained by the parameter EDGEBUFFER which is the distance from the edge of the GIS input data tile where ignitions will not be placed as shown graphically below:
Fig. 1 A graphical display of EDGEBUFFER.
Random ignition location may also be constrained by an ignition mask raster. To do this, set USE_IGNITION_MASK = .TRUE. and specify IGNITION_MASK_FILENAME on the &INPUTS line. This directs ELMFIRE to read a Float32 raster named IGNITION_MASK_FILENAME.tif from the FUELS_AND_TOPOGRAPHY_DIRECTORY. You can also build an ignition mask within ELMFIRE by automatically excluding all nonburnable cells, by setting ADD_TO_IGNITION_MASK = .TRUE.. If the user wants to include nonburnable pixels to be potential ignition spots, then set ALLOW_NONBURNABLE_PIXEL_IGNITION = .TRUE. in the &SIMULATOR namelist.
Distribution of ignitions across the landscape is controlled by the parameter RANDOM_IGNITIONS_TYPE:
RANDOM_IGNITIONS_TYPE=1 (default): Ignitions are spatially distributed uniformly across the landscape in any pixels where the ignition mask raster is greater than zero. This is useful for modeling ignitions originating from powerlines or roads, for example.
RANDOM_IGNITIONS_TYPE=2: Ignitions are spatially distributed across the landscape at a density that is proportional to the ignition mask raster. This is useful for burn probability modeling where some locations across the landscape have higher ignition probabilities than other locations. A global IGNITION_MASK_SCALE_FACTOR can be set to upscale or downscale the mask for calibration or optimization.
The number of randomly-generated ignition points can be specified in two ways:
By directly specifying NUM_ENSEMBLE_MEMBERS, or
By specifying PERCENT_OF_PIXELS_TO_IGNITE and setting NUM_ENSEMBLE_MEMBERS to a value less than 0.
In the first case, ELMFIRE will randomly generate NUM_ENSEMBLE_MEMBERS ignition locations in the allowable ignition area as defined by EDGEBUFFER (and, if USE_IGNITION_MASK = .TRUE., the user-specified ignition mask raster as well). In the second case, ELMFIRE will count all pixels within the allowable ignition area and randomly ignite the user-specified percent of those pixels. In some cases, a pixel may be selected more than once to be ignited. This can be disabled by setting ALLOW_MULTIPLE_IGNITIONS_AT_A_PIXEL = .FALSE..
Ignitions can also be set manually though a csv file with coordinates of ignitions. Setting CSV_FIXED_IGNITION_LOCATIONS = .TRUE. will instruct ELMFIRE to look for a file called IGNITIONS_CSV_FILENAME.csv within the FUELS_AND_TOPOGRAPHY_DIRECTORY folder.
The wind direction can either be changed randomly using the standard monte carlo parameters. In some cases it may be desirable for the wind to always drive the fire from its ignition point towards the center of the domain. For this case, POINT_WIND_TO_CENTER can be set to .TRUE. and the wind direction of every case will point from the ignition point to the center of the domain.
Randomized weather streams
In the example discussed in Randomized ignition locations, ignition locations are selected randomly and a single weather stream (hindcast or forecast) is provided as input to those simulations. Often, as part of a climatological fire risk analysis, it is desirable to simulate wind and weather conditions under a range of historical (or forecasted) wind and weather conditions. This can be accomplished in ELMFIRE using stacked/multiband weather/meteorology rasters.
The manner in which these rasters are used is controlled by the parameters NUM_METEOROLOGY_TIMES, METEOROLOGY_BAND_START, METEOROLOGY_BAND_STOP, and METEOROLOGY_BAND_SKIP_INTERVAL. This is perhaps best illustrated by an example. Assume that numerical weather prediction has been used to generate 100 24-hour “blocks” of historical wind/weather data at hourly intervals that will be provided as input to a Monte Carlo analysis. The goal is to simulate 24-hours of fire spread, for each of these 24-hour blocks. However, these 24-hour blocks are not temporally contiguous, meaning the first 24-hour block could be from August 1983 and the next 24-hour block could be from October 2012, and so on.
Each 24-hour block consists of 25 bands since Band 1 is \(t = 0\) and Band 25 is \(t = 24\) hours. Therefore, each meteorology raster would contain 2,500 separate bands (100 blocks \(\times\) 25 bands per block). Since ELMFIRE needs 25 bands of wind/weather data to drive each 24-hour simulation, we would set METEOROLOGY_BAND_START=1, METEOROLOGY_BAND_STOP=2476, and METEOROLOGY_BAND_SKIP_INTERVAL=25. This tells ELMFIRE to use every 25th band as the starting band for a 24-hour simulation and ensures that each 24-hour simulation starts with Band 1, 26, 51, and so on until the final 24-hour block is reached at meteorology band 2476.
If, instead, the 100 24-hour blocks were temporally contiguous (for example, a continuous hindcast from mid-July through the end of October) and the purpose of the Monte Carlo analysis is to ignite fires every 3 hours and model their spread, we would set METEOROLOGY_BAND_SKIP_INTERVAL=4.
The output of each weather band range will be saved as a separate raster file, with the band number appended at the end. This number is restricted to 3 digits, but 4 can be used by adding USE_FOUR_DIGITS_IN_IWX_BAND = .TRUE..
Spatial and temporal perturbations of input rasters
All inputs are subject to inherent uncertainty. To address this uncertainty, input rasters may be perturbed stochastically from their baseline values in a Monte Carlo analysis. Currently, the following rasters may be perturbed:
ADJ: Spread rate adjustment factor (-)
CBD: Canopy bulk density (\(kg/m^3\))
CBH: Canopy base height (m)
CC: Canopy cover (-)
CH: Canopy height (m)
FMC: Foliar moisture content (-)
M1: 1-hour fuel moisture (-)
M10: 10-hour fuel moisture (-)
M100: 100-hour fuel moisture (-)
MLH: Live herbaceous fuel moisture (-)
MLW: Live woody fuel moisture (-)
WAF: Wind adjustment factor (-)
WD: Wind direction (deg)
WS: Wind speed (mph)
Parameters controlling stochastic perturbations of input rasters are specified in the &MONTE_CARLO namelist group. A random sampling procedure is implemented such that the spatial perturbation to be applied to a given input raster sampled from a probability density function (pdf). The keyword NUM_RASTERS_TO_PERTURB prescribes the number of input rasters to be perturbed and the keyword RASTER_TO_PERTURB(:) is a string corresponding to one of the raster names in the bulleted list above (ADJ, CBD, etc.). As an example, consider the following lines:
NUM_RASTERS_TO_PERTURB = 1
RASTER_TO_PERTUB(1) = 'ADJ'
SPATIAL_PERTURBATION(1) = 'GLOBAL'
TEMPORAL_PERTURBATION(1) = 'STATIC'
PDF_TYPE(1) = 'UNIFORM'
PDF_LOWER_LIMIT(1) = -0.10
PDF_UPPER_LIMIT(1) = 0.10
These lines specify that a randomly selected value between -0.1 and 0.1 should be added to the spread rate adjustment factor(ADJ). This perturbation will be applied globally to all pixels (SPATIAL_PERTURBATION = ’GLOBAL’) and is temporally invariant for the duration of the simulation (TEMPORAL_PERTURBATION = ’STATIC’). Rather than applying such perturbations globally to all pixels, different perturbations can be applied to different pixels by setting SPATIAL_PERTURBATION = ’PIXEL’. Some raster inputs, such as wind speed and direction, are multi-band rasters that vary temporally. Different perturbations may be applied at each time by setting TEMPORAL_PERTURBATION = ’DYNAMIC’. Normally, this would only be done for wind speed and direction.
ELMFIRE now supports three kinds of statistical raster pertrubations, ’UNIFORM’, ’GAUSSIAN’ and ’LOGNORMAL’ specified by the PDF_TYPE input. The ’UNIFORM’ option selects a random pertrubation amount ranging between PDF_LOWER_LIMIT and PDF_UPPER_LIMIT. The ’GAUSSIAN’ option randomly selects a pertrubation value based on a normal (or gaussian) distribution with mean PDF_MEAN and standard deviation PDF_SIGMA. The ’LOGNORMAL’ option is a bit more complicated, as to allow for positive and negative pertrubations, a mean-shifted lognormal implementation is applied instead. The standard deviation of the lognormal curve is controlled by PDF_SIGMA and the mean shift amount is controlled by PDF_MEAN.
To visualise each of these options, the example case monte_carlo has been set up with three variables being perturbed with the three different methods:
&MONTE_CARLO
NUM_METEOROLOGY_TIMES = 72
RANDOM_IGNITIONS = .TRUE.
USE_IGNITION_MASK = .TRUE.
EDGEBUFFER = 5.
NUM_ENSEMBLE_MEMBERS = 5000
!PERCENT_OF_PIXELS_TO_IGNITE = 10
NUM_RASTERS_TO_PERTURB = 3
RASTER_TO_PERTURB(1) = 'WS'
SPATIAL_PERTURBATION(1) = 'GLOBAL'
TEMPORAL_PERTURBATION(1) = 'STATIC'
PDF_TYPE(1) = 'UNIFORM'
PDF_LOWER_LIMIT(1) = -5.0
PDF_UPPER_LIMIT(1) = 5.0
RASTER_TO_PERTURB(2) = 'WD'
SPATIAL_PERTURBATION(2) = 'GLOBAL'
TEMPORAL_PERTURBATION(2) = 'STATIC'
PDF_TYPE(2) = 'GAUSSIAN'
PDF_MEAN(2) = 0.0
PDF_SIGMA(2) = 20.0
RASTER_TO_PERTURB(3) = 'M1'
SPATIAL_PERTURBATION(3) = 'GLOBAL'
TEMPORAL_PERTURBATION(3) = 'STATIC'
PDF_TYPE(3) = 'LOGNORMAL'
PDF_MEAN(3) = 1.0
PDF_SIGMA(3) = 0.3
/
This case is run 5000 times and the pertrubation amounts are saved in the coeffs.csv file in outputs/. We have included a python script to help visualise the results and compare them with the requested distributions. Below are the results.
Fig. 2 The perturbation coefficient histograms, each using a different pertrubation method.
The number of ensemble members in the Monte Carlo analysis should be specified using the keyword NUM_ENSEMBLE_MEMBERS (&MONTE_CARLO namelist group). However, when using randomly-placed ignitions it may instead be preferable to specify the total number of ensemble members by specifying the percentage of pixels within the computational domain and possibly within a user-specified ignition mask to ignite. This is described in Randomized ignition locations.
Randomized wind fluctuation intensities
Wind fluctuations are implemented by changing PERTURB_WIND_DIRECTION_FLUCTUATION_INTENSITY = .TRUE. and PERTURB_WIND_SPEED_FLUCTUATION_INTENSITY = .TRUE. respectively. The keywords that control these fluctuations are WIND_SPEED_FLUCTUATION_INTENSITY and WIND_DIRECTION_FLUCTUATION_INTENSITY. These values can be randomized by setting the following four parameters (in the &MONTE_CARLO namelist group):
WIND_DIRECTION_FLUCTUATION_INTENSITY_MIN: Minimum wind direction fluctuation intensity value
WIND_DIRECTION_FLUCTUATION_INTENSITY_MAX: Maximum wind direction fluctuation intensity value
WIND_SPEED_FLUCTUATION_INTENSITY_MIN: Minimum wind speed fluctuation intensity value
WIND_SPEED_FLUCTUATION_INTENSITY_MAX: Maximum wind speed fluctuation intensity value
The wind fluctuation intensities are then randomly generated according to a uniform probability density function, with the upper and lower values specified by the above four parameters.
Outputs
Several outputs are specific to Monte Carlo analyses. Often, when conducting a Monte Carlo analysis with randomly distributed ignitions, it is informative to view spatial burn probabilities, defined as the fraction of simulations in which a given pixel burned. To enable this calculation (which adds some computational and network overhead), set CALCULATE_TIMES_BURNED = .TRUE. in the &OUTPUTS namelist group.
This instructs ELMFIRE to aggregate all simulated fire perimeters and calculate the burn probability across all runs and write the results to disk (in a file called burn_probability.tif). The output raster has three bands. The first is the conventional burn probability. The second is passive crown fire burn probability, meaning the fraction of times in which a pixel burned as passive crown fire. The third band is active crown fire burn probability.
During a Monte Carlo simulation, it is often useful to compute the total deposited firebrand count across all ensemble cases and MPI ranks and write the result to a single final ember-flux raster. This can be enabled by setting ACCUMULATE_EMBER_FLUX to .TRUE.
Urban Fire Spread
ELMFIRE includes two experimental building fire-spread models for WUI applications, based on the work of Hamada [11] and Purnomo et al. [18]. Most Rothermel-based models treat built-up areas as nonburnable, since urban conflagrations were not a primary concern when the model was developed. Consequently, the associated spread mechanisms and building fuel models were not included in the original framework.
The experimental models described here extend ELMFIRE to estimate surface fire spread through built-up areas in a manner analogous to the Rothermel model. The Hamada model assumes elliptical fire spread within an uniform urban community. The WU-E model provides semi-physical predictions based on the heat flux from discretized sources representing burning structures. Additional details are provided in the mathematical formulation section.
USE_BLDG_SPREAD_MODEL = .TRUE. must be set to enable either building fire-spread model. The input parameters for these models include the characteristic building footprint dimension, building separation distance, nonburnable fraction of the structure, fraction of the computational cell occupied by the building footprint, and building type. These parameters can be specified as constants over the entire simulation domain by setting USE_CONSTANT_BLDG_SPREAD_MODEL_PARAMS = .TRUE., which is the default option. The BUILDING_FUEL_MODEL_FILE must also be specified. The BLDG_SPREAD_MODEL_TYPE option is used to select the building spread model: Hamada model (1) or UCB–UMD WU-E model (2).
The Hamada and WU-E models account only for fire spread within built-up areas. Fire spread from wildland fuels into built-up areas is treated separately using one of two interface-spread options: the original formulation used by Purnomo et al. [18] (1), or a simplified formulation based on distance and fireline-intensity thresholds (2). This option is selected in the &WUI namelist using INTERFACE_MODEL_TYPE.
The corresponding universal input parameters can be set in the &WUI namelist as follows:
BLDG_AREA_CONSTANT: characteristic building footprint dimension (\(\mathrm{m}\))BLDG_SEPARATION_DIST_CONSTANT: building separation distance (\(\mathrm{m}\))BLDG_NONBURNABLE_FRAC_CONSTANT: nonburnable fraction of the structureBLDG_FOOTPRINT_FRAC_CONSTANT: fraction of the computational cell occupied by the building footprintBLDG_FUEL_MODEL_CONSTANT: building fuel model number
The equivalent raster inputs, specified in &INPUTS are:
BLDG_AREA_FILENAMEBLDG_SEPARATION_DIST_FILENAMEBLDG_NONBURNABLE_FRAC_FILENAMEBLDG_FOOTPRINT_FRAC_FILENAMEBLDG_FUEL_MODEL_FILENAME
As such, a valid part of the input file would be:
&WUI
BLDG_AREA_CONSTANT = 20.0
BLDG_SEPARATION_DIST_CONSTANT = 10.0
BLDG_NONBURNABLE_FRAC_CONSTANT = 0.9
BLDG_FOOTPRINT_FRAC_CONSTANT = 0.2
BLDG_FUEL_MODEL_CONSTANT = 2
BLDG_SPREAD_MODEL_TYPE = 2
INTERFACE_MODEL_TYPE = 1
USE_BLDG_SPREAD_MODEL = .TRUE.
USE_CONSTANT_BLDG_SPREAD_MODEL_PARAMS = .TRUE.
/
The keyword USE_BLDG_SPREAD_MODEL determines whether or not the urban fire spread is activated. The keyword BLDG_SPREAD_MODEL_TYPE corresponds to the urban fire spread model selected, 1 for Hamada model and 2 for WU-E model. The keyword USE_CONSTANT_BLDG_SPREAD_MODEL_PARAMS determines if the structure attributes are assumed to be uniform. If this parameter is set .TRUE., then the structures in the domain to be simulated have uniform attributes determined by the 5 first parameters in the &WUI namelist. All the structures in the domain will have characteristic dimension specified by BLDG_AREA_CONSTANT, separation distance by BLDG_SEPARATION_DIST_CONSTANT, burnable fraction by BLDG_NONBURNABLE_FRAC_CONSTANT, and building footprint by BLDG_FOOTPRINT_FRAC_CONSTANT. When BLDG_SPREAD_MODEL_TYPE is set to 2 (i.e., WU-E model), the structures also have attributes following the structure fuel model in building_fuel_models.csv. The value specified in BLDG_FUEL_MODEL_CONSTANT corresponds to the row number in the building_fuel_models.csv. The structure fuel model categorizes structures based on their burning behavior consisting of heat release rate (HRR) curve and heat transfer coefficients. Columns 3 to 6 correspond to the time constant in the HRR curve, column 8 corresponds to the peak HRR, column 9 corresponds to critical flux time product (FTP), column 10 corresponds to radiation absorptivity, column 11 corresponds to structure height, and column 12 corresponds to noncombustible fraction by surface area of structures. A complete example, with units and indicative values, can be found in section Miscellaneous.
If USE_CONSTANT_BLDG_SPREAD_MODEL_PARAMS is set .FALSE., the structures attributes in the domain will become nonuniform and are specified based on input rasters, which are declared in the &INPUTS namelist as the following:
BLDG_AREA_FILENAME: Structure area, m² (32-bit floating)
BLDG_FOOTPRINT_FRAC_FILENAME: Structure footprint fraction (32-bit floating)
BLDG_FUEL_MODEL_FILENAME: Structure fuel model in a cell (16-bit integer)
BLDG_NONBURNABLE_FRAC_FILENAME: Nonburnable fraction of structure in a cell (32-bit floating)
BLDG_SEPARATION_DIST_FILENAM: Separation distance, m (32-bit floating)
One important thing to highlight is the effect of roadways to WU-E. In the original LANDFIRE data, roadways are classified as fuel type 91, grouping them with urban cells. To differentiate between roadways and structures within these urban cells, roadway data such as from the Natural Earth public repository can be overlaid on the fuel type data. Initially, all urban cells, including structures and paved surfaces, were classified as fuel type 91, which is “burnable” when the urban fire spread model is enabled. However, by using the roadway data, cells containing paved areas can be identified and separated from those containing buildings. Urban cells without major roads were reclassified as “burnable”, indicating the presence of structures that are susceptible to fire.
Cloudfire provides a tool for creating the required raster inputs for a urban fire spread simulation that takes into account the separation of roads and structures. It uses global data sources for most of the required parameters, and US-based data sources for a complete dataset. The tool makes conducting urban fire spread simulation much easier and feasible without extensive knowledge of the target area’s layout. The tool can be found at https://github.com/ma-th/firedx.
In the most recent version, a new parameter is introduced in &WUI namelist: HRR_ELLIPSE_ADJ. This parameter control the effective area of the flame ellipse affecting heat transfer to subsequent structures. A default value of 0.5 is used here; in future, this can be subject to calibration.
Note that the WU-E model employs an algorithm in which only fuels within a finite distance are considered WUI fuels and are included in the heat-flux contribution to structural fuels. This approach facilitates fire spread between regular wildland fuels, typically represented by wildland fire models (e.g., Rothermel-based models), and structural fuels.
This distance is defined by a user-specified parameter in the &WUI namelist, BANDTHICKNESS_WUI. By default, BANDTHICKNESS_WUI = 5, corresponding to a neighborhood of computational cells within an 11 \(\times\) 11 cell square centered on each structural cell. Increasing this parameter allows heat-flux contributions from more distant vegetative fuels to be included, but it also significantly increases computational cost.
For typical applications with a grid resolution of approximately 30 m, BANDTHICKNESS_WUI values between 3 and 5 are generally sufficient.
Apart from the outputs that can be generated by the original ELMFIRE, when WU-E model is activated (BLDG_SPREAD_MODEL_TYPE is set to 2), additional outputs on HRR and incident heat flux can be generated as the following:
DUMP_TOTAL_DFC_RECEIVED: total accumulated incident energy from direct flame contact (\(\mathrm{kJ}/\mathrm{m}^2\))DUMP_TOTAL_RAD_RECEIVED: total accumulated incident energy from radiation (\(\mathrm{kJ}/\mathrm{m}^2\))DUMP_TRANSIENT_DFC: incident heat flux from direct flame contact (\(\mathrm{kW}/\mathrm{m}^2\))DUMP_TRANSIENT_RAD: incident radiative heat flux (\(\mathrm{kW}/\mathrm{m}^2\))DUMP_FUEL_CONSUMPTION: total consumed structural fuel load at a given time (\(\mathrm{kJ}/\mathrm{m}^2\)). Fuel consumption is allowed only when the total accumulated incident energy from direct flame contact and radiation exceeds the critical heat-flux threshold specified byCRITICL_HF_WUIin the&WUInamelist. The current consumption model is a placeholder for future development.DUMP_HRR_TRANSIENT: heat release rate per unit area at a given time (\(\mathrm{kW}/\mathrm{m}^2\))
Extra outputs can be specified with the building spread model. Turning ESTIMATE_URBAN_LOSSES = .TRUE. in the &OUTPUTS namespace will include the results of the building fire spread to the affected population and surface fire area statistics.
Suppression
ELMFIRE can represent the effects of wildfire suppression on the advancing fire front. The suppression module does not simulate individual firefighting resources or tactical actions explicitly. Instead, it provides simplified representations of initial attack and extended attack that modify fire growth and containment during a simulation.
Initial Attack
Initial attack can be activated through the switch ENABLE_INITIAL_ATTACK in the &SUPPRESSION namelist. The attack time is specified using INITIAL_ATTACK_TIME in seconds. At the specified time, ELMFIRE estimates the probability of successful initial attack based on the current fire area and average fireline intensity. If the initial attack successfully contains the fire, the simulation terminates.
Extended Attack
Extended attack is activated by setting
ENABLE_EXTENDED_ATTACK = .TRUE.
Two extended-attack formulations are available through EXTENDED_ATTACK_MODEL:
EXTENDED_ATTACK_MODEL = 0: area-growth-based containment model;EXTENDED_ATTACK_MODEL = 1: spatially explicit suppression model.
Area-Growth-Based Extended-Attack Model
An example configuration for the Area-Growth-Based containment model is
&INPUTS
...
SDI_FILENAME = 'sdi'
...
&SUPPRESSION
ENABLE_EXTENDED_ATTACK = .TRUE.
EXTENDED_ATTACK_MODEL = 0
DT_EXTENDED_ATTACK = 3600
AREA_NO_CONTAINMENT_CHANGE = 10000
MAX_CONTAINMENT_PER_DAY = 100
SDI_FACTOR = 1
USE_SDI = .TRUE.
USE_SDI_LOG_FUNCTION = .TRUE.
B_SDI = 1
The Area-Growth-Based containment model estimates changes in containment at intervals defined by DT_EXTENDED_ATTACK. At each interval, the model compares the change in fire area with AREA_NO_CONTAINMENT_CHANGE and uses this information, together with the Suppression Difficulty Index (SDI), MAX_CONTAINMENT_PER_DAY, and B_SDI, to determine the change in containment.
When SDI is enabled, spatial differences in suppression difficulty modify the effective change in fire area. SDI_FACTOR provides an additional scaling factor that can be used for calibration or sensitivity analysis. The relationship between fire-area growth and containment change is linear by default and can be changed to a logarithmic formulation using USE_SDI_LOG_FUNCTION. If SDI data are unavailable, USE_SDI can be set to .FALSE., in which case a uniform SDI factor of 1 is applied.
Spatially Explicit Extended-Attack Model
The new extended-attack model is activated by setting
&SUPPRESSION
ENABLE_EXTENDED_ATTACK = .TRUE.
EXTENDED_ATTACK_MODEL = 1
ENABLE_INDIRECT_ATTACK = .TRUE.
EXTENDED_ATTACK_TIME = -1.0
INITIAL_CONTAINMENT_SHAPE_FACTOR = 10
AVAILABLE_SUPPRESSION_CAPACITY = 2000
FIRELINE_LENGTH_REF = 15000
PCL_THRESHOLD = 30.0
FL_MAX_DIRECT_ATTACK = 8.0
SDI_MAX_DIRECT_ATTACK = 100.0
FIRE_LINE_THICKNESS = 1
DELTA_ROS = 10
DELTA_FL = 2
DELTA_SDI = 10
DELTA_PCL = 10
The spatially explicit model represents suppression through two linked components: direct attack on the active fireline and indirect attack at favorable control locations. Suppression is evaluated during the fire-spread simulation so that successfully suppressed portions of the fireline influence subsequent fire growth.
Suppression Capacity and Deployment Delay:
AVAILABLE_SUPPRESSION_CAPACITY specifies the maximum suppression capacity available to the incident in units of meters of fireline per hour. The full capacity does not need to be available immediately after ignition. Instead, the model allows suppression capacity to increase from zero to its specified maximum as resources are deployed.
The deployment period can be defined in two ways using EXTENDED_ATTACK_TIME. If a positive value is specified, it represents a fixed time, in seconds, at which the full suppression capacity becomes available. This option can be used when an approximate mobilization or deployment time is known.
If EXTENDED_ATTACK_TIME is negative, the model estimates the deployment time from the early growth of the active fireline. The average fireline-growth rate during the first day of simulation is calculated and used to estimate the time required for the fireline to reach FIRELINE_LENGTH_REF. FIRELINE_LENGTH_REF therefore represents the expected active fireline length, in meters, at which full suppression capacity is deployed. Because this option relies on fireline growth during the first day, the simulated fire duration must exceed one day.
The parameter INITIAL_CONTAINMENT_SHAPE_FACTOR controls the shape of the capacity buildup from zero to the full available capacity. Smaller values produce a more gradual increase, whereas larger values delay a larger fraction of the capacity until closer to the estimated or specified full-deployment time and therefore produce a sharper increase in suppression capability.
Direct Attack:
Direct attack operates on the active fire edge. The model first identifies active fireline cells and groups neighboring cells with similar fire behavior and suppression conditions into fireline segments. Segment formation considers fireline type, rate of spread (ROS), flame length, SDI, and Potential Control Location (PCL).
The parameters
DELTA_ROS
DELTA_FL
DELTA_SDI
DELTA_PCL
define the allowable differences between neighboring cells when constructing fireline segments. Their units are ft min\(^{-1}\) for DELTA_ROS, ft for DELTA_FL, and the corresponding scaled SDI and PCL units for DELTA_SDI and DELTA_PCL. FIRE_LINE_THICKNESS specifies the number of raster cells used to represent the active fireline.
For each fireline segment, the model evaluates the feasibility and relative difficulty of direct attack using flame length and SDI. FL_MAX_DIRECT_ATTACK specifies the reference flame length for direct attack, with a suggested default value of 8 ft. SDI_MAX_DIRECT_ATTACK specifies the corresponding reference SDI value, with a suggested default value of 100. For SDI products stored as SDI multiplied by 100, values may extend to approximately 318 for the USDA SDI product.
Segments with more favorable fire behavior and suppression conditions receive higher priority for direct attack. Available suppression capacity is progressively allocated among eligible segments, while increasingly difficult segments consume a larger fraction of the available capacity.
Indirect Attack:
Indirect attack can be enabled or disabled using
ENABLE_INDIRECT_ATTACK = .TRUE.
When enabled, the model uses PCL information to identify favorable locations where the advancing fire may be stopped. PCL_THRESHOLD defines the minimum PCL value used to identify candidate control locations. A suggested default value of 30 is used for PCL data represented on a 0–100 scale.
Spatially connected candidate cells are grouped into control-location segments, and the representative PCL value of each segment is calculated from the mean PCL of its cells. When the advancing fire reaches a candidate control location, the model estimates its probability of holding based on the segment PCL and the local fire behavior. Increasing flame length reduces the probability that the control location will hold. A random value drawn from a uniform distribution is then compared with the calculated holding probability. If the control location holds, fire spread across the affected portion of the segment is prevented; otherwise, the location is breached and the fire continues to spread.
The parameters shown above provide suggested default values and can be modified to represent different suppression environments, input datasets, or calibration requirements.
Fire Potential Mode
So far, ELMFIRE has been set to estimate the fire propagation based on some starting conditions and (potentially) transient weather. This is similar to the function of FARSITE. ELMFIRE is also capable of estimating the fire risk of an area at a given weather, much like the FLAMMAP program. This behavior is controlled through the MODE variable.
The modes that ELMFIRE has are:
MODE = 1: The standard ELMFIRE spread model, with (potentially) transient weather, ignitions, firebrands, level set propagation.
MODE = 2: Fire potential mode. No ignitions are provided, instead ELMFIRE calculated the maximum rate of spread and potential crown fire activity for all cells of the domain, for each weather band.
MODE = 3: Both output types from above.
Assets at Risk
An important part of quantifying fire risk is assessing potential impacts to assets at risk. ELMFIRE is currently capable of quantifying impacts to three assets at risk. Since some of the most relevant assets at risk are population, real estate/structures, and land/timber, the keywords that are used to specify assets at risk in the &INPUTS namelist group are hardcoded as REAL_ESTATE, POPULATION_DENSITY, and LAND_VALUE although each of these is treated identically. Since other assets at risk may be relevant (cultural resources, sensitive habitat, watershed, etc.), the total number of assets at risk eventually will be expanded. However, for the time being, assets at risk are specified as follows:
Land value: Set USE_LAND_VALUE = .TRUE. and specify the land value filename via LAND_VALUE_FILENAME
Real estate value: Set USE_REAL_ESTATE_VALUE = .TRUE. and specify the real estate value filename via REAL_ESTATE_VALUE_FILENAME
Population density: Set USE_POPULATION_DENSITY = .TRUE. and specify the population density filename via POPULATION_DENSITY_FILENAME
Note that assets at risk are read in from the FUELS_AND_TOPOGRAPHY directory. Additionally, all assets at risk should be Float32 GeoTiff rasters. Units should be quantity per acre, e.g. structures per acre, population per acre, $ per acre, etc.
If assets at risk rasters are provided as input, ELMFIRE will sum total impacts by integrating fire area over asset at risk density and report this in the fire_size_stats.csv output file. ELMFIRE will also create impact rasters affected_land_value.tif, affected_real_estate_value.tif, and affected_population.tif.
Pyrome Calibration
Large areas of the landscape can be categorised or delineated based on their historic fire conditions, or the way that wildfires historically spread and behave. Such areas are called Pyromes, and outline areas of similar fire behavior beyond having similar fuels, weather patterns or topography. Such delineations require expert judgement or knowledge of the local fire landscape, though an initial delineation of the continental United States, along with guides on how they can be generated, can be found in Short et al.
If the simulation area contains multiple pyromes, the fire behaviour of each area can be adjusted. Pyrome adjustment can be activated through USE_PYROMES = .TRUE. in the &SIMULATOR namelist. A raster named PYROMES_FILENAME.tif can be specified in the &INPUTS namelist. Each point in that raster is assigned an integer, specifying which pyrome it belongs to. Subsequent Pyrome files belong to the &CALIBRATION namelist can be specified to make adjustments to various parameters depending on which pyrome they belong to. As an example, below is a sample file which contains different adjustment factors, ADJUSTMENT_FACTORS_FILENAME (which requires ADJUSTMENT_FACTORS_BY_PYROME = .TRUE. to be used):
108 121 162 163 181 202
1 1.0 1.1 1.1 0.9 1.0 0.8
2 1.1 1.0 0.9 1.0 1.2 1.0
3 1.2 1.0 1.0 1.1 1.1 0.9
4 1.0 0.8 1.1 0.9 1.0 0.8
In the case of ADJUSTMENT_FACTORS_FILENAME, each of these values adjusts the predicted surface and crown fire rates of spread. For example, within pyrome 3, surface and crown fire rate of spread will be multiplied by 1.2 for cells with fuel model 108, 1.0 for fuel model 121 and so on.
If CALIBRATION_CONSTANTS_BY_PYROME is set to .TRUE., and accompanying CALIBRATION_CONSTANTS_FILENAME file should be provided, with the structure:
InitialAttackTime BSDI MAXCPERDAY AREANCCHANGE SIMDURATION IGNDENSITYADJ
1 3600 0.9 100 10000 16000 0.8
2 3600 1.0 90 8500 12000 1.0
3 3600 1.0 100 10000 16000 0.9
4 1800 0.9 100 10000 14000 0.8
The spaces between the values are just added here to illustrate which column they correspond to, they are not necessary. The columns are, in order, suppression initial attack time, adjustment factor \(B_SDI\), max containment per day, area of no containment change, ELMFIRE simulation duration and ignition density (probability) adjustment. See the Suppression section for more details on the first four parameters, and the monte carlo (ignition) section for the latter two.
For long-term monte carlo simulations, another way to set the total simulation time is by providing probability density functions to individual day durations. By setting DURATION_PDF_BY_PYROME = .TRUE., an input file DURATION_PDF_FILENAME can be specified:
1 2 3 ... 364 355
1 0.000 0.001 0.050 0.000 0.000
2 0.000 0.001 0.001 0.010 0.000
3 0.000 0.001 0.100 0.000 0.000
...
Each value denotes the probability that the duration of the simulation will be equal to that day duration. A hard limit of DURATION_MAX_DAYS is set, so no simulation can be longer.
Smoke
ELMFIRE can calculate the smoke emissions of any given simulation for use with external dispersion models. As of this version, ELMFIRE treats each simulation as one source of dispersants (meaning any output files will treat any part of the burning landscape as one source instead of splitting them apart). It is assumed that the main dispersant that users may be interested in is PM2.5, so most program constants have been selected based on this assumptions. They have been made user-modifiable if a different pollutant is required.
Smoke calculations can be enabled by setting ENABLE_SMOKE_OUTPUTS = .TRUE. in the &SMOKE namelist. Enabling this feature will result in the output of an additional smoke_000001.csv file being generated, containing the simulation time in hours, the timestamp of the simulation, the x and y center of the burning area of that time interval (geometric center, does not get weighted by any parameter as was the case in previous versions), the total burned area of that time interval, the average HRR in MW and the average pollutant injection per hour. The center of the burning area is given in units related to the projection of the input geotiff rasters.
The dispersion is based on a simple calculation relating total energy released by the wildfire at time interval DT_SMOKE_OUTPUTS, energy released per kg of wood (used to estimate total burned mass, with a constant DRY_WODD_CALORIFIC_VALUE = 19 MJ/kg, later adjusted by the 10-h fuel moisture content), and the pollutant released per kg of burned wood (PM_EMISSION_FACTOR_FLAMING and PM_EMISSION_FACTOR_SMOLDERING for the two burning phases). The total flaming and smoldering time (also referred to as residence time) can also be adjusted from their default values, using inputs FLAMING_TIME and SMOLDERING_TIME in seconds.
This module was made for use with external dispersion program, with HYSPLIT as a main example. For a better integration with HYSPLIT, the EMITIMES.txt file can be written directly by ELMFIRE. EMITIMES.txt is used to specify complex, transient or moving sources, all three of which are the case with an evolving fire front. To generate this file, set DUMP_EMITIMES = .TRUE. in the &OUTPUTS namelist.
Running HYSPLIT
In the examples/ folder we have provided a set of helper scripts to run elmfire simulations, whose outputs can be used to run HYSPLIT. HYSPLIT requires the following files to run a simulation:
SETUP: global simulation settings
EMITIMES.txt: emission and fire size entries per hour
CONTROL: specific simulation parameters
ASCDATA.CFG: simulation domain config file
The examples/smokeHelpers/elmfire2hysplit.py file helps prepare all the needed files for a HYSPLIT run, based on an ELMFIRE simulation. The helper script creates the CONTROL, SETUP, ASCDATA.CFG files with some baseline options setup. Advanced users are free to change these values. The helper file also automatically downloads the weather files required by HYSPLIT that describe the global composition of the atmosphere (weekly GDAS1). The standard source of these files is US NOAA.
The simulation is then run automatically via examples/smoke/elmfire_hysplit.sh, which handles everything from running the ELMFIRE simulation, setting up the necessary folders, and running HYSPLIT. The final files are in a binary format that is difficult to use, and to help convert them to a format that is more friendly to GIS systems, bin2nc.py is provided. It converts the smoke.bin output to smoke.nc, which can then be opened with programs like QGIS. bin2nc.py is automatically run within elmfire_hysplit.py.
smoke.nc can then be imported directly to GIS applications. With QGIS, specifically, two features will be imported, one with individual smoke raster bands, and one with no bands and just a premade colormap of PM2.5 concentration in \(\mu g/m^3\). This file is already temporally enables, and Temporal Controller can be used to scroll through the simulation daterange.
Memory Optimization
ELMFIRE has been developed from the start to be a fast wildfire spread model, with great parallel processing and monte-carlo processing capabilities. These capabilities require that all data is loaded in memory at the start of model calculations. For the majority of cases there is no issue with this setup, but for cases with larger rasters and longer run times (in the order of 2000 x 2000 points and 800 hours or above), RAM usage can reach 60 GB and be unsustainable for many systems. The problem stems from the need to load all temporal data in memory at once, with larger rasters requiring 150 MB of RAM per weather band.
To reduce the RAM usage of ELMFIRE, a MEMOPT version of the code has been developed that requires far less RAM resources to run, for the price of longer run times. ELMFIRE-MEMOPT only loads part of the temporal weather rasters in memory at a time. Once all processes/simulations are finished with the current weather band range, a new one is loaded. This can bring the RAM requirement of a large simulation down from 60 GB to 5 GB, and increase the simulation run time by 10 % (depending on the case). The switch that controls how many weather bands are loaded at a time is WX_BANDS_KEPT_IN_MEM, in the &SIMULATOR namelist. A standard value of 30 has been set as standard based on a balance of runtime and RAM usage.
Docker and Containerisation
The ELMFIRE distribution also provides a docker image to run ELMFIRE without the need to install any packages or specific python versions. Using it should be straightforward if you are familiar with docker; this guide has been written for people with no docker familiarity.
Running ELMFIRE through docker ascertains that ELMFIRE will run as expected every time, avoiding the ’it works on my machine’ debugging problem. Users can just mount a pre-made image, run ELMFIRE, and save the results without any further installations needed.
You can install docker either through its desktop version or though a more minimal command line version. If using ELMFIRE on windows via WSL2, you can download docker for desktop on windows and then enable docker for WSL (some setting changes are needed).
Once you have installed docker in your system, cd to the directory where elmfire is installed. That directory should have a Dockerfile and a docker-compose.yml file. Within that directory, first build the image. This creates the environment where ELMFIRE can run. It usually takes a relatively long time (about 10 mins) to download all dependencies, python packages, setup environment variables, and compile ELMFIRE.
docker compose up -d --build
This command will build and activate the ELMFIRE image. To then use this image,
docker compose exec elmfire bash
This will activate a bash terminal within the docker image where you can use ELMFIRE just like in any other linux installation. The examples, tutorials and verification cases all work within the image. Once you are done, to stop using up resources, you can stop the image through:
docker compose down
You do not need to build the image again to activate it, you only need to build it if there are changes made to the ELMFIRE distribution.
Please note that once you bring down the image, all changes and files generated will be deleted. The one exception to this, and the way that a docker version of ELMFIRE becomes useful, is through the docker_shared_folder that appears once you build the image. The contents of that folder are visible to both the docker image and the host machine and persist even when the docker image is brought down. A viable workflow is to then copy specific cases into that folder, run ELMFIRE through the image, and retrieve the results. Note that sometimes there are issues with folder ownership and you may be prohibited from copying files into the generated folder. In this case, you might need to change ownership of the folder to your username through chown.
Data Sources and Helper Scripts
This section is devoted into compiling data sources and helper scripts that can be used alongside ELMFIRE to either compile all the data needed for the simulation or pre- / postprocess the results. Note that this list is a compilation of frequently used resources and does not necessarily reflect implicit approval of the accuracy of the data or continuous support alongside ELMFIRE.
FireDX [US / GLOBAL]: Automatic generation of urban fire spread input rasters. https://github.com/ma-th/firedx
utils/makeBarrierFile.py [GLOBAL]: Create a valid barrier file based on OSM roads and rivers.
LANDFIRE [US]: Download complete landscape files for any US area. https://landfire.gov
CWFIS [CANADA]: Download topography, fuel, weather, and danger index information for all of Canada. https://cwfis.cfs.nrcan.gc.ca/downloads/docs/en/how-tos/how-to-access-cwfis-data-services.pdf
MesoWest [US]: (Scheduled for sunsetting by end of 2026) Automated Weather Station data repository. https://mesowest.utah.edu
Process Flowchart
ELMFIRE Workflow:
Setup variables
Setup MPI
Read and check input files
Set randomizer seed
Calculate sunrise and sunset times
Calculate and save lookup tables (for easy/fast access)
Read headers of weather, fuels & topography
Read weather, fuels & topography raster data
Determine number of cases to run
Rotate wind if GRID_DECLINATION
If pyromes are used, parse adjustment factors
Remap the weather input grids (coarse) to the simulation cellsize (fine)
Allocate memory for additional rasters (outputs, intermediate rasters etc.)
(if Random Ignitions) Determine ignition locations
Allocate memory for output rasters
If in fire potential mode (MODE = 2 or 3):
Initialize spread output rasters
Keep track of all burnable cells (burnable fuel types and outside of Edgebuffer range)
For each weather band:
Calculate surface and crown spread rates
Check surface flame length, if high enough then apply crown fire calculations.
Output spread raster values
If in fire spread mode (MODE = 1 or 3)
(ensemble monte carlo) initialize random parameters and pretrubations.
For each scenario call level set propagation algorithm.
Accumulate ensemble statistics
Run postprocessing for advanced outputs
Shutdown
Main level set propagation algorithm:
Since the first Memory Optimisation (MEMOPT) version of ELMFIRE, the structure of the level set method has been changed to:
Check if new weather band range is needed and update weather band range loaded in memory
If ignition time is reached:
Determine simulation stop time
Allocate intermediate rasters
Determine output time interval
Allocate output rasters
Set pointer addresses
If random ignitions are on:
Set ignition location
Adjust simulation time and suppression parameters through Pyrome
Exclude and set outputs if nonburnable cell is selected for ignition
Check that weather band exists for this time step
Initialize weather, suppression, point list variables
If random ignitions are not enabled:
Check each landscape point for \(\phi < 0\), set as burning, and set initial weather parameters
Calculate surface and crown rates of spread for all points currently burning
Calculate front normal vectors, calculate X and Y ROS components
Check for eligible fire spread cells within fire front BANDTHICKNESS
Start the main loop until stop condition is reached:
If applicable, calculate overnight adjustment factor time span
If random ignitions are on, set \(\phi\) of ignition point to zero and save potential spread points.
If multiple ignitions are specified in the input, check if any new ignitions apply.
Interpolate current weather values
Apply wind fluctuations
Calculate surface spread rate
Calculate crown spread rate
Calculate components of normal vectors of fire front
Calculate Ux and Uy velocity components
If FLIN is high enough for crown fire, apply results of crown spread rate to total.
Calculate new time step with CFL and Flux limiter
Integrate level set equations with Runge Kutta 2nd order
Update burning point values and statistics
If enabled, save binary outputs
If enabled, calculate new spot fire locations
If UMD spotting is enabled, calculate physical parameters and run spotting model.
Calculate and clear extinguished embers (separate processes for eulerian and lagrangian)
Calculate interpolated weather values for newly-included cells
Calculate surface and crown spread rates for new cells
If applicable, calculate initial attach probability
Stop simulation if less than two points are burning, or if a max acreage criterion is reached.
If applicable, append acreage timings statistics
Calculate extended attack containment
Dump main outputs
Advance simulation time
If simulation stop time has been reached:
Process and output timed location data (does not apply to newer versions).
Calculate and output fire size statistics
If applicable, dump binary outputs
If applicable, dump ember count bin measurements.