feat: initial release

Assisted-by: GLM 5.3 Flash
2026-09-03 10:00:00 +02:00
commit af4ee19703
617 changed files with 191195 additions and 0 deletions
@@ -0,0 +1,424 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: MIT
+
+package stats
+
+import (
+	"math"
+	"strings"
+	"testing"
+
+	"sourcedock.dev/petrbalvin/tensor/internal/core"
+)
+
+// TestGPInterpolatesNoiselessTrainingPoints fits a noiseless GP on its
+// own training points: the posterior must reproduce every observation
+// to rounding and carry no variance there.
+func TestGPInterpolatesNoiselessTrainingPoints(t *testing.T) {
+	g := core.NewGenerator(41)
+	const n = 9
+	train := core.New(core.Float, n, 1)
+	y := core.New(core.Float, n)
+	for i := range n {
+		x := -2 + 0.5*float64(i)
+		train.RawFloats()[i] = x
+		y.RawFloats()[i] = math.Sin(x) + 0.1*x*g.Unit()
+	}
+	kernel, err := SquaredExponentialKernel(0.7)
+	if err != nil {
+		t.Fatalf("SquaredExponentialKernel: %v", err)
+	}
+	res, err := GaussianProcessRegression(kernel, train, y, 0, train)
+	if err != nil {
+		t.Fatalf("GaussianProcessRegression: %v", err)
+	}
+	for i := range n {
+		if math.Abs(res.Mean[i]-y.FloatAt(i)) > 1e-9 {
+			t.Fatalf("point %d: posterior mean %.12g against the observation %.12g",
+				i, res.Mean[i], y.FloatAt(i))
+		}
+		if res.Variance[i] > 1e-12 {
+			t.Fatalf("point %d: posterior variance %.3g at a noiseless training point", i, res.Variance[i])
+		}
+	}
+	// The full posterior covariance vanishes on the training set too:
+	// the conditioning has removed everything the prior had there.
+	for i := range n {
+		for j := range n {
+			if math.Abs(res.Covariance[i*n+j]) > 1e-10 {
+				t.Fatalf("posterior covariance (%d, %d) = %.3g at the training points, want zero",
+					i, j, res.Covariance[i*n+j])
+			}
+		}
+	}
+	// The reported marginal likelihood must match the standalone
+	// function bit for bit on the same inputs.
+	mll, err := MarginalLogLikelihood(kernel, train, y, 0)
+	if err != nil {
+		t.Fatalf("MarginalLogLikelihood: %v", err)
+	}
+	if mll != res.LogLikelihood {
+		t.Fatalf("the fit reported %.17g but the standalone %.17g", res.LogLikelihood, mll)
+	}
+}
+
+// TestGPHugeLengthScaleFollowsGlobalMean pins the limiting behaviour
+// of a giant length scale: when the prior cannot tell neighbouring
+// inputs apart, the posterior mean collapses onto the constant that
+// the likelihood alone supports, the sample mean of the training
+// responses. A small noise keeps the Gram matrix well conditioned;
+// with n = 30 and noise 1e-6 the constant fit sits within 1e-7 of the
+// mean, far inside the 1e-4 tolerance.
+func TestGPHugeLengthScaleFollowsGlobalMean(t *testing.T) {
+	g := core.NewGenerator(43)
+	const n = 30
+	train := core.New(core.Float, n, 1)
+	y := core.New(core.Float, n)
+	total := 0.0
+	for i := range n {
+		train.RawFloats()[i] = float64(i) / float64(n-1)
+		y.RawFloats()[i] = 3 + 0.4*g.NormalUnit()
+		total += y.FloatAt(i)
+	}
+	meanY := total / n
+	kernel, err := SquaredExponentialKernel(1e6)
+	if err != nil {
+		t.Fatalf("SquaredExponentialKernel: %v", err)
+	}
+	test := mustFloats(t, []float64{-5, 0.37, 12}, 3, 1)
+	res, err := GaussianProcessRegression(kernel, train, y, 1e-6, test)
+	if err != nil {
+		t.Fatalf("GaussianProcessRegression: %v", err)
+	}
+	for i, m := range res.Mean {
+		if math.Abs(m-meanY) > 1e-4 {
+			t.Fatalf("test point %d: posterior mean %.8g against the global mean %.8g", i, m, meanY)
+		}
+	}
+}
+
+// TestGPVarianceFarFromDataEqualsPrior pins the uncertainty
+// behaviour: a test point many length scales from every observation
+// has learned nothing, so its posterior variance returns to the prior
+// variance of 1 and its posterior covariance with the data region
+// vanishes.
+func TestGPVarianceFarFromDataEqualsPrior(t *testing.T) {
+	const n = 6
+	train := mustFloats(t, []float64{0, 0.2, 0.4, 0.6, 0.8, 1.0}, n, 1)
+	y := mustFloats(t, []float64{1, -1, 0.5, -0.5, 2, -2}, n)
+	kernel, err := SquaredExponentialKernel(0.3)
+	if err != nil {
+		t.Fatalf("SquaredExponentialKernel: %v", err)
+	}
+	// 30 is one hundred length scales from the nearest observation.
+	test := mustFloats(t, []float64{0.5, 30}, 2, 1)
+	res, err := GaussianProcessRegression(kernel, train, y, 0, test)
+	if err != nil {
+		t.Fatalf("GaussianProcessRegression: %v", err)
+	}
+	if v := res.Variance[1]; math.Abs(v-1) > 1e-10 {
+		t.Fatalf("far posterior variance %.15g, want the prior 1", v)
+	}
+	// The far point's covariance with the data region: the cross
+	// covariances are underflows, so the off-diagonal entry must be a
+	// rounding dust.
+	if c := res.Covariance[0*2+1]; math.Abs(c) > 1e-10 {
+		t.Fatalf("far covariance with the data region %.3g, want a rounding dust", c)
+	}
+}
+
+// TestMatern32MatchesSpectralForm holds the Matérn 3/2 closed form
+// against its defining spectral equation: the density
+// S(ω) = 4a³/(a² + ω²)², a = √3/L, inverts to the kernel through
+// k(r) = (1/π)∫₀^∞ S(ω)·cos(ω·r) dω. The integral is evaluated by
+// trapezoid out to five hundred decay widths, where the integrand's
+// ω⁻⁴ tail has less than 1e-7 left to give.
+func TestMatern32MatchesSpectralForm(t *testing.T) {
+	const lengthScale = 1.3
+	kernel, err := Matern32Kernel(lengthScale)
+	if err != nil {
+		t.Fatalf("Matern32Kernel: %v", err)
+	}
+	a := math.Sqrt(3) / lengthScale
+	const omegaMax = 500
+	const steps = 400000
+	h := omegaMax / float64(steps)
+	spectral := func(r float64) float64 {
+		total := 0.0
+		for s := range steps + 1 {
+			omega := float64(s) * h
+			w := 1.0
+			if s == 0 || s == steps {
+				w = 0.5
+			}
+			den := a*a + omega*omega
+			total += w * 4 * a * a * a / (den * den) * math.Cos(omega*r)
+		}
+		return total * h / math.Pi
+	}
+	for _, r := range []float64{0, 0.7, lengthScale, 2.9} {
+		want := kernel.Covariance([]float64{r}, []float64{0})
+		got := spectral(r)
+		if math.Abs(got-want) > 1e-6 {
+			t.Fatalf("r = %g: closed form %.9g against the spectral inversion %.9g", r, want, got)
+		}
+	}
+	// And the spot values of both Matérns: k(0) = 1 and the documented
+	// closed forms at one length scale, r = L, where the shape
+	// parameter a = √3 (respectively √5) exactly.
+	m52, err := Matern52Kernel(lengthScale)
+	if err != nil {
+		t.Fatalf("Matern52Kernel: %v", err)
+	}
+	if kernel.Covariance([]float64{0}, []float64{0}) != 1 {
+		t.Fatal("the Matern 3/2 kernel is not of unit amplitude")
+	}
+	if m52.Covariance([]float64{0}, []float64{0}) != 1 {
+		t.Fatal("the Matern 5/2 kernel is not of unit amplitude")
+	}
+	a32 := math.Sqrt(3)
+	want32 := (1 + a32) * math.Exp(-a32)
+	if math.Abs(kernel.Covariance([]float64{lengthScale}, []float64{0})-want32) > 1e-12 {
+		t.Fatalf("Matern 3/2 at r = L: %.15g, want %.15g",
+			kernel.Covariance([]float64{lengthScale}, []float64{0}), want32)
+	}
+	a52 := math.Sqrt(5)
+	want52 := (1 + a52 + a52*a52/3) * math.Exp(-a52)
+	if math.Abs(m52.Covariance([]float64{lengthScale}, []float64{0})-want52) > 1e-12 {
+		t.Fatalf("Matern 5/2 at r = L: %.15g, want %.15g",
+			m52.Covariance([]float64{lengthScale}, []float64{0}), want52)
+	}
+}
+
+// TestPeriodicKernelRepeats pins the period: a full period apart the
+// kernel returns to 1, half a period apart with a short length scale
+// it has decorrelated to rounding dust.
+func TestPeriodicKernelRepeats(t *testing.T) {
+	kernel, err := PeriodicKernel(0.2, 3)
+	if err != nil {
+		t.Fatalf("PeriodicKernel: %v", err)
+	}
+	if got := kernel.Covariance([]float64{7}, []float64{7 + 3}); math.Abs(got-1) > 1e-12 {
+		t.Fatalf("one period apart the covariance is %.15g, want 1", got)
+	}
+	if got := kernel.Covariance([]float64{0}, []float64{1.5}); got > 1e-6 {
+		t.Fatalf("half a period apart with a short scale the covariance is %.3g", got)
+	}
+}
+
+// TestMarginalLogLikelihoodPrefersTrueHyperparameters draws one path
+// of a Gaussian process with known hyperparameters over the house
+// generator and requires the marginal likelihood to rank the true pair
+// above badly mismatched ones, with a margin far beyond the rounding.
+func TestMarginalLogLikelihoodPrefersTrueHyperparameters(t *testing.T) {
+	g := core.NewGenerator(53)
+	const n = 30
+	const trueScale = 1.0
+	const trueNoise = 0.05
+	train := core.New(core.Float, n, 1)
+	for i := range n {
+		train.RawFloats()[i] = 5 * float64(i) / float64(n-1)
+	}
+	// The path: one multivariate normal draw over the grid under the
+	// true kernel, plus the observation noise.
+	trueKernel, err := SquaredExponentialKernel(trueScale)
+	if err != nil {
+		t.Fatalf("SquaredExponentialKernel: %v", err)
+	}
+	cov := core.New(core.Float, n, n)
+	for i := range n {
+		for j := range n {
+			cov.RawFloats()[i*n+j] = trueKernel.Covariance(train.RawFloats()[i:i+1], train.RawFloats()[j:j+1])
+		}
+		// A hair of jitter on the diagonal: the Gram matrix of a long
+		// length scale is positive definite by a margin that float64
+		// rounding can eat on the way down, and the draw is fixture
+		// construction, not the model, whose noise variance is fitted
+		// separately below.
+		cov.RawFloats()[i*n+i] += 1e-9
+	}
+	paths, err := MultivariateNormalDraws(g, 1, core.New(core.Float, n), cov)
+	if err != nil {
+		t.Fatalf("MultivariateNormalDraws: %v", err)
+	}
+	y := core.New(core.Float, n)
+	for i := range n {
+		y.RawFloats()[i] = paths.FloatAt(i) + trueNoise*g.NormalUnit()
+	}
+	truth, err := MarginalLogLikelihood(trueKernel, train, y, trueNoise)
+	if err != nil {
+		t.Fatalf("MarginalLogLikelihood: %v", err)
+	}
+	mismatched := []struct {
+		scale float64
+		noise float64
+	}{
+		{0.05, 5},
+		{10, 1e-4},
+	}
+	for _, pair := range mismatched {
+		wrongKernel, kerr := SquaredExponentialKernel(pair.scale)
+		if kerr != nil {
+			t.Fatalf("SquaredExponentialKernel(%g): %v", pair.scale, kerr)
+		}
+		wrong, err := MarginalLogLikelihood(wrongKernel, train, y, pair.noise)
+		if err != nil {
+			t.Fatalf("MarginalLogLikelihood at scale %g: %v", pair.scale, err)
+		}
+		if truth < wrong+5 {
+			t.Fatalf("the true pair scored %.4g against (%g, %g) at %.4g, the margin is under 5",
+				truth, pair.scale, pair.noise, wrong)
+		}
+	}
+}
+
+// TestGPRegressionMultiDimensional fits a three-dimensional input and
+// requires the same exact interpolation, the path the Euclidean
+// distance of every kernel takes over columns.
+func TestGPRegressionMultiDimensional(t *testing.T) {
+	g := core.NewGenerator(59)
+	const n = 8
+	train := core.New(core.Float, n, 3)
+	y := core.New(core.Float, n)
+	for i := range n {
+		for j := range 3 {
+			train.RawFloats()[i*3+j] = g.Unit()
+		}
+		y.RawFloats()[i] = g.NormalUnit()
+	}
+	kernel, err := Matern52Kernel(1.5)
+	if err != nil {
+		t.Fatalf("Matern52Kernel: %v", err)
+	}
+	res, err := GaussianProcessRegression(kernel, train, y, 0, train)
+	if err != nil {
+		t.Fatalf("GaussianProcessRegression: %v", err)
+	}
+	for i := range n {
+		if math.Abs(res.Mean[i]-y.FloatAt(i)) > 1e-8 {
+			t.Fatalf("point %d: mean %.10g against the observation %.10g", i, res.Mean[i], y.FloatAt(i))
+		}
+		if res.Variance[i] > 1e-10 {
+			t.Fatalf("point %d: variance %.3g at a training point", i, res.Variance[i])
+		}
+	}
+	// The posterior covariance is symmetric by construction; the
+	// mirror must hold.
+	for i := range n {
+		for j := range n {
+			if res.Covariance[i*n+j] != res.Covariance[j*n+i] {
+				t.Fatalf("the posterior covariance is not symmetric at (%d, %d)", i, j)
+			}
+		}
+	}
+}
+
+// TestGPValidationAndKernelRefusals checks the constructors and the
+// entry points refuse what they must, including the singular Gram
+// matrix that duplicated noiseless rows name.
+func TestGPValidationAndKernelRefusals(t *testing.T) {
+	kernel, kerr := SquaredExponentialKernel(1)
+	if kerr != nil {
+		t.Fatalf("SquaredExponentialKernel: %v", kerr)
+	}
+	train := mustFloats(t, []float64{0, 1, 2}, 3, 1)
+	y := mustFloats(t, []float64{1, -1, 0.5}, 3)
+	test := mustFloats(t, []float64{0.5}, 1, 1)
+
+	for _, scale := range []float64{0, -1, math.Inf(1), math.NaN()} {
+		if _, err := SquaredExponentialKernel(scale); err == nil {
+			t.Fatalf("squared exponential accepted the scale %v", scale)
+		}
+		if _, err := Matern32Kernel(scale); err == nil {
+			t.Fatalf("Matern 3/2 accepted the scale %v", scale)
+		}
+		if _, err := Matern52Kernel(scale); err == nil {
+			t.Fatalf("Matern 5/2 accepted the scale %v", scale)
+		}
+		if _, err := PeriodicKernel(scale, 1); err == nil {
+			t.Fatalf("periodic kernel accepted the length scale %v", scale)
+		}
+		if _, err := PeriodicKernel(1, scale); err == nil {
+			t.Fatalf("periodic kernel accepted the period %v", scale)
+		}
+	}
+	if _, err := GaussianProcessRegression(nil, train, y, 0, test); err == nil || !strings.Contains(err.Error(), "kernel is nil") {
+		t.Fatalf("nil kernel: got %v, want the nil-kernel refusal", err)
+	}
+	for _, noise := range []float64{-0.1, math.Inf(-1), math.NaN()} {
+		if _, err := GaussianProcessRegression(kernel, train, y, noise, test); err == nil || !strings.Contains(err.Error(), "noise variance") {
+			t.Fatalf("noise variance %v: got %v, want the noise-variance refusal", noise, err)
+		}
+		if _, err := MarginalLogLikelihood(kernel, train, y, noise); err == nil || !strings.Contains(err.Error(), "noise variance") {
+			t.Fatalf("marginal likelihood, noise variance %v: got %v, want the noise-variance refusal", noise, err)
+		}
+	}
+	if _, err := GaussianProcessRegression(kernel, core.New(core.Float, 3), y, 0, test); err == nil || !strings.Contains(err.Error(), "must be rank 2") {
+		t.Fatalf("rank-1 training design: got %v, want the rank refusal", err)
+	}
+	if _, err := GaussianProcessRegression(kernel, train, core.New(core.Float, 3, 1), 0, test); err == nil || !strings.Contains(err.Error(), "must be rank 1") {
+		t.Fatalf("rank-2 response: got %v, want the rank refusal", err)
+	}
+	if _, err := GaussianProcessRegression(kernel, train, mustFloats(t, []float64{1, -1}, 2), 0, test); err == nil || !strings.Contains(err.Error(), "rows but the response") {
+		t.Fatalf("short response: got %v, want the length refusal", err)
+	}
+	if _, err := GaussianProcessRegression(kernel, train, y, 0, core.New(core.Float, 2)); err == nil || !strings.Contains(err.Error(), "must be rank 2") {
+		t.Fatalf("rank-1 test design: got %v, want the rank refusal", err)
+	}
+	wide := mustFloats(t, []float64{0.1, 0.2, 0.3, 0.4}, 2, 2)
+	if _, err := GaussianProcessRegression(kernel, train, y, 0, wide); err == nil || !strings.Contains(err.Error(), "wide but the test design") {
+		t.Fatalf("test design of the wrong width: got %v, want the width refusal", err)
+	}
+	sick := core.New(core.Float, 3, 1)
+	sick.RawFloats()[2] = math.NaN()
+	if _, err := GaussianProcessRegression(kernel, sick, y, 0, test); err == nil || !strings.Contains(err.Error(), "non-finite") {
+		t.Fatalf("non-finite training design: got %v, want the non-finite refusal", err)
+	}
+	if _, err := GaussianProcessRegression(kernel, train, mustFloats(t, []float64{1, -1, math.Inf(1)}, 3), 0, test); err == nil || !strings.Contains(err.Error(), "non-finite") {
+		t.Fatalf("non-finite response: got %v, want the non-finite refusal", err)
+	}
+	// Duplicated rows with no noise: the Gram matrix is singular and
+	// the refusal names the row.
+	dup := mustFloats(t, []float64{1, 1, 2}, 3, 1)
+	_, err := GaussianProcessRegression(kernel, dup, y, 0, test)
+	if err == nil || !strings.Contains(err.Error(), "positive definite") {
+		t.Fatalf("duplicated noiseless rows: got %v, want a positive-definiteness refusal", err)
+	}
+	// A zero-column design has nothing to evaluate.
+	if _, err := GaussianProcessRegression(kernel, core.New(core.Float, 3, 0), y, 0, test); err == nil || !strings.Contains(err.Error(), "at least one column") {
+		t.Fatalf("zero-column design: got %v, want the column refusal", err)
+	}
+	if _, err := GaussianProcessRegression(kernel, core.New(core.Complex, 3, 1), y, 0, test); err == nil || !strings.Contains(err.Error(), "complex") {
+		t.Fatalf("complex training design: got %v, want the complex refusal", err)
+	}
+	if _, err := GaussianProcessRegression(kernel, train, core.New(core.Complex, 3), 0, test); err == nil || !strings.Contains(err.Error(), "complex") {
+		t.Fatalf("complex response: got %v, want the complex refusal", err)
+	}
+	// Integer inputs take the widening accessor path end to end:
+	// design, response and the likelihood assembly.
+	intTrain, ierr := core.FromInts([]int64{0, 10, 20}, 3, 1)
+	if ierr != nil {
+		t.Fatalf("FromInts: %v", ierr)
+	}
+	intY, ierr := core.FromInts([]int64{1, -2, 4}, 3)
+	if ierr != nil {
+		t.Fatalf("FromInts: %v", ierr)
+	}
+	intRes, err := GaussianProcessRegression(kernel, intTrain, intY, 0, intTrain)
+	if err != nil {
+		t.Fatalf("GaussianProcessRegression over int inputs: %v", err)
+	}
+	for i := range 3 {
+		if math.Abs(intRes.Mean[i]-intY.FloatAt(i)) > 1e-8 {
+			t.Fatalf("int input point %d: mean %.10g against the observation %.10g",
+				i, intRes.Mean[i], intY.FloatAt(i))
+		}
+	}
+	intMLL, err := MarginalLogLikelihood(kernel, intTrain, intY, 0)
+	if err != nil {
+		t.Fatalf("MarginalLogLikelihood over int inputs: %v", err)
+	}
+	if intMLL != intRes.LogLikelihood {
+		t.Fatalf("the int-input likelihoods disagree: %.17g against %.17g", intRes.LogLikelihood, intMLL)
+	}
+}