hypercomplex-engine 1.0.1__py3-none-any.whl

hypercomplex/__init__.py

@@ -0,0 +1,63 @@
+from .facade import (
+    build_table,
+    multiply,
+    format_element,
+    print_table,
+    export_csv,
+)
+
+from .core import (
+    BasisElement,
+    BasisNotation,
+    Validation,
+
+    StandardTableBuilder,
+    SplitTableBuilder,
+    DualTableBuilder,
+
+    StandardHolographic,
+    SplitHolographic,
+    DualHolographic,
+
+    FastStandard,
+    FastSplit,
+    FastDual,
+)
+
+from .printer import (
+    CDFormat,
+    CDTablePrinter,
+)
+
+__all__ = [
+    # Simple API
+    "build_table",
+    "multiply",
+    "format_element",
+    "print_table",
+    "export_csv",
+
+    # Core
+    "BasisElement",
+    "BasisNotation",
+    "Validation",
+
+    # Table builders
+    "StandardTableBuilder",
+    "SplitTableBuilder",
+    "DualTableBuilder",
+
+    # Holographic O(n)
+    "StandardHolographic",
+    "SplitHolographic",
+    "DualHolographic",
+
+    # O(1)
+    "FastStandard",
+    "FastSplit",
+    "FastDual",
+
+    # Printer / formatter
+    "CDFormat",
+    "CDTablePrinter",
+]

hypercomplex/core/__init__.py

@@ -0,0 +1,39 @@
+from .basis_element import BasisElement
+from .basis_notation import BasisNotation
+from .validation import Validation
+
+from .table_builder import (
+    StandardTableBuilder,
+    SplitTableBuilder,
+    DualTableBuilder,
+)
+
+from .holographic import (
+    StandardHolographic,
+    SplitHolographic,
+    DualHolographic,
+)
+
+from .fast import (
+    FastStandard,
+    FastSplit,
+    FastDual,
+)
+
+__all__ = [
+    "BasisElement",
+    "BasisNotation",
+    "Validation",
+
+    "StandardTableBuilder",
+    "SplitTableBuilder",
+    "DualTableBuilder",
+
+    "StandardHolographic",
+    "SplitHolographic",
+    "DualHolographic",
+
+    "FastStandard",
+    "FastSplit",
+    "FastDual",
+]

hypercomplex/core/basis_element.py

@@ -0,0 +1,58 @@
+class BasisElement:
+    """
+    Basis elements are represented as plain tuples.
+
+    Standard / Split:
+        (sign, index)
+
+    Dual:
+        (sign, index, eps_flag)
+
+    sign:
+        -1, 0, or +1
+        sign == 0 means the zero element.
+
+    index:
+        basis index k, meaning e_k.
+
+    eps_flag:
+        0 or 1, used only for dual numbers.
+    """
+
+    @staticmethod
+    def make(sign: int, index: int, eps: int | None = None) -> tuple:
+        if eps is None:
+            return (int(sign), int(index))
+        return (int(sign), int(index), int(eps))
+
+    @staticmethod
+    def zero(eps: int = 0) -> tuple:
+        return (0, 0, int(eps))
+
+    @staticmethod
+    def sign(element: tuple) -> int:
+        return int(element[0])
+
+    @staticmethod
+    def index(element: tuple) -> int:
+        return int(element[1])
+
+    @staticmethod
+    def eps(element: tuple) -> int:
+        if len(element) >= 3:
+            return int(element[2])
+        return 0
+
+    @staticmethod
+    def is_zero(element: tuple) -> bool:
+        return int(element[0]) == 0
+
+    @staticmethod
+    def negate(element: tuple) -> tuple:
+        if len(element) == 2:
+            return (-int(element[0]), int(element[1]))
+        return (-int(element[0]), int(element[1]), int(element[2]))
+
+    @staticmethod
+    def with_eps(element: tuple, eps: int) -> tuple:
+        return (int(element[0]), int(element[1]), int(eps))

hypercomplex/core/basis_notation.py

