|pipeline|_ |coverage|_ |pypi|_

.. |pipeline| image:: https://iffgit.fz-juelich.de/empyre/empyre/badges/master/pipeline.svg
.. _pipeline: https://iffgit.fz-juelich.de/empyre/empyre/commits/master

.. |coverage| image:: https://iffgit.fz-juelich.de/empyre/empyre/badges/master/coverage.svg
.. _coverage: https://iffgit.fz-juelich.de/empyre/empyre

.. |pypi| image:: https://badge.fury.io/py/empyre.svg
.. _pypi: https://pypi.org/project/empyre/


EMPyRe is an open source framework for constructing and solving hyperdimensional inverse problems and visualizing the corresponding input and output data. it has
its roots in the reconstruction of three-dimensional magnetization distributions from magnetic phase images generated by electron holography but is meant to be
extendable for many other problems that are based on forward models that are expressable as a combination of linear subproblems. EMPyRe is purely Python
package, so all platforms should be supported.


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

EMPyRe is available on the `Python Package Index <http://pypi.python.org/pypi>`_ and can be simply be installed via `pip <http://pypi.python.org/pypi/pip>`_:

.. code-block:: bash

    $ pip install empyre

Per default, only the strictly required libraries are installed, but there are a few additional dependencies that will unlock additional capabilites of EMPYRE.

* ``io`` will install the `tvtk <http://docs.enthought.com/mayavi/tvtk/README.html>`_  & `HyperSpy <https://hyperspy.org/>`_ packages that are used for loading and saving additional file formats.

    .. warning::
        Due to this `issue <https://github.com/hyperspy/hyperspy/issues/2315>`_, a pip install of hyperspy is currently not possible. Please use
        `conda <https://docs.conda.io/en/latest/>`_ to install HyperSpy, instead.


* ``fftw`` will install `PyFFTW <https://github.com/pyFFTW/pyFFTW>`_ to speed up Fourier transforms used in some forward models.

* ``colors`` will install the `cmocean <https://matplotlib.org/cmocean/>`_, whose ``balance`` color map is used as a default for the ``imshow`` commmand, if available.

* ``tests`` will install all dependencies that are needed to test the package (usually not necessary for the average user).

* ``all`` will install all of the dependencies listed above.


You can choose these settings by using, *e.g.*:

.. code-block:: bash

    $ pip install empyre[all]


Structure
---------

EMPyRe has several dedicated modules which are fully documented `here <https://empyre.iffgit.fz-juelich.de/empyre/>`_!

* The ``fields`` module provides the ``Field`` container class for multidimensional scalar or vector fields and is the fundamental data structure used in EMPyRe.

* The ``vis`` module enables the plotting of ``Field`` objects, based on and similar in syntax to the commonly known `matplotlib <https://matplotlib.org/>`_ framework.

* The ``models`` module provides tools for constructing forward models that describe processes in Electron Microscopy.

* The ``reconstruct`` module is a collection of tools for solving the inverse problems corresponding to the constructed forward models and diagnostic tools for their assessment.

* The ``io`` module is used to load and save ``Field`` objects and the models generated by the ``models`` subpackage.

* The ``utils`` module, which houses utility functionality used throughout EMPyRe.



License
-------
EMPyRe is licensed under `GPLv3 <https://iffgit.fz-juelich.de/empyre/empyre/-/blob/master/LICENSE>`_.
