--- manual/s_getstarted/text/getting_started.tex 2001/10/21 04:19:40 1.7 +++ manual/s_getstarted/text/getting_started.tex 2003/07/30 13:42:52 1.14 @@ -1,4 +1,4 @@ -% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.7 2001/10/21 04:19:40 cnh Exp $ +% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.14 2003/07/30 13:42:52 edhill Exp $ % $Name: $ %\section{Getting started} @@ -28,7 +28,7 @@ documentation, to data-sources and other related sites. There is also a support news group for the model that you can email at -\texttt{support@mitgcm.org} or browse at: +\texttt{MITgcm-support@mitgcm.org} or browse at: \begin{verbatim} news://mitgcm.org/mitgcm.support \end{verbatim} @@ -41,14 +41,14 @@ MITgcm can be downloaded from our system by following the instructions below. As a courtesy we ask that you send e-mail to us at -\begin{rawhtml} \end{rawhtml} -support@mitgcm.org +\begin{rawhtml} \end{rawhtml} +MITgcm-support@mitgcm.org \begin{rawhtml} \end{rawhtml} to enable us to keep track of who's using the model and in what application. You can download the model two ways: \begin{enumerate} -\item Using CVS software. CVS is a freely available source code managment +\item Using CVS software. CVS is a freely available source code management tool. To use CVS you need to have the software installed. Many systems come with CVS pre-installed, otherwise good places to look for the software for a particular platform are @@ -86,7 +86,7 @@ To obtain the sources for release1 type: \begin{verbatim} -% cvs co -d directory -P -r release1 MITgcmUV +% cvs co -d directory -P -r release1_beta1 MITgcm \end{verbatim} This creates a directory called \textit{directory}. If \textit{directory} @@ -116,17 +116,80 @@ delete; even if you do not use CVS yourself the information can help us if you should need to send us your copy of the code. +\paragraph*{Upgrading from an earlier version} + +If you already have an earlier version of the code you can ``upgrade'' +your copy instead of downloading the entire repository again. First, +``cd'' (change directory) to the top of your working copy: +\begin{verbatim} +% cd MITgcm +\end{verbatim} +and then issue the cvs update command: +\begin{verbatim} +% cvs -q update -r release1_beta1 -d -P +\end{verbatim} +This will update the ``tag'' to ``release1\_beta1'', add any new +directories (-d) and remove any empty directories (-P). The -q option +means be quiet which will reduce the number of messages you'll see in +the terminal. If you have modified the code prior to upgrading, CVS +will try to merge your changes with the upgrades. If there is a +conflict between your modifications and the upgrade, it will report +that file with a ``C'' in front, e.g.: +\begin{verbatim} +C model/src/ini_parms.F +\end{verbatim} +If the list of conflicts scrolled off the screen, you can re-issue the +cvs update command and it will report the conflicts. Conflicts are +indicated in the code by the delimites ``<<<<<<<'', ``======='' and +``>>>>>>>''. For example, +\begin{verbatim} +<<<<<<< ini_parms.F + & bottomDragLinear,myOwnBottomDragCoefficient, +======= + & bottomDragLinear,bottomDragQuadratic, +>>>>>>> 1.18 +\end{verbatim} +means that you added ``myOwnBottomDragCoefficient'' to a namelist at +the same time and place that we added ``bottomDragQuadratic''. You +need to resolve this conflict and in this case the line should be +changed to: +\begin{verbatim} + & bottomDragLinear,bottomDragQuadratic,myOwnBottomDragCoefficient, +\end{verbatim} +and the lines with the delimiters (<<<<<<,======,>>>>>>) be deleted. +Unless you are making modifications which exactly parallel +developments we make, these types of conflicts should be rare. + +\paragraph*{Upgrading to the current pre-release version} + +We don't make a ``release'' for every little patch and bug fix in +order to keep the frequency of upgrades to a minimum. However, if you +have run into a problem for which ``we have already fixed in the +latest code'' and we haven't made a ``tag'' or ``release'' since that +patch then you'll need to get the latest code: +\begin{verbatim} +% cvs -q update -A -d -P +\end{verbatim} +Unlike, the ``check-out'' and ``update'' procedures above, there is no +``tag'' or release name. The -A tells CVS to upgrade to the +very latest version. As a rule, we don't recommend this since you +might upgrade while we are in the processes of checking in the code so +that you may only have part of a patch. Using this method of updating +also means we can't tell what version of the code you are working +with. So please be sure you understand what you're doing. + \section{Model and directory structure} -The ``numerical'' model is contained within a execution environment support -wrapper. This wrapper is designed to provide a general framework for -grid-point models. MITgcmUV is a specific numerical model that uses the -framework. Under this structure the model is split into execution -environment support code and conventional numerical model code. The -execution environment support code is held under the \textit{eesupp} -directory. The grid point model code is held under the \textit{model} -directory. Code execution actually starts in the \textit{eesupp} routines -and not in the \textit{model} routines. For this reason the top-level +The ``numerical'' model is contained within a execution environment +support wrapper. This wrapper is designed to provide a general +framework for grid-point models. MITgcmUV is a specific numerical +model that uses the framework. Under this structure the model is split +into execution environment support code and conventional numerical +model code. The execution environment support code is held under the +\textit{eesupp} directory. The grid point model code is held under the +\textit{model} directory. Code execution actually starts in the +\textit{eesupp} routines and not in the \textit{model} routines. For +this reason the top-level \textit{MAIN.F} is in the \textit{eesupp/src} directory. In general, end-users should not need to worry about this level. The top-level routine for the numerical part of the code is in \textit{model/src/THE\_MODEL\_MAIN.F% @@ -139,7 +202,7 @@ \item \textit{diags}: contains the code relative to time-averaged diagnostics. It is subdivided into two subdirectories \textit{inc} and -\textit{src} that contain include files (*.\textit{h} files) and fortran +\textit{src} that contain include files (*.\textit{h} files) and Fortran subroutines (*.\textit{F} files), respectively. \item \textit{doc}: contains brief documentation notes. @@ -180,40 +243,47 @@ \section{Example experiments} \label{sect:modelExamples} -Now that you have successfully downloaded the model code we recommend that -you first try to run the examples provided with the base version. You will -probably want to run the example that is the closest to the configuration -you will use eventually. The examples are located in subdirectories under -the directory \textit{verification} and are briefly described below (a full -description is given in section 2): +The MITgcm distribution comes with a set of twenty-four pre-configured +numerical experiments. Some of these examples experiments are tests of +individual parts of the model code, but many are fully fledged numerical +simulations. A few of the examples are used for tutorial documentation +in sections \ref{sect:eg-baro} - \ref{sect:eg-global}. The other examples +follow the same general structure as the tutorial examples. However, +they only include brief instructions in a text file called {\it README}. +The examples are located in subdirectories under +the directory \textit{verification}. Each +example is briefly described below. -\subsection{List of model examples} +\subsection{Full list of model examples} -\begin{itemize} +\begin{enumerate} \item \textit{exp0} - single layer, ocean double gyre (barotropic with -free-surface). +free-surface). This experiment is described in detail in section +\ref{sect:eg-baro}. -\item \textit{exp1} - 4 layers, ocean double gyre. +\item \textit{exp1} - Four layer, ocean double gyre. This experiment is described in detail in section +\ref{sect:eg-baroc}. \item \textit{exp2} - 4x4 degree global ocean simulation with steady -climatological forcing. +climatological forcing. This experiment is described in detail in section +\ref{sect:eg-global}. -\item \textit{exp4} - flow over a Gaussian bump in open-water or channel +\item \textit{exp4} - Flow over a Gaussian bump in open-water or channel with open boundaries. -\item \textit{exp5} - inhomogenously forced ocean convection in a doubly +\item \textit{exp5} - Inhomogenously forced ocean convection in a doubly periodic box. -\item \textit{front\_relax} - relaxation of an ocean thermal front (test for +\item \textit{front\_relax} - Relaxation of an ocean thermal front (test for Gent/McWilliams scheme). 2D (Y-Z). -\item \textit{internal wave} - ocean internal wave forced by open boundary +\item \textit{internal wave} - Ocean internal wave forced by open boundary conditions. -\item \textit{natl\_box} - eastern subtropical North Atlantic with KPP +\item \textit{natl\_box} - Eastern subtropical North Atlantic with KPP scheme; 1 month integration -\item \textit{hs94.1x64x5} - zonal averaged atmosphere using Held and Suarez +\item \textit{hs94.1x64x5} - Zonal averaged atmosphere using Held and Suarez '94 forcing. \item \textit{hs94.128x64x5} - 3D atmosphere dynamics using Held and Suarez @@ -222,24 +292,52 @@ \item \textit{hs94.cs-32x32x5} - 3D atmosphere dynamics using Held and Suarez '94 forcing on the cubed sphere. -\item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics, 5 layers -Molteni physics package. Global Zonal Mean configuration, 1x64x5 resolution. +\item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics. Global +Zonal Mean configuration, 1x64x5 resolution. \item \textit{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate Atmospheric -physics, 5 layers Molteni physics package. Equatorial Slice configuration. +physics, equatorial Slice configuration. 2D (X-Z). \item \textit{aim.5l\_Equatorial\_Channel} - Intermediate Atmospheric -physics, 5 layers Molteni physics package. 3D Equatorial Channel -configuration (not completely tested). +physics. 3D Equatorial Channel configuration. -\item \textit{aim.5l\_LatLon} - Intermediate Atmospheric physics, 5 layers -Molteni physics package. Global configuration, 128x64x5 resolution. +\item \textit{aim.5l\_LatLon} - Intermediate Atmospheric physics. +Global configuration, on latitude longitude grid with 128x64x5 grid points +($2.8^\circ{\rm degree}$ resolution). -\item \textit{adjustment.128x64x1} +\item \textit{adjustment.128x64x1} Barotropic adjustment +problem on latitude longitude grid with 128x64 grid points ($2.8^\circ{\rm degree}$ resolution). \item \textit{adjustment.cs-32x32x1} -\end{itemize} +Barotropic adjustment +problem on cube sphere grid with 32x32 points per face ( roughly +$2.8^\circ{\rm degree}$ resolution). + +\item \textit{advect\_cs} Two-dimensional passive advection test on +cube sphere grid. + +\item \textit{advect\_xy} Two-dimensional (horizontal plane) passive advection +test on Cartesian grid. + +\item \textit{advect\_yz} Two-dimensional (vertical plane) passive advection test on Cartesian grid. + +\item \textit{carbon} Simple passive tracer experiment. Includes derivative +calculation. Described in detail in section \ref{sect:eg-carbon-ad}. + +\item \textit{flt\_example} Example of using float package. + +\item \textit{global\_ocean.90x40x15} Global circulation with +GM, flux boundary conditions and poles. + +\item \textit{global\_ocean\_pressure} Global circulation in pressure + coordinate (non-Boussinesq ocean model). Described in detail in + section \ref{sect:eg-globalpressure}. + +\item \textit{solid-body.cs-32x32x1} Solid body rotation test for cube sphere +grid. + +\end{enumerate} \subsection{Directory structure of model examples} @@ -266,7 +364,7 @@ code} depending on the particular experiment. See section 2 for more details. \item \textit{input}: contains the input data files required to run the -example. At a mimimum, the \textit{input} directory contains the following +example. At a minimum, the \textit{input} directory contains the following files: \begin{itemize} @@ -299,9 +397,9 @@ To compile the code, we use the {\em make} program. This uses a file ({\em Makefile}) that allows us to pre-process source files, specify compiler and optimization options and also figures out any file -dependancies. We supply a script ({\em genmake}), described in section +dependencies. We supply a script ({\em genmake}), described in section \ref{sect:genmake}, that automatically creates the {\em Makefile} for -you. You then need to build the dependancies and compile the code. +you. You then need to build the dependencies and compile the code. As an example, let's assume that you want to build and run experiment \textit{verification/exp2}. The are multiple ways and places to actually @@ -323,7 +421,7 @@ % ../../../tools/genmake -mods=../code \end{verbatim} -Next, create the dependancies: +Next, create the dependencies: \begin{verbatim} % make depend \end{verbatim} @@ -375,7 +473,7 @@ % cp ../code/mitgcmuv ./ % ./mitgcmuv > output.txt \end{verbatim} -or if you will be making muliple runs with the same executable: +or if you will be making multiple runs with the same executable: \begin{verbatim} % cd ../ % cp -r input run1 @@ -387,7 +485,7 @@ \subsubsection{Building from a new directory} Since the {\em input} directory contains input files it is often more -useful to keep {\em input} prestine and build in a new directory +useful to keep {\em input} pristine and build in a new directory within {\em verification/exp2/}: \begin{verbatim} % cd verification/exp2 @@ -773,43 +871,70 @@ \item time-discretization \end{itemize} -The time steps are set through the real variables \textbf{deltaTMom }and -\textbf{deltaTtracer }(in s) which represent the time step for the momentum -and tracer equations, respectively. For synchronous integrations, simply set -the two variables to the same value (or you can prescribe one time step only -through the variable \textbf{deltaT}). The Adams-Bashforth stabilizing -parameter is set through the variable \textbf{abEps }(dimensionless). The -stagger baroclinic time stepping can be activated by setting the logical -variable \textbf{staggerTimeStep }to '.\texttt{TRUE}.'. +The time steps are set through the real variables \textbf{deltaTMom} +and \textbf{deltaTtracer} (in s) which represent the time step for the +momentum and tracer equations, respectively. For synchronous +integrations, simply set the two variables to the same value (or you +can prescribe one time step only through the variable +\textbf{deltaT}). The Adams-Bashforth stabilizing parameter is set +through the variable \textbf{abEps} (dimensionless). The stagger +baroclinic time stepping can be activated by setting the logical +variable \textbf{staggerTimeStep} to '.\texttt{TRUE}.'. \subsection{Equation of state} -First, because the model equations are written in terms of perturbations, a -reference thermodynamic state needs to be specified. This is done through -the 1D arrays \textbf{tRef}\textit{\ }and \textbf{sRef}. \textbf{tRef }% -specifies the reference potential temperature profile (in $^{o}$C for -the ocean and $^{o}$K for the atmosphere) starting from the level -k=1. Similarly, \textbf{sRef}\textit{\ }specifies the reference salinity -profile (in ppt) for the ocean or the reference specific humidity profile -(in g/kg) for the atmosphere. - -The form of the equation of state is controlled by the character variables -\textbf{buoyancyRelation}\textit{\ }and \textbf{eosType}\textit{. }\textbf{% -buoyancyRelation}\textit{\ }is set to '\texttt{OCEANIC}' by default and -needs to be set to '\texttt{ATMOSPHERIC}' for atmosphere simulations. In -this case, \textbf{eosType}\textit{\ }must be set to '\texttt{IDEALGAS}'. -For the ocean, two forms of the equation of state are available: linear (set -\textbf{eosType}\textit{\ }to '\texttt{LINEAR}') and a polynomial -approximation to the full nonlinear equation ( set \textbf{eosType}\textit{\ -}to '\texttt{POLYNOMIAL}'). In the linear case, you need to specify the -thermal and haline expansion coefficients represented by the variables -\textbf{tAlpha}\textit{\ }(in K$^{-1}$) and \textbf{sBeta}\textit{\ }(in ppt$% -^{-1}$). For the nonlinear case, you need to generate a file of polynomial -coefficients called \textit{POLY3.COEFFS. }To do this, use the program -\textit{utils/knudsen2/knudsen2.f }under the model tree (a Makefile is -available in the same directory and you will need to edit the number and the -values of the vertical levels in \textit{knudsen2.f }so that they match -those of your configuration). \textit{\ } +First, because the model equations are written in terms of +perturbations, a reference thermodynamic state needs to be specified. +This is done through the 1D arrays \textbf{tRef} and \textbf{sRef}. +\textbf{tRef} specifies the reference potential temperature profile +(in $^{o}$C for the ocean and $^{o}$K for the atmosphere) starting +from the level k=1. Similarly, \textbf{sRef} specifies the reference +salinity profile (in ppt) for the ocean or the reference specific +humidity profile (in g/kg) for the atmosphere. + +The form of the equation of state is controlled by the character +variables \textbf{buoyancyRelation} and \textbf{eosType}. +\textbf{buoyancyRelation} is set to '\texttt{OCEANIC}' by default and +needs to be set to '\texttt{ATMOSPHERIC}' for atmosphere simulations. +In this case, \textbf{eosType} must be set to '\texttt{IDEALGAS}'. +For the ocean, two forms of the equation of state are available: +linear (set \textbf{eosType} to '\texttt{LINEAR}') and a polynomial +approximation to the full nonlinear equation ( set +\textbf{eosType}\textit{\ }to '\texttt{POLYNOMIAL}'). In the linear +case, you need to specify the thermal and haline expansion +coefficients represented by the variables \textbf{tAlpha}\textit{\ + }(in K$^{-1}$) and \textbf{sBeta} (in ppt$^{-1}$). For the nonlinear +case, you need to generate a file of polynomial coefficients called +\textit{POLY3.COEFFS}. To do this, use the program +\textit{utils/knudsen2/knudsen2.f} under the model tree (a Makefile is +available in the same directory and you will need to edit the number +and the values of the vertical levels in \textit{knudsen2.f} so that +they match those of your configuration). + +There there are also higher polynomials for the equation of state: +\begin{description} +\item['\texttt{UNESCO}':] The UNESCO equation of state formula of + Fofonoff and Millard \cite{fofonoff83}. This equation of state + assumes in-situ temperature, which is not a model variable; \emph{its use + is therefore discouraged, and it is only listed for completeness}. +\item['\texttt{JMD95Z}':] A modified UNESCO formula by Jackett and + McDougall \cite{jackett95}, which uses the model variable potential + temperature as input. The '\texttt{Z}' indicates that this equation + of state uses a horizontally and temporally constant pressure + $p_{0}=-g\rho_{0}z$. +\item['\texttt{JMD95P}':] A modified UNESCO formula by Jackett and + McDougall \cite{jackett95}, which uses the model variable potential + temperature as input. The '\texttt{P}' indicates that this equation + of state uses the actual hydrostatic pressure of the last time + step. Lagging the pressure in this way requires an additional pickup + file for restarts. +\item['\texttt{MDJWF}':] The new, more accurate and less expensive + equation of state by McDougall et~al. \cite{mcdougall03}. It also + requires lagging the pressure and therefore an additional pickup + file for restarts. +\end{description} +For none of these options an reference profile of temperature or +salinity is required. \subsection{Momentum equations} @@ -1042,3 +1167,8 @@ The precision with which to write the binary data is controlled by the integer variable w\textbf{riteBinaryPrec }(set it to \texttt{32} or \texttt{% 64}). + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: t +%%% End: