spectrochempy-hypercomplex 0.1.1__tar.gz

spectrochempy_hypercomplex-0.1.1/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: spectrochempy-hypercomplex
+Version: 0.1.1
+Summary: Hypercomplex / quaternion support plugin for SpectroChemPy
+Requires-Python: >=3.11
+Requires-Dist: spectrochempy<0.10,>=0.9.0.dev0
+Requires-Dist: numpy
+Requires-Dist: numpy-quaternion>=2024.0.7

spectrochempy_hypercomplex-0.1.1/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spectrochempy-hypercomplex"
+version = "0.1.1"
+description = "Hypercomplex / quaternion support plugin for SpectroChemPy"
+requires-python = ">=3.11"
+dependencies = [
+    "spectrochempy>=0.9.0.dev0,<0.10",
+    "numpy",
+    "numpy-quaternion>=2024.0.7",
+]
+
+[project.entry-points."spectrochempy.plugins"]
+hypercomplex = "spectrochempy_hypercomplex:HyperComplexPlugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

spectrochempy_hypercomplex-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spectrochempy_hypercomplex-0.1.1/src/spectrochempy_hypercomplex/__init__.py

@@ -0,0 +1,338 @@
+# ruff: noqa: PLC0415 — defer imports in plugin methods to avoid startup cost
+"""Hypercomplex / quaternion support plugin for SpectroChemPy."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+
+from spectrochempy.api.plugins import CORE_PLUGIN_API_VERSION
+from spectrochempy.api.plugins import PluginCapability
+from spectrochempy.api.plugins import SpectroChemPyPlugin
+
+# Public quaternion utilities — safe for other plugins to import
+from ._quaternion import _HAS_QUATERNION as is_available  # noqa: F401, N811
+from ._quaternion import as_float_array  # noqa: F401
+from ._quaternion import as_quat_array  # noqa: F401
+from ._quaternion import as_quaternion  # noqa: F401
+
+
+class HyperAccessor:
+    """
+    Dataset accessor for hypercomplex / quaternion operations.
+
+    Accessed via ``dataset.hyper``.
+    """
+
+    def __init__(self, dataset) -> None:
+        self._dataset = dataset
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def is_quaternion(self) -> bool:
+        """True if the data array is hypercomplex (quaternion)."""
+        from ._quaternion import typequaternion  # noqa: PLC0415
+
+        return (
+            typequaternion is not None and self._dataset._data.dtype == typequaternion
+        )
+
+    @property
+    def RR(self):
+        """Real-real component of a 2D hypercomplex array."""
+        if not self.is_quaternion:
+            raise TypeError("Not a hypercomplex array")
+        return self.component("RR")
+
+    @property
+    def RI(self):
+        """Real-imaginary component of a 2D hypercomplex array."""
+        if not self.is_quaternion:
+            raise TypeError("Not a hypercomplex array")
+        return self.component("RI")
+
+    @property
+    def IR(self):
+        """Imaginary-real component of a 2D hypercomplex array."""
+        if not self.is_quaternion:
+            raise TypeError("Not a hypercomplex array")
+        return self.component("IR")
+
+    @property
+    def II(self):
+        """Imaginary-imaginary component of a 2D hypercomplex array."""
+        if not self.is_quaternion:
+            raise TypeError("Not a hypercomplex array")
+        return self.component("II")
+
+    # ------------------------------------------------------------------
+    # Methods
+    # ------------------------------------------------------------------
+
+    def set_quaternion(self, inplace=False):
+        """Convert the dataset data to quaternion (hypercomplex) type."""
+        from ._quaternion import typequaternion  # noqa: PLC0415
+
+        if typequaternion is None:
+            raise RuntimeError(
+                "numpy-quaternion is required for hypercomplex support. "
+                "Install it with: pip install numpy-quaternion"
+            )
+
+        new = self._dataset if inplace else self._dataset.copy()
+        dtype = new._data.dtype if hasattr(new._data, "dtype") else new.dtype
+        if dtype != typequaternion:
+            new._data = _make_quaternion(new.data)
+        if not inplace:
+            return new
+        return None
+
+    set_hypercomplex = set_quaternion
+    set_hypercomplex.__doc__ = "Alias of set_quaternion."
+
+    def component(self, select="REAL"):
+        """
+        Extract a named component from a hypercomplex array.
+
+        Parameters
+        ----------
+        select : str
+            Component selector: ``"RR"``, ``"RI"``, ``"IR"``, ``"II"``,
+            or ``"REAL"`` / ``"R"`` / ``"I"`` for 1D complex data.
+        """
+        from ._quaternion import get_component  # noqa: PLC0415
+
+        return get_component(self._dataset.data, select)
+
+
+def _make_quaternion(data):
+    """Convert real/interleaved data to quaternion dtype."""
+    from ._quaternion import typequaternion  # noqa: PLC0415
+
+    if data.ndim == 0:
+        return data
+    if typequaternion is not None and data.dtype == typequaternion:
+        return data
+    if data.ndim == 1:
+        r, i = data[::2], data[1::2]
+        return as_quaternion(r, i)
+    if data.ndim == 2:
+        return as_quaternion(data[:, ::2], data[:, 1::2])
+    msg = (
+        "An array of data to be transformed to quaternion must be 2D or 1D, "
+        f"got {data.ndim}D."
+    )
+    raise ValueError(msg)
+
+
+# ------------------------------------------------------------------
+# NDMath handler implementations
+# ------------------------------------------------------------------
+
+
+# Ufunc names that numpy-quaternion handles natively (no decomposition needed).
+# Everything else must be decomposed into complex arrays, executed,
+# and recomposed.
+_NATIVE_QUATERNION_UFUNCS = frozenset(
+    [
+        "add",
+        "iadd",
+        "sub",
+        "isub",
+        "subtract",
+        "mul",
+        "imul",
+        "multiply",
+        "div",
+        "idiv",
+        "divide",
+        "true_divide",
+        "truediv",
+        "power",
+        "negative",
+        "positive",
+        "sign",
+        "equal",
+        "not_equal",
+        "less",
+        "less_equal",
+        "greater",
+        "greater_equal",
+        "isnan",
+        "isinf",
+        "isfinite",
+        "copysign",
+        "nextafter",
+        "spacing",
+        "maximum",
+        "minimum",
+        "fmax",
+        "fmin",
+        "absolute",
+        "fabs",
+        "conj",
+        "conjugate",
+    ]
+)
+
+
+def _hyper_ndmath_branch(fname: str, data: np.ndarray, args: list) -> str | None:
+    """Return ``"quaternion"`` when the operands require quaternion execution."""
+    from ._quaternion import typequaternion  # noqa: PLC0415
+
+    if typequaternion is None:
+        return None
+
+    is_quaternion = data.dtype == typequaternion
+    for arg in args:
+        if hasattr(arg, "dtype") and arg.dtype == typequaternion:
+            is_quaternion = True
+            break
+
+    if not is_quaternion:
+        return None
+
+    # numpy-quaternion handles these ufuncs natively — no need to decompose.
+    if fname in _NATIVE_QUATERNION_UFUNCS:
+        return None
+
+    return "quaternion"
+
+
+def _hyper_ndmath_execute(branch: str, f, d, args):
+    """Execute *f* on quaternion data *d* by decomposing into complex arrays."""
+    if branch != "quaternion":
+        return None
+    from ._quaternion import quat_as_complex_array  # noqa: PLC0415
+
+    dr, di = quat_as_complex_array(d)
+    datar = f(dr, *args)
+    datai = f(di, *args)
+    return as_quaternion(datar, datai)
+
+
+# ------------------------------------------------------------------
+# Numpy-method overrides for quaternion data
+# ------------------------------------------------------------------
+
+
+def _is_quaternion_dataset(dataset) -> bool:
+    """Return True if *dataset* carries quaternion data."""
+    from ._quaternion import typequaternion  # noqa: PLC0415
+
+    return (
+        typequaternion is not None
+        and hasattr(dataset, "_data")
+        and hasattr(dataset._data, "dtype")
+        and dataset._data.dtype == typequaternion
+    )
+
+
+def _hyper_numpy_abs(dataset, *args, **kwargs):
+    """Quaternion-aware absolute value."""
+    if not _is_quaternion_dataset(dataset):
+        return None
+
+    w, x, y, z = as_float_array(dataset.data).T
+    data = np.ma.sqrt(w**2 + x**2 + y**2 + z**2)
+    dataset._data = data.data
+    dataset._mask = getattr(data, "mask", False)
+    return dataset
+
+
+def _hyper_numpy_conjugate(dataset, *args, **kwargs):
+    """Quaternion-aware conjugate."""
+    if not _is_quaternion_dataset(dataset):
+        return None
+    dim = kwargs.get("dim", "x")
+    axis, _ = dataset.get_axis(dim, allows_none=True)
+    dataset = dataset.swapdims(axis, -1)
+    dataset[..., 1::2] = -dataset[..., 1::2]
+    return dataset.swapdims(axis, -1)
+
+
+def _hyper_numpy_max(dataset, *args, **kwargs):
+    """Quaternion-aware max — operates on the real (w) component."""
+    if not _is_quaternion_dataset(dataset):
+        return None
+
+    data = dataset.data
+    w = as_float_array(data)[..., 0]
+    axis = kwargs.get("axis")
+    keepdims = kwargs.get("keepdims", False)
+    m = np.ma.max(w, axis=axis, keepdims=keepdims)
+    if np.isscalar(m) or (m.size == 1 and not keepdims):
+        if not np.isscalar(m):
+            m = m[()]
+        if dataset.units is not None:
+            from spectrochempy.core.units import Quantity  # noqa: PLC0415
+
+            return Quantity(m, dataset.units)
+        return m
+    dataset._data = m.data
+    dataset._mask = getattr(m, "mask", False)
+    return dataset
+
+
+def _hyper_numpy_min(dataset, *args, **kwargs):
+    """Quaternion-aware min — operates on the real (w) component."""
+    if not _is_quaternion_dataset(dataset):
+        return None
+
+    data = dataset.data
+    w = as_float_array(data)[..., 0]
+    axis = kwargs.get("axis")
+    keepdims = kwargs.get("keepdims", False)
+    m = np.ma.min(w, axis=axis, keepdims=keepdims)
+    if np.isscalar(m) or (m.size == 1 and not keepdims):
+        if not np.isscalar(m):
+            m = m[()]
+        if dataset.units is not None:
+            from spectrochempy.core.units import Quantity  # noqa: PLC0415
+
+            return Quantity(m, dataset.units)
+        return m
+    dataset._data = m.data
+    dataset._mask = getattr(m, "mask", False)
+    return dataset
+
+
+# ------------------------------------------------------------------
+# Plugin class
+# ------------------------------------------------------------------
+
+
+class HyperComplexPlugin(SpectroChemPyPlugin):
+    """Hypercomplex / quaternion support for SpectroChemPy."""
+
+    name = "hypercomplex"
+    version = "0.1.0"
+    description = "Hypercomplex / quaternion data support"
+    spectrochempy_min_version = "0.9.0.dev0"
+    PLUGIN_API_VERSION = CORE_PLUGIN_API_VERSION
+    capabilities = [PluginCapability.ACCESSOR]
+
+    def register_accessors(self) -> list[dict]:
+        """Register the ``hyper`` dataset accessor."""
+        return [
+            {
+                "name": "hyper",
+                "func": HyperAccessor,
+                "description": "Hypercomplex / quaternion dataset operations",
+            },
+        ]
+
+    def register_handlers(self) -> dict[str, Callable]:
+        """Register NDMath execution handlers for quaternion dispatch."""
+        return {
+            "ndmath.execution_branch": _hyper_ndmath_branch,
+            "ndmath.execute": _hyper_ndmath_execute,
+            "ndmath.numpy_method.absolute": _hyper_numpy_abs,
+            "ndmath.numpy_method.conjugate": _hyper_numpy_conjugate,
+            "ndmath.numpy_method.amax": _hyper_numpy_max,
+            "ndmath.numpy_method.amin": _hyper_numpy_min,
+        }

spectrochempy_hypercomplex-0.1.1/src/spectrochempy_hypercomplex/_quaternion.py

@@ -0,0 +1,185 @@
+# ======================================================================================
+# Copyright (©) 2014-2026 Laboratoire Catalyse et Spectrochimie (LCS), Caen, France.
+# CeCILL-B FREE SOFTWARE LICENSE AGREEMENT
+# See full LICENSE agreement in the root directory.
+# ======================================================================================
+"""
+Optional quaternion support — internal to the hypercomplex plugin.
+
+The public API is exposed through :class:`HyperAccessor`.
+"""
+
+import warnings
+
+import numpy as np
+
+from spectrochempy.utils.constants import TYPE_COMPLEX
+
+# Try to import the quaternion library (optional dependency)
+_HAS_QUATERNION = False
+typequaternion = None
+as_float_array = None
+as_quat_array = None
+
+try:
+    from quaternion import as_float_array  # noqa: F811
+    from quaternion import as_quat_array  # noqa: F811
+
+    _HAS_QUATERNION = True
+    typequaternion = np.dtype(np.quaternion)
+except ImportError:
+    pass
+
+
+def _check():
+    if not _HAS_QUATERNION:
+        raise ImportError(
+            "Missing optional dependency 'numpy-quaternion'. "
+            "Use pip or conda to install numpy-quaternion."
+        )
+
+
+# ======================================================================================
+# Public methods
+# ======================================================================================
+def as_quaternion(*args):
+    """
+    Recombine the arguments to produce a numpy array with quaternion dtype.
+
+    Parameters
+    ----------
+    *args : `ndarray` with dtype: `float` or `complex`
+        The quaternion array components: If there is 4 components, then we assume it is
+        the four components of the
+        quaternion array: w, x, y, z. If there is only two, they are casted to complex
+        and correspond respectively
+        to w + i.x and y + j.z.
+
+    """
+    _check()
+    if len(args) == 4:
+        w, x, y, z = args
+    elif len(args) == 2:
+        r, i = args
+        w, x, y, z = r.real, r.imag, i.real, i.imag
+    else:
+        raise ValueError("as_quaternion requires 2 or 4 arguments")
+
+    data = as_quat_array(
+        list(zip(w.flatten(), x.flatten(), y.flatten(), z.flatten(), strict=False)),
+    )
+    return data.reshape(w.shape)
+
+
+def quat_as_complex_array(arr):
+    """
+    Recombine the component of a quaternion array into a tuple of two complex array.
+
+    Parameters
+    ----------
+    arr : quaternion ndarray
+        The arr will be separated into (w + i.x) and (y + i.z).
+
+    Returns
+    -------
+    tuple
+        Tuple of two complex array.
+
+    """
+    _check()
+    if typequaternion is None or arr.dtype != typequaternion:
+        return arr
+
+    wt, xt, yt, zt = as_float_array(arr).T
+    w, x, y, z = wt.T, xt.T, yt.T, zt.T
+
+    return (w + 1j * x), (y + 1j * z)
+
+
+def get_component(data, select="REAL"):
+    """
+    Take selected components of an hypercomplex array (RRR, RIR, ...).
+
+    Parameters
+    ----------
+    data : `ndarray`
+        Input data array.
+    select : `str`, optional, default: 'REAL'
+        If 'REAL', only real component in all dimensions will be selected.
+        Else a string must specify which real (R) or imaginary (I) component
+        has to be selected along a specific dimension. For instance,
+        a string such as 'RRI' for a 2D hypercomplex array indicated
+        that we take the real component in each dimension except the last
+        one, for which imaginary component is preferred.
+
+    Returns
+    -------
+    component
+        A component of the complex or hypercomplex array.
+
+    .. warning::
+        The definition is somewhat different from Bruker, as we order the component in
+        the order of the dimensions in
+        dataset:
+        e.g., for dims = ['y','x'], 'IR' means that the `y` component is imaginary
+        while the `x` is real.
+
+    """
+    if not select:
+        return data
+
+    new = data.copy()
+
+    if select == "REAL":
+        select = "R" * new.ndim
+
+    w = x = y = z = None
+
+    if typequaternion is not None and new.dtype == typequaternion:
+        w, x, y, z = as_float_array(new).T
+        w, x, y, z = w.T, x.T, y.T, z.T
+        if select == "R":
+            new = w + x * 1j
+        elif select == "I":
+            new = y + z * 1j
+        elif select == "RR":
+            new = w
+        elif select == "RI":
+            new = x
+        elif select == "IR":
+            new = y
+        elif select == "II":
+            new = z
+        else:
+            raise ValueError(
+                f"something wrong: cannot interpret `{select}` for hypercomplex (quaternion) data!",
+            )
+
+    elif new.dtype in TYPE_COMPLEX:
+        w, x = new.real, new.imag
+        if (select == "R") or (select == "RR"):
+            new = w
+        elif (select == "I") or (select == "RI"):
+            new = x
+        else:
+            raise ValueError(
+                f"something wrong: cannot interpret `{select}` for complex data!",
+            )
+    else:
+        warnings.warn(
+            f"No selection was performed because datasets with complex data have no "
+            f"`{select}` component. ",
+            stacklevel=2,
+        )
+
+    return new
+
+
+def interleaved2complex(data):
+    """Make a complex array from interleaved data."""
+    return data[..., ::2] + 1j * data[..., 1::2]
+
+
+def interleaved2quaternion(data):
+    """Make a complex array from interleaved data."""
+    return data[..., ::2] + 1j * data[..., 1::2]

spectrochempy_hypercomplex-0.1.1/src/spectrochempy_hypercomplex.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: spectrochempy-hypercomplex
+Version: 0.1.1
+Summary: Hypercomplex / quaternion support plugin for SpectroChemPy
+Requires-Python: >=3.11
+Requires-Dist: spectrochempy<0.10,>=0.9.0.dev0
+Requires-Dist: numpy
+Requires-Dist: numpy-quaternion>=2024.0.7

spectrochempy_hypercomplex-0.1.1/src/spectrochempy_hypercomplex.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+pyproject.toml
+src/spectrochempy_hypercomplex/__init__.py
+src/spectrochempy_hypercomplex/_quaternion.py
+src/spectrochempy_hypercomplex.egg-info/PKG-INFO
+src/spectrochempy_hypercomplex.egg-info/SOURCES.txt
+src/spectrochempy_hypercomplex.egg-info/dependency_links.txt
+src/spectrochempy_hypercomplex.egg-info/entry_points.txt
+src/spectrochempy_hypercomplex.egg-info/requires.txt
+src/spectrochempy_hypercomplex.egg-info/top_level.txt
+tests/test_hypercomplex.py

spectrochempy_hypercomplex-0.1.1/src/spectrochempy_hypercomplex.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

spectrochempy_hypercomplex-0.1.1/src/spectrochempy_hypercomplex.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[spectrochempy.plugins]
+hypercomplex = spectrochempy_hypercomplex:HyperComplexPlugin

spectrochempy_hypercomplex-0.1.1/src/spectrochempy_hypercomplex.egg-info/requires.txt

@@ -0,0 +1,3 @@
+spectrochempy<0.10,>=0.9.0.dev0
+numpy
+numpy-quaternion>=2024.0.7

spectrochempy_hypercomplex-0.1.1/src/spectrochempy_hypercomplex.egg-info/top_level.txt

@@ -0,0 +1 @@
+spectrochempy_hypercomplex

spectrochempy_hypercomplex-0.1.1/tests/test_hypercomplex.py

@@ -0,0 +1,49 @@
+# ruff: noqa: S101
+import pytest
+
+
+class TestHyperAccessor:
+    def test_accessor_registered(self):
+        import spectrochempy as scp
+
+        ds = scp.NDDataset([1.0, 2.0, 3.0])
+        assert hasattr(ds, "hyper")
+
+    def test_is_quaternion_false_for_real(self):
+        import spectrochempy as scp
+
+        ds = scp.NDDataset([1.0, 2.0, 3.0])
+        assert ds.hyper.is_quaternion is False
+
+    def test_set_quaternion_creates_quaternion_dtype(self):
+        import spectrochempy as scp
+
+        ds = scp.NDDataset([1.0, 2.0, 3.0, 4.0])
+        result = ds.hyper.set_quaternion()
+        # After conversion, the data should have a quaternion dtype
+        assert result._data.dtype.name == "quaternion"
+
+    def test_component_real_data_noop(self):
+        import spectrochempy as scp
+
+        ds = scp.NDDataset([1.0, 2.0, 3.0])
+        # For real data, get_component returns the array unchanged
+        result = ds.hyper.component("RR")
+        assert result is not None
+
+    def test_RR_RI_IR_II_raise_for_real(self):
+        import spectrochempy as scp
+
+        ds = scp.NDDataset([1.0, 2.0, 3.0])
+        for prop in ["RR", "RI", "IR", "II"]:
+            with pytest.raises(TypeError):
+                getattr(ds.hyper, prop)
+
+
+class TestNDMathHandlers:
+    def test_handler_registration(self):
+        from spectrochempy.plugins import manager
+
+        registry = manager.plugin_manager.registry
+        assert registry.get_handler("ndmath.execution_branch") is not None
+        assert registry.get_handler("ndmath.execute") is not None