clif-ga 0.1.0__tar.gz

clif_ga-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 D. A. Jones
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

clif_ga-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: clif-ga
+Version: 0.1.0
+Summary: Clifford-algebra engine: multivector inverse algorithms
+Author: D. A. Jones
+License: MIT License
+        
+        Copyright (c) 2026 D. A. Jones
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/dajonesy/engine
+Project-URL: Documentation, https://clif-ga.readthedocs.io
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: numba>=0.58
+Provides-Extra: dev
+Requires-Dist: jupyter; extra == "dev"
+Requires-Dist: ipykernel; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: myst-nb; extra == "dev"
+Requires-Dist: jupyter-cache; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: furo; extra == "dev"
+Dynamic: license-file
+
+# clif
+
+A research toolkit for numerical computations in Clifford / geometric algebras, 
+with an emphasis on **fast multivector inverses**, including a 6D inverse and 
+an emerging dimension-independent approach.
+
+> **Status:** research prototype, not yet a packaged release.
+> The API is unstable and the test suite is still being built out.
+> Star the repo if you want to follow along.
+
+---
+
+## What's here
+
+The package implements Clifford algebra with explicit ordinal indexing of 
+multivector components, efficient sign-table-based multiplication, and support 
+for arbitrary metric signature and degeneracy. 
+It's organized as four cooperating layers:
+
+- `clif.context` — global algebra state (dimension, signature, degeneracy, grade table).
+- `clif.sign_table` — builds/caches the multiplication sign table and a Numba-jitted fast
+  multiplier for dimensions < 8.
+- `clif.multivector` — the `Accum` class, a multivector as a NumPy array of real coefficients indexed by ordinal.
+- `clif.util` — construction, printing, grade projection, involutions, and inverse models for specific dimensions.
+- `clif.tools` — primitive signtable support functions
+ 
+Inverse algorithms live in `clif.inverse`:
+
+- `clif.inverse.fls` (and `clif.inverse.sparse_fls`) — Faddeev–LeVerrier–Souriau based inverses, with even/odd-graded variants.
+- `clif.inverse.euclidean` — inverse for Euclidean (positive-definite) signatures.
+- `clif.inverse.newton` — iterative refinement via Newton–Schulz.
+
+## A worked example
+
+```python
+from clif.context import Cl, Layout
+from clif.multivector import Accum
+
+Cl(1, 1, 1)        # algebra with 1 positive, 1 negative, 1 null basis vector
+A = Accum.random()
+print(A)
+
+Cl(1, 3)                  # spacetime algebra  Cl(1,3)
+Layout([1, -1, -1, -1])   # equivalent, explicit
+```
+
+## Documentation
+
+Built locally with Sphinx:
+
+```bash
+cd docs && make html
+```
+
+Then open `docs/_build/html/index.html` in a browser.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

clif_ga-0.1.0/README.md

@@ -0,0 +1,59 @@
+# clif
+
+A research toolkit for numerical computations in Clifford / geometric algebras, 
+with an emphasis on **fast multivector inverses**, including a 6D inverse and 
+an emerging dimension-independent approach.
+
+> **Status:** research prototype, not yet a packaged release.
+> The API is unstable and the test suite is still being built out.
+> Star the repo if you want to follow along.
+
+---
+
+## What's here
+
+The package implements Clifford algebra with explicit ordinal indexing of 
+multivector components, efficient sign-table-based multiplication, and support 
+for arbitrary metric signature and degeneracy. 
+It's organized as four cooperating layers:
+
+- `clif.context` — global algebra state (dimension, signature, degeneracy, grade table).
+- `clif.sign_table` — builds/caches the multiplication sign table and a Numba-jitted fast
+  multiplier for dimensions < 8.
+- `clif.multivector` — the `Accum` class, a multivector as a NumPy array of real coefficients indexed by ordinal.
+- `clif.util` — construction, printing, grade projection, involutions, and inverse models for specific dimensions.
+- `clif.tools` — primitive signtable support functions
+ 
+Inverse algorithms live in `clif.inverse`:
+
+- `clif.inverse.fls` (and `clif.inverse.sparse_fls`) — Faddeev–LeVerrier–Souriau based inverses, with even/odd-graded variants.
+- `clif.inverse.euclidean` — inverse for Euclidean (positive-definite) signatures.
+- `clif.inverse.newton` — iterative refinement via Newton–Schulz.
+
+## A worked example
+
+```python
+from clif.context import Cl, Layout
+from clif.multivector import Accum
+
+Cl(1, 1, 1)        # algebra with 1 positive, 1 negative, 1 null basis vector
+A = Accum.random()
+print(A)
+
+Cl(1, 3)                  # spacetime algebra  Cl(1,3)
+Layout([1, -1, -1, -1])   # equivalent, explicit
+```
+
+## Documentation
+
+Built locally with Sphinx:
+
+```bash
+cd docs && make html
+```
+
+Then open `docs/_build/html/index.html` in a browser.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

