hypercomplex-engine 1.0.1__py3-none-any.whl

hypercomplex/core/fast/fast_standard.py

@@ -0,0 +1,124 @@
+from ..validation import Validation
+from .bit_utils import nu2, popcount
+
+
+class FastStandard:
+    """
+    Standard Cayley-Dickson O(1) multiplier.
+
+    Input / output convention:
+        (sign, index)
+
+    The sign is computed in O(1) Word-RAM time using:
+        t  = nu2(i XOR j)
+        ti = nu2(i)
+        tj = nu2(j)
+
+    The basis index is always:
+        i XOR j
+    """
+
+    def multiply(self, t1: tuple, t2: tuple) -> tuple:
+        """
+        Multiply two standard basis element tuples.
+
+        t1 = (sign1, index1)
+        t2 = (sign2, index2)
+
+        Returns:
+            (final_sign, index1 XOR index2)
+        """
+        Validation.basis_tuple(t1, allow_zero=True, allow_eps=False)
+        Validation.basis_tuple(t2, allow_zero=True, allow_eps=False)
+
+        s1, i = int(t1[0]), int(t1[1])
+        s2, j = int(t2[0]), int(t2[1])
+
+        if s1 == 0 or s2 == 0:
+            return (0, 0)
+
+        sign, idx = self.multiply_indices(i, j)
+
+        return (s1 * s2 * sign, idx)
+
+    def multiply_indices(self, i: int, j: int) -> tuple:
+        """
+        Core O(1) multiplication for non-negative integer indices.
+
+        Returns:
+            (sign, i XOR j)
+        """
+        i = int(i)
+        j = int(j)
+
+        if i < 0 or j < 0:
+            raise ValueError("indices must be >= 0")
+
+        # Identity
+        if i == 0 or j == 0:
+            return (1, i ^ j)
+
+        # Main diagonal
+        if i == j:
+            return (-1, 0)
+
+        # Structural break levels
+        t = nu2(i ^ j)
+        ti = nu2(i)
+        tj = nu2(j)
+
+        # --------------------------------------------------------------
+        # Diagonal break:
+        #   t >= ti and t >= tj
+        # --------------------------------------------------------------
+        if t >= ti and t >= tj:
+            k = t + 1
+            s = 2 * ((i >> t) & 1) - 1
+
+        # --------------------------------------------------------------
+        # i-axis break:
+        #   ti > t and ti >= tj
+        # --------------------------------------------------------------
+        elif ti >= tj:
+            k = ti + 1
+
+            # Quadrant bit:
+            #   0 -> quadrant c
+            #   1 -> quadrant d
+            b = (j >> ti) & 1
+
+            # Local j below the break level
+            j_loc = j & ((1 << ti) - 1)
+
+            # delta(j_loc):
+            #   +1 if j_loc == 0
+            #   -1 otherwise
+            delta = 1 if j_loc == 0 else -1
+
+            if b == 0:
+                # quadrant c
+                s = delta
+            else:
+                # quadrant d
+                s = -delta
+
+        # --------------------------------------------------------------
+        # j-axis break:
+        #   tj > t and tj > ti
+        # --------------------------------------------------------------
+        else:
+            k = tj + 1
+
+            # Quadrant bit:
+            #   0 -> quadrant b, sign +1
+            #   1 -> quadrant d, sign -1
+            s = 1 - 2 * ((i >> tj) & 1)
+
+        # --------------------------------------------------------------
+        # Higher-bit parity correction:
+        # standard flips in quadrants b, c, d
+        # --------------------------------------------------------------
+        if popcount((i | j) >> k) & 1:
+            s = -s
+
+        return (s, i ^ j)

hypercomplex/core/holographic/__init__.py

@@ -0,0 +1,9 @@
+from .standard import StandardHolographic
+from .split import SplitHolographic
+from .dual import DualHolographic
+
+__all__ = [
+    "StandardHolographic",
+    "SplitHolographic",
+    "DualHolographic",
+]

hypercomplex/core/holographic/dual.py

