Revision 7992cfe14ca4d212808eaebe9717ee11eee3ec4d authored by Adiv Paradise on 27 June 2019, 20:16:47 UTC, committed by Adiv Paradise on 27 June 2019, 20:16:47 UTC
1 parent 134ef1d
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}
![swh spinner](/static/img/swh-spinner.gif)
Computing file changes ...