pycauset 0.6.1.dev10__tar.gz → 0.6.1.dev13__tar.gz

{pycauset-0.6.1.dev10 → pycauset-0.6.1.dev13}/CHANGELOG.md

@@ -34,8 +34,43 @@ milestone corresponds to **v0.5.1**.
 - GitHub Actions CI matrix (`ci.yml`): Windows / macOS / Linux on Python 3.12.
 - Benchmark harness (`benchmarks/bench.py`, `benchmarks/plot.py`) with graphs, and the
   out-of-core RAM-limit demo (`benchmarks/bench_ram.py`).
+- `bool`: alias for the `bool_` dtype token (both normalize to `"bool"`). `pc.bool`
+  now resolves and is star-exported; `bool_` remains for back-compat.
+- `zeros`/`ones`/`empty` no longer require `dtype=`. With no dtype they return a
+  dtype-deferred wrapper that resolves to `int32` on first use (or to the dtype of
+  the first written value); a still-typeless `empty` raises on read/use.
+- `dot(a, b)` now accepts matrices and matches `np.dot` semantics (vector-vector
+  scalar, matrix-matrix matmul, matrix-vector / vector-matrix products).
+- "constant" structure registered in the properties/structure system
+  (`is_constant` + `constant_value`); `ones` without a dtype carries it.
+- Everyday-use scenario tests (`tests/python/test_everyday_scenarios.py`), each
+  exercised in at least two ways and cross-checked against NumPy, plus a findings
+  note (`documentation/dev/FINDINGS_EVERYDAY_SCENARIOS.md`) and a scenario
+  benchmark script (`benchmarks/scenario_benchmarks.py`).
 
 ### Fixed
+- Bool/bit matmul no longer raises `Unsupported matrix multiplication types`:
+  `DenseBitMatrix @ TriangularBitMatrix` and `TriangularBitMatrix @ DenseBitMatrix`
+  now promote to a dense `int32` result (bit x bit counting semantics).
+- Cubing a causal matrix now works: `TriangularIntegerMatrix x TriangularBitMatrix`
+  and `TriangularIntegerMatrix x TriangularIntegerMatrix` matmul are supported
+  (native `int32` result), so `(C @ C) @ C` and `matrix_power(C, 3)` no longer throw
+  `Unsupported matrix multiplication types`.
+- `TriangularIntegerMatrix` (the result of `C @ C`) now exports to NumPy as
+  `int32` instead of raising `TypeError: data type 'triangularinteger' not
+  understood`.
+- Dense mixed-dtype matmul now works via a general promotion fallback:
+  `int32 @ float64`, `float64 @ int32`, `int32 @ TriangularBitMatrix`, and
+  `float64 @ TriangularBitMatrix` (and their reverses) no longer raise
+  `Unsupported matrix multiplication types`.
+- `matrix_power(C, k)` keeps triangular causal-matrix powers triangular (it no
+  longer densifies to a dense `IntegerMatrix` for some powers).
+- `dot(vector, matrix)` returns a 1-D vector like `np.dot` (previously a
+  transposed `(1, n)` row vector).
+- Wide mixed-integer matmul now promotes to the wider type instead of raising:
+  `int8 @ int16`, `int64 @ int32`, `uint8 @ uint16`, `uint32 @ int32` (promotes to
+  `int64`), and other mixed-width integer combinations all work via a generic
+  integer fallback kernel.
 - `norm(matrix, ord=2)` now returns the spectral norm (largest singular value); it
   previously returned the Frobenius norm for `ord=2`.
 - `np.asarray(IdentityMatrix)` no longer raises `TypeError: data type 'identity' not
@@ -84,3 +119,11 @@ milestone corresponds to **v0.5.1**.
   `MemoryGovernor`, `IOAccelerator`, `OpContract`, `OpRegistry`, `get_storage_root`,
   `set_storage_root`, `make_coordinates`, `sprinkle`). These stay reachable as
   `pycauset.<name>` for advanced use, but are no longer presented as public API.
+
+### Performance
+- `DenseBitMatrix x TriangularBitMatrix` matmul now uses a popcount kernel instead
+  of a naive element loop (~15x faster at n=256).
+- `C @ vector` matvec for `TriangularBitMatrix` now uses scale-first kernels that
+  iterate the set bits (beats NumPy's dense int64 matvec by ~30x at N=5000).
+- R1 goal restated to allow targeted optimization of correctness-first paths where a
+  naive fallback is egregiously slow relative to NumPy.

{pycauset-0.6.1.dev10 → pycauset-0.6.1.dev13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pycauset
-Version: 0.6.1.dev10
+Version: 0.6.1.dev13
 Summary: High-performance Causal Set matrix operations using memory-mapped files
 Author: Bror Hjemgaard
 License: MIT
@@ -28,8 +28,8 @@ Requires-Dist: psutil; extra == "dev"
 Description-Content-Type: text/markdown
 
 <div align="center">
-  <img src="documentation/docs/assets/logo/logo.png" width="150" alt="PyCauset Logo" style="vertical-align: middle; margin-right: 20px;">
-  <img src="documentation/docs/assets/logo/logo-text-colour.png" width="300" alt="PyCauset Text" style="vertical-align: middle;">
+  <img src="https://raw.githubusercontent.com/BrorH/pycauset/main/documentation/docs/assets/logo/logo.png" width="150" alt="PyCauset Logo" style="vertical-align: middle; margin-right: 20px;">
+  <img src="https://raw.githubusercontent.com/BrorH/pycauset/main/documentation/docs/assets/logo/logo-text-colour.png" width="300" alt="PyCauset Text" style="vertical-align: middle;">
 
   <br><br>
 
@@ -65,7 +65,7 @@ fig = plot_embedding(c)             # interactive Plotly figure
 fig.show()
 ```
 
