Initial draft of Users Guide

.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "doc/" directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: doc/requirements.txt

doc/Configuration.rst

@@ -0,0 +1,252 @@
+.. _Configuration:
+
+==============================================
+Configuring the Community Fire Behavior Module
+==============================================
+
+
+.. _domain_config:
+
+Configuring a domain with the WRF Pre-processing System (WPS)
+=============================================================
+
+Because the CFBM was originally developed as part of the WRF model, creating a domain must be done using the WRF Pre-processing System (WPS). These instructions can be found in `the WRF Users Guide <https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/fire.html#running-wrf-fire-on-real-data>`_.
+
+Future releases will include a method for creating domains without needing to compile WPS.
+
+.. _namelist:
+
+Namelist Configuration
+======================
+
+The options specific to the CFBM are controlled by a :term:`namelist` file ``namelist.fire``. This namelist file consists of three sections: ``&time``, ``&atm``, and ``&fire``. The available options in each section are described below.
+
+Example namelists can be found in the various test subdirectories under the ``tests/`` directory.
+
+
+&time
+---------------------------------
+
+``start_year``: *integer* (**Required**)
+   Start year of the simulation.
+
+``start_month``: *integer* (**Required**)
+   Start month of the simulation.
+
+``start_day``: *integer* (**Required**)
+   Start day of the simulation.
+
+``start_hour``: *integer* (**Required**)
+   Start hour of the simulation.
+
+``start_minute``: *integer* (**Required**)
+   Start minute of the simulation.
+
+``start_second``: *integer* (**Required**)
+   Start second of the simulation.
+
+``end_year``: *integer* (**Required**)
+   End year of the simulation.
+
+``end_month``: *integer* (**Required**)
+   End month of the simulation.
+
+``end_day``: *integer* (**Required**)
+   End day of the simulation.
+
+``end_hour``: *integer* (**Required**)
+   End hour of the simulation.
+
+``end_minute``: *integer* (**Required**)
+   End minute of the simulation.
+
+``end_second``: *integer* (**Required**)
+   End second of the simulation.
+
+``dt``: *real* (Default: ``2.0``)
+   Atmospheric time step in seconds.
+
+``interval_output``: *integer* (**Required**)
+   [Units: s]
+   Specifies the time interval (in seconds) for writing to the history output files
+
+``num_tiles``: *integer* (Default: ``1``)
+   Number of tiles for MPI domain decomposition. Not yet implemented.
+
+
+&atm
+----
+``kde``: *integer* (Default: ``2``)
+   Number of vertical levels for the atmospheric simulation
+
+``interval_atm``: *integer* (Default: ``0``)
+   [Units: s]
+   Time interval (in seconds) for incoming atmospheric data. When running a coupled model, this value represents the atmospheric timestep. In offline mode, it determines the frequency of reading atmospheric data from the input file.
+
+
+&fire
+-----
+
+``fire_print_msg``: *integer* (Default: ``0``)
+   Debug print level for the fire module.
+     Levels greater than 0 will print extra messages at run time.
+
+     0: no extra prints
+
+     1: Extra prints
+
+     2: More extra prints
+
+     3: Even more extra prints
+
+``fire_atm_feedback``: *real* (Default: ``1.0``)
+   Multiplier for heat fluxes from the fire to the atmosphere.
+     0.0: one-way (atmosphere --> fire) coupling.
+
+     1.0: normal two-way coupling.
+
+     Intermediate values will vary the amount of forcing provided from the fire to the dynamical core.
+
+``fire_upwinding``: *integer* (Default: ``9``)
+   This option controls the type of upwinding scheme used for calculating the normal spread of the fire front. The choice of upwinding scheme significantly impacts the accuracy of fire spread simulations. Higher-order schemes, like WENO3 and WENO5, generally offer better accuracy but can be more computationally expensive.
+     0: Central Difference: Uses central differences for calculating gradients, combining left- and right-sided differences for both x- and y-directions to compute a central gradient approximation.
+
+     1: Standard: Employs an upwind scheme, selecting between left- and right-sided differences based on flow direction.
+
+     2: Godunov: The Godunov scheme is a first-order upwind scheme based on Osher & Fedkiw
+
+     3: ENO1: The First-Order Essentially Non-Oscillatory (ENO1) scheme uses the smoothest stencil to avoid sharp gradients, which can lead to underestimations of fire area and errors in the rate of spread.
+
+     4: Sethian scheme :cite:`SethianMethod`
+
+     5: 2nd-order: Calculates gradients using a second-order central difference.
+
+     6: WENO3: Third-Order Weighted Essentially Non-Oscillatory (WENO3) scheme.
+
+     7: WENO5: Fifth-Order Weighted Essentially Non-Oscillatory (WENO5) scheme.
+
+     8: Hybrid WENO3/ENO1: A hybrid scheme that combines WENO3 in a band surrounding the fire front interface with ENO1 for regions further away. This approach reduces computational cost while maintaining accuracy near the front.
+
+     9: Hybrid WENO5/ENO1 (default): Similar to option 8, but uses WENO5 instead of WENO3 in the band surrounding the fire front. This approach reduces computational cost while maintaining accuracy near the front.
+
+``fire_viscosity``: *real* (Default: ``0.4``)
+   Artificial viscocity in :term:`level-set method` away from the near-front region.
+
+``fire_lsm_reinit``: *logical* (Default: ``.true.``)
+   Flag to activate reinitialization of the :term:`level-set method`
+
+``fire_lsm_reinit_iter``: *integer* (Default: ``1``)
+   Number of iterations for reinitialization :term:`PDE`
+
+``fire_upwinding_reinit``: *integer* (Default: ``4``)
+   Numerical scheme (space) for reinitialization :term:`PDE`.
+     1: WENO3
+
+     2: WENO5
+
+     3: hybrid WENO3-ENO1
+
+     4: hybrid WENO5-ENO1
+
+``fire_lsm_band_ngp``: *integer* (Default: ``4``)
+   When using ``fire_upwinding_reinit=3,4`` and ``fire_upwinding=8/9``, the number of grid points around lfn=0 that WENO5/3 is used
+
+``fire_lsm_zcoupling``: *logical* (Default: ``1``)
+   When true, uses ``fire_lsm_zcoupling_ref`` instead of ``fire_wind_height`` as a reference height to calculate the logarithmic surface layer wind profile
+
+``fire_lsm_zcoupling_ref``: *real* (Default: ``50.0``)
+   [Units: m]
+   Reference height from which the velocity at ``fire_wind_height`` is calculated using a logarithmic profile
+
+``fire_viscosity_bg``: *real* (Default: ``0.4``)
+   Artificial viscosity in the near-front region
+
+``fire_viscosity_band``: *real* (Default: ``0.5``)
+   Number of times the hybrid advection band to transition from ``fire_viscosity_bg`` to ``fire_viscosity``
+
+``fire_viscosity_ngp``: *integer* (Default: ``2``)
+   Number of grid points around lfn=0 where ``fire_viscosity_bg`` is used
+
+``fmoist_run``: *logical* (Default: ``.false.``)
+   Runs moisture model on the atmospheric grid, outputting the result as a variable named ``fmc_gc``
+
+``fmoist_freq``: *integer* (Default: ``0``)
+   Frequency to run moisture model.
+     0: use ``fmoist_dt``
+
+     k>0: every "k" timesteps
+
+``fmoist_dt``: *real* (Default: ``600.0``)
+   [Units: s]
+   Time step of moisture model (only used if ``fmoist_freq=0``)
+
+``fire_wind_height``: *integer* (Default: ``6.096``)
+   [Units: m]
+   Height of uah,vah wind in fire spread formula
+
+``fire_is_real_perim``: *logical* (Default: ``.false.``)
+   Determines if perimeter represents a real fire boundary.
+     .true. = observed perimeter
+
+     .false. = point/line ignition
+
+``frac_fburnt_to_smoke``: *real* (Default: ``0.02``)
+   [Units: g/kg]
+   Parts per unit of burned fuel converted to smoke, represented as grams of smoke per kilogram of air.
+
+``fuelmc_g``: *real* (Default: ``0.08``)
+   Fuel moisture content ground (Dead :term:`FMC`)
+
+``fuelmc_g_live``: *real* (Default: ``0.30``)
+   Fuel moisture content ground (Live :term:`FMC`). 30% Completely cured, treat as dead fuel
+
+``fuelmc_c``: *real* (Default: ``1.00``)
+   Fuel moisture content of the canopy
+
+``fuel_opt``: *integer* (Default: ``1``)
+   Fuel type model.
+     1:  Anderson fuel model (only option currently implemented)
+
+``ros_opt``: *integer* (Default: ``0``)
+   Rate of Spread (ROS) parameterization option.
+     0: Rothermel model (only option currently implemented)
+
+``fmc_opt``: *integer* (Default: ``1``)
+   :term:`FMC` model
+     -1 = Constant fuel moisture (only option currently implemented)
+
+``fire_num_ignitions``: *integer* (Default: ``1``)
+   Number of ignitions for fire initiation. Maximum of 5.
+
+.. note::
+  For each additional fire ignition, you must specify an additional set of ignition parameters below, with increasing numerical suffixes ( *e.g.* ``fire_ignition_start_lon2``, ``fire_ignition_start_lon3``, etc. )
+
+``fire_ignition_start_lon1``: *real* (Default: ``0.0``)
+   Longitude of first ignition start point.
+
+``fire_ignition_start_lat1``: *real* (Default: ``0.0``)
+   Latitude of first ignition start point.
+
+``fire_ignition_end_lon1``: *real* (Default: ``0.0``)
+   Longitude of first ignition end point.
+
+``fire_ignition_end_lat1``: *real* (Default: ``0.0``)
+   Latitude of first ignition end point.
+
+``fire_ignition_ros1``: *real* (Default: ``0.01``)
+   [Units: m/s]
+   Rate of spread for first ignition (Rothermel parameterization).
+
+``fire_ignition_start_time1``: *real* (Default: ``0.0``)
+   [Units: s]
+   Start time of first ignition in seconds (counting from the beginning of the simulation)
+
+``fire_ignition_end_time1``: *real* (Default: ``1``)
+   [Units: s]
+   End time of first ignition in seconds (counting from the beginning of the simulation)
+
+``fire_ignition_radius1``: *real* (Default: ``0.0``)
+   [Units: m]
+   Radius of the ignition area for first ignition.
+
+

