Changeset 12377 for NEMO/trunk/doc/latex/NEMO/subfiles/chap_misc.tex

Timestamp:

2020-02-12T15:39:06+01:00 (4 years ago)

Author:

acc

Message:

The big one. Merging all 2019 developments from the option 1 branch back onto the trunk.

This changeset reproduces 2019/dev_r11943_MERGE_2019 on the trunk using a 2-URL merge
onto a working copy of the trunk. I.e.:

svn merge --ignore-ancestry \

​svn+ssh://acc@forge.ipsl.jussieu.fr/ipsl/forge/projets/nemo/svn/NEMO/trunk \
​svn+ssh://acc@forge.ipsl.jussieu.fr/ipsl/forge/projets/nemo/svn/NEMO/branches/2019/dev_r11943_MERGE_2019 ./

The --ignore-ancestry flag avoids problems that may otherwise arise from the fact that
the merge history been trunk and branch may have been applied in a different order but
care has been taken before this step to ensure that all applicable fixes and updates
are present in the merge branch.

The trunk state just before this step has been branched to releases/release-4.0-HEAD
and that branch has been immediately tagged as releases/release-4.0.2. Any fixes
or additions in response to tickets on 4.0, 4.0.1 or 4.0.2 should be done on
releases/release-4.0-HEAD. From now on future 'point' releases (e.g. 4.0.2) will
remain unchanged with periodic releases as needs demand. Note release-4.0-HEAD is a
transitional naming convention. Future full releases, say 4.2, will have a release-4.2
branch which fulfills this role and the first point release (e.g. 4.2.0) will be made
immediately following the release branch creation.

2020 developments can be started from any trunk revision later than this one.

Location:

NEMO/trunk

Files:

• . (modified) (1 prop)
• doc/latex/NEMO/subfiles/chap_misc.tex (modified) (1 diff)

NEMO/trunk

@@ -3 +3 @@
 ^/utils/build/mk@HEAD         mk
 ^/utils/tools@HEAD            tools
-^/vendors/AGRIF/dev@HEAD      ext/AGRIF
+^/vendors/AGRIF/dev_r11615_ENHANCE-04_namelists_as_internalfiles_agrif@HEAD      ext/AGRIF
 ^/vendors/FCM@HEAD            ext/FCM
 ^/vendors/IOIPSL@HEAD         ext/IOIPSL

@@ -3 +3 @@
 ^/utils/build/mk@HEAD         mk
 ^/utils/tools@HEAD            tools
-^/vendors/AGRIF/dev@HEAD      ext/AGRIF
+^/vendors/AGRIF/dev_r11615_ENHANCE-04_namelists_as_internalfiles_agrif@HEAD      ext/AGRIF
 ^/vendors/FCM@HEAD            ext/FCM
 ^/vendors/IOIPSL@HEAD         ext/IOIPSL

NEMO/trunk/doc/latex/NEMO/subfiles/chap_misc.tex

@@ -362 +362 @@
 
 %% =================================================================================================
