PlaSim/Puma_UG_17/modules.tex

This is the technical documentation of the PUMA model. In the following, the purpose of each
module is given and its general structure and possible input and output
parameters provided (namelist, files) are explained. 

%--------------------------------------------------------------------------------

\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{fftmod.f90 / fft991mod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module fftmod.f90} contains all subroutines
necessary to perform the fast fourier transformation and its inverse. The interface to the main
PUMA module {\module puma.f90}
is given by the subroutines {\sub gp2fc} and {\sub
fc2gp} which are called in {\module puma.f90} from the subroutine {\sub gridpoint}.  \vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module fftmod.f90} does not use any additional input or
output files. No namelist input is required. \vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module fftmod.f90} uses the FORTRAN-90 module
{\module fftmod}, which uses no other modules. Subroutine {\sub gp2fc} performs the
transformation from gridpoint space into fourier space while the subroutine {\sub fc2gp} does
the transformation from fourier space into grid point space. Both routines use several
subroutines
to do the direct or indirect transformation for different factors. When {\sub gp2fc} or {\sub
fc2gp} is called for the first time, {\sub fftini} is called to initialize the FFT.
\vspace{3mm} \\
\hline
\vspace{2mm} Alternatively, the module {\module fft991mod.f90} may be used
instead of {\module fftmod.f90}. While {\module fftmod.f90} runs faster,
{\module fft991mod.f90} can be used for resolutions that are not supported by {\module fftmod.f90}, e.g. T63 or T106.
To select the appropriate module edit the file "Most15/puma/src/make\_puma".
Use either:
\begin{verbatim}
FFTMOD=fftmod
\end{verbatim}
or
\begin{verbatim}
FFTMOD=fft991mod
\end{verbatim}
\vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage

%---------------------------------------------------------------------------------------------

\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{guimod.f90 / guimod\_stub.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module guimod.f90}
contains subroutines for communication with the GUI.
On operating systems that do not support the Xlib library (X11R6) e.g. Windows,
{\module guimod\_stub.f90} may be used as a stub replacement.
\vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure}
The following subroutines are included in {\module guimod.f90}:

\begin{center}
\begin{tabular}{l p{2cm} l}
Subroutine & &Purpose \\
&& \\
{\sub guistart} && initialize the GUI \\
{\sub guistop}  && finalize the GUI \\
{\sub guistep\_puma} && called every timestep from PUMA \\
{\sub guistep\_plasim} && called every timestep from PLASIM \\
{\sub guips} && gather, scale, and send surface pressure to the GUI \\
{\sub guihor} && gather, scale, and send a gridpoint array to the GUI \\
{\sub guigv} && gather, scale, and send wind components to the GUI \\
{\sub change\_disp} && called for user input into the GUI \\
{\sub change\_dtep} && called for user input into the GUI \\
{\sub change\_dtns} && called for user input into the GUI \\
{\sub change\_co2} && called for user input into the GUI \\
{\sub change\_gsol0} && called for user input into the GUI \\
{\sub change\_dawn} && called for user input into the GUI \\
\end{tabular}
\end{center}
\vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage

%---------------------------------------------------------------------------------------------

\begin{center}
\begin{tabular}{|p{14cm}|}
\hline
\vspace{-5mm} \section{legsym.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module legsym.f90}
 contains all the subroutines
necessary to perform the Legendre transformation and its inverse.
The module legsym is written for arrays in alternate representation,
which use pairs of Northern and Southern latitudes. This symmetry conserving
scheme is different to the Legendre modules used in PLASIM or the preprocessor.

 The interface to the main
PUMA module {\module puma.f90} is given by the subroutines {\sub legini}, {\sub
inigau}, {\sub fc2sp}, {\sub fc3sp}, and {\sub sp2gp}
 which are called in {\module puma.f90}
from the subroutines {\sub prolog} and {\sub gridpoint}.
\vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module legsym.f90}
 does not use any other input or output files. No namelist input is required. 
 \vspace{3mm} \\
\hline
\vspace{1mm}
The following subroutines are included in {\module legsym.f90}:

\begin{center}
\begin{tabular}{l p{2cm} l}
Subroutine & &Purpose \\
&& \\
{\sub inigau} && compute Gaussian abscissae and weights \\
{\sub legini} && compute Legendre polynomials \\
{\sub fc2sp}  && Fourier to Spectral transformation \\
{\sub fc2spdmu}  && Fourier to Spectral transformation with d/dmu \\
{\sub sp2fc}  && Spectral to Fourier transformation \\
{\sub sp3fc}  && simultaneous transformation of T, Div., and Vort. \\
{\sub mktend} && compute and transform tendencies \\
{\sub reg2alt} && convert regular array to alternate array \\
{\sub alt2reg} && convert alternate array to regular array \\
\end{tabular}
\end{center}
\vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage

