Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: model output and appendix #798

Merged
merged 1 commit into from
Dec 21, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 133 additions & 11 deletions docs/userguide/appendices.rest
Original file line number Diff line number Diff line change
Expand Up @@ -1473,6 +1473,27 @@ land cover type.
| vcmx25 | Maximum rate of carboxylation at 25°C |
| | [:math:`umol\ CO_{2}/m^2/s`] |
+------------+----------------------------------------------------------+
| AXAJ | Tension water distribution inflection parameter |
+------------+----------------------------------------------------------+
| BXAJ | Tension water distribution shape parameter |
+------------+----------------------------------------------------------+
| XXAJ | Free water distribution shape parameter |
+------------+----------------------------------------------------------+
| rsurfsnow | Surface resistance for snow [s/m] |
+------------+----------------------------------------------------------+
| scamax | Maximum fractional snow covered area [0-1] |
+------------+----------------------------------------------------------+
| snowretfac | Snowpack water release timescale factor [1/s] |
+------------+----------------------------------------------------------+
| ssi | Liquid water holding capacity for snowpack |
| | [:math:`m^3/m^3`] |
+------------+----------------------------------------------------------+
| tau0 | Snow albedo decay timescale parameter [s] |
+------------+----------------------------------------------------------+
| imperv | Impervious factor |
+------------+----------------------------------------------------------+



.. _section-a8:

Expand Down Expand Up @@ -1535,6 +1556,10 @@ within these files are described in the tables below.
| LKSAT | Lateral saturated soil hydraulic |
| | conductivity [:math:`m/s`] |
+-----------------------+----------------------------------------------+
| NEXP | Exponent in the decay function for lateral |
| | Ksat over depth |
+-----------------------+----------------------------------------------+


.. _section-a9:

Expand Down Expand Up @@ -1611,12 +1636,18 @@ the tables below.
+----------------------+-----------------------------------------------+
| n | Manning's roughness |
+----------------------+-----------------------------------------------+
| nCC | Compound Channel Manning's roughness |
+----------------------+-----------------------------------------------+
| order | Strahler stream order |
+----------------------+-----------------------------------------------+
| to | To Link ID |
+----------------------+-----------------------------------------------+
| time | Time of measurement |
+----------------------+-----------------------------------------------+
| TopWdth | Top Width [m] |
+----------------------+-----------------------------------------------+
| TopWdthCC | Compound Channel Top Width [m] |
+----------------------+-----------------------------------------------+

.. _section-a10:

Expand Down Expand Up @@ -1667,6 +1698,8 @@ in the tables below.
+-----------------------+----------------------------------------------+
| ComID | NHDCatchment FEATUREID (NHDFlowline ComID) |
+-----------------------+----------------------------------------------+
| Loss | Fraction of bucket output lost |
+-----------------------+----------------------------------------------+

.. _section-20:

Expand Down Expand Up @@ -1757,6 +1790,38 @@ Variables within the `LAKEPARM.nc` file are described in the tables below.
A13. Restart Files Overview
----------------------------

**Cold start versus warm start model simulations:**

When one start the model as a `cold start` (meaning that it is starting with the default values at the very
beginning), it takes time for the model to warm up and reach an equilibrium state. For example, consider
simulating streamflow values for a stream which has a base flow of at least 10 cms during the year, and you
have a `cold start`. The default values of the streamflow might be zeros at the start of the modeling. It then
takes time for the simulated streamflow within the model to reach the 10 cms. In contrast, a `warm start` is
when the model simulation begins with the simulated values of a given time step (starting time step) from a
previous run. This eliminates the processing time the model would take to reach an equilibrium state.
Depending on which variable of the model you are looking at, the time required to reach to the warm state may
differ. For example, groundwater requires a longer time period to reach to equilibrium.

**How to do a warm start simulations with WRF-Hydro?**

