Skip Navigation Links 
NOAA logo - Click to go to the NOAA home page National Weather Service   NWS logo - Click to go to the NWS home page
Climate Prediction Center

About Us
   Our Mission
   Who We Are

Contact Us
   CPC Information
   CPC Web Team

HOME > Monitoring_and_Data > Oceanic and Atmospheric Data > Reanalysis: Atmospheric Data > alt_g2ctl and alt_gmp

new format grib2 control files

The official grib2 control file uses a sequence of numbers to specify the grib2 messages. This system worked well for grib1 but has limitations for grib2. Grib2 has a more complicated metadata structure and a change in one of the metadata tables can completely change the interpretation of a value. Unfortunately the current sequence of numbers do not include all the tables. for example:

           GRIB2 - TABLE 1.4

     0     Analysis Products
     1     Forecast Products
     2     Analysis and Forecast Products
     3     Control Forecast Products
     4     Perturbed Forecast Products
     5     Control and Perturbed Forecast Products
     6     Processed Satellite Observations
     7     Processed Radar Observations
     8     Event Probability
Depending on the value of the table, the units of the field can change from what is expected (ex. temperature = K) to a a probability. Here another example.
     GRIB2 - TABLE 4.3

     0     Analysis
     1     Initialization
     2     Forecast
     3     Bias Corrected Forecast
     4     Ensemble Forecast
     5     Probability Forecast
     6     Forecast Error
     7     Analysis Error
     8     Observation
     9     Climatological
    10     Probability-Weighted Forecast
    11     Bias-Corrected Ensemble Forecast
Depending the contents of this table, the field can change from forecast to a forecast error. In one NCEP product, two fields have the same metadata except for this table (analysis vs analysis error.) Unfortunately the current GrADS control file format ingnores tables 1.4 and 4.3.

I believe that a more flexible method of identifying the grib2 fields is needed. Instead of using a sequence of numbers, a free-format text string is used. This new control file format used by alt_g2ctl and alt_gmp is compatible with GrADS.

New Tools: alt_g2ctl and alt_gmp

alt_g2ctl and alt_gmp are alternative g2ctl and gribmap programs. alt_g2ctl takes grib2 files and creates GrADS control files. alt_gmp takes the control files generated by alt_g2ctl and creates GraDS index files. The alt control files are compatible with GrADS but not gribmap. Here is the workflow.
     std:   g2ctl (1) -> gribmap (3) -> GrADS
     alt:   alt_g2ctl (2)-> alt_gmp (3) -> GrADS

     (1) std-format grib2 control file format
     (2) alt-format grib2 control file format, compatible with GrADS
     (3) std format index file

Speed and BIG datasets

The current gribmap is single threaded. You paid all that money for more cores and you are stuck using one core. Alt_gmp will take advantage of the extra cores. Won't make any difference with a small file but you'll notice the difference with a TB data set. For example, you have a templated data set of 40 years of daily files (40 * 365.25 = 14610). Gribmap will use one thread to read all the 14610 files. You can run alt_gmp to have N threads and each thread will read 14610/N files.

Another problem with making index files of big datasets, is that if you update one file (example add the current month to an archive), gribmap forces you to reread the entire data set with one thread. (Note: GrADS 2.1.a2 fixes this problem with an update mode.) Alt_gmp has a threaded update mode. This update mode works by saving the scan as a tiny file (compressed wgrib2 inventory).

The New Design

The alt gribmap (alt_gmp) is a completely new implementation of the gribmap program. It is uses the more flexible alt-grib2 control format. The options for alt_gmp are stored in the ctl file, so the options for alt_g2ctl and alt_gmp are consistent. (For example, the ctl file was made with the -O option, the idx file will also be made with the -0 option.) Alt_gmp is also multitasked (user selectable) and has an update option. The latter two features are important when working with large grib2 datasets. The design of alt_gmp is different from gribmap. Gribmap is C code that reads the ctl and grib files to create an index file. Alt_gmp is a perl script that
(1) scans the ctl file (perl is great for text scanning)
(2) finds the grib files that need to be read (file1..filen)
(3) do file = file1 .. filen (this loop is threaded)
(4)    runs wgrib2 on the file to create an inventory
(5)    reads the wgrib2 inventory to updates the index
(6) enddo
(5) writes out the index

