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.
______________________________________________________________________________ L. D. Pearlstein
office: 925-422-9859 FAX: 925-423-3484 Lawrence Livermore National Laboratory, Box 808 L-630, Livermore, CA 94550 ______________________________________________________________________________