hypercomplex-engine 0.0.4__py3-none-any.whl

hypercomplex/core/table_builder/standard.py

@@ -0,0 +1,90 @@
+import numpy as np
+
+from ..validation import Validation
+from .common import index_dtype, real_table
+
+
+class StandardTableBuilder:
+    """
+    Standard Cayley-Dickson table builder.
+
+    OPMT Theorem 1.2:
+        Block a: inherits parent
+        Block b: transpose, index shifted
+        Block c: conjugation on column j
+        Block d: standard sign rules
+    """
+
+    def build(self, n: int):
+        """
+        Build the standard Cayley-Dickson table A_n.
+
+        Returns
+        -------
+        signs:
+            signs[i, j] = ±1
+        indices:
+            indices[i, j] = k, where e_i e_j = signs[i, j] * e_k
+        """
+        n = Validation.dimension(n)
+
+        signs, indices = real_table()
+
+        for _ in range(n):
+            half = signs.shape[0]
+            full = 2 * half
+            dtype = index_dtype(full)
+
+            new_signs = np.zeros((full, full), dtype=np.int8)
+            new_indices = np.zeros((full, full), dtype=dtype)
+
+            # ----------------------------------------------------------
+            # Block a:
+            # (e_i, 0)(e_j, 0) = (e_i e_j, 0)
+            # ----------------------------------------------------------
+            new_signs[:half, :half] = signs
+            new_indices[:half, :half] = indices
+
+            # ----------------------------------------------------------
+            # Block b:
+            # (e_i, 0)(0, e_j) = (0, e_j e_i)
+            # ----------------------------------------------------------
+            new_signs[:half, half:] = signs.T
+            np.add(
+                indices.T,
+                dtype(half),
+                out=new_indices[:half, half:],
+                casting="unsafe",
+            )
+
+            # ----------------------------------------------------------
+            # Block c:
+            # (0, e_i)(e_j, 0) = (0, e_i e_j*)
+            # Conjugation flips columns j > 0.
+            # ----------------------------------------------------------
+            block_c = signs.copy()
+            block_c[:, 1:] = -block_c[:, 1:]
+
+            new_signs[half:, :half] = block_c
+            np.add(
+                indices,
+                dtype(half),
+                out=new_indices[half:, :half],
+                casting="unsafe",
+            )
+
+            # ----------------------------------------------------------
+            # Block d:
+            # (0, e_i)(0, e_j) = (-e_j* e_i, 0)
+            # Start from -signs.T, then conjugation flips columns j > 0.
+            # ----------------------------------------------------------
+            block_d = -signs.T
+            block_d[:, 1:] = -block_d[:, 1:]
+
+            new_signs[half:, half:] = block_d
+            new_indices[half:, half:] = indices.T
+
+            signs = new_signs
+            indices = new_indices
+
+        return signs, indices

hypercomplex/core/validation.py

