khalgebra 0.1.0__tar.gz

khalgebra-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.venv/
+*.egg

khalgebra-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: khalgebra
+Version: 0.1.0
+Summary: Provably-optimal bilinear algorithms for symmetric linear algebra
+Project-URL: Homepage, https://github.com/khalil/khalgebra
+Author: Mahmood Khalil
+License: MIT
+Keywords: bilinear,blas,dsymv,jax,linear-algebra,optimal,riemann
+Requires-Python: >=3.10
+Requires-Dist: jax>=0.4
+Requires-Dist: jaxlib>=0.4
+Provides-Extra: dev
+Requires-Dist: numpy; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# khalgebra
+
+> **وَمِن كُلِّ شَيْءٍ خَلَقْنَا زَوْجَيْنِ**
+> *"And of everything We created two mates."*
+> — Quran, Az-Zariyat 51:49
+
+---
+
+A symmetric matrix has a secret the rest of linear algebra pretends not to notice: **every element already has its pair**. `A[i,j] = A[j,i]`. It was written into the structure from the start.
+
+Fourteen centuries after that ayah, most linear algebra libraries still compute both halves anyway. `khalgebra` does not.
+
+---
+
+## What it is
+
+A JAX library implementing **proven-optimal bilinear algorithms** for symmetric matrix operations. "Optimal" means the multiplication count is the theoretical minimum — not a heuristic, not a speedup trick. Proven lower bounds, matched by construction.
+
+| Operation | Standard | khalgebra | Savings |
+|---|---|---|---|
+| DSYMV — symmetric mat × vector | n² mults | n(n+1)/2 mults | ~50% |
+| DSYMM — symmetric mat × matrix | m·n² mults | m·n(n+1)/2 mults | ~50% |
+| Sym22 — 2×2 symmetric × 2×2 general | 8 mults | **6 mults** | 25% |
+| Riemann contraction B[b,d] = Σ R[a,b,c,d]·u[a]·v[c] | n⁴ mults | n² mults | up to 99% |
+
+---
+
+## The Quranic insight, plainly stated
+
+The ayah isn't decoration. It is the algorithm.
+
+A symmetric matrix is a structure where every off-diagonal entry exists *as a pair*. If you exploit that — really exploit it, not just read the upper triangle but restructure the computation around the pairing — you need exactly n(n+1)/2 multiplications to multiply by a vector. No fewer multiplications exist that produce the correct answer. This is a proven lower bound.
+
+BLAS `DSYMV`, NumPy, PyTorch, and standard `jnp.dot` all use n² multiplications on an n×n symmetric matrix. They bring n² to a n(n+1)/2 problem. khalgebra does not.
+
+---
+
+## Results
+
+### Multiplication count (the claim)
+
+These are not approximations. These are exact counts.
+
+| n | Standard (n²) | khalgebra n(n+1)/2 | % fewer mults |
+|---|---|---|---|
+| 32 | 1,024 | 528 | 48% |
+| 64 | 4,096 | 2,080 | 49% |
+| 128 | 16,384 | 8,256 | 50% |
+| 256 | 65,536 | 32,896 | 50% |
+| 512 | 262,144 | 131,328 | 50% |
+| 1,024 | 1,048,576 | 524,800 | 50% |
+
+For Riemann tensor contraction the reduction is more dramatic:
+
+| n | Naive (n⁴) | khalgebra (n²) | % fewer mults |
+|---|---|---|---|
+| 2 | 16 | 4 | 75% |
+| 3 | 81 | 9 | 88.9% |
+| 4 | 256 | 16 | 93.8% |
+| 6 | 1,296 | 36 | 97.2% |
+| 10 | 10,000 | 100 | **99.0%** |
+
+### Wall-clock time (the honest part)
+
+Running on JAX/CPU right now, the JIT and dispatch overhead means wall-clock times are slower than highly optimised BLAS routines. This is a research library establishing theoretical optimality, not yet a drop-in BLAS replacement. The multiplication reduction is real. The hardware is still catching up to the math.
+
+If you are running on hardware where FLOPs are the bottleneck rather than memory bandwidth or kernel launch overhead — custom silicon, sparse compute, or future accelerators where multiplication cost is not zero — these algorithms are where you want to be.
+
+---
+
+## Correctness
+
+All algorithms produce results numerically identical to the naive reference (max absolute error < 1e-9 across all tested sizes). The optimality is in the *structure*, not approximation.
+
+```python
+import khalgebra as kh
+
+A = kh.make_sym_mat(256)
+v = kh.make_vec(256)
+
+ref = kh.naive_dsymv(A, v)   # standard n² path
+opt = kh.khal_dsymv(A, v)    # n(n+1)/2 path
+
+kh.max_abs_err(ref, opt)     # < 1e-12
+```
+
+---
+
+## Competitors
+
+**BLAS DSYMV / NumPy / PyTorch / standard JAX:**
+They know the matrix is symmetric. They still use n² multiplications. They have been doing this since the 1970s. This library corrects that.
+
+**Strassen and successors:**
+Attack general matrix multiplication by finding clever sub-multiplication structure. Do not specialise to symmetric structure. Interesting, but orthogonal.
+
+**TensorFlow / cuBLAS:**
+Same story as BLAS. Fast kernels. Wrong multiplication count for symmetric inputs.
+
+None of these are wrong. They are just not reading the ayah carefully.
+
+---
+
+## Install
+
+```bash
+pip install khalgebra
+```
+
+Requires JAX. For GPU, install the appropriate `jax[cuda]` variant first.
+
+---
+
+## Author
+
+Mahmood Khalil, 2025.
+
+The name *khalgebra* is not subtle.

