pycauset 0.5.1.dev2__tar.gz → 0.5.1.dev104__tar.gz

pycauset-0.5.1.dev104/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.os }} · py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-15, windows-latest]
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools_scm needs full history + tags to detect the version
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install system OpenBLAS (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libopenblas-dev liblapacke-dev gfortran
+
+      - name: Install system OpenBLAS (macOS)
+        if: runner.os == 'macOS'
+        run: brew install openblas
+
+      - name: Install Python build/test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pytest
+
+      - name: Build and install pycauset
+        run: python -m pip install .
+
+      - name: Deploy native extension into source tree
+        # The test suite adds the repo's python/ dir to sys.path and imports the
+        # package from there, but pip installs the compiled _pycauset extension and
+        # its DLLs into site-packages. Copy the native artifacts next to the source
+        # so the tests find them.
+        run: python -c "import pycauset, pathlib, shutil; sp = pathlib.Path(pycauset.__file__).parent; dst = pathlib.Path('python/pycauset'); [shutil.copy2(str(f), str(dst / f.name)) for pat in ('*.pyd','*.so','*.dylib','*.dll') for f in sp.glob(pat)]; libs = sp / 'libs'; shutil.copytree(str(libs), str(dst / 'libs'), dirs_exist_ok=True) if libs.exists() else None"
+
+      - name: Run tests
+        run: python -m pytest tests/python -q

pycauset-0.5.1.dev104/.github/workflows/publish.yml

@@ -0,0 +1,119 @@
+name: Publish to PyPI.
+
+on:
+  push:
+    branches: ["main"]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-15]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for setuptools_scm to find tags
+
+      # Setup ccache to speed up re-compilation
+      - name: Setup ccache
+        uses: hendrikmuhs/ccache-action@v1.2
+        with:
+          key: ${{ matrix.os }}-ccache
+          update-package-index: true
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21.3
+        env:
+          # Configure cibuildwheel to build for Python 3.8+
+          # Skip 32-bit builds (Linux i686 is skipped by pattern, Windows 32-bit by ARCHS config)
+          CIBW_SKIP: "cp36-* cp37-* pp* *i686* *-musllinux*"
+          
+          # Pass specific hints to CMake via environment variables to help FindPython
+          # scikit-build-core usually handles this, but explicit hints prevent "found 3.8 but wanted 3.11" errors
+          
+          # Windows: Build only 64-bit wheels (avoids OpenBLAS 32/64 bit mismatch and speeds up CI)
+          CIBW_ARCHS_WINDOWS: "auto64"
+          CIBW_ENVIRONMENT_WINDOWS: "CMAKE_ARGS='-DPython_FIND_STRATEGY=LOCATION'"
+
+          # Linux: Use manylinux_2_28 (AlmaLinux 8) and install GCC 12 via gcc-toolset.
+          # This ensures full C++20 support (including <bit>, char8_t, <filesystem>).
+          CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
+          CIBW_MANYLINUX_AARCH64_IMAGE: manylinux_2_28
+          
+          # Install GCC 12 on Linux before build
+          # We also install openblas-devel to avoid building it from source (which fails and is slow)
+          # and lapack-devel for the LAPACKE C-interface header (CpuSolver.cpp includes <lapacke.h>).
+          # The wheels will bundle the library via auditwheel
+          CIBW_BEFORE_ALL_LINUX: "yum install -y epel-release && yum install -y gcc-toolset-12-gcc gcc-toolset-12-gcc-c++ libatomic openblas-devel lapack-devel ccache"
+          
+          # Point the build to use GCC 12
+          CIBW_ENVIRONMENT_LINUX: "CMAKE_ARGS='-DPython_FIND_STRATEGY=LOCATION' CC='/opt/rh/gcc-toolset-12/root/usr/bin/gcc' CXX='/opt/rh/gcc-toolset-12/root/usr/bin/g++' PATH=\"/usr/lib64/ccache:$PATH\""
+          
+          # macOS: Install build dependencies.
+          # OpenBLAS and libomp are needed for the C++ extension.
+          CIBW_BEFORE_ALL_MACOS: "brew install libomp openblas ccache"
+          
+          # macOS: Env Setup
+          # 1. Point to Homebrew locations for headers/libs (Apple Silicon uses /opt/homebrew, Intel uses /usr/local)
+          # 2. Add ccache to PATH (checking both potential locations)
+          # 3. MACOSX_DEPLOYMENT_TARGET must match the Homebrew bottles on the runner.
+          #    We pin the runner to macos-15 so Homebrew builds against macOS 15 and the
+          #    wheel supports macOS 15+, instead of being dragged to the newest runner OS.
+          CIBW_ENVIRONMENT_MACOS: >
+            MACOSX_DEPLOYMENT_TARGET="15.0"
+            CMAKE_ARGS='-DPython_FIND_STRATEGY=LOCATION'
+            CC="clang"
+            CXX="clang++"
+            CFLAGS="-Xpreprocessor -fopenmp -I/opt/homebrew/opt/libomp/include -I/usr/local/opt/libomp/include"
+            CXXFLAGS="-Xpreprocessor -fopenmp -I/opt/homebrew/opt/libomp/include -I/usr/local/opt/libomp/include"
+            LDFLAGS="-L/opt/homebrew/opt/libomp/lib -L/usr/local/opt/libomp/lib -lomp"
+            PATH="/opt/homebrew/opt/ccache/libexec:/usr/local/opt/ccache/libexec:$PATH"
+
+      - uses: actions/upload-artifact@v4
+        if: ${{ !env.ACT }}
+        with:
+          name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Build sdist
+        run: pipx run build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz
+
+  publish_to_pypi:
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pycauset
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