@@ -0,0 +1,112 @@
+from numbers import Integral
+
+
+class Validation:
+    """
+    Input validation for basis elements, indices, and dimensions.
+    """
+
+    @staticmethod
+    def dimension(dim) -> int:
+        """
+        Validates an algebra dimension exponent.
+
+        dim must be a non-negative integer.
+        dim = n means algebra dimension 2^n.
+        """
+        if isinstance(dim, bool) or not isinstance(dim, Integral):
+            raise TypeError(f"dim must be an integer, got {type(dim).__name__}")
+
+        dim = int(dim)
+
+        if dim < 0:
+            raise ValueError(f"dim must be >= 0, got {dim}")
+
+        return dim
+
+    @staticmethod
+    def basis_tuple(
+        data,
+        allow_zero: bool = False,
+        allow_eps: bool = False,
+    ) -> bool:
+        """
+        Validates a basis-element tuple.
+
+        Standard / Split:
+            (sign, index)
+
+        Dual:
+            (sign, index, eps_flag)
+
+        Parameters
+        ----------
+        data:
+            The tuple to validate.
+
+        allow_zero:
+            If True, sign == 0 is allowed.
+            This is needed for dual nilpotent zero products.
+
+        allow_eps:
+            If True, 3-tuples with an epsilon flag are allowed.
+        """
+        if not isinstance(data, tuple):
+            raise TypeError(f"Expected tuple, got {type(data).__name__}")
+
+        if len(data) not in (2, 3):
+            raise ValueError(f"Basis tuple must have length 2 or 3, got {len(data)}")
+
+        if len(data) == 3 and not allow_eps:
+            raise ValueError("3-tuple epsilon form is not allowed here")
+
+        sign = data[0]
+        index = data[1]
+
+        if isinstance(sign, bool) or not isinstance(sign, Integral):
+            raise TypeError(f"sign must be an integer, got {type(sign).__name__}")
+
+        if isinstance(index, bool) or not isinstance(index, Integral):
+            raise TypeError(f"index must be an integer, got {type(index).__name__}")
+
+        sign = int(sign)
+        index = int(index)
+
+        if index < 0:
+            raise ValueError(f"index must be >= 0, got {index}")
+
+        allowed_signs = (-1, 0, 1) if allow_zero else (-1, 1)
+
+        if sign not in allowed_signs:
+            raise ValueError(f"sign must be in {allowed_signs}, got {sign}")
+
+        if len(data) == 3:
+            eps = data[2]
+
+            if isinstance(eps, bool) or not isinstance(eps, Integral):
+                raise TypeError(f"eps must be an integer, got {type(eps).__name__}")
+
+            eps = int(eps)
+
+            if eps not in (0, 1):
+                raise ValueError(f"eps must be 0 or 1, got {eps}")
+
+        return True
+
+    @staticmethod
+    def index_in_range(index, dim: int) -> int:
+        """
+        Validates that index is inside [0, 2^dim - 1].
+        """
+        if isinstance(index, bool) or not isinstance(index, Integral):
+            raise TypeError(f"index must be an integer, got {type(index).__name__}")
+
+        index = int(index)
+        dim = Validation.dimension(dim)
+
+        size = 1 << dim
+
+        if index < 0 or index >= size:
+            raise ValueError(f"index must be in [0, {size - 1}] for dim={dim}, got {index}")
+
+        return index

hypercomplex/facade.py