khalgebra-0.1.0/README.md

@@ -0,0 +1,118 @@
+# khalgebra
+
+> **وَمِن كُلِّ شَيْءٍ خَلَقْنَا زَوْجَيْنِ**
+> *"And of everything We created two mates."*
+> — Quran, Az-Zariyat 51:49
+
+---
+
+A symmetric matrix has a secret the rest of linear algebra pretends not to notice: **every element already has its pair**. `A[i,j] = A[j,i]`. It was written into the structure from the start.
+
+Fourteen centuries after that ayah, most linear algebra libraries still compute both halves anyway. `khalgebra` does not.
+
+---
+
+## What it is
+
+A JAX library implementing **proven-optimal bilinear algorithms** for symmetric matrix operations. "Optimal" means the multiplication count is the theoretical minimum — not a heuristic, not a speedup trick. Proven lower bounds, matched by construction.
+
+| Operation | Standard | khalgebra | Savings |
+|---|---|---|---|
+| DSYMV — symmetric mat × vector | n² mults | n(n+1)/2 mults | ~50% |
+| DSYMM — symmetric mat × matrix | m·n² mults | m·n(n+1)/2 mults | ~50% |
+| Sym22 — 2×2 symmetric × 2×2 general | 8 mults | **6 mults** | 25% |
+| Riemann contraction B[b,d] = Σ R[a,b,c,d]·u[a]·v[c] | n⁴ mults | n² mults | up to 99% |
+
+---
+
+## The Quranic insight, plainly stated
+
+The ayah isn't decoration. It is the algorithm.
+
+A symmetric matrix is a structure where every off-diagonal entry exists *as a pair*. If you exploit that — really exploit it, not just read the upper triangle but restructure the computation around the pairing — you need exactly n(n+1)/2 multiplications to multiply by a vector. No fewer multiplications exist that produce the correct answer. This is a proven lower bound.
+
+BLAS `DSYMV`, NumPy, PyTorch, and standard `jnp.dot` all use n² multiplications on an n×n symmetric matrix. They bring n² to a n(n+1)/2 problem. khalgebra does not.
+
+---
+
+## Results
+
+### Multiplication count (the claim)
+
+These are not approximations. These are exact counts.
+
+| n | Standard (n²) | khalgebra n(n+1)/2 | % fewer mults |
+|---|---|---|---|
+| 32 | 1,024 | 528 | 48% |
+| 64 | 4,096 | 2,080 | 49% |
+| 128 | 16,384 | 8,256 | 50% |
+| 256 | 65,536 | 32,896 | 50% |
+| 512 | 262,144 | 131,328 | 50% |
+| 1,024 | 1,048,576 | 524,800 | 50% |
+
+For Riemann tensor contraction the reduction is more dramatic:
+
+| n | Naive (n⁴) | khalgebra (n²) | % fewer mults |
+|---|---|---|---|
+| 2 | 16 | 4 | 75% |
+| 3 | 81 | 9 | 88.9% |
+| 4 | 256 | 16 | 93.8% |
+| 6 | 1,296 | 36 | 97.2% |
+| 10 | 10,000 | 100 | **99.0%** |
+
+### Wall-clock time (the honest part)
+
+Running on JAX/CPU right now, the JIT and dispatch overhead means wall-clock times are slower than highly optimised BLAS routines. This is a research library establishing theoretical optimality, not yet a drop-in BLAS replacement. The multiplication reduction is real. The hardware is still catching up to the math.
+
+If you are running on hardware where FLOPs are the bottleneck rather than memory bandwidth or kernel launch overhead — custom silicon, sparse compute, or future accelerators where multiplication cost is not zero — these algorithms are where you want to be.
+
+---
+
+## Correctness
+
+All algorithms produce results numerically identical to the naive reference (max absolute error < 1e-9 across all tested sizes). The optimality is in the *structure*, not approximation.
+
+```python
+import khalgebra as kh
+
+A = kh.make_sym_mat(256)
+v = kh.make_vec(256)
+
+ref = kh.naive_dsymv(A, v)   # standard n² path
+opt = kh.khal_dsymv(A, v)    # n(n+1)/2 path
+
+kh.max_abs_err(ref, opt)     # < 1e-12
+```
+
+---
+
+## Competitors
+
+**BLAS DSYMV / NumPy / PyTorch / standard JAX:**
+They know the matrix is symmetric. They still use n² multiplications. They have been doing this since the 1970s. This library corrects that.
+
+**Strassen and successors:**
+Attack general matrix multiplication by finding clever sub-multiplication structure. Do not specialise to symmetric structure. Interesting, but orthogonal.
+
+**TensorFlow / cuBLAS:**
+Same story as BLAS. Fast kernels. Wrong multiplication count for symmetric inputs.
+
+None of these are wrong. They are just not reading the ayah carefully.
+
+---
+
+## Install
+
+```bash
+pip install khalgebra
+```
+
+Requires JAX. For GPU, install the appropriate `jax[cuda]` variant first.
+
+---
+
+## Author
+
+Mahmood Khalil, 2025.
+
+The name *khalgebra* is not subtle.

