ionics 0.2

Ionization Cross Sections
=========================

Installation
------------

Requirements
~~~~~~~~~~~~

In order to download the latest version of the application (and to stay up-to-date) the version
control application ``git`` is required. Please consider
`these instructions <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_ on how to
install git for your operating system.

As this is a Python package you need to have Python running. Python is shipped with most Unix systems.
On Windows please download the latest version of **Python 2.7** from `here <https://www.python.org/downloads/>`_.

.. warning::
If you are using Windows then the ``numpy`` and ``scipy`` dependencies can't be installed
automatically as they require precompiled binaries for the specific operating system. Scipy
doesn't support binaries for Windows officially. Please consider the scipy installation
instructions about `scientific Python distributions`_ and `inofficial binaries`_.

.. _scientific Python distributions: https://www.scipy.org/install.html#scientific-python-distributions
.. _inofficial binaries: https://www.scipy.org/install.html#windows-packages

The GUI uses PyQt4_ which must be installed separately. You can use the package of course without
the GUI in your scripts by simply importing it. However if you want to use the GUI please consider
the following resources:

* **Unix** - You can downloaded the latest release from `here
<https://www.riverbankcomputing.com/software/pyqt/download>`_. Please follow the installation
instructions on this website. Usually you have to build it from source which is fairly simple though.

* **Windows** - Download the correct PyQt4 version from `here <http://www.lfd.uci.edu/~gohlke/pythonlibs/#pyqt4>`_;
make sure that you match yout Python and OS version. Then open Powershell (press the Windows key
and type "Powershell" in the search field; we recommend to use the x86 version) and navigate to
the folder where you downloaded the ``.whl`` file to (usually ``Downloads``). Then install the
package via ``pip install <version>.whl`` where you replace ``<version>.whl`` with the name of
the file you downloaded (you can use tab completion in Powershell).

.. _PyQt4: https://www.riverbankcomputing.com/software/pyqt/intro

.. note::
The GUI also uses ``matplotlib``; please visit their `website
<https://matplotlib.org/users/installing.html>`_ for the installation instructions.


Install the package
~~~~~~~~~~~~~~~~~~~

To install the package follow those steps:

1. Clone the repository: ``git clone https://gitlab.com/IPMsim/Ionization-Cross-Sections.git``
2. Switch to the repo's directory: ``cd Ionization-Cross-Sections``
3. Install the package: ``pip install -e .``

.. note::
If you are using Windows you can use the Git Bash for the above tasks if you installed it
together with git for Windows (which is the default). Just hit the Windows key and type
"git bash" in the search field.


Usage
-----

The GUI
~~~~~~~

To use the graphical user interface nagigate to ``Ionization-Cross-Sections/cross_sections`` and
run ``python start_gui.py``.

Browsing cross section
``````````````````````

On the left side you find a file browser exposing the cross section files that are contained by
the ``cross_sections`` package. You can get a list of available cross sections by either clicking
on a directory (all cross section within that directory) or a module itself (all cross sections
within that module). The cross sections are shown in the window below the file browser.
By clicking on a cross section you can obtain information about them.

Plotting cross sections
```````````````````````

To plot a specific cross section drag and drop it onto a plot canvas on the right side.
You are prompted to enter the cross section's specific parameters as well as the plot range.
You can also specify the scale for which the data should be generated (*linear* means the data is
evenly distributed, *log* means the data is exponentially distributed so it will be evenly
distributed when using a log-scale).

Also:

* You can stack multiple single-differential cross sections by dropping them onto the same canvas.
* You can add a new canvas by clicking on the "add" button on the very right.
* You can change the scale for each axis at the bottom of the corresponding plot.


Usage within your applications
``````````````````````````````

This package contains various ionization cross sections as well as related auxiliary functions
(such as random sampling). Two kinds of ionization cross sections are provided:

* Single differential ionization cross sections (SDCS); see ``cross_sections.ddcs``.
* Double differential ionization cross sections (DDCS); see ``cross_sections.sdcs``.

Required parameters for cross sections must be specified in their ``__init__`` methods. A cross
section can be evaluated by calling it (via ``__call__``) (for the signature see the help text of
one of the cross sections). SDCS require the kinetic energy of the ionized particle as an argument
while DDCS also require the polar scattering angle (in addition).

Random sampling is available for double differential cross sections. Two general methods are available
which are meant to work with any two-dimensional distribution:

* Inverse transform sampling
* Rejection sampling

Please consider ``cross_sections.ddcs.random_sampling`` for more information.


Examples
--------

.. code:: python

>>> from ionics.ddcs.voitkiv import VoitkivDDCS
>>> ddcs = VoitkivDDCS(4.0e9, 1, 'H') # 4 TeV protons on Hydrogen.
>>> ddcs(10, pi/2) # Kinetic energy 10eV, transverse scattering.
0.00043127346990368256


>>> from ionics.ddcs.voitkiv import VoitkivDDCS
>>> ddcs = VoitkivDDCS(4.0e9, 1, 'H') # 4 TeV protons on Hydrogen.
>>> ddcs(10, pi/2) # Kinetic energy 10eV, transverse scattering.
0.00043127346990368256


>>> from cross_sections.ddcs.voitkiv import VoitkivDDCS
>>> ddcs = VoitkivDDCS(4.0e9, 1, 'H') # 4 TeV protons on Hydrogen.
>>> ddcs(10, pi/2) # Kinetic energy 10eV, transverse scattering.
0.00043127346990368256