diff --git a/README.md b/README.md index 5afc467..d18e977 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/plan-ndarray.md b/docs/plan-ndarray.md index 4bb9def..91a7895 100644 --- a/docs/plan-ndarray.md +++ b/docs/plan-ndarray.md @@ -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.