PlaSim/Plasim_UG_16/modules.tex

In the following, the purposes of the
individual modules is given and the general structure and possible
input and output opportunities (namelist and files) are explained. 

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

\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{fluxmod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module fluxmod.f90} contains subroutines to
compute the different surface fluxes and to perform the vertical diffusion. The interface to the
main PUMA module {\module puma.f90} is given by the subroutines {\sub fluxini}, {\sub
fluxstep} and {\sub fluxstop} which are called in {\module puma.f90} from the subroutines
{\sub prolog}, {\sub gridpointd} and {\sub epilog}, respectively. \vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module fluxmod.f90} does not use any extra input file  or
output file and  is controlled by the namelist {\nam fluxpar} which is part of the namelist file
{\file puma$\_$namelist}:

 \vspace{1mm} 

\begin{center}
\begin{tabular}{l l p{7cm} c}  %  {p{3cm} p{2cm} p{6cm} p{2cm}}
Parameter & Type & Purpose & Default \\
&&&\\
NEVAP & Integer & Switch for surface evaporation (0~=~off, 1~=~ on) & 1 \\
NSHFL & Integer &Switch for surface sensible heat flux (0~=~off, 1~=~ on) & 1 \\
NSTRESS & Integer & Switch for surface wind stress (0~=~off, 1~=~on) & 1 \\
NTSA & Integer & Switch for computing the near surface air temperature which is used for the
Richardson number (1~=~potential temperature, 2~=~virtual potential temperature)& 2 \\
NVDIFF & Integer & Switch for vertical diffusion (0~=~off, 1~=~on) & 1 \\
VDIFF$\_$LAMM & Real & Tuning parameter for vertical diffusion & 160. \\
VDIFF$\_$B & Real &Tuning parameter for vertical diffusion & 5. \\
VDIFF$\_$C & Real &Tuning parameter for vertical diffusion & 5. \\
VDIFF$\_$D & Real &Tuning parameter for vertical diffusion & 5. \\
ZUMIN$\_$D & Real &Minimum surface wind speed (m/s) & 1. \\
\end{tabular} 
\end{center}
\vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module fluxmod.f90} uses the FORTRAN-90
module {\modu fluxmod}, which uses the global common module {\modu pumamod} from
{\module pumamod.f90}. Subroutine {\sub fluxini} reads the namelist and, if the parallel
version
is used,  distributes the namelist parameters to the different processes. Subroutine {\sub
fluxstep}
calls the subroutine {\sub surflx} to compute the surface fluxes and calls the subroutine {\sub
vdiff} to do the vertical diffusion. Subroutine {\sub fluxstop} is a dummy subroutine since there
is nothing to do to finalize the computations in {\module fluxmod.f90}. The computation of the
surface fluxes in {\sub surflx} is spitted into several parts. After initializing the stability
dependent transfer coefficients, the subroutines {\sub mkstress}, {\sub mkshfl} and {\sub
mkevap} do the computations which are related to the surface wind stress, the surface sensible
heat flux and the surface evaporation, respectively. \vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage
%--------------------------------------------------------------------------------

\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{miscmod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module miscmod.f90} contains
miscellaneous subroutines which do not fit well to other modules.
The interface to the main module {\module plasim.f90} is given by
the subroutines {\sub miscini}, {\sub miscstep} and {\sub miscstop}
which are called in {\module puma.f90} from the subroutines {\sub prolog},
{\sub gridpointd} and {\sub epilog}, respectively.
A subroutine to eliminate spurious negative humidity and an optional
subroutine to relax the upper level temperature towards a prescribed 
distribution is included in {\module miscmod.f90}. \vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module miscmod.f90}
does not use any extra output file.
If the relaxation is switched on, a climatological annual cycle
of the prescribed  upper level temperature distribution [K] is read
from the external file {\file surface.txt}.
The file format is formatted SERVICE format with (8I10) for the headers
and (8E12.6) for the temperature fields. To assign the field,
the header needs to have the header information code 130,
level 1 and a date identifier of the form {\it yymmdd} or
{\it mmdd} where {\it mm} goes from 1 to 12 (January to December)
or from 0 to 14 (including the December of the previous year and
the January of the following year).
Fields which are not needed will be skipped. The module is
controlled by the namelist {\nam miscpar} which is part of the
namelist file {\file puma$\_$namelist}:

\vspace{1mm} 

\begin{center}
\begin{tabular}{l l p{5cm} c} % {p{3cm} p{2cm} p{6cm} p{2cm}}
Parameter & Type & Purpose & default \\
&&& \\
NFIXER & Integer & Switch for correction of negative moisture (0 = off , 1= on) & 1 \\
NUDGE  & Integer & Switch for temperature relaxation in the uppermost level (0 = off , 1= on)
& 0 \\
TNUDGE& Real & Time scale [d] of the temperature relaxation & 10. \\
\end{tabular} 
\end{center}
\vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module miscmod.f90} uses the FORTRAN-90
module {\modu miscmod}, which uses the global common module {\modu pumamod} from
{\module pumamod.f90}. Subroutine {\sub miscini} reads the namelist and, if the parallel
version is used,  distributes the namelist parameters to the different processes. If the relaxation
is
switched on, the climatological temperature is read from {\file surface.txt} and distributed
to the processors.   Subroutine {\sub miscstep} calls the subroutine {\sub fixer} to eliminate
spurious negative humidity arising from the spectral method and, if the relaxation is switched
on,
calls the subroutine {\sub mknudge} to do the temperature nudging. Subroutine {\sub miscstop}
is a dummy subroutine since there is nothing to do to finalize the computations in {\module
miscmod.f90}. \vspace{3mm} \\
\hline
\end{tabular}
\end{center} 
\newpage
%--------------------------------------------------------------------------------
\clearpage
\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{surfmod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module surfmod.f90}
deals as an interface between
the atmospheric part of the model and modules, or models, for the land and the oceans. The
interface to the main PUMA module {\module puma.f90} is given by the subroutines {\sub
surfini}, {\sub surfstep} and {\sub surfstop} which are called in {\module puma.f90} from the
subroutines {\sub prolog}, {\sub gridpointd} and {\sub epilog}, respectively. Calls to
subroutines
named {\sub landini}, {\sub landstep} and {\sub landstop} and {\sub seaini}, {\sub seastep} and
{\sub seastop} provide the interface to land and the ocean modules, respectively.
\vspace{3mm}
\\
\hline
\vspace{1mm} {\bf Input/Output} {\module surfmod.f90} reads the
land-sea mask and the orography (surface geopotential) [m$^2$/s$^2$]
from file {\file surface.txt}.
The file format is formatted SERVICE format with (8I10) for the headers
and (8E12.6) for the fields. To assign
the fields, the headers need to have the header information
code 129 for the surface geopotential
and 172 for the land-sea  mask (1.0 = land; 0.0 = sea).
Fractional land-sea-masks containing other values than 1.0 and 0.0
will be converted  with values $>$ 0.5 set to 1.0 and all other to 0.0.
{\module surfmod.f90} is controlled by the namelist {\nam surfpar} which is part of the
namelist file {\file puma$\_$namelist}:

\vspace{1mm} 

\begin{center}
\begin{tabular}{l l p{5cm} c} %{p{3cm} p{2cm} p{6cm} p{2cm}}
Parameter & Type & Purpose & default \\
&&&\\
NSURF & Integer & Debug switch  & not active \\
NOROMAX & Integer & Resolution of orography & NTRU \\
OROSCALE & Real & Scaling factor for orography & 1.0 \\
\end{tabular} 
\end{center}
\vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module surfmod.f90}
uses the FORTRAN-90 module {\modu surfmod}, which uses the global
common module {\modu pumamod} from {\module pumamod.f90}.
Subroutine {\sub surfini} reads the namelist and, if the parallel version
is used,  distributes the namelist parameters to the different processes.
If the run is not started from a restart file, the
land-sea-mask and the
orography are read from file {\file surface.txt}.
According to the namelist input, the orography
is scaled by OROSCALE, transfered into spectral space and truncated
to NOROMAX. Calls to subroutines {\sub landini} and {\sub seaini}
are the interfaces to the respective initialization
routines contained in the land and ocean modules.
During the run, the interface to land and ocean
is given by calls to the external subroutines {\sub landstep}
and {\sub seastep}, which are called by {\sub surfstep}.
At the end of the integration, interface subroutines
{\sub landstop} and {\sub
seastop} are called by {\sub surfstop}. \vspace{3mm} \\
\hline
\end{tabular}
\end{center} 
\newpage
%-----------------------------------------------------------------------------

