Merge branch 'release-0.1.0' into 'master'

Release 0.1.0

See merge request empyre/empyre!27

.gitlab-ci.yml

@@ -17,7 +17,7 @@ test_style:
     image: continuumio/miniconda3:latest
     script:
         # -m: only run tests marked with "flake8"
-        - pyroma . --min=9  # Checks setup.py for cheese! # TODO: Set to maxium cheese (10)!
+        - pyroma . --min=10  # Checks setup.py for cheese! Maxium cheese 10!
         - python setup.py test --addopts "--flake8 -m flake8"
 
 test_function:
@@ -39,7 +39,8 @@ test_docs:
         # -e: Put documentation for each module on its own page.
         # -o: Directory to place the output files. If it does not exist, it is created.
         # last parameter: module path
-        - sphinx-apidoc -f -e -o docs/api src/empyre
+        - python setup.py  clean  # TODO: Simplest way to generate version.py without doing anything else?
+        #- sphinx-apidoc -f -e -o docs/api src/empyre
         # Build the documentation from 'docs' and put into 'build/sphinx':
         - sphinx-build docs build/sphinx
     artifacts:

README.rst

-The documentation can be found [here](https://empyre.iffgit.fz-juelich.de/empyre/)!
+|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 `HyperSpy <https://hyperspy.org/>`_ package that is 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.
+
+* ``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 submodules which are fully documented `here <https://empyre.iffgit.fz-juelich.de/empyre/>`_!
+
+* The ``fields`` submodule provides the ``Field`` container class for multidimensional scalar or vector fields and is the fundamental data structure used in EMPyRe.
+
+* The ``vis`` submodule enables the plotting of ``Field`` objects, based on and similar in syntax to the commonly known `matplotlib <https://matplotlib.org/>`_ framework.
+
+* The ``models`` submodule provides tools for constructing forward models that describe processes in Electron Microscopy.
+
+* The ``reconstruct`` submodule is a collection of tools for solving the inverse problems corresponding to the constructed forward models and diagnostic tools for their assessment.
+
+* The ``io`` submodule is used to load and save ``Field`` objects and the models generated by the ``models`` subpackage.
+
+
+
+License
+-------
+EMPyRe is licensed under `GPLv3 <https://iffgit.fz-juelich.de/empyre/empyre/-/blob/master/LICENSE>`_.

docs/api/empyre.fields.rst

-empyre.fields package
-=====================
-
-Submodules
-----------
-
-empyre.fields.field module
---------------------------
-
-.. automodule:: empyre.fields.field
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-empyre.fields.shapes module
----------------------------
-
-.. automodule:: empyre.fields.shapes
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-empyre.fields.vectors module
-----------------------------
-
-.. automodule:: empyre.fields.vectors
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: empyre.fields
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/api/empyre.io.rst

-empyre.io package
-=================
-
-Module contents
----------------
-
-.. automodule:: empyre.io
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/api/empyre.models.rst

-empyre.models package
-=====================
-
-Module contents
----------------
-
-.. automodule:: empyre.models
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/api/empyre.reconstruct.rst

-empyre.reconstruct package
-==========================
-
-Module contents
----------------
-
-.. automodule:: empyre.reconstruct
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/api/empyre.rst

-empyre package
-==============
-
-Subpackages
------------
-
-.. toctree::
-
-   empyre.fields
-   empyre.io
-   empyre.models
-   empyre.reconstruct
-   empyre.vis
-
-Submodules
-----------
-
-empyre.version module
----------------------
-
-.. automodule:: empyre.version
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: empyre
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/api/empyre.vis.rst

-empyre.vis package
-==================
-
-Submodules
-----------
-
-empyre.vis.colors module
-------------------------
-
-.. automodule:: empyre.vis.colors
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-empyre.vis.decorators module
-----------------------------
-
-.. automodule:: empyre.vis.decorators
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-empyre.vis.plot2d module
-------------------------
-
-.. automodule:: empyre.vis.plot2d
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-empyre.vis.tools module
------------------------
-
-.. automodule:: empyre.vis.tools
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: empyre.vis
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/api/modules.rst

-empyre
-======
-
-.. toctree::
-   :maxdepth: 4
-
-   empyre

docs/conf.py

@@ -35,8 +35,7 @@ author = 'Jan Caron'
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
+    'sphinx.ext.viewcode',
     'numpydoc'
 ]
 

docs/fields.rst

 The Field container class
 =========================
 
-Field docu here!
+General empyre.fields docu here!
+
+
+The field submodule
+-------------------
+
+.. automodule:: empyre.fields.field
+   :members:
+   :show-inheritance:
+
+
+The shapes submodule
+--------------------
+
+.. automodule:: empyre.fields.shapes
+   :members:
+   :show-inheritance:
+
+
+The vectors submodule
+---------------------
+
+.. automodule:: empyre.fields.vectors
+   :members:
+   :show-inheritance:

docs/index.rst

@@ -3,8 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to EMPyRe's documentation!
-==================================
+EMPyRe - Electron Microscopy Reconstruction
+===========================================
 
 .. include:: ../README.rst
 

docs/vis.rst

 The vis visualization submodule
 ===============================
 
-vis docu here!
+General empyre.vis docu here!
+
+
+The plot2d submodule
+--------------------
+
+.. automodule:: empyre.vis.plot2d
+   :members:
+   :show-inheritance:
+
+
+The decorators submodule
+------------------------
+
+.. automodule:: empyre.vis.decorators
+   :members:
+   :show-inheritance:
+
+
+The colors submodule
+--------------------
+
+.. automodule:: empyre.vis.colors
+   :members:
+   :show-inheritance:
+
+
+The tools submodule
+-------------------
+
+.. automodule:: empyre.vis.tools
+   :members:
+   :show-inheritance:

environment.yml

@@ -38,7 +38,7 @@ dependencies:
   #- pytest-mpl=0.10  # Needed for testing hyperspy! # TODO: Use for pyramid/plotting library, too!
   - coverage=4.5
   # Documentation:
-  - sphinx=2.1
+  - sphinx=2.4
   - numpydoc=0.9
   - sphinx_rtd_theme=0.4  # TODO: not needed?
   # IPython and notebooks:

src/empyre/fields/field.py

@@ -438,7 +438,7 @@ class Field(NDArrayOperatorsMixin):
         The calculation depends on the input:
         3 dimensions, 3 components: Calculates the full 3D rotational vector field!
         2 dimensions, 2 components: Calculates the out-of-plane component of the curl as a 2D scalar field!
-        2 dimensions, scalar: Calculates the planar rotatio as a 2D vector field!
+        2 dimensions, scalar: Calculates the planar rotation as a 2D vector field!
 
         """
         self._log.debug('Calling curl')
@@ -447,12 +447,12 @@ class Field(NDArrayOperatorsMixin):
             if squeezed_field.ncomp == 3:  # 3 component vector field (standard case):
                 self._log.debug('input: 3 dimensions, 3 components!')
                 field_x, field_y, field_z = squeezed_field.comp
-                grad_xx, grad_xy, grad_xz = field_x.gradient().comp
-                grad_yx, grad_yy, grad_yz = field_y.gradient().comp
-                grad_zx, grad_zy, grad_zz = field_z.gradient().comp
-                curl_x = grad_zy - grad_yz
-                curl_y = grad_xz - grad_zx
-                curl_z = grad_yx - grad_xy
+                gradx_x, grady_x, gradz_x = field_x.gradient().comp
+                gradx_y, grady_y, gradz_y = field_y.gradient().comp
+                gradx_z, grady_z, gradz_z = field_z.gradient().comp
+                curl_x = grady_z - gradz_y
+                curl_y = gradz_x - gradx_z
+                curl_z = gradx_y - grady_x
                 return Field.from_scalar_fields([curl_x, curl_y, curl_z])
             else:
                 raise AssertionError('Can only handle 3 component vector fields in 3D!')
@@ -460,14 +460,14 @@ class Field(NDArrayOperatorsMixin):
             if squeezed_field.ncomp == 2:  # 2 component vector field (return perpendicular component as scalar field):
                 self._log.debug('input: 2 dimensions, 2 components!')
                 field_x, field_y = squeezed_field.comp
-                grad_xx, grad_xy = field_x.gradient().comp
-                grad_yx, grad_yy = field_y.gradient().comp
-                return grad_yx - grad_xy
+                gradx_x, grady_x = field_x.gradient().comp
+                gradx_y, grady_y = field_y.gradient().comp
+                return gradx_y - grady_x
             elif not squeezed_field.vector:  # scalar field (return planar components as 2D vector field):
                 self._log.debug('input: 3 dimensions, scalar field!')
-                grad_x, grad_y = squeezed_field.gradient().comp
-                curl_x = grad_y
-                curl_y = -grad_x
+                gradx, grady = squeezed_field.gradient().comp
+                curl_x = grady
+                curl_y = -gradx
                 return Field.from_scalar_fields([curl_x, curl_y])
             else:
                 raise AssertionError('Can only handle 3 component vector or scalar fields in 2D!')
@@ -475,7 +475,7 @@ class Field(NDArrayOperatorsMixin):
             raise AssertionError('Can only handle 3D or 2D cases (see documentation for specifics)!')
 
     def clip(self, vmin=None, vmax=None, sigma=None, mask=None):
-        """Clip (limit) the values in an array. For vector fields, this will take the amplitude into account
+        """Clip (limit) the values in an array. For vector fields, this will take the amplitude into account.
 
         Parameters
         ----------
@@ -517,9 +517,8 @@ class Field(NDArrayOperatorsMixin):
         if vmax is None:
             vmax = np.nanmax(amp_masked)
         if self.vector:  # Vector fields need to scale components according to masked amplitude
-            mask_vec = np.logical_and(mask, amp <= vmax)  # Only vmax is important!
-            data = amp / np.where(mask_vec, 1, amp)  # TODO: needs testing!
-            # TODO: Test np.clip(field) (also ufunc?? think not...) seems to work, but what about others?
+            mask_vec = (amp <= vmax)[..., None]  # Only vmax is important for vectors! mask_vec broadcast to components!
+            data = np.where(mask_vec, self.data, vmax * self.data/amp[..., None])  # Scale outliers to vmax!
         else:  # For scalar fields, just delegate to the numpy function:
             data = np.clip(self.data, vmin, vmax)
         return Field(data, self.scale, self.vector)