READING AND WRITING NetCDF FILES: -------------------------------- Feb 6, 1997 HOW TO GET STARTED: ------------------ 1. A suite of "shell" routines has been developed at GFDL to minimize the work required to read and write netCDF files. The "surface area" of contact between the user and netCDF is reduced to a limited number of FORTRAN routines for which the user need only satisfy an argument list. There is no need to make the (many) low-level netCDF API calls. In addition, the use of these routines helps insure a consistent structure which also complies with the COARDS conventions for writing netCDF files. The current "official" version of these routines reside in /home/jps/pub/netcdf/NCIR/src/ Read the files "WHATS_NEW" and "CHANGES_*" there to see what has changed recently. Note: The "Cooperative Ocean-Atmosphere Research Data Service", or COARDS, is a NOAA/university cooperative for the sharing and distribution of global atmospheric and oceanographic research data sets. See file "coards_conventions" for info about these, or point your Web browser at http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html 2. First, note that your code will have to interface with the following subroutines: Writing: ------- Mandatory: ncsetup.F ncstore.F ncdone.F Optional: ncaddatt.F/ncaddcatt.F sincestr.F ncreo1.F ncstrav.F Reading: ------- Mandatory: readnc_1.F Optional: readnc_0.F ncgetatt.F/ncgetcatt.F ncgetav.F ncinfo.F ncymdhms.F nctfind.F Before proceeding any further, look at the documentation at the top of these routines - especially "ncsetup.F" and/or "readnc_1.F" - where you'll find an explanation of all the incoming and outgoing arguments. 3. Next, it'll dawn on you that you are going to have to define, in your code, all those variables required by the argument lists of these routines. Fortunately, this definition has been done for you! The following include files set up all these variables suitable for use as arguments: Writing: nc_stufw.h Reading: nc_stufr.h The only thing you need to do to use these is to first define some parameters that help define the upper limits of some arrays - see the documentation at the top of these .h files. In addition, you may find it convenient to include the file "init_cblanks.h" toward the beginning of your executable code. This will initialize all those CHARACTER variables to blanks - a worthwhile precaution. 4. "Units" for the quantities in your file are important. The COARDS conventions mandate that the *dimensions* (ie, axes) associated with your data be consistent with the Unidata UDUNITS package. These GFDL netCDF interface routines enforce this when writing a file, and specification of units which are not recognized by the UDUNITS package will result in an error. The file "udunits.dat" summarizes the acceptable units; at GFDL, this file can be found at: /usr/local/etc/udunits.dat Non-recognized units for *data* variables are permitted (for now), but a warning is issued. 5. OK, once you've got some code created, you need to coordinate the compile/link process, accessing all the necessary libraries. Again, this is (mostly) done for you in the form of 2 prototype scripts which go through all the motions for some test/demo programs. These scripts work on both the T90 and the SGI's: Writing: prepnc_w.csh Reading: prepnc_r.csh and perform the actual compilation and linking in the predefined (but customizable) directories: T90 : $FTMPDIR/codes/netcdf/test SGI : $WDISK/codes/netcdf/test 6. Examples and helpful tools: - there are a couple of small demo programs in the distribution. These small (?) test programs demonstrate the use of the writing and reading interface routines: test_ncsetup.F test_readnc.F - In building your own codes, you'll find "Flint" to be *very* helpful in keeping the argument lists straight. (for more info on how to use Flint, see the file: "/home/jps/pub/netcdf/README.PUB.COMPILING_LINKING"). - Another tool I've found *VERY* helpful is the "xdbx" debugger. To make the look & feel of xdbx nicer, get some helpful X-resources from "/home/jps/pub/netcdf/.Xdefaults-nc_utils". - If you'd like to see a more substantial code which creates netCDF files, take a look at "/home/jps/codes/to_netcdf/nmc2cdf/nmc2cdf.F" This code converts NMC analysis data (in a very local format!) to netCDF. To see what the resulting files look like (there is a mix of packed and unpacked data), see the items off the directory : "/net/jps/netcdf/sample/NMC/*/" 7. When you have finally succeeded in creating a netCDF file, how do you look at it? Point your *Netscape* browser (Mosaic won't work right) at the GFDL Visualization Guide : http://www.gfdl.noaa.gov/~jps/GFDL_Vis_Guide.html to see a fairly complete summary of 1-, 2-, and 3-D packages which can be used to view netCDF data. "Freud" is a 2D plotting packages with a GUI, and should satisfy most users' basic plotting requirements. You can also use the routines READNC_0 and READNC_1 in your own application codes to access the data in the netCDF file, then plot it as you usually do. 8. Editing netCDF files and extracting data: A number of netCDF file manipulation tools are available, and are also summarized in the GFDL Visualization Guide. I am still assembling a more "comprehensive" tool (ncEdit) for editing the "metadata" of a netCDF file, extracting parts of files, and combining files. Don't forget, you can use the routines READNC_0 and READNC_1 in your own codes to read in netCDF data. If you are anxious to try some of the other tools, contact me. 9. Performance Beginning with version 2.4 of the netCDF distribution, performance on the T90 can be *dramatically* improved, in some cases to the point where it is virtually indistinguishable from flat binary writes. This is accomplished through the use of the FFIO cache layer. Properly configured, wall clock performance and system CP-time can be reduced dramatically. This is particularly important in the case of vertically slabbed models. For more information, see http://www.gfdl.noaa.gov/~jps/txt/README.IO_Optimization.txt or the file (! which may not be updated as often !): /home/jps/pub/netcdf/NCIR/src/README.IO_Optimization If you have any other questions, drop me a line. John P. Sheldon (jps@gfdl.noaa.gov) (609) 987-5053