Skip to content

Commit

Permalink
doc: update histfreq_base and hist_avg descriptions (#898)
Browse files Browse the repository at this point in the history
* doc: ug_implementation.rst: do not use curly quotes

The namelist excerpt in section 'History' of the Implementation part of
the user guide uses curly quotes (’) instead of regular straight quotes
('). This is probably a remnant of the LaTeX version of the doc. These
quotes can't be used in Fortran and so copy pasting from the doc to the
namelist causes runtime failures. Use straigth quotes instead.

* doc: ug_implementation.rst: align histfreq_n with histfreq

Align frequencies with their respective streams, which makes the example
clearer.

* doc: ug_implementation.rst: avoid "now" and "still"

The documentation talks about the current version of the code, so it is
unnecessary to use words like "now" and "still" to talk about the model
features. Remove them.

* doc: ug_implementation.rst: mention histfreq_base and hist_avg are per-stream

In 35ec167 (Add functionality to change hist_avg for each stream
(#827), 2023-05-17), hist_avg was made into an array, allowing each
stream to individually be set to instantaneous or averaged mode. The
first paragraph of the "History" section of the user guide was updated,
but another paragraph a little below was not.

In 933b148 (Extend restart output controls, provide multiple frequency
options (#850), 2023-08-24), histfreq_base was also made into an array,
but the "History" section of the user guide was not updated.

Adjust the wording of the doc to reflect the fact that both hist_avg and
histfreq_base are per-stream. Also adjust the namelist excerpt to make
histfreq_base an array, and align hist_avg with it.

* doc: ug_implementation.rst: refer to 'timemanager' after mentioning histfreq_base

In 34dc667 (Namelist option for time axis position. (#839),
2023-07-06), the namelist option hist_time_axis was added, and the
"History" section of the user guide updated to mention it.

The added sentence, however, separates the mention of 'histfreq_base'
and the reference to the "Time manager" section, which explains the
different allowed values for that variable. Move the reference up so
both are next to each other.
  • Loading branch information
phil-blain committed Oct 26, 2023
1 parent b4abca4 commit 2e13606
Showing 1 changed file with 19 additions and 17 deletions.
36 changes: 19 additions & 17 deletions doc/source/user_guide/ug_implementation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1192,33 +1192,35 @@ The history modules allow output at different frequencies. Five output
frequencies (``1``, ``h``, ``d``, ``m``, ``y``) are available simultaneously during a run.
The same variable can be output at different frequencies (say daily and
monthly) via its namelist flag, `f\_` :math:`\left<{var}\right>`, which
is now a character string corresponding to ``histfreq`` or ‘x’ for none.
(Grid variable flags are still logicals, since they are written to all
is a character string corresponding to ``histfreq`` or ‘x’ for none.
(Grid variable flags are logicals, since they are written to all
files, no matter what the frequency is.) If there are no namelist flags
with a given ``histfreq`` value, or if an element of ``histfreq_n`` is 0, then
no file will be written at that frequency. The output period can be
discerned from the filenames. All history streams will be either instantaneous
or averaged as specified by the ``hist_avg`` namelist setting and the frequency
will be relative to a reference date specified by ``histfreq_base``. Also, some
discerned from the filenames. Each history stream will be either instantaneous
or averaged as specified by the corresponding entry in the ``hist_avg`` namelist array, and the frequency
will be relative to a reference date specified by the corresponding entry in ``histfreq_base``.
More information about how the frequency is
computed is found in :ref:`timemanager`.
Also, some
Earth Sytem Models require the history file time axis to be centered in the averaging
interval. The flag ``hist_time_axis`` will allow the user to chose ``begin``, ``middle``,
or ``end`` for the time stamp. More information about how the frequency is
computed is found in :ref:`timemanager`.
or ``end`` for the time stamp.

For example, in the namelist:

::

histfreq = ’1’, ’h’, ’d’, ’m’, ’y’
histfreq_n = 1, 6, 0, 1, 1
histfreq_base = 'zero'
hist_avg = .true.,.true.,.true.,.true.,.true.
f_hi = ’1’
f_hs = ’h’
f_Tsfc = ’d’
f_aice = ’m’
f_meltb = ’mh’
f_iage = ’x’
histfreq = '1', 'h', 'd', 'm', 'y'
histfreq_n = 1 , 6 , 0 , 1 , 1
histfreq_base = 'zero','zero','zero','zero','zero'
hist_avg = .true.,.true.,.true.,.true.,.true.
f_hi = '1'
f_hs = 'h'
f_Tsfc = 'd'
f_aice = 'm'
f_meltb = 'mh'
f_iage = 'x'

Here, ``hi`` will be written to a file on every timestep, ``hs`` will be
written once every 6 hours, ``aice`` once a month, ``meltb`` once a month AND
Expand Down

0 comments on commit 2e13606

Please sign in to comment.