Introduction
The ECMWF grib_api software library provides a set of functions/subroutines and command line tools for encoding and decoding WMO FM-92 GRIB edition 1 and edition 2 messages. The OpenIFS model uses GRIB for its input and output files.
The grib_api software library must be build and installed before building OpenIFS. Although there may be a version of grib_api on your system already that would most likely work, it is recommended that you build and install grib-api as described below to ensure the correct configuration is used for OpenIFS. Also, to ensure the same compiler and compiler version is used, as otherwise, error messages about conflicting module versions when compiling OpenIFS can arise.
This page gives additional information about grib-api for OpenIFS. For more information about grib_api, to download and install it please visit the grib_api website.
Before you start
Decide where you will put the grib_api package.
For a single user, grib_api might be installed in your home directory. For a multi-user environment, say a cluster or High Performance Computing Facility (HPCF), installing the grib_api package centrally once only is probably best and pointing your build configuration to this location.
In the walk-through example that follows, a single-user download and install is assumed.
Download and unpack
In this example, create a directory called $HOME/ecmwf in which grib-api will be downloaded and compiled.
If you haven't already obtained the grib_api package, get it from the grib-api web site.
We recommend downloading the latest version. Some of the instructions for options below may differ with the very latest versions.
Unpacking grib_api
To unpack the software:
mkdir -p ecmwf/src cd ecmwf/src tar zxf grib_api-1.14.0-Source.tar.gz
or if your version of tar doesn't support the 'z' option, do:
gunzip grib_api_1.14.0.tar.gz tar xf grib_api-1.14.0.tar
Configuring using CMake
Grib_api uses the CMake command for configuration and compilation. CMake is available for modern Linux systems but may have to be installed.
Alternately grib_api supports installation via a 'configure' script, though this option is deprecated. See instructions below and GRIB API Installation for more details.
CMake compilation must be done is a separate build directory to both the source and the install directory.
mkdir bld
mkdir grib-api
cd bld
export CC=gcc
export FC=gfortran
cmake ../grib_api-1.14.0-Source \
-DCMAKE_BUILD_TYPE=Bit \
-DCMAKE_INSTALL_PREFIX="../grib-api" \
-DENABLE_NETCDF=ON \
-DENABLE_JPG=OFF \
-DENABLE_PNG=OFF \
-DENABLE_PYTHON=ON \
-DENABLE_FORTRAN=ON \
-DENABLE_GRIB_THREADS=ON
Explanation of lines:
| These lines set the choice of compiler. CMake is often able to determine the available compilers for itself. However, in cases where multiple compilers are available, or where compiler wrappers are used (as on HPC systems), it's preferable to set these explicitly by use of environment variables. These lines can often be omitted. |
CMAKE_BUILD_TYPE=Bit | "Bit" here means 'bit-reproducible'. It instructs CMake to use conservative compiler options that are known to ensure bit-reproducibility in separate runs of OpenIFS. |
CMAKE_INSTALL_PREFIX="../grib_api" | This specifies the location where the 'make install' command will place the grib-api installation. |
ENABLE_NETCDF=ON | Enabling netcdf ensures the grib_to_netcdf command can be used. |
ENABLE_JPG=OFFENABLE_PNG=OFF | As OpenIFS does not deal with any image based GRIB data these options can be disabled, unless you have other grib data containing images that you need to work with. |
ENABLE_PYTHON=ON | Some of the utilities that come with OpenIFS make use of the python interface to grib_api, e.g. the tools to create and manipulate the model data. For this option to work, ensure that a python installation is available. |
ENABLE_FORTRAN=ON | This enables the Fortran interface to grib_api and should always be on. |
ENABLE_GRIB_THREADS=ON | This ensures grib_api is compiled to be 'thread-safe'. Although OpenIFS does not currently use multiple threaded calls to grib-api, future versions may do so this option is recommended. |
Other build types
CMake supports several standard 'build types'. These are:
| Release | Release mode - the binary package does not include debug symbols and some of the source code is ignored; this mode is the default for users. |
| Debug | Debug mode - the binary package includes debug symbols in the source code are not ignored; this mode is the default for developers and typically uses low or no optimisation. |
| RelWithDebInfo | Release mode, but the binary package includes debug symbols this mode is for developers and users and is often the default build type. |
| Bit | Bit-reproducibility mode - This is non-standard and will not be found on other cmake enabled packages. It is used at ECMWF to set compiler options that have been tested to provide bit-reproducibility. |
Available options
To get additional help on the available options (similar to the 'configure --help' command) run the command:
cmake -LH grib_api-1.14.0-Source
This command will cause cmake to run its system discovery if this is the first time the command has been used. On some systems, this may take time to complete.
Configuring using configure
Grib_api compilation can also be made using the GNU configure tool.
The configure command is contained in the grib_api directory. A few options are needed to suit OpenIFS and gcc & gfortran compilers are assumed in the example below. If you use different compilers, see below.
cd grib_api_1.14.0-Source ./configure --prefix=$HOME/ecmwf/grib_api --enable-pthread --enable-python --disable-jpeg
A description of what these options are for:
--prefix | This specifies where you want the grib_api files to be installed. In example here, the source code is in $HOME/ecmwf/grib_api_1.14.0-Source and the compiled grib_api libraries will go in directory $HOME/ecmwf/grib_api. You are free to choose any installation directory but it's recommended to keep the installed binaries & libraries in a separate directory to the source code, in case different compiler versions are needed. On a shared high performance computer facility, the install path would most likely be somewhere central. If nothing is specified for --prefix, by default grib_api will install in /usr/local. |
--disable-jpeg | OpenIFS does not need to support JPEG and PNG for data compression. This removes the need to link OpenIFS against the Jasper library (libjasper.a). |
--enable-pthread | This option ensures that grib_api is thread-safe and is a recommended option. |
--enable-python | This enables the python interface and is required as some OpenIFS utilities make use of the grib-api python interface. If the make fails because of a missing numpy header file you should add the --disable-numpy option. |
Other options
--help option to configure can be used to see what other options are possible, also see the grib_api website for more detailed documentation.
--enable-vector option should be used on vector based computers (e.g. NEC). Grib_api will then use a more efficient packing/unpacking method suitable for vector hardware. n.b. there is a bug in the 1.9.18 release that if the --disable-vector option is used, this has the reverse effect of enabling the vector code. See grib_api issue GRIB-269 for more details.
--disable-numpy option should be used if python is enabled but configure can't find the NumPy package.
Shared and static libraries
grib_api will build both shared and static libraries by default. Shared libraries may need to be built if the python interface is used, depending on your installation.
Some compilers will link to the shared version by default if both are found (e.g. the GNU compiler). Alternately, the option --disable-shared stops the shared libraries from being generated, only the static libraries are built and will be linked. However, this may prevent other grib api tools working and is not generally recommended.
Choice of compiler and options
By default, cmake and configure will use the preferred compiler and set appropriate compiler options accordingly (for cmake, this depends on the build type).
This may not be what you need if you have multiple compilers available and want to direct cmake/configure to the most appropriate one to use. In the above example, we enforce the use of the GNU C and Fortran compilers. If you intend to use other compilers with OpenIFS you will need to set these appropriately.
Recommended options are conservative to ensure stability and bit-reproducibility. The cmake and configure commands usually choose a sensible set of optimized compiler flags for the choice of supported compiler for the 'Bit' build type.
Changing compiler options is not normally necessary. However, the following examples show the recommended compiler options and how to set them for the cmake and configure commands.
export CC=gcc export FC=gfortran cmake .... -DCMAKE_C_FLAGS="-g -O2" -DCMAKE_Fortran_FLAGS="-g -O2"
export CC=icc
export FC=ifort
cmake ... -DCMAKE_C_FLAGS="-g -O1 -fp-model precise" \
-DCMAKE_Fortran_FLAGS="-g -O1 -fp-model precise"
export CC=cc
export FC=ftn
cmake ... -DCMAKE_C_FLAGS="-O1 -G2 -hflex_mp=conservative -hadd_paren -hfp1" \
-DCMAKE_Fortran_FLAGS="-O1 -G2 -hflex_mp=conservative -hadd_paren -hfp1"
export CC=xlc_r
export FC=xlf90_r
cmake ... -DCMAKE_C_FLAGS="-g -O2 -qstrict -qarch=auto -qtune=auto" \
-DCMAKE_Fortran_FLAGS="-g -O2 -qstrict -qarch=auto -qtune=auto"
export CC=gcc export FC=gfortran export CCFLAGS="-g -O2" export FCFLAGS="-g -O2" ./configure ...
export CC=icc export FC=ifort export CFLAGS="-g -O1 -fp-model precise" export FCFLAGS="-g -O1 -fp-model precise" ./configure ...
export CC=cc export FC=ftn export CFLAGS="-O1 -G2 -hflex_mp=conservative -hadd_paren -hfp1" export FCFLAGS="-O1 -G2 -hflex_mp=conservative -hadd_paren -hfp1" ./configure ...
export CC=xlc_r export FC=xlf90_r export CFLAGS="-g -O2 -qstrict -qarch=auto -qtune=auto" export FCFLAGS="-g -O2 -qstrict -qarch=auto -qtune=auto" ./configure ...
Intel compiler
We currently recommend not using a higher optimization level than -O1 with the Intel compiler. Failures have been seen with grib_api and the Intel compiler when compiled with -O2.
IBM compiler
For the IBM xlc compiler we recommend disabling the creation of 'shared libraries' which is known to cause problems with some versions of grib_api.
In this example, note the use of the '_r' form of the IBM compiler to ensure grib_api is compiled 'thread-safe'.
Compiling, checks and installing
After configuration the next steps are to compile grib-api and install it. To compile grib_api do:
make | tee make.out
which will send all the output from the make command to the file 'make.out' as well as the terminal. This is recommended as the output is lengthy.
Parallel make
If your computer has multiple cores as many, use the -j flag to make to build grib_api faster. e.g.
make -j 3 | tee make.out
Next, to verify grib_api works correctly run:
make check | tee check.out
Verify that all the grib_api tests have passed. If not, go back and check your configure options. In case of difficulty, contact Software.Support@ecmwf.int.
Building on High Performance Computer systems
Some HPC batch systems have a different hardware architecture for their login (or frontend node) to the batch node, but the frontend compilation system is targeted at the batch nodes. This is known as cross-compilation. If this is the case you may see failures in the 'make check' stage because the checks, although compiled for the backend batch nodes, are being run on the frontend nodes and therefore may not work correctly. If this is the case on your system, we recommend using a batch job to do the 'configure; make; make check; make install' steps.
In some cases, the batch system cannot be used for compilation at all. In this case, you have to compile on the frontend but without extra flags 'configure' will assume the build is for the frontend. You can make use of the --host option to ensure the build is correct for the architecture of the batch system. Again though, the tests will fail, a small serial batch job is recommended to make sure grib_api is installed correctly.
Note if you plan on using the grib_api software in your own software that runs on the frontend nodes you will need to install grib_api twice; one for the batch system and again for the frontend system.
If you have any questions installing grib_api in this type of environment, please contact: openifs-support@ecmwf.int for assistance.
Finally, to install grib_api do:
make install | tee install.out
At the end of this step, in the directory $HOME/ecmwf/ we are using in this example you should now have a directory called grib_api (or some other compiler suffix) which contains the following:
% ls grib_api bin include lib share % ls grib_api/lib libgrib_api.a libgrib_api.la libgrib_api_f77.a libgrib_api_f77.la libgrib_api_f90.a libgrib_api_f90.la pkgconfig
After this stage, next steps are to download and install FCM and then download the OpenIFS code and accompanying files.
Verify the installation
To verify that the installation was successful, first ensure that the grib_api bin directory is added to your PATH environment variable and then run the grib_info command e.g.
% export PATH=$PATH:$HOME/ecmwf/grib_api_gcc/bin % grib_info grib_api Version 1.14.0 Default definition files path is used: ..../grib_api_gcc/share/definitions Definition files path can be changed setting GRIB_DEFINITION_PATH environment variable Default SAMPLES path is used: ..../grib_api_gcc/share/samples SAMPLES path can be changed setting GRIB_SAMPLES_PATH environment variable
If the installation was successful, grib_info will report the installation directories. Any problems, please contact openifs-support@ecmwf.int.