%--------------------------------------------------------------------------------
\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{mpimod.f90 / mpimod\_stub.f90} \vspace{-5mm}
\\
\hline
\vspace{1mm} {\bf General} The module {\module mpimod.f90} contains the interface
subroutines of the MPI ({\bf M}essage {\bf P}assing {\bf I}nterface) needed for 
(massive) parallel computing.  Several MPI
routines are called from the module. The interface to the other modules is provided by numerous
subroutines with names which begin with {\sub mp}. Subroutines in {\module mpimod.f90}  are
called from several other modules. There  are no direct calls to the MPI other than
from within {\module mpimod.f90}. This encapsulation makes it possible to
use {\module mpimod\_stub.f90} for single CPU runs without
changing any other part of the model code.
The selection is done automatically when using MoSt, or can be done manually
by editing "Most16/puma/src/make\_puma".  \vspace{3mm} 
\\
\hline
\vspace{1mm} {\bf Input/Output} {\module mpimod.f90} and {\module mpimod\underline{
}stub} do not use any extra input or
output files. No namelist input is required. \vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module mpimod.f90} uses the FORTRAN-90
module
{\module mpimod},  which in turn uses the global common module {\module pumamod} from
{\module pumamod.f90} and the MPI module {\module mpi}. {\module mpimod\underline{
}stub.f90} does not use any other module. The following subroutines are included in {\module
mpimod.f90}:

\begin{center}
\begin{tabular}{l p{2cm} l}
Subroutine & &Purpose \\
&& \\
{\sub mpbci} && broadcast 1 integer \\
{\sub mpbcin} & &broadcast n integers \\
{\sub mpbcr} & &broadcast 1 real \\
{\sub mpbcrn} & &broadcast n reals \\
{\sub mpbcl} && broadcast 1 logical \\
{\sub mpscin} & &scatter n integers \\
{\sub mpscrn} && scatter n reals \\
{\sub mpscgp} && scatter grid point field \\
{\sub mpgagp} && gather grid point field \\
{\sub mpgallgp} && gather grid point field to all \\
{\sub mpscsp} & &scatter spectral field \\
{\sub mpgasp} && gather spectral field \\
{\sub mpgacs} && gather cross section \\
{\sub mpgallsp} && gather spectral field to all \\
{\sub mpsum} && sum spectral field \\
{\sub mpsumsc} && sum and scatter spectral field \\
{\sub mpsumr} && sum n reals \\
{\sub mpsumbcr}& & sum and broadcast n reals \\
{\sub mpstart} & &initialize MPI \\
{\sub mpstop} & &terminate MPI \\
\end{tabular}
\end{center}
\vspace{3mm} \\
\hline
\end{tabular}
\end{center}

\newpage

\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\begin{center}
\begin{tabular}{l p{2cm} l}
Subroutine & &Purpose \\
&& \\
{\sub mpreadgp}& & read and scatter grid point field \\
{\sub mpwritegp}& & gather and write grid point field \\
{\sub mpwritegph} && gather and write (with header) grid point field \\
{\sub mpreadsp} & &read and scatter spectral field \\
{\sub mpwritesp} &&gather and write spectral field \\
{\sub mpi\_info} && report information about setup \\
{\sub mpgetsp}   && read spectral array from restart file \\
{\sub mpgetgp}   && read gridpoint array from restart file \\
{\sub mpputsp}   && write spectral array to restart file \\
{\sub mpputgp}   && write gridpoint array to restart file \\
{\sub mpmaxval}  && compute maximum value of an array \\
{\sub mpsumval}  && compute sum of all array elements \\
\end{tabular}
\end{center}

\vspace{3mm} \\

\hline
\end{tabular}
\end{center}
\newpage
%--------------------------------------------------------------------------------

\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{puma.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module puma.f90}
is the main module of the
model. It includes the main program {\sub puma} and controls the run.
The interface routines to all other modules are
called from {\module puma.f90}.
The output is performed by calling the subroutine to {\module outsp}, and
the adiabatic tendencies and the horizontal
diffusion are also computed in {\module puma.f90}.
To do the necessary transformations, calls to the modules {\module fftmod.f90}
and {\module legsym.f90} are used. \vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module puma.f90}
A diagnostic printout is written to the standard output
(usually redirected with the operator "$>$" to a file). {\module puma.f90} is
controlled by the namelist {\nam inp} which is part of the namelist file {\file
puma$\_$namelist}. For a complete list of namelist variables see
Appendix C. Here is a table of the most important ones:

\vspace{1mm} 

\begin{center}
\begin{tabular}{l l p{6cm} c}
Parameter & Type & Purpose & Default \\
&&&\\
MPSTEP & Integer & MPSTEP (Minutes Per STEP) defines the length of the
                   time step. Recommended values are 60 min. for T21
                   and 20 min for T42. The values are not checked
                   so take care not to violate the CFL
                   (Courant-Friedrichs-Levy) criterion!  & 60 \\
NYEARS  & Integer & Number of years to be run & 1 \\
NMONTHS & Integer & Number of months to be run : NYEARS and NMONTHS
                    may be used together. The simulation length in
                    days is: NYEARS * 360 + NMONTHS * 30.  & 0 \\
