pycauset 0.6.2.dev15__tar.gz → 0.6.2.dev16__tar.gz

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/.gitignore

@@ -133,7 +133,7 @@ tools/test_release_locally.sh
 build_*/
 
 # --- Local rebuild/scratch artifacts ---
-third_party/openblas_src/
+third_party/
 *.log
 *.release_bak
 /cpp_diff.txt

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/CMakeLists.txt

@@ -486,8 +486,11 @@ if(ENABLE_CUDA)
     check_language(CUDA)
 
     if(CMAKE_CUDA_COMPILER)
-        # Target the native architecture of the build machine (supports Pascal 6.1 on CUDA 12)
-        set(CMAKE_CUDA_ARCHITECTURES "native")
+        # Default to the build machine's GPU ("native"), but allow distribution
+        # builds (CI) to override with a list of target compute capabilities
+        # (e.g. "61;70;75;80;86;89") so the wheel runs on a range of GPUs and
+        # does not require a GPU on the builder.
+        set(CMAKE_CUDA_ARCHITECTURES "native" CACHE STRING "CUDA compute capabilities to target")
         enable_language(CUDA)
         find_package(CUDAToolkit REQUIRED)
         

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pycauset
-Version: 0.6.2.dev15
+Version: 0.6.2.dev16
 Summary: High-performance Causal Set matrix operations using memory-mapped files
 Author: Bror Hjemgaard
 License: MIT
@@ -25,6 +25,10 @@ Requires-Dist: ruff; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: psutil; extra == "dev"
+Provides-Extra: gpu
+Requires-Dist: nvidia-cuda-runtime-cu12>=12.6; extra == "gpu"
+Requires-Dist: nvidia-cublas-cu12>=12.6; extra == "gpu"
+Requires-Dist: nvidia-cusolver-cu12>=12.6; extra == "gpu"
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -137,6 +141,25 @@ cd pycauset
 pip install .
 ```
 
+### GPU acceleration (optional)
+
+PyCauset ships **CPU-only by default** to keep the install small. The GPU backend is a
+one-command opt-in:
+
+```bash
+pip install "pycauset[gpu]"
+```
+
+That pulls the CUDA runtime (~500 MB) and enables the `pycauset_cuda` backend. Requirements:
+
+- NVIDIA GPU, Compute Capability 6.0+ (Pascal or newer)
+- Linux or Windows (macOS has no NVIDIA CUDA)
+
+If you run on a machine with an NVIDIA GPU but haven't installed the GPU backend, PyCauset
+prints a one-line reminder at import telling you the exact command (silence it with
+`PYCAUSET_GPU_HINT=0`). CPU remains the correct, fully-supported default — the GPU backend
+is used automatically only when the cost model predicts it will be faster.
+
 ## Status
 
 Pre-alpha. Release 1 (v0.6.1, the Foundation Release) shipped the numerical core — matrices, storage, and linear algebra — CPU-only (GPU parity is deferred). Release 2 (the Physics Release) adds the physics suite — arbitrary-dimension and curved spacetimes, fields, and the Sorkin-Johnston vacuum — and folds in the deferred optimization program. The current plan is tracked in the documentation.

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/README.md

@@ -108,6 +108,25 @@ cd pycauset
 pip install .
 ```
 
+### GPU acceleration (optional)
+
+PyCauset ships **CPU-only by default** to keep the install small. The GPU backend is a
+one-command opt-in:
+
+```bash
+pip install "pycauset[gpu]"
+```
+
+That pulls the CUDA runtime (~500 MB) and enables the `pycauset_cuda` backend. Requirements:
+
+- NVIDIA GPU, Compute Capability 6.0+ (Pascal or newer)
+- Linux or Windows (macOS has no NVIDIA CUDA)
+
+If you run on a machine with an NVIDIA GPU but haven't installed the GPU backend, PyCauset
+prints a one-line reminder at import telling you the exact command (silence it with
+`PYCAUSET_GPU_HINT=0`). CPU remains the correct, fully-supported default — the GPU backend
+is used automatically only when the cost model predicts it will be faster.
+
 ## Status
 
 Pre-alpha. Release 1 (v0.6.1, the Foundation Release) shipped the numerical core — matrices, storage, and linear algebra — CPU-only (GPU parity is deferred). Release 2 (the Physics Release) adds the physics suite — arbitrary-dimension and curved spacetimes, fields, and the Sorkin-Johnston vacuum — and folds in the deferred optimization program. The current plan is tracked in the documentation.

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/documentation/docs/functions/pycauset.cuda.is_available.md

