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
3 Bias Corrected Forecast
4 Ensemble Forecast
5 Probability Forecast
6 Forecast Error
7 Analysis Error
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
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
(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.
- big (templated) data sets: multitasking (linux and unix) vs single task with gribmap
- big (templated) data sets: fast update mode
- grib2 support: more flexible
- grib2 support: can support variants that g2ctl may not support
- grib2 support: easier to support variants that g2ctl doesn't (yet) support
- ensemble dimension not supported yet
- alt_g2ctl and alt_gmp are more integrated. Options for alt_g2ctl are saved and passed to alt_gmp.
- code is simpler (IMHO)
- immature: 2GB+ files not supported (is there a need?)
- ensemble dimension not supported yet
- immature: many small features are not supported yet
- 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.
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.
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.
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,
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.
- by ftp
- by http
- You need to use a recent version of wgrib2.