PlaSim/Plasim_RM_16/modules.tex

This is a technical documentation of the PUMA-II model. In the following, the purposes of the
individual modules is given and the general structure and possible input and output
opportunities
(namelist, files) are explained. 

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

% \clearpage
\begin{center}
\begin{tabular}{|p{14cm}|}
\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. \\
\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{14cm}|}
\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 PUMA module
{\module puma.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 CLIMATEFILE} (see namelist).
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
01 to 12 (January to December). 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. \\
CLIMATEFILE& Character & Name of the file containing the prescribed temperature
distribution & surface\underline{ }parameter  
\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 CLIMATEFILE} 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{14cm}|}
\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 [frac.] and
the orography (surface geopotential) [m$^2$/s$^2$] from file {\file INPUTFILE} (see
namelist). 
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. = land; 0. = sea). Fields which are not needed will be skipped. 
{\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 \\
INPUTFILE& Character & Name of the input file & surface\underline{ }parameter  
\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 (NRESTART from namelist {\nam inp}of {\module puma.f90} is 0), the
land-sea-mask and the
orography are read from file {\file INPUTFILE}. 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{14cm}|}
\hline
\vspace{-5mm} \section{fftmod.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} and to other modules (at the moment {\module
surfmod.f90}, {\module
legmod.f90} and {\module rainmod.f90}) is given by the subroutines {\sub gp2fc} and {\sub
fc2gp} which are called in {\module puma.f90} from the subroutines {\sub gridpointa} and
{\sub gridpointd}, in {\module surfmod.f90} from {\sub surfini}, in {\module legmod.f90}
from {\sub sp2gp}, and in {\module rainmod.f90} from {\sub mkdqdtgp}.  \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
{\modu 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 the first time, {\sub fftini} is called to do the initialization of the FFT.
\vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage
%--------------------------------------------------------------------------------

\begin{center}
\begin{tabular}{|p{14cm}|}
\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 PUMA 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 STARTFILE} (see namelist)  or from the  restart file
{\file land\underline{ }restart} which is written at the end of an integration. {\file STARTFILE}
contains
different 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 [frac.], 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 01 to 12
(January to December) is required. Fields which are not needed will be skipped. If there are
some
fields not present in the  {\file STARTFILE} 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 land\underline{ }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\underline{ }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; 2~=~climatology) &
1 \\
NLANDW & Integer &  Switch for soil wettness (1~=~computed; 2~=~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}
\end{tabular}
\end{center}

\newpage 

\begin{center}
\begin{tabular}{|p{14cm}|}
\begin{center}
\begin{tabular}{l l p{5cm} c} %{p{3cm} p{2cm} p{6cm} p{2cm}}
Parameter & Type & Purpose & Default \\
&&&\\
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\\
STARTFILE & Character & Initialization file & surface\underline{ }parameter \\  
\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 pumamod.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 (NRESTART from namelist {\nam inp} of {\module puma.f90}is
0), the initialization file
{\file STARTFILE} 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 STARTFILE}. If it is a restart  (NRESTART~=~1), the restart records are being
read
from {\file land\underline{ }restart}. Additionally, the climatological surface temperatures
and
soil
wetnesses are updated from {\file STARTFILE} 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 land\underline{ }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
PUMA module {\module puma.f90} and to other modules (at the moment {\module
surfmod.f90} and {\module rainmod.f90}) is given by the subroutines {\sub legini}, {\sub
gauaw}, {\sub sp2fl}, {\sub invlega}, {\sub invlegd}, {\sub fc2sp}, {\sub dirlega}, {\sub
dirlegd}, {\sub fc3sp}, {\sub uv2dv}  and {\sub sp2gp} which are called in {\module
puma.f90}
from the subroutines {\sub prolog}, {\sub gridpointa} and {\sub
gridpointd}, in {\module surfmod.f90} from {\sub surfini}, and in {\module rainmod.f90}
from
{\sub mkdqdtgp}.  \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{2mm} {\bf Structure} Internally, {\module legmod.f90} uses the FORTRAN-90
module
{\modu legmod},  which uses the global common module {\modu pumamod} from
{\module pumamod.f90}. Subroutine {\sub legini} does the initialization. Subroutine {\sub
gauaw} computes the Gaussian latitudes and the corresponding weights. Subroutine {\sub
sp2fl}    performs the transformation from spectral to fourier space for multilevel fields. The
Subroutines {\sub invlega} and {\sub invlegd} contain the transformations from spectral to
fourier space for all varibles which are needed in the adiabatic and in the diabatic part of the
model, respectively. Subroutine {\sub fc2sp} does the transformation from fourier to spectral
space. The Subroutines {\sub dirlega} and {\sub dirlegd} contain the transformations from 
fourier to spectral  space for the tendencies computed in the adiabatic and in the diabatic part
of
the model, respectively. 
Subroutine {\sub uv2dv} transforms the fourier coefficients of the zonal and meridional wind
components to spectral coefficients of divergence and vorticity. 
\vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage

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

