--- manual/s_ecco/text/ecco.tex	2016/09/18 21:19:54	1.2
+++ manual/s_ecco/text/ecco.tex	2016/09/21 12:50:01	1.4
@@ -4,9 +4,9 @@
 <!-- CMIREDIR:package_ecco: -->
 \end{rawhtml}
 
-\def\mitgcmCheckpointVersion{65x}
+\def\mitgcmCheckpointVersion{65z}
 
-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
 \begin{align} 
 	\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} \\
 	\vec{d}_i &= \mathcal{P}(\vec{m}_i - \vec{o}_i), \label{eq:Jposproc} \\
@@ -14,7 +14,7 @@
 	\vec{v}	  &= \mathcal{Q}(\vec{u}), \label{eq:Upreproc} \\
 	\vec{u}	  &= \mathcal{R}(\vec{u}') \label{eq:Uprecond}
 \end{align}
-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}.
 
 \begin{table}[!ht]
 \centering
@@ -38,9 +38,9 @@
 \label{tbl:gencost_symbols}
 \end{table}
 
-\subsection{Generic Cost Function Terms} \label{costgen}
+\subsection{Generic Cost Function} \label{costgen}
 
-The parameters available for configuring generic cost terms in \texttt{data.ecco} are given in table~\ref{tbl:gencost_ecco_params} and examples of possible specifications are available in:
+The parameters available for configuring generic cost function terms in \texttt{data.ecco} are given in table~\ref{tbl:gencost_ecco_params} and examples of possible specifications are available in:
 \begin{itemize}
 \itemsep0em
 \item MITgcm\_contrib/verification\_other/global\_oce\_cs32/input/data.ecco
@@ -49,16 +49,15 @@
 \end{itemize}
  
  \noindent
-The gridded observation file name is specified by \texttt{gencost\_datafile}. Observational time series may be provided as on big file or split into yearly files finishing in \texttt{`\_1992'}, \texttt{`\_1993'}, etc. The corresponding $\vec{m}_i$ physical variable is specified via the \texttt{gencost\_barfile} root (see table~\ref{tbl:gencost_ecco_barfile}). A file named as specified by \texttt{gencost\_barfile} gets created where averaged fields are written progressively as the model steps forward in time. After the final time step this file is re-read by \texttt{cost\_generic.F} to compute the cost function. If \texttt{gencost\_outputlevel} = 1 then \texttt{cost\_generic.F} outputs model-data misfit fields (i.e., $\vec{d}_i$) to a file which name starts with `misfit\_' for offline analysis and visualization.
+The gridded observation file name is specified by \texttt{gencost\_datafile}. Observational time series may be provided as on big file or split into yearly files finishing in `\_1992', `\_1993', etc. The corresponding $\vec{m}_i$ physical variable is specified via the \texttt{gencost\_barfile} root (see table~\ref{tbl:gencost_ecco_barfile}). A file named as specified by \texttt{gencost\_barfile} gets created where averaged fields are written progressively as the model steps forward in time. After the final time step this file is re-read by \texttt{cost\_generic.F} to compute the corresponding cost function term. If \texttt{gencost\_outputlevel} = 1 and \texttt{gencost\_name}=`foo' then \texttt{cost\_generic.F} outputs model-data misfit fields (i.e., $\vec{d}_i$) to a file named `misfit\_foo.data' for offline analysis and visualization.
 
-In the current implementation, model-data error covariance matrices $R_i$ omit non-diagonal terms. Specifying $R_i$ thus boils down to providing uncertainty fields ($\sigma_i$ such that $R_i=\sigma_i^2$) in a file specified via \texttt{gencost\_errfile}. By default $\sigma_i$ is assumed to be time-invariant but a $\sigma_i$ time series of the same length as $\vec{o}_i$ time series can be provided using the \texttt{variaweight} option (table~\ref{tbl:gencost_ecco_preproc}). By default cost functions are quadratic but $\vec{d}_i^T R_i^{-1} \vec{d}_i$ can be replaced with $R_i^{-1/2} \vec{d}_i$ using the \texttt{nosumsq} option (table~\ref{tbl:gencost_ecco_preproc}). 
+In the current implementation, model-data error covariance matrices $R_i$ omit non-diagonal terms. Specifying $R_i$ thus boils down to providing uncertainty fields ($\sigma_i$ such that $R_i=\sigma_i^2$) in a file specified via \texttt{gencost\_errfile}. By default $\sigma_i$ is assumed to be time-invariant but a $\sigma_i$ time series of the same length as the $\vec{o}_i$ time series can be provided using the \texttt{variaweight} option (table~\ref{tbl:gencost_ecco_preproc}). By default cost functions are quadratic but $\vec{d}_i^T R_i^{-1} \vec{d}_i$ can be replaced with $R_i^{-1/2} \vec{d}_i$ using the \texttt{nosumsq} option (table~\ref{tbl:gencost_ecco_preproc}). 
 
-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. 
+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. 
 
-Climatologies of $\vec{m}_i$ can be formed from the time series of model averages in order to compare with climatologies of $\vec{o}_i$ by activating the \texttt{`clim'} option via \texttt{gencost\_preproc} and setting the corresponding \texttt{gencost\_preproc\_i}  integer parameter to the number of records (i.e., months, days, or time steps) per climatological cycle. The generic post-processor ($\mathcal{P}$ in Eq.~\eqref{eq:Jposproc}) also allows model-data misfits to be, for example, smoothed in space by setting \texttt{gencost\_posproc} to \texttt{`smooth'}. Other options associated with the computation of Eq.~\eqref{eq:Jtotal} are summarized in table~\ref{tbl:gencost_ecco_preproc} and further discussed below. Multiple \texttt{gencost\_preproc} / \texttt{gencost\_posproc} options may be specified per cost term. 
+Climatologies of $\vec{m}_i$ can be formed from the time series of model averages in order to compare with climatologies of $\vec{o}_i$ by activating the `clim' option via \texttt{gencost\_preproc} and setting the corresponding \texttt{gencost\_preproc\_i}  integer parameter to the number of records (i.e., a \# of months, days, or time steps) per climatological cycle. The generic post-processor ($\mathcal{P}$ in Eq.~\eqref{eq:Jposproc}) also allows model-data misfits to be, for example, smoothed in space by setting \texttt{gencost\_posproc} to {`smooth'} and specifying the smoother parameters via \texttt{gencost\_posproc\_c} and \texttt{gencost\_posproc\_i} (see table~\ref{tbl:gencost_ecco_preproc}). Other options associated with the computation of Eq.~\eqref{eq:Jtotal} are summarized in table~\ref{tbl:gencost_ecco_preproc} and further discussed below. Multiple \texttt{gencost\_preproc} / \texttt{gencost\_posproc} options may be specified per cost term. 
 