\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 module {\module \modir.f90}
is given by the subroutines {\sub gp2fc} and {\sub
fc2gp} which are called in {\module \modir.f90} from the subroutine {\sub gridpoint}.  \vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module fftmod.f90} does not use any extra input file or
output file. 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 grid point 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 do the initialization of the FFT.
\vspace{3mm} \\
\hline
\vspace{2mm} The alternate 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.
Edit the file {\bf \most/\modir/src/make\_\modir } for module selection.
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{landmod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module landmod.f90} contains parameterizations
for
land surface and soil processes which include the simple biome model SIMBA and a model for
the river runoff. The interface to the {\model} is given via the module {\module surfmod.f90} by the
subroutines {\sub landini}, {\sub landstep} and {\sub landstop} which are called in {\module
surfmod.f90} from the subroutines {\sub surfini}, {\sub surfstep} and {\sub surfstop},
respectively. \vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module landmod.f90} reads several surface and soil
parameters either from the initial file {\file surface.txt}
or from the  restart file {\file \modir\_restart} which is written at
the end of an integration.
{\file surface.txt} contains several surface fields which are needed
for initialization. The file format is formatted
SERVICE
format with (8I10) for the header and (8E12.6) for the fields.
The file may include the following fields:
surface
geopotential (orography) [m$^2$/s$^2$], land-sea mask [1.0,0.0],
surface roughness [m],
background albedo [frac.], glacier mask [frac.], bucket size [m], soil temperature [K],
climatological annual cycle of the surface temperature [K], climatological annual cycle of the
soil wetness [m]. To assign the fields, the headers need to have the header information code
129
for surface geopotential, code 172 for the land-sea mask (1.~=~land; 0.~=~sea), 173 for the
surface
roughness, 174 for the background albedo, 232 for the glacier mask (1.~=~glacier; 0.~=~no
glacier),
229 for the bucket size, 209 for the soil temperature, 169 for the surface temperature and 140
for
the soil wetness. for the climatological annual cycles of surface temperature and soil wetness,
a
date identifier of the form {\it yymmdd} or {\it mmdd} where {\it mm}
goes from 1 to 12 (January to December) is required.
Two additional months with mm=0 indicating the December of the
preceding year an mm=13 for the January of the following year
may be included for interpolation during transient simulations.
If there are some fields not present in the  {\file surface.txt}
default values will be used which can be set in the
namelist. The use of some fields depend on the setting of some namelist  parameters. The
restart
file {\file \modir\_restart} is an unformatted file which contains
all variables needed to continue the run.
{\module landmod.f90} is controlled by the namelist {\nam landpar}
given in the namelist file {\file land\_namelist}:

 \vspace{1mm} 

\begin{center}
\begin{tabular}{l l p{5cm} c} %{p{3cm} p{2cm} p{6cm} p{2cm}}
Parameter & Type & Purpose & Default \\
&&&\\
NLANDT & Integer & Switch for surface temperature (1~=~computed; 0~=~climatology) &
1 \\
NLANDW & Integer & Switch for soil wetness (1~=~computed; 0~=~climatology) & 1 \\
NBIOME & Integer & Switch for biome model SIMBA (1~=~on ; 0~=~off) & 0 \\
ALBLAND & Real & Background albedo & 0.2 \\
DZ0LAND & Real & Roughnesslength [m]& 2.0 \\
DRHSLAND & Real & Wetness factor & 0.25 \\
ALBSMIN & Real& Minimum albedo for snow & 0.4 \\
ALBSMAX & Real& Maximum albedo for snow & 0.8
\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 \\
&&&\\
NWATCINI & Integer& Switch to initialize soil water content manually (1~=~on;0~=~off) & 0 \\
DWATCINI & Real& Soil water content (m) for manual initialization & 0.0 \\
ALBGMIN & Real& Minimum albedo for glaciers & 0.6 \\
ALBGMAX & Real& Maximum albedo for glaciers & 0.8 \\
WSMAX & Real&  Maximum field capacity of soil water (bucket size) [m] & 0.5 \\
DRHSFULL & Real&  Threshold above which wetness factor is 1 & 0.4 \\
DZGLAC &Real&  Threshold of orography to be glacier (-1.0~=~none) [m] & -1.0 \\
DZTOP &Real& Thickness of the uppermost soil layer [m] & 0.2 \\
DSOILZ(5) & Real Array & Soil layer thicknesses [m] & 0.4,0.8,1.6,3.2,6.4\\
\end{tabular}
\end{center}
\vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module landmod.f90} uses the FORTRAN-90
module {\modu landmod}, which uses the global common module {\modu pumamod} from
{\module plasimmod.f90}. Subroutine {\sub landini} reads the namelist and, if the parallel
version is used,  distributes the namelist parameters to the different
processes. If the run is not started from a restart file,
the initialization file
{\file surface.txt} is being read. The soil and the river runoff are initialized via {\sub
soilini}
and {\sub roffini} and different variables are set according to the
values given by the namelist or the {\file surface.txt}.
Additionally, the climatological surface temperatures and soil
wetnesses are updated from {\file surface.txt} if NRESTART~=~2. If NRESTART~=~3
(special application) the bucket size, the roughness length and the albedo are set to the values
given in the namelist.  Subroutine {\sub landstep} computes new surface and soil values via
{\sub soilstep} which calls {\sub tands} and {\sub wandr} for the heat and water budgets,
respectively. If NLANDT and/or NLANDW are set to 0, climatological values are used for
the
surface temperature and the soil wetness. Via {\sub roffstep} the river runoff is computed.
Finally
the biome model {\sub simbastep} is called. The land model is finalized by {\sub landstop}
which writes the restart record to {\file \modir\_restart}. \vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage
%----------------------------------------------------------------------------