-<img src="documentation/docs/assets/gallery/diamond_embedding.png" width="520" alt="3000 points in a 2D Minkowski diamond">
+<img src="https://raw.githubusercontent.com/BrorH/pycauset/main/documentation/docs/assets/gallery/diamond_embedding.png" width="520" alt="3000 points in a 2D Minkowski diamond">
 
 
 
@@ -117,10 +117,10 @@ However, the biggest reason to use PyCauset is that it memory-maps past RAM, whe
 
 Both images come straight from the public API. Reproduce them with `scripts/make_r1_gallery.py`.
 
-<img src="documentation/docs/assets/gallery/diamond_hasse.png" width="420" alt="Hasse diagram of an 80-point diamond">
+<img src="https://raw.githubusercontent.com/BrorH/pycauset/main/documentation/docs/assets/gallery/diamond_hasse.png" width="420" alt="Hasse diagram of an 80-point diamond">
 *The causal links of an 80-point diamond (Hasse diagram).*
 
-<img src="documentation/docs/assets/gallery/cylinder_embedding.png" width="420" alt="3000 points on a Minkowski cylinder">
+<img src="https://raw.githubusercontent.com/BrorH/pycauset/main/documentation/docs/assets/gallery/cylinder_embedding.png" width="420" alt="3000 points on a Minkowski cylinder">
 *3000 points sprinkled onto a Minkowski cylinder, rendered as a 3D tube.*
 
 ## Installation

{pycauset-0.6.1.dev10 → pycauset-0.6.1.dev13}/README.md

@@ -1,6 +1,6 @@
 <div align="center">
-  <img src="documentation/docs/assets/logo/logo.png" width="150" alt="PyCauset Logo" style="vertical-align: middle; margin-right: 20px;">
-  <img src="documentation/docs/assets/logo/logo-text-colour.png" width="300" alt="PyCauset Text" style="vertical-align: middle;">
+  <img src="https://raw.githubusercontent.com/BrorH/pycauset/main/documentation/docs/assets/logo/logo.png" width="150" alt="PyCauset Logo" style="vertical-align: middle; margin-right: 20px;">
+  <img src="https://raw.githubusercontent.com/BrorH/pycauset/main/documentation/docs/assets/logo/logo-text-colour.png" width="300" alt="PyCauset Text" style="vertical-align: middle;">
 
   <br><br>
 
