--- manual/s_ecco/text/ecco.tex	2016/09/16 18:52:27	1.1
+++ manual/s_ecco/text/ecco.tex	2016/09/18 21:19:54	1.2
@@ -40,7 +40,7 @@
 
 \subsection{Generic Cost Function Terms} \label{costgen}
 
-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 terms in \texttt{data.ecco} are given in table~\ref{tbl:gencost_ecco_params} and examples of possible specifications are available in:
 \begin{itemize}
 \itemsep0em
 \item MITgcm\_contrib/verification\_other/global\_oce\_cs32/input/data.ecco
@@ -49,16 +49,16 @@
 \end{itemize}
  
  \noindent
-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 \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.
 
-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 $\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 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 \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').
 \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. 
 
-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 \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. 
 
-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 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}). 
 
 \begin{table}[!ht]
 \centering
@@ -106,35 +106,35 @@
 \begin{table}[!ht]
 \centering
 \begin{tabular}{lll}
-variable name				&	description						&	remarks \\ \hline\hline
-\texttt{m\_eta}				&	sea surface height				&	free surface + corrections \\
-\texttt{m\_sst}				&	sea surface temperature			&	first level potential temperature \\
-\texttt{m\_sss}				&	sea surface salinity			&	first level salinity \\ 
-\texttt{m\_bp}				&	bottom pressure					& \\ \hline
-\texttt{m\_ustress}			&	zonal wind stress				& \\
-\texttt{m\_vstress}			&	meridional wind stress			& \\
-\texttt{m\_uwind}			&	zonal wind 						& \\
-\texttt{m\_vwind}			&	meridional wind 				& \\
-\texttt{m\_atemp}			&	atmospheric temperature			& \\
-\texttt{m\_aqh}				&	atmospheric specific humidity	& \\
-\texttt{m\_precip}			&	precipitation					& \\
-\texttt{m\_swdown}			&	downward shortwave				& \\
-\texttt{m\_lwdown}			&	downward longwave				& \\
-\texttt{m\_wspeed}			&	wind speed						& \\ \hline
-\texttt{m\_siarea}			&	sea-ice area					& \\
-\texttt{m\_siheff}			&	sea-ice effective thickness		& \\
-\texttt{m\_sihsnow}			&	snow effective thickness		& \\ \hline
-\texttt{m\_theta}			&	potential temperature			& three-dimensional \\
-\texttt{m\_salt}			&	salinity						& three-dimensional \\
-\texttt{m\_UE}				&	zonal velocity					& three-dimensional \\
-\texttt{m\_VN}				&	meridional velocity				& three-dimensional \\ \hline
-\texttt{m\_diffkr}			&	vertical/diapycnal diffusivity	& three-dimensional, constant \\ 
-\texttt{m\_kapgm}			&	GM diffusivity					& three-dimensional, constant \\ 
+variable name				&	description				& remarks \\ \hline\hline
+\texttt{m\_eta}				&	sea surface height			& free surface + ice + global steric correction \\
+\texttt{m\_sst}				&	sea surface temperature		& first level potential temperature \\
+\texttt{m\_sss}				&	sea surface salinity			& first level salinity \\ 
+\texttt{m\_bp}				&	bottom pressure			& phiHydLow\\ 
+\texttt{m\_siarea}			&	sea-ice area				& from pkg/seaice \\
+\texttt{m\_siheff}			&	sea-ice effective thickness		& from pkg/seaice \\
+\texttt{m\_sihsnow}			&	snow effective thickness		& from pkg/seaice \\ \hline
+\texttt{m\_theta}				&	potential temperature		& three-dimensional \\
+\texttt{m\_salt}				&	salinity					& three-dimensional \\
+\texttt{m\_UE}				&	zonal velocity				& three-dimensional \\
+\texttt{m\_VN}				&	meridional velocity			& three-dimensional \\ \hline
+\texttt{m\_ustress}			&	zonal wind stress			& from pkg/exf \\
+\texttt{m\_vstress}			&	meridional wind stress		& from pkg/exf\\
+\texttt{m\_uwind}			&	zonal wind 				& from pkg/exf\\
+\texttt{m\_vwind}			&	meridional wind 			& from pkg/exf\\
+\texttt{m\_atemp}			&	atmospheric temperature		& from pkg/exf\\
+\texttt{m\_aqh}				&	atmospheric specific humidity	& from pkg/exf\\
+\texttt{m\_precip}			&	precipitation				& from pkg/exf\\
+\texttt{m\_swdown}			&	downward shortwave		& from pkg/exf\\
+\texttt{m\_lwdown}			&	downward longwave			& from pkg/exf\\
+\texttt{m\_wspeed}			&	wind speed				& from pkg/exf\\ \hline
+\texttt{m\_diffkr}				&	vertical/diapycnal diffusivity	& three-dimensional, constant \\ 
+\texttt{m\_kapgm}			&	GM diffusivity				& three-dimensional, constant \\ 
 \texttt{m\_kapredi}			&	isopycnal diffusivity			& three-dimensional, constant \\ 
