This is the technical documentation of the PUMA model. In the following, the purpose of each module is given and its general structure and possible input and output parameters provided (namelist, files) are explained. %-------------------------------------------------------------------------------- \begin{center} \begin{tabular}{|p{15cm}|} \hline \vspace{-5mm} \section{fftmod.f90 / fft991mod.f90} \vspace{-5mm} \\ \hline \vspace{1mm} {\bf General} The module {\module fftmod.f90} contains all subroutines necessary to perform the fast fourier transformation and its inverse. The interface to the main PUMA module {\module puma.f90} is given by the subroutines {\sub gp2fc} and {\sub fc2gp} which are called in {\module puma.f90} from the subroutine {\sub gridpoint}. \vspace{3mm} \\ \hline \vspace{1mm} {\bf Input/Output} {\module fftmod.f90} does not use any additional input or output files. No namelist input is required. \vspace{3mm} \\ \hline \vspace{2mm} {\bf Structure} Internally, {\module fftmod.f90} uses the FORTRAN-90 module {\module fftmod}, which uses no other modules. Subroutine {\sub gp2fc} performs the transformation from gridpoint space into fourier space while the subroutine {\sub fc2gp} does the transformation from fourier space into grid point space. Both routines use several subroutines to do the direct or indirect transformation for different factors. When {\sub gp2fc} or {\sub fc2gp} is called for the first time, {\sub fftini} is called to initialize the FFT. \vspace{3mm} \\ \hline \vspace{2mm} Alternatively, the module {\module fft991mod.f90} may be used instead of {\module fftmod.f90}. While {\module fftmod.f90} runs faster, {\module fft991mod.f90} can be used for resolutions that are not supported by {\module fftmod.f90}, e.g. T63 or T106. To select the appropriate module edit the file "Most15/puma/src/make\_puma". Use either: \begin{verbatim} FFTMOD=fftmod \end{verbatim} or \begin{verbatim} FFTMOD=fft991mod \end{verbatim} \vspace{3mm} \\ \hline \end{tabular} \end{center} \newpage %--------------------------------------------------------------------------------------------- \begin{center} \begin{tabular}{|p{15cm}|} \hline \vspace{-5mm} \section{guimod.f90 / guimod\_stub.f90} \vspace{-5mm} \\ \hline \vspace{1mm} {\bf General} The module {\module guimod.f90} contains subroutines for communication with the GUI. On operating systems that do not support the Xlib library (X11R6) e.g. Windows, {\module guimod\_stub.f90} may be used as a stub replacement. \vspace{3mm} \\ \hline \vspace{2mm} {\bf Structure} The following subroutines are included in {\module guimod.f90}: \begin{center} \begin{tabular}{l p{2cm} l} Subroutine & &Purpose \\ && \\ {\sub guistart} && initialize the GUI \\ {\sub guistop} && finalize the GUI \\ {\sub guistep\_puma} && called every timestep from PUMA \\ {\sub guistep\_plasim} && called every timestep from PLASIM \\ {\sub guips} && gather, scale, and send surface pressure to the GUI \\ {\sub guihor} && gather, scale, and send a gridpoint array to the GUI \\ {\sub guigv} && gather, scale, and send wind components to the GUI \\ {\sub change\_disp} && called for user input into the GUI \\ {\sub change\_dtep} && called for user input into the GUI \\ {\sub change\_dtns} && called for user input into the GUI \\ {\sub change\_co2} && called for user input into the GUI \\ {\sub change\_gsol0} && called for user input into the GUI \\ {\sub change\_dawn} && called for user input into the GUI \\ \end{tabular} \end{center} \vspace{3mm} \\ \hline \end{tabular} \end{center} \newpage %--------------------------------------------------------------------------------------------- \begin{center} \begin{tabular}{|p{14cm}|} \hline \vspace{-5mm} \section{legsym.f90} \vspace{-5mm} \\ \hline \vspace{1mm} {\bf General} The module {\module legsym.f90} contains all the subroutines necessary to perform the Legendre transformation and its inverse. The module legsym is written for arrays in alternate representation, which use pairs of Northern and Southern latitudes. This symmetry conserving scheme is different to the Legendre modules used in PLASIM or the preprocessor. The interface to the main PUMA module {\module puma.f90} is given by the subroutines {\sub legini}, {\sub inigau}, {\sub fc2sp}, {\sub fc3sp}, and {\sub sp2gp} which are called in {\module puma.f90} from the subroutines {\sub prolog} and {\sub gridpoint}. \vspace{3mm} \\ \hline \vspace{1mm} {\bf Input/Output} {\module legsym.f90} does not use any other input or output files. No namelist input is required. \vspace{3mm} \\ \hline \vspace{1mm} The following subroutines are included in {\module legsym.f90}: \begin{center} \begin{tabular}{l p{2cm} l} Subroutine & &Purpose \\ && \\ {\sub inigau} && compute Gaussian abscissae and weights \\ {\sub legini} && compute Legendre polynomials \\ {\sub fc2sp} && Fourier to Spectral transformation \\ {\sub fc2spdmu} && Fourier to Spectral transformation with d/dmu \\ {\sub sp2fc} && Spectral to Fourier transformation \\ {\sub sp3fc} && simultaneous transformation of T, Div., and Vort. \\ {\sub mktend} && compute and transform tendencies \\ {\sub reg2alt} && convert regular array to alternate array \\ {\sub alt2reg} && convert alternate array to regular array \\ \end{tabular} \end{center} \vspace{3mm} \\ \hline \end{tabular} \end{center} \newpage %-------------------------------------------------------------------------------- \begin{center} \begin{tabular}{|p{15cm}|} \hline \vspace{-5mm} \section{mpimod.f90 / mpimod\_stub.f90} \vspace{-5mm} \\ \hline \vspace{1mm} {\bf General} The module {\module mpimod.f90} contains the interface subroutines of the MPI ({\bf M}essage {\bf P}assing {\bf I}nterface) needed for (massive) parallel computing. Several MPI routines are called from the module. The interface to the other modules is provided by numerous subroutines with names which begin with {\sub mp}. Subroutines in {\module mpimod.f90} are called from several other modules. There are no direct calls to the MPI other than from within {\module mpimod.f90}. This encapsulation makes it possible to use {\module mpimod\_stub.f90} for single CPU runs without changing any other part of the model code. The selection is done automatically when using MoSt, or can be done manually by editing "Most16/puma/src/make\_puma". \vspace{3mm} \\ \hline \vspace{1mm} {\bf Input/Output} {\module mpimod.f90} and {\module mpimod\underline{ }stub} do not use any extra input or output files. No namelist input is required. \vspace{3mm} \\ \hline \vspace{2mm} {\bf Structure} Internally, {\module mpimod.f90} uses the FORTRAN-90 module {\module mpimod}, which in turn uses the global common module {\module pumamod} from {\module pumamod.f90} and the MPI module {\module mpi}. {\module mpimod\underline{ }stub.f90} does not use any other module. The following subroutines are included in {\module mpimod.f90}: \begin{center} \begin{tabular}{l p{2cm} l} Subroutine & &Purpose \\ && \\ {\sub mpbci} && broadcast 1 integer \\ {\sub mpbcin} & &broadcast n integers \\ {\sub mpbcr} & &broadcast 1 real \\ {\sub mpbcrn} & &broadcast n reals \\ {\sub mpbcl} && broadcast 1 logical \\ {\sub mpscin} & &scatter n integers \\ {\sub mpscrn} && scatter n reals \\ {\sub mpscgp} && scatter grid point field \\ {\sub mpgagp} && gather grid point field \\ {\sub mpgallgp} && gather grid point field to all \\ {\sub mpscsp} & &scatter spectral field \\ {\sub mpgasp} && gather spectral field \\ {\sub mpgacs} && gather cross section \\ {\sub mpgallsp} && gather spectral field to all \\ {\sub mpsum} && sum spectral field \\ {\sub mpsumsc} && sum and scatter spectral field \\ {\sub mpsumr} && sum n reals \\ {\sub mpsumbcr}& & sum and broadcast n reals \\ {\sub mpstart} & &initialize MPI \\ {\sub mpstop} & &terminate MPI \\ \end{tabular} \end{center} \vspace{3mm} \\ \hline \end{tabular} \end{center} \newpage \begin{center} \begin{tabular}{|p{15cm}|} \hline \begin{center} \begin{tabular}{l p{2cm} l} Subroutine & &Purpose \\ && \\ {\sub mpreadgp}& & read and scatter grid point field \\ {\sub mpwritegp}& & gather and write grid point field \\ {\sub mpwritegph} && gather and write (with header) grid point field \\ {\sub mpreadsp} & &read and scatter spectral field \\ {\sub mpwritesp} &&gather and write spectral field \\ {\sub mpi\_info} && report information about setup \\ {\sub mpgetsp} && read spectral array from restart file \\ {\sub mpgetgp} && read gridpoint array from restart file \\ {\sub mpputsp} && write spectral array to restart file \\ {\sub mpputgp} && write gridpoint array to restart file \\ {\sub mpmaxval} && compute maximum value of an array \\ {\sub mpsumval} && compute sum of all array elements \\ \end{tabular} \end{center} \vspace{3mm} \\ \hline \end{tabular} \end{center} \newpage %-------------------------------------------------------------------------------- \begin{center} \begin{tabular}{|p{15cm}|} \hline \vspace{-5mm} \section{puma.f90} \vspace{-5mm} \\ \hline \vspace{1mm} {\bf General} The module {\module puma.f90} is the main module of the model. It includes the main program {\sub puma} and controls the run. The interface routines to all other modules are called from {\module puma.f90}. The output is performed by calling the subroutine to {\module outsp}, and the adiabatic tendencies and the horizontal diffusion are also computed in {\module puma.f90}. To do the necessary transformations, calls to the modules {\module fftmod.f90} and {\module legsym.f90} are used. \vspace{3mm} \\ \hline \vspace{1mm} {\bf Input/Output} {\module puma.f90} A diagnostic printout is written to the standard output (usually redirected with the operator "$>$" to a file). {\module puma.f90} is controlled by the namelist {\nam inp} which is part of the namelist file {\file puma$\_$namelist}. For a complete list of namelist variables see Appendix C. Here is a table of the most important ones: \vspace{1mm} \begin{center} \begin{tabular}{l l p{6cm} c} Parameter & Type & Purpose & Default \\ &&&\\ MPSTEP & Integer & MPSTEP (Minutes Per STEP) defines the length of the time step. Recommended values are 60 min. for T21 and 20 min for T42. The values are not checked so take care not to violate the CFL (Courant-Friedrichs-Levy) criterion! & 60 \\ NYEARS & Integer & Number of years to be run & 1 \\ NMONTHS & Integer & Number of months to be run : NYEARS and NMONTHS may be used together. The simulation length in days is: NYEARS * 360 + NMONTHS * 30. & 0 \\ NOUTPUT & Integer & NOUTPUT is a global switch for enabling (1) or disabling (0) writing to {\bf puma\_output}. & 1 \\ NWPD & Integer & NWPD (Number of Writes Per Day) defines the output interval for writing model arrays to the file {\bf puma\_output}. Possible values range from 1 (daily output) to 24 (hourly). & 1 \\ NDIAG & Integer & NDIAG sets the interval (in time steps) for printing out some diagnostic arrays and values to the standard output. & 12 \\ \end{tabular} \end{center} \vspace{3mm} \\ \hline \end{tabular} \end{center} \newpage \begin{center} \begin{tabular}{|p{15cm}|} \hline \begin{center} \begin{tabular}{l l p{5cm} c} %{p{3cm} p{2cm} p{6cm} p{2cm}} Parameter & Type & Purpose & Default \\ &&&\\ NDL(NLEV) & Integer Array & Switch for diagnostic print out of a level (0~=~off; 1~=~on) & NLEV $\cdot$ 0 \\ DTEP & Real & Equator to pole temperature difference [K] for Newtonian cooling & 60.0 \\ DTNS & Real & North to South pole temperature difference [K] for Newtonian cooling & 0.0 \\ DTROP & Real & Tropopause height [m] for Newtonian cooling & 12000.0 \\ DTTRP & Real & Smoothing of the tropopause [K] for Newtonian cooling & 2 \\ TGR & Real & Surface temperature [K] for Newtonian cooling & 288 \\ TDISS & Real & Time scale [d] for the horizontal diffusion & 0.25 \\ PSURF & Real & Global mean sea level pressure [Pa] & 101100.00 \\ RESTIM(NLEV) & Real Array & Time scale [d] for Newtonian cooling & 0.0 \\ T0K(NLEV) & Real Array & Reference temperature used in the discretization scheme & 250.0 \\ TFRC(NLEV) & Real Array & Time scale [d] for Rayleigh friction (0.0~=~off)& 0.0 \end{tabular} \end{center} \vspace{3mm} \\ \hline \vspace{2mm} {\bf Structure} After starting MPI, the main program {\sub puma} calls {\sub prolog} to initialize the model. Then {\sub master} is called to do the time stepping. Finally, subroutine {\sub epilog} terminates the run. In subroutine {\sub prolog} calls to different subroutines, which are part of {\module puma.f90} or are provided by other modules, initialize various parts of the model: {\sub gauaw} and {\sub inilat} build the grid, {\sub readnl} reads the namelist file and sets parameters using the namelist input, {\sub initpm} and {\sub initsi} initialize parameters for the physics and the semi implicit scheme respectively, and {\sub outini} starts the output. The program then checks for the existence of a file named "puma\_restart". If the file can be opened then the restart record is read by {\sub restart}, otherwise {\sub initfd} sets the prognostic variables to their initial values. Finally, the global averaged surface pressure is set using PSURF and the orography. The subroutine {\sub master} controls the time stepping. First, if it is not a restart, the initial NKITS explicit forward time steps are performed. The main loop is defined by calling {\sub gridpoint} to set the nonlinear tendencies, and {\sub spectral} to add the linear tendencies. The run is finalized by subroutine {\sub epilog} which writes the restart records and terminates the MPI. \vspace{3mm} \\ \hline \end{tabular} \end{center} \newpage %--------------------------------------------------------------------------------------- \begin{center} \begin{tabular}{|p{15cm}|} \hline \vspace{-5mm} \section{pumamod.f90} \vspace{-5mm} \\ \hline \vspace{1mm} {\bf General} The module {\module pumamod.f90} contains all the parameters and variables which may be used to share information between {\module puma.f90} and other modules. No subroutines or programs are included. \vspace{3mm} \\ \hline \vspace{1mm} {\bf Input/Output} {\module pumamod.f90} does not use any extra input or output files. No namelist input is required. \vspace{3mm} \\ \hline \vspace{2mm} {\bf Structure} Internally, {\module pumamod.f90} is a FORTRAN-90 module named {\module pumamod}. Names for global parameters, scalars and arrays are declared and, if possible, values are preset.\vspace{3mm} \\ \hline \end{tabular} \end{center} \newpage %--------------------------------------------------------------------------------------------- \begin{center} \begin{tabular}{|p{15cm}|} \hline \vspace{-5mm} \section{restartmod.f90} \vspace{-5mm} \\ \hline \vspace{1mm} {\bf General} The module {\module restartmod.f90} contains routines for opening, reading and writing the restart files. The scalars and arrays of the restart files are identified by name. This enables adding or removing variables from the restart files without loosing compatibility. There is also no dependence on the sequence of variables. In parallel runs these routines are either called from the root process, which takes care of broadcasting, or from subroutines in {\module mpimod.f90} which gather before writing, or scatter after reading, the arrays. \vspace{3mm} \\ \hline \vspace{2mm} {\bf Structure} \begin{center} \begin{tabular}{l p{2cm} l} Subroutine & &Purpose \\ && \\ {\sub restart\_ini} && Scan restart file and store pointer \\ {\sub restart\_prepare} && Open file for restart ouput \\ {\sub restart\_stop} && Close files \\ {\sub get\_restart\_integer} && Read integer scalar \\ {\sub get\_restart\_array} && Read real array \\ {\sub put\_restart\_integer} && Write integer scalar \\ {\sub put\_restart\_array} && Write real array \\ {\sub fileseek} && position filepointer to requested variable \\ {\sub check\_equality} && May be used as debug tool \\ \end{tabular} \end{center} \vspace{3mm} \\ \hline \end{tabular} \end{center} \newpage %---------------------------------------------------------------------------------------------