Review of Kapisn for NTCC Module Library:
=========================================
P.I. Strand, ORNL
KAPISN calculates neoclassical ion heat diffusivities from several models
including the Rutherford-Juelich (197?), Modified Hazeltine-Hinton (as in
the Baldur code), Bolton (1981), Chang Hinton (1982) and the modified
Chang-Hinton (1986) model. The calculations are performed in simple circular
geometry. The Chang-Hinton models both includes finite inverse
aspect ratio effects, whereas the modified Chang-Hinton is the only model
that explicitly deals with impurities. Some dilution effects (Zeff .ne. 1),
have been incorporated into the other models. These corrections seem to be
limited to values of Zeff close to unity.
The distribution comes with a detailed README file, describing
installation and usage of the module. An extensive LaTeX document is
supplied together with the fortran (f90) source files (testkapisn.f, kapisn.f,
stripx.f). The source code can in addition be extracted from the LaTeX
document using supplied tools.
A multi platform make file (gnu make compliant) is supplied and the README
file also contain manual build instructions for non-supported platforms.
Conformance to standards:
-------------------------
The documentation standards (and some of the goals) have been met. The
reviewer has tested the code on most of the supported platforms. (IBM/AIX,
SGI/IRIX, DEC/ALPHA, SUN Solaris as well as HP-UX and Windows NT). The code
did build on all platforms and passed the supplied test cases with no
exceptions.
During the review process the original submission has been improved to
provide a more readable and portable code. Several people appear to have
been contributing to the module over the years and the original code
has been edited somewhat to improve readability. In addition, some numerical
and portability (mainly precision related) issues have been addressed.
Comments:
---------
It is not clear from the coding or the documentation whether the returned
heat diffusivities are diagonal or if they are to be viewed as effective
heat diffusivities (e.g., including off-diagonal, grad n driven, effects).
In addition, the heat diffusivities calculated from the different models are
quite different. Using profile data from DIII-D #78283 the Modified
Chang-Hinton
model gave chi_i=0.47m^/s (midradius) whereas the modified Hazeltine-Hinton at
the other end of the range gave chi_i = 0.13 m^2/s. (Zeff = 2 with a single
carbon impurity species).
See the attached summary graph of this comparison, which also includes a
comparison with NCLASS (diagonal and effective chi's) using the same
geometry.
A similar comparison at lower Zeff with higher densities and temperatures
gives a somewhat smaller range but there is still a factor of 2 difference
between the smallest and the largest estimate from kapisn. I feel that an
end user may need some more guidance towards chosing apropriate settings for
the module than what is currently provided.
Based on the adherence to programming and documentation standards I
recommend that KAPISN be accepted for inclusion in the NTCC library.
---------------
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. Gnu make compliant make files are provided for IBM/AIX,
SUN/SOLARIS, SGI/IRIX, DEC/ALPHA and some linux compilers.
Requires an environment variable (CPU) to be exported to work
properly. The supplied README file also give step by step
instructions for compilation on non-supported systems.
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. A detailed README file is included in the distribution.
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. A latex document contains an annotated version of the
fortran code and there is some relevant information included in
the README file as well
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. The source code can be extracted from the latex
documentation using supplied fortran based tools as well.
Goal:
Portability (code should run on multiple platforms and under
different operating systems).
** The reviewer has tested the code under Solaris, Aix, HP-UX,
SGI/IRIX and in addition on Windows NT using compaq fortran,
with no portability problems. The module assumes a fortran 90
compliant compiler. The deviations from f77 are mild and the code
would compile under most f77 flavours (namelist input is in f90
format though).
Goal:
Offer single and double precision versions or offer user control of
precision at compile time.
** The module is a double precision (real*8) code
Goal:
Multi-platform (code should run on different computers).
** yes, see portability comment above.
Goal:
Provide error checking (but not stops).
** Not supplied
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.
**
Goal:
Arrays should be dynamically allocated.
** Passed in argument list to kapisn. Can accomodate several ion
species
Standard:
The characteristics of the I/O should be clearly documented (i.e.,
the implementation I/O unit numbers, if any).
** Testdriver reads and writes to files, description in
documentation
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.
** Kapisn.f uses unit 6 for fatal error messages. No other
messages provided
Documentation Standards:
========================
Standard:
Provide Name of contact person for support.
** Done
Standard:
Provide Date of last revision.
** Done. Revision history starts 1979 with a first revision
Standard:
Provide at least comments describing module or code, citations to
publications (if any), and range of validity.
** References to the underlying theory basis is provided in the
source code and LaTeX documentation
Standard:
Specify the precision of floating point calculations.
** Implicitely done in LaTeX document.
Standard:
Provide index of input-output variables for each module (include
type of variable, dimensions, units).
** Appears in the LaTeX doxumentation
Standard:
List dependencies -- names of external routines called.
** No external dependencies
Standard:
Provide statement of known bugs.
** None