clif_ga-0.1.0/clif/__init__.py

@@ -0,0 +1,92 @@
+# file: clif/__init__.py
+"""
+clif — a Python package for Clifford algebra.
+
+This package implements Clifford algebra (geometric algebra) with a focus on
+explicit ordinal indexing of multivector components, efficient sign-table-based
+multiplication, and support for arbitrary metric signature and degeneracy.
+
+Architecture
+------------
+The package is organized as four cooperating layers:
+
+1. **context** — global algebra state (dimension, signature, degeneracy, grade table).
+   Call :func:`context.Initialize`, :func:`context.Layout`, or :func:`context.Cl`
+   to configure the algebra before constructing any multivectors.
+
+2. **sign_table** — builds and caches the multiplication sign table for the current
+   algebra, and generates a Numba-jitted fast multiplier for dimensions < 8.
+
+3. **multivector** — the :class:`multivector.Accum` class, which implements a
+   multivector as a NumPy array of real coefficients indexed by their ordinal
+   (a bitmask whose set bits name the basis vectors in the blade).
+
+4. **util** — convenience functions for constructing, printing, and operating on
+   multivectors (grade projection, involutions, random multivectors, inverses
+   for specific dimensions).
+
+5. **tools** — stand alone assistant functions 
+
+Inverse algorithms live in the :mod:`clif.inverse` sub-package:
+:func:`clif.inverse.fls_inverse` (Faddeev–LeVerrier–Souriau based, with
+:func:`even_inverse`/:func:`odd_inverse` variants and sparse counterparts),
+:func:`clif.inverse.euclidean_inverse`, and
+:func:`clif.inverse.newton_schulz` (iterative refinement).
+
+Ordinal indexing convention
+---------------------------
+An element of the algebra is identified by a non-negative integer whose binary
+representation names the basis vectors it contains.  In a 3-dimensional algebra::
+
+    0  = 0b000  scalar          (grade 0)
+    1  = 0b001  e1              (grade 1)
+    2  = 0b010  e2              (grade 1)
+    3  = 0b011  e1^e2           (grade 2)
+    4  = 0b100  e3              (grade 1)
+    5  = 0b101  e1^e3           (grade 2)
+    6  = 0b110  e2^e3           (grade 2)
+    7  = 0b111  e1^e2^e3  = I   (grade 3, pseudoscalar)
+
+This ordering differs from the graded lexicographic ordering used in the public
+``clifford`` package (pygae) and is a deliberate design choice of this implementation.
+
+Quick start
+-----------
+::
+
+    from clif.context import Cl, Layout
+    from clif.multivector import Accum
+
+    Cl(1, 1, 1)        # algebra with 1 positive, 1 negative, 1 null basis vector
+    A = Accum.random()
+    print(A)
+
+    Cl(1, 3)                  # spacetime algebra  Cl(1,3)
+    Layout([1, -1, -1, -1])   # equivalent, explicit
+
+Authors
+-------
+D. A. Jones  (original implementation)
+"""
+
+# ---- nice for the developer ---- (maybe)
+from clif import context
+from clif import sign_table
+from clif import multivector
+from clif import util
+from clif import tools
+
+# ---- all a user should need ----
+from clif.context import Cl, Grade
+from clif.multivector import Accum
+
+__all__ = [
+    "context",
+    "sign_table",
+    "multivector",
+    "util",
+    "tools",
+    "Cl",
+    "Grade",
+    "Accum"
+]

clif_ga-0.1.0/clif/context.py

