Hypercomplex (quaternion) plugin๏ƒ

The spectrochempy-hypercomplex plugin extends SpectroChemPy with quaternion/hypercomplex data support. It is designed for scientific domains that need complex numbers in more than one dimension, most commonly phase-sensitive 2D NMR.

Why a plugin?๏ƒ

Hypercomplex data is powerful but niche. Keeping it in the core would:

  • add a heavy optional dependency (numpy-quaternion) to every SpectroChemPy installation;

  • embed NMR-specific assumptions into generic dataset infrastructure;

  • make the core harder to maintain and test for the majority of users who only need ordinary complex numbers.

By extracting hypercomplex support into an official plugin:

  • the core stays lightweight and domain-neutral;

  • NMR users can install full 2D support on demand;

  • the hypercomplex backend can evolve independently;

  • other scientific domains can reuse the same mechanism if needed.

Installation๏ƒ

Install the plugin directly or through the NMR extra:

pip install spectrochempy-hypercomplex

# or, together with the NMR plugin
pip install spectrochempy[nmr,hypercomplex]

The plugin is discovered automatically once installed. No explicit loading step is required.

Ordinary complex vs hypercomplex๏ƒ

An ordinary complex dataset stores one complex number per point:

import spectrochempy as scp
import numpy as np

c = scp.NDDataset(np.array([1+2j, 3+4j]))

A hypercomplex dataset stores two complex numbers per point, typically written as a quaternion:

\[q = w + x\,i + y\,j + z\,k\]

In 2D NMR this corresponds to four real arrays: RR, RI, IR, II (Real-Real, Real-Imaginary, Imaginary-Real, Imaginary-Imaginary).

The core SpectroChemPy package understands ordinary complex data natively. Hypercomplex data requires the plugin. Once installed, the plugin provides the dataset.hyper accessor and enables supported math and 2D NMR operations on quaternion arrays.

API overview๏ƒ

All hypercomplex operations are accessed through dataset.hyper:

Operation

Example

Convert to quaternion

dataset.hyper.set_quaternion(inplace=True)

Check type

dataset.hyper.is_quaternion

Extract RR component

dataset.hyper.RR

Extract RI component

dataset.hyper.component("RI")

Extract IR component

dataset.hyper.IR

Extract II component

dataset.hyper.II

2D NMR example๏ƒ

After reading a 2D TopSpin dataset, the NMR plugin can optionally convert the data to hypercomplex form (this happens automatically when both the NMR and hypercomplex plugins are installed):

import spectrochempy as scp

# Requires spectrochempy-nmr and spectrochempy-hypercomplex
dataset = scp.nmr.read_topspin("path/to/ser", expno=1)

# The NMR reader may already have called set_quaternion;
# if not, you can do it explicitly:
if not dataset.hyper.is_quaternion:
    dataset.hyper.set_quaternion(inplace=True)

# Now fft() understands STATES / TPPI / ECHO-ANTIECHO encodings
spectrum = dataset.fft()

# Extract a component for display
rr = spectrum.hyper.RR
rr.plot(method="map")

Future directions๏ƒ

The hypercomplex plugin is intentionally narrow at this stage:

  • it supports quaternion data in NDDataset;

  • it provides the numeric hooks needed by the core math framework;

  • it enables 2D NMR phase-sensitive workflows.

Possible future extensions (not yet planned):

  • octonion or other Clifford-algebra types for higher-dimensional data;

  • non-NMR uses of hypercomplex arrays (e.g. certain radar or optics signal-processing workflows);

  • additional component-extraction convenience methods.