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
17 changes: 10 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,16 @@ The numeric inner loops are kept behind a narrow kernel API. Behind it,
`GOMAXPROCS`); the sum reduction uses a **go-asmgen SIMD kernel** (NEON on
arm64, SSE2 on amd64); and `MatMul` is a **panel-packed, cache-blocked GEMM**
with a go-asmgen SIMD-FMA micro-kernel (NEON 4×8 on arm64, SSE2 4×4 on amd64) —
the OpenBLAS/BLIS structure. So go-ndarray **beats single-threaded NumPy** on its
core ops on large arrays — measured honestly in **[docs/perf.md](docs/perf.md)**
(e.g. on arm64 vs NumPy 2.2.4: Add/Mul ~2×, Sum ~2.4×; the packed GEMM is **3–7×
faster than the prior kernel** and sustains **~156 GFLOP/s**, reaching **~76% of
multi-threaded OpenBLAS**). Where a faster reference exists — `Sqrt`/`Max` small
sizes, and **tuned BLAS (OpenBLAS/MKL) for matmul** — it says so. It is a
**standalone, reusable** module and the cgo-free ndarray backend behind
the OpenBLAS/BLIS structure. So go-ndarray **beats single-threaded NumPy** on
its core ops on large arrays (Add/Mul ~2×, Sum ~2.4×), and `MatMul` reaches
**tuned-BLAS parity at 1024²**: ≈0.99× vs multi-threaded OpenBLAS 0.3.29 on an
arm64 VM (~203 GFLOP/s, up from an earlier ~156 GFLOP/s / 0.76× before the
by-lane-FMLA micro-kernel fix — see **[docs/perf.md](docs/perf.md)**), and
≈1.00× of single-threaded vecLib on an Apple M4 Max (~373 GFLOP/s), where it
also decisively **beats the pure-Go `gonum` 4–10×** at every size — see
**[BENCHMARKS.md](BENCHMARKS.md)**. Where a faster reference exists —
`Sqrt`/`Max` small sizes, and tuned BLAS at small matmul sizes — it says so.
It is a **standalone, reusable** module and the cgo-free ndarray backend behind
[go-embedded-ruby](https://github.com/go-embedded-ruby/ruby)'s `NDArray` class.

> ⚠️ **Status: float64 NumPy parity for the core surface, and faster than NumPy
Expand Down
53 changes: 33 additions & 20 deletions docs/plan-ndarray.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,26 +97,39 @@ suite (plus the per-arch CI jobs already wired in `.github/workflows/ci.yml`).
GEMM/dot kernels live in `internal/kernels` for the Phase 1 SIMD path. Matches
numpy 2.2.4. Blocked/transpose-aware and decomposition variants remain in
Phase 4.
- **Performance — IN PROGRESS (beats NumPy on its core ops).** Two levers behind
the kernel seam, measured honestly vs NumPy 2.2.4 on arm64 (see
[docs/perf.md](perf.md)):
- **Multicore.** `Add/Sub/Mul/Div/Map`, `Sum/Max/Min`, and the GEMM fan out
across `GOMAXPROCS` above a size threshold (small arrays stay serial). Plus
an allocation fix: the elementwise/reduce fast path no longer copies
broadcast operands for the same-shape contiguous case. Result on large
arrays: Add/Mul ~2×, Sum ~2.4×, MatMul ~2.7× faster than NumPy.
- **SIMD sum via go-asmgen — DONE for amd64 (SSE2) + arm64 (NEON).** A
4-accumulator reduction kernel, generated by go-asmgen and validated
per-arch in CI to a tight tolerance vs the scalar oracle (a reduction's
lane-parallel grouping is a valid reordering, not bit-identical — the same
trade-off as NumPy's pairwise sum). The other four targets keep the
validated scalar reduction (no vector-double asm in Go's loong64/ppc64le
assemblers; riscv64 V optional) and still win via multicore. Split-CI: the
pure-Go core + multicore are held to 100% statement coverage; the generated
`.s` is validated by the per-arch native/qemu execution jobs.
- **Still TODO:** SIMD `Sqrt`/`Max` kernels (currently trail NumPy), and a
register/cache-blocked GEMM (the parallel ikj GEMM beats reference BLAS but
a tuned OpenBLAS/MKL would lead).
- **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](perf.md) and the repo's
[BENCHMARKS.md](../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
elementwise/reduce fast path no longer copies broadcast operands for the
same-shape contiguous case. Result on large arrays: Add/Mul ~2×, Sum ~2.4×,
and the packed GEMM reaches **parity with single-threaded vecLib at 1024²**
(~373 GFLOP/s on an Apple M4 Max) while beating the pure-Go gonum **4–10×**
at every size. (A many-core join panic in the parallel GEMM was fixed in
the 2026-06-23 pass.)
- **SIMD via go-asmgen — DONE for amd64 (SSE2) + arm64 (NEON).** Hand-vectorized
`sum` (4-accumulator), `sqrt` (packed `SQRTPD` / NEON `FSQRT V.2D`),
`max`/`min` (`MAXPD`/`MINPD` + NaN scan / four-accumulator builtin), the
elementwise `add`/`sub`/`mul`/`div`, and the **GEMM micro-kernel** (NEON 4×8
by-lane FMLA on arm64, SSE2 4×4 on amd64), generated by go-asmgen and
validated per-arch in CI (bit-identical to the scalar oracle for the
elementwise/sqrt/max ops; tight-tolerance for the sum reduction, whose
lane-parallel grouping is a valid reordering — the same trade-off as
NumPy's pairwise sum). The other four targets keep the validated scalar
oracles plus a scalar 4×4 GEMM micro-kernel over the packed panels, and
still win via packing + cache-blocking + multicore. Split-CI: the pure-Go
core + multicore are held to 100% statement coverage; the generated `.s`
is validated by the per-arch native/qemu execution jobs.
- **SIMD `Sqrt`/`Max` and the packed, cache-blocked GEMM — DONE (no longer
TODO).** `Sqrt`/`Max`/`Min` now WIN vs single-threaded NumPy, and the
panel-packed, cache-blocked GEMM with its SIMD-FMA micro-kernel reaches
**parity with tuned BLAS** (single-threaded vecLib at 1024² on M4 Max,
≈0.99× vs multi-threaded OpenBLAS at n=1024 on an arm64 VM) and beats
gonum 4–10× everywhere. Remaining headroom is small-n per-call overhead
and an AVX2/FMA amd64 micro-kernel.
- **More reductions — DONE.** `ArgMax`/`ArgMin` (flat and per-axis with
keepdims), `CumSum`/`CumProd` (per-axis scans + flat), `Clip(lo,hi)`, and the
three-operand broadcasting `Where(cond,t,f)`. Match numpy 2.2.4.
Expand Down