@@ -0,0 +1,312 @@
+# file: clif/context.py
+"""
+Algebra context — global state for the current Clifford algebra.
+
+This module holds the parameters that define the algebra in use: the number of
+dimensions, the metric signature (which basis vectors square to −1), and the
+degeneracy mask (which basis vectors square to 0).  It also maintains the
+pre-computed :data:`Grade` table and the active :class:`~clif.sign_table.SignTable`.
+
+All multivectors created after a call to :func:`Initialize` (or the convenience
+wrappers :func:`Layout` and :func:`Cl`) share the same algebra context.
+
+.. warning::
+
+    The context is **module-level mutable state**.  Two multivectors created
+    under different :func:`Initialize` calls are mathematically incompatible.
+    Each :class:`~clif.multivector.Accum` instance records the context at
+    the time of its creation; use :func:`Check` to verify compatibility before
+    operating on a pair.
+
+Initialisation functions
+------------------------
+Three entry points are provided for different workflows:
+
+* :func:`Initialize` — specify dimension, signature mask, and degeneracy mask
+  directly (low-level, most explicit).
+* :func:`Layout` — specify the metric signature as a list of ``{+1, 0, −1}``
+  values, one per basis vector.
+* :func:`Cl` — specify the algebra as ``Cl(p, q, r)`` — ``p`` positive,
+  ``q`` negative, ``r`` degenerate basis vectors.
+
+Examples
+--------
+Euclidean 3-space::
+
+    import clif.context as Clif
+    Clif.Cl(3)           # Cl(3, 0, 0)
+
+Minkowski spacetime (one time-like dimension)::
+
+    Clif.Cl(1, 3)        # Cl(1, 3, 0)
+
+Projective geometry (one degenerate dimension)::
+
+    Clif.Cl(3, 0, 1)     # Cl(3, 0, 1)
+
+Explicit per-axis metric::
+
+    Clif.Layout([1, 1, -1, 0])
+"""
+
+import numpy as np
+import clif.sign_table as ST
+# NOTE: clif.inverse is imported lazily inside Initialize().  A top-level
+# import here would be circular: context -> inverse/__init__ -> fls -> context.
+
+# ---------------------------------------------------------------------------
+# Module-level state
+# ---------------------------------------------------------------------------
+
+#: Number of basis vectors in the current algebra.
+dimensions: int = 0
+
+#: Bitmask selecting the basis vectors that square to −1.
+#: Bit *k* is set when basis vector *e*\ (k+1) has negative signature.
+signature: int = 0
+
+#: Bitmask selecting the basis vectors that square to 0 (degenerate/null).
+#: Bit *k* is set when basis vector *e*\ (k+1) is degenerate.
+degenerate: int = 0
+
+#: Grade table: ``Grade[i]`` is the number of set bits in ``i``, i.e. the
+#: grade of the blade whose ordinal index is ``i``.
+#: Recomputed by :func:`Initialize`.
+Grade: np.ndarray = []
+
+#: The active :class:`~clif.sign_table.SignTable` for the current algebra.
+#: Set by :func:`Initialize`; ``None`` until the first call.
+_ActiveTable = None
+
+_ActiveInverse = None
+
+# ---------------------------------------------------------------------------
+# Derived quantities
+# ---------------------------------------------------------------------------
+
+def bases() -> int:
+    """Return the number of basis blades in the current algebra.
+
+    Equal to ``2 ** dimensions``.
+
+    Returns
+    -------
+    int
+        The number of basis blades.
+
+    Examples
+    --------
+    ::
+
+        Clif.Cl(3)
+        assert Clif.bases() == 8   # scalar + 3 vectors + 3 bivectors + 1 trivector
+    """
+    return 1 << dimensions
+
+
+def mask() -> int:
+    """Return a bitmask covering all valid ordinal indices.
+
+    Equal to ``bases() - 1``.
+
+    Returns
+    -------
+    int
+        Bitmask with the lowest ``dimensions`` bits set.
+    """
+    return (1 << dimensions) - 1
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _build_grade_table( dimensions: int ) -> np.ndarray:
+    """Recompute the :data:`Grade` table for the current :data:`dimensions`.
+
+    ``Grade[i]`` equals the number of 1-bits (population count) in ``i``,
+    which is the grade of the blade with ordinal index ``i``.
+
+    This function modifies the module global :data:`Grade` in place.
+    """
+
+    table = np.empty( 1<<dimensions, dtype=np.uint8 )
+    table[0] = 0
+    for d in range( dimensions ):
+        m = 1<<d
+        for n in range( m ):
+            table[m + n] = 1 + table[n]
+    return table
+
+
+# ---------------------------------------------------------------------------
+# Initialisation entry points
+# ---------------------------------------------------------------------------
+
+def Initialize(d: int, s: int = 0, x: int = 0) -> None:
+    """Configure the algebra by specifying dimension and metric masks.
+
+    This is the lowest-level initialisation entry point.  :func:`Layout` and
+    :func:`Cl` are more convenient for most uses.
+
+    Parameters
+    ----------
+    d : int
+        Number of basis vectors (dimensions of the vector space).
+    s : int, optional
+        Signature mask.  Bit *k* is set when basis vector *e*\\ (k+1) squares
+        to −1.  Default ``0`` gives a fully Euclidean algebra.
+    x : int, optional
+        Degeneracy mask.  Bit *k* is set when basis vector *e*\\ (k+1) squares
+        to 0.  Default ``0`` gives a non-degenerate algebra.
+
+    Notes
+    -----
+    Calling this function rebuilds the grade table and instantiates a new
+    :class:`~clif.sign_table.SignTable`.  For dimensions ≥ 8 the sign
+    table is not pre-built (the Numba multiplier is not generated); a
+    different multiplication strategy is required for those cases.
+
+    Examples
+    --------
+    Euclidean 6-space::
+
+        Initialize(6)
+
+    Minkowski space (negative first axis)::
+
+        Initialize(4, s=0b0001)
+
+    Degenerate axis (projective)::
+
+        Initialize(4, x=0b1000)
+    """
+    global dimensions, signature, degenerate, Grade, _ActiveTable, _ActiveInverse
+    dimensions = d
+    signature  = s
+    degenerate = x
+    Grade = _build_grade_table( d )
+    _ActiveTable = ST.SignTable(d, s, x)
+    
+    from clif.inverse import tau_api          # local: breaks the cycle
+    try:
+        _ActiveInverse = tau_api.get_inverter(get_signature()).inverse
+    except AssertionError:
+        # sparse_fls is the single source of truth on what it supports
+        # (currently d = 4..11, non-degenerate). Anything else: no inverse.
+        _ActiveInverse = None
+    return
+
+def Layout(Signature: list) -> None:
+    """Configure the algebra from a per-axis metric list.
+
+    Parameters
+    ----------
+    Signature : list of int
+        A list of ``+1``, ``0``, or ``-1`` values, one per basis vector.
+        The first entry describes *e1*, the second *e2*, and so on.
+
+    Examples
+    --------
+    Euclidean 3D::
+
+        Layout([1, 1, 1])
+
+    Minkowski (time-first)::
+
+        Layout([1, -1, -1, -1])
+
+    Projective 3D (degenerate first axis)::
+
+        Layout([0, 1, 1, 1])
+    """
+    d = len(Signature)
+    s = 0
+    x = 0
+    for w in Signature[::-1]:
+        s <<= 1
+        x <<= 1
+        if w < 0:
+            s |= 1
+        elif w == 0:
+            x |= 1
+    Initialize(d, s, x)
+    return
+
+def get_signature():
+    global dimensions
+    global signature
+    global degenerate
+    layout = []
+    for d in range(dimensions):
+        mask = 1 << d
+        if 0 != degenerate & mask:
+            this1 = 0
+        elif 0 != signature & mask:
+            this1 = -1
+        else:
+            this1 = 1
+        layout += [ this1 ]
+    return layout        
+
+def Cl(p: int, q: int = 0, r: int = 0) -> None:
+    """Configure the algebra as Cl(p, q, r).
+
+    Constructs the Clifford algebra with ``p`` basis vectors squaring to +1,
+    ``q`` squaring to −1, and ``r`` squaring to 0, in that order.
+
+    Parameters
+    ----------
+    p : int
+        Number of positive-signature (Euclidean) basis vectors.
+    q : int, optional
+        Number of negative-signature basis vectors.  Default 0.
+    r : int, optional
+        Number of degenerate (null) basis vectors.  Default 0.
+
+    Examples
+    --------
+    Euclidean 3-space ``Cl(3, 0)``::
+
+        Cl(3)
+
+    Spacetime algebra ``Cl(1, 3)``::
+
+        Cl(1, 3)
+
+    Conformal model of 3D space ``Cl(4, 1)``::
+
+        Cl(4, 1)
+    """
+    Layout( [1]*p + [-1]*q + [0]*r )
+    return
+
+
+# ---------------------------------------------------------------------------
+# Compatibility check
+# ---------------------------------------------------------------------------
+
+def Check(A, B) -> None:
+    """Assert that two multivectors share the same algebra context.
+
+    Parameters
+    ----------
+    A, B : :class:`~clif.multivector.Accum`
+        The two multivectors to compare.
+
+    Raises
+    ------
+    AssertionError
+        If the multivectors differ in dimension, signature, or degeneracy.
+
+    Notes
+    -----
+    This check is *not* called automatically during arithmetic for performance
+    reasons.  Call it explicitly during debugging or testing.
+    """
+    assert A.dimensions == B.dimensions, \
+        f"Dimension mismatch: {A.dimensions} vs {B.dimensions}"
+    assert A.signature  == B.signature,  \
+        f"Signature mismatch: {A.signature:#010b} vs {B.signature:#010b}"
+    assert A.degenerate == B.degenerate, \
+        f"Degeneracy mismatch: {A.degenerate:#010b} vs {B.degenerate:#010b}"

