Comments by Glenn Bateman on the PPPL U-file Related Utilities: bateman@fusion.lehigh.edu 13 October 1999 The PPPL U-file related utilities are an extensive collection of utilities for reading and writing U-files as well as manipulating and visualizing data. There are hundreds of separate routines in this collection of modules. There is extensive Web page documentation starting at http://w3.pppl.gov/NTCC/Ufiles/ufiles.html This excellent documentation, which is several hundred pages long, is precise and detailed. The "INSTALL" and "README" files (in uinstall.tar) lead the user through the installation and testing procedures. There are a large number of separate utilities in this PPPL package. I evaluated the utilities in the following tar files: sglib.tar Scientific Graphics Library trgraf.tar Interactive Data Display System ufiles.tar U-files module uinstall.tar installation scripts uread.tar Terminal Command System with Scripting and Automation uutil.tar Utilities for display and manipulation of U-file data The modules compiled and ran on Dec, HP, IBM, Sun, and SGI workstations. In order to compile on LINUX, the modules need the commercial Portland Group f77 v1.7, which I did not have available. I did not try DEC VMS, but these modules were originally developed for DEC VMS. In order to run the graphics correctly on the IBM AIX workstation, I had to run xterm rather than aixterm. Alternatively, I was able to use another utility from PPPL called "xtc" (which is available in the module library) to get the graphics to run correctly when running aixterm. Sixteen test programs are provided to demonstrate most of the features in this collection of modules. The feedbacks (text and plots) provided by these test programs are reasonably clear. There is a considerable amount of interconnection between different parts of these modules. The "README" file describes which libraries are needed to use each part of this collection of modules. For example, uread.tar is needed to use the U-files module (ufiles.tar), but the graphics packages are not needed. The authors recommend that each library be kept intact. Overall, this is an impressive collection of modules and documentation. ____________________________________________________________________________ Appended is the form provided by Doug, derived from the latest version of the NTCC Library's Standards and Goals, with item by item checks. I've adopted a MET/NOT MET/UNTESTED/NA grade, with only occasional comments (NA = not applicable). ============================================================================= ============================================================================= ** GENERAL STANDARDS ** ============================================================================= Standard: Provide source code for each physics module or code. ----------------------------------------------------------------------------- MET --- user is encouraged to compile collections of routines into libraries and to keep the libraries intact. ============================================================================= Standard: Provide test case(s) with driver program(s) with input and output data and their documentation. ----------------------------------------------------------------------------- MET --- 16 test cases are provided. Documentation provided on the Web. ============================================================================= 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 (possibly in the README file) on how to use the script or makefile. ----------------------------------------------------------------------------- MET --- INSTALL and README files well written (found in file uinstall.tar). ============================================================================= 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. ----------------------------------------------------------------------------- MET --- INSTALL and README files stored in file uinstall.tar. ============================================================================= 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. ----------------------------------------------------------------------------- MET --- hundreds of pages on Web starting with http://w3.pppl.gov/NTCC/Ufiles/ufiles.html ============================================================================= Standard: Eliminate graphics calls embedded in physics modules. ----------------------------------------------------------------------------- NA Most of this collection of modules is about graphics. The graphics was specifically designed to compile and run on six different UNIX platforms. ============================================================================= Standard: The source code files (e.g. *.f, *.c, or *.cpp files) should be submitted rather than requiring extraction from another file. ----------------------------------------------------------------------------- MET ============================================================================= 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. ----------------------------------------------------------------------------- NA ============================================================================= Goal: Multi-platform portability (code should run on different computers). ----------------------------------------------------------------------------- MET (as much as I could test) The modules compiled and ran on Dec, HP, IBM, Sun, and SGI workstations. In order to compile on LINUX, the modules need the commercial Portland Group f77 v1.7, which I did not have available. I did not try DEC VMS, but these modules were originally developed for DEC VMS. ============================================================================= Goal: Provide error checking (but not stops). ----------------------------------------------------------------------------- MET as much as possible. There are stops in SGLIB. ============================================================================= Goal: Portability (code should run in different environments, e.g. different operating systems). ----------------------------------------------------------------------------- MET (as much as I could test) ============================================================================= Goal: Minimize external dependencies that cost money (i.e. avoid using expensive proprietary licenses). ----------------------------------------------------------------------------- MET except for use of commercial Portland Group f77 v1.7 to compile on LINUX. ============================================================================= Standard: Supply warnings in the documentation when the above goal has not been met. ----------------------------------------------------------------------------- MET ============================================================================= Goal: Arrays should be dynamically allocated. ----------------------------------------------------------------------------- MET ============================================================================= Standard: The characteristics of I/O should be clearly documented (i.e. the implementation of I/O unit numbers, if any). ----------------------------------------------------------------------------- MET --- the user must set the logical unit numbers. ============================================================================= 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. ----------------------------------------------------------------------------- MET ============================================================================= ============================================================================= ** DOCUMENTATION STANDARDS ** ============================================================================= Standard: Provide name of contact person for support. ----------------------------------------------------------------------------- MET ============================================================================= Standard: Provide date of last revision. ----------------------------------------------------------------------------- MET on Web page documentation and updates at the end of each section. ============================================================================= Standard: Provide at least comments describing module or code, citations to publications (if any), and range of validity. ----------------------------------------------------------------------------- NA --- effectively published on Web. ============================================================================= Standard: Specify the precision of floating point calculations. ----------------------------------------------------------------------------- MET --- the system is designed for single precision. ============================================================================= Goal: offer single and double precision versions or offer user control of precision at compile time. ----------------------------------------------------------------------------- NOT MET --- the system is designed for single precision. ============================================================================= Standard: Provide the index of input-output variables for each module (include type of variable, dimension, units). ----------------------------------------------------------------------------- MET in Web pages describing these modules. This documentation is spread out because the collection of modules is so large. ============================================================================= Standard: Provide statement of known bugs. ----------------------------------------------------------------------------- NA ============================================================================= Goal: Index of modules, routines, variables. ----------------------------------------------------------------------------- MET: There is extensive online documentation with tables of the modules and those routines used to access the modules and their argument lists. This documentation is spread out because the collection of modules is so large. ============================================================================= Goal: Publication of code or module in journal (such as Computer Physics Communications). ----------------------------------------------------------------------------- NOT MET --- but documentation on Web pages is an effective means of publication. ============================================================================= Goal: Online hyper-text reference documentation. ----------------------------------------------------------------------------- MET ============================================================================= Goal: Interactive online help menus. ----------------------------------------------------------------------------- NOT MET --- but there is considerable feedback when modules are used. ============================================================================= ============================================================================= **DATA STANDARDS** ============================================================================= ============================================================================= Goal: Provide interface routines to data. ----------------------------------------------------------------------------- MET ============================================================================= Goal: Use self-describing data files (such as NetCDF). ----------------------------------------------------------------------------- MET. U-files are self-describing data files and NetCDF interface is available as an option. ============================================================================= Goal: Use public domain, portable, available and well-documented data file formats. ----------------------------------------------------------------------------- MET ============================================================================= Goal: Establish standards for variable names, units, dimensions independent variables and grid descriptions as they appear in the module interfaces. ----------------------------------------------------------------------------- MET ============================================================================= -- Glenn Bateman (Research Physicist) Lehigh University Physics Department, 16 Memorial Drive East, Bethlehem, PA 18015 USA Phone: (610) 758 5733 (Lehigh office) (610) 758 5730 (Lehigh FAX) http://www.lehigh.edu/~glb4 bateman@fusion.physics.lehigh.edu