From 101cb89236c8dcaa5a52d2e091a58c6695750648 Mon Sep 17 00:00:00 2001 From: Philippe Blain Date: Thu, 26 Oct 2023 10:41:43 -0400 Subject: [PATCH 1/5] doc: ug_implementation.rst: do not use curly quotes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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/source/user_guide/ug_implementation.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/source/user_guide/ug_implementation.rst b/doc/source/user_guide/ug_implementation.rst index 8480eb9aa..414a9b64f 100644 --- a/doc/source/user_guide/ug_implementation.rst +++ b/doc/source/user_guide/ug_implementation.rst @@ -1209,16 +1209,16 @@ For example, in the namelist: :: - histfreq = ’1’, ’h’, ’d’, ’m’, ’y’ + 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’ + 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 From 3e15203dad2d5aa6210de98334bbd2dbbcec44a4 Mon Sep 17 00:00:00 2001 From: Philippe Blain Date: Thu, 26 Oct 2023 10:49:54 -0400 Subject: [PATCH 2/5] doc: ug_implementation.rst: align histfreq_n with histfreq Align frequencies with their respective streams, which makes the example clearer. --- doc/source/user_guide/ug_implementation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/user_guide/ug_implementation.rst b/doc/source/user_guide/ug_implementation.rst index 414a9b64f..d6e163b72 100644 --- a/doc/source/user_guide/ug_implementation.rst +++ b/doc/source/user_guide/ug_implementation.rst @@ -1209,8 +1209,8 @@ For example, in the namelist: :: - histfreq = '1', 'h', 'd', 'm', 'y' - histfreq_n = 1, 6, 0, 1, 1 + 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' From 29d9454f1425d40aacb01355be4c76611fc93ae6 Mon Sep 17 00:00:00 2001 From: Philippe Blain Date: Thu, 26 Oct 2023 11:03:57 -0400 Subject: [PATCH 3/5] 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/source/user_guide/ug_implementation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/user_guide/ug_implementation.rst b/doc/source/user_guide/ug_implementation.rst index d6e163b72..f30be72fd 100644 --- a/doc/source/user_guide/ug_implementation.rst +++ b/doc/source/user_guide/ug_implementation.rst @@ -1192,8 +1192,8 @@ 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 From bb16e32ed01573add8659f2d73430603d46bf2da Mon Sep 17 00:00:00 2001 From: Philippe Blain Date: Thu, 26 Oct 2023 11:14:59 -0400 Subject: [PATCH 4/5] 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/source/user_guide/ug_implementation.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/source/user_guide/ug_implementation.rst b/doc/source/user_guide/ug_implementation.rst index f30be72fd..26073a8e8 100644 --- a/doc/source/user_guide/ug_implementation.rst +++ b/doc/source/user_guide/ug_implementation.rst @@ -1197,9 +1197,9 @@ is a character string corresponding to ``histfreq`` or ‘x’ for none. 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``. 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 @@ -1211,8 +1211,8 @@ 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. + histfreq_base = 'zero','zero','zero','zero','zero' + hist_avg = .true.,.true.,.true.,.true.,.true. f_hi = '1' f_hs = 'h' f_Tsfc = 'd' From 0743f6b9d54ad3601baf6d1e89ffaf155f08f769 Mon Sep 17 00:00:00 2001 From: Philippe Blain Date: Thu, 26 Oct 2023 11:49:26 -0400 Subject: [PATCH 5/5] 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 | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/source/user_guide/ug_implementation.rst b/doc/source/user_guide/ug_implementation.rst index 26073a8e8..7cdec0c85 100644 --- a/doc/source/user_guide/ug_implementation.rst +++ b/doc/source/user_guide/ug_implementation.rst @@ -1199,11 +1199,13 @@ 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. 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``. Also, some +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: