NTCC module: glf23 Reviewer: Doug McCune Date: 6/29/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 29-Jun-1999. The glf23 module consists of real*8 precision fixed form source fortran-90 code. All communications with the code is through subroutine arguments in the call interface ("callglf2d" subroutine). All arguments are of intrinsic datatypes, so that calling from an f77 or C/C++ driver should pose no great problem. Most arguments are physics quantities; there are a handful of numerical options that are adequately explained in the documentation. There are physics model switches for ExB shear stabilization and for MHD alpha stabilization. There are no subtle usability issues apparent -- one simply calls the subroutine with appropriate input arguments set. The 28-Jun-1999 release of the code (version 1.3 in the authors' nomenclature) includes a new control switch, "leigen". This switch permits selection of either the traditional cgg/eispack solver (leigen=0) or the newly installed tomsqz solver (leigen=1). The latter solver, based on more modern code, yields full precision eigenvector solutions. The older code (cgg) loses some precision, as will be evident comparing runs between different machines, but is retained for compatibility with earlier versions of the code. 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: Portability (code should run on multiple platforms and under different operating systems). ----------------------------------------------------------------------------- tested OK. ============================================================================= Goal: Offer single and double precision versions or offer user control of precision at compile time. ----------------------------------------------------------------------------- real*8 version provided. ============================================================================= Goal: Provide error checking (but not stops). ----------------------------------------------------------------------------- there are no internal stops. the error checking provided is minimal. the user will have to exercise due caution in setting the units of input parameters. ============================================================================= 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. ----------------------------------------------------------------------------- N.A. ============================================================================= Goal: Arrays should be dynamically allocated. ----------------------------------------------------------------------------- partially done. ============================================================================= Standard: The characteristics of I/O should be clearly documented (i.e. the implementation of I/O unit numbers, if any). ----------------------------------------------------------------------------- there is no file i/o. ============================================================================= 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. ----------------------------------------------------------------------------- Done. ============================================================================= Standard: Provide date of last revision. ----------------------------------------------------------------------------- Done. ============================================================================= 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. ----------------------------------------------------------------------------- all floating point numbers are real*8. ============================================================================= Standard: Provide the index of input-output variables for each module (include type of variable, dimension, units). ----------------------------------------------------------------------------- Done. ============================================================================= Standard: List dependencies -- names of external routines called. ----------------------------------------------------------------------------- N.A. -- no external dependencies. ============================================================================= Standard: Provide statement of known bugs. ----------------------------------------------------------------------------- N.A. -- no known bugs. ============================================================================= Goal: Index of modules, routines, variables. ----------------------------------------------------------------------------- no, only the interface is documented. ============================================================================= Goal: Publication of code or module in journal (such as Computer Physics Communications). ----------------------------------------------------------------------------- not done. ============================================================================= Goal: Online hyper-text reference documentation. ----------------------------------------------------------------------------- tex file and readme included with module. No www documentation. ============================================================================= Goal: Interactive online help menus. ----------------------------------------------------------------------------- no. ============================================================================= ============================================================================= **DATA STANDARDS** ============================================================================= ============================================================================= Goal: Provide interface routines to data. ----------------------------------------------------------------------------- N.A. -- subroutine argument list only. ============================================================================= Goal: Use self-describing data files (such as NetCDF). ----------------------------------------------------------------------------- N.A. -- no files. ============================================================================= 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. ----------------------------------------------------------------------------- The interface is reasonably well described; MKS (with KeV for temperatures) is used for physics units. There is no over-arching standard for variable names, etc. =============================================================================