[tannevaled]

Ruby gets scipy's special functions, distributions, quadrature and optimisers with no SciPy and no cgo — four modules of two organisations, under scipy's own names:

Ruby module	from	surface
Special	go-numerics/special	all 67 exported functions, under 66 Ruby names
Stats	go-statistics/stats	all 32 univariate distributions, 19 methods each
Integrate	go-numerics/integrate	10 quadrature routines
Optimize	go-numerics/optimize	11 root finders and minimisers

Special.gamma(5.0)                                      # => 24.0
Special.zeta(2.0)                                       # => 1.6449340668482264   (pi^2/6)
Stats.norm.ppf(0.975)                                   # => 1.9599639845400538
Stats.poisson(3.0).pmf(2)                               # => 0.22404180765538775
Integrate.quad(0.0, 1.0) { |x| x * x }                  # => [0.3333333333333333, 3.7e-15]
Optimize.brentq(0.0, 2.0) { |x| x * x - 2 }             # => 1.4142135623730951

a = NDArray.from([1.0, 2.0, 3.0, 4.0], [2, 2])
Special.gamma(a)                                        # => array([[1., 1.], [2., 6.]])
Stats.t(10.0).cdf(a)                                    # element-wise, same shape
Special.xlogy(2.0, a)                                   # a Float broadcasts against an array

66 Ruby names for 67 Go functions, because scipy spells the Riemann and Hurwitz zeta as one zeta(x, q = nil).

The names are measured, not transliterated

Every module states its own specification: it compares itself against scipy in ULPs, and the pairing is a file in its repository — bench/scipy_server.py and testdata/gen/fam_*.py for special, each distribution's doc comment for stats. Those files are the bibliography, so the Ruby names come from them rather than from the Go name:

Go	Ruby (= scipy)	transliteration would give
Log1pExp	softplus	log1pexp ❌
LogGamma	gammaln	log_gamma ❌
GammaP / GammaQ	gammainc / gammaincc	gamma_p ❌
StudentT	t	student_t ❌
ChiSquared / NoncentralChiSquared	chi2 / ncx2	chi_squared ❌
DiscreteUniform	randint	discrete_uniform ❌
Weibull / Gumbel	weibull_min / gumbel_r	weibull ❌

Two functions have no scipy counterpart and keep the Go name: log_factorial, loggamma_sign.

One Ruby name, two Go paths — which is what a ufunc is

special ships each function twice: a float64 form in go-numerics/special and an element-wise form over *ndarray.Array in go-numerics/special/nd. They cannot share a package, because Go cannot hold two functions of one name — which is why there are two import paths here. rbgo already binds go-ndarray, so the array type is shared rather than introduced (see Dependency versions below for which version, and why it moved).

• every argument a number → the float64 function, answering a Float;
• any argument an NDArray → every argument goes through go-ndarray, a Float becoming a 0-d array, which broadcasts against any shape.

Measured before being written: Scalar(2) × shape{3}, shape{3} × Scalar(2), ternary, 2-D shape preservation. Stats's per-point methods are ufuncs the same way, through the module's own stats.Map.

Nothing is reimplemented. The element-wise path calls the module's own nd package, which already parallelises and broadcasts; argument checking reuses NDArray's helpers (ndArgc, ndFloat, ndInt, mustArray, ndRaise, ndKw); and the seventeen methods Stats::Continuous and Stats::Discrete share are defined once, against a Go interface holding exactly the part of the module's two interfaces that is the same. The two Ruby classes differ only in the density — pdf/logpdf against pmf/logpmf — which is the only place the Go interfaces differ.

#rvs answers a Float with no size and an NDArray with one, as scipy's does; without seed: it draws from one generator per VM that advances across calls (scipy's module-level random state), and seed: asks for a fresh reproducible stream. A parameter outside its domain is refused at construction, as an ArgumentError where SciPy raises ValueError.

Verification: facts, not the code being bound

Comparing a binding against the Go function it calls proves only that the call happened. So every expected value is a mathematical fact:

