PlaSim/Plasim_UG_16/pumaburn.tex

\section{Introduction}

The {\bf Pumaburner} is a postprocessor for the {\bf Planet Simulator}
and the {\bf PUMA} model family.
It's the only interface between {\it raw} model data output
and diagnostics, graphics, and user software.

The output data of the {\bf Planet Simulator} are stored as
packed binary (16 bit) values using the model representation.
Prognostic variables like temperature, divergence, vorticity,
pressure, and humidity are stored as coefficients of spherical harmonics
on $\sigma$ levels. Variables like radiation,
precipitation, evaporation, clouds, and other fields of the
parameterization package are stored on Gaussian grids.

The tasks of the {\bf Pumaburner} are:
\begin{itemize}
\item Unpack the {\it raw} data to full real representation.
\item Transform variables from the model's representation
      to a user selectable format, e.g. grids,
      zonal mean cross sections, fourier coefficients.
\item Calculate diagnostic variables, like vertical velocity,
      geopotential height, wind components, etc.
\item Transfrom variables from $\sigma$ levels to user
      selectable pressure levels.
\item Compute monthly means and standard deviations.
\item Write selected data either in SERVICE, GRIB, or NetCDF format
      for further processing.
\end{itemize}

\section{Usage}

\begin{verbatim}
pumaburn4 [options] InputFile OutputFile <namelist >printout
     option -h : help (this output)
     option -c : print available codes and names
     option -d : debug mode (verbose output)
     option -g : Grib   output (override namelist option)
     option -n : NetCDF output (override namelist option)
     option -m : Mean=1 output (override namelist option)
     InputFile : Planet Simulator or PUMA data file
    OutputFile : GRIB, SERVICE, or NetCDF format file
      namelist : redirected <stdin>
      printout : redirected <stdout>
\end{verbatim}

\section{Namelist}

The namelist values control the selection, coordinate system
and output format of the postprocessed variables.
Names and values are not case sensitive.
You can assign values to the following names: \vspace{0.4cm}

\begin{tabular}{|l|c|l|l|l|}
\hline
Name   & Def. & Type & Description & Example \\
\hline
{\bf HTYPE  }& S & char & Horizontal type               & HTYPE=G \\
{\bf VTYPE  }& S & char & Vertical type                 & VTYPE=P \\
{\bf MODLEV }& 0 & int  & Model levels                  & MODLEV=2,3,4 \\
{\bf hPa    }& 0 & real & Pressure levels               & hPa=500,1000 \\
{\bf CODE   }& 0 & int  & ECMWF field code              & CODE=130,152 \\
{\bf GRIB   }& 0 & int  & GRIB output selector          & GRIB=1 \\
{\bf NETCDF }& 0 & int  & NetCDF output selector        & NETCDF=1 \\
{\bf MEAN   }& 1 & int  & Compute monthly means         & MEAN=0 \\
{\bf HHMM   }& 1 & int  & Time format in Service format & HHMM=0 \\
{\bf HEAD7  }& 0 & int  & User parameter                & HEAD7=0815 \\
{\bf MARS   }& 0 & int  & Use constants for planet Mars & MARS=1 \\
{\bf MULTI  }& 0 & int  & Process multiple input files  & MULTI=12 \\
\hline
\end{tabular}

\section{HTYPE}

{\bf HTYPE} accepts the first character of the following string.
Following settings are equivalent: HTYPE = S, HTYPE=Spherical Harmonics
HTYPE = Something. Blanks and the equal-sign are optional. \\
Possible Values are:

\begin{tabular}{|l|l|l|}
\hline
   Setting   & Description          & Dimension for T21 resolution   \\
\hline
   HTYPE = S & Spherical Harmonics  & (506):(22 * 23 coefficients)   \\
   HTYPE = F & Fourier Coefficients & (32,42):(latitudes,wavenumber) \\
   HTYPE = Z & Zonal Means          & (32,levels):(latitudes,levels) \\
   HTYPE = G & Gauss Grid           & (64,32):(longitudes,latitudes) \\
\hline
\end{tabular}

\section{VTYPE}

{\bf VTYPE} accepts the first character of the following string.
Following settings are equivalent: VTYPE = S, VTYPE=Sigma
VTYPE = Super. Blanks and the equal-sign are optional. \\
Possible Values are:

\begin{tabular}{|l|l|l|}
\hline
   Setting   & Description          & Remark \\
\hline
   VTYPE = S & Sigma (model) levels & Some derived variables are not available \\
   VTYPE = P & Pressure levels      & Interpolation to pressure levels \\
\hline
\end{tabular}

\section{MODLEV}

{\bf MODLEV} is used in combination with {\bf VTYPE = S}.
If VTYPE is not set to Sigma, the contents of MODLEV are ignored.
MODLEV is an integer array that can get as many values as there are
levels in the model output. The levels are numbered from top of
the atmosphere to the bottom. The number of levels and the 
corresponding sigma values are listed in the pumaburner printout.
The outputfile orders the level according to the MODLEV values.
MODLEV=1,2,3,4,5 produces an output file of five model levels
sorted from top to bottom, while MODLEV=5,4,3,2,1 sorts them
from bottom to top.

\section{hPa}

{\bf hPa} is used in combination with {\bf VTYPE = P}.
If VTYPE is not set to Pressure, the contents of hPa are ignored.
hPa is a real array that accepts pressure values with the
units hectoPascal or millibar. All output variables will be
interpolated to the selected pressure levels.
There is no extrapolation on the top of the atmosphere.
For pressure values, that are lower than that of the model's
top level, the top level value of the variable is taken.
The variables temperature and geopotential height are extrapolated
if the selected pressure is higher than the surface pressure.
All other variables are set to the value of the lowest mode level
for this case. The outputfile contains the levels in the same order
as set in hPa. Example: hpa = 100,300,500,700,850,900,1000.

\section{MEAN}

{\bf MEAN} can be used to compute montly means and/or deviations.
The Pumaburner reads date and time information from the model file
and handles different lengths of months and output intervals correctly.

\begin{tabular}{|l|p{12cm}|}
\hline
Setting & Description \\
\hline
        MEAN  =  0 & Do no averaging - all terms are processed. \\

        MEAN  =  1 & Compute and write monthly mean fields.
                     Not for spherical harmonics, Fourier coefficients or
                     zonal means on sigma levels. \\

        MEAN  =  2 & Compute and write monthly deviations.
                     Not for spherical harmonics, Fourier coefficients or
                     zonal means on sigma levels.
                     Deviations are not available for NetCDF output. \\

        MEAN  =  3 & Combination of MEAN=1 and MEAN=2.
                     Each mean field is followed by a deviation
                     field with an identical header record.
                     Not for spherical harmonics, Fourier coefficients or
                     zonal means on sigma levels. \\
\hline
\end{tabular}

\section{Format of output data}

The {\bf pumaburner} supports three different output formats:

\begin{itemize}
\item {\bf GRIB} (GRIdded Binary) WMO standard for gridded data.
\item {\bf NetCDF} (Network Common Data Format)
\item {\bf Service} Format for user readable data (see below).
\end{itemize}

For more detailed descriptions see for example:

