How run-\/time parameters work in M\+O\+M6

M\+O\+M6 has an extensive set of parameters that are set at run-\/time by parsing an input file. Many parameters have default values and are not required to be in the input file, although there are a number of parameters that must be set for the model to run. The numerous examples provided with the M\+O\+M6 code mostly differ in their run-\/time parameters (although some add other components, like sea-\/ice), and comparison between these examples is an excellent way to get a broad overview of many of M\+O\+M6\textquotesingle{}s parameters and how they might be set.\hypertarget{Runtime_Parameter_System_reading_params}{}\doxysection{Getting parameters into M\+O\+M6}\label{Runtime_Parameter_System_reading_params}
Run-\/time parameters are provided to the model in two phases\+:


\begin{DoxyEnumerate}
\item A very small set of logistical parameters are read as namelist variables from the F\+MS parameter file {\ttfamily input.\+nml}. One of these logistical parameters is a list of ascii files that contain all the other run-\/time parameters.
\item All of the above-\/named parameter files are scanned for M\+O\+M6 model parameters, default values assigned and replaced, conflicts detected and various parameter summaries logged to files and/or the standard output.
\end{DoxyEnumerate}\hypertarget{Runtime_Parameter_System_mom6_namelist}{}\doxysubsection{Namelist parameters ($<$tt$>$input.\+nml$<$/tt$>$)}\label{Runtime_Parameter_System_mom6_namelist}
All F\+MS derived M\+O\+M6 parameters reside in the namelist {\ttfamily M\+O\+M\+\_\+input\+\_\+nml} in the file {\ttfamily input.\+nml}. The parameters are\+:
\begin{DoxyItemize}
\item {\ttfamily input\+\_\+filename} -\/ If equal to \char`\"{}n\char`\"{} will run a new run (i.\+e. will not read a restart file). If equal to \char`\"{}r\char`\"{} M\+O\+M6 will attempt to read a restart file.
\item {\ttfamily parameter\+\_\+filename} -\/ A list of file names containing the M\+O\+M6 internal run-\/time parameters. Typically {\ttfamily param\+\_\+files=\char`\"{}\+M\+O\+M6\+\_\+input\char`\"{},\char`\"{}\+M\+O\+M6\+\_\+override\char`\"{}} where the file M\+O\+M6\+\_\+input contains all the non-\/default parameters that define a \char`\"{}baseline\char`\"{} experiment and M\+O\+M6\+\_\+override will be either empty (for baseline) or contain a few parameters that define a \char`\"{}derived\char`\"{} experiment (that differs from the baseline). This helps keep the parameter lists concise and enables easy comparison of parameters in related experiments.
\item {\ttfamily restart\+\_\+input\+\_\+dir}, {\ttfamily restart\+\_\+output\+\_\+dir}, and {\ttfamily output\+\_\+directory} -\/ These specify the directories for reading input files, writing restart files, and writing many non-\/restart files.
\end{DoxyItemize}\hypertarget{Runtime_Parameter_System_fms_params}{}\doxysubsection{Other M\+O\+M6-\/relevant F\+M\+S parameters}\label{Runtime_Parameter_System_fms_params}
The namelist ocean\+\_\+solo\+\_\+nml may have the integer parameters secs, hours, days, months and years, which dictate how long the F\+MS ocean driver will try to run the model each run-\/segment.\hypertarget{Runtime_Parameter_System_param_syntax}{}\doxysubsection{M\+O\+M6 parameter file syntax}\label{Runtime_Parameter_System_param_syntax}
The general syntax for an entry in a M\+O\+M6 parameter file is 
\begin{DoxyCode}{0}
\DoxyCodeLine{[!]\#[override] PARAMETER\_NAME = value[,value][...][!comments]}
\end{DoxyCode}


Parameter names must be constructed from the characters {\ttfamily \mbox{[}A-\/\+Za-\/z0-\/9\+\_\+\mbox{]}} and by soft convention are upper case. The {\ttfamily !} character is a remark or comment indicator; all subsequent text on that line is ignored.

Parameters that are not specified in the parameter files may assume a default value. It is not an error to specify a parameter more than once with the same value. It is an error to specify different values.

The keyword \#override indicates that this parameter specification takes precedence over other specifications. It is {\bfseries{not}} an error to have two \#override specifications for a single parameter with the same values. It is an error to have two \#override statements with different values.

Some illustrations\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{DO\_THIS = True  ! Set the Boolean to .TRUE.}
\DoxyCodeLine{DO\_THAT = False ! Set the Boolean to .FALSE.}
\DoxyCodeLine{NXYZ = 5  ! Set the value to NXYZ to 5}
\DoxyCodeLine{HALF = 0.5  ! Set the value of HALF to 0.5}
\DoxyCodeLine{NAME = "{}abc"{}  ! Set the string NAME to 'abc'}
\DoxyCodeLine{VECTOR = 1.0,2.0  ! Set the array VECTOR to [1.0, 2.0]}
\DoxyCodeLine{NAMES = 'abc','xyz' ! Set the strings NAMES to 'abc','xyz'}
\DoxyCodeLine{\#override DO\_THIS = False ! Set the Boolean to .FALSE., ignoring the above specification}
\DoxyCodeLine{\#override HALF = 0.25 ! Set the value of HALF to 0.25, ignoring the above value}
\DoxyCodeLine{\#override HALF = 0.25 ! Same as the above value of HALF to 0.25 so is accepted}
\end{DoxyCode}
\hypertarget{Runtime_Parameter_System_param_logging}{}\doxysubsection{Logging of parameters}\label{Runtime_Parameter_System_param_logging}
The subroutine that reads M\+O\+M6 parameters has also serves to log every parameter to a file set by D\+O\+C\+U\+M\+E\+N\+T\+\_\+\+F\+I\+LE, usually \char`\"{}\+M\+O\+M6\+\_\+parameter\+\_\+doc\char`\"{}. In addition to the name of the variable being read, these calls contain a brief description, along with a description of the units and the default value (if any) or an indication that there is no default and that the variable must be present. For example, {\ttfamily DT} is always required to be present\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{comment}{call get\_param(param\_file, module, "{}DT"{}, CS\%dt, \&}}
\DoxyCodeLine{            \textcolor{stringliteral}{"{}The (baroclinic) dynamics time step.  The time-\/step that \(\backslash\)n"{}}\textcolor{comment}{//\&}}
\DoxyCodeLine{\textcolor{comment}{}            \textcolor{stringliteral}{"{}is actually used will be an integer fraction of the \(\backslash\)n"{}}//\&}
\DoxyCodeLine{            \textcolor{stringliteral}{"{}forcing time-\/step (DT\_FORCING in ocean-\/only mode or the \(\backslash\)n"{}}\textcolor{comment}{//\&}}
\DoxyCodeLine{\textcolor{comment}{}            \textcolor{stringliteral}{"{}coupling timestep in coupled mode.)"{}}, units=\textcolor{stringliteral}{"{}s"{}}, \&}
\DoxyCodeLine{            fail\_if\_missing=.true.)}
\end{DoxyCode}


At run-\/time, two levels of logging are performed, depending on the value of the parameter {\ttfamily M\+I\+N\+I\+M\+A\+L\+\_\+\+D\+O\+C\+U\+M\+E\+N\+T\+A\+T\+I\+ON}\+:


\begin{DoxyItemize}
\item (T\+R\+UE) The end result of the combination of default values, assignments and overrides are recorded with default and current values, description and units, for all parameters.
\item (F\+A\+L\+SE) The minimal list of required and non-\/default value parameters are recorded with current values, description and units only for those parameters needed to reproduce the configuration.
\end{DoxyItemize}

Either of the generated logging files can be used as inputs and yield the same configuration.

In addition, there are also calls that log derived quantities (e.\+g., a time-\/step that is derived from a C\+FL number, or the full path to an input file) without reading anything in.\hypertarget{Runtime_Parameter_System_param_checking}{}\doxysubsection{Error checking of parameters and parameter files}\label{Runtime_Parameter_System_param_checking}
There are several techniques that are used for error checking on M\+O\+M6 parameters\+:


\begin{DoxyItemize}
\item Some parameters have internal error messages if they are set to nonsensical values.
\item No parameter can be set twice inconsistently without an explicit \#override specification.
\item If the run-\/time parameter R\+E\+P\+O\+R\+T\+\_\+\+U\+N\+U\+S\+E\+D\+\_\+\+P\+A\+R\+A\+MS is true, a warning will be issued for any entries in the input parameter files that are not read in, for instance if they are misspelled.
\item Setting the run-\/time parameter F\+A\+T\+A\+L\+\_\+\+U\+N\+U\+S\+E\+D\+\_\+\+P\+A\+R\+A\+MS to true causes a fatal error that will bring down the model if there are any unused entries in the input parameter files. 
\end{DoxyItemize}