PlaSim/Puma_UG_17/install.tex

The whole package, containing the models ``Planet Simulator'' and ``PUMA''
along with the {\bf mo}del {\bf st}arter ``most''.

The following subsection shows the commands to use for installation,
assuming your downloadfile is named ```Most17.tgz´´´. For other
formats like zip use unzip instead of tar.

\section{Quick Installation}

\begin{verbatim}
tar -zxvf Most17.tgz
cd Most17
./configure.sh
./most.x
\end{verbatim}

If your tar command doesn't support the ``-z'' option (e.g. on SOLARIS),
type instead:

\begin{verbatim}
gunzip Most17.tgz
tar -xvf Most17.tar
cd Most17
./configure.sh
./most.x
\end{verbatim}

If this sequence of commands produces error messages,
consult the FAQ (Frequently Asked Questions) and the README files
in the Most17 directory. They are in plain text files that can be read with
the more command or any other text editor.

\section{Most17 directory }

\begin{verbatim}
home/Most17> ls -lg

-rw-r--r--    3730  FAQ                 <- Frequently Asked Questions
-rw-r--r--    7862  NEW_IN_VERSION_17   <- New in this version
drwxr-xr-x     748  Plasim_RM_17        <- LaTeX source for RM
drwxr-xr-x     612  Plasim_UG_17        <- LaTeX source for UG
drwxr-xr-x    1122  Puma_UG_17          <- LaTeX source for UG
-rw-r--r--     718  README              <- Read this first
-rw-r--r--     617  README.md           <- File for download page
-rw-r--r--    1226  README_COUPLING_PLASIM_PUMA <- sic
-rw-r--r--     168  README_MAC_USER     <- Notes for MAC user
-rw-r--r--     462  README_UBUNTU       <- Notes for UBUNTU user
-rw-r--r--     698  README_WINDOWS_USER <- Notes for Windows user
-rw-r--r--    1548  cc_check.c          <- Used by configure script
-rwxr-xr-x      57  cleanplasim         <- Empty run, bld and bin for PLASIM
-rwxr-xr-x      51  cleanpuma           <- Empty run, bld and bin for PUMA
-rwxr-xr-x      48  cleansam            <- Empty run, bld and bin for SAM
-rwxr-xr-x     161  cmdpuma             <- Build GUI-less PUMA
-rwxr-xr-x    5611  configure.sh        <- Configure script (for bash shell)
-rw-r--r--     308  csub.c              <- Used by configure script
-rw-r--r--     234  f90check.f90        <- Used by configure script
drwxr-xr-x     102  images              <- Most images
-rw-r--r--      81  make_most           <- Used by configure script
-rw-r--r--     154  makecheck           <- Used by configure script
-rw-r--r--     108  makedebug           <- Used by configure script
-rw-r--r--      84  makefile            <- Makefile for building most.x
-rw-r--r--  113461  most.c              <- C source code for most
drwxr-xr-x     306  plasim              <- Planet Simulator directory tree
drwxr-xr-x     238  postprocessor       <- Postprocessor source and docs
drwxr-xr-x     306  puma                <- PUMA directory tree
drwxr-xr-x     510  sam                 <- SAM directory tree
drwxr-xr-x     680  tools               <- Some tools

\end{verbatim}

The directory structure must not be changed! Even empty directories must be
kept as they are, because the Most program relies on their existence!

For each model, currently ``Planet Simulator'', ``SAM'', and ``PUMA'', a directory exists
(plasim or sam or puma) with the following subdirectories:

\begin{verbatim}
Most17/puma> ls -lg

drwxr-xr-x  2   128  bin   <- model executables
drwxr-xr-x  2  1824  bld   <- build directory
drwxr-xr-x  2   280  dat   <- initial and boundary data
drwxr-xr-x  2    80  doc   <- documentation, user's guide, reference manual
drwxr-xr-x  2   928  run   <- run directory
drwxr-xr-x  2  1744  src   <- source code
\end{verbatim}

After installation only ``dat'', ``doc'' and ``src'' contain files.
All other directories are empty.

``MoSt'' (the executable is named most.x) is used to define parameters,
build the model, create a runscript and optional start the model.
The directories of the model are used in the following manner:

\section{Model build phase}

Most writes an executable shell script to the ``bld'' directory
and then executes it.
First, it copies all necessary source files from ``src'' to ``bld''
and modifies them according to the selected parameter configuration.
Modification of source code is necessary for vertical and horizontal
resolution changes, and when using more than one processor (parallel program
execution). The original files in the ``src`` directory are not changed by MoSt.

The program modules are then compiled and linked using the make command,
also issued by MoSt. MoSt provides two different makefiles:
one for the single CPU version and the other for the parallel version
(using MPI, the Message Passing Interface).
For Planet Simulator the resolution and CPU parameters are coded into the filename of the
executable, in order that there are different names for different versions.
E.g. the executable ``most\_plasim\_t21\_l10\_p2.x''
is an executable compiled for a horizontal resolution of T21,
a vertical resolution of 10 levels and 2 CPU's.
PUMA and SAM use universal executables, that can be used for different
resolutions, because they use dynamical array allocation at runtime.

The executable is copied to the model's ``bin'' directory
at the end of the build.
Rebuilding may be forced by using the {clean\modir} command
in the most directory.
The build directory is not cleared after usage. The user may want
to modify the makefile or the build script for his own purposes
and start the building directly by executing the ``most\_\modir\_build''
script.
For permanent user modifications,
the contents of the ``bld'' directory has to be copied elsewhere,
because each usage of MoSt overwrites its contents.

\section{Model run phase}

After building the model with the selected configuration,
MoSt writes or copies all the necessary files to the model's
``run'' directory. These are the executable, initial and boundary data,
namelist files containing the parameter, and finally the
run script itself. Depending on the exit selected from MoSt,
either ``Save \& Exit'' or ``Run \& Exit'', the run script is started
from MoSt and takes control of the model run. A checkmark on
GUI invokes the Graphical User Interface allowing the user to control
and display variables during the run.
Again, all the contents of the ``run'' directory are subject to change
by the user. However, it is better to save the changed run setups
in other user-created directories, because each usage of
MoSt will overwrite the contents of the run directory.
Alternatively, the user changed files could be renamed,
because MoSt always generates files with names beginning with ``most\_''
and leaves any other files untouched.

\section{Running long simulations}

For long simulations create a new directory on a file system
that has enough free disk space to store the results.
You can use the ``df'' command to check file systems.

Hint 1: Do not use your home directory if there are file quotas.
Your run may crash due to file quota being exceeded.

Hint 2: If possible use a local disk for long runs.
Network attached storage runs fine, but may slow down the model.

Example:

\begin{itemize}
\item cd Most17
\item ./most.x
\item Select model and resolution
\item Switch GUI off
\item Switch Output on
\item Edit number of years to run
\item Click on ``Save \& Exit''
\item Make a directory, e.g. mkdir /data/longsim
\item cp {\modir/run/*} /data/longsim
\item cd /data/longsim
\item Edit the experiment name in most\_\modir\_run
\item Edit the namelist files if necessary
\item Start the simulation with most\_\modir\_run \&
\end{itemize}