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.
- 1 List of modules
- 2 NcdfUtilities within GEOS-Chem
- 3 NcdfUtilities as a standalone distribution
- 3.1 ===================================================================
- 3.2 ===================================================================
- 3.3 ===================================================================
- 3.4 Compiling the NcdfUtilities Library
- 3.5 Testing the NcdfUtilities Library
List of modules
NcdfUtilities within GEOS-Chem
Setting environment variables for GEOS-Chem
NcdfUtilities as a standalone distribution
The following sections describe
=== ties Directory Structure:
The root-level directory contains these subdirectories:
Code/ : Subdir containing Fortran source code files bin/ : Subdir where the TestNcdfUtilities.x executable will be sent doc/ : Subdir where the NcdfUtilities documentation will be built lib/ : Subdir where the library file libNcUtils.a will be built
NOTE: Each directory also has a "CVS/" subdirectory. This is for the CVS version control system, and does not contain any usable files.
(1) In order to use NcdfUtilities, you will first have to make sure that the netCDF library is installed on your system. Consult with your local sysadmin as to where these libraries are found.
If the netCDF library has not yet been installed on your system, then you (or your local sysadmin) will have to install it. An easy way to do this is to obtain the "Baselibs" package from Bob Yantosca and follow the directions on the GEOS-Chem wiki page:
(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 environment variables:
The NcdfUtilities library requires that you set the following environment variables in your system startup file (e.g. .bashrc or .cshrc):
(1) NETCDF_BIN : The "bin/" folder of the netCDF installation,
where utilities such as nc-config are stored
(2) NETCDF_INCLUDE : The "include" folder of the netCDF installation,
where the netcdf.inc and netcdf_mod.F90 are found.
(3) NETCDF_LIB : The "lib/" or "lib64" folder of the netCDF
installation, where the netCDF library files (ending in *.a) files 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:
(4) NETCDF_FORTRAN_BIN : The "bin/" folder of the netCDF-Fortran
installation, where "nf-config" is found.
(5) NETCDF_FORTRAN_INCLUDE : The "include/" folder of the netCDF-Fortran
installation, where "netcdf.inc" is found.
(6) NETCDF_FORTRAN_LIB : The "lib/" or "lib64/" folder of the
netCDF-Fortran installation, where the library files (ending in *.a) are found.
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:
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:
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:
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:
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:
To remove all of the *.o, *.mod and executable file in the Code subdirectory only, type:
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:
That's it. Good luck and contact me if you have any questions:
Bob Yantosca email@example.com