• 56 closed forms for Special — gamma(5)=24, gamma(0.5)=sqrt(pi), zeta(2)=pi^2/6, digamma(1)=-euler_gamma, polygamma(1,1)=pi^2/6, ellipk(0)=ellipe(0)=pi/2, beta(2,3)=1/12, xlogy(0,0)=0, betainc(1,1,x)=x, inverse pairs round-tripping, j0(0)=1…
• 57 closed forms for Stats, covering all 32 distributions — each constructor is written out separately in scipy's shape-then-loc-then-scale order, so a table of known moments is exactly what catches a swapped or dropped parameter: norm.entropy=(1/2)log(2 pi e), poisson.var=mean, binom(10,.5).pmf(5)=252/1024, zipf(2).pmf(1)=1/zeta(2), randint(0,10).var=8.25, gumbel_r.mean=euler_gamma, rayleigh.mean=sqrt(pi/2), f(5,10).mean=1.25, ncx2(2,3).mean=5, hypergeom(10,5,3).mean=1.5…
• 42 identities across four continuous and two discrete laws — sf=1-cdf, the logs are logs, ppf inverts cdf, isf(q)=ppf(1-q), std^2=var, median=ppf(0.5), interval(0.95) covering 0.95 of the mass. These hold for any distribution, so a method wired to the wrong Go function breaks one without breaking the others.
• the five non-finite answers scipy gives outside a domain (gamma(0)=Infinity, logit(2)=NaN…), which a binding easily turns into a Ruby error or a zero;
• jn_zeros against the tabulated zeros of J0 and against j0 vanishing at the first one — a check on the pair, not on either alone;
• the ufunc property — scalar and element-wise paths answering the same numbers, at every arity and every method, which is the only part of this that is not the modules' own code;
• the method set of each Stats class, as a SET, so a method lost from the shared definition fails;
• #rvs draws from the law asked for — 20000 seeded draws from norm(10, 2) with a sample mean and sd within 6 standard errors, which is a check and not a flake;
• the surface is complete — Special defines exactly 66 names and Stats exactly the 32 the module has univariate constructors for, so a function added upstream and forgotten here fails rather than going unnoticed;
• argument and parameter errors at every arity, with MRI's message.

Ten negative controls on the bindings, each verified to have really changed the file: binding softplus to Logit, pointing gamma's array path at LogGamma, dropping an arity check (which makes the census name the exact 33 methods affected), swapping loc and scale, pointing Stats.t at ChiSquared, wiring #pdf to CDF, dropping a shared method, ignoring seed:, drawing from the wrong law, and skipping parameter validation — all turn the suite red.

A README that cannot drift

The README lists these names one by one, which is the claim that goes stale silently. readme_numeric_surface_test.go reads the names the four bindings register and the names the README lists and requires the sets to be equal in both directions, with each entry's non-method words named beside their reason (scipy's loc/scale, the method: values, the block-pass idiom) rather than one shared list that would also excuse a real omission.

Writing it found two defects in the README text committed minutes earlier: the Special entry claimed all 67 functions while omitting log_factorial and loggamma_sign from its list, and it backticked log1pexp and log_gamma as counter-examples — which reads as a promise. Both fixed; the counter-examples are italic now, because a name that deliberately does not exist is not code. The guard was then broken in all three of its directions (a name dropped from the list, a skellam promised that does not exist, #entropy removed from the binding) and went red for each, and again for the two new modules.

A side finding, filed separately

A census over rbgo itself found 31 methods — all 17 of FFT's and 14 of Image's — that index args[0] with no arity check, so FFT.fft() answers ArgumentError: fft: runtime error: index out of range [0] with length 0: a Go runtime panic converted into a Ruby error, where MRI says wrong number of arguments. NDArray is clean because it uses ndArgc, which is what all four modules here use. Filed as #820 with the full table; TestSpecialArityIsAlwaysChecked, TestStatsArityIsAlwaysChecked and TestNumericsArityIsAlwaysChecked keep these four modules at 0, as a census rather than a list, so a method added later is covered without being named.

---

Second half: Integrate and Optimize

The request names go-numerics, which is three modules. Special above is one; these are the other two, and together they are the four symbols the notebook census ranks highest inside scipy — integrate.quad, optimize.minimize, minimize_scalar, brentq.

Integrate.quad(0.0, 1.0) { |x| x * x }                  # => [0.3333333333333333, 3.7e-15]
Integrate.quad(0.0, Float::INFINITY) { |x| Math.exp(-x) }   # an infinite limit
Optimize.brentq(0.0, 2.0) { |x| x * x - 2 }             # => 1.4142135623730951
Optimize.minimize([-1.2, 1.0]) { |v| 100*(v[1]-v[0]**2)**2 + (1-v[0])**2 }

The function is a block. That is how Ruby passes a callable, and it takes &f for a Proc or lambda with no further surface — so there is no second spelling to document or test. A function of several variables receives one Array; dblquad's inner limits may be numbers or callables, as scipy allows.

Return shapes are scipy's, under one rule: one number → a Float; a tuple → an Array (quad is (value, abserr) and curve_fit is (popt, pcov), both destructuring as scipy's tuples do); an OptimizeResult or RootResults → a Hash with symbol keys, which full_output: true asks a root finder for.

