Merge #519 from hakonanes/numpy-quaternion-optional

Make numpy-quaternion optional

.github/workflows/build.yml

@@ -50,6 +50,9 @@ jobs:
             python-version: 3.8
             DEPENDENCIES: diffpy.structure==3.0.2  matplotlib==3.5
             LABEL: -oldest
+          - os: ubuntu-latest
+            python-version: 3.11
+            LABEL: -minimum_requirement
     steps:
       - uses: actions/checkout@v4
 
@@ -58,10 +61,16 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install depedencies and package
+      - name: Install core depedencies and package
+        shell: bash
+        run: |
+          pip install -U -e .'[tests,coverage]'
+
+      - name: Install optional dependencies
+        if: ${{ !contains(matrix.LABEL, 'minimum_requirement') }}
         shell: bash
         run: |
-          pip install -U -e .'[doc,tests,coverage]'
+          pip install -e .'[all]'
 
       - name: Install oldest supported version
         if: ${{ contains(matrix.LABEL, 'oldest') }}

.gitignore

@@ -63,7 +63,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-doc/build/
+_build/
 doc/examples/
 doc/reference/generated/
 doc/source/_autosummary/

RELEASE.rst

@@ -1,7 +1,7 @@
 How to make a new release of ``orix``
 =====================================
 
-After version 0.9.0, orix' branching model changed to one similar to the Gitflow
+After version 0.9.0, orix's branching model changed to one similar to the Gitflow
 Workflow (`original blog post
 <https://nvie.com/posts/a-successful-git-branching-model/>`__).
 

doc/Makefile

@@ -6,7 +6,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = PYDEVD_DISABLE_FILE_VALIDATION=1 python -Xfrozen_modules=off -m sphinx
 SOURCEDIR     = .
-BUILDDIR      = build
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:

doc/conf.py

@@ -6,10 +6,8 @@
 import inspect
 import os
 from os.path import dirname, relpath
-from pathlib import Path
 import re
 import sys
-import tomllib
 
 from numpydoc.docscrape_sphinx import SphinxDocString
 
@@ -22,13 +20,8 @@
 # sys.path.insert(0, os.path.abspath("."))
 sys.path.append("../")
 
-top_dir = Path(__file__).parent.parent
-
-with open(top_dir / "pyproject.toml", "rb") as f:
-    metadata = tomllib.load(f)
-
-project = metadata["project"]["name"]
-author = metadata["project"]["authors"][0]["name"]
+project = "orix"
+author = "orix developers"
 copyright = f"2018-{str(datetime.now().year)}, {author}"
 release = orix.__version__
 
@@ -66,8 +59,10 @@
     "matplotlib": ("https://matplotlib.org/stable", None),
     "nbsphinx": ("https://nbsphinx.readthedocs.io/en/latest", None),
     "nbval": ("https://nbval.readthedocs.io/en/latest", None),
+    "numba": ("https://numba.readthedocs.io/en/latest", None),
     "numpy": ("https://numpy.org/doc/stable", None),
     "numpydoc": ("https://numpydoc.readthedocs.io/en/latest", None),
+    "pooch": ("https://www.fatiando.org/pooch/latest", None),
     "pytest": ("https://docs.pytest.org/en/stable", None),
     "python": ("https://docs.python.org/3", None),
     "pyxem": ("https://pyxem.readthedocs.io/en/latest", None),
@@ -85,7 +80,7 @@
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
-    "build",
+    "_build",
     "Thumbs.db",
     ".DS_Store",
     # Suppress warnings from Sphinx regarding "duplicate source files":
@@ -336,7 +331,7 @@ def _str_examples(self):
     "filename_pattern": "^((?!sgskip).)*$",
     "gallery_dirs": "examples",
     "reference_url": {"orix": None},
-    "run_stale_examples": True,
+    "run_stale_examples": False,
     "show_memory": True,
 }
 autosummary_generate = True

doc/user/installation.rst

@@ -13,10 +13,18 @@ With pip
 ========
 
 orix is availabe from the Python Package Index (PyPI), and can therefore be installed
-with `pip <https://pip.pypa.io/en/stable>`__. To install, run the following::
+with `pip <https://pip.pypa.io/en/stable>`__.
+To install all of orix's functionality, do::
+
+    pip install orix[all]
+
+To install only the strictly required dependencies with limited functionality, do::
 
     pip install orix
 
+See :ref:`dependencies` for the base and optional dependencies and alternatives for how
+to install these.
+
 To update orix to the latest release::
 
     pip install --upgrade orix
@@ -25,7 +33,7 @@ To install a specific version of orix (say version 0.8.1)::
 
     pip install orix==0.8.1
 
-.. _optional-dependencies:
+.. _install-with-anaconda:
 
 With Anaconda
 =============
@@ -35,16 +43,23 @@ To install with Anaconda, we recommend you install it in a `conda environment
 with the `Miniconda distribution <https://docs.conda.io/en/latest/miniconda.html>`__.
 To create an environment and activate it, run the following::
 