@@ -36,7 +36,7 @@ fig = plot_embedding(c)             # interactive Plotly figure
 fig.show()
 ```
 
-<img src="documentation/docs/assets/gallery/diamond_embedding.png" width="520" alt="3000 points in a 2D Minkowski diamond">
+<img src="https://raw.githubusercontent.com/BrorH/pycauset/main/documentation/docs/assets/gallery/diamond_embedding.png" width="520" alt="3000 points in a 2D Minkowski diamond">
 
 
 
@@ -88,10 +88,10 @@ However, the biggest reason to use PyCauset is that it memory-maps past RAM, whe
 
 Both images come straight from the public API. Reproduce them with `scripts/make_r1_gallery.py`.
 
-<img src="documentation/docs/assets/gallery/diamond_hasse.png" width="420" alt="Hasse diagram of an 80-point diamond">
+<img src="https://raw.githubusercontent.com/BrorH/pycauset/main/documentation/docs/assets/gallery/diamond_hasse.png" width="420" alt="Hasse diagram of an 80-point diamond">
 *The causal links of an 80-point diamond (Hasse diagram).*
 
-<img src="documentation/docs/assets/gallery/cylinder_embedding.png" width="420" alt="3000 points on a Minkowski cylinder">
+<img src="https://raw.githubusercontent.com/BrorH/pycauset/main/documentation/docs/assets/gallery/cylinder_embedding.png" width="420" alt="3000 points on a Minkowski cylinder">
 *3000 points sprinkled onto a Minkowski cylinder, rendered as a 3D tube.*
 
 ## Installation

pycauset-0.6.1.dev13/benchmarks/scenario_benchmarks.py

@@ -0,0 +1,83 @@
+"""Everyday-use scenario benchmarks with NumPy comparison.
+
+Times representative causal-set operations in pycauset and, where a dense
+NumPy equivalent exists, compares wall-clock time. Run with:
+
+    .venv\\Scripts\\python.exe benchmarks\\scenario_benchmarks.py
+
+These are informal wall-clock measurements (best of N), not a rigorous
+statistical benchmark.
+"""
+
+import time
+
+import numpy as np
+
+import pycauset as pc
+
+
+def _best(fn, *, repeat, number):
+    best = float("inf")
+    for _ in range(repeat):
+        t0 = time.perf_counter()
+        for _ in range(number):
+            fn()
+        dt = (time.perf_counter() - t0) / number
+        best = min(best, dt)
+    return best
+
+
+def _dense(mat, n):
+    out = np.zeros((n, n), dtype=int)
+    for i in range(n):
+        for j in range(n):
+            out[i, j] = 1 if mat.get(i, j) else 0
+    return out
+
+
+def main():
+    n = 256
+    sp = pc.MinkowskiDiamond(3)
+    C = pc.CausalSet(n, spacetime=sp, seed=1234).C
+    B = pc.ones((n, n), dtype=pc.bool_)
+    Cn = _dense(C, n)                 # int64 dense reference
+    Bn = np.ones((n, n), dtype=bool)
+
+    print(f"n = {n} (3D diamond causal matrix + a bool matrix)\n")
+    print(f"{'operation':<40} {'pycauset':>10} {'numpy':>10} {'ratio':>8}")
+
+    def row(name, pc_fn, np_fn, *, repeat=5, number=10):
+        pc_t = _best(pc_fn, repeat=repeat, number=number)
+        np_t = _best(np_fn, repeat=repeat, number=number)
+        print(f"{name:<40} {pc_t*1e3:>9.3f} {np_t*1e3:>9.3f} {pc_t/np_t:>7.2f}x")
+
+    row("C @ C (triangular bit x bit)",
+        lambda: C @ C, lambda: Cn @ Cn)
+    row("B @ C (dense bool x triangular bit)",
+        lambda: B @ C, lambda: Bn.astype(int) @ Cn)
+    row("(C @ C) @ C (cube)",
+        lambda: (C @ C) @ C, lambda: Cn @ Cn @ Cn)
+    row("matrix_power(C, 3)",
+        lambda: pc.matrix_power(C, 3), lambda: np.linalg.matrix_power(Cn, 3))
+    row("dot(C, C)",
+        lambda: pc.dot(C, C), lambda: Cn @ Cn)
+    ones_pc = pc.ones(n, dtype="int32")
+    ones_np = np.ones(n, dtype=int)
+    row("C @ ones (matvec)",
+        lambda: C @ ones_pc,
+        lambda: Cn @ ones_np)
+
+    # Float64 dense matmul: NumPy uses BLAS here, so this is the realistic
+    # "NumPy fast path" comparison.
+    F = pc.ones((n, n), dtype="float64")
+    Fn = np.ones((n, n), dtype=float)
+    row("float64 dense matmul (BLAS)",
+        lambda: F @ F, lambda: Fn @ Fn)
+
+    print("\nratio < 1 means pycauset is faster; > 1 means slower than NumPy.")
+    print("NumPy int reference uses int64 dense arrays (NumPy's int matmul is a naive")
+    print("loop, not BLAS); the float64 row is NumPy's BLAS-backed fast path.")
+
+
+if __name__ == "__main__":
+    main()

pycauset-0.6.1.dev13/documentation/dev/FINDINGS_EVERYDAY_SCENARIOS.md

@@ -0,0 +1,141 @@
+# Findings: everyday-use scenarios
+
+This document records what happened when we exercised PyCauset through
+realistic "everyday" causal-set workflows, each implemented at least two
+different ways and cross-checked against NumPy. It lists the bugs we found and
+fixed, the remaining limitations, and benchmark numbers (including a NumPy
+comparison and a large-N check).
+
+Scenarios live in `tests/python/test_everyday_scenarios.py`. Benchmarks live in
+`benchmarks/scenario_benchmarks.py` (NumPy comparison) and
+`benchmarks/large_n_check.py` (large-N correctness and timing).
+
+## Scenarios and results
+
+| Scenario | Ways exercised | Result |
+|---|---|---|
+| Cube 3 causal matrices (3D diamond) and add them | `(C@C)@C` chain, `matrix_power(C, 3)` | Both agree with NumPy |
+| Count 2-step causal relations (`C^2`) | `@`, `pc.matmul`, `pc.dot` | All three agree with NumPy |
+| Count elements in each element's causal future (row sums) | `C @ ones`, NumPy row sums | Agree |
+| Constant working matrix without a dtype | lazy `ones` vs explicit `bool_`, lazy `zeros` then `fill` | Agree |
+| `K = C (I + C)^-1` | `pc.compute_k` vs NumPy `inv` | Agree (rtol 1e-10) |
+
+## Bugs found and fixed
+
+1. **`TriangularIntegerMatrix` could not be exported to NumPy.**
+   `to_numpy(C @ C)` raised `TypeError: data type 'triangularinteger' not
+   understood`. Fixed by adding the `triangularinteger -> int32` entry to the
+   export guard's type-name-to-dtype map.
+
+2. **Cubing a causal matrix threw "Unsupported matrix multiplication types".**
+   `(C @ C) @ C` failed because `C @ C` yields a `TriangularIntegerMatrix`, and
+   `TriangularIntegerMatrix x {TriangularBitMatrix, TriangularIntegerMatrix}` had
+   no native dispatch. Fixed with new C++ cases and a correctness-first kernel.
+
+3. **Dense mixed-dtype matmul threw for common combinations.** `int32 @ float64`,
+   `float64 @ int32`, `int32 @ TriangularBitMatrix`, `float64 @ TriangularBitMatrix`
+   (and their reverses) all raised `Unsupported matrix multiplication types`.
+   Fixed by adding a general fallback at the end of the C++ dispatch that resolves
+   the promoted result dtype via `PromotionResolver` and computes through a generic
+   element-access path (with an `int32` result branch in the CPU solver).
+
+4. **`matrix_power(C, 4)` densified to a dense `IntegerMatrix`.** The
+   `TriangularIntegerMatrix` operands were being caught by the "same-dtype integer"
+   case (which matches on `get_data_type()`), producing a dense result. Fixed by
+   moving the triangular-int case ahead of the same-dtype integer case; powers now
+   stay `TriangularIntegerMatrix`.
+
+5. **`pc.dot(vector, matrix)` returned a row vector `(1, n)` instead of NumPy's
+   1-D `(n,)`.** Fixed by un-transposing the native vec-mat result inside `pc.dot`.
+
+6. **Wide mixed-integer matmul threw.** `int64 @ int32`, `int8 @ int16`,
+   `uint8 @ uint16`, `uint32 @ int32`, and other mixed-width integer combinations
+   raised `Unsupported matrix multiplication types`. Fixed by extending the general
+   fallback to every integer width (int8/int16/int32/int64/uint8/uint16/uint32/
+   uint64) via a templated generic integer kernel.
+
+7. **Naive correctness-first kernels were unacceptably slow.** The
+   `DenseBitMatrix x TriangularBitMatrix` matmul and the causal-matrix matvec
+   (`C @ vector`) used naive element-access loops. Added a popcount kernel for
+   bit x bit (materializing a triangular bit operand to dense first) and
+   scale-first matvec kernels for `TriangularBitMatrix x {int32, float64, bool}`
+   vectors. See benchmarks for the speedups.
+
+## Remaining limitations
+
+1. **int64/uint64 mixed matmul is exact only up to 2^53.** The generic mixed-kind
+   integer path accumulates in `double` (exact for every other integer width). For
+   `int64`/`uint64` results the values are exact only below 2^53; beyond that the
+   result can lose precision. Same-dtype `int64 @ int64` / `uint64 @ uint64` use
+   the dedicated exact kernels and are unaffected.
+
+2. **`pc.empty(shape)` without a dtype raises on first use.** Intentional ("no
+   silent wrong answers"): an empty allocation has no dtype until a value is
+   written, so reading it raises a clear `TypeError`. Callers must `fill(...)` or
+   `set(...)` first, or pass `dtype=`.
+
+## Benchmarks (NumPy comparison)
+
+Informal wall-clock, best of 5, `n = 256` (3D diamond), Windows MSVC. The NumPy
+reference uses dense `int64` arrays except the float64 row (BLAS-backed). `B @ C`
+and the matvec numbers reflect the optimized popcount / scale-first kernels.
+
+| Operation | pycauset (ms) | numpy (ms) | ratio |
+|---|---|---|---|
+| `C @ C` (triangular bit x bit) | 0.090 | 24.97 | 0.00x |
+| `B @ C` (dense bool x triangular bit) | 0.717 | 23.31 | 0.03x |
+| `(C @ C) @ C` (cube) | 2.73 | 40.36 | 0.07x |
+| `matrix_power(C, 3)` | 8.07 | 44.02 | 0.18x |
+| `dot(C, C)` | 0.71 | 20.60 | 0.03x |
+| `C @ ones` (matvec) | 0.046 | 0.032 | 1.44x |
+| float64 dense matmul (BLAS) | 0.52 | 0.19 | 2.74x |
+
+Notes:
+
+- For integer matmul, pycauset is much faster because its bit-packed popcount
+  kernel is `O(N^3/64)` while NumPy's integer matmul is a naive (non-BLAS) loop.
+  `B @ C` dropped from ~10.8 ms to ~0.7 ms (about 15x) after adding the popcount
+  path for mixed bit operands.
+- `C @ ones` matvec went from a generic `O(N^2)` element loop to a scale-first
+  `O(set bits)` kernel. At `n = 256` it is ~1.4x NumPy; at larger N the sparse
+  triangular form wins decisively (see below).
+- For float64 dense matmul, NumPy's BLAS wins by ~2.7x (0.19 ms vs 0.52 ms); this
+  remains the main gap and is part of the post-R1 float64-parity program.
+
+## Large-N check
+
+`benchmarks/large_n_check.py` verifies `C @ C` correctness on a random sample of
+entries (direct `O(N)` reference) plus a structural invariant (strictly upper
+triangular square has zero diagonal). All checks passed up to N = 80000.
+
+| N | build (s) | `C @ C` (s) | correct |
+|---|---|---|---|
+| 2000 | 0.016 | 0.006 | yes |
+| 5000 | 0.094 | 0.059 | yes |
+| 10000 | 0.368 | 0.409 | yes |
+| 20000 | 1.465 | 3.234 | yes |
+| 40000 | 5.834 | 24.700 | yes |
+| 80000 | 23.315 | 181.676 | yes |
+
+At N = 40000 and N = 80000 the out-of-core memory governor kicked in and spilled
+the intermediate result to disk ("RAM full ... falling back to disk", ~12 GB at
+N = 80000); the computation still completed correctly. This exercises the
+disk-backed path end to end at scale.
+
+## Matvec at larger N
+
+The scale-first triangular matvec is sparse-aware, so it beats NumPy's dense
+`int64` matvec once N grows:
+
+| N | pycauset (ms) | numpy (ms) | ratio |
+|---|---|---|---|
+| 256 | 0.048 | 0.032 | 1.49x |
+| 1000 | 0.053 | 0.454 | 0.12x |
+| 2000 | 0.108 | 2.433 | 0.04x |
+| 5000 | 0.483 | 16.03 | 0.03x |
+
+## Remaining performance work (post-R1)
+
+The targeted correctness-first optimizations are done. The remaining performance
+gaps are the full post-R1 program: float64 matmul parity with BLAS (currently
+~2.7x behind), GPU parity, and streaming-everything.

{pycauset-0.6.1.dev10 → pycauset-0.6.1.dev13}/documentation/dev/ONBOARDING_DTYPE_DEEP_DIVE.md

@@ -13,9 +13,11 @@ matrices/vectors with a NumPy-like API, memory-mapped / out-of-core storage, and
 Repo: `C:\Users\ireal\Documents\Projects\pycauset`
 
 Release-1 (R1) gate (authoritative): ship on **correctness + no silent wrong answers +
-explicit support status everywhere**. Optimization (>= 0.90x NumPy, GPU parity,
-streaming-everything) is deferred to a continuous post-R1 program. R1 is nearly shipped;
-the remaining work is release mechanics (CI green, tag v0.5.1, PyPI publish).
+explicit support status everywhere**. Targeted optimization of correctness-first paths is
+in scope where a naive fallback is egregiously slow relative to NumPy (bit-matmul
+popcount, causal-matrix matvec); the full performance program (>= 0.90x NumPy everywhere,
+GPU parity, streaming-everything) remains a continuous post-R1 program. R1 is nearly
+shipped; the remaining work is release mechanics (CI green, tag v0.5.1, PyPI publish).
 
 ## 2. Non-negotiable rules (from the project owner)
 
@@ -126,11 +128,11 @@ C = pc.CausalSet(N, seed=1223).C          # TriangularBitMatrix
 B = pc.ones((N, N), dtype=pc.bool_)       # currently requires dtype; should not
 
 # these should all work after the fix:
-print(pc.ones((N, N)))                    # default dtype, no keyword
-print(pc.zeros((2, 2)))                   # default dtype
-print(pc.empty((2, 2)))                   # default dtype
+print(pc.ones((N, N)))                    # dtype-deferred; resolves to int32
+print(pc.zeros((2, 2)))                   # dtype-deferred; resolves to int32
+e = pc.empty((2, 2)); e.fill(0.0); print(e)  # empty resolves on first write
 print(pc.bool)                            # alias for pc.bool_ (should resolve)
-print(B @ C)                              # bool @ bit matmul (promote)
+print(B @ C)                              # bool @ bit matmul (promote to int32)
 print(pc.dot(B, C))                       # dot should accept matrices
 ```
 
