This report constitutes my review of the NTCC module ESC. I have built the code out of the box on several platforms, with minor changes in MakeFlags. I have run and compared results with the excellent suite of test cases provided. I have also inserted the module into the CORSICA code and both evaluated the performance with ESC and compared results with those run with the POLAR1 inverse equilibrium code of Drozdov. During the process of this review some issues/problems were raised. These were handled expeditiously and led to improvements. Detailed performance are given below under "Documentation Standards" and additional overall comments are at the end of the review. I recommend approval of this module.
Module Standards Version Date: Feb. 26, 1999
The tables below list ``Standards" and ``Goals". The ``Standards'' described below will be enforced for the modules submitted to the library; whereas, ``Goals'' are strongly encouraged and may become future standards for the module 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
COMMENTS: The agreement with the test cases provided, which
were generated on a LINUX box, with the calculation
on a LINUX box are to the last place. The agreement on
other platforms is essentially as good.
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
COMMENTS: The module was built on LINUX (pgf90), ALPHA,
SOLARIS, SGI and HP. Occasionally a compiler
directive had to be modified due to different
compiler dates. This is a very minor
inconvenience and one that can be solved by
the most inexperienced UNIX user.
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
COMMENTS: The module has public variables. It would be
preferable if all such variables had a unique extension
appended to them to avoid conflict. Perhaps a standard
would be to use the code name, i.e. TwoPI--->ESC_TwoPi.
a change already made for this variable.
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.
NOT APPLICABLE (initial version)
Goal:
Portability (code should run on multiple
platforms and under different operating
systems).
DONE see above
Goal:
Offer single and double precision versions or
offer user control of precision at compile
time.
COMMENTS: Only a double precision version is provided.
Given my experience with this code and an other
inverse solver (POLAR1), I believe a 4 byte
version would be useless.
Goal:
Multi-platform (code should run on different
computers).
DONE
Goal:
Provide error checking (but not stops).
DONE
COMMENTS: My experience is that if such a warning appears,
even those suggested by the author to be probably
benign, the calculation is invalid.
Goal:
Minimize external dependencies that cost
money (i.e., avoid using expensive proprietary
licenses).
NONE
Standard:
Supply warnings in the documentation when
the above goal has not been met.
NOT APPLICABLE
Goal:
Arrays should be dynamically allocated.
HARD WIRED ALLOCATION
COMMENTS: The inputs all have a maximum allowable size. This
was a purposefull decision of the author, who
thought, for example, too many spline nodes(>121)
made no sense. This limit should be indicated in the
README file. However I think this should be left to
the user with a warning. For example if the goal is
to study edge current profiles more spline nodes may be
necessary since the input arrays are required to be
uniform in the square root of toroidal flux.
Also, perhaps limiting mpol
to a maximum of 12 should also be left to the user with
a message BEWARE. To properly implement this it would be
necessary to dynamically allocate the module.
Standard:
The characteristics of the I/O should be
clearly documented (i.e., the implementation
I/O unit numbers, if any).
NONE
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.
NOT APPLICABLE
Standard:
Documentation Standards:
Standard:
Provide Name of contact person for support.
DONE
Standard:
Provide Date of last revision.
Standard:
Provide at least comments describing module
or code, citations to publications (if any), and
range of validity.
DONE
COMMENTS:
The authors state that:
(1) When inputing the q-profile it is
necessary to initialize with the J-profile and
then switch. I have found this to be necessary only
for the very first call to ESC.
Quality of ESC solutions:
(1) I conclude that there is a problem with ESC at the edge.
The problem manifests itself as follows. I start with a
j|| profile with no structure at the edge. Using this as input
I generate a j|| in excellent agreement and a q profile. I then
use this generated q profile as input. The q profile on output
is in excellent qgreement. The j|| on output now has structure
at the edge. If I complete the cycle by using this latter j||
profile as input, the generated j|| profile is basically the
same as the starting j|| profile. (No structure at the edge.)
Comparison with POLAR1:
(1) I have compared the relative time for a single ESC and
POLAR1 run. The comparison between the two codes is
somewhat arbitrary in that there is no measure of accuracy
control(convergence) in ESC available to the user. (This
capability should be made functional.) Also POLAR1 makes
maximal use of a previously converged solution. A comparison
was made with 101 surfaces for both, ESC with 8 harmonics, an
POLAR1 with 128 poloidal angles with an accuracy of
1e-6. The bottom line is that avoiding the special case
of starting from a nearby solution, the times used are
comparable. The very first ESC calculation generally
takes much more time.
(2) I have also used the ESC
module in the 1 and 1/2 D transport code (CORSICA)
and I find the evolution of the q-profile is quite
robust but near the edge it is not in good agreement with that
generated by POLAR1. In fact, this difference (the ESC case
appears quite pathological) reinforces my contention that ESC
has problems at the edge. Note in this simulation both POLAR1
and ESC use q as the input profile. The simulation with POLAR1
used about 30% less time. This time is also somewhat arbitrary
in that:
(1) There has been no attempt to optimize ESC; and (2)
ESC generates a "converged" solution each transport time
iteration, whereas POLAR1 converges as the time step converges.
(3) POLAR1 can get closer to the separatrix.
(4) The error as measured by the difference between the
surfaced averaged right-hand-side and left-hand-side of
Grad-Shafronov equation (in inverse coordinates) can
be quite large in the vicinity of the edge in ESC;
as the boundary moves away from the separatrix the error
does improve. The error in the interior is considerably better.
I have compared this error evaluation with POLAR1 and ESC;
the results are quite similar with minor differences.(1)
POLAR1 is better at the edge; (2) ESC is better in the
interior; and (3) they are comparable in the vicinity of the
magnetic axis.
Standard:
Specify the precision of floating point
calculations.
DONE
Standard:
Provide index of input-output variables for
each module (include type of variable,
dimensions, units).
DONE
Standard:
List dependencies -- names of external
routines called.
NONE NEEDED
Standard:
Provide statement of known bugs.
DONE
Goal:
Index of modules, routines, variables.
COMMENTS: No list but descriptions in the README file, on the WEB
and in the files in man/man3
Goal:
Publication of code or module in journal (such
as Computer Physics Communications).
DONE
Goal:
Online hyper-text reference documentation.
DONE: There is a web page; see README file
Goal:
Interactive online help menus.
NONE
Data Standards:
Goal:
Provide interface routines to data.
NONE NEEDED
Goal:
Use self-describing data files (such as
NetCDF).
NOT APPLICABLE
Goal:
Use public domain, portable, available and
well-documented data file formats.
NOT APPLICABLE
Goal:
Establish standards for variable names, units,
dimensions, independent variables and grid
descriptions as they appear in the module
interfaces.
DONE
Standards for Users:
Standard:
Users of NTCC codes and modules must
acknowledge the author(s) and any
modifications made when publishing or
presenting results.
Standard:
Users who find bugs in NTCC codes or modules
must report back to the contact person first.
Standard:
Users who make improvements to a module's
source code, makefile, or documentation, will
submit these improvements to the module's
author or support person, who may choose to
incorporate these improvements in a future
release of the module.
GENERAL COMMENTS:
(1) I like the code. The documentation made it very easy to insert
into an existing code. I would encourage theauthor to make
error control available to the user; also the sizeof input arrays
should be under total control of the user. Theauthor should
make maximal effort to avoid conflicts in variablenames. Good job.