From a84c5f994b75a84e8e9f839dd8caa675accc399d Mon Sep 17 00:00:00 2001 From: tannevaled Date: Thu, 12 Nov 2026 11:57:22 +0100 Subject: [PATCH] docs: ndarray v0.40.1 Re-sync the mirrored pages at v0.40.1, move the docs version to 0.40, add the Accuracy contract page (mirrors the README section), the riscv64 float32 GEMM section in performance.md and its audit entry in security.md. Co-Authored-By: Claude Sonnet 5.5 --- README.md | 2 +- content/en/accuracy.md | 23 ++++++++++++++ content/en/dtypes.md | 2 +- content/en/linalg.md | 4 +-- content/en/performance-history.md | 50 +++++++++++++++++++++++++++++++ content/en/performance.md | 23 +++++++++++--- content/en/random.md | 8 ++--- content/en/roadmap.md | 4 +-- content/en/security.md | 14 ++++++++- hugo.yaml | 4 +-- 10 files changed, 117 insertions(+), 17 deletions(-) create mode 100644 content/en/accuracy.md diff --git a/README.md b/README.md index 60992ef..9feb208 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ describes**: | Source | Published under | | --- | --- | -| branch `main`, with `params.ndarray.version: v0.39.0` in `hugo.yaml` | `https://go-ndarray.github.io/docs//`, here `/docs/0.39/` | +| branch `main`, with `params.ndarray.version: v0.40.1` in `hugo.yaml` | `https://go-ndarray.github.io/docs//`, here `/docs/0.40/` | | the newest version | also `https://go-ndarray.github.io/docs/latest/` | `https://go-ndarray.github.io/docs/` redirects to `latest/`. Each push to diff --git a/content/en/accuracy.md b/content/en/accuracy.md new file mode 100644 index 0000000..7133a7e --- /dev/null +++ b/content/en/accuracy.md @@ -0,0 +1,23 @@ +--- +# Below the "Mirrored from" line, this page is the "Accuracy contract" section +# of go-ndarray/ndarray README.md, verbatim (README: "Mirrored pages"). +title: "Accuracy contract" +linkTitle: "Accuracy" +weight: 25 +description: "What go-ndarray promises about its results: a stated error bound, checked against an exact oracle, not equality with NumPy's bits." +tags: [accuracy, numpy, math/big] +--- + +> Mirrored from [`README.md`](https://github.com/go-ndarray/ndarray/blob/v0.40.1/README.md#accuracy-contract) at v0.40.1. + +The contract is **correct, and as fast as possible**. "Correct" means a stated error bound, checked against an exact oracle. Equality with NumPy's bits is not the contract: wherever it holds today, it is how a function was ported, and a faster default that stays within its bound may replace it. + +Bound: elementwise `+ − × ÷` and `Sqrt` are correctly rounded (one IEEE operation, ≤ 0.5 ULP). Float64 `Exp`/`Log` have a worst error of 0.511 / 0.519 ULP, the figures of Arm's optimized-routines, which go-simd/floats ports. Float32 `Exp`/`Log` are correctly rounded. The proof covers all 2³² inputs and lives in go-simd/floats; it runs on demand, and CI checks a sample. `Max`/`Min` are exact. + +`Sum` satisfies |Ŝ − S| ≤ γ_d·Σ|xᵢ|, with γ_m = m·u/(1 − m·u), u = 2⁻⁵³ for float64 and 2⁻²⁴ for float32. d is the rounding depth of NumPy's pairwise tree: at most 24 in a leaf of up to 128 elements, plus one per halving. The bound holds for any tree at most d deep, not for a serial loop, which needs γ_{n−1}. + +Every element of `MatMul`/`Dot` satisfies |Ĉᵢⱼ − Cᵢⱼ| ≤ γ_k·(|A|·|B|)ᵢⱼ, whatever the summation order, with or without FMA. Both bounds are from Higham, *Accuracy and Stability of Numerical Algorithms*, §3.1 and §4.2. + +Oracle: `math/big` at 1024 bits for sums and inner products. `TestSumDepth`, `TestAccuracyBoundSum` and `TestAccuracyBoundMatMul` check them; the difference is taken in `big.Float`, so the oracle is never rounded. `Exp`/`Log` are checked against a 300-bit reference in go-simd/floats. + +Exact: the defaults are still the exact ports, NumPy's pairwise order for `Sum` included, so results match NumPy bit for bit where they did before. When a faster default lands, that arithmetic stays available behind an explicit option. diff --git a/content/en/dtypes.md b/content/en/dtypes.md index 3b3440b..468a2a6 100644 --- a/content/en/dtypes.md +++ b/content/en/dtypes.md @@ -8,7 +8,7 @@ description: "Why the dtype is a run-time property of one Array type, how arrays tags: [dtypes, numpy] --- -> Mirrored from [`docs/design-dtypes.md`](https://github.com/go-ndarray/ndarray/blob/v0.39.0/docs/design-dtypes.md) at v0.39.0. +> Mirrored from [`docs/design-dtypes.md`](https://github.com/go-ndarray/ndarray/blob/v0.40.1/docs/design-dtypes.md) at v0.40.1. > Status: implemented (Phase 2). Supersedes decision 4 of > [plan-ndarray.md](roadmap.md) ("`float64` first"). diff --git a/content/en/linalg.md b/content/en/linalg.md index 274f6e4..3ba81cb 100644 --- a/content/en/linalg.md +++ b/content/en/linalg.md @@ -8,9 +8,9 @@ description: "Solve, Inv, Det, Cholesky, QR, SVD, Eig and the rest of numpy.lina tags: [linalg, numpy] --- -> Mirrored from [`docs/linalg.md`](https://github.com/go-ndarray/ndarray/blob/v0.39.0/docs/linalg.md) at v0.39.0. +> Mirrored from [`docs/linalg.md`](https://github.com/go-ndarray/ndarray/blob/v0.40.1/docs/linalg.md) at v0.40.1. -Package [`linalg`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.39.0/linalg) gives ndarray arrays the functions of +Package [`linalg`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.40.1/linalg) gives ndarray arrays the functions of `numpy.linalg`, written in Go without cgo or assembly of its own: the matrix products it relies on are the ndarray package's packed SIMD GEMM. diff --git a/content/en/performance-history.md b/content/en/performance-history.md index be5a95c..fb48071 100644 --- a/content/en/performance-history.md +++ b/content/en/performance-history.md @@ -1808,6 +1808,56 @@ the 4.8. (cfarm94, SiFive U74), the same build runs the scalar path and passes the same tests. + **float32 GEMM on RVV, 8×16 tile (2026-11-11, #107).** OpenBLAS's + `riscv64_zvl256b` SGEMM (v0.3.34, `param.h`, `sgemm_kernel_16x8_zvl256b.c`) is + a 16×8 tile, LMUL=2 (vl = 16, a full register pair at VLEN 256), eight + accumulator pairs fed by eight scalar loads and one vector load per k step, + blocking P = Q = 128, R = 16384, with a separate tail pass per edge size. Ours + ran LMUL=4 with vl = 16: half of each register group idle on a 256-bit core, + and 6 rows, so every 256-row block ended in a 4-row edge tile. Attribution, + one change at a time (`abbench`, cfarm95, core 0, load 5.3–5.8 of 8): + - **8×16 tile at LMUL=2** (`gemmMicro8x16RVV`, chosen when `vlenb ≥ 32`; the + 6×16 kernel stays for VLEN 128): 64² 184.6 → 147.0 µs (−20%, p = 0.011), + 256² 7.19 → 5.25 ms (−27%, p = 0.002). 64, 256 and 1024 are multiples of 8, + so no edge tile is left. + - **k unrolled 4× instead of 2×**: no change (142.0 vs 141.8 µs, p = 0.63; + 5.09 vs 4.81 ms, p = 0.09): the loads are hidden, so the loop is bound by + the FMAs (about 8.5 GFLOPS per core). Kept at 2. + - **blocking** (MC, KC, NC from 64 to 512 around the 256/256/512 default, + OpenBLAS's 128/128 included): within 5% except KC = 128, +20% at 1024², so + unchanged. + - **packing A** (`packRows8`, eight sequential row streams, one 32-byte store + per step instead of eight strided scatters): 64² packing 33 → 11.7 µs, + 256² 561 → ~220 µs. + - Left over at 64²: allocating and zeroing the 16 KiB result is 17–27 µs of + the 142 (OpenBLAS's figure is on a preallocated array), packing B 12 µs. + + | float32 `MatMul` | 64² | 256² | 1024² | + |---|---:|---:|---:| + | before (6×16, LMUL=4) | 184.6 µs | 7.19 ms | 462 ms | + | **8×16, LMUL=2, packRows8** | **~142 µs** | **4.49 ms** | **356 ms** | + | OpenBLAS 0.3.34, 1 thread, preallocated (`sgemm.py` through the scipy-openblas32 venv, `~/nd-bench/venv`) | 105 µs | 5.34 ms | 380 ms | + | after / OpenBLAS | 1.35× | 0.84× | 0.94× | + + 256² and 1024² are now faster than OpenBLAS: −38% and −23% against the + 6×16 kernel in the table above. The final 8-round `abbench`, a separate run + at higher load, read −41% and −24% (p = 0.000). The 64² figure is from the quiet runs (the final + 8-round run, at higher load, read 283 → 207 µs, ±25%); about 20 µs of the + remaining gap is the result allocation the OpenBLAS reference does not pay. + + **float32 `Max`/`Min` (v0.39.0).** They come from go-simd/floats since v0.15.0 + (AVX2 `Float32Max`/`Float32Min`). cfarm420 (EPYC 7773X), one core, + interleaved, medians: + + | n = 16384 | `Max` | `Min` | + |---|---:|---:| + | floats v0.14.0 (SSE2) | 1.40 µs | 1.32 µs | + | floats v0.15.0 (AVX2) | 0.77 µs | 0.74 µs | + | NumPy 2.5.4 | 2.61–3.32 µs | 2.61–2.82 µs | + + At 1M elements the timing is memory-bound and NumPy varied from 64 to 113 µs + across runs, so no ranking is claimed at that size (go-simd/floats#46). + **GEMM micro-kernel (v0.7.1).** NR is fixed by the packing, while VLEN varies between RISC-V cores. The V extension guarantees VLEN ≥ 128, so a group of four registers (LMUL=4) holds at least eight float64, and `VSETIVLI $8` diff --git a/content/en/performance.md b/content/en/performance.md index bbdbb55..6344fef 100644 --- a/content/en/performance.md +++ b/content/en/performance.md @@ -8,11 +8,11 @@ description: "go-ndarray against the pinned NumPy on one core, both sides: the m tags: [performance, numpy, refbench] --- -> Mirrored from [`docs/perf.md`](https://github.com/go-ndarray/ndarray/blob/v0.39.0/docs/perf.md) at v0.39.0. +> Mirrored from [`docs/perf.md`](https://github.com/go-ndarray/ndarray/blob/v0.40.1/docs/perf.md) at v0.40.1. -The table is [perf-table.md](https://github.com/go-ndarray/ndarray/blob/v0.39.0/docs/perf-table.md), generated by +The table is [perf-table.md](https://github.com/go-ndarray/ndarray/blob/v0.40.1/docs/perf-table.md), generated by [refbench](https://github.com/go-scikit/refbench) (go-scikit/refbench v0.1.2) -from [perf.json](https://github.com/go-ndarray/ndarray/blob/v0.39.0/docs/perf.json); nothing in it is edited by hand. The rules are +from [perf.json](https://github.com/go-ndarray/ndarray/blob/v0.40.1/docs/perf.json); nothing in it is edited by hand. The rules are those of the go-scikit performance campaign ([go-scikit/roadmap#27](https://github.com/go-scikit/roadmap/issues/27)): @@ -36,7 +36,7 @@ those of the go-scikit performance campaign `TestRefSmoke` runs every NumPy call once. - **One case per public function** (a function with several shapes of use has several rows, `Array.SumAxis/axis0` and `/axis1`), or a named exemption with - its reason in [perf-exempt.md](https://github.com/go-ndarray/ndarray/blob/v0.39.0/docs/perf-exempt.md). CI fails on a public function + its reason in [perf-exempt.md](https://github.com/go-ndarray/ndarray/blob/v0.40.1/docs/perf-exempt.md). CI fails on a public function with neither. ## float32 Max and Min (v0.39.0) @@ -49,6 +49,21 @@ take 0.77 µs (Max) and 0.74 µs (Min), against 1.40 and 1.32 µs with SSE2 and NumPy varied from 64 to 113 µs across runs, so no ranking is claimed at that size ([go-simd/floats#46](https://github.com/go-simd/floats/issues/46)). +## riscv64 float32 GEMM (v0.40.0) + +On riscv64 with vector registers of at least 256 bits, float32 `MatMul` uses an +8×16 tile at LMUL=2 (#112). SpacemiT X60, one core, square float32 products: + +| | 64² | 256² | 1024² | +|---|---:|---:|---:| +| before | 185 µs | 7.19 ms | 462 ms | +| after | ~142 µs | 4.49 ms | 356 ms | +| OpenBLAS 0.3.34 | 105 µs | 5.34 ms | 380 ms | + +At 256² and 1024² it is faster than OpenBLAS; at 64² it is still 1.35× slower, so +[#107](https://github.com/go-ndarray/ndarray/issues/107) stays open. The entry is +in [performance history](performance-history.md). + ## What a row times Each row calls the Go function once on a vector of 100 000 elements (a 1000 x diff --git a/content/en/random.md b/content/en/random.md index 83893d1..02b21f3 100644 --- a/content/en/random.md +++ b/content/en/random.md @@ -8,9 +8,9 @@ description: "numpy.random with NumPy's numbers for the same seed: the bit gener tags: [random, numpy] --- -> Mirrored from [`docs/random.md`](https://github.com/go-ndarray/ndarray/blob/v0.39.0/docs/random.md) at v0.39.0. +> Mirrored from [`docs/random.md`](https://github.com/go-ndarray/ndarray/blob/v0.40.1/docs/random.md) at v0.40.1. -Package [`random`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.39.0/random) is `numpy.random` over go-ndarray arrays. Its goal +Package [`random`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.40.1/random) is `numpy.random` over go-ndarray arrays. Its goal is migration: a notebook moved from NumPy to Go keeps its numbers for the same seed. @@ -24,7 +24,7 @@ u, _ := random.Rand(3) // np.random.rand(3) ``` `Example`, `ExampleSeed` and `ExampleGenerator_ChoiceN` in -[`example_test.go`](https://github.com/go-ndarray/ndarray/blob/v0.39.0/random/example_test.go) print NumPy's own numbers. +[`example_test.go`](https://github.com/go-ndarray/ndarray/blob/v0.40.1/random/example_test.go) print NumPy's own numbers. ## What is implemented @@ -142,7 +142,7 @@ random arguments. Used as-is, that made 3% of `np.random.randn` values and 10% of `lognormal` values one ULP off. So `random` rounds `log`, `log1p`, `exp`, `expm1` and `pow` **correctly** -([`libm.go`](https://github.com/go-ndarray/ndarray/blob/v0.39.0/random/libm.go)): a fast evaluation to about 2⁻⁶⁸ with Ziv's +([`libm.go`](https://github.com/go-ndarray/ndarray/blob/v0.40.1/random/libm.go)): a fast evaluation to about 2⁻⁶⁸ with Ziv's rounding test, and a double-double fallback (about 2⁻¹⁰⁰) for the one argument in ~2¹⁵ that needs it. Checked against mpmath at 300 bits on 63,000 arguments (0 misrounded; the committed `libm.json` keeps 8,400), and the fast paths diff --git a/content/en/roadmap.md b/content/en/roadmap.md index ae1dea6..cdd43a9 100644 --- a/content/en/roadmap.md +++ b/content/en/roadmap.md @@ -8,7 +8,7 @@ description: "The plan for go-ndarray and what ships today." tags: [roadmap] --- -> Mirrored from [`docs/plan-ndarray.md`](https://github.com/go-ndarray/ndarray/blob/v0.39.0/docs/plan-ndarray.md) at v0.39.0. +> Mirrored from [`docs/plan-ndarray.md`](https://github.com/go-ndarray/ndarray/blob/v0.40.1/docs/plan-ndarray.md) at v0.40.1. > Goal: a **pure-Go (CGO=0)** NumPy-style N-dimensional array library, as a > **standalone, reusable** module with correct scalar kernels now and a clean @@ -112,7 +112,7 @@ suite (plus the per-arch CI jobs already wired in `.github/workflows/ci.yml`). - **Performance — DONE (beats NumPy on its core ops; matmul at tuned-BLAS parity).** Several levers behind the kernel seam, measured honestly vs NumPy 2.2.4 (see [docs/perf.md](performance.md) and the repo's - [BENCHMARKS.md](https://github.com/go-ndarray/ndarray/blob/v0.39.0/BENCHMARKS.md)): + [BENCHMARKS.md](https://github.com/go-ndarray/ndarray/blob/v0.40.1/BENCHMARKS.md)): - **Multicore.** `Add/Sub/Mul/Div/Map`, `Sum/Max/Min`, the axis reductions, `Concatenate`/`Stack`, and the GEMM fan out across `GOMAXPROCS` above a size threshold (small arrays stay serial). Plus an allocation fix: the diff --git a/content/en/security.md b/content/en/security.md index 85d7f80..0c78749 100644 --- a/content/en/security.md +++ b/content/en/security.md @@ -8,7 +8,7 @@ description: "How to report a vulnerability, what the library guarantees, and th tags: [security] --- -> Mirrored from [`SECURITY.md`](https://github.com/go-ndarray/ndarray/blob/main/SECURITY.md) at v0.39.0. +> Mirrored from [`SECURITY.md`](https://github.com/go-ndarray/ndarray/blob/main/SECURITY.md) at v0.40.1. ## Reporting @@ -105,6 +105,18 @@ runs whichever `gemm32` the CPU selects) and the root suite on a real SpacemiT X60, and CI's riscv64 lane runs it with V enabled. This entry was written after the v0.38.0 tag; the code it describes is that release's. +**2026-11-11 (go-ndarray/ndarray#107).** A second riscv64 float32 kernel, +`gemmMicro8x16RVV`, runs where the vector registers are at least 256 bits +(`gemmVLENB`, a `VSETVLI` with AVL = VLMAX, read once at start-up; E32 with +LMUL=2 only yields vl = 16 from VLEN 256). It reads `kc·8` and `kc·16` packed +floats and one 8×16 tile of C; its wrapper `gemmMicro32x8` bounds-checks +`pa[kc*8-1]`, `pb[kc*16-1]` and `dst[7*ldc+15]` before the call, like +`gemmMicro32`, which still serves narrower cores. The kernel loads no step past +`kc` (the unrolled pass is preceded by a `kc mod 2` single-step loop). The +shared 8-row A packer `packRows8` slices every row to `kc` elements (checked) +and is covered by `TestPackRows8`. Both kernels run through the float32 suite on +the X60 (`TestGemm32NarrowKernel`, `TestGemm32WideKernel`, the fence test). + **2026-11-07 (v0.36.0).** The AVX2 float64 log kernel (`logAVX2`) reads and writes at most `n` doubles, a positive multiple of 4 chosen by the Go wrapper, and returns how many it wrote; the wrapper finishes the block it diff --git a/hugo.yaml b/hugo.yaml index 6b72904..b176599 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -6,7 +6,7 @@ # have used since the site was built with MkDocs and mike. The CI sets it # through --baseURL, from params.ndarray.version below. This default is the # same build. -baseURL: "https://go-ndarray.github.io/docs/0.39/" +baseURL: "https://go-ndarray.github.io/docs/0.40/" title: "go-ndarray" # themes/hextra is the tannevaled/hextra fork, pinned at a release tag: # upstream Hextra plus opt-in features (partial menu items, combos, @@ -100,7 +100,7 @@ params: # The ndarray release these pages describe. Its minor version is the # documentation's version label (v0.9.1 -> 0.9): the CI reads it here. ndarray: - version: "v0.39.0" + version: "v0.40.1" navbar: displayTitle: true