\begin{center}
\begin{tabular}{|p{14cm}|}
\hline
\vspace{-5mm} \section{legmod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module legmod.f90}
contains all subroutines
necessary to perform the Legendre transformation and its inverse.
The interface to the main
module {\module \modir.f90} is given by the subroutines {\sub legini}, {\sub
inigau}, {\sub fc2sp}, {\sub fc3sp}, and {\sub sp2gp}
which are called in {\module \modir.f90}
from the subroutines {\sub prolog} and {\sub gridpoint}
\vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module legmod.f90}
 does not use any extra input file or
output file. No namelist input is required \vspace{3mm} \\
\hline
\vspace{1mm}
The following subroutines are included in {\module legmod.f90}:

\begin{center}
\begin{tabular}{l p{2cm} l}
Subroutine & &Purpose \\
&& \\
{\sub inigau} && compute Gaussian abscissas and weights \\
{\sub legini} && compute Legendre polynomials \\
{\sub fs2sp}  && Fourier to Spectral transformation \\
{\sub sp2fc}  && Spectral to Fourier transformation \\
{\sub sp3fc}  && Simultaneous transformation of T, Div., and Vort. \\
{\sub dirlega} && Compute and transform adiabatic tendencies \\
{\sub dirlegd} && Compute and transform diabatic tendencies \\
{\sub invlega} && Spectral to Fourier - adiabatic part \\
{\sub invlegd} && Spectral to Fourier - diabatic part \\
\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 interface
subroutines to the MPI (Message Passing Interface) needed for
(massive) parallel computing.  Several MPI routines are called
from the module. The interface to other modules are given by numerous
subroutines which names starts with {\sub mp}.
Subroutines from {\module mpimod.f90}  are
called in sveral other modules. There  are no direct calls to MPI other than
in {\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 by using MoSt or manually
by editing "Most15/\modir/src/make\_\modir".  \vspace{3mm} 
\\
\hline
\vspace{1mm} {\bf Input/Output} {\module mpimod.f90} and
{\module mpimod\_stub} do not use any extra input file or output file.
No namelist input is required \vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module mpimod.f90}
uses the FORTRAN-90 module
{\module mpimod},  which uses the global common module {\module pumamod} from
{\module \modir mod.f90} and the MPI module {\module mpi}.
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} & &finalize 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} && give 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{outmod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module outmod.f90} controls the data output of
the
model. The interface to the main
PUMA module {\module puma.f90} is given by the subroutines {\sub outini}, {\sub outgp},
{\sub outsp}, {\sub outreset} and {\sub outaccu} which are called in {\module puma.f90}
from
the subroutines {\sub prolog} and {\sub
master}. \vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module outmod.f90} writes the output data to the file
{\file
puma\_output} which is an unformatted file.
{\file puma\_output} is designed to be  post processed by the
program {\bf burn} (see section \ref{Pumaburner}), which  converts
the model variables to useful output in user friendly format. There is no separate namelist for
{\module outmod.f90} but some parameter of namelist {\nam inp}
of {\module \modir.f90}
are used to control the format and the output interval. \vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module outmod.f90} uses the global common
module {\modu pumamod} from
{\module \modir mod.f90} in several subroutines.
Subroutine {\sub outini} does the
initialization. Subroutines {\sub outgp} and {\sub outsp} write the grid point and the spectral
fields to the output file {\file puma\_output}.  {\sub outaccu} accumulates some
output variables  over the output interval. {\sub outreset} resets the accumulated arrays to
zero. 
\vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage
%--------------------------------------------------------------------------------

\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{plasim.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module plasim.f90}
is the main module of the model. It includes the main program
{\sub plasim} and controls the run.
From {\module plasim.f90} the interface routines to the modules
{\module miscmod.f90}, {\module fluxmod.f90}, {\module radmod.f90},
{\module rainmod.f90}, {\module surfmod.f90} are
called. The output is done by calling the interface routines to
{\module outmod.f90}. In addition, the adiabatic tendencies and
the horizontal diffusion are computed in {\module plasim.f90}.
To do the necessary transformations, calls to the modules
{\module fftmod.f90} and {\module legmod.f90} are used. \vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module plasim.f90} does not use
any extra input file  or output file.
A diagnostic print out is written on standard output.
{\module plasim.f90} is controlled by the namelist {\nam inp}
which is part of the namelist file {\file puma$\_$namelist}:

\vspace{1mm} 

