From adc0e0b6dfa62134191249427bd688fc4635b22f Mon Sep 17 00:00:00 2001 From: tannevaled Date: Sun, 15 Nov 2026 18:17:44 +0100 Subject: [PATCH 1/4] perf: float64 Abs, Neg, Square, Floor, Ceil on go-simd/floats v0.23.0 kernels Bump go-simd/floats to v0.23.0 and route the contiguous float64 case of Abs, Neg, Square, Floor and Ceil through its SIMD kernels, still split across cores above kernels.ParThreshold. Results are bit for bit those of math.Abs, -x, x*x, math.Floor and math.Ceil (a signalling NaN may come back quieted). Round is unchanged: it rounds half away from zero, which floats.RoundEven does not. On 10^5 float64, one core of cfarm420: Abs 244-258 -> 70-75 us, Neg 243-249 -> 72-75, Square 243-247 -> 72-80, Floor 432-457 -> 73-81, Ceil 437-464 -> 72-81 (result allocation included). Refs go-ndarray/ndarray#118 Co-Authored-By: Claude Sonnet 5.5 --- README.md | 6 ++ bench/go.mod | 2 +- bench/go.sum | 4 +- benchmarks/unary_bench_test.go | 31 ++++++++ docs/perf.md | 28 +++++++ go.mod | 2 +- go.sum | 4 +- internal/kernels/unary.go | 36 +++++++++ ndarray.go | 4 +- ufunc.go | 6 +- unary_kernels_test.go | 129 +++++++++++++++++++++++++++++++++ 11 files changed, 241 insertions(+), 11 deletions(-) create mode 100644 benchmarks/unary_bench_test.go create mode 100644 internal/kernels/unary.go create mode 100644 unary_kernels_test.go diff --git a/README.md b/README.md index 769ea82..7f25cf0 100644 --- a/README.md +++ b/README.md @@ -141,6 +141,12 @@ one-core rule does not allow; it is kept as [docs/perf-history.md](docs/perf-history.md) for its kernel-level analysis, and its ratios are not a verdict. +Float64 `Abs`, `Neg`, `Square`, `Floor` and `Ceil` run on the SIMD kernels of +go-simd/floats (v0.23.0), bit for bit the results of `math.Abs`, `-x`, `x*x`, +`math.Floor` and `math.Ceil` (a signalling NaN may come back quieted): on 10⁵ +float64 on one core of cfarm420 they went from 243–464 µs to 70–81 µs +([docs/perf.md](docs/perf.md), *Since the table*). `Round` is unchanged. + On Apple silicon the GEMM reached parity with tuned BLAS at 1024² (OpenBLAS in an arm64 VM, single-threaded vecLib on an M4 Max), and every product beats the pure-Go `gonum` 4–10× (**[BENCHMARKS.md](BENCHMARKS.md)**). On the other diff --git a/bench/go.mod b/bench/go.mod index b222337..5d6883d 100644 --- a/bench/go.mod +++ b/bench/go.mod @@ -11,7 +11,7 @@ require ( github.com/go-blas/blas v0.2.1 // indirect github.com/go-fft/fft v0.29.0 // indirect github.com/go-fleettools/fleettools v0.81.0 // indirect - github.com/go-simd/floats v0.17.0 // indirect + github.com/go-simd/floats v0.23.0 // indirect golang.org/x/sys v0.49.0 // indirect ) diff --git a/bench/go.sum b/bench/go.sum index 43fe0a2..604416c 100644 --- a/bench/go.sum +++ b/bench/go.sum @@ -6,7 +6,7 @@ github.com/go-fleettools/fleettools v0.81.0 h1:UnMflmNw5b82Z+7Ums7UVaW5RrGuACCVm github.com/go-fleettools/fleettools v0.81.0/go.mod h1:y/o3p2HZAvto9J5G5gtPxhN45zgvaYFAXCY9RCK/lQw= github.com/go-scikit/refbench v0.3.0 h1:ng9b3FRwOWyarkoHHLar1bs43TWi9TydZeO29Yr9iSw= github.com/go-scikit/refbench v0.3.0/go.mod h1:PhJxvLwXiQeKLP2f5ndcb9k5k4PTvU1rSFJ/MKRCrU0= -github.com/go-simd/floats v0.17.0 h1:Dv0ZmZ3k0IavvHwQgstpUz+TeIf/gGJ9HEGQ/UART8Q= -github.com/go-simd/floats v0.17.0/go.mod h1:Aq5a6oY5pUqm9Hpi+iV2nrNmaaUb0rwHvUHIerXWSvA= +github.com/go-simd/floats v0.23.0 h1:aHEbbiVmhLmoR8FdUWDCHMRctFajm11wKnfbbs9FOxk= +github.com/go-simd/floats v0.23.0/go.mod h1:Aq5a6oY5pUqm9Hpi+iV2nrNmaaUb0rwHvUHIerXWSvA= golang.org/x/sys v0.49.0 h1:XbzkgYJHdqh/8m2Uu0W/dQv8nktxx4BFHp1M0gROTXA= golang.org/x/sys v0.49.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og= diff --git a/benchmarks/unary_bench_test.go b/benchmarks/unary_bench_test.go new file mode 100644 index 0000000..363a879 --- /dev/null +++ b/benchmarks/unary_bench_test.go @@ -0,0 +1,31 @@ +package benchmarks + +import "testing" + +// BenchmarkUnary times the float64 unary ufuncs on 10^5 elements, the size of +// the single-core table (#118). Round is not routed through a SIMD kernel (it +// rounds half away from zero, which go-simd/floats does not provide); it is +// here as the unchanged control. +func BenchmarkUnary(b *testing.B) { + const n = 100000 + x := vec(n) + ops := []struct { + name string + do func() + }{ + {"Abs", func() { _ = x.Abs() }}, + {"Neg", func() { _ = x.Neg() }}, + {"Square", func() { _ = x.Square() }}, + {"Floor", func() { _ = x.Floor() }}, + {"Ceil", func() { _ = x.Ceil() }}, + {"Round", func() { _ = x.Round() }}, + } + for _, op := range ops { + b.Run(op.name, func(b *testing.B) { + b.SetBytes(n * 8) + for i := 0; i < b.N; i++ { + op.do() + } + }) + } +} diff --git a/docs/perf.md b/docs/perf.md index e720f89..1a029af 100644 --- a/docs/perf.md +++ b/docs/perf.md @@ -95,6 +95,34 @@ rounds: element at a time. `Full` went from 131–135 µs to 84–104 µs. `Ones` calls `Full`. `FullOf`, which fills the other dtypes, was not timed. +- Float64 `Abs`, `Neg`, `Square`, `Floor` and `Ceil` run on the go-simd/floats + v0.23.0 kernels (above the parallel threshold, split across cores as before) + instead of a scalar loop through `Map`. The results are bit for bit those of + `math.Abs`, `-x`, `x*x`, `math.Floor` and `math.Ceil`, except that a + signalling NaN may come back quieted + (`TestUnaryKernelsBitIdentical`: edge table, lengths 0–33 and one above the + threshold). `go test -bench Unary` (`benchmarks/unary_bench_test.go`), 10⁵ + float64 including the result allocation, one pinned core of cfarm420 + (`GOMAXPROCS=1`, `taskset -c 9`), a test binary of v0.42.0 and one of this + change, four interleaved rounds of 1 s, 1-minute load 2.34 at the start and + 3.32 at the end. Before → after, range over the rounds: + + | operation | before (µs) | after (µs) | + |---|---|---| + | `Abs` | 244–258 | 70–75 | + | `Neg` | 243–249 | 72–75 | + | `Square` | 243–247 | 72–80 | + | `Floor` | 432–457 | 73–81 | + | `Ceil` | 437–464 | 72–81 | + + These are times of the Go code against itself; no NumPy ratio is claimed + here, as the new table run has not been made. `Round` is not on a kernel and + stays at 316–339 µs before and 291–303 µs after (the control): it rounds + half away from zero as `math.Round` does, while `floats.RoundEven` rounds + half to even, which is `np.round` but a different result on every half. + Changing `Round` to half-to-even is a decision for the maintainers, not part + of this change. + 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 in the allocating goroutine) and about 23% zeroing. NumPy frees each result diff --git a/go.mod b/go.mod index 03f28b9..a77b0ce 100644 --- a/go.mod +++ b/go.mod @@ -5,7 +5,7 @@ go 1.27.2 require ( github.com/go-blas/blas v0.2.1 github.com/go-fft/fft v0.29.0 - github.com/go-simd/floats v0.17.0 + github.com/go-simd/floats v0.23.0 ) require golang.org/x/sys v0.49.0 // indirect diff --git a/go.sum b/go.sum index c9567c6..9aabc36 100644 --- a/go.sum +++ b/go.sum @@ -2,7 +2,7 @@ github.com/go-blas/blas v0.2.1 h1:5uZfmvXVZn9CjE+I3DalALqWHdKz+rbBs8VffH3dAZo= github.com/go-blas/blas v0.2.1/go.mod h1:WjhlqzQ+RA8tS473f18QtcJl5Q0GonPs3RJIxT5G7Bk= github.com/go-fft/fft v0.29.0 h1:WtJb5K3dmbLWREvvZ50od0fxtjIBiXrg7mVybz/nPoA= github.com/go-fft/fft v0.29.0/go.mod h1:GN5V4TWCjV05ECqH1ONfjFM6Z1m2shqCdssxKGqQ41s= -github.com/go-simd/floats v0.17.0 h1:Dv0ZmZ3k0IavvHwQgstpUz+TeIf/gGJ9HEGQ/UART8Q= -github.com/go-simd/floats v0.17.0/go.mod h1:Aq5a6oY5pUqm9Hpi+iV2nrNmaaUb0rwHvUHIerXWSvA= +github.com/go-simd/floats v0.23.0 h1:aHEbbiVmhLmoR8FdUWDCHMRctFajm11wKnfbbs9FOxk= +github.com/go-simd/floats v0.23.0/go.mod h1:Aq5a6oY5pUqm9Hpi+iV2nrNmaaUb0rwHvUHIerXWSvA= golang.org/x/sys v0.49.0 h1:XbzkgYJHdqh/8m2Uu0W/dQv8nktxx4BFHp1M0gROTXA= golang.org/x/sys v0.49.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og= diff --git a/internal/kernels/unary.go b/internal/kernels/unary.go new file mode 100644 index 0000000..d7a5b0b --- /dev/null +++ b/internal/kernels/unary.go @@ -0,0 +1,36 @@ +package kernels + +import "github.com/go-simd/floats" + +// Unary float64 kernels from go-simd/floats (v0.23.0), parallelised above +// ParThreshold like the other elementwise kernels. Each is bit-identical to the +// scalar expression it replaces (math.Abs, -x, x*x, math.Floor, math.Ceil), a +// signalling NaN possibly coming back quieted. + +// unaryP runs k over dst/src, serially below ParThreshold and fanned across +// cores above it. len(src) >= len(dst) is required, as for the kernels. +func unaryP(k func(dst, src []float64), dst, src []float64) { + n := len(dst) + if n < ParThreshold { + k(dst, src) + return + } + parallelFor(n, numWorkers(n), func(lo, hi int) { + k(dst[lo:hi], src[lo:hi]) + }) +} + +// AbsP writes |src[i]| into dst[i]. +func AbsP(dst, src []float64) { unaryP(floats.Abs, dst, src) } + +// NegP writes -src[i] into dst[i]. +func NegP(dst, src []float64) { unaryP(floats.Neg, dst, src) } + +// SquareP writes src[i]*src[i] into dst[i]. +func SquareP(dst, src []float64) { unaryP(floats.Square, dst, src) } + +// FloorP writes math.Floor(src[i]) into dst[i]. +func FloorP(dst, src []float64) { unaryP(floats.Floor, dst, src) } + +// CeilP writes math.Ceil(src[i]) into dst[i]. +func CeilP(dst, src []float64) { unaryP(floats.Ceil, dst, src) } diff --git a/ndarray.go b/ndarray.go index 34b3936..e5253bb 100644 --- a/ndarray.go +++ b/ndarray.go @@ -842,7 +842,7 @@ func (a *Array) Neg() *Array { if a.dtype != Float64 { return a.intUnary(uNeg, (*Array).Neg) } - return a.Map(func(x float64) float64 { return -x }) + return a.unary(kernels.NegP) } // Abs returns the elementwise absolute value. @@ -852,7 +852,7 @@ func (a *Array) Abs() *Array { if a.dtype != Float64 { return a.intUnary(uAbs, (*Array).Abs) } - return a.Map(kernels.Abs) + return a.unary(kernels.AbsP) } // --- reductions ------------------------------------------------------------ diff --git a/ufunc.go b/ufunc.go index 06e4688..7935a47 100644 --- a/ufunc.go +++ b/ufunc.go @@ -167,7 +167,7 @@ func (a *Array) Floor() *Array { if a.dtype != Float64 { return a.exactUnary(uFloor, (*Array).Floor) } - return a.Map(math.Floor) + return a.unary(kernels.FloorP) } // Ceil returns the elementwise ceiling (least integer >= x). @@ -175,7 +175,7 @@ func (a *Array) Ceil() *Array { if a.dtype != Float64 { return a.exactUnary(uCeil, (*Array).Ceil) } - return a.Map(math.Ceil) + return a.unary(kernels.CeilP) } // Round returns the elementwise round-half-away-from-zero, matching math.Round. @@ -192,7 +192,7 @@ func (a *Array) Square() *Array { if a.dtype != Float64 { return a.intUnary(uSquare, (*Array).Square) } - return a.Map(func(x float64) float64 { return x * x }) + return a.unary(kernels.SquareP) } // Power returns the elementwise a**p (every element raised to p). diff --git a/unary_kernels_test.go b/unary_kernels_test.go new file mode 100644 index 0000000..f14fb53 --- /dev/null +++ b/unary_kernels_test.go @@ -0,0 +1,129 @@ +package ndarray + +import ( + "math" + "math/rand" + "testing" + + "github.com/go-ndarray/ndarray/internal/kernels" +) + +// unaryEdge is the table every float64 unary kernel is checked on. +func unaryEdge() []float64 { + nan := math.NaN() + snan := math.Float64frombits(0x7FF0000000000001) // signalling NaN + two52, two63 := math.Ldexp(1, 52), math.Ldexp(1, 63) + v := []float64{ + 0, math.Copysign(0, -1), math.Inf(1), math.Inf(-1), nan, -nan, snan, + math.Float64frombits(0xFFF8000000000123), + 5e-324, -5e-324, 2.2250738585072009e-308, -2.2250738585072014e-308, + math.MaxFloat64, -math.MaxFloat64, math.SmallestNonzeroFloat64, + 0.5, -0.5, 1.5, -1.5, 2.5, -2.5, 0.49999999999999994, -0.49999999999999994, + 1, -1, 0.1, -0.1, 3.7, -3.7, 1e-10, -1e-10, 1e10, -1e10, + 1e154, -1e154, 1e155, 1e-155, + } + for _, b := range []float64{two52, two63, math.Ldexp(1, 53), math.Ldexp(1, 62), math.Ldexp(1, 64)} { + for _, s := range []float64{1, -1} { + v = append(v, s*b, s*math.Nextafter(b, 0), s*math.Nextafter(b, math.Inf(1)), + s*(b+0.5), s*(b-0.5), s*(b/2+0.5)) + } + } + return v +} + +func sameBits(got, want float64) bool { + if math.IsNaN(want) { + return math.IsNaN(got) // a signalling NaN may come back quieted + } + return math.Float64bits(got) == math.Float64bits(want) +} + +// TestUnaryKernelsBitIdentical checks Abs, Neg, Square, Floor and Ceil against +// the math expression they replaced, on lengths 0..33 and one above the +// parallel threshold, cut from the edge table and random values. +func TestUnaryKernelsBitIdentical(t *testing.T) { + ops := []struct { + name string + do func(*Array) *Array + ref func(float64) float64 + }{ + {"Abs", (*Array).Abs, math.Abs}, + {"Neg", (*Array).Neg, func(x float64) float64 { return -x }}, + {"Square", (*Array).Square, func(x float64) float64 { return x * x }}, + {"Floor", (*Array).Floor, math.Floor}, + {"Ceil", (*Array).Ceil, math.Ceil}, + } + rng := rand.New(rand.NewSource(1)) + pool := unaryEdge() + for i := 0; i < 4096; i++ { + pool = append(pool, math.Float64frombits(rng.Uint64()), (rng.Float64()-0.5)*1e6, + math.Round(rng.Float64()*2000-1000)/2) + } + lengths := make([]int, 0, 35) + for n := 0; n <= 33; n++ { + lengths = append(lengths, n) + } + lengths = append(lengths, kernels.ParThreshold+37) + for _, op := range ops { + for _, n := range lengths { + for off := 0; off < 3; off++ { // different alignments of the table + src := make([]float64, n) + for i := range src { + src[i] = pool[(off*7+i*(1+off))%len(pool)] + } + if n > 64 { + copy(src, pool) // the whole edge table, in the parallel case + } + a, err := FromData(append([]float64(nil), src...), n) + if err != nil { + t.Fatal(err) + } + got := op.do(a).materialize() + if len(got) != n { + t.Fatalf("%s n=%d: len %d", op.name, n, len(got)) + } + for i, x := range src { + if w := op.ref(x); !sameBits(got[i], w) { + t.Fatalf("%s n=%d [%d] %#x: got %#x want %#x", op.name, n, i, + math.Float64bits(x), math.Float64bits(got[i]), math.Float64bits(w)) + } + } + in := a.materialize() + for i := range src { // the input is not modified + if !sameBits(in[i], src[i]) { + t.Fatalf("%s n=%d: input modified at %d", op.name, n, i) + } + } + } + } + } +} + +// TestUnaryKernelsStrided checks the non-contiguous path (a transposed view). +func TestUnaryKernelsStrided(t *testing.T) { + src := unaryEdge() + n := len(src) / 2 * 2 + a, err := FromData(append([]float64(nil), src[:n]...), 2, n/2) + if err != nil { + t.Fatal(err) + } + tr := a.Transpose() + view := tr.materialize() + for name, c := range map[string]struct { + got []float64 + ref func(float64) float64 + }{ + "Abs": {tr.Abs().materialize(), math.Abs}, + "Neg": {tr.Neg().materialize(), func(x float64) float64 { return -x }}, + "Square": {tr.Square().materialize(), func(x float64) float64 { return x * x }}, + "Floor": {tr.Floor().materialize(), math.Floor}, + "Ceil": {tr.Ceil().materialize(), math.Ceil}, + } { + for i, x := range view { + if !sameBits(c.got[i], c.ref(x)) { + t.Fatalf("%s strided [%d]: got %#x want %#x", name, i, + math.Float64bits(c.got[i]), math.Float64bits(c.ref(x))) + } + } + } +} From aa6438eab8166578c155269620fd156612eee87e Mon Sep 17 00:00:00 2001 From: tannevaled Date: Sun, 15 Nov 2026 18:29:33 +0100 Subject: [PATCH 2/4] docs: GEMM now in go-blas/blas; release tags for the two unreleased audit entries docs/linalg.md and docs/design-linalg.md named the ndarray package's own GEMM; since #122 it is go-blas/blas. SECURITY.md: the go-blas entry is v0.42.0 (#122, commit 208bdac, tag v0.42.0 contains it); the Choice gather entry is v0.40.2 (#115, 8ac94fb, first tag containing it, Refs #103). Co-Authored-By: Claude Sonnet 5.5 --- SECURITY.md | 4 ++-- docs/design-linalg.md | 2 +- docs/linalg.md | 3 ++- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 5399d2f..a5646c5 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -70,7 +70,7 @@ standard library's known vulnerabilities; `govulncheck ./...` reports none. ## Audit log -**2026-11-15 (unreleased).** The GEMM moved to +**2026-11-15 (v0.42.0, #122).** The GEMM moved to [go-blas/blas](https://github.com/go-blas/blas) v0.2.1 (the micro-kernels, their wrappers, the packing and their fence tests, byte for byte; the audit of that code is that repository's). What ndarray adds is `internal/blasmm`, which hands @@ -82,7 +82,7 @@ on an axis longer than one (a broadcast or reversed view) is copied to a contiguous matrix first. ndarray keeps the dot kernels (`dot_.go`), the mat-vec and the thread pool, with their wrappers and fences. -**2026-11-12 (unreleased, #103).** The gather of `random`'s `Choice` +**2026-11-12 (v0.40.2, #115, Refs #103).** The gather of `random`'s `Choice` (`takeAxis`, random/arrays.go) now copies bytes through `bytesOf`, an `unsafe.Slice` view of a slice's backing array of exactly `Len()·size` bytes. Every dtype the package stores is a fixed-size value without pointers diff --git a/docs/design-linalg.md b/docs/design-linalg.md index 9fecc39..eef0084 100644 --- a/docs/design-linalg.md +++ b/docs/design-linalg.md @@ -365,7 +365,7 @@ kd = 1, 5, 50; allocations counted exactly. ```text internal/libm/ correctly rounded log, log1p, exp, expm1, pow (moved from random/), + exp2, log2, hypot -internal/kernels/ refgemm micro-kernels (go-asmgen, every GOARCH), no FMA +internal/kernels/ dot, mat-vec and elementwise kernels (the GEMM micro-kernels are in go-blas/blas since v0.42.0) linalg/internal/lapack/ exact column-major ports of Reference-LAPACK v3.12.1, generic over 4 types refblas.go level 1-3 BLAS in netlib loop order (dnrm2 Blue, ddot, daxpy, dgemv, dger, dtrmv, dtrsv, dgemm, dtrmm, dtrsm, dsyrk) arith.go no-fuse helpers, gfortran complex mul/div, lamch, ilaenv, iparmq diff --git a/docs/linalg.md b/docs/linalg.md index 134db19..ab26d1b 100644 --- a/docs/linalg.md +++ b/docs/linalg.md @@ -2,7 +2,8 @@ Package [`linalg`](../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. +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). | numpy.linalg | linalg | |---|---| From a7093c299dfd290472ef1d59e7ff4213303785fd Mon Sep 17 00:00:00 2001 From: tannevaled Date: Sun, 15 Nov 2026 18:55:38 +0100 Subject: [PATCH 3/4] feat!: Round is half to even (np.round) on the RoundEven kernel; add RoundHalfAway Round now rounds exact halves to the even neighbour on every dtype (float64 on the go-simd/floats RoundEven kernel; float32 and each part of a complex number through math.RoundToEven), as np.round with no decimals. The old half-away-from-zero behaviour (math.Round) is RoundHalfAway, on the scalar path, on the same dtypes. Integers and bools are unchanged by both. There is no decimals variant. Tests: halves and the edge table for both against math.RoundToEven and math.Round; Abs and Neg now compared with strict NaN bits, the others with is-NaN only. On 10^5 float64, cfarm420 one core: Round 325-340 -> 71-80 us; RoundHalfAway (control) 324-345 us. Refs go-ndarray/ndarray#118 Co-Authored-By: Claude Sonnet 5.5 --- README.md | 22 +++++++++++----- benchmarks/unary_bench_test.go | 6 ++--- docs/coverage.md | 2 +- docs/design-dtypes.md | 1 - docs/perf.md | 27 ++++++++++--------- dtype_api_test.go | 16 +++++++++++- internal/kernels/unary.go | 3 +++ typed.go | 19 ++++++++------ ufunc.go | 22 +++++++++++++++- ufunc_test.go | 7 ++--- unary_kernels_test.go | 48 ++++++++++++++++++++-------------- 11 files changed, 117 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 7f25cf0..6b454a5 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,8 @@ returning strided views that share data. - **Elementwise** — `Add`/`Sub`/`Mul`/`Div` (+ scalar) with full **NumPy broadcasting**, `Map`/`Neg`/`Abs`, math **ufuncs** (`Sqrt`/`Exp`/`Log`/`Sin`/ - `Cos`/…), broadcasting **comparisons** (`Greater`/`Equal`/… returning Bool + `Cos`/…), rounding (`Floor`/`Ceil`, `Round` half to even as `np.round`, + `RoundHalfAway` the old half away from zero), broadcasting **comparisons** (`Greater`/`Equal`/… returning Bool masks), `Maximum`/`Minimum`, `Logical*`, and the complex parts `Real`/`Imag`/`Conj`/`Angle`. - **Reductions** — whole-array (`Sum`/`Prod`/`Max`/`Min`/`Mean`), per-axis @@ -141,11 +142,20 @@ one-core rule does not allow; it is kept as [docs/perf-history.md](docs/perf-history.md) for its kernel-level analysis, and its ratios are not a verdict. -Float64 `Abs`, `Neg`, `Square`, `Floor` and `Ceil` run on the SIMD kernels of -go-simd/floats (v0.23.0), bit for bit the results of `math.Abs`, `-x`, `x*x`, -`math.Floor` and `math.Ceil` (a signalling NaN may come back quieted): on 10⁵ -float64 on one core of cfarm420 they went from 243–464 µs to 70–81 µs -([docs/perf.md](docs/perf.md), *Since the table*). `Round` is unchanged. +Float64 `Abs`, `Neg`, `Square`, `Floor`, `Ceil` and `Round` run on the SIMD +kernels of go-simd/floats (v0.23.0), bit for bit the results of `math.Abs`, +`-x`, `x*x`, `math.Floor`, `math.Ceil` and `math.RoundToEven` (`Abs` and `Neg` +keep NaN bits exactly; for the others a signalling NaN may come back quieted): +on 10⁵ float64 on one core of cfarm420 they went from 243–464 µs to 70–81 µs +([docs/perf.md](docs/perf.md), *Since the table*). + +**Behaviour change in the next release (a MINOR): `Round` rounds halves to +even.** It is now `np.round` with no decimals, on every dtype (float64, float32 +and each part of a complex number): `Round` of 0.5, 1.5, 2.5 and -0.5 gives 0, 2, +2 and -0. Until v0.42.0 it rounded halves away from zero (1, 2, 3, -1), and +that behaviour is now `RoundHalfAway` (`math.Round`, the scalar path, the same +dtypes). The two differ only on exact halves; integers and bools are returned +unchanged by both. There is no decimals variant. On Apple silicon the GEMM reached parity with tuned BLAS at 1024² (OpenBLAS in an arm64 VM, single-threaded vecLib on an M4 Max), and every product beats the diff --git a/benchmarks/unary_bench_test.go b/benchmarks/unary_bench_test.go index 363a879..fd1a80f 100644 --- a/benchmarks/unary_bench_test.go +++ b/benchmarks/unary_bench_test.go @@ -3,9 +3,8 @@ package benchmarks import "testing" // BenchmarkUnary times the float64 unary ufuncs on 10^5 elements, the size of -// the single-core table (#118). Round is not routed through a SIMD kernel (it -// rounds half away from zero, which go-simd/floats does not provide); it is -// here as the unchanged control. +// the single-core table (#118). RoundHalfAway stays on the scalar path and is +// the control: it is what Round did before it became half-to-even. func BenchmarkUnary(b *testing.B) { const n = 100000 x := vec(n) @@ -19,6 +18,7 @@ func BenchmarkUnary(b *testing.B) { {"Floor", func() { _ = x.Floor() }}, {"Ceil", func() { _ = x.Ceil() }}, {"Round", func() { _ = x.Round() }}, + {"RoundHalfAway", func() { _ = x.RoundHalfAway() }}, } for _, op := range ops { b.Run(op.name, func(b *testing.B) { diff --git a/docs/coverage.md b/docs/coverage.md index bf8ff24..45a9082 100644 --- a/docs/coverage.md +++ b/docs/coverage.md @@ -114,7 +114,7 @@ backticked name in the first column. See "Counting" at the end. | `equal`, `not_equal`, `greater`, `greater_equal`, `less`, `less_equal` | `==`, `~=`, `>`, `>=`, `<`, `<=` | `Equal`, `NotEqual`, `Greater`, `GreaterEqual`, `Less`, `LessEqual` | done | | | `logical_and`, `logical_or`, `logical_xor`, `logical_not` | `&`, `\|`, `xor`, `~` | `LogicalAnd`, `LogicalOr`, `LogicalXor`, `LogicalNot` | done | | | `power`, `pow` | `.^` | `Power` | partial | scalar exponent only: no array exponent, no integer-power semantics | -| `around`, `round` | `round` | `Round` | partial | rounds half away from zero (NumPy: half to even); no `decimals` | +| `around`, `round` | `round` | `Round` | partial | half to even, as NumPy (`RoundHalfAway` is the old half away from zero); no `decimals` | | `clip` | `min(max(..))`, `rescale` | `Clip` | partial | array bounds, one-sided (`a_min` or `a_max` alone) | | `sinh`, `cosh`, `tanh`, `arcsinh`, `arccosh`, `arctanh`, `asinh`, `acosh`, `atanh` | `sinh`, `cosh`, `tanh`, `asinh`, `acosh`, `atanh` | | missing | scalar kernels (go-numerics/special or math), SIMD later | | `arcsin`, `arccos`, `arctan`, `asin`, `acos`, `atan` | `asin`, `acos`, `atan` | | missing | same | diff --git a/docs/design-dtypes.md b/docs/design-dtypes.md index 5afd98a..858737f 100644 --- a/docs/design-dtypes.md +++ b/docs/design-dtypes.md @@ -101,7 +101,6 @@ dtype by dtype after correctness, `float32` first. | NumPy | here | why | |---|---|---| | `float16` exists; `sqrt(int8)` is `float16` | no `float16`; `sqrt(int8)`, `sqrt(uint8)` and `sqrt(bool)` give `float32` | Go has no half-precision arithmetic; `float32` is the smallest type that holds the result exactly | -| `round` is half-to-even | half-away-from-zero (unchanged) | documented since v0.1.0 | | `datetime64`, `str_`, `object`, structured dtypes | absent | out of scope for a numeric library | ## Element access diff --git a/docs/perf.md b/docs/perf.md index 1a029af..2f728d2 100644 --- a/docs/perf.md +++ b/docs/perf.md @@ -95,13 +95,15 @@ rounds: element at a time. `Full` went from 131–135 µs to 84–104 µs. `Ones` calls `Full`. `FullOf`, which fills the other dtypes, was not timed. -- Float64 `Abs`, `Neg`, `Square`, `Floor` and `Ceil` run on the go-simd/floats - v0.23.0 kernels (above the parallel threshold, split across cores as before) - instead of a scalar loop through `Map`. The results are bit for bit those of - `math.Abs`, `-x`, `x*x`, `math.Floor` and `math.Ceil`, except that a - signalling NaN may come back quieted +- Float64 `Abs`, `Neg`, `Square`, `Floor`, `Ceil` and `Round` run on the + go-simd/floats v0.23.0 kernels (above the parallel threshold, split across + cores as before) instead of a scalar loop through `Map`. The results are bit + for bit those of `math.Abs`, `-x`, `x*x`, `math.Floor`, `math.Ceil` and + `math.RoundToEven`. `Abs` and `Neg` keep NaN bits exactly; for `Square`, + `Floor`, `Ceil` and `Round` a signalling NaN may come back quieted (`TestUnaryKernelsBitIdentical`: edge table, lengths 0–33 and one above the - threshold). `go test -bench Unary` (`benchmarks/unary_bench_test.go`), 10⁵ + threshold). `Round` is now half to even, as `np.round`; the old half away + from zero is `RoundHalfAway`, on the scalar path (see the README). `go test -bench Unary` (`benchmarks/unary_bench_test.go`), 10⁵ float64 including the result allocation, one pinned core of cfarm420 (`GOMAXPROCS=1`, `taskset -c 9`), a test binary of v0.42.0 and one of this change, four interleaved rounds of 1 s, 1-minute load 2.34 at the start and @@ -114,14 +116,13 @@ rounds: | `Square` | 243–247 | 72–80 | | `Floor` | 432–457 | 73–81 | | `Ceil` | 437–464 | 72–81 | + | `Round` (the old one was half away from zero) | 325–340 | 71–80 | - These are times of the Go code against itself; no NumPy ratio is claimed - here, as the new table run has not been made. `Round` is not on a kernel and - stays at 316–339 µs before and 291–303 µs after (the control): it rounds - half away from zero as `math.Round` does, while `floats.RoundEven` rounds - half to even, which is `np.round` but a different result on every half. - Changing `Round` to half-to-even is a decision for the maintainers, not part - of this change. + `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. 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 diff --git a/dtype_api_test.go b/dtype_api_test.go index 29b90e7..21d1378 100644 --- a/dtype_api_test.go +++ b/dtype_api_test.go @@ -310,9 +310,12 @@ func TestTypedUnary(t *testing.T) { if got := data[float32](t, h.Ceil()); !reflect.DeepEqual(got, []float32{2, -2}) { t.Errorf("float32 ceil = %v", got) } - if got := data[float32](t, h.Round()); !reflect.DeepEqual(got, []float32{2, -3}) { + if got := data[float32](t, h.Round()); !reflect.DeepEqual(got, []float32{2, -2}) { t.Errorf("float32 round = %v", got) } + if got := data[float32](t, h.RoundHalfAway()); !reflect.DeepEqual(got, []float32{2, -3}) { + t.Errorf("float32 RoundHalfAway = %v", got) + } if got := data[float32](t, h.Power(2)); !reflect.DeepEqual(got, []float32{2.25, 6.25}) { t.Errorf("float32 power = %v", got) } @@ -323,6 +326,17 @@ func TestTypedUnary(t *testing.T) { if got := c.Round(); got.AtComplex(0) != 3+4i { t.Errorf("complex round = %v", got) } + cz := must(FromSlice([]complex128{2.5 - 3.5i, -0.5 + 1.5i}, 2)) + if got := cz.Round(); got.AtComplex(0) != 2-4i || got.AtComplex(1) != complex(math.Copysign(0, -1), 2) { + t.Errorf("complex round half to even = %v", got) + } + if got := cz.RoundHalfAway(); got.AtComplex(0) != 3-4i || got.AtComplex(1) != -1+2i { + t.Errorf("complex RoundHalfAway = %v", got) + } + ii := must(FromSlice([]int32{-3, 4}, 2)) + if got := data[int32](t, ii.RoundHalfAway()); !reflect.DeepEqual(got, []int32{-3, 4}) { + t.Errorf("int RoundHalfAway = %v", got) + } mustPanic(t, "not defined for complex128", func() { c.Ceil() }) if r := i.Map(func(x float64) float64 { return x + 0.5 }); r.DType() != Float64 || r.At(0) != 1.5 { t.Errorf("int Map = %v", r) diff --git a/internal/kernels/unary.go b/internal/kernels/unary.go index d7a5b0b..d40d9fa 100644 --- a/internal/kernels/unary.go +++ b/internal/kernels/unary.go @@ -32,5 +32,8 @@ func SquareP(dst, src []float64) { unaryP(floats.Square, dst, src) } // FloorP writes math.Floor(src[i]) into dst[i]. func FloorP(dst, src []float64) { unaryP(floats.Floor, dst, src) } +// RoundEvenP writes math.RoundToEven(src[i]) into dst[i]. +func RoundEvenP(dst, src []float64) { unaryP(floats.RoundEven, dst, src) } + // CeilP writes math.Ceil(src[i]) into dst[i]. func CeilP(dst, src []float64) { unaryP(floats.Ceil, dst, src) } diff --git a/typed.go b/typed.go index 82de375..6482d48 100644 --- a/typed.go +++ b/typed.go @@ -252,16 +252,18 @@ const ( uNeg uAbs uPow + uRoundHalfAway ) // realFuncs are the float64 functions behind the unary codes. var realFuncs = [...]func(float64) float64{ uSqrt: math.Sqrt, uExp: math.Exp, uLog: math.Log, uLog2: log2, uLog10: math.Log10, uSin: math.Sin, uCos: math.Cos, uTan: math.Tan, - uFloor: math.Floor, uCeil: math.Ceil, uRound: math.Round, - uSquare: func(x float64) float64 { return x * x }, - uNeg: func(x float64) float64 { return -x }, - uAbs: math.Abs, + uFloor: math.Floor, uCeil: math.Ceil, uRound: math.RoundToEven, + uRoundHalfAway: math.Round, + uSquare: func(x float64) float64 { return x * x }, + uNeg: func(x float64) float64 { return -x }, + uAbs: math.Abs, } // complexFuncs are the complex128 functions behind the unary codes; nil where @@ -271,10 +273,11 @@ var complexFuncs = [...]func(complex128) complex128{ uLog2: func(z complex128) complex128 { return cmplx.Log(z) / math.Ln2 }, uLog10: cmplx.Log10, uSin: cmplx.Sin, uCos: cmplx.Cos, uTan: cmplx.Tan, uFloor: nil, uCeil: nil, - uRound: func(z complex128) complex128 { return complex(math.Round(real(z)), math.Round(imag(z))) }, - uSquare: func(z complex128) complex128 { return z * z }, - uNeg: func(z complex128) complex128 { return -z }, - uAbs: nil, // complex abs is real-valued: see absStore + uRound: func(z complex128) complex128 { return complex(math.RoundToEven(real(z)), math.RoundToEven(imag(z))) }, + uRoundHalfAway: func(z complex128) complex128 { return complex(math.Round(real(z)), math.Round(imag(z))) }, + uSquare: func(z complex128) complex128 { return z * z }, + uNeg: func(z complex128) complex128 { return -z }, + uAbs: nil, // complex abs is real-valued: see absStore } // unaryFloat32 applies f, computed in float64 and rounded, to float32 diff --git a/ufunc.go b/ufunc.go index 7935a47..14c10f8 100644 --- a/ufunc.go +++ b/ufunc.go @@ -178,11 +178,31 @@ func (a *Array) Ceil() *Array { return a.unary(kernels.CeilP) } -// Round returns the elementwise round-half-away-from-zero, matching math.Round. +// Round returns the elementwise rounding to the nearest integer, a half going +// to the even neighbour (2.5 gives 2, 3.5 gives 4, -0.5 gives -0), as +// np.round(a) with no decimals does and as math.RoundToEven. Float32 and +// complex elements round the same way (each part of a complex number), and +// integers and bools are returned unchanged. Before v0.43.0 Round rounded halves +// away from zero; that is RoundHalfAway. +// +// A Float64 array runs on the go-simd/floats RoundEven kernel. func (a *Array) Round() *Array { if a.dtype != Float64 { return a.exactUnary(uRound, (*Array).Round) } + return a.unary(kernels.RoundEvenP) +} + +// RoundHalfAway returns the elementwise rounding to the nearest integer, a half +// going away from zero (2.5 gives 3, -2.5 gives -3, 0.5 gives 1), as math.Round +// does and as Round did before v0.43.0. It differs from Round, and from +// np.round, only on exact halves: Round sends those to the even neighbour. +// The dtypes are the same as for Round (integers and bools unchanged, float32 +// and complex rounded part by part). It runs on the scalar path. +func (a *Array) RoundHalfAway() *Array { + if a.dtype != Float64 { + return a.exactUnary(uRoundHalfAway, (*Array).RoundHalfAway) + } return a.Map(math.Round) } diff --git a/ufunc_test.go b/ufunc_test.go index 22ff359..debbaad 100644 --- a/ufunc_test.go +++ b/ufunc_test.go @@ -43,10 +43,11 @@ func TestMathUfuncs(t *testing.T) { cc := mustArr(t, ok(FromData([]float64{1.2, -1.7}, 2))) eqFloats(t, cc.Ceil().materialize(), []float64{2, -1}) - // Round here is math.Round (half away from zero); this intentionally differs - // from numpy's banker's rounding, so 0.5 -> 1 and 2.5 -> 3. + // Round is half to even, as np.round: 0.5 -> 0 and 2.5 -> 2. RoundHalfAway + // is the old math.Round: 0.5 -> 1 and 2.5 -> 3. rc := mustArr(t, ok(FromData([]float64{0.5, 1.5, 2.5, -0.5}, 4))) - eqFloats(t, rc.Round().materialize(), []float64{1, 2, 3, -1}) + eqFloats(t, rc.Round().materialize(), []float64{0, 2, 2, 0}) + eqFloats(t, rc.RoundHalfAway().materialize(), []float64{1, 2, 3, -1}) sq := mustArr(t, ok(FromData([]float64{2, -3}, 2))) eqFloats(t, sq.Square().materialize(), []float64{4, 9}) diff --git a/unary_kernels_test.go b/unary_kernels_test.go index f14fb53..7961100 100644 --- a/unary_kernels_test.go +++ b/unary_kernels_test.go @@ -21,6 +21,8 @@ func unaryEdge() []float64 { 0.5, -0.5, 1.5, -1.5, 2.5, -2.5, 0.49999999999999994, -0.49999999999999994, 1, -1, 0.1, -0.1, 3.7, -3.7, 1e-10, -1e-10, 1e10, -1e10, 1e154, -1e154, 1e155, 1e-155, + 3.5, -3.5, 4.5, -4.5, 1e15 + 0.5, -(1e15 + 0.5), 1e15 + 1.5, 4503599627370495.5, + -4503599627370495.5, 4503599627370494.5, 2.5000000000000004, 1.4999999999999998, } for _, b := range []float64{two52, two63, math.Ldexp(1, 53), math.Ldexp(1, 62), math.Ldexp(1, 64)} { for _, s := range []float64{1, -1} { @@ -31,9 +33,12 @@ func unaryEdge() []float64 { return v } -func sameBits(got, want float64) bool { - if math.IsNaN(want) { - return math.IsNaN(got) // a signalling NaN may come back quieted +// sameBits compares bit patterns. Unless strict, a NaN matches any NaN: a +// signalling NaN may come back quieted from Square, Floor, Ceil and Round. Abs +// and Neg keep NaN bits exactly, so they are compared strictly. +func sameBits(got, want float64, strict bool) bool { + if !strict && math.IsNaN(want) { + return math.IsNaN(got) } return math.Float64bits(got) == math.Float64bits(want) } @@ -43,15 +48,18 @@ func sameBits(got, want float64) bool { // parallel threshold, cut from the edge table and random values. func TestUnaryKernelsBitIdentical(t *testing.T) { ops := []struct { - name string - do func(*Array) *Array - ref func(float64) float64 + name string + do func(*Array) *Array + ref func(float64) float64 + strict bool // NaN bits must match exactly }{ - {"Abs", (*Array).Abs, math.Abs}, - {"Neg", (*Array).Neg, func(x float64) float64 { return -x }}, - {"Square", (*Array).Square, func(x float64) float64 { return x * x }}, - {"Floor", (*Array).Floor, math.Floor}, - {"Ceil", (*Array).Ceil, math.Ceil}, + {"Abs", (*Array).Abs, math.Abs, true}, + {"Neg", (*Array).Neg, func(x float64) float64 { return -x }, true}, + {"Square", (*Array).Square, func(x float64) float64 { return x * x }, false}, + {"Floor", (*Array).Floor, math.Floor, false}, + {"Ceil", (*Array).Ceil, math.Ceil, false}, + {"Round", (*Array).Round, math.RoundToEven, false}, + {"RoundHalfAway", (*Array).RoundHalfAway, math.Round, false}, } rng := rand.New(rand.NewSource(1)) pool := unaryEdge() @@ -83,14 +91,14 @@ func TestUnaryKernelsBitIdentical(t *testing.T) { t.Fatalf("%s n=%d: len %d", op.name, n, len(got)) } for i, x := range src { - if w := op.ref(x); !sameBits(got[i], w) { + if w := op.ref(x); !sameBits(got[i], w, op.strict) { t.Fatalf("%s n=%d [%d] %#x: got %#x want %#x", op.name, n, i, math.Float64bits(x), math.Float64bits(got[i]), math.Float64bits(w)) } } in := a.materialize() for i := range src { // the input is not modified - if !sameBits(in[i], src[i]) { + if !sameBits(in[i], src[i], true) { t.Fatalf("%s n=%d: input modified at %d", op.name, n, i) } } @@ -113,14 +121,16 @@ func TestUnaryKernelsStrided(t *testing.T) { got []float64 ref func(float64) float64 }{ - "Abs": {tr.Abs().materialize(), math.Abs}, - "Neg": {tr.Neg().materialize(), func(x float64) float64 { return -x }}, - "Square": {tr.Square().materialize(), func(x float64) float64 { return x * x }}, - "Floor": {tr.Floor().materialize(), math.Floor}, - "Ceil": {tr.Ceil().materialize(), math.Ceil}, + "Abs": {tr.Abs().materialize(), math.Abs}, + "Neg": {tr.Neg().materialize(), func(x float64) float64 { return -x }}, + "Square": {tr.Square().materialize(), func(x float64) float64 { return x * x }}, + "Floor": {tr.Floor().materialize(), math.Floor}, + "Ceil": {tr.Ceil().materialize(), math.Ceil}, + "Round": {tr.Round().materialize(), math.RoundToEven}, + "RoundHalfAway": {tr.RoundHalfAway().materialize(), math.Round}, } { for i, x := range view { - if !sameBits(c.got[i], c.ref(x)) { + if !sameBits(c.got[i], c.ref(x), name == "Abs" || name == "Neg") { t.Fatalf("%s strided [%d]: got %#x want %#x", name, i, math.Float64bits(c.got[i]), math.Float64bits(c.ref(x))) } From 92898819f8b9758d6fab2e10b46e63c7aec1648a Mon Sep 17 00:00:00 2001 From: tannevaled Date: Sun, 15 Nov 2026 19:07:06 +0100 Subject: [PATCH 4/4] docs: exempt Array.RoundHalfAway from the perf table (no NumPy counterpart) TestPerf requires every public function to have a row or an exemption. RoundHalfAway rounds halves away from zero; np.round is half to even, which is Array.Round, so there is nothing to time it against. Refs go-ndarray/ndarray#118 Co-Authored-By: Claude Sonnet 5.5 --- docs/perf-exempt.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/perf-exempt.md b/docs/perf-exempt.md index 36a194c..4210322 100644 --- a/docs/perf-exempt.md +++ b/docs/perf-exempt.md @@ -11,6 +11,7 @@ Each is named with the reason it has no case (refbench's coverage rule). Every o - `Array.Display`: builds a Jupyter MIME bundle; NumPy has no counterpart - `Array.Map`: takes a Go callback per element; the NumPy counterpart (np.vectorize) is a Python loop, not a kernel - `Array.Ndim`: attribute read +- `Array.RoundHalfAway`: rounds halves away from zero (math.Round); NumPy has no counterpart (np.round is half to even, which is `Array.Round`) - `Array.SetComplex`: one scalar element access, a few ns; the NumPy counterpart is dominated by the Python interpreter, not a kernel - `Array.Set`: one scalar element access, a few ns; the NumPy counterpart is dominated by the Python interpreter, not a kernel - `Array.Shape`: attribute read