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

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

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


Revision 1.2 - (show annotations) (download) (as text)
Sun Sep 18 21:19:54 2016 UTC (8 years, 10 months ago) by gforget
Branch: MAIN
Changes since 1.1: +52 -54 lines
File MIME type: application/x-tex
- improve pkg/ecco documentation

1 \section{ECCO: model-data comparisons using gridded data sets}
2 \label{sec:pkg:ecco}
3 \begin{rawhtml}
4 <!-- CMIREDIR:package_ecco: -->
5 \end{rawhtml}
6
7 \def\mitgcmCheckpointVersion{65x}
8
9 The functionalities implemented in \texttt{pkg/ecco} are: (1) output time-averaged model fields to compare with gridded data sets; (2) compute normalized model-data distances or cost functions. The former is achieved as the model runs forwards in time whereas the latter occurs after time-integration has completed. Following \cite{for-eta:15} the resulting `cost function' is formulated generically as
10 \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} \\
12 \vec{d}_i &= \mathcal{P}(\vec{m}_i - \vec{o}_i), \label{eq:Jposproc} \\
13 \vec{m}_i &= \mathcal{S}\mathcal{D}\mathcal{M}(\vec{v}), \label{eq:Jpreproc} \\
14 \vec{v} &= \mathcal{Q}(\vec{u}), \label{eq:Upreproc} \\
15 \vec{u} &= \mathcal{R}(\vec{u}') \label{eq:Uprecond}
16 \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}.
18
19 \begin{table}[!ht]
20 \centering
21 \begin{tabular}{rl}
22 symbol & definition \\ \hline
23 $\vec{u}$ & vector of nondimensional control variables \\
24 $\vec{v}$ & vector of dimensional control variables \\
25 $\alpha_i, \beta_j$ & misfit and control cost function multipliers (1 by default) \\
26 $R_i$ & data error covariance matrix ($R_i^{-1}$ are weights) \\
27 $\vec{d}_i$ & a set of model-data differences \\
28 $\vec{o}_i$ & observational data vector \\
29 $\vec{m}_i$ & model counterpart to $\vec{o}_i$ \\
30 $\mathcal{P}$ & post-processing operator (e.g., a smoother) \\
31 $\mathcal{M}$ & forward model dynamics operator \\
32 $\mathcal{D}$ & diagnostic computation operator \\
33 $\mathcal{S}$ & averaging/subsampling operator \\
34 $\mathcal{Q}$ & Pre-processing operator \\
35 $\mathcal{R}$ & Pre-conditioning operator
36 \end{tabular}
37 \caption{Symbol definitions for pkg/ecco and pkg/ctrl generic cost functions.}
38 \label{tbl:gencost_symbols}
39 \end{table}
40
41 \subsection{Generic Cost Function Terms} \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:
44 \begin{itemize}
45 \itemsep0em
46 \item MITgcm\_contrib/verification\_other/global\_oce\_cs32/input/data.ecco
47 \item MITgcm\_contrib/verification\_other/global\_oce\_cs32/input\_ad.sens/data.ecco
48 \item MITgcm\_contrib/gael/verification/global\_oce\_llc90/input.ecco\_v4/data.ecco
49 \end{itemize}
50
51 \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.
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}).
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').
57 \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.
58
59 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.
60
61 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}).
62
63 \begin{table}[!ht]
64 \centering
65 \begin{tabular}{lll}
66 parameter & type & function \\ \hline
67 %\texttt{using\_gencost} & logical & Turns specified generic cost term on. \\
68 \texttt{gencost\_name} & character(*) & Name of cost term \\
69 \texttt{gencost\_barfile} & character(*) & File to receive model counterpart $\vec{m}_i$ (see table~\ref{tbl:gencost_ecco_barfile}) \\
70 \texttt{gencost\_datafile} & character(*) & File containing observational data $\vec{o}_i$ \\
71 \texttt{gencost\_avgperiod} & character(5) & Averaging period for $\vec{o}_i$ and $\vec{m}_i$ (see text) \\
72 \texttt{gencost\_outputlevel} & integer & Greater than 0 will output misfit fields\\
73 \texttt{gencost\_errfile} & character(*) & File containing diagonal of error matrix $R_i$\\
74 \texttt{mult\_gencost} & real & Multiplier $\alpha_i$ (default: 1) \\
75 \hline
76 \texttt{gencost\_preproc} & character(*) & Preprocessor names \\
77 \texttt{gencost\_preproc\_c} & character(*) & Preprocessor character arguments \\
78 \texttt{gencost\_preproc\_i} & integer(*) & Preprocessor integer arguments \\
79 \texttt{gencost\_preproc\_r} & real(*) & Preprocessor real arguments \\
80 \texttt{gencost\_posproc} & character(*) & Post-processor names \\
81 \texttt{gencost\_posproc\_c} & character(*) & Post-processor character arguments \\
82 \texttt{gencost\_posproc\_i} & integer(*) & Post-processor integer arguments \\
83 \texttt{gencost\_posproc\_r} & real(*) & Post-processor real arguments \\
84 \hline
85 \texttt{gencost\_mask} & character(1) & Location of $\vec{m}_i$\\
86 \texttt{gencost\_spmin} & real & Data less than this value will be omitted \\
87 \texttt{gencost\_spmax} & real & Data greater than this value will be omitted \\
88 \texttt{gencost\_spzero} & real & Data points equal to this value will be omitted \\
89 \texttt{gencost\_startdate1} & integer & Start date of observations (YYYMMDD) \\
90 \texttt{gencost\_startdate2} & integer & Start date of observations (HHMMSS) \\
91 \texttt{gencost\_is3d} & logical & Needs to be true for 3D fields \\
92 \hline
93 \texttt{gencost\_smooth2Ddiffnbt} &integer & Smoother \# of time steps (sec.~\ref{v4custom} only)
94 \\
95 \texttt{gencost\_scalefile} & character(*) & Smoothing scale file (sec.~\ref{v4custom} only)
96 \\
97 \texttt{gencost\_nrecperiod} & integer & Deprecated \\
98 \texttt{gencost\_timevaryweight}& logical & Deprecated \\
99 \texttt{gencost\_enddate1} & integer & Not fully implemented \\
100 \texttt{gencost\_enddate2} & integer & Not fully implemented \\
101 \end{tabular}
102 \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.}
103 \label{tbl:gencost_ecco_params}
104 \end{table}
105
106 \begin{table}[!ht]
107 \centering
108 \begin{tabular}{lll}
109 variable name & description & remarks \\ \hline\hline
110 \texttt{m\_eta} & sea surface height & free surface + ice + global steric correction \\
111 \texttt{m\_sst} & sea surface temperature & first level potential temperature \\
112 \texttt{m\_sss} & sea surface salinity & first level salinity \\
113 \texttt{m\_bp} & bottom pressure & phiHydLow\\
114 \texttt{m\_siarea} & sea-ice area & from pkg/seaice \\
115 \texttt{m\_siheff} & sea-ice effective thickness & from pkg/seaice \\
116 \texttt{m\_sihsnow} & snow effective thickness & from pkg/seaice \\ \hline
117 \texttt{m\_theta} & potential temperature & three-dimensional \\
118 \texttt{m\_salt} & salinity & three-dimensional \\
119 \texttt{m\_UE} & zonal velocity & three-dimensional \\
120 \texttt{m\_VN} & meridional velocity & three-dimensional \\ \hline
121 \texttt{m\_ustress} & zonal wind stress & from pkg/exf \\
122 \texttt{m\_vstress} & meridional wind stress & from pkg/exf\\
123 \texttt{m\_uwind} & zonal wind & from pkg/exf\\
124 \texttt{m\_vwind} & meridional wind & from pkg/exf\\
125 \texttt{m\_atemp} & atmospheric temperature & from pkg/exf\\
126 \texttt{m\_aqh} & atmospheric specific humidity & from pkg/exf\\
127 \texttt{m\_precip} & precipitation & from pkg/exf\\
128 \texttt{m\_swdown} & downward shortwave & from pkg/exf\\
129 \texttt{m\_lwdown} & downward longwave & from pkg/exf\\
130 \texttt{m\_wspeed} & wind speed & from pkg/exf\\ \hline
131 \texttt{m\_diffkr} & vertical/diapycnal diffusivity & three-dimensional, constant \\
132 \texttt{m\_kapgm} & GM diffusivity & three-dimensional, constant \\
133 \texttt{m\_kapredi} & isopycnal diffusivity & three-dimensional, constant \\
134 \texttt{m\_geothermalflux} & geothermal heat flux & constant \\
135 \texttt{m\_bottomdrag} & bottom drag & constant \\
136 \end{tabular}
137 \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.}
138 \label{tbl:gencost_ecco_barfile}
139 \end{table}
140
141 \begin{table}[!ht]
142 \centering
143 \begin{tabular}{lll}
144 name & description & specs needed via \texttt{gencost\_preproc\_i}, \texttt{\_r}, or \texttt{\_c} \\ \hline\hline
145 \texttt{gencost\_preproc} \\ \hline
146 \texttt{clim} & Use climatological misfits & integer: no.\ of records per climatological cycle \\
147 \texttt{mean} & Use time mean of misfits & --- \\
148 \texttt{anom} & Use anomalies from time mean & --- \\
149 \texttt{variaweight} & Use time-varying weight $W_i$& --- \\
150 \texttt{nosumsq} & Use linear misfits & --- \\
151 \texttt{factor} & Multiply $\vec{m}_i$ by a scaling factor & real: the scaling factor \\ \hline \hline
152 \texttt{gencost\_posproc} \\ \hline
153 \texttt{smooth} & Smooth misfits & character: smoothing scale file\\
154 & & integer: smoother \# of time steps \\
155 \end{tabular}
156 \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.}
157 \label{tbl:gencost_ecco_preproc}
158 \end{table}
159
160 \clearpage
161
162 \subsection{Custom Cost Function Terms} \label{v4custom}
163
164 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.}
165
166 \subsection{Boxmean Generic Cost Function} \label{genboxmean}
167
168 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.
169
170 \subsection{Transport Generic Cost Function} \label{gentrsp}
171
172 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.
173
174 \begin{table}[!ht]
175 \centering
176 \begin{tabular}{lll}
177 name & description & remarks \\ \hline\hline
178 \texttt{sshv4-mdt} & sea surface height & mean dynamic topography (SSH - geod) \\
179 \texttt{sshv4-tp} & sea surface height & Along-Track Topex/Jason SLA (level 3) \\
180 \texttt{sshv4-ers} & sea surface height & Along-Track ERS/Envisat SLA (level 3)\\
181 \texttt{sshv4-gfo} & sea surface height & Along-Track GFO class SLA (level 3)\\
182 \texttt{sshv4-lsc} & sea surface height & Large-Scale SLA (from the above)\\
183 \texttt{sshv4-gmsl} & sea surface height & Global-Mean SLA (from the above)\\ \hline
184 \texttt{bpv4-grace} & bottom pressure & GRACE maps (level 4) \\ \hline
185 \texttt{sstv4-amsre} & sea surface temperature & Along-Swath SST (level 3)\\
186 \texttt{sstv4-amsre-lsc} & sea surface temperature & Large-Scale SST (from the above)\\ \hline
187 \texttt{si4-cons} & sea ice concentration & needs sea-ice adjoint (level 4)\\
188 \texttt{si4-deconc} & model sea ice deficiency & proxy penalty (from the above)\\
189 \texttt{si4-exconc} & model sea ice excess & proxy penalty (from the above)\\ \hline
190 \texttt{boxmean} & mean over a box & see section~\ref{genboxmean} \\
191 \texttt{transp} & transport across section & see section~\ref{gentrsp} \\
192 \end{tabular}
193 \caption{Pre-defined \texttt{gencost\_name} special cases (sections~\ref{v4custom}, \ref{genboxmean}, \ref{gentrsp}).}
194 \label{tbl:gencost_ecco_name}
195 \end{table}
196
197 \begin{table}[!ht]
198 \centering
199 \begin{tabular}{lll}
200 variable name & description & remarks \\ \hline\hline
201 \texttt{m\_trVol} & volume transport & three-dimensional, specify section \\
202 \texttt{m\_trHeat} & heat transport & three-dimensional, specify section \\
203 \texttt{m\_trSalt} & salt transport & three-dimensional, specify section \\
204 \texttt{m\_boxmean\_theta} & mean of theta over box & specify box \\
205 \texttt{m\_boxmean\_salt} & mean of salt over box & specify box \\
206 \texttt{m\_boxmean\_eta} & mean of SSH over box & specify box
207 \end{tabular}
208 \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}.}
209 \label{tbl:gencost_ecco_barfile_custom}
210 \end{table}
211
212
213
214 \subsection{Key Routines}
215
216 TBA... \texttt{cost\_generic.F}, \texttt{ecco\_check.F}, \texttt{ecco\_phys.F}, \texttt{ecco\_summary.F}, \texttt{ecco\_readparms.F}, ...
217
218 \subsection{Compile Options}
219
220 TBA... ALLOW\_GENCOST3D, ALLOW\_PSBAR\_STERIC, ECCO\_CTRL\_DEPRECATED, ...

  ViewVC Help
Powered by ViewVC 1.1.22