From 2e13606558f7ce71633274bc38630caa23de3392 Mon Sep 17 00:00:00 2001 From: Philippe Blain Date: Thu, 26 Oct 2023 13:24:37 -0400 Subject: [PATCH] doc: update histfreq_base and hist_avg descriptions (#898) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 35ec167d (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 933b148c (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 34dc6670 (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. --- doc/source/user_guide/ug_implementation.rst | 36 +++++++++++---------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/doc/source/user_guide/ug_implementation.rst b/doc/source/user_guide/ug_implementation.rst index b24d96909..ab1d2fcc3 100644 --- a/doc/source/user_guide/ug_implementation.rst +++ b/doc/source/user_guide/ug_implementation.rst @@ -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