-\texttt{m\_geothermalflux}	&	geothermal heat flux			& constant \\ 
-\texttt{m\_bottomdrag}		&	bottom drag						& constant \\
+\texttt{m\_geothermalflux}		&	geothermal heat flux			& constant \\ 
+\texttt{m\_bottomdrag}		&	bottom drag				& constant \\
 \end{tabular}
-\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} 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.}
 \label{tbl:gencost_ecco_barfile}
 \end{table}
 
@@ -153,7 +153,7 @@
 \texttt{smooth} 			&	Smooth misfits				&	character: smoothing scale file\\ 
 						&								&	integer: smoother \# of time steps \\
 \end{tabular} 
-\caption{\texttt{gencost\_preproc} and \texttt{gencost\_posproc} options implemented as of checkpoint \mitgcmCheckpointVersion.}
+\caption{\texttt{gencost\_preproc} and \texttt{gencost\_posproc} options implemented as of checkpoint \mitgcmCheckpointVersion. Note: the distinction between \texttt{gencost\_preproc} and \texttt{gencost\_posproc} may be revisited in the future.}
 \label{tbl:gencost_ecco_preproc}
 \end{table}
 
@@ -161,38 +161,36 @@
 
 \subsection{Custom Cost Function Terms} \label{v4custom}
 
-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.
+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.}
 
 \subsection{Boxmean Generic Cost Function} \label{genboxmean}
 
-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.
+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.
 
 \subsection{Transport Generic Cost Function} \label{gentrsp}
 
-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.
+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.
 
 \begin{table}[!ht]
 \centering
 \begin{tabular}{lll}
 name						&	description					&	remarks \\ \hline\hline
-\texttt{sshv4-mdt}			&	sea surface height			&	mean dynamic topography (SLA + geod) \\
-\texttt{sshv4-tp}			&	sea surface height			&	TOPEX SLA \\
-\texttt{sshv4-ers}			&	sea surface height			&	ERS SLA \\
-\texttt{sshv4-gfo}			&	sea surface height			&	\\
-\texttt{sshv4-lsc}			&	sea surface height			&	\\
-\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	& \\
+\texttt{sshv4-mdt}			&	sea surface height			&	mean dynamic topography (SSH - geod) \\
+\texttt{sshv4-tp}				&	sea surface height			&	Along-Track Topex/Jason SLA (level 3) \\
+\texttt{sshv4-ers}			&	sea surface height			&	Along-Track ERS/Envisat SLA (level 3)\\
+\texttt{sshv4-gfo}			&	sea surface height			&	Along-Track GFO class SLA (level 3)\\
+\texttt{sshv4-lsc}			&	sea surface height			&	Large-Scale SLA (from the above)\\
+\texttt{sshv4-gmsl}			&	sea surface height			&	Global-Mean SLA (from the above)\\ \hline
+\texttt{bpv4-grace}			&	bottom pressure			&	GRACE maps (level 4) \\ \hline
+\texttt{sstv4-amsre}			&	sea surface temperature		&	Along-Swath SST (level 3)\\
+\texttt{sstv4-amsre-lsc}		&	sea surface temperature		&	Large-Scale SST (from the above)\\ \hline
+\texttt{si4-cons}				&	sea ice concentration		& 	needs sea-ice adjoint (level 4)\\
+\texttt{si4-deconc}			&	model sea ice deficiency		& 	proxy penalty (from the above)\\
+\texttt{si4-exconc}			&	model sea ice excess		& 	proxy penalty (from the above)\\ \hline
+\texttt{boxmean}			&	mean over a box			&	see section~\ref{genboxmean}  \\
+\texttt{transp}				&	transport across section		&	see section~\ref{gentrsp} \\ 
 \end{tabular}
-\caption{Pre-defined \texttt{gencost\_name} options associated with the sections~\ref{v4custom}, \ref{genboxmean}, \ref{gentrsp} special cases.}
+\caption{Pre-defined \texttt{gencost\_name} special cases (sections~\ref{v4custom}, \ref{genboxmean}, \ref{gentrsp}).}
 \label{tbl:gencost_ecco_name}
 \end{table}
 
