by Glenn Bateman and Federico Halpern
Lehigh University, Bethlehem PA 18015
10 December 2004
The KDSAW module implements an ideal Kadomtsev Sawtooth Model [B. Kadomtsev, Sov. J. Plasma Phys. 1 (1975) 389] for tokamaks in general geometry. The module is initialized by a call to "kdsaw_init" providing a grid, iota(bar) (1/q) profile, and zone volumes; kdsaw_init computes the Kadomtsev mapping and stores it in the module's internal memory. Subsequent calls are used to extract specific information about the ideal Kadomtsev sawtooth map. The grid passed to kdsaw_init is specified in normalized square-root-toroidal-flux, a coordinate which functions in a way strictly analogous to the minor radial coordinate "r" in Kadomtsev's original paper, but is suitable for general geometry. The grid is given explicitly and need not be evenly spaced. The current profile is expressed as (1/q), and the zone volumes (in any suitable units) are used to adjust the mapping such that a change in a particle or energy density profile according to the ideal Kadomtsev mapping volume integrates to precisely zero: typically, a peaked density profile is flattened, with the ! density reduced in the center and raised at the edge of the mixing region. A user-adjustable current profile remapping is also provided. Both REAL and REAL*8 interfaces are provided to all routines in the module.
We find that the documentation, programming style and organization of the module are quite good. It is easy to compile and test the module on different computers.
The Ntcc Kdsaw module was installed on several workstations. The makefile, quite likely generated using autoconfig, provides support for numerous compilers, architectures and unix flavors. The KDSAW module compiled and worked correctly on the following computers:
+---------------+-------------------+---------------------+------------------+ | Architecture | Operating System | Compiler | Status | +---------------+-------------------+---------------------+------------------+ +---------------+-------------------+---------------------+------------------+ | i686 | RedHat 7.2 | Lahey Fujitsu 5.7 | OK | +---------------+-------------------+---------------------+------------------+ | Sun | Solaris 8.0 | Forte Developer 7.0 | OK | +---------------+-------------------+---------------------+------------------+ | HP | HP - UX | f90 - HP Fortran | OK | +---------------+-------------------+---------------------+------------------+General Standards
+-------------------------------------------------------------------------------
Standard: Provide source code for each physics module or code
Done.
+-------------------------------------------------------------------------------
Standard: Provide test case(s), driver program(s), 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. A GNU Makefile is provided for a variety of compilers, architectures and operating systems. The README file clearly indicates how to build the module and run test cases. Information is also included on how to review, choose or modify environment variables.
+-------------------------------------------------------------------------------
Standard: Provide a README file giving 1. The name of the module and its authors. 2. The location and form of general module documentation. 3. Information enabling a user to build binaries from the source code.
Done. The README file includes contact information, useful tutorial on how to build binaries, and a weblink indicating where to find additional documentation.
+-------------------------------------------------------------------------------
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. Documentation addressing these issues has been provided. The common variables declared in the KDSAW_MODULE module have also been documented.
+-------------------------------------------------------------------------------
Standard: Eliminate graphics calls embedded in physics modules.
Done. There are no graphic calls or output inside the package by default.
+-------------------------------------------------------------------------------
Standard: The source code files (e.g., *.f, *.c or *.cpp files) should be submitted rather than requiring extraction from another file.
Done. The KDSAW package is distributed as a gzipped tarball containing the Fortran source code files, documentation, Makefile, etc.
+-------------------------------------------------------------------------------
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.
n/a
+-------------------------------------------------------------------------------
Standard: The characteristics of the I/O should be clearly documented (i.e., the implementation I/O unit numbers, if any).
Done. I/O unit numbers can be specified at runtime. Input and output variables are documented.
+-------------------------------------------------------------------------------
Standard: Supply warnings in the documentation when external dependencies, such as expensive proprietary licenses are needed.
Done. None used.
+-------------------------------------------------------------------------------
+-------------------------------------------------------------------------------
Goal: Portability (code should run on multiple platforms and under different operating systems).
No portability issues are known by the reviewer. Compiler or architecture dependent calls have not been observed. Consequently, the code should compile and run without problem in multiple platforms and operating systems.
+-------------------------------------------------------------------------------
Goal: Offer single and double precision versions or offer user control of precision at compile time.
Done. User can choose between real and real*8.
+-------------------------------------------------------------------------------
Goal: Multi-platform (code should run on different computers).
Done. A table is given at the beginning of this review indicating the platforms on which the code has been tested.
+-------------------------------------------------------------------------------
Goal: Provide error checking, with no stops.
Done. Upon failure, subroutines print error messages, return to parent subroutine and report an error code.
+-------------------------------------------------------------------------------
Goal: Minimize external dependencies that cost money (i.e., avoid using expensive proprietary licenses).
Done. The KDSAW package has no external dependencies.
+-------------------------------------------------------------------------------
Goal: Arrays should be dynamically allocated.
Done. Arrays are dynamically allocated.
+-------------------------------------------------------------------------------
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. No hard wired I/O unit numbers are used. Each output routine can be assigned a different I/O unit number if this is necessary. By default, no output is done.
+-------------------------------------------------------------------------------
Documentation Standards
+-------------------------------------------------------------------------------
Standard: Provide name of contact person for support.
Done.
+-------------------------------------------------------------------------------
Standard: Provide at least comments describing module or code, citations to publications, and range of validity.
Done. This module implements the Kadomtsev sawtooth model for tokamaks with general geometry. Details can be found in the documentation and in the reference given.
+-------------------------------------------------------------------------------
Standard: Provide date of last revision.
Done.
+-------------------------------------------------------------------------------
Standard: Specify the precision of floating point calculations.
Done. Choice of floating point calculations is given between real and real*8
+-------------------------------------------------------------------------------
Standard: List dependencies, i.e. names of external routines called.
n/a
+-------------------------------------------------------------------------------
Standard: Provide index of input-output variables for each module, including type of variable, dimension, units.
Done. They can be found in the documentation.
+-------------------------------------------------------------------------------
Standard: Provide statement of known bugs.
+-------------------------------------------------------------------------------
+-------------------------------------------------------------------------------
Goal: Index of modules, routines, variables.
Done.
+-------------------------------------------------------------------------------
Goal: Publication of code or module in a journal, such as Computer Physics Communications.
n/a
+-------------------------------------------------------------------------------
Goal: Online hypertext reference documentation.
Documentation available at https://w3.pppl.gov/ntcc/kdsaw/
+-------------------------------------------------------------------------------
Goal: Interactive online help menus
n/a
+-------------------------------------------------------------------------------
Data Standards
+-------------------------------------------------------------------------------
Standard: Provide interface routines to data.
Data can be accessed through output routines.
+-------------------------------------------------------------------------------
Standard: Use self-describing files
n/a
+-------------------------------------------------------------------------------
Standard: Use public domain, portable, available, and well documented data file formats.
Done. Standard ASCII files are used.
+-------------------------------------------------------------------------------
Standard: Establish standards for variable names, units, dimensions, independent variables, and grid descriptions as they appear in the interface module.
n/a
+-------------------------------------------------------------------------------
Glenn Bateman, Lehigh University,
Physics Department, 16 Memorial Drive East, Bethlehem, PA 18015 USA
(610) 704 5444 (Cell) (610) 758 5733 (office) (610) 758 5730 (FAX)