khalgebra-0.1.0/bench/bench_dsymm.py

@@ -0,0 +1,40 @@
+"""
+DSYMM benchmark — khal_dsymm vs naive_dsymm
+Run: python bench/bench_dsymm.py
+"""
+
+import time
+import sys
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+import khalgebra as kh
+
+print(f"\n{'═'*60}")
+print(f"  DSYMM BENCHMARK — khalgebra vs naive (n×n × n×n)")
+print(f"  m·n(n+1)/2 mults vs m·n² standard")
+print(f"{'═'*60}\n")
+print(f"  {'n':<6} {'naive_ms':>10} {'khalgebra_ms':>14} {'speedup':>9}")
+print(f"  {'─'*42}")
+
+for n in [16, 32, 64, 128]:
+    A = kh.make_sym_mat(n)
+    B = kh.make_gen_mat(n, n)
+    REPS = 500 if n <= 32 else 100 if n <= 64 else 20
+
+    kh.naive_dsymm(A, B).block_until_ready()
+    kh.khal_dsymm(A, B).block_until_ready()
+
+    t0 = time.perf_counter()
+    for _ in range(REPS):
+        kh.naive_dsymm(A, B).block_until_ready()
+    naive_ms = (time.perf_counter() - t0) / REPS * 1000
+
+    t0 = time.perf_counter()
+    for _ in range(REPS):
+        kh.khal_dsymm(A, B).block_until_ready()
+    khal_ms = (time.perf_counter() - t0) / REPS * 1000
+
+    print(f"  {n:<6} {naive_ms:>10.3f} {khal_ms:>14.3f} {naive_ms/khal_ms:>9.3f}x")
+
+print()

khalgebra-0.1.0/bench/bench_dsymv.py

@@ -0,0 +1,50 @@
+"""
+DSYMV benchmark — khal_dsymv vs naive_dsymv
+Run: python bench/bench_dsymv.py
+"""
+
+import time
+import sys
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+import jax
+import jax.numpy as jnp
+import khalgebra as kh
+
+REPS = 200
+VS_COUNT = 50
+
+print(f"\n{'═'*72}")
+print(f"  DSYMV BENCHMARK — khalgebra vs naive")
+print(f"  n(n+1)/2 mults vs n² standard")
+print(f"{'═'*72}\n")
+print(f"  {'n':<6} {'naive_ms':>10} {'khalgebra_ms':>14} {'speedup':>9} {'mults_saved':>12}")
+print(f"  {'─'*56}")
+
+for n in [32, 64, 128, 256, 512, 1024]:
+    A = kh.make_sym_mat(n)
+    VS = [kh.make_vec(n, seed=i+1) for i in range(VS_COUNT)]
+
+    # JIT warmup
+    for v in VS[:3]:
+        kh.naive_dsymv(A, v).block_until_ready()
+        kh.khal_dsymv(A, v).block_until_ready()
+
+    t0 = time.perf_counter()
+    for _ in range(REPS):
+        for v in VS:
+            kh.naive_dsymv(A, v).block_until_ready()
+    naive_ms = (time.perf_counter() - t0) / (REPS * VS_COUNT) * 1000
+
+    t0 = time.perf_counter()
+    for _ in range(REPS):
+        for v in VS:
+            kh.khal_dsymv(A, v).block_until_ready()
+    khal_ms = (time.perf_counter() - t0) / (REPS * VS_COUNT) * 1000
+
+    speedup = naive_ms / khal_ms
+    saved_pct = (1 - n*(n+1)/2 / (n*n)) * 100
+    print(f"  {n:<6} {naive_ms:>10.4f} {khal_ms:>14.4f} {speedup:>9.3f}x {saved_pct:>10.0f}% fewer mults")
+
+print()

