Skip to content

Changelog

All notable changes to MTL5 are documented in this file. Format follows Conventional Commits.

  • 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 is docs/examples/zero-copy-overlay.md.

    • ode_rhs_callback.cpp: a C-style RK4 integrator calls rhs(t, const double* y, double* dydt, ...). The callback computes dydt = L y with vec::const_view and mult into 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 a dense2D over each frame and ndarray slices 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) and mat::const_view(rows, cols, ptr) take a const Value* and return a dense_vector or dense2D that reads the buffer in place, so a callback such as an ODE integrator’s rhs(t, const double* y, double* dydt) needs no const_cast and no copy (#834).

    • Writing through a view does not compile: element writes, data(), begin(), assignment, compound assignment, change_dim, swap and vec::fill are all constrained away.
    • It works with the existing operations: a view is still a dense_vector<V, P> or dense2D<V, P>, so norms, dot, A * x (dense and compressed2D), mult, the expression templates and the Krylov solvers accept it, as the new tests show.
    • Aliases and overloads: vec::const_vector_view<V, Orientation> and mat::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) and dense2D<double> M(view) make owning copies; that conversion is explicit (#855), so a view passed to a by-value parameter no longer deep-copies silently.
    • Tests: tests/unit/vec/test_const_view.cpp and tests/unit/mat/test_const_view.cpp.
  • Run-time selection of the interleave width (#778). With MTL5_INTERLEAVE_RUNTIME (CMake option, off by default), the generic gemv, trmv and 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 x86 cpuid or 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 or interleave_rows specialization keep the compile-time width.
    • Results are bit-identical whichever width runs. op_test_interleave_runtime forces each width with force_interleave_rows and 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_rows now prints the run-time choice and its distance from the fastest. See docs/benchmarks/interleave-width.md.
  • Two Ventuno Q sessions with native-fast on the cores’ own features (#806). benchmarks/data/arduino-ventuno-q/mtl5_bench/20261113T170450Z and 20261113T174232Z, at bf315e4 (after #819), every check passed, 780 of 824 entries within ±5% between them; the card moves to the pair.

    • The quad integer gemm: gemm_quad i8>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 SDOT path; the Ventuno’s builds before #819 were baseline Armv8.0-a.
  • 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/20261113T131507Z and 20261113T140622Z, benchmarks/data/arduino-ventuno-q/mtl5_bench/20261113T131507Z and 20261113T135246Z. 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/lu f64 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: gemm at 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.md has 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 gemv takes 12.9 ms (Jetson) and 7.73 ms (Ventuno) on one core, against 50.1 and 49.2 ms on 2026-11-11.
  • The sparse direct solvers against CHOLMOD and PARDISO: an i7-12700K session pair and an analysis page (#810). docs/benchmarks/direct-solver-references.md reads the direct-solver entries of two pinned sessions, benchmarks/data/i7-12700k/mtl5_bench/20261113T055208Z and 20261113T060838Z (at 8867b44, 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_cholesky 768×.
    • 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-major gemv takes 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). The direct entries 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_lu and supernodal_lu each get .analyze (ordering and symbolic), .factor and .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, which platform.sh’s and platform.ps1’s blas variant now sets:

      • ref_cholmod: CHOLMOD, supernodal L Lᵀ, AMD.
      • ref_pardiso_spd and ref_pardiso_lu: MKL PARDISO, mtype 2 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_bench loads libmkl_rt with dlopen(RTLD_LOCAL), so MKL’s BLAS symbols cannot displace the BLAS the build chose for every other entry. CHOLMOD is visible to mtl5_bench only.

    • 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 gains skip().

    • First numbers, i7-12700K, one thread, 20³ factorization: sparse_cholesky 7.35 s and supernodal_ldlt 66.6 ms, against 11.5 ms for CHOLMOD and 9.6 ms for PARDISO; sparse_lu 538 ms and supernodal_lu 625 ms, against 19.0 ms for PARDISO’s LU.

    • Fix: the direct solvers’ check passed an all-NaN solution. backward_error took its maxima with std::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 vendors benchmarks build compiles the reference entries.

    • plot_roofline.py: direct3d gets its own colour, appended so every earlier area keeps its colour; reference entries are diamonds; --areas keeps only the named areas.

  • benchmarks/publish_platform.cmake publishes an mtl5_bench platform session (#758, #737). Copying a platform.sh/platform.ps1 results 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.
    • 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.
    • 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.md has a “Publishing a session” section.
  • Benchmark data: the first four mtl5_bench sessions are in the repository (#760, #762, #764, #765, #737). Each was published with publish_platform.cmake and is marked preliminary: unpinned cores, no clock policy, one session. All four are class medium.

    • Ryzen 7 2700X: benchmarks/data/ryzen-7-2700x/mtl5_bench/20261108T223729Z/, built at e096dbbc6788.
    • Ryzen 9 8945HS: benchmarks/data/ryzen-9-8945hs/mtl5_bench/20261108T231039Z/, built at 685e2711d5ff.
    • i7-12700K: benchmarks/data/i7-12700k/mtl5_bench/20261109T025123Z/, built at e7497e6e4c47. 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 at 73d11400a0e3.
    • Each card page (docs/benchmarks/<machine>-mtl5-bench.md) now links its raw data, and each machine’s Systems-table row links its card.
  • 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 native build is the baseline a straightforward implementation gives, native-fast the best MTL5 does, and the blas build, with OpenBLAS and its LAPACK behind the dense kernels, the target. --variants picks 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.
  • Tensors and the follow-ups of dense2D aliasing (issue 857, from QA sweep #832).

    • contract requires 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]. bind of a temporary is deleted (it dangled).
    • Bounds: tensor’s access checks each index against Dim under bounds_checking, not the flat offset (t(0,3) of a 3x3 tensor aliased t(1,0)); symmetric_tensor and antisymmetric_tensor check too, where they checked nothing. An initializer list longer than the tensor throws std::invalid_argument in every build (an assert, then a buffer overrun).
    • Generic numbers: frobenius_norm sums |t_i|^2 and returns the magnitude type, so it is a norm for complex tensors; trace, identity, set_to_zero, contract and the metrics use math::zero / math::one. The unused zero_val_ is gone, and from_full documents that it truncates for integers.
    • Expression assignment: a sparse or block operand whose storage for_each_storage_range lists (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 * cols is the exact span of a data() 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_symmetric with a tolerance), compile-fail tests for a two-index contraction and a bound temporary, and test_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_rows and map_view index 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_solve rejects a complex factor at compile time, pointing at cholesky_h_solve, as cholesky_factor does (#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_solve keeps complex factors: LDL^T of a complex symmetric matrix is supported (#352), and its documentation now says that a factor from ldlt_h_factor needs ldlt_h_solve.
    • A NaN pivot stops ldlt_factor, ldlt_h_factor, ldlt_bk_factor and lu_factor, reported as the step’s index like a zero one (detail::pivot_unusable, !(|p| > 0)). Only p == 0 was tested, so [[NaN, 1], [1, 2]] returned 0 with NaN in D and L. On the LAPACK path, getrf flags only exact zeros, so lu_factor checks U’s diagonal after it.
    • lu_iterative_refine throws std::runtime_error when 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 with converged = false.
    • qr_solve throws std::invalid_argument for m < n (it read past row m: an out_of_range, or UB without bounds checks) and for vectors of the wrong size; inv throws for a non-square matrix.
    • trsm with 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_Q applies reflector j to Q’s columns j onward only (the others are untouched by it): bit-identical, fewer products (296 ms against qr_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 than ldlt_factor at 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, tall qr_solve against the normal equations and its shape checks, qr_extract_Q’s Q R = A and orthogonality, singular, empty and 1x1 LU and inv, both orientations, tall LQ, trsm with alpha = 0, row- and column-major Bunch-Kaufman agreeing to rounding); a compile-fail test for complex cholesky_solve.
  • Eigensolvers, SVD and Givens rotations (issue 853, from QA sweep #848).

    • Complex Givens rotations are unitary. math::givens_rotation took 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’s zlartg (real c, s = (a/|a|)·conj(b)/d, r with a’s phase), scaled like the real case, and apply_givens_rotation / apply_stored_rotation apply [c s; −conj(s) c]. Complex GMRES, which solved the wrong least-squares problem, converges. Real rotations are bit-identical.
    • eigenvalue() and eigen() scale A by a power of two, as schur() does (now a shared detail::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 (LAPACK dtrevc’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_error in the native eigenvalue_symmetric and eigen_symmetric (max_iter), eigen_symmetric_jacobi (max_sweeps) and the SVD’s one-sided Jacobi (60 sweeps), as eigenvalue(), 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, hessenberg and hessenberg_factor, and a NaN or infinite entry to the eigensolvers and svd, throw std::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 the std::runtime_error of a failed syev, heev or gesdd, and a 1x1 [Inf] came back as {Inf}; both are now this std::invalid_argument.
    • Tests: a new test_givens.cpp (complex rotations, zero arguments, the GMRES helpers); complex GMRES; a new test_eigen_robustness.cpp (scaling at 1e±170..1e±250 on the in-house and default paths, in-house eigen residuals, independence and pairing, non-convergence, NaN/Inf and non-square input).
  • ndarray: one iteration order, checked preconditions, reductions, broadcast lifetimes, views (issue 856, from QA sweep #832).

    • One logical order per array: its own Order. An f_order array iterated first-index-fastest when contiguous and last-index-fastest when not, so flatten, reduce and for_each_element depended on the strides. iterate_indices and the strided paths now follow the array’s Order, so flatten(a) matches a.reshape({a.size()}) (#359). c_order arrays are unchanged.
    • Checked in every build: reshape to another size and a shape list of the wrong length throw std::invalid_argument (under NDEBUG, a 3-element array reshaped to 100 elements was a view past its buffer). slice clamps a range to the extent as NumPy does, throws for step 0 (a division by zero) and for an integer index out of range. as_vector and as_matrix throw for a strided array, and sum_axis for an axis ≥ N. slice() of a rank-0 array compiles.
    • Reductions: sum and prod start from math::zero/math::one. min and max start from the first element, so a type without numeric_limits is right (it got V() = 0). min, max, mean and mean_axis throw on an empty array or axis (they returned DBL_MAX, -DBL_MAX, NaN, or divided an integer by zero). They, transform and flatten compile for read-only arrays and return the unqualified type.
    • broadcast_expr stores a temporary operand by value, so make_arr() + b and auto e = a.transpose() + b no longer dangle; operator[] honours bounds_checking.
    • reshape and transpose of a const array return read-only views; they returned mutable ones through a const_cast.
    • Assignment and views (decided on issue 856):
      • An owning ndarray, dense_vector or dense2D move-assigned a view or an external-buffer object copies the elements and stays owning. own = std::move(view) and own = a.transpose() used to make own a 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 under NDEBUG re-pointed the object at the source’s storage. Death tests cover the vector, the matrix and the ndarray view.
    • Faster strided paths: for_each_element, fill, copies, transform, sum_axis and broadcast_expr::eval walk 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, so a(all, 0) = a(all, 1) no longer copies through a temporary.
    • Tests: the cases above, f_order content through flatten, reduce, sum_axis, transform, slice and broadcasting; copies of transpose, reshape and nested views; broadcast - and /; compound assignment through a view, flat, fill on a strided view, size-1 strides; std::complex arrays.
  • Matrix Market reading, aliased products, and the follow-ups of QA sweep #848 (issue 855).

    • Duplicates past m*n: a coordinate file whose nnz exceeds the matrix’s capacity, with its entries summed (#653), was rejected by #843’s header check (1 1 3 with three entries threw; it reads as 6 again). A coordinate file whose rows * cols overflows size_t is read by mm_read (mm_read_dense still rejects it). The reserve stays capped by the file’s size.
    • Parsing: +-5 parsed as -5 and is rejected now, for floating-point and integer fields. The strto* path, taken where std::from_chars lacks floating point and for out-of-range values, refuses hexadecimal floats, so it accepts what from_chars does. A generic value type is value-initialized before it is read.
    • gzip: lines are split from gzread chunks instead of with gzgets, 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, symv and the block_matrix_view mat-vec compute through a temporary, in every build, when the output shares storage with an input, as the mat-vec mult does since #840. They were debug-only asserts that saw only the same object: mult(A, B, A) on a 3x3 dense2D<double> under NDEBUG differed in all 9 entries.
    • storage_overlaps also sees a coordinate2D’s triplets, each block of a block_diagonal2D, and a block_matrix_view’s encoded bytes (new bytes()).
    • A compressed2D_inserter that inserts nothing costs O(1) and leaves the matrix as it was. The slots are set up on the first ins[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_strto called directly; mm_read_dense on coordinate skew-symmetric and Hermitian files; mult(A, B, A) in both orientations and for float, through trans(A) and with an Accumulator; a C over part of A; mult(A, x, x) with a column-major A, float, and trans(A); read-only views as does-not-compile checks; mat::const_view of column-major, Fortran-index and fixed-size matrices; signum<bool>. The gemv tail test compares with a std::fma chain instead of simd::scalar_fma, the function the tail calls.
  • 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_numeric reports 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 assert only: a release build read out of bounds on a 3x4 A. These now throw std::invalid_argument in every build, as KLU, CHOLMOD and SuperLU do. umfpack_solver gains move assignment, num_rows() and num_cols(); a moved-from solver’s solve() throws std::logic_error.
    • 0x0 matrices: umfpack_solver and klu_solver threw, since the libraries reject n = 0. They now return an empty solver whose solve() takes empty vectors, as CHOLMOD and SPQR do; superlu_solver handles it the same way.
    • KLU status: klu_solver now checks common.status after klu_factor and klu_solve, and names a singular matrix in the message. With KLU’s default halt_if_singular a 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 with KLU_SINGULAR.
    • n or nnz above INT_MAX now throws std::length_error in all three bindings, as CHOLMOD and SPQR do, instead of wrapping in the int conversion.
    • Sparse dispatch with float or other vectors did not compile with the SuiteSparse bindings on: lu_solve_dispatch, cholesky_solve_dispatch and qr_solve_dispatch sent every float or double compressed2D to UMFPACK, CHOLMOD or SPQR, which take double and dense_vector<double> only. The new interface::suitesparse_solve_dispatches_v<M, X, B> routes only those operands to the libraries; everything else takes the native solvers. An underdetermined system throws std::invalid_argument on 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.cpp adds singular, non-square, size-mismatch, move, 0x0 and 1x1 cases. test_klu.cpp adds singular, 0x0 and 1x1. The new test_superlu.cpp covers reuse, factor_nnz, singular, non-square, move, 0x0 and 1x1. test_unified_dispatch.cpp adds float and mixed-vector dispatch. Not tested: the INT_MAX checks, 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.
  • LAPACK eigenvalue_symmetric and full svd on empty input, and syev/heev failures (#849, from the QA sweep #774).

    • 0x0 eigenvalue_symmetric: the real (syev) branch called LAPACK with lda = 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, in gesdd. An empty A now skips LAPACK and gets what the generic path returns: identity U and V, and an m x n S.
    • syev and heev info codes: both were ignored, so a NaN or Inf in A came back as NaN eigenvalues. eigenvalue_symmetric now throws std::runtime_error with the code on any non-zero info, as svd and eigenvalue do. A NaN or Inf usually gives one (info = 2 on a 3x3, reference LAPACK and OpenBLAS), but not always: syev copies a 1x1 A to the result without iterating, so [Inf] still returns {Inf}.
    • Untested wrappers: lapack::getrs, potrs, orgqr and trtrs, and blas::copy, had no caller in the library or the tests. blas::asum and blas::iamax are new wrappers over the ?asum and i?amax externs, which had none. tests/unit/interface/test_lapack_wrappers.cpp checks each one in float and double.
    • Tests: test_lapack_dispatch.cpp gains the empty eigenvalue_symmetric and svd cases, which ended the test binary before the fix with LAPACK on, and the NaN and Inf cases, which returned NaN. test_trmv_trsv_interleaved.cpp runs its bit-identity checks on native_shim, on a transposed_view and on lower_trisolve(L, x, x). test_mult_generic_mt.cpp adds a threaded double GEMV whose bands start inside an interleave block.
  • Test-matrix generators: Kahan conditioning, forsythe(1), make_sigma(0), Wilkinson sizes, the Rosser spectrum, reproducible random generators (#844, from the QA sweep #789).

    • kahan was not ill-conditioned. Its diagonal was s^i · 25 rather than s^i, which gave κ₁ = 2.1 for n = 10. It now follows MATLAB’s gallery('kahan', n, theta, pert): K = diag(s^i)·(I − c·triu(ones, 1)) + pert·ε·diag(n, …, 1). The third parameter, formerly zeta, is now MATLAB’s pert, 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, randsym and randspd with n = 0 and a kappa wrote sigma[0] out of bounds under NDEBUG. They now return an empty matrix.
    • wilkinson(n) follows MATLAB for any n ≥ 1, so an even n gets the half-integer diagonal abs(-(n-1)/2 : (n-1)/2). Under NDEBUG an even n used to build a wrong matrix, and n = 0 wrapped. n = 0 now throws std::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, randsym and randspd gain a std::uint64_t seed overload and a std::mt19937_64& overload.
      • The draws come from the raw engine stream, as in gen_dot and gen_sum, so a seed gives the same values with libstdc++, libc++ and MSVC. Each value is formed with an explicit fma, 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 through std::uniform_real_distribution.
      • The square randsvd with a kappa takes a seed through randsvd(n, n, kappa, mode, seed).
    • randsym and randspd are now exactly symmetric: they average A(i,j) and A(j,i) after forming Q·Λ·Qᵀ.
    • Argument checks now throw std::invalid_argument in every build. They used to be asserts. 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 randspd eigenvalue;
      • hi < lo or an infinite bound in the random fills (an infinite bound never returned);
      • gen_dot and gen_sum’s n, c < 1 and c beyond the type’s range;
      • NaN endpoints in geomspace.
    • Genericity: clement and kahan call sqrt, sin and cos through ADL, and test_shim_genericity covers them.
    • Smaller items:
      • testsuite::by_name joins its path with std::filesystem::path.
      • The pascal header documents where float and double stop being exact (n = 14 and 29) and where the entries overflow (n = 67 and 516).
      • The clement comment now states its formula and spectrum correctly.
    • Tests:
      • test_generator_properties.cpp checks 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 float for pascal, hilbert, kahan and clement.
      • test_random_seed.cpp checks that a seed reproduces exact values of the mt19937_64 stream, covers the [lo, hi) bounds, and checks the condition number in every randsvd mode.
      • test_testsuite.cpp loads 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. faires74x3 had the ∞-norm value. steam3 and fs_183_1 had 1-norm values. fs_183_3 repeated fs_183_1’s value, and west0167 repeated steam1’s (2.827e7, where the true value is 4.785e10). rump6x6ill had 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 into size_t as 2^64-1. mm_read then wrapped nrows + 1 to 0 and wrote out of bounds, and mm_read_dense threw bad_alloc. Sizes are now parsed strictly: non-negative integers, the whole token, exactly two or three per line.
      • A header nnz larger than the matrix can hold (2 2 99999999999999) used to reserve that many entries. It now throws.
      • nrows * ncols is 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_dense checks 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 by nrows * ncols.
    • Banner: all five tokens are required and checked: tag, object, format, field and symmetry. foo matrix coordinate real general used to be accepted, and a missing field or symmetry token defaulted to real/general.
    • Symmetric storage:
      • A valid array real symmetric file (the lower triangle by columns) used to throw “unexpected EOF”. An n*n-value file under that banner was read as general. Array files with symmetric, skew-symmetric and hermitian symmetry are now read as the format defines them and mirrored.
      • skew-symmetric coordinate files are read too (they were rejected), with a stored diagonal entry rejected.
      • hermitian files are read and mirrored conjugated.
    • Complex values: complex files read into a std::complex value type. mm_write and mm_write_sparse used to write real whatever the value type, and streamed a complex value as (re,im). They now take the banner’s field from the value type (complex, integer or real) and write max_digits10 digits. 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.
      • nan and inf, which the writers emit, used to be rejected on reading; they now read back.
    • gzip: a corrupt or truncated .gz stream used to read as a shorter file, because gzgets returning nullptr was taken as end of file. The reader now asks gzerror and throws.
    • read_dense and read_sparse:
      • A bad token used to stop the read and return a partial matrix; now it throws.
      • read_dense throws 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_sparse throws std::out_of_range for an index outside the given dimensions, with the line number.
    • write_png throws 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_chars where the standard library supports it for floating point, which ignores the locale, and with strtod otherwise. Loading bbmat (1.77M nnz) takes 0.22 s instead of 0.52 s, and rajat30 (6.18M nnz) 0.77 s instead of 1.76 s. All 35 bundled .mtx files read identically to before.
    • CI: the Linux LAPACK jobs link zlib, so the [gzip] tests run in CI. No job built with MTL5_WITH_ZLIB before.
    • 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_write of a sparse matrix, and mm_write_sparse with a comment.
      • The gzip tests cover a 70 KB line, a stream missing its last 4 bytes, and .gz through mm_read_dense.
      • The spy tests cover log_scale in spy_magnitude and spy_density, max_pixels == 0, 1x1, non-square, float values, and scale_index near 2^62.
      • The PNG tests cover an unwritable path and bad channel counts.
  • CHOLMOD and SPQR bindings: lifetime, concurrent const solves, and SPQR’s first tests (#839, from the QA sweeps #816 and #774).

    • Concurrent solves: cholmod_solver::solve() and spqr_solver::solve() are const but wrote the solver’s shared cholmod_common, so two threads solving on one solver raced. Each solve now runs on a cholmod_common of 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 a const solve is safe to call concurrently. The cost is one cholmod_start and cholmod_finish per solve.
    • SPQR lifetime: the move constructor copied the cholmod_common struct, so both objects finished the same workspace, a double free once a solve had filled it. The workspace is now a unique_ptr with a cholmod_finish deleter (interface/cholmod_workspace.hpp, shared with CHOLMOD). spqr_solver gains a move assignment, frees its matrix if the copy throws, rejects m, n or nnz above INT_MAX with std::length_error, and throws std::logic_error from a moved-from solve().
    • CHOLMOD: a failed cholmod_start throws instead of being ignored. A moved-from solver reports sizes 0. The comment on factorize(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 a factorize() succeeds.
    • Orientation: the CRS-to-CCS copies are correct as written, because compressed2D is row-major only (a static_assert). The comments now say so.
    • Build: MTL5_WITH_SUITESPARSE_SPQR links CHOLMOD too, since spqr.hpp calls cholmod_* itself. The Linux LAPACK CI jobs turn SPQR on, so iface_test_spqr runs against the real library and sparse qr_solve_dispatch goes through SPQR.
    • Tests: new test_spqr.cpp covers 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.cpp adds a refactorize with the same column counts but different rows, an indefinite refactorize followed by a good one, a non-square analyze(), 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.
  • Foundations fixes from the QA sweep #816 (#838).

    • functor::scalar::abs and signum compile for unsigned types; signum(NaN) is NaN, not 0.
    • The max and min identities are -inf and +inf for types with infinities. They were lowest() and max(), so a max over -inf values gave lowest().
    • magnitude_t and is_complex_v ignore cv-qualifiers.
    • The Magnitude concept finds abs through std and ADL; Magnitude<double> had held only through C’s ::abs(int).
    • aligned_allocator and allocate_aligned reject an n whose n * sizeof(T) overflows, with std::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; the LinearOperator, Preconditioner, FieldVector, NdArray and MutableNdArray concepts.
  • mult(A, x, y) with y sharing storage with x or A, the column-major gemv tail, and the cache_info sysfs scan (#840, from the QA sweep #816).

    • Aliasing: every kernel writes y while still reading its inputs, and the column-major gemv zeroes y first. A y that is the same vector as x, or a vector over part of x’s or A’s buffer, gave wrong results under NDEBUG; a debug-only assert caught only the same object. mult now checks the address ranges (detail::storage_overlaps, which also sees a compressed2D’s value array and the matrix behind a view) in every build and computes through a temporary, still writing y’s own buffer. The transposed-compressed2D overload does the same.
    • The column-major gemv tail: the last m mod W rows 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 uses simd::scalar_fma, the batch’s own fma. Every row gets the same chain, as the kernel’s comment claimed. This changes the tail rows’ last bit where the batch fma fuses (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 each shared_cpu_list counted 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.
  • sparse_vector and strided_vector_ref fixes (#830, from the QA sweep #767).

    • Index checks: sparse_vector::insert and operator[] 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 signed size_type rejects negatives. exists() returns false outside the vector.
    • -fno-exceptions: sparse_vector threw directly and did not compile there; it uses detail::throw_or_abort, and the no-exceptions test builds it.
    • crop: takes a magnitude threshold, so std::complex values 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, so end() 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 empty sub_vector at the end keeps the base pointer.
    • CI: the publish step checks that a repeat publish leaves systems.md and the card page byte for byte. It also checks DRY_RUN, a blank or different card cell, an older session, and the warning for a systems.md without a card column.
  • 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; gave v a private copy, and bd.block(0) = X on a block_diagonal2D had no effect.

    • Copy and move assignment write through an external or view contiguous_memory_block of the same size, so dense_vector, dense2D and block_diagonal2D::block(k) keep writing the caller’s buffer, as expression assignment already did.
    • Another size throws std::domain_error for copy and expression assignment, instead of detaching. Move assignment is noexcept, so it asserts. change_dim and realloc, explicit resizes, still detach.
    • ndarray views: 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-size dense2D, 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 owning ndarray copies 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-from ndarray is empty.
    • dense_vector(n, 0) fills with zeros; it was ambiguous with the external-pointer constructor, which now takes exactly Value*. vec::fill(v, 0) compiles for a double vector. dense_vector has owns_memory(), like dense2D.
    • Tests for contiguous_memory_block assignment, dense_vector, dense2D, block_diagonal2D and ndarray views, and a new tests/unit/vec/test_vec_expr.cpp for the vector expression templates.
  • Sparse construction: a second inserter kept only its own entries, insertion indices went unchecked, and coordinate2D summed duplicates in an arbitrary order (#825, from the QA sweep #740).

    • compressed2D_inserter amends the matrix, as MTL4’s does. The matrix’s entries are loaded at construction, so inserting at an existing position applies the updater (update_store replaces, update_plus adds) 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) left nnz == 1. No caller in the library, examples or benchmarks reuses a filled matrix; make_empty() or change_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 signed Parameters::size_type is rejected too.
      • coordinate2D::compress() checks every entry, an O(nnz) pass per matrix. Under NDEBUG a bad row was a heap write past starts, and a bad column was stored. insert() no longer asserts, so the check is the same in every build.
      • compressed2D_inserter checks ins[r] and ins[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.
    • coordinate2D sums duplicates in insertion order: sort() and compress() use std::stable_sort, so the result is reproducible for rounding-sensitive values. compress() after sort() 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.sh matches manifest targets on a name boundary: krylov/gmres30 still passed after its entry was renamed. A trailing * asks for a family, as krylov/idr_s* now does.
    • Not changed: the sweep’s claim that the f32 gemm and trsm platform 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_size 0, 0-row and 0-column matrices and the index checks. test_coordinate2D covers compress() on empty matrices and rows, duplicate order and the index check; test_ell_matrix the width-0, non-square and 3-argument cases. test_batch adds value-level load and store for all four lane types, load_widen and convert, 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, and P({2}) the 2×2 identity: {0} chose the size constructor. A braced list is now the permutation, through an std::initializer_list constructor; P(n) is still the identity.
    • Every permutation is validated at construction: a duplicate or out-of-range entry throws std::invalid_argument. It made inverse() and P * x index out of bounds. swap_rows checks its rows under bounds_checking.
    • hermitian_view requires a square matrix: for a 3×2 A, H(2,0) read A(0,2). The diagonal is returned as stored, which is exact for a Hermitian matrix, and that is now documented.
    • map_view checks its map entries at construction, and (r, c) under bounds_checking. Repeated entries are allowed.
    • Block mult summed in float for a double y: the SIMD branch tested only x. A float x into a double y now sums in double, as a non-contiguous x already did.
    • block_diagonal2D:
      • block(k) no longer exposes the block itself: the non-const overload returns a dense2D over the block’s storage. change_dim on 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: a block() view passed to set_block, add_block or the vector constructor is copied, where set_block(k, bd.block(k)) would have freed the buffer the view points into. The new dense2D::owns_memory() tells them apart.
      • add_block is O(1) (it was O(n) per call), and operator() finds the block by binary search instead of scanning.
    • mxint8 and mxfp4::decode_element assert j < 32. For mxint8, a larger j read past the block.
    • Not changed:
      • std::common_type_t in the permutation_matrix and block_diagonal2D products works for same-type posits and LNS, and mixed types follow mult’s rule, as for #824.
      • P * A already existed for a dense2D A, in operation/reorder.hpp. The header now says so.
    • Tests: test_permutation_matrix, test_block_diagonal2D, test_matrix_views, test_triangular_views and test_block_matrix_view cover the cases the sweep listed. The float-x/double-y test fails before the fix. death_test_mat_index_asserts covers block_matrix_view::row and decode_element.
  • dense2D assignment 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 a block_diagonal2D can hold the target as a block. An external-pointer target keeps writing its own buffer.
    • A ragged initializer list is rejected with std::invalid_argument, through throw_or_abort. dense2D<double>{{1,2},{3,4,5}} wrote past the buffer, and a shorter row was padded with zeros.
    • mult with mixed dense operand types under BLAS (float A, double B and C) didn’t compile: the ?gemm branch didn’t require one element type. Mixed operands now take the generic kernel, as on the native-fast path. And mult(trans(S), x, y) for a sparse S is now constrained to vectors, so trans(S) * B with a dense B reaches the matrix product.
    • The generic Matrix * Matrix now calls mult. It was its own unblocked triple loop, reading B down its columns through operator(). Dense float and double now get BLAS or the native-fast GEMM, and compressed2D * dense2D gets 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, as mult’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_ARCH built the Arduino Ventuno Q for baseline Armv8.0-a (#806). GCC 13 resolves -march=native to nothing on that board’s Cortex-A78C + A55 SoC: the driver passes no -march or -mcpu on to the compiler. Every native-fast build there lacked DotProd, so mult_quad ran Highway’s emulation of SDOT. gemm_quad i8>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 flags MTL5_NATIVE_ARCH adds. A non-default value is recorded in the build provenance, so the sidecar’s cxx_flags= names it.
    • A configure-time guard on AArch64 Linux: CMake warns when the flags don’t enable a feature /proc/cpuinfo lists (asimddp → DotProd, i8mm → I8MM). platform.sh repeats the warning on the console.
    • platform.sh --arch FLAGS for the native-fast build. 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-a78c measured 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=NEON and the Jetson Orin as NEON DOTPROD. The Jetson’s quad gemm, 3.9× the plain one, is the native SDOT path.
  • mtl5_bench’s blas variant didn’t build against CHOLMOD before version 5 (#810). The CHOLMOD reference entry set cholmod_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, which platform.sh already 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_solver had no unit test, and no CI job built it.

    • Move: the move constructor copied the cholmod_common struct, 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 throws std::logic_error if used.
    • Indefinite matrices: a matrix that isn’t positive definite now throws std::runtime_error from the factorization. On the supernodal path CHOLMOD reported it only in Common->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_MAX throws std::length_error instead 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, and common() for CHOLMOD’s settings. cholmod_solver(A) and cholmod_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.cpp covers 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.
  • The harness README has its sparse direct-solver section again. #468 deleted “Sparse direct-solver scoreboards” (how to run bench_klu, bench_superlu and bench_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_sparse takes 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.ps1 matched 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 blocked platform.ps1 with 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_processes and 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.sh applies the same test on Linux, from /proc/<pid>/stat. On macOS every match still counts, and idle_build_processes is unavailable.
    • mtl5_bench: both preflights looked for bench_*, which the platform harness doesn’t match, so a second platform.sh or platform.ps1 could measure alongside a running one. *_bench is now matched too. Benchmarks always count, without sampling.
    • Test: bench_preflight_contract requires idle_build_processes from both scripts.
  • mtl5_bench capability 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, and publish_platform.cmake repairs cards written by an older binary.

  • The mtl5_bench card 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 in FILE_MAP, so the site didn’t build them and systems.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>.md stays the written analysis page, as for the i7-12700K and the Ryzen 9.
    • systems.md lists both kinds in separate columns.
    • Each card page is marked preliminary, because none was measured under #737’s methodology.
  • IDR(s) keeps one ω per cycle, so a larger s no longer costs more iterations (#734). mtl5_bench found itl::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_bench entries 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.
    • Test: test_idr_s runs 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.
  • TFQMR converges on unsymmetric systems, and its reported convergence is the true residual’s (#731). itl::tfqmr stalled 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 tfqmr does. 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_tfqmr adds 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, the Accumulator path, and an iteration-limit case. The “non-symmetric” 3×3 test is now nonsymmetric. The mtl5_bench tfqmr+ilu0 entry is back on convection–diffusion.
  • <mtl/mtl.hpp> compiles with BLAS and SuperLU both enabled (#725). SuperLU’s slu_ddefs.h declares its own extern "C" prototypes for the BLAS routines it calls. Their signatures differ from MTL5’s const-correct ones in interface/blas.hpp, and between SuperLU versions: int returns in 5.x, void with non-const pointers in 7.x. Any translation unit holding both headers failed with “conflicting declaration of C function”: the umbrella header, or interface/superlu.hpp next to any operation that dispatches to BLAS.

    • The fix: superlu.hpp renames 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 compiled libsuperlu, so which BLAS it links against is unchanged. A name that slu_Cnames.h already maps, for a Fortran convention other than the trailing underscore, is left alone.
    • Test: iface_test_superlu_blas includes 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.
  • mtl5_bench charges symv for one triangle of A, not all of it, and flags results far above their roofline (#743). The blas2/symv entry 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² + 2n elements, as trmv and trsv already 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, and suspect_model in 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 medium runs on the same machine. A byte model that counts a triangle as the full matrix still reads about 200%.
    • What changes: symv %roof and GB/s figures from earlier runs are twice what this build reports for the same speed, so they aren’t comparable. No other entry’s model changed.
  • Three generic-type defects found by the new native_shim test 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_symmetric and eigen_symmetric did not compile for such a type. They now compare with math::zero<real_t>().
    • The property predicates defaulted tol to an int literal (tol = 0, or the sentinel -1). This affected 22 functions in matrix_properties.hpp, factorization_properties.hpp, vector_properties.hpp, spectral_properties.hpp and tensor/properties.hpp, so a call that relied on the default did not compile. The default is now magnitude_t<T>(0) or magnitude_t<T>(-1).
    • has_nan, has_inf and is_finite treated every custom real type as finite and never NaN. A posit NaR or an lns NaN went unseen even when the type provides isnan. The classification now uses the type’s own isfinite, isnan and isinf when ADL finds them, and only falls back to “finite” for a type without them.
  • mult asserts in debug builds that its output does not alias an input (#696). mult(A, B, C) and mult(A, x, y) overwrite C (or y) while still reading the inputs, so mult(A, B, A) or mult(A, x, x) silently gave a wrong result. The precondition was documented but not checked.

    • The fix: the public mult overloads (dense, sparse transposed, block matrix) and mult_quad assert that 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 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 requires lda >= max(1, rows). The gemv dispatch in mult, and ger, symv, trmv and trsv, 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, so mult on a 3x0 A 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 mult then 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.
  • syrk, syr2k, symv, symm and trmm follow the BLAS alpha/beta convention on every path; symv and symm read only A’s lower triangle (#692). BLAS defines beta == 0 to mean C (or y) is not read, so it may hold NaN or uninitialized values, and alpha == 0 to mean A and B (or x) are not read. The generic paths computed alpha*sum + beta*C regardless, so a NaN in C survived beta == 0, since 0 * NaN is NaN, while gemmt and the BLAS paths gave the right result. trmm, which has no beta, kept a NaN in A or B under alpha == 0. The generic symv and symm also 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 gemmt computes it. When alpha is zero it is beta*C, or zero when beta is zero too. Otherwise it is alpha*sum, plus beta*C only when beta is nonzero. trmm with alpha == 0 sets B to zero. On the generic and accumulator paths, symv and symm take A(i,j) above the diagonal from A(j,i).
    • What changes: results for a nonzero alpha and beta are unchanged. With beta == 0 and a finite C they are unchanged too. For a symmetric A, symv and symm are 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_zero runs 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 at beta == 0, A and B filled with NaN at alpha == 0, both at once, and a NaN-filled upper triangle for symv and symm. Against the old headers every path fails.
  • kron takes 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, so kron(dense2D<int>{2}, dense2D<double>{0.25}) gave 0, and kron of a double matrix with a std::complex<double> one did not compile.

    • The fix: the value type is std::common_type_t of the two value types, as in dot, axpy and the other mixed-type operations.
    • What changes: nothing when both operands have the same value type. For example, int8_t (x) int8_t stays int8_t, although int8_t * int8_t is int. A pair of custom types with no std::common_type keeps A’s value type, as before, rather than failing to compile.
    • Test: test_kron covers int (x) double in both orders, float (x) double, double (x) complex<double>, same-type double and int8_t, and the no-common-type fallback. Against the old header, the new cases do not compile.
  • Scaled project_onto and embed_into saturate correctly between integers of different signedness (#691). detail::saturating_cast cast the target’s limits to the source type before comparing, and those limits wrap when the signedness differs. So project_onto<int32_t>(dense_vector<uint32_t>{5, 100}, uint32_t{1}) gave INT32_MIN for both elements, and embed_into<uint32_t>(dense_vector<int16_t>{5, 7}, 1) gave UINT32_MAX.

    • The fix: the comparison is by value, with std::cmp_less and std::cmp_greater. Both sides are first widened to long long or unsigned long long, since those functions reject bool and the character types. Widening between signed types was broken the same way: static_cast<int>(LLONG_MAX) is -1, so embed_into<long long> of an int vector clamped every positive value to LLONG_MAX and every negative one to LLONG_MIN. That is fixed too. Same-signedness narrowing, unsigned widening and floating-point conversions are unchanged.
    • Test: test_projection covers 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, and char targets. Against the old header, 5 of its 26 test cases fail.
  • two_norm and frobenius_norm no longer overflow or underflow; the max-based norms propagate NaN (#690). The default path summed unscaled squares, so two_norm of dense_vector<float>{1e20f, 1e20f} was inf and of dense_vector<double>{1e-200, 1e-200} was 0, while a BLAS build, whose nrm2 scales, gave the right answer. infinity_norm and the matrix one_norm and infinity_norm kept the maximum with a > result, which skips a NaN, so infinity_norm({1, NaN, 2}) was 2 although one_norm of 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 below min()/epsilon(), where the small squares may have underflowed. It sums the squares scaled by a power of two near max|a|. A vector whose norm genuinely overflows is still inf, and one containing an inf is inf. The max-based norms return NaN when any element, column sum or row sum is NaN.

    • Custom number types are rescaled too: frexp, ldexp and sqrt are found by ADL, with the std versions 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 a std::numeric_limits specialization.

    • What changes: nothing for an ordinary input: it never rescans, so its result is bit-identical to before. A type without frexp, ldexp, sqrt or std::numeric_limits keeps the plain sum. Integer norms keep their wrapping semantics. A magnitude type without != keeps the plain maximum. The explicit-Accumulator overloads are unchanged.

    • Test: test_norms covers:

      • values near the float and double overflow and underflow thresholds;
      • subnormals, and zero and inf vectors;
      • the generic loop, through std::complex<double>;
      • a user-defined real type that is rescaled only through its own frexp and ldexp;
      • 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.

  • BREAKING: an owning dense_vector or dense2D is constructed from a read-only view only explicitly (issue 855, from QA sweep #848). The converting constructors from vec::const_vector_view and mat::const_matrix_view are explicit. Implicit, they let a view passed to a by-value dense_vector or dense2D parameter 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)), or mat::dense2D<double> M(view);. Code that only reads should take the view, or const dense_vector<V, P>& with the view’s parameters, and copy nothing.
  • BREAKING: Scalar requires std::numeric_limits on the element type’s magnitude type (#838, from the QA sweep #816). Scalar<T> now includes HasNumericLimits<T>, which is std::numeric_limits<magnitude_t<T>>::is_specialized. It applies to the magnitude type because the standard has no numeric_limits<std::complex<T>>, so std::complex<T> qualifies through T.

    • 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, sylvester and eigen_symmetric; an exact comparison in the ldlt/cholesky structure guards (structure_tol), which then rejected matrices symmetric only to rounding; no scaling in sylvester and svd; and a zero identity for min/max. Those paths are removed: machine_epsilon and structure_tol read numeric_limits, and the eight is_specialized branches 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 new tests/support/mtl5_test/limits_of.hpp.
  • 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.md to docs/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 and systems.md’s card links follow the new path.
    • The sidebar order:

      1. the harness overview and the systems page;
      2. the cross-machine analyses;
      3. the per-machine analyses;
      4. the cards, in a collapsed group.

      A new page in docs/benchmarks/ needs a sidebar entry in docs-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.cmake now 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.md is 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.sh and 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.py on 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).
    • 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 trmv and forward substitution stay 1.45–1.48× behind it even at #798’s W = 2.
    • i7-12700k.md and ryzen-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 /arch flag 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 gemv in 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 SDOT quad integer gemm is slower than its plain i8 gemm (#806).
    • 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.
  • Behaviour change for BLAS builds: Level 1 no longer calls the vendor (#754). With MTL5_HAS_BLAS, dot, two_norm, axpy and scale on dense float/double vectors called ?dot, ?nrm2, ?axpy and ?scal at any length. They now take MTL5’s own SIMD loops, as a build without BLAS does. Level 2 and Level 3 still dispatch, and interface::blas:: keeps the Level 1 wrappers for a direct call.

    • Why: OpenBLAS splits ddot and daxpy across 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, and mtl5_bench --class medium --filter krylov in a BLAS build ran 17–123× slower than without BLAS under that load. For example, bicgstab+ilu0 took 378 ms and gmres30+ilu0 3,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 dot and two_norm can differ in the last bits, since they now use MTL5’s summation order instead of the vendor’s. axpy now rounds as a build without BLAS does. A large ddot on an idle machine loses OpenBLAS’s threading: 208 µs single-threaded against 54 µs on 20 threads at n = 10⁶. With MTL5_NUM_THREADS > 1, MTL5’s loops split across its own pool above 65,536 elements.
    • Recorded: mtl5_bench writes probes.blas_vendor and probes.blas_vendor_threads into its JSON (blas_vendor= and blas_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_dispatch requires each of the four routines to give exactly the bits of its simd:: loop at n = 20,000. Against the old dispatch, it fails in the OpenBLAS build.
  • A PR that only publishes benchmark data no longer runs the build matrix (#761). ci.yml and regression.yml now ignore benchmarks/data/**, which no build or test reads. The sidecar check (#477) moved from ci.yml into a new bench-data.yml, which runs when benchmarks/data/, check_sidecars.sh or the workflow itself changes. A session published with publish_platform.cmake (data, card page, FILE_MAP entry) now runs that check and the docs build. The benchmark sources elsewhere under benchmarks/ still run full CI.

  • BREAKING: trans and the other view factories reject a temporary at compile time (#695). Every view in mat/view/ holds a reference to its matrix, and the factories took const M&, so auto t = trans(A * B); compiled and t read freed memory once the product was destroyed.

    • The fix: trans, upper, lower, strict_upper, strict_lower, triu, tril, banded, hermitian and mapped each have a deleted const M&& overload, which an rvalue prefers over const 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 as trans(upper(A)). Name the matrix or the inner view first. Views of named matrices are unchanged.
  • superlu_solver factors once (#850, from the QA sweep #774). solve() ran dgssv, a full factorization, on every call. The constructor now runs the column ordering and dgstrf, and solve() runs only dgstrs with 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).

  • mult mat*mat reaches ?gemm for every orientation mix, and ger for a row-major A (#849, from the QA sweep #774). Both were gated on one orientation, so they fell to the generic kernels: mult unless A, B and C shared one, ger unless A was column-major, which left out the default row-major dense2D. A row-major buffer is the column-major transpose, so mult now passes ?gemm the 'T' flag for each operand whose orientation differs from C’s. ger on a row-major A updates A^T with x and y swapped. ger calls BLAS only when alpha’s type is no wider than A’s element type: ?ger takes 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_v and detail::ger_dispatches_blas_v say which calls reach BLAS. test_blas_layout_dispatch.cpp checks them, and the trmv/trsv traits, at compile time, and checks the result for every orientation mix against a long-double reference.
  • GCC’s float trmv and forward substitution on AArch64: no keep_scalar barrier, 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 trmv at 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.
    • gemv keeps the barrier: neutral on the Jetson, 1.66× faster with it on the Ventuno (5.51 against 9.14 ms). detail::keep_scalar_triangular_v is the triangular kernels’ predicate; x86-64 is unchanged.
  • thread_pool spins 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-LAPACK lu_factor opens 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_us before blocking. generation_ and remaining_ 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 now shared_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 1TVentuno 4T, before → afterJetson 6T, before → after
      lu 512²23.8 ms179.0 → 20.7 ms38.1 → 26.7 ms
      qr252 ms329.7 → 149.6 ms265.2 → 214.5 ms
      lq60.7 ms208.1 → 42.3 ms86.0 → 66.6 ms
      hessenberg353 ms744.6 → 205.8 ms379.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_relax and spin_step moved from spin_pool.hpp to thread_pool.hpp, so both pools use them. test_thread_pool no longer calls a Catch2 assertion on a worker thread, which ThreadSanitizer reported as a race.

  • The native-fast gemv on 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:

      machinedtypegenericnative-fast beforenative-fast after
      i7-12700Kf64 / f324.76 / 2.29 ms9.66 / 4.27 ms3.45 / 1.69 ms
      Xeon E5-2420 v2f64 / f3213.56 / 6.60 ms38.17 / 17.19 ms12.98 / 6.46 ms
      Jetson Orin Nanof64 / f3221.47 / 8.27 ms63.92 / 31.40 ms17.78 / 7.93 ms
      Arduino Ventuno Qf64 / f3210.06 / 4.74 ms47.52 / 22.77 ms7.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_gemv gains sizes across the strip boundaries; the old sizes stopped at 100 rows.

  • The generic gemv, trmv and 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: f32 gemv ran 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) and detail::lower_trisolve_column_sweep (each strip adds the solved columns, then solves its diagonal block column by column). detail/column_sweep.hpp holds the dispatch predicate and the strip size.

    • Speed: i7-12700K, n = 4096, one core, generic build:

      column-majorbeforeafter
      gemv f32 (mtl5_bench)19.1 ms, 9% of roofline2.24 ms, 78%
      gemv f64 (mtl5_bench)19.9 ms, 18%4.80 ms, 73%
      trmv f32 lower / upper8.46 / 6.79 ms1.68 / 1.57 ms
      trmv f64 lower / upper12.3 / 8.95 ms3.19 / 3.15 ms
      forward substitution f32 / f647.69 / 9.04 ms1.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_bench gains blas2/gemv_colmajor in f32 and f64.

    • Tests: op_test_trmv_trsv_interleaved checks 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, trmv and 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_scalar in include/mtl/detail/scalar_chain.hpp, an empty asm that 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-majorbeforeafter
      gemv, GCC -O33.05 ms2.71 ms
      trmv, GCC -O31.71 ms1.45 ms
      forward substitution, GCC -O31.65 ms1.42 ms
      gemv, GCC -march=native3.79 ms2.88 ms
      trmv, GCC -march=native1.76 ms1.51 ms
      forward substitution, GCC -march=native1.73 ms1.47 ms

      f64 and column-major times are unchanged. f32 gemv at 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_interleaved take 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, trmv and 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> in include/mtl/interface/interleave_rows.hpp, with Kernel one of interface::kernel::gemv, trmv and lower_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=W or -DMTL5_INTERLEAVE_ROWS=W (all types). CMake passes the last from the MTL5_INTERLEAVE_ROWS cache variable, which must be 1–64.
    • Measuring: the new bench_interleave_rows times 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 at MTL5_INTERLEAVE_ROWS=4: f64 gemv 3.85 → 3.75 ms (90% → 94% of the roofline), f32 gemv 3.69 → 3.05 ms (47% → 57%), f64 trmv 2.16 → 2.04 ms and trsv 2.13 → 2.03 ms (81% → 86%). f32 trmv and trsv are unchanged at about 52%.
    • Benchmarks: mtl5_bench gains f32 trmv and trsv entries.
    • Tests: op_test_trmv_trsv_interleaved checks 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 new op_test_interleave_rows_override checks that the defines reach the kernels. Both are built with -ffp-contract=off.
  • The generic trmv, forward substitution and gemv take four rows at a time, with results unchanged bit for bit (#749). Without BLAS or MTL5_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) and lower_trisolve (both overloads), so trsv with a lower A as well. The Accumulator paths 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. Upper trsv keeps its one-row loop.
    • Speed: mtl5_bench --class medium --filter blas2 in the generic build (f64, n = 4096, one thread) went from 42% to 87–92% of the bandwidth roofline for trmv and trsv, from 4.4 ms to 2.1 ms.
    • Test: op_test_trmv_trsv_interleaved compares 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, behind mult_generic and the threaded mult_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, f64 gemv went 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 wrapping int32 and a double A with a float y.
  • pc::ic_0 and pc::ildl apply in O(nnz), and pc::ilu_0 and pc::ilut set 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_0 and ildl apply (solve and adjoint_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_0 setup: 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.

    • ilut setup: 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, solve and adjoint_solve, the default and a long double accumulator, and three ILUT fill and threshold settings.

    • Results on the 2D 5-point stencil, one thread, i7-12700K:

      nic_0 applyildl applyilu_0 setupilut setup
      4,0969.3 → 0.037 ms3.7 → 0.021 ms5.5 → 0.39 ms9.0 → 4.1 ms
      16,384129 → 0.17 ms57 → 0.095 ms84 → 1.5 ms99 → 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+ilu0 becomes cg+ic0, CG with IC(0) as the textbook pairs them, which ILU(0) had stood in for. The pc/ic_0 and pc/ildl setup entries lose their 64² grid cap.

    • Memory: ic_0 and ildl with the default accumulator hold a second copy of L, by column. The accumulator path scatters and keeps none.

    • Test: test_pc_sparse_cost times 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.

  • trmv and trsv reach 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, while gemv reached the roofline in the BLAS and native-fast builds.

    • BLAS build: the dispatch took only a column-major A, so the default row-major dense2D never reached BLAS. A row-major A is now passed to ?trmv/?trsv as its buffer read column-major, which is Aᵀ: the other triangle, with trans = '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. For trmv the blocks go bottom-up (lower) or top-down (upper), so every x(j) read still holds its original value. For trsv they 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:

      buildngemvtrmv before → aftertrsv before → after
      BLAS (OpenBLAS 0.3.32)40969.50 (110%)3.79 (41%) → 8.81 (102%)3.80 (41%) → 9.22 (107%)
      BLAS (OpenBLAS 0.3.32)81929.32 (102%)→ 8.84 (96%)→ 9.09 (99%)
      native-fast40969.69 (100%)3.81 (41%) → 9.15 (94%)3.85 (41%) → 9.10 (94%)
      native-fast81929.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_fast compares 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-b trsv. 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.

  • gemmt runs through a full-speed GEMM on BLAS and native-fast builds, 2.8–3.7× faster (#744). It forms half of gemm’s product, but it was slower than a full gemm on every build. With OpenBLAS it called dgemmt, which takes about twice as long as OpenBLAS’s own dgemm. 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 ?gemm in a BLAS build and gemm_blocked otherwise.

    • When it applies: dense float or double operands of one type, in any orientation or as trans() views, with the default accumulator, n > 64, k > 0 and α ≠ 0. With a BLAS library other than OpenBLAS that has a working ?gemmt (MKL, BLIS), gemmt still calls it. With OpenBLAS, dgemmt is still used at 64 rows and fewer, where it is as fast as the alternatives. A BLAS build without ?gemmt now takes the blocked path instead of the generic loops.

    • Contract: the other triangle of C is never written before the mirror, and beta == 0 does not read C. Rounding is the GEMM’s, as for mult on these builds.

    • The mirror: gemmt_fill::mirror copies 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 as trans(A), with no copy. Below that it copies Aᵀ as before. With OpenBLAS it is unchanged up to d = 60 and 6–11% faster from d = 150.

    • Results: mtl5_bench blas3/gemmt, f64, one thread, i7-12700K, counting n³ flops:

      buildnbeforeaftertime vs gemm
      BLAS (OpenBLAS 0.3.32)51218.9 GFLOP/s52.3 GFLOP/s0.70×
      BLAS (OpenBLAS 0.3.32)102419.0 GFLOP/s60.4 GFLOP/s0.61×
      native-fast512about 14 GFLOP/s51.4 GFLOP/s0.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_blocked checks 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 with beta == 0 does not reach the result, and that alpha == 0 reads 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, trmm and symm run through the blocked GEMM (#724, part 3 of 3). With MTL5_NATIVE_FAST_GEMM and 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, and gemm_blocked handles the rest: B(I) := αB(I) − A(I, solved)·X(solved) for trsm, and B(I) += α·A(I, rest)·B(rest) for trmm, 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 one gemm_blocked call. beta == 0 still 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 mult on this build.

    • Results: mtl5_bench --class medium, native-fast build (Highway, -march=native), one thread, i7-12700K, in GFLOP/s:

      opbeforeaftershare of reference
      trsm1.7449.269% of gemm (71.4)
      trmm1.7743.561% of gemm
      symm1.0067.194% of gemm
      symv0.505.4454% of gemv (10.0), from part 2
    • Test: test_blas_blocked_native_fast checks 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_v traits.

      Each of 9 mutations of the block offsets, betas, ranges and order makes it fail.

  • The generic trsm, trmm, symm, symv, syrk and syr2k walk 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) and gemmt already 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=fast with an FMA target), which can fuse a different product in each form, as it can for mult’s i-k-j loop.

    • Results: mtl5_bench --class medium, generic build (no BLAS, no Highway), one thread, i7-12700K, in GFLOP/s:

      opbeforeafterreference
      trsm1.7014.5gemm 14.2
      trmm1.7313.7gemm 14.2
      symm1.0116.0gemm 14.2
      syrk5.5711.5gemm 14.2
      syr2k10.213.0gemm 14.2
      symv0.495.18gemv 4.05

      trsm f32 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_v traits;
      • covers alpha 0 and empty shapes.

      The test is built with -ffp-contract=off, like op_test_mult_ikj. symv now asserts that y doesn’t alias x.

  • trsm, trmm, symm, symv, syrk and syr2k call 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-major dense2D never 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 gemv and gemmt already do:

      • a row-major B makes trsm and trmm side 'R';
      • a row-major A flips op and uplo;
      • row-major B and C make symm side 'R';
      • a symmetric operand’s lower triangle is its row-major buffer’s upper one.
    • Mixed orientations: symm needs B and C in the same orientation, and syr2k needs A and B in the same orientation. Other mixes keep the generic path.

    • Results: mtl5_bench --class medium, OpenBLAS, one thread, i7-12700K:

      opbefore (GFLOP/s)after (GFLOP/s)gemm
      symm1.072.772.7
      trsm1.7563.172.7
      trmm1.7663.872.7
      syr2k10.957.272.7
      syrk5.753.272.7
      symv0.4517.59.8 (gemv)

      trsm f32 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_v traits, 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_rotation takes 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*b can neither overflow nor lose a term to underflow, about (2^-483, 2^510) for double, the rotation is r = 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_limits declares 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.
  • CI checks that mtl5_bench covers all of MTL5, and matrix results are checked on every entry (#721, milestone M7).

    • Coverage manifest: benchmarks/platform/coverage.txt maps 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.sh fails 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 --list doesn’t have;
      • an exemption with no reason.
    • DotK: a new entry, blas1/dot_k3, brings the catalogue to 107. It runs dot_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, sylvester and 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 double the same as double (tested with g++ -mlong-double-64), as on MSVC and Apple ARM64.
  • mtl5_bench covers 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 FILE reports 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.sh and platform.ps1 pass 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 small with Clang 18, with a 64-bit long 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_bench covers 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, and idr_s at 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 small with Clang 18, with a 64-bit long 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_0 and pc::ildl applies are quadratic in n: 131 ms and 57 ms per apply at n = 16384, against 0.14 ms for ilu_0. CG is therefore paired with ILU(0), the same incomplete factor on an SPD matrix, and the ic_0/ildl setup entries are capped at a 64² grid.
    • The pc::ilu_0 and pc::ilut setups are quadratic in n: 0.4 ms, 82 ms and 1.3 s at n = 1024, 16384 and 65536.
  • mtl5_bench covers 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 amd check that measured a fresh AMD call instead of the permutation under test. Timing-only entries now show n/a instead of 0%. All 66 pass at every class with GCC 15, and at small with Clang 18 and on aarch64 (NEON) under QEMU. Run time on an i7-12700K with one thread: small about 10 s, medium about 55 s, large about 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_klu 17 ms, supernodal_ldlt 9 ms). The entry runs QR on half the grid side until this is fixed.
    • sparse_cholesky: 73 ms, slower than sparse_ldlt (27 ms) and 8× slower than supernodal_ldlt. At the large grid the gap is 17× (900 ms against 52 ms).
    • supernodal_lu: 56 ms, slower than the non-supernodal sparse_lu (41 ms).
  • mtl5_bench covers 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 at small with Clang 18 and on aarch64 (NEON and SVE_256) under QEMU. Run time on an i7-12700K with one thread: small about 9 s, medium about 45 s, large about 4 minutes. Rates use the conventional LAPACK operation counts. The shared check helpers moved to benchmarks/platform/common.hpp.

    The first run found these gaps, which aren’t addressed here (medium class, generic build):

    • qr_factor is 10× slower than lq_factor for the same work: 217 ms against 22 ms at n = 512.
    • Bunch–Kaufman ldlt_bk is 7× slower than ldlt.
    • eigenvalue() defaults to a deflation tolerance of 1e-10. It therefore stops short of full accuracy, while schur() runs the same iteration at machine epsilon. The benchmark calls eigenvalue with tol = eps.
  • benchmarks/platform.sh and platform.ps1: characterize a machine with one command (#721, milestone M2). After a git clone, benchmarks/platform.sh does the whole job:

    • gates the session with preflight, before the builds and again after them;
    • builds mtl5_bench for the native, native-fast and (if a system BLAS is found) blas variants, 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 .sysinfo sidecars that carry the machine state, plus markdown capability cards and a summary.md.

    native-fast doesn’t use -march=native on SVE hardware, because of #720, or on macOS. A new CI job runs the script at --class small on Linux x64, Linux ARM64, macOS and Windows.

    mtl5_bench gains --card FILE and --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 the native and blas variants 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_bench is now built in CI. The benchmarks job’s target list didn’t include it, although the M1 PR said it did.
  • 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 the gamma_k error 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 FILE with a FILE.sysinfo provenance sidecar. benchmarks/check_sidecars.sh now 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: small about 5 s, medium about 20 s, large about 85 s.
    • First findings: in the generic build, symm, trmm and trsm reach 1–2% of the roofline at n = 512, against 25% for gemm. symv reaches 5% against 46% for gemv.
    • The remaining areas follow in later milestones of #721.
  • Fixed-length SVE support in simd::batch (#717). batch previously 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’s SVE2_128 and SVE_256), batch now 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=128 gets real SVE2 code with batch<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 scalar batch (#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 with aarch64-linux-gnu-g++ (or clang with MTL5_AARCH64_CLANG=ON) and makes ctest run every test through qemu-aarch64. MTL5_QEMU_CPU selects the emulated core, and with it the SVE vector length. Four presets go with it, each with a -simd test 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_256 had 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_256 at 128 or 512 bits crashes in every SIMD test.
    • SVE2_128 at 256 bits fails 6 of 11 tests, and passes the other 5.
  • Highway lanes on Linux ARM64 (#717). The highway job 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 marks SVE2_128 broken before Clang 21.
    • native, MTL5_NATIVE_ARCH=ON with GCC 13, running the SIMD tests. It confirms that -march=native on an SVE machine selects scalable SVE2, so batch falls 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), and test_batch fails to compile on any other target. test_batch also requires size > 1 on AArch64, as it already did on x86-64, except on a scalable target, where it pins size == 1 until #427. The Highway cache key now includes the architecture and the lane.

  • 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 the keep_scalar barrier 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’s nthreads_max on 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_128 needs I8MM and BF16 in the flags;
    • a fixed-length binary is tied to its vector length;
    • MTL5_NATIVE_ARCH=ON with 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.

  • mult with a zero inner dimension, on every kernel path (#714). mult assigns, 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_ikj now covers the rest: the generic GEMM’s row-major, col-major and trans() 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_ordering and test_householder_textbook dropped their local emul, and their bit-for-bit comparisons still hold. Each one was checked by breaking, for non-native types only, the code its double_shim cases 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 a double_shim assertion. Four tests keep their own type on purpose, with a comment saying why:

    • test_mult_generic_mt and test_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_requirement and itl/test_pc_field_requirement: emul has 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 accepts double_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_shim and double_shim are in tests/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_point or is_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_genericity runs 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 qualified std::frexp in the two_norm rescan (#700) makes it fail to compile. Gating that rescan on is_floating_point makes it fail at run time. Both tests carry the CTest label generic.

  • 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_symmetric scaled 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, and eigen_symmetric returns NaN eigenpairs.
    • The identity rotation for x = z = 0: a 3x3 fixed-point tridiagonal whose QR sweep rounds both to zero, for eigenvalue_symmetric_generic and eigen_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_signs on a complex L (test_qr), and randorth’s sign normalization (test_randorth): without qr_normalize_signs, Q(0,0) is negative on every draw.
    • Already covered: the Hessenberg and eigen_symmetric pivot signs from #678 and the subnormal Householder scaling fail existing tests when broken, so they needed none.

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_vector and dense2D compile 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’s try/catch, so the pool looked like the only blocker. Clang lists every error, and that shows the throws 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, defines MTL5_HAS_EXCEPTIONS from the compiler’s own flags; you can also define it yourself. thread_pool, spin_pool and the aligned allocator compile out their try/catch when exceptions are off. The containers’ throws go through detail::throw_or_abort, which calls std::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_noexc or pool_local_noexc instead of pool_shared or pool_local. The workers run worker_loop() as compiled where the pool was built, and without exceptions it has no catch. 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 an mtl5_pool built the other way. Two translation units built different ways each get their own pool rather than sharing one worker_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 -Werror on GCC and Clang, with bounds checking forced on. It runs once per pool mode, and it asserts that the pool is in the _noexc namespace. It runs in every Linux and macOS CI job. Against the old headers it fails on both compilers.
  • pow2_scaling’s fallback finds the right exponent at a tapered type’s coarse ends, in O(log |e|) (#680). givens_rotation, householder() and householder_reflector() scale by an exact power of two through math::pow2_scaling<T>. For a type without std::ilogb, its exponent(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_rotation at 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() and scale() 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 from double where 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_exponent for 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 cases givens_rotation returns the remedy’s c and s.
    • What changes: the std::floating_point types keep std::ilogb and std::ldexp, so their results are unchanged. A user-defined type gets the same exponent wherever the old search found the right one.
  • Householder factorizations store the reflector’s β as the pivot (#678). The default qr_factor, lq_factor and hessenberg_factor, and eigen_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_solve divided by it.
    • Found by the decompositions study (stillwater-sc/mp-numerics#20). After qr_factor, qr_solve divided 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.
  • 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 pwsh fails in LaunchServices with a timeout before it parses anything, and leaves orphaned pwsh processes, so bench_powershell_parse failed on main from the #679 merge on. The Linux and Windows runners still parse the same harnesses.
  • A daily QA sweep for scheduled runs: the /qa-sweep skill and the read-only qa-reviewer agent, synced into .claude/skills/ and .claude/agents/ from the qa-sweep plugin 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 labelled qa-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.baseUrl with the generated src/content/docs/ path, so every link went to a file that does not exist, such as docs/src/content/docs/getting-started/index.md. sync-content.mjs now gives each page an editUrl: docs/<page> for the synced and site pages, and the file itself for those synced from outside docs/: CHANGELOG.md, benchmarks/README.md and 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.

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.

  • 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 takes dlarfg’s sign, as LAPACK geqrf, 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 do lq_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‖, as zlarfg does.
    • 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_factor and the geqrf path 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) and lq_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::randorth uses 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.
  • Givens rotations scale by an exact power of two (#671, #673). apply_givens_rotation (GMRES’s Hessenberg QR), MINRES, and eigenvalue_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 lapy2 max-scaling and dlartg safe 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_symmetric of 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.
  • math::pow2_scaling<T>, math::givens_rotation and math::scaled_hypot (<mtl/math/pow2_scaling.hpp>, #673). pow2_scaling<T> is a customization point with exponent(m) and scale(x, k).
    • The built-in floating-point types use std::ilogb and std::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).
  • qr_normalize_signs(Q, R) and lq_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-14 on 2026-11-02 and fails jobs on it during scheduled brownouts until then (actions/runner-images#13518). The base job moves to macos-15, and the “latest” job from macos-15 to macos-26. mtl5-python and universal_dtypes moved too, with their wheels’ MACOSX_DEPLOYMENT_TARGET pinned at 11.0, the tag of every macOS wheel they have published.
  • The history of Givens rotations and Householder reflectors (docs/algorithms/givens-householder-history.md, #667), from Jacobi and Givens to LAPACK’s dlartg and dlarfg.
  • 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 in qr_factor’s order (#670).

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 with normest1.

    • θ_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_epsilon and detail::unit_roundoff (<mtl/detail/unit_roundoff.hpp>) measure the epsilon of a type without numeric_limits; default_eigen_tolerance delegates 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 without numeric_limits. docs/algorithms/matrix-functions.md covers what a matrix function is, how MTL5 computes this one, and its history.
  • schur, the real Schur decomposition, and rsf2csf (#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() into detail/francis_qr.hpp. The eigenvalue-only form is the old loop, and eigenvalue() 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’s dlanv2. hessenberg_extract_Q forms the Hessenberg reduction’s Q.
    • Generic: the in-house path uses only + − × ÷, comparisons, and abs and sqrt found 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 LAPACK gees.
  • sylvester and sylvester_triangular: A X ± X B = C (#650, #657). sylvester_triangular takes A and B in Schur form and runs the block back substitution of Bartels–Stewart, as LAPACK trsyl does, solving each block of at most 2×2 unknowns with complete pivoting (dlasy2). Pivots at or below trsyl’s smin are replaced by it and reported in the result’s perturbed flag. sylvester reduces general real A and B with schur, transforms C, solves and transforms back.

    • Real or complex, any element type; dense float/double and complex<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 with std::invalid_argument. sylvester_triangular_scaled returns {X, scale, perturbed} with A X ± X B = scale · C, as trsyl does.
    • 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. See docs/algorithms/sylvester.md.
  • gemmt, the triangular-output product, and congruence (#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 of mult, and mirrors it (the default) or leaves the other triangle (gemmt_fill::keep). B may be dense, trans() of one, or trans() of a compressed2D, 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 to mult, and an Accumulator sums each entry as mult<Acc> does.
    • congruence(A, P, C) computes C = A P Aᵀ as T = A P with mult, then gemmt(T, Aᵀ); A may be dense or compressed2D, and dense and CRS A give the same bits. The α/β form accumulates, and congruence(alpha, K, r, beta, C) computes α K diag(r) Kᵀ + βC for the Joseph form’s K R Kᵀ term.
    • BLAS: ?gemmt is an extension, so configure links and runs a small dgemmt_ call and defines MTL5_BLAS_HAS_GEMMT only if the answer is right. OpenBLAS 0.3.26 (Ubuntu 24.04) exports it with its lda/ldb checks swapped and rejects valid calls, so on it gemmt keeps 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): generic congruence takes 1819 µs against 3542 µs for mult(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 passing trans(A), which mult cannot hand to BLAS. With A = Φ ⊕ I as a compressed2D, it takes 60 µs. Adopters moving from mult plus (C + Cᵀ)/2 see last-bit differences.
  • The thread pool is public API: mtl::parallel::thread_pool, with pool() and configure() (#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 in docs/algorithms/on-node-threading.md:

    • the caller runs tid 0, and run blocks until every tid completes;
    • every task’s writes happen-before the caller’s next action;
    • nested or concurrent regions run serially.

    mtl::detail::thread_pool and <mtl/detail/thread_pool.hpp> remain as aliases, so existing callers compile unchanged.

    • run() and parallel_for() no longer allocate, whatever the task captures. The task used to be copied into a std::function, once by run and 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 global operator new to check this with a 256-byte capture. parallel_reduce and parallel_accumulate still 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, overrides MTL5_NUM_THREADS, is clamped to the hardware concurrency in the same way, and returns false once the pool exists. Before this, an application had to setenv before first use.
    • A per-call team cap. parallel_for, parallel_reduce and parallel_accumulate take max_threads before the body (0: the whole pool), so a caller can run below the pool’s size without partitioning by hand through run. 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).
  • One thread pool across shared libraries: MTL5::shared_pool (#639). Header-only MTL5 gives each shared object built with -fvisibility=hidden and 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 from MTL5_NUM_THREADS, and configure() reached only one of them.

    • The new CMake option MTL5_SHARED_POOL_LIBRARY (default off) builds and installs mtl5_pool, a small shared library that holds the process’s one pool. Modules that link MTL5::shared_pool get MTL5_SHARED_POOL defined. Their pool() and configure() then use that pool, looked up once per module, so run() 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.
  • 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’s nthreads_max and SPQR’s SPQR_nthreads are capped where cholmod_common has 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.md describes the two working setups, either MTL5 threaded with OPENBLAS_NUM_THREADS=1 or 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() and detail::on_pool_worker(), shared across modules under MTL5::shared_pool.
  • mtl::parallel::spin_pool: a pool for callers in a real-time loop (#636, #647). It has thread_pool’s interface and contract, but nothing in run() 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::wait is a futex on Linux and WaitOnAddress on Windows.
    • Selecting it: -DMTL5_POOL_SPIN makes mtl::parallel::pool(), and so MTL5’s kernels, use the process-wide spin_pool, as a direct call with no virtual dispatch. The environment variable MTL5_POOL_SPIN sets the spin in iterations (default 4096, about 140 µs on an Alder Lake P-core; 0 sleeps at once). Under MTL5::shared_pool the spin pool is shared across modules too.
    • Kernels now call parallel::pool() instead of thread_pool::instance(); without the macro that is the same pool. The chunked loops are shared detail:: function templates, so a kernel partitions its work identically on either pool, and thread_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 against thread_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, calling thread_pool::instance() directly starts a second pool beside the kernels’ pool; go through pool().
  • Arduino Ventuno Q benchmark profiles (#642, #644): a blocking A/B profile pinned to the board’s Cortex-A78C cores (found from /proc/cpuinfo rather 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> sets mr alone so a sweep holds the cache blocks fixed.

  • 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_traits gains acc_vectors, and aarch64 now gets 32 registers with a 16-accumulator budget.
    • Measured on the Ventuno Q (4× Cortex-A78C, mr swept at fixed nr/kc/mc/nc, geomean ratio to mr = 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 a tile6 arm remain measurable.
  • ldlt_factor no longer reports a zero pivot that ldlt_bk_factor and cholesky_factor don’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 on A(j,j) and returned j + 1, while ldlt_bk_factor factored the same matrix without an interchange. The default paths of ldlt_factor and ldlt_h_factor now do what their comment always described: form v(k) = L(j,k) * D(k) (conjugated for LDLᴴ) once per column, and subtract L(·,k) * v(k). That is the association ldlt_bk_factor and 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’s D now matches ldlt_factor<T>’s bit for bit (L still 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.
  • 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 mult with k = 0 did not zero C under BLIS. Every leading dimension is now at least 1.
  • analyze_blocking_ab.py called 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_dense sums 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, where mm_read and 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 the sylvester accuracy 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>, whose sqrt is accurate only to double (stillwater-sc/universal#1846), goes from 29 to 2.5 ε in the sylvester table. Found by building mtl5-python against the release candidate.
  • One thread pool per process or one per component (docs/design/concurrency-runtime-ownership.md, #638): the design question behind MTL5::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), the schur section of docs/algorithms/eigenvalues.md (#655), docs/algorithms/sylvester.md with the accuracy table remeasured after #658 (#657, #659), and docs/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.

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-only Matrix over block-quantized storage (#629), parameterized by the new BlockScheme concept: block geometry (block_size, block_bytes) plus a reference decode of one block’s raw bytes, and optionally decode_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 decoded float; block(r, b) and row(r) expose the encoded bytes.

    • Operations: convert to a dense matrix and mult(A, x, y) / A * x decode a row at a time, threaded over rows and independent of the thread count. A scheme can plug in a fused gemv by specializing mtl::block_kernels<S>, which mult uses for contiguous float vectors with no explicit Accumulator. The kernel’s working memory (typically the quantized x) is the caller’s: mult(A, x, y, scratch) passes it through, sized and aligned by block_gemv_scratch_bytes<S> and block_gemv_scratch_alignment<S>, and mult(A, x, y) allocates it for the call.
    • In-tree OCP MX schemes, Universal-free: mx::mxint8 (E8M0 scale plus 32 × INT8, q/64) and mx::mxfp4 (E8M0 plus 32 × FP4 E2M1, in GGML’s block_mxfp4 nibble 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.
  • simd::reduce_dot_block_scaled: block-scaled integer dot products (#628). Computes Σ_b scales[b] · Σ_{j∈b} a_j·x_j over 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 takes reduce_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>::convert from int32_t and uint32_t lanes, rounding as static_cast does. widen_dot_accumulate and quad_dot_accumulate are 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 one reduce_dot_widen per block in cache, and 1.15–1.4× faster at 4096×4096; at block 256 the two match. The numbers and their limits are in docs/algorithms/mixed-precision-kernels.md.
  • #458 before/after profiles benchmarks/machines/{xeon-e5-2420,i7-12700k,ryzen-9-8945hs}-mc.sh and a legacymc benchmark arm, with the three machines’ data under benchmarks/data/*-mc458.

  • The threaded GEMM chooses its ic step by micro-panels (#458, #626). The serial path rounded mc down to whole mr-row panels; the threaded path rounded the ic block count up to a multiple of the thread count and kept whatever mc came out, so every block carried a padded partial panel. The Xeon’s shipped threaded mc = 32 against mr = 6 ran 5.33 panels padded to 6. This is what made #458’s multi-threaded mc curve W-shaped. The busiest thread’s panel count fits that curve at r = +0.83; the block-count balance balanced_mc optimised fits at +0.23.
    • Rule: in the threaded path, balanced_mc keeps the block-count result unless a block size in [ceil(mc_max/2), mc_max] gives the busiest thread strictly fewer panels (new detail::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 and mr = 1 callers are unchanged. MTL5_GEMM_LEGACY_BALANCED_MC restores 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.
  • run_blocking_ab.sh called default and legacymc a consistency pair (#626). It compared configured kc/mc only; it now also keys on every row’s mc_used. It also refuses an arm CSV with no complete data record, which previously compared equal to another empty one.

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 for float and double;
  • 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_factor and ldlt_bk_solve take a leading Accumulator = void. A non-void accumulator skips LAPACK (interface::accumulator_allows_blas_v).

    • LU and Bunch–Kaufman change loop order for it. Their void factorizations 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 the ipiv encoding are the same as the void path’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, as lower_trisolve does, 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 inv n = 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.
  • Accumulator policy for the incomplete-factorization preconditioners (#597, #598, #600, #603). pc::ilu_0, pc::ic_0, pc::ilut and pc::ildl take a trailing Accumulator = void, the class-template convention pc::ssor set.

    • 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 the void path 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 leading Accumulator = 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 void bits, except that an entry whose only nonzero contribution is a −0 product comes back +0.
  • Accumulator policy for svd and null_vector (#606). Every overload takes a leading Accumulator = 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 skips gesdd and geqrf. The finding is no ordering: Jacobi’s error comes from applying the rotations, not from the inner products that choose them.

  • Accumulator policy for sum and trace (#607). Each element goes through add_product(acc, x, 1), which is exact for every number system, so the protocol needs no add primitive. 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_eigs and sparse_eigs_shift_invert take a leading Accumulator, and shift_invert_operator takes 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 through mult<Accumulator>.
  • Accumulator policy for multigrid (#608). restrict and prolongate take a leading Accumulator, and multigrid<Value, Accumulator> passes it to both transfers in the V- and W-cycles and to the cycle residual r = b − A·x, formed in the b − Σ 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_norm and frobenius_norm with an explicit Accumulator split across thread_pool when mergeable_accumulator<Acc, Value> holds, combining partials with accumulator_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 new detail::parallel_accumulate and detail::accumulate carry it.
  • math::exact_accumulator<T> (#612, #611), in include/mtl/math/exact_accumulator.hpp. The test-only Kulisch accumulator of #589 moves into the library: an exact sum of products of float or double, 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: V must be exactly representable in T. long double is excluded.
    • Integration: it plugs in through the ADL hook, so every accumulator-aware operation takes it, and its merge is exact.
    • Docs: docs/architecture/exact-accumulator.md.
  • Error-free transformations (#614), in include/mtl/math/error_free.hpp: two_sum, fast_two_sum, Veltkamp split, two_product_dekker (exact up to max by rescaling) and two_product (FMA, moved from accumulator_traits.hpp, which includes the new header; split_product is kept as an alias). Each returns exact_pair<T>{hi, lo}.

    • split and two_product_dekker switch FP contraction off locally, since GCC’s -ffp-contract=fast otherwise turns split into (a, 0) on any FMA target. Their test is built with -ffp-contract=fast so the ARM64 runners exercise the guard.
    • -ffast-math is unsupported. See docs/architecture/error-free-transformations.md.
  • math::compensated_accumulator<T>, configuration 2c (#615). This is Ogita–Rump–Oishi Sum2/Dot2 as an accumulator, holding two Ts. The result is as accurate as twice the working precision, rounded once. mtl::dot with 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) and dot_k<K>(x, y) (#616), in include/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> and dot_k<2> give the same bits as compensated_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_product takes two factors, so the L·d of each L(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 pass two_product’s lo, 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_numeric and supernodal_ldlt_numeric. Bunch–Kaufman feeds stored Schur columns and is unaffected.
    • Trait coverage: it holds for an IEEE Value with 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.
  • generators::gen_dot and gen_sum (#617), in include/mtl/generators/ill_conditioned.hpp: the Ogita–Rump–Oishi Algorithm 6.1 GenDot and its derived ill-conditioned sums. exact_accumulator serves as the paper’s DotExact. Each returns the exact result rounded to nearest and the achieved condition number. A seed reproduces the same vectors with any standard library. See docs/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.md plots 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, sum and svd, plus determinism. The rows are tagged [586:*] so the peer repos’ quire rows can name them.

    • Theorem tests: test_ogita_rump_oishi asserts 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.
  • A non-void Accumulator now reaches the eigensolvers’ matrix-vector product (#593, #591). power_iteration, lanczos and arnoldi take a leading Accumulator. When A is a Matrix, ev_matvec now forms w with mult<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_iteration with the exact accumulator now converges, to 8.0e-6, where all configurations previously stalled at 5.4e-3.
    • void and matrix-free operators keep A * x, byte-identical.
  • Threaded accumulator reductions regroup by chunk (#584). With MTL5_NUM_THREADS > 1, a rounding accumulator such as a wider type or fma_accumulator in dot, dot_real, two_norm or frobenius_norm now gives bits that depend on the thread count. This is the contract the threaded float/double reductions 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 direct accumulator_traits specialization 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× for double/plain, 4.6× for fma_accumulator and 8–15× for float into a double accumulator.
    • 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.
  • itl::idr_s accepts any linear operator (#624): its Matrix LinearOp constraint is now typename, 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 a Matrix, so an operator with only operator* stopped compiling in all ten solvers.
    • Fix: the new itl::apply_operator and apply_transpose (in itl/krylov/apply_operator.hpp) send a Matrix through mult<Accumulator> exactly as before, and apply anything else as A * x. bicg and qmr use a matrix-free trans(A) found by ADL.
    • Accumulator contract: a non-void accumulator reaches only the dot products around a matrix-free operator, the contract ev_matvec has.
    • 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_transpose past a temporary trans(A); it fails under AddressSanitizer without the lifetime fix.
  • pc::ilut back substitution counted the diagonal twice (#599). This is the #323 bug ilu_0 once 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) = −3 for b(0) = 1. The diagonal now lives only in u_diag_.
  • pc::ilut::adjoint_solve applied 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_0 and pc::ildl adjoint_solve applied M⁻¹ for complex values (#601). Both factor L·Lᵀ (L·D·Lᵀ) without conjugation, so a complex Value models a complex symmetric matrix, whose adjoint is conj(M), not M. The adjoint identity was off by up to 1.2. solve and adjoint_solve now share apply<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 from math::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.
  • 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.md is reconciled with the threaded kernels.
  • docs/design/iterative-solvers-architecture.md documents the matrix-free operator contract (#624).

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_traits through free functions found by argument-dependent lookup (#581, #582). When an accumulator’s own namespace provides accumulator_clear, accumulator_assign, accumulator_add_product and accumulator_value(acc, std::type_identity<R>{}), the adl_accumulator concept is satisfied and a constrained specialization forwards each operation to them. accumulator_merge is 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 beside quire (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) and sparse_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_value takes a std::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 with Value.
  • accumulator_traits::merge(a, b) combines two partial accumulators of the same reduction: an ordinary add for plain accumulators and fma_accumulator, and accumulator_merge for an ADL accumulator, which has no merge() 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 on thread_pool is tracked in #582.
  • Tests: test_accumulator_adl_hook uses 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, merge for 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.
  • docs/other/elemental-architecture.md (#578) surveys Elemental: the DistMatrix distribution 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 and merge above.

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 full svd(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 full svd bit for bit. With LAPACK, dense2D<float/double> goes to gesdd in its thin mode, 'S', as the full svd uses '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. The null-vector benchmark suite gains a svd_thin arm, whose answer is checked like the others.

    • Refactor: U’s basis completion moved into detail::complete_orthonormal, shared by both overloads. The full svd’s arithmetic is unchanged.

    • Tests: test_svd_thin checks:

      • bit identity with the full svd for m ≤ n;
      • agreement to rounding in long double on 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;
      • double against the full svd in either build;
      • rank-deficient, zero and empty inputs.

      Skipping the reflectors, applying them in the wrong order, or skipping the completion each fails it.

  • 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 their solve() methods summed in plain Value, 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.hpp take a leading Accumulator = void, the convention #542 set: level_scheduled_lower_solve<Acc>(L, s, x). With void they run the original loop. With an accumulator, each row’s whole b[i] − Σ T(i,k)·x[k], b[i] included, goes through accumulator_traits (assign, then add_product of 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 to cholesky_numeric, ldlt_numeric, lu_numeric, supernodal_lu_factor and supernodal_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-shot sparse_{cholesky,ldlt,lu,qr}_solve<Acc> and supernodal_{ldlt,lu}_solve<Acc> pass Acc to both the factorization and the solve. With the default void, 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_refined wrappers, which use the default solve.

    • Note: the LU solve uses mtl::math::accumulator_traits, as Cholesky, LDLᵀ and QR do. A specialization of only the sparse::factorization::accumulator_traits alias is not picked up by lu_numeric::solve<Acc>.

    • Tests: test_solve_accumulator_policy checks:

      • void and Acc == Value against the dense_* references, bit for bit;
      • a float row where 1 − 10⁸ + 10⁸ cancels to 0, which gives 1 with a double or fma_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*b into an FMA differently in the gather and the scatter, so the target is built with -ffp-contract=off, as trisolve_level_schedule_mt is (#381). The FP-contract lane found this on the first push.

  • The one-sided Jacobi core behind svd is 1.3–3.6× faster, and its results change in the last bits. It is shared by the generic svd(A, U, S, V), the V-only svd(A, s, V) and null_vector. The LAPACK gesdd path 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 in double). 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 a std::numeric_limits specialization always takes the scaled path.
    • Speed: median µs from bench_all --suite null-vector, old core against new, run alternately.

      m × Nnull_vectorfull svd
      16 × 924 → 6.646 → 13
      64 × 933 → 9.71,025 → 448
      400 × 933 → 27238,000 (unchanged)
      16 × 1227 → 1338 → 18
      64 × 1231 → 16521 → 452
      400 × 1262 → 46239,000 (unchanged)

      At m = 400, QR dominates null_vector and the completion of U to m × m dominates the full svd.

    • 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’s float accuracy table in docs/algorithms/eigenvalues.md is unchanged within noise.

    • Tests: a new case in test_svd scales 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.

  • svd throws when LAPACK’s gesdd fails, instead of returning whatever its buffers held. The LAPACK path of the full svd(A, U, S, V) ignored gesdd’s info, so a NaN in A, which LAPACK 3.10+ rejects with info = -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 thin svd now check info after the workspace query and after the decomposition, and throw std::runtime_error on a nonzero value, as eigenvalue does for geev. The generic path is unchanged. A LAPACK-only case in test_svd_thin passes a NaN to both and requires the throw; it fails against the previous header. Found by CodeRabbit on #575.

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, householder and apply_householder_left/right have taken an Accumulator (#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, eigenvalue and eigen now take a leading Accumulator = void, following #542’s convention (qr_factor<Acc>(A, tau)), and forward it to every Householder call. qr_solve also 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, syev for real and heev for complex Hermitian matrices, geev), since LAPACK’s sums are its own. With the default void, every call runs exactly the code it ran before. The QR iterations, the Givens rotations and eigen’s inverse iteration keep plain arithmetic: they work on fixed 2- and 3-term expressions or are outside the Householder path. test_householder_accumulator_callers counts the accumulator’s add_product calls 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 the heev branch, which CodeRabbit found ungated in review. Measured on random 256 × 256 float matrices, accumulating in double lowers QR’s backward error ‖QR − A‖/‖A‖ from 6.8e-7 to 3.7e-7. On the same matrices qr_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} as eigen_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 for eigen_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. tol defaults to ε and max_sweeps to 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. Header operation/eigenvalue_symmetric_jacobi.hpp, included from mtl.hpp.

    • Tests: test_eigen_symmetric_jacobi checks:

      • reconstruction and orthogonality for n = 1…16, in double and float;
      • 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 double reference where long double is wider than double;
      • zero eigenvalues and trivial sizes.

      Mutating the stop to the Frobenius test, or squaring entries in the pair test, fails the suite.

    • Benchmark: a new bench_all --suite eig-small (not part of all) times it against eigen_symmetric and svd for n = 3…16. At n = 9 it takes 11–12 µs, against 4–5 µs for eigen_symmetric and 14–23 µs for svd.

    • Docs: docs/algorithms/eigenvalues.md covers when to choose it, which was item 3 of #565.

  • svd(A, s, V), a V-only SVD with QR preconditioning, and null_vector(A) (#566). The full svd(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 svd on 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 full svd bit for bit.

    • Speed: median times in µs, measured by the new bench_all --suite null-vector (not part of all).

      m × Nnull_vectorfull svdeigen_symmetric(AᵀA)eigen_symmetric_jacobi(AᵀA)
      16 × 922395.59.9
      400 × 934238,5431518
      400 × 1261239,7322636

      It is slower than the AᵀA eigensolvers but does not square A’s condition number. In float on 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 full svd’s bits, so it is left for a separate change.

    • Backend: both calls always use the generic C++ path, since LAPACK’s gesdd has no V-only mode.

    • Refactor: the one-sided Jacobi loop moved into detail::one_sided_jacobi, shared by all svd overloads. The full svd returns bit-identical results to before.

    • Tests: test_svd_null_vector covers bit identity for m ≤ n (in long double, so a LAPACK build compares generic against generic), and agreement to rounding on graded tall cases. It also checks that null_vector recovers 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.

  • eigen_symmetric, eigenvalue_symmetric and eigenvalue_symmetric_generic default tol to machine epsilon and use LAPACK dsteqr’s deflation test (#565). Results change: the in-house symmetric eigensolver returns different bits for most inputs. The LAPACK syev/heev path is unaffected, since it ignores tol. The default was 1e-10, which capped accuracy far short of what the method reaches, the same problem svd’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 default tol, 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. With tol = 1e-10 passed explicitly, the new deflation test alone lowers the error from 8.4e-12 to 2.0e-12. With tol = ε 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’s eigh and eigvalsh pass tol = 1e-10 explicitly, so only the deflation change reaches them. spectral_properties uses the default. New tests in test_eigen_symmetric fail against the old header: a 2 × 2 case with tol = 1e-6, where the old test returned the small eigenvalue 2.5e-5 relatively wrong, and a null-vector case at the default tol. A third test checks that exactly zero eigenvalues still deflate under the stricter test. A custom real without a std::numeric_limits specialization reports epsilon() as zero, which would deflate only exact zeros: about a third of random 10 × 10 matrices then ran out of max_iter with eigenvalues ~5e-8 off, unreported. For such a type the default is measured instead (the spacing at 1, found by halving), and a non-positive tol maps to the default, as in svd. Found by CodeRabbit on #568.
  • CMake declares a 3.22...4.2 policy range (#571), in CMakeLists.txt and ppe/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 identical CMAKE_CXX_FLAGS* and no warnings.

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{}) and lq_factor(A, tau, tag::textbook_reflector{}), and the same tag on householder, apply_householder_left and apply_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 update f = (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, and apply_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 tagged qr_factor never dispatches to LAPACK. Its R, on and above the diagonal, is bit-identical to a textbook QR, signs included. Below the diagonal and in tau it stores the same reflector in MTL5’s packed form (v/v(0), τ = 2v(0)²/vᵀv), so qr_extract_Q and qr_solve work unchanged, with Q matching the textbook Q to rounding. The tagged lq_factor is its row mirror: L, on and below the diagonal, is bit-identical to a textbook LQ, and lq_extract_Q works unchanged. The default overloads are unchanged. Real element types only. The tag lives in <mtl/tag/reflector_form.hpp>. test_householder_textbook checks each tagged path against reference textbook loops with == on double, float and 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.md covers the why, what and how.
  • qr_solve skips 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_solve applied it anyway as y -= 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 textbook qr_factor leave τ = 0 for such a column. qr_extract_Q already skipped it, since apply_householder_left returns early on a zero τ. Finite inputs are unaffected, except that a zero in y can no longer change sign through y − 0. Found by CodeRabbit on #560.
  • The regression test tier is documented in Getting Started → Build Options (#561). It covers MTL5_BUILD_REGRESSION_TESTS, how to run the tier with the ci-regression preset and the regression CTest label, and what each of the 14 programs in tests/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-platform build job.

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.

  • The generic dense GEMM runs as an i-k-j loop when B and C are row-major (#549). detail::mult_generic_rows was 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 adds A(r,k) * B.row(k) for each k. That inner loop is contiguous and independent, so it vectorizes. Each C(r,c) is still built as zero plus the products in ascending k with the same generic_fma, so results are bit-identical for every scalar type when the compiler does not contract acc + a*b into 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_ikj compares bits against the old loop, including -0 and infinities, and is built with -ffp-contract=off like the other bit-identity tests. Other layouts and the custom-Accumulator path 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_factor forms each entry as a − (Σ 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, and tag::subtract_sum names the default explicitly. The tags live in <mtl/tag/summation_order.hpp>. test_cholesky_ordering checks the opt-in against a reference term-by-term loop with ==, on double, float and 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 reads A(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 instantiates is_row_major_v for operands without an orientation. Before, that was a compile error for a compressed2D or transposed_view operand. 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_factor rejects a NaN pivot (#556). The generic path tested diag <= 0, which is false for NaN, so a NaN in A returned 0 (success) with NaNs in L. It now tests !(diag > 0), as cholesky_h_factor already did, and returns k+1 for a NaN pivot in either summation order. Finite inputs are unaffected. The LAPACK path’s behaviour is potrf’s own.
  • 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 is benchmarks/bench_mult_ikj.cpp and the figures come from benchmarks/fig_mult_ikj.cpp. Both are registered under MTL5_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 instantiated M::orientation on types without one, and a test that assumed mult() 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.yml ran its whole matrix, unit and regression, for a commit that touched only docs/. It now has paths-ignore for docs/, docs-site/, Markdown, images, LICENSE, .coderabbit.yaml and .nojekyll; docs.yml still 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 on main and 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 with gh workflow run ci.yml --ref <branch>. No check is required by name, so a docs-only PR stays mergeable.
  • CI action bump: actions/setup-node 7.1.0 (#553).

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 / scalar and their vector forms accept any non-container Scalar (#548, resolves #538). The six operators were gated on std::is_arithmetic_v<S>, which rejected posits, cfloat, LNS, fixed-point and std::complex, even though all of them satisfy mtl::Scalar and mtl::Field. It turned up in a Kalman filter over posits: K = P H^T / S did not compile. The gate is now !Collection<S> && Scalar<S>. The !Collection check comes first and short-circuits, because evaluating Scalar<S> for a matrix or vector operand would recurse into these same operators. matrix * matrix, matrix * vector and 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, lanczos and arnoldi tests, a float accumulator and a double one 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. A float accumulator gets exactly 0, a double accumulator 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.
  • Session log for 2026-10-09 – 2026-10-10: docs/sessions/2026-10-10-every-test-overrode-the-default.md. Covers the leading-Accumulator convention (#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 overrode clear(), 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 a float accumulator from a double one, since both only need to reach a 1e-4 floor. CodeRabbit noted this on #540.

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-initialized Acc (#544). clear() reset with a = 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’s lns{} is 1.0, and every sum of products over an lns accumulator started at 1. 5.13.0 made this reachable without opting in: #537 routed householder()’s sum of squares through clear() on the default path, where 5.12.0 had started it at mag_t(0). As a result QR and LQ over lns were 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 assigns math::zero<Acc>(). fma_accumulator had the same flaw in its clear() and in its member default T 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 specialized accumulator_traits, so none exercised the primary template. The new regression test uses a mock type whose value-initialization is 1.

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.

  • 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 leading Accumulator = void in front of Scalar S. A 5.12 call that fixed the scalar type explicitly, e.g. axpy<float>(0.1, x, y) meaning “convert alpha to float”, still compiles and now means “accumulate in float, alpha stays double”. Results can differ with no diagnostic. To keep the old meaning, convert the argument instead: axpy(float(0.1), x, y). Explicit lists on trmv, trsv, lower_trisolve and upper_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, tfqmr and idr_s had 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 now itl::cg<Acc>(...). Old full lists fail to compile. Downstream: mp-iterative updated in its #44.
  • Sparse numeric factorizations take a leading Accumulator, defaulting to void (#542). sparse_lu_numeric, native_klu_factor, supernodal_lu_numeric and supernodal_ldlt_numeric had Accumulator = Value last, 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 now supernodal_lu_numeric<float>(A, sym). A leading default cannot name Value, so the default is void, resolved to Value inside; 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 in mtl5_sparse_direct.cpp need 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 a void default that means “accumulate in T”. 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: axpy and scale (#511). axpy is a one-term sum of products seeded with y(i) rather than zero, so it is the first caller of the contract’s assign. A test asserts the operation counts directly (axpy drives assign and never clear; scale the reverse), which turns #261 Part A’s “audit the call sites” from a reading into a check. scale sums 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 before add_product.
  • Accumulator policy for BLAS L2: ger, symv, trmv, trsv (#515, #516). gemv was already covered through mult. trsv delegates its reduction to lower_trisolve/upper_trisolve, so both trisolve headers carry the accumulator too. trsv’s BLAS dispatch is now gated on accumulator_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/beta and the triangular division are applied afterwards, outside the accumulator. The upper-triangle mirror in syrk/syr2k is a plain copy, not a re-sum.
  • Accumulator policy for sparse_cholesky, sparse_ldlt and sparse_qr (#530, #531, #534). This completes the sparse direct line alongside sparse_lu, native_klu, supernodal_lu and supernodal_ldlt. In sparse_ldlt the per-term square is still rounded in Value before 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 in apply_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 from qr/lq/svd: qr calls apply_householder_left without 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’ tol is non-deduced (#540). It is now std::type_identity_t<T>, so power_iteration(A, v_float, 1000, 1e-6) compiles. T comes from the vector alone; before, a double literal tolerance conflicted with a float vector in deduction.
  • SIMD scalar tails round the way the vector body does (#513, resolves #512). reduce_dot, reduce_dot_widen, reduce_sum_squares and axpy used fma() in the vector body and a plain multiply-add in the scalar tail, so an element’s rounding depended on its index. For axpy, where every element is an independent output, the first W·⌊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’s MulAdd branch instead failed on clang + Highway, and a decomposed c + a*b could 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_generic builds on glibc 2.43 (#541). glibc now declares C2y’s uabs in <stdlib.h>, which made the test’s own uabs ambiguous on GCC and Clang. It is renamed abs_as_u32 and the reference helpers moved into mtl::test.
  • 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-release 3.0.3 (#520), actions/deploy-pages 5.0.1 (#519).

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.

  • mtl::itl requires a Field element type — solvers, preconditioners and smoothers (#503, #505). Every Krylov solver computes its step lengths as ratios in the element type: cg’s beta = rho / rho_1 and alpha = rho / dot(p, q), ten such divisions in qmr, eight in tfqmr, at least two in every one of the ten including cgs and gmres. 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, so pc::ilu_0<int> M(A) truncated its factorization at construction and a solver gate would never have fired. This is #450’s lu_factor(dense2D<int>) one and two levels up: ℤ is a ring, not a field. New FieldVector (the vector counterpart of FieldMatrix) gates the eleven solver entry points including gmres_inner; FieldMatrix and Field<Value> gate the eighteen preconditioner and smoother types. What breaks downstream: integral element types in itl no longer compile. Every affected call site was already wrong — for diagonal, jacobi, gauss_seidel and sor it was worse than truncation, since value_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 unaffected
  • ilut’s threshold parameter is the real magnitude type, not the element type (#505). magnitude_t<Value>, which is Value for every real element type, so real users see no change. It was Value, which made abs(w[k]) < drop_tol compare a double against a complex<double>: ilut<complex<double>> named a valid type whose factorize() did not compile
  • Threaded dense GEMV and GEMM for non-BLAS scalar types (#446). is_blas_scalar_v gated 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 of MTL5_NUM_THREADS. New ThreadableDenseMatrix / ThreadableDenseVector carry 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 into gemm_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, but detail::mult_sparse_crs — the accumulator-aware kernel mult(compressed2D, x, y) dispatches to, and the one a mixed-precision sweep calls — ran it serially. The gather from x is 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 a double SpMV is memory-bandwidth-bound and the cores have nothing to do
  • parallel_chunk_units<T> and row_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_for caps the team at n / grain chunks, 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) is 65536 / 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 of balanced_mc), the two mediators grid_imbalance and packed_b_bytes recorded per point by bench_blocking_ab, models M0–M5 as pure functions, and sweep_nc_models to enumerate offline where they disagree. balanced_nc is 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_nc first rounded the balanced nc up to a multiple of nr, which undid the balancing — a pre-registered control caught m4_per_sharer at 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_blocked read 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_nt is 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 have jc_nt ≥ 2, and all 35 control arms have jc_nt == 1. Gated, every control keeps M0’s nc by 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_all and run_int_bench now record their own provenance (#475). #442’s contract says every new sidecar carries git_commit, git_dirty, cxx_flags, governor and pool_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-exempt and 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 through detail::generic_fma and two new siblings — generic_add for the loops that accumulate a term they did not form by multiplying, generic_mul for scale — across mult_sparse_crs and its transpose, axpy, scale, six accumulations in norms, and the eager operator* loops in mat/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::abs at the minimum of a signed type (#461). UB — there is no positive 2^(N−1) — so one_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. New generic_abs returns the wrapping answer. The consequence is recorded rather than hidden: the wrapped |min| is negative, so it never wins infinity_norm’s max — an integer norm is defined and reduced mod 2^N, but it is only a norm when nothing overflowed
  • ilut could not be instantiated with a complex element type (#505). Two causes: the threshold typing above, and two std::sort(entries.begin(), entries.end()) calls that compared pairs lexicographically, requiring an ordered element type for a .second comparison 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 *_mt targets but ran ctest -R _mt, which finds every _mt test whether or not it was built — so adding one failed the lane with Could not find executable, reported as a test failure inside a TSan job, which reads as a race and is not one
  • balanced_mc could return a block shorter than the register tile (#488, fixed in #489). plan_gemm_grid floors mc at mr and says why in its own comment — “a block shorter than mr would waste the micro-kernel” — and balanced_mc then ran and lowered it straight back through that floor, because balancing works by raising the block count. At mc=5 against mr=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 none
  • packed_b_bytes reported 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 a packed_buffer<TB> (2× off for float operands into an fp64 accumulator, 4× for i8 into i32); it ignored the column padding, since balanced_nc deliberately does not round nc to a multiple of nr on the threaded path — so a ragged nc is the normal case, and this one was wrong even for double; and it ignored the quad k-padding. Resolved by answering #486’s three questions rather than by making nc bigger, 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_models printed “worst first-round excess over the minimum … (raise --rounds)” computed from round 0, which is a warmup question — raising --rounds cannot 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 — and A || B runs B only when A fails. On ARM the grep succeeds, returning a generic ARMv8 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
  • detail::mult_sparse_crs keeps 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 literal 0 costs the optimizer something on the starts[r] / starts[r+1] pair, and the restated assertions that recovered the dense case did not recover this one. That 6.5% would land on double SpMV at MTL5_NUM_THREADS=1, the default, and the inner loop of every Krylov iteration in itl/. A test pins the two bodies to each other
  • The default jc block size is m6_guarded, and then the shape-gated per-sharer budget M7 (#429 first half in #490, #492 in #499). balanced_nc became 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: lowering nc raises njb, which can take jc_nt 2 → 4, and each team holds its own kc × nc panel — 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: grew alone catches both regressions but declines two gains, exceeds L3 alone 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_mul are exempt from -fsanitize=integer by name (#461). That group bundles unsigned-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 on main either — and is narrow, so accidental wrap-around anywhere else stays caught
  • 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/

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> accepts int32_t and uint32_t lanes, so dot and both gemv orientations 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 a batch<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 up
  • dot<int32_t> over int16_t uses the hardware widening multiply-accumulate (#463) — vpmaddwd on x86 (pmaddwd at SSE), SMLAL/UMLAL on 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, because ReorderWidenMulAccumulate permutes which product lands in which lane and guarantees only the total — disqualifying for a floating accumulator, unobservable on integer lanes
  • dot<int32_t> over 8-bit operands uses the quad multiply-accumulate (#464) — vpdpbusd on x86, SDOT/UDOT on 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 full HWY_AVX3_DL set 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 for i8×i8 against 3 for i16×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_widen offers exactly the three pairings the instruction offers and rejects (int8, uint8) at compile time naming the fix, while dot/dot_real accept 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_widen for 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 across pc blocks, 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 int runs fp64/fp32 baselines against int32, int16→int32, int8→int32 and uint8×int8→int32 for dot, and int32 for gemv, 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 sizes
  • run_int_bench.sh refuses to time a build without the instruction it claims to measure. Nothing in a timing distinguishes vpdpbusd from the vpmaddwd decomposition, 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-decomposed measures it anyway and labels the run so the CSV cannot be mistaken. Both guards were tested by firing them. build_isa now carries AVX512VNNI, AVX3_DL, AVX10.2, DOTPROD and I8MM, since it previously recorded AVX512F and stopped
  • mult_quad drives the hardware quad multiply-accumulate — vpdpbusd on x86, SDOT/UDOT on NEON — four k-values per instruction against the widening path’s one. vpdpbusd consumes 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 accumulates sum_{q<4} A(i,p+q) · B(p+q,j). gemm_blocked gains TA/TB as separate operand types — (u8,i8) is VNNI’s native shape and the two must differ — plus a gemm_kernel template 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 as C^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 rerouted mult’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::widening is the default, mult is 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 gets u8×i8 at AVX3_DL and the symmetric pairings only at AVX10.2; ARM gets i8×i8/u8×u8 with FEAT_DotProd and u8×i8 only 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_support summarises as none/partial/all, and partial is what every machine measured so far reports. has_native_quad_dot keeps its original any-pairing meaning so no committed sidecar changes meaning. The gates now use Highway’s own conditions (HWY_TARGET <= HWY_AVX3_DL is literally the gate in x86_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-decomposed decision live in the repository. The two decomposed profiles assert --allow-decomposed on 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 pins 0,1,2,3,4,5 where every other profile pins 0,2,4,…: its SMT siblings are blocked (0,6), not adjacent pairs
  • verify_gemm_int checks every integer GEMM arm against a 64-bit reference, outside the timed region, and fails the run rather than warning. measure only 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
  • The integer-lane results are recorded in the living assessment, and the i7 corrected them (#467). On a Zen 4 with native vpdpbusd, dot with uint8 × int8 reaches 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 (native u8×i8 against emulated i8×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 ÷ emulated ratio 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. The best int8 ÷ fp32 column 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
  • mc is bounded at runtime by the strip of C the ic block accumulates into (#457, #459). The L2 model sizes mc so 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 be mc × nc, and reproducing the shipped mc = 64 then needs mc·(kc+nc)·sizeof ≤ 8.5·L2, which is not a residency statement, and the nr = 4 family needs 2.5 rather than 8.5. What survives is the same idea in the right place — the strip is mc × min(n, nc) and n is known at the call, which is already where mc is 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 mconly holding 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 shrank mc for 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 the ccap/ccap2 benchmark 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_nt per point, from #448), which is what it always meant to say; CSVs predating mc_used fall 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/uint32 only, 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_ref supplies data() and size(), which is all BlasDenseVector asked for, so ten operations accepted it and walked data() with unit stride: dot_real over a stride-2 view returned 14 where the answer is 44. This affected float and double, 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 mult takes in the default build, since MTL5_NATIVE_FAST_GEMM is off. The wrapping helpers were also not performed wide enough to be defined: integral promotion sends anything narrower than int to signed int, so uint16 operands overflowed it, reachable as dot_real over a dense_vector<int16_t>
  • Shell scripts checked out with CRLF on Windows and could not run under WSL (#466). There was no .gitattributes at all, which CLAUDE.md’s cross-platform rules already required, so all fifteen tracked shell scripts were affected — preflight.sh, every run_* harness and every machine profile — meaning no part of the benchmark contract could be executed from a Windows checkout. *.sh/*.bash are pinned to eol=lf; *.ps1/*.bat/*.cmd keep CRLF since they only run on Windows; .mtx/.csv are 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)·rs for 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’s pointer-overflow check 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 any Matrix without an orientation alias (#469). interface::is_row_major_v<MC> was named at function scope, outside any discarded branch, and the concept does not require that alias — compressed2D and transposed_view both 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

A benchmarking-infrastructure release, and the experiment it was built to run. Two breaking changes, both narrow; see Breaking below before upgrading.

  • Field<T> is now false for integral T, 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. Field asked only that a / b compile and yield a T, which int satisfies, 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. Field now excludes std::is_integral types, the new FieldMatrix applies 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 keep Scalar, 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 not is_integral. What breaks downstream: vec<int> / 2 and 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_DETECTION if 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. Emits key=value machine 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 records unavailable out loud. Governor is recorded and warned about, never failed: every machine in systems.md runs 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. Plus build_isa (mtl::util::build_isa_list), read from the compiler’s own predefined macros: cxx_flags is the build’s intent and can omit the flag that mattered (MTL5_NATIVE_ARCH adds -march=native through target_compile_options and appears in no CMAKE_CXX_FLAGS variable), while build_isa is 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>() returns mc, nib, njb, ic_nt, jc_nt, budget, and gemm_blocked now uses it rather than recomputing the same three steps inline. Benchmarks record mc_used per point, so the parameter under test is in the record of the experiment testing it: three stages separate the configured mc from 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_caches takes 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 its nvpmodel power 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 from cpu_simd (what the machine supports). Emitted as build_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 an int64 accumulator 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 two int32 always fits an int64, 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_nt was taken as min(budget, nib) and jc_nt as the integer quotient, which throws the remainder away: at budget 6 with nib = 4 that is 4×1 = 4 of 6 threads, and with njb = 1 (square problems) no jc parallelism compensates. plan_gemm_grid searches the legal factorizations and also caps mc so 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 to benchmarks/data/<machine> so it cannot become a hole through the gate), and -AllowDirty exists because set ALLOW_DIRTY=1 is cmd.exe syntax that silently does nothing in PowerShell
  • A per-machine OUTDIR is 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_pool clamps MTL5_NUM_THREADS to hardware_concurrency, so a request of 8 on a 6-core part measured 6 while the CSV said 8; the pool column records what ran
  • CMakePresets.json lowered to schema v3 so CMake 3.22 can read it (#435)
  • A wall-clock ratio no longer gates every PR (#454). sparse_test_native_klu asserted time_ratio < 13.0 on 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 asserts fill_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 to tests/regression/sparse/test_klu_scaling.cpp in 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_gmres also gets the 600 s timeout cg and bicgstab already 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
  • run_scaling and run_sweeps build 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’s setvars.sh is now sourced in a subshell for both configure and run, so oneAPI’s LD_LIBRARY_PATH cannot leave the openblas and blis binaries resolving MKL’s libraries while still labelled as themselves
  • 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 mc is the harm and it is visible with one thread; raising kc is 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 kconly is default), 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
  • ROUNDS is rounded up to a multiple of the arm count, so the rotation balances exactly
  • Sparse LU refactor 23% faster via sparse_lu_refactor_in_place / supernodal_lu_refactor_in_place (#310). The reported defect was real: *_refactor installed through set_factor, which unconditionally rebuilds both level-solve schedules, even though a same-pattern refactor leaves col_ptr/row_ind byte-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 copies prev, and copying the schedules (two nnz-length size_t arrays 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_refactor keep their signatures as “copy prev, refactor in place”, and native_klu_refactor inherits the change through its per-block call
    • set_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 installed nnz and the schedules’ built_nnz staleness guards — the same guards the solves assert on — so a pattern change cannot slip through silently. set_factor remains 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 dense2D expression sweeps (ctor / = / += / -=) made each row one parallel_ewise work unit, and thread_pool::parallel_for runs serially when n < grain*2 — so a 1 x 300000 assignment had n == 1 and could never split, however much work the row held. Same wide-shape gap #311 closed for GEMM. detail::parallel_ewise_2d flattens (r, c) to a linear element index [0, rows*cols) before chunking, so the split follows the element count and 1 x N parallelizes exactly like N 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 the t / cols, t % cols a per-element decomposition would pay; and work_per_elem = 1 yields grain = 65536 elements, exactly the chunk size the row form’s 65536 / num_cols rows 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 at MTL5_NUM_THREADS=4. The second half of #313 — the ~K× too-coarse grain for the opt-in lazy mat_mat_times_expr, whose operator()(r,c) is a length-K inner product — is split out to #424, since it needs a public per-element work-hint trait

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 with CHOLESKY_NOT_HERMITIAN. cholesky_factor is now restricted to real element types with a diagnostic naming the alternative — unlike ldlt there 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 now H = I − τ·v·vᴴ with H·x = β·e₁ and β real, built as in LAPACK zlarfg. H is unitary but not Hermitian for complex τ, so H⁻¹ = Hᴴ; that lands as conj(tau) in qr_extract_Q, plain tau in lq_extract_Q, and a conjugated row plus Hᴴ on the LQ factor side. Verified ‖QᴴQ−I‖ ≤ 7.8e-16 and ‖QR−A‖ ≤ 7.0e-16 over square, tall and wide shapes (#361)
  • hessenberg_factor and eigen_symmetric now reject complex element types. They apply H·A·H, a similarity transform only because a real reflector is Hermitian and involutory; making householder() 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·D that preserves the spectrum, so eigenvalue_symmetric needs only |T(i+1,i)| while eigen_symmetric folds D into the eigenvectors so A·v == λ·v (skip it and the eigenvalues still look right — the silent-wrong shape #352/#353 kept hitting). But MTL5’s householder() reflects to a real β, so for n ≥ 3 the 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), where T(1,0) is the original off-diagonal. The 2×2 tests ([[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 calls householder; 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 == λ·v per pair, Qᴴ·Q == I, and the reconstruction V·diag(λ)·Vᴴ == A — the check that catches a non-similar reduction, which a merely-unitary Q does not (#361’s lesson). eigenvalue_symmetric_generic also gained a 0×0 guard before its e(n-1) sentinel write

LAPACK Hermitian eigensolver + native cross-validation (#415)

Section titled “LAPACK Hermitian eigensolver + native cross-validation (#415)”
  • cheev/zheev bindings (interface/lapack.hpp) and a BlasHermitianMatrix concept (interface/dispatch_traits.hpp); eigenvalue_symmetric routes a complex Hermitian matrix to heev under MTL5_HAS_LAPACK, mirroring the real syev path. Eigenvalues W are real, heev takes an extra real rwork of length max(1, 3n−2), and the optimal lwork returns in the real part of the query’s work[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_dispatch now cross-checks eigenvalue_symmetric_generic (native) against zheev and they agree to 1e-9 on known, degenerate ({2,2,2,10} from 2I + 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) and svd (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/cholesky pass the raw A.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_factor delegates to cholesky_factor for real BLAS types — L·Lᴴ is L·Lᵀ there — which keeps the two entry points bit-identical (an invariant test_cholesky.cpp pins with ==, which independent factoring would break once cholesky_factor uses potrf). A zero-dimension guard was added to all three (LAPACK rejects lda == 0)
  • The #297 determinism tests move to a non-BLAS type. They assert the threaded factorization is bit-identical to a serial generic reference — a property of the parallel_for kernel, not of LAPACK. Since the default double path now dispatches to LAPACK (a different algorithm), the LU/Cholesky determinism cases switch to long double (never is_blas_scalar), so dense2D<det_t> keeps exercising the generic parallel path in LAPACK and non-LAPACK builds alike; the apply_householder_* cases stay double, since those kernels never dispatch
  • mtl::spgemm(A, B) (operation/spgemm.hpp) — Gustavson’s row-by-row algorithm over the existing sparse accumulator (sparse/util/scatter.hpp, CSparse’s cs_scatter), so work is proportional to the multiply-adds actually performed rather than n³. compressed2D * compressed2D previously fell through to the generic dense operator*, which both materialised an n × n dense intermediate at the fine-grid size and reached every element through compressed2D::operator()(r, c) — itself a binary search. The Galerkin triple product A_coarse = R·A·P, the one product a multigrid user most needs to stay sparse, was the one that did not. operator* on two compressed2D now returns compressed2D; 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() uses std::lower_bound and 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, nnz is correct, row sums off the raw CSR arrays are correct to 4.4e-16, and a sparse matvec is correct to rounding — it sums data[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, so test_spgemm.cpp asserts the index structure directly instead of trusting a residual (#402)
  • 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 with PASS_REGULAR_EXPRESSION rather than CMake’s WILL_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 the cholesky guard leaves the file still failing to compile via the old operator<= error, so WILL_FAIL would have been green while the regex catches the regression to the worse diagnostic (#358)
  • ppe/ — a progression of GEMM implementations (naive → loop order → blocking/packing → register tiling → compile-time microtile) measured across int8/16/32/64 and fp16/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 for fp32, because full unrolling removes the loop structure the vectorizer needs and 32 scalar accumulators then spill — while being the best kernel for int32, 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.

  • bicg computed rho from z̃ᵀz instead of zᵀ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; with pc::diagonal on a 144×144 SPD Laplacian it hit the 3000-iteration cap where cg took 33. Preconditioned BiCG reduces exactly to preconditioned CG when both A and M are 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 against pc::diagonal, which is symmetric whatever A is: same iteration count, not merely convergence (#392)
  • qmr applied the preconditioner twice, once on each side, rather than the Freund–Nachtigal split M = M₁·M₂ with M₁ = M, M₂ = I. The algorithm needs w̃ᵀM⁻¹ṽ; the old code produced M⁻¹ on both the shadow and the primary vector. Fixed at the update sites, with q built from z̃. 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_0 and pc::block_diagonal had adjoint_solve stubs that delegated to solve, which is correct only when M is self-adjoint. M = L·U is not, and a diagonal block of a non-symmetric A is not either, so bicg/qmr applied the wrong operator outright and did not converge at all. ilu_0 now does U⁻ᴴ then L⁻ᴴ in scatter form over the existing row storage; block_diagonal routes each block through the new public mtl::lu_adjoint_solve (operation/lu.hpp), which applies Uᴴ forward, Lᴴ backward, and the inverse permutation as the same interchanges in reverse. ic_0 and ildl were checked and are correct by construction — L·Lᴴ and L·D·Lᵀ are self-adjoint — so delegation there is right rather than lucky (#394)
  • itl/mg/multigrid.hpp was not self-contained. It used mat::operators.hpp without including it and compiled only because every existing consumer happened to include it first — test_multigrid.cpp supplied it at line 7 of a 16-line include list. A new translation unit including only multigrid.hpp failed. Added the include, plus test_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 a long double reference, 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·eps is not a tightening of a k·eps worst case, it is 4× wider, and the true worst-case relative error against the test’s (|ref|+1) denominator is nearer k^1.5·u (#386)
  • pc::ssor applied the wrong operator, because its sweeps started from x = b instead of x = 0. A stationary iteration and a preconditioner are the same splitting matrix M viewed two ways, and applying M⁻¹ means running one sweep from zero; from any other start the result is M⁻¹b + G·x₀ with G = 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 operator M = ω/(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 of M at two ω. For Hermitian A that is c·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 and adjoint_solve’s delegation to solve becomes 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-Hermitian A remains 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 is cg + ssor on a non-symmetric A (45 iterations → does not converge), which is outside CG’s domain in the first place: its former convergence rested on the extra G_B·G_F term, not on the preconditioner (#398, #394)
  • ldlt returned a wrong answer for Hermitian complex input under info == 0. Added ldlt_h_factor / ldlt_h_solve for A = L·D·Lᴴ, and guards in both directions: LDLT_NOT_SYMMETRIC when Hermitian input reaches the LDLᵀ form, LDLT_NOT_HERMITIAN when a non-real diagonal reaches the LDLᴴ form. Both tests are scale-relative (n · eps · scale, via LAPACK’s CABS1 to avoid an O(n²) sweep of hypot), 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 in detail/structure_tol.hpp (#352, #356)
  • compressed2D accepted tag::col_major and ignored it. The container is CSR unconditionally, so a col_major instance 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_matrix carried the same inert-orientation hole and is rejected too. coordinate2D is deliberately untouched — it stores explicit (row, col, value) triplets, so orientation cannot change a result (#355, #358)
  • householder broke its own real-β guarantee for a complex vector with a vanishing tail and a complex leading entry, returning tau = 0 and leaving a complex R/L diagonal — silent, since Q stayed unitary and Q·R still reproduced A. The identity shortcut is now taken only when it is exact (#361)
  • 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 mc was rounded down to a multiple of mr — coupling a cache quantity to the register tile. The L2 budget yields exactly 64, which survives mr=4 but drops to 60 under #382’s mr=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. mc now derives from the cache alone, and detail::balanced_mc chooses the block size against m and the thread count at runtime, where both are known; the serial path still rounds to whole mr-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-mr constraint was never a correctness requirement — pack_A already handles a ragged final panel, since m is not generally a multiple of mr
  • 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·nc per pc step (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)
  • 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 = 1 baseline #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_mc only engages when ic_nt > 1 — which gives a control: native-fast’s T = 1 figure 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 the native-fast move 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.hpp is gated behind MTL5_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. axpy also moved +37% with no commit in the window that touches it, likewise marked undetermined

  • pc::ssor is now the adapter over smoother::symmetric_sor it 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 a compressed2D specialization — while docs/design/smoothers-architecture.md described it as a wrapper. Since #398 established that one symmetric-SOR application from a zeroed vector is M⁻¹b, the preconditioner collapses to three lines over the smoother: −129 lines, and the matrix-type specialization comes from smoother::sor so the O(nnz) sparse path is inherited rather than restated. Two consequences beyond the line count: pc::ssor gains the Accumulator template parameter (defaulted to void, 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 now const (they only ever mutated the caller’s x), which is what lets the preconditioner hold one as a member and still expose a const solve() without mutable. 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.md no longer advertises a “zero-cost CSC view over compressed2D with col-major parameters” — never implemented; sparse/util/csc.hpp uses a standalone owning csc_matrix. docs/architecture/aggregate-types.md no longer claims “Full support (CSR, CSC, COO, ELLPACK)”; CSC exists only as a conversion utility (#358)

  • 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 as sqrt: the accumulator itself for a plain arithmetic Acc, T for fma_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 of sparse::iterative_refine: factor A once in a low Working precision via lu_factor/lu_solve, then correct with a residual formed in the (deduced, higher) Residual precision. Universal-free and generic over the arithmetic type. Shares the sibling’s refine_options/refine_result shape: best-iterate return, patience for a noisy low-precision residual, rel_tol convergence, and an opt-in scaled (scale-and-round) variant that carries the correction magnitude in Residual precision so narrow-exponent Working factors 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.hpp as 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 returning vec::dense_vector<T>, generic over the scalar type (Universal-free). geomspace computes a true geometric progression between its endpoints, fixing the historical Universal implementation that aliased logspace and 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 throw std::invalid_argument pending support.
  • Migrated from Universal’s sw::blas as 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_invertible and determinant (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) and is_normal (AAᴴ == AᴴA), plus inertia (the congruence-invariant (positive, negative, zero) eigenvalue-sign triple, Sylvester’s law) and is_indefinite; inertia is backed by the symmetric eigensolver so it is robust for singular/semidefinite inputs (#249)
  • mtl::detail::thread_pool — a persistent worker pool (no OpenMP/TBB, just the C++ standard concurrency runtime) with run, parallel_for (bit-identical contiguous chunking), and parallel_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/nrm2 and column-major GEMV (#241), and sparse SpMV compressed2D * 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_nt thread 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 a detail::parallel_ewise helper; each output element is independent, so contiguous chunking is bit-identical (#312)
  • Encapsulation — the numeric factor types privatize L/U/D and their coupled solve schedules behind a validating, strongly-exception-safe set_factor(...) with read-only accessors, so the schedule can never drift from the factor pattern; solve() rejects a missing factor with std::logic_error (#305–#309, #307/#308)
  • CI — threaded (GCC+Clang, MTL5_NUM_THREADS=4) and ThreadSanitizer lanes on push and PRs, plus the design field guide docs/design/parallelization-patterns-and-pitfalls.md (#299/#303, #301)
  • cg accumulator policy — the conjugate-gradient solver routes its two dot calls and the mult through an optional accumulator_traits accumulator (#158); default (void) behavior is unchanged, while posit32+quire shows a consistent accuracy gain over naive posit32 (#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 generalized value<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/mult with the result type inferred from C (#161), gemv (#160), and the sum-of-squares norms two_norm/frobenius_norm (#162). E.g. mult<float>(A_bf16, B_bf16, C_bf16) accumulates in fp32 and writes bf16 once. Default Accumulator = void is 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 (Highway Rebind+PromoteTo) + simd::reduce_dot_widen for float→double; dot routes its mixed path to it (~2.6× over scalar) (#165)
  • SIMD widening GEMM — the blocked GEMM generalized to <TC accumulator, TAB operand> (default TAB = TC ⇒ same-type path byte-identical): the micro-kernel widens narrow operands on load (batch<TC>::load_widen<TAB>) into TC accumulator 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_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)
  • 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 the accumulator_traits accumulator, so a low-precision factor can accumulate in higher precision — the mixed-precision capability the fixed-precision SuiteSparse library cannot offer. Matches scalar sparse_lu to 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=true factors R·A (r=1/max|row|) for pivot stability in low/mixed precision; RHS row-scaled in solve(), x unchanged (#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
  • “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)
  • Size-N sweep (--sweep START:STOP:STEP and :xFACTOR) plus BLAS-level suite groups l1/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 under benchmarks/data/ with provenance (#78, #79, #80)
  • One-executable-per-backend methodology — bench_all calls only the public mtl:: API; the build flags choose the backend (native / OpenBLAS / MKL); run_sweeps.sh builds 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.sh gain a blis variant (CMake BLA_VENDOR=FLAME, auto-skipped if absent); the harness now benchmarks all core BLAS routines MTL5 implements (adds axpy/scal at L1, and L2/L3 as they land); analyze_gate.py --reference baselines against OpenBLAS, BLIS, or MKL (#227, #228)
  • 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 of MTL5_HAS_LAPACK (#78)
  • .github/dependabot.yml for the github-actions ecosystem (#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), mirroring eigen_symmetric. In the in-house path, eigenvalues come from the general QR path and each eigenvector is recovered by inverse iteration on A - 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, eigen instead dispatches to geev (which returns the eigenvectors directly — see #204). Eigenvectors are unit-norm with a canonical phase (#203)
  • LAPACK geev dispatch for the general eigenproblem — eigenvalue/eigen route to sgeev_/dgeev_ when MTL5_HAS_LAPACK is defined and the matrix is a column-major dense2D<float/double> (mirrors the symmetric syev dispatch); 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 the LinearOperator concept (A * x) so they apply to dense2D, 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; an eigen_which selector 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 nearest sigma via (A - sigma*I)^{-1} applied inside Arnoldi, mapping lambda = sigma + 1/theta), and the reusable shift_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 (solve A*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/syr2k produce 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/gemm gating. New s/d bindings added to interface/blas.hpp (ger, symv, trmv, trmm, trsm, symm, syrk, syr2k). BLAS leading dimensions are clamped to max(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_SUPERLU comparison paths are exercised. MTL5_BUILD_BENCHMARKS defaults OFF and no workflow enabled it, so benchmarks/*.cpp was compiled by no runner; that is how the lu_numeric breakage 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 set MTL5_WITH_HIGHWAY, so every lane built the size == 1 scalar fallback in simd/batch.hpp and the Highway specialization — the SIMD register type under the blocked GEMM — was compiled nowhere, while that flag is what the native-fast variant 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 a libhwy artifact was built, and simd/test_batch.cpp static-asserts batch::size > 1 under MTL5_HAS_HIGHWAY on x86-64 (the previous assertion was >= 1, which passes in both configurations) (#330)
  • 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.sh defaults to SPARSE_SIZES=100,160 (was 200,320, which did not complete — a T=1 run 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_request declared no types, so the default [opened, synchronize, reopened] applied and ready_for_review fired nothing. Since the Tier 2 regression job gates on draft == false, a PR opened as a draft only ever had runs in which it skipped — silently, because gh pr checks reports green when a job skips rather than fails (#333)
  • cmake --preset release builds something. It set tests and examples OFF with benchmarks defaulting OFF, leaving a configured tree with zero buildable targets, since the only target is an INTERFACE header-only library (#319)
  • mtl::svd now uses one-sided Jacobi instead of an alternating-QR iteration, and its default tol is machine epsilon rather than 1e-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; pass 1e-10 explicitly for the previous looser behaviour. Singular values are non-negative and returned in descending order, and U is completed to a genuine orthogonal basis for rank-deficient or m > n input (#337)
  • mtl::ldlt_bk_factor’s stored factor now matches LAPACK dsytrf entry 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; ipiv is unchanged and was always LAPACK-compatible (#335)
  • mtl::dot / dot_real now dispatch to BLAS ?dot when types qualify (consistency with two_norm); both dot and two_norm BLAS paths guard the int length cast against overflow (#81)
  • Benchmarks rewritten to the single-path public-API model; deleted the Native/Blas/Lapack policy-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 lapack job (Linux GCC + Clang, -DMTL5_WITH_LAPACK=ON) builds and runs the external-library geev/syev paths, which the default LAPACK-free matrix never compiled (#212)
  • bench_klu / bench_superlu did not compile — they referenced blk.L / blk.U on lu_numeric, whose members are private (L_ / U_). Nothing caught it because no CI job built the benchmark targets; they had not been compiled since lu_numeric was encapsulated. Now use the public factorL() / 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, but max(8, ...) bounds g3 only 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::svd returned 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_rank and nullity all inherited it through detail::singular_values. Two independent defects. (a) householder formed sum(x(i)^2) unscaled and guarded only exact zero, so a tiny sigma reached beta = 2*v0*v0/(sigma + v0*v0) with both terms flushed to zero (0/0), while v(i) /= v0 overflowed; apply_householder_left/right then evaluated beta * v(i) * w as 0 * inf. Since qr_factor stores v below 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 LAPACK dgesvd over 1800 random matrices: 0 NaN, worst relative deviation 3.0e-15 (#337)
  • mtl::itl::pc::ilu_0::solve counted the diagonal in its back-substitution off-diagonal sum, computing x(i) = (y(i) - sum_{j>=i} U(i,j)*x(j)) / U(i,i) — subtracting U(i,i)*x(i) and then dividing the difference by that same U(i,i). Wrong for every input: on a diagonal matrix, where ILU(0) is exact, it returned (b - d*b)/d instead of b/d. The diagonal is now stored only in u_diag_, making u_rows strictly 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_factor produced a wrong solution whenever a pivot interchange occurred, under info == 0 — normwise backward error ~1e-1 instead of ~1e-16, in 4560 of 5700 random symmetric matrices. symmetric_swap permuted the L columns written by earlier steps, putting the stored factor in the “single global P” convention while ldlt_bk_solve replays the interchanges one step at a time (as LAPACK’s dsytrs does); 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 — ipiv matched dsytrf before and after — and the stored factor now matches dsytrf entry 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 why two_norm<double> worked and hid it, but an fma_accumulator<T> or a quire for configurations 2 and 3, neither of which has a sqrt. Now rounds out to the accumulator’s own arithmetic precision via the new accumulator_round_type (#324)
  • mtl::eigenvalue single-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 (EISPACK hqr): real Schur form via 1×1/2×2 block deflation, exceptional shifts to break stagnation, and a std::runtime_error on 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::set wrote out of bounds for diagonal indices (i == j) under NDEBUG, where the guarding assert is compiled out; now a safe no-op (#63)
  • Benchmark native eigenvalue backend was silently dispatching to LAPACK; it now uses the generic C++ solver so native vs lapack is a genuine comparison (#78)
  • 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

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, FillReducingOrdering and SparseDirectSolver concepts
  • 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, #ifdef guards, and CRS-to-CCS conversion
  • 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)
  • 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)
  • 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
  • include/mtl/mtl.hpp — added sparse solver and external interface umbrella includes
  • CMakeLists.txt — added MTL5_ENABLE_SUPERLU, MTL5_ENABLE_KLU, MTL5_ENABLE_CHOLMOD, MTL5_ENABLE_SPQR options
  • CLAUDE.md — documented sparse/ namespace, conventional commits, branch workflow, PR process