@@ -0,0 +1,88 @@
+from ..validation import Validation
+from .standard import StandardHolographic
+from .split import SplitHolographic
+
+
+class DualHolographic:
+    """
+    Dual Cayley-Dickson holographic multiplier.
+
+    Input index convention:
+        The total dual dimension is 2^(dim + 1).
+        Bit `dim` marks the epsilon component.
+
+        lower half: 0 ... 2^dim - 1
+        upper half: epsilon times lower half
+
+    Output:
+        (sign, local_index, eps_flag)
+
+    Nilpotency:
+        (epsilon e_i) * (epsilon e_j) = 0
+        returned as (0, 0, 1)
+    """
+
+    def __init__(self, split: bool = False):
+        self._split_mode = bool(split)
+        self._standard = StandardHolographic()
+        self._split = SplitHolographic() if self._split_mode else None
+
+    def multiply(self, t1: tuple, t2: tuple, dim: int) -> tuple:
+        """
+        Multiply two dual basis elements.
+
+        t1, t2 may be:
+            (sign, global_index)
+            (sign, global_index, eps_flag)
+
+        The epsilon component is determined by bit `dim` of global_index.
+
+        Returns:
+            (final_sign, local_index, eps_flag)
+        """
+        Validation.basis_tuple(t1, allow_zero=True, allow_eps=True)
+        Validation.basis_tuple(t2, allow_zero=True, allow_eps=True)
+
+        dim = Validation.dimension(dim)
+
+        s1, i = int(t1[0]), int(t1[1])
+        s2, j = int(t2[0]), int(t2[1])
+
+        # Zero propagates.
+        if s1 == 0 or s2 == 0:
+            return (0, 0, 0)
+
+        total_size = 1 << (dim + 1)
+
+        if i < 0 or i >= total_size:
+            raise ValueError(f"index must be in [0, {total_size - 1}] for dual dim={dim}, got {i}")
+
+        if j < 0 or j >= total_size:
+            raise ValueError(f"index must be in [0, {total_size - 1}] for dual dim={dim}, got {j}")
+
+        half = 1 << dim
+
+        i_eps = i >= half
+        j_eps = j >= half
+
+        i_loc = i & (half - 1)
+        j_loc = j & (half - 1)
+
+        # --------------------------------------------------------------
+        # Epsilon nilpotency:
+        # (epsilon e_i) * (epsilon e_j) = 0
+        # --------------------------------------------------------------
+        if i_eps and j_eps:
+            return (0, 0, 1)
+
+        # --------------------------------------------------------------
+        # Base multiplication.
+        # --------------------------------------------------------------
+        if self._split_mode:
+            base_sign, local_idx = self._split.multiply_indices(i_loc, j_loc, dim)
+        else:
+            base_sign, local_idx = self._standard.multiply_indices(i_loc, j_loc)
+
+        eps_flag = 1 if (i_eps or j_eps) else 0
+
+        return (s1 * s2 * base_sign, local_idx, eps_flag)

hypercomplex/core/holographic/split.py

