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 you try to build OpenIFS on your system. Although you may have a version of grib_api on your system already that would most likely work, it is recommended that you build and install the version of the software provided on the OpenIFS ftp site. This version will have been tested with OpenIFS and known to work.
For more information about grib_api, please visit the grib_api website.
Before you start
Decide where you will put the grib_api package.
For a single user, we recommend installing grib_api in the same directory as the model distribution. For a multi-user environment, say a cluster or High Performance Computing Facility (HPCF), we suggest installing the grib_api package centrally once only and pointing your build configuration to this location.
In the walk-through example that follows, we assume a single-user download and install.
Feeling lucky?
- Download grib_api from OpenIFS ftp site
- ./configure --prefix=<your choice>
- make
- make check
- make install
but read this page if you encounter problems.
Download grib_api
In this example, assume you have created a directory called 'oifs' in which you will download and compile grib_api and the OpenIFS code.
If you haven't already obtained the grib_api package, get it from the OpenIFS ftp site. The userid for ftp is 'openifs'. If you need the password, please email: openifs-support@ecmwf.int. Please note that currently we require a signed license before password access can be granted to the ftp site, though grib_api is freely available from the ECMWF website.
ftp ftp.ecmwf.int Connected to ftp-int.ecmwf.int. Name (ftp.ecmwf.int:nagc): openifs 331 User openifs OK. Password required Password: ftp> cd src/grib_api ftp> get grib_api-1.9.18.tar.gz ftp> close
For versions of grib_api before 1.9.18 you will also need to download and install the oifs_samples.tar.gz file in the src/grib_api directory on the ftp server, because some of the GRIB templates that OpenIFS requires are not present in the 1.9.16 (or previous) distribution. Please see the README file in the grib_api directory for more information.
Unpacking grib_api
To unpack the software:
tar zxf grib_api-1.9.18.tar.gz
or if your version of tar doesn't support the 'z' option, do:
gunzip grib_api_1.9.18.tar.gz tar xf grib_api-1.9.18.tar
In order to make the build configuration generic and make it easier to swap to later versions of grib_api, we recommend creating a link to the version of grib_api:
ln -s grib_api-1.9.18 grib_api
so all future references to this directory will refer to 'oifs/grib_api'.
Configuring grib_api
If you are familiar with compiling and installing software on linux systems, you will be used to the following steps. Grib_api uses the GNU configure tool to ease building and compilation. It is tested on different platforms and compilers and should not cause any problems. If however, you do have a problem installing grib_api, please email: Software.Support@ecmwf.int.
The configure command is contained in the grib_api directory you have just unpacked. We will use the command with a few options to suit OpenIFS and assume we'll use the gcc & gfortran compilers. If you use different compilers, see below.
cd grib_api CC=gcc FC=gfortran ./configure --prefix=$(pwd)/myinstall --enable-static --enable-pthread --disable-shared --disable-jpeg --disable-omp-packing --disable-vector
A quick description of what these options are for:
--prefix=$(pwd)/myinstall | This specifies where you want the grib_api files to be installed. In our example here, we will put the compiled grib_api libraries in our example directory oifs/grib_api/myinstall. If you are on a shared high performance computer facility, the install path would most likely be somewhere central. If you specify nothing for --prefix, by default grib_api will install in /usr/local. |
--enable-static | OpenIFS needs to link with a static library for grib_api (i.e. libgrib.a), so a shared library version is not required. By default both are built but in case defaults change in future releases, better enforce them. |
--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). |
--disable-omp-packing | OpenMP enabled packing is removed as the model needs to have control over OpenMP multithreading. This is usually disabled by default but it's best to enforce it in case the default changes for future releases. |
--disable-vector | Likewise, on vector computer hardware (e.g. NEC), you can enable this option and grib_api will use a more efficient packing/unpacking method suitable for vector machines. |
--enable-pthread | This option ensures that grib_api is thread-safe. Again, this is normally the default but we enforce it here as OpenIFS will call grib_api from parallel threads. |
The --help option to configure can be used to what other options are possible, though see the grib_api website for more detailed documentation.
Choice of compiler and options
By default, grib_api will use the first known compiler it finds (by searching your PATH environment variable). This may not be what you need if you have multiple compilers available. As in the above example, we enforce the use of the GNU C and Fortran compilers (as this is the default compiler for OpenIFS). If you intend to use other compilers with OpenIFS you will need to set these appropriately.
The configure script usually chooses a sensible set of optimized compiler flags for the choice of supported compiler. If you need to override the compiler flags you can do so as shown in the following example. Note also the use of '\' to extend the command over multiple lines.
Intel compiler:
CC=icc FC=ifort \ CFLAGS="-O" FCFLAGS="-O2 -fp-model precise" \ ./configure --prefix=$(pwd)/myinstall --enable-static --enable-pthread --disable-shared --disable-jpeg --disable-omp-packing --disable-vector
IBM compiler:
CC=xlc_r FC=xlf90_r \ CFLAGS="-O" FCFLAGS="-g -O3 -qstrict -qarch=auto -qtune=auto" \ ./configure --prefix=$(pwd)/myinstall --enable-static --enable-pthread --disable-shared --disable-jpeg --disable-omp-packing --disable-vector
In this example, note the use of the '_r' form of the IBM compiler to ensure grib_api is compiled 'thread-safe'. This is important as grib_api will be called by multiple threads with OpenIFS.
Compiling, checks and installing
Configure creates a 'Makefile' in the directory where it resides. 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.
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.
NOTE!
Some HPC systems use a different architecture for their login or frontend node but their compilation system is targeted at the batch nodes. 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 running the 'make check' step in a small batch job to verify grib_api works correctly.
Finally 
, to install grib_api do:
make install | tee install.out
At the end of this step, in the directory oifs/grib_api we are using in this example you should now have a directory called 'myinstall' which contains the following:
% ls myinstall bin include lib share % ls myinstall/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, proceed to downloading the OpenIFS model itself.