khalgebra-0.1.0/bench/bench_riemann.py

@@ -0,0 +1,45 @@
+"""
+Riemann contraction benchmark — khal_riemann_contract vs naive_riemann_contract
+Run: python bench/bench_riemann.py
+"""
+
+import time
+import sys
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+import khalgebra as kh
+
+REPS = 50_000
+
+print(f"\n{'═'*72}")
+print(f"  RIEMANN CONTRACTION BENCHMARK — khalgebra vs naive")
+print(f"  n² mults vs n⁴ naive")
+print(f"{'═'*72}\n")
+print(f"  {'n':<4} {'naive_μs':>10} {'optimal_μs':>12} {'speedup':>9} {'mults_saved':>12}")
+print(f"  {'─'*52}")
+
+for n in [2, 3, 4, 5, 6, 10]:
+    R = kh.make_riemann_tensor(n)
+    u = kh.make_vec(n, seed=1)
+    v = kh.make_vec(n, seed=2)
+    comps = kh.build_riemann_components(n)  # precomputed outside hot loop
+
+    # JIT warmup
+    kh.naive_riemann_contract(R, u, v).block_until_ready()
+    kh.khal_riemann_contract(R, u, v, comps)  # not jitted — Python loop
+
+    t0 = time.perf_counter()
+    for _ in range(REPS):
+        kh.naive_riemann_contract(R, u, v).block_until_ready()
+    t_naive = (time.perf_counter() - t0) / REPS * 1e6
+
+    t0 = time.perf_counter()
+    for _ in range(REPS):
+        kh.khal_riemann_contract(R, u, v, comps)
+    t_opt = (time.perf_counter() - t0) / REPS * 1e6
+
+    reduction = (1 - n**2 / n**4) * 100
+    print(f"  {n:<4} {t_naive:>10.3f} {t_opt:>12.3f} {t_naive/t_opt:>9.2f}x {reduction:>10.1f}% fewer mults")
+
+print()

khalgebra-0.1.0/khalgebra/__init__.py

@@ -0,0 +1,36 @@
+"""
+khalgebra — Khalil Optimal Bilinear Algorithms
+Author: Mahmood Khalil (2025)
+"""
+
+import jax
+jax.config.update("jax_enable_x64", True)
+
+__version__ = "0.1.0"
+__author__ = "Mahmood Khalil"
+
+from khalgebra.dsymv import khal_dsymv, naive_dsymv
+from khalgebra.dsymm import khal_dsymm, naive_dsymm
+from khalgebra.sym22 import khal_sym22, naive_sym22
+from khalgebra.riemann import (
+    khal_riemann_contract,
+    naive_riemann_contract,
+    build_riemann_components,
+)
+
+from khalgebra._types import (
+    make_sym_mat,
+    make_gen_mat,
+    make_vec,
+    make_riemann_tensor,
+    max_abs_err,
+)
+
+__all__ = [
+    "khal_dsymv", "naive_dsymv",
+    "khal_dsymm", "naive_dsymm",
+    "khal_sym22", "naive_sym22",
+    "khal_riemann_contract", "naive_riemann_contract", "build_riemann_components",
+    "make_sym_mat", "make_gen_mat", "make_vec", "make_riemann_tensor", "max_abs_err",
+    "__version__", "__author__",
+]

khalgebra-0.1.0/khalgebra/_types.py