WRF-Hydro model outputs two set of model restart files (:file:`RESTART.YYYYmmddHH_DOMAIN` and
:file:`HYDRO_RST.YYYY-mm-dd_HH:MM_DOMAIN1`) which store the model states at a specified time and
could be used to start the model from that point in time. :file:`RESTART.YYYYmmddHH_DOMAIN` stores the
state variables reqiured for restarting LSM and :file:`HYDRO_RST.YYYY-mm-dd_HH:MM_DOMAIN`
stores the state variables required to resume the hydro components of the WRF-Hydro model.

To warm start the LSM part of the model, specify path to the restart file in the :file:`namelist.hrldas`
using `RESTART\_FILENAME\_REQUESTED` option.
To warm start the HYDRO part of the model, specify the path to the `HYDRO\_RST` file in
the :file:`hydro.namelist` using the option `RESTART\_FILE`, and also set the `gw\_restart` option to 1.
If the path to the files are left empty or commented out, it means the model simulation is cold started.


One could control the frequency of outputting restart files using the options `RESTART\_FREQUENCY\_HOURS`
and `rst\_dt` in the :file:`namelist.hrldas` and :file:`hydro.namelist`, respectively. If these options are set
to -9999, model outputs restart files once a month. Restart files are large in size, and therefore user
needs to be cautious of how frequently it outputs the restart files.

.. figure:: media/restarts.png
:align: center

Expand All @@ -1780,6 +1845,14 @@ A13.1 RESTART_MP File Variable Table
| **Variable | **Description** | **Units** |
| name** | | |
+=============+===========================================+==================+
| ACCPRCP | Accumulated precipitation | :math:`mm` |
+-------------+-------------------------------------------+------------------+
| ACCECAN | Accumulated canopy evaporation | :math:`mm` |
+-------------+-------------------------------------------+------------------+
| ACCEDIR | Accumulated direct soil evaporation | :math:`mm` |
+-------------+-------------------------------------------+------------------+
| ACCETRAN | Accumulated transpiration | :math:`mm` |
+-------------+-------------------------------------------+------------------+
| ACMELT | accumulated melting water out of snow | :math:`mm` |
| | bottom | |
+-------------+-------------------------------------------+------------------+
Expand Down Expand Up @@ -1902,24 +1975,16 @@ A13.1 RESTART_MP File Variable Table
+-------------+-------------------------------------------+------------------+
| VEGFRA | Vegetation fraction | |
+-------------+-------------------------------------------+------------------+
| ACCPRCP | Accumulated precipitation | :math:`mm` |
+-------------+-------------------------------------------+------------------+
| ACCECAN | Accumulated canopy evaporation | :math:`mm` |
+-------------+-------------------------------------------+------------------+
| ACCEDIR | Accumulated direct soil evaporation | :math:`mm` |
+-------------+-------------------------------------------+------------------+
| ACCETRAN | Accumulated transpiration | :math:`mm` |
+-------------+-------------------------------------------+------------------+
| SMOISEQ | volumetric soil moisture | :math:`m^3/m^3` |
+-------------+-------------------------------------------+------------------+



.. _section-23:

A13.2 HYDRO_RST File Variable Table
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
The variables are written to the `HYDRO_RST` file in the subroutine of
The variables are written to the `HYDRO\_RST` file in the subroutine of
``RESTART_OUT_nc`` in the :file:`Routing/module_HYDRO_io.F90`. The tables below
contain all the information on the dimensions and variables in the Hydro
RESTART file (`HYDRO\_RST`).
Expand Down Expand Up @@ -2672,3 +2737,60 @@ layers contain the initialized ice.
surface runoff, thus ``FLOW_SNOW`` and ``FLOW_ICE`` cannot be used directly
as indication if melt is from the ice part of the glacier or snow part of
the glacier.


.. _section-a17:

A17. Model Output Variables
---------------------------------------------

.. rubric:: 1. Land surface model output variables

\
:file:`{YYYYMMDDHHMM}.LDASOUT_DOMAIN{X}`

.. rubric:: 2. Land surface diagnostic output variables

\
:file:`{YYYYMMDDHHMM}.LSMOUT_DOMAIN{X}`


.. rubric:: 3. Streamflow output variables at all channel reaches/cells