@@ -0,0 +1,100 @@
+from ..validation import Validation
+from .standard import StandardHolographic
+
+
+class SplitHolographic:
+    """
+    Split Cayley-Dickson holographic O(n) multiplier.
+
+    Architecture:
+        Standard parent A_{dim-1} + one split doubling at the top.
+
+    Blocks A, B, C:
+        delegate to StandardHolographic.
+
+    Block D:
+        handled by split rules.
+    """
+
+    def __init__(self):
+        self._standard = StandardHolographic()
+
+    def multiply(self, t1: tuple, t2: tuple, dim: int) -> tuple:
+        """
+        Multiply two basis elements in split A_dim.
+
+        t1 = (sign1, index1)
+        t2 = (sign2, index2)
+
+        Returns:
+            (final_sign, index1 XOR index2)
+        """
+        Validation.basis_tuple(t1, allow_zero=False, allow_eps=False)
+        Validation.basis_tuple(t2, allow_zero=False, allow_eps=False)
+
+        s1, i = int(t1[0]), int(t1[1])
+        s2, j = int(t2[0]), int(t2[1])
+
+        dim = Validation.dimension(dim)
+        Validation.index_in_range(i, dim)
+        Validation.index_in_range(j, dim)
+
+        sign, idx = self.multiply_indices(i, j, dim)
+
+        return (s1 * s2 * sign, idx)
+
+    def multiply_indices(self, i: int, j: int, dim: int) -> tuple:
+        """
+        Core split multiplication for non-negative indices.
+
+        Returns:
+            (sign, i XOR j)
+        """
+        i = int(i)
+        j = int(j)
+        dim = Validation.dimension(dim)
+
+        if i < 0 or j < 0:
+            raise ValueError("indices must be >= 0")
+
+        Validation.index_in_range(i, dim)
+        Validation.index_in_range(j, dim)
+
+        if dim == 0:
+            return (1, 0)
+
+        half = 1 << (dim - 1)
+
+        # --------------------------------------------------------------
+        # Top-level Block D:
+        # both indices are in the upper half.
+        # --------------------------------------------------------------
+        if i >= half and j >= half:
+            i_loc = i - half
+            j_loc = j - half
+
+            # Split Block D diagonal:
+            # (e_i ℓ)^2 = +e_0 for all i.
+            if i_loc == j_loc:
+                return (1, 0)
+
+            # Split Block D first row:
+            # i_loc == 0, j_loc > 0 -> sign -1.
+            if i_loc == 0:
+                return (-1, i ^ j)
+
+            # Split Block D first column:
+            # j_loc == 0, i_loc > 0 -> sign +1.
+            if j_loc == 0:
+                return (1, i ^ j)
+
+            # Split Block D interior:
+            # sign = sigma_a(i_loc, j_loc).
+            sign, _ = self._standard.multiply_indices(i_loc, j_loc)
+            return (sign, i ^ j)
+
+        # --------------------------------------------------------------
+        # Blocks A, B, C:
+        # identical to standard.
+        # --------------------------------------------------------------
+        return self._standard.multiply_indices(i, j)

hypercomplex/core/holographic/standard.py

@@ -0,0 +1,141 @@
+from ..validation import Validation
+
+
+class StandardHolographic:
+    """
+    Standard Cayley-Dickson holographic O(n) multiplier.
+
+    Input / output convention:
+        (sign, index)
+    """
+
+    def multiply(self, t1: tuple, t2: tuple) -> tuple:
+        """
+        Multiply two basis elements.
+
+        t1 = (sign1, index1)
+        t2 = (sign2, index2)
+
+        Returns:
+            (final_sign, index1 XOR index2)
+        """
+        Validation.basis_tuple(t1, allow_zero=False, allow_eps=False)
+        Validation.basis_tuple(t2, allow_zero=False, allow_eps=False)
+
+        s1, i = int(t1[0]), int(t1[1])
+        s2, j = int(t2[0]), int(t2[1])
+
+        sign, idx = self.multiply_indices(i, j)
+
+        return (s1 * s2 * sign, idx)
+
+    def multiply_indices(self, i: int, j: int) -> tuple:
+        """
+        Core O(n) descent for non-negative integer indices.
+
+        Returns:
+            (sign, i XOR j)
+        """
+        i = int(i)
+        j = int(j)
+
+        if i < 0 or j < 0:
+            raise ValueError("indices must be >= 0")
+
+        if i == 0 and j == 0:
+            return (1, 0)
+
+        sign = 1
+        ic = i
+        jc = j
+
+        n = max(i, j).bit_length()
+
+        for level in range(n, 0, -1):
+            half = 1 << (level - 1)
+
+            if ic < half and jc < half:
+                q = "a"
+            elif ic < half and jc >= half:
+                q = "b"
+                jc -= half
+            elif ic >= half and jc < half:
+                q = "c"
+                ic -= half
+            else:
+                q = "d"
+                ic -= half
+                jc -= half
+
+            # Structural position inside the current quadrant.
+            if ic == 0 or jc == 0 or ic == jc:
+                structural_sign = self._structural_sign(q, ic, jc, split=False)
+                return (sign * structural_sign, i ^ j)
+
+            # Non-structural sign flip.
+            if self._flips(q, split=False):
+                sign = -sign
+
+        # Should normally terminate via structural detection.
+        return (sign, i ^ j)
+
+    @staticmethod
+    def _flips(q: str, split: bool) -> bool:
+        """
+        Non-structural sign flip rule.
+
+        Standard:
+            flips in b, c, d
+
+        Split:
+            flips in b, c only
+        """
+        if split:
+            return q in ("b", "c")
+        return q in ("b", "c", "d")
+
+    @staticmethod
+    def _structural_sign(q: str, i_loc: int, j_loc: int, split: bool) -> int:
+        """
+        Structural sign tables from OPMT Theorem 1.2 and Theorem 2.1.
+        """
+
+        # --------------------------------------------------------------
+        # Diagonal
+        # --------------------------------------------------------------
+        if i_loc == j_loc:
+            if i_loc == 0:
+                if q in ("a", "b", "c"):
+                    return 1
+                # Block d, (0,0)
+                return 1 if split else -1
+
+            # i_loc == j_loc > 0
+            if q in ("a", "b"):
+                return -1
+            if q == "c":
+                return 1
+            # Block d diagonal
+            return 1 if split else -1
+
+        # --------------------------------------------------------------
+        # First row: i_loc == 0, j_loc > 0
+        # --------------------------------------------------------------
+        if i_loc == 0:
+            if q in ("a", "b"):
+                return 1
+            if q == "c":
+                return -1
+            # Block d first row
+            return -1 if split else 1
+
+        # --------------------------------------------------------------
+        # First column: j_loc == 0, i_loc > 0
+        # --------------------------------------------------------------
+        if j_loc == 0:
+            if q in ("a", "b", "c"):
+                return 1
+            # Block d first column
+            return 1 if split else -1
+
+        raise ValueError("Not a structural position.")

