.. PyISOLVER documentation master file, created by
   sphinx-quickstart on Tue Sep 18 17:01:03 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.


=========
PyISOLVER
=========
--- A Fast Python OOP Implementation of LRDFIT Algorithm


Version: Beta 0.20

Fanghao Yang, PPPL
10/05/2018

Overview
========
PyISOVLER is the Python version of ISOLVER ported from the original IDL version of ISOLVER,
which is mostly developed by Jon Menard and Bill Davis.

PyISOVLER is not ported from IDL version line by line but totally refactored into OOP style
Python code. It contains most frequently used methods and data structures from EFIT, LRDFIT
and a few other IDL libraries using by ISOLVER.

Current PyISOVLER is still under development and testing. It only runs with current input
data and parameters which are hard coded in the “isolver_input.py” file. It may not run at
all or not run correctly for other input data sets.

PyISOVLER is developed with Python 2. However, the code may be moved to Python 3 in near
future, Thus, it was written to get best compatibility with Python 3 (does not mean working
with Python 3). In this way, only a small effort was need to upgrade to Python 3.

How to Acquire PyISOLVER
========================
To run the PyISOLVER on your local domain, you need use subversion to checkout via:

``svn checkout svn+ssh://svnsrv.pppl.gov/svn/nanalysis/pyIsolver/release/beta0.20 ./beta0.20``

If you want to change the original code published by Fanghao Yang. You may create a side-line
development version in the branch. If necessary, your revision would be merged into the trunk
for future release.


How to Run
==========
Now to use it, you need load the module first,

``module load nstx/pyisolver``

Then, go to the directory of current copy and run the program,

``python -s run.py``

The maximum number of iterations is limited to 51 for current input parameter.
You shall see 5 out of 6 profiles converged within 51 iterations.

How to Change Input Parameters
==============================
The "input_generator.py" is a tool for users to generate input JSON files for batch jobs.

For example, if you want to test the convergence for different input sets, you may need
change the max iteration number in input JSON file. There are three methods to change input
paramters:

1. Edit the function "generate_input"

"generate_input" is a function which has hard-coded input parameters and it will return an
instance of Inputs class. You may edit those hard-coded parameters to generate input file.
Find where the instance of “IterConvParam” is created in "generate_input()" and “nitmax” is
the number to set the maximum iterations.

2. Load existing input file, edit and save the file

You may also load existing JSON input file.
For example, you want to load an input parameter file for NSTX.

.. code-block:: python

    filename = "input/nstx_test.json"
    input_obj = lrdfit.Inputs()
    input_obj.load_json(filename)

Then, for example, you want to change the maximum iteration number to 100.

.. code-block:: python

    input_obj.itconvpars.nitmax = 100

After you have changed the parameter, you may save the input parameter as JSON file for
running ISOLVER code.

.. code-block:: python

    input_obj.save_json(filename)

You are free to edit the "input_generator.py" to generate a batch of input files for your job.

3.  Edit JSON files

You can also edit the JSON file directly and save it for your job. Since there is no comment
in JSON file, you need know what you are changing.

How to Plot Figures
===================
In the example run code “run.py”, in line 40:

.. code-block:: python

    ctimes = s.iterate_state_to_convergence(c, m, grs, noplot=False)

If argument “noplot” is false, it will dynamically plot results after each iteration

If argument “noplot” is true, it will disable the plot then no figure would be plotted.

If you want to get faster calculation, then, disable the plot option since plotting takes extra
time.

Reference to Original IDL ISOLVER
=================================
Current input data sets and profile parameters are derived from the IDL version isolver batch
file “input”. For more information, you may find it from the IDL version isolver subversion
repository

``svn+ssh://svnsrv.pppl.gov/usr/local/svn/isolver/trunk``

Example Run
===========
An example of running ISOLVER is included in "run.py".

The first step is load user input file as JSON format.

First, create an instance of Inputs from lrdfit library. The input data set includes all
parameters to initialize ISOLVER and iteratively approach to the solution.

.. code-block:: python

    input_obj = lrdfit.Inputs()

Then, use "load_json" method to load the JSON file which stores input data.

.. code-block:: python

    input_obj.load_json(filename)

If you have changed some parameters in Inputs data and you may save it as a local JSON file
for future work.

.. code-block:: python

    input_obj.save_json(filename)

Next, create an instance of GridStructure from lrdfit library for loading and computing
grid data with Green's function.

.. code-block:: python

    grs = lrdfit.GridStructure()

Then, use "get_greens_data" method to load the grid data in NetCDF4 format.

.. code-block:: python

    grs.get_greens_data(grsfile)

Next, create an instance of FluxCoord from lrdfit library, which has all flux coordinate
data for the tokamak device. Some parameters from the Inputs would be used to initialize
flux coordinates.

.. code-block:: python

    cfc = lrdfit.FluxCoord(nradius=input_obj.fcspars.nradius,
                           ntheta=input_obj.fcspars.ntheta)

The State data comprises all profiles about targeting shot including temperature, pressure,
voltage, current, flux and more. Then, an instance of State would be created using Inputs data,
moreover, using all existing data sets, the State data would be initialized from Equilibrium
data.

The Equilibrium data was previously calculated by EFIT and usually stored as G-EQDSK format.
There are two ways to load EFIT G-EQDSK data, either from the local file or from MDS+ tree.
All paramters about loading Q-EQDSK data are included as Inputs parameter.

.. code-block:: python

    isj = lrdfit.State(inputobj=input_obj)
    isj.initialize_from_equilibrium(grs, cfc)

The following step is to calculate the momentum from initial State and flux cooridnate data.
The momentum data has similar data structure as class Equilibrium.
The momentum data contains boundary data and other data derived from current State profiles
and current flux coordinate data.

.. code-block:: python

    m = lrdfit.Momentum()
    m.compute_state_moments(s, cfc)

The initial State is renamed as State for following iterative computation.

.. code-block:: python

    s = isj

Then, the solver starts to solve Grad–Shafranov equation and converge into an acceptable solution.
All tolerance of profiles are controlled by parameters from Inputs data.

.. code-block:: python

    ctimes = s.iterate_state_to_convergence(cfc, m, grs, noplot=True)

After the convergence is reached or the maximum iteration number is reached, the method would
return an instance of ComputingTime which contains time spent on each step of iteration. The
user may plot or print the time data for performance review.
Currently, there is no methods for post-processing results. The post-processing methods would
be provide in the near future.

Performance
===========
Current version uses Numba JIT (just-in-time) compiler to accelerate Python code. Thus, for the
first run of ISOLVER, it will take a few extra seconds to compile the math utilities library.
This part code will be ported into Cython in the following update so that it could call pre-compiled
library directly without delays.

To get best compatibility, the multi-processing is disabled to get the code running with
module “anaconda2” on PPPL cluster. Also the “fast math” option for Numba JIT is disabled
for public interpreter “anaconda2”, since the “fast math” option uses Intel SVML to accelerate
computing, which would lead to small errors for non-Intel platform.

Without plotting, the original IDL program would take 64 iterations to converge and cost ~80
seconds on AMD CPU or ~43 second on Intel CPU. The ported Python version would takes ~43 second
on AMD CPU or ~26 second on Intel CPU. A better performance could be achieved with multi-processing
and Intel SVML.

Documentation for the Code
==========================
.. toctree::
   :maxdepth: 2
   :caption: Contents:


LRDFIT
******
.. automodule:: lib.lrdfit
   :members:

EFIT
****
.. automodule:: lib.efit
   :members:

NEOC
****
.. automodule:: lib.neoc
   :members:

EQSC
****
.. automodule:: lib.eqsc
   :members:


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`