Changelog
All notable changes to MTL5 are documented in this file. Format follows Conventional Commits.
[Unreleased]
Section titled “[Unreleased]”-
Zero-copy overlay examples (#834).
examples/zero_copy/shows MTL5 vectors and matrices laid over buffers the application owns, so MTL5 algorithms run on the buffer in place. The walkthrough isdocs/examples/zero-copy-overlay.md.ode_rhs_callback.cpp: a C-style RK4 integrator callsrhs(t, const double* y, double* dydt, ...). The callback computesdydt = L ywithvec::const_viewandmultinto the integrator’s buffer, checks the heat-equation solution, and times copy-in/copy-out against it: 3.2× slower on an i7-12700K at n = 2·10⁶.shared_frame_pipeline.cpp: a producer and a processing thread share double-buffered frames, corrected in place through adense2Dover each frame andndarrayslices over its tiles.zero_copy_rules.cpp: the contract, one checked demonstration per rule.- CTest runs all three. Each exits non-zero if a buffer is copied or a check fails.
-
Read-only vector and matrix views over a caller’s const buffer (
tag::read_only).vec::const_view(n, ptr)andmat::const_view(rows, cols, ptr)take aconst Value*and return adense_vectorordense2Dthat reads the buffer in place, so a callback such as an ODE integrator’srhs(t, const double* y, double* dydt)needs noconst_castand no copy (#834).- Writing through a view does not compile: element writes,
data(),begin(), assignment, compound assignment,change_dim,swapandvec::fillare all constrained away. - It works with the existing operations: a view is still a
dense_vector<V, P>ordense2D<V, P>, so norms,dot,A * x(dense andcompressed2D),mult, the expression templates and the Krylov solvers accept it, as the new tests show. - Aliases and overloads:
vec::const_vector_view<V, Orientation>andmat::const_matrix_view<V, Orientation>name the types.const_view(v)gives a read-only view of an existing vector or matrix; the rvalue overload is deleted, since a view of a temporary would dangle. - Copy semantics: copying a view gives another view of the same buffer.
dense_vector<double> y(view)anddense2D<double> M(view)make owning copies; that conversion isexplicit(#855), so a view passed to a by-value parameter no longer deep-copies silently. - Tests:
tests/unit/vec/test_const_view.cppandtests/unit/mat/test_const_view.cpp.
- Writing through a view does not compile: element writes,
-
Run-time selection of the interleave width (#778). With
MTL5_INTERLEAVE_RUNTIME(CMake option, off by default), the genericgemv,trmvand forward substitution compile at W = 2, 4, 6, 8 and 12 for float and double, and on first use take the width a table of the #780 sweeps lists for the compiler and the core (include/mtl/interface/interleave_runtime.hpp). The core is read from x86cpuidor the Arm part number in/proc/cpuinfo.- Fallbacks: a CPU or compiler the table doesn’t list, an x86-64 build with AVX, and any
MTL5_INTERLEAVE_ROWS*override orinterleave_rowsspecialization keep the compile-time width. - Results are bit-identical whichever width runs.
op_test_interleave_runtimeforces each width withforce_interleave_rowsand compares it with the one-row loop. - Measured with the table in place, worst kernel against its fastest width (fixed default in brackets): i7-12700K 1.007 under GCC (1.044) and 1.007 under Clang (1.094); Jetson Orin 1.000 (1.128); Ventuno Q 1.000 under both compilers (1.000). The Xeon’s and the Ryzens’ entries come from their 2026-11-11 sweeps and are still to be measured.
- Costs: a file calling all three kernels for both types compiles 0.5–0.9 s slower, and the dispatch adds under 1% per call at n = 64, except 1–3.4% on the Ventuno under GCC (
bench_interleave_dispatch).bench_interleave_rowsnow prints the run-time choice and its distance from the fastest. Seedocs/benchmarks/interleave-width.md.
- Fallbacks: a CPU or compiler the table doesn’t list, an x86-64 build with AVX, and any
-
Two Ventuno Q sessions with native-fast on the cores’ own features (#806).
benchmarks/data/arduino-ventuno-q/mtl5_bench/20261113T170450Zand20261113T174232Z, atbf315e4(after #819), every check passed, 780 of 824 entries within ±5% between them; the card moves to the pair.- The quad integer gemm:
gemm_quadi8>i32 at 512³ takes 3.68 ms on one core, 6.4× the baseline-Armv8 build and 4.5× faster than the plain i8 gemm, where it was 30% slower. The u8i8 pairing, still emulated without I8MM, gains 3.8×; the 8-bit dots 2.8–3.4×. - native-fast’s Gauss–Seidel smoother took 1.9× the generic build’s time on baseline Armv8.0-a and now matches it.
- Nothing else moves beyond the run-to-run spread: GEMM and the factorizations are unchanged.
- Pages corrected: the Ventuno and Jetson pages had the two boards’ build ISAs the wrong way round. The Jetson’s 3.9× quad gemm is the native
SDOTpath; the Ventuno’s builds before #819 were baseline Armv8.0-a.
- The quad integer gemm:
-
Platform sessions on the Jetson Orin and the Ventuno Q after #811, with CHOLMOD on ARM (#805, #810). Two cold-boot sessions per board at
967d20a, every check passed:benchmarks/data/jetson-orin/mtl5_bench/20261113T131507Zand20261113T140622Z,benchmarks/data/arduino-ventuno-q/mtl5_bench/20261113T131507Zand20261113T135246Z. Both cards move to the new pairs; the analysis pages keep their 2026-11-11 figures and add a section for these sessions.- The Ventuno’s threaded LU (#805):
factor/luf64 512×512 in native-fast takes 24.7 ms on one thread and 17.2 ms on four, 1.4× faster; on 2026-11-11 four threads took 109 ms. LQ, Hessenberg, the inverse and the mixed-precision refinement, all slower on four threads then, are now 1.16–1.75× faster; QR’s gain grows from 1.26× to 1.70×. - The Ventuno’s first OpenBLAS column:
gemmat 89% of the FMA peak on one core, native-fast at 64% of it. - CHOLMOD on ARM (#810): on the 3D grid MTL5’s supernodal LDLᵀ takes 3.6× CHOLMOD’s time on the Jetson and 4.8× on the Ventuno (6.1× on the i7), and on the 2D grid it matches CHOLMOD.
docs/benchmarks/direct-solver-references.mdhas an AArch64 section. - The Jetson’s CHOLMOD is 3.7–5.7× slower on six threads than on one. A diagnostic run traces it to OpenBLAS 0.3.20’s threading on that board; MTL5’s thread pool and #811’s spin make no difference.
- Both boards confirm #804’s fix in a session: native-fast column-major
gemvtakes 12.9 ms (Jetson) and 7.73 ms (Ventuno) on one core, against 50.1 and 49.2 ms on 2026-11-11.
- The Ventuno’s threaded LU (#805):
-
The sparse direct solvers against CHOLMOD and PARDISO: an i7-12700K session pair and an analysis page (#810).
docs/benchmarks/direct-solver-references.mdreads the direct-solver entries of two pinned sessions,benchmarks/data/i7-12700k/mtl5_bench/20261113T055208Zand20261113T060838Z(at8867b44, every check passed, 1-thread direct entries within ±2% of each other but two).- The 2D grid caps everyone: even PARDISO reaches only 7.5–8.8% of peak in the factorization, so the old 0.02–1.7% was partly the problem.
- The 3D grid (20³) does not: CHOLMOD and PARDISO reach 35–41% of peak. MTL5’s supernodal LDLᵀ takes 7.2× PARDISO’s time, its supernodal LU 35× (slower than its plain LU), and the up-looking
sparse_cholesky768×. - Analysis is close: MTL5’s COLAMD-based LU analysis is about 2× faster than PARDISO’s. In 3D, the solves are 2.8× (Cholesky) and 7.1× (LU) behind.
- Threads: PARDISO’s 3D factorization is 4.1× faster on 8 cores; MTL5’s direct solvers gain at most 8%.
- A direct-only roofline (
roofline-direct.svg), the card now on the new pair, and the i7 page’s #804 note updated: in these sessions native-fast column-majorgemvtakes 3.45 ms, against 4.70 ms generic and 3.61 ms OpenBLAS.
-
mtl5_bench: the direct solvers one phase at a time, on a 3D grid too, with CHOLMOD and MKL PARDISO beside them (#810). Thedirectentries ran at 0.02–1.7% of the roofline, and nothing measured on the same problem said how much of that was MTL5.-
Phase entries (
benchmarks/platform/entries_direct.hpp):sparse_cholesky,supernodal_ldlt,sparse_luandsupernodal_lueach get.analyze(ordering and symbolic),.factorand.solve. The earlier phases run untimed, and every check is the backward error of a full solve. -
A 3D grid, area
direct3d: the 7-point Laplacian and convection-diffusion at 10³, 20³ and 24³ for the three classes. A 2D grid leaves only small supernodes; this one doesn’t. The one-shot entries are unchanged, so earlier cards stay comparable. -
References, with
-DMTL5_BENCH_REFERENCES=ON, whichplatform.sh’s andplatform.ps1’sblasvariant now sets:ref_cholmod: CHOLMOD, supernodal L Lᵀ, AMD.ref_pardiso_spdandref_pardiso_lu: MKL PARDISO,mtype2 and 11, minimum degree.
Each has a one-shot entry and phase entries on both grids, and takes the run’s thread count.
-
No MKL link.
mtl5_benchloadslibmkl_rtwithdlopen(RTLD_LOCAL), so MKL’s BLAS symbols cannot displace the BLAS the build chose for every other entry. CHOLMOD is visible tomtl5_benchonly. -
Skipped entries: where a library is missing, its entries are listed as skipped with the reason, on the card (“Skipped in this build”), in the JSON (
"skipped") and on the console. The registry gainsskip(). -
First numbers, i7-12700K, one thread, 20³ factorization:
sparse_cholesky7.35 s andsupernodal_ldlt66.6 ms, against 11.5 ms for CHOLMOD and 9.6 ms for PARDISO;sparse_lu538 ms andsupernodal_lu625 ms, against 19.0 ms for PARDISO’s LU. -
Fix: the direct solvers’ check passed an all-NaN solution.
backward_errortook its maxima withstd::max, which drops a NaN, so the residual and |x| both stayed 0 and the error was 0. A nonfinite x now fails the check. -
CI: the
vendorsbenchmarks build compiles the reference entries. -
plot_roofline.py:direct3dgets its own colour, appended so every earlier area keeps its colour; reference entries are diamonds;--areaskeeps only the named areas.
-
-
benchmarks/publish_platform.cmakepublishes anmtl5_benchplatform session (#758, #737). Copying aplatform.sh/platform.ps1results directory into the repository by hand left the raw JSON behind and produced card pages the docs site didn’t know about.- Running it:
cmake -DRESULTS=<results dir> -DMACHINE=<systems.md name> -P benchmarks/publish_platform.cmake. It needs only CMake, so it runs on the machine that made the session, Windows included. - What it checks first:
- every run’s JSON (
mtl5-bench/1), sidecar and card are present; - all runs are one commit and one class;
- no check failed, and no run was built from a dirty tree. Either can be overridden, and the page then says so.
- every run’s JSON (
- What it writes:
- It copies the session to
benchmarks/data/<machine>/mtl5_bench/<UTC session>/. That directory is append-only: republishing identical files is a no-op, and different files under an existing session are refused. These files are what stillwater-sc/mtl5-python#121 ingests. - It writes the card page
docs/benchmarks/<machine>-mtl5-bench.md: a provenance table, then the session’s cards. The page shows the latest session. - It registers the page in the site’s
FILE_MAP. - It links the page from
docs/benchmarks/systems.md: the machine’s “mtl5_bench card” cell becomes[Card](<machine>-mtl5-bench.md), marked(preliminary)when the page is. Before, it only warned, and the cell had to be edited by hand. Its first version failed on every publish under CMake 3.x, the versions on the Linux and Windows runners, which broke the platform smoke job there: a trailing-blank regex,[ \t]*$, matched an empty string, which CMake before 4.x rejects. It now strips with[ \t]+$, and runs under CMake 3.22, the script’s declared minimum.
- It copies the session to
- CI: the platform smoke job now publishes its session into the runner’s checkout on all four OSes, then checks the files, the page, the sidecars, and that a second publish is a no-op. It takes the session it checks from the results directory’s name (#763), because once a real i7-12700K session was committed, listing the data directory returned two.
- Docs:
benchmarks/README.mdhas a “Publishing a session” section.
- Running it:
-
Benchmark data: the first four
mtl5_benchsessions are in the repository (#760, #762, #764, #765, #737). Each was published withpublish_platform.cmakeand is marked preliminary: unpinned cores, no clock policy, one session. All four are classmedium.- Ryzen 7 2700X:
benchmarks/data/ryzen-7-2700x/mtl5_bench/20261108T223729Z/, built ate096dbbc6788. - Ryzen 9 8945HS:
benchmarks/data/ryzen-9-8945hs/mtl5_bench/20261108T231039Z/, built at685e2711d5ff. - i7-12700K:
benchmarks/data/i7-12700k/mtl5_bench/20261109T025123Z/, built ate7497e6e4c47. Its threaded runs used 20 threads, E-cores included, though the Systems table lists 8 P-cores for this machine. - Xeon E5-2420 v2:
benchmarks/data/xeon-e5-2420v2/mtl5_bench/20261109T035023Z/, built at73d11400a0e3. - Each card page (
docs/benchmarks/<machine>-mtl5-bench.md) now links its raw data, and each machine’s Systems-table row links its card.
- Ryzen 7 2700X:
-
Each per-machine analysis has a roofline plot of its platform session (#799).
benchmarks/plot_roofline.py <session dir> --out <image>places every entry at its arithmetic intensity and measured GFLOP/s, against each run’s own bandwidth slope and f64 and f32 FMA ceilings, with the points coloured by area.- The grid: one row per thread count (1 thread, then all threads) and one column per build, all on the same axes. The generic
nativebuild is the baseline a straightforward implementation gives,native-fastthe best MTL5 does, and theblasbuild, with OpenBLAS and its LAPACK behind the dense kernels, the target.--variantspicks the columns, and a variant the session didn’t run is left out and named in the title (the Ventuno Q has no OpenBLAS). - What it leaves out: integer entries, because the model has no integer ceiling, and the 28 entries that record no flops or bytes (Krylov solvers, preconditioners, orderings, sparse eigensolvers). That leaves 74 of the 111 entries in each panel.
- What the plots show:
- The memory-bound entries sit on the slope in every column.
- Level 3 is where the builds separate. On one core, GEMM goes from 17% of peak to 90% to 92% on the i7-12700K, and from 33% to 60% to 94% on the Jetson Orin.
- The factorizations and eigensolvers rise only in the OpenBLAS column, where LAPACK takes them.
- The elementwise transcendentals sit far under the slope, because the model counts one flop per element.
- Pages: the Jetson Orin, Ventuno Q, i7-12700K and Ryzen 9 8945HS analyses, under a new Roofline section, with the command under Reproducing.
- The grid: one row per thread count (1 thread, then all threads) and one column per build, all on the same axes. The generic
-
Tensors and the follow-ups of dense2D aliasing (issue 857, from QA sweep #832).
contractrequires exactly one shared index, and none repeated within a tensor, at compile time. With two shared, it summed over the first:contract(A(i,j), B(i,j))with A = {1,2,3,4}, B = I gave [1 3; 2 4].bindof a temporary is deleted (it dangled).- Bounds:
tensor’s access checks each index against Dim underbounds_checking, not the flat offset (t(0,3)of a 3x3 tensor aliasedt(1,0));symmetric_tensorandantisymmetric_tensorcheck too, where they checked nothing. An initializer list longer than the tensor throwsstd::invalid_argumentin every build (an assert, then a buffer overrun). - Generic numbers:
frobenius_normsums |t_i|^2 and returns the magnitude type, so it is a norm for complex tensors;trace,identity,set_to_zero,contractand the metrics usemath::zero/math::one. The unusedzero_val_is gone, andfrom_fulldocuments that it truncates for integers. - Expression assignment: a sparse or block operand whose storage
for_each_storage_rangelists (compressed2D, ell_matrix, coordinate2D, block_diagonal2D, block_matrix_view) goes in place unless that storage overlaps the target’s. It always took a dense temporary.rows * colsis the exact span of adata()leaf: dense2D, the only one with a leading dimension, has no padding. - Tests: a new
test_tensor_edges.cpp(per-index bounds, list length, transposed contraction patterns, complex norm, the untested arithmetic, symmetric and antisymmetric operations, rank 0 and dimension 1, the rank-4 outer product, 3-D metrics,is_symmetricwith a tolerance), compile-fail tests for a two-index contraction and a bound temporary, andtest_expr_alias_followups.cpp(dense2D<float> += trans(A), a fixed-size target,A -= A * A, sparse operands in place and over the target’s storage,swap_rowsandmap_viewindex checks).
-
Dense factorizations: Hermitian factors in the real solves, NaN pivots, singular refinement, qr_solve’s shape, trsm with alpha = 0 (issue 854, from QA sweep #848).
cholesky_solverejects a complex factor at compile time, pointing atcholesky_h_solve, ascholesky_factordoes (#353). It applied L^T where a Hermitian factor needs L^H: for [[4, 1+2i], [1−2i, 6]] the residual was 2.0 against 2e-16.ldlt_solvekeeps complex factors: LDL^T of a complex symmetric matrix is supported (#352), and its documentation now says that a factor fromldlt_h_factorneedsldlt_h_solve.- A NaN pivot stops
ldlt_factor,ldlt_h_factor,ldlt_bk_factorandlu_factor, reported as the step’s index like a zero one (detail::pivot_unusable, !(|p| > 0)). Onlyp == 0was tested, so [[NaN, 1], [1, 2]] returned 0 with NaN in D and L. On the LAPACK path,getrfflags only exact zeros, solu_factorchecks U’s diagonal after it. lu_iterative_refinethrowsstd::runtime_errorwhen the Working-precision factor is singular or overflows to a NaN pivot; it went on to divide by the zero pivot and returned inf/NaN withconverged = false.qr_solvethrowsstd::invalid_argumentfor m < n (it read past row m: anout_of_range, or UB without bounds checks) and for vectors of the wrong size;invthrows for a non-square matrix.trsmwith alpha = 0 sets B to zero without reading it, on every path, as BLAS defines it; the generic paths turned a NaN or Inf in B into NaN.- Performance:
qr_extract_Qapplies reflector j to Q’s columns j onward only (the others are untouched by it): bit-identical, fewer products (296 ms againstqr_factor’s 220 ms at 600 x 600 before).ldlt_bk_factor’s trailing update runs by rows on row-major storage, where it strided by n (3.1x slower thanldlt_factorat n = 1200); each entry gets the same update, so the factor agrees with the column-major one to rounding (bit for bit unless the compiler contracts the two loop shapes into fmas differently). - Tests: a new
test_factorization_edges.cpp(NaN pivots on every factorization and path, singular and overflowing working factors, tallqr_solveagainst the normal equations and its shape checks,qr_extract_Q’s Q R = A and orthogonality, singular, empty and 1x1 LU andinv, both orientations, tall LQ,trsmwith alpha = 0, row- and column-major Bunch-Kaufman agreeing to rounding); a compile-fail test for complexcholesky_solve.
-
Eigensolvers, SVD and Givens rotations (issue 853, from QA sweep #848).
- Complex Givens rotations are unitary.
math::givens_rotationtook the real formula over complex numbers, r = sqrt(a·a + b·b), a complex square: (1, i) gave r = 0 and the identity, (1+i, 1−i) gave r = 0 for |r| = 2. It now follows LAPACK’szlartg(real c, s = (a/|a|)·conj(b)/d, r with a’s phase), scaled like the real case, andapply_givens_rotation/apply_stored_rotationapply [c s; −conj(s) c]. Complex GMRES, which solved the wrong least-squares problem, converges. Real rotations are bit-identical. eigenvalue()andeigen()scale A by a power of two, asschur()does (now a shareddetail::scale_to_unit_binade). A 4x4 matrix scaled by 1e-170 or 1e-200 gave eigenvalues off by about 0.7; at 1e±250 the iteration failed to converge. The LAPACK path was right, so the paths disagreed.eigen()’s in-house path is O(n³): the real Schur form, then each eigenvector by back-substitution on it (LAPACKdtrevc’s recurrence), v = Q y. It factored a fresh complex n x n matrix per eigenvalue, O(n⁴): 0.38 s at n = 160.- Non-convergence throws
std::runtime_errorin the nativeeigenvalue_symmetricandeigen_symmetric(max_iter),eigen_symmetric_jacobi(max_sweeps) and the SVD’s one-sided Jacobi (60 sweeps), aseigenvalue(),schur()and the LAPACK paths (#851) do. They returned the unconverged values. - Checked in every build: a non-square A to
eigenvalue,eigen,eigenvalue_symmetric,eigen_symmetric,eigen_symmetric_jacobi,hessenbergandhessenberg_factor, and a NaN or infinite entry to the eigensolvers andsvd, throwstd::invalid_argument(detail/matrix_checks.hpp). They were asserts, or reached the iteration. On the LAPACK paths a NaN or Inf used to surface as thestd::runtime_errorof a failedsyev,heevorgesdd, and a 1x1[Inf]came back as{Inf}; both are now thisstd::invalid_argument. - Tests: a new
test_givens.cpp(complex rotations, zero arguments, the GMRES helpers); complex GMRES; a newtest_eigen_robustness.cpp(scaling at 1e±170..1e±250 on the in-house and default paths, in-houseeigenresiduals, independence and pairing, non-convergence, NaN/Inf and non-square input).
- Complex Givens rotations are unitary.
-
ndarray: one iteration order, checked preconditions, reductions, broadcast lifetimes, views (issue 856, from QA sweep #832).
- One logical order per array: its own
Order. Anf_orderarray iterated first-index-fastest when contiguous and last-index-fastest when not, soflatten,reduceandfor_each_elementdepended on the strides.iterate_indicesand the strided paths now follow the array’sOrder, soflatten(a)matchesa.reshape({a.size()})(#359).c_orderarrays are unchanged. - Checked in every build:
reshapeto another size and a shape list of the wrong length throwstd::invalid_argument(underNDEBUG, a 3-element array reshaped to 100 elements was a view past its buffer).sliceclamps arangeto the extent as NumPy does, throws for step 0 (a division by zero) and for an integer index out of range.as_vectorandas_matrixthrow for a strided array, andsum_axisfor an axis ≥ N.slice()of a rank-0 array compiles. - Reductions:
sumandprodstart frommath::zero/math::one.minandmaxstart from the first element, so a type withoutnumeric_limitsis right (it gotV()= 0).min,max,meanandmean_axisthrow on an empty array or axis (they returnedDBL_MAX,-DBL_MAX, NaN, or divided an integer by zero). They,transformandflattencompile for read-only arrays and return the unqualified type. broadcast_exprstores a temporary operand by value, somake_arr() + bandauto e = a.transpose() + bno longer dangle;operator[]honoursbounds_checking.reshapeandtransposeof a const array return read-only views; they returned mutable ones through aconst_cast.- Assignment and views (decided on issue 856):
- An owning
ndarray,dense_vectorordense2Dmove-assigned a view or an external-buffer object copies the elements and stays owning.own = std::move(view)andown = a.transpose()used to makeowna view of another buffer. - A move of another size into a non-owning object aborts with a message in every build (
detail::contract_abort). It asserted, and underNDEBUGre-pointed the object at the source’s storage. Death tests cover the vector, the matrix and the ndarray view.
- An owning
- Faster strided paths: for_each_element, fill, copies,
transform,sum_axisandbroadcast_expr::evalwalk strides with an odometer and a plain inner loop (detail_nd::walk_offsets), with no per-element index array or bounds check. Contiguity ignores the stride of an extent-1 dimension, as NumPy does. Two views of one layout, such as two columns, are tested for a shared element exactly, soa(all, 0) = a(all, 1)no longer copies through a temporary. - Tests: the cases above,
f_ordercontent throughflatten,reduce,sum_axis,transform,sliceand broadcasting; copies oftranspose,reshapeand nested views; broadcast-and/; compound assignment through a view,flat,fillon a strided view, size-1 strides;std::complexarrays.
- One logical order per array: its own
-
Matrix Market reading, aliased products, and the follow-ups of QA sweep #848 (issue 855).
- Duplicates past
m*n: a coordinate file whosennzexceeds the matrix’s capacity, with its entries summed (#653), was rejected by #843’s header check (1 1 3with three entries threw; it reads as 6 again). A coordinate file whoserows * colsoverflowssize_tis read bymm_read(mm_read_densestill rejects it). The reserve stays capped by the file’s size. - Parsing:
+-5parsed as -5 and is rejected now, for floating-point and integer fields. Thestrto*path, taken wherestd::from_charslacks floating point and for out-of-range values, refuses hexadecimal floats, so it accepts whatfrom_charsdoes. A generic value type is value-initialized before it is read. - gzip: lines are split from
gzreadchunks instead of withgzgets, which cut a line at an embedded NUL byte and dropped the rest. The NUL now reaches the parser, which rejects it. - Aliased products:
mult(A, B, C),mult_quad,symvand theblock_matrix_viewmat-vec compute through a temporary, in every build, when the output shares storage with an input, as the mat-vecmultdoes since #840. They were debug-only asserts that saw only the same object:mult(A, B, A)on a 3x3dense2D<double>underNDEBUGdiffered in all 9 entries. storage_overlapsalso sees acoordinate2D’s triplets, each block of ablock_diagonal2D, and ablock_matrix_view’s encoded bytes (newbytes()).- A
compressed2D_inserterthat inserts nothing costs O(1) and leaves the matrix as it was. The slots are set up on the firstins[r]; before, every inserter paid O(nrows * slot_size + nnz), so many small inserters on a large matrix were quadratic. - Tests: the cases above;
parse_float_strtocalled directly;mm_read_denseon coordinate skew-symmetric and Hermitian files;mult(A, B, A)in both orientations and for float, throughtrans(A)and with an Accumulator; a C over part of A;mult(A, x, x)with a column-major A, float, andtrans(A); read-only views as does-not-compile checks;mat::const_viewof column-major, Fortran-index and fixed-size matrices;signum<bool>. The gemv tail test compares with astd::fmachain instead ofsimd::scalar_fma, the function the tail calls.
- Duplicates past
-
UMFPACK, KLU and SuperLU bindings: a leak, release-build asserts, empty matrices, and float sparse dispatch (#850, from the QA sweep #774).
- UMFPACK leaked its Numeric object on a singular matrix:
umfpack_di_numericreports a singular A as a warning (status 1) with a valid Numeric, and the constructor freed only the Symbolic before throwing (536 bytes under LeakSanitizer for a 3x3). Both are freed now, and the message says the matrix is singular. - UMFPACK checked squareness and the x and b sizes with
assertonly: a release build read out of bounds on a 3x4 A. These now throwstd::invalid_argumentin every build, as KLU, CHOLMOD and SuperLU do.umfpack_solvergains move assignment,num_rows()andnum_cols(); a moved-from solver’ssolve()throwsstd::logic_error. - 0x0 matrices:
umfpack_solverandklu_solverthrew, since the libraries reject n = 0. They now return an empty solver whosesolve()takes empty vectors, as CHOLMOD and SPQR do;superlu_solverhandles it the same way. - KLU status:
klu_solvernow checkscommon.statusafterklu_factorandklu_solve, and names a singular matrix in the message. With KLU’s defaulthalt_if_singulara singular A already threw (KLU returns a null Numeric), so the sweep’s “reports success” case did not reproduce; the check covers a non-null Numeric withKLU_SINGULAR. - n or nnz above
INT_MAXnow throwsstd::length_errorin all three bindings, as CHOLMOD and SPQR do, instead of wrapping in theintconversion. - Sparse dispatch with float or other vectors did not compile with the SuiteSparse bindings on:
lu_solve_dispatch,cholesky_solve_dispatchandqr_solve_dispatchsent every float or doublecompressed2Dto UMFPACK, CHOLMOD or SPQR, which takedoubleanddense_vector<double>only. The newinterface::suitesparse_solve_dispatches_v<M, X, B>routes only those operands to the libraries; everything else takes the native solvers. An underdetermined system throwsstd::invalid_argumenton both QR paths. - Tests: every binding is now tested on an unsymmetric matrix, so a transposed CRS-to-CCS conversion would fail (
test_klu.cpp’s “unsymmetric” case used a symmetric matrix).test_umfpack.cppadds singular, non-square, size-mismatch, move, 0x0 and 1x1 cases.test_klu.cppadds singular, 0x0 and 1x1. The newtest_superlu.cppcovers reuse,factor_nnz, singular, non-square, move, 0x0 and 1x1.test_unified_dispatch.cppadds float and mixed-vector dispatch. Not tested: theINT_MAXchecks, since a matrix that large takes 16 GB. - CI: the two Linux LAPACK jobs now build with UMFPACK and KLU, so these tests run against the libraries; before this, no unit-test job turned either on.
- UMFPACK leaked its Numeric object on a singular matrix:
-
LAPACK
eigenvalue_symmetricand fullsvdon empty input, andsyev/heevfailures (#849, from the QA sweep #774).- 0x0
eigenvalue_symmetric: the real (syev) branch called LAPACK withlda = 0. LAPACK rejects that argument, and its error handler prints the bad parameter and ends the process. The branch now returns an empty vector, as the complex (heev) branch already did. - Empty full
svd(A, U, S, V): a 0x0 or an m x 0 A ended the process the same way, ingesdd. An empty A now skips LAPACK and gets what the generic path returns: identity U and V, and an m x n S. syevandheevinfo codes: both were ignored, so a NaN or Inf in A came back as NaN eigenvalues.eigenvalue_symmetricnow throwsstd::runtime_errorwith the code on any non-zero info, assvdandeigenvaluedo. A NaN or Inf usually gives one (info = 2 on a 3x3, reference LAPACK and OpenBLAS), but not always:syevcopies a 1x1 A to the result without iterating, so[Inf]still returns{Inf}.- Untested wrappers:
lapack::getrs,potrs,orgqrandtrtrs, andblas::copy, had no caller in the library or the tests.blas::asumandblas::iamaxare new wrappers over the?asumandi?amaxexterns, which had none.tests/unit/interface/test_lapack_wrappers.cppchecks each one in float and double. - Tests:
test_lapack_dispatch.cppgains the emptyeigenvalue_symmetricandsvdcases, which ended the test binary before the fix with LAPACK on, and the NaN and Inf cases, which returned NaN.test_trmv_trsv_interleaved.cppruns its bit-identity checks onnative_shim, on atransposed_viewand onlower_trisolve(L, x, x).test_mult_generic_mt.cppadds a threaded double GEMV whose bands start inside an interleave block.
- 0x0
-
Test-matrix generators: Kahan conditioning,
forsythe(1),make_sigma(0), Wilkinson sizes, the Rosser spectrum, reproducible random generators (#844, from the QA sweep #789).kahanwas not ill-conditioned. Its diagonal was s^i · 25 rather than s^i, which gave κ₁ = 2.1 for n = 10. It now follows MATLAB’sgallery('kahan', n, theta, pert): K = diag(s^i)·(I − c·triu(ones, 1)) + pert·ε·diag(n, …, 1). The third parameter, formerlyzeta, is now MATLAB’spert, still defaulting to 25. κ₁ is now 92 for n = 10 and 2.9e5 for n = 30.forsythe(1)returned alpha, because the corner write landed on the diagonal. It now returns [lambda].randsvd,randsymandrandspdwith n = 0 and a kappa wrotesigma[0]out of bounds underNDEBUG. They now return an empty matrix.wilkinson(n)follows MATLAB for any n ≥ 1, so an even n gets the half-integer diagonalabs(-(n-1)/2 : (n-1)/2). UnderNDEBUGan even n used to build a wrong matrix, and n = 0 wrapped. n = 0 now throwsstd::invalid_argument, and so does an even n with an integer value type.rosser’s documented eigenvalues listed 1020 twice and lacked 510 − 100√26, so they summed to 5059.9 instead of the trace 4040. The header and the docs now give the true spectrum.- Reproducible random generators:
fill_random,random_vector,random_matrix,randorth,randsvd,randsymandrandspdgain astd::uint64_tseed overload and astd::mt19937_64&overload.- The draws come from the raw engine stream, as in
gen_dotandgen_sum, so a seed gives the same values with libstdc++, libc++ and MSVC. Each value is formed with an explicitfma, so the compiler’s contraction setting cannot change its rounding. - Calls without a seed stay non-deterministic, seeded from
std::random_device. Their values are now drawn the same portable way, not throughstd::uniform_real_distribution. - The square
randsvdwith a kappa takes a seed throughrandsvd(n, n, kappa, mode, seed).
- The draws come from the raw engine stream, as in
randsymandrandspdare now exactly symmetric: they average A(i,j) and A(j,i) after forming Q·Λ·Qᵀ.- Argument checks now throw
std::invalid_argumentin every build. They used to beasserts. They cover:- kappa < 1 or infinite, and a mode outside 1–5 (an invalid mode used to fall back to mode 3);
- a σ or eigenvalue list of the wrong length, and a non-positive
randspdeigenvalue; - hi < lo or an infinite bound in the random fills (an infinite bound never returned);
gen_dotandgen_sum’s n, c < 1 and c beyond the type’s range;- NaN endpoints in
geomspace.
- Genericity:
clementandkahancallsqrt,sinandcosthrough ADL, andtest_shim_genericitycovers them. - Smaller items:
testsuite::by_namejoins its path withstd::filesystem::path.- The
pascalheader documents where float and double stop being exact (n = 14 and 29) and where the entries overflow (n = 67 and 516). - The
clementcomment now states its formula and spectrum correctly.
- Tests:
test_generator_properties.cppchecks each generator’s documented property against an independent computation:- the Clement, Rosser, Frank, Forsythe and companion eigenvalues, and the Wilkinson W21+ pair;
- the Pascal determinant, and that Pascal, Moler, Lehmer and minij are SPD;
- the Lehmer and minij inverses;
- the Hilbert condition numbers, and Kahan’s κ₁ against its closed-form inverse.
- The same file tests n = 0 and n = 1 for every generator, and
floatfor pascal, hilbert, kahan and clement. test_random_seed.cppchecks that a seed reproduces exact values of the mt19937_64 stream, covers the [lo, hi) bounds, and checks the condition number in everyrandsvdmode.test_testsuite.cpploads all 20 catalog matrices, not 7, and checks each one’s 2-norm condition number from the SVD.- Every fix has a test that fails on the previous code.
- Catalog condition numbers:
testsuite::kappa()is documented as the 2-norm condition number, but six entries held something else.faires74x3had the ∞-norm value.steam3andfs_183_1had 1-norm values.fs_183_3repeatedfs_183_1’s value, andwest0167repeatedsteam1’s (2.827e7, where the true value is 4.785e10).rump6x6illhad an estimate of 1e16, where the true value is 7.84e24. All six are now singular-value ratios computed in 60-digit arithmetic. The other 14 published values agree with the computed ones to 1%, and the test now holds all 20 to that.
-
Matrix Market and element-list I/O: header and entry validation, symmetric array files, complex values, the nan/inf round trip, gzip errors, PNG sizes (#843, from the QA sweep #789).
- Sizes:
- A negative dimension (
-1 2 0) parsed intosize_tas 2^64-1.mm_readthen wrappednrows + 1to 0 and wrote out of bounds, andmm_read_densethrewbad_alloc. Sizes are now parsed strictly: non-negative integers, the whole token, exactly two or three per line. - A header
nnzlarger than the matrix can hold (2 2 99999999999999) used to reserve that many entries. It now throws. nrows * ncolsis checked for overflow.- The triplet buffer is still sized from
nnz, but capped at what the file’s size can hold, or at 2^22 entries for gzip input. mm_read_densechecks that an array file is long enough for its declared values before allocating the result.- With a narrow
size_type, a coordinate file is limited by its nnz, not bynrows * ncols.
- A negative dimension (
- Banner: all five tokens are required and checked: tag, object, format, field and symmetry.
foo matrix coordinate real generalused to be accepted, and a missing field or symmetry token defaulted to real/general. - Symmetric storage:
- A valid
array real symmetricfile (the lower triangle by columns) used to throw “unexpected EOF”. An n*n-value file under that banner was read as general. Array files withsymmetric,skew-symmetricandhermitiansymmetry are now read as the format defines them and mirrored. skew-symmetriccoordinate files are read too (they were rejected), with a stored diagonal entry rejected.hermitianfiles are read and mirrored conjugated.
- A valid
- Complex values:
complexfiles read into astd::complexvalue type.mm_writeandmm_write_sparseused to writerealwhatever the value type, and streamed a complex value as(re,im). They now take the banner’s field from the value type (complex,integerorreal) and writemax_digits10digits. Char-sized integers are written as numbers. A failed write throws, also when the data was still buffered at the end. - Entries:
- Entries beyond the header’s count used to be ignored; now they throw.
- A whitespace-only line used to throw “malformed”; now it is skipped.
- An entry line with extra tokens, or a value with trailing characters, throws.
nanandinf, which the writers emit, used to be rejected on reading; they now read back.
- gzip: a corrupt or truncated
.gzstream used to read as a shorter file, becausegzgetsreturningnullptrwas taken as end of file. The reader now asksgzerrorand throws. read_denseandread_sparse:- A bad token used to stop the read and return a partial matrix; now it throws.
read_densethrows on an empty field (1,,2) or a row of a different length. A ragged row used to be zero-padded or truncated to row 0’s width.read_sparsethrowsstd::out_of_rangefor an index outside the given dimensions, with the line number.
write_pngthrows for a width or height above 2^31 − 1, PNG’s limit. Such a dimension used to be truncated into a wrong header.- Parsing: values are parsed with
std::from_charswhere the standard library supports it for floating point, which ignores the locale, and withstrtodotherwise. Loadingbbmat(1.77M nnz) takes 0.22 s instead of 0.52 s, andrajat30(6.18M nnz) 0.77 s instead of 1.76 s. All 35 bundled.mtxfiles read identically to before. - CI: the Linux LAPACK jobs link zlib, so the
[gzip]tests run in CI. No job built withMTL5_WITH_ZLIBbefore. - Tests:
- Every fix above has a test that fails on the previous code.
- Coverage was added for CRLF, no trailing newline, 0x0/1x1/non-square/empty-row files, the array branch of
mm_read,mm_writeof a sparse matrix, andmm_write_sparsewith a comment. - The gzip tests cover a 70 KB line, a stream missing its last 4 bytes, and
.gzthroughmm_read_dense. - The
spytests coverlog_scaleinspy_magnitudeandspy_density,max_pixels == 0, 1x1, non-square, float values, andscale_indexnear 2^62. - The PNG tests cover an unwritable path and bad channel counts.
- Sizes:
-
CHOLMOD and SPQR bindings: lifetime, concurrent
constsolves, and SPQR’s first tests (#839, from the QA sweeps #816 and #774).- Concurrent solves:
cholmod_solver::solve()andspqr_solver::solve()areconstbut wrote the solver’s sharedcholmod_common, so two threads solving on one solver raced. Each solve now runs on acholmod_commonof its own, which copies the solver’s error and thread settings and only reads the factor (CHOLMOD) or the stored matrix (SPQR). Both classes document that aconstsolve is safe to call concurrently. The cost is onecholmod_startandcholmod_finishper solve. - SPQR lifetime: the move constructor copied the
cholmod_commonstruct, so both objects finished the same workspace, a double free once a solve had filled it. The workspace is now aunique_ptrwith acholmod_finishdeleter (interface/cholmod_workspace.hpp, shared with CHOLMOD).spqr_solvergains a move assignment, frees its matrix if the copy throws, rejectsm,nornnzaboveINT_MAXwithstd::length_error, and throwsstd::logic_errorfrom a moved-fromsolve(). - CHOLMOD: a failed
cholmod_startthrows instead of being ignored. A moved-from solver reports sizes 0. The comment onfactorize(A)now says what happens: a different pattern is refused with the old factor intact, while a failed numeric factorization leaves the solver unfactored until afactorize()succeeds. - Orientation: the CRS-to-CCS copies are correct as written, because
compressed2Dis row-major only (astatic_assert). The comments now say so. - Build:
MTL5_WITH_SUITESPARSE_SPQRlinks CHOLMOD too, sincespqr.hppcallscholmod_*itself. The Linux LAPACK CI jobs turn SPQR on, soiface_test_spqrruns against the real library and sparseqr_solve_dispatchgoes through SPQR. - Tests: new
test_spqr.cppcovers a non-symmetric square solve, least squares (checked through the normal equations), argument and size checks, move construction and assignment, and concurrent solves.test_cholmod.cppadds a refactorize with the same column counts but different rows, an indefinite refactorize followed by a good one, a non-squareanalyze(), moved-from sizes, and concurrent solves. The leak and double-free cases fail only under AddressSanitizer, and their comments say so. The concurrency tests check answers only: the old race was inside the uninstrumented SuiteSparse, where ThreadSanitizer cannot see it.
- Concurrent solves:
-
Foundations fixes from the QA sweep #816 (#838).
functor::scalar::absandsignumcompile for unsigned types;signum(NaN)is NaN, not 0.- The
maxandminidentities are-infand+inffor types with infinities. They werelowest()andmax(), so a max over-infvalues gavelowest(). magnitude_tandis_complex_vignore cv-qualifiers.- The
Magnitudeconcept findsabsthroughstdand ADL;Magnitude<double>had held only through C’s::abs(int). aligned_allocatorandallocate_alignedreject annwhosen * sizeof(T)overflows, withstd::bad_array_new_length.f_index’s precondition (index 0 is out of range) is documented.- Tests: the 26 untested scalar functors;
cabs1,structure_tol,same_object,expr_store_t,c_index/f_index,transposed_orientation; theLinearOperator,Preconditioner,FieldVector,NdArrayandMutableNdArrayconcepts.
-
mult(A, x, y)withysharing storage withxorA, the column-majorgemvtail, and thecache_infosysfs scan (#840, from the QA sweep #816).- Aliasing: every kernel writes
ywhile still reading its inputs, and the column-majorgemvzeroesyfirst. Aythat is the same vector asx, or a vector over part ofx’s orA’s buffer, gave wrong results underNDEBUG; a debug-onlyassertcaught only the same object.multnow checks the address ranges (detail::storage_overlaps, which also sees acompressed2D’s value array and the matrix behind a view) in every build and computes through a temporary, still writingy’s own buffer. The transposed-compressed2Doverload does the same. - The column-major
gemvtail: the lastm mod Wrows used a separate multiply and add while the SIMD rows used FMA, so a row’s rounding depended on where it fell. The tail now usessimd::scalar_fma, the batch’s ownfma. Every row gets the same chain, as the kernel’s comment claimed. This changes the tail rows’ last bit where the batchfmafuses (Highway builds with FMA). cache_info: the Linux sysfs walk examined each shared cache once per CPU that lists it and recounted its cores each time: O(cpus² · files), about 140k reads for one L3 shared by 256 threads. Each cache instance is now examined once and eachshared_cpu_listcounted once, with the same result. The walk takes its reader as a parameter, and a test runs it on a synthetic 256-CPU tree.- Interleave cap:
interface::interleave_cap(measured, registers)is tested for 8, 16 and 32 registers. The docs now say that targets other than x86-64 and AArch64 get 4 (the measured 6, capped), where they said 6.
- Aliasing: every kernel writes
-
sparse_vectorandstrided_vector_reffixes (#830, from the QA sweep #767).- Index checks:
sparse_vector::insertandoperator[]check the index in every build (the #825/#826 policy, per insert since there is no finalize step); a release build used to store index 10 in a size-3 vector. A signedsize_typerejects negatives.exists()returns false outside the vector. -fno-exceptions:sparse_vectorthrew directly and did not compile there; it usesdetail::throw_or_abort, and the no-exceptions test builds it.crop: takes a magnitude threshold, sostd::complexvalues compile; keeps NaN entries instead of dropping them; compacts in place.reserve(nnz)is new.strided_vector_ref: the iterator is a base pointer and an index, soend()of a column of a row-major matrix no longer forms a pointer beyond one past the end, and stride 0 has a defined distance. An emptysub_vectorat the end keeps the base pointer.- CI: the publish step checks that a repeat publish leaves
systems.mdand the card page byte for byte. It also checksDRY_RUN, a blank or different card cell, an older session, and the warning for asystems.mdwithout a card column.
- Index checks:
-
Assigning to a vector or matrix over an external buffer detached it, leaving the buffer unchanged (#829, from the QA sweeps #767 and #816).
double buf[3]; dense_vector<double> v(3, buf); v = w;gaveva private copy, andbd.block(0) = Xon ablock_diagonal2Dhad no effect.- Copy and move assignment write through an
externalorviewcontiguous_memory_blockof the same size, sodense_vector,dense2Dandblock_diagonal2D::block(k)keep writing the caller’s buffer, as expression assignment already did. - Another size throws
std::domain_errorfor copy and expression assignment, instead of detaching. Move assignment isnoexcept, so it asserts.change_dimandrealloc, explicit resizes, still detach. ndarrayviews: assignment writes the viewed elements through the view’s strides, with a shape check, and reads an overlapping source in full first. Copying a strided view (a slice or a transpose) now copies its elements; it copied the raw memory from the view’s base pointer, reading past the end for a slice.- Fixed-size heap vectors and matrices always have storage: default-constructed and moved-from ones held a null pointer behind a nonzero
size(). A moved-from fixed-sizedense2D, on the stack or the heap, also kept a leading dimension of 0, so every row read row 0. - Overlap: two non-owning blocks over overlapping parts of one buffer copy in a safe direction.
a = a.transpose()on an owningndarraycopies the view out before releasing the storage it points into, and a view assigned from an array it shares memory with reads the source in full first. A moved-fromndarrayis empty. dense_vector(n, 0)fills with zeros; it was ambiguous with the external-pointer constructor, which now takes exactlyValue*.vec::fill(v, 0)compiles for adoublevector.dense_vectorhasowns_memory(), likedense2D.- Tests for
contiguous_memory_blockassignment,dense_vector,dense2D,block_diagonal2Dandndarrayviews, and a newtests/unit/vec/test_vec_expr.cppfor the vector expression templates.
- Copy and move assignment write through an
-
Sparse construction: a second inserter kept only its own entries, insertion indices went unchecked, and
coordinate2Dsummed duplicates in an arbitrary order (#825, from the QA sweep #740).compressed2D_inserteramends the matrix, as MTL4’s does. The matrix’s entries are loaded at construction, so inserting at an existing position applies the updater (update_storereplaces,update_plusadds) and every other entry is kept. A second inserter used to rebuild the matrix from its own entries: after inserting (0,0) and (1,1), a second inserter setting (2,2) leftnnz == 1. No caller in the library, examples or benchmarks reuses a filled matrix;make_empty()orchange_dim()refills from scratch.- Indices are checked in every build (the #825/#826 “check once” policy), throwing
std::out_of_range. A negative index of a signedParameters::size_typeis rejected too.coordinate2D::compress()checks every entry, an O(nnz) pass per matrix. UnderNDEBUGa bad row was a heap write paststarts, and a bad column was stored.insert()no longer asserts, so the check is the same in every build.compressed2D_inserterchecksins[r]andins[r][c]as they are used, one comparison per index. That is the exception to “once per matrix”: the row indexes the slot arrays immediately, and the final merge runs in the destructor, which cannot throw. The column was not checked at all.
coordinate2Dsums duplicates in insertion order:sort()andcompress()usestd::stable_sort, so the result is reproducible for rounding-sensitive values.compress()aftersort()no longer copies and re-sorts.- The inserter’s merge reserves each row’s own entry count and reuses one buffer. It reserved the whole overflow map’s size for every row. An insert skips the overflow map lookup while the map is empty.
benchmarks/check_coverage.shmatches manifest targets on a name boundary:krylov/gmres30still passed after its entry was renamed. A trailing*asks for a family, askrylov/idr_s*now does.- Not changed: the sweep’s claim that the f32
gemmandtrsmplatform checks pass an all-zero result does not hold.tol<float>(512)is 2.45e-4, not 0.245, and a zero C fails the Freivalds check by 27× at n = 512 (error 0.0066) and 10× at n = 1024. - Tests:
test_inserter(new) covers reinsertion with both updaters, the overflow map,slot_size0, 0-row and 0-column matrices and the index checks.test_coordinate2Dcoverscompress()on empty matrices and rows, duplicate order and the index check;test_ell_matrixthe width-0, non-square and 3-argument cases.test_batchadds value-level load and store for all four lane types,load_widenandconvert, which the fixed-length SVE lanes run.
-
Structured matrices and views (#826, from the QA sweep #740). Construction-time index checks now run once per object, in every build: that is the policy decided for #825 and #826. Element access keeps
bounds_checking.permutation_matrix<double> P({0})was a 0×0 matrix, andP({2})the 2×2 identity:{0}chose the size constructor. A braced list is now the permutation, through anstd::initializer_listconstructor;P(n)is still the identity.- Every permutation is validated at construction: a duplicate or out-of-range entry throws
std::invalid_argument. It madeinverse()andP * xindex out of bounds.swap_rowschecks its rows underbounds_checking. hermitian_viewrequires a square matrix: for a 3×2 A,H(2,0)readA(0,2). The diagonal is returned as stored, which is exact for a Hermitian matrix, and that is now documented.map_viewchecks its map entries at construction, and(r, c)underbounds_checking. Repeated entries are allowed.- Block
multsummed in float for a doubley: the SIMD branch tested onlyx. A floatxinto a doubleynow sums in double, as a non-contiguousxalready did. block_diagonal2D:block(k)no longer exposes the block itself: the non-const overload returns adense2Dover the block’s storage.change_dimon the old reference left the offsets and the total shape stale. Writing its elements writes the block. A resize to another element count detaches it; a reshape to the same count still writes the block, in the new layout.set_block(k, B)replaces a block of any shape. Every stored block owns its storage: ablock()view passed toset_block,add_blockor the vector constructor is copied, whereset_block(k, bd.block(k))would have freed the buffer the view points into. The newdense2D::owns_memory()tells them apart.add_blockis O(1) (it was O(n) per call), andoperator()finds the block by binary search instead of scanning.
mxint8andmxfp4::decode_elementassertj < 32. Formxint8, a largerjread past the block.- Not changed:
std::common_type_tin thepermutation_matrixandblock_diagonal2Dproducts works for same-type posits and LNS, and mixed types followmult’s rule, as for #824.P * Aalready existed for a dense2D A, inoperation/reorder.hpp. The header now says so.
- Tests:
test_permutation_matrix,test_block_diagonal2D,test_matrix_views,test_triangular_viewsandtest_block_matrix_viewcover the cases the sweep listed. The float-x/double-y test fails before the fix.death_test_mat_index_assertscoversblock_matrix_view::rowanddecode_element.
-
dense2Dassignment from an expression that reads the target elsewhere, ragged initializer lists, and the generic matrix product (#824, from the QA sweep #740).A = A + trans(A)gave a wrong answer, and was a data race under threads.operator=(expr),+=and-=wrote element (r, c) while the expression still read A’s other elements. For{{1,2,3},{4,5,6},{7,8,9}}, A(1,0) came out 10 where 6 is right.- The fix: an assignment now goes through a temporary when its expression reads the target through a view or a lazy product, or reads a matrix whose storage overlaps it (
mat/expr/expr_alias.hpp). - Unchanged: element-wise use of the target (
A = A + B,A = 2*A - A) and unaliased dense assignments still evaluate in place. An expression with a sparse, block or other non-contiguous operand takes the temporary, since ablock_diagonal2Dcan hold the target as a block. An external-pointer target keeps writing its own buffer.
- The fix: an assignment now goes through a temporary when its expression reads the target through a view or a lazy product, or reads a matrix whose storage overlaps it (
- A ragged initializer list is rejected with
std::invalid_argument, throughthrow_or_abort.dense2D<double>{{1,2},{3,4,5}}wrote past the buffer, and a shorter row was padded with zeros. multwith mixed dense operand types under BLAS (float A, double B and C) didn’t compile: the?gemmbranch didn’t require one element type. Mixed operands now take the generic kernel, as on the native-fast path. Andmult(trans(S), x, y)for a sparse S is now constrained to vectors, sotrans(S) * Bwith a dense B reaches the matrix product.- The generic
Matrix * Matrixnow callsmult. It was its own unblocked triple loop, reading B down its columns throughoperator(). Dense float and double now get BLAS or the native-fast GEMM, andcompressed2D * dense2Dgets the CRS kernel (#550) instead of a binary search per element. Results for float and double can differ in the last bits from the old loop, asmult’s do. - Tests:
test_dense2D.cpp: initializer lists of every shape, expression construction and assignment, the aliased cases, compound, copy and move assignment,checked_change_dim, and swaps of fixed-size and external-pointer matrices.- The new
test_mat_operators.cpp: the lazy product, negation and right-scalar expressions, and the products at the edges, including sparse operands. death_test_mat_expr_shape: the expressions’ shape assertions.
-
MTL5_NATIVE_ARCHbuilt the Arduino Ventuno Q for baseline Armv8.0-a (#806). GCC 13 resolves-march=nativeto nothing on that board’s Cortex-A78C + A55 SoC: the driver passes no-marchor-mcpuon to the compiler. Everynative-fastbuild there lacked DotProd, somult_quadran Highway’s emulation ofSDOT.gemm_quadi8>i32 at 512³ took 23.7 ms on one core, slower than the plain i8 gemm’s 16.6 ms; with the cores’ features enabled it takes 3.7 ms, 72.8 GOP/s.MTL5_NATIVE_ARCH_FLAGS(default-march=native) replaces the flagsMTL5_NATIVE_ARCHadds. A non-default value is recorded in the build provenance, so the sidecar’scxx_flags=names it.- A configure-time guard on AArch64 Linux: CMake warns when the flags don’t enable a feature
/proc/cpuinfolists (asimddp→ DotProd,i8mm→ I8MM).platform.shrepeats the warning on the console. platform.sh --arch FLAGSfor thenative-fastbuild. The Ventuno’s platform and cache-blocking profiles pass-march=armv8.2-a+dotprod+fp16+rcpc -mtune=cortex-a78c, the features every core lists;-mcpu=cortex-a78cmeasured within 4% but also enables PAuth, which the kernel doesn’t report.- The issue read the boards the wrong way round: the sessions record the Ventuno as
build_isa=NEONand the Jetson Orin asNEON DOTPROD. The Jetson’s quad gemm, 3.9× the plain one, is the nativeSDOTpath.
-
mtl5_bench’sblasvariant didn’t build against CHOLMOD before version 5 (#810). The CHOLMOD reference entry setcholmod_common::nthreads_max, which CHOLMOD 5 (SuiteSparse 7) introduced, so the build failed on the Jetson Orin, whose Ubuntu 22.04 ships CHOLMOD 3. The member is now set only where it exists; an older CHOLMOD threads only through its BLAS, whichplatform.shalready pins to the run’s thread count. -
The CHOLMOD binding: a double free on move, an indefinite matrix factored silently, and leaks when its constructor throws (#774, for #810).
mtl::interface::cholmod_solverhad no unit test, and no CI job built it.- Move: the move constructor copied the
cholmod_commonstruct, so the moved-from object and the new one both freed its workspace. The workspace now lives on the heap and moves as a pointer. Move assignment is added; a moved-from solver throwsstd::logic_errorif used. - Indefinite matrices: a matrix that isn’t positive definite now throws
std::runtime_errorfrom the factorization. On the supernodal path CHOLMOD reported it only inCommon->status, which the binding never read. On the simplicial path it reported nothing at all: CHOLMOD’s simplicial default is L D L^T, which factors an indefinite matrix with status OK. The binding now asks for L L^T (Common->final_ll) on both paths, which is what its documentation promised. - Leaks: if analysis or factorization threw, the constructor had started CHOLMOD but the destructor never ran. The one-call constructor now delegates to the default one, so the destructor frees the workspace, the matrix copy and the factor.
- Sizes: an n or nnz above
INT_MAXthrowsstd::length_errorinstead of wrapping in the int32 interface. - New: one phase at a time.
analyze(A),factorize(),factorize(A2)for new values on the same pattern (checked in full before any value is replaced),solve, andcommon()for CHOLMOD’s settings.cholmod_solver(A)andcholmod_solve(A, x, b)work as before. #810’s reference entries time the phases separately through this. - Tests and CI:
tests/unit/interface/test_cholmod.cppcovers simplicial and supernodal solves, indefinite input on both, refactorization and a pattern mismatch, phases out of order, move construction and assignment, size checks, and n = 0 and 1. The two OpenBLAS LAPACK jobs now install SuiteSparse and build with-DMTL5_WITH_SUITESPARSE_CHOLMOD=ON, so the test runs against the library. - SPQR’s move constructor has the same double free; it is still open in #774.
- Move: the move constructor copied the
-
The harness README has its sparse direct-solver section again. #468 deleted “Sparse direct-solver scoreboards” (how to run
bench_klu,bench_superluandbench_sparse) but kept the link to it in the Layout section, so the link led nowhere. The section is restored as it was, with one correction:bench_sparsetakes one matrix per--file, so the example now reads--file A.mtx --file B.mtx. -
The benchmark preflight no longer fails on idle build processes, and it detects a running
mtl5_bench(#756).preflight.ps1matched build tools by name only, so an idle reusable MSBuild worker node failed the gate. Command-line builds leave those nodes for about 15 minutes, and Visual Studio leaves them while it is open. An open Visual Studio failed it too. On Windows, that blockedplatform.ps1with no build running.- The fix: a matched build process counts as competing load only if it uses more than 50 ms of CPU in a one-second sample, 5% of one core. An idle one is recorded in the new sidecar key
idle_build_processesand passes. A build that is really running still fails, since its compiler or linker is busy even while the driver waits. The sample costs a second, and only when a build process exists. preflight.shapplies the same test on Linux, from/proc/<pid>/stat. On macOS every match still counts, andidle_build_processesisunavailable.mtl5_bench: both preflights looked forbench_*, which the platform harness doesn’t match, so a secondplatform.shorplatform.ps1could measure alongside a running one.*_benchis now matched too. Benchmarks always count, without sampling.- Test:
bench_preflight_contractrequiresidle_build_processesfrom both scripts.
- The fix: a matched build process counts as competing load only if it uses more than 50 ms of CPU in a one-second sample, 5% of one core. An idle one is recorded in the new sidecar key
-
mtl5_benchcapability cards escape|in table cells (#758). Shapes such as|v| <= 15, from the integer entries, added two columns to their rows, so those rows’ figures sat under the wrong headings. The three published cards are corrected, andpublish_platform.cmakerepairs cards written by an older binary. -
The
mtl5_benchcard pages are on the docs site (#758). The Ryzen 7 2700X and Xeon E5-2420 v2 pages, and the new Ryzen 9 8945HS one, weren’t inFILE_MAP, so the site didn’t build them andsystems.md’s links to them were dead.- The pages are now
docs/benchmarks/<machine>-mtl5-bench.md, each with its own title. A bare<machine>.mdstays the written analysis page, as for the i7-12700K and the Ryzen 9. systems.mdlists both kinds in separate columns.- Each card page is marked preliminary, because none was measured under #737’s methodology.
- The pages are now
-
IDR(s) keeps one ω per cycle, so a larger s no longer costs more iterations (#734).
mtl5_benchfounditl::idr_s’s iteration counts irregular in s: 80, 77, 101 and 59 at s = 1, 2, 4 and 8 on 128² convection–diffusion with ILU(0).- The cause: after its s initial steps, IDR(s) runs in cycles of s + 1 steps that must share one ω. That puts their residuals in the same space G_j, which is the dimension reduction (Sonneveld and van Gijzen, SISC 31, 2008, Alg. 3.1). The implementation recomputed ω at every step.
- Unpreconditioned 128² Poisson failed to converge at four of s = 1, 2, 4, 8 and 16.
- With ILU(0), 128² Poisson took 551, 205, 153, 932 and 253 iterations and ended at a residual of 2e-2.
- The fix: ω is chosen at the first step of each cycle, and the other s steps reuse it, with dR = −A·dX. Each step still costs one product with A and one preconditioner solve.
- What was ruled out: the issue’s other hypotheses were measured over 20 seeds for P and s = 1–16, on convection–diffusion and Poisson, with and without ILU(0). With ω fixed per cycle, the median falls with s on every problem, and the spread across seeds is 5–15%. Orthonormalizing P, or the κ = 0.7 ω safeguard, moved the medians by at most about 6%, so neither was adopted. The fixed seed stays, so runs are reproducible.
- Results: all 40 runs (32² and 128², s = 1–16, four problems) converge to a true residual ≤ 1e-8.
- The
mtl5_benchentries now take 28, 24, 23 and 23 iterations (small) and 71, 63, 59 and 54 (medium) at s = 1, 2, 4 and 8. - Unpreconditioned 128² Poisson takes 374, 327, 327, 324 and 330 iterations for s = 1, 2, 4, 8 and 16.
- The
- Test:
test_idr_sruns s = 1, 2, 4, 8 on convection–diffusion, with and without ILU(0), and on unpreconditioned Poisson. Each s must reach a true residual within 10× rtol, s = 8 must not exceed s = 1, and no s may exceed the best smaller s by more than 10%. Against the old header, the Poisson case fails: 245, 198, 214 and 735 iterations.
- The cause: after its s initial steps, IDR(s) runs in cycles of s + 1 steps that must share one ω. That puts their residuals in the same space G_j, which is the dimension reduction (Sonneveld and van Gijzen, SISC 31, 2008, Alg. 3.1). The implementation recomputed ω at every step.
-
TFQMR converges on unsymmetric systems, and its reported convergence is the true residual’s (#731).
itl::tfqmrstalled at a 5–9% residual on a mild 2D convection–diffusion matrix with any preconditioner, where BiCGSTAB converged in 13–60 iterations. On SPD matrices it took up to 16× BiCGSTAB’s iterations.- The cause: each iteration’s two half-steps need two search vectors, u_m and u_{m+1} = u_m − α·v_m, and the next pair starts from u_{m+2} = w + β·u_{m+1} (Freund 1993; Saad, Algorithm 7.8). The implementation had no u recurrence, so w stood in for both vectors. Both unit tests used symmetric matrices, so nothing caught it.
- The fix: the u recurrence is restored, with u kept preconditioned (right preconditioning,
y = M⁻¹u). The cost per iteration is unchanged: two products with A and two preconditioner solves. - The true residual: TFQMR tests the quasi-residual τ. Without a preconditioner, the updated residual drifts from b − A·x by rounding, and the true residual stalls near 2·10⁻⁷ on the 32×32 problem, as CGS’s does. When τ converges, the solver now recomputes b − A·x and restarts from the current x if that hasn’t converged, as MATLAB’s
tfqmrdoes. A reported convergence is now real, down to rtol 1e-14. The check costs one product with A, plus a solve per restart. - Results (32×32, rtol 1e-8):
- Convection–diffusion: 113 iterations unpreconditioned against BiCGSTAB’s 60, true residual 9.4e-9. With ILU(0), 16 against 14. Before the fix, it failed after 3000 iterations with either preconditioner.
- Poisson: 83 iterations against 69 unpreconditioned, and 23 against 24 with ILU(0). Before the fix, it took 3000 and 205.
- Tests:
test_tfqmradds convection–diffusion with the identity, diagonal and ILU(0) preconditioners, and Poisson. Each checks the true residual and caps the iteration count at 3× BiCGSTAB’s. It also adds a tolerance sweep that checks the reported convergence is real, theAccumulatorpath, and an iteration-limit case. The “non-symmetric” 3×3 test is now nonsymmetric. Themtl5_benchtfqmr+ilu0entry is back on convection–diffusion.
-
<mtl/mtl.hpp>compiles with BLAS and SuperLU both enabled (#725). SuperLU’sslu_ddefs.hdeclares its ownextern "C"prototypes for the BLAS routines it calls. Their signatures differ from MTL5’s const-correct ones ininterface/blas.hpp, and between SuperLU versions:intreturns in 5.x,voidwith non-const pointers in 7.x. Any translation unit holding both headers failed with “conflicting declaration of C function”: the umbrella header, orinterface/superlu.hppnext to any operation that dispatches to BLAS.- The fix:
superlu.hpprenames the double-precision BLAS names while SuperLU’s header is parsed, so SuperLU’s prototypes declare names nothing references, then removes the macros. SuperLU’s calls are made inside the compiledlibsuperlu, so which BLAS it links against is unchanged. A name thatslu_Cnames.halready maps, for a Fortran convention other than the trailing underscore, is left alone. - Test:
iface_test_superlu_blasincludes the umbrella header and calls a SuperLU solve, dgemm, dgemv and ddot in one translation unit. It checks that no renaming macro leaks. The OpenBLAS entries of the CI LAPACK lane (Ubuntu 24.04, GCC 13 and Clang 18) now link SuperLU, so the suite is built in that configuration.
- The fix:
-
mtl5_benchcharges symv for one triangle of A, not all of it, and flags results far above their roofline (#743). Theblas2/symventry counted n² elements of A, but every symv path reads only the stored triangle: BLAS?symv, and the generic single pass since #724. So BLAS symv showed 184–203% of the DRAM roofline on an i7-12700K.- The fix: the byte model is
0.5·n² + 2nelements, astrmvandtrsvalready use. BLAS symv now reads 97%. - The guard: a bandwidth-bound result that is not cache-resident and exceeds 150% of its roofline is marked
!in the console and card output, andsuspect_modelin the JSON. It is a warning, not a failed check. It is not raised for compute-bound results, or when the cache size is unknown. The threshold leaves room for tuned kernels beating the measured ceilings, and for noise in the bandwidth probe: axpy read 120% and 137% in two--class mediumruns on the same machine. A byte model that counts a triangle as the full matrix still reads about 200%. - What changes: symv
%roofandGB/sfigures from earlier runs are twice what this build reports for the same speed, so they aren’t comparable. No other entry’s model changed.
- The fix: the byte model is
-
Three generic-type defects found by the new
native_shimtest type (#703). Each one broke a user-defined number type that has no implicit conversions to or from the built-in types:- The symmetric eigensolvers compared
delta >= 0, an int.eigenvalue_symmetricandeigen_symmetricdid not compile for such a type. They now compare withmath::zero<real_t>(). - The property predicates defaulted
tolto an int literal (tol = 0, or the sentinel-1). This affected 22 functions inmatrix_properties.hpp,factorization_properties.hpp,vector_properties.hpp,spectral_properties.hppandtensor/properties.hpp, so a call that relied on the default did not compile. The default is nowmagnitude_t<T>(0)ormagnitude_t<T>(-1). has_nan,has_infandis_finitetreated every custom real type as finite and never NaN. A posit NaR or an lns NaN went unseen even when the type providesisnan. The classification now uses the type’s ownisfinite,isnanandisinfwhen ADL finds them, and only falls back to “finite” for a type without them.
- The symmetric eigensolvers compared
-
multasserts in debug builds that its output does not alias an input (#696).mult(A, B, C)andmult(A, x, y)overwrite C (or y) while still reading the inputs, somult(A, B, A)ormult(A, x, x)silently gave a wrong result. The precondition was documented but not checked.- The fix: the public
multoverloads (dense, sparse transposed, block matrix) andmult_quadassertthat the output is not the same object as an input. Release builds are unchanged. - Limits: the check compares object addresses, so it does not see a view of the output, such as
mult(trans(C), B, C).
- The fix: the public
-
The BLAS Level 2 calls pass a valid leading dimension for an empty matrix, and
mult(A, x, y)sets y to zero when A has no columns (#693). BLAS requireslda >= max(1, rows). The gemv dispatch inmult, andger,symv,trmvandtrsv, passed 0 for an empty matrix, so BLAS reported an illegal parameter through XERBLA and returned; other BLAS libraries may abort. gemv also returns without touching y when a dimension is 0, somulton a3x0A left y’s old values instead of making it 0, as the generic path does.- The fix: every one of these calls is skipped for an empty matrix, and
multthen sets y to zero. The leading dimension is also clamped to at least 1, as the Level 3 dispatches already do. - What changes: nothing for a non-empty matrix, and nothing without BLAS.
- The fix: every one of these calls is skipped for an empty matrix, and
-
syrk,syr2k,symv,symmandtrmmfollow the BLAS alpha/beta convention on every path;symvandsymmread only A’s lower triangle (#692). BLAS definesbeta == 0to mean C (or y) is not read, so it may hold NaN or uninitialized values, andalpha == 0to mean A and B (or x) are not read. The generic paths computedalpha*sum + beta*Cregardless, so a NaN in C survivedbeta == 0, since0 * NaNis NaN, whilegemmtand the BLAS paths gave the right result.trmm, which has no beta, kept a NaN in A or B underalpha == 0. The genericsymvandsymmalso read A’s full matrix, while BLAS reads only the lower triangle, so for a non-symmetric A the two paths gave different results.- The fix: each element is computed as
gemmtcomputes it. When alpha is zero it isbeta*C, or zero when beta is zero too. Otherwise it isalpha*sum, plusbeta*Conly when beta is nonzero.trmmwithalpha == 0sets B to zero. On the generic and accumulator paths,symvandsymmtake A(i,j) above the diagonal from A(j,i). - What changes: results for a nonzero alpha and beta are unchanged. With
beta == 0and a finite C they are unchanged too. For a symmetric A,symvandsymmare unchanged. A caller that stored only the upper triangle of A, and relied on the generic path reading it, now gets the lower triangle’s values, as a BLAS build always gave. - Test:
test_blas_alpha_beta_zeroruns each routine on the generic path, the column-major path (BLAS in a BLAS build) and the accumulator path. It covers C or y filled with NaN atbeta == 0, A and B filled with NaN atalpha == 0, both at once, and a NaN-filled upper triangle forsymvandsymm. Against the old headers every path fails.
- The fix: each element is computed as
-
krontakes its value type from both operands, so a mixed-type product is no longer narrowed (#694). The result’s value type was A’s alone, sokron(dense2D<int>{2}, dense2D<double>{0.25})gave0, andkronof adoublematrix with astd::complex<double>one did not compile.- The fix: the value type is
std::common_type_tof the two value types, as indot,axpyand the other mixed-type operations. - What changes: nothing when both operands have the same value type. For example,
int8_t (x) int8_tstaysint8_t, althoughint8_t * int8_tisint. A pair of custom types with nostd::common_typekeeps A’s value type, as before, rather than failing to compile. - Test:
test_kroncoversint (x) doublein both orders,float (x) double,double (x) complex<double>, same-typedoubleandint8_t, and the no-common-type fallback. Against the old header, the new cases do not compile.
- The fix: the value type is
-
Scaled
project_ontoandembed_intosaturate correctly between integers of different signedness (#691).detail::saturating_castcast the target’s limits to the source type before comparing, and those limits wrap when the signedness differs. Soproject_onto<int32_t>(dense_vector<uint32_t>{5, 100}, uint32_t{1})gaveINT32_MINfor both elements, andembed_into<uint32_t>(dense_vector<int16_t>{5, 7}, 1)gaveUINT32_MAX.- The fix: the comparison is by value, with
std::cmp_lessandstd::cmp_greater. Both sides are first widened tolong longorunsigned long long, since those functions rejectbooland the character types. Widening between signed types was broken the same way:static_cast<int>(LLONG_MAX)is -1, soembed_into<long long>of anintvector clamped every positive value toLLONG_MAXand every negative one toLLONG_MIN. That is fixed too. Same-signedness narrowing, unsigned widening and floating-point conversions are unchanged. - Test:
test_projectioncovers unsigned to signed and signed to unsigned at both ends of the range, equal-width (uint32 to int32), narrowing (int64 to uint16, uint64 to int8), integer scale factors, widening between signed types, andchartargets. Against the old header, 5 of its 26 test cases fail.
- The fix: the comparison is by value, with
-
two_normandfrobenius_normno longer overflow or underflow; the max-based norms propagate NaN (#690). The default path summed unscaled squares, sotwo_normofdense_vector<float>{1e20f, 1e20f}wasinfand ofdense_vector<double>{1e-200, 1e-200}was0, while a BLAS build, whosenrm2scales, gave the right answer.infinity_normand the matrixone_normandinfinity_normkept the maximum witha > result, which skips a NaN, soinfinity_norm({1, NaN, 2})was2althoughone_normof the same vector was NaN.-
The fix: the plain sum stays the fast path. A second pass runs when that sum reaches
max(), either infinite or saturated as a posit saturates, or falls belowmin()/epsilon(), where the small squares may have underflowed. It sums the squares scaled by a power of two nearmax|a|. A vector whose norm genuinely overflows is stillinf, and one containing aninfisinf. The max-based norms return NaN when any element, column sum or row sum is NaN. -
Custom number types are rescaled too:
frexp,ldexpandsqrtare found by ADL, with thestdversions brought in by using-declarations. A number library’s own functions are used, for example for lns, fixpnt, posit or takum. A type takes the rescan when it has those three functions and astd::numeric_limitsspecialization. -
What changes: nothing for an ordinary input: it never rescans, so its result is bit-identical to before. A type without
frexp,ldexp,sqrtorstd::numeric_limitskeeps the plain sum. Integer norms keep their wrapping semantics. A magnitude type without!=keeps the plain maximum. The explicit-Accumulatoroverloads are unchanged. -
Test:
test_normscovers:- values near the float and double overflow and underflow thresholds;
- subnormals, and zero and
infvectors; - the generic loop, through
std::complex<double>; - a user-defined real type that is rescaled only through its own
frexpandldexp; - a magnitude type without equality;
- NaN in every position for every norm.
It passes in a BLAS build too. Against the old header, 7 of the 22 test cases in the first version of this change fail.
-
Changed
Section titled “Changed”-
BREAKING: an owning
dense_vectorordense2Dis constructed from a read-only view only explicitly (issue 855, from QA sweep #848). The converting constructors fromvec::const_vector_viewandmat::const_matrix_viewareexplicit. Implicit, they let a view passed to a by-valuedense_vectorordense2Dparameter deep-copy with nothing at the call site to show it.- What no longer compiles: copy-initialization,
vec::dense_vector<double> v = view;, and passing a view where an owning vector or matrix is taken by value. - Migrating: write the copy out:
vec::dense_vector<double> v(view);,f(vec::dense_vector<double>(view)), ormat::dense2D<double> M(view);. Code that only reads should take the view, orconst dense_vector<V, P>&with the view’s parameters, and copy nothing.
- What no longer compiles: copy-initialization,
-
BREAKING:
Scalarrequiresstd::numeric_limitson the element type’s magnitude type (#838, from the QA sweep #816).Scalar<T>now includesHasNumericLimits<T>, which isstd::numeric_limits<magnitude_t<T>>::is_specialized. It applies to the magnitude type because the standard has nonumeric_limits<std::complex<T>>, sostd::complex<T>qualifies throughT.- Why: one source for a type’s precision and range, instead of per-algorithm fallbacks that disagreed. A type without limits used to get a measured epsilon in
expm,schur,sylvesterandeigen_symmetric; an exact comparison in theldlt/choleskystructure guards (structure_tol), which then rejected matrices symmetric only to rounding; no scaling insylvesterandsvd; and a zero identity formin/max. Those paths are removed:machine_epsilonandstructure_tolreadnumeric_limits, and the eightis_specializedbranches are gone. - Migrating: a custom number type specializes
std::numeric_limits, as every Universal number system does. The one Universal scalar type without it,unum2, is stillwater-sc/universal#2075. The tests’ class stand-ins use the newtests/support/mtl5_test/limits_of.hpp.
- Why: one source for a type’s precision and range, instead of per-algorithm fallbacks that disagreed. A type without limits used to get a measured epsilon in
-
The docs site’s Benchmarking section keeps the capability cards apart from the analyses (#799, step 1). The generated cards and the written analyses were listed together in alphabetical order, so the i7-12700K analysis sat next to its card with nothing to tell them apart.
-
Where the cards are: they moved from
docs/benchmarks/<machine>-mtl5-bench.mdtodocs/benchmarks/cards/<machine>.md.- The site serves them at
/benchmarks/cards/<machine>/. - The old
/benchmarks/<machine>-mtl5-bench/URLs redirect there. publish_platform.cmake, the CI publish test andsystems.md’s card links follow the new path.
- The site serves them at
-
The sidebar order:
- the harness overview and the systems page;
- the cross-machine analyses;
- the per-machine analyses;
- the cards, in a collapsed group.
A new page in
docs/benchmarks/needs a sidebar entry indocs-site/astro.config.mjs. A newly published card doesn’t: it appears in its group automatically.
-
-
Capability card pages compare their runs side by side (#799, step 2). A card page held one section per run, six on most machines, each with an entry table of about 110 rows, so comparing native with blas, or one thread with all of them, meant scrolling between sections.
publish_platform.cmakenow adds an “Across the runs” section after the provenance table:- each area’s median %roof, one column per run;
- each entry’s median time in every run, with the fastest run in bold.
Each run’s full entry table is folded into a
<details>block, so the page opens on the comparison. The site’s sidebar lists each card by its machine name. All seven cards are regenerated from their published sessions; only the new sections and the<details>markers change. -
systems.mdis the machine registry again (#799, step 3). It had grown to 1,114 lines, about 700 of them analyses. It now keeps each machine’s hardware, caches, vendor libraries, blocking and pinning policy, and links to the analyses that moved to their own pages:docs/benchmarks/cache-blocking-ab.md: the #430 four-machine result, the i7-12700K, Jetson Orin and Arduino Ventuno Q sessions, and how to run the A/B on a new machine;docs/benchmarks/register-tile-sweep.md: the #643 sweeps on the Ryzen 9 8945HS and the Ventuno Q;docs/benchmarks/run-contract.md: the run contract and the backend methodology;- the i7-12700K analysis,
docs/benchmarks/i7-12700k.md: the #640 vendor-BLAS-in-a-region test and the #636 pool latency. Both were measured only on the i7.
The text moved unchanged, apart from new section titles and three cross-references that pointed “above”. The links into the moved sections, and the “run contract in systems.md” pointers in
run_sweeps.sh,run_scaling.shand the README, follow them. “Adding a system” now describes publishing a card and adding an analysis page to the sidebar. -
The per-machine analyses cover the #737 platform sessions, and the Jetson Orin and Ventuno Q have one (#799, step 4). Each figure comes from the machine’s two published sessions, and each repeatability figure from
benchmarks/compare_sessions.pyon that pair.- New
docs/benchmarks/jetson-orin.md:- 25 W with
jetson_clocks; 96.5% of entries within ±5% between the sessions; - native-fast GEMM at 60% of peak and 64% of OpenBLAS on one core; one core reaches 16 of the module’s 35 GB/s;
- the interleave widths, #795 under GCC 11, and the bimodal 6-thread integer gemm (#785).
- 25 W with
- New
docs/benchmarks/arduino-ventuno-q.md:- the four A78C cores; 93.0% repeatability; one core saturates memory;
- native-fast GEMM at 57% of peak, scaling 3.6× on four cores;
- GCC against Clang: Clang’s W = 4 is fastest in every kernel, and GCC’s f32
trmvand forward substitution stay 1.45–1.48× behind it even at #798’s W = 2.
i7-12700k.mdandryzen-9-8945hs.md: a dated “Platform benchmark (#737)” section each, with the provenance table extended to it and to the threading measurements. On the i7 (91.3% repeatability), native-fast GEMM at 512³ is at 98% of OpenBLAS on one core, which reproduces the #82 parity in a second benchmark.- Correction on the Ryzen 9 8945HS (87.1%): the page said that under MSVC “only Highway’s dispatched kernels target AVX2/AVX-512”. MTL5 doesn’t use Highway’s run-time dispatch, and the sidecars record native-fast’s target as
SSE2, so the missing/archflag is the leading explanation of the #82 gate failure, pending an MSVC measurement with/arch. The caveat is corrected in place. - Open observations, recorded on the pages, each with a tracking issue:
- Column-major
gemvin native-fast is 2.2–5.0× slower than the generic build on all four machines (#804). - The Ventuno’s threaded LU is 4.4× slower on four cores than on one (#805).
- The Ventuno’s
SDOTquad integer gemm is slower than its plain i8 gemm (#806).
- Column-major
systems.md: the Results column links the two new pages, and the Jetson section notes that the #737 sessions use 25 W rather than the 15 W of the #430 run. The Xeon E5-2420 v2, Ryzen 7 8845HS and Ryzen 7 2700X stay card-only for now.
- New
-
Behaviour change for BLAS builds: Level 1 no longer calls the vendor (#754). With
MTL5_HAS_BLAS,dot,two_norm,axpyandscaleon dense float/double vectors called?dot,?nrm2,?axpyand?scalat any length. They now take MTL5’s own SIMD loops, as a build without BLAS does. Level 2 and Level 3 still dispatch, andinterface::blas::keeps the Level 1 wrappers for a direct call.- Why: OpenBLAS splits
ddotanddaxpyacross its process-wide thread team above a few thousand elements. On a machine with busy cores, each call then waits 3–6 ms for the team, about 1,000× the work at n = 16,384 (OpenBLAS 0.3.32, i7-12700K, 3 cores busy). On an idle machine the team costs nothing, so the slowdown appeared only on shared workstations and CI runners. A Krylov iteration makes several such calls, andmtl5_bench --class medium --filter krylovin a BLAS build ran 17–123× slower than without BLAS under that load. For example,bicgstab+ilu0took 378 ms andgmres30+ilu03,672 ms. With this change the BLAS build matches the native one within 0.3% on all 13 entries: 12.8 ms and 29.8 ms. - What changes: in a BLAS build, results of
dotandtwo_normcan differ in the last bits, since they now use MTL5’s summation order instead of the vendor’s.axpynow rounds as a build without BLAS does. A largeddoton an idle machine loses OpenBLAS’s threading: 208 µs single-threaded against 54 µs on 20 threads at n = 10⁶. WithMTL5_NUM_THREADS> 1, MTL5’s loops split across its own pool above 65,536 elements. - Recorded:
mtl5_benchwritesprobes.blas_vendorandprobes.blas_vendor_threadsinto its JSON (blas_vendor=andblas_vendor_threads=in the sidecar), and prints<vendor>_threads=in its header line. - Docs:
docs/algorithms/on-node-threading.md, “Level 1 never calls the vendor”. - Test:
iface_test_blas_dispatchrequires each of the four routines to give exactly the bits of itssimd::loop at n = 20,000. Against the old dispatch, it fails in the OpenBLAS build.
- Why: OpenBLAS splits
-
A PR that only publishes benchmark data no longer runs the build matrix (#761).
ci.ymlandregression.ymlnow ignorebenchmarks/data/**, which no build or test reads. The sidecar check (#477) moved fromci.ymlinto a newbench-data.yml, which runs whenbenchmarks/data/,check_sidecars.shor the workflow itself changes. A session published withpublish_platform.cmake(data, card page,FILE_MAPentry) now runs that check and the docs build. The benchmark sources elsewhere underbenchmarks/still run full CI. -
BREAKING:
transand the other view factories reject a temporary at compile time (#695). Every view inmat/view/holds a reference to its matrix, and the factories tookconst M&, soauto t = trans(A * B);compiled andtread freed memory once the product was destroyed.- The fix:
trans,upper,lower,strict_upper,strict_lower,triu,tril,banded,hermitianandmappedeach have a deletedconst M&&overload, which an rvalue prefers overconst M&. - What changes: a view of a temporary no longer compiles, including one used within a single expression, such as
mult(trans(A * B), x, y), and an inline view of a view, such astrans(upper(A)). Name the matrix or the inner view first. Views of named matrices are unchanged.
- The fix:
Performance
Section titled “Performance”-
superlu_solverfactors once (#850, from the QA sweep #774).solve()randgssv, a full factorization, on every call. The constructor now runs the column ordering anddgstrf, andsolve()runs onlydgstrswith the stored factors, as KLU and UMFPACK do.factor_nnz()is set as soon as the constructor returns, and a singular A throws there. On an i7-12700K, a 40,000-unknown unsymmetric 2D grid with 10 right-hand sides takes 0.122 s instead of 0.956 s; one right-hand side costs the same (0.093 s against 0.098 s). -
multmat*mat reaches?gemmfor every orientation mix, andgerfor a row-major A (#849, from the QA sweep #774). Both were gated on one orientation, so they fell to the generic kernels:multunless A, B and C shared one,gerunless A was column-major, which left out the default row-majordense2D. A row-major buffer is the column-major transpose, somultnow passes?gemmthe'T'flag for each operand whose orientation differs from C’s.geron a row-major A updates A^T with x and y swapped.gercalls BLAS only when alpha’s type is no wider than A’s element type:?gertakes alpha in that type, so a double alpha of 2^-150 with a float A would round to 0 and skip the update, where the generic path gives the exact 1 (this applied to the column-major BLAS path before too). Measured on an i7-12700K, OpenBLAS, one thread, best of 5 or 10:mult, 400x400 double: row/column/row 21.8 ms → 1.8 ms, column/row/column 40.2 ms → 1.8 ms. The all-row-major and all-column-major cases are unchanged at 1.8 ms.ger, 2000x2000 row-major double: 1.45 ms → 1.07 ms, the column-major time.detail::gemm_dispatches_blas_vanddetail::ger_dispatches_blas_vsay which calls reach BLAS.test_blas_layout_dispatch.cppchecks them, and thetrmv/trsvtraits, at compile time, and checks the result for every orientation mix against a long-double reference.
-
GCC’s float
trmvand forward substitution on AArch64: nokeep_scalarbarrier, and W = 4 (#795). The barrier of #776 was on for GCC on AArch64 without a measurement there, and it made these two kernels 5.6–7.2× slower at W = 4 than at W = 2; #798 had held them at 2. An A/B on both ARM boards (bench_interleave_rows, n = 4096, one core, median of 3):- Jetson Orin, GCC 11: f32
trmvat W = 4 takes 6.31 ms without the barrier against 50.04 ms with it; the forward substitution 5.58 against 39.45. - Ventuno Q, GCC 13: 3.12 against 31.66 ms and 2.99 against 26.22 ms, now a little faster than Clang’s 3.29 and 3.18.
- W = 4 is now their fastest width and the AArch64 default for every compiler, 13–36% faster than the 2 they were held at.
gemvkeeps the barrier: neutral on the Jetson, 1.66× faster with it on the Ventuno (5.51 against 9.14 ms).detail::keep_scalar_triangular_vis the triangular kernels’ predicate; x86-64 is unchanged.
- Jetson Orin, GCC 11: f32
-
thread_poolspins for up to 1 ms before it sleeps, so threaded factorizations no longer slow down on boards with deep idle states (#805). The default pool woke its workers through a condition variable only, so every gap between parallel regions let their cores go idle. The Arduino Ventuno Q’s A78C idle states take 1.45–1.76 ms to leave, and after a gap of 5 µs or more a handoff cost about 1 ms instead of 14–22 µs. The non-LAPACKlu_factoropens one region per column, so a 512×512 LU ran 7× slower on four threads than on one.-
The change: a waiting worker, and the caller in its join, spin for up to
thread_pool::spin_usbefore blocking.generation_andremaining_became atomics so the spins can read them without the lock; they are still written only under the mutex, and the condition-variable predicates are unchanged. -
Setting:
MTL5_THREAD_POOL_SPIN_US, default 1000; 0 restores the old behavior. Define it the same in every translation unit. A worker can burn up to that much of a core after the last region of a burst. On the Ventuno at 4 threads, 50 µs left LU at 76 ms, 200 µs fixed LU, QR, LQ and Hessenberg needed 1000 µs, and 3000 µs gained nothing more. -
ABI:
thread_pool’s layout changed, so the shared-pool export is nowshared_pool_v2. A module built against the old header fails to link instead of misbehaving. -
Speed (
mtl5_bench, generic build, f64, median of three):Ventuno 1T Ventuno 4T, before → after Jetson 6T, before → after lu512²23.8 ms 179.0 → 20.7 ms 38.1 → 26.7 ms qr252 ms 329.7 → 149.6 ms 265.2 → 214.5 ms lq60.7 ms 208.1 → 42.3 ms 86.0 → 66.6 ms hessenberg353 ms 744.6 → 205.8 ms 379.5 → 315.3 ms On the i7-12700K at 8 threads the factor and BLAS entries are unchanged or up to 9% faster.
-
Also:
cpu_relaxandspin_stepmoved fromspin_pool.hpptothread_pool.hpp, so both pools use them.test_thread_poolno longer calls a Catch2 assertion on a worker thread, which ThreadSanitizer reported as a race.
-
-
The native-fast
gemvon a column-major matrix is 2.5–6× faster and no longer slower than the generic build (#804). Its kernel kept 16 rows of y in registers and swept all n columns for them, so every load came from another column and, at n = 4096, another page. It ran 2.2–5× slower than the generic build’s column sweep (#777).-
The kernel (
detail::gemv_colmajor) now sweeps 64 KB strips of y down the columns, 4 columns per pass where the target has a fused multiply-add and 2 where it has not. Each y[i] gets the same chain of operations as before, so results are bit-identical to the old kernel. -
Why 64 KB, not the 16 KB that keeps y in L1: each strip restarts every column’s contiguous run, and the Jetson’s Cortex-A78 pays for each restart (f64, n = 4096: 26 ms with 16 KB strips, 17.8 ms with 64 KB).
-
Why 2 columns without FMA: on the Xeon E5-2420 v2 (AVX, no FMA), 4 columns ran 9–10% behind the generic build at n = 16384; 2 matched it.
-
Speed:
mtl5_bench,blas2/gemv_colmajor, n = 4096, one core, median of three:machine dtype generic native-fast before native-fast after i7-12700K f64 / f32 4.76 / 2.29 ms 9.66 / 4.27 ms 3.45 / 1.69 ms Xeon E5-2420 v2 f64 / f32 13.56 / 6.60 ms 38.17 / 17.19 ms 12.98 / 6.46 ms Jetson Orin Nano f64 / f32 21.47 / 8.27 ms 63.92 / 31.40 ms 17.78 / 7.93 ms Arduino Ventuno Q f64 / f32 10.06 / 4.74 ms 47.52 / 22.77 ms 7.74 / 4.10 ms All threads, the fix is at or ahead of the generic build except the Ventuno’s f64 cell (8 threads: 34.8 ms against 26.5 generic and 28.3 before). On that machine every gemv is slower on 8 threads than on one, the row-major one included, so that cell belongs to #805.
-
Tests:
test_gemvgains sizes across the strip boundaries; the old sizes stopped at 100 rows.
-
-
The generic
gemv,trmvand forward substitution on a column-major matrix are 3–8× faster, with results unchanged bit for bit (#777). The row kernels read W rows of each column per step, so on a column-major A each step touched a new cache line, and often a new page, for a handful of elements: f32gemvran at 9% of the bandwidth roofline.-
The column sweep: on a contiguous column-major A (
dense2D) with an arithmetic accumulator (float, double, long double, integers), the kernels keep a strip of row sums in a 16 KB stack buffer, which stays in L1, and walk down each column:acc[0..S) += A(r0..r0+S-1, c) * x(c). The inner loop is lane-wise, so the compiler vectorizes it itself, one row per lane, with no Highway needed. Each row still adds the same terms in ascending column order with the same expression as the one-row loop, which is why the bits don’t change. -
The kernels:
detail::mult_rows_column_sweep,detail::trmv_column_sweep(both triangles; strips top-down for upper and bottom-up for lower, so every x(j) read is still the original) anddetail::lower_trisolve_column_sweep(each strip adds the solved columns, then solves its diagonal block column by column).detail/column_sweep.hppholds the dispatch predicate and the strip size. -
Speed: i7-12700K, n = 4096, one core, generic build:
column-major before after gemvf32 (mtl5_bench)19.1 ms, 9% of roofline 2.24 ms, 78% gemvf64 (mtl5_bench)19.9 ms, 18% 4.80 ms, 73% trmvf32 lower / upper8.46 / 6.79 ms 1.68 / 1.57 ms trmvf64 lower / upper12.3 / 8.95 ms 3.19 / 3.15 ms forward substitution f32 / f64 7.69 / 9.04 ms 1.74 / 2.98 ms -
Not row-major: vertical lanes on a row-major A need a transpose. Prototyped as a packed panel, it ran 1.4–2× slower than the scalar row kernels under GCC and Clang, plain and
-march=native. Row-major keeps the interleaved rows. Reaching the roofline there needs reassociation, which the native-fast path’s SIMD gemv already does. -
Benchmarks:
mtl5_benchgainsblas2/gemv_colmajorin f32 and f64. -
Tests:
op_test_trmv_trsv_interleavedchecks each sweep at strip sizes 1, 2, 3, 5, 8 and 16 against the verbatim one-row loops: f32, f64 and long double, both triangles, unit and non-unit, in place and out of place, and a band of rows. It also checks wrapping int32, a double A into a float y, and when the sweep applies. The existing column-major cases of the public functions now take the sweep.
-
-
Under GCC, the generic f32
gemv,trmvand forward substitution on a row-major matrix are 11–24% faster, with results unchanged bit for bit (#776). GCC’s SLP vectorizer packed the interleaved row accumulators into vector registers, filling each vector from scalar loads a whole row apart, which cost more than the vector add saved.-
The fix:
detail::keep_scalarininclude/mtl/detail/scalar_chain.hpp, an emptyasmthat holds each accumulator in a scalar register of its own. It emits no instruction and leaves the value unchanged; GCC just can no longer pack it. -
Where it applies: GCC on x86-64 or AArch64, float, a row-major matrix, and a width of at least 4. Double, column-major (where the rows of a column are contiguous and packing is cheap), Clang and MSVC keep their code as it was, because the barrier didn’t help them or made them slower.
-
Speed: i7-12700K, n = 4096, one core,
bench_interleave_rows, at the default width of 6:f32, row-major before after gemv, GCC-O33.05 ms 2.71 ms trmv, GCC-O31.71 ms 1.45 ms forward substitution, GCC -O31.65 ms 1.42 ms gemv, GCC-march=native3.79 ms 2.88 ms trmv, GCC-march=native1.76 ms 1.51 ms forward substitution, GCC -march=native1.73 ms 1.47 ms f64 and column-major times are unchanged. f32
gemvat width 6 now matches the build with the vectorizer switched off (2.72 ms). -
Tests: the row-major float cases of
op_test_trmv_trsv_interleavedtake the new path in a GCC build and are still checked bit for bit. A new case pins down exactly where the barrier applies.
-
-
The interleave width of the generic
gemv,trmvand forward substitution is a trait, and float/double default to 6 rows instead of 4 (#772). Every width gives the same bits, so the width is a pure speed knob; results are unchanged.- The trait:
interface::interleave_rows<T, Kernel>ininclude/mtl/interface/interleave_rows.hpp, withKernelone ofinterface::kernel::gemv,trmvandlower_trisolve. The three kernels (detail::mult_rows_interleaved,detail::trmv_upper_rows/trmv_lower_rows,detail::lower_trisolve_rows) are written once for any width W, and the rows left over go to W/2, down to the one-row loop. - Defaults: 6 for float and double, capped at half the target’s vector registers; 4, as before, for long double, integers and software number types.
- Overrides: specialize the trait for a type or a kernel, or set
-DMTL5_INTERLEAVE_ROWS_F32=W,-DMTL5_INTERLEAVE_ROWS_F64=Wor-DMTL5_INTERLEAVE_ROWS=W(all types). CMake passes the last from theMTL5_INTERLEAVE_ROWScache variable, which must be 1–64. - Measuring: the new
bench_interleave_rowstimes each kernel at widths 1–16 in f32 and f64 and prints the defines for the fastest on the machine it runs on. - Why 6: on an i7-12700K, 6 matched or beat 4 for every kernel in f32 and f64 under GCC (plain and
-march=native) and Clang. 8 was faster for f64 but 13% slower for f32 gemv under GCC-march=native. f32 does not reach the roofline with wider scalar chains: GCC’s SLP vectorizer packs a row-major A’s accumulators into vectors from scalar loads a row apart. With the vectorizer off, f32 gemv runs about 25% faster at every width from 4 up. - Speed:
mtl5_bench --class medium --filter blas2, generic build, n = 4096, one core, against the same build atMTL5_INTERLEAVE_ROWS=4: f64gemv3.85 → 3.75 ms (90% → 94% of the roofline), f32gemv3.69 → 3.05 ms (47% → 57%), f64trmv2.16 → 2.04 ms andtrsv2.13 → 2.03 ms (81% → 86%). f32trmvandtrsvare unchanged at about 52%. - Benchmarks:
mtl5_benchgains f32trmvandtrsventries. - Tests:
op_test_trmv_trsv_interleavedchecks the detail kernels at widths 1, 2, 3, 4, 5, 6, 8 and 16 against the one-row loops, for n on both sides of W and 2W, and a user specialization of the trait. The newop_test_interleave_rows_overridechecks that the defines reach the kernels. Both are built with-ffp-contract=off.
- The trait:
-
The generic
trmv, forward substitution andgemvtake four rows at a time, with results unchanged bit for bit (#749). Without BLAS orMTL5_NATIVE_FAST_GEMM, each row was one serial reduction, so the loop ran at one add per FMA latency, whatever the memory bandwidth.- The change: four rows share one pass over their common columns, with one accumulator each: four independent chains instead of one. Each row still sums the same terms in the same order, so the bits don’t change. The terms inside the 4×4 diagonal block are added per row, in order.
- Where:
trmv(both triangles) andlower_trisolve(both overloads), sotrsvwith a lower A as well. TheAccumulatorpaths are unchanged. - Not
upper_trisolve: row i sums in ascending j, so its first term needs x(i+1), and no two rows’ reductions can overlap without reordering them, which would change the bits. Uppertrsvkeeps its one-row loop. - Speed:
mtl5_bench --class medium --filter blas2in the generic build (f64, n = 4096, one thread) went from 42% to 87–92% of the bandwidth roofline fortrmvandtrsv, from 4.4 ms to 2.1 ms. - Test:
op_test_trmv_trsv_interleavedcompares both against verbatim copies of the old loops, in f32, f64 and long double, row- and column-major, unit and non-unit, for n from 0 to 64. It is built with-ffp-contract=off. - gemv: the generic mat*vec row loop (
detail::mult_generic_rows, behindmult_genericand the threadedmult_generic_par) does the same, four rows to one pass over x. A row band that doesn’t start or end on a multiple of 4 finishes with the one-row loop, so a threaded run is still bit-identical to a serial one. In the same benchmark, f64gemvwent from 8.4 ms to 3.8 ms (44% of the roofline to about 100%) and f32 from 6.9 ms to 3.7 ms (27% to 52–64%). f32 was thought to be still latency-bound at four chains; #772 found GCC’s SLP vectorization holding it back instead. The test also covers this loop, including a band of rows inside a block, a wrappingint32and a double A with a float y.
-
pc::ic_0andpc::ildlapply in O(nnz), andpc::ilu_0andpc::ilutset up in O(nnz), with results unchanged bit for bit (#732, #733). Each had a loop that was quadratic in n however sparse the matrix: IC(0) was about 1,000× slower per apply than ILU(0) at n = 16,384, and the ILU(0)/ILUT setup took longer than the Krylov solve that followed.-
ic_0andildlapply (solveandadjoint_solve): the Lᵀ back substitution found column i of L by scanning every later row. It now gathers from a transposed (CSC) copy of the strictly lower L, built once at factorization. Each column lists its rows in ascending order, the order the scan found them, so every x(i) subtracts the same terms in the same order. -
ilu_0setup: each row’s elimination visited every column k < i to find the few that are nonzero. ILU(0) has no fill, so it now loops over the row’s own sorted columns k < i, the same k in the same order. -
ilutsetup: the same scan, kept because ILUT’s fill must be eliminated in ascending column order. The pending lower columns are now a min-heap (Saad, Iterative Methods for Sparse Linear Systems, §10.4). Each column is pushed when it first becomes nonzero, from A or as fill, and the smallest is popped next. Fill from step k lands only above k, and a column is dropped only when it is popped, so the heap yields exactly the k the scan did, in the same order. This applies to the accumulator path too, which shares the loop. -
Bit identity: the four headers from before the change, compiled side by side with the new ones, agree bit for bit in all 37 combinations tried. These cover SPD, nonsymmetric, random-pattern and complex-symmetric matrices,
solveandadjoint_solve, the default and along doubleaccumulator, and three ILUT fill and threshold settings. -
Results on the 2D 5-point stencil, one thread, i7-12700K:
n ic_0applyildlapplyilu_0setupilutsetup4,096 9.3 → 0.037 ms 3.7 → 0.021 ms 5.5 → 0.39 ms 9.0 → 4.1 ms 16,384 129 → 0.17 ms 57 → 0.095 ms 84 → 1.5 ms 99 → 17.9 ms 65,536 — → 0.74 ms — → 0.41 ms — → 6.1 ms — → 76 ms Each 4× step in n now costs 4.0–4.4×, where it cost 10–16×.
-
mtl5_bench:krylov/cg+ilu0becomescg+ic0, CG with IC(0) as the textbook pairs them, which ILU(0) had stood in for. Thepc/ic_0andpc/ildlsetup entries lose their 64² grid cap. -
Memory:
ic_0andildlwith the default accumulator hold a second copy of L, by column. The accumulator path scatters and keeps none. -
Test:
test_pc_sparse_costtimes each operation at n = 64² and 256², a 16× step, and requires a ratio under 64×. Linear code gives 18–21×; the old loops gave 214× (ic_0) and 240× (ilu_0) when restored. It also checks the four factorizations are exact on a tridiagonal at n = 65,536.
-
-
trmvandtrsvreach the bandwidth roofline on BLAS and native-fast builds, up from 41% (#747). They had run at about 3.8 GFLOP/s in every build, whilegemvreached the roofline in the BLAS and native-fast builds.-
BLAS build: the dispatch took only a column-major A, so the default row-major
dense2Dnever reached BLAS. A row-major A is now passed to?trmv/?trsvas its buffer read column-major, which is Aᵀ: the other triangle, withtrans = 'T'. This is the same mapping #724 gave the Level 3 operations. -
Native-fast build without BLAS: above 64 rows (
detail::triangular_block), A’s diagonal is walked in blocks of 64. The SIMD gemv forms each block’s off-diagonal panel into a buffer, and the row loop forms the diagonal block and adds the buffer. Fortrmvthe blocks go bottom-up (lower) or top-down (upper), so every x(j) read still holds its original value. Fortrsvthey go the other way, so every x(j) read is already solved. Either orientation of A works. -
When it applies: float or double A and x of the same type, with the default accumulator. Rounding is BLAS’s or the SIMD gemv’s.
-
Results:
mtl5_bench --filter blas2, f64, one thread, i7-12700K, in GFLOP/s with the share of the roofline:build n gemv trmv before → after trsv before → after BLAS (OpenBLAS 0.3.32) 4096 9.50 (110%) 3.79 (41%) → 8.81 (102%) 3.80 (41%) → 9.22 (107%) BLAS (OpenBLAS 0.3.32) 8192 9.32 (102%) → 8.84 (96%) → 9.09 (99%) native-fast 4096 9.69 (100%) 3.81 (41%) → 9.15 (94%) 3.85 (41%) → 9.10 (94%) native-fast 8192 9.61 (102%) → 9.13 (96%) → 9.11 (96%) -
Generic build: unchanged, at 41%. That matches the generic
gemv(43%): both are serial per-row reductions, limited by FMA latency. -
Test:
test_trmv_trsv_fastcompares against a long-double reference for both orientations, both triangles and unit and non-unit diagonals, in float and double. It covers n = 64, 65 and 214, and both in-place and separate-btrsv. The triangle that must not be read holds NaN.static_asserts cover the traits. Mutations to the BLAS uplo and trans mapping and to the blocked path’s panel width, panel orientation and panel subtraction each fail it.
-
-
gemmtruns through a full-speed GEMM on BLAS and native-fast builds, 2.8–3.7× faster (#744). It forms half ofgemm’s product, but it was slower than a fullgemmon every build. With OpenBLAS it calleddgemmt, which takes about twice as long as OpenBLAS’s owndgemm. On the native-fast build it had no fast path at all.-
The blocked path: the triangle is halved recursively. The off-diagonal half is one rectangular GEMM, and each diagonal block of at most 64 rows is a square GEMM into a scratch tile, of which only the triangle is copied into C. The GEMM is
?gemmin a BLAS build andgemm_blockedotherwise. -
When it applies: dense
floatordoubleoperands of one type, in any orientation or astrans()views, with the default accumulator,n > 64,k > 0andα ≠ 0. With a BLAS library other than OpenBLAS that has a working?gemmt(MKL, BLIS),gemmtstill calls it. With OpenBLAS,dgemmtis still used at 64 rows and fewer, where it is as fast as the alternatives. A BLAS build without?gemmtnow takes the blocked path instead of the generic loops. -
Contract: the other triangle of C is never written before the mirror, and
beta == 0does not read C. Rounding is the GEMM’s, as formulton these builds. -
The mirror:
gemmt_fill::mirrorcopies in 8 × 8 tiles, which every path uses. A plain loop cost 1.4 ms at n = 1024, because a power-of-two leading dimension sends a column’s writes to a few L1 sets. -
congruence: above 64 rows, passes its second product to the blocked path astrans(A), with no copy. Below that it copiesAᵀas before. With OpenBLAS it is unchanged up tod = 60and 6–11% faster fromd = 150. -
Results:
mtl5_benchblas3/gemmt, f64, one thread, i7-12700K, counting n³ flops:build n before after time vs gemmBLAS (OpenBLAS 0.3.32) 512 18.9 GFLOP/s 52.3 GFLOP/s 0.70× BLAS (OpenBLAS 0.3.32) 1024 19.0 GFLOP/s 60.4 GFLOP/s 0.61× native-fast 512 about 14 GFLOP/s 51.4 GFLOP/s 0.69× The issue aimed for 0.6×. The remainder is OpenBLAS’s rate on the recursion’s small GEMMs (46–64 GFLOP/s at 64 rows and fewer) and the eighth of extra work in the diagonal blocks.
-
Test:
test_gemmt_blockedchecks every orientation of A, B and C, transposed views, both triangles and both fills, at shapes on both sides of the block size and with several levels of recursion, against a long-double reference. It also checks exactly that the other triangle keeps its sentinels, that a NaN C withbeta == 0does not reach the result, and thatalpha == 0reads neither A nor B. Mutations of the leaf range, a panel offset, a panel’s beta and the transposition for column-major and row-major C each fail it.
-
-
On the native-fast build,
trsm,trmmandsymmrun through the blocked GEMM (#724, part 3 of 3). WithMTL5_NATIVE_FAST_GEMMand no BLAS, they used a scalar loop at a fifth of the fast GEMM’s rate, even after part 2.-
trsm/trmm: walk A’s diagonal in blocks of 64 rows, the LAPACK/BLIS structure. The row loop handles each diagonal block, andgemm_blockedhandles the rest: B(I) := αB(I) − A(I, solved)·X(solved) fortrsm, and B(I) += α·A(I, rest)·B(rest) fortrmm, in the block order that leaves B(rest) unread. All but about 64/m of the flops run in the GEMM. -
symm: expands A’s lower triangle once, at O(m²) cost, and makes onegemm_blockedcall.beta == 0still doesn’t read C. -
When it applies: float or double, a dense A, a row-major B (for
symm, a row-major C), and m > 64. Other cases keep part 2’s row loops. -
Rounding is the blocked GEMM’s, as for
multon this build. -
Results:
mtl5_bench --class medium, native-fast build (Highway,-march=native), one thread, i7-12700K, in GFLOP/s:op before after share of reference trsm1.74 49.2 69% of gemm(71.4)trmm1.77 43.5 61% of gemmsymm1.00 67.1 94% of gemmsymv0.50 5.44 54% of gemv(10.0), from part 2 -
Test:
test_blas_blocked_native_fastchecks against a long-double reference:- shapes of one block, one block plus one row, and several blocks with a remainder;
- upper and lower, unit and non-unit diagonal;
- A in both orientations, f32 and f64;
- NaN in the unread triangle, and in C at
beta == 0; static_asserts on the*_uses_blocked_vtraits.
Each of 9 mutations of the block offsets, betas, ranges and order makes it fail.
-
-
The generic
trsm,trmm,symm,symv,syrkandsyr2kwalk row-major matrices row by row, with bit-identical results (#724, part 2 of 3). The old loops read a row-major operand down a column, one stride of n per access, so nothing vectorized.-
The fix: the i-k-j forms that
mult(#549) andgemmtalready use:trsm/trmm: subtract or add A(i,j) × B.row(j), one whole row at a time;symm: adds a(i,k) × B.row(k) into each row of C;symv: makes one pass over the stored triangle. Each A(i,j) is read once and feeds both y(i) and y(j);syrk/syr2k: read a transposed copy of A (and B), made once at O(m·k) cost.
-
Results are unchanged. Every entry keeps its terms, their order and its expression types, so the result is bit-identical to the old loop. The exception is a compiler that contracts across statements (GCC’s
-ffp-contract=fastwith an FMA target), which can fuse a different product in each form, as it can formult’s i-k-j loop. -
Results:
mtl5_bench --class medium, generic build (no BLAS, no Highway), one thread, i7-12700K, in GFLOP/s:op before after reference trsm1.70 14.5 gemm14.2trmm1.73 13.7 gemm14.2symm1.01 16.0 gemm14.2syrk5.57 11.5 gemm14.2syr2k10.2 13.0 gemm14.2symv0.49 5.18 gemv4.05trsmf32 went from 3.78 to 27.1 GFLOP/s. -
Test:
test_blas_row_loops:- compares each operation with a verbatim copy of its old loop, in f32, f64 and
long double, with a double alpha over float matrices, at beta 0 and nonzero, and on odd shapes; static_asserts on the new*_uses_row_loop_vtraits;- covers alpha 0 and empty shapes.
The test is built with
-ffp-contract=off, likeop_test_mult_ikj.symvnow asserts that y doesn’t alias x. - compares each operation with a verbatim copy of its old loop, in f32, f64 and
-
-
trsm,trmm,symm,symv,syrkandsyr2kcall BLAS for row-major matrices (#724, part 1 of 3). Each gated its BLAS call on every operand being column-major, so the default row-majordense2Dnever reached BLAS, even in a BLAS build.-
The fix: a row-major buffer is the column-major transpose, so the call is made on the transposed problem, as
gemvandgemmtalready do:- a row-major B makes
trsmandtrmmside'R'; - a row-major A flips op and uplo;
- row-major B and C make
symmside'R'; - a symmetric operand’s lower triangle is its row-major buffer’s upper one.
- a row-major B makes
-
Mixed orientations:
symmneeds B and C in the same orientation, andsyr2kneeds A and B in the same orientation. Other mixes keep the generic path. -
Results:
mtl5_bench --class medium, OpenBLAS, one thread, i7-12700K:op before (GFLOP/s) after (GFLOP/s) gemm symm1.0 72.7 72.7 trsm1.75 63.1 72.7 trmm1.76 63.8 72.7 syr2k10.9 57.2 72.7 syrk5.7 53.2 72.7 symv0.45 17.5 9.8 (gemv) trsmf32 went from 3.7 to 140 GFLOP/s. -
Builds without BLAS are unchanged. Parts 2 and 3 address them.
-
Test:
test_blas_layout_dispatch:static_asserts on the new*_dispatches_blas_vtraits, so a return to the column-major-only gate fails to compile;- every orientation combination in f64 and f32, on non-square shapes, against a long-double reference;
- NaN in the triangle that must not be read.
A mutation test of each mapping (uplo, op, side, dimensions, leading dimension) fails it.
-
-
math::givens_rotationtakes the plain formula for ordinary magnitudes, about 4x faster for double and 6x for float (#697). Since #671 every call extracted an exponent and made three power-of-two scalings, even when nothing needed scaling. The rotation is in the inner loops of GMRES, MINRES and the implicit QR sweep.- The fix: when the larger magnitude lies in an interval where
a*a + b*bcan neither overflow nor lose a term to underflow, about (2^-483, 2^510) for double, the rotation isr = sqrt(a*a + b*b),c = a/r,s = b/r. Outside it, the scaled path is unchanged. - Who gets it: any type whose
std::numeric_limitsdeclares a binary IEEE format (is_iec559, radix 2), including a user-defined one. Tapered types such as posit and takum don’t declare it, and keep the scaled path, which keeps their arithmetic near 1, where they are most precise. - Results: in the interval, the same r as before, and the same c and s except where one of them is subnormal, where the new value is the correctly rounded quotient.
bench_givens, 20M calls on values in [1, 2): double 0.258 s → 0.062 s, float 0.297 s → 0.044 s.
- The fix: when the larger magnitude lies in an interval where
-
CI checks that
mtl5_benchcovers all of MTL5, and matrix results are checked on every entry (#721, milestone M7).- Coverage manifest:
benchmarks/platform/coverage.txtmaps each of the 150 public headers in the operation, solver, preconditioner, factorization, ordering and eigensolver directories to one of four things: the entry that measures it, the entry it runs inside, an entry of the same kernel class, or a written exemption. 23 headers are exempt, all of them queries, predicates, I/O, umbrella includes or plumbing. benchmarks/check_coverage.shfails in the benchmarks CI lane on any of these:- a header with no line;
- a line for a header that is gone;
- an entry name that
mtl5_bench --listdoesn’t have; - an exemption with no reason.
- DotK: a new entry,
blas1/dot_k3, brings the catalogue to 107. It runsdot_k<3>on an integer dot product built to cancel, so the exact answer is an int64 sum, and checks it against the Ogita–Rump–Oishi bound. A plain dot misses that bound by a factor of about 10⁷. - Freivalds’ check for matrix results: level-3 BLAS (gemm, gemmt, symm, syrk, syr2k, trmm, trsm, kron),
inv, Schur, SVD,expm,sylvesterand the f32→f64 GEMM keep their 64-sample check and add Freivalds’ check. It compares C·x with the product applied factor by factor, such as A·(B·x), for two probe vectors, so it covers every entry in O(n²). For residuals (A·X − I, Q·T·Qᵀ − A, …) it checks the normwise bound in the matching norm. Both checks must pass.- What the samples missed: in mutation tests, the 64 samples missed a single wrong GEMM entry, one wrong entry in GEMMT’s mirrored triangle, a partial SYRK row and one Kronecker entry. Freivalds caught all four, and every other mutation tried.
- Platforms: the tolerances hold with
long doublethe same asdouble(tested withg++ -mlong-double-64), as on MSVC and Apple ARM64.
- Coverage manifest:
-
mtl5_benchcovers mixed precision, integer kernels and thread scaling (#721, milestone M6). There are 12 new entries, bringing the catalogue to 106:- Mixed precision: f32→f64 dot and GEMM, checked at the f64 bound so that a kernel accumulating in f32 fails; and the block-scaled int8 dot (Q8_0), with each block checked on its own.
- Integer: dot and GEMM at i32, i16→i32, i8→i32 and u8×i8→i32, plus
mult_quad. These are exact, with GEMM checked by Freivalds’ C·x = A·(B·x) in int64. They report GOP/s and no %roof.
Thread scaling:
mtl5_bench --baseline FILEreports each entry’s speedup and parallel efficiency against a run at fewer threads, and refuses a baseline from another size class. The card adds a scaling column and a per-area median efficiency.platform.shandplatform.ps1pass each variant’s 1-thread JSON as the baseline for its other runs.The mutation runs found two blind spots, both fixed:
- Integer GEMM checks sampled 64 entries. Corrupting every third diagonal entry passed. They now use Freivalds, which sees every entry.
- The block-scaled total is bound by f32 summation. It now also checks every block against
γ_32.
All 106 pass at every class with GCC 15, and at
smallwith Clang 18, with a 64-bitlong double, and on aarch64 under QEMU.Findings, not addressed here (i7-12700K):
- Plain
mult(A, B, C)with f32 A and B and an f64 C is only f32-product accurate (about 1e-8), because C++ promotion rounds each product in f32.mult<double>is accurate to 1e-16, and the entry uses it. mult<double>on f32 operands runs at 4.3 GFLOP/s, against about 20 for f64 GEMM. It doesn’t reach the blocked kernel.- The 4-thread median parallel efficiency of the BLAS level-3 entries is 25%, because most of them run serially. The cause is the same as #724.
-
mtl5_benchcovers Krylov solvers, preconditioners, smoothers, multigrid and the sparse eigensolvers (#721, milestone M5). There are 28 new entries, bringing the catalogue to 94, and each has a check that a wrong result can’t pass:- Krylov solvers (
cg,minres,bicg,bicgstab,bicgstab_ell,cgs,gmres,qmr,tfqmr, andidr_sat s = 1, 2, 4 and 8): the solver reports convergence, and the true residual is ≤ 1e-6. - Preconditioner setups (
diagonal,ilu_0,ilut,ic_0,ildl,ssor,block_diagonal): each must cut the Krylov iteration count to at most ¾, and the diagonal one must also match b_i/a_ii exactly. - Smoothers (
jacobi,gauss_seidel,sor): each sweep satisfies its defining splitting row by row, withinγ_k. - Multigrid: a 2D Poisson V(1,1) hierarchy with tensor-product transfers and Galerkin coarse operators must reach 1e-6 in 10 cycles.
- Shift-invert: convergence, and the analytic smallest eigenvalues to 1e-10. The generated Laplacian and convection–diffusion matrices have closed-form spectra.
- Lanczos, Arnoldi and power iteration: a Bauer–Fike enclosure of every returned pair, plus rigorous upper bounds (Cauchy interlacing, and the numerical range for Arnoldi) and an accuracy floor.
The mutation runs found three checks too weak (a near-correct diagonal preconditioner, and eigenvalues shifted together with their error bars), and those checks were strengthened. All checks then fail on corrupted results. All 94 pass at every class with GCC 15, and at
smallwith Clang 18, with a 64-bitlong double(as on MSVC and Apple ARM64) and on aarch64 under QEMU. Run time on an i7-12700K with one thread: about 11 s / 70 s / 7.5 min.The run found these problems, which aren’t addressed here:
- TFQMR fails on unsymmetric systems. On convection–diffusion it stalls at a 6–9% residual after thousands of iterations with any preconditioner, where BiCGSTAB converges in 13–52. Its unit tests use only symmetric matrices (the “non-symmetric” 3×3 case is symmetric). On the SPD Poisson matrix it converges, but needs 10× BiCGSTAB’s iterations; the entry runs there.
- The
pc::ic_0andpc::ildlapplies are quadratic in n: 131 ms and 57 ms per apply at n = 16384, against 0.14 ms forilu_0. CG is therefore paired with ILU(0), the same incomplete factor on an SPD matrix, and theic_0/ildlsetup entries are capped at a 64² grid. - The
pc::ilu_0andpc::ilutsetups are quadratic in n: 0.4 ms, 82 ms and 1.3 s at n = 1024, 16384 and 65536.
- Krylov solvers (
-
mtl5_benchcovers sparse kernels, sparse direct solvers and orderings (#721, milestone M4). There are 16 new entries, bringing the catalogue to 66. Every input is generated (2D Poisson, unsymmetric convection–diffusion, scrambled copies, a planted block-triangular matrix), so nothing is downloaded. Each check is one a wrong result can’t pass:- SpMV, transposed SpMV on an unsymmetric matrix, CRS×dense: per-row error against
γ_k·|A||x|. - SpGEMM: C·x against A·(A·x).
- Level-scheduled lower solve: the componentwise backward error of each row.
- Direct solvers (
sparse_cholesky,sparse_ldlt,supernodal_ldlt,sparse_lu,supernodal_lu,native_klu,sparse_qr): the backward error of the solve. - AMD and COLAMD: a valid permutation, with at most half the Cholesky fill of the scrambled natural order (of A, and of AᵀA).
- RCM: a bandwidth within 4× of the grid side.
- Block-triangular form: valid permutations, a zero-free diagonal, no entry below its block, and at least the planted number of blocks.
Every check was confirmed to fail when its result is corrupted. That process caught an
amdcheck that measured a fresh AMD call instead of the permutation under test. Timing-only entries now shown/ainstead of 0%. All 66 pass at every class with GCC 15, and atsmallwith Clang 18 and on aarch64 (NEON) under QEMU. Run time on an i7-12700K with one thread:smallabout 10 s,mediumabout 55 s,largeabout 5.5 minutes.These findings aren’t addressed here (medium class, generic build, 96² grid):
sparse_qr: 4.1 s per solve, more than 50× any other solver on the same matrix (native_klu17 ms,supernodal_ldlt9 ms). The entry runs QR on half the grid side until this is fixed.sparse_cholesky: 73 ms, slower thansparse_ldlt(27 ms) and 8× slower thansupernodal_ldlt. At the large grid the gap is 17× (900 ms against 52 ms).supernodal_lu: 56 ms, slower than the non-supernodalsparse_lu(41 ms).
- SpMV, transposed SpMV on an unsymmetric matrix, CRS×dense: per-row error against
-
mtl5_benchcovers dense factorizations, eigensolvers, SVD, matrix functions and element-wise kernels (#721, milestone M3). There are 25 new entries, bringing the catalogue to 50, and each has a check that a wrong result can’t pass:- Factorizations (
lu,cholesky,ldlt,ldlt_bk,qr): the backward error of a solve. lq: L·Lᵀ against A·Aᵀ.hessenberg: its structure, plus the trace and Frobenius invariants.inv: A·X = I.lu_iterative_refine: the f64 backward error it reaches.- Eigenvalues (symmetric and general): traces of the powers of A.
- Eigenvectors: A·v = λ·v and Vᵀ·V = I.
schur: Q·T·Qᵀ = A, orthogonality, and quasi-triangular structure.svd: U·S·Vᵀ = A, orthogonality, and the ordering of S.expm: expm(A)·expm(−A) = I.sylvester: its residual.- Householder: H·x = β·e₁.
- Element-wise functions:
std::per element.
Every factorization and eigen check was confirmed to fail when its result is corrupted. All 50 pass at every class (
small,medium,large) with GCC 15, and atsmallwith Clang 18 and on aarch64 (NEON and SVE_256) under QEMU. Run time on an i7-12700K with one thread:smallabout 9 s,mediumabout 45 s,largeabout 4 minutes. Rates use the conventional LAPACK operation counts. The shared check helpers moved tobenchmarks/platform/common.hpp.The first run found these gaps, which aren’t addressed here (medium class, generic build):
qr_factoris 10× slower thanlq_factorfor the same work: 217 ms against 22 ms at n = 512.- Bunch–Kaufman
ldlt_bkis 7× slower thanldlt. eigenvalue()defaults to a deflation tolerance of 1e-10. It therefore stops short of full accuracy, whileschur()runs the same iteration at machine epsilon. The benchmark callseigenvaluewithtol = eps.
- Factorizations (
-
benchmarks/platform.shandplatform.ps1: characterize a machine with one command (#721, milestone M2). After agit clone,benchmarks/platform.shdoes the whole job:- gates the session with
preflight, before the builds and again after them; - builds
mtl5_benchfor thenative,native-fastand (if a system BLAS is found)blasvariants, all before any measurement; - runs each variant at 1 thread and at all CPUs, with every vendor library’s thread pool pinned to the same count;
- writes per-run JSON, with
.sysinfosidecars that carry the machine state, plus markdown capability cards and asummary.md.
native-fastdoesn’t use-march=nativeon SVE hardware, because of #720, or on macOS. A new CI job runs the script at--class smallon Linux x64, Linux ARM64, macOS and Windows.mtl5_benchgains--card FILEand--machine NAME.- The FMA ceiling is now the machine’s, not the build’s. M1 measured it over
simd::batch, which is scalar in a build without Highway, so thenativeandblasvariants reported GEMM at 2,300% and 39,000% of “peak”. A hardware probe now picks the widest ISA the CPU and OS support at run time (AVX-512F, AVX2+FMA or SSE2, checking CPUID and XCR0; NEON on AArch64), and the roofline uses the higher of the two peaks. mtl5_benchis now built in CI. Thebenchmarksjob’s target list didn’t include it, although the M1 PR said it did.
- gates the session with
-
mtl5_bench, the platform benchmark: milestone M1 (#721). One binary that characterizes a machine the same way every time.- Probes first: it measures the FMA peak (f64 and f32) with the build’s own SIMD target. It measures memory bandwidth with three-stream read, update (
a += s*b) and STREAM triad, and takes the best as the ceiling. - Then the registry: it runs every registered operation at a fixed size for
--class small|medium|large. Each result is checked against a long-double reference using thegamma_kerror bound, so a fast wrong answer is a failure. Each rate is reported as a percentage of the roofline for its arithmetic intensity, and a bandwidth-bound result that fits in the last-level cache is flagged. - Output: a console table, plus
--json FILEwith aFILE.sysinfoprovenance sidecar.benchmarks/check_sidecars.shnow also requires sidecars for committed JSON results. - Coverage so far: 25 entries across BLAS levels 1–3 (
dot,axpy,scale, the norms,sum,gemv,symv,trmv,trsv,ger,gemm,gemmt,symm,syrk,syr2k,trmm,trsm,kron), in f64 and, for the key kernels, f32. - Run time on an i7-12700K with one thread:
smallabout 5 s,mediumabout 20 s,largeabout 85 s. - First findings: in the generic build,
symm,trmmandtrsmreach 1–2% of the roofline at n = 512, against 25% forgemm.symvreaches 5% against 46% forgemv. - The remaining areas follow in later milestones of #721.
- Probes first: it measures the FMA peak (f64 and f32) with the build’s own SIMD target. It measures memory bandwidth with three-stream read, update (
-
Fixed-length SVE support in
simd::batch(#717).batchpreviously compiled for no SVE target at all, because Highway’s SVE vectors are sizeless ACLE types (svfloat32_t, …) and a sizeless type cannot be a class member. On the fixed-length targets (-msve-vector-bits=N, Highway’sSVE2_128andSVE_256),batchnow stores the register as a fixed-length ACLE type (arm_sve_vector_bits(N)). NEON and x86 builds are unchanged. A build with-mcpu=neoverse-n2 -msve-vector-bits=128gets real SVE2 code withbatch<float>::size == 4. Such a binary is correct only on a machine whose SVE vector length is 128 bits. The scalable targets (no-msve-vector-bits) are still demoted to the scalarbatch(#427).
-
Build and test aarch64 code on an x86 host, under QEMU. There’s a new toolchain file,
tools/cmake/toolchains/aarch64-linux-gnu.cmake, that cross-compiles withaarch64-linux-gnu-g++(or clang withMTL5_AARCH64_CLANG=ON) and makesctestrun every test throughqemu-aarch64.MTL5_QEMU_CPUselects the emulated core, and with it the SVE vector length. Four presets go with it, each with a-simdtest preset:aarch64-neon: NEON, emulated Neoverse N2.aarch64-sve2-128: fixed-length SVE2 at 128 bits, emulated N2.aarch64-sve-256: fixed-length SVE at 256 bits, emulated Neoverse V1.aarch64-sve2-scalable: scalable SVE2, at any emulated width.
All four pass the 11 SIMD tests.
SVE_256had never been built or run before, because CI’s ARM runners are 128-bit. The scalable build passes at 128, 256, 512 and 2048 bits.The emulation is for correctness only: timings under it say nothing about hardware. Running a fixed-length binary at the wrong width confirmed the hazard in
docs/performance/arm64-simd-neon-sve.md(R3):SVE_256at 128 or 512 bits crashes in every SIMD test.SVE2_128at 256 bits fails 6 of 11 tests, and passes the other 5.
-
Highway lanes on Linux ARM64 (#717). The
highwayjob now also runs on the Neoverse N2 ARM64 runners, in three lanes:- NEON, the default ARM64 Highway build, on GCC 13 and Clang 18 with the full suite. No CI job compiled it before.
SVE2_128, GCC 13 with the full suite. It refuses to run unless the runner’s SVE vector length is 128 bits. GCC only, because Highway 1.4.0 marksSVE2_128broken before Clang 21.native,MTL5_NATIVE_ARCH=ONwith GCC 13, running the SIMD tests. It confirms that-march=nativeon an SVE machine selects scalable SVE2, sobatchfalls to one lane and a “native” build has no SIMD.
Each lane names the Highway target it exists to cover (
MTL5_TEST_EXPECT_HWY_TARGET), andtest_batchfails to compile on any other target.test_batchalso requiressize > 1on AArch64, as it already did on x86-64, except on a scalable target, where it pinssize == 1until #427. The Highway cache key now includes the architecture and the lane.
Documentation
Section titled “Documentation”-
Session log for 2026-11-12 – 2026-11-13:
docs/sessions/2026-11-13-it-was-never-measured-there.md. Covers #811 to #821 and the six issues they closed (#795, #799, #804, #805, #806, #810): the direct solvers against CHOLMOD and PARDISO, the Ventuno’s threaded LU, its baseline-Armv8 build, and thekeep_scalarbarrier on AArch64. Its through-line is that four of the problems were settings measured on one machine and applied to another nobody had measured: the barrier (x86-64 to AArch64),-march=native(which GCC 13 resolves to nothing on the Ventuno), the thread pool’s sleep (cheap to wake on x86, 1.5–1.8 ms on the A78C), and CHOLMOD 5’snthreads_maxon the Jetson’s CHOLMOD 3. It also records that the 2026-11-11 sidecars had the two ARM boards’ build ISAs right while the issue and the pages had them swapped. -
ARM64 SIMD: NEON, fixed-length SVE2 and scalable SVE2 (#717). It covers which Highway target each set of compiler flags selects, with GCC and with Clang, and the requirements #716 and #717 found:
- sizeless SVE types can’t be stored in
batch; SVE2_128needs I8MM and BF16 in the flags;- a fixed-length binary is tied to its vector length;
MTL5_NATIVE_ARCH=ONwith GCC on SVE hardware loses SIMD.
It also sets out the performance work for each target, with the experiment that would test each claim. For scalable SVE (#427) it compares runtime-dispatched fixed-length kernels with fully vector-length-agnostic ones. No number in it has been measured.
- sizeless SVE types can’t be stored in
-
multwith a zero inner dimension, on every kernel path (#714).multassigns, so an m×0 times 0×n product must be the zero matrix and an m×0 matvec the zero vector, whatever C or y held before. Only the default dense GEMM path had a test for this.test_mult_ikjnow covers the rest: the generic GEMM’s row-major, col-major andtrans()paths, its accumulator path, the packed-panel accumulator kernel (#587), the matvec with and without an accumulator, and the CRS × dense and CRS × vector products. In each one, making the kernel skip its store when there are no terms fails the matching section. Six of those nine breaks failed no test before. -
Tests that only needed a class wrapping a double now use
double_shim(#712).test_mult_ikj,test_cholesky_orderingandtest_householder_textbookdropped their localemul, and their bit-for-bit comparisons still hold. Each one was checked by breaking, for non-native types only, the code itsdouble_shimcases cover: the i-k-j summation order, both Cholesky orderings, the textbook reflector’s sums and update, and the textbook QR and LQ falling back to the default reflector. Every break fails adouble_shimassertion. Four tests keep their own type on purpose, with a comment saying why:test_mult_generic_mtandtest_mult_sparse_mt: the multiply records which thread ran it, and the tests that check rows are split across threads rely on that.itl/test_field_requirementanditl/test_pc_field_requirement:emulhas only the five field operators, so a solver or preconditioner gate that asks for more than a Field rejects it. Both tests now also assert that every gate acceptsdouble_shim, which catches a gate that requires an implicit conversion from double.
-
native_shim, a user-defined float for testing genericity over the number type (#703).float_shimanddouble_shimare intests/support/mtl5_test/native_shim.hpp, which every test can include and which is not installed. Each holds a native float or double and rounds exactly as it does, but is a class:- it is not
is_floating_pointoris_arithmetic; - it converts to or from a native type only explicitly, and has no mixed operators;
- its math functions are found only by ADL, so a qualified
std::sqrt(x)does not compile.
test_shim_genericityruns norms, dot, axpy, gemv, gemm, kron, LU, QR, Cholesky, Householder, Givens,pow2_scaling, the SVD, the symmetric eigensolvers, CG, BiCGSTAB, GMRES and MINRES (with identity, diagonal and ILU(0) preconditioners), the projections, and the property predicates on both shims. It compares each result with the native one: bit for bit where MTL5 runs the same code for both, and within a few eps where native types take a BLAS, LAPACK or SIMD path. A qualifiedstd::frexpin thetwo_normrescan (#700) makes it fail to compile. Gating that rescan onis_floating_pointmakes it fail at run time. Both tests carry the CTest labelgeneric. - it is not
-
Regression tests for the recent factorization and rotation changes that no test exercised (#698). Each new test fails when the behaviour it covers is removed, which was checked by breaking the code locally; none of these lines failed a test before.
- MINRES and
eigen_symmetricscaled rotations (#671): both now run on an operator of 2^600 and one of 2^-600 (test_pow2_scaling). With the unscaled rotation, MINRES reports convergence with x = 0 at 2^600 and breaks down at 2^-600, andeigen_symmetricreturns NaN eigenpairs. - The identity rotation for x = z = 0: a 3x3 fixed-point tridiagonal whose QR sweep rounds both to zero, for
eigenvalue_symmetric_genericandeigen_symmetric(test_householder). Double never reaches this case. - Complex
householder_reflector: beta is real, of magnitude ||x||, opposite in sign to Re(x0), and H x = beta e_1, at scales far from 1; plus the zero-tail cases. lq_normalize_signson a complex L (test_qr), andrandorth’s sign normalization (test_randorth): withoutqr_normalize_signs, Q(0,0) is negative on every draw.- Already covered: the Hessenberg and
eigen_symmetricpivot signs from #678 and the subnormal Householder scaling fail existing tests when broken, so they needed none.
- MINRES and
[5.23.0] - 2026-11-05
Section titled “[5.23.0] - 2026-11-05”Three fixes, each found by a study or a downstream project. dense_vector and dense2D build with exceptions disabled, for flight-control firmware (#652). pow2_scaling’s fallback finds the right exponent near the ends of a tapered type, so Givens rotations and Householder reflectors scale correctly in posits and takums (#680). Householder factorizations store the reflector’s β as the pivot, so qr_solve no longer divides by a pivot that rounded to zero in fixed point (#678). It is a minor release because #678 adds householder_reflector. Nothing is breaking: in float and double the factorizations’ pivots move by a rounding, and with exceptions enabled the thread pool’s names and layout are unchanged.
-
dense_vectoranddense2Dcompile with exceptions and RTTI disabled (#652). Firmware builds with-fno-exceptions, but including either header failed. GCC reports only the first such error in a translation unit, the thread pool’stry/catch, so the pool looked like the only blocker. Clang lists every error, and that shows thethrows in the bounds-checked element accessors fail too, on both compilers, so fixing the pool alone would not have been enough. This blocked branes-ai/reflex’s flight-control code, which uses the fixed-size, on-stack types.- The fix: a new header,
mtl/detail/exceptions.hpp, definesMTL5_HAS_EXCEPTIONSfrom the compiler’s own flags; you can also define it yourself.thread_pool,spin_pooland the aligned allocator compile out theirtry/catchwhen exceptions are off. The containers’throws go throughdetail::throw_or_abort, which callsstd::abort()instead, as an uncaught exception would have. - The pool’s names carry the mode: without exceptions the pool’s inline namespace is
pool_shared_noexcorpool_local_noexcinstead ofpool_sharedorpool_local. The workers runworker_loop()as compiled where the pool was built, and without exceptions it has nocatch. If an exception-enabled module ran a throwing task on such a pool, the process would terminate. With the mode in the names, that module fails to link against anmtl5_poolbuilt the other way. Two translation units built different ways each get their own pool rather than sharing oneworker_loop(). - What changes: nothing when exceptions are enabled. The names and layout are as before.
- Test:
build_test_no_exceptions_{default,spin,shared}builds both headers with-fno-exceptions -fno-rtti -Werroron GCC and Clang, with bounds checking forced on. It runs once per pool mode, and it asserts that the pool is in the_noexcnamespace. It runs in every Linux and macOS CI job. Against the old headers it fails on both compilers.
- The fix: a new header,
-
pow2_scaling’s fallback finds the right exponent at a tapered type’s coarse ends, in O(log |e|) (#680).givens_rotation,householder()andhouseholder_reflector()scale by an exact power of two throughmath::pow2_scaling<T>. For a type withoutstd::ilogb, itsexponent(m)halved m one binade at a time and stopped when a halving did not decrease m, taking that for a non-finite m.- The wrong exponent: near the ends of a posit with es = 2, or a takum, not every binade is representable, so m·½ can round back to m. The search then stopped early, often at e = 0, and the rotation squared unscaled values. Rerunning the Givens and Householder study against 5.22.0 measured
givens_rotationat 2.0×10⁹⁰ ε in posit<64,2> and 7.1×10⁷² ε in takum<8>, against 1 ε for the power-of-two remedy it adopted (stillwater-sc/mp-numerics#21). - The cost: both
exponent()andscale()took one multiplication per binade: 88 ms per call for cfloat<256,19> near 2²⁰⁰⁰⁰⁰. The study’s full run went from about 4 minutes to 2.2 hours. - The fix: the fallback uses two ladders of exact powers, 2^(2^i) and 2^−(2^i), each rung the square of the one before, kept while the square is exact, and built once per type. A type that converts to
double(all of Universal’s do) has its exponent read from that conversion, which is exact inside double’s range; the rungs only bring m into that range, so cfloat<256,19> takes about 0.5 ms instead of 88. Stepping alone would not do: near takum<8>‘s maxpos its values lie farther apart than its largest exact rung, 2^8, so m / 2^8 rounds back to m. A type with no conversion is stepped by the rungs, and a step that leaves m unchanged ends the search.scale()multiplies once by 2^k, taken fromdoublewhere it is a value of T, otherwise formed from the rungs, so it still rounds once. - Checked against Universal:
exponent()now agrees with mp-numerics’binary_exponentfor posit<16,2> and posit<64,2> out to their ends (2⁵⁶ gives 52, the old fallback 0), for takum<8> (2²⁵⁰ gives 239, against 0), and for cfloat<128,15> and cfloat<256,19>. In each of those casesgivens_rotationreturns the remedy’s c and s. - What changes: the
std::floating_pointtypes keepstd::ilogbandstd::ldexp, so their results are unchanged. A user-defined type gets the same exponent wherever the old search found the right one.
- The wrong exponent: near the ends of a posit with es = 2, or a takum, not every binade is representable, so m·½ can round back to m. The search then stopped early, often at e = 0, and the rotation squared unscaled values. Rerunning the Givens and Householder study against 5.22.0 measured
-
Householder factorizations store the reflector’s β as the pivot (#678). The default
qr_factor,lq_factorandhessenberg_factor, andeigen_symmetric’s tridiagonalization, applied each reflector to its own pivot column (or row), so the pivot was recomputed as x₀ − τ(vᵀx) instead of set to the β the reflector maps x onto.- In fixed point, the products v(i)·x(i) of a column near the type’s resolution round to zero, so the pivot came out exactly 0 although β is representable, and
qr_solvedivided by it. - Found by the decompositions study (stillwater-sc/mp-numerics#20). After
qr_factor,qr_solvedivided by zero in 72 of 404 fixpnt<16,8> least-squares problems and 12 of 558 fixpnt<32,16> problems; with β stored, none do. Universal’s fixpnt reports a division by zero by printing and returning maxpos, so the study first saw it as a forward error of 426 (stillwater-sc/universal#1894). - The fix stores β, as LAPACK’s xGEQR2, xGELQ2, xGEHD2 and xSYTD2 store
dlarfg’s, and applies the reflector to the trailing columns (or rows) only. - What changes: in float and double the pivots, and what is computed from them (the solution of
qr_solve, Schur forms, eigenvalues), move by a rounding; they aren’t bit-identical. Q is unchanged. The LAPACK and textbook paths are unaffected.
- In fixed point, the products v(i)·x(i) of a column near the type’s resolution round to zero, so the pivot came out exactly 0 although β is representable, and
householder_reflector(x)returns{v, tau, beta}, with H x = beta e₁ (#678).householder(x)delegates to it and still returns{v, tau}, so existing structured bindings compile unchanged. When tau == 0, beta is x(0).
- The PowerShell parse test is skipped on Apple platforms (#682). On the macos-latest runner image, launching
pwshfails in LaunchServices with a timeout before it parses anything, and leaves orphanedpwshprocesses, sobench_powershell_parsefailed on main from the #679 merge on. The Linux and Windows runners still parse the same harnesses.
Documentation and maintenance
Section titled “Documentation and maintenance”-
A daily QA sweep for scheduled runs: the
/qa-sweepskill and the read-onlyqa-revieweragent, synced into.claude/skills/and.claude/agents/from theqa-sweepplugin in stillwater-sc/claude-plugins, with MTL5’s build commands, area rotation, sanitizer pass and review focus in.claude/qa-sweep.md. Each run builds and runs the unit tests, reviews the commits since the last sweep, takes a deep pass over one of eleven areas in rotation with ASan and UBSan, and files its findings as one issue labelledqa-sweep. It does not edit, push or comment; the next run finds its starting commit in the last sweep issue. -
The Givens/Householder study and history pages give the study’s type count as 57, not 65. The results they report (stillwater-sc/mp-numerics@382bcea) cover 57 types; 65 was a miscount carried over from the study’s README.
-
The docs site links to the mp-numerics site (stillwater-sc/mp-numerics#22): a “Studies across number systems” section on the landing page, a Related sidebar group with mp-numerics and Universal, and links from the Givens/Householder study and history pages to the published studies.
-
The docs site’s “Edit page” links point at the source files. Starlight joins
editLink.baseUrlwith the generatedsrc/content/docs/path, so every link went to a file that does not exist, such asdocs/src/content/docs/getting-started/index.md.sync-content.mjsnow gives each page aneditUrl:docs/<page>for the synced and site pages, and the file itself for those synced from outsidedocs/:CHANGELOG.md,benchmarks/README.mdand the others. All 85 pages’ links now resolve to tracked files. The same fix went into mp-numerics’ new site (stillwater-sc/mp-numerics#23). -
Session log for 2026-11-01:
docs/sessions/2026-11-01-the-docstring-still-said-q-equals-i.md. Covers the 5.22.0 tag and its rollout to the peer repos:- mtl5-python moves to MTL5 v5.22.0 (mtl5-python#120), and its 5.22.0 is on PyPI;
- mp-dsp’s headers-only fallback moves from v5.12.0 to v5.22.0 (mp-dsp#219);
- mp-dsp-python’s floor and pin move to 5.22.0 (mp-dsp-python#136).
Every repo built against 5.22.0 and every bump PR’s CI passed; the local runs’ only failures were environmental, as the log records per repo. No binding source changed. What went stale was the text: mtl5-python’s tests, docstrings and a comment still described the narrow formats’ Q = I fallback, which #675 removed.
[5.22.0] - 2026-11-01
Section titled “[5.22.0] - 2026-11-01”The plane rotations and reflectors that QR, LQ, GMRES, MINRES and the symmetric eigensolver are built on now hold up across the element type’s whole range and precision. A study of Givens rotations and Householder reflectors in 65 number systems, published with this release (#667–#670), found that the forms MTL5 used fail where a type is narrow, tapered or near its range limits. Givens rotations now scale by an exact power of two before squaring (#673). Inside the old range the results are bit-identical under separately rounded arithmetic (FMA contraction can move them by an ulp); outside it, the old form returned inf, 0 or NaN. householder() now reflects onto LAPACK dlarfg’s sign, which bounds every entry of v by 1 (#675).
One breaking change: R’s diagonal in qr_factor, and L’s in lq_factor, is now −sign(x₀)·‖x‖, the sign LAPACK’s geqrf gives, instead of non-negative. Q·R = A is unchanged. qr_normalize_signs and lq_normalize_signs restore the old convention.
Changed
Section titled “Changed”- BREAKING:
householder()reflects onto LAPACK’s sign, so R’s diagonal is −sign(x₀)·‖x‖ (#672). The real default reflector used Parlett’s v₀ = −σ/(x₀ + ‖x‖) for x₀ > 0 and reflected onto +‖x‖, which made R’s diagonal non-negative. It now takesdlarfg’s sign, as LAPACKgeqrf, the textbook form and the complex path do, with sign(0) = +1.- What changes for callers: wherever a pivot entry is ≥ 0,
qr_factor’s R(k,k) and the matching column of Q change sign, and so dolq_factor’s L(k,k) and the matching row of Q, and the Hessenberg reduction’s subdiagonal. Q·R = A and Q’s orthogonality hold either way, so only code that reads those signs, or compares Q, R or L entrywise, is affected. The complex path changes only where Re(x₀) = 0, which now takes −‖x‖, aszlarfgdoes. - Why: for a small tail Parlett’s v₀ is small and v(1) ≈ −2x₀/x(1) is large, and a tapered or fixed-point type has few bits there. The Givens and Householder study measured worst orthogonality on its tail sweep of 8.0×10⁵ ε for posit<64,2>, 512 ε for posit<32,2> and 2.4×10³ ε for fixpnt<32,16>, against 4.1, 3.8 and 2.8 ε with
dlarfg’s sign, where every |v(i)| ≤ 1; double goes from 7.4 to 4.0 ε. In a fixpnt<16,8>-like type, the first column of mtl5-python’s QR fixture now keeps a reflector accurate to the type’s 2⁻⁸ resolution, where #662 had to fall back to H = I. - One convention: the generic
qr_factorand thegeqrfpath of a LAPACK build now give the same R, signs included; they disagreed wherever x₀ > 0. - To keep the old convention,
qr_normalize_signs(Q, R)andlq_normalize_signs(L, Q)(new) negate rows of R, or columns of L, and the matching parts of Q to make the diagonal non-negative, which for a full-rank A is the unique such factorization.generators::randorthuses it, so the distribution of its Q is unchanged. - The reflector also scales x by an exact power of two instead of dividing by max |xᵢ|, through
math::pow2_scaling(#671), so the scaling rounds nothing. A complex x is still divided by max |xᵢ|. - Documented in
docs/numerical/householder-reflector-forms.md.
- What changes for callers: wherever a pivot entry is ≥ 0,
- Givens rotations scale by an exact power of two (#671, #673).
apply_givens_rotation(GMRES’s Hessenberg QR), MINRES, andeigenvalue_symmetric’s implicit QR step and Wilkinson shift formed r = sqrt(a² + b²) unscaled. The squares overflow once |a| passes sqrt(max) and underflow below sqrt(min), so the rotation was correct on only about half of each type’s exponent range: in double, ‖x‖ from 2^−533 to 2^509 of 2^−1074 to 2^1023. They now scale a and b by 2^−e, where 2^e ≤ max(|a|, |b|), so the squares sit near 1.- Measured in the Givens and Householder study, worst ‖QᵀQ − I‖ over the whole exponent range: double 1.46 ε, posit<64,2> 2.01 ε, takum<64> 3.65 ε, dd 3.79 ε. LAPACK’s
lapy2max-scaling anddlartgsafe scaling each fail somewhere in those four types, by up to 10³¹ ε. - Results: in a binary type the scaling rounds nothing, so float and double results inside the old band are bit-identical under separately rounded arithmetic. Only inputs where the old form overflowed, underflowed or lost bits change.
eigenvalue_symmetricof a tridiagonal scaled by 2^600 now gives its eigenvalues, where it returned NaN. - The Wilkinson shift’s b²/(δ + sign(δ)·hypot(δ, b)) is now b·(b/(…)). Once the hypot no longer overflowed, b·b overflowed on its own.
- Complex and non-finite inputs keep the unscaled formula.
- Measured in the Givens and Householder study, worst ‖QᵀQ − I‖ over the whole exponent range: double 1.46 ε, posit<64,2> 2.01 ε, takum<64> 3.65 ε, dd 3.79 ε. LAPACK’s
math::pow2_scaling<T>,math::givens_rotationandmath::scaled_hypot(<mtl/math/pow2_scaling.hpp>, #673).pow2_scaling<T>is a customization point withexponent(m)andscale(x, k).- The built-in floating-point types use
std::ilogbandstd::ldexp. - Any other type gets an exact halving-and-doubling fallback that forms 2^k once and multiplies by it, so a tapered type rounds once.
- A number library can specialize the trait with its own exact
ldexp, for example for Universal’s dd and qd, whose multiplication near DBL_MAX overflows to NaN (stillwater-sc/universal#1881).
- The built-in floating-point types use
qr_normalize_signs(Q, R)andlq_normalize_signs(L, Q)(#675). They make the diagonal non-negative on the explicit factors, which for a full-rank A is the unique such factorization.
- The macOS jobs move off the retiring macOS 14 image (#674). GitHub retires
macos-14on 2026-11-02 and fails jobs on it during scheduled brownouts until then (actions/runner-images#13518). The base job moves tomacos-15, and the “latest” job frommacos-15tomacos-26. mtl5-python and universal_dtypes moved too, with their wheels’MACOSX_DEPLOYMENT_TARGETpinned at 11.0, the tag of every macOS wheel they have published.
Documentation
Section titled “Documentation”- The history of Givens rotations and Householder reflectors (
docs/algorithms/givens-householder-history.md, #667), from Jacobi and Givens to LAPACK’sdlartganddlarfg. - Animated figures of the plane rotation, the reflector, QR fill-in, bulge chasing and orthogonality drift (
docs/algorithms/givens-householder-pictures.md, #668), with their generator,tools/givens_householder_svg.py. - An interactive explorer that applies a rotation or reflector in emulated number formats (
docs/site/algorithms/givens-householder-explorer.mdx, #669). Its arithmetic is tested against vectors from the Python generator. - Givens and Householder across 65 number systems (
docs/algorithms/givens-householder-study.md, #670): the results of stillwater-sc/mp-numerics#13 for the rotation and reflector forms MTL5 and LAPACK use, and the source of #671 and #672. The explorer’s reflector now rounds inqr_factor’s order (#670).
[5.21.0] - 2026-10-29
Section titled “[5.21.0] - 2026-10-29”Matrix functions arrive, generic in the element type. expm is the matrix exponential by scaling and squaring, with its Padé degree chosen from the element type’s unit roundoff (#651). schur is the real Schur decomposition, built on the Francis loop eigenvalue() already used (#655). sylvester solves A X ± X B = C by Bartels–Stewart on top of it (#657). All three run for user-defined number types such as Universal’s posits, takums, LNS and double-double, and dispatch to LAPACK for float and double. gemmt forms one triangle of a product known to be symmetric, and congruence builds A P Aᵀ and K diag(r) Kᵀ on it, the terms of a Kalman covariance update (#656, #660). The thread pool becomes public API, with a cross-library shared pool and a mutex-free spin_pool for real-time loops (#630, #639, #636), and a vendor BLAS called inside an MTL5 region now runs on one thread (#640).
Two fixes change results in the last bits: ldlt_factor’s default path (#421) and the Householder β (#658, #662). mm_read_dense now sums duplicate coordinates, as mm_read and SciPy do (#653).
-
expm, the matrix exponential, with the Padé degree chosen from the element type’s precision (#650, #651). Scaling and squaring with Padé approximants (Higham 2005), with the α_p scaling, the ℓ correction and the exact triangular entries of Al-Mohy and Higham (2009, Algorithm 6.1). The norms of A⁸ and A¹⁰ are bounded from the exact norms of A², A⁴ and A⁶, which can only increase s, instead of being estimated withnormest1.- θ_m follows the element type: tables for nine unit roundoffs, from bfloat16 to binary256, generated by
tools/expm_theta.py, which first reproduces Higham’s double values. Each θ_m is capped where the bound on κ(q_m) reaches its value at Al-Mohy and Higham’s θ₁₃ = 4.25. detail::machine_epsilonanddetail::unit_roundoff(<mtl/detail/unit_roundoff.hpp>) measure the epsilon of a type withoutnumeric_limits;default_eigen_tolerancedelegates to them.- Tested against closed forms, the identities exp(A) exp(−A) = I and exp(2A) = exp(A)², and a 60-digit mpmath reference for double, float,
long double(including binary128 on aarch64),std::complex<double>and a scalar withoutnumeric_limits.docs/algorithms/matrix-functions.mdcovers what a matrix function is, how MTL5 computes this one, and its history.
- θ_m follows the element type: tables for nine unit roundoffs, from bfloat16 to binary256, generated by
-
schur, the real Schur decomposition, andrsf2csf(#650, #655).schur(A)returns{Q, T}with A = Q T Qᵀ, Q orthogonal and T quasi-upper-triangular, its 2×2 blocks in LAPACK’s standard form.rsf2csf(Q, T)turns that into the complex triangular form, scaling each 2×2 discriminant so that entries near 1e200 or 1e−200 give no NaN.- One Francis loop: the double-shift QR iteration moves from
eigenvalue()intodetail/francis_qr.hpp. The eigenvalue-only form is the old loop, andeigenvalue()is bit-identical before and after on 864 cases (gcc and clang). The Schur form is EISPACK’s hqr2: it updates all of T, accumulates Q, and standardizes each 2×2 block with a port of LAPACK’sdlanv2.hessenberg_extract_Qforms the Hessenberg reduction’s Q. - Generic: the in-house path uses only
+ − × ÷, comparisons, andabsandsqrtfound by ADL. It deflates at the type’s own epsilon and scales A by a power of two to max |a_ij| in [1/2, 1]; without that scaling, entries near 1e200 or 1e−200 did not converge.dense2D<float/double>dispatch to LAPACKgees.
- One Francis loop: the double-shift QR iteration moves from
-
sylvesterandsylvester_triangular: A X ± X B = C (#650, #657).sylvester_triangulartakes A and B in Schur form and runs the block back substitution of Bartels–Stewart, as LAPACKtrsyldoes, solving each block of at most 2×2 unknowns with complete pivoting (dlasy2). Pivots at or belowtrsyl’s smin are replaced by it and reported in the result’sperturbedflag.sylvesterreduces general real A and B withschur, transforms C, solves and transforms back.- Real or complex, any element type; dense
float/doubleandcomplex<float/double>dispatch to?trsyl, the complex ones only for strictly triangular A and B. - Overflow is reported, not returned: both functions return the true X or throw
std::overflow_error, and reject NaN or infinite input withstd::invalid_argument.sylvester_triangular_scaledreturns{X, scale, perturbed}with A X ± X B = scale · C, astrsyldoes. - Measured relative residual, in units of each type’s ε, worst of 54 equations (
sylvester_triangular/sylvester): float and double ≤ 0.41 / ≤ 2.7, bfloat16 0.45 / 1.8, half 0.39 / 1.6, posit<32,2> 0.26 / 2.1, takum<32> 0.75 / 4.0, lns<32,22> 0.35 / 2.2, dd 0.11 / 3.2, posit<64,3> 0.31 / 2.5. Seedocs/algorithms/sylvester.md.
- Real or complex, any element type; dense
-
gemmt, the triangular-output product, andcongruence(#656, #660), requested by branes-ai/cortex for the covariance updates of its MSCKF.<mtl/operation/gemmt.hpp>.gemmt(alpha, A, B, beta, C, uplo, fill)forms one triangle of C = αAB + βC, half the multiply–adds ofmult, and mirrors it (the default) or leaves the other triangle (gemmt_fill::keep). B may be dense,trans()of one, ortrans()of acompressed2D, which walks only stored entries. α and β are converted to C’s element type and follow BLAS: with β = 0 C is not read; with α = 0 A and B are not read. With β ≠ 0 and the mirror, C must be symmetric. On the generic path the triangle is bit-identical tomult, and anAccumulatorsums each entry asmult<Acc>does.congruence(A, P, C)computes C = A P Aᵀ as T = A P withmult, thengemmt(T, Aᵀ); A may be dense orcompressed2D, and dense and CRS A give the same bits. The α/β form accumulates, andcongruence(alpha, K, r, beta, C)computes α K diag(r) Kᵀ + βC for the Joseph form’s K R Kᵀ term.- BLAS:
?gemmtis an extension, so configure links and runs a smalldgemmt_call and definesMTL5_BLAS_HAS_GEMMTonly if the answer is right. OpenBLAS 0.3.26 (Ubuntu 24.04) exports it with itslda/ldbchecks swapped and rejects valid calls, so on itgemmtkeeps the generic path. A row-major C is computed as Cᵀ = BᵀAᵀ. - Measured (i7-12700K, one pinned core, d = 200,
benchmarks/bench_congruence.cpp): genericcongruencetakes 1819 µs against 3542 µs formult(mult(A, P), trans(A))plus a symmetrize, and 0.73–0.78× the time of the best two-product form from d = 60 up. With OpenBLAS it takes 446 µs against 2545, mostly from no longer passingtrans(A), whichmultcannot hand to BLAS. With A = Φ ⊕ I as acompressed2D, it takes 60 µs. Adopters moving frommultplus(C + Cᵀ)/2see last-bit differences.
-
The thread pool is public API:
mtl::parallel::thread_pool, withpool()andconfigure()(#630). Code built on MTL5, such as synapse’s quantized matmul and attention kernels, can run its parallel work on the pool MTL5’s own kernels use, and so share one set of workers instead of oversubscribing the cores. The header is<mtl/parallel/thread_pool.hpp>, and its contract is documented there and indocs/algorithms/on-node-threading.md:- the caller runs tid 0, and
runblocks until every tid completes; - every task’s writes happen-before the caller’s next action;
- nested or concurrent regions run serially.
mtl::detail::thread_pooland<mtl/detail/thread_pool.hpp>remain as aliases, so existing callers compile unchanged.run()andparallel_for()no longer allocate, whatever the task captures. The task used to be copied into astd::function, once byrunand again by each worker. That was allocation-free only while the wrapping lambda fitted the standard library’s small buffer, which the standard does not promise. The pool now holds a pointer to the caller’s callable plus a function pointer. A test replaces globaloperator newto check this with a 256-byte capture.parallel_reduceandparallel_accumulatestill allocate their per-chunk partials, and are documented as doing so.configure(threads)sizes the pool from code. It applies only before the pool’s first use, overridesMTL5_NUM_THREADS, is clamped to the hardware concurrency in the same way, and returnsfalseonce the pool exists. Before this, an application had tosetenvbefore first use.- A per-call team cap.
parallel_for,parallel_reduceandparallel_accumulatetakemax_threadsbefore the body (0: the whole pool), so a caller can run below the pool’s size without partitioning by hand throughrun. The existing signatures and their behaviour are unchanged. - A real-time variant, with mutex-free dispatch and a spin-then-sleep wait, is
spin_pool, below (#636).
- the caller runs tid 0, and
-
One thread pool across shared libraries:
MTL5::shared_pool(#639). Header-only MTL5 gives each shared object built with-fvisibility=hiddenand each Windows DLL its own copy of the pool. Python extension modules built with nanobind or pybind11 are built that way, so two such modules in one process started two pools. Each pool was sized fromMTL5_NUM_THREADS, andconfigure()reached only one of them.- The new CMake option
MTL5_SHARED_POOL_LIBRARY(default off) builds and installsmtl5_pool, a small shared library that holds the process’s one pool. Modules that linkMTL5::shared_poolgetMTL5_SHARED_POOLdefined. Theirpool()andconfigure()then use that pool, looked up once per module, sorun()stays inline. <mtl/parallel/shared_pool_definition.hpp>provides the same definition for builds that do not use MTL5’s CMake.- The exported functions carry a layout version (
_v1), so a module built against an incompatible pool header fails to link. - A test loads two hidden-visibility modules, which are DLLs on Windows, and checks that they and the executable share one pool, its configuration and its busy state. A third module, built without the macro, shows that it keeps a pool of its own.
- The default header-only build is unchanged.
- The new CMake option
-
A vendor BLAS called inside an MTL5 parallel region runs on one thread (#640, #645). A region thread that calls MKL or BLIS used to have that library start a full team of its own, so an 8-thread region ran 64 threads on 8 cores. The BLAS and LAPACK wrappers and the CHOLMOD/SPQR calls now limit the vendor to one thread on region threads, once per region thread, and restore the caller’s setting when the region ends. Calls made outside a region keep the vendor’s threads.
- Which vendors: configure identifies the linked vendor from its exported symbols. MKL is capped with its thread-local
MKL_Set_Num_Threads_Local. BLIS is capped only where configure measures its thread setting to be per-thread (BLIS 1.0 and later; BLIS 0.9’s setting is process-wide), and the status line says which. CHOLMOD’snthreads_maxand SPQR’sSPQR_nthreadsare capped wherecholmod_commonhas them. - OpenBLAS is not capped: its only setting is process-wide, so capping it in a region would also serialize direct calls.
docs/algorithms/on-node-threading.mddescribes the two working setups, either MTL5 threaded withOPENBLAS_NUM_THREADS=1or OpenBLAS threaded with MTL5 at one thread. - Measured (i7-12700K, 64 dgemms in an 8-thread region, vendor team 8, median of 3 rounds,
benchmarks/bench_vendor_nested.cpp): BLIS 1.1 goes from 0.1 / 0.6 / 3.0 to 405 / 457 / 507 GFLOP/s at n = 128 / 256 / 512, and MKL 2026.1 goes from 328 / 338 / 381 to 499 / 468 / 513. OpenBLAS uncapped is erratic (102–407 across rounds); at one process-wide thread it holds 462 / 430 / 486. - New in
<mtl/parallel/thread_pool.hpp>:detail::in_region()anddetail::on_pool_worker(), shared across modules underMTL5::shared_pool.
- Which vendors: configure identifies the linked vendor from its exported symbols. MKL is capped with its thread-local
-
mtl::parallel::spin_pool: a pool for callers in a real-time loop (#636, #647). It hasthread_pool’s interface and contract, but nothing inrun()takes a lock, so a preempted worker never holds anything the caller needs and the pool has no priority inversion. The header is<mtl/parallel/spin_pool.hpp>.- How it hands off: dispatch is one atomic store of a word holding a 48-bit generation and the team size. A waiting worker spins (a CPU pause, and a yield every 64th iteration), then sleeps in
std::atomic::wait. The join is an atomic countdown that the caller spins on, then waits on. A thread notifies (notify_one/notify_all) only when another is actually asleep.std::atomic::waitis a futex on Linux andWaitOnAddresson Windows. - Selecting it:
-DMTL5_POOL_SPINmakesmtl::parallel::pool(), and so MTL5’s kernels, use the process-widespin_pool, as a direct call with no virtual dispatch. The environment variableMTL5_POOL_SPINsets the spin in iterations (default 4096, about 140 µs on an Alder Lake P-core;0sleeps at once). UnderMTL5::shared_poolthe spin pool is shared across modules too. - Kernels now call
parallel::pool()instead ofthread_pool::instance(); without the macro that is the same pool. The chunked loops are shareddetail::function templates, so a kernel partitions its work identically on either pool, andthread_pool’s behaviour is unchanged. - Measured (i7-12700K, P-cores pinned, T = 2–8,
benchmarks/bench_pool_latency.cpp): a back-to-back region takes 0.23–0.48 µs at the median againstthread_pool’s 3.0–6.1 µs. In a 1 kHz loop the default spin runs out within the gap, so every pool pays the kernel’s wake-up (11–16 µs median); a spin longer than the gap holds the loop at 0.7–1.1 µs median and 1.0–1.4 µs p99, at the cost of those cores spinning continuously. - What it cannot bound is written out in the header and in
docs/algorithms/on-node-threading.md: the wake-up of a sleeping worker, and a worker preempted mid-region. Pinned, reserved cores and a real-time scheduling class are the deployment’s part. - Under
MTL5_POOL_SPIN, callingthread_pool::instance()directly starts a second pool beside the kernels’ pool; go throughpool().
- How it hands off: dispatch is one atomic store of a word holding a 48-bit generation and the team size. A waiting worker spins (a CPU pause, and a yield every 64th iteration), then sleeps in
-
Arduino Ventuno Q benchmark profiles (#642, #644): a blocking A/B profile pinned to the board’s Cortex-A78C cores (found from
/proc/cpuinforather than assumed), and register-tile sweep profiles for the Ventuno Q, the Jetson Orin Nano and the Ryzen 9 8945HS.MTL5_GEMM_MR_OVERRIDE=<n>setsmralone so a sweep holds the cache blocks fixed.
Changed
Section titled “Changed”- The NEON GEMM register tile grows from 6 × nr to 8 × nr (#643, #644): 8×4 for fp64 and 8×8 for fp32 on aarch64. AVX-512 keeps 6×16. The tile derivation had assumed AVX2’s 16 vector registers on every ISA;
hw_traitsgainsacc_vectors, and aarch64 now gets 32 registers with a 16-accumulator budget.- Measured on the Ventuno Q (4× Cortex-A78C,
mrswept at fixed nr/kc/mc/nc, geomean ratio tomr = 6): fp64 8×4 is 1.174× at T=1 and 1.102× at T=4, and no shape is below 1.06. fp32 8×8 is 1.170× and 1.219×. Single-core fp64 goes from 8.3 to 9.7 GFLOP/s, 57% of peak. - Why not 3/4 of the register file: 12×4 would have regressed T=4 by up to 16%. On the 64-row shapes, each of four threads gets a 16-row block, which 8-row panels tile exactly and 12-row panels cover with 24 rows of work.
- AVX-512 is unchanged because no tile cleared a 5–40% round-to-round spread on Zen 4 under WSL2. The Jetson and other aarch64 cores also move with this change and are not yet measured.
MTL5_GEMM_TARGET_REGISTER_FILE(the rejected 3/4 candidate) and atile6arm remain measurable.
- Measured on the Ventuno Q (4× Cortex-A78C,
ldlt_factorno longer reports a zero pivot thatldlt_bk_factorandcholesky_factordon’t see (#421). Its default path formed each diagonal term as(L(j,k) * L(j,k)) * D(k): the square of an already-rounded multiplier, scaled afterwards. On an SPD float matrix whose Schur complement is under 2 ulps of the diagonal, that landed exactly onA(j,j)and returnedj + 1, whileldlt_bk_factorfactored the same matrix without an interchange. The default paths ofldlt_factorandldlt_h_factornow do what their comment always described: formv(k) = L(j,k) * D(k)(conjugated for LDLᴴ) once per column, and subtractL(·,k) * v(k). That is the associationldlt_bk_factorand the accumulator kernel already use, and it saves a multiply per inner-loop term.- Results change in the last bits for float and double input to the default path, since the products round differently. A matrix that factored before still factors, except possibly one sitting on a pivot that is zero to rounding either way. The accumulator paths (
ldlt_factor<Acc>) are unchanged, and the default path’sDnow matchesldlt_factor<T>’s bit for bit (Lstill sums before subtracting, as before). - The issue’s own caveat stands: this changes a one-rounding coin flip on pivots within a couple of ulps of zero. Further into ill-conditioning, no association helps.
- Results change in the last bits for float and double input to the default path, since the products round differently. A matrix that factored before still factors, except possibly one sitting on a pivot that is zero to rounding either way. The accumulator paths (
- GEMM with an empty dimension passed a leading dimension of 0 to BLAS (#645). BLIS rejects that (“parameter number 10 had an illegal value”) and leaves C untouched, so
multwith k = 0 did not zero C under BLIS. Every leading dimension is now at least 1. analyze_blocking_ab.pycalled a null run a match (#642). On a board whose kernel lists cache levels without sizes, every detecting arm fell back to the compile-time model, and the analyzer reported “its caches already match the compile-time model”. It now says that detection found nothing.- Highway’s CMP0111 deprecation warning no longer prints on every configure with
MTL5_WITH_HIGHWAY=ON(#642). mm_read_densesums duplicate coordinates (#653). It assigned each coordinate entry, so a file with two entries for the same (row, col) kept only the last: 2 then 3 read as 3, wheremm_readand SciPy give 5. Symmetric files did the same at both mirrored positions. Reported by a user through the mtl5 5.19.2 Python package, which calls this reader.- The Householder β no longer squares v₀ (#658). The real path formed β = 2v₀² / (σ + v₀²). For a tail small against x(0), v₀² underflows or loses its bits in a type with little range below 1: the Hessenberg reduction of a half-precision matrix with a 2% tail had a backward error of 101 n ε (posit<16,1>: 389 n ε). σ + v₀² is exactly −2‖x‖v₀, so β = −v₀/‖x‖, as
dlarfg’s τ; a tail below half an ulp of x(0) returns the identity explicitly. Found by thesylvesteraccuracy table, whose half and posit<16,1> outliers went from 57 and 215 ε to 1.6 and 4.7 ε. float and double change in the last bits of β.- A reflector the type cannot hold is the identity (#662). The new β no longer underflowed to zero where the old one had, and in 8-bit floats and fixed point that exposed reflectors the type cannot represent: on mtl5-python’s 8×8 QR fixture, fp8 gave NaN and fixpnt<16,8> an orthogonality error of 7.8.
householder()now evaluates β vᵀv, which is 2 for an exact reflector, and keeps the reflector only when its distance from orthogonal is at most ‖tail‖/‖x‖, the cost of leaving the column alone. Those types are back to 5.20.0’s finite, degenerate results (Q = I), and half and posit<16,1> keep the gain: QR residual 0.00998 → 0.00212 and 0.00918 → 0.00406. posit<64,3>, whosesqrtis accurate only to double (stillwater-sc/universal#1846), goes from 29 to 2.5 ε in thesylvestertable. Found by building mtl5-python against the release candidate.
- A reflector the type cannot hold is the identity (#662). The new β no longer underflowed to zero where the old one had, and in 8-bit floats and fixed point that exposed reflectors the type cannot represent: on mtl5-python’s 8×8 QR fixture, fp8 gave NaN and fixpnt<16,8> an orthogonality error of 7.8.
Documentation
Section titled “Documentation”- One thread pool per process or one per component (
docs/design/concurrency-runtime-ownership.md, #638): the design question behindMTL5::shared_pool, weighed before #639 was built. - Quaternions, Lie algebras and matrix functions, assessed for MTL5 (
docs/other/quaternions-lie-algebras-matrix-functions.md, #649): neither a quaternion type nor Lie-group classes belong in MTL5, but the matrix functions those layers need do, with Padé degrees chosen from the scalar’s precision. That assessment is the plan #650 tracks. docs/algorithms/matrix-functions.md(#651), theschursection ofdocs/algorithms/eigenvalues.md(#655),docs/algorithms/sylvester.mdwith the accuracy table remeasured after #658 (#657, #659), anddocs/algorithms/gemmt.md(#660).- The origins of gemmt (
docs/algorithms/gemmt-origins.md, #661): the Joseph-stabilized covariance update (Bucy and Joseph, 1968), why classical Level-3 BLAS has no routine for its terms, and how the GEMMT extension arrived across MKL, BLIS, OpenBLAS and reference BLAS.
[5.20.0] - 2026-10-22
Section titled “[5.20.0] - 2026-10-22”Block-quantized data becomes a first-class operand. mat::block_matrix_view is a read-only Matrix over the encoded bytes of a block-quantized format, parameterized by the new BlockScheme concept, with the OCP MXINT8 and MXFP4 schemes in-tree (#629). A scheme can plug in a fused gemv whose working memory the caller supplies. simd::reduce_dot_block_scaled is the inner-product kernel such formats need: each block’s exact integer sum is scaled in-register, with one horizontal reduce per call (#628). The threaded GEMM now chooses its ic step by micro-panels, 3–16% faster on the configurations it changes, measured on three machines, and slower on none (#458).
Everything new is additive. The GEMM change alters only how rows are split into blocks, not the order of any sum.
-
mat::block_matrix_view: a read-onlyMatrixover block-quantized storage (#629), parameterized by the newBlockSchemeconcept: block geometry (block_size,block_bytes) plus a referencedecodeof one block’s raw bytes, and optionallydecode_element. The view is non-owning (typically over a memory map), row-major with blocks along rows, and read-only, and its constructor checks the shape. Elements read as decodedfloat;block(r, b)androw(r)expose the encoded bytes.- Operations:
convertto a dense matrix andmult(A, x, y)/A * xdecode a row at a time, threaded over rows and independent of the thread count. A scheme can plug in a fused gemv by specializingmtl::block_kernels<S>, whichmultuses for contiguousfloatvectors with no explicitAccumulator. The kernel’s working memory (typically the quantizedx) is the caller’s:mult(A, x, y, scratch)passes it through, sized and aligned byblock_gemv_scratch_bytes<S>andblock_gemv_scratch_alignment<S>, andmult(A, x, y)allocates it for the call. - In-tree OCP MX schemes, Universal-free:
mx::mxint8(E8M0 scale plus 32 × INT8, q/64) andmx::mxfp4(E8M0 plus 32 × FP4 E2M1, in GGML’sblock_mxfp4nibble order, so gpt-oss GGUF data can be viewed in place). A scale of 0xFF is NaN. Under the largest scale, elements of magnitude 2 or more decode to infinity, since they exceed float’s range. - Design notes:
docs/architecture/containers/block-matrix-view-architecture.md. The encode direction (quantizing activations into a block format) is a follow-up.
- Operations:
-
simd::reduce_dot_block_scaled: block-scaled integer dot products (#628). ComputesΣ_b scales[b] · Σ_{j∈b} a_j·x_jover consecutive blocks, the inner product of block-quantized formats (GGML Q4_0/Q8_0/Q4_K/Q6_K, OCP MXINT8, 16-wide NVIDIA-style blocks), with the caller supplying decoded float scales. Each block’s exact integer sum stays in vector lanes and is converted and scaled in-register, with one horizontal reduce per call instead of one per block. It takesreduce_dot_widen’s operand pairs, and blocks of any length; the part that isn’t a multiple of the SIMD step is summed as a scalar.- Contract: each block’s integer total is exact. Lane partial sums are converted and accumulated in float in an order fixed by block index, so the result is reproducible run to run on one target and equals the per-block loop up to float re-association across targets. Overflow is a per-block precondition (
Σ |a_j·x_j| < 2³¹, or 2³² for the unsigned pairs), not “the sum wraps”. - New primitive:
batch<float>::convertfromint32_tanduint32_tlanes, rounding asstatic_castdoes.widen_dot_accumulateandquad_dot_accumulateare now documented as public building blocks for this pattern. - Measured (i7-12700K, AVX2, single thread,
benchmarks/bench_block_scaled_dot.cpp): at block 32 it is 1.3–1.4× faster than onereduce_dot_widenper block in cache, and 1.15–1.4× faster at 4096×4096; at block 256 the two match. The numbers and their limits are indocs/algorithms/mixed-precision-kernels.md.
- Contract: each block’s integer total is exact. Lane partial sums are converted and accumulated in float in an order fixed by block index, so the result is reproducible run to run on one target and equals the per-block loop up to float re-association across targets. Overflow is a per-block precondition (
-
#458before/after profilesbenchmarks/machines/{xeon-e5-2420,i7-12700k,ryzen-9-8945hs}-mc.shand alegacymcbenchmark arm, with the three machines’ data underbenchmarks/data/*-mc458.
Changed
Section titled “Changed”- The threaded GEMM chooses its ic step by micro-panels (#458, #626). The serial path rounded
mcdown to wholemr-row panels; the threaded path rounded the ic block count up to a multiple of the thread count and kept whatevermccame out, so every block carried a padded partial panel. The Xeon’s shipped threadedmc = 32againstmr = 6ran 5.33 panels padded to 6. This is what made #458’s multi-threadedmccurve W-shaped. The busiest thread’s panel count fits that curve at r = +0.83; the block-count balancebalanced_mcoptimised fits at +0.23.- Rule: in the threaded path,
balanced_mckeeps the block-count result unless a block size in[ceil(mc_max/2), mc_max]gives the busiest thread strictly fewer panels (newdetail::critical_panels, closed form). Ties keep the old plan; the window stops it shrinking blocks into extra passes over packed B. The serial path, the #488 sub-tile fallback andmr = 1callers are unchanged.MTL5_GEMM_LEGACY_BALANCED_MCrestores the old rule for diagnosis. - Measured (pinned, 4 interleaved rounds against the old rule built from the same tree): Xeon E5-2420 v2 all 16 changed plans faster by 7.5–16.2%, 2048³ T=6 45.3 → 52.6 GF/s; i7-12700K 12 of 13 faster by 3.1–9.2%; Ryzen 9 8945HS (Zen 4, WSL2) all 5 faster by 3.4–6.4%. None slower on any machine; T=1 unchanged everywhere. See
docs/performance/mc-critical-panels.md.
- Rule: in the threaded path,
run_blocking_ab.shcalleddefaultandlegacymca consistency pair (#626). It compared configured kc/mc only; it now also keys on every row’smc_used. It also refuses an arm CSV with no complete data record, which previously compared equal to another empty one.
[5.19.0] - 2026-10-20
Section titled “[5.19.0] - 2026-10-20”The accumulator policy now reaches every reduction-bearing routine in the library (#585): the dense direct factorizations, Bunch–Kaufman, the four incomplete-factorization preconditioners, spgemm, svd, sum and trace, the sparse eigensolvers, and the multigrid transfers and cycle. Accumulator-typed dot and norms run on the thread pool through merge, and the accumulator GEMM is up to 23× faster. Three new accumulation tools join plain and FMA:
math::exact_accumulator<T>, an in-library Kulisch accumulator forfloatanddouble;- Ogita, Rump and Oishi’s compensated Sum2/Dot2 as
compensated_accumulator<T>(configuration 2c); - their K-fold
sum_k/dot_k, built on new error-free transformations.
The configuration 1/2/2c/3 accumulation matrix (#586) is measured, tested and published. Two preconditioner bugs are fixed, and matrix-free operators work in the Krylov solvers again.
Every new Accumulator parameter defaults to void, which runs exactly the code 5.18.0 ran. Three behaviour changes affect only callers who pass an accumulator explicitly; see Changed.
-
Accumulator policy for the dense direct factorizations (#594, #595, #585).
lu_factor,lu_solve,lu_adjoint_solve,lu_apply,inv,cholesky_factor/_solve,cholesky_h_factor/_solve,ldlt_factor/_solve,ldlt_h_factor/_solve,ldlt_bk_factorandldlt_bk_solvetake a leadingAccumulator = void. A non-void accumulator skips LAPACK (interface::accumulator_allows_blas_v).- LU and Bunch–Kaufman change loop order for it. Their
voidfactorizations are right-looking, where an entry is updated once per step and there is no single sum to hold. The accumulator paths are left-looking: Doolittle for LU, and a Bunch–Kaufman that forms each Schur column on demand from W = L·D. Each entry of the factor is one reduction, rounded once. Pivoting, storage and theipivencoding are the same as thevoidpath’s, so either solve reads either factor. The tests mix the factor of one path with the solve of the other. - Solves form
b(i) − Σinside the accumulator and round once before the division. Rounding the sum first, aslower_trisolvedoes, gave away the whole gain: every configuration landed near 1e-8. - Effect (float Hilbert(n), exact relative residuals; plain / fma / exact): LU n = 8 gives 2.8e-8 / 1.3e-8 / 2.9e-9, and
invn = 8 gives 1.7e-1 / 6.9e-1 / 3.8e-3. Cholesky of Hilbert(9) factors only with the exact accumulator. - Cost: the accumulator paths of LU and Bunch–Kaufman store an n × n workspace; see
docs/architecture/accuracy-architecture.md§2.
- LU and Bunch–Kaufman change loop order for it. Their
-
Accumulator policy for the incomplete-factorization preconditioners (#597, #598, #600, #603).
pc::ilu_0,pc::ic_0,pc::ilutandpc::ildltake a trailingAccumulator = void, the class-template conventionpc::ssorset.- Factorizations: ILU(0) and ILUT keep one accumulator per live entry of the row being eliminated. IC(0) and ILDL are already up-looking, so each entry is one reduction.
- Solves: they form
b − Σin the accumulator. The adjoint and Lᵀ solves scatter into n accumulators, which is O(nnz), where thevoidpath scans later rows. - ILUT drop tests read the single-rounded values, so with dropping, a different accumulator can keep a different pattern.
- Finding: the length of the reductions decides whether an exact accumulator helps. On stencil patterns all configurations agree. On a dense pattern, where IC(0) and ILU(0) are Cholesky and LU, exact is 2–4× better at least. At Hilbert(9), IC(0) breaks down to NaN under plain and FMA but not under exact.
-
Accumulator policy for
spgemm(#604). A leadingAccumulator = void, with one accumulator per touched column of the current row, mapped through a slot table so that at most nnz(C row i) are live. The pattern is unchanged.- With the exact accumulator every entry is correctly rounded. On a 40×60 · 60×40 cancelling product, plain misses at 584 of 1589 entries, FMA at 446 and exact at none.
- A plain element-type accumulator gives the
voidbits, except that an entry whose only nonzero contribution is a −0 product comes back +0.
-
Accumulator policy for
svdandnull_vector(#606). Every overload takes a leadingAccumulator = void. It covers:- the one-sided Jacobi inner products, raw and scaled;
- the Gram–Schmidt completion of U;
- the Householder QR preconditioner and U’s reflector back-application.
The plane rotations stay in
value_type, and a non-void accumulator skipsgesddandgeqrf. The finding is no ordering: Jacobi’s error comes from applying the rotations, not from the inner products that choose them. -
Accumulator policy for
sumandtrace(#607). Each element goes throughadd_product(acc, x, 1), which is exact for every number system, so the protocol needs noaddprimitive. For a plain sum, configurations 1 and 2 are therefore bit-identical. The exact accumulator returns the correctly rounded sum. -
Accumulator policy for the sparse eigensolvers (#605).
sparse_eigsandsparse_eigs_shift_inverttake a leadingAccumulator, andshift_invert_operatortakes a trailing one. It reaches:- the LU factorization of A − σI and every solve that applies it;
- Arnoldi’s inner products;
- for
sparse_eigs, the matvec throughmult<Accumulator>.
-
Accumulator policy for multigrid (#608).
restrictandprolongatetake a leadingAccumulator, andmultigrid<Value, Accumulator>passes it to both transfers in the V- and W-cycles and to the cycle residualr = b − A·x, formed in theb − Σshape. Smoothers remain the caller’s choice (smoother::*<Matrix, Accumulator>). This completes #585. -
Accumulator-typed reductions run on the thread pool (#584).
dot,dot_real,two_normandfrobenius_normwith an explicitAccumulatorsplit acrossthread_poolwhenmergeable_accumulator<Acc, Value>holds, combining partials withaccumulator_traits::merge(5.18.0) in chunk order.- Determinism: an exact accumulator gives the serial bits at every thread count. For a posit⟨32,2⟩ quire over 2²⁰ elements it went from 830 ms on one thread to 125 ms on eight, with identical bits.
- Accumulators without a
merge, and non-dense operands, stay serial. The newdetail::parallel_accumulateanddetail::accumulatecarry it.
-
math::exact_accumulator<T>(#612, #611), ininclude/mtl/math/exact_accumulator.hpp. The test-only Kulisch accumulator of #589 moves into the library: an exact sum of products offloatordouble, rounded once to nearest-even, with subnormals and overflow handled. Each object is 88 bytes for float and 544 for double: 10 or 67 64-bit limbs plus a non-finite flag.- Non-finite inputs follow IEEE, kept apart from the finite sum.
- Operand types:
Vmust be exactly representable inT.long doubleis excluded. - Integration: it plugs in through the ADL hook, so every accumulator-aware operation takes it, and its
mergeis exact. - Docs:
docs/architecture/exact-accumulator.md.
-
Error-free transformations (#614), in
include/mtl/math/error_free.hpp:two_sum,fast_two_sum, Veltkampsplit,two_product_dekker(exact up tomaxby rescaling) andtwo_product(FMA, moved fromaccumulator_traits.hpp, which includes the new header;split_productis kept as an alias). Each returnsexact_pair<T>{hi, lo}.splitandtwo_product_dekkerswitch FP contraction off locally, since GCC’s-ffp-contract=fastotherwise turnssplitinto(a, 0)on any FMA target. Their test is built with-ffp-contract=fastso the ARM64 runners exercise the guard.-ffast-mathis unsupported. Seedocs/architecture/error-free-transformations.md.
-
math::compensated_accumulator<T>, configuration 2c (#615). This is Ogita–Rump–Oishi Sum2/Dot2 as an accumulator, holding twoTs. The result is as accurate as twice the working precision, rounded once.mtl::dotwith it gives the bits of the paper’s Dot2 loop.- Merge stays within the bound but is not bit-identical across thread counts.
- Accuracy: on GenDot in double it stays at exact’s level up to cond ≈ 1e16 and then grows as u²·cond.
-
sum_k<K>(x)anddot_k<K>(x, y)(#616), ininclude/mtl/operation/sum_dot_k.hpp: Ogita–Rump–Oishi SumK and DotK. Each returns the sum or dot product as if computed in K-fold precision, then rounded once.sum_k<2>anddot_k<2>give the same bits ascompensated_accumulator. They take whole vectors, since they keep n or 2n error terms. -
Exact three-factor terms in the LDLᵀ accumulator paths (#609, #610, #602).
add_producttakes two factors, so theL·dof eachL(i,k)·d_k·L(j,k)was rounded before the accumulator saw it. A new trait,math::splits_product_terms_v<Acc, Value>, marks when that rounding error is worth recovering. When it holds, the kernels also passtwo_product’slo, so the whole term reaches the accumulator. Over 300 perturbed Hilbert matrices this adds 1.1–1.6×, and dense LDLᵀ, sparse LDLᵀ and ILDL now order exact below plain and FMA.- Paths changed: dense
ldlt_factor/ldlt_h_factor,ildl,sparse_ldlt_numericandsupernodal_ldlt_numeric. Bunch–Kaufman feeds stored Schur columns and is unaffected. - Trait coverage: it holds for an IEEE
Valuewith an ADL accumulator, the compensated accumulator, or a strictly wider built-in float. - Perf: #610 forms the supernodal split coefficients once per update column, with identical bits.
- Paths changed: dense
-
generators::gen_dotandgen_sum(#617), ininclude/mtl/generators/ill_conditioned.hpp: the Ogita–Rump–Oishi Algorithm 6.1 GenDot and its derived ill-conditioned sums.exact_accumulatorserves as the paper’sDotExact. Each returns the exact result rounded to nearest and the achieved condition number. A seed reproduces the same vectors with any standard library. Seedocs/generators/ill-conditioned.md. -
examples/accurate_sum_dot(#619, #620) reproduces Section 6 of Ogita, Rump and Oishi:- Figures 6.1–6.4, with an added float run;
- Table 6.2, correct digits;
- Tables 6.4–6.5, timings.
Errors are measured exactly, and no proven bound is violated on 3000 dot products under GCC or Clang.
docs/examples/accurate-sum-dot.mdplots the results beside the paper’s. -
Tests for the accumulation matrix (#589, #590, #622). The configuration 1/2/2c/3 matrix covers dot, gemm, norms, the direct solvers, refinement, Krylov, eigen, the preconditioners,
spgemm,sumandsvd, plus determinism. The rows are tagged[586:*]so the peer repos’ quire rows can name them.- Theorem tests:
test_ogita_rump_oishiasserts the paper’s numbered bounds as inequalities on every GenDot/GenSum instance (#618). - Portability: #622 fixed undefined seed conversions and unspecified argument evaluation order, so GCC, Clang and MSVC now draw the same random inputs.
- Theorem tests:
Changed
Section titled “Changed”- A non-void
Accumulatornow reaches the eigensolvers’ matrix-vector product (#593, #591).power_iteration,lanczosandarnolditake a leadingAccumulator. WhenAis aMatrix,ev_matvecnow formswwithmult<Accumulator>, as the Krylov solvers do; before, the accumulator covered only the dot products.- Results change for callers who pass one. On a float matrix whose matvec cancels by four orders of magnitude,
power_iterationwith the exact accumulator now converges, to 8.0e-6, where all configurations previously stalled at 5.4e-3. voidand matrix-free operators keepA * x, byte-identical.
- Results change for callers who pass one. On a float matrix whose matvec cancels by four orders of magnitude,
- Threaded accumulator reductions regroup by chunk (#584). With
MTL5_NUM_THREADS> 1, a rounding accumulator such as a wider type orfma_accumulatorindot,dot_real,two_normorfrobenius_normnow gives bits that depend on the thread count. This is the contract the threadedfloat/doublereductions already have. With one thread, the default, nothing changes; exact accumulators are unaffected. - LDLᵀ results with exact, compensated or wider accumulators change (#609): they now see whole three-factor terms.
void, plain,fma_accumulator, complex, non-IEEE types, and accumulators with a directaccumulator_traitsspecialization give the 5.18.0 bits. - The accumulator GEMM is 5–23× faster (#588).
mult<Acc>(A, B, C)packs B into k-major column panels and keeps one accumulator per column, so the k loop is unit-stride. At n = 1024: 23× fordouble/plain, 4.6× forfma_accumulatorand 8–15× forfloatinto adoubleaccumulator.- Bits: each entry gets the same terms in the same order, so results are bit-identical under
-ffp-contract=off. Under FMA contraction the new kernel may fuse where the old one didn’t on GCC. - Gate: software element types such as posits, and large accumulators such as quires, keep the dot-product loop.
- Bits: each entry gets the same terms in the same order, so results are bit-identical under
itl::idr_saccepts any linear operator (#624): itsMatrix LinearOpconstraint is nowtypename, like the other Krylov solvers.
- Matrix-free operators compile in the Krylov solvers again (#624, #278). The accumulator rollout (#254) moved every matvec to
mult<Accumulator>, which requires aMatrix, so an operator with onlyoperator*stopped compiling in all ten solvers.- Fix: the new
itl::apply_operatorandapply_transpose(initl/krylov/apply_operator.hpp) send aMatrixthroughmult<Accumulator>exactly as before, and apply anything else asA * x.bicgandqmruse a matrix-freetrans(A)found by ADL. - Accumulator contract: a non-void accumulator reaches only the dot products around a matrix-free operator, the contract
ev_matvechas. - Tests: all ten solvers run on a matrix-free operator and are bit-identical to the stored-matrix solve. A lazy-product case runs
apply_transposepast a temporarytrans(A); it fails under AddressSanitizer without the lifetime fix.
- Fix: the new
pc::ilutback substitution counted the diagonal twice (#599). This is the #323 bugilu_0once had. The diagonal was stored in the U rows and divided by again, which is wrong for every input: a no-drop ILUT, which is an exact LU, gave(Ax)(0) = −3forb(0) = 1. The diagonal now lives only inu_diag_.pc::ilut::adjoint_solveapplied M⁻¹ instead of M⁻ᴴ (#599), the #394 defect. ILUT of a symmetric A is not symmetric, so even there the adjoint identity failed, by 1.6e-3. It now has a real scatter-form adjoint.pc::ic_0andpc::ildladjoint_solveapplied M⁻¹ for complex values (#601). Both factor L·Lᵀ (L·D·Lᵀ) without conjugation, so a complexValuemodels a complex symmetric matrix, whose adjoint is conj(M), not M. The adjoint identity was off by up to 1.2.solveandadjoint_solvenow shareapply<Conj>, and real types are byte-identical.- The multigrid transfers started their sums from
Value{}(#608), which is 1, not 0, for an LNS type. They start frommath::zero<Value>(), byte-identical for built-in types.
- Tier 2 runs from its own workflow,
regression.yml(#613), so promoting a draft no longer re-runs Tier 1 on an already-tested commit. That saves about 128 runner-minutes per promotion. Tier 2 no longer waits for Tier 1.
Documentation
Section titled “Documentation”docs/algorithms/accumulation-configurations.md(#621, #623, #592) publishes the #586 matrix. It covers what plain, FMA, compensated and exact accumulation each buy, routine by routine, with the tag that reproduces each number.- It includes the configuration-3 quire rows from mp-blas, mp-iterative and mp-ir, whose IEEE quires equal the exact accumulator bit for bit, and the posit⟨32,2⟩ CG result.
- It ends with a “which accumulator when” table.
docs/architecture/accuracy-architecture.md(#621, #596) explains why the results come out as they do:- the accumulator protocol and what an exact accumulator needs from an algorithm;
- left- against right-looking loops, with a measured cost table from the new
bench_accumulator_factor; - per-algorithm coverage tables;
- parallel and distributed reductions;
- guidance.
- New pages:
docs/architecture/exact-accumulator.md,docs/architecture/error-free-transformations.md,docs/generators/ill-conditioned.md,docs/examples/accurate-sum-dot.md. docs/algorithms/on-node-threading.mdis reconciled with the threaded kernels.docs/design/iterative-solvers-architecture.mddocuments the matrix-free operator contract (#624).
[5.18.0] - 2026-10-16
Section titled “[5.18.0] - 2026-10-16”A Universal quire is now an accumulator for any MTL5 operation that takes one, with no bridge header in between. accumulator_traits forwards to free functions defined next to the accumulator type, which Universal 5.7.0 provides for its quire. The trait also gains merge, the combine step a parallel reduction needs. Nothing changes for existing accumulators: plain and fma_accumulator behave as before, and an explicit accumulator_traits specialization still takes precedence. Two design documents compare MTL5 with Elemental.
- Super-accumulators plug into
accumulator_traitsthrough free functions found by argument-dependent lookup (#581, #582). When an accumulator’s own namespace providesaccumulator_clear,accumulator_assign,accumulator_add_productandaccumulator_value(acc, std::type_identity<R>{}), theadl_accumulatorconcept is satisfied and a constrained specialization forwards each operation to them.accumulator_mergeis optional.- Why: the Universal quire’s specialization was a header,
quire_accumulator.hpp, copied byte for byte into mp-blas, mp-ir, mp-iterative and mp-numerics, with diverged copies in mp-spice and mtl5-python. It specialized MTL5’s trait, so it had to include MTL5 and couldn’t live in Universal. Now Universal defines the functions besidequire(universal#1699, in 5.7.0) without including MTL5, and MTL5 only names them, so it stays Universal-free.dot<quire<P>, P>(x, y)andsparse_lu_solve<quire<P>>(A, x, b)work with Universal 5.7.0 and nothing else. The mp-* repos have deleted their copies; mtl5-python can once it pins this release. - Precedence: a specialization that names the accumulator type is more specialized than the constrained one, so an existing bridge keeps compiling and keeps being used until it is deleted.
- Naming:
accumulator_valuetakes astd::type_identity<R>tag rather than an explicit template argument, so the call is an ordinary ADL call on every compiler. The hook functions should be constrained on the accumulator type, since ADL also searches the namespaces associated withValue.
- Why: the Universal quire’s specialization was a header,
accumulator_traits::merge(a, b)combines two partial accumulators of the same reduction: an ordinary add for plain accumulators andfma_accumulator, andaccumulator_mergefor an ADL accumulator, which has nomerge()if it doesn’t provide one. For an exact accumulator the combination is exact, so a reduction split across threads or processes gives the same bits however it was split. No kernel uses it yet; letting one accumulator-typed reduction run onthread_poolis tracked in #582.- Tests:
test_accumulator_adl_hookuses a mock exact accumulator in its own namespace. It checks concept satisfaction (configurations 1 and 2 don’t satisfy it), forwarding, a 1 − 10⁸ + 10⁸ cancellation that the accumulator keeps exact,mergefor all three configurations, that a specialization beats the hook,dot<Acc, Result>, and all six one-shot sparse direct solvers factoring and solving through the hook.
Documentation
Section titled “Documentation”docs/other/elemental-architecture.md(#578) surveys Elemental: theDistMatrixdistribution algebra, its MPI layer, the closed set of precisions it instantiates, and its maintenance status.docs/other/mtl5-elemental-assessment.md(#580) compares MTL5 with Elemental and proposes a layering. Its recommendation is not to port Elemental. The single-node dense algorithms it has and MTL5 lacks, such as column-pivoted QR, pivoted Cholesky and polar decomposition, belong in MTL5. A distributed layer would be a separate repository depending on MTL5 alone, and is worth building only for reductions that are exact and independent of the process count. Its prerequisites were the ADL hook andmergeabove.
[5.17.0] - 2026-10-15
Section titled “[5.17.0] - 2026-10-15”A thin SVD and a faster Jacobi core behind every svd, and the accumulator policy carried from the sparse direct factorizations into their solves, so a factorization with a wider or exact accumulator no longer ends in a plain rounded triangular solve. One behavior change: the generic svd, the V-only svd and null_vector return different last bits (see Changed); the LAPACK gesdd path is unaffected. The new Accumulator parameter on the sparse solves defaults to void, which returns exactly the bits 5.16.0 did.
-
Thin SVD:
svd(A, U, s, V), with U m × k, s of length k and V n × k, where k = min(m, n). This is the thin U left out of #566. The fullsvd(A, U, S, V)completes U to an m × m basis, which is almost all of its 0.24 s at 400 × 9.-
How: for a tall A, the generic path reuses the V-only
svd’s QR preconditioning. It runs one-sided Jacobi on R and forms U = Q [U_R; 0] by applying the n stored Householder reflectors, in O(mn²). For m ≤ n, U, s and V’s columns match the first k of the fullsvdbit for bit. With LAPACK,dense2D<float/double>goes togesddin its thin mode,'S', as the fullsvduses'A'. -
Speed: in µs, thin against full
svd: 13 against 459 at 64 × 9, 49 against 238,000 at 400 × 9, and 85 against 238,000 at 400 × 12. Thenull-vectorbenchmark suite gains asvd_thinarm, whose answer is checked like the others. -
Refactor: U’s basis completion moved into
detail::complete_orthonormal, shared by both overloads. The fullsvd’s arithmetic is unchanged. -
Tests:
test_svd_thinchecks:- bit identity with the full
svdfor m ≤ n; - agreement to rounding in
long doubleon tall shapes up to 400 × 12, including columns graded across 10⁸, with U and V orthonormal, A reconstructed, and the sign of each (uᵢ, vᵢ) pair consistent; doubleagainst the fullsvdin either build;- rank-deficient, zero and empty inputs.
Skipping the reflectors, applying them in the wrong order, or skipping the completion each fails it.
- bit identity with the full
-
-
The accumulator policy reaches the solve phase of every sparse direct solver (#535, #576, #261 Part C). Since 5.13.0 the numeric factorizations have taken an
Accumulator(#530, #531, #534, #542), but theirsolve()methods summed in plainValue, so a factorization done with a wider or exact accumulator still ended in an ordinary rounded triangular solve.-
Kernels: the five level-scheduled triangular solves in
sparse/factorization/level_schedule.hpptake a leadingAccumulator = void, the convention #542 set:level_scheduled_lower_solve<Acc>(L, s, x). Withvoidthey run the original loop. With an accumulator, each row’s whole b[i] − Σ T(i,k)·x[k], b[i] included, goes throughaccumulator_traits(assign, thenadd_productof the negated terms) and is rounded once before the division by the diagonal. An exact accumulator therefore delivers b − Σ with a single rounding. Each row keeps its own accumulator, so the parallel levels stay race-free and no workspace is added. -
Solvers:
solve<Acc>()is added tocholesky_numeric,ldlt_numeric,lu_numeric,supernodal_lu_factorandsupernodal_ldlt_factor.qr_numeric::solve<Acc>covers its two inline sums, the vₖᵀw dot of Q_hᵀb and the R back-substitution; the latter keeps one accumulator per column, O(ncols), and adds terms in the same order as the default. The one-shotsparse_{cholesky,ldlt,lu,qr}_solve<Acc>andsupernodal_{ldlt,lu}_solve<Acc>passAccto both the factorization and the solve. With the defaultvoid, every call returns exactly the bits it did before. -
Not covered: the scatter kernels in
triangular_solve.hpp, which no solve path calls and which remain the raw reference;klu_numeric::solve’s block coupling; and the*_solve_refinedwrappers, which use the default solve. -
Note: the LU solve uses
mtl::math::accumulator_traits, as Cholesky, LDLᵀ and QR do. A specialization of only thesparse::factorization::accumulator_traitsalias is not picked up bylu_numeric::solve<Acc>. -
Tests:
test_solve_accumulator_policychecks:voidandAcc == Valueagainst thedense_*references, bit for bit;- a
floatrow where 1 − 10⁸ + 10⁸ cancels to 0, which gives 1 with adoubleorfma_accumulator<double>accumulator, in all five kernels and both QR sums; solve<Acc>against the default on every factorization and every one-shot wrapper.
The bit-identity claim depends on the compiler not contracting
x -= a*binto an FMA differently in the gather and the scatter, so the target is built with-ffp-contract=off, astrisolve_level_schedule_mtis (#381). The FP-contract lane found this on the first push.
-
Changed
Section titled “Changed”- The one-sided Jacobi core behind
svdis 1.3–3.6× faster, and its results change in the last bits. It is shared by the genericsvd(A, U, S, V), the V-onlysvd(A, s, V)andnull_vector. The LAPACKgesddpath is unaffected. Each column pair’s inner products ‖b_p‖², ‖b_q‖² and b_p·b_q were formed from entries divided by the pair’s largest magnitude, which costs a max pass and 2m divisions per pair, to keep the squares from overflowing or underflowing. They are now summed raw, and kept when ‖b_p‖² and ‖b_q‖² both lie in [√min/ε, √max/2] (about 2^-459 to 2^511 indouble). Outside that window, which includes any inf or NaN, the sums are re-formed scaled as before. The window also keeps ‖b_p‖²·‖b_q‖² finite and normal, since the convergence test takes its square root. The sweeps also run on column-major copies of B and V, which on its own was about 10% faster with identical bits. A type without astd::numeric_limitsspecialization always takes the scaled path.-
Speed: median µs from
bench_all --suite null-vector, old core against new, run alternately.m × N null_vectorfull svd16 × 9 24 → 6.6 46 → 13 64 × 9 33 → 9.7 1,025 → 448 400 × 9 33 → 27 238,000 (unchanged) 16 × 12 27 → 13 38 → 18 64 × 12 31 → 16 521 → 452 400 × 12 62 → 46 239,000 (unchanged) At m = 400, QR dominates
null_vectorand the completion of U to m × m dominates the fullsvd. -
Accuracy: on the same inputs the singular values agree with the old core to 1e-15 relative, the sweep counts are the same, and
null_vector’sfloataccuracy table indocs/algorithms/eigenvalues.mdis unchanged within noise. -
Tests: a new case in
test_svdscales a uniform matrix, and one with columns spread from 2^-560 to 2^-80, by 2^k for k from -560 to 520, across both bounds of the window. The singular values must scale by exactly 2^k and V must not move. Removing the lower bound, the upper bound or the scaled fallback each fails it; the upper bound is checked by this test alone.
-
svdthrows when LAPACK’sgesddfails, instead of returning whatever its buffers held. The LAPACK path of the fullsvd(A, U, S, V)ignoredgesdd’sinfo, so a NaN in A, which LAPACK 3.10+ rejects withinfo = -4, or a divide-and-conquer that did not converge came back as an apparently valid U, S and V. The full and the new thinsvdnow checkinfoafter the workspace query and after the decomposition, and throwstd::runtime_erroron a nonzero value, aseigenvaluedoes forgeev. The generic path is unchanged. A LAPACK-only case intest_svd_thinpasses a NaN to both and requires the throw; it fails against the previous header. Found by CodeRabbit on #575.
[5.16.0] - 2026-10-12
Section titled “[5.16.0] - 2026-10-12”Small dense eigen and singular value problems, driven by null-space solves (8-point, DLT, plane fits): a Jacobi eigensolver that keeps small eigenvalues relatively accurate, a V-only SVD with QR preconditioning and null_vector, a tighter default tolerance and deflation test for eigen_symmetric, and the Householder accumulator forwarded through QR, LQ and the eigensolvers. One behavior change: eigen_symmetric and its relatives return different bits by default (see Changed). The full svd is bit-identical to 5.15.0.
-
The Householder accumulator reaches QR, LQ, the Hessenberg reduction and the dense eigensolvers (#536, #261 Part C). Since 5.13.0,
householderandapply_householder_left/righthave taken anAccumulator(#537), but none of their callers passed one, so no factorization or eigensolver could use it.qr_factor,qr_extract_Q,qr_solve,lq_factor,lq_extract_Q,hessenberg_factor,hessenberg,tridiagonalize,eigenvalue_symmetric_generic,eigenvalue_symmetric,eigen_symmetric,eigenvalueandeigennow take a leadingAccumulator = void, following #542’s convention (qr_factor<Acc>(A, tau)), and forward it to every Householder call.qr_solvealso uses it for the two sums it forms itself: vᴴy when forming Qᴴb, and each row of the back substitution. A non-void accumulator skips the LAPACK dispatch (geqrf,syevfor real andheevfor complex Hermitian matrices,geev), since LAPACK’s sums are its own. With the defaultvoid, every call runs exactly the code it ran before. The QR iterations, the Givens rotations andeigen’s inverse iteration keep plain arithmetic: they work on fixed 2- and 3-term expressions or are outside the Householder path.test_householder_accumulator_callerscounts the accumulator’sadd_productcalls in each routine and compares them with the exact number of terms its sums contain, so a caller that drops the accumulator anywhere fails, including a LAPACK build that dispatches instead. A complex Hermitian case covers theheevbranch, which CodeRabbit found ungated in review. Measured on random 256 × 256floatmatrices, accumulating indoublelowers QR’s backward error ‖QR − A‖/‖A‖ from 6.8e-7 to 3.7e-7. On the same matricesqr_solve’s error and the symmetric eigenvalues’ error showed no consistent improvement, since conditioning and the QR iteration dominate them. -
eigen_symmetric_jacobi(A): a two-sided cyclic Jacobi eigensolver for small dense symmetric matrices (#564). It returns the same{eigenvalues, eigenvectors}aseigen_symmetric, eigenvalues ascending. Tridiagonal QR is accurate to about ε‖A‖ in each eigenvalue. For a positive (semi)definite matrix, Jacobi gets small eigenvalues and their eigenvectors to high relative accuracy (Demmel & Veselić), which matters for the null vector of a normal matrix AᵀA. On 9 × 9 and 12 × 12 null-vector problems with columns scaled across 10⁶ (200 trials each), the eigenvector error is 4.9e-15 and 5.4e-15 rad, against 6.6e-7 and 1.9e-6 foreigen_symmetric. On graded positive definite matrices whose eigenvalues span 8 to 24 decades, the worst relative eigenvalue error is 6.6e-16, against 2e-13 to 8e-11. It sweeps pairs row by row with the stable rotation t = sign(θ)/(|θ| + √(θ²+1)), formed so θ² cannot overflow. A pair is skipped once |a_pq| ≤ tol·√|a_pp|·√|a_qq|, and the solver stops after a sweep with no rotation.toldefaults to ε andmax_sweepsto 60. The issue proposed stopping on off-diagonal mass ≤ ε²‖A‖²_F instead. That test guarantees only absolute accuracy: it returns diag(1, 1e-10, 2e-10) coupled by 1.5e-16 with the small eigenvalues 2.25e-12 relatively wrong, and a unit test checks that case. No entry is squared, so matrices scaled from 1e+300 down to subnormal values converge. Real element types only, posits included; complex is rejected at compile time. Headeroperation/eigenvalue_symmetric_jacobi.hpp, included frommtl.hpp.-
Tests:
test_eigen_symmetric_jacobichecks:- reconstruction and orthogonality for n = 1…16, in
doubleandfloat; - agreement with
eigen_symmetric; - convergence in under 20 sweeps on 9 × 9 and 12 × 12 normal matrices, by comparing bits with a run capped at 19 sweeps;
- matrices scaled by 1e±160;
- relative accuracy against a
long doublereference wherelong doubleis wider thandouble; - zero eigenvalues and trivial sizes.
Mutating the stop to the Frobenius test, or squaring entries in the pair test, fails the suite.
- reconstruction and orthogonality for n = 1…16, in
-
Benchmark: a new
bench_all --suite eig-small(not part ofall) times it againsteigen_symmetricandsvdfor n = 3…16. At n = 9 it takes 11–12 µs, against 4–5 µs foreigen_symmetricand 14–23 µs forsvd. -
Docs:
docs/algorithms/eigenvalues.mdcovers when to choose it, which was item 3 of #565.
-
-
svd(A, s, V), a V-only SVD with QR preconditioning, andnull_vector(A)(#566). The fullsvd(A, U, S, V)always forms the m × m U, then runs one-sided Jacobi over all m rows. A null-space caller (8-point 2k × 9, DLT 2k × 12) needs only V’s last column. It paid 500 µs at 64 × 9 and 0.24 s at 400 × 9, almost all of it completing U to a full basis.-
What it computes: the new overload returns the singular values (descending) and the n × n V, and never forms U.
null_vector(A)returns V’s last column, the unit vector minimizing ‖Ax‖. -
How: for a tall A it first reduces A = QR by Householder QR and runs Jacobi on the n × n R, which is Drmač and Veselić’s preconditioner.
-
Accuracy: against the full
svdon 10 × 3 to 400 × 12 matrices, including rows or columns scaled across 10⁸, the singular values agree to 1.3e-15 relative, and the columns of V to the same. For m ≤ n it runs Jacobi on A and matches the fullsvdbit for bit. -
Speed: median times in µs, measured by the new
bench_all --suite null-vector(not part ofall).m × N null_vectorfull svdeigen_symmetric(AᵀA)eigen_symmetric_jacobi(AᵀA)16 × 9 22 39 5.5 9.9 400 × 9 34 238,543 15 18 400 × 12 61 239,732 26 36 It is slower than the AᵀA eigensolvers but does not square A’s condition number. In
floaton 36 × 9 matrices whose second-smallest singular value is 1e-3, its null vector is off by 1.3e-5 rad, against 2.0e-2 for Jacobi on AᵀA. Most of its time is spent in the Jacobi sweeps on R: the shared one-sided Jacobi core divides every element by a scale factor on every pair, to stay safe from overflow. Making that cheaper would change the fullsvd’s bits, so it is left for a separate change. -
Backend: both calls always use the generic C++ path, since LAPACK’s
gesddhas no V-only mode. -
Refactor: the one-sided Jacobi loop moved into
detail::one_sided_jacobi, shared by allsvdoverloads. The fullsvdreturns bit-identical results to before. -
Tests:
test_svd_null_vectorcovers bit identity for m ≤ n (inlong double, so a LAPACK build compares generic against generic), and agreement to rounding on graded tall cases. It also checks thatnull_vectorrecovers a known null vector of 2k × 9 and 2k × 12 systems for k = 8, 32 and 200, plus wide, square-singular and empty shapes. -
Not included: a thin U (m × min(m,n)) is left for a follow-up.
-
Changed
Section titled “Changed”eigen_symmetric,eigenvalue_symmetricandeigenvalue_symmetric_genericdefaulttolto machine epsilon and use LAPACKdsteqr’s deflation test (#565). Results change: the in-house symmetric eigensolver returns different bits for most inputs. The LAPACKsyev/heevpath is unaffected, since it ignorestol. The default was1e-10, which capped accuracy far short of what the method reaches, the same problemsvd’s default had (#337). A subdiagonal entry e between d₀ and d₁ was dropped once |e| ≤ tol·(|d₀| + |d₁|), a test that scales with the larger eigenvalue. It is now dropped once |e| ≤ tol·√|d₀|·√|d₁|, which scales with the smaller one. Measured on 9 × 9 and 12 × 12 normal matrices AᵀA with a known null vector (200 trials each): with the defaulttol, the smallest eigenvalue’s eigenvector moves from 8.4e-12 to 9.0e-16 rad (N = 9) and from 9.1e-12 to 1.1e-15 (N = 12), and the new default accounts for all of it. Withtol = 1e-10passed explicitly, the new deflation test alone lowers the error from 8.4e-12 to 2.0e-12. Withtol = εit changes nothing measurable. Neither change helps when A’s columns are scaled across 10⁶: the eigenvector error stays at 6.6e-7 (N = 9) and 1.9e-6 (N = 12), because tridiagonal QR is only accurate to ε‖A‖ in each eigenvalue. Closing that gap is the job of the Jacobi solver in #564. mtl5-python’seighandeigvalshpasstol = 1e-10explicitly, so only the deflation change reaches them.spectral_propertiesuses the default. New tests intest_eigen_symmetricfail against the old header: a 2 × 2 case withtol = 1e-6, where the old test returned the small eigenvalue 2.5e-5 relatively wrong, and a null-vector case at the defaulttol. A third test checks that exactly zero eigenvalues still deflate under the stricter test. A custom real without astd::numeric_limitsspecialization reportsepsilon()as zero, which would deflate only exact zeros: about a third of random 10 × 10 matrices then ran out ofmax_iterwith eigenvalues ~5e-8 off, unreported. For such a type the default is measured instead (the spacing at 1, found by halving), and a non-positivetolmaps to the default, as insvd. Found by CodeRabbit on #568.
Documentation and maintenance
Section titled “Documentation and maintenance”- CMake declares a
3.22...4.2policy range (#571), inCMakeLists.txtandppe/CMakeLists.txt. 3.22 stays the oldest supported CMake; a newer CMake now applies new-style behavior for every policy up to 4.2 instead of the 3.22 defaults. It is the same range as mp-blas, mp-iterative, mp-ode, mp-spice and Universal. Configuring with CMake 4.2.1 before and after registers the same 210 tests, with identicalCMAKE_CXX_FLAGS*and no warnings.
[5.15.0] - 2026-10-11
Section titled “[5.15.0] - 2026-10-11”The QR counterpart of 5.14.0’s Cholesky opt-in: an opt-in textbook Householder reflector, so a port pinned to a hand-written textbook QR or LQ can reproduce it bit for bit. Reviewing it turned up a qr_solve fix that applies to the default QR too. No breaking changes. The default reflector, qr_factor and lq_factor compute exactly what they did in 5.14.0.
qr_factor(A, tau, tag::textbook_reflector{})andlq_factor(A, tau, tag::textbook_reflector{}), and the same tag onhouseholder,apply_householder_leftandapply_householder_right: an opt-in textbook Householder reflector for bit-reproducible ports (#559). The default reflector is LAPACK’s form: x scaled by max|x|, v(0) = 1, τ = 2v₀²/(σ + v₀²), and R’s diagonal non-negative. Many hand-written QRs use the textbook (Golub & Van Loan) form instead: unscaled ‖x‖, α = −sign(x₀)·‖x‖, unnormalized v with v(0) = x₀ − α, and a per-column updatef = (2·s)/vᵀv; A(i,j) -= f·v(i). The two round differently and, when x₀ > 0, reflect onto opposite signs. branes-ai/cortex’s filter port saw 10 of 117 stage outputs move, its null-space projection change at O(1), and 1 of 16,265 update decisions flip on EuRoC V2_03.householder(x, tag)returns{v, vtv, alpha}.apply_householder_left(A, v, vtv, row, col, tag)applies it, threaded over columns, andapply_householder_right(A, v, vtv, row, col, tag)applies it on the right, threaded over rows, so neither result depends on the thread count. Zero and NaN columns are skipped with a hand-written loop’s own tests,!(norm > 0)and!(vᵀv > 0). The taggedqr_factornever dispatches to LAPACK. Its R, on and above the diagonal, is bit-identical to a textbook QR, signs included. Below the diagonal and intauit stores the same reflector in MTL5’s packed form (v/v(0), τ = 2v(0)²/vᵀv), soqr_extract_Qandqr_solvework unchanged, with Q matching the textbook Q to rounding. The taggedlq_factoris its row mirror: L, on and below the diagonal, is bit-identical to a textbook LQ, andlq_extract_Qworks unchanged. The default overloads are unchanged. Real element types only. The tag lives in<mtl/tag/reflector_form.hpp>.test_householder_textbookchecks each tagged path against reference textbook loops with==ondouble,floatand a class-typed scalar, including skipped zero and NaN columns and 300 × 2000 and 2000 × 300 updates split across 4 threads; it is built with-ffp-contract=off.docs/numerical/householder-reflector-forms.mdcovers the why, what and how.
qr_solveskips a reflector with τ = 0 (#559). τ = 0 is the identity reflection, and the column below the diagonal then holds the column’s own entries, not a reflector.qr_solveapplied it anyway asy -= 0·v·(vᵀy), which is NaN as soon as one of those entries is NaN, so a skipped NaN column turned the whole solution into NaN. Both the default and the textbookqr_factorleave τ = 0 for such a column.qr_extract_Qalready skipped it, sinceapply_householder_leftreturns early on a zero τ. Finite inputs are unaffected, except that a zero in y can no longer change sign throughy − 0. Found by CodeRabbit on #560.
Documentation and maintenance
Section titled “Documentation and maintenance”- The regression test tier is documented in Getting Started → Build Options (#561). It covers
MTL5_BUILD_REGRESSION_TESTS, how to run the tier with theci-regressionpreset and theregressionCTest label, and what each of the 14 programs intests/regression/checks, with problem sizes and pass thresholds. It also gives the per-test time limits, and when CI runs the tier: non-draft PRs only, after the 8-platformbuildjob.
[5.14.0] - 2026-10-11
Section titled “[5.14.0] - 2026-10-11”Three changes driven by branes-ai/cortex’s port of a Kalman filter onto MTL5: two speed up mult() on the small, structured operands of filter covariance algebra, and one lets a port pinned to a hand-written Cholesky factorization reproduce it bit for bit. No breaking changes. cholesky_factor’s default results are unchanged except that a NaN pivot is now reported as an error instead of returning success.
Performance
Section titled “Performance”- The generic dense GEMM runs as an i-k-j loop when B and C are row-major (#549).
detail::mult_generic_rowswas an i-j-k dot product. Its inner loop walks B down a column, and its single accumulator is a sequential reduction the compiler cannot vectorize, so it ran 1.5–2.6× slower than an i-k-j loop. Those numbers are from 15–81-wide shapes in branes-ai/cortex’s filter covariance algebra. The kernel now keeps C’s row as the accumulator and addsA(r,k) * B.row(k)for each k. That inner loop is contiguous and independent, so it vectorizes. EachC(r,c)is still built as zero plus the products in ascending k with the samegeneric_fma, so results are bit-identical for every scalar type when the compiler does not contractacc + a*binto an FMA. That holds under-ffp-contract=off, and on targets without FMA such as baseline x86-64. Under contraction, the i-k-j loop fuses every term while the old loop fused only some, so the two agree to rounding but not to the bit.test_mult_ikjcompares bits against the old loop, including -0 and infinities, and is built with-ffp-contract=offlike the other bit-identity tests. Other layouts and the custom-Accumulatorpath keep the dot-product loop. Measured at-O3, gcc 15, no-march: P·P (81×81) 142 → 75 µs; P·Hᵀ (81×81·81×15) 30 → 18 µs; K·H (81×15·15×81) 25 → 14 µs.
-
cholesky_factor(A, tag::subtract_term_by_term{}): an opt-in summation order for bit-reproducible ports (#556).cholesky_factorforms each entry asa − (Σ products): it sums the products from zero, then subtracts once. Many hand-written factorizations instead start from the matrix entry and subtract term by term. Both forms are backward stable, but they round differently, so a port pinned to the term-by-term form couldn’t move to MTL5 without changing bits. branes-ai/cortex’s filter port saw 37 of 117 stage outputs move and 2 of 16,265 update decisions flip on EuRoC V2_03. The new overload selects the term-by-term form. It never dispatches to LAPACK, whose order is its own, and it keeps the same row-partitioned threading, so the result doesn’t depend on the thread count.cholesky_factor(A)is unchanged, andtag::subtract_sumnames the default explicitly. The tags live in<mtl/tag/summation_order.hpp>.test_cholesky_orderingchecks the opt-in against a reference term-by-term loop with==, ondouble,floatand a class-typed scalar up to n = 768 with 4 threads. It is built with-ffp-contract=off, like the other bit-identity tests. Neither order is more accurate across the board: term by term is ahead on ill-conditioned spectra and sum-then-subtract on well-conditioned ones, both within a small multiple of the unit roundoff. The new Numerical Considerations docs section,docs/numerical/summation-order-in-cholesky.md, covers the why, what and how with measurements and a worked example. -
mult(compressed2D A, dense2D B, dense2D C): a sparse × dense matrix product (#550). It previously fell to the generic kernel, which readsA(r,k)by binary search for every (r, c, k). It now walks A’s stored entries row by row (detail::mult_sparse_crs_dense_par, threaded over row bands like the sparse matvec):C.row(r) = Σ v · B.row(k)over A’s entries in ascending k. That is the dense product’s summation order with A’s zero terms left out, so it equals the dense result bit for bit whenever those terms are exact zeros (with the same contraction caveat). With BLAS enabled,mult()’s BLAS gate no longer instantiatesis_row_major_vfor operands without anorientation. Before, that was a compile error for acompressed2Dortransposed_viewoperand. The test checks this, and checks agreement with the column-by-column sparse matvec. B and C must be row-major dense; other layouts are unchanged.
cholesky_factorrejects a NaN pivot (#556). The generic path testeddiag <= 0, which is false for NaN, so a NaN in A returned 0 (success) with NaNs in L. It now tests!(diag > 0), ascholesky_h_factoralready did, and returns k+1 for a NaN pivot in either summation order. Finite inputs are unaffected. The LAPACK path’s behaviour ispotrf’s own.
Documentation and maintenance
Section titled “Documentation and maintenance”- Performance analysis of #549 and #550:
docs/performance/ikj-gemm-and-crs-dense.md, which arrived with #552. It shows the filter operands’ non-zero structure (F = Φ ⊕ I is 4.4 % non-zero; the Joseph factor I − KH ranges from 27 % to 100 %), explains why the i-k-j order vectorizes while keeping each element’s summation order, and gives an interleaved before/after on an i7-12700K with hand-written control loops in both builds. Results: P·P (81×81) 137 → 76 µs at baseline x86-64 and 141 → 53 µs with AVX2; F·P 635 → 3.6 µs. The A/B source isbenchmarks/bench_mult_ikj.cppand the figures come frombenchmarks/fig_mult_ikj.cpp. Both are registered underMTL5_BUILD_BENCHMARKS. - Session log for 2026-10-10 – 2026-10-11:
docs/sessions/2026-10-11-true-under-the-flags-it-was-checked-with.md. Covers #547, #548, the 5.13.2 release, mtl5-python’s pin bump, and #552’s performance page together with the three CI defects writing it uncovered: FP contraction against a bit-identity claim, a BLAS gate that instantiatedM::orientationon types without one, and a test that assumedmult()never reaches BLAS. Its through-line is that each of the day’s claims was true in the configuration it had been checked in, and stopped being true outside it. - CI skips docs-only changes and runs once per PR commit (#555).
ci.ymlran its whole matrix, unit and regression, for a commit that touched onlydocs/. It now haspaths-ignorefordocs/,docs-site/, Markdown, images,LICENSE,.coderabbit.yamland.nojekyll;docs.ymlstill builds the site for those. A PR commit had also run the matrix twice, once for the branch push and once for the PR: pushes now trigger only onmainand release tags, and a new commit on a PR cancels that PR’s run in progress. Each PR commit went from 46 checks to 25. Feature branches without a PR can still be run withgh workflow run ci.yml --ref <branch>. No check is required by name, so a docs-only PR stays mergeable. - CI action bump:
actions/setup-node7.1.0 (#553).
[5.13.2] - 2026-10-11
Section titled “[5.13.2] - 2026-10-11”A patch release: the scalar operators work with the custom number types MTL5 is built for, and the eigensolvers’ accumulator tests can now tell the two policies apart.
scalar * matrix,matrix * scalar,matrix / scalarand their vector forms accept any non-containerScalar(#548, resolves #538). The six operators were gated onstd::is_arithmetic_v<S>, which rejected posits,cfloat, LNS, fixed-point andstd::complex, even though all of them satisfymtl::Scalarandmtl::Field. It turned up in a Kalman filter over posits:K = P H^T / Sdid not compile. The gate is now!Collection<S> && Scalar<S>. The!Collectioncheck comes first and short-circuits, because evaluatingScalar<S>for a matrix or vector operand would recurse into these same operators.matrix * matrix,matrix * vectorand built-in scalars resolve as before, and a new test checks that.- The eigensolver accumulator tests can tell the policies apart (#547). This resolves the follow-up recorded in the 2026-10-10 session log below. In the earlier
power_iteration,lanczosandarnolditests, afloataccumulator and adoubleone both reached the 1e-4 tolerance floor, so a solver that ignored the accumulator would still pass. Each solver now has a test on a 1024×1024 diagonal (2^20, 1022 ×2^-5,-2^20) whose Rayleigh quotient cancels. Afloataccumulator gets exactly 0, adoubleaccumulator gets the exact value, and the test fails if the accumulator is ignored. Arnoldi’s second Gram–Schmidt pass leaves its result 0.2% high, so it is checked to within 1%. The original tests are kept, renamed to say what they check: that both policies converge.
Documentation and maintenance
Section titled “Documentation and maintenance”- Session log for 2026-10-09 – 2026-10-10:
docs/sessions/2026-10-10-every-test-overrode-the-default.md. Covers the leading-Accumulatorconvention (#539, #540, #542), the 5.13.0 and 5.13.1 releases, and the downstream bumps in mp-iterative, mp-spice and mtl5-python. Its through-line is the 5.13.0 regression: every test accumulator overrodeclear(), the one function that was broken, so the suite never ran the default it fell back to. It also records an open follow-up: the restored Lanczos accumulator test (#540), and the Arnoldi test it was rewritten from, can’t tell afloataccumulator from adoubleone, since both only need to reach a 1e-4 floor. CodeRabbit noted this on #540.
[5.13.1] - 2026-10-10
Section titled “[5.13.1] - 2026-10-10”A patch for one regression in 5.13.0. If you use Universal’s lns types, or any arithmetic type whose value-initialized state is not zero, upgrade.
accumulator_traits::clear()sets zero, not a value-initializedAcc(#544).clear()reset witha = Acc{}, assuming value-initialization is zero. That holds for every built-in type but not in general. A logarithmic number system encodes 2⁰ in its all-zero bit pattern, so Universal’slns{}is 1.0, and every sum of products over anlnsaccumulator started at 1. 5.13.0 made this reachable without opting in: #537 routedhouseholder()’s sum of squares throughclear()on the default path, where 5.12.0 had started it atmag_t(0). As a result QR and LQ overlnswere wrong outright (Q orthogonality error 1.5, QR residual 0.53 for lns16 and lns32), and with them everything built on Householder reflectors. mtl5-python’s suite caught it on the v5.13.0 bump.clear()now assignsmath::zero<Acc>().fma_accumulatorhad the same flaw in itsclear()and in its member defaultT sum{}, and both are fixed. An audit found every other accumulator declaration and workspace is cleared or assigned before it is read. The suite had missed this because every test accumulator specializedaccumulator_traits, so none exercised the primary template. The new regression test uses a mock type whose value-initialization is 1.
[5.13.0] - 2026-10-10
Section titled “[5.13.0] - 2026-10-10”One programme: the accumulator policy reaches the rest of BLAS and the solvers (#261 Part C). accumulator_traits<Acc, Value> lets a caller choose how a sum of products is rounded: wider IEEE, FMA, or a quire through the peer repos. Until this release that choice was available on dot, mult, norms, the Krylov solvers and four sparse factorizations. It now covers every BLAS L1/L2/L3 routine, the sparse Cholesky/LDLᵀ/QR factorizations, Householder reflectors, and the three iterative eigensolvers. The release then settles one calling convention for all of them: Accumulator is the first template parameter, so op<Acc>(args...) selects it and everything else is deduced.
Breaking changes, all in explicit template arguments; calls that deduce everything are unaffected. Read the first entry before upgrading — it is the one place an old call still compiles but means something different.
Breaking
Section titled “Breaking”axpy,scale,ger,symv,trmm,trsm,symm,syrk,syr2k: the first explicit template argument is now the accumulator, not the scalar type (#511, #515, #522–#526). Each gained a leadingAccumulator = voidin front ofScalar S. A 5.12 call that fixed the scalar type explicitly, e.g.axpy<float>(0.1, x, y)meaning “convert alpha tofloat”, still compiles and now means “accumulate infloat, alpha staysdouble”. Results can differ with no diagnostic. To keep the old meaning, convert the argument instead:axpy(float(0.1), x, y). Explicit lists ontrmv,trsv,lower_trisolveandupper_trisolve, whose first parameter was the matrix type, fail to compile rather than change meaning.- Krylov solvers take a leading
Accumulator(#539).cg,bicg,bicgstab,bicgstab_ell,cgs,gmres,minres,qmr,tfqmrandidr_shad it last, after five deduced types, so it could only be set by restating all of them:itl::cg<M, VX, VB, PC, Iter, Acc>(...)is nowitl::cg<Acc>(...). Old full lists fail to compile. Downstream: mp-iterative updated in its #44. - Sparse numeric factorizations take a leading
Accumulator, defaulting tovoid(#542).sparse_lu_numeric,native_klu_factor,supernodal_lu_numericandsupernodal_ldlt_numerichadAccumulator = Valuelast, so a caller had to spell out the matrix’s internal parameter type:supernodal_lu_numeric<double, decltype(A)::param_type, float>(A, sym)is nowsupernodal_lu_numeric<float>(A, sym). A leading default cannot nameValue, so the default isvoid, resolved toValueinside; default calls are byte-identical. Old full lists fail to compile. A single explicit<Value>still compiles and behaves as before. Downstream: mp-spice updated in its #18; mtl5-python’s five call sites inmtl5_sparse_direct.cppneed the same change when its pin moves past v5.11.0. power_iteration,lanczos,arnoldi: explicit<LinearOp, T>no longer compiles (#540). These gained an accumulator in this release (#518, #528, #529), placed leading with avoiddefault that means “accumulate inT”. A 5.12 call that named the operator and value types explicitly now fails to compile; drop the arguments, both are deducible.sparse_cholesky_numeric,sparse_ldlt_numeric,sparse_qr_numeric: explicit<Value, Parameters>no longer compiles (#530, #531, #534, #542). The same shape as the entry above for the sparse factorizations that gained an accumulator in this release. A single explicit<Value>still works.
- Accumulator policy for the BLAS L1 remainder:
axpyandscale(#511).axpyis a one-term sum of products seeded withy(i)rather than zero, so it is the first caller of the contract’sassign. A test asserts the operation counts directly (axpy drivesassignand neverclear; scale the reverse), which turns #261 Part A’s “audit the call sites” from a reading into a check.scalesums nothing; what a non-default accumulator buys it is widening, and the entry says so. The accumulator sees the scalar at its own precision: a wider alpha is no longer rounded to the element type beforeadd_product. - Accumulator policy for BLAS L2:
ger,symv,trmv,trsv(#515, #516).gemvwas already covered throughmult.trsvdelegates its reduction tolower_trisolve/upper_trisolve, so both trisolve headers carry the accumulator too.trsv’s BLAS dispatch is now gated onaccumulator_allows_blas_v, which it previously was not. - Accumulator policy for BLAS L3:
trmm,trsm,symm,syrk,syr2k(#522–#526, sub-issue #521). In each, the reduction is accumulated and rounded out once;alpha/betaand the triangular division are applied afterwards, outside the accumulator. The upper-triangle mirror insyrk/syr2kis a plain copy, not a re-sum. - Accumulator policy for
sparse_cholesky,sparse_ldltandsparse_qr(#530, #531, #534). This completes the sparse direct line alongsidesparse_lu,native_klu,supernodal_luandsupernodal_ldlt. Insparse_ldltthe per-term square is still rounded inValuebefore reaching the accumulator, a limit documented at the call site. - Accumulator policy for Householder reflector construction and application (#537).
householder’s sum of squares and the per-column/per-row dot products inapply_householder_left/right. The default path keeps the threaded fast path untouched; a non-default accumulator runs a serial loop, since the threaded combiner does not reason about a caller’s accumulator type. Not yet reachable fromqr/lq/svd:qrcallsapply_householder_leftwithout forwarding an accumulator. Tracked in #261. - Accumulator policy for the iterative eigensolvers:
power_iteration,lanczos,arnoldi(#518, #528, #529, sub-issue #527). These route the Rayleigh quotient, Lanczos’s α/β and Arnoldi’s Hessenberg entries and residual norm through the accumulator. On the well-conditioned test problems the error is dominated by Krylov convergence, not accumulation, so the accuracy tests assert both configurations reach the tolerance floor rather than a strict ordering. - The eigensolvers’
tolis non-deduced (#540). It is nowstd::type_identity_t<T>, sopower_iteration(A, v_float, 1000, 1e-6)compiles.Tcomes from the vector alone; before, adoubleliteral tolerance conflicted with afloatvector in deduction.
- SIMD scalar tails round the way the vector body does (#513, resolves #512).
reduce_dot,reduce_dot_widen,reduce_sum_squaresandaxpyusedfma()in the vector body and a plain multiply-add in the scalar tail, so an element’s rounding depended on its index. Foraxpy, where every element is an independent output, the firstW·⌊n/W⌋entries were computed differently from the rest. The tail now applies the body’s own batch primitive to a broadcast and reads one lane back. Mirroring Highway’sMulAddbranch instead failed on clang + Highway, and a decomposedc + a*bcould be re-contracted under-ffp-contract=fast. - The Lanczos accumulator test is back (#540). #529 rewrote it in place into the Arnoldi test instead of adding one alongside it, which left
lanczos’s accumulator path untested; the suite’s case count did not move because the whole file is one ctest entry. test_integer_wrapping_genericbuilds on glibc 2.43 (#541). glibc now declares C2y’suabsin<stdlib.h>, which made the test’s ownuabsambiguous on GCC and Clang. It is renamedabs_as_u32and the reference helpers moved intomtl::test.
Documentation and maintenance
Section titled “Documentation and maintenance”- The release checklist starts from the commit range, not from memory (#510), after the 5.12.0 CHANGELOG covered 7 of 28 PRs. The 5.12.0 entry was completed in #509.
- CI action bumps:
softprops/action-gh-release3.0.3 (#520),actions/deploy-pages5.0.1 (#519).
[5.12.0] - 2026-08-27
Section titled “[5.12.0] - 2026-08-27”Two programmes. On-node parallelism for emulated formats — the threaded
kernels that the BLAS-scalar gate had been keeping them out of — together with the
completion of #450’s integer exclusion through itl/. And the nc model: the
jc partition made measurable, timed on four microarchitectures, and then adopted
as the default on evidence rather than argument.
Two breaking changes, both narrow and both removing instantiations that already returned wrong answers; see Breaking below before upgrading.
Breaking
Section titled “Breaking”mtl::itlrequires aFieldelement type — solvers, preconditioners and smoothers (#503, #505). Every Krylov solver computes its step lengths as ratios in the element type:cg’sbeta = rho / rho_1andalpha = rho / dot(p, q), ten such divisions inqmr, eight intfqmr, at least two in every one of the ten includingcgsandgmres. On an integral type that division truncates, so the iteration was nonsense from the first step — it ran, it converged or it did not, and it returned a confident wrong answer with no assertion and no flag. The preconditioners and smoothers are a separate entry point, constructed before any solver sees them, sopc::ilu_0<int> M(A)truncated its factorization at construction and a solver gate would never have fired. This is #450’slu_factor(dense2D<int>)one and two levels up: ℤ is a ring, not a field. NewFieldVector(the vector counterpart ofFieldMatrix) gates the eleven solver entry points includinggmres_inner;FieldMatrixandField<Value>gate the eighteen preconditioner and smoother types. What breaks downstream: integral element types initlno longer compile. Every affected call site was already wrong — fordiagonal,jacobi,gauss_seidelandsorit was worse than truncation, sincevalue_type(1) / A(i, i)is 0 whenever |A(i,i)| > 1, making the preconditioner the zero operator. float, double, complex and the custom number types are unaffectedilut’s threshold parameter is the real magnitude type, not the element type (#505).magnitude_t<Value>, which isValuefor every real element type, so real users see no change. It wasValue, which madeabs(w[k]) < drop_tolcompare adoubleagainst acomplex<double>:ilut<complex<double>>named a valid type whosefactorize()did not compile
- Threaded dense GEMV and GEMM for non-BLAS scalar types (#446).
is_blas_scalar_vgated two unrelated questions at once — “may this go to OpenBLAS or a SIMD micro-kernel?” and “may these output rows be split across cores?”. Only the first is about the scalar type; a row partition hands each worker a disjoint set of output elements and runs the same per-element code the serial loop would. Every software-emulated format — posit, cfloat, lns, the dd/qd cascades — therefore ran its dense matvec and matmul on one core regardless ofMTL5_NUM_THREADS. NewThreadableDenseMatrix/ThreadableDenseVectorcarry the storage shape only, with no constraint on the element type, and gate a row-partitioned wrapper around the generic kernel — deliberately not a reroute intogemm_blocked, which earns its keep through a vectorized micro-kernel and measured ~3.4× slower for a type Highway cannot vectorize. Measured on an i7, GEMM n=384 on a class-typed scalar, min of 5: flat before (0.120 / 0.177 / 0.113 / 0.117s at 1, 2, 4 and 8 threads) against 0.115 / 0.062 / 0.031 / 0.049s after — 3.7× at four threads. Bit-identical at every thread count, asserted with==rather than a tolerance - Threaded sparse CRS matvec in
mult(#446 follow-up).mat::operator*(compressed2D, dense_vector)had threaded this traversal for any value type since #221, butdetail::mult_sparse_crs— the accumulator-aware kernelmult(compressed2D, x, y)dispatches to, and the one a mixed-precision sweep calls — ran it serially. The gather fromxis what makes the forward kernel safe to partition and its transpose not. 3.8× at four threads, 4.8× at eight on a scalar whose multiply costs what an emulated format costs. The honest counterweight is recorded with it: on a cheap scalar the same kernel gains only 1.18×, because adoubleSpMV is memory-bandwidth-bound and the cores have nothing to do parallel_chunk_units<T>androw_grain<T>(#446). The 65536-unit chunk budget is a wall-clock quantity counted in operations, so it only fits a type whose multiply-add is one instruction. Charging an emulated format the same costs parallelism, not overhead:parallel_forcaps the team atn / grainchunks, so a posit GEMM at n=64 would form four and idle half an eight-way pool. Class types get 1024. Unchanged for float/double —row_grain<double>(nn)is65536 / nn
The nc model: making the jc partition measurable, then choosing one (#479, #492)
Section titled “The nc model: making the jc partition measurable, then choosing one (#479, #492)”- The prerequisites that need no hardware (#480).
balanced_nc(the jc counterpart ofbalanced_mc), the two mediatorsgrid_imbalanceandpacked_b_bytesrecorded per point bybench_blocking_ab, models M0–M5 as pure functions, andsweep_nc_modelsto enumerate offline where they disagree.balanced_ncis deliberately not wired into the nest here — measuring whether it should be is a separate step from applying it. The work caught a defect in itself:balanced_ncfirst rounded the balancedncup to a multiple ofnr, which undid the balancing — a pre-registered control caughtm4_per_sharerat n=276681 going from a perfectly even partition to 1.0038, the balancing step making the imbalance worse - The harness arm that made the models timeable (#484).
gemm_blockedread its jc block size from a compile-time constant, so six candidate models could be enumerated but not timed. The nest now takes a model per call, defaulted to the process selection (MTL5_NC_MODEL, M0 when unset) — per call because six arms must run back-to-back in one process to share a thermal state and a warmed pool, or the machine rather than the model becomes the thing under test. M0 short-circuits to the shipped constant rather than recomputing it, so the baseline arm is the code that ships and the control cannot have moved m7_sharer_gated, added as a candidate and explicitly not as a default (#497). M4 (per-sharer budget) had the largest wins measured anywhere in this work — median ×1.769 — but was not shippable ungated: the win is confined to the shapes the sweep selects and it costs ~1.2% on square GEMM, the common case. The gate is structural, which is the point:jc_ntis read from the baseline grid before any model runs, and on four machines it separates the shape classes exactly — 105 of 105 jc-parallel arms havejc_nt ≥ 2, and all 35 control arms havejc_nt == 1. Gated, every control keeps M0’sncby construction and cannot move
Benchmark provenance, carried through to the whole fleet (#442 follow-through)
Section titled “Benchmark provenance, carried through to the whole fleet (#442 follow-through)”bench_allandrun_int_benchnow record their own provenance (#475). #442’s contract says every new sidecar carriesgit_commit,git_dirty,cxx_flags,governorandpool_size; half the fleet never did. Every CSV the integer suite had produced, on all four machines, could not be traced to a commit, a compiler flag or a machine state — including the data the entire VNNI conclusion rests on. That is the exact failure #442 was written to prevent, and its own text names the precedent: the first Zen 4 run was AVX2 when AVX-512 was intended, and nothing in the data could say so- CI fails when a committed CSV has no provenance sidecar (#478). A check that fails rather than a person noticing — the 28 pre-existing files are listed in
benchmarks/data/.sidecar-exemptand cost nothing; what the check forbids is adding another. Retro-fitting them is deliberately not attempted, since the information was never captured and inventing it would be worse than its absence. The list only ever shrinks, and the checker enforces that from both sides: it also fails when an exempt file has gained a sidecar, or names a CSV that no longer exists, so the exemption list cannot rot into a permanent amnesty
- Integer overflow is no longer UB in the sparse and remaining L1 generic loops (#461). #460 defined the wrapping contract for the dense path; these loops were outside it and still accumulated with a plain
+=/*=. Routed throughdetail::generic_fmaand two new siblings —generic_addfor the loops that accumulate a term they did not form by multiplying,generic_mulforscale— acrossmult_sparse_crsand its transpose,axpy,scale, six accumulations innorms, and the eageroperator*loops inmat/operators.hpp, which were not on the issue’s list but are the same defect two lines from one that was. All are the plain expression for every non-integral type, so float, double, posit, LNS and fixpnt are unaffected std::absat the minimum of a signed type (#461). UB — there is no positive 2^(N−1) — soone_norm(dense_vector<int32_t>)over full-range data was undefined before any accumulation happened, and it is reached by exactly the test the wrapping fix requires. Newgeneric_absreturns the wrapping answer. The consequence is recorded rather than hidden: the wrapped |min| is negative, so it never winsinfinity_norm’s max — an integer norm is defined and reduced mod 2^N, but it is only a norm when nothing overflowedilutcould not be instantiated with a complex element type (#505). Two causes: the threshold typing above, and twostd::sort(entries.begin(), entries.end())calls that compared pairs lexicographically, requiring an ordered element type for a.secondcomparison that unique column indices meant never happened at runtime. Both fixed; the row 2-norm now accumulates |a|² rather than a², which agrees for real elements and is only a norm for complex ones- The ThreadSanitizer CI lane discovers its own targets (#446). It built a hand-maintained list of
*_mttargets but ranctest -R _mt, which finds every_mttest whether or not it was built — so adding one failed the lane withCould not find executable, reported as a test failure inside a TSan job, which reads as a race and is not one balanced_mccould return a block shorter than the register tile (#488, fixed in #489).plan_gemm_gridfloorsmcatmrand says why in its own comment — “a block shorter thanmrwould waste the micro-kernel” — andbalanced_mcthen ran and lowered it straight back through that floor, because balancing works by raising the block count. Atmc=5againstmr=6, every ic block takes the micro-kernel’s edge path, not just the trailing one it was written for. The argument for the change is not “sub-tile is wasteful”: exhaustively over the 383,934 parameter combinations where the answer moves, the padded rows on the busiest thread are identical before and after — the old rule looked better balanced only in raw rows, and the padding erased exactly that difference. What did change is the total: the new answer does less work across all threads in 94.9% of those cases, 2.28× less on average, 16× at best, and more in nonepacked_b_bytesreported a panel larger than the nest builds, three ways (#486, fixed in #496). It is the mediator #479 records per point and the left-hand side of M6’s guard, so it has to be true rather than approximately true. It used the accumulator type where the panel is apacked_buffer<TB>(2× off for float operands into an fp64 accumulator, 4× for i8 into i32); it ignored the column padding, sincebalanced_ncdeliberately does not roundncto a multiple ofnron the threaded path — so a raggedncis the normal case, and this one was wrong even fordouble; and it ignored the quad k-padding. Resolved by answering #486’s three questions rather than by makingncbigger, which a naive reading would have done and which the data says is the wrong direction- The benchmark harness measured warmup and called it convergence (#493, fixed in #494).
bench_nc_modelsprinted “worst first-round excess over the minimum … (raise--rounds)” computed from round 0, which is a warmup question — raising--roundscannot change round 0 at all. It misled in practice: on the Xeon session behind #485 it fired at 45.62% and advised doubling the machine time for a session whose 24 control arms agreed to within 1.48%, and the false judgement was written into a committed sidecar. Now two numbers for two questions — convergence as the best time over all rounds against the best over the earlier two thirds, and warmup as a diagnostic only - The machine-identity guard never worked on ARM (#487).
grep -m1 'model name' /proc/cpuinfo || tr -d '\0' < /proc/device-tree/model— andA || Bruns B only when A fails. On ARM the grep succeeds, returning a genericARMv8 Processor rev 1 (v8l)with no board identity, so the device-tree fallback never ran on the one architecture that needs it. #439’s protection — do not write one machine’s numbers into another machine’s directory — was silently off on the Jetson for every sweep already committed. It failed in the safe direction, refusing a machine that was an Orin, which is why it was noticed; had the expected substring been something the generic ARM string contained, it would have accepted anything
Changed
Section titled “Changed”detail::mult_sparse_crskeeps its own copy of the CSR traversal rather than delegating to the row-range kernel the way the dense path does (#446 follow-up). Delegating measured 6.5% slower — starting the loop at a parameter rather than a literal0costs the optimizer something on thestarts[r] / starts[r+1]pair, and the restated assertions that recovered the dense case did not recover this one. That 6.5% would land ondoubleSpMV atMTL5_NUM_THREADS=1, the default, and the inner loop of every Krylov iteration initl/. A test pins the two bodies to each other- The default jc block size is
m6_guarded, and then the shape-gated per-sharer budgetM7(#429 first half in #490, #492 in #499).balanced_ncbecame the default in #490 on 840 arms across four microarchitectures and two dtypes, every one verified bit-identical to the baseline: M6 (M1 + guard) took 42 of 44 arms, median ×1.161, worst ×1.0002, zero regressions, where M1 plain had median ×1.152 but two regressions to ×0.82–0.89. The guard is the mechanism, not a curve fit, and that is why it shipped where an earlier candidate did not: loweringncraisesnjb, which can takejc_nt2 → 4, and each team holds its ownkc × ncpanel — so the resident set moves 16 MB → 24 MB, which a 25 MB L3 absorbs (×1.02) and a 16 MB L3 does not (×0.82, reproduced across three sessions including one with a pinned governor). Both terms are load-bearing, measured rather than argued:grewalone catches both regressions but declines two gains,exceeds L3alone catches both but declines 33 gains, the conjunction catches both and declines nothing. #499 then adopted M7 — M4 applied only where the baseline grid is jc-parallel, M0 everywhere else — against M6 on 1280 arms, again all bit-identical: Xeon +74%, i7 +108–116%, Ryzen +73–76% (all decisive against both the noise floor and session instability), Jetson +15–22% (supportive, its sessions too noisy to count as independent confirmation, recorded rather than averaged in). Zero arms worse than M6 anywhere, zero regressions against M0, all 40 control arms unchanged. The gate was pre-registered on the issue before the confirming run wrap_add/wrap_sub/wrap_mulare exempt from-fsanitize=integerby name (#461). That group bundlesunsigned-integer-overflow, which is not a UB check but a lint for accidental wrap-around, and it fires on the three helpers whose entire contract is deliberate unsigned wrapping. The exemption predates nothing — the acceptance criterion could not have been met onmaineither — and is narrow, so accidental wrap-around anywhere else stays caught
Documentation and data
Section titled “Documentation and data”- The nc-model sweeps and their tooling (#481, #482, #483, #485). The Xeon sweep and the tool hardening it exposed, a committed profile and README section so nobody retypes the invocation, a restamp of the Xeon sweep through that profile, and the timing run whose headline is that balance explains 92% of the variance. Committed benchmark data for all four machines — Xeon E5-2420 v2, i7-12700K, Ryzen 9 8945HS, Jetson Orin Nano — across the nc sweep, the nc-model timings and the provenance re-runs
- Figures refreshed against re-run data (#473, #474, #476). The Zen 4 claim that the data “disagrees” was stale — it had been re-run — and the figures across all four machines now match the provenance re-runs rather than the pre-contract ones
- Two documents that stopped describing fixed things as open (#491, #495). The L3 tripwire is no longer waiting on
balanced_nc, and the convergence metric is no longer a known defect - The BLIS five-loop GEMM, panels and micro-panels (#498), written up in
docs/algorithms/
[5.11.0] - 2026-08-22
Section titled “[5.11.0] - 2026-08-22”The integer-lane release. batch<T> gains 32-bit integer lanes, the two widening
dot kernels the hardware has instructions for, an integer GEMM, and the VNNI /
SDOT micro-kernel that puts those instructions inside a GEMM — measured on four
machines across two ISAs. No breaking changes.
Two fixes here change results for existing float/double code and are worth
reading before upgrading: a GCC 13 miscompile of AVX2 integer reductions, and
strided vector views reaching contiguous fast paths through ten operations —
dot_real over a stride-2 view returned 14 where the answer is 44, which
predates the integer work and affects a column of a row-major matrix. See
Fixed.
Integer lanes, and the widening dot kernels the epic was for (#451)
Section titled “Integer lanes, and the widening dot kernels the epic was for (#451)”batch<T>acceptsint32_tanduint32_tlanes, sodotand bothgemvorientations run the SIMD kernels for integer vectors instead of falling to the generic scalar loop (#460). The boundary is deliberate at both ends: 8- and 16-bit lanes are worth having only with the widening accumulate they exist for, and 64-bit integer multiply is emulated before AVX512DQ, so abatch<int64_t>would advertise a vector multiply that is a scalar loop in disguise. Integer arithmetic is two’s-complement wrapping — what Highway specifies and what every target ISA does — which buys a property floating point cannot offer: addition mod 2³² is associative, so an integer reduction is bit-identical across lane counts, unroll factors, backends and thread partitions. The tests assert exact equality against a closed-form reference and never mention accumulation order. Division is not offered on integer lanes, matching the position #450 took one level updot<int32_t>overint16_tuses the hardware widening multiply-accumulate (#463) —vpmaddwdon x86 (pmaddwdat SSE),SMLAL/UMLALon NEON — one instruction for the widen, the multiply and the accumulate, verified at the instruction level rather than only by value. 16-bit types are operands, not lanes:batch<int16_t>deliberately does not exist, because a 16-bit lane’s value is this accumulate. The overflow contract is the substance: products are always exact (|−2¹⁵·−2¹⁵| = 2³⁰ fits an int32), but the sum wraps soon — worst case at k = 3, ~36 for random signed data. The useful regime is small operands rather than short vectors: at b bits of operand magnitude the headroom is ~2^(31−2b) terms. This kernel may use an instruction the float one may not, becauseReorderWidenMulAccumulatepermutes which product lands in which lane and guarantees only the total — disqualifying for a floating accumulator, unobservable on integer lanesdot<int32_t>over 8-bit operands uses the quad multiply-accumulate (#464) —vpdpbusdon x86,SDOT/UDOTon NEON — four products into each 32-bit lane per instruction. Verified as codegen on icelake-server, sapphirerapids and znver4, which matters because Cascade Lake has AVX512-VNNI without Highway’s fullHWY_AVX3_DLset and so takes the decomposed path with identical results and more instructions. Eight bits is the width that matters for headroom, not lanes: halving the operand quarters the product, so the same int32 accumulator holds ~131 000 terms fori8×i8against 3 fori16×i16— four to five orders of magnitude, and the reason the quantized-inference instructions are 8-bit. Tested rather than asserted: 100 000 worst-case int8 terms sum exactly. The signedness asymmetry is handled at two levels:simd::reduce_dot_widenoffers exactly the three pairings the instruction offers and rejects(int8, uint8)at compile time naming the fix, whiledot/dot_realaccept every pairing and stay fast by swapping the operands onto the native instruction — a dot product is symmetric, so refusing one for a hardware reason would break generic code and dropping to the generic loop would cost an order of magnitude unremarked- Integer GEMM: same-type int32, and 8/16-bit operands accumulated in int32 through the blocked nest’s widening load (#468). The nest, the packing and the micro-kernel needed no changes — they were already generic over (accumulator, operand) from #176; what was missing was
batch::load_widenfor integers, which phase 0 had disabled pending the signedness convention and overflow contract that #463/#464 then supplied. The tests include one a float GEMM cannot make: the blocked nest must be bit-identical to the naive triple loop, because it reorders the k loop acrosspcblocks, partitions m across threads and accumulates in a register tile — all of which is addition mod 2³², which is associative
Benchmark integer arms, and the guard that is their substance (#465)
Section titled “Benchmark integer arms, and the guard that is their substance (#465)”--suite intruns fp64/fp32 baselines against int32, int16→int32, int8→int32 and uint8×int8→int32 fordot, and int32 forgemv, at identical sizes so the comparison lands in one CSV. The dot sweep is by footprint — 1K to 4M elements, L1 through DRAM — because a dot is a streaming reduction and two effects must be separated: at large n it is bandwidth-bound and int8 moves one byte per element against fp64’s eight, so a ~8× speedup is expected on any machine, VNNI or not, while the instruction only shows at L1-resident sizesrun_int_bench.shrefuses to time a build without the instruction it claims to measure. Nothing in a timing distinguishesvpdpbusdfrom thevpmaddwddecomposition, and having the hardware is not sufficient — Highway selects its VNNI target only on the full AVX3_DL conjunction (VNNI plus VBMI, VBMI2, BITALG, VPOPCNTDQ, VAES, VPCLMULQDQ), so an AVX-512 machine with VNNI can still compile to the slow path, and MSVC defines none of those macros, so the existing MSVC Zen 4 profile cannot produce a VNNI build.--allow-decomposedmeasures it anyway and labels the run so the CSV cannot be mistaken. Both guards were tested by firing them.build_isanow carriesAVX512VNNI,AVX3_DL,AVX10.2,DOTPRODandI8MM, since it previously recordedAVX512Fand stopped
The VNNI / SDOT GEMM micro-kernel (#469)
Section titled “The VNNI / SDOT GEMM micro-kernel (#469)”mult_quaddrives the hardware quad multiply-accumulate —vpdpbusdon x86,SDOT/UDOTon NEON — four k-values per instruction against the widening path’s one.vpdpbusdconsumes four k-values at once, so it needs a quad-interleaved pack (Ap[…][i*4+q] == A(i, 4g+q), and the same for B, with k zero-padded to a multiple of four) and a micro-kernel whose left operand is a broadcast quad rather than a broadcast scalar: a 32-bit splat of four bytes, so lane j accumulatessum_{q<4} A(i,p+q) · B(p+q,j).gemm_blockedgainsTA/TBas separate operand types —(u8,i8)is VNNI’s native shape and the two must differ — plus agemm_kerneltemplate argument; the five loops, cache blocks, thread grid, cooperative B-pack and exception handling are shared, since none of them depend on which micro-kernel runs.(i8, u8)is rejected rather than reordered: a dot product is symmetric so swapping fixes it there, but a GEMM is not, so column-major C — computed asC^T = B^T A^T— cannot take the asymmetric pairing and falls to the generic loop- The kernel selection is an explicit template argument, not inferred from the element types. It was inferred at first, and since
(i8,i8)is valid input to both kernels that silently reroutedmult’s widening path — through a completely green test suite, because the two kernels agree bit for bit and no result can tell them apart. The benchmark caught it: the two int8 arms began reporting the same number to three digits, so the arm meant to be the control had stopped being one.gemm_kernel::wideningis the default,multis unchanged, and a structural test pins the default since a result-based one provably cannot has_native_quad_dot_v<NA, NB>reports quad support per operand pairing, because the hardware is per pairing and the two ISAs implement opposite ones first: x86 getsu8×i8at AVX3_DL and the symmetric pairings only at AVX10.2; ARM getsi8×i8/u8×u8with FEAT_DotProd andu8×i8only with I8MM. A single flag mislabelled at least one arm on every machine measured, and a cross-machine comparison that pairs arms by name gets the sign of the effect wrong — the fastest arm inverts between Zen 4 and a Cortex-A78.quad_dot_native_supportsummarises asnone/partial/all, andpartialis what every machine measured so far reports.has_native_quad_dotkeeps its original any-pairing meaning so no committed sidecar changes meaning. The gates now use Highway’s own conditions (HWY_TARGET <= HWY_AVX3_DLis literally the gate inx86_128-inl.h) rather than a hand-reconstructed seven-macro AVX-512 conjunction- Committed int-suite run profiles for all four machines (
benchmarks/machines/*-int.sh), so the arch flag, pin list, output directory and--allow-decomposeddecision live in the repository. The two decomposed profiles assert--allow-decomposedon the operator’s behalf — on those parts the decomposition is the measurement — while the two native ones deliberately do not, so a build that misses its ISA stops. The Xeon pins0,1,2,3,4,5where every other profile pins0,2,4,…: its SMT siblings are blocked(0,6), not adjacent pairs verify_gemm_intchecks every integer GEMM arm against a 64-bit reference, outside the timed region, and fails the run rather than warning.measureonly invokes the lambda and records elapsed time, so before this no GEMM arm ever read its output: a kernel returning nonsense produced a well-formed CSV row, and an unread output is also the shape of work a compiler may delete
Changed
Section titled “Changed”- The integer-lane results are recorded in the living assessment, and the i7 corrected them (#467). On a Zen 4 with native
vpdpbusd,dotwithuint8 × int8reaches 26× over fp64 at n = 4M — almost all of it bytes, one per element against fp64’s eight. The instruction’s share looked like 1.42× from that machine alone (nativeu8×i8against emulatedi8×i8, same run), but those two arms also take different decompositions: on the i7, where both are decomposed, the same pair still differs by 1.17×, putting the instruction at ~1.2× net. Nothing in the Zen 4 data could have exposed it, and the claim stood for a day before the control arrived. The i7 also retires the 2013 Xeon as the bandwidth control — reaching 15.4× at n = 4M without a usable VNNI instruction is the clearest statement of the finding. §7 records the capability fact behind that: the i7 has AVX-VNNI silicon and MTL5 cannot reach it, because Highway implements the quad accumulate only in its AVX3_DL target, gated on AVX-512 macros Alder Lake does not have. Adds the hardware expansion plan — nine candidates written as experiments rather than a shopping list - The int8 GEMM claims are now measured on four machines, and the single-machine ones did not survive (#470). #469 concluded from the Xeon alone that the quad kernel is worth “~1.25×” and that a VNNI purchase would be “buying something we already have”. Both were wrong. The kernel effect ranges 1.27×–3.64× — the Xeon is the low outlier by about a factor of three — and only the machines with the instruction beat fp32 by a margin worth having: the two decomposed parts land at 1.01× and 1.09× — beside fp32, not below it — while the two native parts reach 2.20× and 3.29×. The
native ÷ emulatedratio is a raw pairing ratio, not the instruction’s contribution: the pairings differ in signedness and decomposition path too, and netting the shape control (1.28× Xeon, 1.10× i7, measured where both pairings are emulated) puts Zen 4 at 1.74–2.02× and the Jetson at 2.64–3.06×, the control acting in opposite directions because the machines implement opposite pairings. Against ~1.2× for the same instruction on a dot, this is the prediction the hardware plan made in direction and could not size — a dot is bandwidth-bound so instruction efficiency barely shows, a GEMM is compute-bound and shows it fully. Thebest int8 ÷ fp32column carries no pairing confound, comparing each machine’s fastest int8 arm against its own fp32 GEMM, and is the one to quote when justifying hardware - The within-machine control for the instruction already existed. The hardware plan said measuring it alone needs an AVX10.2 part or a Highway AVX-VNNI path, since forcing a decomposed Zen 4 build also drops AVX-512. Partial support is the control: native and emulated arms run in the same binary, on the same machine, in the same run. It is a control and not a clean one — the decomposition-path residue remains, which the fully-decomposed machines measure directly — so an ARM part that emulates both pairings is now worth as much as an AVX10.2 one
Performance
Section titled “Performance”mcis bounded at runtime by the strip of C the ic block accumulates into (#457, #459). The L2 model sizesmcso the packed A block fills half of L2 and counts nothing else, while the same cache simultaneously holds that C strip. The obvious repair — adding the C term to the compile-time model — is falsified by its own calibration point rather than by a measurement: with n unknown there the strip must bemc × nc, and reproducing the shippedmc = 64then needsmc·(kc+nc)·sizeof ≤ 8.5·L2, which is not a residency statement, and thenr = 4family needs 2.5 rather than 8.5. What survives is the same idea in the right place — the strip ismc × min(n, nc)and n is known at the call, which is already wheremcis capped for the thread budget- A is not charged against that budget, and the measurement decided it (#459). Charging A+C fires whenever the pair exceeds L2, but on a Xeon E5-2420 (3 arms × 6 rounds, one session, with
mconlyholding as a null control) every win was a shape where C alone exceeded L2 (2048², 4096²: 1.151×, 1.158×) and every loss was a shape where C already fitted and the bound shrankmcfor nothing (1024², 96×4096: 0.854×, 0.832×). A is streamed into the packed buffer and consumed once per jc block; C is read-modify-written across the whole kc loop and is the operand that has to stay resident. Shipped off, as theccap/ccap2benchmark arms, so the bound is measured before it is adopted; #453 is falsified and #458 opened - The A/B analyzer was hiding a 15% effect and blaming the machine for it (#459). It decided two arms were “identical” from their configured
kc/mc, which are the same for all three arms on that machine — so it reported “null (identical blocking)” and raised an integrity failure against the same points. Identity now means the arms ran the same plan (mc_used,ic_nt,jc_ntper point, from #448), which is what it always meant to say; CSVs predatingmc_usedfall back to the old comparison, and every known case was re-verified
- A GCC 13 miscompile on AVX2 integer reductions (#460). The four interleaved accumulator chains are legal to reassociate on integers, and GCC 13 fuses them into one contiguous reduction while advancing three of them at half the required stride — silently wrong for 176 of the first 299 compile-time-constant lengths,
int32/uint32only, Clang unaffected. Caught by CI’s FP-contract lane; the emitted assembly accounts for the wrong value bit for bit. Integer reductions now run one accumulator, which is the right shape for them anyway — the loop-carried dependency is a 1-cycle add, so there is no latency to hide — and the floating-point path is byte-identical, verified - Strided vectors reached the contiguous fast paths (#460).
strided_vector_refsuppliesdata()andsize(), which is allBlasDenseVectorasked for, so ten operations accepted it and walkeddata()with unit stride:dot_realover a stride-2 view returned 14 where the answer is 44. This affectedfloatanddouble, predates the integer work, and a column of a row-major matrix is exactly such a view - Integer overflow was undefined behaviour in the generic dense loops (#460) — the path an integer
multtakes in the default build, sinceMTL5_NATIVE_FAST_GEMMis off. The wrapping helpers were also not performed wide enough to be defined: integral promotion sends anything narrower thanintto signedint, souint16operands overflowed it, reachable asdot_realover adense_vector<int16_t> - Shell scripts checked out with CRLF on Windows and could not run under WSL (#466). There was no
.gitattributesat all, which CLAUDE.md’s cross-platform rules already required, so all fifteen tracked shell scripts were affected —preflight.sh, everyrun_*harness and every machine profile — meaning no part of the benchmark contract could be executed from a Windows checkout.*.sh/*.bashare pinned toeol=lf;*.ps1/*.bat/*.cmdkeep CRLF since they only run on Windows;.mtx/.csvare pinned explicitly because the IO tests compare fixtures byte for byte. Repository content is unchanged (git add --renormalize .stages nothing) — only checkout behaviour, which is the whole defect - Undefined behaviour in the quad pack (#469). Both pack routines hoisted a source pointer out of the padding guard, forming
A + (i0+i)·rsfor rows past the end of the source. The value is never loaded, but forming the pointer is already undefined. Neither sanitizer catches this — ASan sees no bad load because there is none, and UBSan’spointer-overflowcheck tests wraparound rather than escape from the object — so UBSan runs were clean before and after; it was found by reading mult_quad’s documented generic fallback was a hard compile error for anyMatrixwithout anorientationalias (#469).interface::is_row_major_v<MC>was named at function scope, outside any discarded branch, and the concept does not require that alias —compressed2Dandtransposed_viewboth lack it — so the path that existed to keep the function “always correct, never merely fast” could not be reached by the types it existed for
[5.10.0] - 2026-08-17
Section titled “[5.10.0] - 2026-08-17”A benchmarking-infrastructure release, and the experiment it was built to run. Two breaking changes, both narrow; see Breaking below before upgrading.
Breaking
Section titled “Breaking”Field<T>is now false for integralT, and the factorizations require it (#450).lu_factor(dense2D<int>)used to compile and return a truncated factorization — right shape, right type, wrong numbers, no diagnostic.Fieldasked only thata / bcompile and yield aT, whichintsatisfies, so every algorithm meaning “I will divide and expect the quotient back” accepted a type that cannot give it one. ℤ is a ring, not a field: only 1 and −1 have inverses.Fieldnow excludesstd::is_integraltypes, the newFieldMatrixapplies it, and the 25 entry points that divide — LU, QR, LQ, Cholesky (real + Hermitian), LDLᵀ incl. Bunch-Kaufman, SVD, eigen (general + symmetric),inv, factor and solve alike — require it. Integers keepScalar, which is the honest statement: they add and multiply, so dot/gemv/gemm remain open to them (a ring is all those need). Custom number types are unaffected — posit, LNS, fixpnt and rationals are notis_integral. What breaks downstream:vec<int> / 2and integer matrix/scalar division, deliberately, since truncating division is the same hazard one level down- Runtime cache detection is opt-in and off by default (#433). Introduced in #426 on the assumption that real cache sizes must beat constants tuned for a Haswell-class core, it lost on every machine measured. Enable with
MTL5_ENABLE_CACHE_DETECTIONif you want to evaluate it on your own hardware; the shipped blocking is byte-identical to pre-#426
A measurement contract for every benchmark (#442)
Section titled “A measurement contract for every benchmark (#442)”Each guard below was added after the matching error had already produced a number someone believed — a Zen 4 run that deleted the i7’s committed CSVs, an analyzer that called a 4.8% “win” between byte-identical arms, a Jetson that asked for eight threads on a six-core part. The contract is the first layer written before the error rather than after it.
benchmarks/preflight.sh/.ps1(#444) — runs before any measurement and fails, not warns, on a dirty working tree, a competing build or benchmark, or a thread count above the available cpus. Emitskey=valuemachine state either way, so it lands in the sidecar rather than in the operator’s memory of the session. The thermal gate fails only where a sensor and a limit are both readable — Windows desktop firmware usually implements neither, and refusing to run there would make the machine unbenchmarkable while passing silently would hide the gap; it recordsunavailableout loud. Governor is recorded and warned about, never failed: every machine insystems.mdruns a non-performance governor, and a hard gate would block all of them- Build provenance in every sidecar (#443) —
git_commit,git_dirty,cxx_flags,cmake_type, regenerated at build time rather than configure time, so a sidecar cannot name a commit it was not built from. Plusbuild_isa(mtl::util::build_isa_list), read from the compiler’s own predefined macros:cxx_flagsis the build’s intent and can omit the flag that mattered (MTL5_NATIVE_ARCHadds-march=nativethroughtarget_compile_optionsand appears in noCMAKE_CXX_FLAGSvariable), whilebuild_isais the effect. This is what finally answered whether a Zen 4 session had been AVX-512 or AVX2 - The plan the GEMM nest actually runs (#448) —
detail::gemm_plan_for<T>()returnsmc,nib,njb,ic_nt,jc_nt,budget, andgemm_blockednow uses it rather than recomputing the same three steps inline. Benchmarks recordmc_usedper point, so the parameter under test is in the record of the experiment testing it: three stages separate the configuredmcfrom the one the loops step by, and the CSVs previously reported the first - Four selectable A/B arms (#449) —
default,detected(L1+L2),kconly(L1 → kc),mconly(L2 → mc), all the same source, run in one session with the order rotated per round.with_detected_cachestakes the levels as an argument rather than reading macros, so every combination is unit-testable without recompiling - Per-machine run profiles (
benchmarks/machines/) — the pin list, thread counts, ISA flag and output directory for the i7-12700K, Jetson Orin Nano and Ryzen 9 8945HS, committed instead of retyped. Each refuses to run on a machine it does not recognise, since the CSVs are named by arm and the runner clears them before writing. The Jetson’s output directory follows itsnvpmodelpower mode, because a 15 W run and a MAXN run are not comparable and one directory is how they would end up averaged mtl::util::build_isa_list()(util/system_info.hpp) — the ISA the binary was compiled for, distinct fromcpu_simd(what the machine supports). Emitted asbuild_isa=in every sidecar- The integer accumulation envelope, measured (
tests/unit/simd/test_int_accumulation.cpp) — how deep an integer dot product can go before anint64accumulator overflows, as a contract test rather than a rule of thumb. ≤16-bit operands are safe past a million terms in both the zero-mean and the offset regime; only full-range operands genuinely fail. Portable by construction: a product of twoint32always fits anint64, so only the running sum can overflow and checked addition detects it without__int128
- The GEMM thread grid is planned, not greedily filled (#441).
ic_ntwas taken asmin(budget, nib)andjc_ntas the integer quotient, which throws the remainder away: at budget 6 withnib = 4that is 4×1 = 4 of 6 threads, and withnjb = 1(square problems) nojcparallelism compensates.plan_gemm_gridsearches the legal factorizations and also capsmcso the ic partition can fill the machine. Measured: i7 1024³ at 8 threads 0.551 → 0.707, Zen 4 0.590 → 0.928, Jetson 0.760 → 0.938 relative to the shipped blocking - Cache detection is deterministic and shared-cache aware (#436) — per-core budgets divide by the number of cores sharing a level, and SMT siblings no longer halve L1d/L2
- Preflight no longer fails on the harness’s own output (#447) — the PowerShell driver builds before it measures and wrote its cmake logs beside the CSVs, so the run tripped over files it had just produced. Logs are gitignored, the dirty check excludes the harness’s own
OUTDIR(contained tobenchmarks/data/<machine>so it cannot become a hole through the gate), and-AllowDirtyexists becauseset ALLOW_DIRTY=1is cmd.exe syntax that silently does nothing in PowerShell - A per-machine
OUTDIRis required, with no default (#439) — the CSVs are named by arm and the runners delete them before writing, so a shared default destroys another machine’s committed results. Which is exactly what happened once - The effective thread pool is recorded (#440) —
thread_poolclampsMTL5_NUM_THREADStohardware_concurrency, so a request of 8 on a 6-core part measured 6 while the CSV said 8; thepoolcolumn records what ran CMakePresets.jsonlowered to schema v3 so CMake 3.22 can read it (#435)- A wall-clock ratio no longer gates every PR (#454).
sparse_test_native_kluassertedtime_ratio < 13.0on a ratio of two single timings, in the fast tier, on shared cloud runners — it failed on macOS on a PR that changed no C++ at all (14.997), and sampled three times on an idle machine the statistic itself moved 31% (5.24, 5.91, 6.87). Nothing algorithmic was lost by removing it, because the same test already assertsfill_ratio < 8.0, and fill is the deterministic observable of the same property: a sparse factorization’s asymptotic cost is driven by fill growth, and the clock measures fill plus noise. The timing claim moves totests/regression/sparse/test_klu_scaling.cppin a stricter form — minimum of 3 samples per size, both refinement steps checked rather than only the last, and a floor requiring the baseline to exceed 1 ms so the ratio cannot degenerate into a timer-resolution artefact. The unit test drops from 10.19 s to 1.49 s.regression_itl_test_gmresalso gets the 600 s timeoutcgandbicgstabalready had: at 8m06s on a Xeon E5-2420 v2 it timed out at the 300 s default, making the regression tier unrunnable locally on any machine slower than a CI runner
Performance
Section titled “Performance”run_scalingandrun_sweepsbuild every variant before measuring any of them (#445) — each backend used to be built and then immediately measured, so every arm was timed on a machine still hot from compiling its own binary while the next compiled during the previous one’s cooldown. MKL’ssetvars.shis now sourced in a subshell for both configure and run, so oneAPI’sLD_LIBRARY_PATHcannot leave the openblas and blis binaries resolving MKL’s libraries while still labelled as themselves
Changed
Section titled “Changed”- Performance studies are a top-level documentation section (
docs/performance/), lifted out of Design: they answer “what did the machine do”, not “how is it built” - Cache blocking A/B — the four-machine experiment written up with its hypothesis, exact sign and permutation tests, identical-binary calibration and verdict. The headline: raising
mcis the harm and it is visible with one thread; raisingkcis free serially. The earlier conclusion, which had it backwards, is corrected in place. Neither parameter is ever a win, which is why detection ships off - The analyzer fails identical-parameter arms that disagree systematically — arms sometimes collapse onto each other (on Zen 4
kconlyisdefault), and those pairs measure the session rather than the code. It disqualified a Jetson session whose round-to-round spread was larger than the effect under test ROUNDSis rounded up to a multiple of the arm count, so the rotation balances exactly
[5.9.1] - 2026-08-13
Section titled “[5.9.1] - 2026-08-13”Performance
Section titled “Performance”- Sparse LU refactor 23% faster via
sparse_lu_refactor_in_place/supernodal_lu_refactor_in_place(#310). The reported defect was real:*_refactorinstalled throughset_factor, which unconditionally rebuilds both level-solve schedules, even though a same-pattern refactor leavescol_ptr/row_indbyte-identical and the schedules are value-agnostic — they cache positions into the factor’s value arrays, not the values. But fixing exactly that measured ~2%. The value-returning API copiesprev, and copying the schedules (twonnz-lengthsize_tarrays each) costs about what rebuilding them costs, so removing the rebuild moved the O(nnz) work rather than removing it. The win needed the copy gone too: the in-place entry points replay the values on the installed pattern and install them without copying pattern, schedules, or permutations. Measured on a 6400-DOF 5-point grid (nnz(L)+nnz(U)= 390K, GCC -O2, min of 5 runs): 26.3 → 20.3 ms/refactor, with markedly lower run-to-run variance since no large allocation remains on the path.sparse_lu_refactor/supernodal_lu_refactorkeep their signatures as “copyprev, refactor in place”, andnative_klu_refactorinherits the change through its per-block callset_factor_values(lu_numeric,supernodal_lu_factor) is the validated value-only install: it requires a factor already installed and re-checks the value counts against both the installednnzand the schedules’built_nnzstaleness guards — the same guards the solves assert on — so a pattern change cannot slip through silently.set_factorremains the entry point for that. The install is ordered first in both refactor paths because every member update after it is noexcept, which gives the whole operation a strong guarantee: values are computed into scratch arrays and installed only after the last column succeeds, so a zero pivot leaves the factorization untouched and still solvable with its previous values (asserted, not assumed)
- Wide/short dense-matrix expressions now parallelize at all (#313). The
dense2Dexpression sweeps (ctor /=/+=/-=) made each row oneparallel_ewisework unit, andthread_pool::parallel_forruns serially whenn < grain*2— so a1 x 300000assignment hadn == 1and could never split, however much work the row held. Same wide-shape gap #311 closed for GEMM.detail::parallel_ewise_2dflattens(r, c)to a linear element index[0, rows*cols)before chunking, so the split follows the element count and1 x Nparallelizes exactly likeN x 1. Two things worth stating because the obvious implementation gets them wrong: each chunk walks(r, c)incrementally from a single division at its start, so the per-element cost is an increment and a compare rather than thet / cols,t % colsa per-element decomposition would pay; andwork_per_elem = 1yieldsgrain = 65536elements, exactly the chunk size the row form’s65536 / num_colsrows produced, so tall matrices see identical splitting behaviour and only the boundary alignment changes (row-aligned → element-aligned), which element-wise results cannot observe. Bit-identity holds by construction — row-major visit order is unchanged, each element is produced by exactly one chunk, and the per-element computation is thread-independent — and is asserted with==on wide shapes through all four sweeps. The split itself is observed rather than inferred: a probe expression records which thread evaluated each element, an assertion that fails on the row-per-unit sweep (1 > 1). TSan clean atMTL5_NUM_THREADS=4. The second half of #313 — the ~K× too-coarse grain for the opt-in lazymat_mat_times_expr, whoseoperator()(r,c)is a length-K inner product — is split out to #424, since it needs a public per-element work-hint trait
[5.9.0] - 2026-08-07
Section titled “[5.9.0] - 2026-08-07”Complex (Hermitian) dense factorizations (#353)
Section titled “Complex (Hermitian) dense factorizations (#353)”cholesky, qr and lq did not compile for std::complex, failing first on relational operators applied to a complex where a magnitude was meant. Repairing only those comparisons would have produced routines that compile and compute the wrong result, by a different mechanism in each: cholesky’s unconjugated inner product yields L·Lᵀ rather than the L·Lᴴ a Hermitian matrix has, while qr/lq additionally need Σ|z|² in place of Σz² and a reflector written I − τ·v·vᴴ rather than I − β·v·vᵀ. Neither fix repairs a comparison.
mtl::cholesky_h_factor/mtl::cholesky_h_solve(operation/cholesky.hpp) —A = L·Lᴴfor Hermitian positive definite input. The pivot is accumulated in the magnitude type rather than the element type, which is what makes the positivity test well-formed: an ordering is exactly what the element type lacks. Rejects a non-real diagonal withCHOLESKY_NOT_HERMITIAN.cholesky_factoris now restricted to real element types with a diagnostic naming the alternative — unlikeldltthere is no complex-symmetric variant to offer, since “positive definite” is a statement about an ordering (#360)- Complex Householder, QR and LQ (
operation/householder.hpp,qr.hpp,lq.hpp) — the reflector is nowH = I − τ·v·vᴴwithH·x = β·e₁and β real, built as in LAPACKzlarfg.His unitary but not Hermitian for complex τ, soH⁻¹ = Hᴴ; that lands asconj(tau)inqr_extract_Q, plaintauinlq_extract_Q, and a conjugated row plusHᴴon the LQ factor side. Verified‖QᴴQ−I‖ ≤ 7.8e-16and‖QR−A‖ ≤ 7.0e-16over square, tall and wide shapes (#361) hessenberg_factorandeigen_symmetricnow reject complex element types. They applyH·A·H, a similarity transform only because a real reflector is Hermitian and involutory; makinghouseholder()complex-capable would otherwise have let them compute a non-similar matrix. The Hermitian reduction is tracked in #362 (#361)
Hermitian eigenproblem — unitary reduction (#362)
Section titled “Hermitian eigenproblem — unitary reduction (#362)”The guards above are lifted. hessenberg_factor/hessenberg/tridiagonalize, eigenvalue_symmetric(_generic) and eigen_symmetric now accept complex element types via the unitary reduction A → H·A·Hᴴ — the right factor passes conj(τ) to apply_householder_right (the same adjoint bookkeeping #361 worked out for qr_extract_Q), a genuine similarity since H⁻¹ = Hᴴ. For a real element type conj is the identity, so every real path stays bit-identical: the QR-iteration scalars are typed magnitude_t<value_type> (which is value_type there), and eigenvalues come back as that magnitude type (real for Hermitian).
- The phase, and where it is actually exercised. A Hermitian tridiagonal has a real diagonal but phased subdiagonals; making them real is a diagonal unitary similarity
Dᴴ·T·Dthat preserves the spectrum, soeigenvalue_symmetricneeds only|T(i+1,i)|whileeigen_symmetricfoldsDinto the eigenvectors soA·v == λ·v(skip it and the eigenvalues still look right — the silent-wrong shape #352/#353 kept hitting). But MTL5’shouseholder()reflects to a real β, so forn ≥ 3the reduction yields real subdiagonals for free and the fold is a no-op ±1; the phase is genuinely complex only when the reduction is skipped (n < 3), whereT(1,0)is the original off-diagonal. The2×2tests ([[2,i],[-i,2]], and an off-axis[[1,1+i],[1-i,2]]) are therefore the cases that pin the fold — drop it and their eigenvectors come back real and fail the residual - The #361 guard had been covering nothing. It sat on
eigenvalue_symmetric_generic, which never callshouseholder; the compile-failure test matched its regex and passed while the actual reduction site,eigen_symmetric, stayed open. The two compile-failure pins are retired and the reduction site is what the new tests exercise. Invariants asserted self-consistently (no LAPACK dependency): real eigenvalues,A·v == λ·vper pair,Qᴴ·Q == I, and the reconstructionV·diag(λ)·Vᴴ == A— the check that catches a non-similar reduction, which a merely-unitaryQdoes not (#361’s lesson).eigenvalue_symmetric_genericalso gained a0×0guard before itse(n-1)sentinel write
LAPACK Hermitian eigensolver + native cross-validation (#415)
Section titled “LAPACK Hermitian eigensolver + native cross-validation (#415)”cheev/zheevbindings (interface/lapack.hpp) and aBlasHermitianMatrixconcept (interface/dispatch_traits.hpp);eigenvalue_symmetricroutes a complex Hermitian matrix toheevunderMTL5_HAS_LAPACK, mirroring the realsyevpath. EigenvaluesWare real,heevtakes an extra realrworkof lengthmax(1, 3n−2), and the optimallworkreturns in the real part of the query’swork[0]- This gives the native complex reduction a reference oracle. The self-consistent #414 invariants catch a phase bug but not an algorithm that is self-consistently wrong;
test_lapack_dispatchnow cross-checkseigenvalue_symmetric_generic(native) againstzheevand they agree to1e-9on known, degenerate ({2,2,2,10}from2I + v·vᴴ), and dense spectra
LAPACK dispatch for the default (row-major) matrix type (#417)
Section titled “LAPACK dispatch for the default (row-major) matrix type (#417)”dense2D defaults to tag::row_major, and every LAPACK factorization/eigensolver dispatch guarded on !is_row_major_v<M> — so the default matrix type never took the accelerated path, and the pre-existing real syev/geev “dispatch” tests were silently running the generic path. Invisible because both paths return correct answers; the only decisive check is a symbol assertion — a row-major-only translation unit referenced no LAPACK symbols before and dsyev_/zheev_/dgeev_/dgesdd_ (+ dgetrf_/dgeqrf_/dpotrf_) after.
- Category A — the guard was redundant (#418).
eigenvalue_symmetric(syev+heev),eigenvalue(geev) andsvd(gesdd) already build a column-major copy through the(i,j)accessor, so they are correct for either orientation; dropping!is_row_major_v<M>enables LAPACK for the default type at zero correctness risk - Category B — the guard was load-bearing (#419).
lu/qr/choleskypass the rawA.data()buffer to Fortran, where a row-major buffer is the transpose of what LAPACK reads. Row-major now factors through a column-major scratch (copy in via(i,j), LAPACK in place, copy the factor back via(i,j)), so the accessor-based solves read it unchanged.cholesky_h_factordelegates tocholesky_factorfor real BLAS types —L·LᴴisL·Lᵀthere — which keeps the two entry points bit-identical (an invarianttest_cholesky.cpppins with==, which independent factoring would break oncecholesky_factorusespotrf). A zero-dimension guard was added to all three (LAPACK rejectslda == 0) - The
#297determinism tests move to a non-BLAS type. They assert the threaded factorization is bit-identical to a serial generic reference — a property of theparallel_forkernel, not of LAPACK. Since the defaultdoublepath now dispatches to LAPACK (a different algorithm), the LU/Cholesky determinism cases switch tolong double(neveris_blas_scalar), sodense2D<det_t>keeps exercising the generic parallel path in LAPACK and non-LAPACK builds alike; theapply_householder_*cases staydouble, since those kernels never dispatch
Sparse × sparse product (SpGEMM)
Section titled “Sparse × sparse product (SpGEMM)”mtl::spgemm(A, B)(operation/spgemm.hpp) — Gustavson’s row-by-row algorithm over the existing sparse accumulator (sparse/util/scatter.hpp, CSparse’scs_scatter), so work is proportional to the multiply-adds actually performed rather thann³.compressed2D * compressed2Dpreviously fell through to the generic denseoperator*, which both materialised ann × ndense intermediate at the fine-grid size and reached every element throughcompressed2D::operator()(r, c)— itself a binary search. The Galerkin triple productA_coarse = R·A·P, the one product a multigrid user most needs to stay sparse, was the one that did not.operator*on twocompressed2Dnow returnscompressed2D; verified before the change that no call site multiplied two sparse matrices, so nothing relied on the dense result. Single pass, no separate symbolic phase — that buys exact sizing and a reusable pattern only when the same structure is multiplied repeatedly, and multigrid setup builds each level once. Entries that cancel to exactly zero are kept, so a Galerkin hierarchy’s pattern is stable across re-assembly (#402)- The gathered indices are sorted before being written, because
compressed2D::operator()usesstd::lower_boundand ascending column indices are therefore a correctness invariant rather than a convention. Worth stating how invisible skipping it would be: measured with the sort removed,nnzis correct, row sums off the raw CSR arrays are correct to 4.4e-16, and a sparse matvec is correct to rounding — it sumsdata[k]*x(indices[k])over whatever order the row is in, and reordering preserves the set of products, so the sum is still right (not bit-identical, since floating-point addition is not associative, but wrong at eps rather than at all) — while element access is wrong by 3.2 absolute. The natural tests for a matrix product all pass on the corrupt result, sotest_spgemm.cppasserts the index structure directly instead of trusting a residual (#402)
Compile-failure test harness
Section titled “Compile-failure test harness”tests/unit/compile_fail/— sources that must not compile, built on demand by ctest (EXCLUDE_FROM_ALL) so ordinary builds are unaffected. Each declares an// EXPECT-ERROR: <regex>line and is matched withPASS_REGULAR_EXPRESSIONrather than CMake’sWILL_FAIL, which passes on any non-zero build exit and would go green on a typo in the test source. The distinction is not theoretical: removing thecholeskyguard leaves the file still failing to compile via the oldoperator<=error, soWILL_FAILwould have been green while the regex catches the regression to the worse diagnostic (#358)
Platform Performance Engineering lab
Section titled “Platform Performance Engineering lab”ppe/— a progression of GEMM implementations (naive → loop order → blocking/packing → register tiling → compile-time microtile) measured acrossint8/16/32/64andfp16/32/64, with hypotheses recorded before the experiments that test them. Documents the vectorization cliff: the compile-time-unrolled microtile is 5× slower than a plain loop reorder forfp32, because full unrolling removes the loop structure the vectorizer needs and 32 scalar accumulators then spill — while being the best kernel forint32, whose SIMD headroom is small (#354)
Preconditioned Krylov solvers: three defects behind one blind spot
Section titled “Preconditioned Krylov solvers: three defects behind one blind spot”All three were invisible to the existing tests for the same structural reason: every preconditioned bicg/qmr case used pc::identity, the one preconditioner for which applying M⁻¹ twice, or on the wrong side, or with the wrong adjoint, is indistinguishable from applying it once correctly. tests/unit/itl/test_preconditioner_adjoint.cpp now asserts the defining property — ⟨M⁻¹b, c⟩ == ⟨b, M⁻ᴴc⟩ — which is exact, cheap, and found two defects the reporting issue had not identified.
bicgcomputedrhofromz̃ᵀzinstead ofzᵀr̃, i.e. from two preconditioned vectors rather than one preconditioned and one raw. With a non-trivial preconditioner it converged to the wrong scaling or not at all; withpc::diagonalon a 144×144 SPD Laplacian it hit the 3000-iteration cap wherecgtook 33. Preconditioned BiCG reduces exactly to preconditioned CG when bothAandMare SPD — the symmetry of the preconditioner is a separate requirement from that of the system, and is what makes the reduction hold — so the fix is asserted that way againstpc::diagonal, which is symmetric whateverAis: same iteration count, not merely convergence (#392)qmrapplied the preconditioner twice, once on each side, rather than the Freund–Nachtigal splitM = M₁·M₂withM₁ = M,M₂ = I. The algorithm needsw̃ᵀM⁻¹ṽ; the old code producedM⁻¹on both the shadow and the primary vector. Fixed at the update sites, withqbuilt fromz̃. QMR minimizes a quasi-residual so it does not reduce exactly to CG; the test asserts it tracks within two iterations rather than pinning a coincidence of stopping criteria (#393)pc::ilu_0andpc::block_diagonalhadadjoint_solvestubs that delegated tosolve, which is correct only whenMis self-adjoint.M = L·Uis not, and a diagonal block of a non-symmetricAis not either, sobicg/qmrapplied the wrong operator outright and did not converge at all.ilu_0now doesU⁻ᴴthenL⁻ᴴin scatter form over the existing row storage;block_diagonalroutes each block through the new publicmtl::lu_adjoint_solve(operation/lu.hpp), which appliesUᴴforward,Lᴴbackward, and the inverse permutation as the same interchanges in reverse.ic_0andildlwere checked and are correct by construction —L·LᴴandL·D·Lᵀare self-adjoint — so delegation there is right rather than lucky (#394)
itl/mg/multigrid.hppwas not self-contained. It usedmat::operators.hppwithout including it and compiled only because every existing consumer happened to include it first —test_multigrid.cppsupplied it at line 7 of a 16-line include list. A new translation unit including onlymultigrid.hppfailed. Added the include, plustest_multigrid_self_contained.cpp, whose include list is load-bearing and labelled as such so it is not “tidied” later (#401)fast_gemm’s numeric test compared against along doublereference, which is 80-bit on x86-64, 64-bit on Apple ARM64 and MSVC, and 128-bit on ARM64 Linux — so the assertions inverted by platform. Replaced with a portable double-double reference (Knuth two-sum + exact two-product via FMA, ~106 bits). The tolerance is now stated as empirical rather than derived:4·k·epsis not a tightening of ak·epsworst case, it is 4× wider, and the true worst-case relative error against the test’s(|ref|+1)denominator is nearerk^1.5·u(#386)pc::ssorapplied the wrong operator, because its sweeps started fromx = binstead ofx = 0. A stationary iteration and a preconditioner are the same splitting matrixMviewed two ways, and applyingM⁻¹means running one sweep from zero; from any other start the result isM⁻¹b + G·x₀withG = I − M⁻¹A— fine for a solver, where the initial guess is arbitrary, wrong for a preconditioner. Run from zero the two sweeps are exactly the classical operatorM = ω/(2−ω)·(D/ω + L)·D⁻¹·(D/ω + U)(Sheldon 1955), scalar factor included, so sweeps and triangular solves are the same operator rather than two competing formulations — now asserted against a dense LU ofMat two ω. For HermitianAthat isc·X·D⁻¹·Xᴴ, self-adjoint by construction, which is why the symmetric variant exists at all; the adjoint identity violation goes from 1.1e-01 to 3.4e-16 andadjoint_solve’s delegation tosolvebecomes correct rather than a stub. On a symmetric 144×144 Laplacian every solver improves: cg 16 → 13 iterations, gmres 13 → 12, bicg 16 → 13, qmr 16 → 13. SSOR of a non-HermitianAremains non-self-adjoint (2.6e-01) — a property of the method, now asserted so it is not mistaken for a residual bug. The one configuration that gets worse iscg+ssoron a non-symmetricA(45 iterations → does not converge), which is outside CG’s domain in the first place: its former convergence rested on the extraG_B·G_Fterm, not on the preconditioner (#398, #394)ldltreturned a wrong answer for Hermitian complex input underinfo == 0. Addedldlt_h_factor/ldlt_h_solveforA = L·D·Lᴴ, and guards in both directions:LDLT_NOT_SYMMETRICwhen Hermitian input reaches the LDLᵀ form,LDLT_NOT_HERMITIANwhen a non-real diagonal reaches the LDLᴴ form. Both tests are scale-relative (n · eps · scale, via LAPACK’sCABS1to avoid an O(n²) sweep ofhypot), because an exact test only catches matrices that are bit-exactly Hermitian — a one-ULP perturbation slipped past the first version and produced an answer wrong in the first significant digit. Shared thresholds live indetail/structure_tol.hpp(#352, #356)compressed2Dacceptedtag::col_majorand ignored it. The container is CSR unconditionally, so acol_majorinstance was byte-for-byte a CSR matrix and genuine CSC input came back as its transpose while the constructor reported success. Now rejected at compile time;ell_matrixcarried the same inert-orientation hole and is rejected too.coordinate2Dis deliberately untouched — it stores explicit(row, col, value)triplets, so orientation cannot change a result (#355, #358)householderbroke its own real-β guarantee for a complex vector with a vanishing tail and a complex leading entry, returningtau = 0and leaving a complexR/Ldiagonal — silent, sinceQstayed unitary andQ·Rstill reproducedA. The identity shortcut is now taken only when it is exact (#361)
Performance
Section titled “Performance”- Multi-core GEMM +27% at N=1024 and +10% at N=2048 on 8 P-cores, recovering the scaling regression #382 introduced (#408). The cause was not cache pressure from the larger register tile, as first supposed, but that
mcwas rounded down to a multiple ofmr— coupling a cache quantity to the register tile. The L2 budget yields exactly 64, which survivesmr=4but drops to 60 under #382’smr=6; that moved the ic-block count at m=1024 from 16 (exactly 2.00 blocks per thread on 8 threads) to 18 (2.25), and since the threaded nest hands ic-blocks out round-robin, the most-loaded thread went from 128 rows to 180 — a 1.41× critical path that turned a +21.5% single-thread win into a −7.4% eight-thread regression.mcnow derives from the cache alone, anddetail::balanced_mcchooses the block size againstmand the thread count at runtime, where both are known; the serial path still rounds to wholemr-panels, since with nothing to balance that is strictly better. Measured interleaved against the same session’s baseline, three reps, ranges non-overlapping: parallel efficiency 62.7% → 81.8% at N=1024 and 77.5% → 85.8% at N=2048, with T=1 unchanged (−2.5%/−0.4%, overlapping ranges). The multiple-of-mrconstraint was never a correctness requirement —pack_Aalready handles a ragged final panel, sincemis not generally a multiple ofmr - Blocked GEMM parallel efficiency 79% → 91% on 8 physical cores. The shared B panel was packed by each jc-team’s leader while the rest of the team waited on the barrier — a serial region proportional to
kc·ncperpcstep (at N=2048 with a team of 8, one thread packed ~67 MB while seven idled). The team now splits the NR-column panels; packing is pure data movement into disjoint offsets, so the packed bytes and the result are unchanged (#348)
Changed
Section titled “Changed”-
i7-12700K GEMM scaling re-measured a second time after #410 (2026-08-05). Multi-core throughput is now the highest recorded on this machine — 470.9 GFLOP/s at N = 2048 on 8 P-cores against 429.4 before #410 and 401.8 before #382 — and the −7.4% regression at N = 1024 is gone (+22.0%). The “native-fast is the worst scaler” finding is softened, not withdrawn: efficiency is 85.5%, up from 79.2% but still short of the pre-#382 era’s 90.5% and last of the four backends. Part of that is arithmetic — efficiency divides by a
T = 1baseline #382 raised 22% — but not all: at 2 and 4 threads native-fast reaches 1.92×/3.72× where every vendor is at 1.97–1.99×/3.91–3.93×, so something remains in the parallel path and is not yet tracked by an issue. The page also retracts the cause it previously offered for the regression (cache pressure from the larger register tile, flagged there as untested) in favour of the coupling #410 actually found. The single-threaded BLAS sweep was deliberately not re-run —balanced_mconly engages whenic_nt > 1— which gives a control: native-fast’sT = 1figure moved 67.81 → 68.82, inside the ~4% session band -
i7-12700K benchmark data re-measured after #382 (2026-08-05). All five backends were re-run in one session rather than only
native-fast, because the headline claim is a ratio to OpenBLAS and a ratio is only defensible when both sides come from the same session — and because the three untouched backends holding still (native±0.3,openblas±0.2,blis±0.6 GFLOP/s) is what makes thenative-fastmove attributable rather than machine drift. GEMM at N = 1025: 59.44 → 69.81 GFLOP/s (+17.4%), and the epic #82 gate moves from 82.3% to 97.4% of OpenBLAS (range 95.5–98.8%, previously 76.3–86.5%) — the single-core kernel is now at parity, not “inside the 10–20% target”. The LAPACK sweep and sparse scoreboards were deliberately not re-run:blocking.hppis gated behindMTL5_NATIVE_FAST_GEMM, so #382 cannot reach them -
Three findings on the benchmark page are retracted in place rather than silently overwritten, per its provenance discipline: (1) “native-fast now scales better than OpenBLAS and MKL” — it is now the worst of the four at 6.33× / 79.2% efficiency against BLIS 7.37×, MKL 7.21×, OpenBLAS 7.11%, because #382’s single-thread gain decays with thread count and turns negative at N = 1024 / 8 threads (−7.4%), filed as #408; (2) “threading is no longer what separates native-fast from the tuned libraries” — relative throughput is no longer flat, 91.5% of OpenBLAS at T=1 against 81.5% at T=8, so the differentiator moved to the parallel path; (3) “MKL is remarkably weak at small N” — 17.5 GFLOP/s at N = 65 did not reproduce, measuring 60.8–71.4 across four independent runs with the MKL version unchanged since 2026-07-07 and large-N identical. The obvious explanation for (3) — a cold P-core at its 800 MHz idle clock — was tested and refuted (60.8 cold vs 61.0 warm), so the cause is recorded as undetermined rather than replaced with an untested story.
axpyalso moved +37% with no commit in the window that touches it, likewise marked undetermined -
pc::ssoris now the adapter oversmoother::symmetric_sorit was already documented to be (#405). It had been an independent reimplementation of the same two sweeps — its own loops and diagonal cache, duplicated across a generic and acompressed2Dspecialization — whiledocs/design/smoothers-architecture.mddescribed it as a wrapper. Since #398 established that one symmetric-SOR application from a zeroed vector isM⁻¹b, the preconditioner collapses to three lines over the smoother: −129 lines, and the matrix-type specialization comes fromsmoother::sorso the O(nnz) sparse path is inherited rather than restated. Two consequences beyond the line count:pc::ssorgains theAccumulatortemplate parameter (defaulted tovoid, so a widening rather than a break) — mixed-precision preconditioning was previously impossible while mixed-precision smoothing worked, with nothing in the API saying so; and the class of bug fixed in #398 becomes unrepresentable, since the duplicate was where it lived. The smoothers’ sweeps are nowconst(they only ever mutated the caller’sx), which is what lets the preconditioner hold one as a member and still expose aconst solve()withoutmutable. Operator and iteration counts are unchanged — the adjoint violation moves 3.432e-16 → 3.545e-16, a last-ulp shift from the smoother’s reciprocal-multiply against the old divide -
docs/sparse-direct-solvers-design.mdno longer advertises a “zero-cost CSC view overcompressed2Dwith col-major parameters” — never implemented;sparse/util/csc.hppuses a standalone owningcsc_matrix.docs/architecture/aggregate-types.mdno longer claims “Full support (CSR, CSC, COO, ELLPACK)”; CSC exists only as a conversion utility (#358)
[5.8.0] - 2026-08-02
Section titled “[5.8.0] - 2026-08-02”mtl::math::accumulator_round_type<Acc, Mag>(math/accumulator_traits.hpp) — names the arithmetic type an accumulator should be rounded out to before a scalar post-processing step such assqrt: the accumulator itself for a plain arithmeticAcc,Tforfma_accumulator<T>, and the magnitude type for a custom/quire accumulator. Lets the sum-of-squares norms accept all three configurations of the accumulator model without narrowing the sum before the root, and requires nothing new of external specializations (#324)
Dense mixed-precision iterative refinement (BLAS extraction from Universal)
Section titled “Dense mixed-precision iterative refinement (BLAS extraction from Universal)”mtl::lu_iterative_refine<Working>(A, b, x, opt)(operation/lu_iterative_refine.hpp) — the dense counterpart ofsparse::iterative_refine: factor A once in a lowWorkingprecision vialu_factor/lu_solve, then correct with a residual formed in the (deduced, higher)Residualprecision. Universal-free and generic over the arithmetic type. Shares the sibling’srefine_options/refine_resultshape: best-iterate return, patience for a noisy low-precision residual,rel_tolconvergence, and an opt-inscaled(scale-and-round) variant that carries the correction magnitude inResidualprecision so narrow-exponentWorkingfactors don’t underflow.mtl::normwise_backward_error(A, x, b)(operation/backward_error.hpp) — the normwise backward error||b - A x||_inf / (||A||_inf ||x||_inf + ||b||_inf)(Higham, “Accuracy and Stability of Numerical Algorithms”, Thm 7.1), the natural quality/termination metric for refinement.- Ported (Universal-free) from Universal’s
blas/ext/solvers/luir.hpp(SolveIRLU) +blas/utes/nbe.hppas the first library piece of the Universal->MTL5 linear-algebra extraction; the posit/precision experiments driving it live in mp-ir (Universal epic #1204, phase #1207).
Range and test-matrix generators (BLAS extraction from Universal)
Section titled “Range and test-matrix generators (BLAS extraction from Universal)”mtl::generators::{arange, linspace, logspace, geomspace}(generators/ranges.hpp) — NumPy-style spacing vectors returningvec::dense_vector<T>, generic over the scalar type (Universal-free).geomspacecomputes a true geometric progression between its endpoints, fixing the historical Universal implementation that aliasedlogspaceand treated the endpoints as exponents (geomspace(1, 1000, 4) == {1, 10, 100, 1000}).mtl::generators::magic(generators/magic.hpp) — magic square of order N (odd via the Siamese method, doubly-even via the complement method); singly-even orders throwstd::invalid_argumentpending support.- Migrated from Universal’s
sw::blasas the first step of extracting the linear-algebra layer into MTL5 (Universal epic #1204, phase #1206).
Matrix/vector/tensor property predicate module (#244)
Section titled “Matrix/vector/tensor property predicate module (#244)”A cohesive set of runtime property and predicate queries as free functions in namespace mtl, built on the existing primitives (cholesky/lu/svd/eigenvalue/norms) with no new dependencies. Consistent tolerance policy: structural checks are exact-by-default and NaN-safe (!(dev <= tol)), while norm/factorization/spectral-backed checks use relative or scale-aware tolerances; verified on both the in-house and LAPACK paths.
- Structural + vector predicates (
operation/matrix_properties.hpp,operation/vector_properties.hpp) —is_square,is_empty,is_symmetric,is_hermitian,is_upper/lower/is_triangular,is_diagonal,is_banded,is_diagonally_dominant;is_zero,is_finite/has_nan/has_inf,is_normalized/is_unit,is_orthogonal_to. O(n)/O(nnz), no factorization (#245) - Factorization-backed predicates (
operation/factorization_properties.hpp) —is_spd/is_positive_definite(symmetric + Cholesky),is_singular/is_nonsingular/is_invertibleanddeterminant(LU), each on a copy so the caller’s matrix is unchanged (#246) - Spectral / condition / rank (
operation/spectral_properties.hpp) —spectral_radius,condition_number,rcond,numerical_rank,nullity, wrapping the dense SVD and eigensolver (#247) - Rank-2 tensor predicates (
tensor/properties.hpp) —is_symmetric,is_antisymmetric(#248) - Orthogonality + inertia —
is_orthogonal/is_unitary(AᴴA == I) andis_normal(AAᴴ == AᴴA), plusinertia(the congruence-invariant(positive, negative, zero)eigenvalue-sign triple, Sylvester’s law) andis_indefinite; inertia is backed by the symmetric eigensolver so it is robust for singular/semidefinite inputs (#249)
On-node threading (#221)
Section titled “On-node threading (#221)”mtl::detail::thread_pool— a persistent worker pool (no OpenMP/TBB, just the C++ standard concurrency runtime) withrun,parallel_for(bit-identical contiguous chunking), andparallel_reduce(chunked, deterministic-per-thread-count). Threading is off by default;MTL5_NUM_THREADS(read once, clamped to hardware concurrency) sizes the pool, and=1/unset creates no workers and runs the original serial paths (#239)- Threaded kernels on the pool — blocked GEMM (#239), row-/col-major GEMV and
axpy/scal(#240),dot/nrm2and column-major GEMV (#241), and sparse SpMVcompressed2D * vector(#242). The iterative and eigensolvers inherit the SpMV/L1 threading with no solver-code changes. Every kernel except the reductions is bit-identical across thread counts - Documentation — an on-node threading reference (
docs/algorithms/on-node-threading.md) and a performance-engineering case study on multi-core scaling (docs/design/multicore-scaling-investigation.md), including the SMT-affinity measurement pitfall and the corrected 6.3–6.9× GEMM scaling on 8 physical cores (#243)
On-node threading — factorizations, triangular solves, multi-loop GEMM, element-wise (#297)
Section titled “On-node threading — factorizations, triangular solves, multi-loop GEMM, element-wise (#297)”Extends the #221 pool from the BLAS kernels to every substantial dense and sparse kernel, each bit-identical across thread counts (the parallel result equals the serial one exactly, ==, not to a tolerance) and serial-by-default. Rolled out in ten batches; validated per batch against the serial path and under ThreadSanitizer.
- Dense factorizations — parallel trailing/column updates in LU and Cholesky (#298); parallel Householder reflector application (apply-left over columns, apply-right over rows) in QR (#300)
- Sparse triangular solves via level scheduling — a reusable, value-agnostic schedule (
sparse/factorization/level_schedule.hpp) that stores positions into the factor’s arrays (not values), so it survives a same-pattern in-place refactorization and reproduces the serial accumulation order exactly. Applied to sparse Cholesky forward + transpose (#301, #302), sparse LU lower/upper (#304), sparse LDLᵀ unit-lower + transpose (#305), and the supernodal LDLᵀ (#306) and supernodal LU (#309) solves - BLIS multi-loop GEMM — the blocked GEMM’s ic-only parallelism generalized to a 2D
jc_nt × ic_ntthread grid: each jc-team’s leader packs the shared B panel once and the team splits the ic-blocks, synchronized by a per-team barrier. Scales tall, wide, and square shapes; every C macro-block gets the same FMAs in the same order regardless of grid shape. The per-team barrier keeps a throwing worker in the barrier protocol so a team can never hang, rethrowing after the region joins (#311) - Element-wise expression sweeps — the dense vector/matrix expression-template assignments (
y = a + b,C += A + B, construct-from-expression,+=/-=) route through adetail::parallel_ewisehelper; each output element is independent, so contiguous chunking is bit-identical (#312) - Encapsulation — the numeric factor types privatize
L/U/Dand their coupled solve schedules behind a validating, strongly-exception-safeset_factor(...)with read-only accessors, so the schedule can never drift from the factor pattern;solve()rejects a missing factor withstd::logic_error(#305–#309, #307/#308) - CI —
threaded(GCC+Clang,MTL5_NUM_THREADS=4) andThreadSanitizerlanes on push and PRs, plus the design field guidedocs/design/parallelization-patterns-and-pitfalls.md(#299/#303, #301)
Iterative solvers
Section titled “Iterative solvers”cgaccumulator policy — the conjugate-gradient solver routes its twodotcalls and themultthrough an optionalaccumulator_traitsaccumulator (#158); default (void) behavior is unchanged, whileposit32+quire shows a consistent accuracy gain over naiveposit32(#238)
Mixed-precision tensor operations (epic #157)
Section titled “Mixed-precision tensor operations (epic #157)”mtl::math::accumulator_traits<Acc, Value>— a shared, cross-cutting accumulator policy with a generalizedvalue<Result>round-out, expressing the three independent precisions of a mixed-precision op: element (storage), accumulator (compute), result (serialize). The accumulate→output conversion is fused into the final store (#158)- Accumulator/result policy on the dense operations:
dot/dot_real(#159),gemm/multwith the result type inferred fromC(#161),gemv(#160), and the sum-of-squares normstwo_norm/frobenius_norm(#162). E.g.mult<float>(A_bf16, B_bf16, C_bf16)accumulates in fp32 and writes bf16 once. DefaultAccumulator = voidis byte-identical to prior behavior - Dispatch guarantee
interface::accumulator_allows_blas_v— any non-default accumulator forces the native kernel even for float/double (external BLAS cannot honor a custom accumulator); proven via a counting accumulator (#163) mtl::convert— standalone element-wise tensor re-quantization for non-fused re-typing (distinct from the fused accumulate→store epilogue) (#164)- SIMD widening dot —
batch::load_widen(HighwayRebind+PromoteTo) +simd::reduce_dot_widenfor float→double;dotroutes its mixed path to it (~2.6× over scalar) (#165) - SIMD widening GEMM — the blocked GEMM generalized to
<TC accumulator, TAB operand>(defaultTAB = TC⇒ same-type path byte-identical): the micro-kernel widens narrow operands on load (batch<TC>::load_widen<TAB>) intoTCaccumulator registers.mult<double>(A_float, B_float, C_double)routes to it; 10–16× over the scalar generic kernel (Highway), matching the wide-accumulator reference to rounding (#176)
Sparse direct solvers
Section titled “Sparse direct solvers”sparse_lu_refactor+native_klu_refactor— analyze/factor/refactor: refactorize a same-pattern matrix by reusing the symbolic structure + pivot sequence (no BTF/ordering/reach/pivot-search), ~2.2× faster than a full factor; the SPICE-transient path (#153, #154)mtl::sparse::iterative_refine— generic, Universal-free iterative refinement through any factorization, with a templated residual precision, an optional scaled variant (rescues narrow-exponent low-precision factors), patience-based termination, and best-iterate return (#119, #167)
Native supernodal LU (SuperLU epic #186)
Section titled “Native supernodal LU (SuperLU epic #186)”mtl::sparse::analysis::analyze_unsymmetric— column elimination tree (etree of AᵀA without forming AᵀA), column counts, and the unsymmetric supernode partition + LU fill bound, in the postorder that makes supernode columns contiguous (#181)supernodal_lu_numeric— native left-looking Gilbert–Peierls LU that groups columns into supernodes and applies each as a dense block update, with threshold partial pivoting, Eisenstat–Liu symmetric pruning, and dynamic supernode formation. Generic over theaccumulator_traitsaccumulator, so a low-precision factor can accumulate in higher precision — the mixed-precision capability the fixed-precision SuiteSparse library cannot offer. Matches scalarsparse_luto machine precision (#182)supernodal_lu_refactor— numeric-only recompute that reuses a prior factorization’s order + pivot sequence + L/U pattern; 1.9–3.2× faster than a full factor (the transient-SPICE / mp-spice path) (#184)- Row equilibration — opt-in
scale=truefactorsR·A(r=1/max|row|) for pivot stability in low/mixed precision; RHS row-scaled insolve(),xunchanged (#185) bench_superlu— native-vs-SuiteSparse-SuperLU scoreboard on an unsymmetric suite (#180)- Mixed-precision iterative refinement integrates end-to-end via
iterative_refine(low-precision supernodal factor + high-precision residual) - Note: FP64 single-factor speed parity with SuiteSparse SuperLU is out of scope / not planned (#183). Profiling showed the panel GEMM is only ~14% of factor time (the bottleneck is scalar/serial work), so parity would require a full SuperLU-style reimplementation; MTL5’s differentiator is mixed precision, which is delivered
Documentation
Section titled “Documentation”- “Measuring Solver Accuracy” algorithm page — residuals, norms, absolute vs relative error, and backward-vs-forward error / conditioning (#152)
- “Mixed-Precision Kernels: Why, What, and How” algorithm page — an introduction to mixed-precision algorithm design: store-narrow/accumulate-wide, the Element → Accumulate → Result model, and the SIMD widening GEMM as a worked optimization example (#200)
Benchmark suite
Section titled “Benchmark suite”- Size-N sweep (
--sweep START:STOP:STEPand:xFACTOR) plus BLAS-level suite groupsl1/l2/l3/blas; default sizes now bracket powers of two with odd/1.5x neighbours to expose padding overhead (#77) - GFLOP/s-vs-N plotting (
benchmarks/plot_results.py, matplotlib) and committed example data + rendered plots underbenchmarks/data/with provenance (#78, #79, #80) - One-executable-per-backend methodology —
bench_allcalls only the publicmtl::API; the build flags choose the backend (native / OpenBLAS / MKL);run_sweeps.shbuilds all variants, pins to a P-core, and emits one CSV per backend (#81) - BLIS backend + expanded BLAS routine coverage —
run_sweeps.sh/run_scaling.shgain ablisvariant (CMakeBLA_VENDOR=FLAME, auto-skipped if absent); the harness now benchmarks all core BLAS routines MTL5 implements (addsaxpy/scalat L1, and L2/L3 as they land);analyze_gate.py --referencebaselines against OpenBLAS, BLIS, or MKL (#227, #228)
Documentation & API
Section titled “Documentation & API”- Capability assessment & expansion analysis —
docs/design/capability-assessment-and-expansion.md: a source-grounded assessment across functionality, performance (single/multi-thread), distributed-memory and hardware-accelerator readiness, with a maturity scorecard and a prioritized expansion roadmap (seeded the roadmap epic #220 and issues #221–#227) (#219) - Doxygen C++ API reference generated into the docs site (
docs-site/Doxyfile,npm run api, sidebar link, CI step) (#73) - Public
eigenvalue_symmetric_generic()— the generic (LAPACK-free) symmetric eigensolver, extracted so it can be called regardless ofMTL5_HAS_LAPACK(#78)
Tooling / CI
Section titled “Tooling / CI”.github/dependabot.ymlfor thegithub-actionsecosystem (#64)
Eigenvalue/eigenvector solvers (epic #202)
Section titled “Eigenvalue/eigenvector solvers (epic #202)”mtl::eigen— general (non-symmetric) eigenvalues and right eigenvectors, returned as a structured-bindable{ eigenvalues, eigenvectors }(complex), mirroringeigen_symmetric. In the in-house path, eigenvalues come from the general QR path and each eigenvector is recovered by inverse iteration onA - lambda_k*I(partial-pivot complex LU with a pivot floor); cluster-aware Gram-Schmidt deflation yields an independent basis for repeated eigenvalues. When LAPACK is available and the type qualifies,eigeninstead dispatches togeev(which returns the eigenvectors directly — see #204). Eigenvectors are unit-norm with a canonical phase (#203)- LAPACK
geevdispatch for the general eigenproblem —eigenvalue/eigenroute tosgeev_/dgeev_whenMTL5_HAS_LAPACKis defined and the matrix is a column-majordense2D<float/double>(mirrors the symmetricsyevdispatch); custom number types and other orientations use the in-house path (#204) - Matrix-free iterative eigensolvers in
mtl::itl(include/mtl/itl/eigen/), operating through theLinearOperatorconcept (A * x) so they apply todense2D,compressed2D, and user matrix-free operators:power_iteration(dominant pair),lanczos(symmetric, k extremal Ritz pairs via a tridiagonal projection),arnoldi(general, k Ritz pairs via a Hessenberg projection). Each solves the small projected problem with the dense eigensolvers; aneigen_whichselector picks the wanted end of the spectrum (#205) - Sparse eigensolver with shift-invert in
mtl::sparse—sparse_eigs(largest-magnitude, Arnoldi directly on the sparse operator),sparse_eigs_shift_invert(k eigenpairs nearestsigmavia(A - sigma*I)^{-1}applied inside Arnoldi, mappinglambda = sigma + 1/theta), and the reusableshift_invert_operator(factor once with sparse LU, apply many; tiny pivots perturbed so a shift on an eigenvalue stays solvable) (#206) - Eigenvalue/eigenvector solver guide —
docs/algorithms/eigenvalues.md: a decision guide plus a runnable snippet for every public eigen API across dense/iterative/sparse, the LAPACK dispatch conditions, and the custom-number-type story (#203, #207)
Core BLAS Level-2 / Level-3 operators (#229)
Section titled “Core BLAS Level-2 / Level-3 operators (#229)”- Level 2:
ger(rank-1 update),symv(symmetric matrix-vector),trmv(triangular matrix-vector),trsv(triangular solve) (#230) - Level 3 triangular:
trmm(B = alpha*A*B),trsm(solveA*X = alpha*B) — left side, no transpose (#231) - Level 3 symmetric:
symm(C = alpha*A*B + beta*C, A symmetric),syrk(C = alpha*A*Aᵀ + beta*C),syr2k(C = alpha*(A*Bᵀ + B*Aᵀ) + beta*C);syrk/syr2kproduce the full symmetric result (both triangles) (#232) - Each is a generic templated function (any Matrix/Vector type and orientation, and custom number types) with optional external-BLAS dispatch for column-major dense float/double, mirroring the existing
gemv/gemmgating. News/dbindings added tointerface/blas.hpp(ger,symv,trmv,trmm,trsm,symm,syrk,syr2k). BLAS leading dimensions are clamped tomax(1,m)for empty inputs - With this, MTL5 covers the core BLAS surface: L1 dot/nrm2/axpy/scal, L2 gemv/ger/symv/trmv/trsv, L3 gemm/trmm/trsm/symm/syrk/syr2k
Benchmark results site, and CI coverage for code no runner compiled
Section titled “Benchmark results site, and CI coverage for code no runner compiled”- Benchmark results site (
docs/benchmarks/) — a systems landing page indexing the machines (topology, vendor library versions, pinning policy and why it is mandatory on a hybrid P/E-core CPU) linking to a full per-system result page with figures and written assessments for the dense BLAS/LAPACK sweeps, the #82 gate, #108 GEMM scaling, the #297 kernel families and the sparse scoreboards. Adding a machine costs one page and one table row. The harness README is published alongside it at/mtl5/benchmarks/(#320) - CI: benchmark targets are now compiled on every push and PR in two configurations — native, and with BLAS/LAPACK + KLU + SuperLU so the
#ifdef MTL5_HAS_KLU/MTL5_HAS_SUPERLUcomparison paths are exercised.MTL5_BUILD_BENCHMARKSdefaultsOFFand no workflow enabled it, sobenchmarks/*.cppwas compiled by no runner; that is how thelu_numericbreakage below survived. Build-only: timed runs need pinned cores and a quiet machine, which shared runners cannot provide (#329) - CI: a Highway SIMD lane (
-DMTL5_WITH_HIGHWAY=ON -DMTL5_NATIVE_FAST_GEMM=ON, GCC + Clang) that builds and runs the suite. No workflow setMTL5_WITH_HIGHWAY, so every lane built thesize == 1scalar fallback insimd/batch.hppand the Highway specialization — the SIMD register type under the blocked GEMM — was compiled nowhere, while that flag is what thenative-fastvariant and every published benchmark number use. The fetched Highway build is cached on the pinned tag. Two guards against the lane passing while covering nothing: the workflow asserts alibhwyartifact was built, andsimd/test_batch.cppstatic-assertsbatch::size > 1underMTL5_HAS_HIGHWAYon x86-64 (the previous assertion was>= 1, which passes in both configurations) (#330)
Changed
Section titled “Changed”- The epic #82 acceptance gate now asserts the MEDIAN of the per-size ratios, with a new
--floor(default 0.70) that no individual size may fall below. It previously failed if any size fell under the threshold — gating on the minimum, the noisiest statistic available. Two runs of the identical protocol on the same idle machine failed at disjoint sets of sizes; the median is reproducible to 0.2 points where per-size values swing up to 6. Raising the iteration count does not help: within-run stddev is already 0.3–2.2%, so the variance is between runs, not within them (#327) run_scaling_297.shdefaults toSPARSE_SIZES=100,160(was200,320, which did not complete — aT=1run was killed after 3 h 28 min without finishing its first size). Sparse cost is dominated by the untimed factorization and grows steeply with the grid side: 11 s at 100, 3 m 38 s at 160, 8 m 46 s at 200, per thread count. The cost table is recorded next to the default so it is raised deliberately (#321)- CI runs when a draft PR is promoted to ready.
pull_requestdeclared notypes, so the default[opened, synchronize, reopened]applied andready_for_reviewfired nothing. Since the Tier 2regressionjob gates ondraft == false, a PR opened as a draft only ever had runs in which it skipped — silently, becausegh pr checksreports green when a job skips rather than fails (#333) cmake --preset releasebuilds something. It set tests and examplesOFFwith benchmarks defaultingOFF, leaving a configured tree with zero buildable targets, since the only target is anINTERFACEheader-only library (#319)mtl::svdnow uses one-sided Jacobi instead of an alternating-QR iteration, and its defaulttolis machine epsilon rather than1e-10. Results change for existing callers: they are correct where they previously were not, and accurate to ~1e-15 against LAPACK rather than ~1e-10 at best. The old default would have capped accuracy several orders short of what the method achieves; pass1e-10explicitly for the previous looser behaviour. Singular values are non-negative and returned in descending order, andUis completed to a genuine orthogonal basis for rank-deficient orm > ninput (#337)mtl::ldlt_bk_factor’s stored factor now matches LAPACKdsytrfentry for entry. Code reading the raw factor from a build before this release will see different values in the L columns whenever a pivot interchange occurred;ipivis unchanged and was always LAPACK-compatible (#335)mtl::dot/dot_realnow dispatch to BLAS?dotwhen types qualify (consistency withtwo_norm); bothdotandtwo_normBLAS paths guard theintlength cast against overflow (#81)- Benchmarks rewritten to the single-path public-API model; deleted the
Native/Blas/Lapackpolicy-tag harness (#81) - CI hardening: all GitHub Actions pinned to commit SHAs with
persist-credentials: false(#64); sccache gated to trusted runs to prevent GHA cache poisoning (#74); Dependabot action bumps (#66–#71) - Benchmark README: corrected CMake option names (
MTL5_WITH_BLAS/LAPACK) and added Intel MKL (BLA_VENDOR=Intel10_64lp) instructions (#75) .gitignore: ignore Claude Code per-user/runtime files (#76)- CI now exercises the LAPACK dispatch paths — a
lapackjob (Linux GCC + Clang,-DMTL5_WITH_LAPACK=ON) builds and runs the external-librarygeev/syevpaths, which the default LAPACK-free matrix never compiled (#212)
bench_klu/bench_superludid not compile — they referencedblk.L/blk.Uonlu_numeric, whose members are private (L_/U_). Nothing caught it because no CI job built the benchmark targets; they had not been compiled sincelu_numericwas encapsulated. Now use the publicfactorL()/factorU()accessors (#319)bench_sparse’s 3-D Laplacian grid is clamped.g3 = cbrt(g^2)sized it so its DOF count matched the 2-D case, butmax(8, ...)boundsg3only from below despite the comment claiming otherwise. Equal DOF is not equal cost — a 3-D Laplacian has far worse fill growth under Cholesky — so raising the 2-D size implicitly selected an intractable 3-D problem. Clamped to 32; grid side 200 went from killed after 3 h 28 min to 8 m 46 s (#322)mtl::svdreturned all-NaN singular values for ~30% of ordinary symmetric matrices, and values wrong by up to several hundred percent for many of the rest;condition_number,rcond,numerical_rankandnullityall inherited it throughdetail::singular_values. Two independent defects. (a)householderformedsum(x(i)^2)unscaled and guarded only exact zero, so a tiny sigma reachedbeta = 2*v0*v0/(sigma + v0*v0)with both terms flushed to zero (0/0), whilev(i) /= v0overflowed;apply_householder_left/rightthen evaluatedbeta * v(i) * was0 * inf. Sinceqr_factorstoresvbelow the diagonal, the poison spread into the factor. (b) The alternating-QR iteration converged to ~1e-9 and then corrupted its own answer — 136% wrong by iteration 1000 on a 10×10 SPD case — while its convergence test (off-diagonal mass / diagonal mass) kept shrinking and so read as converged;max_iter = 100*max(m,n)meant the corrupted value was the one returned. Replaced with one-sided Jacobi. Verified against LAPACKdgesvdover 1800 random matrices: 0 NaN, worst relative deviation 3.0e-15 (#337)mtl::itl::pc::ilu_0::solvecounted the diagonal in its back-substitution off-diagonal sum, computingx(i) = (y(i) - sum_{j>=i} U(i,j)*x(j)) / U(i,i)— subtractingU(i,i)*x(i)and then dividing the difference by that sameU(i,i). Wrong for every input: on a diagonal matrix, where ILU(0) is exact, it returned(b - d*b)/dinstead ofb/d. The diagonal is now stored only inu_diag_, makingu_rowsstrictly upper by construction so no consumer can forget to skip it. On a tridiagonal system where the factorization is exact, preconditioned BiCGSTAB now converges in 1 iteration instead of 11 (#323)mtl::ldlt_bk_factorproduced a wrong solution whenever a pivot interchange occurred, underinfo == 0— normwise backward error ~1e-1 instead of ~1e-16, in 4560 of 5700 random symmetric matrices.symmetric_swappermuted the L columns written by earlier steps, putting the stored factor in the “single global P” convention whileldlt_bk_solvereplays the interchanges one step at a time (as LAPACK’sdsytrsdoes); the two agree only when nothing is interchanged, which is why the n=2 and n=3 tests passed. The swap is now restricted to columns>= k. The pivot search was always correct —ipivmatcheddsytrfbefore and after — and the stored factor now matchesdsytrfentry for entry (#335)mtl::two_norm<Acc>/frobenius_norm<Acc>did not compile for either non-trivial accumulator configuration. They rounded the accumulator out to the accumulator type and took its square root — a no-op for a plain arithmetic accumulator, which is whytwo_norm<double>worked and hid it, but anfma_accumulator<T>or a quire for configurations 2 and 3, neither of which has asqrt. Now rounds out to the accumulator’s own arithmetic precision via the newaccumulator_round_type(#324)mtl::eigenvaluesingle-shift QR stalled on strongly non-normal matrices whose complex eigenvalues need a double-shift (Francis) step — it fell through to reading the diagonal and silently returned wrong eigenvalues (e.g. the Forsythe companion matrix returned all shift value, which the old trace-only test accepted). Replaced with the Francis implicit double-shift QR (EISPACKhqr): real Schur form via 1×1/2×2 block deflation, exceptional shifts to break stagnation, and astd::runtime_erroron non-convergence instead of a wrong result. Discovered while implementing the eigenvector generator (#203); tightened the Forsythe test to compare the full spectrum (#209)- AMD/COLAMD minimum-degree garbage-collection compaction mis-restored each element’s first entry, corrupting the quotient-graph pointers once fill exhausted the elbow room (e.g. the AᵀA pattern of a 2-D 5-point grid at n ≥ 64); it now follows the CSparse compaction order. Surfaced while validating the supernodal-LU column ordering; regression test added (#189, #191)
antisymmetric_tensor::setwrote out of bounds for diagonal indices (i == j) underNDEBUG, where the guardingassertis compiled out; now a safe no-op (#63)- Benchmark
nativeeigenvalue backend was silently dispatching to LAPACK; it now uses the generic C++ solver sonativevslapackis a genuine comparison (#78)
Planned
Section titled “Planned”- Epic #82 — native dense BLAS performance (sub-issues #83–#93, milestone v0.6): bring the native GEMM/GEMV/L1 kernels to within 10–20% of OpenBLAS/MKL via a SIMD abstraction layer, register-blocked micro-kernel, GotoBLAS/BLIS-style cache blocking + packing, and multithreading
[5.2.0] — 2026-03-16
Section titled “[5.2.0] — 2026-03-16”Sparse Direct Solver Infrastructure (Phases 1-6)
Section titled “Sparse Direct Solver Infrastructure (Phases 1-6)”- Phase 1: Infrastructure — CSC format (
csc_matrix), permutation utilities, sparse accumulator, elimination tree (O(nnz) via path compression), postorder traversal, sparse/dense triangular solves (Gilbert-Peierls reach + solve), Reverse Cuthill-McKee ordering,FillReducingOrderingandSparseDirectSolverconcepts - Phase 2: Sparse Cholesky (
sparse_cholesky.hpp) — Up-looking LL^T factorization for SPD matrices with symbolic/numeric phase separation, pluggable fill-reducing orderings, automatic permutation handling in solve - Phase 3: Sparse LU (
sparse_lu.hpp) — Left-looking PA=LU factorization with threshold partial pivoting,requires OrderedField<Value>concept constraint, sparse workspace tracking for efficient column processing - Phase 4: Sparse QR (
sparse_qr.hpp) — Householder QR for square and overdetermined systems, least-squares solve (min ||Ax-b||), compact V+beta storage, handles rectangular matrices (m >= n) - Phase 5: AMD/COLAMD orderings — Approximate Minimum Degree for symmetric fill reduction (Cholesky), Column AMD for unsymmetric fill reduction (LU/QR) via A^T*A column intersection graph
- Phase 6: External solver interfaces — RAII wrappers for SuperLU (
superlu_solver), KLU (klu_solver), CHOLMOD (cholmod_solver), SPQR (spqr_solver), with CMake find logic,#ifdefguards, and CRS-to-CCS conversion
Development Workflow
Section titled “Development Workflow”- Conventional commit format (
feat:,fix:,test:,docs:,chore:) - CodeRabbit AI review configuration (
.coderabbit.yaml) with C++20-specific review instructions - Branch protection on
main(PRs required, CI must pass)
Documentation
Section titled “Documentation”- Sparse direct solvers design document (
docs/sparse-direct-solvers-design.md) - Position paper: MTL5 + Universal for accelerated mixed-precision linear algebra (
docs/position-mixed-precision-acceleration.md)
Testing
Section titled “Testing”- Exhaustive cross-solver validation: Cholesky/LU/QR consistency on systems up to 100x100
- UMFPACK vs native solver comparison
- Edge cases: block diagonal, permutation matrices, identity, rectangular CSC, 1x1
- 90 total tests, all passing across GCC, Clang, Apple Clang, MSVC
Changed
Section titled “Changed”include/mtl/mtl.hpp— added sparse solver and external interface umbrella includesCMakeLists.txt— addedMTL5_ENABLE_SUPERLU,MTL5_ENABLE_KLU,MTL5_ENABLE_CHOLMOD,MTL5_ENABLE_SPQRoptionsCLAUDE.md— documentedsparse/namespace, conventional commits, branch workflow, PR process