mtl5 5.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. mtl5-5.7.0/.github/workflows/ci.yml +120 -0
  2. mtl5-5.7.0/.github/workflows/release.yml +77 -0
  3. mtl5-5.7.0/.github/workflows/wheels.yml +112 -0
  4. mtl5-5.7.0/.gitignore +63 -0
  5. mtl5-5.7.0/CHANGELOG.md +105 -0
  6. mtl5-5.7.0/CLAUDE.md +69 -0
  7. mtl5-5.7.0/CMakeLists.txt +122 -0
  8. mtl5-5.7.0/LICENSE +21 -0
  9. mtl5-5.7.0/PKG-INFO +907 -0
  10. mtl5-5.7.0/README.md +874 -0
  11. mtl5-5.7.0/applications/heat_equation_1d.py +156 -0
  12. mtl5-5.7.0/applications/iterative_refinement.py +219 -0
  13. mtl5-5.7.0/applications/pandas_sensor_analysis.py +215 -0
  14. mtl5-5.7.0/applications/precision_showcase.py +186 -0
  15. mtl5-5.7.0/applications/quantized_inference.py +221 -0
  16. mtl5-5.7.0/applications/truss_analysis_2d.py +368 -0
  17. mtl5-5.7.0/config/TestMatrixDataDirConfig.hpp.in +4 -0
  18. mtl5-5.7.0/docs/designs/custom-dtype-feasibility.md +174 -0
  19. mtl5-5.7.0/docs/designs/multi-precision-type-dispatch.md +220 -0
  20. mtl5-5.7.0/docs/gap-analysis-2026-08.md +582 -0
  21. mtl5-5.7.0/docs/pypi-release.md +277 -0
  22. mtl5-5.7.0/docs/sessions/2026-08-05.md +142 -0
  23. mtl5-5.7.0/mtl5/__init__.py +660 -0
  24. mtl5-5.7.0/mtl5/io.py +102 -0
  25. mtl5-5.7.0/mtl5/pandas_ext.py +180 -0
  26. mtl5-5.7.0/mtl5/sparse/__init__.py +844 -0
  27. mtl5-5.7.0/mtl5/tensor.py +104 -0
  28. mtl5-5.7.0/notebooks/README.md +14 -0
  29. mtl5-5.7.0/notebooks/generators.ipynb +458 -0
  30. mtl5-5.7.0/pyproject.toml +106 -0
  31. mtl5-5.7.0/python/CMakeLists.txt +73 -0
  32. mtl5-5.7.0/python/include/mtl/math/quire_accumulator.hpp +207 -0
  33. mtl5-5.7.0/python/src/mtl5_complex.cpp +759 -0
  34. mtl5-5.7.0/python/src/mtl5_dense_factor.cpp +464 -0
  35. mtl5-5.7.0/python/src/mtl5_dense_ops.cpp +471 -0
  36. mtl5-5.7.0/python/src/mtl5_generators.cpp +293 -0
  37. mtl5-5.7.0/python/src/mtl5_io.cpp +171 -0
  38. mtl5-5.7.0/python/src/mtl5_krylov.cpp +411 -0
  39. mtl5-5.7.0/python/src/mtl5_mixed_precision.cpp +585 -0
  40. mtl5-5.7.0/python/src/mtl5_module.cpp +1587 -0
  41. mtl5-5.7.0/python/src/mtl5_multigrid.cpp +310 -0
  42. mtl5-5.7.0/python/src/mtl5_ndarray.cpp +574 -0
  43. mtl5-5.7.0/python/src/mtl5_sparse_direct.cpp +845 -0
  44. mtl5-5.7.0/python/src/mtl5_sparse_formats.cpp +322 -0
  45. mtl5-5.7.0/python/src/mtl5_sparse_refine.hpp +73 -0
  46. mtl5-5.7.0/python/src/mtl5_tensor.cpp +364 -0
  47. mtl5-5.7.0/python/src/mtl5_types.hpp +247 -0
  48. mtl5-5.7.0/python/src/mtl5_views.cpp +168 -0
  49. mtl5-5.7.0/tests/conftest.py +10 -0
  50. mtl5-5.7.0/tests/test_complex.py +551 -0
  51. mtl5-5.7.0/tests/test_dense_factor.py +305 -0
  52. mtl5-5.7.0/tests/test_dense_ops.py +346 -0
  53. mtl5-5.7.0/tests/test_generators.py +256 -0
  54. mtl5-5.7.0/tests/test_import.py +91 -0
  55. mtl5-5.7.0/tests/test_io.py +232 -0
  56. mtl5-5.7.0/tests/test_iterative_solvers.py +179 -0
  57. mtl5-5.7.0/tests/test_krylov_dispatch.py +315 -0
  58. mtl5-5.7.0/tests/test_linalg.py +213 -0
  59. mtl5-5.7.0/tests/test_matrix.py +124 -0
  60. mtl5-5.7.0/tests/test_mixed_precision.py +382 -0
  61. mtl5-5.7.0/tests/test_multigrid.py +347 -0
  62. mtl5-5.7.0/tests/test_ndarray.py +567 -0
  63. mtl5-5.7.0/tests/test_notebooks.py +93 -0
  64. mtl5-5.7.0/tests/test_pandas_ext.py +136 -0
  65. mtl5-5.7.0/tests/test_runtime_config.py +203 -0
  66. mtl5-5.7.0/tests/test_sparse.py +208 -0
  67. mtl5-5.7.0/tests/test_sparse_accumulator.py +269 -0
  68. mtl5-5.7.0/tests/test_sparse_direct.py +422 -0
  69. mtl5-5.7.0/tests/test_sparse_formats.py +284 -0
  70. mtl5-5.7.0/tests/test_tensor.py +290 -0
  71. mtl5-5.7.0/tests/test_universal.py +173 -0
  72. mtl5-5.7.0/tests/test_universal_types.py +151 -0
  73. mtl5-5.7.0/tests/test_vector.py +197 -0
  74. mtl5-5.7.0/tests/test_views.py +222 -0