doc/Glossary.rst

@@ -0,0 +1,73 @@
+.. _Glossary:
+
+*************************
+Glossary
+*************************
+
+.. glossary::
+
+   advect
+   advection
+      According to the American Meteorological Society (AMS) definition, `advection <https://glossary.ametsoc.org/wiki/Advection>`_ is "The process of transport of an atmospheric property solely by the mass motion (velocity field) of the atmosphere." In common parlance, advection is movement of atmospheric substances that are carried around by the wind.
+
+   CCPP
+      The `Common Community Physics Package <https://dtcenter.org/community-code/common-community-physics-package-ccpp>`_ is a forecast-model agnostic, vetted collection of code containing atmospheric physical parameterizations and suites of parameterizations for use in Numerical Weather Prediction (NWP) along with a framework that connects the physics to the host forecast model.
+
+   ESMF
+      `Earth System Modeling Framework <https://earthsystemmodeling.org/docs/release/latest/ESMF_usrdoc/>`__. The ESMF defines itself as “a suite of software tools for developing high-performance, multi-component Earth science modeling applications.” 
+
+   FMC
+      Fuel moisture content
+
+   FV3
+      The Finite-Volume Cubed-Sphere :term:`dynamical core` (dycore). Developed at NOAA's `Geophysical 
+      Fluid Dynamics Laboratory <https://www.gfdl.noaa.gov/>`__ (GFDL), it is a scalable and flexible dycore capable of both hydrostatic and non-hydrostatic atmospheric simulations. It is the dycore used in the UFS Weather Model.
+
+   HRRR
+      `High Resolution Rapid Refresh <https://rapidrefresh.noaa.gov/hrrr/>`__. The HRRR is a NOAA real-time 3-km resolution, hourly updated, cloud-resolving, convection-allowing atmospheric model initialized by 3km grids with 3km radar assimilation. Radar data is assimilated in the HRRR every 15 min over a 1-h period adding further detail to that provided by the hourly data assimilation from the 13km radar-enhanced Rapid Refresh.
+
+   ICs
+      Initial conditions
+
+   level-set method
+      A commonly used method in wildland fire modeling used to track and propogate the fire perimiter. More details available in :cite:alp:`LevelSetMethod`.
+
+   LBCs
+      Lateral boundary conditions
+
+   namelist
+      A namelist defines a group of variables or arrays. Namelists are an I/O feature for format-free input and output of variables by key-value assignments in Fortran compilers. Fortran variables can be read from and written to plain-text files in a standardised format, usually with a ``.nml`` file ending.
+
+   NCAR
+      The National Science Foundation's `National Center for Atmospheric Research <https://ncar.ucar.edu/>`__. 
+
+   NCEP
+      National Centers for Environmental Prediction (NCEP) is an arm of the National Weather Service
+      consisting of nine centers. More information can be found at https://www.ncep.noaa.gov.
+
+   netCDF
+      NetCDF (`Network Common Data Form <https://www.unidata.ucar.edu/software/netcdf/>`__) is a file format and community standard for storing multidimensional scientific data. It includes a set of software libraries and machine-independent data formats that support the creation, access, and sharing of array-oriented scientific data.
+
+   NUOPC
+      The `National Unified Operational Prediction Capability <https://earthsystemmodeling.org/nuopc/>`__ Layer "defines conventions and a set of generic components for building coupled models using the Earth System Modeling Framework (:term:`ESMF`)." 
+
+   NWS
+      The `National Weather Service <https://www.weather.gov/>`__ (NWS) is an agency of the United States government that is tasked with providing weather forecasts, warnings of hazardous weather, and other weather-related products to organizations and the public for the purposes of protection, safety, and general information. It is a part of the National Oceanic and Atmospheric Administration (NOAA) branch of the Department of Commerce.
+
+   Parameterizations
+      Simplified functions that approximate the effects of small-scale processes (e.g., microphysics, gravity wave drag) that cannot be explicitly resolved by a model grid’s representation of the earth.
+
+   PDE
+      Partial differential equation
+
+   SDF
+      Suite Definition File. An external file containing information about the construction of a physics suite. It describes the schemes that are called, in which order they are called, whether they are subcycled, and whether they are assembled into groups to be called together.
+
+   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."
+
+   UFS
+      The Unified Forecast System is a community-based, coupled, comprehensive Earth modeling 
+      system consisting of several applications (apps). These apps span regional to global 
+      domains and sub-hourly to seasonal time scales. The UFS is designed to support the :term:`Weather Enterprise` and to be the source system for NOAA's operational numerical weather prediction applications. For more information, visit https://ufs.epic.noaa.gov/.
+

doc/Idealized.rst

@@ -0,0 +1,13 @@
+.. _Idealized:
+
+=====================
+CFBM: Idealized cases
+=====================
+
+Under construction
+
+.. image:: https://media.tenor.com/4fu8LKc2vZ4AAAAi/under-construction-wip.gif
+   :height: 400
+   :alt: An animated construction sign
+   :align: center
+

doc/Introduction.rst

@@ -0,0 +1,19 @@
+.. _Introduction:
+
+==============
+Introduction
+==============
+
+This is the users guide for the Community Fire Behavior Model (CFBM).
+
+This page is under construction
+
+.. image:: https://media.tenor.com/4fu8LKc2vZ4AAAAi/under-construction-wip.gif
+   :height: 400
+   :alt: An animated construction sign
+   :align: center
+
+References
+=================
+
+.. bibliography:: references.bib