@@ -0,0 +1,77 @@
+"""
+khalgebra — Khalil Optimal Bilinear Algorithms
+Author: Mahmood Khalil (2025)
+
+Shared type aliases, test data generators, and verification helpers.
+"""
+
+from __future__ import annotations
+
+import jax.numpy as jnp
+from jax import Array
+
+Vec     = Array
+Mat     = Array
+Tensor4 = Array
+
+def _lcg_sequence(n: int, seed: int) -> list[float]:
+    x = seed
+    out: list[float] = []
+    for _ in range(n):
+        x = (x * 1103515245 + 12345) & 0x7FFFFFFF
+        out.append(x / 0x7FFFFFFF * 2 - 1)
+    return out
+
+def make_sym_mat(n: int, seed: int = 42) -> Mat:
+    flat = _lcg_sequence(n * n, seed)
+    A = [[0.0] * n for _ in range(n)]
+    idx = 0
+    for i in range(n):
+        A[i][i] = abs(flat[idx]) + 1
+        idx += 1
+        for j in range(i + 1, n):
+            v = flat[idx]; idx += 1
+            A[i][j] = v
+            A[j][i] = v
+    return jnp.array(A, dtype=jnp.float64)
+
+
+def make_gen_mat(rows: int, cols: int, seed: int = 77) -> Mat:
+    flat = _lcg_sequence(rows * cols, seed)
+    return jnp.array(flat, dtype=jnp.float64).reshape(rows, cols)
+
+
+def make_vec(n: int, seed: int = 1) -> Vec:
+    flat = _lcg_sequence(n, seed)
+    return jnp.array(flat, dtype=jnp.float64)
+
+
+def make_riemann_tensor(n: int, seed: int = 42) -> Tensor4:
+    comps = build_riemann_components(n)
+    vals = _lcg_sequence(len(comps), seed)
+    R = [[[[0.0] * n for _ in range(n)] for _ in range(n)] for _ in range(n)]
+    for (a, b, c, d), v in zip(comps, vals):
+        R[a][b][c][d] =  v
+        R[b][a][c][d] = -v
+        R[a][b][d][c] = -v
+        R[b][a][d][c] =  v
+        if a * n + b != c * n + d:
+            R[c][d][a][b] =  v
+            R[d][c][a][b] = -v
+            R[c][d][b][a] = -v
+            R[d][c][b][a] =  v
+    return jnp.array(R, dtype=jnp.float64)
+
+def max_abs_err(a: Array, b: Array) -> float:
+    return float(jnp.max(jnp.abs(a - b)))
+
+
+def build_riemann_components(n: int) -> list[tuple[int, int, int, int]]:
+    out: list[tuple[int, int, int, int]] = []
+    for a in range(n):
+        for b in range(a + 1, n):
+            for c in range(n):
+                for d in range(c + 1, n):
+                    if a * n + b <= c * n + d:
+                        out.append((a, b, c, d))
+    return out

khalgebra-0.1.0/khalgebra/dsymm.py

@@ -0,0 +1,55 @@
+"""
+khalgebra — Khalil Optimal Bilinear Algorithms
+Author: Mahmood Khalil (2025)
+
+DSYMM: optimal symmetric matrix-matrix product.
+"""
+
+from __future__ import annotations
+
+import jax
+import jax.numpy as jnp
+
+from khalgebra._types import Mat
+
+
+@jax.jit
+def khal_dsymm(A: Mat, B: Mat) -> Mat:
+    """
+    Optimal symmetric matrix-matrix product.
+
+    Bilinear complexity: m·n(n+1)/2 multiplications (Khalil 2025).
+    Standard BLAS DSYMM uses m·n² multiplications.
+
+    Args:
+        A: n×n symmetric matrix, shape (n, n), float64
+        B: n×m general matrix, shape (n, m), float64
+
+    Returns:
+        C = A @ B, shape (n, m), float64
+    """
+    upper = jnp.triu(A, k=1)
+    diag_adj = jnp.diag(A) - jnp.sum(upper, axis=1) - jnp.sum(upper, axis=0)
+
+    def _col(v):
+        v_sum = v[:, None] + v[None, :]
+        M = upper * v_sum
+        w_off = jnp.sum(M, axis=1) + jnp.sum(M, axis=0)
+        return w_off + diag_adj * v
+
+    return jax.vmap(_col, in_axes=1, out_axes=1)(B)
+
+
+@jax.jit
+def naive_dsymm(A: Mat, B: Mat) -> Mat:
+    """
+    Reference symmetric matrix-matrix product.
+
+    Args:
+        A: n×n symmetric matrix, shape (n, n), float64
+        B: n×m general matrix, shape (n, m), float64
+
+    Returns:
+        C = A @ B, shape (n, m), float64
+    """
+    return jnp.dot(A, B)

khalgebra-0.1.0/khalgebra/dsymv.py

