wgrib2: wgrib for GRIB-2
Utility to read and write grib2 files
wgrib2 v3.1.0 has been released
pywgrib2_s been released for beta (Linux/MacOS) (wgrib2 v3.0.0, 9/2020)
wgrib2 is not simple upgrade of wgrib for grib2 files. wgrib
can slice and dice grib1 files. wgrib2 is more like four
drawers of kitchen utensils as well as the microwave and blender.
This kitchen miracle was done by a more developer friendly design
and the contributions of many people. Some functionality include,
- inventory and read grib2 files
- create subsets
- create regional subsets by cookie cutter or projections
- export to ieee, text, binary, CSV, netcdf and mysql
- write of new grib2 fields
- parallel processing by using threads (OpenMP)
- parallel processing by flow-based programming
- fortran, C, and
OpenMP is used to speed up wgrib2 by running loops over
multiple cores. With gcc, clang and icc, OpenMP is on by default.
In general, you set the number of threads to be less or equal
to the number of CPU cores available. Usually I set the number to 3 on
a 4-core/4-thread machine. Setting the number of threads to 4
leads to a sluggish machine. So I added these two lines to my .bashrc
The first line limits OpenMP to three threads (cores)
The second line tells OpenMP to release unused threads (cores)
For a 4-core/8-thread CPU (Xeon(R) W-2123), taking advantage of
hyper-threading would seem to be a good idea.
(Use the clock cycles spent waiting for reading the DRAM.) However,
more threads means the effective size of the cache per active thread
is reduced which means more reading of the DRAM.
So the optimal number of cores is determined by the equivalent of the
the Laffer curve for the number of threads.
Compiling: NetCDF Configuration
Wgrib2 can be configured with (1) no NetCDF support, (2) NetCDF3 support or
(3) NetCDF4 support. The advantages and disadvantages are,
- Option 1: No NetCDF support
- fast compile
- small executable (3.9 MB as of 2014)
- compile works on 32+ bit machines
- cannot read nor write NetCDF files
- no library conflicts in wgrib2lib when calling program
uses netcdf or hdf
- makefile configuration: USE_NETCDF3=0, USE_NETCDF4=0
- Option 2: NetCDF3 support (default in makefile)
- fast compile
- modest increase in executable size (5.7 MB vs 3.9 MB as of 2014)
- compile may fail on 32-bit machines
- library conflict in wgrib2lib when calling program that uses netcdf
- makefile configuration: USE_NETCDF3=1, USE_NETCDF4=0
- Option 3: NetCDF4 support
- slow compile time (hours on an Intel Apollo Lake)
- 3.5x increase in executable size (13.5 MB vs 3.9 MB as of 2014)
- HDF5-1.10.4: compile works on RedHat 6 (gcc 4.x and intel 17.03)
- HDF5-1.10.4: compile has failed on Ubuntu and various other systems (newer gcc)
- HDF5-1.10.4: compile has failed on Ubuntu and AOCC (clang variant)
- HDF5-1.10.6: compiles on Ubuntu and many other machines
- HDF5-1.10.6: requires fortran90 compiler
- HDF5-1.10.6: wgrib2 fails with hdf5 internal error
- library conflict in wgrib2lib when calling program that use netcdf
- makefile configuration: USE_NETCDF3=0, USE_NETCDF4=1
- prompts for downloading netcdf4/hdf5 libraries
1/2019: Debian and Fedora and many others have patches
to make hdf5-1.10.4 work (needed for netCDF4). After you download
hdf5-1.10.4, apply the patches. Then you may be able to compile
wgrib2 with netCDF4 support by changing the makefile.
8/2020: NetCDF4 remains on the unsupported feature list because of
long-term problems with the hdf5 library. If you are willing to trust
a long-term archive to a format that has only one implementation,
well that is your choice.
There are many other programs that can handle grib and NetCDF4.
Use one of those programs if you want support.
Execution: Segment Faults
Wgrib2 is used in NCEP operations and by many daily processing jobs
at CPC. Seg-faults are pretty uncommon to wgrib2. The common problems
are in related to experimental/alpha features and the following 3 problems.
The jpeg2000 library (Jasper) could seg-fault with larger grids. This
problem was fixed with an Ubuntu/Debian update to Jasper (fall 2015) which was
incorporated into wgrib2 v2.0.3. If your copy of wgrib2 is using another version of the
Jasper library, then your copy of wgrib2 may be vunerable to this
Wgrib2 can decode grib using g2clib. Using the g2clib that was
not included with the wgrib2 source code could cause a seg-fault. Wgrib2 had patches
to g2clib that were not fully incorporated until g2clib v1.4.0. In addition,
g2clib can be compiled either with a 32 or 64-bit interface. The default
makefile assumes that a 32-bit interface is used on 32-bit processors and a
64-bit interface is used 64-bit processors. Third-parties often followed
NCEP's lead and used a 32-bit interface for 32 and 64 bit machines.
Of course, that limits the current g2clib (8/2020) to 2GB files.
Finally, the third problem is a compiler bug and only affects
This problem appears in gcc 2.4.7's handling of unsigned int
looping variables when OpenMP is enabled. The problem is
fixed by gcc 2.5.0.
- wgrib2 v2.0.4
- wgrib2 was compiled with OpenMP support
- number of threads is greater than one
- creating simple packed grib messages
- all the grid points are undefined
- compiled with older versions of gcc such as 2.4.7
There a potential for seg-faults by reading using specially crafted png or jpeg2000
compressed grib files. For example, a few days after the release of wgrib2 v2.0.3, the pnglib
was upgraded to fix a seg-fault when reading a specially crafted png file.
5/6/2021: PNG support is lacking for bit depths of 1, 2 and 4.
Fix has been tested.
3/27/2021: AOCC v3.0 requires OpenJPEG for jpeg-2000 support.
The default Jasper library produces empty data.
Unfortunately OpenJPEG requires CMake which is unavailable on my work machine.
This is show that I have some empathy for users with restrictive sys admins.
3/01/2021: wgrib2 v3.0.1: the wrong files were written to the web servers
So the update is being released as wgrib2 v3.0.2.
Changes for wgrib2 v3.0.2
- tested: gcc/gfortran on Ubuntu 20.04, Redhat 7, SUSE
- tested: AOCC v2.3 (clang, flang) on Ubuntu 20.04
- tested: nvidia HPD-SDK on Ubuntu 20.04
- tested: icc/ifort on Redhat 7
- tested: Windows 10 using cygwin64
- notes: Redhat 6 is EOL. moved to Ubuntu 18.04 to 20.04 at home
9/30/2020: wgrib2 v3.0.0 is released.
- tested: gcc/gfortran on Ubuntu (18.04/20.04), Redhat (6/7), SUSE
- tested: AOCC (clang, flang) on Ubuntu (18.04)
- tested: icc/ifort on Redhat 7
- tested: MacOS with a real gcc/gfortran
- tested: Windows 10 using cygwin64
- each option call corresponds to a subroutine call
- type wgrib2 to see primary options
- inventory format is specified on command line by options
- if no "inv" option is specified, -s is used
Joining the development effort
- Source code: knowledge of C and some grib-2
- Changes to existing source code should use the same licence as the original code
- New code (files) must either be GNU or public domain.
- Bug reports are important
- Contact email@example.com
- Wesley Ebisuzaki: many modules
- Reinoud Bokhorst: tosubmsg, checksum
- DWD (Gregor Schee, Daniel Lee and others): AEC compression
- Jaakko Hyvätti: gribtab
- John Howard: callable wgrib2
- Dusan Jovic: staggered grids, proj4 code
- Kristian Nilssen: netcdf module
- Karl Pfeiffer: georeferencing
- Pablo Romero: unix_time
- Manfred Schwarb: many modules
- Arlindo da Silva: openGrADS, bbox
- Niklas Sondell: mysql module
- Sam Trahan: satellite tables
- George Trojan: python interface, improvements to wgrib2api
- Sergey Varlamov: netcdf module improvements, georeferencing updates
- thanks to the people who report the bugs and more who provide the fixes!
Select/Ignore by name/level/time/etc
- -match process records that match a posix extended regular expression
- -not process records not matching a regular expression
- -match_inv the inventory used by -match and -not
- -i reads inventory from stdin for record selection
Select by number (better to use previous method)
- -d dump specific record
- -for select a range of records to process (nth message)
- -for_n select a range of records to process (nth message/submessage)
Selective Processing: if options
After selecting the fields to process, you can refine the processing by
the "if" options. With wgrib2 v3.0.0, the IF
structure was improved. Scripts that used the older IF structure still work;
however, the new IF structure is easier to read.
If possible, it is better to use the match options than the if options.
The -match/-not options prevent unwanted records from being processed which
saves time over the if options which process the fields.
Individual Grid Point Data
- -ij print value at grid point (i, j)
- -ijlat print lat, lon, value at grid point (i, j)
- -ilat print lat, lon, value of Nth grid point
- -lon prints the lat-lon, and value of the grid point nearest the specified lat-lon
- -max prints the maximum value
- -min prints the minimum value
- -stats prints some statistics about the fields
- -V verbose inventory (shows stats)
Regridding, Interpolating to new grids
Wgrib2 has the ability to convert grib files from one grid
to another. The conversion uses a user-selected interpolation
scheme: bilinear (default), bicubic, nearest neighbor, budget, and spectral.
The supported grids include lat-lon, gaussian, Lambert conformal, polar stereographic,
and WMO-defined rotated lat-lon grid. This capability uses the NCEP IPOLATES2 library
and is an optional package.
Note: the interpolation uses scalar and vector interpolation
schemes. For the vector quantities the V field must immediately
follow the corresponding U field.
Exporting data to other programs
For a short list of options, type "wgrib -h"
- -netcdf: write data in netcdf format
- -mysql: export data to a mysql database
- -mysql_speed: export data to a mysql database
- -spread: write data for spreadsheets
- -csv: write in column separated values, another one for spreadsheets
- -text: data in text format
- -bin: data native binary floating point
- -ieee: data in big endian IEEE format
- -ijbox: write a rectangular grid of data
- -AAIG: arcinfo ascii grid, GIS
For a complete list, type "wgrib -help all"
To search for an option, type "wgrib -help keyword"
Wgrib2 has adopted the template approach for writing grib. You
have a sample grib2 message (template), and you modify the grid point values
and metadata to create a new grib message that you can write.
This is similar to how ECMWF's ECCodes writes grib. The other approach
is to supply many parameters to create a grib message which is used
by NCEP's g2 library.
- from wgrib2 command line
- from GrADS using g2grb.gs
- fron python using write
- from fortran using grb2_write
Machines able to run wgrib2
- linux: 64-bit with IPOLATES
The makefile works on Redhat and Ubuntu (with needed installed options).
For other systems, you may have to modify the makefile. The makefile
requires gnu make is a common version of make.
- Redhat 6 Enterprise: primary development system
- Redhat 7 Enterprise
- Redhat 5 Enterprise: remove compile option "-Werror=format-security"
from the makefile. This is a mandatory compile option for some
distributions and is just a good idea. However, the gcc in RH5 doesn't support this option.
- Ubuntu 18.04 and 20.04: 64-bit with IPOLATES
- Ubuntu: AOCC's clang and flang
- ARM: needed to be compiled with USE_NETCDF4=1, USE_JASPER=0
- Redhat linux: 32-bit with IPOLATES, not tested recently, use netcdf4
instead of netcdf3
- Mandriva linux (old report)
- AIX: use makefile, some fiddling with libraries is necessary, not tested recently
- Solaris, needs gnu make and gcc (old report)
- HPUX, needs changes to makefiles (old report)
- Windows: using Cygwin system produces 32-bit binaries. using netcdf4
- Windows: using Cygwin system produces 64-bit binaries
- Windows: compiled MingW (not recent), Watcom C, icc/ifort
- Windows/linux subsystem (ubuntu): compiled with gcc/gfortran
- Intel-based Mac using gcc and gfortran
- The IPOLATES library has been tested with on AIX fortran, g95, gfortran, ifort, and openf95
System dependencies: 32 vs 64 bit, Windows vs Linux/UNIX
The wgrib2 source code is written to be portable; there are no
issues with big vs little endian or the size of the integer as
long as it is 32 bits or more. The source code is written to
the ANSI/ISO C standard, with "optional" features that require
POSIX or POSIX-2 compiler support. There has been a debate about
moving the base level to C99.
Foe windows, the cygwin's gcc supports the POSIX standard and allows
the standard source code to be compiled. For other windows compilers,
it is possible to compile the code with many of the POSIX extentions turned off.
Usually the grib files are limited to 2GB.
Wgrib2 can be compiled for 32-bit systems. However, this feature hasn't
been tested in years.
For most Windows 64-bit C compilers, "long int" is defined as 32 bits.
Consequently the ISO C random-access routine is limited to 2GB files.
The 64-bit cygwin gcc works the way it should and is recommended
for windows compilations.
The main difference
between the windows and linux versions is that windows treats
binary and text files differently. Consequently you can send
a grib or binary data to STDOUT in unix/linux with no problem.
Under windows, the results are implementation dependent.
In addition, POSIX1 and POSIX2 functions may not be supported
or may function differently. Consequently certain options
may work differently.
- The maximum number of open files is system dependent.
- The maximum number of arguments to wgrib2 may be limited wgrib2 or by the system.
- The netcdf conversion is done in memory, so the speed is dependent
on the free memory available.
- Some wgrib2 options need to keep a copy of previously read data, so
may fail with insufficient memory
- the accuracy of the trig functions depends on the compiler
- wgrib2 is usually compiled in fast mode rather than ieee mode.
- Windows stdin and stdout have text and binary modes. Whether
using stdin/stdout for grib files works is compiler/OS dependent.
Source Code and Compling Hints
The wgrib2 source code is written to the POSIX-2 standard. Features requiring
POSIX2, such as regular expressions, can usually be turned off
in the makefile. The wgrib2 code can be compiled with 32 or 64 bit pointers and integers.
However, the code has to be compiled in a like manner for all the libraries.
Some packages are optional (netcdf, mysql) and enabling these options can really
increase the executable size.
While compiling wgrib2, you may see warnings about unknown pragmas. Pragmas
are "comments" that are used when compiling an OpenMP version of the code. The
default is to compile with OpenMP turned on.
2/2019: The HDF5 library has problems being compiled with newer gcc compilers.
The only consisten method of adding NetCDF4 to wgrib2 is by using old compilers
(RedHat 6) or using the Intel compilers. The work around to enable NetCDF3 support
and use an external utility to convert the files to Netcdf4.
NetCDF3 has problem being compiled on 32-bit machines.
Wgrib2 from VLAB
The VLAB/HPC-stack version of wgrib2 is for use by the NOAA supercomputers
and NCEP operations. It is based on the public release version
of wgrib2 but uses the CMake build system (requirement of HPC-stack)
instead of the makefile build. (Ironic comment: the CMake build
supports fewer OSes and compilers than the makefile build.)
Problems with building the VLAB version should be sent to the
people supporting the VLAB/HPC-stack version of wgrib2.
Problems with building the public release version should be
sent to firstname.lastname@example.org.
The theoretical advantage of VLAB is that it opens up the
development of the wgrib2 by using git. "Theoretical" is not
used in a pejorative manner, just that changes to wgrib2 have
never been enter through git. The current method is for
the code submissions be sent to me (email@example.com),
and I do the code review and testing. For major changes,
such as callable wgrib2, and adding python support, sometimes much
co-development is needed. OTOH The netcdf was in good shape at
the start. The plan is keep the current method of code
submissions and to vet the code changes from VLAB when necessary.
Personally I think that the old method is better for the code
because it keeps the design consistent and provides a better
evolution of the code.
Precompiled code from External Sites
There are many sites with precompiled versions of wgrib2. This list
is neither exhaustive nor an endorsement of the sites. I have
not tested the wgrib2 executables from these sites and YMMV.
Other programs that use wgrib2 (incomplete list)
a control maker for GraADS
- atl_g2ctl, alt_gmp
alternative versions of g2ctl/gribmap for for
- grib-filter/g2subset cgi-bin programs for Nomads (NOAA OperationalModel Archive & Distribution System)
- g2grb.gs enables GrADS to write grib2 files
- rNOMADS R interface for NOAA weather data
- rNOMADS R interface for NOAA weather data
- grb1to2.pl grib1 to grib2 converter
- wgrib2api, a fortran API for reading/writing grib2
The code is being developed on a Redhat linux x86_64 platform in standard (POSIX) C.
The wgrib2 source code requires an integer size of 32 or more bits. Incompatibilites
tend to be related to problems in compiling of the external libraries (ex. netcdf,
9/2018: netcdf4 will not compile with Ubuntu, upgrade to hdf5 v1.10.4
11/2016: wgrib2 v2.0.5 AEC library doesn't compile, upgrade library source code
8/2015: wgrib2 v2.0.0-v2.0.2 -ieee does not work with OpenMP. Fixed 2.0.3
8/2015: complex packing: problem when creating if grid values are all undefined. Fixed 2.0.3
5/2015: callable wgrib2 and fatal errors. The error handling code can
cause a seg fault on subsequent calls to wgrib2. Problem has been fixed v2.0.3
1/2014: Jasper library bug? Grib files that have large grids and that are
compressed with jpeg-2000 can have problems. Have seen this problem in GrADS,
wgrib2 and it has been reported in WCT. update: 11/2016: this problem was
fixed by using Debian/Ubuntu version of the Jasper library included with wgrib2 2.0.3.
Please report them to firstname.lastname@example.org. When you report bugs,
try to make them reproducible on a linux machine and include sample data.
The source code modules for wgrib2 are either in the public domain or under the GNU
licence depending on the authors of the various modules. Wgrib2 uses libraries that
are in the public domain, under various GNU licences, the Image Power JPEG-2000 Public Licence*,
libpng licence*, the zlib licence*, the netcdf licence*, HDF5 licence*, MySQL licence* and perhaps others. How
about one licence to rule them all?
* optional package