Introduction
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.
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.
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 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
or if you 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'.
Compiling grib_api
If you are familiar with compiling and installing software on linux systems, this step will be familiar. 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.
cd grib_api CC=gcc FC=gfortran ./configure --prefix=$(pwd)/install --enable-static --enable-pthread --disable-shared --disable-jpeg --disable-omp-packing --disable-vector
A quick description of what these options are for:
--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, 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).
--disable-omp-packing OpenMP enabled packing is disabled 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 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
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
Things to cover:
- specify compiler choice
- correct options for different compilers
- missing grib templates