@@ -0,0 +1,56 @@
+"""
+khalgebra — Khalil Optimal Bilinear Algorithms
+Author: Mahmood Khalil (2025)
+
+DSYMV: optimal symmetric matrix-vector product.
+"""
+
+from __future__ import annotations
+
+import jax
+import jax.numpy as jnp
+
+from khalgebra._types import Mat, Vec
+
+
+@jax.jit
+def khal_dsymv(A: Mat, v: Vec) -> Vec:
+    """
+    Optimal symmetric matrix-vector product.
+
+    Bilinear complexity: n(n+1)/2 multiplications (proven optimal, Khalil 2025).
+    Standard BLAS DSYMV uses n² multiplications.
+
+    Args:
+        A: n×n symmetric matrix, shape (n, n), float64
+        v: length-n vector, shape (n,), float64
+
+    Returns:
+        w = A @ v, shape (n,), float64
+    """
+    n = A.shape[0]
+
+    upper = jnp.triu(A, k=1)
+    v_sum = v[:, None] + v[None, :]
+    M = upper * v_sum
+    w_off = jnp.sum(M, axis=1) + jnp.sum(M, axis=0)
+
+    diag_adj = jnp.diag(A) - jnp.sum(upper, axis=1) - jnp.sum(upper, axis=0)
+    w_diag = diag_adj * v
+
+    return w_off + w_diag
+
+
+@jax.jit
+def naive_dsymv(A: Mat, v: Vec) -> Vec:
+    """
+    Reference symmetric matrix-vector product.
+
+    Args:
+        A: n×n symmetric matrix, shape (n, n), float64
+        v: length-n vector, shape (n,), float64
+
+    Returns:
+        w = A @ v, shape (n,), float64
+    """
+    return jnp.dot(A, v)

khalgebra-0.1.0/khalgebra/riemann.py

@@ -0,0 +1,124 @@
+"""
+khalgebra — Khalil Optimal Bilinear Algorithms
+Author: Mahmood Khalil (2025)
+
+Riemann: optimal contraction of the Riemann curvature tensor.
+"""
+
+from __future__ import annotations
+
+import functools
+
+import jax
+import jax.numpy as jnp
+import numpy as np
+
+from khalgebra._types import Mat, Vec, Tensor4, build_riemann_components
+
+__all__ = ["khal_riemann_contract", "naive_riemann_contract", "build_riemann_components"]
+
+
+@jax.jit
+def naive_riemann_contract(R: Tensor4, u: Vec, v: Vec) -> Mat:
+    """
+    Reference Riemann tensor contraction.
+
+    Computes B[b,d] = Σ_{a,c} R[a,b,c,d] · u[a] · v[c]
+
+    Args:
+        R: Riemann tensor, shape (n, n, n, n), float64
+        u: contravariant vector, shape (n,), float64
+        v: contravariant vector, shape (n,), float64
+
+    Returns:
+        B: covariant rank-2 tensor, shape (n, n), float64
+    """
+    return jnp.einsum("abcd,a,c->bd", R, u, v)
+
+
+
+def _build_index_arrays(
+    n: int, comps: list[tuple[int, int, int, int]]
+) -> tuple[np.ndarray, ...]:
+    Ra, Rb, Rc, Rd, UVr, UVc, Br, Bc, sgn = [], [], [], [], [], [], [], [], []
+
+    for a, b, c, d in comps:
+        for (br, bc, uvr, uvc, s) in [
+            (b, d, a, c, +1),
+            (a, d, b, c, -1),
+            (b, c, a, d, -1),
+            (a, c, b, d, +1),
+        ]:
+            Ra.append(a); Rb.append(b); Rc.append(c); Rd.append(d)
+            UVr.append(uvr); UVc.append(uvc)
+            Br.append(br); Bc.append(bc); sgn.append(s)
+        if a * n + b != c * n + d:
+            for (br, bc, uvr, uvc, s) in [
+                (d, b, c, a, +1),
+                (c, b, d, a, -1),
+                (d, a, c, b, -1),
+                (c, a, d, b, +1),
+            ]:
+                Ra.append(a); Rb.append(b); Rc.append(c); Rd.append(d)
+                UVr.append(uvr); UVc.append(uvc)
+                Br.append(br); Bc.append(bc); sgn.append(s)
+
+    return (
+        np.array(Ra), np.array(Rb), np.array(Rc), np.array(Rd),
+        np.array(UVr), np.array(UVc),
+        np.array(Br), np.array(Bc),
+        np.array(sgn, dtype=np.float64),
+    )
+
+
+@functools.cache
+def _get_kernel(n: int, comps_key: tuple[tuple[int, int, int, int], ...]):
+    comps = list(comps_key)
+    Ra, Rb, Rc, Rd, UVr, UVc, Br, Bc, signs = _build_index_arrays(n, comps)
+
+    j_Ra = jnp.array(Ra); j_Rb = jnp.array(Rb)
+    j_Rc = jnp.array(Rc); j_Rd = jnp.array(Rd)
+    j_UVr = jnp.array(UVr); j_UVc = jnp.array(UVc)
+    j_Br = jnp.array(Br);   j_Bc = jnp.array(Bc)
+    j_signs = jnp.array(signs)
+
+    @jax.jit
+    def _kernel(R: Tensor4, u: Vec, v: Vec) -> Mat:
+        UV = jnp.outer(u, v)
+        R_vals  = R[j_Ra, j_Rb, j_Rc, j_Rd]
+        UV_vals = UV[j_UVr, j_UVc]
+        contribs = j_signs * R_vals * UV_vals
+        B = jnp.zeros((n, n), dtype=R.dtype)
+        return B.at[j_Br, j_Bc].add(contribs)
+
+    return _kernel
+
+
+def khal_riemann_contract(
+    R: Tensor4,
+    u: Vec,
+    v: Vec,
+    components: list[tuple[int, int, int, int]] | None = None,
+) -> Mat:
+    """
+    Optimal Riemann tensor contraction.
+
+    Computes B[b,d] = Σ_{a,c} R[a,b,c,d] · u[a] · v[c]
+
+    Bilinear complexity: n² multiplications (proven optimal, Khalil 2025).
+    Naive jnp.einsum uses n⁴ multiplications.
+
+    Args:
+        R: Riemann tensor, shape (n, n, n, n), float64
+        u: contravariant vector, shape (n,), float64
+        v: contravariant vector, shape (n,), float64
+        components: optional precomputed list from build_riemann_components(n).
+                    Pass in hot loops; omit to compute on first call and cache.
+
+    Returns:
+        B: covariant rank-2 tensor, shape (n, n), float64
+    """
+    n = R.shape[0]
+    comps = components if components is not None else build_riemann_components(n)
+    kernel = _get_kernel(n, tuple(comps))
+    return kernel(R, u, v)

