pycauset 0.4.18.dev25__tar.gz → 0.5.1.dev2__tar.gz

{pycauset-0.4.18.dev25 → pycauset-0.5.1.dev2}/CMakeLists.txt

@@ -505,6 +505,14 @@ if(ENABLE_CUDA)
             $<$<COMPILE_LANGUAGE:CUDA>:--diag_suppress=177>
         )
         
+        # --- Python Bindings for CUDA (Internal) ---
+        # Only meaningful if CUDA is enabled. This module provides discovery functions.
+        python_add_library(_pycauset_cuda MODULE src/bindings/bind_cuda.cpp)
+        target_include_directories(_pycauset_cuda PRIVATE include)
+        target_link_libraries(_pycauset_cuda PRIVATE pycauset_cuda pybind11::module pycauset_core)
+        set_target_properties(_pycauset_cuda PROPERTIES WINDOWS_EXPORT_ALL_SYMBOLS ON)
+        install(TARGETS _pycauset_cuda DESTINATION pycauset)
+
         install(TARGETS pycauset_cuda DESTINATION pycauset)
     else()
         message(STATUS "CUDA not found. Skipping pycauset_cuda accelerator.")

{pycauset-0.4.18.dev25 → pycauset-0.5.1.dev2}/PKG-INFO

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

{pycauset-0.4.18.dev25 → pycauset-0.5.1.dev2}/documentation/guides/Storage and Memory.md

@@ -61,9 +61,36 @@ This specific format enables two user-facing behaviors:
 1) **Gigantic matrices actually work:** the payload lives on disk and is paged in as needed.
 2) **Some operations are instant:** things like transpose or scaling can be represented by changing metadata (no rewrite of the large payload).
 
-Also, even if you *haven’t manually saved anything yet*, PyCauset still needs a place to put the payload bytes for big matrices.
+## Semantic Properties (Metadata)
 
-So most large matrices you create during a session are backed by files under the storage root directory (by default, `.pycauset/`). Your OS then treats those files like disk-backed working memory: it keeps “hot” pages in RAM automatically and reloads them on demand.
+In addition to physical metadata (shape/dtype), Release 1 allows attaching **Semantic Properties**. These are asserted facts about the matrix that are "gospel" (authoritative) and can drastically speed up computations.
+
+### What `properties` is
+
+- `obj.properties` is a mapping (`str` keys → typed values) exposed on every matrix/vector.
+- It stores **gospel assertions** (e.g., `is_upper_triangular=True`) which the system accepts without truth-validation.
+- It also stores **cached-derived values** (e.g., `determinant`) which are invalidated on mutation.
+
+### Common keys (Release 1)
+
+These keys are treated as **semantic structure claims** (no truth validation):
+- **Structure:** `is_symmetric`, `is_hermitian`, `is_upper_triangular`, `is_lower_triangular`, `is_diagonal`
+- **Identity:** `is_identity` (implies diagonal, symmetric, etc.)
+- **Vector hints:** `is_sorted`, `is_unit_norm`
+
+Example:
+```python
+A = pc.identity(3)
+# Gospel assertion: solver is allowed to treat off-triangle entries as zero.
+A.properties["is_upper_triangular"] = True
+```
+
+### Technical Implementation (Python-Managed)
+
+Currently, the property system is implemented primarily in the **Python layer**:
+- The `properties` dictionary is injected into the native object at runtime (via `python/pycauset/_internal/properties.py`).
+- C++ kernels currently see physical metadata (shape/dtype) but not these semantic properties directly.
+- **Future Integration:** A mechanism to mirror these high-impact flags to C++ (e.g., via a bitmask) is planned so that backend drivers (like the GPU engine) can inspect them without crossing the Python boundary.
 
 ## Where backing files go (temporary storage)
 

pycauset-0.5.1.dev2/documentation/internals/plans/R1_GPU_PLAN.md

@@ -0,0 +1,108 @@
+# R1_GPU Plan: Robust, Cooperative Hardware Acceleration
+
+
+## Executive Summary
+
+The **R1_GPU** node turns the experimental CUDA backend into a robust, "Just Works" acceleration tier.
+
+Crucially, we do **not** invent a new scheduler. We leverage the existing, sophisticated **`AsyncStreamer`** architecture. The goal is to build **Algorithm Drivers**—smart host-side loops that orchestrate the `AsyncStreamer` logic to handle complex operations (Inversion, Eigen) on datasets larger than GPU memory.
+
+## Core Philosophy
+
+1.  **"Just Works" (No Tuning Required)**: The system automatically detects hardware, benchmarks capabilities, and routes operations. Defaults are safe.
+2.  **Streaming First**: We assume data does *not* fit in GPU RAM. All implementations must support tiling via the `MemoryGovernor`.
+3.  **Cooperative Pipelining**: We rarely split a single math op between CPU/GPU (bandwidth contention). Instead, we pipeline: CPU handles logistics (prefetch/pin/format) in parallel with GPU compute.
+
+---
+
+## Deliverables & Phases
+
+### Phase 1: Robust Discovery & "Just Works" Dispatch
+**Goal**: Make the `AutoSolver` smart enough to trust by default.
+
+*   **Hardware Audit & Persistence**:
+    *   Query `cudaGetDeviceProperties`.
+    *   **Micro-benchmark**: Run silent `SGEMM`/`DGEMM` startup test.
+    *   **Cache**: Save results to `~/.pycauset/hardware_profile.json` to skip benchmarks on future runs.
+    *   **Dynamic Pinning Budget**: Implement heuristic `Budget = min(SystemRAM * 0.5, FreeRAM * 0.8, 8GB)` to safely maximize I/O throughput.
+*   **Cost Model Dispatch**:
+    *   Replace fixed size thresholds with a transfer-vs-compute cost equation:
+        $$ T_{gpu} = \frac{\text{Bytes}}{\text{BW}_{pci}} + \frac{\text{Ops}}{\text{FLOPS}_{gpu}} + T_{latency} $$
+*   **Control Surface (Python)**:
+    *   `pycauset.cuda.force_backend(...)`
+    *   `pycauset.cuda.set_pinning_budget(bytes)`
+    *   `pycauset.cuda.benchmark(force=True)`
+*   **Documentation Checkpoint**:
+    *   [ ] Update `internals/Compute Architecture.md`.
+    *   [ ] Add `docs/functions/pycauset.cuda.*` API references.
+    *   [ ] Add `docs/parameters/pinning_budget.md`.
+
+### Phase 2: Streaming Algorithm Drivers (Host-Orchestrated)
+**Goal**: Implement robust out-of-core drivers for complex linear algebra by orchestrating the existing `AsyncStreamer`.
+
+*   **Strategy: Host-Side Orchestration**:
+    *   We reject a generic runtime scheduler.
+    *   We implement **Algorithm-Specific Drivers** (C++ classes) where the CPU executes the algorithm state machine (loops, barriers, dependency checks).
+    *   The Host submits batches of independent tiles to `AsyncStreamer`, which handles the low-level double-buffered prefetch/pin/issue pipeline.
+*   **Deliverables (The "Drivers")**:
+    *   **`MatmulDriver`**: Verification of existing flat streaming for 100GB+ scale.
+    *   **`CholeskyDriver`**: Implement Right-Looking Block Cholesky. Host logic manages dependencies (Diagonal wait -> Panel update -> Trailing update).
+    *   **`ArnoldiDriver`**: Implement Block Arnoldi. Optimizes memory bandwidth by fusing multiple vector updates into blocked operations.
+*   **Documentation Checkpoint**:
+    *   [ ] Update `internals/Streaming Manager.md` to document the Driver pattern. Also document how to create drivers and how they fit into the compute architecture.
+    *   [ ] Update `guides/Performance Guide.md` with a section on "Streaming Constraints".
+
+### Phase 3: Integration (Properties & Heterogeneity)
+**Goal**: Routing respects semantic properties to exploit PyCauset's structural advantage.
+
+*   **Mechanism: Traits-Based Dispatch (Tag Dispatch)**:
+    *   Implement C++20 `MatrixTraits` derived from **R1_PROPERTIES**.
+    *   `AutoSolver` selects kernels based on `BestKernel(Op, Traits)`, decoupling policy from execution.
+*   **Feature: C++ Property Mirroring (Fast Flags)**:
+    *   Since properties are currently Python-only (see `Storage and Memory.md` -> "Technical Implementation"), `AutoSolver` cannot currently see them.
+    *   Add a `uint64_t properties_flags` field to `PersistentObject` in C++.
+    *   Wire the Python setter to update this C++ bitmask in $O(1)$.
+*   **The "PyCauset Advantage"**:
+    *   We use physics knowledge (Causality=Triangular, Propagator=Symmetric) to select $O(N^2)$ shortcuts.
+*   **Phase 3 Documentation**:
+    *   Update key `docs/classes/Matrix.md` regarding how properties affect performance.
+    *   Update `internals/algorithms.md` with property-specific complexity guarantees.
+    *   Update `project/protocols/Adding Operations.md` to include steps for registering new Traits/Tags.
+
+### Phase 4: Block Matrix Orchestration
+**Goal**: Ensure the `BlockMatrix` composite structure utilizes the new drivers.
+
+*   **Routing**: Ensure `BlockMatrix` operations (which decompose into sub-ops) route those sub-ops through `AutoSolver` correctly.
+*   **Heterogeneity**: Handle cases where one block is on GPU and another must stay on CPU (utilizing the unified worker interface defined in **R1_CPU**).
+*   **Phase 4 Documentation**:
+    *   Update `internals/Block Matrices.md`.
+
+### Phase 5: Robustness, Documents & Benchmarking (The "Shield")
+**Goal**: Final polish, stress testing, and complete documentation.
+
+*   **Stress Test**: Run the "100GB Matrix" test case on a machine with <16GB RAM and <8GB VRAM.
+*   **Unit Tests**: Mock `cudaGetDeviceProperties` to simulate hardware states.
+*   **Documentation Sweep**:
+    *   **Guide**: Add "GPU Configuration" section to existing `guides/Performance Guide.md`.
+    *   **Internal**: Update `documentation/project/protocols/Adding Operations.md` with GPU-specific kernel checklist.
+    *   **Compliance**: Verify all new APIs have `docs/` entries.
+
+---
+
+## Technical Constraints & Decisions
+
+### 1. The PCI-e Bottleneck
+Relying on the GPU for everything is often slower for medium sizes due to transfer overhead.
+*   **Decision**: The "Cost Model" (Phase 1) is strict. If the model says CPU is faster, we must use CPU.
+
+### 2. Pinned Memory Scarcity
+Pinned memory locks physical RAM.
+*   **Decision**: We use the `MemoryGovernor`'s dynamic pinning budget. Drivers must request a "ticket" to pin. If denied, they degrade to pageable memory (slower) but do not crash.
+
+### 3. Precision & Properties
+GPU paths must respect **R1_PROPERTIES**. Specialized kernels (Syrk, Trmm) are preferred over generic Gemm to save 50% FLOPs.
+
+## Open Questions
+
+*   **Context Management**: Global pool vs Per-Thread? (Likely global pool for R1).
+*   **Multi-GPU**: Explicitly out-of-scope for R1.