-In general the specification of \texttt{gencost\_name} is optional, has no impact on the end-result, and only serves to identify cost function terms in model outputs (STDOUT.0000, STDERR.0000, costfunction000, misfit*.data). Exceptions listed in table~\ref{tbl:gencost_ecco_name} activate alternative cost function codes (in place of \texttt{cost\_generic.F}) described in the following subsections. The specification of \texttt{gencost\_mask} allows the user to specify whether the gridded data input and model counterparts are located at tracer points (`c'; the default) or velocity points (`w' or `s'). However the `c' option (not `w' or `s') should be used when gridded velocity data is provided as zonal/meridional components at tracer points (e.g., for all vector cases listed in table~\ref{tbl:gencost_ecco_barfile}). 
+In general the specification of \texttt{gencost\_name} is optional, has no impact on the end-result, and only serves to distinguish between cost function terms amongst the model output (STDOUT.0000, STDERR.0000, costfunction000, misfit*.data). Exceptions listed in table~\ref{tbl:gencost_ecco_name} however activate alternative cost function codes (in place of \texttt{cost\_generic.F}) described in section~\ref{v4custom}. In this section and in table~\ref{tbl:gencost_ecco_barfile} (unlike in other parts of the manual) `zonal' / `meridional' are to be taken literally and these components are centered (i.e., not at the staggered model velocity points). Preparing gridded velocity data sets for use in cost functions thus boils down to interpolating them to XC / YC.
 
 \begin{table}[!ht]
 \centering
@@ -70,8 +69,9 @@
 \texttt{gencost\_datafile} 		&	character(*)	&	File containing observational data $\vec{o}_i$ \\
 \texttt{gencost\_avgperiod}	&	character(5)	&	Averaging period for $\vec{o}_i$ and $\vec{m}_i$ (see text) \\
 \texttt{gencost\_outputlevel} 	&	integer 		&	Greater than 0 will output misfit fields\\
