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.

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:
 * 4) *export CC=gcc
 * 5) *export CXX=g++
 * 6) *export FC=ifort
 * 7) *export CPPFLAGS="-DpgiFortran"
 * 8) 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.
 * 9) Finally run make and then make install.
 * 10) 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.