pycauset-0.5.1.dev104/.gitignore

@@ -0,0 +1,133 @@
+# --- Python ---
+test.py
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.pyd
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# --- Generated Version File ---
+python/pycauset/_version.py
+
+# --- Virtual Environments ---
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# --- Testing & Coverage ---
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# --- C++ / CMake / Visual Studio ---
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+Makefile
+*.vcxproj
+*.vcxproj.filters
+*.vcxproj.user
+*.sln
+*.slnx
+*.dir/
+*.lib
+*.exp
+*.dll
+*.exe
+*.pdb
+*.ilk
+*.obj
+*.iobj
+*.ipdb
+*.tlog
+_deps/
+x64/
+x86/
+Debug/
+Release/
+RelWithDebInfo/
+MinSizeRel/
+out/
+
+# --- IDEs / Editors ---
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# --- Project Specific ---
+benchmarks/*
+!benchmarks/*.py
+# Scratch/exploration benchmark scripts superseded by the canonical suite
+# (bench.py, bench_coverage.py, bench_structures.py, bench_ram.py, plot.py).
+# Kept on disk but not tracked.
+benchmarks/benchmark_*.py
+benchmarks/comprehensive_benchmark.py
+benchmarks/debug_matmul.py
+benchmarks/inspect_temp.py
+benchmarks/stress_test_memory_system.py
+# Explicitly tracked harnesses referenced by documentation/dev/Testing & Benchmarks.md.
+!benchmarks/benchmark_numpy_parity.py
+!benchmarks/benchmark_io_smoke.py
+.pycauset/
+*.pycauset
+storage/
+site/
+
+# --- CTest output ---
+Testing/
+
+# --- Local binary artifacts (accidental) ---
+/test_f32
+/test_f32_2
+/test_f32_res
+/test_arnoldi_f32
+/test_complex_scalar
+
+
+documentation/dev/Agent Bootstrap.md
+documentation/.obsidian/
+documentation/internals/CURRENT_MISSION.md
+4_Build wheels.txt
+
+# --- Local Build Artifacts ---
+.ccache/
+wheelhouse/
+tools/bin/
+event.json
+bin/
+tools/test_release_locally.sh
+
+# --- Stray artifacts (de-AI-ification) ---
+/_vals
+/_vecs
+/_codeql_detected_source_root
+/tmp_debug_cache/
+/.pycauset_stability/
+/tmp_verification_phase3_4/
+build_*/