@@ -10,6 +10,18 @@ This is **not** a hardware probe. It reports whether the CUDA backend is
 currently active (plugin loaded + device created). If you need to attempt
 activation, call `pycauset.cuda.enable()` first.
 
+## Installing the GPU backend
+
+The GPU backend is opt-in. The base install is CPU-only; add the CUDA runtime
+(~500 MB) with:
+
+```bash
+pip install "pycauset[gpu]"
+```
+
+On a machine with an NVIDIA GPU but no GPU backend, `import pycauset` prints a
+one-line reminder with this command (silence it with `PYCAUSET_GPU_HINT=0`).
+
 ## Returns
 
 *   **bool**: Whether the CUDA backend is active.

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/documentation/internals/plans/TODO.md

@@ -16,8 +16,15 @@ status lives in `R1_EXECUTION.md`.
 - [ ] API lock: mark `_internal` as private (`__all__` is already curated)
 
 ### Known issues (bugs, fix post-R1, do not forget)
-- **Teardown hang in `release_tracked_matrices()`** (mitigated by skipping native
-  `close()` during interpreter finalization; root cause unfixed).
+- **Teardown hang in `release_tracked_matrices()`** — root-caused and fixed
+  (R2_HARDEN, 2026-08): the `MemoryGovernor`/`ComputeContext`/`ThreadPool`/
+  `OpRegistry` singletons were Meyers statics whose destruction order is undefined
+  during interpreter finalization, so `PersistentObject` destructors and `close()`
+  calling `instance()` could hang or crash. They are now heap singletons that are
+  intentionally never destroyed (destructors are empty or the OS reclaims the
+  resources at process exit), eliminating the whole class of teardown-ordering
+  hazards. The `release_tracked_matrices()` finalization skip is retained as
+  defense-in-depth (the OS reclaims mappings anyway).
 - **Dead code / deprecated-feature sweep** — in progress (R2_HARDEN): removed the
   import-time-skipped `test_pauli_jordan_spectrum.py` (referenced the removed
   `.eigenvalues()` API) and the stale `*.dll.stale` build artifacts. `test_skew.py`

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/documentation/project/plans/R2_ROADMAP.md

@@ -593,7 +593,7 @@ and recomputes; round-trip correctness pinned by test.
 
 ### R2_HARDEN — Robustness + Polish Backlog
 
-Status: - [ ] (in progress: dead-code/deprecated-feature sweep started — removed the import-time-skipped `test_pauli_jordan_spectrum.py` (removed `.eigenvalues()` API) and stale `*.dll.stale` artifacts; `test_skew{,_comprehensive}.py` re-enabled after the R2_CATALOG skew eigensystem landed. Native concurrency thread-safety proven on Windows (`test_threaded_io_stress` re-enabled; 800+ concurrent construction/save/load/delete ops clean — the segfaults were the governor dangling-pointer bug, fixed). Ruff cleanup started — import-sorting (`I001`) auto-fixed across `python/pycauset`; remaining `E501`/`UP006`/`UP045` are mechanical follow-ups. Remaining: teardown-hang root cause, `__init__.py` slimming, CMake warning audit, macOS wheel portability)
+Status: - [ ] (in progress: dead-code/deprecated-feature sweep started — removed the import-time-skipped `test_pauli_jordan_spectrum.py` (removed `.eigenvalues()` API) and stale `*.dll.stale` artifacts; `test_skew{,_comprehensive}.py` re-enabled after the R2_CATALOG skew eigensystem landed. Native concurrency thread-safety proven on Windows (`test_threaded_io_stress` re-enabled; 800+ concurrent construction/save/load/delete ops clean — the segfaults were the governor dangling-pointer bug, fixed). Ruff cleanup started — import-sorting (`I001`) auto-fixed across `python/pycauset`; remaining `E501`/`UP006`/`UP045` are mechanical follow-ups. Teardown-hang root cause fixed (2026-08): the `MemoryGovernor`/`ComputeContext`/`ThreadPool`/`OpRegistry` singletons were Meyers statics with undefined destruction order during finalization; converted to intentionally-leaked heap singletons so object destructors can always reach them. Remaining: `__init__.py` slimming, CMake warning audit, macOS wheel portability)
 
 Goal: close the post-R1 bug/polish backlog tracked in `documentation/internals/plans/TODO.md` so R2
 ships professionally.

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/pyproject.toml

