--- manual/s_phys_pkgs/text/rbcs.tex	2011/01/18 20:38:16	1.3
+++ manual/s_phys_pkgs/text/rbcs.tex	2011/07/29 18:36:38	1.4
@@ -55,16 +55,26 @@
 is only read in at the beginning of the run and kept constant
 the rest of the run. Default is 0.
 \\
-$\bullet$  {\bf rbcsForcingOffset}: if you want to offset rbcs forcing
-timing. This is the time at the beginning of the first forcing period
-(in seconds).  Default is 0.  (This used to be rbcsInIter and was in
-units of iterations.)\\
-$\bullet$  {\bf rbcsSingleTimeFiles}: if true, relax fields are given
-1 file per time labeled by iteration number.\\
-$\bullet$  {\bf deltaTrbcs}: time step used to compute iteration numbers 
-for rbcsSingleTimeFiles.\\
-$\bullet$  {\bf rbcsIter0}: rbcsSingleTimeFiles iteration number
-corresponding to rbcsForcingOffset.\\
+$\bullet$  {\bf rbcsForcingOffset}: time offset of forcing fields (in seconds).
+If the forcing fields are time averages over forcing periods,
+then this must be set to the time at the beginning of the
+first forcing period.  The fields will then be placed at time
+rbcsForcingOffset+rbcsForcingPeriod/2 for interpolation.  Default is 0.
+If you use snapshots and the first snapshot is at $t_1$, you need to set
+\[
+  {\rm rbcsForcingOffset} = t_1 - {\rm rbcsForcingPeriod}/2
+\]
+(This used to be rbcsInIter and was in units of iterations.)\\
+$\bullet$  {\bf rbcsSingleTimeFiles}: true or false (default false),
+if true, forcing fields are given 1 file per time labeled by iteration number.\\
+$\bullet$  {\bf deltaTrbcs}: time step used to compute the iteration numbers
+for rbcsSingleTimeFiles=T.\\
+$\bullet$  {\bf rbcsIter0}: shift in iteration numbers used to label files if
+rbcsSingleTimeFiles=T (default 0).  If the file for the first forcing period
+(as specified by rbcsForcingOffset) has label $i_1$, you need to set
+\[
+  {\rm rbcsIter0} = i_1 - {\rm rbcsForcingPeriod}/{\rm deltaTrbcs}
+\]
 $\bullet$  {\bf useRBCtemp}: true or false (default false)\\
 $\bullet$  {\bf useRBCsalt}: true or false (default false)\\
 $\bullet$  {\bf useRBCptracers}: true or false (default false), must be using
@@ -72,8 +82,8 @@
 $\bullet$  {\bf tauRelaxT}: timescale in seconds of relaxing
 in temperature ($\tau_T$ in equation above). 
 Where mask is 1, relax rate will be
-1/tauRelaxT. Default is 1.
-$\bullet$  {\bf tauRelaxS}: same for salinity.
+1/tauRelaxT. Default is 1.\\
+$\bullet$  {\bf tauRelaxS}: same for salinity.\\
 $\bullet$  {\bf relaxMaskFile(irbc)}: filename of 3-D file
 with mask ($M_{rbc}$ in equation above. 
 Need a file for each irbc. 1=temperature,
@@ -109,29 +119,23 @@
 \item Non-cyclic time-varying forcing:
   \begin{quote}
      rbcsForcingPeriod = period in seconds\\
-     rbcsForcingCycle = 0\\
-     rbcsForcingOffset = beginning of first forcing period in seconds (default 0)
+     rbcsForcingCycle = 0
   \end{quote}
   When starting the run at time 0 (as usually the case), a period with center before
-  or at time 0 is needed for time interpolation, hence Offset needs to be negative.
+  or at time 0 is needed for time interpolation.  If you are not providing separate
+  files for each time (rbcsSingleTimeFiles=F), rbcsForcingOffset needs to be negative.
   For aligned periods (one period starting at time 0) and one extra record before
-  time 0 (and ending at time 0), set Offset=-Period.
-
-  This option makes most sense with rbcsSingleTimeFiles=T (see below), but may be
-  used with either setting.
+  time 0 (and ending at time 0), set rbcsForcingOffset${}=-$Period.
+  For other situations, see the description of rbcsForcingOffset above.
 
 \item Cyclic Forcing:
   \begin{quote}
      rbcsForcingPeriod = period in seconds\\
-     rbcsForcingCycle = cycle in seconds\\
-     rbcsForcingOffset = beginning of first forcing period in seconds (default 0)
+     rbcsForcingCycle = cycle in seconds
   \end{quote}
-  Here Offset may be at or after the start time (actually starttime-period/2),
-  in which case records from the end of the cycle are used for missing records at
-  the beginning (via cyclicity).  Not very nice, but works.
-
-  This is the traditional way used with rbcsSingleTimeFiles=F, but again may be
-  used with either setting.
+  The same comment as for non-cyclic forcing applies, but rbcsForcingOffset may now be
+  after the time of the first required record even with rbcsSingleTimeFiles=F, in which
+  case records from the end of the file will be used (via cyclicity).
 \end{enumerate}
 
 \noindent
@@ -139,19 +143,19 @@
 \begin{enumerate}
 \item One big file with many time records:
   \begin{quote}
-     rbcsSingleTimeFiles = .False.
+     rbcsSingleTimeFiles = .FALSE.
   \end{quote}
   All time records are in one big file.
 
 \item A separate file for each time:
   \begin{quote}
-     rbcsSingleTimeFiles = .True.\\
+     rbcsSingleTimeFiles = .TRUE.\\
      deltaTrbcs = time step used to generate forcing files\\
-     rbcsIter0 = forcing file iteration number corresponding to rbcsForcingOffset
+     rbcsIter0 = iteration number of first file $-$ rbcsForcingPeriod/deltaTrbcs
   \end{quote}
   The rbcs field for each time needed is in a separate file, labeled by the
   iteration number at the end of the forcing period.  If a different timestep
-  was used for generating the files (and the file names), set deltaTrbcs.
+  was used for generating the files (and the file names), set deltaTrbcs to it.
   If there is a shift in time, set rbcsIter0.
 \end{enumerate}
 
@@ -164,6 +168,13 @@
 \subsubsection{Experiments and tutorials that use rbcs}
 \label{sec:pkg:rbcs:experiments}
 
+In the directory \code{verifcation}, the following experiments use
+\code{rbcs}:
+\begin{itemize}
+\item \code{exp4}: box with 4 open boundaries, simulating flow over a
+  Gaussian bump based on \citet{adcroft:97}.
+\end{itemize}
+
 
 
 %%% \end{itemize}