Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ describes**:

| Source | Published under |
| --- | --- |
| branch `main`, with `params.ndarray.version: v0.44.0` in `hugo.yaml` | `https://go-ndarray.github.io/docs/<MAJOR.MINOR>/`, here `/docs/0.44/` |
| branch `main`, with `params.ndarray.version: v0.45.0` in `hugo.yaml` | `https://go-ndarray.github.io/docs/<MAJOR.MINOR>/`, here `/docs/0.45/` |
| the newest version | also `https://go-ndarray.github.io/docs/latest/` |

`https://go-ndarray.github.io/docs/` redirects to `latest/`. Each push to
Expand Down
4 changes: 2 additions & 2 deletions content/en/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `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)
allocation count of every row checked in CI. The table measured at `37c1b86` (shipped in v0.45.0) has
185 of 256 rows slower than NumPy, 54 faster and 17 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.
Expand Down
2 changes: 1 addition & 1 deletion content/en/accuracy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.44.0/README.md#accuracy-contract) at v0.44.0.
> Mirrored from [`README.md`](https://github.com/go-ndarray/ndarray/blob/v0.45.0/README.md#accuracy-contract) at v0.45.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.

Expand Down
2 changes: 1 addition & 1 deletion content/en/dtypes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.44.0/docs/design-dtypes.md) at v0.44.0.
> Mirrored from [`docs/design-dtypes.md`](https://github.com/go-ndarray/ndarray/blob/v0.45.0/docs/design-dtypes.md) at v0.45.0.

> Status: implemented (Phase 2). Supersedes decision 4 of
> [plan-ndarray.md](roadmap.md) ("`float64` first").
Expand Down
4 changes: 2 additions & 2 deletions content/en/linalg.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.44.0/docs/linalg.md) at v0.44.0.
> Mirrored from [`docs/linalg.md`](https://github.com/go-ndarray/ndarray/blob/v0.45.0/docs/linalg.md) at v0.45.0.

Package [`linalg`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.44.0/linalg) gives ndarray arrays the functions of
Package [`linalg`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.45.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).
Expand Down
105 changes: 57 additions & 48 deletions content/en/performance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.44.0/docs/perf.md) at v0.44.0.
> Mirrored from [`docs/perf.md`](https://github.com/go-ndarray/ndarray/blob/v0.45.0/docs/perf.md) at v0.45.0.

The table is [perf-table.md](https://github.com/go-ndarray/ndarray/blob/v0.44.0/docs/perf-table.md), generated by
The table is [perf-table.md](https://github.com/go-ndarray/ndarray/blob/v0.45.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.44.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.45.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)):

Expand All @@ -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.44.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.45.0/docs/perf-exempt.md). CI fails on a public function
with neither.

## What a row times
Expand Down Expand Up @@ -72,32 +72,32 @@ go test -run 'TestDataParity|TestRefSmoke' -perf.parity . # needs uv

## Status

The table is **measured** at `c198892` (the head of the `feat/ravel-real-views`
The table is **measured** at `37c1b86` (the head of the `perf/fftshift-one-pass`
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
Zen 3), NumPy 2.5.4. The 1-minute load over the rounds was 2.62 to 3.99, 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.

**186 rows are slower than NumPy, 51 are faster and 19 tie** (v0.41.0: 188, 54
**185 rows are slower than NumPy, 54 are faster and 17 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.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×);
- result allocation: the allocating `Add` is 3.9× slower, while `AddInto` is
within 5% (1.05);
- elementwise operations: the unary `Ceil` (6.0×), `Floor` (5.8×), `Square`
(5.5×), `Abs` (5.5×), `Neg` (5.4×) and `Round` (4.7×) now run on vector
kernels and what remains is the result allocation; `Maximum`, `Minimum` and
`Power` (5.3–5.8×) and `Log2` (4.0×) are the worst of the others;
- copies where NumPy returns a view or wraps the buffer (`Flatten` 5.7×,
`Copy` 5.8×, `Imag` 5.2×);
- `linalg` at 64 × 64 (1.5–3.9×);
- the `fft` shifts, now 2.0× (they were 9.7× and 9.9×);
- the `random` draws built on `log`/`exp`.

Faster, for example: `SqrtInto` (0.52), `fft.FFT` (0.64), `Sum` (0.76), `Log10`
(0.57). `Exp` (0.92) ties.
Faster, for example: `SqrtInto` (0.50), `fft.FFT` (0.52), `Sum` (0.80), `Log10`
(0.57). `Exp` (0.98) ties.

### Since the v0.41.0 table

Expand All @@ -107,39 +107,48 @@ 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 |
| `fft.FFTShift` | 9.72 | 2.03 | 29 → 9 |
| `fft.IFFTShift` | 9.90 | 2.02 | 29 → 9 |
| `Ravel` | 566.8 | 0.36 | 4 → 3 |
| `Real` | 565.9 | 0.58 | 4 → 3 |
| `Ceil` | 20.4 | 5.95 | 5 |
| `Floor` | 19.2 | 5.75 | 5 |
| `Round` | 13.8 | 4.67 | 5 |
| `Abs` | 11.9 | 5.48 | 5 |
| `Square` | 11.0 | 5.51 | 5 |
| `Neg` | 10.3 | 5.44 | 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 |
| `Full` | 8.00 | 5.51 | 5 |
| `Ones` | 7.34 | 5.30 | 5 |
| `fft.RFFT2` | 1.41 | 1.17 | 31 → 30 |
| `fft.RFFT2With` | 1.50 | 1.15 | 31 → 30 |
| `fft.IHFFT` | 1.33 | 1.04 | 35 → 34 |
| `fft.IHFFTWith` | 1.22 | 1.05 | 35 → 34 |
| `fft.RFFTN` | 0.95 | 0.75 | 32 → 31 |
| `fft.RFFTNWith` | 0.92 | 0.73 | 32 → 31 |
| `fft.RFFT` | 0.90 | 0.75 | 30 → 29 |
| `fft.RFFTWith` | 0.95 | 0.79 | 30 → 29 |

`fft.FFTShift` and `fft.IFFTShift` now shift in one pass (the allocation count
falls from 29 to 9), and their ratio from about 9.8 to 2.0. This change is
well above the run-to-run spread below. They remain slower than NumPy.

`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).
the remaining gap (`Add` 3.85, `AddInto` 1.05).

