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}