{pycauset-0.4.18.dev25 → pycauset-0.5.1.dev2}/documentation/internals/plans/TODO.md

@@ -364,41 +364,66 @@ Deliverables:
 
 Status: - [ ]
 
-Goal: GPU behavior is predictable and correct.
+Goal: GPU behavior is predictable, correct, and **cooperative**.
+
+Authoritative plan: `documentation/internals/plans/R1_GPU_PLAN.md`.
 
 Deliverables:
-- AutoSolver routing is explicit and testable.
-- For unsupported GPU cases: either CPU route or clear error.
-- Benchmark-based thresholds are documented.
-- Routing policy must account for **semantic properties** (effective structure categories) deterministically when GPU/CPU support differs by structure.
-- Default UX is seamless/automatic, but power users can override:
-    - a supported way to disable GPU globally (force CPU),
-    - a supported way to tweak thresholds/heuristics and precision policy,
-    - a supported way to inspect/verify what routing decision was taken.
+- **Phase 1: Robust Discovery & "Just Works" Dispatch:**
+    - AutoSolver routing is explicit, testable, and uses a cost model (transfer overhead vs dispatch gain).
+    - Hard fallback to CPU if GPU is missing capabilities or memory.
+    - Python API control surface (`pycauset.cuda.*`) for overrides and inspection.
+- **Phase 2: Streaming Algorithm Drivers (The "Cooperative" Core):**
+    - Implement **Algorithm-Specific Drivers** (Host-Side Orchestration) for complex ops (Cholesky, Arnoldi) that utilize the existing `AsyncStreamer` pipeline.
+    - CPU orchestrates dependencies; `AsyncStreamer` handles the heavy I/O and compute overlapping.
+    - *Note:* These drivers are critical for GPU VRAM limits but will also power the future R1_CPU engine.
+- **Phase 3: Integration:**
+    - Routing uses **Tag Dispatch** (`MatrixTraits`) to map Properties to optimized kernels (e.g., `cublasSyrk`).
+
+### R1_CPU — Modern Tiled CPU Engine (No More Legacy Loops)
+
+Status: - [ ]
 
-### R1_SRP — Support Readiness Program (SRP)
+Goal: The CPU is not a fallback; it is a **First-Class Worker** for the Streaming Architecture.
+
+Deliverables:
+- **Unified Worker Interface:**
+    - Implement `CpuWorker` that implements the same standard interface as `CudaWorker` (e.g., `compute_tile(A, B, C)`).
+    - Allows the `AsyncStreamer` and Algorithm Drivers (from R1_GPU) to run on CPU without code changes.
+- **Core Kernel Modernization:**
+    - Delete legacy simple loops.
+    - Implement Tiled / Blocked Matmul (OpenMP) to match the tile sizes used by the streamer (L2 Cache fitting).
+    - Implement Vectorized (AVX2/AVX-512) kernels for Elementwise ops.
+- **Standardization:**
+    - Ensure CPU kernels respect the same `MatrixTraits` tag dispatch system as GPU kernels.
+
+### R1_SRP — Support Readiness Program (SRP) & Optimization Catalog
 
 Status: - [ ]
 