pycauset-0.5.1.dev104/BENCHMARKS.md

@@ -0,0 +1,183 @@
+# PyCauset Benchmarks
+
+Measured performance of PyCauset against NumPy, for every operation that has a
+direct NumPy equivalent. These numbers are reproducible on your machine:
+
+```
+python benchmarks/bench.py --large
+python benchmarks/plot.py
+```
+
+## Methodology
+
+- **Hardware:** Intel Core i9-10850K (10 cores @ 3.6 GHz), 32 GB RAM, Windows 11.
+- **Versions:** NumPy 2.3.5 (OpenBLAS), PyCauset 0.5.1 (OpenBLAS 0.3.26).
+- **Timing:** `time.perf_counter`, best-of-N per operation (fewer repeats at large n).
+- **Dtype:** dense float64.
+- **Ratio:** `numpy_time / pycauset_time`. Values above 1.0x mean PyCauset is faster.
+
+## Dtype coverage (correctness)
+
+`benchmarks/bench_coverage.py` checks every operation against NumPy across all
+supported dtypes and classifies each cell as `ok`, `by-design` (documented error), or
+`WRONG`. Current status: every operation passes all its supported dtypes.
+
+| op | dtypes | result |
+|---|---|---|
+| matmul, add, norm, trace | 14 (bit + all int/uint + all float/complex) | all ok |
+| invert, solve, cholesky, svdvals, matrix_rank, determinant, eigvalsh | 4 (float32/64, complex64/128) | all ok |
+| matrix_power, outer | 6 (float/complex + int32/64) | all ok |
+
+## Structural shortcuts (instant metadata calculations)
+
+PyCauset stores semantic metadata on matrices (properties-as-gospel). When a matrix is
+marked as identity, diagonal, triangular, or zero, operations that would otherwise be
+O(n^3) reduce to O(1) or O(n) closed forms. Measured at n=800 (shortcut vs the general
+path on identical data, via `benchmarks/bench_structures.py`):
+
+| operation on a structured matrix | shortcut vs general | NumPy does |
+|---|---|---|
+| `matrix_rank(identity)` | 700x faster | full SVD |
+| `matrix_rank(diagonal)` | 126x faster | full SVD |
+| `matrix_rank(triangular)` | 157x faster | full SVD |
+| `norm(identity)` | 314x faster | full Frobenius pass |
+| `norm(diagonal)` | 734x faster | full Frobenius pass |
+| `determinant(identity/diagonal/triangular)` | 200-240x faster | LU |
+| `matrix_power(identity/zero)` | 200-240x faster | repeated matmul |
+| `invert(identity)` | 24x faster | LU |
+
+This is where PyCauset wins even though its dense kernels run at NumPy parity: a large
+identity or diagonal matrix gets an answer instantly instead of spending seconds on an
+SVD or LU factorization, and NumPy has no equivalent metadata shortcut at all.
+
+## Symmetric / anti-symmetric storage (2x smaller)
+
+`pycauset.symmetric(data)` and `pycauset.antisymmetric(data)` construct native
+`SymmetricMatrix` / `AntiSymmetricMatrix` objects that store only the upper triangle
+(including the diagonal), so an n x n float64 matrix costs roughly n(n+1)/2 elements
+instead of n^2. For large n this is about a 2x reduction in RAM and disk footprint,
+independent of the out-of-core threshold, and `to_numpy`/`save`/`load` reconstruct the
+full matrix on demand. Optimization of symmetric/antisymmetric kernels is part of the
+post-R1 program.
+
+## Summary
+
+PyCauset's dense kernels run on the same OpenBLAS/LAPACK backend as NumPy, so the
+realistic goal is parity, not a large speedup. At large sizes PyCauset matches or
+edges ahead of NumPy on matmul, eigenvalues, and Cholesky. The current gaps are SVD
+(about 2x, from the row-major transpose) and elementwise materialization, both tracked
+for the post-R1 program.
+
+## The reason to use PyCauset: it scales past RAM
+
+NumPy keeps every array in RAM, so a square float64 matrix is capped by memory: on a
+16 GB machine that is about 46340 x 46340 (16.2 GB), and beyond that NumPy raises
+`MemoryError`. PyCauset memory-maps to disk beyond a RAM budget, so its RAM usage is
+bounded by your threshold and the matrix can be far larger than RAM.
+
+| RAM budget | max n (NumPy) | PyCauset |
+|---|---|---|
+| 4 GB | 23170 x 23170 | unbounded (disk-backed) |
+| 8 GB | 32768 x 32768 | unbounded (disk-backed) |
+| 16 GB | 46340 x 46340 | unbounded (disk-backed) |
+| 32 GB | 65536 x 65536 | unbounded (disk-backed) |
+| 64 GB | 92681 x 92681 | unbounded (disk-backed) |
+
+Demonstration (run `python benchmarks/bench_ram.py`): a 12000 x 12000 float64 matrix is
+1.07 GB; NumPy holds all of it in RAM, while PyCauset with a 256 MB budget stores it on
+disk and still computes `trace(identity) = 12000` correctly. This is the regime where
+PyCauset does something NumPy cannot, which is the practical reason to use it even where
+NumPy is a bit faster on in-memory matrices.
+
+## Time vs n
+
+![matmul, inverse, solve](documentation/docs/assets/benchmarks/time_matmul_fact.png)
+
+![cholesky, eigh, svd](documentation/docs/assets/benchmarks/time_eigen_svd.png)
+
+![elementwise add, dot](documentation/docs/assets/benchmarks/time_elem_dot.png)
+
+## Speedup by operation
+
+![speedup by operation](documentation/docs/assets/benchmarks/speedup_by_op.png)
+
+## Dense float64 matmul (C = A @ B)
+
+| n | NumPy | PyCauset | speedup |
+|---|---|---|---|
+| 256 | 1.9ms | 4.0ms | 0.46x |
+| 512 | 7.2ms | 10.4ms | 0.69x |
+| 1024 | 32.5ms | 42.6ms | 0.76x |
+| 2048 | 173.7ms | 188.9ms | 0.92x |
+| 4096 | 968.9ms | 990.4ms | 0.98x |
+| 8192 | 6.11s | 5.92s | **1.03x** |
+
+Matmul crosses parity around n = 4096 and edges ahead at n = 8192. Small sizes carry
+fixed Python dispatch overhead.
+
+## Dense float64 factorizations
+
+| op | n | NumPy | PyCauset | speedup |
+|---|---|---|---|---|
+| inverse | 256 | 4.2ms | 4.9ms | 0.86x |
+| inverse | 512 | 12.4ms | 13.6ms | 0.92x |
+| inverse | 1024 | 66.8ms | 94.4ms | 0.71x |
+| inverse | 2048 | 348.3ms | 371.7ms | 0.94x |
+| inverse | 4096 | 1.71s | 2.22s | 0.77x |
+| solve | 256 | 1.4ms | 2.6ms | 0.54x |
+| solve | 512 | 6.0ms | 9.2ms | 0.65x |
+| solve | 1024 | 31.5ms | 40.2ms | 0.78x |
+| solve | 2048 | 190.8ms | 261.8ms | 0.73x |
+| solve | 4096 | 1.19s | 1.46s | 0.81x |
+| cholesky | 256 | 2.0ms | 2.8ms | 0.71x |
+| cholesky | 512 | 7.3ms | 9.4ms | 0.77x |
+| cholesky | 1024 | 35.4ms | 46.8ms | 0.75x |
+| cholesky | 2048 | 173.5ms | 165.9ms | **1.05x** |
+| cholesky | 4096 | 959.5ms | 1.01s | 0.95x |
+| svd | 256 | 19.2ms | 25.7ms | 0.75x |
+| svd | 512 | 67.2ms | 193.3ms | 0.35x |
+| svd | 1024 | 315.6ms | 541.3ms | 0.58x |
+| svd | 2048 | 2.42s | 4.74s | 0.51x |
+
+Inverse, solve, and Cholesky are competitive (0.7x to 1.05x). SVD now uses the same
+divide-and-conquer LAPACK routine (`gesdd`) as NumPy; the remaining roughly 2x gap is the
+row-major transpose overhead and is tracked for the post-R1 program.
+
+## Dense float64 eigenvalues
+
+| op | n | NumPy | PyCauset | speedup |
+|---|---|---|---|---|
+| eigh | 256 | 11.0ms | 13.0ms | 0.84x |
+| eigh | 512 | 46.7ms | 49.1ms | 0.95x |
+| eigh | 1024 | 157.8ms | 161.6ms | 0.98x |
+| eigh | 2048 | 840.4ms | 831.1ms | **1.01x** |
+| eigvalsh | 256 | 6.5ms | 7.6ms | 0.86x |
+| eigvalsh | 512 | 32.2ms | 33.8ms | 0.95x |
+| eigvalsh | 1024 | 107.9ms | 109.0ms | 0.99x |
+| eigvalsh | 2048 | 447.7ms | 465.4ms | 0.96x |
+
+Eigenvalue routines reach parity (0.95x to 1.01x) across the measured range.
+
+## Elementwise add and dot
+
+| op | n | NumPy | PyCauset | speedup |
+|---|---|---|---|---|
+| add | 1024 | 28.6ms | 51.3ms | 0.56x |
+| add | 2048 | 107.1ms | 193.0ms | 0.55x |
+| add | 4096 | 440.6ms | 811.4ms | 0.54x |
+| add | 8192 | 1.91s | 3.18s | 0.60x |
+| dot | 100000 | 0.087ms | 0.014ms | **6.21x** |
+| dot | 1000000 | 0.168ms | 0.210ms | 0.80x |
+| dot | 10000000 | 5.72ms | 6.05ms | 0.95x |
+
+Dot is at parity or faster (vectors are pre-constructed; the earlier gap was vector
+construction overhead, not the dot itself). Elementwise add remains below parity because
+the lazy-expression materialization path is not yet SIMD-optimized; it is a post-R1 target.
+
+## What this means
+
+- **Matmul, eigenvalues, Cholesky, and dot** match or beat NumPy at large sizes.
+- **Inverse and solve** are competitive, within 25% of NumPy.
+- **SVD** is roughly 2x slower (down from 25x after switching to `gesdd`); the row-major
+  overhead and elementwise add are the concrete targets for the post-R1
+  "greater than 0.90x NumPy" program (tracked in `TODO.md`).