\begin{center}
\begin{tabular}{|p{14cm}|}
\hline
\vspace{-5mm} \section{mpimod.f90 and mpimod\underline{ }dummy.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 name starts with {\sub mp}. Subroutines from {\module mpimod.f90}  are
called
in {\module fluxmod.f90, icemod.f90, landmod.f90, miscmod.f90, oceanmod.f90,
oceanmod50.f90, outmod.f90, puma.f90, radmod.f90, rainmod.f90, seamod.f90,
surfmod.f90}
and {\module visumod.f90}. The module {\module mpimod\underline{ }dummy.f90} is used
instead of {\module mpimod.f90} for simulations on a single processor. {\module
mpimod\underline{ }dummy.f90} contains subroutines having the same name as the
corresponding routine in {\module mpimod.f90}. However, there is no interface to MPI
present
in these routines and most of them are dummies. \vspace{3mm} 
\\
\hline
\vspace{1mm} {\bf Input/Output} {\module mpimod.f90} and {\module mpimod\underline{
}dummy} 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
{\modu mpimod},  which uses the global common module {\modu pumamod} from
{\module pumamod.f90} and the MPI module {\modu mpi}. {\module mpimod\underline{
}dummy.f90} does not use any 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 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}
\end{tabular}
\end{center}

\newpage

\begin{center}
\begin{tabular}{|p{14cm}|}
\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\underline{ }info} && give information about setup \\
\end{tabular}
\end{center}

\vspace{3mm} \\

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

\begin{center}
\begin{tabular}{|p{14cm}|}
\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\underline{ }output} which is an unformatted file. {\file puma\underline{ }output} is 
designed to be  post processed by the AFTERBURNER program (see EDI) 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 puma.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 pumamod.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\underline{ }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{14cm}|}
\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. From {\module
puma.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
puma.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 puma.f90} does not use any extra input file  or
output file. A diagnostic print out is written on standard output. {\module puma.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 \\
&&&\\
KICK & Integer & Switch for initial white noise disturbance on surface pressure (0~=~none;
1~=~global; 2~=~hemispherically symmetric; 3~=~one wavenumber only) & 1 \\
NAFTER & Integer &Time interval for output [time steps] & 12 \\
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\\
NEXP & Integer & Experiment identifier & 0 \\
NEXPER & Integer & Switch for predefined experiments (not used) & 0 \\
NKITS & Integer & Number of initial explicit Euler time steps & 3 \\
NRESTART & Integer & Switch for restart (0~=~initial run;  1~=~normal restart;
2~=~restart plus update of surface climatology; 3~=~restart plus update of surface parameter
(see {\module landmod.f90})) & 0 \\
NRUN & Integer & Number of time steps to be run & 0 \\
NSTEP & Integer & Current time step (replaced by restart record) & 0 \\
\end{tabular}
\end{center}
\end{tabular}
\end{center}

\newpage 

\begin{center}
\begin{tabular}{|p{14cm}|}
\begin{center}
\begin{tabular}{l l p{5cm} c} %{p{3cm} p{2cm} p{6cm} p{2cm}}
Parameter & Type & Purpose & Default \\
&&&\\
NSTOP & Integer & Finishing time step & 0 (=~not active) \\
NTSPD & Integer & Number of time steps per day & 24 \\
NDAYS & Integer & Number of days to be run (overwrites NRUN if  $>$ 0) & 0 \\
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}
\end{tabular}
\end{center}

