GENIE Using netCDF

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 the choice between Fortran77 and Fortran90--there are different libraries for the two languages.

Quickstart

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 upto date copy of the NetCDF libraries.

1. First of all unpack the gzipped tar file which you downloaded, e.g. tar -xzf netcdf-3.6.0-p1.tar.gz
2. Change directory to that containing the source code, e.g. cd netcdf-3.6.0-p1/src
3. 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:
   • export CC=gcc
   • export FC=ifort
   • export CPPFLAGS="-DpgiFortran"
4. Now run the configure script. You can use the "--prefix" option to choose where to install the libraries. For example, "--prefix=/opt/local" will cause files to be placed in /opt/local/lib, opt/local/bin and /opt/local/include.
5. Finally run make and then make install.
6. 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 and doesn't seem to be an issue. Now, if you compiled your NetCDF libraries with one compiler and the GENIE source code with another, you will get errors. In particular, you will get errors about 'unresolved symbols'--decorated subroutine names etc. are often referred to as symbols. This is because compiler A might expect symbols to look like myname_, wheeras compiler B might expect myname__ and hence you can expect trouble.

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

1. Make sure you use the same compiler for both the NetCDF libararies and GENIE.
2. Use an argument to your compiler to 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 elect for the second approach, 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.