--- manual/s_phys_pkgs/text/obcs.tex 2011/02/25 17:26:17 1.6 +++ manual/s_phys_pkgs/text/obcs.tex 2011/03/01 07:53:21 1.8 @@ -11,7 +11,17 @@ \subsubsection{Introduction \label{sec:pkg:obcs:intro}} - +The OBCS-package is fundamental to regional ocean modelling with the +MITgcm, but because there are so many details to be considered in +regional ocean modelling that this package cannot accomodate all +imaginable and possible options. Therefore, for a regional simulation +with very particular details, it is recommended to familiarize oneself +not only with the compile- and runtime-options of this package, but +also with the code itself. In many cases it will be necessary to adapt +the obcs-code (in particular \code{S/R OBCS\_CALC}) to the application +in question; in these cases the obcs-package (together with the +rbcs-package, section \ref{sec:pkg:rbcs}) is a very +useful infrastructure for implementing special regional models. %---------------------------------------------------------------------- @@ -95,7 +105,7 @@ \code{data.pkg}, \code{data.obcs}, and \code{data.exf} if ``real-time'' prescription is requested (i.e. package \code{exf} enabled). -These parameter files are read in S/R +vThese parameter files are read in S/R \code{packages\_readparms.F}, \code{obcs\_readparms.F}, and \code{exf\_readparms.F}, respectively. Run-time parameters may be broken into 3 categories: @@ -143,6 +153,8 @@ ~ \\ useOBCSbalance & \code{.FALSE.} & ~ \\ + OBCS\_balanceFacN/S/E/W & 0 & factor(s) determining the details + of the balaning code \\ useOrlanskiNorth/South/EastWest & \code{.FALSE.} & turn on Orlanski boundary conditions for individual boundary\\ useStevensNorth/South/EastWest & \code{.FALSE.} & @@ -232,21 +244,26 @@ means there is no corresponding OB in that column/row. For a Northern/Southern OB, the OB V point is to the South/North. For an Eastern/Western OB, the OB U point is to the West/East. - -\begin{verbatim} - For example - OB_Jnorth(3)=34 means that: - T( 3 ,34) is a an OB point - U(3:4,34) is a an OB point - V( 4 ,34) is a an OB point - while - OB_Jsouth(3)=1 means that: - T( 3 ,1) is a an OB point - U(3:4,1) is a an OB point - V( 4 ,2) is a an OB point -\end{verbatim} - -For convenience, negative values for Jnorth/Ieast refer to +For example, +\begin{tabbing} + \code{OB\_Jnorth(3)=34} \= means that: \= \\ + \> \code{T(3,34)} \> is a an OB point \\ + \> \code{U(3,34)} \> is a an OB point \\ + \> \code{V(3,34)} \> is a an OB point \\ + \code{OB\_Jsouth(3)=1} \> means that: \\ + \> \code{T(3,1)} \> is a an OB point \\ + \> \code{U(3,1)} \> is a an OB point \\ + \> \code{V(3,2)} \> is a an OB point \\ + \code{OB\_Ieast(10)=69} \> means that: \> \\ + \> \code{T(69,10)} \> is a an OB point \\ + \> \code{U(69,10)} \> is a an OB point \\ + \> \code{V(69,10)} \> is a an OB point \\ + \code{OB\_Iwest(10)=1} \> means that: \> \\ + \> \code{T(1,10)} \> is a an OB point \\ + \> \code{U(2,10)} \> is a an OB point \\ + \> \code{V(1,10)} \> is a an OB point +\end{tabbing} +For convenience, negative values for \code{Jnorth}/\code{Ieast} refer to points relative to the Northern/Eastern edges of the model eg. $\tt OB\_Jnorth(3)=-1$ means that the point $\tt (3,Ny)$ is a northern OB. @@ -291,7 +308,6 @@ use prescribed boundary fields to compute Stevens boundary conditions. \end{itemize} - \paragraph{ORLANSKI:} ~ \\ % Orlanski radiation conditions \citep{orl:76}, examples can be found in @@ -317,24 +333,27 @@ \item If non-hydrostatic dynamics are used (\ref{sec:non-hydrostatic}), additional files \code{OB[N/S/E/W]wFile} for the vertical velocity $w$ with - dimensions $(N_{x/y}\times N_r\times\mbox{time levels})$ may be + dimensions $(N_{x/y}\times N_r\times\mbox{time levels})$ can be specified. \item If \code{useSEAICE=.TRUE.} then additional files \code{OB[N/S/E/W][a,h,sl,sn,uice,vice]} for sea ice area, thickness (\code{HEFF}), seaice salinity, snow and ice velocities - $(N_{x/y}\times\mbox{time levels})$ may be specified. + $(N_{x/y}\times\mbox{time levels})$ can be specified. \end{itemize} -When the \code{exf}-package is used, the time levels are controlled -for each boundary separately in the same way as the \code{exf}-fields -in \code{data.exf}, namelist \code{EXF\_NML\_OBCS}. The runtime flags +As in \code{S/R external\_fields\_load} or the \code{exf}-package, the +code reads two time levels for each variable, e.g.\ \code{OBNu0} and +\code{OBNu1}, and interpolates linearly between these time levels to +obtain the value \code{OBNu} at the current model time (step). When the +\code{exf}-package is used, the time levels are controlled for each +boundary separately in the same way as the \code{exf}-fields in +\code{data.exf}, namelist \code{EXF\_NML\_OBCS}. The runtime flags follow the above naming conventions, e.g. for the western boundary the corresponding flags are \code{OBCWstartdate1/2} and \code{OBCWperiod}. Sea-ice boundary values are controlled separately -with \code{siobWstartdate1/2} and \code{siobWperiod}. -When the \code{exf}-package is not used, the time levels are -controlled by the runtime flags \code{externForcingPeriod} and -\code{externForcingCycle} in \code{data}, see \code{verification/exp4} -for an example. +with \code{siobWstartdate1/2} and \code{siobWperiod}. When the +\code{exf}-package is not used, the time levels are controlled by the +runtime flags \code{externForcingPeriod} and \code{externForcingCycle} +in \code{data}, see \code{verification/exp4} for an example. \paragraph{OBCS\_CALC\_STEVENS:} ~ \\ (THE IMPLEMENTATION OF THESE BOUNDARY CONDITIONS IS NOT COMPLETE. SO @@ -367,9 +386,28 @@ \texttt{useStevensPhaseVel} and \texttt{useStevensAdvection} to \texttt{.FALSE.}.\end{itemize} See \citet{stevens:90} for details. -\paragraph{OBCS\_BALANCE} ~ \\ +\paragraph{OBCS\_BALANCE:} ~ \\ % -~ +This is not (yet) a separate routine in the code, but it may become +one to make this code more transparent. The code is part of +\code{S/R~OBCS\_CALC}. When turned on (\code{ALLOW\_OBCS\_BALANCE} +defined in \code{OBCS\_OPTIONS.h} and \code{useOBCSbalance=.true.} in +\code{data.obcs/OBCS\_PARM01}), the normal velocities across each of +the four boundaries are modified separately, so that the net volume +transport across \emph{each} boundary is zero. For example, for the +western boundary at $i=i_{b}$, the modified velocity is: +\[ +u(y,z) - \int_{\mbox{western boundary}}u\,dy\,dz \approx OBNu(j,k) - \sum_{j,k} +OBNu(j,k) h_{w}(i_{b},j,k)\Delta{y_G(i_{b},j)}\Delta{z(k)}. +\] +This also ensures a net total inflow of zero through all boundaries to +make it a useful flag to prevent infinite sea-level change within the +domain, but the flag is \emph{not} useful if you want to simulate, +say, a sector of the Southern Ocean with a strong ACC entering through +the western and leaving through the eastern boundary, because this +flag will make sure that the strong inflow is removed. It is +recommended that this part of the code is adapted to the particular +needs of the simulation in question. \paragraph{OBCS\_APPLY\_*:} ~ \\ ~ @@ -425,6 +463,22 @@ %---------------------------------------------------------------------- \subsubsection{Reference experiments} +In the directory \code{verifcation}, the following experiments use +\code{obcs}: +\begin{itemize} +\item \code{exp4}: box with 4 open boundaries, simulating flow over a + Gaussian bump based on \citet{adcroft:97}, also tests + Stevens-boundary conditions; +\item \code{dome}: based on the project ``Dynamics of Overflow Mixing + and Entrainment'' + (\url{http://www.rsmas.miami.edu/personal/tamay/DOME/dome.html}), uses + Orlanski-BCs; +\item \code{internal\_wave}: uses a heavily modified \code{S/R~OBCS\_CALC} +\item \code{seaice\_obcs}: simple example who to use the sea-ice + related code, based on \code{lab\_sea}; +\item \code{tutorial\_plume\_on\_slope}: uses Orlanski-BCs, see also + section~\ref{sec:eg-gravityplume}. +\end{itemize} @@ -436,7 +490,7 @@ \label{sec:pkg:obcs:experiments} \begin{itemize} -\item{Ocean experiment in exp4 verification directory. } +\item \code{tutorial\_plume\_on\_slope} (section~\ref{sec:eg-gravityplume}) \end{itemize}