Verified against integrals and roots that are known exactly

• 16 definite integrals: x² over [0,1] = 1/3, sin over [0,π] = 2, 1/x over [1,e] = 1, e^-x over [0,∞) = 1, the Gaussian integral √π over (−∞,∞), 1/√x over [0,1] = 2 — an integrable singularity — the Gauss-Legendre exactness property (an n-point rule is exact to degree 2n−1), the two-point rule's nodes ±1/√3 with weight 1, the sampled rules on data where they are exact, and the unit square and a 1×2 rectangle.
• five root finders × two functions: √2 and the Dottie number 0.7390851332151607, the unique solution of cos x = x. Each root is checked against the known value and by evaluating the function there, so a plausible wrong number fails twice. newton with fprime: answers 1.4142135623730951 exactly.
• Rosenbrock through all five methods (BFGS, CG, Nelder-Mead, Powell, L-BFGS-B): the minimum is exactly (1, 1), so a method that merely descends somewhere fails.
• curve_fit on data lying exactly on its model recovers the model's own parameters; approx_fprime on a linear objective recovers its constant gradient; bracket is checked by the property that its three points bracket a minimum, not against a fixed triple.
• every keyword, in the "given" direction, with an observable effect: points: naming a kink, divmax: 1 producing the one reachable non-convergence (a RuntimeError naming DivMax, where SciPy warns), a callable inner limit distinguishing the triangle's 1/2 from the square's 1, bounds: binding minimize to 1 where the free minimum is 5, fprime2: (Halley) and x1: (the secant's second point), and method: as a Symbol.

What the coverage gate asked for, and what it found

The first push failed CI — not the tests, which were green, but the per-function coverage ratchet: five functions newly below 100%. Recording them in BELOW100 was the wrong fix, and working out why took three different answers:

• untested — Truthy on both distribution classes (only a boolean context calls it) and factorial2 on an array: tests.
• unreachable, and so deleted — an ErrFit arm when no Fit* function is bound; cycle_ier in quad's full record, which is only non-nil for the QAWF weight that is not bound; nd.LogSumExp's error, which reports a complex array when rbgo's NDArray is float64 only. Each was a branch nothing could reach, which BELOW100 would have preserved as a promise. #logsumexp now calls the root function with the slice it already holds — fewer layers and no dead arm.
• looked unreachable and was not — #rvs's error arm. I validate negative sizes myself, so I was about to call it unreachable; measuring instead, Stats.norm.rvs(2 ** 40, 2 ** 40) answers "shape … is too big", refused by go-ndarray at validation without allocating. It has a test.

Separately, twenty-one inline if err != nil { raiseNumerics(err) } arms are now one raiseIf, which the refusals that are reachable cover — twenty-one half-covered functions became one covered branch. The rewrite that did it matched its own helper and briefly made raiseIf call raiseIf: infinite recursion that compiled and that go build accepted without a word. Caught by counting both sides of the replacement, and the helper is now shaped so the pattern cannot match it.

All four files are at 100% of statements with covblocks, which names the blocks go tool cover -func rounds away. That figure is from a plain go test -coverprofile run: the CI-equivalent measurement (-race, -coverpkg ./internal/...) was started and killed — this machine was carrying 30 concurrent agent sessions and a load average of 70, and both the test binary and the ratchet died with signal: terminated. So the -race ratchet here is CI's word, not mine; the lane result on this PR is the measurement.

Dependency versions, and what resolved them

This branch originally pinned go-numerics/{integrate,optimize} at v0.1.0 on purpose: their v0.2.0 required go-ndarray v0.12.0, and Go resolves to the maximum of all requirements, so taking it would have moved go-ndarray under NDArray, FFT, Special and Stats at once. That is a dependency decision with its own witness, not a side effect of a binding, so it was filed as #822 rather than smuggled in — with the evidence that rbgo's NDArray.zeros(0) expectation of array([]) is wrong on either version, since go-ndarray v0.12.0 ports NumPy 2.5.3's arrayprint.py and its expectations are copied verbatim from NumPy's own test suite, where np.zeros(0) is array([], dtype=float64).

#821 then landed exactly that, and #822 is closed. So the reason to hold back is gone, and this branch is rebased onto it:

go-ndarray/ndarray	v0.12.0 (from main)
go-numerics/{integrate,optimize}	v0.2.0
go-numerics/special, go-statistics/stats	v0.1.0 (their latest)

The two v0.2.0 releases claim results unchanged to the last bit. That claim is checked here, not taken: the 113 closed forms, the 42 identities and every keyword test pass unchanged on the new pair, and nothing in the four bindings' tests depends on an array repr, so v0.12.0's printing rework touches none of them.

credscan 0 over 37 directories walked; govulncheck 0 reachable across ./.... The gitsafe and agentsync binaries and both global hooks were checked at v0.10.0/v0.5.0, matching their repositories.

---

What the rbgo_core lane said, and the measurement it forced

The core wasm build grew past its bound — 27,479,576 bytes against 27,000,000. The gate was right to stop it, and raising the number without saying what bought the growth would have turned a budget into a formality. So the cost is attributed, and the two obvious ways to attribute it disagree, which turned out to be the useful part:

	one module alone	added in turn down the branch
Special	+591,000	+591,000
Stats	+2,685,365	+2,438,092
Integrate	+267,470	+266,797
Optimize	+1,020,511	+987,989
	+4,564,346	+4,283,878

Two rows of that table are the model confirming itself:

• Special is identical in both columns — which is what "whoever goes first pays for the shared code" predicts for whoever goes first.
• isolated overcounts the real +4,284,384 by 279,962, and that residual is the code the four share (go-ndarray, the special/nd layer, the argument helpers) — a figure neither method reports on its own. The same pair of measurements on go-ndarray v0.11.0 gave 279,063: 899 bytes apart across a dependency upgrade, so the residual is a property of the code and not of one run.
• cumulative undercounts all but the first, and its sum lands 506 bytes from the real total.

Neither is "the" per-module cost. What both agree on is the ranking and the total, which is what the comment in ci.yml now says to read: Stats ~59% (36 distributions, 27,599 lines of Go), Optimize ~22%, Special ~13%, Integrate ~6% — against ~1,500 lines of binding.

An earlier revision of that comment, which I wrote, presented the cumulative column as "each module added to origin/main alone". It was not, and a reviewing session that measured Special in isolation could only report the two as 7% apart on an unstable baseline. They were not noisy — they were two different quantities.

One more thing that comparison turned up: the build is not byte-reproducible across worktrees. The same commit gave 23,173,500 in one and 23,172,890 in another, 610 bytes apart. Only same-worktree comparisons mean anything, so every figure above comes from one.

The bound is 29,000,000, ~1.5 MB above the measurement. It deliberately does not restore the original proportional headroom (3.8 MB on 23.1 MB): this number only has to notice growth nobody intended, and a gem coming back is caught by the module-path check in the same step, by name and exactly. That check was run against this branch and passes — 47 modules linked, none on the list, with the six numeric ones present as intended. CI's rbgo_core lane is green on the rebased head.

A concurrent session had implemented the other answer — Stats behind !rbgo_core, joining Image outside the core build, landing at 24,987,852 with no new bound — and dropped it, because it would cost the browser build the single most-used part of scipy (stats.norm leads the notebook census). That trade is recorded in the branch history rather than left implicit.

README's wasm table was re-measured in full rather than patched in one cell, because both columns moved, and it is dated:

cmd/wasm (js/wasm)	default	rbgo_core
unstripped	102.6 → 107.4 MB	23.7 → 28.2 MB
stripped	99.9 → 104.5 MB	23.1 → 27.5 MB
stripped, gzip -9	22.3 → 22.2 MB	5.7 → 6.4 MB
Go modules	253 → 256	44 → 47, no gem

core.go's statement of what core is names the four modules too; it listed the numeric stack as "NDArray and FFT", which was the whole of it when written.

Documentation

docs#27 adds a section per module to the site's scientific-stack page — and a tools/docexample guard that runs every Ruby example on the site and checks it against the answer written beside it, which nothing did before. It reports 11 examples / 25 claimed answers / 0 disagreements against an rbgo built from this branch, and correctly refuses the four new sections against today's main, naming each missing module. It merges after this PR, which is why.