clif_ga-0.1.0/clif/inverse/__init__.py

@@ -0,0 +1,26 @@
+# file: clif/inverse/__init__.py
+# 2026.05.14 DAJones: created
+# 2026.08.17 DAJones: updated sparse_fls and added tau_api
+
+"""
+clif.inverse
+~~~~~~~~~~~~
+Fast, JIT-compiled multivector inverse routines for arbitrary signature.
+"""
+
+from .fls import fls_inverse
+from .newton import newton_schulz
+from .euclidean import euclidean_inverse
+from .sparse_fls import TauInverse
+from .sparse_fls_dd import DDTauInverse
+from .tau_api import get_inverter, inverse, warm
+from .low_dim_inverse import inverse
+
+__all__ = [
+    "euclidean_inverse",
+    "fls_inverse",
+    "newton_schulz",
+    "TauInverse",
+    "get_inverter", "inverse", "warm"
+    "inverse"
+]

clif_ga-0.1.0/clif/inverse/euclidean.py

@@ -0,0 +1,60 @@
+# file: clif/inverse/euclidean.py
+"""
+Top-level multivector inverse via the tau-domain kernel, d in 4-11.
+"""
+
+import clif.context as Clif
+from clif.multivector import Accum
+from clif.inverse.tau_api import get_inverter
+from clif.inverse.newton  import newton_schulz
+
+
+def euclidean_inverse(A: Accum, refine: bool = True) -> Accum:
+    """Inverse of a non-singular multivector in Euclidean Cl(d, 0), d in 6-13.
+
+    Uses the sparse FLS kernel for speed.  At dimensions 12-13 the
+    polynomial iteration accumulates enough floating-point error that
+    the raw result has residuals of O(10⁻⁵) to O(10⁻³); when
+    ``refine=True`` (the default) Newton-Schulz iteration is applied
+    automatically to recover machine precision.
+
+    Parameters
+    ----------
+    A : Accum
+        Non-singular multivector.
+    refine : bool, optional
+        If True (default), apply Newton-Schulz refinement for dim >= 12.
+        Set False to return the raw FLS result at any dimension.
+
+    Returns
+    -------
+    Accum
+        Multiplicative inverse of A.
+
+    Raises
+    ------
+    ValueError
+        If dimension is outside 6-13.
+
+    Notes
+    -----
+    Typical residuals (max |A · A⁻¹ − e₀| over all blades):
+
+    ======  ============  ===============
+    dim     FLS only      FLS + NS
+    ======  ============  ===============
+    6       1.4 × 10⁻¹⁴  —
+    7       1.7 × 10⁻¹⁵  —
+    8       2.4 × 10⁻¹⁴  —
+    9       1.8 × 10⁻¹²  —
+    10      3.6 × 10⁻¹⁰  —
+    11      2.9 × 10⁻¹⁰  —
+    12      9.4 × 10⁻⁶   9.0 × 10⁻¹⁶
+    13      4.2 × 10⁻³   1.8 × 10⁻¹⁵
+    ======  ============  ===============
+    """
+    X = Accum()
+    X.Reg = get_inverter(Clif.get_signature()).inverse(A.Reg)
+    if refine and A.dimensions >= 12:
+        X = newton_schulz(A, X)
+    return X