==============================
Getting started with ChiantiPy
==============================

Prerequisites
-------------

* CHIANTI_, the atomic database for astrophysical spectroscopy (Version 8)

.. _CHIANTI: http://www.chiantidatabase.org/

* Python_ (developed with versions 2.7 and 3.3, 3.4)

.. _PYTHON:  http://www.python.org

* Numpy_ (developed with 1.10)

.. _Numpy:  http://www.scipy.org/

* Scipy_ (developed with 0.16)

.. _Scipy:  http://www.scipy.org/

* Matplotlib_ (developed with 1.5 and 2.0)

.. _Matplotlib:  http://matplotlib.sourceforge.net/

* Matplotlib requires a GUI library

  PyQt5_, PyQt4_ or wxPython_ (wxPython is not compatible with Python3)

  Once one of these is installed, it must be set as the backend in your matplotlibrc file, e.g., backend:  Qt4Agg

.. _PyQt5: http://www.riverbankcomputing.co.uk/

.. _PyQt4: http://www.riverbankcomputing.co.uk/

.. _wxPython:  http://www.wxpython.org/

* ipyparallel (required for multiprocessing with ipymspectrum)

* (not really a prerequisite but **extremely** useful) IPython_ version 6 and Jupyter_

.. _IPython:  http://ipython.org

.. _Jupyter: http://jupyter.readthedocs.io/en/latest/


Install the CHIANTI database
----------------------------

The gzipped *data* tar ball can be downloaded from the CHIANTI website_

.. _website: http://www.chiantidatabase.org/chianti_download.html

*  put the file in a convenient directory, cd to the directory and untar the file

* ChiantiPy uses the environment variable *XUVTOP* to find the database.  Set XUVTOP to the name of the directory where the CHIANTI data tarball was placed.  For example

::

  setenv XUVTOP /data1/xuv/directory.where.the.tarball.was.placed


or on Windows:   To set the environment variable, go to Control Panel -> System -> Advanced System Properties -> Environment Variables.


Some sites have the CHIANTI database maintained as part of a SolarSoft distribution.  In that case, simply set XUVTOP to the directory were it resides, usually something like $SSW/packages/chianti/dbase

Install the Prerequisites
-------------------------

On **Linux** systems this can usually be done with your package manager.

On **Windows**, **Linux** and **Mac** systems, it is possible to use

* the Anaconda_ distribution from from Continuum, or,

.. _Anaconda:  http://continuum.io/downloads

* the Canopy_ distribution from Enthought.

.. _Canopy:  https://store.enthought.com/downloads/#default

On **Windows**, it is also possible to use:

* WinPython_

.. _WinPython:  http://winpython.github.io/

All of these packages are free, at least for noncommercial use (I believe) and have a considerable amount of documentation.  **You shoud check the version of IPython that is provided**.


Install the ChiantiPy package
-----------------------------

In order to be compatible with the latest version (8.0) of the CHIANTI atomic database, it is necessary to install the latest version (0.6.0) of ChiantiPy

::

  pip install ChiantiPy

or

::

  pip3 install ChiantiPy


I have not tried this with ChiantiPy, myself.


The ChiantiPy package can be downloaded from the ChiantiPy_ project page at Sourceforge, untar it, cd to the directory where it was unpacked, and then, as root

.. _ChiantiPy:  http://sourceforge.net/projects/chiantipy/

::

  python setup.py install

If you do not have root privileges, simply put the ChiantiPy directory in your PYTHONPATH

::

  python setup.py install --prefix=somewhere_in_my_PYTHONPATH


or on a Mac, with the Anaconda package

::

  python setup.py install --prefix=/Users/your_user_name/anaconda/

**Thanks to Peter Young (GMU) for providing the instructions for installation on Mac and Windows**

Note - ChiantiPy interactions with various GUI backends
-------------------------------------------------------

First, Matplotlib requires a GUI backend and can be specified by the user in the matplotlibrc file.  Matplotlib expects to find this file in  $HOME/.config/matplotlib, although it might require that you copy it to that directory.

ChiantiPy also uses a set of GUI dialog widgets using PyQt4 or wxPython (for Python 2).  Selections can also be made via the command line.  The user choice is specified in the $HOME/.chianti/chiantirc file if one has been copied there.  Otherwise, the default GUI is to use the command line.  A default chiantirc file is included with the distribution.

In order for the ChiantiPy dialog widget to be used, a backend for them must be initiated.  If you choose the same backend for matplotlib as for the ChiantiPy widgets, then running %matplotlib in an IPython or Jupyter session will do the trick.  In an interactive Python session, invoking a matplotlib command first should also do the trick.

::

  matplotlib inline

or

::

  matplotlib qt

if you are using Qt4 or Qt5

If you choose to use a GUI backend other than that used for matplotlib, then in an IPython or a Jupyter command the following magic commands are also available to start the backend:

::

  %gui qt
  %gui wx


ChiantiPy has mostly been tested with the Qt5 backend for Matplotlib and using the ChiantiPy Qt5 widgets.