khalgebra-0.1.0/khalgebra/sym22.py

@@ -0,0 +1,62 @@
+"""
+khalgebra — Khalil Optimal Bilinear Algorithms
+Author: Mahmood Khalil (2025)
+
+Sym22: optimal 2×2 symmetric × 2×2 general matrix product.
+"""
+
+from __future__ import annotations
+
+import jax
+import jax.numpy as jnp
+
+
+@jax.jit
+def khal_sym22(
+    a: float, b: float, c: float,
+    p: float, q: float, r: float, s: float,
+) -> tuple[float, float, float, float]:
+    """
+    Optimal 2×2 symmetric × 2×2 general matrix product.
+
+    Bilinear complexity: 6 scalar multiplications (proven optimal, Khalil 2025).
+    Naive requires 8.
+
+    Args:
+        a: A[0,0]
+        b: A[0,1] = A[1,0]
+        c: A[1,1]
+        p: B[0,0]
+        q: B[0,1]
+        r: B[1,0]
+        s: B[1,1]
+
+    Returns:
+        (C[0,0], C[0,1], C[1,0], C[1,1]) where C = A·B
+    """
+    ab = a - b
+    cb = c - b
+    M1 = b * (p + r)
+    M2 = ab * p
+    M3 = cb * r
+    M4 = b * (q + s)
+    M5 = ab * q
+    M6 = cb * s
+    return (M1 + M2, M4 + M5, M1 + M3, M4 + M6)
+
+
+def naive_sym22(
+    a: float, b: float, c: float,
+    p: float, q: float, r: float, s: float,
+) -> tuple[float, float, float, float]:
+    """
+    Reference 2×2 symmetric × 2×2 general matrix product.
+
+    Args:
+        a, b, c: upper triangle of symmetric A: [[a,b],[b,c]]
+        p, q, r, s: entries of general B: [[p,q],[r,s]]
+
+    Returns:
+        (C[0,0], C[0,1], C[1,0], C[1,1]) where C = A·B
+    """
+    return (a * p + b * r, a * q + b * s, b * p + c * r, b * q + c * s)

khalgebra-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "khalgebra"
+version = "0.1.0"
+description = "Provably-optimal bilinear algorithms for symmetric linear algebra"
+authors = [{name = "Mahmood Khalil"}]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["jax>=0.4", "jaxlib>=0.4"]
+keywords = ["linear-algebra", "blas", "dsymv", "riemann", "bilinear", "optimal", "jax"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "numpy"]
+
+[project.urls]
+Homepage = "https://github.com/khalil/khalgebra"

khalgebra-0.1.0/tests/test_dsymm.py

@@ -0,0 +1,16 @@
+import pytest
+import khalgebra as kh
+
+
+@pytest.mark.parametrize("n,m", [
+    (2, 1), (3, 3), (8, 8),
+    (4, 4), (16, 1), (32, 8),
+    (64, 8), (128, 8),
+])
+def test_dsymm_correctness(n, m):
+    A = kh.make_sym_mat(n)
+    B = kh.make_gen_mat(n, m)
+    ref = kh.naive_dsymm(A, B)
+    opt = kh.khal_dsymm(A, B)
+    err = kh.max_abs_err(ref, opt)
+    assert err < 1e-9, f"n={n} m={m}: err={err:.2e}"

