GENIE Using netCDF

Quickest Possible Start

cd genie/genie-main
make netcdf

This will download the NetCDF library source code and compile, using the compiler selections in user.mak. Once built, the libraries will be placed in the NETCDF_DIR, also set in user.mak.

What is NetCDF? and why use it?

NetCDF is fast becoming the de facto standard format for storing climate model data. It is a 'platform independent' format and so is good for sharing data between members of the community. The format is also flexible in what can be stored and self-documenting--two more very useful features. There is of course some overhead in learning any new file format, but I believe that using NetCDF is well worth the relatively small amount of effort (honest) involved.

Data are stored in NetCDF in the form of variables. These can have dimensions and other attributes. A NetCDF file is split into two main sections; (i) a header, which describes all the variables, dimensions and attributes; and (ii) the data part in which, well, the data is stored (ahem).

In order to read and write data to and from a NetCDF file, we must tell our programs how to do it. To do this fro scratch each time would be both tedious and a waste of time. Luckily the kind folks at Unidata make a high-level interface available which we can use in our programs. This is distributed in the form of a library which we can link to our programs. (They produce libraries for a number of languages such as F77 and F90, C and C++.)

Obtaining the NetCDF Libraries

You can download the source code for the NetCDF libraries from the Unidata NetCDF web page. Note for older versions of the libraries, there is a choice of download between Fortran77 and Fortran90--i.e. there were different libraries for the two languages. For more recent versions however, one downloa fits all:

wget http://www.unidata.ucar.edu/downloads/netcdf/ftp/netcdf-4.0.tar.gz

Compiling the NetCDF libraries

The Unidata webpage contains links to documentation describing installing and using the libraries. However, the quickstart below, may be enough to get you going. Note that it's far easier if you use the same fortran compiler to compile both GENIE and the NetCDF libraries. If you do not, then you will need to become familiar with compiler options which deal with the topic of "name mangling" (enough said). Note that you will also most likely fair better with an up-to-date copy of the NetCDF libraries. The libraries are written in C and Fortran. You need to set some environment variables to tell the installation process which compilers you are using. On my Linux system, using gcc to compile the C code and ifort for the Fortran, I typed the following in my bash shell:

tar -xzf netcdf-4.0.tar.gz
cd netcdf-4.0
./configure --prefix=${HOME}/netcdf/4.0 FC=gfortran CC=gcc CXX=g++ CPPFLAGS="-DpgiFortran"
make
make check
make install

Check that you have the created all the files you need. You should see libnetcdf.a in the your installation lib directory. For Fortran90 support, you will also need netcdf.mod in the include directory.

Linking with GENIE

Once you have compiled the NetCDF libraries, you must make them available to GENIE. To do this, you will need edit genie-main/user.mak. If you followed the example above, you should edit the line begining NETCDF_DIR= to be NETCDF_DIR=/opt/local.

If you get Compilation Errors

If you have followed the guidelines above and you still find you get errors compiling GENIE, then it is likely that these are due to something called name-mangling. When I compiler creates object code from source code (you will see .o files created from .f files, for example--.o stands for 'object'), it mangles or decorates the names of functions, subroutines etc. typically with a number of leading or trailing underscores. This is all fine and dandy--so long as the decorated names, or symbols, match between your program and your library. If different compilers were used to compile your NetCDF libraries and GENIE, then you will get a mismatch, and errors about unresolved symbols, i.e. compiler A might work with symbols like myname_, wheeras compiler B might expect myname__ and hence we get trouble.

If you are in this situation, you can do one of several things:

1. Make sure you use the same compiler for both the NetCDF libararies and GENIE.
2. If (1) is true and you are using the g95 compiler, you will need to add -fno-second-underscore to the Fortran compilation flags for both the NetCDF libs and GENIE
3. If you can't satisfy (1) an argument to your compiler (such as in 2) can change the way it mangles names so that you can match the symbols in your NetCDF libraries to those expected when compiling GENIE.

If you must use different compilers, you will find the UNIX command line tool nm useful for examing the contents of object files and libraries, e.g. nm path_to_netcdf_lib or nm path_to_a_genie_object_file. Determine the form of decoration and provide the appropriate options to the compiler.