external/io_grib1/README.io_grib1

   1 io_grib1
   2
   3 Author: Todd Hutchinson
   4         WSI
   5         thutchinson@wsi.com
   6
   7 5 August 2004
   8 8 February 2005 - Updated by Todd Hutchinson.  Section V was updated to
   9                   clarify the description of the decimal scale factor field
  10                   in the gribmap file.
  11 12 July 2005    - Updated by Todd Hutchinson.  GRIB version 1 input capability
  12                   was added to WRF. All sections in this README were updated to
  13                   add information relevant for grib input capability.
  14
  15
  16 I. Introduction
  17
  18 io_grib1 is a WRF module that allows for input and output of WRF data in GRIB
  19    version 1 format.
  20
  21 Why would anyone use GRIB output?
  22   GRIB stores data in a compressed format so output files are much smaller
  23     than in other formats such as netCDF.  In addition, encoding in GRIB format
  24     is very efficient and can be faster than writing out netCDF formatted
  25     data, especially for large grids.  (See Section V for more on performance).
  26
  27 II. Running WRF
  28   1. Set namelist entry or entries io_form_<x> to 5
  29   2. Run WRF as you normally would, for example:
  30      cd test/em_real
  31      ./wrf.exe
  32
  33 IV. Examining GRIB output with wgrib
  34   1. wgrib is installed within external/io_grib1
  35      (See http://wesley.wwb.noaa.gov/wgrib.html for more information.)
  36   2. Define the GRIBTAB environment variable:
  37         For bourne shell users:
  38           export GRIBTAB=<your WRF dir>/run/gribmap.txt
  39         For csh users
  40           setenv GRIBTAB <your WRF dir>/run/gribmap.txt
  41   3. To get a listing of the records in the GRIB data:
  42         <your WRF dir>/external/io_grib1/wgrib wrfout_d01_000000
  43
  44 IV. Quilting
  45   If you are running WRF using MPI, you may use a seperate processor for
  46     quilting just as is done with netCDF.  Simply set the namelist variable
  47     nio_tasks_per_group to 1 (or more).
  48
  49 V. Details
  50   1. gribmap.txt file
  51      io_grib1 makes use of a GRIB table for encoding the WRF data into GRIB
  52         format.  The GRIB table that io_grib1 uses is contained in the
  53         WRF run directory, and is called gribmap.txt.  This file is read at
  54         run-time by io_grib1.  Settings in this file are used to encode the
  55         corresponding parameters in the GRIB output files.  You may modify
  56         this file to suit your needs.
  57
  58       The file has the following format:
  59
  60       the first line of a table (note: there may be several tables in a
  61                                  gribmap.txt file)
  62       -1:CENTER:SUBCENTER:PARAMETER_TABLE_VERSION
  63           "-1" is an indicator for the start of a table
  64           "CENTER" is generating center (PDS 5, i.e., for NCEP, this is 7)
  65           "SUBCENTER" is the generating sub-center (PDS 26)
  66           "PARAMETER_TABLE_VERSION" is the parameter table version (PDS 4)
  67
  68       Subsequent lines:
  69       GRIBID:<PARAMETER>:<DESCRIPTION>:<WRF VAR>:<DECSCL>
  70           "GRIBID" is the GRIB parameter id (PDS 9).
  71           "PARAMETER" is the abbreviated parameter name.
  72           "DESCRIPTION" is a description of the parameter.
  73           "WRF VAR" is a comma-seperated list of WRF variables that will be
  74                     encoded as with PARAMETER described in the line and with
  75                     the CENTER, SUBCENTER and PARAMETER_TABLE_VERSION listed
  76                     at the beginning of the table.  WRF VAR must use
  77                     the WRF variable names that are defined in the "DNAME"
  78                     column in the WRF Registry.
  79           "DECSCL" is the decimal scale factor.  It is the number of digits
  80                     to the right of the decimal point that will be saved in
  81                     the output data.  This number may be less than zero, in
  82                     which case, the precision of data will be truncated the
  83                     specified number of digits to the left of the decimal
  84                     point.
  85                        Examples:
  86                          -2 : Data will be encoded at the hundreds level,
  87                               i.e., 102425.231 will be encoded as 102400
  88                           3 : Data will be encoded at the thousandths level,
  89                               i.e., 102425.231243 will be encoded as 1024.231
  90       Example:
  91            1:PRES:Pressure [Pa]:P,PSFC:1
  92              In this example, GRIB parameter 1, abbreviated PRES, is
  93                 pressure in pascals.  WRF variables P and PSFC (as listed in
  94                 the WRF Registry) will be encoded as PRES.  The data will have
  95                 one decimals of precision, i.e., 101323.1 Pa.
  96            62:NCPCP:Large scale precipitation [kg/m^2]:NCPCP:2
  97              In this example, GRIB parameter 62, abbreviated NCPCP, is
  98                 Large-scale precipitation.  The WRF variables NCPCP (as listed
  99                 in the WRF Registry) will be encoded as NCPCP.  The data will
 100                 have two decimals of precision, i.e., 1.23 kg/m^2 (i.e.,
 101                 1.23 mm).
 102
 103       Note:
 104           For GRIB encoding, parameters 1-127 are the standard parameters
 105             described by the WMO GRIB convention.  Interpretation of parameters
 106             128-254 vary depending on the setting of the CENTER, SUBCENTER,
 107             and PARAMETER_TABLE_VERSION.  In the default gribmap.txt file,
 108             the CENTER and SUBCENTER are both set to be 255.  Five tables
 109             with PARAMETER_TABLE_VERSION's varying between 2 and 6 are
 110             specified in the default gribmap.txt file.
 111
 112   2. Variable dimensions.
 113       A GRIB file is a set of records of data.  Each record is a 2-dimensional,
 114         horizontal field, i.e., temperature on a pressure surface,
 115         In the case of the WRF Eulerian mass model, we have variables on Eta
 116         coordinates, so, we have, i.e., temperature on the 0.995 Eta level.
 117       WRF outputs 3, 2 and 1-dimensional fields and point data.  3-dimensional
 118         (i.e., u-component of wind) fields are stored in GRIB as a series of
 119         horizontal 2-dimensional fields.  WRF horizontal 2-d fields are stored
 120         simply as horizontal 2-d fields (i.e., surface pressure).
 121         One-dimensional fields with dimension varying in the vertical (i.e.,
 122         the vertical coordinate ZN), are stored as a set of 1x1 grids valid
 123         at the center of the grid.  So, the third vertical level (ZN) is
 124         encoded as a 1x1 grid, valid at the center of the grid.  Point data
 125         is also stored as a 1x1 grid valid at the center of the grid.
 126
 127 VI. Performance
 128    GRIB output has proven to be very fast, as compared to netcdf output.
 129
 130    Listed below is a comparison of file size and run-time for io_grib1 and
 131    io_netcdf.  WRF was run twice, once with GRIB output and once with netcdf
 132    output.  In both cases, 32 CPUS (on 16 machines) were dedicated to
 133    model integration, and one was CPU dedicated to I/O and quilting (using
 134    nio_tasks_per_group = 1).  The run had a domain with 360x485 grid points
 135   (12 km spacing) and 10-minute output.  The model was run out to 3 hours.
 136
 137    Shown is the file size for one-output time, the total model run-time
 138    and the time for I/O as listed in the WRF output.  In addition, the
 139    additional time that is required for a time-step just after model output
 140    is listed.
 141
 142    Format    File Size    Run time     I/O time   additional time after output
 143    netCDF     368 MB       719 s         1.26 s            3.3 s
 144    GRIB v1    109 MB       519 s         0.28 s            1.9 s
 145
 146
 147 VII. Testing
 148    We (at WSI) have tested io_grib1 with WRF running on linux (redhat v 9.0).
 149    We typically use the intel fortran compiler (v8.0) and the gnu C compiler,
 150    so, that configuration has the most testing.  We have also done limited
 151    testing with the Portland Group Compiler on linux.  We have not tested any
 152    other platforms or compilers.
 153
 154 io_grib1
 155
 156 Author: Todd Hutchinson
 157         WSI
 158         thutchinson@wsi.com
 159