NOUTPUT & Integer & NOUTPUT is a global switch for enabling (1)
                    or disabling (0) writing to {\bf puma\_output}.   & 1 \\
NWPD    & Integer & NWPD (Number of Writes Per Day) defines the
                    output interval for writing model arrays to the
                    file {\bf puma\_output}. Possible values range
                    from 1 (daily output) to 24 (hourly).   & 1 \\
NDIAG   & Integer & NDIAG sets the interval (in time steps) for 
                    printing out some diagnostic arrays and values
                    to the standard output.   & 12 \\
\end{tabular}
\end{center}
\vspace{3mm} \\
\hline
\end{tabular}
\end{center}

\newpage 

\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\begin{center}
\begin{tabular}{l l p{5cm} c} %{p{3cm} p{2cm} p{6cm} p{2cm}}
Parameter & Type & Purpose & Default \\
&&&\\
NDL(NLEV) & Integer Array & Switch for diagnostic print out of a level (0~=~off; 1~=~on)
& NLEV $\cdot$ 0 \\
DTEP  & Real & Equator to pole temperature difference [K] for Newtonian cooling & 60.0 \\ 
DTNS  & Real & North to South pole temperature difference [K] for Newtonian cooling & 0.0 \\   
DTROP & Real & Tropopause height [m] for Newtonian cooling & 12000.0 \\  
DTTRP & Real & Smoothing of the tropopause [K] for Newtonian cooling & 2 \\
TGR   & Real & Surface temperature [K] for Newtonian cooling & 288 \\
TDISS & Real & Time scale [d] for the horizontal diffusion & 0.25 \\
PSURF & Real & Global mean sea level pressure [Pa] & 101100.00 \\
RESTIM(NLEV)  & Real Array & Time scale [d] for Newtonian cooling & 0.0 \\
T0K(NLEV)  & Real Array & Reference temperature used in the discretization scheme & 250.0 \\
TFRC(NLEV) & Real Array & Time scale [d] for Rayleigh friction (0.0~=~off)& 0.0
\end{tabular} 
\end{center}
\vspace{3mm} \\
\hline

\vspace{2mm} {\bf Structure}
After starting MPI, the main program {\sub puma} calls {\sub
prolog} to initialize the model. Then {\sub master} is called to do the time stepping.
Finally, subroutine {\sub epilog} terminates the run. In subroutine {\sub prolog} calls to
different subroutines, which are part of {\module puma.f90} or are  provided by other
modules, initialize various parts of the model: {\sub gauaw} and {\sub inilat} build  the grid,
{\sub readnl} reads the namelist file and sets parameters using the namelist input,
{\sub initpm} and {\sub initsi} initialize parameters for the physics and the semi
implicit scheme respectively, and {\sub outini} starts the output.
The program then checks for the existence of a file named "puma\_restart".
If the file can be opened then the restart record
is read by {\sub restart}, otherwise {\sub initfd} sets the prognostic variables 
to their initial values.
Finally, the global averaged surface
pressure is set using PSURF and the orography. The subroutine {\sub master} controls the
time stepping. First, if it is not a restart, the initial NKITS explicit forward time steps are
performed.
The main loop is defined by calling {\sub gridpoint} to set the nonlinear tendencies,
and {\sub spectral} to add the linear tendencies. The run is finalized by subroutine
{\sub epilog} which writes the restart records and terminates the MPI. \vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage
 %---------------------------------------------------------------------------------------
\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{pumamod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module pumamod.f90} contains all the parameters
and
variables which may be used to share information between {\module puma.f90} and other
modules. No subroutines or programs are included. \vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module pumamod.f90} does not use any extra input
or output files. No namelist input is required. \vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module pumamod.f90} is a FORTRAN-90
module named {\module pumamod}. Names for global parameters, scalars and arrays are
declared and, if possible, values are preset.\vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage

%---------------------------------------------------------------------------------------------
\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{restartmod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module restartmod.f90}
contains routines for opening, reading and writing the restart files.
The scalars and arrays of the restart files
are identified by name. This enables adding or removing
variables from the restart files without loosing compatibility.
There is also no dependence on the sequence of variables.
In parallel runs 
these routines are either called from the root process,
which takes care of broadcasting, or from subroutines in
{\module mpimod.f90} which gather before writing,
or scatter after reading, the arrays.
\vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure}
\begin{center}
\begin{tabular}{l p{2cm} l}
Subroutine & &Purpose \\
&& \\
{\sub restart\_ini} && Scan restart file and store pointer \\
{\sub restart\_prepare} && Open file for restart ouput \\
{\sub restart\_stop} && Close files \\
{\sub get\_restart\_integer} && Read integer scalar \\
{\sub get\_restart\_array} && Read real array \\
{\sub put\_restart\_integer} &&  Write integer scalar \\
{\sub put\_restart\_array}   && Write real array \\
{\sub fileseek} && position filepointer to requested variable \\
{\sub check\_equality} && May be used as debug tool \\
\end{tabular}
\end{center}

\vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage

%---------------------------------------------------------------------------------------------