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
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,9 @@
PCG64DXSM, MT19937, Philox, SFC64; `Generator` (`DefaultRNG`: uniform,
integers, ziggurat normal/exponential, gamma, beta, binomial, Poisson,
choice, shuffle, … 40 samplers) and the legacy `RandomState` behind
`random.Seed(0)` / `random.Rand(…)`. Bit-exact against NumPy 2.5.3 on
`random.Seed(0)` / `random.Rand(…)`; allocation-free scalar draws for
solvers (`Float64`, `FillUniform`, `IntN`, `FillIntN`, `ShuffleInt64` on both,
NumPy's stream consumed call for call). Bit-exact against NumPy 2.5.3 on
x86-64; see [docs/random.md](docs/random.md) for the few ULP-level
exceptions (C-library `log`/`exp` rounding) and NumPy's own aarch64 drift.
- **Notebooks and storage** — `Repr` prints what NumPy 2.5.3's `repr` prints
Expand Down
25 changes: 25 additions & 0 deletions docs/random.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,30 @@ u, _ := random.Rand(3) // np.random.rand(3)
| `rand`, `randn`, `randint`, `random_sample`, `normal`, `uniform`, `choice`, `shuffle`, `permutation`, `binomial`, `poisson`, `standard_normal`, `standard_exponential`, `exponential`, `standard_gamma`, `gamma`, `chisquare`, `lognormal`, `multinomial`, `bytes` | `RandomState` methods of the same names |
| `np.random.seed`, `rand`, `randn`, `randint`, `random_sample`, `normal`, `uniform`, `choice`, `shuffle`, `permutation`, `binomial`, `poisson` | package functions over a shared `RandomState` behind a mutex |

### Allocation-free scalar draws

Every sampler above returns a `*ndarray.Array`. A solver that needs a few draws
per candidate (differential evolution, basin hopping) would spend its time
allocating, so `Generator` and `RandomState` both have five methods that draw
into caller storage or return a Go scalar, allocate nothing, and consume
exactly the bit-generator output NumPy consumes for the same call:

| NumPy | `Generator` / `RandomState` |
|---|---|
| `random()` / `random_sample()`, `size=None` | `Float64() float64` |
| `uniform(low, high, size=len(dst))` | `FillUniform(dst []float64, low, high float64) error` (Generator: error when `high-low` is negative, NaN or infinite; legacy: only NaN or infinite, `high < low` is accepted) |
| `integers(0, high)` / `randint(0, high)`, `size=None`, int64 | `IntN(high int64) int64` (Lemire for `Generator`, masked rejection for `RandomState`; panics when `high <= 0`, like `math/rand`) |
| `integers(0, high, size=len(dst))` / `randint(…)` | `FillIntN(dst []int64, high int64) error` (error when `high <= 0` and `dst` is not empty; nothing is drawn) |
| `shuffle(x)` of a 1-D int64 array | `ShuffleInt64(d []int64)` (Fisher-Yates from the end, `random_interval`) |

A failing call draws nothing, as in NumPy. A mixed sequence of 32-bit and
64-bit draws keeps PCG64's buffered half-word exactly as NumPy does.
`testdata/scalar.py` and `TestScalarDrawsMatchNumPy` compare 7 296 calls on 192
scripts (48 seeds × Generator over PCG64 and MT19937, `RandomState` over MT19937
and PCG64) with NumPy 2.5.3, errors included; `TestScalarAllocations` asserts
zero allocations with `testing.AllocsPerRun`; `FuzzScalarDraws` throws NaN,
±Inf, negative and zero bounds, `MaxInt64` and `MinInt64` at them.

The size comes last; no size gives a 0-d array holding what NumPy returns as a
scalar (`size=None`), which draws exactly the same values. `ChoiceOptions`'
zero value is NumPy's defaults (`NoReplace`, `NoShuffle` are the negations).
Expand Down Expand Up @@ -213,6 +237,7 @@ interface. The samplers that call `pow`/`exp` per draw cost about what
uv run --python cpython-3.12-macos-x86_64 --with numpy==2.5.3 python random/testdata/cases.py > random/testdata/cases.json
uv run --with mpmath python random/testdata/libm.py > random/testdata/libm.json
uv run --with mpmath python random/testdata/libm_tables.py > random/zz_libm_tables.go
GONDARRAY_REGEN=1 go test ./random -run TestRegenerateScalarFixture # scalar.json: x86-64 NumPy in an amd64 container
python3 random/testdata/zig2go.py <numpy>/numpy/random/src/distributions/ziggurat_constants.h random/zz_ziggurat.go
```

Expand Down
4 changes: 4 additions & 0 deletions random/doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@
// RandomSample, Normal, Uniform, Choice, Shuffle, Permutation, Binomial
// and Poisson over a shared one.
//
// For solvers that draw a few values per step, Generator and RandomState also
// have allocation-free scalar draws that consume NumPy's stream call for call:
// Float64, FillUniform, IntN, FillIntN and ShuffleInt64.
//
// Results are arrays with NumPy's dtypes and shapes: the size arguments come
// last (numpy's size), and no size gives a 0-d array holding what NumPy
// returns as a scalar. Parameters are scalars (NumPy also broadcasts array
Expand Down
182 changes: 182 additions & 0 deletions random/scalar.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,182 @@
package random

import "math"

// Allocation-free scalar draws.
//
// Every sampler of Generator and RandomState returns a *ndarray.Array, even
// for one value; a solver that needs a handful of draws per candidate would
// spend more time allocating than evaluating. The methods here draw into
// caller storage or return a Go scalar, consume exactly the bit-generator
// output NumPy consumes for the same call, and allocate nothing on their
// success path.
//
// Sources (NumPy v2.5.3, opened): numpy/random/_generator.pyx (uniform,
// shuffle, _shuffle_raw), mtrand.pyx (uniform, randint, shuffle, _shuffle_raw),
// _bounded_integers.pyx.in (_rand_int64: scalar and sized paths both call
// random_bounded_uint64_fill) and src/distributions/distributions.c
// (random_uniform, random_interval, random_bounded_uint64_fill).

// uniformRange is the range numpy's uniform(low, high) passes to
// random_uniform. Both classes reject a range that is not finite
// (OverflowError); Generator also rejects a negative one (ValueError), the
// legacy RandomState accepts high < low.
func uniformRange(low, high float64, legacy bool) (float64, error) {
rng := high - low
if math.IsInf(rng, 0) || math.IsNaN(rng) {
if legacy {
return 0, valueErr("Range exceeds valid bounds")
}
return 0, valueErr("high - low range exceeds valid bounds")
}
if !legacy {
if err := nonNegative(rng, "high - low"); err != nil {
return 0, err
}
}
return rng, nil
}

// fillUniform is random_uniform in a loop: low + rng*next_double. The
// float64 conversion forbids a fused multiply-add, which NumPy's x86-64
// builds do not use.
func fillUniform(bg BitGenerator, dst []float64, low, rng float64) {
if p, ok := bg.(*PCG64); ok {
for i := range dst {
dst[i] = low + float64(rng*uint64ToDouble(p.Uint64()))
}
return
}
for i := range dst {
dst[i] = low + float64(rng*bg.Float64())
}
}

// intN is _rand_int64(0, high) for one value: random_bounded_uint64_fill
// with cnt = 1 on the range [0, high-1].
func intN(bg BitGenerator, high int64, masked bool) int64 {
if high <= 0 {
panic(boundsErr(false, 0))
}
rng := uint64(high - 1)
if !masked && rng != 0 && rng < 0xFFFFFFFF {
if p, ok := bg.(*PCG64); ok {
return int64(lemire32PCG(p, uint32(rng)))
}
}
return int64(boundedUint64(bg, 0, rng, masked))
}

// fillIntN is _rand_int64(0, high, size=len(dst)). An empty dst draws
// nothing and is never an error, as numpy returns an empty array first.
func fillIntN(bg BitGenerator, dst []int64, high int64, masked bool) error {
if len(dst) == 0 {
return nil
}
if high <= 0 {
return boundsErr(false, 0)
}
fillUint64(bg, 0, uint64(high-1), masked, asUint64(dst))
return nil
}

// shuffleInterval is _shuffle_raw with first = 1 (and the legacy
// _shuffle_raw, which is the same loop): Fisher-Yates from the last element
// down to the second, each j from random_interval(i).
func shuffleInterval(bg BitGenerator, d []int64) {
if p, ok := bg.(*PCG64); ok {
for i := len(d) - 1; i >= 1; i-- {
j := intervalPCG(p, uint64(i))
d[i], d[j] = d[j], d[i]
}
return
}
for i := len(d) - 1; i >= 1; i-- {
j := interval(bg, uint64(i))
d[i], d[j] = d[j], d[i]
}
}

// intervalPCG is interval on a *PCG64, which the compiler can inline.
func intervalPCG(p *PCG64, max uint64) uint64 {
mask := genMask(max)
if max <= 0xFFFFFFFF {
for {
if v := uint64(p.Uint32()) & mask; v <= max {
return v
}
}
}
for {
if v := p.Uint64() & mask; v <= max {
return v
}
}
}

// Float64 returns the next double in [0, 1), numpy's random() with
// size=None: next_double, 53 bits of one 64-bit output.
func (g *Generator) Float64() float64 { return g.bg.Float64() }

// FillUniform fills dst with values in [low, high), numpy's
// uniform(low, high, size=len(dst)) in order: low + (high-low)*U. It returns
// an error, and draws nothing, when high-low is NaN, infinite or negative.
func (g *Generator) FillUniform(dst []float64, low, high float64) error {
rng, err := uniformRange(low, high, false)
if err != nil {
return err
}
fillUniform(g.bg, dst, low, rng)
return nil
}

// IntN returns an integer in [0, high), numpy's integers(0, high) with the
// default int64 dtype and size=None: Lemire's bounded method, 32-bit draws
// when high-1 fits 32 bits (half of a 64-bit PCG64 output, the other half
// kept for the next 32-bit draw). IntN panics when high <= 0, as
// math/rand's Intn does; numpy raises ValueError.
func (g *Generator) IntN(high int64) int64 { return intN(g.bg, high, false) }

// FillIntN fills dst with integers in [0, high), numpy's
// integers(0, high, size=len(dst)). It returns an error, and draws nothing,
// when high <= 0 and dst is not empty.
func (g *Generator) FillIntN(dst []int64, high int64) error {
return fillIntN(g.bg, dst, high, false)
}

// ShuffleInt64 shuffles d in place, numpy's shuffle of a one-dimensional
// int64 array: Fisher-Yates from the end, each index from random_interval.
func (g *Generator) ShuffleInt64(d []int64) { shuffleInterval(g.bg, d) }

// Float64 returns the next double in [0, 1), numpy's random_sample() with
// size=None.
func (r *RandomState) Float64() float64 { return r.bg.Float64() }

// FillUniform fills dst with values in [low, high), numpy's legacy
// uniform(low, high, size=len(dst)). Unlike Generator's it accepts
// high < low; it returns an error, and draws nothing, when high-low is NaN
// or infinite.
func (r *RandomState) FillUniform(dst []float64, low, high float64) error {
rng, err := uniformRange(low, high, true)
if err != nil {
return err
}
fillUniform(r.bg, dst, low, rng)
return nil
}

// IntN returns an integer in [0, high), numpy's legacy randint(0, high) with
// size=None, by masked rejection. It panics when high <= 0, as numpy raises
// ValueError.
func (r *RandomState) IntN(high int64) int64 { return intN(r.bg, high, true) }

// FillIntN fills dst with integers in [0, high), numpy's legacy
// randint(0, high, size=len(dst)). It returns an error, and draws nothing,
// when high <= 0 and dst is not empty.
func (r *RandomState) FillIntN(dst []int64, high int64) error {
return fillIntN(r.bg, dst, high, true)
}

// ShuffleInt64 shuffles d in place, numpy's legacy shuffle of a
// one-dimensional int64 array.
func (r *RandomState) ShuffleInt64(d []int64) { shuffleInterval(r.bg, d) }
93 changes: 93 additions & 0 deletions random/scalar_bench_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
package random

import (
"strconv"
"testing"
)

// Benchmarks of the scalar draws. NumPy's reference is the scalar call
// (rng.random(), rng.integers(0, n), rng.uniform(lo, hi, size=n),
// rng.shuffle(arange)), timed in a loop on the same machine; only run these
// when the one-minute load average is low.

var benchSink float64
var benchISink int64

func BenchmarkScalarFloat64(b *testing.B) {
g := DefaultRNG(1)
var s float64
for range b.N {
s += g.Float64()
}
benchSink = s
}

func BenchmarkScalarIntN(b *testing.B) {
for _, tc := range []struct {
name string
high int64
}{{"small", 97}, {"2^33", 1 << 33}} {
b.Run("gen/"+tc.name, func(b *testing.B) {
g := DefaultRNG(1)
var s int64
for range b.N {
s += g.IntN(tc.high)
}
benchISink = s
})
b.Run("legacy/"+tc.name, func(b *testing.B) {
r := NewRandomState(1)
var s int64
for range b.N {
s += r.IntN(tc.high)
}
benchISink = s
})
}
}

func BenchmarkScalarFillUniform(b *testing.B) {
dst := make([]float64, 30)
g := DefaultRNG(1)
r := NewRandomState(1)
b.Run("gen/30", func(b *testing.B) {
for range b.N {
_ = g.FillUniform(dst, -5, 5)
}
})
b.Run("legacy/30", func(b *testing.B) {
for range b.N {
_ = r.FillUniform(dst, -5, 5)
}
})
}

func BenchmarkScalarFillIntN(b *testing.B) {
dst := make([]int64, 30)
g := DefaultRNG(1)
for range b.N {
_ = g.FillIntN(dst, 30)
}
benchISink = dst[0]
}

func BenchmarkScalarShuffleInt64(b *testing.B) {
for _, n := range []int{30, 300} {
d := make([]int64, n)
for i := range d {
d[i] = int64(i)
}
b.Run("gen/"+strconv.Itoa(n), func(b *testing.B) {
g := DefaultRNG(1)
for range b.N {
g.ShuffleInt64(d)
}
})
b.Run("legacy/"+strconv.Itoa(n), func(b *testing.B) {
r := NewRandomState(1)
for range b.N {
r.ShuffleInt64(d)
}
})
}
}
Loading
Loading