-This is the long “painstaking” program.
+This is the long “painstaking” program. Only when this is done can we claim to be "PyCauset".
 
 Authoritative checklist: `documentation/internals/plans/SUPPORT_READINESS_FRAMEWORK.md`.
 
 SRP phases:
 - SRP-0: Canonical inventories locked (dtypes + ops + structures + devices).
 - SRP-1: CPU correctness across the inventory (Gate A + Gate B).
-- SRP-2: CPU optimization to ≥0.90× NumPy for declared benchmark regimes (Gate E).
+- SRP-2: **Causal Math Optimization Catalog** (The "Monster"):
+    - Identify the specific operator combinations used in Causal Set Theory (Propagators, Action, etc.).
+    - Map these to numerical shortcuts (e.g., triangularity, Neumann series, property-abuse).
+    - Ensure these shortcuts are implemented and routed correctly.
 - SRP-3: GPU coverage implemented OR explicitly routed/blocked (Gate C).
 - SRP-4: CCA lookahead hints + out-of-core performance validation (Gate D + Gate E).
 
 Definition of Done (Release 1 gate):
 - Every op in the canonical inventory has an explicit support status for every public dtype/structure/device case.
+- **Physics-Aware Optimizations** are verified: specific causal structures trigger their optimized paths (not just generic fallback).
 - No “silent wrong answers” and no “mysterious slow paths”.
 - Benchmarks exist and failures are actionable.
 
 Notes:
-- SRP correctness/coverage must include **property-aware variants** of operators once R1_PROPERTIES lands (because properties change semantics and algorithmic work).
-- Streaming manager: every op in the canonical inventory must either (a) have a per-op streaming descriptor with memory-optimized defaults for CPU and GPU (when GPU is in-scope) or (b) be explicitly routed/blocked with rationale. Close SRP only after this inventory is covered using the final CPU/GPU profiling data. This should be done through the "streaming manager".
+- SRP correctness/coverage must include **property-aware variants** of operators once R1_PROPERTIES lands.
+- Streaming manager coverage is verified here.
 ### R1_QA — Bench + Correctness Gates Enforced
 
 Status: - [ ]

{pycauset-0.4.18.dev25 → pycauset-0.5.1.dev2}/python/pycauset/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.4.18.dev25'
-__version_tuple__ = version_tuple = (0, 4, 18, 'dev25')
+__version__ = version = '0.5.1.dev2'
+__version_tuple__ = version_tuple = (0, 5, 1, 'dev2')
 
-__commit_id__ = commit_id = 'g75e4baea0'
+__commit_id__ = commit_id = 'gec3f1258f'

{pycauset-0.4.18.dev25 → pycauset-0.5.1.dev2}/src/accelerators/cuda/CudaDevice.cu

@@ -57,6 +57,40 @@ void CudaDevice::qr(const MatrixBase& in, MatrixBase& Q, MatrixBase& R) {
 
 namespace pycauset {
 
+// --- Discovery API ---
+
+int CudaDevice::get_device_count() {
+    int count = 0;
+    cudaError_t err = cudaGetDeviceCount(&count);
+    if (err == cudaSuccess) {
+        return count;
+    } else {
+        // If we can't get the count, assume 0 (no driver, or no gpu).
+        // Clear error to avoid polluting subsequent calls?
+        cudaGetLastError(); 
+        return 0;
+    }
+}
+
+std::string CudaDevice::get_device_name(int device_id) {
+    cudaDeviceProp prop;
+    cudaError_t err = cudaGetDeviceProperties(&prop, device_id);
+    if (err == cudaSuccess) {
+        return std::string(prop.name);
+    } else {
+        return "Unknown Device (Error: " + std::string(cudaGetErrorString(err)) + ")"; 
+    }
+}
+
+bool CudaDevice::is_available() {
+    int count = 0;
+    if (cudaGetDeviceCount(&count) != cudaSuccess) {
+        cudaGetLastError();
+        return false;
+    }
+    return count > 0;
+}
+
 CudaDevice::CudaDevice(const AcceleratorConfig& config) : config_(config) {
     // Initialize CUDA context
     cudaError_t err = cudaSetDevice(config_.device_id);

{pycauset-0.4.18.dev25 → pycauset-0.5.1.dev2}/src/accelerators/cuda/CudaDevice.hpp

@@ -70,6 +70,11 @@ public:
     int get_compute_capability_major() const { return cc_major_; }
     int get_compute_capability_minor() const { return cc_minor_; }
 
+    // Discovery API (Static)
+    static int get_device_count();
+    static std::string get_device_name(int device_id);
+    static bool is_available();
+
     // Accessors for Solver
     cublasHandle_t get_cublas_handle() const { return cublas_handle_; }
     cusolverDnHandle_t get_cusolver_handle() const { return cusolver_handle_; }