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