In the update mode, a small wgrib2 inventory file is written for each grib file. In future runs of alt_gmp, the small inventory file, if present, is read instead of the much larger grib2 file. This save considerable amount of time for large datasets.

alt_g2ctl is modification of g2ctl. It remains a perl script that uses wgrib2 to query the files.

The Good

  1. big (templated) data sets: multitasking (linux and unix) vs single task with gribmap
  2. big (templated) data sets: fast update mode
  3. grib2 support: more flexible
  4. grib2 support: can support variants that g2ctl may not support
  5. grib2 support: easier to support variants that g2ctl doesn't (yet) support
  6. ensemble dimension not supported yet
  7. alt_g2ctl and alt_gmp are more integrated. Options for alt_g2ctl are saved and passed to alt_gmp.
  8. code is simpler (IMHO)

The Bad

  1. immature: 2GB+ files not supported (is there a need?)
  2. ensemble dimension not supported yet
  3. immature: many small features are not supported yet
  4. limitations of g2ctl still remain in alt_g2ctl

You may notice that "ensemble dimension not supported yet" is both a Good and a Bad. A former boss wanted to have a dataset of ensemble forecasts. There were multiple starting times and multiple forecast hours. With the alt system, he has able to use the time dimension to refer to the valid time and special names to indicate the ensemble and forecast hour. The ctl file had to be hand modified but it worked. In another case, a user had a time series of 120 hour forecasts by the control forecast. Since forecasts had ensemble information (control), it needed an EDEF section. However, the starting time of the control forecast was not fixed. It could be handled by alt_gmp but not gribmap.


I (WNE) use both alt_g2ctl and g2ctl for my work. For ensembles and large (2GB+) files, I use g2ctl/gribmap. For large reanalysis data sets, I use alt_g2ctl/alt_gmp. For newer grib2 product definition templates, you may have to use alt_g2ctl. For simple stuff, there is no big difference between g2ctl and alt_g2ctl.


Was released early 2013.

Instructions: alt_gmp

     alt_gmp   (-i) FILE.CTL

     -i FILE.CTL   identifies the control file
                   -i is optional (v 0.0.3)

      Comments: No options are allowed.  The options like -update, -b, -0
                are embedded in the .ctl file by alt_g2ctl.

Instructions: alt_g2ctl

     alt_g2ctl [list of options] TEMPLATE [INDEX] > FILE.CTL

     TEMPLATE      The TEMPLATE may include an optional directory
                   TEMPLATE may contain template wildcards: %y4, %y2, %m2,
                   %d2, %h2,  %n2, %f2, %f3
                   alt_g2ctl only understands a fraction of the possible template
                   possibiilities.  The template wild cards can only be in the
                   filename.  The chronological order of the files must match
                   the sorted namelist.  This restricts the order of the template

                   If your filename and directory structure do not match this,
                   make the CTL file for a single file.  Then add the templates,
                   and adjust the TDEF statement.  This works because alt_gmp
                   is not restricted to a sorted namelist == chronological order.

     INDEX         the INDEX file name is optional, if not provided, the name of
                   the index file will be generated


 -0              .. use analysis time
                          same as g2ctl/gribmap
 -0t             .. use analysis time + fhour
 -b              .. use use start of ave/acc period or fcst time
                          same as g2ctl/gribmap
 -bt             .. use use start of ave/acc period or fcst time + fhour
 -e              .. use use end of ave/acc period or fcst time (default)
 -et             .. use use end of ave/acc period or fcst time + fhour
 -update         .. alt_gmp will be in fast update mode
 -nthreads N     .. number of threads used by alt_gmp (default=1)
 -wgrib2 EXE     .. replace wgrib2 by EXE
 -short          .. remove comments and shorten variables names
 -sub "A" "B"    .. substiute variables names, A -> B, use regular expressions
                 .. any number of -sub options can be used
 -prs            .. pressure (mb) vertical coordinates (default)
 -iso            .. pot temp (K) vertical coordinates
 -dsl            .. below sea level (m)  vertical coordinates
 -bsl            .. below sea level (m)  vertical coordinates (obsolete)
 -sig            .. sigma (0..1) vertical coordinates
 -no_profile     .. no vertical coordinates
 -365            .. 365 day calendar
 -ts[timestep]   .. set timestep for individual time files (e.g. -ts6hr)
 -lc             .. set lowercase option for parameter names
 -pdef_linear    .. linear interpolation for thinned grids
 -raw            .. raw grid

