# $Id: rzsolver.doc,v 1.7 2003/11/10 15:03:14 xshare Exp $

RZSOLVER

A. Pletzer (pletzer@pppl.gov)

Rzsolver is a Python script that solves the mhd equilibrium (Grad-Shafranov) equation in (r,z). In general, the user need not choose explicitly Rzsolver via the LEVGEO switch. Rather, Rzsolver is automatically invoked "in rescue mode" when the master (e.g. Esc) equilibrium codes fails to compute an accurate solution. It is also possible to run Rzsolver in master mode by setting LEVGEO=10.

Because Rzsolver solves the Grad-Shafranov (GS) equation in direct coordinates (r,z), the code is less liable to problems associated with sharp separatrix and/or the difficulty to correctly locate the magnetic axis than inverse coordinate solvers such as Esc, Vmec6, etc. On the other hand, solving in real space is less efficient (more degrees of freedom) and due to the fact that Rzsolver is implemented in Python, the code is significantly slower (factor ~100) than Esc. For this reasons, we anticipate Rzsolver to run mainly in rescue mode, where a different numerical approach is required. Tests show that Rzsolver can help a Transp complete a run that would otherwise have crashed for equilibrium reasons (http://w3.pppl.gov/~pletzer/rzsolver/tests/NSTX.109070A33/esc-rzsolver/rmjmp.png vs. http://w3.pppl.gov/~pletzer/rzsolver/tests/NSTX.109070A33/new_esc/rmjmp.png).

The right hand side of the GS equation is the toroidal current density p'(psi)*r + g g'(psi)/r. However, Transp prefers to provide the safety factor profile q(psi) instead of the poloidal current g(psi). To get g(psi) from q(psi), Rzsolver invokes a "polcal" call in Transp, which requires the knowledge of the topology (r, z) as a function of the flux, which is taken at the previous time step.

Rzsolver's features can be summarized as follows:

+ robustness: geometry and profiles can have sharp features
- speed, takes J// as input profile, contouring of solution requires high resolution

The run will abort if Rzsolver failed to converge to a prescribed accuracy. This generally indicates severe problems with the input profiles (e.g. negative q). If Rzsolver fails later, in the contouring step, one may want to increase the resolution (--nx1=...). 

Activation:

Normally Rzsolver runs only in rescue mode, it is not activated unless ESC fails (i.e. GS error > SOFTESC). Users who want to run ESC with Rzsolver in rescue mode (preferred way) must set LEVGEO=7. The threshold beyond which RZsolver kicks in is SOFTESC. Setting LEVGEO=10 will invoke ESC in the warm-up phase (STEP=0) and then switch to Rzsolver for subsequent time steps STEP > 0. 


Installation:

Rzsolver requires:

* Python 2.2.2 or later. 

The following Python modules must in addition be installed:

* Ellipt2d: http://ellipt2d.sourceforge.net

* Numpy: http://www.pfdubois.com/numpy

* Scientific: http://starship.python.net/~hinsen/ScientificPython/

* Optionally, for graphics purposes only, you may also want to install Pmw (http://pmw.sourceforge.net/) and BLT. The latter are Tcl/Tk extensions. My Linux box already had BLT installed, otherwise you can install from RPMs. To use the rzsolver graphics capability, you will need Tkinter activated, see below. 


-- Installation tips for Python neophytes:

You can download Python from http://python.org. You don't need to be admin to build python. You can build under your username and install in your own area by typing ./configure --prefix=... (by default python is installed under /usr/local/). Though not strictly necessary, I recommend to build Python with Tkinter activated (search for Tkinter in README file). This requires commenting out a number of lines in the Modules/Setup file (as per README) and assumes that the tcl/tk libraries are already installed. Tkinter provides a convenient graphics capability. 

The other packages are build using the commands

cd ellipt2d
python setup.py install [--prefix=<path>]

which will install the packages under <path>/lib/python2.2/site-packages/ where path is where <path>/bin/python lives.


You can check whether Python is running (and which version) by typing:

[pletzer@apletzer-pc pletzer]$ python
Python 2.2.2 (#1, Mar 10 2003, 13:57:18) 
[GCC 2.96 20000731 (Red Hat Linux 7.1 2.96-98)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> 

On some systems you may have to type python2 as there may be an older version (often 1.5) coexisting. Rzsolver will not run properly on older versions than 2.2.2! Next, to check whether the above add-ons are available, type:

>>> import ellipt2d
>>> import Numeric
>>> import Scientific.IO.NetCDF

You should not get any errors. Type Ctrl-D to exit. 

-- Checking whether Rzsolver is running

cd $CODESYSDIR/rzsolver_test
python rzso_solver.py --runid=51976C34 --nx1=21 --rtol=0.001

...

Statistics
== no of times Picard error increased: 0 
== min error                         : 0.000547694 
== this error                        : 0.000547694 
== prescribed tolerance              : 0.001   OK 
== no of iterations                  : 7 

-- More tips

To visualize the output add the option --plot=1 at execution (which requires Tkinter, and possibly other packages such as Pmw and Blt). 

python rzso_solver.py --help 

will report the list of options.

-- Tips for advanced users

For maximum performance, you may want to compile Python using the Intel compiler icc. Expect a 20% performance improvement over gcc (2.95). This is what I did to compile Python 2.3 on a Linux box running Red Hat 7.3 using icc version 6.0.1:

./configure --without-gcc --with-cxx=icc

edit Modules/Setup file to activate Tkinter
edit Makefile.pre to force 
CC=		icc -pthread
CXX=		icc -pthread
..
OPT=		-DNDEBUG -O3 -tpp7
BASECFLAGS=	 -fno-alias

in Modules/posixmodule.c I added
#undef HAVE_DEVICE_MACROS