The NcdfUtilities package

The NcdfUtilities package contains Fortran modules that you can use to write data to and read data from netCDF files. This package is contained within GEOS-Chem (in the NcdfUtil/ folder, but may also be downloaded as a separate standalone package.

NcdfUtilities as a standalone distribution

The following sections describe

=== ties Directory Structure:

Standalone directory structure

If you download the NcdfUtilities as a standalone package, the root-level directory will contain the following sub-directories:

Sub-directory	Description
Code/	The Fortran source code files (*.F *.F90) reside here.
bin/	The TestNcdfUtilities.x executable will be created here.
doc/	The NcdfUtilities documentation will be created here.
lib/	The NetCdfUtilities library file (libNcUtils.a) will be created here.
mod/	Compiled module files (*.mod) will be created here.
perl/	Several perl scripts that can be useful in creating netCDF files are contained here.

System requirements for using NcdfUtilities

1. In order to use NcdfUtilities, you will first have to check to see if the netCDF library is installed on your system. You may find that there are several netCDF library versions to select from. Or you can ask your IT staff to build you a version.

2. In order to build the reference documents (described below), you must have the LaTeX utilities (i.e. latex, dvips, dvipdf) installed on your system.

Setting enviroment variables for the standalone NcdfUtilities package

The NcdfUtilities library requires that you set the following environment variables listed below in your system startup file (e.g. .bashrc or .cshrc).

NOTE: If you load a netCDF library into your Unix environment with the module command, then very often the root path to the netCDF library will be automatically set for you. Then you can use this to define the variables listed below. Ask your IT staff for more information.

Variable	Description
NETCDF_BIN	The bin/ folder of the netCDF installation, where utilities such as nc-config, ncdump, etc. are stored.
NETCDF_INCLUDE	The include/ folder of the netCDF installation, where the netcdf.inc and netcdf_mod.F90 are found.
NETCDF_LIB	The lib/ or lib64/ folder of the netCDF installation, where the netCDF library files (e.g. libnetcdf.a) are found.

NOTE: In netCDF-4.2 and higher versions, the netCDF Fortran libraries are built from a separate distribution. If on your system, the netCDF-Fortran libraries have been installed into a different folder than the rest of the netCDF libaries, you will also need to set these environment variables in your system startup file:

Variable	Description
NETCDF_FORTRAN_BIN	The bin/ folder of the netCDF-Fortran installation, where utilities such as nf-config is stored.
NETCDF_FORTRAN_INCLUDE	The include/ folder of the netCDF-Fortran installation, where the netcdf.inc and netcdf_mod.F90 are found.
NETCDF_FORTRAN_LIB	The lib/ or lib64/ folder of the netCDF-Fortran installation, where the netCDF-Fortran library files (e.g. libnetcdff.a) are found.

--Bob Yantosca (talk) 18:43, 8 March 2017 (UTC)

Compiling the NcdfUtilities Library

The NcdfUtilities/Code directory contains the Fortran source code modules as well as two Makefiles (named Makefile and Makefile_header.mk).

The file "Makefile_header.mk" is a sub-makefile which is used to define the compilation options for different compilers. At present, the ifort, gfortran, and pgfortran compilers are supported.

Once you have set the proper environment variables for your system (as described above), you are ready to build the executable. Make sure you are in the Code/ subdirectory and type:

  make lib

This should start building the source code and create a library file named "libNcUtils.a" in the lib/ subdirectory.

Testing the NcdfUtilities Library

Once the "libNcUtils.a" file has been created in the lib/ subdirectory, you can test to see if the library was created (and can link to) the netCDF library correctly. Type:

  make check

This will create an executable file named "TestNcdfUtilities.x" in the bin subdirectory, and will also execute the file. If the libNcUtils.a library was installed correctly you should see the following output:

  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  %%%  Testing libNcdfUtilities.a  %%%
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  === Begin netCDF file creation test ===
  Writing XDim (# lons)   to netCDF file
  Writing YDim (# lats)   to netCDF file
  Writing ZDim (# alts)   to netCDF file
  Writing LON  (1D array) to netCDF file
  Writing LAT  (1D array) to netCDF file
  Writing PLEV (1D array) to netCDF file
  Writing PS   (2D array) to netCDF file
  Writing T    (3D array) to netCDF file
  === End netCDF file creation test ===
  === Begin netCDF file reading test ===
  Reading XDim back from netCDF file...........PASSED
  Reading YDim back read from netCDF...........PASSED
  Reading ZDim back from netCDF file...........PASSED
  Reading LON  back from netCDF file...........PASSED
  Reading LAT  back from netCDF file...........PASSED
  Reading PLEV back from netCDF file...........PASSED
  Reading PS   back from netCDF file...........PASSED
  Reading T    back from netCDF file...........PASSED
  === End of netCDF file read test! ===

If all of the tests return with "PASSED" then the libNcUtils.a file was created correctly and you have

Building the NcdfUtilities Reference Documentation:

Building

The NcdfUtilities Fortran source code and Makefiles use the ProTeX automatic documentation system. This enables you to create reference documents in *.pdf and *.ps format from the comments in the subroutine headers.

To build the reference documents, make sure you are in the doc/ subdirectory, then type:

  make doc

This will create the following documents in the doc/ subdirectory:

  NcdfUtilities.pdf               
  NcdfUtilities.ps
  NcdfUtilities.tex

-- Reference document for the NcdfUtilities Fortran code

          in *.pdf, *.ps, and LaTeX formats

  NcdfUtilities_Makefiles.pdf
  NcdfUtilities_Makefiles.ps
  NcdfUtilities_Makefiles.tex

-- Reference document for the NcdfUtilities Makefiles

          in *.pdf, *.ps, and LaTeX formats

The reference documents contain a description of each subroutine and function, the variables that are passed to it as input & output arguments, and the revision history. The Makefile reference document displays the full text of the Makefiles. These documents will come in handy if you need to modify or update the Fortran code or Makefiles.

If you wish to remove the NcdfUtilities reference documentation files, then make sure you are in the doc directory and type:

  make clean

--Bob Yantosca (talk) 18:45, 8 March 2017 (UTC)

Cleaning up

To remove all of the *.o, *.mod and executable file in the Code/ subdirectory only, type:

  make clean

However, if you wish to also remove the contents of the bin/ and lib/ subdirectories (as well as removing the *.ps, *.pdf, and *.txt files from the doc/ subdirectory), then type:

  make realclean

--Bob Yantosca (talk) 18:46, 8 March 2017 (UTC)