{\url{http://www.nws.noaa.gov/om/ord/iob/NOAAPORT/resources/}}

\begin{tabular}{|l|l|p{10cm}|}
\hline
Setting & Description \\
\hline
   GRIB = 1 & NetCDF = 0 & The output file is written GRIB format.
                     This option can be used only for
                     HTYPE=Spherical Harmonics or HTYPE=Gauss Grid. \\
   GRIB = 0 & NetCDF = 1 & The output file is written in NetCDF format.
                     This option can be used for HTYPE=Gauss Grid only. \\
   GRIB = 0 & NetCDF = 0 & The output file is written in Service format.
                     This is the preferred format for user programs.
                     For a detailed description see the following section. \\
   GRIB = 1 & NetCDF = 1 & Illegal combination. \\
\hline
\end{tabular}

\section{SERVICE format}

     The SERVICE format uses the following structure:
     The whole file consists of pairs of
     header records and data records.
     The header record is an integer array of 8 elements.

\begin{verbatim}
     head(1) = ECMWF field code
     head(2) = modellevel or pressure in [Pa]
     head(3) = date  [yymmdd]  (yymm00 for monthly means)
     head(4) = time  [hhmm]  or [hh] for HHMM=0
     head(5) = 1. dimension of data array
     head(6) = 2. dimension of data array
     head(7) = may be set with the parameter HEAD7
     head(8) = experiment number (extracted from filename)

     Example for reading the SERVICE format (GRIB=0 , NETCDF=0)

     INTEGER HEAD(8)
     REAL    FIELD(64,32)     ! dimensions for T21 grids
     READ (10,ERR=888,END=999) HEAD
     READ (10,ERR=888,END=999) FIELD
     ....
 888 STOP 'I/O ERR'
 999 STOP 'EOF'
     ....
\end{verbatim}

\section{HHMM}

\begin{tabular}{|l|p{12cm}|}
\hline
Setting & Description \\
\hline
  HHMM  =  0 & head(4) shows the time in hours (HH). \\
  HHMM  =  1 & head(4) shows the time in hours and minutes (HHMM). \\
\hline
\end{tabular}

\section{HEAD7}
The 7th. element of the header is reserved for the user.
It may be used for experiment numbers, flags or anything else.
Setting HEAD7 to a number exports this number to every header record
in the output file (SERVICE format only).

\section{MARS}
This parameter is used for processing simulations of the Mars atmosphere.
Setting MARS=1 switches gravity, gas constant and planet radius
to the correct values for the planet Mars.

\section{MULTI}
The parameter MULTI can bes used to process a series of input data
within one run of the pumaburner. Setting MULTI to a number (n)
tells the pumaburner to procees (n) input files.
The input files must follow one of the following two rules:
\begin{itemize}
\item YYMM rule: The last four characters of the filename 
                 contain the data in the form YYMM.
\item .NNN rule: The last four characters of the filename
                 consist of a dot followed ny a 3-digit sequence number.
\end{itemize}

\begin{verbatim}
Examples:

Namelist contains MULTI=3
Command: pumaburn <namelist >printout run.005 out
pumaburn processes the files <run.005> <run.006> <run.007>

Namelist contains MULTI=4
Command: pumaburn <namelist >printout exp0211 out
pumaburn processes the files <exp0211> <exp0212> <exp0301> <exp0302>
\end{verbatim}

\section{Namelist example}
\begin{verbatim}
       VTYPE  = Pressure
       HTYPE  = Grid
       CODE   = 130,131,132
       hPa    = 200,500,700,850,1000
       MEAN   = 0
       GRIB   = 0
       NETCDF = 0
\end{verbatim}

    This namelist will write Temperature(130), u(130) and v(131)
    on pressure levels 200hPa, 500hPa, 700hPa, 850hPa and 1000hPa.
    The output interval is the same as found on the model data,
    e.g. every 12 or every 6 hours (MEAN=0). The output format
    is SERVICE format.

\section{Troubleshooting}
If the pumaburner reports an error or doesn't produce 
the expected results, try the following:

\begin{itemize}

\item Check your namelist, especially for invalid codes, types and levels.

\item Run the pumaburner in debug-mode by using the option -d.
Example:
\begin{verbatim}
pumaburn <namelist >printout -d data.in data.out
\end{verbatim}

This will print out some details like parameters and memory allocation
during the run. The additional information may help to detect
the problem.

\item Not all combinations of HTYPE, VTYPE, and CODE are valid.
Try to use HTYPE=Grid and VTYPE=Pressure before switching to
exotic parameter combinations.

\end{itemize}