NTCC modules library reviewer: Doug McCune 17-Mar-1999 Summary Recommendation: this code is in good shape and should be approved by the committee. Details are presented in the form and checklist, below. National Transport Code Modules Library Standards Form and Checklist. --------------------------------------------------------------------- Fill in the blank areas with comments on the code, relating to the indicated NTC modules library code standard or goal... ============================================================================= Space is provided here for general comments. ----------------------------------------------------------------------------- The modified submission provided by the authors has satisfied the reviewer's concerns about the portability and interface documentation of the earlier release. The updated release was posted to the NTCC website on 17-Mar-1999. (The changes since February pertain to code comments and README text only). mmm95 is a fortran-77 code. All communication with the code is through the subroutine arguments in the call interface. Almost all of the arguments ordinarily touched by users are physics quantities: temperatures, densities, q, gradients as input, transport coefficients, convective velocities, fluxes, mode growth rates and frequencies as output. Although there are extensive model control options (the lswitch and cswitch arrays), these should be defaulted by most users; those needing access to the control options should communicate directly with the authors, as specified in the documentation. The only model option left easily accessible to the ordinary user (not counting array dimensioning and output message control options) is lsuper >0 for supershot simulations =0 for all other discharges. There are no subtle usability issues apparent -- one simply calls the subroutine with appropriate input arguments set. Note that the code does contain some static memory, and should not be considered MPP-safe. It has not been tested for MPP use. If MPP capability is needed, the authors should be consulted. Multiple test datasets are provided in the distribution. The reviewer finds that these tests run correctly on all workstation brands tested: DEC, SGI, SUN, IBM, HP. The makefile is sensibly organized, so that extension to another architecture should be straightforward. Users making makefile changes should communicate these back to the authors, so that these may be posted in a new release to the NTCC website. ================================================================== ** GENERAL STANDARDS ** ============================================================================= Standard: Provide source code for each physics module or code. ----------------------------------------------------------------------------- done. ============================================================================= Standard: Provide test case(s) with driver program(s) with input and output data and their documentation. ----------------------------------------------------------------------------- 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 (possibly in the README file) on how to use the script or makefile. ----------------------------------------------------------------------------- done. ============================================================================= 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. ----------------------------------------------------------------------------- done. ============================================================================= 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. ----------------------------------------------------------------------------- done. ============================================================================= Standard: Eliminate graphics calls embedded in physics modules. ----------------------------------------------------------------------------- done. ============================================================================= 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). ----------------------------------------------------------------------------- multiple brands of UNIX ============================================================================= Goal: Provide error checking (but not stops). ----------------------------------------------------------------------------- nerr return argument ============================================================================= 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). ----------------------------------------------------------------------------- no external dependencies. ============================================================================= Standard: Supply warnings in the documentation when the above goal has not been met. ----------------------------------------------------------------------------- OK ============================================================================= Goal: Arrays should be dynamically allocated. ----------------------------------------------------------------------------- no, this is a fortran-77 code, however, there are no large internal arrays -- essentially all arrays are passed. ============================================================================= Standard: The characteristics of I/O should be clearly documented (i.e. the implementation of I/O unit numbers, if any). ----------------------------------------------------------------------------- this is done. the user can control the f77 i/o unit number and the "level" of message output to this unit number. ============================================================================= 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. ----------------------------------------------------------------------------- done. ============================================================================= ** DOCUMENTATION STANDARDS ** ============================================================================= Standard: Provide name of contact person for support. ----------------------------------------------------------------------------- done. ============================================================================= Standard: Provide date of last revision. ----------------------------------------------------------------------------- in the README and in the mmm95 subroutine comments. ============================================================================= 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. ----------------------------------------------------------------------------- done: double precision via autodouble f77 compiler (or Cray compiler, but reviewer did not test on any Cray machine). ============================================================================= Standard: Provide the index of input-output variables for each module (include type of variable, dimension, units). ----------------------------------------------------------------------------- thorougly done. ============================================================================= Standard: List dependencies -- names of external routines called. ----------------------------------------------------------------------------- no external dependencies -- Weiland model and linear algebra routines are included in the distribution. ============================================================================= Standard: Provide statement of known bugs. ----------------------------------------------------------------------------- no known bugs. ============================================================================= Goal: Index of modules, routines, variables. ----------------------------------------------------------------------------- just input & output arguments -- but the code is well commented, including .tex file description with mathematical notation. ============================================================================= Goal: Publication of code or module in journal (such as Computer Physics Communications). ----------------------------------------------------------------------------- reference [1] of the documentation. ============================================================================= Goal: Online hyper-text reference documentation. ----------------------------------------------------------------------------- none available -- not really needed. ============================================================================= Goal: Interactive online help menus. ----------------------------------------------------------------------------- none available. ============================================================================= ============================================================================= **DATA STANDARDS** ============================================================================= ============================================================================= Goal: Provide interface routines to data. ----------------------------------------------------------------------------- N.A.: no data interface other than calling arguments. ============================================================================= Goal: Use self-describing data files (such as NetCDF). ----------------------------------------------------------------------------- no file i/o other than message output. ============================================================================= 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. ----------------------------------------------------------------------------- not explicitly done.