-\subsection{Control print}
-
-The \np{ln_ctl}{ln\_ctl} switch was originally used as a debugging option in two modes:
-
-\begin{enumerate}
-\item {\np{ln_ctl}{ln\_ctl}: compute and print the trends averaged over the interior domain in all TRA, DYN, LDF and
-ZDF modules.
-This option is very helpful when diagnosing the origin of an undesired change in model results. }
-
-\item {also \np{ln_ctl}{ln\_ctl} but using the nictl and njctl namelist parameters to check the source of differences between
-mono and multi processor runs.}
+\subsection{Status and debugging information output}
+
+
+NEMO can produce a range of text information output either: in the main output
+file (ocean.output) written by the normal reporting processor (narea == 1) or various
+specialist output files (e.g. layout.dat, run.stat, tracer.stat etc.). Some, for example
+run.stat and tracer.stat, contain globally collected values for which a single file is
+sufficient. Others, however, contain information that could, potentially, be different
+for each processing region. For computational efficiency, the default volume of text
+information produced is reduced to just a few files from the narea=1 processor.
+
+When more information is required for monitoring or debugging purposes, the various
+forms of output can be selected via the \np{sn\_cfctl} structure. As well as simple
+on-off switches this structure also allows selection of a range of processors for
+individual reporting (where appropriate) and a time-increment option to restrict
+globally collected values to specified time-step increments.
+
+Most options within the structure are influenced by the top-level switches shown here
+with their default settings:
+
+\begin{verbatim}
+   sn_cfctl%l_allon  = .FALSE.    ! IF T activate all options. If F deactivate all unless l_config is T
+     sn_cfctl%l_config = .TRUE.     ! IF .true. then control which reports are written with the following
+\end{verbatim}
+
+The first switch is a convenience option which can be used to switch on and off all
+sub-options. However, if it is false then switching off all sub-options is only done
+if \texttt{sn_cfctl%l\_config} is also false. Specifically, the logic is:
+
+\begin{verbatim}
+  IF ( sn_cfctl%l_allon ) THEN
+    set all suboptions .TRUE.
+    and set procmin, procmax and procincr so that all regions are selected ([0,10000000,1], respectively)
+  ELSEIF ( sn_cfctl%l_config ) THEN
+    honour individual settings of the suboptions from the namelist
+  ELSE
+    set all suboptions .FALSE.
+  ENDIF
+\end{verbatim}
+
+Details of the suboptions follow but first an explanation of the stand-alone option:
+\texttt{sn_cfctl%l_glochk}.  This option modifies the action of the early warning checks
+carried out in \textt{stpctl.F90}. These checks detect probable numerical instabilites
+by searching for excessive sea surface heights or velocities and salinity values
+outside a sensible physical range. If breaches are detected then the default behaviour
+is to locate and report the local indices of the grid-point in breach. These indices
+are included in the error message that precedes the model shutdown. When true,
+\texttt{sn_cfctl%l_glochk} modifies this action by performing a global location of
+the various minimum and maximum values and the global indices are reported. This has
+some value in locating the most severe error in cases where the first detected error
+may not be the worst culprit.
+
+\subsubsection{Control print suboptions}
+
+The options that can be individually selected fall into three categories:
+
+\begin{enumerate} \item{Time step progress information} This category includes
+\texttt{run.stat} and \texttt{tracer.stat} files which record certain physical and
+passive tracer metrics (respectively). Typical contents of \texttt{run.stat} include
+global maximums of ssh, velocity; and global minimums and maximums of temperature
+and salinity.  A netCDF version of \texttt{run.stat} (\texttt{run.stat.nc}) is also
+produced with the same time-series data and this can easily be expanded to include
+extra monitoring information.  \texttt{tracer.stat} contains the volume-weighted
+average tracer value for each passive tracer. Collecting these metrics involves
+global communications and will impact on model efficiency so both these options are
+disabled by default by setting the respective options, \texttt{sn\_cfctl%runstat} and
+\texttt{sn\_cfctl%trcstat} to false. A compromise can be made by activating either or
+both of these options and setting the \texttt{sn\_cfctl%timincr} entry to an integer
+value greater than one. This increment determines the time-step frequency at which
+the global metrics are collected and reported.  This increment also applies to the
+time.step file which is otherwise updated every timestep.
+\item{One-time configuration information/progress logs}
+
+Some run-time configuration information and limited progress information is always
+produced by the first ocean process. This includes the \texttt{ocean.output} file
+which reports on all the namelist options read by the model and remains open to catch
+any warning or error messages generated during execution. A \texttt{layout.dat}
+file is also produced which details the MPI-decomposition used by the model. The
+suboptions: \texttt{sn\_cfctl%oceout} and \texttt{sn\_cfctl%layout} can be used
+to activate the creation of these files by all ocean processes.  For example,
+when \texttt{sn\_cfctl%oceout} is true all processors produce their own version of
+\texttt{ocean.output}.  All files, beyond the the normal reporting processor (narea == 1), are
+named with a \_XXXX extension to their name, where XXXX is a 4-digit area number (with
+leading zeros, if required). This is useful as a debugging aid since all processes can
+report their local conditions. Note though that these files are buffered on most UNIX
+systems so bug-hunting efforts using this facility should also utilise the \fortran:
+
+\begin{verbatim} 
+   CALL FLUSH(numout)
+\end{verbatim}
+
+statement after any additional write statements to ensure that file contents reflect
+the last model state. Associated with the \texttt{sn\_cfctl%oceout} option is the
+additional \texttt{sn\_cfctl%oasout} suboption. This does not activate its own output
+file but rather activates the writing of addition information regarding the OASIS
+configuration when coupling via oasis and the sbccpl routine. This information is
+written to any active \texttt{ocean.output} files.
+\item{Control sums of trends for debugging}
+
+NEMO includes an option for debugging reproducibility differences between
+a MPP and mono-processor runs.  This is somewhat dated and clearly only
+useful for this purpose when dealing with configurations that can be run
+on a single processor. The full details can be found in this report: \href{
+http://forge.ipsl.jussieu.fr/nemo/attachment/wiki/Documentation/prtctl_NEMO_doc_v2.pdf}{The
+control print option in NEMO} The switches to activate production of the control sums
+of trends for either the physics or passive tracers are the \texttt{sn\_cfctl%prtctl}
+and \texttt{sn\_cfctl%prttrc} suboptions, respectively. Although, perhaps, of limited use for its
+original intention, the ability to produce these control sums of trends in specific
+areas provides another tool for diagnosing model behaviour.  If only the output from a
+select few regions is required then additional options are available to activate options
+for only a simple subset of processing regions. These are: \texttt{sn\_cfctl%procmin},
+\texttt{sn\_cfctl%procmax} and \texttt{sn\_cfctl%procincr} which can be used to specify
+the minimum and maximum active areas and the increment. The default values are set
+such that all regions will be active. Note this subsetting can also be used to limit
+which additional \texttt{ocean.output} and \texttt{layout.dat} files are produced if
+those suboptions are active.
+
 \end{enumerate}
 