@@ -0,0 +1,120 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ jobs:
10
+ lint:
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - uses: actions/checkout@v5
14
+ - uses: actions/setup-python@v5
15
+ with:
16
+ python-version: "3.12"
17
+ # Pinned deliberately. Unpinned, a ruff release retroactively fails every
18
+ # open PR for reasons unrelated to the change under review — 0.16 began
19
+ # formatting Python blocks inside Markdown, which turned two untouched
20
+ # design docs red. Bump this on purpose, in its own commit.
21
+ - run: pip install ruff==0.16.1
22
+ - run: ruff check .
23
+ - run: ruff format --check .
24
+
25
+ build-and-test:
26
+ strategy:
27
+ fail-fast: false
28
+ matrix:
29
+ include:
30
+ # Linux
31
+ - os: ubuntu-22.04
32
+ python: "3.10"
33
+ compiler: gcc
34
+ - os: ubuntu-22.04
35
+ python: "3.11"
36
+ compiler: gcc
37
+ - os: ubuntu-22.04
38
+ python: "3.12"
39
+ compiler: gcc
40
+ - os: ubuntu-22.04
41
+ python: "3.12"
42
+ compiler: clang
43
+ # macOS
44
+ - os: macos-14
45
+ python: "3.10"
46
+ - os: macos-15
47
+ python: "3.12"
48
+ # Windows
49
+ - os: windows-2022
50
+ python: "3.10"
51
+ - os: windows-2022
52
+ python: "3.12"
53
+
54
+ runs-on: ${{ matrix.os }}
55
+
56
+ steps:
57
+ - uses: actions/checkout@v5
58
+
59
+ - uses: actions/setup-python@v5
60
+ with:
61
+ python-version: ${{ matrix.python }}
62
+
63
+ - name: Set up Clang (Linux)
64
+ if: matrix.compiler == 'clang'
65
+ run: |
66
+ sudo apt-get update
67
+ sudo apt-get install -y clang-15
68
+ echo "CC=clang-15" >> $GITHUB_ENV
69
+ echo "CXX=clang++-15" >> $GITHUB_ENV
70
+
71
+ - name: Install package
72
+ # matplotlib comes from the notebooks extra; tests/test_notebooks.py
73
+ # executes every notebook so the docs cannot rot, and skips without it.
74
+ run: pip install ".[dev,notebooks]" -v
75
+
76
+ - name: Run tests
77
+ run: pytest -v
78
+
79
+ ecosystem-test:
80
+ runs-on: ubuntu-22.04
81
+ steps:
82
+ - uses: actions/checkout@v5
83
+ - uses: actions/setup-python@v5
84
+ with:
85
+ python-version: "3.12"
86
+ - name: Install with all optional dependencies
87
+ run: |
88
+ pip install ".[dev,notebooks]" -v
89
+ pip install pandas scikit-learn
90
+ # torch and jax are large; install CPU-only variants
91
+ pip install torch --index-url https://download.pytorch.org/whl/cpu
92
+ pip install "jax[cpu]"
93
+ - name: Run all tests
94
+ run: pytest -v
95
+
96
+ # The .gz Matrix Market path is compiled in only with MTL5_WITH_ZLIB, which is
97
+ # off by default for portability. Without this lane that code would ship with
98
+ # no coverage — tests/test_io.py::TestGzip skips itself when the flag is off.
99
+ zlib-test:
100
+ runs-on: ubuntu-22.04
101
+ steps:
102
+ - uses: actions/checkout@v5
103
+ with:
104
+ persist-credentials: false
105
+ - uses: actions/setup-python@v5
106
+ with:
107
+ python-version: "3.12"
108
+ - name: Install zlib headers
109
+ run: sudo apt-get update && sudo apt-get install -y zlib1g-dev
110
+ - name: Install package with zlib enabled
111
+ run: pip install ".[dev,notebooks]" -v -C cmake.define.MTL5_WITH_ZLIB=ON
112
+ - name: Confirm zlib was actually compiled in
113
+ # From a neutral directory: at the repo root, `python -c` puts cwd on
114
+ # sys.path and imports the source `mtl5/` package, which has no compiled
115
+ # _core. pytest is unaffected because it inserts tests/, not the root.
116
+ working-directory: ${{ runner.temp }}
117
+ run: |
118
+ python -c "import mtl5, sys; ok = mtl5.build_info()['zlib']; print('zlib:', ok); sys.exit(0 if ok else 1)"
119
+ - name: Run the I/O tests
120
+ run: pytest tests/test_io.py -v
@@ -0,0 +1,77 @@
1
+ name: Release
2
+
3
+ # Triggered on push to main after CI passes.
4
+ # python-semantic-release analyzes conventional commits since the last tag,
5
+ # determines if a version bump is needed, updates pyproject.toml, creates
6
+ # a git tag, and publishes a GitHub Release.
7
+ #
8
+ # Versioning policy:
9
+ # - mtl5-python follows MTL5's major.minor version (currently 5.2.x)
10
+ # - semantic-release only manages the PATCH component
11
+ # - feat: and fix: commits both trigger a patch bump
12
+ # - Major/minor bumps are manual to align with MTL5 upstream releases
13
+
14
+ on:
15
+ push:
16
+ branches: [main]
17
+
18
+ permissions:
19
+ contents: write # push tags and create releases
20
+ id-token: write # trusted publishing (future PyPI)
21
+
22
+ jobs:
23
+ release:
24
+ runs-on: ubuntu-latest
25
+ # Only run if CI passed (release depends on the CI workflow)
26
+ concurrency:
27
+ group: release
28
+ cancel-in-progress: false
29
+
30
+ steps:
31
+ - uses: actions/checkout@v5
32
+ with:
33
+ fetch-depth: 0 # full history needed for commit analysis
34
+ token: ${{ secrets.GITHUB_TOKEN }}
35
+
36
+ - uses: actions/setup-python@v5
37
+ with:
38
+ python-version: "3.12"
39
+
40
+ - name: Install python-semantic-release
41
+ run: pip install python-semantic-release
42
+
43
+ - name: Run semantic-release
44
+ env:
45
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
46
+ run: semantic-release version --no-push --no-vcs-release --skip-build
47
+
48
+ - name: Check if version was bumped
49
+ id: check
50
+ run: |
51
+ if git diff --name-only | grep -q pyproject.toml; then
52
+ echo "bumped=true" >> "$GITHUB_OUTPUT"
53
+ else
54
+ echo "bumped=false" >> "$GITHUB_OUTPUT"
55
+ fi
56
+
57
+ - name: Commit, tag, and push
58
+ if: steps.check.outputs.bumped == 'true'
59
+ run: |
60
+ VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
61
+ git config user.name "github-actions[bot]"
62
+ git config user.email "github-actions[bot]@users.noreply.github.com"
63
+ git add pyproject.toml
64
+ git commit -m "chore(release): v${VERSION}"
65
+ git tag "v${VERSION}"
66
+ git push origin main --tags
67
+
68
+ - name: Create GitHub Release
69
+ if: steps.check.outputs.bumped == 'true'
70
+ run: |
71
+ VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
72
+ gh release create "v${VERSION}" \
73
+ --title "v${VERSION}" \
74
+ --generate-notes \
75
+ --latest
76
+ env:
77
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -0,0 +1,112 @@
1
+ name: Build wheels
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+ workflow_dispatch:
7
+
8
+ jobs:
9
+ build-wheels:
10
+ strategy:
11
+ matrix:
12
+ os: [ubuntu-22.04, macos-14, windows-2022]
13
+ runs-on: ${{ matrix.os }}
14
+ steps:
15
+ - uses: actions/checkout@v5
16
+
17
+ - uses: actions/setup-python@v5
18
+ with:
19
+ python-version: "3.12"
20
+
21
+ - name: Install cibuildwheel
22
+ run: pip install cibuildwheel
23
+
24
+ - name: Build wheels
25
+ run: cibuildwheel --output-dir wheelhouse
26
+ env:
27
+ # 64-bit only. cibuildwheel's default "auto" archs still include the
28
+ # 32-bit win32 target on Windows, and this C++20 / nanobind / Highway
29
+ # extension has no 32-bit toolchain or deps, so that target fails the
30
+ # build (observed: cp310-win32 exit code 1). auto64 selects just the
31
+ # native 64-bit arch per platform: AMD64 on Windows, x86_64 on Linux,
32
+ # arm64 on the macos-14/15 runners. (Linux i686 was already dropped
33
+ # from "auto" in cibuildwheel 3.0, so it is not a factor here.)
34
+ CIBW_ARCHS: "auto64"
35
+ CIBW_BUILD: "cp310-* cp311-* cp312-*"
36
+ CIBW_SKIP: "*-musllinux*"
37
+ CIBW_TEST_REQUIRES: pytest numpy scipy
38
+ CIBW_TEST_COMMAND: pytest {project}/tests -v
39
+
40
+ - uses: actions/upload-artifact@v5
41
+ with:
42
+ name: wheels-${{ matrix.os }}
43
+ path: wheelhouse/*.whl
44
+
45
+ build-sdist:
46
+ runs-on: ubuntu-latest
47
+ steps:
48
+ - uses: actions/checkout@v5
49
+ - uses: actions/setup-python@v5
50
+ with:
51
+ python-version: "3.12"
52
+ - run: pip install build
53
+ - run: python -m build --sdist
54
+ - uses: actions/upload-artifact@v5
55
+ with:
56
+ name: sdist
57
+ path: dist/*.tar.gz
58
+
59
+ # Publish every built wheel + the sdist to PyPI. Runs only for a real
60
+ # published Release, never for the workflow_dispatch build smoke-tests.
61
+ #
62
+ # Auth: Trusted Publishing (OIDC) — no secrets to store or rotate. This repo
63
+ # lives on github.com, so PyPI's OIDC trusts these runners directly. (The
64
+ # `git@github.sw:` origin is only an SSH-config alias whose HostName is
65
+ # github.com, selecting a specific key — NOT a GitHub Enterprise host.) A
66
+ # matching trusted publisher must be registered on PyPI
67
+ # (owner/repo/workflow=wheels.yml/environment=pypi). See docs/pypi-release.md.
68
+ publish-pypi:
69
+ needs: [build-wheels, build-sdist]
70
+ runs-on: ubuntu-latest
71
+ if: github.event_name == 'release'
72
+ environment: pypi # optional manual-approval gate; configure in repo settings
73
+ permissions:
74
+ id-token: write # mint the OIDC token PyPI verifies; no password needed
75
+ steps:
76
+ - name: Gather wheels and sdist into dist/
77
+ uses: actions/download-artifact@v5
78
+ with:
79
+ path: dist
80
+ merge-multiple: true # flatten wheels-*/ and sdist/ into a single dir
81
+
82
+ - name: Publish to PyPI
83
+ uses: pypa/gh-action-pypi-publish@release/v1
84
+ with:
85
+ packages-dir: dist
86
+
87
+ # Dry-run lane: publish the same artifacts to TestPyPI. Runs ONLY on a manual
88
+ # workflow_dispatch, so a real Release never lands here and a dispatch never
89
+ # touches production PyPI. Uses the TestPyPI trusted publisher (registered
90
+ # with environment=pypi, same as production — the two are separate per-index
91
+ # registrations). skip-existing lets a re-run at an unchanged version succeed
92
+ # instead of 400-ing on a duplicate. See docs/pypi-release.md §4.
93
+ publish-testpypi:
94
+ needs: [build-wheels, build-sdist]
95
+ runs-on: ubuntu-latest
96
+ if: github.event_name == 'workflow_dispatch'
97
+ environment: pypi
98
+ permissions:
99
+ id-token: write
100
+ steps:
101
+ - name: Gather wheels and sdist into dist/
102
+ uses: actions/download-artifact@v5
103
+ with:
104
+ path: dist
105
+ merge-multiple: true
106
+
107
+ - name: Publish to TestPyPI
108
+ uses: pypa/gh-action-pypi-publish@release/v1
109
+ with:
110
+ packages-dir: dist
111
+ repository-url: https://test.pypi.org/legacy/
112
+ skip-existing: true
mtl5-5.7.0/.gitignore ADDED
@@ -0,0 +1,63 @@
1
+ # Prerequisites
2
+ *.d
3
+
4
+ # Compiled Object files
5
+ *.slo
6
+ *.lo
7
+ *.o
8
+ *.obj
9
+
10
+ # Precompiled Headers
11
+ *.gch
12
+ *.pch
13
+
14
+ # Linker files
15
+ *.ilk
16
+
17
+ # Debugger Files
18
+ *.pdb
19
+
20
+ # Compiled Dynamic libraries
21
+ *.so
22
+ *.dylib
23
+ *.dll
24
+
25
+ # Fortran module files
26
+ *.mod
27
+ *.smod
28
+
29
+ # Compiled Static libraries
30
+ *.lai
31
+ *.la
32
+ *.a
33
+ *.lib
34
+
35
+ # Executables
36
+ *.exe
37
+ *.out
38
+ *.app
39
+
40
+ # debug information files
41
+ *.dwo
42
+
43
+ # Python
44
+ __pycache__/
45
+ *.py[cod]
46
+ *.egg-info/
47
+ dist/
48
+ build/
49
+ wheelhouse/
50
+ *.whl
51
+ .eggs/
52
+
53
+ # Build directories
54
+ _skbuild/
55
+ _cmake_test_compile/
56
+
57
+ # IDE
58
+ .vscode/
59
+ .idea/
60
+
61
+ # Virtual environments
62
+ .venv/
63
+ venv/
@@ -0,0 +1,105 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
5
+
6
+ Release sections below the marker are generated by python-semantic-release from
7
+ conventional commits; the `Unreleased` section above it is maintained by hand,
8
+ because a list of commit subjects does not say *why* a binding refuses input it
9
+ could have accepted. Both are kept.
10
+
11
+ Versioning: the **minor** component tracks the MTL5 release this is built
12
+ against, and semantic-release manages only the **patch** component.
13
+
14
+ ## [Unreleased]
15
+
16
+ Closes epic #21 — the binding gap against MTL5 v5.7.0. Every module the
17
+ 2026-08-01 gap analysis inventoried is now reachable from Python, taking the
18
+ surface from roughly 14 numerical entry points to over 150.
19
+
20
+ ### Added
21
+
22
+ - **Mixed precision** — `accumulator=` on `dot`, `norm`, `frobenius_norm`,
23
+ `matvec` and `matmul`; `convert`, `lu_iterative_refine`, `backward_error` and
24
+ sparse `iterative_refine`. Accumulating 4000 posit16 products is bit-exact
25
+ with the quire against 1.8 × 10⁻¹ unaccumulated.
26
+ - **Sparse direct solvers** — `splu`, `klu`, `cholesky`, `ldlt`, `qr`,
27
+ `supernodal_lu`, `supernodal_ldlt`, with the analyze/factor/refactor split,
28
+ plus AMD/COLAMD/RCM orderings.
29
+ - **Accumulator policy on the sparse factorizations** — a float32 factor can
30
+ accumulate its updates in float64. Paired with iterative refinement on an
31
+ ill-conditioned matrix: 4 iterations to 1.4 × 10⁻¹⁰ instead of 6 to
32
+ 2.0 × 10⁻⁹.
33
+ - **Dense completeness** — QR, LQ, LDLᵀ, Bunch–Kaufman; the eigen and SVD
34
+ family; BLAS level 2/3; 28 property predicates.
35
+ - **Complex element types** — `c64`/`c128` containers, norms, Hermitian `dot`
36
+ and `dot_real`, products, `solve`/`lu`/`inv`, `transpose`/`adjoint`/`conj`,
37
+ QR/LQ with least squares, Hermitian Cholesky, and `ldlt_solve` dispatching
38
+ between LDLᵀ and LDLᴴ.
39
+ - **Sparse storage formats** — COO and ELL alongside CSR, with `padding_ratio`
40
+ to decide whether ELL fits, and a native transpose-SpMV so a SciPy
41
+ `LinearOperator` no longer round-trips through scipy.
42
+ - **N-dimensional arrays** (`mtl5.array`) — ranks 1–4, zero-copy in both
43
+ directions with strides, slicing, reductions, and interop with the dense
44
+ containers.
45
+ - **Krylov solvers and preconditioners** — 10 solvers and 8 preconditioners in
46
+ any combination, via a type-erased preconditioner: 20 template instantiations
47
+ rather than the 160 the cross product would have cost.
48
+ - **Smoothers and multigrid** (`mtl5.mg`) — seven smoothers, grid transfer, a
49
+ sparse `galerkin` product, and a hierarchy builder. About 0.03 residual
50
+ reduction per V-cycle on 1-D Poisson, holding as the problem grows.
51
+ - **Matrix views** (`mtl5.view`) — eight views, materialised rather than
52
+ aliasing.
53
+ - **Tensor algebra** (`mtl5.tensor`) — fixed-dimension containers, Einstein
54
+ contraction with runtime index strings, outer products, metric raise/lower,
55
+ packed symmetric storage.
56
+ - **Test matrices, I/O and build** — 25 generators with prescribed spectra,
57
+ Matrix Market read/write, `spy` PNGs with no plotting stack, and all five
58
+ MTL5 acceleration options wired through.
59
+
60
+ ### Changed
61
+
62
+ - `mtl5.sparse.cg`, `gmres` and `bicgstab` keep their signatures and gain a
63
+ working `M=`, which previously raised `NotImplementedError` and pointed at
64
+ scipy.
65
+ - The accumulated norms now call `mtl::two_norm<Acc, Result>` directly. They
66
+ went through local sum-of-squares loops until upstream added the `Result`
67
+ parameter, without which `accumulator=` was unobservable from Python.
68
+
69
+ ### Fixed
70
+
71
+ Seven defects were found in MTL5 and reported; all seven were fixed upstream and
72
+ the workarounds retired. Six returned a wrong answer while reporting success:
73
+
74
+ | upstream | defect |
75
+ |---|---|
76
+ | [#352](https://github.com/stillwater-sc/mtl5/issues/352) | `ldlt` gave a wrong solution for a Hermitian complex matrix with `info = 0` |
77
+ | [#353](https://github.com/stillwater-sc/mtl5/issues/353) | complex `cholesky` and `qr` did not compile |
78
+ | [#355](https://github.com/stillwater-sc/mtl5/issues/355) | `compressed2D` accepted `tag::col_major` and ignored it, transposing CSC input |
79
+ | [#359](https://github.com/stillwater-sc/mtl5/issues/359) | `ndarray` reshape and flatten returned memory order for F-contiguous input |
80
+ | [#379](https://github.com/stillwater-sc/mtl5/issues/379) | the norms had no `Result` parameter, so the accumulator was unobservable |
81
+ | [#392](https://github.com/stillwater-sc/mtl5/issues/392) | `bicg` computed `rho` from the wrong vectors and worked only unpreconditioned |
82
+ | [#401](https://github.com/stillwater-sc/mtl5/issues/401) | `mg/multigrid.hpp` was not self-contained |
83
+
84
+ ### Notes for callers
85
+
86
+ Some inputs are refused that a caller might expect to work. Each is deliberate
87
+ and load-bearing:
88
+
89
+ - `bicg` and `qmr` refuse a non-symmetric preconditioner. They are the only
90
+ solvers applying Mᵀ, and MTL5 implements a preconditioner's adjoint as its
91
+ forward solve — exact when M is symmetric, a breakdown otherwise.
92
+ - `refactor()` on `splu`, `klu` and `supernodal_lu` refuses when a non-default
93
+ accumulator is in effect, rather than silently reverting to element precision.
94
+ - `mtl5.view.banded` refuses a negative bandwidth (the parameters are counts,
95
+ not signed diagonal offsets) and `mtl5.view.hermitian` a non-real diagonal.
96
+ - `mtl5.array.asarray` requires an exact dtype match; converting would return a
97
+ view of a temporary, which is neither zero-copy nor the dtype requested.
98
+ - There is no CSC. MTL5 has no column-major sparse container, so `from_scipy`
99
+ converts at the boundary.
100
+
101
+ Two operations differ from NumPy on purpose: `dot` on complex is Hermitian
102
+ (`numpy.vdot`, not `numpy.dot` — `dot_real` is the latter), and `.T` does not
103
+ conjugate, `.H` does.
104
+
105
+ <!-- version list -->
mtl5-5.7.0/CLAUDE.md ADDED
@@ -0,0 +1,69 @@
1
+ # CLAUDE.md
2
+
3
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+ ## Project Overview
6
+
7
+ **mtl5-python** is a nanobind-based Python module providing zero-copy interop between Python's scientific/ML ecosystem and MTL5 (Mathematics Template Library v5, a C++ library by Stillwater Supercomputing, Inc.).
8
+
9
+ Target ecosystem: NumPy, SciPy, JAX, PyTorch, pandas, scikit-learn.
10
+
11
+ Key capabilities:
12
+ - Zero-copy array interop via `nb::ndarray` (NumPy, PyTorch, JAX)
13
+ - Custom Universal number type dtypes (posit16, posit32) registered across NumPy, PyTorch, and pandas
14
+ - Dense/sparse linear algebra solvers exposed to Python with hardware accelerator dispatch
15
+ - SciPy sparse matrix interop and LinearOperator protocol
16
+
17
+ ## Build and Test Commands
18
+
19
+ ```bash
20
+ # Install (builds C++ extension via scikit-build-core + CMake)
21
+ pip install .
22
+
23
+ # Install in development mode with test dependencies
24
+ pip install -e ".[dev]"
25
+
26
+ # Run all tests
27
+ pytest
28
+
29
+ # Run a single test file
30
+ pytest tests/test_vector.py
31
+
32
+ # Run a single test
33
+ pytest tests/test_vector.py::TestNorm::test_l2_norm -v
34
+
35
+ # Lint
36
+ pip install ruff
37
+ ruff check .
38
+ ruff format --check .
39
+ ```
40
+
41
+ ## Architecture
42
+
43
+ - **nanobind** (not pybind11) for C++ → Python bindings — smaller binaries, faster compilation, first-class `nb::ndarray` multi-framework support
44
+ - **MTL5 C++ headers** (C++20, header-only) fetched via CMake FetchContent from stillwater-sc/mtl5
45
+ - **scikit-build-core** as PEP 517 backend for `pip install` support
46
+ - CMake option `MTL5_ENABLE_PYTHON=ON` (default ON) to build the module
47
+ - The nanobind extension module is `mtl5/_core.so`, re-exported via `mtl5/__init__.py`
48
+
49
+ ### Key source files
50
+
51
+ - `python/src/mtl5_module.cpp` — nanobind `NB_MODULE` entry point, all C++ bindings
52
+ - `python/CMakeLists.txt` — nanobind module build target, links against MTL5 headers
53
+ - `CMakeLists.txt` — top-level CMake, fetches MTL5 and nanobind via FetchContent
54
+ - `mtl5/__init__.py` — Python package, re-exports from `_core`
55
+
56
+ ### MTL5 C++ types used in bindings
57
+
58
+ | Python | C++ | Header |
59
+ |---|---|---|
60
+ | `mtl5.DenseVector` | `mtl::vec::dense_vector<double>` | `<mtl/vec/dense_vector.hpp>` |
61
+ | `mtl5.DenseMatrix` | `mtl::mat::dense2D<double>` | `<mtl/mat/dense2D.hpp>` |
62
+ | `mtl5.norm()` | `mtl::one_norm`, `mtl::two_norm`, `mtl::infinity_norm` | `<mtl/operation/norms.hpp>` |
63
+ | `mtl5.dot()` | `mtl::dot` | `<mtl/operation/dot.hpp>` |
64
+ | `mtl5.solve()` | `mtl::lu_factor` + `mtl::lu_solve` | `<mtl/operation/lu.hpp>` |
65
+
66
+ ## Repository
67
+
68
+ - Remote: `git@github.sw:stillwater-sc/mtl5-python`
69
+ - Branch: `main`
@@ -0,0 +1,122 @@
1
+ cmake_minimum_required(VERSION 3.22)
2
+ project(mtl5_python CXX)
3
+
4
+ set(CMAKE_CXX_STANDARD 20)
5
+ set(CMAKE_CXX_STANDARD_REQUIRED ON)
6
+
7
+ # MSVC: report correct __cplusplus value so that C++20 headers like <bit>
8
+ # are properly detected by Universal's bit_cast.hpp
9
+ if(MSVC)
10
+ add_compile_options(/Zc:__cplusplus)
11
+ endif()
12
+
13
+ option(MTL5_ENABLE_PYTHON "Build Python bindings" ON)
14
+
15
+ # ---------------------------------------------------------------------------
16
+ # MTL5 acceleration options
17
+ #
18
+ # Every MTL5_WITH_*/MTL5_NATIVE_* option defaults to OFF upstream, which
19
+ # compiles out MTL5's entire native performance path — mtl::mult falls back to
20
+ # the generic scalar kernel and get_backend() can only ever report "reference".
21
+ # We declare the same option names here so the cache entry exists before MTL5's
22
+ # own option() runs, which lets us pick wheel-appropriate defaults while still
23
+ # honouring an explicit -D on the command line.
24
+ #
25
+ # MTL5_NATIVE_FAST_GEMM and MTL5_WITH_HIGHWAY are ON together, and that pairing
26
+ # is not optional. The blocked GEMM pays a packing cost that only pays off once
27
+ # the micro-kernel is actually vectorised, and mtl::simd falls back to a
28
+ # scalar batch (lane count 1) unless Highway is present. Measured here,
29
+ # double-precision matmul, GCC -O3, single thread, no -march=native:
30
+ #
31
+ # config n=200 n=600 n=1000
32
+ # both OFF (status quo) 3.51 GF/s 2.67 GF/s 2.15 GF/s
33
+ # fast GEMM alone 0.79 GF/s 0.79 GF/s 0.79 GF/s <- 3.4x SLOWER
34
+ # fast GEMM + Highway 12.63 GF/s 14.40 GF/s 14.66 GF/s <- 5.5-6.8x faster
35
+ #
36
+ # Highway is fetched at a pinned version, is Apache-2.0/BSD-3-Clause, and uses
37
+ # STATIC dispatch — one ISA chosen by the compiler flags. With no -march that
38
+ # is the x86-64 baseline, which is what the numbers above measure, so the
39
+ # result is still a portable binary.
40
+ #
41
+ # MTL5_NATIVE_FAST_GEMM ON — blocked GEMM / SIMD GEMV. if-constexpr gated to
42
+ # dense contiguous float/double, so int/posit/
43
+ # fixpnt/lns still take the generic path.
44
+ # MTL5_WITH_HIGHWAY ON — vectorises that kernel. See the table above for
45
+ # what happens if you turn this off on its own.
46
+ # MTL5_WITH_BLAS OFF — needs a BLAS on the build machine.
47
+ # MTL5_WITH_LAPACK OFF — needs LAPACK; enables geev/syev/gesdd dispatch,
48
+ # which the Phase 3 eigen/SVD bindings will want.
49
+ # MTL5_NATIVE_ARCH OFF — -march=native lets Highway target AVX2/AVX-512
50
+ # instead of the baseline, but the binary then
51
+ # only runs on machines like the build host.
52
+ # Worth enabling for a local build, never for a
53
+ # distributed wheel.
54
+ #
55
+ # Override at install time, e.g.:
56
+ # pip install . -C cmake.define.MTL5_WITH_BLAS=ON \
57
+ # -C cmake.define.MTL5_WITH_LAPACK=ON
58
+ # ---------------------------------------------------------------------------
59
+ option(MTL5_NATIVE_FAST_GEMM "Route mtl::mult through MTL5's blocked GEMM / SIMD GEMV" ON)
60
+ option(MTL5_WITH_HIGHWAY "Use Google Highway as the mtl::simd backend" ON)
61
+ option(MTL5_WITH_BLAS "Link an external BLAS for dense acceleration" OFF)
62
+ option(MTL5_WITH_LAPACK "Link LAPACK (enables geev/syev/gesdd dispatch)" OFF)
63
+ option(MTL5_NATIVE_ARCH "Tune for the host CPU (-march=native; non-portable)" OFF)
64
+
65
+ if(MTL5_NATIVE_FAST_GEMM AND NOT MTL5_WITH_HIGHWAY)
66
+ message(WARNING
67
+ "MTL5_NATIVE_FAST_GEMM=ON with MTL5_WITH_HIGHWAY=OFF is slower than "
68
+ "turning both off: the blocked GEMM pays its packing cost but mtl::simd "
69
+ "falls back to a scalar batch, so the micro-kernel never vectorises "
70
+ "(measured ~3.4x slower than the generic kernel). Enable "
71
+ "MTL5_WITH_HIGHWAY, or set MTL5_NATIVE_FAST_GEMM=OFF as well.")
72
+ endif()
73
+
74
+ # --- MTL5 (header-only) ---
75
+ find_package(MTL5 QUIET)
76
+ if(NOT MTL5_FOUND)
77
+ include(FetchContent)
78
+ # Suppress MTL5's own tests, examples, and install targets
79
+ set(MTL5_BUILD_TESTS OFF CACHE BOOL "" FORCE)
80
+ set(MTL5_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
81
+ set(MTL5_BUILD_REGRESSION_TESTS OFF CACHE BOOL "" FORCE)
82
+ FetchContent_Declare(
83
+ mtl5
84
+ GIT_REPOSITORY https://github.com/stillwater-sc/mtl5.git
85
+ GIT_TAG main
86
+ GIT_SHALLOW TRUE
87
+ EXCLUDE_FROM_ALL
88
+ )
89
+ FetchContent_MakeAvailable(mtl5)
90
+ endif()
91
+
92
+ # --- Universal number library (header-only) ---
93
+ # Provides cfloat<nbits,es>, posit<nbits,es>, and other custom number types
94
+ find_package(universal QUIET)
95
+ if(NOT universal_FOUND)
96
+ include(FetchContent)
97
+ set(BUILD_ALL_LIBS OFF CACHE BOOL "" FORCE)
98
+ set(BUILD_DEMONSTRATION OFF CACHE BOOL "" FORCE)
99
+ set(BUILD_NUMBERS OFF CACHE BOOL "" FORCE)
100
+ set(BUILD_NUMERICS OFF CACHE BOOL "" FORCE)
101
+ set(BUILD_BENCHMARKS OFF CACHE BOOL "" FORCE)
102
+ set(BUILD_TESTS OFF CACHE BOOL "" FORCE)
103
+ set(BUILD_REGRESSION_SUITES OFF CACHE BOOL "" FORCE)
104
+ set(BUILD_CMD_LINE_TOOLS OFF CACHE BOOL "" FORCE)
105
+ set(BUILD_EDUCATION OFF CACHE BOOL "" FORCE)
106
+ set(BUILD_APPLICATIONS OFF CACHE BOOL "" FORCE)
107
+ set(BUILD_PLAYGROUND OFF CACHE BOOL "" FORCE)
108
+ set(BUILD_VALIDATION_HW OFF CACHE BOOL "" FORCE)
109
+ set(BUILD_C_API_LIB OFF CACHE BOOL "" FORCE)
110
+ FetchContent_Declare(
111
+ universal
112
+ GIT_REPOSITORY https://github.com/stillwater-sc/universal.git
113
+ GIT_TAG main
114
+ GIT_SHALLOW TRUE
115
+ EXCLUDE_FROM_ALL
116
+ )
117
+ FetchContent_MakeAvailable(universal)
118
+ endif()
119
+
120
+ if(MTL5_ENABLE_PYTHON)
121
+ add_subdirectory(python)
122
+ endif()