...
In the walk-through example that follows, we assume a single-user download and install.
Download
...
and unpack
In this example, we assume you have created a directory called $HOME/ecmwf in which you will download and compile grib_api.
...
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:
| Code Block | ||||
|---|---|---|---|---|
| ||||
mkdir -p ecmwf/src cd ecmwf/src tar zxf grib_api-1.14.0-Source.tar.gz |
...
| Code Block |
|---|
gunzip grib_api_1.14.0.tar.gz tar xf grib_api-1.14.0.tar |
Configuring
...
for OpenIFS 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 and instructions below.
CMake compilation must be done is a separate build directory to both the source and the install directory.
| Code Block | ||||
|---|---|---|---|---|
| ||||
cd ecmwf mkdir bld mkdir grib-api cd bld export CC=ccgcc export FC=ftngfortran 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. |
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. |
Configuring grib_api with configure script
Available options
To get additional help on the available options (similar to the 'configure --help' command) run the command:
| Code Block |
|---|
cmake -LH grib_api-1.14.0-Source |
| Info |
|---|
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 for OpenIFS using configure script
Grib_api compilation can also be made using 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: openifs-support@ecmwf.int.
...
| Code Block | ||
|---|---|---|
| ||
cd grib_api_1.9.18 ./configure --prefix=$HOME/ecmwf/grib_api_gcc --enable-pthread --enable-python --disable-jpeg |
Note the use of the backslash '\' to allow the command to use two lines.
...
--prefix | 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.914.180-Source 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. |
| Warning | ||
|---|---|---|
| ||
There is a known bug with 1.9.18 grib_api that when some of the --disable-<feature> (e.g. --disable-vector) or --enable-<feature> options are used, it has the reverse effect and actually enables the option. In most cases the default option is the preferred one. The options used above are known to be safe to use. 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.
| 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 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 detailsGRIB-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 need may 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)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 cmake and configure will use the first known preferred 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 cmake and configure script commands 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
The following examples show the recommended compiler options and how to set them for the cmake and configure commands.
| Code Block | ||
|---|---|---|
| ||
export CC=gcc export FC=gfortran export CCFLAGS="-g -O2" FCFLAGS="-g -O2" \ ./configure --prefix=$HOME/ecmwf/grib_api_gcc --enable-pthread --disable-jpeg-g -O2" export FCFLAGS="-g -O2" |
| Code Block | ||
|---|---|---|
| ||
export CC=icc export FC=ifort export CFLAGS="-g -O1 -fp-model precise" FCFLAGS="-g -O1 -fp-model precise" \ ./configure --prefix=$HOME/ecmwf/grib_api_icc --enable-pthread --disable-jpeg" export FCFLAGS="-g -O1 -fp-model precise" |
| Note |
|---|
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.Intel compiler when compiled with -O2. |
| Code Block | ||||
|---|---|---|---|---|
| ||||
export CC=cc
export FC=ftn
export CFLAGS=
export FCFLAGS= |
| Code Block | ||
|---|---|---|
| ||
export CC=pgcc export FC=pgf90 export CFLAGS="-g -O2" export FCFLAGS="-g -O2" \ ./configure --prefix=$HOME/ecmwf/grib_api_pgcc --enable-pthread --disable-jpeg |
| Code Block | ||
|---|---|---|
| ||
export CC=xlc_r export FC=xlf90_r export \ CFLAGS="-g -O2 -qstrict -qarch=auto -qtune=auto" FCFLAGS="-g -O2 -qstrict -qarch=auto -qtune=auto" \ ./configure --prefix=$HOME/ecmwf/grib_api_xlc --enable-pthread --disable-jpeg --disable-shared=auto -qtune=auto" export FCFLAGS="-g -O2 -qstrict -qarch=auto -qtune=auto" |
| Note |
|---|
For the IBM xlc compiler we recommend disabling the creation of 'shared libraries' which is known to cause problems with this version 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'. This is important as grib_api will be called by multiple threads with OpenIFS. |
Compiling, checks and installing
...
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_gcc (or some other compiler suffix) which contains the following:
| Code Block |
|---|
% 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 |
...