/[MITgcm]/manual/s_ecco/text/ecco.tex
ViewVC logotype

Diff of /manual/s_ecco/text/ecco.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph | View Patch Patch

revision 1.1 by gforget, Fri Sep 16 18:52:27 2016 UTC revision 1.3 by gforget, Wed Sep 21 01:28:57 2016 UTC
# Line 6  Line 6 
6    
7  \def\mitgcmCheckpointVersion{65x}  \def\mitgcmCheckpointVersion{65x}
8    
9  The functionalities implemented in \texttt{pkg/ecco} are: (1) output time-averaged model fields to compare with gridded data sets; (2) compute normalized model-data distances or cost functions. The former is achieved as the model runs forwards in time whereas the latter occurs after time-integration has completed. Following \cite{for-eta:15} the resulting `cost function' is formulated generically as  The functionalities implemented in \texttt{pkg/ecco} are: (1) output time-averaged model fields to compare with gridded data sets; (2) compute normalized model-data distances (i.e., cost functions); (3) compute averages and transports (i.e., integrals). The former is achieved as the model runs forwards in time whereas the others occur after time-integration has completed. Following \cite{for-eta:15} the total cost function is formulated generically as
10  \begin{align}  \begin{align}
11          \mathcal{J}(\vec{u}) &= \sum_i \alpha_i \left(\vec{d}_i^T R_i^{-1} \vec{d}_i\right) + \sum_j \beta_j \vec{u}^T\vec{u}, \label{eq:Jtotal} \\          \mathcal{J}(\vec{u}) &= \sum_i \alpha_i \left(\vec{d}_i^T R_i^{-1} \vec{d}_i\right) + \sum_j \beta_j \vec{u}^T\vec{u}, \label{eq:Jtotal} \\
12          \vec{d}_i &= \mathcal{P}(\vec{m}_i - \vec{o}_i), \label{eq:Jposproc} \\          \vec{d}_i &= \mathcal{P}(\vec{m}_i - \vec{o}_i), \label{eq:Jposproc} \\
# Line 14  The functionalities implemented in \text Line 14  The functionalities implemented in \text
14          \vec{v}   &= \mathcal{Q}(\vec{u}), \label{eq:Upreproc} \\          \vec{v}   &= \mathcal{Q}(\vec{u}), \label{eq:Upreproc} \\
15          \vec{u}   &= \mathcal{R}(\vec{u}') \label{eq:Uprecond}          \vec{u}   &= \mathcal{R}(\vec{u}') \label{eq:Uprecond}
16  \end{align}  \end{align}
17  using symbols defined in table~\ref{tbl:gencost_symbols}. Per Eq.~\eqref{eq:Jpreproc} model counterparts ($\vec{m}_i$) to observational data ($\vec{o}_i$) derive from adjustable model parameters ($\vec{v}$) through the model dynamics integration ($\mathcal{M}$), diagnostic calculations ($\mathcal{D}$), and averaging in space and time ($\mathcal{S}$). Alternatively $\mathcal{S}$ stands for subsampling in space and time (section~\ref{sec:pkg:profiles}). Plain model-data misfits ($\vec{m}_i-\vec{o}_i$) can be penalized directly in Eq.~\eqref{eq:Jtotal} but penalized misfits ($\vec{d}_i$) more generally derive from $\vec{m}_i-\vec{o}_i$ through the generic $\mathcal{P}$ post-processor (Eq. \eqref{eq:Jposproc}). Eqs.~\eqref{eq:Upreproc}-\eqref{eq:Uprecond} pertain to model control parameter adjustment capabilities described in section~\ref{sec:pkg:ctrl}.  using symbols defined in table~\ref{tbl:gencost_symbols}. Per Eq.~\eqref{eq:Jpreproc} model counterparts ($\vec{m}_i$) to observational data ($\vec{o}_i$) derive from adjustable model parameters ($\vec{v}$) through model dynamics integration ($\mathcal{M}$), diagnostic calculations ($\mathcal{D}$), and averaging in space and time ($\mathcal{S}$). Alternatively $\mathcal{S}$ stands for subsampling in space and time (section~\ref{sec:pkg:profiles}). Plain model-data misfits ($\vec{m}_i-\vec{o}_i$) can be penalized directly in Eq.~\eqref{eq:Jtotal} but penalized misfits ($\vec{d}_i$) more generally derive from $\vec{m}_i-\vec{o}_i$ through the generic $\mathcal{P}$ post-processor (Eq. \eqref{eq:Jposproc}). Eqs.~\eqref{eq:Upreproc}-\eqref{eq:Uprecond} pertain to model control parameter adjustment capabilities described in section~\ref{sec:pkg:ctrl}.
18    
19  \begin{table}[!ht]  \begin{table}[!ht]
20  \centering  \centering
# Line 38  $\mathcal{R}$          &       Pre-conditioning operat Line 38  $\mathcal{R}$          &       Pre-conditioning operat
38  \label{tbl:gencost_symbols}  \label{tbl:gencost_symbols}
39  \end{table}  \end{table}
40    
41  \subsection{Generic Cost Function Terms} \label{costgen}  \subsection{Generic Cost Function} \label{costgen}
42    
43  The parameters available for configuring generic cost terms in \texttt{data.ecco} are given in table~\ref{tbl:gencost_ecco_params} and example of possible specifications are available in:  The parameters available for configuring generic cost function terms in \texttt{data.ecco} are given in table~\ref{tbl:gencost_ecco_params} and examples of possible specifications are available in:
44  \begin{itemize}  \begin{itemize}
45  \itemsep0em  \itemsep0em
46  \item MITgcm\_contrib/verification\_other/global\_oce\_cs32/input/data.ecco  \item MITgcm\_contrib/verification\_other/global\_oce\_cs32/input/data.ecco
# Line 49  The parameters available for configuring Line 49  The parameters available for configuring
49  \end{itemize}  \end{itemize}
50    
51   \noindent   \noindent
52  The gridded observation file name is specified by `gencost\_datafile'. Observational time series may be provided as on big file or split into yearly files finishing in \texttt{`\_1992'}, \texttt{`\_1993'}, etc. The corresponding physical variable in $\vec{m}_i$ is specified via the first characters in \texttt{gencost\_barfile}. The list of implemented variables (as of checkpoint \mitgcmCheckpointVersion) is reported in table~\ref{tbl:gencost_ecco_barfile}. A file named according to \texttt{gencost\_barfile} will be created where averaged fields will be written progressively as the model integration proceeds forward in time. At the end this file will be re-read by \texttt{cost\_generic} to compute the cost function and (if \texttt{gencost\_outputlevel} = 1) output model-data misfit fields (i.e., $\vec{d}_i$) for offline analysis and visualization.  The gridded observation file name is specified by \texttt{gencost\_datafile}. Observational time series may be provided as on big file or split into yearly files finishing in `\_1992', `\_1993', etc. The corresponding $\vec{m}_i$ physical variable is specified via the \texttt{gencost\_barfile} root (see table~\ref{tbl:gencost_ecco_barfile}). A file named as specified by \texttt{gencost\_barfile} gets created where averaged fields are written progressively as the model steps forward in time. After the final time step this file is re-read by \texttt{cost\_generic.F} to compute the corresponding cost function term. If \texttt{gencost\_outputlevel} = 1 and \texttt{gencost\_name}=`foo' then \texttt{cost\_generic.F} outputs model-data misfit fields (i.e., $\vec{d}_i$) to a file named `misfit\_foo.data' for offline analysis and visualization.
53    
54  In the current implementation, model-data error covariance matrices $R_i$ omit non-diagonal terms. Specifying $R_i=\sigma_i^2$ thus boils down to providing uncertainty fields ($\sigma_i$ such that $R_i=\sigma_i^2$) in a file which name is specified via \texttt{gencost\_errfile}. By default $\sigma_i$ is assumed time-invariant but a $\sigma_i$ time series (of the same length as $\vec{o}_i$ time series) can be provided using the \texttt{variaweight} option. By default a cost function is quadratic but $\vec{d}_i^T R_i^{-1} \vec{d}_i$ can be replaced with $R_i^{-1/2} \vec{d}_i$ using the \texttt{nosumsq} option.  In the current implementation, model-data error covariance matrices $R_i$ omit non-diagonal terms. Specifying $R_i$ thus boils down to providing uncertainty fields ($\sigma_i$ such that $R_i=\sigma_i^2$) in a file specified via \texttt{gencost\_errfile}. By default $\sigma_i$ is assumed to be time-invariant but a $\sigma_i$ time series of the same length as the $\vec{o}_i$ time series can be provided using the \texttt{variaweight} option (table~\ref{tbl:gencost_ecco_preproc}). By default cost functions are quadratic but $\vec{d}_i^T R_i^{-1} \vec{d}_i$ can be replaced with $R_i^{-1/2} \vec{d}_i$ using the \texttt{nosumsq} option (table~\ref{tbl:gencost_ecco_preproc}).
55    
56  In principle, any periodicity should be possible, but only \texttt{`day'}, \texttt{`month'}, \texttt{`step'}, and \texttt{`const'} are implemented for \texttt{gencost\_avgperiod}. If two different averages of the same variable are needed for separate cost function terms (e.g., daily and monthly) then an extension starting with `\_' should be added to \texttt{gencost\_barfile} (such as `\_day' and `\_mon').  In principle, any averaging frequency should be possible, but only {`day'}, {`month'}, {`step'}, and {`const'} are implemented for \texttt{gencost\_avgperiod}. If two different averaging frequencies are needed for a variable used in multiple cost function terms (e.g., daily and monthly) then an extension starting with `\_' should be added to \texttt{gencost\_barfile} (such as `\_day' and `\_mon'). \footnote{ecco\_check may be missing a test for conflicting names...} If two cost function terms use the same variable and frequency, however, then using a common \texttt{gencost\_barfile} saves disk space.
 \footnote{ecco\_check may be missing a test for conflicting names.} If two cost function terms use the same variable and periodicity, however, then using a common \texttt{gencost\_barfile} saves disk space.  
57    
58  Climatologies of $\vec{m}_i$ can be formed from the time series of model averages in order to compare with climatologies of $\vec{o}_i$ by activating the \texttt{`clim'} option via \texttt{gencost\_preproc} and setting the corresponding \texttt{gencost\_preproc\_i}  integer parameter to the number of records (i.e., months, days, or time steps) per climatological cycle. The generic post-processor ($\mathcal{P}$ in Eq.~\eqref{eq:Jposproc}) allows model-data misfits to be, for example, smoothed in space by setting \texttt{gencost\_posproc} to \texttt{`smooth'}. Other options associated with the computation of Eq.~\eqref{eq:Jtotal} are summarized in table~\ref{tbl:gencost_ecco_preproc} and further discussed below. Multiple \texttt{gencost\_preproc} / \texttt{gencost\_posproc} options may be specified per cost term.  Climatologies of $\vec{m}_i$ can be formed from the time series of model averages in order to compare with climatologies of $\vec{o}_i$ by activating the `clim' option via \texttt{gencost\_preproc} and setting the corresponding \texttt{gencost\_preproc\_i}  integer parameter to the number of records (i.e., a \# of months, days, or time steps) per climatological cycle. The generic post-processor ($\mathcal{P}$ in Eq.~\eqref{eq:Jposproc}) also allows model-data misfits to be, for example, smoothed in space by setting \texttt{gencost\_posproc} to {`smooth'} and specifying the smoother parameters via \texttt{gencost\_posproc\_c} and \texttt{gencost\_posproc\_i} (see table~\ref{tbl:gencost_ecco_preproc}). Other options associated with the computation of Eq.~\eqref{eq:Jtotal} are summarized in table~\ref{tbl:gencost_ecco_preproc} and further discussed below. Multiple \texttt{gencost\_preproc} / \texttt{gencost\_posproc} options may be specified per cost term.
59    
60  In general the specification of \texttt{gencost\_name} is optional, has no impact on the end-result, and only serves to identify cost function terms in the model text outputs (STDOUT.0000, STDERR.0000, costfunction000). The exceptions are listed in table~\ref{tbl:gencost_ecco_name}, which activate alternative cost function codes (in place of \texttt{cost\_generic.F}) described in the following subsections. The specification of \texttt{gencost\_mask} allows the user to specify whether the gridded data input and model counterparts is located at tracer points (`c'; the default) or velocity points (`w' or `s'). Note however that the `c' option (not `w' or `s') should be used when gridded velocity data is provided as zonal/meridional components at tracer points.  In general the specification of \texttt{gencost\_name} is optional, has no impact on the end-result, and only serves to distinguish between cost function terms amongst the model output (STDOUT.0000, STDERR.0000, costfunction000, misfit*.data). Exceptions listed in table~\ref{tbl:gencost_ecco_name} however activate alternative cost function codes (in place of \texttt{cost\_generic.F}) described in section~\ref{v4custom}. The specification of \texttt{gencost\_mask}\footnote{This should be renamed \texttt{gencost\_loc} or \texttt{gencost\_point}...} allows the user to specify whether the gridded data input and model counterparts are located at tracer points (`c'; the default) or velocity points (`w' or `s'). However the `c' option (not `w' or `s') should be used when gridded velocity data is provided as zonal/meridional components at tracer points (e.g., for all vector cases listed in table~\ref{tbl:gencost_ecco_barfile}).
61    
62  \begin{table}[!ht]  \begin{table}[!ht]
63  \centering  \centering
# Line 90  parameter                                      &       type                    &       function \\ \hl Line 89  parameter                                      &       type                    &       function \\ \hl
89  \texttt{gencost\_startdate2}    &       integer                 &       Start date of observations (HHMMSS)                             \\  \texttt{gencost\_startdate2}    &       integer                 &       Start date of observations (HHMMSS)                             \\
90  \texttt{gencost\_is3d}          &       logical                 &       Needs to be true for 3D fields \\  \texttt{gencost\_is3d}          &       logical                 &       Needs to be true for 3D fields \\
91  \hline  \hline
92  \texttt{gencost\_smooth2Ddiffnbt} &integer              &       Smoother \# of time steps (sec.~\ref{v4custom} only)  \texttt{gencost\_enddate1}              &       integer &       Not fully implemented (sec.~\ref{v4custom} only)\\
93  \\  \texttt{gencost\_enddate2}              &       integer &       Not fully implemented (sec.~\ref{v4custom} only)\\
 \texttt{gencost\_scalefile}     &       character(*)    &       Smoothing scale file (sec.~\ref{v4custom} only)  
 \\  
 \texttt{gencost\_nrecperiod}    &       integer         &       Deprecated      \\  
 \texttt{gencost\_timevaryweight}&       logical                 &       Deprecated      \\  
 \texttt{gencost\_enddate1}              &       integer &       Not fully implemented \\  
 \texttt{gencost\_enddate2}              &       integer &       Not fully implemented \\  
94  \end{tabular}  \end{tabular}
95  \caption{Parameters in \texttt{ecco\_gencost\_nml} namelist in \texttt{data.ecco}. All parameters are vectors of length \texttt{NGENCOST} (the \# of available cost terms) except for \texttt{gencost\_*proc*} are arrays of size \texttt{NGENPPROC}$\times$\texttt{NGENCOST}. Notes: \texttt{gencost\_is3d} will automatically be reset to true in cases listed as 3D in table~\ref{tbl:gencost_ecco_barfile}; the last group of parameters should be disregarded except for the section~\ref{v4custom} special cases.}  \caption{Parameters in \texttt{ecco\_gencost\_nml} namelist in \texttt{data.ecco}. All parameters are vectors of length \texttt{NGENCOST} (the \# of available cost terms) except for \texttt{gencost\_*proc*} are arrays of size \texttt{NGENPPROC}$\times$\texttt{NGENCOST}. Notes: \texttt{gencost\_is3d} will automatically be reset to true in cases listed as 3D in table~\ref{tbl:gencost_ecco_barfile}; the last group of parameters should be disregarded except for the section~\ref{v4custom} special cases.}
96  \label{tbl:gencost_ecco_params}  \label{tbl:gencost_ecco_params}
# Line 106  parameter                                      &       type                    &       function \\ \hl Line 99  parameter                                      &       type                    &       function \\ \hl
99  \begin{table}[!ht]  \begin{table}[!ht]
100  \centering  \centering
101  \begin{tabular}{lll}  \begin{tabular}{lll}
102  variable name                           &       description                                             &       remarks \\ \hline\hline  variable name                           &       description                             & remarks \\ \hline\hline
103  \texttt{m\_eta}                         &       sea surface height                              &       free surface + corrections \\  \texttt{m\_eta}                         &       sea surface height                      & free surface + ice + global steric correction \\
104  \texttt{m\_sst}                         &       sea surface temperature                 &       first level potential temperature \\  \texttt{m\_sst}                         &       sea surface temperature         & first level potential temperature \\
105  \texttt{m\_sss}                         &       sea surface salinity                    &       first level salinity \\  \texttt{m\_sss}                         &       sea surface salinity                    & first level salinity \\
106  \texttt{m\_bp}                          &       bottom pressure                                 & \\ \hline  \texttt{m\_bp}                          &       bottom pressure                 & phiHydLow\\
107  \texttt{m\_ustress}                     &       zonal wind stress                               & \\  \texttt{m\_siarea}                      &       sea-ice area                            & from pkg/seaice \\
108  \texttt{m\_vstress}                     &       meridional wind stress                  & \\  \texttt{m\_siheff}                      &       sea-ice effective thickness             & from pkg/seaice \\
109  \texttt{m\_uwind}                       &       zonal wind                                              & \\  \texttt{m\_sihsnow}                     &       snow effective thickness                & from pkg/seaice \\ \hline
110  \texttt{m\_vwind}                       &       meridional wind                                 & \\  \texttt{m\_theta}                               &       potential temperature           & three-dimensional \\
111  \texttt{m\_atemp}                       &       atmospheric temperature                 & \\  \texttt{m\_salt}                                &       salinity                                        & three-dimensional \\
112  \texttt{m\_aqh}                         &       atmospheric specific humidity   & \\  \texttt{m\_UE}                          &       zonal velocity                          & three-dimensional \\
113  \texttt{m\_precip}                      &       precipitation                                   & \\  \texttt{m\_VN}                          &       meridional velocity                     & three-dimensional \\ \hline
114  \texttt{m\_swdown}                      &       downward shortwave                              & \\  \texttt{m\_ustress}                     &       zonal wind stress                       & from pkg/exf \\
115  \texttt{m\_lwdown}                      &       downward longwave                               & \\  \texttt{m\_vstress}                     &       meridional wind stress          & from pkg/exf\\
116  \texttt{m\_wspeed}                      &       wind speed                                              & \\ \hline  \texttt{m\_uwind}                       &       zonal wind                              & from pkg/exf\\
117  \texttt{m\_siarea}                      &       sea-ice area                                    & \\  \texttt{m\_vwind}                       &       meridional wind                         & from pkg/exf\\
118  \texttt{m\_siheff}                      &       sea-ice effective thickness             & \\  \texttt{m\_atemp}                       &       atmospheric temperature         & from pkg/exf\\
119  \texttt{m\_sihsnow}                     &       snow effective thickness                & \\ \hline  \texttt{m\_aqh}                         &       atmospheric specific humidity   & from pkg/exf\\
120  \texttt{m\_theta}                       &       potential temperature                   & three-dimensional \\  \texttt{m\_precip}                      &       precipitation                           & from pkg/exf\\
121  \texttt{m\_salt}                        &       salinity                                                & three-dimensional \\  \texttt{m\_swdown}                      &       downward shortwave              & from pkg/exf\\
122  \texttt{m\_UE}                          &       zonal velocity                                  & three-dimensional \\  \texttt{m\_lwdown}                      &       downward longwave                       & from pkg/exf\\
123  \texttt{m\_VN}                          &       meridional velocity                             & three-dimensional \\ \hline  \texttt{m\_wspeed}                      &       wind speed                              & from pkg/exf\\ \hline
124  \texttt{m\_diffkr}                      &       vertical/diapycnal diffusivity  & three-dimensional, constant \\  \texttt{m\_diffkr}                              &       vertical/diapycnal diffusivity  & three-dimensional, constant \\
125  \texttt{m\_kapgm}                       &       GM diffusivity                                  & three-dimensional, constant \\  \texttt{m\_kapgm}                       &       GM diffusivity                          & three-dimensional, constant \\
126  \texttt{m\_kapredi}                     &       isopycnal diffusivity                   & three-dimensional, constant \\  \texttt{m\_kapredi}                     &       isopycnal diffusivity                   & three-dimensional, constant \\
127  \texttt{m\_geothermalflux}      &       geothermal heat flux                    & constant \\  \texttt{m\_geothermalflux}              &       geothermal heat flux                    & constant \\
128  \texttt{m\_bottomdrag}          &       bottom drag                                             & constant \\  \texttt{m\_bottomdrag}          &       bottom drag                             & constant \\
129  \end{tabular}  \end{tabular}
130  \caption{Implemented \texttt{gencost\_barfile} options (as of checkpoint \mitgcmCheckpointVersion) that can be used via \texttt{cost\_generic.F} as explained in section~\ref{costgen}. An extension starting with `\_' can be appended at the end of the variable name to distinguish between separate cost function terms.}  \caption{Implemented \texttt{gencost\_barfile} options (as of checkpoint \mitgcmCheckpointVersion) that can be used via \texttt{cost\_generic.F} (section~\ref{costgen}). An extension starting with `\_' can be appended at the end of the variable name to distinguish between separate cost function terms. Notes: here `zonal' / `meridional' are to be taken literally (unlike in other parts of the manual) and these components are centered (i.e., not at the staggered C-grid velocity points); the `m\_eta' formula depends on the \texttt{ATMOSPHERIC\_LOADING} and \texttt{ALLOW\_PSBAR\_STERIC} compile time options and `useRealFreshWaterFlux' run time parameter.}
131  \label{tbl:gencost_ecco_barfile}  \label{tbl:gencost_ecco_barfile}
132  \end{table}  \end{table}
133    
# Line 153  name                                   &       description                                     &       specs neede Line 146  name                                   &       description                                     &       specs neede
146  \texttt{smooth}                         &       Smooth misfits                          &       character: smoothing scale file\\  \texttt{smooth}                         &       Smooth misfits                          &       character: smoothing scale file\\
147                                                  &                                                               &       integer: smoother \# of time steps \\                                                  &                                                               &       integer: smoother \# of time steps \\
148  \end{tabular}  \end{tabular}
149  \caption{\texttt{gencost\_preproc} and \texttt{gencost\_posproc} options implemented as of checkpoint \mitgcmCheckpointVersion.}  \caption{\texttt{gencost\_preproc} and \texttt{gencost\_posproc} options implemented as of checkpoint \mitgcmCheckpointVersion. Note: the distinction between \texttt{gencost\_preproc} and \texttt{gencost\_posproc} may be revisited in the future.}
150  \label{tbl:gencost_ecco_preproc}  \label{tbl:gencost_ecco_preproc}
151  \end{table}  \end{table}
152    
153  \clearpage  \clearpage
154    
155  \subsection{Custom Cost Function Terms} \label{v4custom}  \subsection{Generic Integral Function} \label{intgen}
   
 This section pertains to the special cases of cost\_gencost\_bpv4.F  cost\_gencost\_seaicev4.F  cost\_gencost\_sshv4.F  cost\_gencost\_sstv4.F  
   
 If \texttt{gencost\_name} is any of the \texttt{sshv4} or \texttt{sstv4} terms, additional smoothing arguments can be specified---\texttt{gencost\_scalefile} points to a file containing the smoothing scales and \texttt{gencost\_smooth2Ddiffnbt} gives the number of smoothing steps. These parameters are otherwise not used.  
   
 \subsection{Boxmean Generic Cost Function} \label{genboxmean}  
156    
157  This section pertains to the special case of cost\_gencost\_boxmean.F and is very much a work in progress. The box mean generic cost function penalizes the mean of a model field over a box (non quadratic cost function). To use this cost function, set \texttt{gencost\_name = 'boxmean*'}, where \texttt{*} is an optional suffix starting with \texttt{`\_'}. The model field of interest is specified by \texttt{gencost\_barfile}. Currently valid options are \texttt{m\_boxmean\_theta}, \texttt{m\_boxmean\_salt}, and \texttt{m\_boxmean\_eta}. The ``box'' is a mask of ones and zeros read from files whose prefix is given by the string \texttt{gencost\_errfile}. Different files contain the horizontal, vertical, and temporal masks; these files are distinguished by the suffixes \texttt{`C'}, \texttt{`K'}, and \texttt{`T'}, respectively. For example, if \texttt{gencost\_errfile = 'foo\_mask'}, then the horizontal, vertical, and temporal mask files are named \texttt{foo\_maskC}, \texttt{foo\_maskK}, and \texttt{foo\_maskT}. Note that the horizontal mask can have an arbitrary shape, so the ``box'' is not necessarily rectangular.  The functionality described in this section is operated by \texttt{cost\_gencost\_boxmean.F}. It is primarily aimed at obtaining a mechanistic understanding of a chosen physical variable via adjoint sensitivity computations (see Chapter~\ref{chap:autodiff}) as done for example in \cite{maro-eta:99,heim-eta:11,fuku-etal:14}. Thus the quadratic term in Eq.~\ref{eq:Jtotal} ($\vec{d}_i^T R_i^{-1} \vec{d}_i$) is by default replaced with a $d_i$ scalar\footnote{The quadratic option in fact does not yet exist in \texttt{cost\_gencost\_boxmean.F}...} that derives from model fields through a generic integral formula (Eq.~\ref{eq:Jpreproc}). The specification of \texttt{gencost\_barfile} again selects the physical variable type. Current valid options to use \texttt{cost\_gencost\_boxmean.F} are reported in table~\ref{tbl:genint_ecco_barfile}. A suffix starting with \texttt{`\_'} can again be appended to \texttt{gencost\_barfile}.
158    % and the basic averaging  frequency is specified via \texttt{gencost\_avgperiod}.
159    
160  \subsection{Transport Generic Cost Function} \label{gentrsp}  The integral formula is defined by masks provided via binary files which names are specified via \texttt{gencost\_errfile}. There are two cases: (1) if \texttt{gencost\_errfile = `foo\_mask'} and \texttt{gencost\_barfile} is of the `m\_boxmean*' type then the model will search for horizontal, vertical, and temporal mask files  named \texttt{foo\_maskC}, \texttt{foo\_maskK}, and \texttt{foo\_maskT}; (2) if instead \texttt{gencost\_barfile} is of the `m\_horflux\_*' type then the model will search for \texttt{foo\_maskW}, \texttt{foo\_maskS}, \texttt{foo\_maskK}, and \texttt{foo\_maskT}.
161    
162  This section pertains to the special case of cost\_gencost\_transp.F and is very much a work in progress. The transport generic cost function penalizes the transport of volume, heat, or salt through a specified section (non quadratic cost function). To use this cost function, set \texttt{gencost\_name = 'transp*'}, where \texttt{*} is an optional suffix starting with \texttt{`\_'}, and set \texttt{gencost\_barfile} to one of \texttt{m\_trVol}, \texttt{m\_trHeat}, and \texttt{m\_trSalt}. The section is specified a mask of ones and zeros denoting ``west'' and ``south'' faces through which to compute transport. The prefix for the mask files is given by the string \texttt{gencost\_errfile}, with the suffixes \texttt{`W'} and \texttt{`S'} denoting the ``west'' and ``south'' faces, respectively. There does not appear to be a suffix denoting a temporal mask, but temporal masking could be achieved using the \texttt{variaweight} post-processor.  The `C' mask or the `W' / `S' masks are expected to be two-dimensional fields. The `K' and T masks (both optional; all 1 by default) are expected to be one-dimensional vectors. The`K' vector length should match Nr. The `T' vector length should match the \# of records that the specification of \texttt{gencost\_avgperiod} implies but there is no restriction on its values. In case \#1 (`m\_boxmean*') the `C' and `K' masks should consists of +1 and 0 values and a volume average will be computed accordingly. In case \#2 (`m\_horflux*') the `W', `S', and `K' masks should consists of +1, -1, and 0 values and an integrated horizontal transport (or overturn) will be computed accordingly.
163    
164  \begin{table}[!ht]  \begin{table}[!ht]
165  \centering  \centering
166  \begin{tabular}{lll}  \begin{tabular}{lll}
167  name                                            &       description                                     &       remarks \\ \hline\hline  variable name                           &       description                                             &       remarks \\ \hline\hline
168  \texttt{sshv4-mdt}                      &       sea surface height                      &       mean dynamic topography (SLA + geod) \\  \texttt{m\_boxmean\_theta}      &       mean of theta over box                  & specify box \\
169  \texttt{sshv4-tp}                       &       sea surface height                      &       TOPEX SLA \\  \texttt{m\_boxmean\_salt}               &       mean of salt over box                   & specify box \\
170  \texttt{sshv4-ers}                      &       sea surface height                      &       ERS SLA \\  \texttt{m\_boxmean\_eta}                &       mean of SSH over box                    & specify box \\
171  \texttt{sshv4-gfo}                      &       sea surface height                      &       \\  \hline
172  \texttt{sshv4-lsc}                      &       sea surface height                      &       \\  \texttt{m\_horflux\_vol}                &       volume transport through section        & specify transect \\
 \texttt{sshv4-gmsl}                     &       sea surface height                      &       \\  
 \texttt{bpv4-grace}                     &       bottom pressure                         &       \\  
 \texttt{sstv4-amsre}            &       sea surface temperature         &       \\  
 \texttt{sstv4-amsre-lsc}        &       sea surface temperature         &       \\ \hline  
 \texttt{boxmean}                        &       mean over a box                         &       specify box \\  
 \texttt{transp}                         &       transport across section        &       specify section \\ \hline  
 \texttt{si4-cons}                       &       sea ice concentration           & \\  
 \texttt{si4-deconc}                     &       model sea ice deficiency        & \\  
 \texttt{si4-exconc}                     &       model sea ice excess    & \\  
173  \end{tabular}  \end{tabular}
174  \caption{Pre-defined \texttt{gencost\_name} options associated with the sections~\ref{v4custom}, \ref{genboxmean}, \ref{gentrsp} special cases.}  \caption{Implemented \texttt{gencost\_barfile} options (as of checkpoint \mitgcmCheckpointVersion) that can be used via \texttt{cost\_gencost\_boxmean.F} (section~\ref{intgen}).}
175  \label{tbl:gencost_ecco_name}  \label{tbl:genint_ecco_barfile}
176  \end{table}  \end{table}
177    
178    \subsection{Custom Cost Functions} \label{v4custom}
179    
180    This section (very much a work in progress...) pertains to the special cases of \texttt{cost\_gencost\_bpv4.F}, \texttt{cost\_gencost\_seaicev4.F}, \texttt{cost\_gencost\_sshv4.F}, \texttt{cost\_gencost\_sstv4.F}, and \texttt{cost\_gencost\_transp.F}. The cost\_gencost\_transp.F function can be used to compute a transport of volume, heat, or salt through a specified section (non quadratic cost function). To this end one sets \texttt{gencost\_name = `transp*'}, where \texttt{*} is an optional suffix starting with \texttt{`\_'}, and set \texttt{gencost\_barfile} to one of \texttt{m\_trVol}, \texttt{m\_trHeat}, and \texttt{m\_trSalt}.
181    
182  \begin{table}[!ht]  \begin{table}[!ht]
183  \centering  \centering
184  \begin{tabular}{lll}  \begin{tabular}{lll}
185  variable name                           &       description                                             &       remarks \\ \hline\hline  name                                    &       description                             &       remarks \\ \hline\hline
186  \texttt{m\_trVol}                       &       volume transport                                & three-dimensional, specify section \\  \texttt{sshv4-mdt}                      &       sea surface height                      &       mean dynamic topography (SSH - geod) \\
187  \texttt{m\_trHeat}                      &       heat transport                                  & three-dimensional, specify section \\  \texttt{sshv4-tp}                               &       sea surface height                      &       Along-Track Topex/Jason SLA (level 3) \\
188  \texttt{m\_trSalt}                      &       salt transport                                  & three-dimensional, specify section \\  \texttt{sshv4-ers}                      &       sea surface height                      &       Along-Track ERS/Envisat SLA (level 3)\\
189  \texttt{m\_boxmean\_theta}      &       mean of theta over box                  & specify box \\  \texttt{sshv4-gfo}                      &       sea surface height                      &       Along-Track GFO class SLA (level 3)\\
190  \texttt{m\_boxmean\_salt}       &       mean of salt over box                   & specify box \\  \texttt{sshv4-lsc}                      &       sea surface height                      &       Large-Scale SLA (from the above)\\
191  \texttt{m\_boxmean\_eta}        &       mean of SSH over box                    & specify box  \texttt{sshv4-gmsl}                     &       sea surface height                      &       Global-Mean SLA (from the above)\\ \hline
192    \texttt{bpv4-grace}                     &       bottom pressure                 &       GRACE maps (level 4) \\ \hline
193    \texttt{sstv4-amsre}                    &       sea surface temperature         &       Along-Swath SST (level 3)\\
194    \texttt{sstv4-amsre-lsc}                &       sea surface temperature         &       Large-Scale SST (from the above)\\ \hline
195    \texttt{si4-cons}                               &       sea ice concentration           &       needs sea-ice adjoint (level 4)\\
196    \texttt{si4-deconc}                     &       model sea ice deficiency                &       proxy penalty (from the above)\\
197    \texttt{si4-exconc}                     &       model sea ice excess            &       proxy penalty (from the above)\\ \hline
198    \texttt{transp\_trVol}                  &       volume transport                        & specify section as in section~\ref{intgen}\\
199    \texttt{transp\_trHeat}         &       heat transport                          & specify section as in section~\ref{intgen} \\
200    \texttt{transp\_trSalt}                 &       salt transport                          & specify section as in section~\ref{intgen} \\
201  \end{tabular}  \end{tabular}
202  \caption{Implemented \texttt{gencost\_barfile} options (as of checkpoint \mitgcmCheckpointVersion) that can be used via \texttt{cost\_gencost\_boxmean.F} or \texttt{cost\_gencost\_transp.F} (see sections~\ref{genboxmean} and ~\ref{gentrsp}.}  \caption{Pre-defined \texttt{gencost\_name} special cases (as of checkpoint \mitgcmCheckpointVersion; section~\ref{v4custom}).}
203  \label{tbl:gencost_ecco_barfile_custom}  \label{tbl:gencost_ecco_name}
204  \end{table}  \end{table}
205    
   
   
206  \subsection{Key Routines}  \subsection{Key Routines}
207    
208  TBA... \texttt{cost\_generic.F}, \texttt{ecco\_check.F}, \texttt{ecco\_phys.F}, \texttt{ecco\_summary.F}, \texttt{ecco\_readparms.F}, ...  TBA... \texttt{cost\_generic.F}, \texttt{cost\_gencost\_boxmean.F}, \texttt{ecco\_phys.F}, \texttt{cost\_gencost\_customize.F}, \texttt{cost\_averagesfields.F} ... \texttt{ecco\_readparms.F}, \texttt{ecco\_check.F}, \texttt{ecco\_summary.F}, ...
209    
210  \subsection{Compile Options}  \subsection{Compile Options}
211    
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.3
  ViewVC Help
Powered by ViewVC 1.1.22