====================================================== 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=======================