Review report of PSPLINE module by Wayne Houlberg: Summary Recommendation: I recommend that the PSPLINE/EZSpline package of routines be accepted for inclusion in the NTCC Library. There have been several modifications since the original submission, including improvements in the basic 1-D spline fitting routines and the addition of the EZSpline F90 interface. Because of the extensive use of 1-D, 2-D and 3-D interpolation in plasma physics problems, the suite of routines in this library are a very valuable set of tools, which are more extensive than found in existing libraries. However, a user looking for specific source code for a specific application (e.g., all the routines to solve a 2-D bicubic interpolation with a periodic BC in the first dimension, and a specified derivative BC on the LHS and not-a-knot BC on the RHS in the second dimension, in double precision on a 32 bit platform) will have to wade through hundreds of routines and nearly 200 files to gather that information. In other words, there are improvements that could be made in the organization and documentation to facilitate the type of user that has to know what is inside a black box (e.g., me - W.A. Houlberg). Inside this black box is a maze. The nice thing about this library is that Doug McCune is willing to help anyone with more specific needs identify the routines he needs to extract. ============================================================================= National Transport Code Modules Library Standards Form and Checklist. --------------------------------------------------------------------- Fill in the blank areas with comments on the code, relating to the indicated NTCC modules library code standard or goal... ============================================================================= Space is provided here for general comments. ----------------------------------------------------------------------------- This is a extensive collection of cubic spline and Hermite polynomial interpolation routines for 1-D, 2-D, and 3-D datasets on rectilinear grids. Although the basic 1-D routines mostly evolved out of what is available in the literature and other libraries, the 2-D and 3-D routines are more unique and valuable tools for many aspects of plasma computation. The EZSpline F90 interface is a step in the direction of standardizing and modernizing the library. Both single and double precision versions of all routines are included. ============================================================================= ** GENERAL STANDARDS ** ============================================================================= Standard: Provide source code for each physics module or code. ----------------------------------------------------------------------------- OK ============================================================================= Standard: Provide test case(s) with driver program(s) with input and output data and their documentation. ----------------------------------------------------------------------------- Although the test cases do not test all the routines in the library, they cover a large fraction of them and their options. ============================================================================= 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. ----------------------------------------------------------------------------- OK ============================================================================= 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. ----------------------------------------------------------------------------- Documentation includes text and HTML files ============================================================================= 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. ----------------------------------------------------------------------------- OK ============================================================================= Standard: Eliminate graphics calls embedded in physics modules ----------------------------------------------------------------------------- A separate MATLAB program is provided for viewing interpolate results ============================================================================= Standard: The source code files (e.g. *.f, *.c, or *.cpp files) should be submitted rather than requiring extraction from another file. ----------------------------------------------------------------------------- OK ============================================================================= 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 - some upgrading occurred during the review process ============================================================================= Goal: Multi-platform portability (code should run on different computers). ----------------------------------------------------------------------------- There may be a problem trying to use 'double precision' in the EZSpline routines on 64-bit machines because of the mixture of REAL*8 and KIND declarations. The 'single precision' options are reported to work on a Cray ============================================================================= Goal: Provide error checking (but not stops). ----------------------------------------------------------------------------- OK ============================================================================= Goal: Portability (code should run in different environments, e.g. different operating systems). ----------------------------------------------------------------------------- The test cases have been run under VMS and UNIX, and I tested them under Compaq Visual Fortran on a PC ============================================================================= Goal: Minimize external dependencies that cost money (i.e. avoid using expensive proprietary licenses). ----------------------------------------------------------------------------- OK - no external dependencies ============================================================================= Standard: Supply warnings in the documentation when the above goal has not been met. ----------------------------------------------------------------------------- OK ============================================================================= Goal: Arrays should be dynamically allocated. ----------------------------------------------------------------------------- The EZSpline F90 interface uses dynamic allocation ============================================================================= Standard: The characteristics of I/O should be clearly documented (i.e. the implementation of I/O unit numbers, if any). ----------------------------------------------------------------------------- OK ============================================================================= 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. ----------------------------------------------------------------------------- Unit numbers are hard-wired, but only in test driver routines ============================================================================= ============================================================================= ** DOCUMENTATION STANDARDS ** ============================================================================= Standard: Provide name of contact person for support. ----------------------------------------------------------------------------- OK ============================================================================= Standard: Provide date of last revision. ----------------------------------------------------------------------------- OK ============================================================================= Standard: Provide at least comments describing module or code, citations to publications (if any), and range of validity. ----------------------------------------------------------------------------- OK ============================================================================= Standard: Specify the precision of floating point calculations. ----------------------------------------------------------------------------- A lot of effort went into providing both 'single' and 'double' precision versions ============================================================================= Standard: Provide the index of input-output variables for each module (include type of variable, dimension, units). ----------------------------------------------------------------------------- OK ============================================================================= Standard: List dependencies -- names of external routines called. ----------------------------------------------------------------------------- The library is extensive and it took a lot of effort for me to generate an internal dependency tree to identify specific routines used under various options. Because the PSPLINE library is designed to be used as a library and not a collection of source routines to be extracted for specific applications, it takes effort to identify all the routines needed for any given application. Streamlining the routines and providing documentation for a breakdown by application must be left to an upgrade at this time. ============================================================================= Standard: Provide statement of known bugs. ----------------------------------------------------------------------------- No known bugs - some deprecated Fortran coding was removed during the review process ============================================================================= Goal: Index of modules, routines, variables. ----------------------------------------------------------------------------- HTML documentation through the NTCC Web site ============================================================================= Goal: Publication of code or module in journal (such as Computer Physics Communications). ----------------------------------------------------------------------------- Many of the routines have references to original publications ============================================================================= Goal: Online hyper-text reference documentation. ----------------------------------------------------------------------------- OK - but not all of it is distributed with the source, so the user has to go through the Web to get it from the server ============================================================================= Goal: Interactive online help menus. ----------------------------------------------------------------------------- No ============================================================================= ============================================================================= **DATA STANDARDS** ============================================================================= ============================================================================= Goal: Provide interface routines to data. ----------------------------------------------------------------------------- NA ============================================================================= Goal: Use self-describing data files (such as NetCDF). ----------------------------------------------------------------------------- EZSpline uses the EZcdf library ============================================================================= Goal: Use public domain, portable, available and well-documented data file formats. ----------------------------------------------------------------------------- OK ============================================================================= Goal: Establish standards for variable names, units, dimensions independent variables and grid descriptions as they appear in the module interfaces. ----------------------------------------------------------------------------- Useful conventions were established in many of the routines (e.g., specification of BC's and structure of the arrays carrying the spline coefficients and return values). These conventions were carried much further in the EZSpline package to facilitate function overloading. ============================================================================= Wayne A. Houlberg Senior Research Staff Fusion Energy Division Oak Ridge National Laboratory P.O. Box 2009, MS 8071 Oak Ridge, TN 37831-8071 Phone (865) 574-1350 Fax (865) 576-7926 E-Mail houlbergwa@ornl.gov *************************************************** General Atomics 13-308a P.O. Box 85608 San Diego, CA 92186-9784 Ph: (858) 455-3336 Fax: (858) 455-3586