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.29.1` in `hugo.yaml` | `https://go-ndarray.github.io/docs/<MAJOR.MINOR>/`, here `/docs/0.29/` |
| branch `main`, with `params.ndarray.version: v0.31.0` in `hugo.yaml` | `https://go-ndarray.github.io/docs/<MAJOR.MINOR>/`, here `/docs/0.31/` |
| 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
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.30.0/docs/design-dtypes.md) at v0.30.0.
> Mirrored from [`docs/design-dtypes.md`](https://github.com/go-ndarray/ndarray/blob/v0.31.0/docs/design-dtypes.md) at v0.31.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.30.0/docs/linalg.md) at v0.30.0.
> Mirrored from [`docs/linalg.md`](https://github.com/go-ndarray/ndarray/blob/v0.31.0/docs/linalg.md) at v0.31.0.

Package [`linalg`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.30.0/linalg) gives ndarray arrays the functions of
Package [`linalg`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.31.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 ndarray package's packed SIMD GEMM.

Expand Down
72 changes: 69 additions & 3 deletions content/en/performance.md
Original file line number Diff line number Diff line change
Expand Up @@ -1403,9 +1403,46 @@ Ruled out on that host, by A/B:
nothing, and NC = 128 or 256 (a B block well inside the 1 MiB L2) moves
float64 by 4–9% but float32 1024² by +4%.

The cause is not found. The quiet-host ratios above stand for a quiet host,
and this one for a contended one. The exception is float64 at 1024² on Zen 3, where we are 3% faster.
The float32 kernels for riscv64 and loong64 are still to write.
On the same host quiet again (load 2, 2026-11-01), measured back to back
with NumPy on the same pinned core, the ratio is:

| N1, load 2, ours / NumPy | 64² | 256² | 1024² |
|---|---:|---:|---:|
| float64 | 1.09 | 1.07 | 1.16 |
| float32 | 1.08 | **1.00** | 1.07 |

Our float64 1024² went from 192 ms busy to 137 ms quiet, and NumPy's from
124 to 118 ms. So the defect is the sensitivity to a busy host, not the
quiet-host speed.

Hardware counters (`perf stat`, `perf record -e ll_cache_miss_rd`) locate
it. Per product, at about the same instruction count, we have 4.5× the
L1D refills, 1.6× the L2 refills and 1.7× the last-level read misses of
OpenBLAS (IPC 1.73 against 2.09). The last level is shared, so contention
there costs us more. The misses fall in the micro-kernel: 36.7M in
`gemmUA4x8D`, against 23.4M in OpenBLAS's kernel plus 2.1M in its A
packing and 1.7M in its B packing (about 10 products each).

Six candidate causes were tested by A/B with counters, and none closes the
gap:

- a regression;
- reading A in place;
- block sizes, alone (KC 320, MC 240; NC 128, 256, 4096);
- writing C (a fresh, zeroed C against a reused one: misses ±1%);
- software prefetch after `dgemm_kernel_8x4.S` (L2 refills 14.1M → 6.2M,
but last-level misses unchanged and the times worse);
- OpenBLAS's whole structure at once: packed A plus KC 320, MC 240,
NC 4096 (last-level misses 56M against OpenBLAS's 31M).

What is left is how the micro-kernel itself touches memory. Closing it
would mean rewriting the N1 kernel after OpenBLAS's instruction by
instruction.

On Zen 3, by contrast, float64 at 1024² is 3% faster than NumPy.

The float32 kernels for riscv64 and loong64 are written (PRs #80 and #81)
but not yet measured on hardware.

**Open: the allocating operations.** `Add` is still 1.5–3.2× slower than
NumPy's `a+b`, for float64 as well. The kernel is no longer the difference,
Expand All @@ -1432,6 +1469,35 @@ What does remove it:
- **Tune the GC:** `GOGC` or `GOMEMLIMIT` for a program dominated by
short-lived results.

### float32 `Exp` and `Log` on the float64 kernels (2026-11-01)

float32 `Exp` and `Log` called `math.Exp` and `math.Log` per element: 6–14×
slower than NumPy's float32 SIMD on one Zen 3 core. They now run this
package's float64 kernels (the ports of Arm's optimized-routines, 0.504 ULP
worst case in float64). Elements go 256 at a time through a stack buffer:
widened (exact), computed in place, rounded once. Nothing is allocated. The
result is within 0.5 + 2⁻²⁹ float32 ULP, so correctly rounded except
next to a rounding midpoint. Overflow and underflow come from the rounding:
exp(89) is finite in float64 and rounds to +Inf.

| float32, one Zen 3 core (`abbench`, 8 rounds) | before | after | NumPy 2.5.4 | after / NumPy |
|---|---:|---:|---:|---:|
| `Exp`, 16 Ki | 297 µs | 84 µs | 26 µs | 3.2 |
| `Log`, 16 Ki | 198 µs | 99 µs | 32 µs | 3.1 |
| `Exp`, 1 Mi | 18.8 ms | 5.2 ms | 1.73 ms | 3.0 |
| `Log`, 1 Mi | 12.4 ms | 6.1 ms | 2.02 ms | 3.0 |

The tests hold the results to `float32(math.Exp/Log(x))`, within one ULP and
equal on at least 99.9% of 100 000 inputs. They also check the edges
(±0, ±Inf, NaN, overflow, the subnormals, log of a negative), every length
across the chunk boundaries, in-place use and the parallel split.

**Open defect: still 3× slower than NumPy.** NumPy computes float32 exp and
log in float32 SIMD (`simd_exp_f32`/`simd_log_f32` in
`loops_exponent_log.dispatch.c.src`). Porting those kernels per architecture
is the next step. float64 `Log` is also 1.23× slower than NumPy at 16 Ki on
Zen 3 (85 µs against 69 µs), while float64 `Exp` is 16% faster.

## SIMD coverage

- **amd64 (SSE2)** ships hand-vectorized `sum` (4-accumulator `ADDPD`), `sqrt`
Expand Down
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.30.0/docs/random.md) at v0.30.0.
> Mirrored from [`docs/random.md`](https://github.com/go-ndarray/ndarray/blob/v0.31.0/docs/random.md) at v0.31.0.

Package [`random`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.30.0/random) is `numpy.random` over go-ndarray arrays. Its goal
Package [`random`](https://pkg.go.dev/github.com/go-ndarray/ndarray@v0.31.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.30.0/random/example_test.go) print NumPy's own numbers.
[`example_test.go`](https://github.com/go-ndarray/ndarray/blob/v0.31.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.30.0/random/libm.go)): a fast evaluation to about 2⁻⁶⁸ with Ziv's
([`libm.go`](https://github.com/go-ndarray/ndarray/blob/v0.31.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
6 changes: 3 additions & 3 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.30.0/docs/plan-ndarray.md) at v0.30.0.
> Mirrored from [`docs/plan-ndarray.md`](https://github.com/go-ndarray/ndarray/blob/v0.31.0/docs/plan-ndarray.md) at v0.31.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 @@ -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.30.0/BENCHMARKS.md)):
[BENCHMARKS.md](https://github.com/go-ndarray/ndarray/blob/v0.31.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 Expand Up @@ -168,7 +168,7 @@ suite (plus the per-arch CI jobs already wired in `.github/workflows/ci.yml`).
SIMD kernels on all six 64-bit targets for `Sum` (v0.14.0–v0.17.0) and for
`Add`/`Sub`/`Mul`/`Div` (v0.18.0) and `Sqrt` (v0.19.0). Still pure Go
for float32: nothing in `Max`/`Min` any more (v0.20.0 to v0.25.0
vectorised them on all six 64-bit targets, for float32 and float64), and the transcendental ufuncs. `MatMul` runs on the float64
vectorised them on all six 64-bit targets, for float32 and float64), and the transcendental ufuncs (float32 `Exp`/`Log` run the float64 kernels since v0.31.0, 2–3.5× faster but still 3× behind NumPy's float32 SIMD). `MatMul` runs on the float64
GEMM since v0.21.0, 77–90% faster than the triple loop, and since v0.26.0
on a native float32 GEMM on arm64 (NEON 8×8) and amd64 with FMA (6×16),
a further 53–61% faster, and since v0.28.0 on ppc64le (VSX 8×16, 37–59%
Expand Down
8 changes: 7 additions & 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.29.1.
> Mirrored from [`SECURITY.md`](https://github.com/go-ndarray/ndarray/blob/main/SECURITY.md) at v0.31.0.

## Reporting

Expand Down Expand Up @@ -76,6 +76,12 @@ standard library's known vulnerabilities; `govulncheck ./...` reports none.

## Audit log

**2026-11-01 (v0.31.0).** float32 `Exp` and `Log` widen their input 256
elements at a time into a fixed stack buffer and call the float64 kernels in
place. There is no allocation proportional to the input beyond the result,
and no index arithmetic beyond slices bounded by `len(dst)`. The source is
resliced to `len(dst)`, so a shorter source panics instead of being read past.

**2026-10-31 (v0.29.1).** The A-in-place GEMM kernels now take B's row
stride (`ldb`) and may read a row-major B operand in place: `kc` rows `ldb`
elements apart, `NR` elements each. The wrappers bounds-check
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.29/"
baseURL: "https://go-ndarray.github.io/docs/0.31/"
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.30.0"
version: "v0.31.0"

navbar:
displayTitle: true
Expand Down
Loading