/[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.3 by gforget, Wed Sep 21 01:28:57 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 (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  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}
# Line 57  In principle, any averaging frequency sh Line 57  In principle, any averaging frequency sh
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 `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.  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 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}).  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 69  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 81  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\_enddate1}              &       integer &       Not fully implemented (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 (sec.~\ref{v4custom} only)\\  \texttt{gencost\_enddate2}      &       integer &       Not fully implemented (used only in sec.~\ref{v4custom})\\
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 127  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} (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.}  \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 139  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    
# Line 157  name                                   &       description                                     &       specs neede Line 157  name                                   &       description                                     &       specs neede
157  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}.  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}.  % and the basic averaging  frequency is specified via \texttt{gencost\_avgperiod}.
159    
160  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}.  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  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.  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
# Line 205  name                                   &       description                             &       remarks \\ \ Line 205  name                                   &       description                             &       remarks \\ \
205    
206  \subsection{Key Routines}  \subsection{Key Routines}
207    
208  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}, ...  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.3  
changed lines
  Added in v.1.4
  ViewVC Help
Powered by ViewVC 1.1.22