@@ -41,6 +41,20 @@ dev = [
     "pytest",
     "psutil",
 ]
+# CUDA runtime for the optional GPU backend (`pycauset_cuda`).
+# These are NVIDIA's official redistributable pip packages (the same mechanism
+# PyTorch/TensorFlow use), so `pip install pycauset[gpu]` downloads the runtime
+# DLLs automatically instead of requiring a full CUDA Toolkit install.
+#
+# The CUDA plugin links cudart/cublas/cusolver only (see
+# CudaDevice.cu + CMakeLists.txt), hence exactly these three. Keep the floor at
+# the CUDA minor the plugin is compiled against (12.6); the runtime is
+# forward-compatible within the 12.x major.
+gpu = [
+    "nvidia-cuda-runtime-cu12>=12.6",
+    "nvidia-cublas-cu12>=12.6",
+    "nvidia-cusolver-cu12>=12.6",
+]
 
 [project.urls]
 Homepage = "https://github.com/BrorH/pycauset"

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/python/pycauset/__init__.py

@@ -97,6 +97,25 @@ try:
 except Exception:
     pass
 
+# One-time GPU install hint. PyCauset ships CPU-only by default; the GPU backend
+# is opt-in via `pip install pycauset[gpu]`. On a machine with an NVIDIA GPU but
+# no GPU backend, emit a single clear install hint (silence with
+# PYCAUSET_GPU_HINT=0). Never blocks or breaks import.
+try:
+    from ._internal.gpu_hint import emit_gpu_install_hint
+
+    def _gpu_backend_available() -> bool:
+        try:
+            from . import _pycauset_cuda as _cuda_mod
+
+            return bool(_cuda_mod.is_available())
+        except Exception:
+            return False
+
+    emit_gpu_install_hint(backend_available=_gpu_backend_available)
+except Exception:
+    pass
+
 # Import modules that depend on the native extension after it is loaded.
 from . import field as field
 from . import spacetime as spacetime

pycauset-0.6.2.dev16/python/pycauset/_internal/gpu_hint.py

