/[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.5 by gforget, Fri Sep 23 18:26:49 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 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}. 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    NGENCOST (20) and NGENPPROC (10) can be changed in ecco.h only at compile time.}
97  \label{tbl:gencost_ecco_params}  \label{tbl:gencost_ecco_params}
98  \end{table}  \end{table}
99    
100  \begin{table}[!ht]  \begin{table}[!ht]
101  \centering  \centering
102  \begin{tabular}{lll}  \begin{tabular}{lll}
103  variable name                           &       description                                             &       remarks \\ \hline\hline  variable name                           &       description                             & remarks \\ \hline\hline
104  \texttt{m\_eta}                         &       sea surface height                              &       free surface + corrections \\  \texttt{m\_eta}                         &       sea surface height                      & free surface + ice + global steric correction \\
105  \texttt{m\_sst}                         &       sea surface temperature                 &       first level potential temperature \\  \texttt{m\_sst}                         &       sea surface temperature         & first level potential temperature \\
106  \texttt{m\_sss}                         &       sea surface salinity                    &       first level salinity \\  \texttt{m\_sss}                         &       sea surface salinity                    & first level salinity \\
107  \texttt{m\_bp}                          &       bottom pressure                                 & \\ \hline  \texttt{m\_bp}                          &       bottom pressure                 & phiHydLow\\
108  \texttt{m\_ustress}                     &       zonal wind stress                               & \\  \texttt{m\_siarea}                      &       sea-ice area                            & from pkg/seaice \\
109  \texttt{m\_vstress}                     &       meridional wind stress                  & \\  \texttt{m\_siheff}                      &       sea-ice effective thickness             & from pkg/seaice \\
110  \texttt{m\_uwind}                       &       zonal wind                                              & \\  \texttt{m\_sihsnow}                     &       snow effective thickness                & from pkg/seaice \\ \hline
111  \texttt{m\_vwind}                       &       meridional wind                                 & \\  \texttt{m\_theta}                               &       potential temperature           & three-dimensional \\
112  \texttt{m\_atemp}                       &       atmospheric temperature                 & \\  \texttt{m\_salt}                                &       salinity                                        & three-dimensional \\
113  \texttt{m\_aqh}                         &       atmospheric specific humidity   & \\  \texttt{m\_UE}                          &       zonal velocity                          & three-dimensional \\
114  \texttt{m\_precip}                      &       precipitation                                   & \\  \texttt{m\_VN}                          &       meridional velocity                     & three-dimensional \\ \hline
115  \texttt{m\_swdown}                      &       downward shortwave                              & \\  \texttt{m\_ustress}                     &       zonal wind stress                       & from pkg/exf \\
116  \texttt{m\_lwdown}                      &       downward longwave                               & \\  \texttt{m\_vstress}                     &       meridional wind stress          & from pkg/exf\\
117  \texttt{m\_wspeed}                      &       wind speed                                              & \\ \hline  \texttt{m\_uwind}                       &       zonal wind                              & from pkg/exf\\
118  \texttt{m\_siarea}                      &       sea-ice area                                    & \\  \texttt{m\_vwind}                       &       meridional wind                         & from pkg/exf\\
119  \texttt{m\_siheff}                      &       sea-ice effective thickness             & \\  \texttt{m\_atemp}                       &       atmospheric temperature         & from pkg/exf\\
120  \texttt{m\_sihsnow}                     &       snow effective thickness                & \\ \hline  \texttt{m\_aqh}                         &       atmospheric specific humidity   & from pkg/exf\\
121  \texttt{m\_theta}                       &       potential temperature                   & three-dimensional \\  \texttt{m\_precip}                      &       precipitation                           & from pkg/exf\\
122  \texttt{m\_salt}                        &       salinity                                                & three-dimensional \\  \texttt{m\_swdown}                      &       downward shortwave              & from pkg/exf\\
123  \texttt{m\_UE}                          &       zonal velocity                                  & three-dimensional \\  \texttt{m\_lwdown}                      &       downward longwave                       & from pkg/exf\\
124  \texttt{m\_VN}                          &       meridional velocity                             & three-dimensional \\ \hline  \texttt{m\_wspeed}                      &       wind speed                              & from pkg/exf\\ \hline
125  \texttt{m\_diffkr}                      &       vertical/diapycnal diffusivity  & three-dimensional, constant \\  \texttt{m\_diffkr}                              &       vertical/diapycnal diffusivity  & three-dimensional, constant \\
126  \texttt{m\_kapgm}                       &       GM diffusivity                                  & three-dimensional, constant \\  \texttt{m\_kapgm}                       &       GM diffusivity                          & three-dimensional, constant \\
127  \texttt{m\_kapredi}                     &       isopycnal diffusivity                   & three-dimensional, constant \\  \texttt{m\_kapredi}                     &       isopycnal diffusivity                   & three-dimensional, constant \\
128  \texttt{m\_geothermalflux}      &       geothermal heat flux                    & constant \\  \texttt{m\_geothermalflux}              &       geothermal heat flux                    & constant \\
129  \texttt{m\_bottomdrag}          &       bottom drag                                             & constant \\  \texttt{m\_bottomdrag}          &       bottom drag                             & constant \\
130  \end{tabular}  \end{tabular}
131  \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. Note: the `m\_eta' formula depends on the \texttt{ATMOSPHERIC\_LOADING} and \texttt{ALLOW\_PSBAR\_STERIC} compile time options and `useRealFreshWaterFlux' run time parameter.}
132  \label{tbl:gencost_ecco_barfile}  \label{tbl:gencost_ecco_barfile}
133  \end{table}  \end{table}
134    
# Line 146  name                                   &       description                                     &       specs neede Line 140  name                                   &       description                                     &       specs neede
140  \texttt{clim}                           &       Use climatological misfits      &       integer: no.\ of records per climatological cycle \\  \texttt{clim}                           &       Use climatological misfits      &       integer: no.\ of records per climatological cycle \\
141  \texttt{mean}                           &       Use time mean of misfits        &       --- \\  \texttt{mean}                           &       Use time mean of misfits        &       --- \\
142  \texttt{anom}                           &       Use anomalies from time mean &  --- \\  \texttt{anom}                           &       Use anomalies from time mean &  --- \\
143  \texttt{variaweight}            &       Use time-varying weight $W_i$&  --- \\  \texttt{variaweight}                    &       Use time-varying weight $W_i$&  --- \\
144  \texttt{nosumsq}                        &       Use linear misfits                      &       --- \\  \texttt{nosumsq}                        &       Use linear misfits                      &       --- \\
145  \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
146  \texttt{gencost\_posproc} \\ \hline  \texttt{gencost\_posproc} \\ \hline
147  \texttt{smooth}                         &       Smooth misfits                          &       character: smoothing scale file\\  \texttt{smooth}                                 &       Smooth misfits                          &       character: smoothing scale file\\
148                                                  &                                                               &       integer: smoother \# of time steps \\                                                  &                                                       &       integer: smoother \# of time steps \\
149  \end{tabular}  \end{tabular}
150  \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} seems unclear and may be revisited in the future.}
151  \label{tbl:gencost_ecco_preproc}  \label{tbl:gencost_ecco_preproc}
152  \end{table}  \end{table}
153    
154  \clearpage  \clearpage
155    
156  \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}  
157    
158  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}.
159    % and the basic averaging  frequency is specified via \texttt{gencost\_avgperiod}.
160    
161  \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\_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}.
162    
163  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.
164    
165  \begin{table}[!ht]  \begin{table}[!ht]
166  \centering  \centering
167  \begin{tabular}{lll}  \begin{tabular}{lll}
168  name                                            &       description                                     &       remarks \\ \hline\hline  variable name                           &       description                                             &       remarks \\ \hline\hline
169  \texttt{sshv4-mdt}                      &       sea surface height                      &       mean dynamic topography (SLA + geod) \\  \texttt{m\_boxmean\_theta}      &       mean of theta over box                  & specify box \\
170  \texttt{sshv4-tp}                       &       sea surface height                      &       TOPEX SLA \\  \texttt{m\_boxmean\_salt}               &       mean of salt over box                   & specify box \\
171  \texttt{sshv4-ers}                      &       sea surface height                      &       ERS SLA \\  \texttt{m\_boxmean\_eta}                &       mean of SSH over box                    & specify box \\
172  \texttt{sshv4-gfo}                      &       sea surface height                      &       \\  \hline
173  \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    & \\  
174  \end{tabular}  \end{tabular}
175  \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}).}
176  \label{tbl:gencost_ecco_name}  \label{tbl:genint_ecco_barfile}
177  \end{table}  \end{table}
178    
179    \subsection{Custom Cost Functions} \label{v4custom}
180    
181    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}.
182    
183  \begin{table}[!ht]  \begin{table}[!ht]
184  \centering  \centering
185  \begin{tabular}{lll}  \begin{tabular}{lll}
186  variable name                           &       description                                             &       remarks \\ \hline\hline  name                                    &       description                             &       remarks \\ \hline\hline
187  \texttt{m\_trVol}                       &       volume transport                                & three-dimensional, specify section \\  \texttt{sshv4-mdt}                      &       sea surface height                      &       mean dynamic topography (SSH - geod) \\
188  \texttt{m\_trHeat}                      &       heat transport                                  & three-dimensional, specify section \\  \texttt{sshv4-tp}                               &       sea surface height                      &       Along-Track Topex/Jason SLA (level 3) \\
189  \texttt{m\_trSalt}                      &       salt transport                                  & three-dimensional, specify section \\  \texttt{sshv4-ers}                      &       sea surface height                      &       Along-Track ERS/Envisat SLA (level 3)\\
190  \texttt{m\_boxmean\_theta}      &       mean of theta over box                  & specify box \\  \texttt{sshv4-gfo}                      &       sea surface height                      &       Along-Track GFO class SLA (level 3)\\
191  \texttt{m\_boxmean\_salt}       &       mean of salt over box                   & specify box \\  \texttt{sshv4-lsc}                      &       sea surface height                      &       Large-Scale SLA (from the above)\\
192  \texttt{m\_boxmean\_eta}        &       mean of SSH over box                    & specify box  \texttt{sshv4-gmsl}                     &       sea surface height                      &       Global-Mean SLA (from the above)\\ \hline
193    \texttt{bpv4-grace}                     &       bottom pressure                 &       GRACE maps (level 4) \\ \hline
194    \texttt{sstv4-amsre}                    &       sea surface temperature         &       Along-Swath SST (level 3)\\
195    \texttt{sstv4-amsre-lsc}                &       sea surface temperature         &       Large-Scale SST (from the above)\\ \hline
196    \texttt{si4-cons}                               &       sea ice concentration           &       needs sea-ice adjoint (level 4)\\
197    \texttt{si4-deconc}                     &       model sea ice deficiency                &       proxy penalty (from the above)\\
198    \texttt{si4-exconc}                     &       model sea ice excess            &       proxy penalty (from the above)\\ \hline
199    \texttt{transp\_trVol}                  &       volume transport                        & specify section as in section~\ref{intgen}\\
200    \texttt{transp\_trHeat}         &       heat transport                          & specify section as in section~\ref{intgen} \\
201    \texttt{transp\_trSalt}                 &       salt transport                          & specify section as in section~\ref{intgen} \\
202  \end{tabular}  \end{tabular}
203  \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}).}
204  \label{tbl:gencost_ecco_barfile_custom}  \label{tbl:gencost_ecco_name}
205  \end{table}  \end{table}
206    
   
   
207  \subsection{Key Routines}  \subsection{Key Routines}
208    
209  TBA... \texttt{cost\_generic.F}, \texttt{ecco\_check.F}, \texttt{ecco\_phys.F}, \texttt{ecco\_summary.F}, \texttt{ecco\_readparms.F}, ...  TBA...
210    \bigskip
211    \texttt{ecco\_readparms.F}, \texttt{ecco\_check.F}, \texttt{ecco\_summary.F}, ...
212    \texttt{cost\_generic.F}, \texttt{cost\_gencost\_boxmean.F}, \texttt{ecco\_toolbox.F}, ...
213    \texttt{ecco\_phys.F}, \texttt{cost\_gencost\_customize.F}, \texttt{cost\_averagesfields.F}, ...
214    
215  \subsection{Compile Options}  \subsection{Compile Options}
216    
217  TBA... ALLOW\_GENCOST3D, ALLOW\_PSBAR\_STERIC, ECCO\_CTRL\_DEPRECATED, ...  TBA...
218    \bigskip
219    ALLOW\_GENCOST\_CONTRIBUTION, ALLOW\_GENCOST3D, ...
220    ALLOW\_PSBAR\_STERIC, ALLOW\_SHALLOW\_ALTIMETRY, ALLOW\_HIGHLAT\_ALTIMETRY, ...
221    ALLOW\_PROFILES\_CONTRIBUTION, ...
222    ALLOW\_ECCO\_OLD\_FC\_PRINT, ...
223    ECCO\_CTRL\_DEPRECATED, ...
224    \bigskip
225    packages required for some functionalities: smooth, profiles, ctrl
226    
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.5
  ViewVC Help
Powered by ViewVC 1.1.22