/[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.2 by gforget, Sun Sep 18 21:19:54 2016 UTC revision 1.4 by gforget, Wed Sep 21 12:50:01 2016 UTC
# Line 4  Line 4 
4  <!-- CMIREDIR:package_ecco: -->  <!-- CMIREDIR:package_ecco: -->
5  \end{rawhtml}  \end{rawhtml}
6    
7  \def\mitgcmCheckpointVersion{65x}  \def\mitgcmCheckpointVersion{65z}
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 examples 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 \texttt{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 $\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 cost function. If \texttt{gencost\_outputlevel} = 1 then \texttt{cost\_generic.F} outputs model-data misfit fields (i.e., $\vec{d}_i$) to a file which name starts with `misfit\_' 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$ 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 $\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}).  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 averaging frequency should be possible, but only \texttt{`day'}, \texttt{`month'}, \texttt{`step'}, and \texttt{`const'} are implemented for \texttt{gencost\_avgperiod}. If two different averaging frequencies are needed for the same variable in 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}) also 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 model outputs (STDOUT.0000, STDERR.0000, costfunction000, misfit*.data). Exceptions listed in table~\ref{tbl:gencost_ecco_name} 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 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}).  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}. In this section and in table~\ref{tbl:gencost_ecco_barfile} (unlike in other parts of the manual) `zonal' / `meridional' are to be taken literally and these components are centered (i.e., not at the staggered model velocity points). Preparing gridded velocity data sets for use in cost functions thus boils down to interpolating them to XC / YC.
61    
62  \begin{table}[!ht]  \begin{table}[!ht]
63  \centering  \centering
# Line 70  parameter                                      &       type                    &       function \\ \hl Line 69  parameter                                      &       type                    &       function \\ \hl
69  \texttt{gencost\_datafile}              &       character(*)    &       File containing observational data $\vec{o}_i$ \\  \texttt{gencost\_datafile}              &       character(*)    &       File containing observational data $\vec{o}_i$ \\
70  \texttt{gencost\_avgperiod}     &       character(5)    &       Averaging period for $\vec{o}_i$ and $\vec{m}_i$ (see text) \\  \texttt{gencost\_avgperiod}     &       character(5)    &       Averaging period for $\vec{o}_i$ and $\vec{m}_i$ (see text) \\
71  \texttt{gencost\_outputlevel}   &       integer                 &       Greater than 0 will output misfit fields\\  \texttt{gencost\_outputlevel}   &       integer                 &       Greater than 0 will output misfit fields\\
72  \texttt{gencost\_errfile}               &       character(*)    &       File containing diagonal of error matrix $R_i$\\  \texttt{gencost\_errfile}               &       character(*)    &       Uncertainty field name (not used in section~\ref{intgen})\\
73  \texttt{mult\_gencost}                  &       real                    &       Multiplier $\alpha_i$ (default: 1) \\  \texttt{gencost\_mask}          &       character(*)    &       Mask file name root (used only in section~\ref{intgen}) \\
74    \texttt{mult\_gencost}          &       real                    &       Multiplier $\alpha_i$ (default: 1) \\
75  \hline  \hline
76  \texttt{gencost\_preproc}               &       character(*)    &       Preprocessor names \\  \texttt{gencost\_preproc}               &       character(*)    &       Preprocessor names \\
77  \texttt{gencost\_preproc\_c}    &       character(*)    &       Preprocessor character arguments        \\  \texttt{gencost\_preproc\_c}    &       character(*)    &       Preprocessor character arguments        \\
# Line 82  parameter                                      &       type                    &       function \\ \hl Line 82  parameter                                      &       type                    &       function \\ \hl
82  \texttt{gencost\_posproc\_i}    &       integer(*)              &       Post-processor integer arguments        \\  \texttt{gencost\_posproc\_i}    &       integer(*)              &       Post-processor integer arguments        \\
83  \texttt{gencost\_posproc\_r}    &       real(*)                 &       Post-processor real arguments   \\  \texttt{gencost\_posproc\_r}    &       real(*)                 &       Post-processor real arguments   \\
84  \hline  \hline
 \texttt{gencost\_mask}          &       character(1)    &       Location of $\vec{m}_i$\\  
85  \texttt{gencost\_spmin}         &       real                    &       Data less than this value will be omitted \\  \texttt{gencost\_spmin}         &       real                    &       Data less than this value will be omitted \\
86  \texttt{gencost\_spmax}         &       real                    &       Data greater than this value will be omitted \\  \texttt{gencost\_spmax}         &       real                    &       Data greater than this value will be omitted \\
87  \texttt{gencost\_spzero}                &       real                    &       Data points equal to this value will be omitted \\  \texttt{gencost\_spzero}                &       real                    &       Data points equal to this value will be omitted \\
88  \texttt{gencost\_startdate1}    &       integer                 &       Start date of observations (YYYMMDD)    \\  \texttt{gencost\_startdate1}    &       integer                 &       Start date of observations (YYYMMDD)    \\
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 (used only in sec.~\ref{v4custom})\\
93  \\  \texttt{gencost\_enddate2}      &       integer &       Not fully implemented (used only in sec.~\ref{v4custom})\\
 \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} is automatically reset to true in all 3D cases in table~\ref{tbl:gencost_ecco_barfile}.}
96  \label{tbl:gencost_ecco_params}  \label{tbl:gencost_ecco_params}
97  \end{table}  \end{table}
98    
# Line 134  variable name                          &       description                             & rema Line 127  variable name                          &       description                             & rema
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. Notes: here `zonal' / `meridional' are to be taken literally (unlike in other parts of the manual) and these components are computed on tracer points (not on the C-grid vector points); the `m\_eta' formula depends on the \texttt{ATMOSPHERIC\_LOADING} and \texttt{ALLOW\_PSBAR\_STERIC} compile time options and `useRealFreshWaterFlux' run time parameter.}  \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. Note: 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 146  name                                   &       description                                     &       specs neede Line 139  name                                   &       description                                     &       specs neede
139  \texttt{clim}                           &       Use climatological misfits      &       integer: no.\ of records per climatological cycle \\  \texttt{clim}                           &       Use climatological misfits      &       integer: no.\ of records per climatological cycle \\
140  \texttt{mean}                           &       Use time mean of misfits        &       --- \\  \texttt{mean}                           &       Use time mean of misfits        &       --- \\
141  \texttt{anom}                           &       Use anomalies from time mean &  --- \\  \texttt{anom}                           &       Use anomalies from time mean &  --- \\
142  \texttt{variaweight}            &       Use time-varying weight $W_i$&  --- \\  \texttt{variaweight}                    &       Use time-varying weight $W_i$&  --- \\
143  \texttt{nosumsq}                        &       Use linear misfits                      &       --- \\  \texttt{nosumsq}                        &       Use linear misfits                      &       --- \\
144  \texttt{factor}                         &       Multiply $\vec{m}_i$ by a scaling factor        &       real: the scaling factor \\ \hline \hline  \texttt{factor}                                 &       Multiply $\vec{m}_i$ by a scaling factor        &       real: the scaling factor \\ \hline \hline
145  \texttt{gencost\_posproc} \\ \hline  \texttt{gencost\_posproc} \\ \hline
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. Note: the distinction between \texttt{gencost\_preproc} and \texttt{gencost\_posproc} may be revisited in the future.}  \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} seems unclear and 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}
156    
157  This section pertains to the special cases of \texttt{cost\_gencost\_bpv4.F}, \texttt{cost\_gencost\_seaicev4.F}, \texttt{cost\_gencost\_sshv4.F}, and \texttt{cost\_gencost\_sstv4.F}. It is very much a work in progress. If \texttt{gencost\_name} is either `sshv4-mdt' or `sshv4-lsc' then additional smoothing arguments can be specified via \texttt{gencost\_scalefile} (file containing the smoothing scale field) and \texttt{gencost\_smooth2Ddiffnbt} (number of smoothing time steps).\footnote{These parameters are otherwise not used and \texttt{gencost\_posproc*} will eventually be used instead.}  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{Boxmean Generic Cost Function} \label{genboxmean}  The integral formula is defined by masks provided via binary files which names are specified via \texttt{gencost\_mask}. There are two cases: (1) if \texttt{gencost\_mask = `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\_boxmean.F and is very much a work in progress. The boxmean 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} to `boxmean' followed by a 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 defined by a mask of ones and zeros read from files whose root 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; the ``box'' is not necessarily rectangular.  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  \subsection{Transport Generic Cost Function} \label{gentrsp}  \begin{table}[!ht]
165    \centering
166    \begin{tabular}{lll}
167    variable name                           &       description                                             &       remarks \\ \hline\hline
168    \texttt{m\_boxmean\_theta}      &       mean of theta over box                  & specify box \\
169    \texttt{m\_boxmean\_salt}               &       mean of salt over box                   & specify box \\
170    \texttt{m\_boxmean\_eta}                &       mean of SSH over box                    & specify box \\
171    \hline
172    \texttt{m\_horflux\_vol}                &       volume transport through section        & specify transect \\
173    \end{tabular}
174    \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:genint_ecco_barfile}
176    \end{table}
177    
178  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 a 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 via masks of +1, -1, and 0 values at `w' and `s' velocity points. The mask files name root is given by the string \texttt{gencost\_errfile}, with the suffixes \texttt{`W'} and \texttt{`S'} denoting the ``w'' and ``s'' points, respectively. Temporal and vertical masks remain to be implemented, although temporal masking can already be achieved using the \texttt{variaweight} post-processor.  \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  name                                            &       description                                     &       remarks \\ \hline\hline  name                                    &       description                             &       remarks \\ \hline\hline
186  \texttt{sshv4-mdt}                      &       sea surface height                      &       mean dynamic topography (SSH - geod) \\  \texttt{sshv4-mdt}                      &       sea surface height                      &       mean dynamic topography (SSH - geod) \\
187  \texttt{sshv4-tp}                               &       sea surface height                      &       Along-Track Topex/Jason SLA (level 3) \\  \texttt{sshv4-tp}                               &       sea surface height                      &       Along-Track Topex/Jason SLA (level 3) \\
188  \texttt{sshv4-ers}                      &       sea surface height                      &       Along-Track ERS/Envisat SLA (level 3)\\  \texttt{sshv4-ers}                      &       sea surface height                      &       Along-Track ERS/Envisat SLA (level 3)\\
# Line 187  name                                           &       description                                     &       remarks \\ Line 195  name                                           &       description                                     &       remarks \\
195  \texttt{si4-cons}                               &       sea ice concentration           &       needs sea-ice adjoint (level 4)\\  \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)\\  \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  \texttt{si4-exconc}                     &       model sea ice excess            &       proxy penalty (from the above)\\ \hline
198  \texttt{boxmean}                        &       mean over a box                 &       see section~\ref{genboxmean}  \\  \texttt{transp\_trVol}                  &       volume transport                        & specify section as in section~\ref{intgen}\\
199  \texttt{transp}                         &       transport across section                &       see section~\ref{gentrsp} \\  \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{Pre-defined \texttt{gencost\_name} special cases (sections~\ref{v4custom}, \ref{genboxmean}, \ref{gentrsp}).}  \caption{Pre-defined \texttt{gencost\_name} special cases (as of checkpoint \mitgcmCheckpointVersion; section~\ref{v4custom}).}
203  \label{tbl:gencost_ecco_name}  \label{tbl:gencost_ecco_name}
204  \end{table}  \end{table}
205    
 \begin{table}[!ht]  
 \centering  
 \begin{tabular}{lll}  
 variable name                           &       description                                             &       remarks \\ \hline\hline  
 \texttt{m\_trVol}                       &       volume transport                                & three-dimensional, specify section \\  
 \texttt{m\_trHeat}                      &       heat transport                                  & three-dimensional, specify section \\  
 \texttt{m\_trSalt}                      &       salt transport                                  & three-dimensional, specify section \\  
 \texttt{m\_boxmean\_theta}      &       mean of theta over box                  & specify box \\  
 \texttt{m\_boxmean\_salt}       &       mean of salt over box                   & specify box \\  
 \texttt{m\_boxmean\_eta}        &       mean of SSH over box                    & specify box  
 \end{tabular}  
 \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}.}  
 \label{tbl:gencost_ecco_barfile_custom}  
 \end{table}  
   
   
   
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\_toolbox.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.2  
changed lines
  Added in v.1.4
  ViewVC Help
Powered by ViewVC 1.1.22