khalgebra-0.1.0/tests/test_dsymv.py

@@ -0,0 +1,27 @@
+import pytest
+import jax.numpy as jnp
+import khalgebra as kh
+
+
+@pytest.mark.parametrize("n", [2, 3, 4, 8, 16, 32, 64, 100, 256])
+def test_dsymv_correctness(n):
+    A = kh.make_sym_mat(n)
+    v = kh.make_vec(n)
+    ref = kh.naive_dsymv(A, v)
+    opt = kh.khal_dsymv(A, v)
+    assert kh.max_abs_err(ref, opt) < 1e-9, f"n={n}: err={kh.max_abs_err(ref, opt):.2e}"
+
+
+def test_dsymv_n3_hand_verified():
+    A = jnp.array([[3.0, 1.5, -0.5],
+                   [1.5, 2.0,  0.7],
+                   [-0.5, 0.7, 4.0]])
+    v = jnp.array([2.0, -1.0, 3.0])
+
+    ref = kh.naive_dsymv(A, v)
+    opt = kh.khal_dsymv(A, v)
+
+    assert abs(float(ref[0]) - 3.0) < 1e-10
+    assert abs(float(ref[1]) - 3.1) < 1e-10
+    assert abs(float(ref[2]) - 10.3) < 1e-10
+    assert kh.max_abs_err(ref, opt) < 1e-9

khalgebra-0.1.0/tests/test_riemann.py

@@ -0,0 +1,47 @@
+import pytest
+import jax.numpy as jnp
+import khalgebra as kh
+
+
+@pytest.mark.parametrize("n", [2, 3, 4, 5, 6])
+def test_riemann_correctness(n):
+    R = kh.make_riemann_tensor(n)
+    u = kh.make_vec(n, seed=1)
+    v = kh.make_vec(n, seed=2)
+
+    ref = kh.naive_riemann_contract(R, u, v)
+    opt = kh.khal_riemann_contract(R, u, v)
+
+    r_max = float(jnp.max(jnp.abs(R)))
+    assert r_max > 0.01, f"n={n}: tensor is degenerate (|R|_max={r_max:.4f})"
+
+    err = kh.max_abs_err(ref, opt)
+    assert err < 1e-12, f"n={n}: err={err:.2e}"
+
+
+@pytest.mark.parametrize("n", [2, 3, 4, 5, 6])
+def test_riemann_precomputed_components(n):
+    R = kh.make_riemann_tensor(n)
+    u = kh.make_vec(n, seed=1)
+    v = kh.make_vec(n, seed=2)
+    comps = kh.build_riemann_components(n)
+
+    with_comps    = kh.khal_riemann_contract(R, u, v, comps)
+    without_comps = kh.khal_riemann_contract(R, u, v)
+
+    assert kh.max_abs_err(with_comps, without_comps) < 1e-15
+
+
+def test_riemann_n4_spot_check():
+    """Spot-check three specific (b,d) entries for n=4."""
+    n = 4
+    R = kh.make_riemann_tensor(n)
+    u = kh.make_vec(n, seed=1)
+    v = kh.make_vec(n, seed=2)
+
+    ref = kh.naive_riemann_contract(R, u, v)
+    opt = kh.khal_riemann_contract(R, u, v)
+
+    for b, d in [(0, 1), (2, 3), (1, 3)]:
+        err = abs(float(opt[b, d]) - float(ref[b, d]))
+        assert err < 1e-12, f"(b,d)=({b},{d}): err={err:.2e}"

khalgebra-0.1.0/tests/test_sym22.py

@@ -0,0 +1,22 @@
+import khalgebra as kh
+from khalgebra._types import _lcg_sequence
+
+
+def test_sym22_fixed_input():
+    """A=[[1,2],[2,3]], B=[[4,5],[6,7]] → C=[[16,19],[26,31]]"""
+    c00, c01, c10, c11 = kh.khal_sym22(1, 2, 3, 4, 5, 6, 7)
+    assert float(c00) == 16.0
+    assert float(c01) == 19.0
+    assert float(c10) == 26.0
+    assert float(c11) == 31.0
+
+
+def test_sym22_50_random_inputs():
+    vals = _lcg_sequence(7 * 50, seed=99)
+    for i in range(50):
+        a, b, c, p, q, r, s = vals[i*7:(i+1)*7]
+        ref = kh.naive_sym22(a, b, c, p, q, r, s)
+        opt = kh.khal_sym22(a, b, c, p, q, r, s)
+        for k in range(4):
+            err = abs(float(opt[k]) - float(ref[k]))
+            assert err < 1e-13, f"input {i} entry {k}: err={err:.2e}"