-However, in recent versions it has also been used to force all processors to assume the
-reporting role. Thus when \np{ln_ctl}{ln\_ctl} is true all processors produce their own versions
-of files such as: ocean.output, layout.dat, etc.  All such files, beyond the the normal
-reporting processor (narea == 1), are named with a \_XXXX extension to their name, where
-XXXX is a 4-digit area number (with leading zeros, if required). Other reporting files
-such as run.stat (and its netCDF counterpart: run.stat.nc) and tracer.stat contain global
-information and are only ever produced by the reporting master (narea == 1). For version
-4.0 a start has been made to return \np{ln_ctl}{ln\_ctl} to its original function by introducing
-a new control structure which allows finer control over which files are produced. This
-feature is still evolving but it does already allow the user to: select individually the
-production of run.stat and tracer.stat files and to toggle the production of other files
-on processors other than the reporting master. These other reporters can be a simple
-subset of processors as defined by a minimum, maximum and incremental processor number.
-
-Note, that production of the run.stat and tracer.stat files require global communications.
-For run.stat, these are global min and max operations to find metrics such as the gloabl
-maximum velocity. For tracer.stat these are global sums of tracer fields. To improve model
-performance these operations are disabled by default and, where necessary, any use of the
-global values have been replaced with local calculations. For example, checks on the CFL
-criterion are now done on the local domain and only reported if a breach is detected.
-
-Experienced users may wish to still monitor this information as a check on model progress.
-If so, the best compromise will be to activate the files with:
-
-\begin{verbatim}
-     sn_cfctl%l_config = .TRUE.
-       sn_cfctl%l_runstat = .TRUE.
-       sn_cfctl%l_trcstat = .TRUE.
-\end{verbatim}
-
-and to use the new time increment setting to ensure the values are collected and reported
-at a suitably long interval. For example:
-
-\begin{verbatim}
-       sn_cfctl%ptimincr  = 25
-\end{verbatim}
-
-will carry out the global communications and write the information every 25 timesteps. This
-increment also applies to the time.step file which is otherwise updated every timestep.
+
+   sn_cfctl%l_glochk = .FALSE.    ! Range sanity checks are local (F) or global (T). Set T for debugging only
+   sn_cfctl%l_allon  = .FALSE.    ! IF T activate all options. If F deactivate all unless l_config is T
+     sn_cfctl%l_config = .TRUE.     ! IF .true. then control which reports are written with the following
+       sn_cfctl%l_runstat = .FALSE. ! switches and which areas produce reports with the proc integer settings.
+       sn_cfctl%l_trcstat = .FALSE. ! The default settings for the proc integers should ensure
+       sn_cfctl%l_oceout  = .FALSE. ! that  all areas report.
+       sn_cfctl%l_layout  = .FALSE. !
+       sn_cfctl%l_prtctl  = .FALSE. !
+       sn_cfctl%l_prttrc  = .FALSE. !
+       sn_cfctl%l_oasout  = .FALSE. !
+       sn_cfctl%procmin   = 0       ! Minimum area number for reporting [default:0]
+       sn_cfctl%procmax   = 1000000 ! Maximum area number for reporting [default:1000000]
+       sn_cfctl%procincr  = 1       ! Increment for optional subsetting of areas [default:1]
+       sn_cfctl%ptimincr  = 1       ! Timestep increment for writing time step progress info
+
+
 
 \subinc{\input{../../global/epilogue}}

@@ -3 +3 @@
 ^/utils/build/mk@HEAD         mk
 ^/utils/tools@HEAD            tools
-^/vendors/AGRIF/dev@HEAD      ext/AGRIF
+^/vendors/AGRIF/dev_r11615_ENHANCE-04_namelists_as_internalfiles_agrif@HEAD      ext/AGRIF
 ^/vendors/FCM@HEAD            ext/FCM
 ^/vendors/IOIPSL@HEAD         ext/IOIPSL