Add Community Fire Behavior Model

[mkavulich]

Note: This PR is in draft mode while we investigate issues with the latest weather model (unrelated to this development) that are causing some tests to fail; see #1136 for details.

DESCRIPTION OF CHANGES:

This PR introduces the Community Fire Behavior Module (ufs-community/ufs-weather-model#2220) to the SRW App. In addition, there are a number of general improvements to the UFS SRW code and workflow. All of these changes are described in more detail below.

Community Fire Behavior Module

Documentation/updating the Users Guide is a work in progress, but the basics are that the fire build requires an additional build flag

./devbuild.sh --platform=[hera|derecho|etc.] --app=ATMF

and has an additional fire: section in config.yaml. There is an example fire configuration available in the new example config config.fire.yaml. Many settings are described in detail in config_defaults.yaml, but I am working on additional details.

Sample data for the case in the example file has been staged on Derecho (/glade/derecho/scratch/kavulich/FIRE/2024/test_data) and Hera (/scratch2/BMC/fv3lam/kavulich/UFS/workdir/UFS_FIRE/test_data). I will reach out to EPIC to see if they would be willing to officially stage this sample data on all Level 1 platforms for community use and potential future tests. This PR does not include a WE2E test because the testing system does not currently have a neat way to handle multiple build types, but in theory the new example case could be used.

Two new pre-defined domains SUBCONUS_CO_1km and SUBCONUS_CO_3km, for use with high-resolution fire experiments, are added.

build_settings.yaml

In develop there is currently no way to reference build settings at configure and run time. There was a vestigial capability in the ufs_srweather_app.settings.in which was added 4+ years ago, but it has never really been used or updated and it is in an ad-hoc format that cannot be easily used. I have leveraged this existing capability to create a new file, build_settings.yaml in the build directory that contains useful build information (the application built, the compiler, the git hash, etc.) and can be easily read using uwtools in the existing workflows and run scripts. Specifically this is used in this PR to ensure that the app has been built with the fire behavior capability if fire options are selected, but this should prove very useful in other parts of the workflow going forward; for just a few examples:

• checking that the right compiler was specified for the experiment settings
• checking that machine settings are correct compared to the build
• checking app-specific settings for other builds such as AQM

This new file and the unused (but potentially useful in the future) ufs_srweather_app_meta.h.in files are moved to the sorc directory to keep the source code more organized and uncluttered.

Improve capability to use a different set of vertical levels

Currently the instructions for running SRW with a different number of vertical levels from the default 65 is quite convoluted, involving the need to manually edit the template namelist file. This PR adds LEVP as a configuration variable to more easily allow for runs with different vertical levels. The users guide instructions have been updated accordingly.

Flexible config file name

Now rather than being forced to use the name config.yaml for your experiment config, you can reference any yaml file by using the -c option for workflow generation:

./generate_FV3LAM_wflow.py -c config.fire.yaml

With these changes, EXPT_CONFIG_FN is removed as a configurable option, but this was uselessly self-referential anyway.

Additional options for retrieve_data.py

A big limitation in specifying filenames in the current app is that there is no capability for filenames to change based on the forecast hour vs the cycle hour. Therefore a new set of variables, identical to the originals but with the prefix f, can now be used when specifying filenames with respect to the forecast hour rather than the cycle hour.

An example of this new usage can be seen in the newly added config.fire.yaml experiment:

  EXTRN_MDL_FILES_LBCS:
    - '{fyyyymmdd}.hrrr.t{fhh}z.wrfprsf00.grib2'

This instructs retrieve_data.py to look for filenames specific to the valid forecast hour for the specific lateral boundary condition file. So for forecast hour zero (valid 2020081318), the expected filename will be 20200813.hrrr.t18z.wrfprsf00.grib2. But at the 18 hour forecast, the LBC filename will be 20200814.hrrr.t12z.wrfprsf00.grib2. This was not previously possible without these new variables, and represents a vast improvement in flexibility for users.

Various random improvements

• Fixed regex statements in WE2E tests to fix SyntaxWarning: invalid escape sequence
• Removed global array logic from boolify to get significant speedup for this frequently used function
• Updated build modulefiles to include FC variable, which is needed by the Fire Behavior component.

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

TESTS CONDUCTED:

A number of fundamental test runs have been conducted on Derecho, Hera, and Orion, both with and without the ATMF build. Not all are passing, but seems to be unrelated to this development; see the note at the top. This section will be updated once those issues are resolved.

• derecho.intel
• gaea.intel
• hera.gnu
• hera.intel
• hercules.intel
• jet.intel
• orion.intel
• wcoss2.intel
• NOAA Cloud (indicate which platform)
• Jenkins
• fundamental test suite
• comprehensive tests (specify which if a subset was used)

DEPENDENCIES:

Pending resolution of whether this or #1136 will be merged first

DOCUMENTATION:

Updates in progress.

ISSUE:

None

CHECKLIST

• My code follows the style guidelines in the Contributor's Guide
• I have performed a self-review of my own code using the Code Reviewer's Guide
• I have commented my code, particularly in hard-to-understand areas
• My changes need updates to the documentation. I have made corresponding changes to the documentation
• My changes do not require updates to the documentation (explain).
• My changes generate no new warnings
• New and existing tests pass with my changes
• Any dependent changes have been merged and published

CONTRIBUTORS (optional):

Thanks to the whole Fire Behavior team for bringing me on to this project, and their extensive efforts to get this capability ready for use by the scientific community: @danrosen25 @masih-e @pedro-jm and @mefrediani