Note 1: the index file will be generated by the alt_gmp program, default: grib_file.idx
Note 2: the pdef file is only generated for thinned lat-lon grids, default: grib_file.pdef
Note 3: template options supported: %y4 %y2 %m2 %d2 %h2 %n2 %f2 %f3

The number of threads used to scan the grib2 files is set by the option -nthreads. For a single lightly used local disk, setting nthreads to one is the fastest as it minimizes disk head movements. For some systems, NFS is the speed limiting factor. By setting nthreads larger than one, you can improve the speed of NFS for loading multiple files. Finally some filesystems have huge bandwidths and the limiting factor is the number of threads. Note that the nthreads option only applies to templated data sets.

Variable names are too long

GrADS allows up to 15 characters for the variable names. Alt_g2ctl uses the wgrib2 extended name as the variable name. Unfortunately with extended name can get quite long. Here is the var section from a ctl file.

vars 3
APCPdpercentile_from_climate_distributionsfc 0 0 "APCP.percentile_from_climate_distribution:surface" * APCP.percentile_from_climate_distribution:surface
TMPdpercentile_from_climate_distribution2m 0 0 "TMP.percentile_from_climate_distribution:2 m above ground" * TMP.percentile_from_climate_distribution:2 m above ground
WINDdpercentile_from_climate_distribution10m 0 0 "WIND.percentile_from_climate_distribution:10 m above ground" * WIND.percentile_from_climate_distribution:10 m above ground

In this example, the variable name exceeds 15 characters so GrADS shortens the name into 15 characters which may cause the variable names to overlap. In this example, the total length of the line may also cause problems for GrADS. The solution is the use the -short option in alt_g2ctl. The option replaces the variable name by "v(integer)" and elminates the comment field. Using the same data file, the var section becomes,

vars 3
v1 0 0 "APCP.percentile_from_climate_distribution:surface"
v2 0 0 "TMP.percentile_from_climate_distribution:2 m above ground"
v3 0 0 "WIND.percentile_from_climate_distribution:10 m above ground"
From GrADS, you can see the variable definitions by "q file".

What are the *.invd??.gz files

The *.invd??.gz files are gzipped inventories of the grib files. Alt_gmp will read the inventories in preference to the grib files. This increases the speed of alt_gmp many-fold. If you change a grib file, you have to delete the corresponding *invd*gz file too. The number in the file name corresponds to the type of inventory being made. For example, if you use the analysis time time instead of the forecast or verification time, then you get two different types of inventories.

Since the inventories can change with the version of wgrib2, you may need to remake the *invd*gz if you adopt a new version of wgrib2.


  1. by ftp
  2. by http
  3. You need to use a recent version of wgrib2.


NOAA/ National Weather Service
National Centers for Environmental Prediction
Climate Prediction Center
5830 University Research Court
College Park, Maryland 20740
Climate Prediction Center Web Team
Page last modified: June 6, 2017
Disclaimer Privacy Policy