hypercomplex/core/table_builder/__init__.py

@@ -0,0 +1,9 @@
+from .standard import StandardTableBuilder
+from .split import SplitTableBuilder
+from .dual import DualTableBuilder
+
+__all__ = [
+    "StandardTableBuilder",
+    "SplitTableBuilder",
+    "DualTableBuilder",
+]

hypercomplex/core/table_builder/common.py

@@ -0,0 +1,23 @@
+import numpy as np
+
+
+def index_dtype(dim: int):
+    """
+    Choose the smallest unsigned dtype capable of storing indices 0 ... dim-1.
+    """
+    if dim <= 1 << 8:
+        return np.uint8
+    if dim <= 1 << 16:
+        return np.uint16
+    if dim <= 1 << 32:
+        return np.uint32
+    return np.uint64
+
+
+def real_table():
+    """
+    The real numbers A_0.
+    """
+    signs = np.array([[1]], dtype=np.int8)
+    indices = np.array([[0]], dtype=np.uint8)
+    return signs, indices

hypercomplex/core/table_builder/dual.py

@@ -0,0 +1,97 @@
+import numpy as np
+
+from ..validation import Validation
+from .common import index_dtype
+from .standard import StandardTableBuilder
+from .split import SplitTableBuilder
+
+
+class DualTableBuilder:
+    """
+    Dual Cayley-Dickson table builder.
+
+    Adds epsilon with epsilon^2 = 0.
+
+    The returned table uses:
+        signs[i, j]
+        indices[i, j]   local parent index
+        eps[i, j]       epsilon flag
+
+    For dual tables, index is the local parent basis index, and eps_flag
+    tells whether the product carries epsilon.
+
+    This matches the tuple convention:
+        (sign, index, eps_flag)
+    """
+
+    def __init__(self):
+        self._standard = StandardTableBuilder()
+        self._split = SplitTableBuilder()
+
+    def build(self, n: int, split: bool = False):
+        """
+        Build the dual extension of A_n.
+
+        Parameters
+        ----------
+        n:
+            Parent algebra exponent.
+            Parent dimension is 2^n.
+            Dual table dimension is 2^(n+1).
+
+        split:
+            False -> dual over standard A_n
+            True  -> dual over split A_n
+
+        Returns
+        -------
+        signs, indices, eps
+        """
+        n = Validation.dimension(n)
+
+        if split:
+            base_signs, base_indices = self._split.build(n)
+        else:
+            base_signs, base_indices = self._standard.build(n)
+
+        N = base_signs.shape[0]
+        full = 2 * N
+        dtype = index_dtype(full)
+
+        signs = np.zeros((full, full), dtype=np.int8)
+        indices = np.zeros((full, full), dtype=dtype)
+        eps = np.zeros((full, full), dtype=np.uint8)
+
+        # --------------------------------------------------------------
+        # Block a:
+        # e_i * e_j = parent product
+        # --------------------------------------------------------------
+        signs[:N, :N] = base_signs
+        indices[:N, :N] = base_indices
+        eps[:N, :N] = 0
+
+        # --------------------------------------------------------------
+        # Block b:
+        # e_i * (epsilon e_j) = epsilon (e_i e_j)
+        # --------------------------------------------------------------
+        signs[:N, N:] = base_signs
+        indices[:N, N:] = base_indices
+        eps[:N, N:] = 1
+
+        # --------------------------------------------------------------
+        # Block c:
+        # (epsilon e_i) * e_j = epsilon (e_i e_j)
+        # --------------------------------------------------------------
+        signs[N:, :N] = base_signs
+        indices[N:, :N] = base_indices
+        eps[N:, :N] = 1
+
+        # --------------------------------------------------------------
+        # Block d:
+        # (epsilon e_i) * (epsilon e_j) = epsilon^2 (e_i e_j) = 0
+        # --------------------------------------------------------------
+        signs[N:, N:] = 0
+        indices[N:, N:] = 0
+        eps[N:, N:] = 0
+
+        return signs, indices, eps

