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.
- mtl5-5.7.0/.github/workflows/ci.yml +120 -0
- mtl5-5.7.0/.github/workflows/release.yml +77 -0
- mtl5-5.7.0/.github/workflows/wheels.yml +112 -0
- mtl5-5.7.0/.gitignore +63 -0
- mtl5-5.7.0/CHANGELOG.md +105 -0
- mtl5-5.7.0/CLAUDE.md +69 -0
- mtl5-5.7.0/CMakeLists.txt +122 -0
- mtl5-5.7.0/LICENSE +21 -0
- mtl5-5.7.0/PKG-INFO +907 -0
- mtl5-5.7.0/README.md +874 -0
- mtl5-5.7.0/applications/heat_equation_1d.py +156 -0
- mtl5-5.7.0/applications/iterative_refinement.py +219 -0
- mtl5-5.7.0/applications/pandas_sensor_analysis.py +215 -0
- mtl5-5.7.0/applications/precision_showcase.py +186 -0
- mtl5-5.7.0/applications/quantized_inference.py +221 -0
- mtl5-5.7.0/applications/truss_analysis_2d.py +368 -0
- mtl5-5.7.0/config/TestMatrixDataDirConfig.hpp.in +4 -0
- mtl5-5.7.0/docs/designs/custom-dtype-feasibility.md +174 -0
- mtl5-5.7.0/docs/designs/multi-precision-type-dispatch.md +220 -0
- mtl5-5.7.0/docs/gap-analysis-2026-08.md +582 -0
- mtl5-5.7.0/docs/pypi-release.md +277 -0
- mtl5-5.7.0/docs/sessions/2026-08-05.md +142 -0
- mtl5-5.7.0/mtl5/__init__.py +660 -0
- mtl5-5.7.0/mtl5/io.py +102 -0
- mtl5-5.7.0/mtl5/pandas_ext.py +180 -0
- mtl5-5.7.0/mtl5/sparse/__init__.py +844 -0
- mtl5-5.7.0/mtl5/tensor.py +104 -0
- mtl5-5.7.0/notebooks/README.md +14 -0
- mtl5-5.7.0/notebooks/generators.ipynb +458 -0
- mtl5-5.7.0/pyproject.toml +106 -0
- mtl5-5.7.0/python/CMakeLists.txt +73 -0
- mtl5-5.7.0/python/include/mtl/math/quire_accumulator.hpp +207 -0
- mtl5-5.7.0/python/src/mtl5_complex.cpp +759 -0
- mtl5-5.7.0/python/src/mtl5_dense_factor.cpp +464 -0
- mtl5-5.7.0/python/src/mtl5_dense_ops.cpp +471 -0
- mtl5-5.7.0/python/src/mtl5_generators.cpp +293 -0
- mtl5-5.7.0/python/src/mtl5_io.cpp +171 -0
- mtl5-5.7.0/python/src/mtl5_krylov.cpp +411 -0
- mtl5-5.7.0/python/src/mtl5_mixed_precision.cpp +585 -0
- mtl5-5.7.0/python/src/mtl5_module.cpp +1587 -0
- mtl5-5.7.0/python/src/mtl5_multigrid.cpp +310 -0
- mtl5-5.7.0/python/src/mtl5_ndarray.cpp +574 -0
- mtl5-5.7.0/python/src/mtl5_sparse_direct.cpp +845 -0
- mtl5-5.7.0/python/src/mtl5_sparse_formats.cpp +322 -0
- mtl5-5.7.0/python/src/mtl5_sparse_refine.hpp +73 -0
- mtl5-5.7.0/python/src/mtl5_tensor.cpp +364 -0
- mtl5-5.7.0/python/src/mtl5_types.hpp +247 -0
- mtl5-5.7.0/python/src/mtl5_views.cpp +168 -0
- mtl5-5.7.0/tests/conftest.py +10 -0
- mtl5-5.7.0/tests/test_complex.py +551 -0
- mtl5-5.7.0/tests/test_dense_factor.py +305 -0
- mtl5-5.7.0/tests/test_dense_ops.py +346 -0
- mtl5-5.7.0/tests/test_generators.py +256 -0
- mtl5-5.7.0/tests/test_import.py +91 -0
- mtl5-5.7.0/tests/test_io.py +232 -0
- mtl5-5.7.0/tests/test_iterative_solvers.py +179 -0
- mtl5-5.7.0/tests/test_krylov_dispatch.py +315 -0
- mtl5-5.7.0/tests/test_linalg.py +213 -0
- mtl5-5.7.0/tests/test_matrix.py +124 -0
- mtl5-5.7.0/tests/test_mixed_precision.py +382 -0
- mtl5-5.7.0/tests/test_multigrid.py +347 -0
- mtl5-5.7.0/tests/test_ndarray.py +567 -0
- mtl5-5.7.0/tests/test_notebooks.py +93 -0
- mtl5-5.7.0/tests/test_pandas_ext.py +136 -0
- mtl5-5.7.0/tests/test_runtime_config.py +203 -0
- mtl5-5.7.0/tests/test_sparse.py +208 -0
- mtl5-5.7.0/tests/test_sparse_accumulator.py +269 -0
- mtl5-5.7.0/tests/test_sparse_direct.py +422 -0
- mtl5-5.7.0/tests/test_sparse_formats.py +284 -0
- mtl5-5.7.0/tests/test_tensor.py +290 -0
- mtl5-5.7.0/tests/test_universal.py +173 -0
- mtl5-5.7.0/tests/test_universal_types.py +151 -0
- mtl5-5.7.0/tests/test_vector.py +197 -0
- 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/
|
mtl5-5.7.0/CHANGELOG.md
ADDED
|
@@ -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()
|