From 6354adff6d8acca312c78e17c364885f29c0d947 Mon Sep 17 00:00:00 2001 From: tannevaled Date: Sun, 15 Nov 2026 21:31:20 +0100 Subject: [PATCH] docs: ndarray v0.44.0 Every mirrored page, hugo.yaml (version and baseURL /docs/0.44/) and the README now point at v0.44.0. Re-synced from the v0.44.0 sources, which changed since v0.43.1: performance.md (docs/perf.md: the table measured at c198892, "Since the v0.41.0 table"). The other mirrored sources (roadmap, dtypes, linalg, random, security, and the accuracy section of the README) are unchanged and only relabelled. The home page quotes the new counts (186 slower, 51 faster, 19 tied) and says Ravel is a view when the elements are one row-major run. performance-history.md is left alone. Refs go-ndarray/ndarray#125 Co-Authored-By: Claude Sonnet 5.5 --- README.md | 2 +- content/en/_index.md | 6 +-- content/en/accuracy.md | 2 +- content/en/dtypes.md | 2 +- content/en/linalg.md | 4 +- content/en/performance.md | 106 +++++++++++++++++++++++++++++--------- content/en/random.md | 8 +-- content/en/roadmap.md | 4 +- content/en/security.md | 2 +- hugo.yaml | 4 +- 10 files changed, 98 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 05a2c2a..b34f89d 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ describes**: | Source | Published under | | --- | --- | -| branch `main`, with `params.ndarray.version: v0.43.1` in `hugo.yaml` | `https://go-ndarray.github.io/docs//`, here `/docs/0.43/` | +| branch `main`, with `params.ndarray.version: v0.44.0` in `hugo.yaml` | `https://go-ndarray.github.io/docs//`, here `/docs/0.44/` | | 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/_index.md b/content/en/_index.md index b97cb96..f571a3b 100644 --- a/content/en/_index.md +++ b/content/en/_index.md @@ -38,7 +38,7 @@ WebAssembly, with nothing to install — build a pipeline step by step (creation | --- | --- | | Dtypes ([page](dtypes.md)) | bool, int8…int64, uint8…uint64, float32/float64, complex64/complex128 with NumPy 2 promotion: `AsType`, `ZerosOf`, `FromSlice`, `Data[T]`/`Item[T]`, weak Go scalars with `Scalar` | | Creation | `New`, `Zeros`, `Ones`, `Full`, `Arange`, `Linspace`, `Eye`, `Identity`, `FromData` | -| Views & shape | `Slice` (`All`/`R`/`Rng`/`From`/`To`/`Step`), `Reshape`, `Ravel`, `Transpose`, `Copy` | +| Views & shape | `Slice` (`All`/`R`/`Rng`/`From`/`To`/`Step`), `Reshape`, `Ravel` (a view when the elements are one row-major run, as `numpy.ravel`), `Transpose`, `Copy`, `Flatten` | | Elementwise | `Add`/`Sub`/`Mul`/`Div` (+`*Scalar`, +`*Into`), `Map`, `Neg`, `Abs`, comparisons (`Greater`/`Equal`/… → Bool masks), `Maximum`/`Minimum`, `Logical*`, `Real`/`Imag`/`Conj`/`Angle` | | Ufuncs | `Sqrt`, `Exp`, `Log`/`Log2`/`Log10`, `Sin`/`Cos`/`Tan`, `Floor`/`Ceil`, `Round` (half to even, as `np.round`; `RoundHalfAway` keeps the old rule), `Square`, `Power` | | Reductions | `Sum`, `Mean`, `Max`/`Min`, `Prod`, `ArgMax`/`ArgMin`, `CumSum`/`CumProd`, `Clip`, `Where` (+ per-axis) | @@ -115,8 +115,8 @@ is wrong on subnormals ([Performance](performance.md)): one row per public function (or a named exemption), against the pinned NumPy 2.5.4, `GOMAXPROCS=1` and one BLAS thread, interleaved rounds, refused at a 1-minute load of 8 or more, with the -allocation count of every row checked in CI. The table measured at v0.41.0 has -188 of 256 rows slower than NumPy and 54 faster ([ndarray#118](https://github.com/go-ndarray/ndarray/issues/118) +allocation count of every row checked in CI. The table measured at `c198892` (the code of v0.44.0) has +186 of 256 rows slower than NumPy, 51 faster and 19 tied ([ndarray#118](https://github.com/go-ndarray/ndarray/issues/118) tracks the slower rows by cause). The earlier multicore comparison with single-threaded NumPy is kept as [Performance history](performance-history.md) for its kernel-level analysis; its ratios are not a verdict. diff --git a/content/en/accuracy.md b/content/en/accuracy.md index 8576b02..ebc8022 100644 --- a/content/en/accuracy.md +++ b/content/en/accuracy.md @@ -8,7 +8,7 @@ description: "What go-ndarray promises about its results: a stated error bound, tags: [accuracy, numpy, math/big] --- -> Mirrored from [`README.md`](https://github.com/go-ndarray/ndarray/blob/v0.43.1/README.md#accuracy-contract) at v0.43.1. +> Mirrored from [`README.md`](https://github.com/go-ndarray/ndarray/blob/v0.44.0/README.md#accuracy-contract) at v0.44.0. 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. diff --git a/content/en/dtypes.md b/content/en/dtypes.md index ba08ef3..abb4224 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.43.1/docs/design-dtypes.md) at v0.43.1. +> Mirrored from [`docs/design-dtypes.md`](https://github.com/go-ndarray/ndarray/blob/v0.44.0/docs/design-dtypes.md) at v0.44.0. > 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 877e08d..6b0cb17 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.43.1/docs/linalg.md) at v0.43.1. +> Mirrored from [`docs/linalg.md`](https://github.com/go-ndarray/ndarray/blob/v0.44.0/docs/linalg.md) at v0.44.0. -Package [`linalg`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.43.1/linalg) gives ndarray arrays the functions of +Package [`linalg`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.44.0/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 packed SIMD GEMM of [go-blas/blas](https://github.com/go-blas/blas), which ndarray's `MatMul` uses too (the same kernels, moved there in v0.42.0, #122). diff --git a/content/en/performance.md b/content/en/performance.md index 01c45e5..1187526 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.43.1/docs/perf.md) at v0.43.1. +> Mirrored from [`docs/perf.md`](https://github.com/go-ndarray/ndarray/blob/v0.44.0/docs/perf.md) at v0.44.0. -The table is [perf-table.md](https://github.com/go-ndarray/ndarray/blob/v0.43.1/docs/perf-table.md), generated by +The table is [perf-table.md](https://github.com/go-ndarray/ndarray/blob/v0.44.0/docs/perf-table.md), generated by [refbench](https://github.com/go-scikit/refbench) (go-scikit/refbench v0.3.0) -from [perf.json](https://github.com/go-ndarray/ndarray/blob/v0.43.1/docs/perf.json); nothing in it is edited by hand. The rules are +from [perf.json](https://github.com/go-ndarray/ndarray/blob/v0.44.0/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.43.1/docs/perf-exempt.md). CI fails on a public function + its reason in [perf-exempt.md](https://github.com/go-ndarray/ndarray/blob/v0.44.0/docs/perf-exempt.md). CI fails on a public function with neither. ## What a row times @@ -72,27 +72,77 @@ go test -run 'TestDataParity|TestRefSmoke' -perf.parity . # needs uv ## Status -The table is **measured** at v0.41.0 (`de3f41ac`) on one pinned core of cfarm420 -(AMD EPYC 7773X, Zen 3). The 1-minute load over the rounds was 4.12 to 5.56, -and all 256 rows are valid. +The table is **measured** at `c198892` (the head of the `feat/ravel-real-views` +branch, clean) on 2026-11-15, on one pinned core of cfarm420 (AMD EPYC 7773X, +Zen 3), NumPy 2.5.4. The 1-minute load over the rounds was 3.01 to 3.86, and +all 256 rows are valid. It replaces the table measured at v0.41.0 +(`de3f41ac`, 2026-11-14, load 4.12 to 5.56), and the section below lists what +differs. -**188 rows are slower than NumPy and 54 are faster.** Every slower row is an +**186 rows are slower than NumPy, 51 are faster and 19 tie** (v0.41.0: 188, 54 +and 14). Every slower row is an open defect. They are tracked by cause in [#118](https://github.com/go-ndarray/ndarray/issues/118) rather than in one issue per row: -- result allocation: the allocating `Add` is 3.1× slower, while `AddInto` ties (1.03); -- elementwise operations without a vector kernel: `Ceil` is 20× slower, `Abs` 12×; -- copies where NumPy returns a view or wraps the buffer; -- `linalg` at 64 × 64 (1.4–4×); -- the `fft` shifts; +- result allocation: the allocating `Add` is 3.7× slower, while `AddInto` is + within 7% (1.07); +- elementwise operations: the unary `Ceil` (5.4×), `Floor` (5.3×), `Square` + (4.9×), `Round`, `Abs` and `Neg` (4.6×) now run on vector kernels and what + remains is the result allocation; `Maximum`, `Minimum` and `Power` + (5.3–5.5×) and `Log2` (4.2×) are the worst of the others; +- copies where NumPy returns a view or wraps the buffer (`Flatten` 5.0×, + `Copy` 4.8×, `Imag` 4.9×); +- `linalg` at 64 × 64 (1.5–4×); +- the `fft` shifts (9.7× and 9.9×); - the `random` draws built on `log`/`exp`. -Faster, for example: `SqrtInto` (0.51), `fft.FFT` (0.54), `Sum` (0.70), `Exp` (0.89). - -### Since the table - -Fixed after v0.41.0, measured by `go test -bench` on the same core, not yet -by a new table run. On 10⁵ float64 at load 2.2–2.4, over three interleaved +Faster, for example: `SqrtInto` (0.52), `fft.FFT` (0.64), `Sum` (0.76), `Log10` +(0.57). `Exp` (0.92) ties. + +### Since the v0.41.0 table + +The changes below were made after v0.41.0 and are included in the table above. +The ratios of this table against the v0.41.0 table (Go time / NumPy time, 10⁵ +float64): + +| row | v0.41.0 | now | allocations | +|---|---:|---:|---| +| `Ravel` | 566.8 | 0.35 | 4 → 3 | +| `Real` | 565.9 | 0.57 | 4 → 3 | +| `Ceil` | 20.4 | 5.44 | 5 | +| `Floor` | 19.2 | 5.28 | 5 | +| `Round` | 13.8 | 4.63 | 5 | +| `Abs` | 11.9 | 4.61 | 5 | +| `Square` | 11.0 | 4.88 | 5 | +| `Neg` | 10.3 | 4.59 | 5 | +| `AddScalar` | 8.56 | 5.40 | 8 | +| `Full` | 8.00 | 5.96 | 5 | +| `Ones` | 7.34 | 5.83 | 5 | +| `fft.RFFT2` | 1.41 | 1.14 | 31 → 30 | +| `fft.RFFT2With` | 1.50 | 1.28 | 31 → 30 | +| `fft.IHFFT` | 1.33 | 1.10 | 35 → 34 | +| `fft.IHFFTWith` | 1.22 | 1.20 | 35 → 34 | +| `fft.RFFTN` | 0.95 | 0.89 | 32 → 31 | +| `fft.RFFTNWith` | 0.92 | 0.81 | 32 → 31 | +| `fft.RFFT` | 0.90 | 0.84 | 30 → 29 | +| `fft.RFFTWith` | 0.95 | 0.97 | 30 → 29 | + +`Ravel` and `Real` are now faster than NumPy, and the `fft` real-input +transforms each save one allocation because they call `x.Real()`, which is a +view. The unary rows remain slower than NumPy, by about 5× instead of 10–20×: +they still allocate the result, which `AddInto` shows to be the main part of +the remaining gap (`Add` 3.74, `AddInto` 1.07). + +Treat small ratio changes with care: the two tables were measured at different +loads, and rows whose code did not change moved by as much as 0.2 to 0.3 +(`Sqrt` 1.01 to 1.20, `fft.IRFFT` 0.72 to 1.06, `AddInto` 1.03 to 1.07, +`fft.HFFT` 1.01 to 1.11). Only the rows above whose +change comes from a known code change, and whose size exceeds that spread, are +claimed as effects. The `fft` ratios in the table above (0.03 to 0.2 lower) are +within that spread, so only the allocation counts are attributed to `Real`. + +The measurements that follow were made at the time by `go test -bench` on the +same core. On 10⁵ float64 at load 2.2–2.4, over three interleaved rounds: - The scalar forms (`AddScalar` … `DivScalar`, `AddInto` … `DivInto`, and any Float64 operation with a one-element operand against a contiguous @@ -131,8 +181,14 @@ rounds: `Round` was measured in a second run of the same kind (four interleaved rounds, load 2.25 to 2.42), v0.42.0 against this change. `RoundHalfAway`, the control on the scalar path, takes 324–345 µs in the same run. These are - times of the Go code against itself; no NumPy ratio is claimed here, as the - new table run has not been made. + times of the Go code against itself; the NumPy ratios are in the table above. +- `Ravel` of a contiguous array and `Real` of a real array return views, as + NumPy does, instead of copying (the table's rows were 566× slower than + NumPy, which returns views). On 10⁵ float64, cfarm420, one pinned core, three + interleaved rounds at load 2.1 to 2.3: `Ravel` went from 83–90 µs to 93–101 + ns and `Real` from 84–91 µs to 101–104 ns, 803 kB to 128 B per call. The + new table measures them against NumPy at 61 ns and 90 ns against 174 ns and + 157 ns (ratios 0.35 and 0.57). This is a behaviour change (see the README). What remains of the allocation cause is Go's own cost. A CPU profile of a bare `make([]float64, 100000)` shows about 60% garbage-collector marking (assists @@ -140,7 +196,7 @@ in the allocating goroutine) and about 23% zeroing. NumPy frees each result when its last reference goes and reuses that memory warm. In Go, the way to avoid both costs is to not allocate: use the `*Into` forms or a `Workspace`. -The run was made from the release's own code. The test binary was -cross-compiled from a clean v0.41.0 worktree, the tag was shipped to the host -as a git bundle, and the binary ran from outside the clone so that the tree -stayed clean. Done that way, the recorded commit is the tag itself. +The run was made from the measured commit's own code. The test binary was +cross-compiled from a clean checkout of `c198892`, the commit was shipped to +the host as a git bundle, and the binary ran from outside the clone so that the +tree stayed clean. Done that way, the recorded commit is `c198892` itself. diff --git a/content/en/random.md b/content/en/random.md index e306469..5752874 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.43.1/docs/random.md) at v0.43.1. +> Mirrored from [`docs/random.md`](https://github.com/go-ndarray/ndarray/blob/v0.44.0/docs/random.md) at v0.44.0. -Package [`random`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.43.1/random) is `numpy.random` over go-ndarray arrays. Its goal +Package [`random`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.44.0/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.43.1/random/example_test.go) print NumPy's own numbers. +[`example_test.go`](https://github.com/go-ndarray/ndarray/blob/v0.44.0/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.43.1/random/libm.go)): a fast evaluation to about 2⁻⁶⁸ with Ziv's +([`libm.go`](https://github.com/go-ndarray/ndarray/blob/v0.44.0/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 8bc2e71..60744f3 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.43.1/docs/plan-ndarray.md) at v0.43.1. +> Mirrored from [`docs/plan-ndarray.md`](https://github.com/go-ndarray/ndarray/blob/v0.44.0/docs/plan-ndarray.md) at v0.44.0. > 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 @@ -118,7 +118,7 @@ suite (plus the per-arch CI jobs already wired in `.github/workflows/ci.yml`). NumPy. What follows is the history of the levers behind the kernel seam, measured then against NumPy 2.2.4 (see [docs/perf.md](performance.md) and the repo's - [BENCHMARKS.md](https://github.com/go-ndarray/ndarray/blob/v0.43.1/BENCHMARKS.md)): + [BENCHMARKS.md](https://github.com/go-ndarray/ndarray/blob/v0.44.0/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 092d225..7a80fb5 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.43.1. +> Mirrored from [`SECURITY.md`](https://github.com/go-ndarray/ndarray/blob/main/SECURITY.md) at v0.44.0. ## Reporting diff --git a/hugo.yaml b/hugo.yaml index fadf2f3..ea86c86 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.43/" +baseURL: "https://go-ndarray.github.io/docs/0.44/" 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.43.1" + version: "v0.44.0" navbar: displayTitle: true