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, grib_api might be installed in your home directory. 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.
Download grib_api
In this example, assume you have created a directory called '$HOME/ecmwf in which you will download and compile grib_api.
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:user): openifs 331 User openifs OK. Password required Password: ftp> cd src/grib_api ftp> get grib_api-1.9.18.tar.gz ftp> quit
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
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_1.9.18 CC=gcc FC=gfortran \ CCFLAGS="-g -O2 -m64 -march=native" FCFLAGS="-g -O2 -m64 -march=native" \ ./configure --prefix=../grib_api_gcc --enable-pthread --disable-jpeg
Note the use of the backslash '\' to allow the command to use two lines.
A quick description of what these options are for:
--prefix=../grib_api_gcc | This specifies where you want the grib_api files to be installed. In our example here, the source code is in $HOME/ecmwf/grib_api_1.9.18 and we will put the compiled grib_api libraries in our example directory $HOME/ecmwf/grib_api_gcc. 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. Again, this is normally the default but we enforce it here as OpenIFS will call grib_api from parallel threads. |
--disable bug in 1.9.18
There is a known bug with 1.9.18 grib_api that when the --disable-<feature> (e.g. --disable-vector) option is used, it has the reverse effect and actually enables the option. In most cases the default option is the preferred one. Any issues or questions can be sent to openifs-suppport@ecmwf.int.
Other options
The --help option to configure can be used to see what other options are possible, also see the grib_api website for more detailed documentation.
The --enable-python option enables the python interface and is optional but might be useful if you intend to use/write software to access the GRIB output files. If the make fails because of a missing numpy header file you should add the --disable-numpy option.
The --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.
Shared and static libraries
grib_api will build both shared and static libraries by default. Shared libraries need to be built if the python interface is used.
Some compilers will link to the shared version by default if both are found (e.g. the GNU compiler). To ensure the correct version of grib_api is found (in case several are available on your system), OpenIFS explicitly lists the static library in the FCM configuration files. Alternately, if you prefer to use the shared library, you must ensure that your LD_LIBRARY_PATH variable is set so that 1.9.18 version compiled here is found first. 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, 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.
CC=icc FC=ifort \ CFLAGS="-g -O2 -m64 -fp-model precise" FCFLAGS="-g -O2 -fp-model precise" \ ./configure --prefix=../grib_api_icc --enable-pthread --disable-jpeg
CC=pgcc FC=pgf90 \ CFLAGS="-g -O2 -m64" FCFLAGS="-g -O2 -m64" \ ./configure --prefix=../grib_api_pgcc --enable-pthread --disable-jpeg
CC=xlc_r FC=xlf90_r \ CFLAGS="-g -O2 -qstrict -qarch=auto -qtune=auto" FCFLAGS="-g -O2 -qstrict -qarch=auto -qtune=auto" \ ./configure --prefix=../grib_api_xlc --enable-pthread --disable-jpeg
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
The 'configure' command 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.
Parallel make
If your computer has multiple cores as many do these days, use the -j flag to make to build grib_api faster. e.g.
make -j 3 | tee make.out
would allow make to compile 3 files at once - appropriate on a 4 core machine.
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/grib_api we are using in this example you should now have a directory called 'grib_api_gcc' (or some other compiler suffix) which contains the following:
% ls grib_api_gcc bin include lib share % ls grib_api_gcc/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.