Add Fire documentation to Users Guide

doc/UsersGuide/BuildingRunningTesting/FIRE.rst

@@ -0,0 +1,259 @@
+.. _UFS_FIRE:
+
+=========================================
+Community Fire Behavior Module (UFS FIRE)
+=========================================
+
+The `Community Fire Behavior Model (CFBM) <https://ral.ucar.edu/model/community-fire-behavior-model>`_ 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 <https://github.com/NCAR/fire_behavior>`_ is a :term:`submodule` of the UFS Weather Model (WM), coupled through the :term:`NUOPC` Layer to provide direct feedback between the simulated atmosphere and the simulated fire. More information about the CFBM can be found in the :fire-ug:`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, additional input files, and some fire-specific config settings, building and running 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 :numref:`Chapter %s <BuildSRW>` and :numref:`Chapter %s <RunSRW>` for additional information on building and running the SRW App, respectively. 
+
+Quick Start Guide (UFS FIRE)
+=====================================
+
+Download the Code
+-------------------
+
+Clone the |branch| branch of the authoritative SRW App repository:
+
+.. code-block:: console
+
+   git clone -b develop https://github.com/ufs-community/ufs-srweather-app
+   cd ufs-srweather-app
+
+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.
+
+.. code-block:: console
+
+   ./manage_externals/checkout_externals
+
+Build the SRW App with Fire Behavior enabled
+--------------------------------------------
+
+To build the SRW with fire behavior code, use the following command:
+
+.. code-block:: console
+
+   ./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 :numref:`Table %s <ExecDescription>`. There are no additional files expected, since the CFBM is coupled to the UFS weather model via the same ``ufs_model`` executable.
+
+Load the |wflow_env| Environment
+--------------------------------------------
+
+Load the python environment for the workflow:
+
+.. code-block:: console
+
+   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: 
+
+.. code-block:: console
+
+   Please do the following to activate conda:
+       > conda activate srw_app
+
+then the user should run |activate|. Otherwise, the user can continue with configuring the workflow. 
+
+.. _FIREConfig:
+
+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``:
+
+.. code-block:: console
+
+   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 :numref:`Section %s <ConfigWorkflow>`.
+
+Activating the fire behavior module is done by setting ``UFS_FIRE: True`` in the ``fire:`` 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 settings.
+
+.. code-block:: console
+
+   fire:
+     UFS_FIRE: True
+
+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
+
+.. code-block:: console
+   
+   fire:
+     FIRE_PRINT_MSG: 1
+
+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 :ref:`input data locations <Data>` under ``LOCATION``. Users can also download the data required for the community experiment from the `UFS SRW App Data Bucket <https://noaa-ufs-srw-pds.s3.amazonaws.com/index.html#develop-20240618/input_model_data/fire>`__.
+
+
+Instructions on how to create this file for your own experiment can be found in the :fire-ug:`CFBM Users Guide <Configuration.html#configuring-a-domain-with-the-wrf-pre-processing-system-wps>`.
+
+Once the file is acquired/created, you will need to specify its location in your ``config.yaml`` file with the setting ``FIRE_INPUT_DIR``.
+
+.. code-block:: console
+
+   fire:
+     FIRE_INPUT_DIR: /directory/containing/geo_em/file
+
+
+
+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 :term:`namelist` file ``namelist.fire``. The available settings in this file are described in the :fire-ug:`CFBM Users Guide <Configuration.html#namelist-configuration>`, 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``.
+
+Example fire configuration
+---------------------------
+
+Here is one example of settings that can be specified for a UFS FIRE simulation.
+
+.. code-block:: console
+
+   fire:
+     UFS_FIRE: True
+     FIRE_INPUT_DIR: /home/fire_input
+     DT_FIRE: 0.5
+     OUTPUT_DT_FIRE: 1800
+     FIRE_NUM_IGNITIONS: 1
+     FIRE_IGNITION_ROS1: 0.05
+     FIRE_IGNITION_START_LAT1: 40.609
+     FIRE_IGNITION_START_LON1: -105.879
+     FIRE_IGNITION_END_LAT1: 40.609
+     FIRE_IGNITION_END_LON1: -105.879
+     FIRE_IGNITION_RADIUS1: 250
+     FIRE_IGNITION_START_TIME1: 6480
+     FIRE_IGNITION_END_TIME1: 7000
+
+In this case, a single fire (``FIRE_NUM_IGNITIONS: 1``) of radius 250 meters (``FIRE_IGNITION_RADIUS1: 250``) is ignited at latitude 40.609˚N (``FIRE_IGNITION_START_LAT1: 40.609``), 105.879˚W (``FIRE_IGNITION_START_LON1: -105.879``) 6480 seconds after the start of the simulation (``FIRE_IGNITION_START_TIME1: 6480``) with a rate of spread specified as 0.05 m/s (``FIRE_IGNITION_ROS1: 0.05``). This "ignition" ends 7000 seconds after the start of the simulation (``FIRE_IGNITION_END_TIME1: 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.
+
+The CFBM creates output files in :term:`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 :fire-ug:`the ``&fire`` section of the namelist <Configuration.html#fire>` 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.
+
+
+Generate the Workflow
+------------------------
+
+Generate the workflow:
+
+.. code-block:: console
+
+   ./generate_FV3LAM_wflow.py
+
+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:
+
+.. code-block:: console
+
+   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 :numref:`Section %s <DirParams>` 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: 
+
+.. code-block:: console
+
+   # 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
+
+To see a description of each of the FIRE workflow tasks, see :numref:`Section %s <FIRE-more-tasks>`.
+
+.. _FIRESuccess:
+
+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: 
+
+.. code-block:: console
+
+         CYCLE                   TASK       JOBID       STATE   EXIT STATUS   TRIES   DURATION
+   ============================================================================================
+   202302170000              make_grid    47411619   SUCCEEDED             0       1       36.0
+   202302170000              make_orog    47411728   SUCCEEDED             0       1      151.0
+   202302170000         make_sfc_climo    47411801   SUCCEEDED             0       1       58.0
+   202302170000          nexus_gfs_sfc    47411620   SUCCEEDED             0       1       37.0
+   202302170000      nexus_emission_00    47411729   SUCCEEDED             0       1      251.0
+   202302170000      nexus_emission_01    47411730   SUCCEEDED             0       1      250.0
+   202302170000      nexus_emission_02    47411731   SUCCEEDED             0       1      250.0
+   202302170000       nexus_post_split    47412034   SUCCEEDED             0       1       44.0
+   202302170000          fire_emission    47411621   SUCCEEDED             0       1       19.0
+   202302170000           point_source    47411732   SUCCEEDED             0       1       82.0
+   202302170000               aqm_lbcs    47412961   SUCCEEDED             0       1      159.0
+   202302170000          get_extrn_ics    47411622   SUCCEEDED             0       1      314.0
+   202302170000         get_extrn_lbcs    47411623   SUCCEEDED             0       1        0.0
+   202302170000        make_ics_mem000    47659593   SUCCEEDED             0       1      126.0
+   202302170000       make_lbcs_mem000    47659594   SUCCEEDED             0       1      113.0
+   202302170000        run_fcst_mem000    47659742   SUCCEEDED             0       1      763.0
+   202302170000   run_post_mem000_f000    47659910   SUCCEEDED             0       1       30.0
+   202302170000   run_post_mem000_f001    47660029   SUCCEEDED             0       1       30.0
+   202302170000   run_post_mem000_f002    47660030   SUCCEEDED             0       1       31.0
+   ...
+   202302170000   run_post_mem000_f006    47660110   SUCCEEDED             0       1       29.0
+   ============================================================================================
+   202302170600          nexus_gfs_sfc    47659421   SUCCEEDED             0       1       44.0
+   202302170600      nexus_emission_00    47659475   SUCCEEDED             0       1      323.0
+   202302170600      nexus_emission_01    47659476   SUCCEEDED             0       1      323.0
+   202302170600      nexus_emission_02    47659477   SUCCEEDED             0       1      329.0
+   202302170600       nexus_post_split    47659595   SUCCEEDED             0       1       60.0
+   202302170600          fire_emission    47659422   SUCCEEDED             0       1       18.0
+   202302170600           point_source    47659478   SUCCEEDED             0       1      128.0
+   202302170600                aqm_ics    47659597   SUCCEEDED             0       1      159.0
+   202302170600               aqm_lbcs    47659598   SUCCEEDED             0       1      158.0
+   202302170600          get_extrn_ics    47659423   SUCCEEDED             0       1      493.0
+   202302170600         get_extrn_lbcs    47659424   SUCCEEDED             0       1      536.0
+   202302170600        make_ics_mem000    47659594   SUCCEEDED             0       1      134.0
+   202302170600       make_lbcs_mem000    47659596   SUCCEEDED             0       1      112.0
+   202302170600        run_fcst_mem000    47659812   SUCCEEDED             0       1     1429.0
+   202302170600   run_post_mem000_f000    47659998   SUCCEEDED             0       1       30.0
+   202302170600   run_post_mem000_f001    47660042   SUCCEEDED             0       1       31.0
+   202302170600   run_post_mem000_f002    47660043   SUCCEEDED             0       1       29.0
+   ...
+   202302170600   run_post_mem000_f012    47660134   SUCCEEDED             0       1       30.0
+
+.. _FIRE-WE2E:
+
+
+WE2E Test for FIRE
+=======================
+
+Build the app for FIRE:
+
+.. code-block:: console
+
+  ./devbuild.sh -p=hera -a=ATMF
+
+
+Run the WE2E test:
+
+.. code-block:: console
+
+   $ cd /path/to/ufs-srweather-app/tests/WE2E
+   $ ./run_WE2E_tests.py -t my_tests.txt -m hera -a gsd-fv3 -q -t UFS_FIRE
+

doc/UsersGuide/BuildingRunningTesting/index.rst

@@ -13,3 +13,4 @@ Building, Running, and Testing the SRW App
    Tutorial
    VXCases
    AQM
+   FIRE

doc/UsersGuide/Reference/Glossary.rst

@@ -239,6 +239,9 @@ Glossary
    spack-stack
       The `spack-stack <https://github.com/JCSDA/spack-stack>`_ is a collaborative effort between the NOAA Environmental Modeling Center (EMC), the UCAR Joint Center for Satellite Data Assimilation (JCSDA), and the Earth Prediction Innovation Center (EPIC). *spack-stack* is a repository that provides a :term:`Spack`-based method for building the software stack required for numerical weather prediction (NWP) tools such as the `Unified Forecast System (UFS) <https://ufs.epic.noaa.gov/>`_ and the `Joint Effort for Data assimilation Integration (JEDI) <https://jointcenterforsatellitedataassimilation-jedi-docs.readthedocs-hosted.com/en/latest/>`_ framework. *spack-stack* uses the Spack package manager along with custom Spack configuration files and Python scripts to simplify installation of the libraries required to run various applications. The *spack-stack* can be installed on a range of platforms and comes pre-configured for many systems. Users can install the necessary packages for a particular application and later add the missing packages for another application without having to rebuild the entire stack. To get started, check out the documentation :doc:`here <spack-stack:index>`.
 
+   submodule
+      A `submodule <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ is a git repository linked to another repository as a subdirectory. Many UFS components are linked in this way; for example, the :term:`UPP` repository is a submodule of the :term:`FV3` repository.
+
    tracer
       According to the American Meteorological Society (AMS) definition, a `tracer <https://glossary.ametsoc.org/wiki/Tracer>`_ is "Any substance in the atmosphere that can be used to track the history [i.e., movement] of an air mass." Tracers are carried around by the motion of the atmosphere (i.e., by :term:`advection`). These substances are usually gases (e.g., water vapor, CO2), but they can also be non-gaseous (e.g., rain drops in microphysics parameterizations). In weather models, temperature (or potential temperature), absolute humidity, and radioactivity are also usually treated as tracers. According to AMS, "The main requirement for a tracer is that its lifetime be substantially longer than the transport process under study."
 

doc/conf.py

@@ -308,6 +308,7 @@ def warn_undocumented_members(app, what, name, obj, options, lines):
             'srw-repo': ('https://github.com/ufs-community/ufs-srweather-app/%s', '%s'),
             'srw-wiki': ('https://github.com/ufs-community/ufs-srweather-app/wiki/%s','%s'),
             'uw': ('https://uwtools.readthedocs.io/en/main/%s', '%s'),
+            'fire-ug': ('https://mkavulich-fire-behavior.readthedocs.io/en/latest/%s', '%s'),
             }
 
 # -- Options for autoyaml extension ---------------------------------------
@@ -316,4 +317,4 @@ def warn_undocumented_members(app, what, name, obj, options, lines):
 autoyaml_doc_delimiter = "###" # Character(s) which start a documentation comment.
 autoyaml_comment = "#" #Comment start character(s).
 autoyaml_level = 6
-#autoyaml_safe_loader = False
+#autoyaml_safe_loader = False