@@ -144,8 +146,10 @@ line in the same commit:
 1. Read `test.py`, `python/pycauset/__init__.py` (zeros/ones/empty/dot/matmul + the dtype
    constants), `python/pycauset/_internal/dtypes.py` (`normalize_dtype`), and
    `src/core/PromotionResolver.cpp` to understand the current promotion rules end to end.
-2. Give `zeros`/`ones`/`empty` a sensible default dtype (float64, matching NumPy) so the
-   `dtype=` keyword becomes optional. Make sure explicit dtype still works.
+2. Give `zeros`/`ones`/`empty` an optional `dtype=` (no longer required). With no dtype
+   they return a dtype-deferred wrapper that resolves to int32 on first use (or to the
+   dtype of the first written value); a still-typeless `empty` raises on read/use.
+   Explicit dtype still works.
 3. Add `bool` as an alias for `bool_` in `normalize_dtype` (and expose `pc.bool`), while
    keeping `bool_` working for back-compat.
 4. Fix bool/bit matmul (`@`) so `B @ C` promotes correctly instead of throwing. The error
@@ -182,8 +186,9 @@ line in the same commit:
 
 ## 10. Definition of done for this mission
 
-- `pc.ones/zeros/empty` work with no dtype argument (default float64) and still accept an
-  explicit dtype.
+- `pc.ones/zeros/empty` work with no dtype argument (a dtype-deferred wrapper that
+  resolves to int32 on first use, or to the first written value's dtype) and still
+  accept an explicit dtype.
 - `pc.bool` resolves (alias of `pc.bool_`), and dtype normalization accepts `bool`.
 - Bool/bit `@` matmul works and produces a correct promoted result (no "unsupported
   matrix multiplication types", no "mixing type error").

pycauset-0.6.1.dev13/documentation/docs/functions/pycauset.dot.md

@@ -0,0 +1,53 @@
+# pycauset.dot
+
+```python
+pycauset.dot(a, b)
+```
+
+Compute a dot product or matrix product, matching NumPy's `np.dot`.
+
+Semantics:
+
+*   vector · vector: scalar inner product (no implicit conjugation).
+*   matrix · matrix: matrix multiplication.
+*   matrix · vector / vector · matrix: matrix-vector product.
+
+Matrix cases route through `pycauset.matmul`.
+
+## Parameters
+
+*   `a`: The first operand (vector or matrix).
+*   `b`: The second operand (vector or matrix).
+
+## Returns
+
+*   `float | complex` for vector · vector.
+*   `MatrixBase | VectorBase` for matrix cases.
+
+## Exceptions
+
+*   Raises `TypeError` if a vector-like `a` lacks a `.dot(...)` method.
+*   Raises `ValueError` for mismatched vector sizes or matrix dimensions.
+
+## Examples
+
+```python
+import numpy as np
+import pycauset as pc
+
+v = pc.vector([1.0, 2.0, 3.0])
+assert pc.dot(v, v) == 14.0
+
+A = pc.matrix(np.array([[1.0, 2.0], [3.0, 4.0]]))
+B = pc.matrix(np.array([[5.0, 6.0], [7.0, 8.0]]))
+C = pc.dot(A, B)  # matrix multiplication
+
+x = pc.vector([1.0, 1.0])
+assert pc.dot(A, x).shape[0] == 2  # matrix-vector product
+```
+
+## See also
+
+*   [[docs/functions/pycauset.matmul.md|pycauset.matmul]]
+*   [[docs/classes/vector/pycauset.VectorBase.md|pycauset.VectorBase]]
+*   [[docs/functions/pycauset.norm.md|pycauset.norm]]

{pycauset-0.6.1.dev10 → pycauset-0.6.1.dev13}/documentation/docs/functions/pycauset.empty.md

@@ -1,14 +1,17 @@
 # pycauset.empty
 
 ```python
-pycauset.empty(shape, *, dtype, **kwargs)
+pycauset.empty(shape, *, dtype=None, **kwargs)
 ```
 
 Allocate a vector or matrix without guaranteeing initialization.
 
 Note: for some backends this may still be zero-initialized.
 
-`dtype` is required.
+When `dtype` is omitted, the result is a dtype-deferred wrapper with no dtype
+at all. Its dtype is deduced from the first value written into it (`set`,
+`fill`, or item assignment). Reading from, or operating on, a still-typeless
+`empty` raises `TypeError` (no silent wrong answer).
 
 ## Parameters
 
@@ -20,12 +23,12 @@ Note: for some backends this may still be zero-initialized.
     Notes:
     *   Rectangular allocation is supported for dense numeric matrix types.
     *   `dtype="bool"`/`dtype="bit"` uses bit-packed storage (`DenseBitMatrix`) and supports rectangular `(rows, cols)` shapes.
-*   **dtype** (*str or type*): Storage dtype token.
+*   **dtype** (*str or type, optional*): Storage dtype token. When omitted, the dtype is deduced from the first written value.
 *   **kwargs**: Passed through to the backend allocator.
 
 ## Returns
 
-*   **VectorBase or MatrixBase**: A newly allocated object.
+*   **VectorBase or MatrixBase**: A newly allocated object. With no `dtype`, a dtype-deferred wrapper is returned instead and materializes on first write.
 
 ## Examples
 
@@ -33,6 +36,9 @@ Note: for some backends this may still be zero-initialized.
 import pycauset as pc
 
 tmp = pc.empty((256, 64), dtype="float32")
+
+late = pc.empty((4, 4))   # dtype-deferred
+late.fill(2.5)            # resolves to float64
 ```
 
 ## See also

{pycauset-0.6.1.dev10 → pycauset-0.6.1.dev13}/documentation/docs/functions/pycauset.matmul.md

@@ -17,6 +17,10 @@ This function is NumPy-like:
 - vector-matrix: `(k,) @ (k, n) -> (1, n)` (row-vector semantics)
 - vector-vector: `(k,) @ (k,) -> scalar` (dot)
 
+Bit operands (`bool`/`bit`, i.e. `DenseBitMatrix` or `TriangularBitMatrix`) promote
+to `int32` on matmul because a bit-bit reduction can exceed `{0,1}`. This includes
+the mixed `DenseBitMatrix @ TriangularBitMatrix` case (and its reverse).
+
 ## Parameters
 
 *   **a** (*MatrixBase or VectorBase or BlockMatrix*): Left operand.

{pycauset-0.6.1.dev10 → pycauset-0.6.1.dev13}/documentation/docs/functions/pycauset.ones.md

@@ -1,12 +1,15 @@
 # pycauset.ones
 
 ```python
-pycauset.ones(shape, *, dtype, **kwargs)
+pycauset.ones(shape, *, dtype=None, **kwargs)
 ```
 
 Allocate a vector or matrix filled with ones.
 
-`dtype` is required.
+When `dtype` is omitted, the result is a dtype-deferred wrapper (all-equal
+"constant" structure, value `1`) that resolves to `int32` on first use, or to
+the dtype of the first value written into it. Passing `dtype` allocates a
+concrete object immediately.
 
 ## Parameters
 
@@ -18,19 +21,19 @@ Allocate a vector or matrix filled with ones.
     Notes:
     *   Rectangular allocation is supported for dense numeric matrix types.
     *   `dtype="bool"`/`dtype="bit"` uses bit-packed storage (`DenseBitMatrix`) and supports rectangular `(rows, cols)` shapes.
-*   **dtype** (*str or type*): Storage dtype token.
+*   **dtype** (*str or type, optional*): Storage dtype token. Defaults to a deferred `int32` when omitted.
 *   **kwargs**: Passed through to the backend allocator.
 
 ## Returns
 
-*   **VectorBase or MatrixBase**: A newly allocated object.
+*   **VectorBase or MatrixBase**: A newly allocated object. With no `dtype`, a dtype-deferred wrapper is returned instead and materializes on first use.
 
 ## Examples
 
 ```python
 import pycauset
 
-v = pycauset.ones((5,), dtype="int32")
+v = pycauset.ones(5)                   # dtype-deferred; resolves to int32
 m = pycauset.ones((3, 7), dtype="float64")
 ```
 

{pycauset-0.6.1.dev10 → pycauset-0.6.1.dev13}/documentation/docs/functions/pycauset.zeros.md

@@ -1,12 +1,14 @@
 # pycauset.zeros
 
 ```python
-pycauset.zeros(shape, *, dtype, **kwargs)
+pycauset.zeros(shape, *, dtype=None, **kwargs)
 ```
 
 Allocate a vector or matrix filled with zeros.
 
-`dtype` is required.
+When `dtype` is omitted, the result is a dtype-deferred wrapper (all-zeros
+structure) that resolves to `int32` on first use, or to the dtype of the first
+value written into it. Passing `dtype` allocates a concrete object immediately.
 
 ## Parameters
 
@@ -18,19 +20,19 @@ Allocate a vector or matrix filled with zeros.
     Notes:
     *   Rectangular allocation is supported for dense numeric matrix types.
     *   `dtype="bool"`/`dtype="bit"` uses bit-packed storage (`DenseBitMatrix`) and supports rectangular `(rows, cols)` shapes.
-*   **dtype** (*str or type*): Storage dtype token (e.g. `"float64"`, `"int32"`, `float`, `int`).
+*   **dtype** (*str or type, optional*): Storage dtype token (e.g. `"float64"`, `"int32"`, `float`, `int`). Defaults to a deferred `int32` when omitted.
 *   **kwargs**: Passed through to the backend allocator.
 
 ## Returns
 
-*   **VectorBase or MatrixBase**: A newly allocated object.
+*   **VectorBase or MatrixBase**: A newly allocated object. With no `dtype`, a dtype-deferred wrapper is returned instead and materializes on first use.
 
 ## Examples
 
 ```python
 import pycauset
 
-v = pycauset.zeros(10, dtype="float64")
+v = pycauset.zeros(10)                 # dtype-deferred; resolves to int32
 m = pycauset.zeros((128, 64), dtype="float32")
 ```
 

{pycauset-0.6.1.dev10 → pycauset-0.6.1.dev13}/documentation/internals/plans/TODO.md

@@ -16,11 +16,13 @@ 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)
-- **Concurrent native matrix construction is not thread-safe** (Linux segfault, GCC
-  build). Constructing native matrices from multiple threads at once crashes in the
-  native constructor. Mitigated by serializing construction in
-  `test_threaded_io_stress`; the root cause needs ASan-on-Linux debugging and proper
-  locking in the allocation path.
+- **Concurrent native operations are not thread-safe** (Linux segfault, GCC build).
+  Constructing, saving, loading, or deleting native matrices from multiple threads at
+  once crashes in the native layer. Serializing only construction was tried and did
+  not help, because the concurrent save/load/delete paths also corrupt shared
+  MemoryGovernor/MemoryMapper state. `test_threaded_io_stress` is skipped in R1; the
+  root cause needs ASan-on-Linux debugging and proper locking across the whole
+  allocation + I/O path.
 - **Teardown hang in `release_tracked_matrices()`** (mitigated by skipping native
   `close()` during interpreter finalization; root cause unfixed).
 - **Heap-corruption heisenbug** (was MinGW-specific; MSVC is clean, verify GCC/Clang).