hypercomplex/core/table_builder/split.py

@@ -0,0 +1,101 @@
+import numpy as np
+
+from ..validation import Validation
+from .common import index_dtype, real_table
+from .standard import StandardTableBuilder
+
+
+class SplitTableBuilder:
+    """
+    Split Cayley-Dickson table builder.
+
+    Architecture:
+        Standard parent A_{n-1} + one split doubling at the top.
+
+    OPMT Theorem 2.1:
+        Blocks a, b, c are identical to standard.
+        Block d is the split Block d:
+            diagonal = +1
+            first column = +1
+            first row j > 0 = -1
+            interior = +sigma_a
+    """
+
+    def __init__(self):
+        self._standard = StandardTableBuilder()
+
+    def build(self, n: int):
+        """
+        Build the split Cayley-Dickson table A_n.
+
+        Returns
+        -------
+        signs:
+            signs[i, j] = ±1
+        indices:
+            indices[i, j] = k
+        """
+        n = Validation.dimension(n)
+
+        if n == 0:
+            return real_table()
+
+        # Standard parent A_{n-1}
+        parent_signs, parent_indices = self._standard.build(n - 1)
+
+        half = parent_signs.shape[0]
+        full = 2 * half
+        dtype = index_dtype(full)
+
+        signs = np.zeros((full, full), dtype=np.int8)
+        indices = np.zeros((full, full), dtype=dtype)
+
+        # --------------------------------------------------------------
+        # Block a:
+        # Inherits the standard parent.
+        # --------------------------------------------------------------
+        signs[:half, :half] = parent_signs
+        indices[:half, :half] = parent_indices
+
+        # --------------------------------------------------------------
+        # Block b:
+        # Same as standard.
+        # --------------------------------------------------------------
+        signs[:half, half:] = parent_signs.T
+        np.add(
+            parent_indices.T,
+            dtype(half),
+            out=indices[:half, half:],
+            casting="unsafe",
+        )
+
+        # --------------------------------------------------------------
+        # Block c:
+        # Same as standard.
+        # --------------------------------------------------------------
+        block_c = parent_signs.copy()
+        block_c[:, 1:] = -block_c[:, 1:]
+
+        signs[half:, :half] = block_c
+        np.add(
+            parent_indices,
+            dtype(half),
+            out=indices[half:, :half],
+            casting="unsafe",
+        )
+
+        # --------------------------------------------------------------
+        # Block d:
+        # Split Block d.
+        #
+        # (0, e_i)(0, e_j) = (+e_j* e_i, 0)
+        #
+        # No leading minus sign, but conjugation still flips columns j > 0.
+        # --------------------------------------------------------------
+        block_d = parent_signs.T.copy()
+        block_d[:, 1:] = -block_d[:, 1:]
+
+        signs[half:, half:] = block_d
+        indices[half:, half:] = parent_indices.T
+
+        return signs, indices