-\texttt{gencost\_errfile} 		& 	character(*)	&	File containing diagonal of error matrix $R_i$\\ 
-\texttt{mult\_gencost} 			&	real			&	Multiplier $\alpha_i$ (default: 1) \\ 
+\texttt{gencost\_errfile} 		& 	character(*)	&	Uncertainty field name (not used in section~\ref{intgen})\\ 
+\texttt{gencost\_mask}		&	character(*)	&	Mask file name root (used only in section~\ref{intgen}) \\
+\texttt{mult\_gencost} 		&	real			&	Multiplier $\alpha_i$ (default: 1) \\ 
 \hline
 \texttt{gencost\_preproc} 		&	character(*)	&	Preprocessor names \\
 \texttt{gencost\_preproc\_c} 	&	character(*)	&	Preprocessor character arguments 	\\
@@ -82,24 +82,17 @@
 \texttt{gencost\_posproc\_i} 	&	integer(*) 		&	Post-processor integer arguments 	\\
 \texttt{gencost\_posproc\_r} 	&	real(*)			&	Post-processor real arguments 	\\
 \hline
-\texttt{gencost\_mask}		&	character(1)	&	Location of $\vec{m}_i$\\
 \texttt{gencost\_spmin}		&	real			&	Data less than this value will be omitted \\
 \texttt{gencost\_spmax}		&	real			&	Data greater than this value will be omitted \\
 \texttt{gencost\_spzero}		&	real			&	Data points equal to this value will be omitted \\
 \texttt{gencost\_startdate1} 	&	integer			&	Start date of observations (YYYMMDD)	\\
 \texttt{gencost\_startdate2} 	&	integer			&	Start date of observations (HHMMSS)				\\
-\texttt{gencost\_is3d}		&	logical 		&	Needs to be true for 3D fields \\
+\texttt{gencost\_is3d}			&	logical 		&	Needs to be true for 3D fields \\
 \hline
-\texttt{gencost\_smooth2Ddiffnbt} &integer		&	Smoother \# of time steps (sec.~\ref{v4custom} only)
-\\
-\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 \\
+\texttt{gencost\_enddate1} 	&	integer	&	Not fully implemented (used only in sec.~\ref{v4custom})\\
+\texttt{gencost\_enddate2} 	&	integer	&	Not fully implemented (used only in sec.~\ref{v4custom})\\
 \end{tabular}
-\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}.}
 \label{tbl:gencost_ecco_params}
 \end{table}
 