-   conda create --name orix-env python=3.9
+   conda create --name orix-env python=3.11
    conda activate orix-env
 
 If you prefer a graphical interface to manage packages and environments, you can install
 the `Anaconda distribution <https://docs.continuum.io/anaconda>`__ instead.
 
-To install::
+To install all of orix's functionality, do::
 
     conda install orix --channel conda-forge
 
+To install only the strictly required dependencies with limited functionality, do::
+
+    conda install orix-base -c conda-forge
+
+See :ref:`dependencies` for the base and optional dependencies and alternatives for how
+to install these.
+
 To update orix to the latest release::
 
     conda update orix
@@ -74,4 +89,43 @@ exchanged with ``zip``.
 See the :ref:`contributing guide <setting-up-a-development-installation>` for how to set
 up a development installation and keep it up to date.
 
-.. _https://github.com/pyxem/orix/archive/v<major.minor.patch>/orix-<major.minor.patch>.tar.gz: https://github.com/pyxem/orix/archive/v<major.minor.patch>/orix-<major.minor.patch>.tar.gz
+.. _https://github.com/pyxem/orix/archive/v<major.minor.patch>/orix-<major.minor.patch>.tar.gz: https://github.com/pyxem/orix/archive/v<major.minor.patch>/orix-<major.minor.patch>.tar.gz
+
+
+.. _dependencies:
+
+Dependencies
+============
+
+orix builds on the great work and effort of many people.
+This is a list of core package dependencies:
+
+================================================ ================================================
+Package                                          Purpose
+================================================ ================================================
+:doc:`dask<dask:index>`                          Out-of-memory processing of data larger than RAM
+:doc:`diffpy.structure <diffpy.structure:index>` Handling of crystal structures
+:doc:`h5py <h5py:index>`                         Read/write of HDF5 files
+:doc:`matplotlib <matplotlib:index>`             Visualization
+`matplotlib-scalebar`_                           Scale bar for crystal map plots
+:doc:`numba <numba:index>`                       CPU acceleration
+:doc:`numpy <numpy:index>`                       Handling of N-dimensional arrays
+:doc:`pooch <pooch:api/index>`                   Downloading and caching of datasets
+:doc:`scipy <scipy:index>`                       Optimization algorithms, filtering and more
+`tqdm <https://tqdm.github.io/>`__               Progressbars
+================================================ ================================================
+
+.. _matplotlib-scalebar: https://github.com/ppinard/matplotlib-scalebar
+
+Some functionality requires optional dependencies:
+
+=================== ===========================================
+Package             Purpose                                    
+=================== ===========================================
+`numpy-quaternion`_ Faster quaternion and vector multiplication
+=================== ===========================================
+
+.. _numpy-quaternion: https://quaternion.readthedocs.io/en/stable/
+
+Optional dependencies can be installed either with ``pip install orix[all]`` or by
+installing each dependency separately, such as ``pip install orix numpy-quaternion``.

examples/plotting/subplots.py

@@ -3,7 +3,7 @@
 Subplots
 ========
 
-This example shows how to place different plots in the same figure using orix' various
+This example shows how to place different plots in the same figure using orix's various
 :mod:`plot types <orix.plot>`, which extend Matplotlib's plot types.
 
 By first creating a blank figure and then using

orix/_base.py

@@ -271,7 +271,7 @@ def reshape(self, *shape: Union[int, tuple]) -> Object3d:
         if len(shape) == 1 and isinstance(shape[0], tuple):
             shape = shape[0]
         obj = self.__class__(self.data.reshape(*shape, self.dim))
-        obj._data = self._data.reshape(*shape, -1)
+        obj._data = self._data.reshape(*shape, self._data.shape[-1])
         return obj
 
     def transpose(self, *axes: Optional[int]) -> Object3d:

orix/constants.py

@@ -0,0 +1,38 @@
+# Copyright 2018-2024 the orix developers
+#
+# This file is part of orix.
+#
+# orix is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# orix is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with orix.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Constants and such useful across modules."""
+
+from importlib.metadata import version
+
+# NB! Update project config file if this list is updated!
+optional_deps: list[str] = ["numpy-quaternion"]
+installed: dict[str, bool] = {}
+for pkg in optional_deps:
+    try:
+        _ = version(pkg)
+        installed[pkg] = True
+    except ImportError:
+        installed[pkg] = False
+
+# Typical tolerances for comparisons in need of a precision. We
+# generally use the highest precision possible (allowed by testing on
+# different OS and Python versions).
+eps9 = 1e-9
+eps12 = 1e-12
+
+del optional_deps

orix/io/plugins/orix_hdf5.py

@@ -16,7 +16,7 @@
 # You should have received a copy of the GNU General Public License
 # along with orix.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Reader and writer of a crystal map to and from orix' own HDF5 file
+"""Reader and writer of a crystal map to and from orix's own HDF5 file
 format.
 """
 
@@ -44,7 +44,7 @@
 
 
 def file_reader(filename: str, **kwargs) -> CrystalMap:
-    """Return a crystal map from a file in orix' HDF5 file format.
+    """Return a crystal map from a file in orix's HDF5 file format.
 
     Parameters
     ----------