@@ -0,0 +1,360 @@
+from .core.table_builder import (
+    StandardTableBuilder,
+    SplitTableBuilder,
+    DualTableBuilder,
+)
+
+from .core.holographic import (
+    StandardHolographic,
+    SplitHolographic,
+    DualHolographic,
+)
+
+from .core.fast import (
+    FastStandard,
+    FastSplit,
+    FastDual,
+)
+
+import numpy as np
+
+from .core.table_builder.common import index_dtype
+from .core.validation import Validation
+
+from .printer import CDFormat, CDTablePrinter
+
+
+# ----------------------------------------------------------------------
+# Internal singletons
+# ----------------------------------------------------------------------
+
+_standard_table = StandardTableBuilder()
+_split_table = SplitTableBuilder()
+_dual_table = DualTableBuilder()
+
+_standard_holo = StandardHolographic()
+_split_holo = SplitHolographic()
+_dual_holo = DualHolographic(split=False)
+_dual_split_holo = DualHolographic(split=True)
+
+_standard_fast = FastStandard()
+_split_fast = FastSplit()
+_dual_fast = FastDual(split=False)
+_dual_split_fast = FastDual(split=True)
+
+
+# ----------------------------------------------------------------------
+# Helpers
+# ----------------------------------------------------------------------
+
+def _normalize_kind(kind: str) -> str:
+    if not isinstance(kind, str):
+        raise TypeError("kind must be a string")
+
+    kind = kind.strip().lower()
+
+    aliases = {
+        "standard": "standard",
+        "std": "standard",
+        "ordinary": "standard",
+        "o": "standard",
+
+        "split": "split",
+        "s": "split",
+
+        "dual": "dual",
+        "dual_standard": "dual",
+        "d": "dual",
+
+        "dual_split": "dual_split",
+        "split_dual": "dual_split",
+        "ds": "dual_split",
+    }
+
+    if kind not in aliases:
+        raise ValueError(
+            f"Unknown algebra kind '{kind}'. "
+            "Valid kinds: standard, split, dual, dual_split"
+        )
+
+    return aliases[kind]
+
+
+def _normalize_engine(engine: str) -> str:
+    if not isinstance(engine, str):
+        raise TypeError("engine must be a string")
+
+    engine = engine.strip().lower()
+
+    aliases = {
+        "fast": "fast",
+        "constant": "fast",
+        "fast": "fast",
+        "bitwise": "fast",
+        "o1":"fast",
+
+        "holographic": "holographic",
+        "on": "holographic",
+        "o(n)": "holographic",
+        "descent": "holographic",
+    }
+
+    if engine not in aliases:
+        raise ValueError(
+            f"Unknown engine '{engine}'. "
+            "Valid engines: fast, holographic"
+        )
+
+    return aliases[engine]
+
+
+def _unpack_table(table):
+    """
+    Accepts:
+        (signs, indices)
+        (signs, indices, eps)
+    """
+    if len(table) == 2:
+        signs, indices = table
+        return signs, indices, None
+
+    if len(table) == 3:
+        signs, indices, eps = table
+        return signs, indices, eps
+
+    raise ValueError(
+        "table must be (signs, indices) or (signs, indices, eps)"
+    )
+
+
+def _as_dual_global(t: tuple, dim: int) -> tuple:
+    """
+    Converts a dual input tuple into a global 2-tuple.
+
+    Accepts:
+        (sign, global_index)
+        (sign, local_index, eps_flag)
+
+    Returns:
+        (sign, global_index)
+    """
+    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 eps == 1 and idx < half:
+            idx += half
+
+    return (sign, idx)
+
+
+# ----------------------------------------------------------------------
+# Public simple API
+# ----------------------------------------------------------------------
+
+# Default memory budget for build_table (bytes of final table data).
+# 256 MiB allows standard/split up to n=13 and dual/dual_split up to n=12.
+DEFAULT_MAX_TABLE_BYTES = 1 << 28
+
+
+def estimate_table_bytes(kind: str, n: int) -> int:
+    """
+    Estimate the bytes of the final table arrays that build_table(kind, n)
+    would allocate. Peak usage while building is roughly 1.5x this value.
+
+    Dual kinds are one doubling larger than the same n for standard/split,
+    and carry an extra uint8 epsilon array.
+    """
+    kind = _normalize_kind(kind)
+    n = Validation.dimension(n)
+
+    is_dual = kind in ("dual", "dual_split")
+    full = 1 << (n + 1 if is_dual else n)
+
+    per_entry = 1 + np.dtype(index_dtype(full)).itemsize  # signs + indices
+    if is_dual:
+        per_entry += 1  # eps array
+
+    return full * full * per_entry
+
+
+def build_table(kind: str, n: int, max_bytes: int | None = DEFAULT_MAX_TABLE_BYTES):
+    """
+    Build a multiplication table.
+
+    kind:
+        "standard"
+        "split"
+        "dual"
+        "dual_split"
+
+    n:
+        Dimension exponent (algebra dimension 2**n). Must be an integer.
+
+    max_bytes:
+        Memory budget for the final table arrays. If the estimated size
+        exceeds it, ValueError is raised instead of attempting the build.
+        Pass a larger int on a strong machine, or None to disable the check.
+        Use estimate_table_bytes(kind, n) to check a size in advance, or
+        multiply(..., engine="fast") to avoid tables entirely.
+    """
+    kind = _normalize_kind(kind)
+    n = Validation.dimension(n)
+
+    if max_bytes is not None:
+        needed = estimate_table_bytes(kind, n)
+        if needed > max_bytes:
+            raise ValueError(
+                f"build_table({kind!r}, {n}) needs about {needed / 2**20:,.1f} MiB "
+                f"(limit {max_bytes / 2**20:,.1f} MiB). Pass a larger max_bytes, "
+                "max_bytes=None to disable the check, or use "
+                'multiply(..., engine="fast") which needs no table.'
+            )
+
+    if kind == "standard":
+        return _standard_table.build(n)
+
+    if kind == "split":
+        return _split_table.build(n)
+
+    if kind == "dual":
+        return _dual_table.build(n, split=False)
+
+    if kind == "dual_split":
+        return _dual_table.build(n, split=True)
+
+    raise ValueError(f"Unknown algebra kind '{kind}'")
+
+
+def multiply(
+    kind: str,
+    a: tuple,
+    b: tuple,
+    dim: int | None = None,
+    engine: str = "fast",
+) -> tuple:
+    """
+    Multiply two basis elements.
+
+    kind:
+        "standard"
+        "split"
+        "dual"
+        "dual_split"
+
+    engine:
+        "fast"          default, fastest
+        "holographic" O(n) descent, useful for verification
+
+    dim:
+        Required for dual and dual_split.
+        Optional for split.
+    """
+    kind = _normalize_kind(kind)
+    engine = _normalize_engine(engine)
+
+    # Zero propagation
+    if int(a[0]) == 0 or int(b[0]) == 0:
+        if kind in ("dual", "dual_split"):
+            return (0, 0, 0)
+        return (0, 0)
+
+    # Dual inputs may be local 3-tuples: (sign, local_index, eps)
+    if kind in ("dual", "dual_split"):
+        if dim is None:
+            raise ValueError("dim is required for dual multiplication")
+
+        a = _as_dual_global(a, dim)
+        b = _as_dual_global(b, dim)
+
+    # ------------------------------------------------------------------
+    # O(1) engine
+    # ------------------------------------------------------------------
+    if engine == "fast":
+        if kind == "standard":
+            return _standard_fast.multiply(a, b)
+
+        if kind == "split":
+            return _split_fast.multiply(a, b, dim)
+
+        if kind == "dual":
+            return _dual_fast.multiply(a, b, dim)
+
+        if kind == "dual_split":
+            return _dual_split_fast.multiply(a, b, dim)
+
+    # ------------------------------------------------------------------
+    # Holographic O(n) engine
+    # ------------------------------------------------------------------
+    if engine == "holographic":
+        if kind == "standard":
+            return _standard_holo.multiply(a, b)
+
+        if kind == "split":
+            if dim is None:
+                dim = max(int(a[1]), int(b[1])).bit_length()
+            return _split_holo.multiply(a, b, dim)
+
+        if kind == "dual":
+            return _dual_holo.multiply(a, b, dim)
+
+        if kind == "dual_split":
+            return _dual_split_holo.multiply(a, b, dim)
+
+    raise ValueError(f"Unknown engine '{engine}'")
+
+
+def format_element(element: tuple, mode: str = "integer") -> str:
+    """
+    Format a basis element tuple.
+    """
+    return CDFormat.format_element(element, mode=mode)
+
+
+def print_table(
+    table,
+    title: str | None = None,
+    limit: int | None = None,
+    mode: str = "integer",
+):
+    """
+    Print a table built by build_table().
+    """
+    signs, indices, eps = _unpack_table(table)
+
+    return CDTablePrinter.print_table(
+        signs,
+        indices,
+        eps=eps,
+        title=title,
+        limit=limit,
+        mode=mode,
+    )
+
+
+def export_csv(
+    path: str,
+    table,
+    mode: str = "integer",
+    csv_mode: str = "matrix",
+) -> str:
+    """
+    Export a table built by build_table().
+    """
+    signs, indices, eps = _unpack_table(table)
+
+    return CDTablePrinter.export_csv(
+        path,
+        signs,
+        indices,
+        eps=eps,
+        mode=mode,
+        csv_mode=csv_mode,
+    )

hypercomplex/printer/__init__.py

@@ -0,0 +1,7 @@
+from .cd_format import CDFormat
+from .cd_table_printer import CDTablePrinter
+
+__all__ = [
+    "CDFormat",
+    "CDTablePrinter",
+]