\
:file:`{YYYYMMDDHHMM}.CHRTOUT_DOMAIN{X}`



.. rubric:: 4. Streamflow output variables at forecast points or gage reaches/cells

\
:file:`{YYYYMMDDHHMM}.CHANOBS_DOMAIN{X}`



.. rubric:: 5. Streamflow output variables on the 2D high resolution routing grid

\
:file:`{YYYYMMDDHHMM}.CHRTOUT_GRID{X}`



.. rubric:: 6. Terrain routing variables on the 2D high resolution routing grid

\
:file:`{YYYYMMDDHHMM}.RTOUT_DOMAIN{X}`



.. rubric:: 7. Lake output variables

\
:file:`{YYYYMMDDHHMM}.LAKEOUT_DOMAIN{X}`



.. rubric:: 8. Ground water output variables

\
:file:`{YYYYMMDDHHMM}.GWOUT_DOMAIN{X}`
14 changes: 6 additions & 8 deletions docs/userguide/model-outputs.rest
Original file line number Diff line number Diff line change
Expand Up @@ -76,10 +76,8 @@ of compression files contain.
be zero for running a gridded channel routing configuration of the model.

An overview of available model output files is shown in :ref:`Figure 6.1 <figure-6.1>`.
For a detailed table of each variable contained within each output file, see
the *WRF-Hydro Output Variable Matrix V5* located on our website
(`https://ral.ucar.edu/projects/wrf_hydro <https://ral.ucar.edu/projects/wrf_hydro/pre-processing-tools>`__)
for details. There is no optimal combination of namelist options to use
For a detailed table of each variable contained within each output file, see :ref:`A17 <section-a17>`.
There is no optimal combination of namelist options to use
for outputs. Flexibility was given to the user as end applications will
vary from one user to another. While a combination of many output
variables with compression may work for a one-time model simulation,
Expand Down Expand Up @@ -148,7 +146,7 @@ predefined link ID value specified via the :file:`Route_Link.nc` file. All files
contain ``model_initialization_time`` and ``model_output_valid_time`` character
attributes to offer additional time information about the output file.
For files that were produced with ``io_form_outputs`` options of ``1`` or ``2``,
standard netCDF variable attributes ``scale_factor`` and add_``offset are
standard netCDF variable attributes ``scale_factor`` and ``add_offset`` are
present to help users and netCDF APIs unpack integer data back to
floating point for visualization and analysis. For a more in-depth
description of netCDF CF compliant output, please visit
Expand Down Expand Up @@ -269,7 +267,7 @@ the domain number of the geogrid input file)
description of the Route_Link.nc file in Appendix :ref:`A9 <section-a9>`),
and size 15. If a channel reach does not contain a gage, the string
stays empty. For example, ``" "`` would represent a channel
reach with no gage, and ``" 07124000"`` would contain a gage labeled
reach with no gage, and ``" 07124000"`` would contain a gage labeled
“07124000”. It is up to the user to create this variable and populate it with
character strings if there is a desire to connect gage locations to channel
reaches. If no locations are found, the output code will simply bypass
Expand All @@ -281,7 +279,7 @@ the domain number of the geogrid input file)
\
:file:`{YYYYMMDDHHMM}.CHRTOUT_GRID{X}`

The ``CHRTOUT_GRID`` option in the :file"`hydro.namelist` is used to activate this
The ``CHRTOUT_GRID`` option in the :file:`hydro.namelist` is used to activate this
output. This output file is a 2D file created from streamflow with 2D gridded
channel routing. Currently, this file is not available for reach-based
routing as channel routing does not occur on the channel grid. Output
Expand Down Expand Up @@ -321,7 +319,7 @@ the domain number of the geogrid input file)
.. rubric:: 8. Ground water output variables

\
:file:`{YYYYMMDDHHMM}.GWOUT_DOMAIN{X}``
:file:`{YYYYMMDDHHMM}.GWOUT_DOMAIN{X}`

The ``output_gw`` option in the :file:`hydro.namelist` will activate this output.
When groundwater buckets are activated in the model simulations, it is
Expand Down
Loading