2.10. Community Fire Behavior Module (UFS FIRE)
The Community Fire Behavior Model (CFBM) is a wildland fire model coupled to the UFS Atmospheric Model. The capability to run this code is now available in the UFS Short-Range Weather App for easy use by the community. The fire_behavior repository is a submodule of the UFS Weather Model (WM), coupled through the NUOPC Layer to provide direct feedback between the simulated atmosphere and the simulated fire. More information about the CFBM can be found in the CFBM Users Guide.
The biggest difference between the UFS FIRE capability and other modes of the UFS SRW is that a special build flag is required to build the coupled fire behavior code, as described in the instructions below. Aside from that, the need for additional input files, and some fire-specific config settings, configuring and running an experiment is the same as any other use of SRW.
Note
Although this chapter is the primary documentation resource for running the UFS FIRE configuration, users may need to refer to Chapter 2.3 and Chapter 2.4 for additional information on building and running the SRW App, respectively.
2.10.1. Quick Start Guide (UFS FIRE)
2.10.1.1. Download the Code
Clone the develop branch of the authoritative SRW App repository:
git clone -b develop https://github.com/ufs-community/ufs-srweather-app.git
2.10.1.2. Checkout Externals
Users must run the checkout_externals script to collect (or “check out”) the individual components of the SRW App from their respective GitHub repositories.
cd /path/to/ufs-srweather-app/
./manage_externals/checkout_externals
2.10.1.3. Build the SRW App with Fire Behavior Enabled
To build the SRW with fire behavior code, use the following command:
./devbuild.sh -p=<machine> -a=ATMF
where <machine> is hera, derecho, or any other Tier 1 platform. The -a argument indicates the configuration/version of the application to build; in this case, the atmosphere-fire coupling (ATMF).
If UFS FIRE builds correctly, users should see the standard executables listed in Table 2.3. There are no additional files expected, since the CFBM is coupled to the UFS weather model via the same ufs_model executable.
2.10.1.4. Load the srw_app Environment
Load the appropriate modules for the workflow:
module use /path/to/ufs-srweather-app/modulefiles
module load wflow_<machine>
where <machine> is hera, derecho, or any other Tier 1 platform.
If the console outputs a message, the user should run the commands specified in the message. For example, if the output says:
Please do the following to activate conda:
> conda activate srw_app
then the user should run conda activate srw_app. Otherwise, the user can continue with configuring the workflow.
2.10.1.5. Configure Experiment
Users will need to configure their experiment by setting parameters in the config.yaml file. To start, users can copy an example experiment setting into config.yaml:
cd ush
cp config.fire.yaml config.yaml
Users will need to change the MACHINE and ACCOUNT variables in config.yaml to match their system. They may also wish to adjust other experiment settings, especially under the fire: section, described in further detail below. For more information on other configuration settings, see Section 3.1.
Activating the fire behavior module is done by setting UFS_FIRE: True in the fire/envvars: section of your config.yaml file. If this variable is not specified or set to false, a normal atmospheric simulation will be run, without fire.
fire:
envvars:
UFS_FIRE: True
Note
The UFS_FIRE capability requires using a CCPP physics suite containing the parameterizations GFS_surface_composites_post and rrfs_smoke_wrapper.
For the v3.0.0 release, these supported suites are FV3_HRRR, FV3_HRRR_gf, and RRFS_sas.
The fire module has the ability to print out additional messages to the log file for debugging; to enable additional log output (which may slow down the integration considerably, especially at higher levels) set FIRE_PRINT_MSG > 0
fire:
FIRE_PRINT_MSG: 1
2.10.1.6. Additional boundary conditions file
The CFBM, as an independent, coupled component, runs separately from the atmospheric component of the weather model, requires an additional input file (geo_em.d01.nc) that contains fire-specific boundary conditions such as fuel properties. On Level 1 systems, users can find an example file in the usual input data locations under LOCATION. Users can also download the data required for the community experiment from the UFS SRW App Data Bucket.
Instructions on how to create this file for your own experiment can be found in the CFBM Users Guide.
Once the file is acquired/created, you will need to specify its location in your config.yaml file with the setting:
fire:
envvars:
FIRE_INPUT_DIR: /directory/containing/geo_em/file
2.10.1.7. Specifying a fire ignition
The CFBM simulates fires by specifying an “ignition” that will then propogate based on the atmospheric conditions and the specified settings. An ignition can either be a “point ignition” (i.e. a disk of fire some specified radius around a single location), or a straight line linear ignition specified by a start and end location and a specified “radius” (width). The ignition can start at the beginning of your simulation, or at some time later as specified. The CFBM can support up to 5 different fire ignitions at different places and times in a given simulation.
The CFBM settings are controlled by the namelist file namelist.fire. The available settings in this file are described in the CFBM Users Guide, and an example file can be found under parm/namelist.fire. However, there is no need to manually provide or edit this file, as the SRW workflow will create the fire namelist using the user settings in config.yaml. The fire-specific options in SRW are documented in Section 3.1.21.
2.10.1.8. Example fire configuration
Here is one example of settings that can be specified for a UFS FIRE simulation:
fire:
envvars:
UFS_FIRE: True
FIRE_INPUT_DIR: /home/fire_input
DT_FIRE: 0.5
OUTPUT_DT_FIRE: 1800
FIRE_NUM_IGNITIONS: 1
FIRE_IGNITION_ROS: 0.05
FIRE_IGNITION_START_LAT: 40.609
FIRE_IGNITION_START_LON: -105.879
FIRE_IGNITION_END_LAT: 40.609
FIRE_IGNITION_END_LON: -105.879
FIRE_IGNITION_RADIUS: 250
FIRE_IGNITION_START_TIME: 6480
FIRE_IGNITION_END_TIME: 7000
FIRE_ATM_FEEDBACK: 1.0
In this case, a single fire (FIRE_NUM_IGNITIONS: 1) of radius 250 meters (FIRE_IGNITION_RADIUS: 250) is ignited at latitude 40.609˚N (FIRE_IGNITION_START_LAT: 40.609), 105.879˚W (FIRE_IGNITION_START_LON: -105.879) 6480 seconds after the start of the simulation (FIRE_IGNITION_START_TIME: 6480) with a rate of spread specified as 0.05 m/s (FIRE_IGNITION_ROS: 0.05). This “ignition” ends 7000 seconds after the start of the simulation (FIRE_IGNITION_END_TIME: 7000), after which the fire behavior is completely governed by the physics of the fire behavior model (integrated every 0.5 seconds as specified by OUTPUT_DT_FIRE), the input fuel conditions, and the simulated atmospheric conditions. This simulated fire will feed back heat and moisture flux to the dynamical core, multiplied by a factor set by the user (FIRE_ATM_FEEDBACK).
The CFBM creates output files in netCDF format, with the naming scheme fire_output_YYYY-MM-DD_hh:mm:ss.nc. In this case the output files are written every 30 minutes (OUTPUT_DT_FIRE: 1800).
Note
Any of the settings under the &fire section of the namelist can be specified in the SRW App config.yaml file under the fire: section, not just the settings described above. However, any additional settings from namelist.fire will need to be added to config_defaults.yaml first; otherwise the check for valid SRW options will fail.
To specify multiple fire ignitions (FIRE_NUM_IGNITIONS > 1), the above settings will need to be specified as a list, with one entry per ignition. See Section 3.1.21 for more details.
2.10.1.9. Generate the Workflow
Generate the workflow:
./generate_FV3LAM_wflow.py
2.10.1.10. Run the Workflow
If USE_CRON_TO_RELAUNCH is set to true in config.yaml, the workflow will run automatically. If it was set to false, users must submit the workflow manually from the experiment directory:
cd ${EXPT_BASEDIR}/${EXPT_SUBDIR}
./launch_FV3LAM_wflow.sh
Repeat the launch command regularly until a SUCCESS or FAILURE message appears on the terminal window. See Section 3.1.3.2 for more on the ${EXPT_BASEDIR} and ${EXPT_SUBDIR} variables.
Users may check experiment status from the experiment directory with either of the following commands:
# Check the experiment status (for cron jobs)
rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10
# Check the experiment status and relaunch the workflow (for manual jobs)
./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow
2.10.1.11. Experiment Output
The workflow run is complete when all tasks display a “SUCCEEDED” message. If everything goes smoothly, users will eventually see a workflow status table similar to the following:
CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION
================================================================================================================================
202008131800 make_grid 6498125 SUCCEEDED 0 1 70.0
202008131800 make_orog 6498145 SUCCEEDED 0 1 87.0
202008131800 make_sfc_climo 6498172 SUCCEEDED 0 1 90.0
202008131800 get_extrn_ics 6498126 SUCCEEDED 0 1 46.0
202008131800 get_extrn_lbcs 6498127 SUCCEEDED 0 1 46.0
202008131800 make_ics_mem000 6498202 SUCCEEDED 0 1 91.0
202008131800 make_lbcs_mem000 6498203 SUCCEEDED 0 1 106.0
202008131800 run_fcst_mem000 6498309 SUCCEEDED 0 1 1032.0
202008131800 run_post_mem000_f000 6498336 SUCCEEDED 0 1 75.0
202008131800 run_post_mem000_f001 6498387 SUCCEEDED 0 1 76.0
202008131800 run_post_mem000_f002 6498408 SUCCEEDED 0 1 75.0
202008131800 run_post_mem000_f003 6498409 SUCCEEDED 0 1 75.0
202008131800 run_post_mem000_f004 6498432 SUCCEEDED 0 1 64.0
202008131800 run_post_mem000_f005 6498433 SUCCEEDED 0 1 77.0
202008131800 run_post_mem000_f006 6498435 SUCCEEDED 0 1 74.0
202008131800 integration_test_mem000 6498434 SUCCEEDED 0 1 27.0
In addition to the standard UFS and UPP output described elsewhere in this users guide, the UFS_FIRE runs produce additional output files described above:
$ cd /path/to/expt_dir/experiment
$ ls 2020081318/fire_output*
fire_output_2020-08-13_18:00:00.nc fire_output_2020-08-13_19:30:00.nc fire_output_2020-08-13_21:00:00.nc fire_output_2020-08-13_22:30:00.nc
fire_output_2020-08-13_18:30:00.nc fire_output_2020-08-13_20:00:00.nc fire_output_2020-08-13_21:30:00.nc fire_output_2020-08-13_23:00:00.nc
fire_output_2020-08-13_19:00:00.nc fire_output_2020-08-13_20:30:00.nc fire_output_2020-08-13_22:00:00.nc fire_output_2020-08-13_23:30:00.nc
These files contain output directly from the fire model (hence why they are at a greater frequency), including variables such as the fire perimeter and area, smoke emitted, and fuel percentage burnt.
2.10.2. WE2E Tests for FIRE
Build the app for FIRE:
./devbuild.sh -p=hera -a=ATMF
Run the WE2E tests:
$ cd /path/to/ufs-srweather-app/tests/WE2E
$ ./run_we2e_tests.py -t my_tests.txt -m <MACHINE> -a <account> -q -t fire
You can also run each test individually if needed:
$ ./run_we2e_tests.py -t my_tests.txt -m <MACHINE> -a <account> -q -t UFS_FIRE_one-way-coupled
$ ./run_we2e_tests.py -t my_tests.txt -m <MACHINE> -a <account> -q -t UFS_FIRE_multifire_two-way-coupled