NTCC modules library reviewer: Jon Kinsey, 19-Oct-2000 Summary Recommendation: The EZCDF module functions as described and has been tested with Netcdf v3.4. I suggest that it is approved by the committee. General Comments: EZCDF consists of a set of routines that provides an simplified interface to allow easy implementation into any code. This simplified interface does, however, have some limitations including: units, labels, scale factors, etc., are not currently supported, it only allows writes of integers, real*4, real*8, and character variables. Arrays of up to rank three are presently supported. I tested the module on Pentium-based Linux and HP-UX systems without any problems once the paths were correctly established for Netcdf v3.4. EZCDF has been implemented in the XPTOR transport code and is routinely being used. The four basic steps for writing data are: USE cdfGenPut INTEGER cdfid INTEGER, DIMENSION(3) :: dimlens=(/1,1,1/) CHARACTER*80 file CHARACTER*4 xtype ! Create file CALL cdfOpn(cdfid,file,'w') ! Define type and rank of varname CALL cdfDefVar(cdfid,'varname',dimlens,xtype) ! Write var CALL cdfPutVar(cdfid,'varname',var) ! Close file CALL cdfCls(cdfid) The reading follows closely the writing except that 'w' should be replaced by 'r', cdfDefVar becomes cdfInqVar and cdfPutVar becomes cdfGetVar. In the above example xtype can be either 'INT', 'R4", 'R8' (=double on most computers) or 'CHAR'. Note that the name of cdfPutVar does not change with the type of var, which can be INTEGER, REAL*4, REAL*8 or CHARACTER. The vector dimlens denotes the dimension(s) of var. Note: If a mixture of 1d and 2d quantities are being written to a given CDF file, it is important to make sure that dimlens is set properly before cdfDefVar is called. For example, if a set of real*8 1d variables on a 50pt grid are written followed by a number of real*8 2d variables, the coding would like something like dimlens(1)=50 ! dimension of 1D real arrays call cdfDefVar(cdfid,'rho',dimlens,'R8') c dimlens(1)=50 ! spatial dimension dimlens(2)=nsteps ! time dimension call cdfDefVar(cdfid,'te_t',dimlens,'R8') call cdfDefVar(cdfid,'ti_t',dimlens,'R8') c call cdfPutVar(cdfid,'rho',rho) call cdfPutVar(cdfid,'te_t',te_t) call cdfPutVar(cdfid,'ti_t',ti_t) GENERAL STANDARDS Standard: Provide source code for each physics module or code Done Standard: Provide script to compile and link (e.g., Makefile). The script should make at least some provision for portability to multiple brands of UNIX (at minimum). Provide clear documentation (possible in the README file) on how to use the script or Makefile. Installation script exists and works on various UNIX platforms. Clear documentation is included in the README file Standard: Provide a README file giving (a) the name of the module and its authors, (b) the location and form of general module documentation, and (c) information (or pointer to more detailed documentation) enabling a user to build binaries from the source code. A README file exists with detailed information about the module. Since this is a perl script, item (c) does not apply here. Standard: Provide documentation about how the module should be used, for example whether the module needs to be initialized or used sequentially. Important usability issues, such as the existence of state information in COMMON or other static memory, which persists between calls, must be described. Instructions about how the utilities should be used are included in the README file. Also, f77 and f90 test routines are included in order to test the utilities. Standard: Eliminate graphics calls embedded in physics modules. N/A Standard: The source code files (e.g. *.f, *.c, or *.cpp files) should be submitted rather than requiring extraction from another file. Done Standard: Authors may upgrade their modules with approval of the current chairperson of the NTCC modules committee. If the upgrade is extensive, the chairperson can require that the upgrade be subject to a full review. OK Goal: Multi-platform portability (code should run on different computers) The utilities run on multiple brands of UNIX Goal: Provide error checking (but not stops). Some error checking exists. Goal: Portability (code should run in different environments, e.g., different operating systems). Only UNIX is confirmed. Goal: Minimize external dependencies that cost money (i.e., avoid using expensive proprietary licenses). The only external programs that are required (perl, gmake, gcc) are freely available for almost all UNIX platforms. Goal: Supply warnings in the documentation when the above goal has not been met. OK Goal: Arrays should be dynamically allocated. N/A Standard: The characteristics of I/O should be clearly documented (i.e. the implementation of I/O unit numbers, if any). N/A Goal: Avoid using hard-wired I/O unit numbers. Allow informational output to be switched on or off. Provide a method for rerouting warning or error message output to a user specified file or I/O unit number. N/A DOCUMENTATION STANDARDS Standard: Provide name of contact person for support. OK. C. Ludescher (transp_support@pppl.gov) and A. Pletzer (pletzer@pppl.gov) Standard: Provide date of last revision. Included in the README file Standard: Provide at least comments describing module or code, citations to publications (if any), and range of validity. Done Standard: Specify the precision of floating point calculations. Module only allows writes of integers, real*4, real*8, and character variables. Standard: Provide the index of input-output variables for each module (include types of variable, dimension, units). N/A Standard: List dependencies - names of external routines called. N/A Standard: Provide statement of known bugs. No known bugs are listed. Goal: Index of modules, routines, variables. N/A Goal: Publication of code or module in journal (such as Computer Physics Communications). N/A Goal: Online hyper-text reference documentation. N/A Goal: Interactive online help menus. N/A. However, a man page is available. DATA STANDARDS Goal: Provide interface routines to data. Requires NetCDF library. See http://www.unidata.ucar.edu/packages/netcdf. Goal: Use self-describing data files (such as NetCDF) OK Goal: Use public domain, portable, available and well-documented data file formats. N/A Goal: Establish standards for variable names, units, dimensions, independent variables and grid descriptions as they appear in the module interfaces. N/A -- Jon E. Kinsey (Research Physicist) General Atomics Fusion Group P.O. Box 85608 San Diego, CA 92186 Work Phone: (858) 455-3336 Home Phone: (858) 536-1439 Fax: (858) 455-3586