======================================================
Review of the XPLASMA module for the NTCC Module Library.

John Mandrekas, GIT

August 8, 2002

SUMMARY:
========
XPLASMA is a set of routines that provides a representation standard for MHD
equilibria in axisymmetric plasmas using spline interpolation. The biggest
advantage of XPLASMA is, in my opinion, the elimination of the need 
that physics
r it works fine for other
GEQDSK files.

I suggest that the XPLASMA module be approved by the NTCC Committee.

Detailed report follows:

I. 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
-----------------------------------------------------------------------------
There are three test programs (test_xplasma, geqxpl, geqxpl2) and corresponding
input and output files that exercise most of the features of the XPLASMA
library. The test programs are also very helpful in demonstrating usage of the
various xplasma routines.

================================================================

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

A multi-platform Makefile (requiring the GNU make) is provided and it supports
most of the UNIX-based platforms, including LINUX. Clear documentation is
provided in the README_Xplasma file, as well in other README files 
for supporting
modules (Ezcdf, Psline). Since Operating Systems and compilers change 
frequently,
some of the sections may be obsolete. The section on the HP-UX system had to be
updated in order to work on the HP-UX systems running the HP-UX 11i version of
the OS.

================================================================

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.
-----------------------------------------------------------------------------
OK

A comprehensive README file is available with detailed instructions on
unpacking, building, testing and installing the module. A link to an extensive
Web-based help file is also included.

================================================================

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

(README file and Web-based help file)

================================================================

Standard: Eliminate graphics calls embedded in physics modules.
-----------------------------------------------------------------------------
OK

================================================================

Standard: The source code files (e.g., *.f, *.c or *.cpp files) should be
submitted rather than requiring extraction from another file.
-----------------------------------------------------------------------------
OK

Source code is included in the package.

================================================================

Goal: Portability (code should run on multiple platforms and under different
operating systems).
-----------------------------------------------------------------------------
OK

The reviewer has tested the module on systems running the SUN (Solaris) and
the HP-UX operating systems. Since the module requires several other libraries,
it is important that they have been correctly installed. Problems in the
building of the code on the HP-UX system were traced to an improper 
installation
of the NetCDF library.

================================================================

Goal: Offer single and double precision versions or offer user control of
precision at compile time.
-----------------------------------------------------------------------------
OK

Real*8 and real*4 routines are available. The real*4 routines can be called
by adding the "r4_" prefix in front of the regular (real*8) routine name.

================================================================

Goal: Multi-platform (code should run on different computers).
-----------------------------------------------------------------------------
OK

see portability comments above.

================================================================

Goal: Provide error checking (but not stops).
-----------------------------------------------------------------------------
OK

Most routines have error messages directed to stdout (I/O unit number 6).
This can be overridden by the user and the error messages can be directed to
a different file.

================================================================

Goal: Minimize external dependencies that cost money (i.e., avoid 
using expensive
proprietary licenses).
-----------------------------------------------------------------------------
OK

All of the required external libraries required are either part of NTCC
(pspline, ezcdf, etc.) or are free and widely available (Lapack, BLAS, NetCDF,
etc.). Certain optional libraries (termcap, history, readline) are part of the
GNU distribution, and therefore also free and widely available.

================================================================

Standard: Supply warnings in the documentation when the above goal has not
been met.
-----------------------------------------------------------------------------
N/A

================================================================

Goal: Arrays should be dynamically allocated.
-----------------------------------------------------------------------------
OK

================================================================

Standard: The characteristics of the I/O should be clearly documented
(i.e., the implementation I/O unit numbers, if any).
-----------------------------------------------------------------------------
OK

This applies only to error messages that are written to unit 6 (stdout), which
can be overridden by the user.

================================================================

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.
-----------------------------------------------------------------------------
OK (See above)


II. DOCUMENTATION STANDARDS:
================================================================

Standard: Provide Name of contact person for support.
-----------------------------------------------------------------------------
OK

Contact information is included in the README file and on the Web page

================================================================

Standard: Provide Date of last revision.
-----------------------------------------------------------------------------
OK (in the README file)

================================================================

Standard: Provide at least comments describing module or code, citations to
publications (if any), and range of validity.
-----------------------------------------------------------------------------
OK

Extensive help on XPLASMA is available at
http://w3.pppl.gov/~pshare/help/xplasma_hlp.html

================================================================

Standard: Specify the precision of floating point calculations.
-----------------------------------------------------------------------------
OK

XPLASMA is written in real*8 precision. Routines can be called with real
precision using the "r4_" prefix. This is explained in the help file.

================================================================

Standard: Provide index of input-output variables for each module (include
type of variable, dimensions, units).
-----------------------------------------------------------------------------
OK

Most of this information is available either in the help file or in the
routines themselves. Subroutine interfaces (Fortran 90) are included in
xplasma_calls.F

================================================================

Standard: List dependencies -- names of external routines called.
-----------------------------------------------------------------------------
OK

XPLASMA requires certain other NTCC modules (Pspline, ezcdf) and some
other external libraries (Lapack, BLAS, netCDF). Some other GNU libraries
are optional (readline, history, termcap) but if not available, calls to
them will be resolved by the provided "generic_dummy" library.

================================================================

Standard: Provide statement of known bugs.
-----------------------------------------------------------------------------
OK

No known bugs are listed, but certain limitations (axisymmetry requirement)
are discussed

================================================================


III. DATA STANDARDS:
================================================================

Goal: Provide interface routines to data:
-----------------------------------------------------------------------------
OK

Data access routines exist and are documented in detail

================================================================

Goal: Use self-describing data files (such as NetCDF):
-----------------------------------------------------------------------------
OK

Save and Restore routines exist that can write the contents of the
XPLASMA module to a NetCDF file

================================================================

Goal: Establish standards for variable names, units, dimensions, independent
variables and grid descriptions as they appear in the module interfaces:
-----------------------------------------------------------------------------
OK

There are standards for the (rho,chi,phi) coordinate system 
representation, with
flexibility in determining the orientation (right-handed or left-handed). No
rigid requirement for physical units, but consistency is expected and the MKS
system is recommended.


======================END OF XPLASMA REVIEW=======================