@@ -0,0 +1,134 @@
+# basis_notation.py
+
+class BasisNotation:
+    """
+    Handles conversions between integer indices, graded (bitmask) notation, 
+    and LaTeX strings for Cayley-Dickson basis elements.
+    """
+    
+    @staticmethod
+    def int_to_generators(k: int) -> tuple:
+        """Converts integer index k to a tuple of 1-based generator indices."""
+        if k == 0: return ()
+        gens = []
+        i = 1
+        temp_k = k
+        while temp_k > 0:
+            if temp_k & 1: gens.append(i)
+            temp_k >>= 1
+            i += 1
+        return tuple(gens)
+
+    @staticmethod
+    def generators_to_int(gens) -> int:
+        """Converts generators (tuple, list, or string like '13') to integer index."""
+        if isinstance(gens, str):
+            # Extract digits from strings like "o13" or "o_{145}"
+            # NOTE: This assumes single-digit generators (valid up to 512-dim / 9 generators).
+            gens = [int(char) for char in gens if char.isdigit()]
+        k = 0
+        for g in gens:
+            k |= (1 << (g - 1))
+        return k
+
+    @staticmethod
+    def to_graded_str(k: int) -> str:
+        """Integer to graded string (e.g., 5 -> 'o13', 0 -> '1')."""
+        if k == 0: return "1"
+        gens = BasisNotation.int_to_generators(k)
+        return "o" + "".join(str(g) for g in gens)
+
+    @staticmethod
+    def to_latex(k: int, mode: str = "integer") -> str:
+        """Integer to LaTeX string.
+        mode="integer": e_{5}, e_{13}   (index as number)
+        mode="graded":  o_{13}, o_{123} (generators)
+        """
+        if k == 0:
+            return "1"
+
+        if mode == "integer":
+            return f"e_{{{k}}}"
+        elif mode == "graded":
+            gens = BasisNotation.int_to_generators(k)
+            return "o_{" + "".join(str(g) for g in gens) + "}"
+        else:
+            raise ValueError("mode must be 'integer' or 'graded'")
+
+    @staticmethod
+    def from_graded_str(s: str) -> int:
+        """Parses a graded string back to an integer index.
+        Accepts 'o13', 'o_{13}', '1', and also legacy 'e13'.
+        """
+        s = s.strip()
+        
+        # Zero / scalar cases
+        if s in ("1", "o", "o0", "e", "e0", "o_\\emptyset"):
+            return 0
+        
+        # Strip prefixes and braces; digit extraction does the real work
+        s = (s.replace("o_", "").replace("o", "")
+              .replace("e_", "").replace("e", "")
+              .replace("{", "").replace("}", ""))
+        
+        gens = [int(char) for char in s if char.isdigit()]
+        return BasisNotation.generators_to_int(gens)
+
+    @staticmethod
+    def format_entry(sign: int, k: int, eps: int = 0, mode: str = "integer") -> str:
+        """Formats a single table cell or O(1) product."""
+        if sign == 0:
+            return "0"
+
+        prefix = "+" if sign > 0 else "-"
+
+        if mode == "integer":
+            base = f"e{k}"
+        elif mode == "graded":
+            base = BasisNotation.to_graded_str(k)
+        elif mode == "latex":              # alias for graded-latex (backward compat)
+            base = BasisNotation.to_latex(k, mode="graded")
+        elif mode == "latex_integer":
+            base = BasisNotation.to_latex(k, mode="integer")
+        elif mode == "latex_graded":
+            base = BasisNotation.to_latex(k, mode="graded")
+        else:
+            raise ValueError("mode must be 'integer', 'graded', 'latex', 'latex_integer', or 'latex_graded'")
+
+        if eps:
+            if mode.startswith("latex"):
+                eps_str = "\\epsilon"
+                if k == 0: return f"{prefix}{eps_str}"
+                return f"{prefix}{base}{eps_str}"
+            else:
+                eps_str = "eps"
+                if k == 0: return f"{prefix}{eps_str}"
+                return f"{prefix}{base}*{eps_str}"
+
+        return prefix + base
+
+    @staticmethod
+    def basis_labels(dim: int, dual: bool = False, mode: str = "integer") -> list:
+        """Generates the headers/row labels for the table."""
+        base_dim = dim // 2 if dual else dim
+
+        def _base_label(i):
+            if mode == "integer": return f"e{i}"
+            elif mode == "graded": return BasisNotation.to_graded_str(i)
+            elif mode == "latex": return BasisNotation.to_latex(i, mode="graded")
+            elif mode == "latex_integer": return BasisNotation.to_latex(i, mode="integer")
+            elif mode == "latex_graded": return BasisNotation.to_latex(i, mode="graded")
+            else: raise ValueError("Invalid mode")
+
+        labels = [_base_label(i) for i in range(base_dim)]
+
+        if dual:
+            is_latex = mode.startswith("latex")
+            eps_str = "\\epsilon" if is_latex else "eps"
+            labels.append(eps_str)
+
+            for k in range(1, base_dim):
+                base = _base_label(k)
+                labels.append(f"{base}{eps_str}" if is_latex else f"{base}*{eps_str}")
+
+        return labels