@@ -0,0 +1,61 @@
+"""One-time GPU-install hint.
+
+PyCauset ships CPU-only by default; the optional GPU backend (and its ~500 MB of
+CUDA runtime) is installed separately via ``pip install pycauset[gpu]``.
+
+To make the GPU backend *impossible to miss* without being annoying, we detect an
+NVIDIA GPU through the *driver* API (``libcuda``/``nvcuda`` — present with any
+NVIDIA GPU, no CUDA runtime required) and, when a GPU is present but the backend
+is not installed, emit a single clear hint pointing at the one-command install.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+from typing import Callable
+
+
+def _driver_has_nvidia_gpu() -> bool:
+    """True if an NVIDIA GPU is present, probed via the driver API (no CUDA runtime needed)."""
+    try:
+        if sys.platform == "win32":
+            lib = ctypes.WinDLL("nvcuda.dll")
+        else:
+            # Linux (macOS has no NVIDIA CUDA).
+            lib = ctypes.CDLL("libcuda.so.1")
+        lib.cuInit.argtypes = [ctypes.c_uint]
+        lib.cuInit.restype = ctypes.c_int
+        if lib.cuInit(0) != 0:
+            return False
+        count = ctypes.c_int(0)
+        lib.cuDeviceGetCount.argtypes = [ctypes.POINTER(ctypes.c_int)]
+        lib.cuDeviceGetCount.restype = ctypes.c_int
+        if lib.cuDeviceGetCount(ctypes.byref(count)) != 0:
+            return False
+        return count.value > 0
+    except Exception:
+        return False
+
+
+def emit_gpu_install_hint(*, backend_available: Callable[[], bool]) -> None:
+    """Emit a single install hint when a GPU is present but the backend is not installed."""
+    if os.environ.get("PYCAUSET_GPU_HINT", "1").strip() in ("0", "false", "False", "no"):
+        return
+
+    try:
+        if backend_available():
+            return  # already installed — nothing to say
+        if not _driver_has_nvidia_gpu():
+            return  # no NVIDIA GPU — stay quiet (CPU user)
+    except Exception:
+        return
+
+    print(
+        "[PyCauset] NVIDIA GPU detected, but the GPU backend is not installed "
+        "(running on CPU).\n"
+        "  Install it with:  pip install \"pycauset[gpu]\"\n"
+        "  (adds ~500 MB of CUDA runtime; set PYCAUSET_GPU_HINT=0 to silence this message)",
+        file=sys.stderr,
+    )

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/python/pycauset/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.6.2.dev15'
-__version_tuple__ = version_tuple = (0, 6, 2, 'dev15')
+__version__ = version = '0.6.2.dev16'
+__version_tuple__ = version_tuple = (0, 6, 2, 'dev16')
 
-__commit_id__ = commit_id = 'g18ee7e7be'
+__commit_id__ = commit_id = 'g402443570'

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/src/compute/ComputeContext.cpp

@@ -31,8 +31,13 @@ struct ConstructionScope {
 };
 
 ComputeContext& ComputeContext::instance() {
-    static ComputeContext ctx;
-    return ctx;
+    // Intentionally leaked: object teardown (MemoryMapper::close_file, CudaDevice
+    // destruction) can reach the context during interpreter finalization, where a
+    // Meyers singleton's destruction order is undefined. Leaking it also skips the
+    // CUDA handle teardown at exit (cublas/cusolver destroy), which the driver
+    // reclaims on process exit anyway — removing a second teardown-hang source.
+    static ComputeContext* ctx = new ComputeContext();
+    return *ctx;
 }
 
 bool compute_context_is_constructing() {

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/src/core/MemoryGovernor.cpp

@@ -21,8 +21,13 @@ namespace pycauset {
 namespace core {
 
 MemoryGovernor& MemoryGovernor::instance() {
-    static MemoryGovernor instance;
-    return instance;
+    // Intentionally leaked: PersistentObject destructors and close() call back
+    // into the governor during interpreter finalization, where the static
+    // destruction order of a Meyers singleton is undefined. A heap singleton that
+    // is never destroyed removes that entire class of teardown hang/crash (the
+    // destructor is empty anyway; the OS reclaims the few bytes at process exit).
+    static MemoryGovernor* instance = new MemoryGovernor();
+    return *instance;
 }
 
 MemoryGovernor::MemoryGovernor() {

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/src/core/OpRegistration.cpp

@@ -3,8 +3,10 @@
 namespace pycauset {
 
 OpRegistry& OpRegistry::instance() {
-    static OpRegistry reg;
-    return reg;
+    // Intentionally leaked (see the other ::instance() singletons): avoids any
+    // static-destruction-order hazard during interpreter finalization.
+    static OpRegistry* reg = new OpRegistry();
+    return *reg;
 }
 
 void OpRegistry::register_op(const OpContract& contract) {

{pycauset-0.6.2.dev15 → pycauset-0.6.2.dev16}/src/core/ParallelUtils.cpp

@@ -14,8 +14,11 @@ size_t ThreadPool::get_num_threads() {
 }
 
 ThreadPool& ThreadPool::instance() {
-    static ThreadPool pool;
-    return pool;
+    // Intentionally leaked: the destructor joins workers, which can block during
+    // interpreter finalization (workers may be mid-task or blocked on I/O). Never
+    // destroying the pool avoids that teardown hang; OS reclaims the threads.
+    static ThreadPool* pool = new ThreadPool();
+    return *pool;
 }
 
 ThreadPool::ThreadPool(size_t threads) : stop(false) {