@@ -134,7 +127,7 @@
 \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. Notes: here `zonal' / `meridional' are to be taken literally (unlike in other parts of the manual) and these components are computed on tracer points (not on the C-grid vector points); the `m\_eta' formula depends on the \texttt{ATMOSPHERIC\_LOADING} and \texttt{ALLOW\_PSBAR\_STERIC} compile time options and `useRealFreshWaterFlux' run time parameter.}
+\caption{Implemented \texttt{gencost\_barfile} options (as of checkpoint \mitgcmCheckpointVersion) that can be used via \texttt{cost\_generic.F} (section~\ref{costgen}). An extension starting with `\_' can be appended at the end of the variable name to distinguish between separate cost function terms. Note: the `m\_eta' formula depends on the \texttt{ATMOSPHERIC\_LOADING} and \texttt{ALLOW\_PSBAR\_STERIC} compile time options and `useRealFreshWaterFlux' run time parameter.}
 \label{tbl:gencost_ecco_barfile}
 \end{table}
 
@@ -146,35 +139,50 @@
 \texttt{clim} 				&	Use climatological misfits	&	integer: no.\ of records per climatological cycle \\
 \texttt{mean} 				&	Use time mean of misfits 	&	--- \\
 \texttt{anom} 				&	Use anomalies from time mean &	--- \\
-\texttt{variaweight}		&	Use time-varying weight $W_i$&	--- \\
+\texttt{variaweight}			&	Use time-varying weight $W_i$&	--- \\
 \texttt{nosumsq} 			&	Use linear misfits 			&	--- \\
-\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
 \texttt{gencost\_posproc} \\ \hline
-\texttt{smooth} 			&	Smooth misfits				&	character: smoothing scale file\\ 
-						&								&	integer: smoother \# of time steps \\
+\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. 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.}
 \label{tbl:gencost_ecco_preproc}
 \end{table}
 
 \clearpage
 
-\subsection{Custom Cost Function Terms} \label{v4custom}
+\subsection{Generic Integral Function} \label{intgen}
 
-This section pertains to the special cases of \texttt{cost\_gencost\_bpv4.F}, \texttt{cost\_gencost\_seaicev4.F}, \texttt{cost\_gencost\_sshv4.F}, and \texttt{cost\_gencost\_sstv4.F}. It is very much a work in progress. If \texttt{gencost\_name} is either `sshv4-mdt' or `sshv4-lsc' then additional smoothing arguments can be specified via \texttt{gencost\_scalefile} (file containing the smoothing scale field) and \texttt{gencost\_smooth2Ddiffnbt} (number of smoothing time steps).\footnote{These parameters are otherwise not used and \texttt{gencost\_posproc*} will eventually be used instead.}
+The functionality described in this section is operated by \texttt{cost\_gencost\_boxmean.F}. It is primarily aimed at obtaining a mechanistic understanding of a chosen physical variable via adjoint sensitivity computations (see Chapter~\ref{chap:autodiff}) as done for example in \cite{maro-eta:99,heim-eta:11,fuku-etal:14}. Thus the quadratic term in Eq.~\ref{eq:Jtotal} ($\vec{d}_i^T R_i^{-1} \vec{d}_i$) is by default replaced with a $d_i$ scalar\footnote{The quadratic option in fact does not yet exist in \texttt{cost\_gencost\_boxmean.F}...} that derives from model fields through a generic integral formula (Eq.~\ref{eq:Jpreproc}). The specification of \texttt{gencost\_barfile} again selects the physical variable type. Current valid options to use \texttt{cost\_gencost\_boxmean.F} are reported in table~\ref{tbl:genint_ecco_barfile}. A suffix starting with \texttt{`\_'} can again be appended to \texttt{gencost\_barfile}.
+% and the basic averaging  frequency is specified via \texttt{gencost\_avgperiod}. 
 
-\subsection{Boxmean Generic Cost Function} \label{genboxmean}
+The integral formula is defined by masks provided via binary files which names are specified via \texttt{gencost\_mask}. There are two cases: (1) if \texttt{gencost\_mask = `foo\_mask'} and \texttt{gencost\_barfile} is of the `m\_boxmean*' type then the model will search for horizontal, vertical, and temporal mask files  named \texttt{foo\_maskC}, \texttt{foo\_maskK}, and \texttt{foo\_maskT}; (2) if instead \texttt{gencost\_barfile} is of the `m\_horflux\_*' type then the model will search for \texttt{foo\_maskW}, \texttt{foo\_maskS}, \texttt{foo\_maskK}, and \texttt{foo\_maskT}. 
 
-This section pertains to the special case of cost\_gencost\_boxmean.F and is very much a work in progress. The boxmean generic cost function penalizes the mean of a model field over a ``box" (non quadratic cost function). To use this cost function, set \texttt{gencost\_name} to `boxmean' followed by a suffix starting with \texttt{`\_'}. The model field of interest is specified by \texttt{gencost\_barfile}. Currently valid options are \texttt{m\_boxmean\_theta}, \texttt{m\_boxmean\_salt}, and \texttt{m\_boxmean\_eta}. The ``box'' is defined by a mask of ones and zeros read from files whose root is given by the string \texttt{gencost\_errfile}. Different files contain the horizontal, vertical, and temporal masks; these files are distinguished by the suffixes \texttt{`C'}, \texttt{`K'}, and \texttt{`T'}, respectively. For example, if \texttt{gencost\_errfile = `foo\_mask'}, then the horizontal, vertical, and temporal mask files are named \texttt{foo\_maskC}, \texttt{foo\_maskK}, and \texttt{foo\_maskT}. Note that the horizontal mask can have an arbitrary shape; the ``box'' is not necessarily rectangular.
+The `C' mask or the `W' / `S' masks are expected to be two-dimensional fields. The `K' and `T' masks (both optional; all 1 by default) are expected to be one-dimensional vectors. The `K' vector length should match Nr. The `T' vector length should match the \# of records that the specification of \texttt{gencost\_avgperiod} implies but there is no restriction on its values. In case \#1 (`m\_boxmean*') the `C' and `K' masks should consists of +1 and 0 values and a volume average will be computed accordingly. In case \#2 (`m\_horflux*') the `W', `S', and `K' masks should consists of +1, -1, and 0 values and an integrated horizontal transport (or overturn) will be computed accordingly. 
 