\begin{center}
\begin{tabular}{l l p{5cm} c}  %  {p{3cm} p{2cm} p{6cm} p{2cm}}
Parameter & Type & Purpose & Default \\
&&&\\
COLUMN & Integer   & 1: Set all parameters for default column mode & 0 \\
KICK & Integer & Switch for initial white noise disturbance on surface pressure (0~=~none;
1~=~global; 2~=~hemispherically symmetric; 3~=~one wavenumber only) & 1 \\
NWPD & Integer & Number of Writes Per Day (for output data) & 1 \\
NADV   & Integer & Switch for advection (0~=~off;1~=~on)    &  1 \\
NCOEFF & Integer &Number of spectral coefficients in diagnostic print out & 0 \\
NDEL(NLEV)  & Integer Array & Order of the horizontal diffusion & NLEV $\cdot$ 2 \\
NDIAG & Integer & Time interval for diagnostic print out [time steps] & 12\\
NKITS & Integer & Number of initial explicit Euler time steps & 3 \\
N\_RUN\_YEARS & Integer & Number of years to run & 1 \\
N\_RUN\_MONTHS & Integer & Number of months to run & 0 \\
N\_RUN\_DAYS & Integer & Number of days to run (for short test runs) & -1 \\
N\_START\_YEAR & Integer & Start year & 1 \\
N\_START\_MONTH & Integer & Start month & 1 \\
N\_DAYS\_PER\_YEAR & Integer & 365: use real calendar with leap years,
360: use simple calendar with 12 months of equal length & 360 \\
N\_DAYS\_PER\_MONTH & Integer & Number of days per month for simple calendar
 & 30 \\
\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 \\
&&&\\
MPSTEP & Integer & Minutes per step $=$ length of timestep & 45 \\
NEQSIG & Integer & Switch for non equally spaced sigma levels (1~=~non equally spaced;
1~=~equally spaced) & 1 \\
NPRINT & Integer & Switch for extended debug print out (0~=~off; 1~=~on; 2~=~very
extended) & 0\\
NPRHOR & Integer & Number of the grid point to be used for very extended debug print out
&
0 \\
NPACKSP & Integer & Switch for spectral output (0~=~normal; 1~=~compressed) & 1 \\
NPACKGP & Integer & Switch for grid point output (0~=~normal; 1~=~compressed) & 1 \\
NRAD & Integer & Switch for radiation (0~=~off; 1~=~on) & 1 \\
NFLUX & Integer & Switch for surface fluxes and vertical diffuson (0~=~off; 1~=~on) & 1
\\
NDIAGGP & Integer & Switch for additional diagnostic grid point output (0~=~off; 1~=~on)
& 0\\
NDIAGSP & Integer & Switch for additional diagnostic spectral output (0~=~off; 1~=~on) &
0 \\
NDIAGCF & Integer & Switch for additional cloud forcing diagnostic (0~=~off; 1~=~on) &
0
\\
NDIAGGP2D & Integer & Number of  additional diagnostic 2-d grid point output (0~=~off;
1~=~on) & 0 \\
NDIAGGP3D & Integer & Number of  additional diagnostic 3-d grid point output (0~=~off;
1~=~on) & 0 \\
NDIAGSP2D & Integer & Number of  additional diagnostic 2-d spectral output (0~=~off;
1~=~on) & 0 \\
NDIAGSP3D & Integer & Number of  additional diagnostic 3-d spectral output (0~=~off;
1~=~on) & 0 \\
\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 \\
NHDIFF & Integer & Cut off wave number for horizontal diffusion &  15 \\
NHORDIF & Integer & Switch for horizontal diffusion (0~=~off;1~=~on) &  1 \\
NTIME & Integer & Switch for CPU time diagnostics (0~=~off; 1~=~on) & 0 \\
NPERPETUAL & Integer & Switch for perpetual simulations (0~=~annual cycle;
$>$0~=~day
of the year) & 0 \\
DTEP & Real & Equator to pole temperature difference [K] for Newtonian cooling (usually
not used) & 0.0 \\ 
DTNS & Real & North pole to south pole temperature difference [K] for Newtonian cooling 
(usually not used) & 0.0 \\   
DTROP & Real & Tropopause height [m] for Newtonian cooling (usually not used) &
12000.0 \\  
DTTRP & Real & Smoothing of the tropopause [K] for Newtonian cooling (usually not used)
& 2 \\
TGR & Real & Surface temperature [K] for Newtonian cooling (usually not used) & 280 \\
TDISSD(NLEV) & Real Array & time scale [d] for the horizontal diffusion of divergence&
NLEV $\cdot$ 0.2 \\
 TDISSZ(NLEV) & Real Array & time scale [d] for the horizontal diffusion of vorticity&
