\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 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 printout : redirected \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 printout run.005 out pumaburn processes the files Namelist contains MULTI=4 Command: pumaburn printout exp0211 out pumaburn processes the files \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 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}