-\subsection{Transport Generic Cost Function} \label{gentrsp}
+\begin{table}[!ht]
+\centering
+\begin{tabular}{lll}
+variable name				&	description						&	remarks \\ \hline\hline
+\texttt{m\_boxmean\_theta}	&	mean of theta over box			& specify box \\
+\texttt{m\_boxmean\_salt}		&	mean of salt over box			& specify box \\
+\texttt{m\_boxmean\_eta}		&	mean of SSH over box			& specify box \\
+\hline
+\texttt{m\_horflux\_vol}		&	volume transport through section	& specify transect \\ 
+\end{tabular}
+\caption{Implemented \texttt{gencost\_barfile} options (as of checkpoint \mitgcmCheckpointVersion) that can be used via \texttt{cost\_gencost\_boxmean.F} (section~\ref{intgen}).}
+\label{tbl:genint_ecco_barfile}
+\end{table}
 
-This section pertains to the special case of cost\_gencost\_transp.F and is very much a work in progress. The transport generic cost function penalizes a transport of volume, heat, or salt through a specified section (non quadratic cost function). To use this cost function, set \texttt{gencost\_name = `transp*'}, where \texttt{*} is an optional suffix starting with \texttt{`\_'}, and set \texttt{gencost\_barfile} to one of \texttt{m\_trVol}, \texttt{m\_trHeat}, and \texttt{m\_trSalt}. The section is specified via masks of +1, -1, and 0 values at `w' and `s' velocity points. The mask files name root is given by the string \texttt{gencost\_errfile}, with the suffixes \texttt{`W'} and \texttt{`S'} denoting the ``w'' and ``s'' points, respectively. Temporal and vertical masks remain to be implemented, although temporal masking can already be achieved using the \texttt{variaweight} post-processor.
+\subsection{Custom Cost Functions} \label{v4custom}
+
+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}. 
 
 \begin{table}[!ht]
 \centering
 \begin{tabular}{lll}
-name						&	description					&	remarks \\ \hline\hline
+name					&	description				&	remarks \\ \hline\hline
 \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)\\
@@ -187,33 +195,17 @@
 \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} \\ 
+\texttt{transp\_trVol}			&	volume transport			& specify section as in section~\ref{intgen}\\ 
+\texttt{transp\_trHeat}		&	heat transport				& specify section as in section~\ref{intgen} \\ 
+\texttt{transp\_trSalt}			&	salt transport				& specify section as in section~\ref{intgen} \\ 
 \end{tabular}
-\caption{Pre-defined \texttt{gencost\_name} special cases (sections~\ref{v4custom}, \ref{genboxmean}, \ref{gentrsp}).}
+\caption{Pre-defined \texttt{gencost\_name} special cases (as of checkpoint \mitgcmCheckpointVersion; section~\ref{v4custom}).}
 \label{tbl:gencost_ecco_name}
 \end{table}
 
-\begin{table}[!ht]
-\centering
-\begin{tabular}{lll}
-variable name				&	description						&	remarks \\ \hline\hline
-\texttt{m\_trVol}			&	volume transport				& three-dimensional, specify section \\ 
-\texttt{m\_trHeat}			&	heat transport					& three-dimensional, specify section \\ 
-\texttt{m\_trSalt}			&	salt transport					& three-dimensional, specify section \\ 
-\texttt{m\_boxmean\_theta}	&	mean of theta over box			& specify box \\
-\texttt{m\_boxmean\_salt}	&	mean of salt over box			& specify box \\
-\texttt{m\_boxmean\_eta}	&	mean of SSH over box			& specify box 
-\end{tabular}
-\caption{Implemented \texttt{gencost\_barfile} options (as of checkpoint \mitgcmCheckpointVersion) that can be used via \texttt{cost\_gencost\_boxmean.F} or \texttt{cost\_gencost\_transp.F} (see sections~\ref{genboxmean} and ~\ref{gentrsp}.}
-\label{tbl:gencost_ecco_barfile_custom}
-\end{table}
-
-
-
 \subsection{Key Routines}
 
-TBA... \texttt{cost\_generic.F}, \texttt{ecco\_check.F}, \texttt{ecco\_phys.F}, \texttt{ecco\_summary.F}, \texttt{ecco\_readparms.F}, ...
+TBA... \texttt{cost\_generic.F}, \texttt{cost\_gencost\_boxmean.F}, \texttt{ecco\_phys.F}, \texttt{cost\_gencost\_customize.F}, \texttt{cost\_averagesfields.F}, \texttt{ecco\_toolbox.F}, ... \texttt{ecco\_readparms.F}, \texttt{ecco\_check.F}, \texttt{ecco\_summary.F}, ...
 
 \subsection{Compile Options}
 
