pycauset 0.6.2.dev1__tar.gz → 0.6.2.dev8__tar.gz

{pycauset-0.6.2.dev1 → pycauset-0.6.2.dev8}/.github/workflows/publish.yml

@@ -16,6 +16,7 @@ jobs:
     name: Build wheels on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-15]
 

{pycauset-0.6.2.dev1 → pycauset-0.6.2.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pycauset
-Version: 0.6.2.dev1
+Version: 0.6.2.dev8
 Summary: High-performance Causal Set matrix operations using memory-mapped files
 Author: Bror Hjemgaard
 License: MIT

pycauset-0.6.2.dev8/benchmarks/r2_parity.py

@@ -0,0 +1,108 @@
+"""R2_PERF — canonical compute-parity benchmark (PyCauset vs NumPy, dense float64).
+
+Reproduces with::
+
+    python benchmarks/r2_parity.py
+
+For each op, reports the ratio ``numpy_time / pycauset_time``. A ratio >= 1.0
+means PyCauset is faster; >= 0.90 means "at parity" (the R2_PERF bar). Sizes are
+chosen large enough that Python-dispatch overhead is amortized. This is the single
+canonical gate — it supersedes the older ad-hoc benchmark scripts.
+"""
+
+from __future__ import annotations
+
+import time
+
+import numpy as np
+
+import pycauset as pc
+
+N = 1024  # matrix ops
+NV = 1_000_000  # vector/memory-bound ops
+
+
+def best_time(fn, repeats=3):
+    best = float("inf")
+    for _ in range(repeats):
+        t0 = time.perf_counter()
+        fn()
+        best = min(best, time.perf_counter() - t0)
+    return best
+
+
+def main() -> None:
+    rng = np.random.default_rng(0)
+    A_np = rng.standard_normal((N, N))
+    B_np = rng.standard_normal((N, N))
+    b_np = rng.standard_normal(N)
+    v_np = rng.standard_normal(NV)
+
+    A = pc.matrix(A_np)
+    B = pc.matrix(B_np)
+    b = pc.vector(b_np)
+    v = pc.vector(v_np)
+
+    # SPD matrix for solve/invert/eigh/det; scaled so det does not overflow.
+    spd_np = (A_np @ A_np.T) / N + np.eye(N)
+    spd = pc.matrix(spd_np)
+
+    print(f"{'op':<14} {'numpy(s)':>12} {'pycauset(s)':>12} {'ratio':>8}  verdict")
+    print("-" * 62)
+    rows = []
+
+    def _materialize(x):
+        try:
+            return np.asarray(x)
+        except Exception:
+            return x
+
+    def run(name, np_fn, pc_fn):
+        np_t = best_time(np_fn)
+        # Force materialization so lazy PyCauset results are actually computed.
+        pc_t = best_time(lambda: _materialize(pc_fn()))
+        ratio = np_t / pc_t if pc_t > 0 else float("inf")
+        verdict = "PASS" if ratio >= 0.90 else "FAIL"
+        rows.append((name, ratio, verdict))
+        print(f"{name:<14} {np_t:>12.4f} {pc_t:>12.4f} {ratio:>8.2f}x  {verdict}")
+
+    # invert() and determinant() memoize their results (a real PyCauset feature:
+    # the inverse lives in `_cached_inverse`, the determinant in the derived-
+    # property store). NumPy recomputes every call, so a warm-cache comparison
+    # would measure a cache hit against a fresh factorization — not parity. Clear
+    # the derived caches before each timed call so both sides recompute.
+    def _clear_derived_caches(m):
+        try:
+            from pycauset._internal.properties import _invalidate_cached_derived
+
+            _invalidate_cached_derived(m)
+        except Exception:
+            if hasattr(m, "_cached_inverse"):
+                del m._cached_inverse
+
+    def _pc_invert():
+        _clear_derived_caches(spd)
+        return pc.invert(spd)
+
+    def _pc_determinant():
+        _clear_derived_caches(spd)
+        return pc.determinant(spd)
+
+    run("matmul", lambda: A_np @ B_np, lambda: pc.matmul(A, B))
+    run("solve", lambda: np.linalg.solve(spd_np, b_np), lambda: pc.solve(spd, b))
+    run("invert", lambda: np.linalg.inv(spd_np), _pc_invert)
+    run("dot", lambda: np.dot(v_np, v_np), lambda: pc.dot(v, v))
+    run("add", lambda: A_np + B_np, lambda: A + B)
+    run("multiply", lambda: A_np * B_np, lambda: A * B)
+    run("determinant", lambda: np.linalg.det(spd_np), _pc_determinant)
+    run("eigh", lambda: np.linalg.eigh(spd_np), lambda: pc.eigh(spd))
+
+    print("-" * 62)
+    fails = [r for r in rows if r[2] == "FAIL"]
+    print(f"{len(rows) - len(fails)}/{len(rows)} ops at parity (>= 0.90x).")
+    if fails:
+        print("Below parity:", ", ".join(f"{n} ({r:.2f}x)" for n, r, _ in fails))
+
+
+if __name__ == "__main__":
+    main()

pycauset-0.6.2.dev8/build_openblas.ps1

@@ -0,0 +1,57 @@
+$ErrorActionPreference = "Stop"
+$root = "C:\Users\ireal\Documents\Projects\pycauset"
+$work = "$root\third_party\openblas_src"
+$ver = "0.3.28"
+$zip = "$root\third_party\openblas-$ver.zip"
+
+New-Item -ItemType Directory -Force -Path "$root\third_party" | Out-Null
+
+# Download OpenBLAS source if not present
+if (-not (Test-Path $zip)) {
+    Write-Host "Downloading OpenBLAS $ver source..."
+    Invoke-WebRequest -Uri "https://github.com/OpenMathLib/OpenBLAS/archive/v$ver.zip" -OutFile $zip -UseBasicParsing
+}
+
+if (-not (Test-Path "$work\Makefile")) {
+    Write-Host "Extracting..."
+    Expand-Archive -Path $zip -DestinationPath "$root\third_party" -Force
+    # Expand-Archive creates OpenBLAS-0.3.28; rename to openblas_src
+    $extracted = "$root\third_party\OpenBLAS-$ver"
+    if (Test-Path $extracted) {
+        if (Test-Path $work) { Remove-Item $work -Recurse -Force }
+        Rename-Item $extracted $work
+    }
+}
+
+# Build with MinGW: DYNAMIC_ARCH (Haswell/Skylake/Zen), threaded, LP64.
+# Combine WinLibs (gcc/gfortran/make/binutils) with Git's POSIX utils (sh/uname/sed).
+Write-Host "Building OpenBLAS (DYNAMIC_ARCH=1 USE_THREAD=1)... this takes 10-20 min."
+Set-Location $work
+$winlibs = "C:\Users\ireal\AppData\Local\Microsoft\WinGet\Packages\BrechtSanders.WinLibs.POSIX.UCRT_Microsoft.Winget.Source_8wekyb3d8bbwe\mingw64\bin"
+$gitposix = "C:\Program Files\Git\usr\bin"
+$env:PATH = "$winlibs;$gitposix;$env:PATH"
+
+# Use `make` if present, else mingw32-make
+$makeExe = "mingw32-make"
+$makeArgs = @("DYNAMIC_ARCH=1","USE_THREAD=1","NUM_THREADS=24","BINARY=64","NO_SHARED=0","NO_STATIC=1","NO_LAPACKE=0","NO_CBLAS=0","CC=gcc","FC=gfortran","HOSTCC=gcc")
+# Run via cmd /c so PowerShell does not treat mingw32-make's stderr chatter
+# (e.g. "ar: creating ...") as a terminating error.
+$argStr = ($makeArgs -join " ")
+cmd /c "`"$winlibs\$makeExe`" $argStr > `"$root\openblas_build.log`" 2>&1"
+Write-Host "make exit code: $LASTEXITCODE"
+
+Write-Host "Build complete. Output files:"
+Get-ChildItem "$work\libopenblas*.dll","$work\*.dll","$work\exports\*.def" -ErrorAction SilentlyContinue | Select-Object FullName, Length | Out-String | Write-Host
+
+# Generate an MSVC-compatible import lib
+$dll = Get-ChildItem "$work\libopenblas.dll" -ErrorAction SilentlyContinue | Select-Object -First 1
+if ($dll) {
+    Write-Host "Generating import lib from $($dll.FullName)..."
+    & gendef $dll.FullName 2>&1 | Out-Host
+    $def = "$work\libopenblas.def"
+    if (Test-Path $def) {
+        & dlltool -d $def -l "$work\libopenblas_msvc.lib" -D libopenblas.dll 2>&1 | Out-Host
+        Write-Host "Import lib: $work\libopenblas_msvc.lib"
+    }
+}
+Write-Host "DONE"

pycauset-0.6.2.dev8/documentation/dev/R2_PERF_FINDINGS.md

@@ -0,0 +1,71 @@
+# R2_PERF — parity findings (R2.2)
+
+Measured with `python benchmarks/r2_parity.py` (dense float64, n=1024 matrices,
+best-of-3, PyCauset result forced through `np.asarray`; `invert`/`determinant`
+clear their derived caches before timing so both sides recompute). The ratio is
+`numpy_time / pycauset_time`; the R2_PERF bar is **≥ 0.90×**.
+
+Current state (threaded DYNAMIC_ARCH OpenBLAS, `OPENBLAS_NUM_THREADS=8` default,
+GEMM bumps to 20 threads internally):
+
+| op | ratio | verdict |
+| :-- | --: | :-- |
+| add | ~1.1–1.2× | PASS |
+| solve | ~0.96× | PASS |
+| invert | ~1.1× | PASS |
+| dot | ~2× | PASS |
+| multiply | ~0.93× | PASS (marginal) |
+| determinant | ~1.24× | PASS |
+| eigh | ~0.98× | PASS |
+| matmul | ~0.87× | FAIL (marginal) |
+
+7/8 ops are at or above parity. `matmul` hovers just under 0.90× (~0.0071 s vs
+NumPy ~0.0063 s) and `multiply` just above it (~0.93×); both flap across the 0.90
+line run-to-run (CPU frequency/thermal noise).
+
+## What landed in R2.2
+
+1. **`determinant` → LAPACK** — `CpuSolver::determinant` uses `LAPACKE_dgetrf`/
+   `zgetrf` (NumPy's own backend) instead of Eigen's single-threaded `PartialPivLU`.
+2. **Fair `invert`/`determinant` benchmarking** — the benchmark clears the derived
+   caches (`_invalidate_cached_derived`) before timing.
+3. **`add` flakiness root-caused** — a stale installed wheel merged into a namespace
+   package and `import_native_extension()` used `next(iter(pkg.__path__))` (filesystem-
+   dependent order on Windows), so ~50% of processes loaded a stale `_pycauset.pyd`.
+   Fixed by loading from the package's `__file__` directory (`native.py`).
+4. **AVX2 f64 sub/mul/div kernels + full-span hardening** — elementwise `subtract`/
+   `multiply`/`divide` now route through AVX2 with strict full-span guards.
+5. **`matmul` OpenBLAS rebuilt** — the CMake fallback downloaded a *generic single-core*
+   0.3.26 binary; rebuilt 0.3.28 with `DYNAMIC_ARCH=1 USE_THREAD=1` (Haswell kernels),
+   relinked, and bundled the MinGW runtime DLLs. `build_openblas.ps1` documents it.
+6. **`OPENBLAS_NUM_THREADS` default 8** — the threaded OpenBLAS uses one pool for BLAS
+   and LAPACK; 20 threads regresses small LAPACK (invert/determinant) via SMP sync
+   overhead, so `pycauset` pins 8 at import and the matmul GEMM temporarily bumps to 20.
+
+## The two memory/perf root fixes (biggest wins)
+
+- **`:memory:` backing switched to `VirtualAlloc`** (`MemoryMapper`) instead of a
+  pagefile-backed section (`CreateFileMappingA(INVALID_HANDLE_VALUE)`). The pagefile
+  path commits a page from the paging file on every first write, costing several ms
+  per 8MB result and dominating small elementwise ops. This single change took
+  `add` 0.88× → ~1.1× and `multiply` 0.72× → ~0.93×.
+- **CPU dgemm no longer pins operands** (`CpuSolver::attempt_direct_path`) — `VirtualLock`
+  is a GPU-DMA optimization and pure overhead for CPU `dgemm`.
+
+## Remaining gap: `matmul` (~0.87×)
+
+The raw `cblas_dgemm` is already **faster than NumPy** (0.0044 s vs NumPy's 0.0060 s
+at the same 20 threads). The residual is per-call wrapper cost on top of the kernel:
+
+| component | time |
+| :-- | --: |
+| raw `cblas_dgemm` (warm buffer, 20 threads) | ~0.0044 s |
+| fresh 8MB result (VirtualAlloc + first-write faults) | ~1.6 ms |
+| C++ `create_matrix` + MemoryGovernor + dispatch | ~0.4 ms |
+| Python `_ops.matmul` (IO planning, streaming checks, inline imports) | ~0.7 ms |
+| **total** | **~0.0071 s** |
+
+NumPy's `@` skips most of the Python/IO-planning layer. Fully closing the 0.03× gap
+means trimming the Python `_ops.matmul` IO-planning/inline-import path (or routing the
+native `matmul` through the eager operator), which trades away the streaming/observability
+layer for the hot dense case. Tracked against `R2_PERF` in `R2_ROADMAP.md`.

{pycauset-0.6.2.dev1 → pycauset-0.6.2.dev8}/documentation/docs/functions/index.md

@@ -1,5 +1,12 @@
 # Functions
 
+* **[[docs/functions/pycauset.field.md|pycauset.field]]**
+* **[[docs/functions/pycauset.spacetime.create.md|spacetime.create]]**
+* **[[docs/functions/pycauset.spacetime.register.md|spacetime.register]]**
+* **[[docs/functions/pycauset.spacetime.export_python.md|spacetime.export_python]]**
+* **[[docs/functions/pycauset.spacetime.get_registry.md|spacetime.get_registry]]**
+* **[[docs/functions/pycauset.synthetic.md|pycauset.synthetic]]**
+* **[[docs/functions/pycauset.show.md|pycauset.show]]**
 * **[[docs/functions/pycauset.I.md|pycauset.I]]**
 * **[[docs/functions/pycauset.identity.md|pycauset.identity]]**
 * **[[docs/functions/pycauset.diagonal.md|pycauset.diagonal]]**
@@ -54,6 +61,7 @@
 * **[[docs/functions/pycauset.eig.md|eig]]**
 * **[[docs/functions/pycauset.eigvals.md|eigvals]]**
 * **[[docs/functions/pycauset.eigvals_arnoldi.md|eigvals_arnoldi]]**
+* **[[docs/functions/pycauset.eigvals_skew.md|eigvals_skew]]**
 * **[[docs/functions/pycauset.load.md|load]]**
 * **[[docs/functions/pycauset.load_matrix.md|load_matrix]]**
 * **[[docs/functions/pycauset.load_npy.md|load_npy]]**

pycauset-0.6.2.dev8/documentation/docs/functions/pycauset.eigvals_skew.md

@@ -0,0 +1,46 @@
+# pycauset.eigvals_skew
+
+~~~python
+pycauset.eigvals_skew(a, k)
+~~~
+
+Compute the top-$k$ eigenvalues (by magnitude) of a real skew-symmetric matrix.
+
+A real skew-symmetric matrix satisfies $A = -A^\top$. Its eigenvalues are purely
+imaginary and come in $\pm i\lambda$ pairs, with one zero eigenvalue when the
+dimension is odd.
+
+## Parameters
+
+* **a**: Input square matrix (real, skew-symmetric).
+* **k**: Number of eigenvalues to return.
+
+## Returns
+
+* **VectorBase**: Complex eigenvalues sorted by descending magnitude, of length
+  `min(k, n)`. Each entry has a negligible real part (machine precision) and an
+  imaginary part of the form $\pm\lambda$.
+
+## Notes
+
+* Uses the native backend when available, otherwise falls back to NumPy's general
+  eigensolver.
+* Requesting `k > n` returns at most `n` eigenvalues.
+* A dedicated Paige–Van Loan tridiagonalization (the asymptotically faster
+  $O(n^2)$-ish algorithm for skew matrices) is planned but not yet implemented;
+  the current native path uses the general LAPACK `dgeev` solver.
+
+## Example
+
+~~~python
+import numpy as np
+import pycauset as pc
+
+rng = np.random.default_rng(0)
+M = rng.random((8, 8))
+A = M - M.T          # skew-symmetric
+
+evals = pc.eigvals_skew(pc.matrix(A), 3)   # top-3 imaginary eigenvalues
+for i in range(evals.size()):
+    print(evals.get(i))                     # e.g. 0+1.23j, 0-1.23j, 0+0.91j
+~~~