pycauset-0.5.1.dev104/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to PyCauset are documented in this file. The project follows
+[Semantic Versioning](https://semver.org/). The documentation's **"Release 1 (R1)"**
+milestone corresponds to **v0.5.1**.
+
+## [Unreleased]: R1 (target v0.5.1)
+
+### Added
+- `pinv`: Moore-Penrose pseudoinverse (normal-equations baseline + NumPy SVD fallback).
+- `load_matrix(path)`: alias of `load`.
+- `svdvals`, `matrix_rank`, `matrix_power`, `outer`: NumPy-equivalent linalg
+  operations, each with structural shortcuts where a closed form exists (rank of
+  identity/diagonal/triangular, power of identity/zero/diagonal, norm of identity/zero).
+- `bitwise_and`, `bitwise_or`, `bitwise_xor`, `bitwise_nand`, `bitwise_nor`,
+  `bitwise_xnor`: elementwise logic operations on bit matrices/vectors, always returning
+  a bit structure (DenseBitMatrix/BitVector).
+- `cross`: 3D cross product.
+- `vecdot`: conjugate dot product (complex-aware inner product).
+- `symmetric(data)` and `antisymmetric(data)`: validated constructors for symmetric
+  (`A == A.T`) and anti-symmetric (`A == -A.T`) matrices. Float input produces a native
+  `SymmetricMatrix`/`AntiSymmetricMatrix` with packed upper-triangle storage (roughly 2x
+  smaller than dense); integer/bool input produces a dense matrix with
+  `is_symmetric`/`is_anti_symmetric` asserted (exact storage, no packing in R1).
+- `diagonal(data)`: constructs a `DiagonalMatrix` from a 1D vector of entries or a 2D
+  square matrix (extracting its diagonal).
+- Complete per-operation support-status registry (`OpRegistry`) now covering the vector
+  and vector-scalar ops (`dot`, `add_vector`, `subtract_vector`, `outer`, `add_scalar`,
+  `mul_scalar`) in addition to the matrix ops.
+- `LICENSE` (MIT) and `THIRD_PARTY_NOTICES.md` (Eigen MPL2, OpenBLAS BSD, pybind11 BSD,
+  googletest BSD, build-time deps, CUDA-not-bundled).
+- 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`).
+
+### Fixed
+- `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
+  understood`; identity matrices export as float64.
+- Structural shortcuts now trigger for native structural types: `matrix_rank` of an
+  `IdentityMatrix`/`DiagonalMatrix` uses a closed form instead of an SVD.
+- `SymmetricMatrix`/`AntiSymmetricMatrix` (present in the native core but previously
+  unreachable from Python) are now integrated end to end: recognized by the structure
+  system (no longer "general"), exported to NumPy without `TypeError: data type
+  'symmetric' not understood`, routed through a dense float64 fallback in `matmul`
+  (no longer `Unsupported matrix multiplication types`), and round-tripped by
+  `save()`/`load()` (no longer `Unknown matrix type: None`).
+- Documentation/export completeness: `dot`, `load`, `load_matrix`, `to_numpy`,
+  `set_export_max_bytes`, `CausalSet`, and `TriangularMatrix` were documented and
+  callable but missing from `__all__`, so `from pycauset import *` dropped them; they
+  are now exported. Reference pages were added for `cross`, `determinant`,
+  `matrix_power`, `matrix_rank`, `outer`, `qr`, `svdvals`, `trace`, `vecdot`, the six
+  `bitwise_*` ops, and `DiagonalMatrix`.
+- `CausalSpacetime` is documented at its real location (`pycauset.CausalSpacetime`, a
+  native abstract type with no R1 constructor/methods), not the non-existent
+  `pycauset.spacetime.CausalSpacetime`.
+- Dense `float64` `solve` and `lu` now route through LAPACK (`dgesv`/`dgetrf`) instead of
+  a naive scalar Gaussian elimination; this also made the float64 path consistent with the
+  float32 path and with NumPy's singularity behavior.
+- `matrix([[1+2j, …]])` (complex *list* input) now constructs a real complex matrix
+  (`ComplexFloat64Matrix`) instead of a broken abstract `Matrix` with no dtype.
+- `matrix(ndarray, backing_file=…)` no longer silently returns an in-memory matrix; it
+  raises a clear `TypeError` directing users to `save()`/`load()`.
+- SIMD kernels are baseline-safe: `-march=native` removed and per-function
+  `__attribute__((target(...)))` added, so built binaries no longer crash with an illegal
+  instruction on CPUs without AVX2/AVX-512.
+- Eigen decomposition correctness across a `save()`/`load()` round-trip is now pinned.
+
+### Changed
+- Integer overflow policy is now documented and explicit: elementwise integer arithmetic
+  wraps silently (C/NumPy two's-complement semantics), while `matmul` reductions raise
+  `OverflowError`. (Previously the docs promised "hard error everywhere" but only `matmul`
+  actually enforced it.)
+- `__all__` no longer star-exports internal native machinery (`LazyMatrix`, `lazy_*`,
+  `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.