NLEV $\cdot$ 1.1 \\
TDISST(NLEV) & Real Array & time scale [d] for the horizontal diffusion of temperature &
NLEV $\cdot$ 5.6 \\
TDISSQ(NLEV) & Real Array & time scale [d] for the horizontal diffusion of moisture&
NLEV $\cdot$ 5.6 \\
PSURF & Real & Global mean sea level pressure [Pa] & 101100.00 \\
RESTIM(NLEV)  & Real Array & Time scale [d] for Newtonian cooling (usually not used)
& NLEV $\cdot$ 0.0 \\
\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}
Parameter & Type & Purpose & Default \\
&&&\\
MARS     & Integer   & 1: Set all parameters for Mars atmosphere & 0 \\
NGUI     & Integer   & Run with (1) or without (0) GUI & 0 \\
NOUTPUT  & Integer   & Global witch for enabling (1) or disabling (0)
output to file {\file puma\_output} & 1 \\
SELLON & Real & Longitude of soundings in the GUI & 0.0 \\
T0(NLEV) & Real Array& Reference temperature used in the discretization scheme & NLEV
$\cdot$ 250.0 \\
TFRC(NLEV) & Real Array & Time scale [d] for Rayleigh friction (0.0~=~off)& NLEV
$\cdot$ 0.0
\end{tabular} 
\end{center}
\vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module plasim.f90}
uses the FORTRAN-90 global common module {\modu pumamod} from
{\module plasimmod.f90}. After starting MPI, the main program
{\sub plasim} calls {\sub prolog} for initializing the model.
Then, {\sub master} is called to do the time stepping.
Finally, subroutine {\sub epilog} finishes the run.
In subroutine {\sub prolog}, calls to different subroutines,
which are part of {\module plasim.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
and sets some parameter according to the namelist input,
{\sub initpm} and {\sub initsi} initialize  some parameter
for the physics and the semi implicit scheme, respectively.
{\sub outini} starts the output. If a file named
{\file plasim\_restart} exists all variables and arrays are read
by {\sub restart}, otherwise {\sub initfd} sets the prognostic variables
to their initial values.  Calls to {\sub miscini} {\sub fluxini},
{\sub radini}, {\sub rainini} and {\sub surfini}
start the initialization of the respective external modules.i
Finally, the global mean surface pressure is set according to PSURF
(the observed value is 1011 hPa (Trenberth 1981) while 1013 is the
ICAO standard) and the orography.
Subroutine {\sub master} controls the time stepping.
First, if its not a restart, initial NKITS explicit forward timesteps are
performed.
The main loop is defined by calling {\sub gridpointa} for the adiabatic
tendencies, {\sub spectrala} to add the adiabatic tendencies,
{\sub gridpointd} for the diabatic tendencies (which are computed
by the external modules), {\sub spectrald} to add the diabatic tendencies and
the interface routines to the output module {\module outmod.f90}.
The run is finalized by subroutine {\sub epilog} which writes the
restart records and calls the respective interface routines of the
external modules. \vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage
 %---------------------------------------------------------------------------
\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{plasimmod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The file {\file plasimmod.f90}
contains the module {\module pumamod.f90} which declares
all parameters and variables which may be used to share
information between {\module plasim.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 file or
output file. No namelist input is required \vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module plasimmod.f90} is a FORTRAN-90
module named {\modu pumamod}. Names for global parameters, scalars and arrays are
declared and, if possible, values are preset.\vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage

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

% \clearpage
\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{radmod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module radmod.f90} contains subroutines to
compute radiative energy fluxes and the temperature tendencies due to long wave and short
wave radiation.  The interface to the
main PLASIM module {\module plasim.f90} is given by the subroutines {\sub radini}, {\sub
radstep} and {\sub radstop} which are called in {\module plasim.f90} from the subroutines
{\sub prolog}, {\sub gridpointd} and {\sub epilog}, respectively. \vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module radmod.f90} does not use an extra output file. If
the Switch for ozone (NO3, see namelist) is set to 2 (externally prescribed), the
climatological
cycle of the ozone distribution is read from the external file {\file surface.txt} which name
is given in the namelist. The file format is formatted SERVICE format with (8I10) for the
header and (8E12.6) for the fields. To assign the fields, the headers need to have the header
information code
200, level going from 1 to NLEV and a date identifier of the form {\it yymmdd} or {\it
mmdd}
where {\it mm} goes from 01 to 12 (January to December). 
{\module radmod.f90} is controlled by the namelist {\nam radpar} which is part of the
namelist
file {\file puma$\_$namelist}:

\vspace{1mm} 

\begin{center}
\begin{tabular}{l l p{5cm} c}  %  {p{3cm} p{2cm} p{6cm} p{2cm}}
Parameter & Type & Purpose & Default \\
&&&\\
NDCYCLE & Integer & Switch for diurnal cycle of insolation (0~=~off, 1~=~ on) & 0 \\
NO3 & Integer &Switch for ozone (0~=~off, 1~=~idealized distribution, 2~=~externally
presrcibed) & 1 \\
CO2 & Real & CO$_2$ concentration [ppmv] & 360.0 \\
GSOL0 & Real & Solar constant [W/m$^2$] & 1367.0 \\
IYRBP & Integer & Year PB (reference is 1950) to calculate orbit from & -50 \\
NSWR& Integer & Switch for short wave radiation (0~=~off, 1~=~ on)  & 1 \\
NLWR& Integer & Switch for long wave radiation (0~=~off, 1~=~ on)  & 1 \\
NSOL& Integer & Switch for incoming solar radiation (0~=~off, 1~=~ on)  & 1 \\
NSWRCL& Integer & Switch for computed short wave cloud properties (0~=~off, 1~=~ on) 
& 1 \\
NRSCAT&  Integer & Switch for Rayleigh scattering (0~=~off, 1~=~ on)  & 1 \\
RCL1(3) & Real Array & Prescribed cloud albedos [frac.] for high, middle and low level
clouds
(spectral range 1)& 0.15,0.30.0.60 \\
\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 \\
&&&\\
RCL2(3) & Real Array & Prescribed cloud albedos [frac.] for high, middle and low level
clouds
(spectral range 2) &0.15,0.30.0.60 \\
ACL2(3) & Real Array & Prescribed cloud absorptivities [frac.] for high, middle and low
level
clouds (spectral range 2) &0.05,0.10.0.20 \\
CLGRAY & Real & Prescribed grayness of clouds (-1.0~=~computed) & -1.0 \\
TPOFMT& Real & Tuning for point of mean transmission & 0.15 \\
ACLLWR& Real & Mass absorption coefficient for clouds (long wave) & 0.1 \\
TSWR1 & Real & Tuning of cloud albedo (spectral range 1) & 0.035 \\
TSWR2 & Real & Tuning of cloud back scattering (spectral range 2) & 0.04 \\
TSWR3 & Real & Tuning of cloud single scattering albedo (spectral range 2) & 0.006 \\
DAWN  & Real & Threshold for zenith angle & 0.0 \\
\end{tabular} 
\end{center}
\vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module radmod.f90}
uses the FORTRAN-90 module {\modu radmod}, which uses the global
common module {\modu pumamod} from {\module plasimmod.f90}.
Additionally,  the  FORTRAN-90 module {\modu orbparam} is used.
Subroutine {\sub radini} reads the namelist and, if the
parallel version is used,  distributes the namelist parameters to
the different processes. 
Orbital parameters are computed by calling {\sub orb$\_$params}.
If NO3 is set to 2, the ozone distribution is read from
{\file surface.txt}. Subroutine {\sub radstep} calls the subroutines
{\sub solang} and {\sub mko3} to compute the cosine of the solar angle
and the ozone distribution, respectively.
The short wave radiative fluxes are calculate in {\sub swr} while
the long wave radiative fluxes are computed in {\sub lwr}.
Subroutine {\sub radstop} is a dummy subroutine since there is
nothing to do to finalize the computations in {\module radmod.f90}.
\vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage

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