\newpage 

\begin{center}
\begin{tabular}{|p{14cm}|}
\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 \\
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 averaged sea level pressure [Pa] & 101325.00 \\
RESTIM(NLEV)  & Real Array & Time scale [d] for Newtonian cooling (usually not used)
& NLEV $\cdot$ 0.0 \\
\end{tabular}
\end{center}
\end{tabular}
\end{center}

\newpage 

\begin{center}
\begin{tabular}{|p{14cm}|}
\begin{center}
\begin{tabular}{l l p{5cm} c} %{p{3cm} p{2cm} p{6cm} p{2cm}}
Parameter & Type & Purpose & Default \\
&&&\\
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 fluxmod.f90} uses the FORTRAN-90
global common module {\modu pumamod} from
{\module pumamod.f90}. After starting MPI, the main program {\sub puma} 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 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 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 NRESTART~$>$~0, the restart
record
is 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. Finally, the global averaged surface
pressure is set according to PSURF 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{14cm}|}
\hline
\vspace{-5mm} \section{pumamod.f90} \vspace{-5mm} \\
\hline
\vspace{1mm} {\bf General} The module {\module pumamod.f90} contains all 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 file
or
output file. No namelist input is required \vspace{3mm} \\
\hline
\vspace{2mm} {\bf Structure} Internally, {\module pumamod.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{14cm}|}
\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 PUMA module {\module puma.f90} is given by the subroutines {\sub radini}, {\sub
radstep} and {\sub radstop} 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 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 OZONEFILE} 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}
\end{tabular}
\end{center}

\newpage 

\begin{center}
\begin{tabular}{|p{14cm}|}
\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 \\
OZONEFILE& Character & File for externally prescribed ozone distribution & ozone.dat \\
\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 pumamod.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 OZONEFILE}. 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{14cm}|}
\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 PUMA module {\module puma.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 \\
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 pumamod.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{14cm}|}
\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 PUMA 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 SSTFILE} (see namelist) and the file {\file
ocean$\_$parameter} or from the  restart file
{\file sea\underline{ }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 SSTFILE}
and formatted
EXTRA format with (4I10) for the header and (6(1X,E12.6)) for the fields  for {\file
ocean$\_$parameter}.
The file {\file SSTFILE} 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\underline{ }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\underline{ }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}
\end{tabular}
\end{center}

\newpage 

\begin{center}
\begin{tabular}{|p{14cm}|}
\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 \\
SSTFILE &  FILE & File with SST data & surface$\_$parameter \\
\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 pumamod.f90}. Subroutine {\sub seaini} reads the namelist and, if the parallel
version is used,  distributes the namelist parameters to the different processes. The coupling
interface routines in {\module intermod$\_$atm.f90} are initialized by calling {\sub cplinit}.
If
it is not a restart (i.e.~if NRESTART from {\nam inp} of {\module puma.f90} is 0), the files
{\file SSTFILE} 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. A call to {\sub cplexchange$\_$ice} from module {\module
intermod$\_$atm.f90} transfers the atmospheric coupling fluxes to the sea ice model and gets
the sea ice and ocean surface data back. After the call, additional surface parameter are
computed. Subroutine {\sub  seastop} finalizes the run and writes the restart records.
\vspace{3mm} \\
\hline
\end{tabular}
\end{center}
\newpage


\clearpage
\section{Files}