Treat small ratio changes with care: the two tables were measured at different
Treat small ratio changes with care: the 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`.
(`Sqrt` 1.01 to 1.32, `fft.IRFFT` 0.72 to 0.74 in the third run but 1.06 in
the second, `SubScalar` 4.81 to 7.11 between two runs of the same code). Only
the rows above whose change comes from a known code change, and whose size
exceeds that spread, are claimed as effects: `FFTShift` and `IFFTShift`,
`Ravel` and `Real`, and the allocation counts. The other `fft` real-input
ratios (0.1 to 0.3 lower than at v0.41.0) are within or near that spread, so
only their allocation counts are attributed to `Real`, and the elementwise
ratios do not show a difference between kernels.

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
Expand Down Expand Up @@ -187,8 +196,8 @@ rounds:
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).
new table measures them against NumPy at 63 ns and 97 ns against 174 ns and
168 ns (ratios 0.36 and 0.58). 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
Expand All @@ -197,6 +206,6 @@ 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 measured commit's own code. The test binary was
cross-compiled from a clean checkout of `c198892`, the commit was shipped to
cross-compiled from a clean checkout of `37c1b86`, 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.
tree stayed clean. Done that way, the recorded commit is `37c1b86` itself.
8 changes: 4 additions & 4 deletions content/en/random.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.44.0/docs/random.md) at v0.44.0.
> Mirrored from [`docs/random.md`](https://github.com/go-ndarray/ndarray/blob/v0.45.0/docs/random.md) at v0.45.0.

Package [`random`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.44.0/random) is `numpy.random` over go-ndarray arrays. Its goal
Package [`random`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.45.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.

Expand All @@ -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.44.0/random/example_test.go) print NumPy's own numbers.
[`example_test.go`](https://github.com/go-ndarray/ndarray/blob/v0.45.0/random/example_test.go) print NumPy's own numbers.

## What is implemented

Expand Down Expand Up @@ -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.44.0/random/libm.go)): a fast evaluation to about 2⁻⁶⁸ with Ziv's
([`libm.go`](https://github.com/go-ndarray/ndarray/blob/v0.45.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
Expand Down
4 changes: 2 additions & 2 deletions content/en/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.44.0/docs/plan-ndarray.md) at v0.44.0.
> Mirrored from [`docs/plan-ndarray.md`](https://github.com/go-ndarray/ndarray/blob/v0.45.0/docs/plan-ndarray.md) at v0.45.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
Expand Down Expand Up @@ -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.44.0/BENCHMARKS.md)):
[BENCHMARKS.md](https://github.com/go-ndarray/ndarray/blob/v0.45.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
Expand Down
2 changes: 1 addition & 1 deletion content/en/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.44.0.
> Mirrored from [`SECURITY.md`](https://github.com/go-ndarray/ndarray/blob/main/SECURITY.md) at v0.45.0.

## Reporting

Expand Down
4 changes: 2 additions & 2 deletions hugo.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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.44/"
baseURL: "https://go-ndarray.github.io/docs/0.45/"
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,
Expand Down Expand Up @@ -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.44.0"
version: "v0.45.0"

navbar:
displayTitle: true
Expand Down
Loading