% \clearpage
\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{rainmod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module rainmod.f90} contains subroutines to
compute large scale and convective precipitation and the related temperature tendencies. In
addition, a parameterization of dry convective mixing of temperature and moisture is
included
and cloud cover is diagnosed. The interface to the main PLASIM module {\module plasim.f90}
is
given by the subroutines {\sub rainini}, {\sub rainstep} and {\sub rainstop} which are called
in
{\module puma.f90} from the subroutines {\sub prolog}, {\sub gridpointd} and {\sub
epilog},
respectively. \vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module rainmod.f90} does not use any extra input or
output file and  is controlled by the namelist {\nam rainpar} which is part of the namelist file
{\file puma$\_$namelist}:

\vspace{1mm} 

\begin{center}
\begin{tabular}{l l p{5cm} c}  %  {p{3cm} p{2cm} p{6cm} p{2cm}}
Parameter & Type & Purpose & Default \\
&&&\\
KBETTA & Integer & Switch for betta in Kuo parameterization (0~=~off, 1~=~ on) & 1 \\
NPRL & Integer &Switch for large scale precipitation (0~=~off, 1~=~on) & 1 \\
NPRC & Integer &Switch for convective  precipitation (0~=~off, 1~=~on) & 1 \\
NDCA & Integer &Switch for dry convective adjustment (0~=~off, 1~=~on) & 1 \\
NSHALLOW & Integer &Switch for shallow convection (0~=~off, 1~=~on) & 1 \\
RCRIT(NLEV) & Real Array & Critical relative humidity for cloud formation & computed \\
CLWCRIT1 & Real & Critical vertical velocity for cloud formation [Pa/s] (not active if
CLWCRIT2~$>$~CLWCRIT1) & -0.1 \\
CLWCRIT2 & Real & Critical vertical velocity for cloud formation [Pa/s] (not active if
CLWCRIT2~$>$~CLWCRIT1) & 0.0
\end{tabular} 
\end{center}
\vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module rainmod.f90} uses the FORTRAN-90
module {\modu rainmod}, which uses the global common module {\modu pumamod} from
{\module plasimmod.f90}. Subroutine {\sub rainini} reads the namelist and, if the parallel
version is used,  distributes the namelist parameters to the different processes. Subroutine
{\sub
rainstep} calls the subroutine {\sub mkdqdtgp} to obtain the adiabatic moisture tendencies in
grid point space, which are needed for the Kuo parameterization. {\sub kuo} is called to
compute the convective precipitation and the respective tendencies. Dry convective
adjustment
is performed in {\sub mkdca}. Large scale precipitation is computed in {\sub mklsp}. Finally,
diagnostic clouds are calculated in {\sub mkclouds}. Subroutine {\sub radstop} is a
dummy subroutine since there is nothing to do to finalize the computations in {\module
radmod.f90}. \vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage

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

