Page History

Introduction

...

For more information about grib_api, please visit the grib_api website.

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.

...

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 distribution.

Unpacking grib_api

Detailed build and install instructions for grib_api can be found in the grib_api documentation. This page describes the basic steps needed for an installation for OpenIFS.

To unpack the software:

tar zxf grib_api-1.9.18.tar.gz

...

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, this step you will be familiar. gribused 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.Services@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)/install --enable-static --enable-pthread --disable-shared --disable-jpeg --disable-omp-packing --disable-vector

...

--prefix=$(pwd)/install      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/install. 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 --disable-shared   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 here..

--disable-jpeg                    OpenIFS does not need to support bitmaps in GRIB so this is disabled. This removes the need to link OpenIFS against the Jasper library (libjasper.a).

--disable-omp-packing      OpenMP enabled packing is disabled removed as the model needs to have control over the generation of 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         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. You can. 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)/install --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)/install --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

Once configure has completed it will create a 'Makefile' in the directory. To compile grib_api do:

make >& make.out

which will send all the output from the make command to the file for make.out. This is recommended as the output is lengthy.

For non-bash Shell users, this command might fail in which case do: make 2>&1 make.out.

Next, to verify grib_api works correctly run:

make check >& 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.Services@ecmwf.int.

Things to cover:

• specify compiler choice
• correct options for different compilers
• missing grib templates