PlaSim/Puma_UG_17/ugrm.tex

\documentclass[12pt,twoside,a4paper]{book}
\usepackage[pdftex]{graphicx}
\usepackage[pdftex]{hyperref}
\usepackage{epsfig}
\usepackage{a4}
\usepackage[margin=2cm]{geometry}
\pagestyle{headings}

\usepackage{afterpage}
\usepackage{latexsym}
\usepackage{ulem}
\usepackage{natbib}

% macros

\def \ba{\begin{array}}
\def \ea{\end{array}}

\def \be{\begin{equation}}
\def \ee{\end{equation}}

\def \bd{\begin{displaymath}}
\def \ed{\end{displaymath}}

\def \bfl{\begin{flushleft}}
\def \efl{\end{flushleft}}

\def \beqa{\begin{eqnarray}}
\def \eeqa{\end{eqnarray}}

\def \di{\displaystyle}

\def \degrees{^\circ}

\newcommand{\pd}[2]{\frac{\partial #1}{\partial #2}}
\newcommand{\module}{\sf}
\newcommand{\sub}{\it}
\newcommand{\nam}{\it}
\newcommand{\file}{\bf}
\newcommand{\modir}{puma}

% end of macro definition

%------- [PUMA - constants]-------%
\def \dtep{$(\Delta T_R)_{\ÄP}\;$}
\def \dtepE{$(\Delta T_R)_{EP}\;$}
\def \dtns{$(\Delta T_R)_{NS}\;$}
\def \dtepk{$(\Delta T_R)_{\ÄP}$}
\def \dtepkE{$(\Delta T_R)_{EP}$}
\def \dtnsk{$(\Delta T_R)_{NS}$}
%---------------------------------%


\begin{document}

\begin{titlepage}
\begin{center}
\begin{figure}
\hspace{1cm}
\parbox{7cm}{
\includegraphics[width=7cm]{Pics/UHH_Logo_RGB}}
\hspace{0.5cm}
\parbox{7cm}{
\includegraphics[width=7cm]{Pics/KC-Logo_RGB}}
\end{figure}

\vspace*{1cm}
{\Huge\bf PUMA} \\
\vspace*{1cm}
\includegraphics[width=15cm]{Pics/guisnap} \\
\vspace*{1cm}
{\huge \bf User's Guide} \\
\vspace*{1cm}
{\huge \bf Version 17}
\vspace*{1cm}

 Frank Lunkeit -
 Edilbert Kirk       \\
 Klaus Fraedrich -
 Valerio Lucarini    \\
 Simon Blessing -
 Hartmut Borth       \\
 Torben Kunz -
 Alastair McDonald   \\
 Silke Schubert -
 Frank Sielmann      \\

\end{center}
\end{titlepage}

\begin{verbatim}
The PUMA User's Guide is a publication of the
Theoretical Meteorology at the Meteorological Institute of
the University of Hamburg.

Address:

Prof. Dr. Valerio Lucarini
Meteorological Institute
KlimaCampus
University of Hamburg
Grindelberg 5
D-20144 Hamburg
Germany

Contact:

Valerio.Lucarini@uni-hamburg.de.
Frank.Lunkeit@uni-hamburg.de
Edilbert.Kirk@uni-hamburg.de
\end{verbatim}


\bibliographystyle{plainnat}


\tableofcontents

\chapter{Installation}
\input{install.tex}

\chapter{Introduction}
\input{introduction.tex}

\nocite{KunzFraeLun09}
\nocite{Perez2005}
\nocite{Blessetal2008}
\nocite{fraelun2008}
\nocite{KunzFraeKirk2008}

\chapter{Horizontal Grid}
\input{grid.tex}
\chapter{Modules}
\input{modules.tex}

\chapter{Parallel Program Execution}
\input{parallel.tex}

\chapter{Graphical User Interface}
\input{gui.tex}

\chapter{Postprocessor Pumaburner}
\label{Pumaburner}
\input{pumaburn}

\chapter{Graphics}
%\section{\verb/GrADS/}
\section{GrADS}
\input{graphics_grads}
%\section{Vis5D}
%\input{graphics_vis5d}

\chapter{Model Dynamics}
\input{dynamics.tex}

\section{Scaling of Variables}
    The variables are rendered dimensionless using the following
     characteristic scales:

\begin{tabular}{|l|l|l|} \hline

Variable    & Scale  & Scale description          \\ \hline \hline
Divergence  & $\Omega$ & $\Omega$  = angular velocity \\ \hline
Vorticity   & $\Omega$ & $\Omega$  = angular velocity \\ \hline
Temperature & $(a^2 {\Omega}^2)/R$ & a = planet radius, R = gas constant \\ \hline
Pressure    & 101100 Pa & PSURF = mean sea level pressure \\ \hline
Orography   & $(a^2 {\Omega}^2)/g$ & g = gravity \\ \hline
\end{tabular}

\section{Vertical Discretization}

\begin{figure}[h]
\setlength{\unitlength}{1cm}
\begin{picture}(14,10)
\thicklines
\multiput(2 ,2)(0,1.5){5}{\line(1,0){8}}
\multiput(10.5,1.25)(0,1.5){5}{\makebox(2,1.5){$\zeta,D,T'$}}
\multiput(10.5,2.00)(0,1.5){4}{\makebox(2,1.5){$\dot{\sigma}$}}
\put(10.5,0.50){\makebox(2,1.5){$p = p_s , \dot{\sigma} = 0$}}
\put(10.5,8.00){\makebox(2,1.5){$p = 0 , \dot{\sigma} = 0$}}
\put(0,8.75){\makebox(1,1.5){$ Level $}}
\put(1,8.75){\makebox(1,1.5){$ \sigma $}}
\put(10.5,8.75){\makebox(2,1.5){$ Variables $}}
\thinlines
\multiput(2,1.25)(0,1.5){6}{\line(1,0){8}}
\put(1,0.50){\makebox(1,1.5){1.0}}
\put(1,1.25){\makebox(1,1.5){0.9}}
\put(1,2.00){\makebox(1,1.5){0.8}}
\put(1,2.75){\makebox(1,1.5){0.7}}
\put(1,3.50){\makebox(1,1.5){0.6}}
\put(1,4.25){\makebox(1,1.5){0.5}}
\put(1,5.00){\makebox(1,1.5){0.4}}
\put(1,5.75){\makebox(1,1.5){0.3}}
\put(1,6.50){\makebox(1,1.5){0.2}}
\put(1,7.25){\makebox(1,1.5){0.1}}
\put(1,8.00){\makebox(1,1.5){0.0}}

\put(0,0.50){\makebox(1,1.5){5.5}}
\put(0,1.25){\makebox(1,1.5){5  }}
\put(0,2.00){\makebox(1,1.5){4.5}}
\put(0,2.75){\makebox(1,1.5){4  }}
\put(0,3.50){\makebox(1,1.5){3.5}}
\put(0,4.25){\makebox(1,1.5){3  }}
\put(0,5.00){\makebox(1,1.5){2.5}}
\put(0,5.75){\makebox(1,1.5){2  }}
\put(0,6.50){\makebox(1,1.5){1.5}}
\put(0,7.25){\makebox(1,1.5){1  }}
\put(0,8.00){\makebox(1,1.5){0.5}}
\end{picture}
\caption{Vertical geometry of PUMA with associated variables (5 level version)}
\label{figlevel}
\end{figure}
    
The model is represented by finite differences in the vertical
as shown in figure \ref{figlevel}. The number of vertical levels 
is variable. The vertical coordinate is defined as $\sigma  = p/p_s$.
The prognostic variables $\zeta,D$, and $T'$ are calculated at full levels.
At the two outer half levels $\sigma = 0$ (upper boundary) and 
$\sigma = 1$ (lower boundary) the vertical velocity is set to zero. 
The vertical advection at level $r$ is approximated as follows:

\begin{equation}
\left( \overline{\dot{\sigma} \delta_{\sigma} Q_{\sigma}} \right)_r = 
\frac{1}{2} \left(
\dot{\sigma}_{r+\frac{1}{2}}
\frac{Q_{r+1}-Q_r}{\Delta \sigma}
+ \dot{\sigma}_{r-\frac{1}{2}}
\frac{Q_r - Q_{r-1}}{\Delta \sigma}
\right)
\end{equation}

The tendencies  of temperature, divergence and surface pressure
are solved by the implicit time step. The vorticity equation
is approximated by the centred differences in time \citep{hossim75}.
    
\section{PUMA Flow Diagram}

\begin{figure}[h]
\setlength{\unitlength}{1cm}
\begin{picture}(14,18)
\thicklines
\newsavebox{\srbox}
\savebox{\srbox}(0,0){
   \thicklines
   \put(0,-0.3){\oval(2.5,0.6)}}
\newsavebox{\cobox}
\savebox{\cobox}(0,0){
   \thinlines
   \put(0,-0.3){\fbox}}
\put(0,16){\usebox{\srbox}\makebox(0,0){puma}}
\put(8,15.9){\fbox{Main program}}
\put(1.25,16){\line(1,0){0.75}}
\put(2,16){\vector(0,-1){0.7}}
\put(2,15){\usebox{\srbox}\makebox(0,0){mpstart}}
\put(8,14.9){\fbox{Multi processing startup}}
\put(2,14.7){\vector(0,-1){0.4}}
\put(2,14){\usebox{\srbox}\makebox(0,0){prolog}}
\put(8,13.9){\fbox{Call initialization routines}}
\put(2,13.7){\vector(0,-1){0.4}}
\put(2,13){\usebox{\srbox}\makebox(0,0){master}}
\put(8,12.9){\fbox{Perform time loop for NRUN time steps}}
\put(3.25,13){\line(1,0){0.75}}
\put(4,13){\vector(0,-1){0.7}}
\put(4,12){\usebox{\srbox}\makebox(0,0){gridpoint}}
\put(8,11.9){\fbox{Call transformation and grid point routines}}
\put(5.25,12){\line(1,0){0.75}}
\put(6,12){\vector(0,-1){0.7}}
\put(6,11){\usebox{\srbox}\makebox(0,0){sp2fc}}
\put(8,10.9){\fbox{Inverse Legendre transformation}}
\put(6,10.7){\vector(0,-1){0.4}}
\put(6,10){\usebox{\srbox}\makebox(0,0){dv2uv}}
\put(8,9.9){\fbox{Divergence and vorticity to u,v - wind components}}
\put(6, 9.7){\vector(0,-1){0.4}}
\put(6, 9){\usebox{\srbox}\makebox(0,0){fc2gp}}
\put(8,8.9){\fbox{Fourier coefficients to grid points (Inverse FFT)}}
\put(6, 8.7){\vector(0,-1){0.4}}
\put(6, 8){\usebox{\srbox}\makebox(0,0){\bf calcgp}}
\put(8,7.9){\fbox{Calculations in grid point space}}
\put(6, 7.7){\vector(0,-1){0.4}}
\put(6, 7){\usebox{\srbox}\makebox(0,0){gp2fc}}
\put(8,6.9){\fbox{Grid point to Fourier coefficients (FFT)}}
\put(6, 6.7){\vector(0,-1){0.4}}
\put(6, 6){\usebox{\srbox}\makebox(0,0){mktend}}
\put(8,5.9){\fbox{Make tendencies for spectral domain}}
\put(6, 5.7){\vector(0,-1){0.4}}
\put(6, 5){\usebox{\srbox}\makebox(0,0){mpsumsc}}
\put(8,4.9){\fbox{MP sum and scatter}}
\put(4, 5){\line(1,0){0.75}}
\put(4, 5){\vector(0,-1){0.7}}
\put(4, 4){\usebox{\srbox}\makebox(0,0){outsp}}
\put(8,3.9){\fbox{Write prognostic fields to file (puma\_data)}}
\put(4, 3.7){\vector(0,-1){0.4}}
\put(4, 3){\usebox{\srbox}\makebox(0,0){diag}}
\put(8,2.9){\fbox{Write diagnostics to standard output}}
\put(4, 2.7){\vector(0,-1){0.4}}
\put(4, 2){\usebox{\srbox}\makebox(0,0){\bf spectral}}
\put(8,1.9){\fbox{Perform spectral calculations and time stepping}}
\put(2, 2){\line(1,0){0.75}}
\put(2, 2){\line(0,1){10}}
\put(2,  7){\makebox(0,0){time \hspace{2mm} loop}}
\put(2, 12){\vector(1,0){0.75}}
\put(4, 1.7){\line(0,-1){0.7}}
\put(4, 1){\vector(-1,0){0.75}}
\put(2, 1){\usebox{\srbox}\makebox(0,0){epilog}}
\put(8,0.9){\fbox{Write restart file (puma\_status)}}
\put(2, 0.7){\vector(0,-1){0.4}}
\put(2, 0){\usebox{\srbox}\makebox(0,0){mpstop}}
\put(8,-0.1){\fbox{MP terminate (end all processes)}}
\end{picture}
\caption{Flow diagram of main routines}
\label{figflow}
\end{figure}


The diagram \ref{figflow} shows the route through the main program
PUMA, with the names of the most important subroutines.
    
    PUMA is the main program. It calls the three subroutines {\sub Prolog},
    {\sub Master}  and {\sub Epilog} .
    {\sub Prolog}  does all initialization. It calls the following subroutines:
    {\sub gauaw} computes gaussian abscissas and weights.
    {\sub inilat} initializes some utility arrays like square of cosine of latitude etc.
    {\sub legpri} prints the arrays of {\sub gauaw} and {\sub inilat}.
    {\sub readnl} reads the namelist from standard input.
    {\sub initpm} initializes most vertical arrays and some in the spectral domain.
    {\sub initsi} computes arrays for the semi-implicit scheme.
    {\sub legini} computes all polynomials needed for the Legendre transformation.
    {\sub restart} starts the model from the restart file, if selected of a previous run.
    {\sub initfd} initializes spectral arrays.
    {\sub setzt} sets up the restoration temperature array.
    {\sub noise} puts a selectable form of noise into $lnPs$.
    {\sub setztex} is a special version of setzt for dipole experiments.
    
    {\sub Master} does some initial timesteps on initial runs, then it runs the 
    time loop for the  selected integration time. It calls the following subroutines:
    {\sub makebm} constructs the array bm, {\sub gridpoint} does all transformations 
    and calculations in the grid point domain. {\sub sp2fc} converts spectral to 
    Fourier coefficients (inverse Legendre transf.), {\sub dv2uv} divergence and 
    vorticity to u and v (implies spectral to Fourier), {\sub fc2gp} Fourier 
    coefficients to grid points (fast Fourier transformation), {\sub calcgp} 
    calculations in grid point space, {\sub gp2fc} grid points to Fourier coefficients 
    (fast Fourier transformation), {\sub fc2sp} Fourier coefficients to spectral 
    (direct Legendre transf.), {\sub mktend} makes tendencies (implies Fourier to spectral),
    {\sub spectral} does all calculations in the spectral domain, {\sub outsp} 
    writes spectral fields in physical dimensions on an output file, and
    {\sub diag} writes selected fields and parameters to the standard output.
    {\sub Epilog} writes the restart file.
    
    
\section{Initialization}
    
    The model starts either from a restart file or with the atmosphere
     at rest. The defaults make the initial state a motionless, stable
     stratified atmosphere. For an initial start the divergence and
     the relative vorticity are set to zero (only mode(1,0) of vorticity
     is set to the planetary vorticity). The temperature is initialized
     as a constant horizontal field. The vertical distribution is
     adopted from the restoration temperature, usually a stable stratification.
     The initialization of the logarithm of the surface pressure
     is controlled by the namelist variable \textbf{kick}:
     \textbf{kick}=0 sets all modes to zero, so the model runs with constant 
     zones without eddies, \textbf{kick}=1 generates random white noise and
     \textbf{kick}=2 generates random white noise that is symmetrical about the equator.
     Runs started with \textbf{kick}=1 or 2 are irreproducible due to the randomization.
     For reproducible runs with eddies use \textbf{kick}=3 which only initializes mode(1,2)
     of $lnPs$ with a small constant.
     The amplitude of the noise perturbation is normalized to 0.1 hPa
     (1.e-4 of the mean surface pressure).
    
     A radiative equilibrium temperature field for the run is set
     up by {\sub setzt}: First, a global mean radiative equilibrium
     temperature profile $T_R(\sigma)$ is defined.
     A hyperbolic function of height is used to provide
     $T_R(\sigma)$, as illustrated in Figure \ref{Tr_z}.
     With $z \rightarrow{} - \infty$ the profile tends to a uniform lapse rate,
     \textbf{alr}, passing through the temperature \textbf{tgr} at \textit{z} = 0.
     With $z \rightarrow{} + \infty$ the profile becomes isothermal. The transition
     takes place at the height \textbf{ztrop}. The sharpness of the tropopause
     is controlled by the parameter \textbf{dttrp}.
     When \textbf{dttrp} = 0,the lapse rate changes discontinuously at \textbf{ztrop}.
     For \textbf{dttrp} small but positive, the transition is spread. The hydrostatic
     relation is used to determine the heights and hence the temperatures
     of the model levels. 
    
\section{Computations in spectral domain}
     The subroutine{\sub spectral} performs one timestep. Details of the time 
     stepping scheme are 
     given in \citep{hossim75}. The adiabatic tendencies
     (advection, etc.) are used. The normal time step is centered in
     time, and includes a Robert time filter to control time splitting.
     For the first \textbf{nkits} time steps, short initial time steps, an initial 
     forward timestep
     followed by a centred step, each twice its predecessor, are taken
     in order to initiate a run from data at only one time level.
     No Robert filter is included in the short steps. The subroutine
     calculates the spectral tendencies due to Newtonian cooling, Rayleigh
     friction and hyperdiffusion:
    
\chapter{Preprocessor}
\input{preprocessor.tex}

\chapter{Benchmark}
\input{benchmark.tex}

\bibliography{ref}
\begin{appendix}
\chapter{List of Constants and Symbols}
\input{symb}
\chapter{PUMA Codes for Variables}
\label{Pumacodes}
\input{puma_codes}
\chapter{Namelist}
\label{Namelist}
\input{namelist}
\end{appendix}

\end{document}