% \clearpage
\begin{center}
\begin{tabular}{|p{15cm}|}
\hline
\vspace{-5mm} \section{seamod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module seamod.f90} is the interface from the
atmosphere to the ocean and the sea ice. The interface to the main PLASIM module {\module
puma.f90} is given by the subroutines {\sub seaini}, {\sub seastep} and {\sub seastop} which
are called in {\module puma.f90} from the subroutines {\sub prolog}, {\sub gridpointd} and
{\sub epilog} respectively. \vspace{3mm} \\
\hline
\vspace{1mm} {\bf Input/Output} {\module seamod.f90} reads different surface
parameters either from the file {\file surface.txt} (see namelist) and the file {\file
ocean$\_$parameter} or from the  restart file
{\file sea\_restart} which is written at the end of an integration.. The files formats
are unformatted for the restart file, formatted
SERVICE format with (8I10) for the header and (8E12.6) for the fields for {\file surface.txt}
and formatted
EXTRA format with (4I10) for the header and (6(1X,E12.6)) for the fields  for {\file
ocean$\_$parameter}.
The file {\file surface.txt} may include the following fields: The 
climatological annual cycle of the surface temperature [K] and the climatological annual
cycle
of the sea ice compactness [frac.]. To assign the fields, the headers need to have the header
information code 169
for surface temperature and code 210 for the compactness (1~=~ice; 0.~=~open water).
a date identifier of the form {\it yymmdd} or {\it mmdd} where {\it mm} goes from 1 to 12
(January to December) is required. Fields which are not needed will be skipped.  The file
{\file
ocean$\_$parameter} includes the following fields: The 
climatological annual cycle of the sea surface temperature [K], the climatological annual
cycle
of the mixed layer depth [m] and the climatological average of the deep ocean temperature
[m].
To assign the fields, the order must be as described above (no header information is used).
The
restart file {\file sea\_restart} contains all variables needed to
continue the run. {\module seamod.f90} is controlled by the namelist {\nam seapar} given in
the namelist file {\file sea\_namelist}:

\vspace{1mm} 

\begin{center}
\begin{tabular}{l l p{5cm} c}  %  {p{3cm} p{2cm} p{6cm} p{2cm}}
Parameter & Type & Purpose & Default \\
&&&\\
ALBSEA & Real & Albedo for ice free ocean & 0.069 \\
ALBICE & Real & Maximum albedo for sea ice & 0.7 \\
DZ0SEA & Real & Minimum roughness length [m] for ice free ocean & 1.0 $\cdot$
10$^{-5}$
\\
DZ0ICE & Real & Roughness length [m] for sea ice & 1.0 $\cdot$ 10$^{-3}$ \\
DRHSSEA& Real & Wetness factor for ice free ocean & 1.0 \\
DRHSICE& Real & Wetness factor for sea ice & 1.0 \\
NOCEAN & Integer & Switch for ocean model (0~=~climatological SST, 1~=~ocean model)
& 1 \\
NICE & Integer & Switch for sea ice model (0~=~climatological, 1~=~sea ice model) & 1 \\
\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 \\
&&&\\
NCPL$\_$ICE$\_$OCEAN& Integer & ice-ocean coupling time steps & 32 \\
NCPL$\_$ATMOS$\_$ICE & Integer & ice atmosphere coupling time steps & 1 \\
TDEEPSEA & Real &Homogeneous deep ocean temperature [K] & 0.0 \\
DHICEMIN & Real &  Minimum sea ice thickness [m] & 0.1 \\
\end{tabular} 
\end{center}
\vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module seamod.f90} uses the FORTRAN-90
module {\modu seamod}, which uses the global common module {\modu pumamod} from
{\module plasimmod.f90}. Subroutine {\sub seaini} reads the namelist and, if the parallel
version is used,  distributes the namelist parameters to the different processes.
If it is not a restart (i.e.~if NRESTART from {\nam inp} of {\module plasimmod.f90} is 0), the files
{\file surface.txt} and {\file ocean$\_$parameter} are being read. The climatological sea ice
compactness is converted to a sea ice thickness as initial condition and additional   surface
parameters are set. If it is a restart, the restart file {\file sea$\_$restart} is read. Subroutine
{\sub
seastep} accumulates the variables used for the coupling between the atmosphere and the
ocean.
The coupling is done via the sea ice model. There is no direct connection between
atmosphere 
and ocean model. If there is no sea ice, the coupling quantities are passed through the ice
model without changes.
Subroutine {\sub  seastop} finalizes the run and writes the restart records.
\vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage