Controlling run-\/time diagnostics and how to add diagnostics to the code

M\+O\+M6 diagnostics are orchestrated via the F\+MS diag\+\_\+manager, as for previous versions of M\+OM. However, because M\+O\+M6 is a general coordinate model, the model native-\/coordinae output can be less familiar to users of earlier generations of M\+OM. To alleviate this problem, M\+O\+M6 provides both \char`\"{}native\char`\"{} and \char`\"{}remapped\char`\"{} diagnostics; the former being diagnostics in the actual model coordinate space, and the latter in user-\/defined coordinates.\hypertarget{Diagnostics_diag_table}{}\section{The \char`\"{}diag\+\_\+table\char`\"{}}\label{Diagnostics_diag_table}
At run-\/time, diagnostics are controlled by the input file {\ttfamily diag\+\_\+table} which is interpreted but the F\+MS package diag\+\_\+manager.

The diag\+\_\+table file has three kinds of section\+: Title, File and Field. The title section is mandatory and always the first. There can be multiple file and field sections, typically either in pairs or grouped in to all files and all fields, but always with the file section preceding the corresponding field section.\hypertarget{Diagnostics_diag_table_title}{}\subsection{Title section}\label{Diagnostics_diag_table_title}
The first two lines are mandatory and comprise a line with a title and a line with six integers defining a base date against which time will be referenced.


\begin{DoxyCode}
\textcolor{stringliteral}{"My ocean-only test case"}
1900 1 1 0 0 0
\end{DoxyCode}
\hypertarget{Diagnostics_diag_table_files}{}\subsection{File section}\label{Diagnostics_diag_table_files}
This section defines an arbitrary number of files that will be created. Each file is limited to a single rate of either sampling or time-\/averaging.


\begin{DoxyCode}
\textcolor{stringliteral}{"file\_name"}, output\_freq, \textcolor{stringliteral}{"output\_freq\_units"}, file\_format, \textcolor{stringliteral}{"time\_axis\_units"}, \textcolor{stringliteral}{"time\_axis\_name"}
\end{DoxyCode}