hypercomplex/core/fast/__init__.py

@@ -0,0 +1,9 @@
+from .fast_standard import FastStandard
+from .fast_split import FastSplit
+from .fast_dual import FastDual
+
+__all__ = [
+    "FastStandard",
+    "FastSplit",
+    "FastDual",
+]

hypercomplex/core/fast/bit_utils.py

@@ -0,0 +1,20 @@
+def nu2(x: int) -> int:
+    """
+    2-adic valuation: index of the lowest set bit.
+
+    nu2(1) = 0
+    nu2(2) = 1
+    nu2(4) = 2
+    nu2(12) = 2
+    """
+    if x == 0:
+        raise ValueError("nu2(0) is undefined in the O(1) structural descent")
+
+    return (x & -x).bit_length() - 1
+
+
+def popcount(x: int) -> int:
+    """
+    Number of set bits.
+    """
+    return int(x).bit_count()

hypercomplex/core/fast/fast_dual.py

@@ -0,0 +1,182 @@
+from ..validation import Validation
+from .fast_standard import FastStandard
+from .fast_split import FastSplit
+
+
+class FastDual:
+    """
+    Dual Cayley-Dickson O(1) multiplier.
+
+    Input index convention:
+        Total dual dimension is 2^(dim + 1).
+        Bit `dim` marks the epsilon component.
+
+        lower half: base elements
+        upper half: epsilon * base elements
+
+    Output:
+        (sign, local_index, eps_flag)
+
+    The output index is the local base index, so it can be formatted
+    directly by CDFormat.
+
+    Zero products are normalized to:
+        (0, 0, 0)
+    """
+
+    def __init__(self, split: bool = False):
+        self._split_mode = bool(split)
+        self._standard = FastStandard()
+        self._split = FastSplit() if self._split_mode else None
+
+    # ==================================================================
+    # Index helpers
+    # ==================================================================
+
+    @staticmethod
+    def local_to_global(index: int, eps: int, dim: int) -> int:
+        """
+        Convert local dual representation to global index.
+
+        local:
+            index in [0, 2^dim - 1]
+            eps = 0 or 1
+
+        global:
+            index in [0, 2^(dim+1) - 1]
+        """
+        dim = Validation.dimension(dim)
+        index = int(index)
+        eps = int(eps)
+
+        half = 1 << dim
+
+        if index < 0 or index >= half:
+            raise ValueError(f"local index must be in [0, {half - 1}], got {index}")
+
+        if eps:
+            return index + half
+
+        return index
+
+    @staticmethod
+    def global_to_local(global_index: int, dim: int) -> tuple:
+        """
+        Convert global dual index to:
+            (local_index, eps_flag)
+        """
+        dim = Validation.dimension(dim)
+        global_index = int(global_index)
+
+        half = 1 << dim
+        total = half << 1
+
+        if global_index < 0 or global_index >= total:
+            raise ValueError(f"global index must be in [0, {total - 1}], got {global_index}")
+
+        return (global_index & (half - 1), 1 if global_index >= half else 0)
+
+    # ==================================================================
+    # Tuple input helper
+    # ==================================================================
+
+    def _extract_global(self, t: tuple, dim: int) -> tuple:
+        """
+        Accepts:
+            (sign, global_index)
+            (sign, local_index, eps_flag)
+
+        Returns:
+            (sign, global_index)
+        """
+        Validation.basis_tuple(t, allow_zero=True, allow_eps=True)
+
+        sign = int(t[0])
+        idx = int(t[1])
+
+        if sign == 0:
+            return (0, 0)
+
+        half = 1 << Validation.dimension(dim)
+
+        if len(t) >= 3:
+            eps = int(t[2])
+
+            # If the tuple carries an epsilon flag and the index is still
+            # local, promote it to the global upper half.
+            if eps == 1 and idx < half:
+                idx += half
+
+        return (sign, idx)
+
+    # ==================================================================
+    # Public API
+    # ==================================================================
+
+    def multiply(self, t1: tuple, t2: tuple, dim: int) -> tuple:
+        """
+        Multiply two dual basis element tuples.
+
+        Accepted inputs:
+            (sign, global_index)
+            (sign, local_index, eps_flag)
+
+        Returns:
+            (final_sign, local_index, eps_flag)
+        """
+        dim = Validation.dimension(dim)
+
+        s1, i = self._extract_global(t1, dim)
+        s2, j = self._extract_global(t2, dim)
+
+        if s1 == 0 or s2 == 0:
+            return (0, 0, 0)
+
+        sign, idx, eps = self.multiply_indices(i, j, dim)
+
+        return (s1 * s2 * sign, idx, eps)
+
+    def multiply_indices(self, i: int, j: int, dim: int) -> tuple:
+        """
+        Core dual O(1) multiplication using global indices.
+
+        Returns:
+            (sign, local_index, eps_flag)
+        """
+        i = int(i)
+        j = int(j)
+        dim = Validation.dimension(dim)
+
+        half = 1 << dim
+        total = half << 1
+
+        if i < 0 or i >= total:
+            raise ValueError(f"index must be in [0, {total - 1}] for dual dim={dim}, got {i}")
+
+        if j < 0 or j >= total:
+            raise ValueError(f"index must be in [0, {total - 1}] for dual dim={dim}, got {j}")
+
+        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, 0)
+
+        # --------------------------------------------------------------
+        # 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 (base_sign, local_idx, eps_flag)

hypercomplex/core/fast/fast_split.py

@@ -0,0 +1,113 @@
+from ..validation import Validation
+from .fast_standard import FastStandard
+
+
+class FastSplit:
+    """
+    Split Cayley-Dickson O(1) multiplier.
+
+    Architecture:
+        Standard parent A_{dim-1} + one split doubling at the top.
+
+    Blocks A, B, C:
+        delegate to FastStandard.
+
+    Block D:
+        split rules:
+            diagonal       = +1
+            first row      = -1
+            first column   = +1
+            interior       = +sigma_a
+    """
+
+    def __init__(self):
+        self._standard = FastStandard()
+
+    def multiply(self, t1: tuple, t2: tuple, dim: int | None = None) -> tuple:
+        """
+        Multiply two split basis element tuples.
+
+        t1 = (sign1, index1)
+        t2 = (sign2, index2)
+
+        dim:
+            Algebra exponent.
+            If None, it is inferred from the indices.
+
+        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)
+
+        if dim is None:
+            dim = max(i, j).bit_length()
+        else:
+            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 O(1) multiplication.
+
+        Returns:
+            (sign, i XOR j)
+        """
+        i = int(i)
+        j = int(j)
+        dim = Validation.dimension(dim)
+
+        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 = +e0
+            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)