Skip to content

feat(random): allocation-free scalar draws (Float64, FillUniform, IntN, FillIntN, ShuffleInt64) - #84

Merged
tannevaled merged 1 commit into
mainfrom
feat/scalar-draws
Nov 1, 2026
Merged

tannevaled merged 1 commit into
mainfrom
feat/scalar-draws

Conversation

@tannevaled

Copy link
Copy Markdown
Contributor

What

Task 1 of docs/design-global.md in go-numerics/optimize (section 2.3): allocation-free scalar draws on random.Generator and random.RandomState:

Float64, FillUniform, IntN, FillIntN, ShuffleInt64.

Each consumes exactly the bit-generator output NumPy 2.5.3 consumes for the same call and allocates nothing on its success path.

Sources opened (NumPy v2.5.3)

_generator.pyx (uniform, shuffle, _shuffle_raw), mtrand.pyx (uniform, randint, shuffle, _shuffle_raw), _bounded_integers.pyx.in (_rand_int64: the scalar and sized paths both call random_bounded_uint64_fill), distributions.c (random_uniform, random_interval, random_bounded_uint64_fill).

Semantics: Generator.FillUniform rejects a negative, NaN or infinite high-low; the legacy one rejects only NaN or infinite (high < low is accepted). Generator.IntN uses Lemire, RandomState.IntN masked rejection. IntN panics on high <= 0 (like math/rand); FillIntN returns an error and draws nothing, except for an empty dst, as NumPy returns the empty array first.

Validation

  • testdata/scalar.py + TestScalarDrawsMatchNumPy: 7296 calls on 192 scripts (48 seeds x Generator/PCG64, Generator/MT19937, RandomState/MT19937, RandomState/PCG64), 760 of them errors on both sides, mixed 32/64-bit draws (PCG64 half-word buffering). Fixture made by an x86-64 NumPy 2.5.3 in an amd64 container (GONDARRAY_REGEN=1 go test ./random -run TestRegenerateScalarFixture; no Rosetta here, and aarch64 NumPy fuses uniform).
  • Planted breaks (skipped call, extra draw, masked instead of Lemire) are detected; the fixture is checked to contain every op and errors.
  • TestScalarAllocations: testing.AllocsPerRun = 0 for every method, 4 generators, all bounded-integer branches.
  • Also checked against this package's array API on Philox, SFC64, PCG64DXSM.
  • FuzzScalarDraws (NaN, +-Inf, negative/zero bounds, MinInt64/MaxInt64, 2^32 boundaries): 8M execs clean.
  • random package coverage 100.0%.
  • Benchmarks added (scalar_bench_test.go); numbers are not published: the host load was above 30 while this was written.

README and docs/random.md updated; landing and docs site follow in their own PRs.

🤖 Generated with Claude Code

Float64, FillUniform, IntN, FillIntN and ShuffleInt64, for solvers that
draw a few values per step (differential evolution, basin hopping). Each
consumes exactly the bit-generator output NumPy 2.5.3 consumes for the
same call (Generator: Lemire bounded integers, non-negative uniform range;
RandomState: masked rejection, uniform accepts high < low) and allocates
nothing.

Tested against NumPy 2.5.3 (x86-64, in an amd64 container): 7296 calls on
192 scripts, errors included, mixed 32/64-bit draws on PCG64; planted
breaks; AllocsPerRun = 0; fuzz on NaN/Inf/negative/zero/MinInt64/MaxInt64.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tannevaled
tannevaled merged commit b83f934 into main Nov 1, 2026
12 checks passed
@tannevaled
tannevaled deleted the feat/scalar-draws branch November 1, 2026 09:37
tannevaled added a commit that referenced this pull request Nov 1, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tannevaled added a commit that referenced this pull request Nov 1, 2026
* perf: float32 Exp and Log on the float64 kernels (2-3.5x faster)

float32 Exp and Log called math.Exp/math.Log per element, 6-14x slower
than NumPy on one Zen 3 core. They now run this package's float64
kernels (the Arm optimized-routines ports) 256 elements at a time
through a stack buffer, rounding each result once: within 0.5 + 2^-29
float32 ULP, no allocation.

abbench, 8 rounds, one Zen 3 core: Exp 297 -> 84 us and Log 198 ->
99 us at 16 Ki; Exp 18.8 -> 5.2 ms and Log 12.4 -> 6.1 ms at 1 Mi.
Still about 3x slower than NumPy's float32 SIMD, recorded as an open
defect in docs/perf.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: the float32 Exp/Log release is v0.31.0 (v0.30.0 was taken by #84)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant