PlaSim/Plasim_UG_16/install.tex

The whole package containing the models "Planet Simulator" and "PUMA"
along with "MoSt", the "Model Starter" comes in a single file,
usually named "Most(n).tgz" with (n) specifying a version number.
The following subsection gives an example, assuming version 16.

\section{Quick Installation}

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

if your tar-command doesn't support the "-z" option (e.g. on Sun UNIX)
type instead:

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

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

\section{{\most}  directory }

\begin{verbatim}
home/Most16> ls -lG

-rw-r--r-- 1   1548 cc_check.c          <- Used by configure.sh
-rwxr-xr-x 1     57 cleanplasim         <- Delete run, bld and bin for PLASIM
-rwxr-xr-x 1     51 cleanpuma           <- Delete run, bld and bin for PUMA
drwxr-xr-x 2   4096 common              <- Topography files
-rwxr-xr-x 1   3911 configure.sh        <- The configure script
-rw-r--r-- 1    308 csub.c              <- Currently unused
-rw-r--r-- 1    234 f90check.f90        <- Used by configure.sh
-rw-r--r-- 1   3033 FAQ                 <- Frequently Asked Questions
drwxr-xr-x 2   4096 images              <- Directory for images
-rw-r--r-- 1    154 makecheck           <- Used by configure.sh
-rw-r--r-- 1     85 makefile            <- Used to "make" most.x
-rw-r--r-- 1 107844 most.c              <- Source for MoSt (Model Starter)
-rw-r--r-- 1   6399 NEW_IN_VERSION_16   <- New in this version
drwxr-xr-x 8   4096 plasim              <- Planet Simulator directory
drwxr-xr-x 2   4096 postprocessor       <- Postprocessor directory
drwxr-xr-x 8   4096 puma                <- PUMA directory
-rw-r--r-- 1    839 README              <- Read this first
-rw-r--r-- 1    191 README_MAC_USER     <- Notes for MAC user
-rw-r--r-- 1    698 README_WINDOWS_USER <- Notes for Windows user
\end{verbatim}

The directory structure must not be changed, even empty directories must be
kept as they are, the Most program relies on the existence of these directories!

For each model, currently "Planet Simulator" and "PUMA" exists a directory
(plasim) and (puma) with following subdirectories:

\begin{verbatim}
Most16/plasim> 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.

Running "Most" to setup a model configuration and define an experiment uses the
directories in the following manner:

\section{Model build phase}

Most writes an executable shell script to the "bld" directory
and executes it directly hereafter.
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 change and for using more than 1 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 
(in bld/most\_plasim\_build),
also issued by Most. Most provides a makefile named make\_\modir \ for
building the executable. For modules that exist in more than one
version the selection of the module to use is done by environment
variables that are set automatically by MoSt but may be changed
manually by the user. Look into the make\_\modir \ for further information.
The resolution and CPU parameters are coded into the filename of the
executable, in order to have different names for different versions.
E.g. the executable "most\_\modir\_t21\_l10\_p2.x" 
is an executable compiled for a horizontal resolution of T21, 
a vertical resolution of 10 levels and 2 CPU's.
The executable is copied to the models "bin" directory after building.
Each time Most is used to setup a new experiment it checks the "bin"
directory for a matching executable. If it's there, it's used without
rebuilding otherwise a new executable with the selected parameters
is created. 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 "most\_\modir\_build".
For permanent user modifications
the contents of the "bld" directories have to be copied elsewhere,
because each usage of Most overwrites the contents of "bld".

\section{Model run phase}

After building the model with the selected configuration,
Most writes or copies all 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 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 also the 
Graphical User Interface for user control and display
of variables during the run.
Again all contents of the "run" directory are subject of change
for the user. But it would be wise to keep changed run setups
in other, user created directories, because each usage of
Most overwrites the contents of the run directory.

\section{Running long simulations}

For long simulations make a new directory on a filesystem,
that has enough free disk space to store the results.
You may use the "df" command to check filesystems.

Hint 1: Don't use your home directory if there are filequotas.
Your run may crash due to file quota exceeded.

Hint 2: Use a local disk, not NFS mounted filesystems if possible.
The model runs much faster writing output to local disks.

Example:

\begin{itemize}
\item cd {\most}
\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 most\_\modir\_run for experiment name
\item edit namelist files if necessary
\item start simulation with most\_\modir\_run \&
\end{itemize}