\begin{DoxyItemize}
\item {\ttfamily file\+\_\+name} \+: The name of the file that contains diagnostics at the given frequency (excluding the \char`\"{}.\+nc\char`\"{} extension).
\item {\ttfamily output\+\_\+freq} \+: The period between records in {\ttfamily file\+\_\+name}, if positive. Special values of 0 mean write every time step and -\/1 write only at the end of the run.
\item {\ttfamily output\+\_\+freq\+\_\+units} \+: The units in which {\ttfamily output\+\_\+freq} is given. Valid values are \char`\"{}years\char`\"{}, \char`\"{}months\char`\"{}, \char`\"{}days\char`\"{}, \char`\"{}hours\char`\"{}, \char`\"{}minutes\char`\"{} or \char`\"{}seconds\char`\"{}.
\item {\ttfamily file\+\_\+format} \+: Always set to 1, meaning netcdf.
\item {\ttfamily time\+\_\+axis\+\_\+units} \+: The units to use for the time-\/axis in the file. Valid values are \char`\"{}years\char`\"{}, \char`\"{}months\char`\"{}, \char`\"{}days\char`\"{}, \char`\"{}hours\char`\"{}, \char`\"{}minutes\char`\"{} or \char`\"{}seconds\char`\"{}.
\item {\ttfamily time\+\_\+axis\+\_\+name} \+: The name of the time-\/axis (usually \char`\"{}\+Time\char`\"{}).
\end{DoxyItemize}

Optional entries in the file line allow the generation of multiple files are intervals\+:


\begin{DoxyCode}
\textcolor{stringliteral}{"file\_name"}, output\_freq, \textcolor{stringliteral}{"output\_freq\_units"}, file\_format, \textcolor{stringliteral}{"time\_axis\_units"}, \textcolor{stringliteral}{"time\_axis\_name"}[, 
      new\_file\_freq, \textcolor{stringliteral}{"new\_file\_freq\_units"}[, \textcolor{stringliteral}{"start\_time"}[, file\_duration, \textcolor{stringliteral}{"file\_duration\_units"}]]]
\end{DoxyCode}



\begin{DoxyItemize}
\item file\+\_\+name \+: The base name of the file that contains diagnostics at the given frequency (excluding the \char`\"{}.\+nc\char`\"{} extension). The strings \%yr, \%mo, \%dy, \%hr \%mi, \%sc are expanded to the current year, month, day, hour, minute and second respectively, with new files created every new\+\_\+file\+\_\+freq.
\item {\ttfamily new\+\_\+file\+\_\+freq} \+: The period between generation of new files.
\item {\ttfamily new\+\_\+file\+\_\+freq\+\_\+units} \+: The units in which {\ttfamily new\+\_\+file\+\_\+freq} is given.
\item {\ttfamily start\+\_\+time}, {\ttfamily file\+\_\+duration}, {\ttfamily file\+\_\+duration\+\_\+units} \+: Even finer grain control of output files.
\end{DoxyItemize}\hypertarget{Diagnostics_diag_table_fields}{}\subsection{Field section}\label{Diagnostics_diag_table_fields}
An arbitrary number of lines, one per diagnostic field\+:


\begin{DoxyCode}
\textcolor{stringliteral}{"module\_name"}, \textcolor{stringliteral}{"field\_name"}, \textcolor{stringliteral}{"output\_name"}, \textcolor{stringliteral}{"file\_name"}, \textcolor{stringliteral}{"time\_sampling"}, \textcolor{stringliteral}{"reduction\_method"}, \textcolor{stringliteral}{"
      regional\_section"}, packing
\end{DoxyCode}



\begin{DoxyItemize}
\item {\ttfamily module\+\_\+name} \+: Name of the component model. For native ocean variables this should be \char`\"{}ocean\+\_\+model\char`\"{}. See \mbox{\hyperlink{Diagnostics_remapped_diagnostics}{Vertically remapped diagnostics}} for non-\/native vertical-\/grid diagnostics in the ocean model.
\item {\ttfamily field\+\_\+name} \+: The name of the variable as registered in the model.
\item {\ttfamily output\+\_\+name} " The name of the variable as it will appear in the file. This is usually the same as the {\ttfamily field\+\_\+name} but can be used to rename a diagnostic.
\item {\ttfamily file\+\_\+name} \+: One of the files defined above in the section \mbox{\hyperlink{Diagnostics_diag_table_files}{File section}}.
\item {\ttfamily time\+\_\+sampling} \+: Always set to \char`\"{}all\char`\"{}.
\item {\ttfamily reduction\+\_\+method} \+: \char`\"{}none\char`\"{} means sample or snapshot. \char`\"{}average\char`\"{} or \char`\"{}mean\char`\"{} performs a time-\/average. \char`\"{}min\char`\"{} or \char`\"{}max\char`\"{} diagnose the minium or maxium over each time period.
\item {\ttfamily regional\+\_\+section} \+: \char`\"{}none\char`\"{} means global output. A string of six space separated numbers, \char`\"{}lat\+\_\+min, lat\+\_\+max, lon\+\_\+min, lon\+\_\+max, vert\+\_\+min, vert\+\_\+max\char`\"{}, limits the diagnostic to a region.
\item {\ttfamily packing} \+: Data representation in the file. 1 means \char`\"{}real$\ast$8\char`\"{}, 2 means \char`\"{}real$\ast$4\char`\"{}, 4 mean 16-\/bit integers, 8 means 1-\/byte.
\end{DoxyItemize}\hypertarget{Diagnostics_diag_table_example}{}\subsection{Example}\label{Diagnostics_diag_table_example}

\begin{DoxyCode}
\textcolor{stringliteral}{"OM4 1/4 degree"}
1900 1 1 0 0 0

\textcolor{preprocessor}{# Static file}
\textcolor{stringliteral}{"ocean\_static"}, -1, \textcolor{stringliteral}{"months"}, 1, \textcolor{stringliteral}{"days"}, \textcolor{stringliteral}{"time"} # ocean\_static is a \textcolor{keyword}{protected} name. Do not change \textcolor{keyword}{this} line
      .
\textcolor{stringliteral}{"ocean\_model"}, \textcolor{stringliteral}{"deptho"},    \textcolor{stringliteral}{"deptho"},    \textcolor{stringliteral}{"ocean\_static"}, \textcolor{stringliteral}{"all"}, \textcolor{stringliteral}{"none"}, \textcolor{stringliteral}{"none"}, 2
\textcolor{stringliteral}{"ocean\_model"}, \textcolor{stringliteral}{"geolon"},    \textcolor{stringliteral}{"geolon"},    \textcolor{stringliteral}{"ocean\_static"}, \textcolor{stringliteral}{"all"}, \textcolor{stringliteral}{"none"}, \textcolor{stringliteral}{"none"}, 2
\textcolor{stringliteral}{"ocean\_model"}, \textcolor{stringliteral}{"geolat"},    \textcolor{stringliteral}{"geolat"},    \textcolor{stringliteral}{"ocean\_static"}, \textcolor{stringliteral}{"all"}, \textcolor{stringliteral}{"none"}, \textcolor{stringliteral}{"none"}, 2
\textcolor{stringliteral}{"ocean\_model"}, \textcolor{stringliteral}{"wet"},       \textcolor{stringliteral}{"wet"},       \textcolor{stringliteral}{"ocean\_static"}, \textcolor{stringliteral}{"all"}, \textcolor{stringliteral}{"none"}, \textcolor{stringliteral}{"none"}, 2

\textcolor{preprocessor}{# High-frequency file}
\textcolor{stringliteral}{"surf\_%4yr\_%3dy"}, 1, \textcolor{stringliteral}{"hours"}, 1, \textcolor{stringliteral}{"days"}, \textcolor{stringliteral}{"time"}, 1, \textcolor{stringliteral}{"months"}
\textcolor{stringliteral}{"ocean\_model"},\textcolor{stringliteral}{"SSH"},\textcolor{stringliteral}{"SSH"},\textcolor{stringliteral}{"surf\_%4yr\_%3dy"},\textcolor{stringliteral}{"all"},\textcolor{stringliteral}{"none"},\textcolor{stringliteral}{"none"},2

\textcolor{preprocessor}{# Daily averages}
\textcolor{stringliteral}{"ocean\_daily"}, 1, \textcolor{stringliteral}{"days"}, 1, \textcolor{stringliteral}{"days"}, \textcolor{stringliteral}{"time"}
\textcolor{stringliteral}{"ocean\_model"}, \textcolor{stringliteral}{"tos"}, \textcolor{stringliteral}{"tos"}, \textcolor{stringliteral}{"ocean\_daily"}, \textcolor{stringliteral}{"all"}, \textcolor{stringliteral}{"mean"}, \textcolor{stringliteral}{"none"},2

\textcolor{preprocessor}{# Monthly averages}
\textcolor{stringliteral}{"ocean\_month"}, 1, \textcolor{stringliteral}{"months"}, 1, \textcolor{stringliteral}{"days"}, \textcolor{stringliteral}{"time"}
\textcolor{stringliteral}{"ocean\_model"}, \textcolor{stringliteral}{"thetao"}, \textcolor{stringliteral}{"thetao"}, \textcolor{stringliteral}{"ocean\_month"}, \textcolor{stringliteral}{"all"}, \textcolor{stringliteral}{"mean"}, \textcolor{stringliteral}{"none"},2

\textcolor{preprocessor}{# Annual averages}
\textcolor{stringliteral}{"ocean\_annual"}, 12, \textcolor{stringliteral}{"months"}, 1, \textcolor{stringliteral}{"days"}, \textcolor{stringliteral}{"time"}
\textcolor{stringliteral}{"ocean\_model"}, \textcolor{stringliteral}{"thetao"}, \textcolor{stringliteral}{"thetao"}, \textcolor{stringliteral}{"ocean\_annual"}, \textcolor{stringliteral}{"all"}, \textcolor{stringliteral}{"mean"}, \textcolor{stringliteral}{"none"},2

\textcolor{preprocessor}{# Vertical section}
\textcolor{stringliteral}{"ocean\_Bering\_Strait"}, 5, \textcolor{stringliteral}{"days"}, 1, \textcolor{stringliteral}{"days"}, \textcolor{stringliteral}{"time"}
\textcolor{stringliteral}{"ocean\_model"}, \textcolor{stringliteral}{"thetao"},\textcolor{stringliteral}{"thetao"}, \textcolor{stringliteral}{"ocean\_Bering\_Strait"}, \textcolor{stringliteral}{"all"}, \textcolor{stringliteral}{"mean"}, \textcolor{stringliteral}{"-171.4 -168.7  66.1 66.1 -1 -1"},2
\end{DoxyCode}
\hypertarget{Diagnostics_native_diagnostics}{}\section{Native diagnostics}\label{Diagnostics_native_diagnostics}
The list of available diagnostics is dependent on the particular configuration of the model. For this reason the model writes a record of the available diagnostic fields at run-\/time into a file \char`\"{}available\+\_\+diags.$\ast$\char`\"{}. See, for example, \href{https://github.com/NOAA-GFDL/MOM6-examples/blob/dev/master/ocean_only/global_ALE/z/available_diags.000000}{\tt available\+\_\+diags.\+000000} for the global\+\_\+\+A\+LE z-\/coordinate ocean-\/only test case.

Diagnostic fields in the module \char`\"{}ocean\+\_\+model\char`\"{} refer to the native variables or diagnostics in the native grid. Since the model can be run in arbitrary coordinates, say in hybrid-\/coordinate mode, then native-\/space diagnostics can be potentially confusing. Native diagnostics are useful when examining exactly what the model is doing, or if the vertical coordinate of the model is configured to be a natural coordinate such as pure isopycnal or z$\ast$ geopotential.\hypertarget{Diagnostics_remapped_diagnostics}{}\section{Vertically remapped diagnostics}\label{Diagnostics_remapped_diagnostics}
Alternative vertical coordinates can be configured for diagnostic purposes only.

The run-\/time parameter {\ttfamily N\+U\+M\+\_\+\+D\+I\+A\+G\+\_\+\+C\+O\+O\+R\+DS} controls how many diagnostic coordinates to use.

The run-\/time parameter {\ttfamily D\+I\+A\+G\+\_\+\+C\+O\+O\+R\+DS} defines the mapping between each coordinate, the name of the module in the diag\+\_\+table and run-\/time parameter names that define the coordinate. A list of string tuples, separated by commas, with each tuple in the form of M\+O\+D\+U\+L\+E\+\_\+\+S\+U\+F\+F\+IX P\+A\+R\+A\+M\+E\+T\+E\+R\+\_\+\+S\+U\+F\+F\+IX C\+O\+O\+R\+D\+I\+N\+A\+T\+E\+\_\+\+N\+A\+ME. {\ttfamily M\+O\+D\+U\+L\+E\+\_\+\+S\+U\+F\+F\+IX} is the string appended to \char`\"{}ocean\+\_\+model\char`\"{} to create a module in the diag\+\_\+table. {\ttfamily P\+A\+R\+A\+M\+E\+T\+E\+R\+\_\+\+S\+U\+F\+F\+IX} is the string appended to \char`\"{}\+Di\+A\+G\+\_\+\+C\+O\+O\+R\+D\+\_\+\+D\+E\+F\char`\"{}, and other parameters, used to control the generation of the named coordinate. {\ttfamily C\+O\+O\+R\+D\+I\+N\+A\+T\+E\+\_\+\+N\+A\+ME} is a name understood by the M\+O\+M6 regridding module. Valid examples are \char`\"{}\+Z\+S\+T\+A\+R\char`\"{}, \char`\"{}\+S\+I\+G\+M\+A\char`\"{}, \char`\"{}\+R\+H\+O\char`\"{}, etc.

By default, {\ttfamily N\+U\+M\+\_\+\+D\+I\+A\+G\+\_\+\+C\+O\+O\+R\+DS=1} and {\ttfamily D\+I\+A\+G\+\_\+\+C\+O\+O\+R\+DS=\char`\"{}z Z Z\+S\+T\+A\+R\char`\"{}}, meaning the module \char`\"{}ocean\+\_\+model\+\_\+z\char`\"{} provides diagnostics in \char`\"{}z$\ast$\char`\"{} coordinates and uses the parameter {\ttfamily D\+I\+A\+G\+\_\+\+C\+O\+O\+R\+D\+\_\+\+D\+E\+F\+\_\+Z}.

For example, multiple z$\ast$-\/coordinates could be used for diagnostics with 
\begin{DoxyCode}
NUM\_DIAG\_COORDS = 2
DIAG\_COORDS = \textcolor{stringliteral}{"z 01 ZSTAR,abc 02 ZSTAR"}
DIAG\_COORD\_DEF\_01 = \textcolor{stringliteral}{"WOA09"}
DIAG\_COORD\_DEF\_02 = \textcolor{stringliteral}{"UNIFORM:10,20."}
\end{DoxyCode}
 would create the diag\+\_\+manager modules \char`\"{}ocean\+\_\+model\+\_\+z\char`\"{} and \char`\"{}ocean\+\_\+model\+\_\+abc\char`\"{}.

The above is equivalent to 
\begin{DoxyCode}
NUM\_DIAG\_COORDS = 2
DIAG\_COORDS = \textcolor{stringliteral}{"z ZA ZSTAR,abc ZB ZSTAR"}
DIAG\_COORD\_DEF\_ZA = \textcolor{stringliteral}{"WOA09"}
DIAG\_COORD\_DEF\_ZB = \textcolor{stringliteral}{"UNIFORM:10,20."}
\end{DoxyCode}


To obtain a diagnostic of monthly-\/averaged potential temperature in both these coordinate systems the diag\+\_\+table must include the lines


\begin{DoxyCode}
\textcolor{stringliteral}{"ocean\_month\_z"}, 1, \textcolor{stringliteral}{"months"}, 1, \textcolor{stringliteral}{"days"}, \textcolor{stringliteral}{"time"}
\textcolor{stringliteral}{"ocean\_month\_abc"}, 1, \textcolor{stringliteral}{"months"}, 1, \textcolor{stringliteral}{"days"}, \textcolor{stringliteral}{"time"}
\textcolor{stringliteral}{"ocean\_model\_z"}, \textcolor{stringliteral}{"temp"}, \textcolor{stringliteral}{"temp"}, \textcolor{stringliteral}{"ocean\_month\_z"}, \textcolor{stringliteral}{"all"}, \textcolor{stringliteral}{"mean"}, \textcolor{stringliteral}{"none"},2
\textcolor{stringliteral}{"ocean\_model\_abc"}, \textcolor{stringliteral}{"temp"}, \textcolor{stringliteral}{"temp"}, \textcolor{stringliteral}{"ocean\_month\_abc"}, \textcolor{stringliteral}{"all"}, \textcolor{stringliteral}{"mean"}, \textcolor{stringliteral}{"none"},2
\end{DoxyCode}
\hypertarget{Diagnostics_diag_table_vertical_coords}{}\subsection{Diagnostic vertical coordinates}\label{Diagnostics_diag_table_vertical_coords}
For each of the {\ttfamily N\+U\+M\+\_\+\+D\+I\+A\+G\+\_\+\+C\+O\+O\+R\+DS} vertical coordinates listed in {\ttfamily D\+I\+A\+G\+\_\+\+C\+O\+O\+R\+DS} the corresponding {\ttfamily D\+I\+A\+G\+\_\+\+C\+O\+O\+R\+D\+\_\+\+D\+E\+F\+\_\+\%} parameter must be provided. It can take the following values\+:
\begin{DoxyItemize}
\item P\+A\+R\+AM \+: In this case, a corresponding parameter {\ttfamily D\+I\+A\+G\+\_\+\+C\+O\+O\+R\+D\+\_\+\+R\+E\+S\+\_\+\%} is read that lists the deltas for each level in the coordinate. For example, D\+I\+A\+G\+\_\+\+C\+O\+O\+DS=\char`\"{}z Z Z\+T\+A\+R\char`\"{}, D\+I\+A\+G\+\_\+\+C\+O\+O\+R\+D\+\_\+\+D\+E\+F\+\_\+Z=\char`\"{}\+P\+A\+R\+A\+M\char`\"{}, D\+I\+A\+G\+\_\+\+C\+O\+O\+R\+D\+\_\+\+R\+E\+S\+\_\+Z=5,10,10,15 creates z$\ast$-\/level with 5,10,10,15 meters thicknesses.
\item U\+N\+I\+F\+O\+RM \+: Uniform distribution down to the maximum depth of the model using the same number of levels as he model.
\item U\+N\+I\+F\+O\+RM\+:N \+: Uniform distribution down to the maximum depth of the model using {\ttfamily N} levels.
\item U\+N\+I\+F\+O\+RM\+:N,D \+: Uniform distribution of {\ttfamily N} levels with thickness {\ttfamily D}.
\item F\+I\+LE\+:filename,varname \+: Reads vector of coordinate thicknesses from field \char`\"{}varname\char`\"{} from file \char`\"{}filename\char`\"{}.
\item F\+I\+LE\+:filename,interfaces=varname \+: Reads vector of coordinate positions from field \char`\"{}varname\char`\"{} from file \char`\"{}filename\char`\"{}.
\item W\+O\+A09 \+: Z-\/levels that correspond to the World Ocean Atlas, 2009, standard levels down to and including the maximum depth of the model.
\item W\+O\+A09\+:N \+: The first {\ttfamily N} levels of the World Ocean Atlas, 2009, standard levels.
\end{DoxyItemize}\hypertarget{Diagnostics_diagnostics_implementation}{}\section{A\+P\+Is for diagnostics}\label{Diagnostics_diagnostics_implementation}
The multiple diagnostic-\/coordinates are implemented in a layer that sits on top of the F\+MS diag\+\_\+manager known as the mom6\+\_\+diag\+\_\+mediator.

A diagnostic is registered with register\+\_\+diag\+\_\+field() which is an A\+PI that looks similar to the F\+MS diag\+\_\+manager routine of the same name\+: 
\begin{DoxyCode}
diag\_id = \mbox{\hyperlink{namespacemom__diag__mediator_ada491446bf7216fe101e6b0f6ed551e1}{register\_diag\_field}}(module\_name, diag\_name, axes, ...)
\end{DoxyCode}


The M\+O\+M6 version of this routine optionally allows the specification of C\+M\+OR names in addition to the native names which then registers the diagnostic twice, once with each name.

For each of the native and C\+M\+OR names, the diagnostic is registered in the native module \char`\"{}ocean\+\_\+model\char`\"{}, corresponding to the native model coordinate, and a module associated with each of the diagnostic coordinates.

For each diagnostic coordinate, a horizontally-\/averaged diagnostic is also registered.

In all, for each 3D diagnostic, the are 2 + 4N diagnostics registered, where N is the number of diagnostic coordinates. As a result, the global\+\_\+\+A\+LE examples have of order 900 total diagnostics available in the shipped configuration.

The data is made available to the diag\+\_\+manager via a call to post\+\_\+data() which is a wrapper that does all the vertical remapping before calling F\+MS\textquotesingle{}s send\+\_\+data()\+: 
\begin{DoxyCode}
call post\_data(diag\_id, data, diag\_control)
\end{DoxyCode}
\hypertarget{Diagnostics_diag_post_frequency}{}\subsection{Artifacts of posting frequency for diagnostics}\label{Diagnostics_diag_post_frequency}
Variables area \char`\"{}posted\char`\"{} for i/o or averaging to the diag\+\_\+manager (via M\+O\+M6\textquotesingle{}s diag\+\_\+mediator) at different frequencies relative to each other. This is because the M\+O\+M6 algorithm takes the form of nested sub-\/cycles with different time-\/steps in each loop (e.\+g. barotropic solver with dynamics). A consequence of this is that a time average of a related quantities may appear to be inconsistent since the diagnostic posted with higher frequency may not vary linearly between the end-\/points seen on the longer time-\/step. The differences are usually small, but if you see large differences it might indicate you should re-\/examine the time-\/steps used for the various sub-\/cycles. 