diff --git a/packages/cultmath/src/CultMath/BoundedLeastSquares.cs b/packages/cultmath/src/CultMath/BoundedLeastSquares.cs index 2d31620e..c005c215 100644 --- a/packages/cultmath/src/CultMath/BoundedLeastSquares.cs +++ b/packages/cultmath/src/CultMath/BoundedLeastSquares.cs @@ -11,10 +11,29 @@ public enum BoundedLeastSquaresStatus /// The iteration cap was reached. x holds the last feasible iterate, which is never worse than the clamped start. IterationLimit, - /// The input broke the contract; nothing was solved and x is exactly as passed. + /// The input broke the contract; nothing was solved and x is exactly as passed. names which input. InvalidInput, } +/// Which input of breaks its contract; the first failure in the order of the members. +public enum BoundedLeastSquaresInput +{ + /// Every input meets the contract; Solve will not return . + Valid, + + /// The KKT tolerance is not finite and greater than zero. + InvalidTolerance, + + /// Some lo or hi is NaN, lo[j] > hi[j], lo[j] is +Inf or hi[j] is -Inf. + InvalidBounds, + + /// Some entry of a is NaN or infinite. + NonFiniteMatrix, + + /// Some entry of b is NaN or infinite. + NonFiniteTarget, +} + /// /// Dense bounded least squares: min ||A x - b||^2 subject to lo <= x <= hi, for small problems /// (tens of rows and columns). C#-only, like the intercept helpers in ; there is no HLSL mirror. @@ -58,7 +77,9 @@ public enum BoundedLeastSquaresStatus /// without throwing, with iterations 0 and /// x exactly as passed. A NaN or infinite warm start is legal: it is clamped into the box (an infinite /// result on an unbounded side becomes 0 clamped to the box). Spans shorter than the stated dimensions are a -/// caller bug and throw . +/// caller bug and throw . reports which input broke the +/// contract, and Solve returns InvalidInput exactly when it does not return +/// . /// /// public static class BoundedLeastSquares @@ -75,6 +96,44 @@ public static class BoundedLeastSquares /// Floats of caller-supplied workspace needed for columns. public static int WorkspaceLength(int n) => 2 * (2 * n * n + 6 * n) + 3 * n; + /// + /// Checks the inputs of Solve against its contract and names the first one that breaks it, in the order + /// tolerance, bounds, matrix, target. Solve calls this and returns + /// for any result but . + /// It reads its arguments only, allocates nothing and does not throw for a bad value. + /// + /// Rows of . + /// Columns of , and length of and . + /// Row-major m * n matrix. + /// Length m target. With n = 0 there is no unknown and is not read. + /// Lower bounds. + /// Upper bounds. + /// The tolerance Solve will be given. + /// A span is shorter than the stated dimensions, or or is negative: a caller bug, not an invalid input. + public static BoundedLeastSquaresInput Validate( + int m, int n, + ReadOnlySpan a, ReadOnlySpan b, + ReadOnlySpan lo, ReadOnlySpan hi, + double kktRelativeTolerance = DefaultKktRelativeTolerance) + { + if (m < 0 || n < 0 || a.Length < m * n || b.Length < m || lo.Length < n || hi.Length < n) + throw new ArgumentException("BoundedLeastSquares: span shorter than the stated dimensions."); + + if (!(kktRelativeTolerance > 0.0) || double.IsPositiveInfinity(kktRelativeTolerance)) + return BoundedLeastSquaresInput.InvalidTolerance; + for (var j = 0; j < n; j++) + if (!(lo[j] <= hi[j]) || float.IsPositiveInfinity(lo[j]) || float.IsNegativeInfinity(hi[j])) + return BoundedLeastSquaresInput.InvalidBounds; + for (var i = 0; i < m * n; i++) + if (!float.IsFinite(a[i])) + return BoundedLeastSquaresInput.NonFiniteMatrix; + if (n > 0) + for (var r = 0; r < m; r++) + if (!float.IsFinite(b[r])) + return BoundedLeastSquaresInput.NonFiniteTarget; + return BoundedLeastSquaresInput.Valid; + } + /// /// Minimises ||A x - b||^2 subject to lo <= x <= hi. is the warm start /// on entry (clamped to the box first) and the result on exit. @@ -124,9 +183,11 @@ public static class BoundedLeastSquares double kktRelativeTolerance, int maxIterations = DefaultMaxIterations) { - if (m < 0 || n < 0 || a.Length < m * n || b.Length < m || lo.Length < n || hi.Length < n - || x.Length < n || workspace.Length < WorkspaceLength(n)) + if (n < 0 || x.Length < n || workspace.Length < WorkspaceLength(n)) throw new ArgumentException("BoundedLeastSquares: span shorter than the stated dimensions."); + iterations = 0; + if (Validate(m, n, a, b, lo, hi, kktRelativeTolerance) != BoundedLeastSquaresInput.Valid) + return BoundedLeastSquaresStatus.InvalidInput; // Double-precision vectors and matrices first, then the integer flags, all carved from the caller's floats. var doubleCount = 2 * n * n + 6 * n; @@ -145,22 +206,11 @@ public static class BoundedLeastSquares var freeIndex = Take(ref ints, n); var dependent = Take(ref ints, n); - iterations = 0; - if (!(kktRelativeTolerance > 0.0) || double.IsPositiveInfinity(kktRelativeTolerance)) - return BoundedLeastSquaresStatus.InvalidInput; - for (var j = 0; j < n; j++) - if (!(lo[j] <= hi[j]) || float.IsPositiveInfinity(lo[j]) || float.IsNegativeInfinity(hi[j])) - return BoundedLeastSquaresStatus.InvalidInput; - - // A float is never large enough to overflow a double product or a sum of tens of them, so a non-finite - // A^T b entry is exactly a non-finite entry of A or b (NaN and infinity never cancel to a finite value). for (var j = 0; j < n; j++) { var sb = 0.0; for (var r = 0; r < m; r++) sb += (double)a[r * n + j] * b[r]; - if (!double.IsFinite(sb)) - return BoundedLeastSquaresStatus.InvalidInput; atb[j] = sb; for (var k = 0; k <= j; k++) { diff --git a/packages/cultmath/tests/CultMath.Tests/BoundedLeastSquaresTests.cs b/packages/cultmath/tests/CultMath.Tests/BoundedLeastSquaresTests.cs index 63bc913e..b9547ce6 100644 --- a/packages/cultmath/tests/CultMath.Tests/BoundedLeastSquaresTests.cs +++ b/packages/cultmath/tests/CultMath.Tests/BoundedLeastSquaresTests.cs @@ -597,6 +597,152 @@ public sealed class BoundedLeastSquaresTests } } + [Fact] + public void ValidateNamesTheFirstInvalidInput() + { + const int m = 5, n = 3; + var nan = float.NaN; + var inf = float.PositiveInfinity; + const double goodTol = 1e-6; + var cases = new (string name, BoundedLeastSquaresInput expected, double tol, Action corrupt)[] + { + ("valid", BoundedLeastSquaresInput.Valid, goodTol, (a, b, lo, hi) => { }), + ("infinite bounds are unbounded", BoundedLeastSquaresInput.Valid, goodTol, (a, b, lo, hi) => { lo[0] = -inf; hi[1] = inf; }), + ("lo = hi", BoundedLeastSquaresInput.Valid, goodTol, (a, b, lo, hi) => { lo[2] = 0.5f; hi[2] = 0.5f; }), + ("tolerance 0", BoundedLeastSquaresInput.InvalidTolerance, 0.0, (a, b, lo, hi) => { }), + ("tolerance negative", BoundedLeastSquaresInput.InvalidTolerance, -1e-6, (a, b, lo, hi) => { }), + ("tolerance NaN", BoundedLeastSquaresInput.InvalidTolerance, double.NaN, (a, b, lo, hi) => { }), + ("tolerance +Inf", BoundedLeastSquaresInput.InvalidTolerance, double.PositiveInfinity, (a, b, lo, hi) => { }), + ("tolerance tiny but positive", BoundedLeastSquaresInput.Valid, double.Epsilon, (a, b, lo, hi) => { }), + ("lo NaN", BoundedLeastSquaresInput.InvalidBounds, goodTol, (a, b, lo, hi) => lo[1] = nan), + ("hi NaN", BoundedLeastSquaresInput.InvalidBounds, goodTol, (a, b, lo, hi) => hi[2] = nan), + ("lo > hi", BoundedLeastSquaresInput.InvalidBounds, goodTol, (a, b, lo, hi) => { lo[1] = 0.5f; hi[1] = 0.25f; }), + ("lo = +Inf", BoundedLeastSquaresInput.InvalidBounds, goodTol, (a, b, lo, hi) => { lo[0] = inf; hi[0] = inf; }), + ("hi = -Inf", BoundedLeastSquaresInput.InvalidBounds, goodTol, (a, b, lo, hi) => { lo[0] = -inf; hi[0] = -inf; }), + ("A NaN", BoundedLeastSquaresInput.NonFiniteMatrix, goodTol, (a, b, lo, hi) => a[4] = nan), + ("A +Inf", BoundedLeastSquaresInput.NonFiniteMatrix, goodTol, (a, b, lo, hi) => a[7] = inf), + ("A -Inf in the last entry", BoundedLeastSquaresInput.NonFiniteMatrix, goodTol, (a, b, lo, hi) => a[m * n - 1] = -inf), + ("b NaN", BoundedLeastSquaresInput.NonFiniteTarget, goodTol, (a, b, lo, hi) => b[2] = nan), + ("b +Inf in the first entry", BoundedLeastSquaresInput.NonFiniteTarget, goodTol, (a, b, lo, hi) => b[0] = inf), + ("b -Inf in the last entry", BoundedLeastSquaresInput.NonFiniteTarget, goodTol, (a, b, lo, hi) => b[m - 1] = -inf), + // Two faults at once: the earlier member in the order wins, whichever input comes first in the argument list. + ("tolerance and bounds", BoundedLeastSquaresInput.InvalidTolerance, 0.0, (a, b, lo, hi) => lo[0] = nan), + ("tolerance and A", BoundedLeastSquaresInput.InvalidTolerance, double.NaN, (a, b, lo, hi) => a[0] = nan), + ("tolerance and b", BoundedLeastSquaresInput.InvalidTolerance, -1.0, (a, b, lo, hi) => b[0] = nan), + ("bounds and A", BoundedLeastSquaresInput.InvalidBounds, goodTol, (a, b, lo, hi) => { hi[0] = nan; a[0] = nan; }), + ("bounds and b", BoundedLeastSquaresInput.InvalidBounds, goodTol, (a, b, lo, hi) => { lo[2] = 1f; hi[2] = -1f; b[4] = inf; }), + ("A and b", BoundedLeastSquaresInput.NonFiniteMatrix, goodTol, (a, b, lo, hi) => { a[14] = inf; b[0] = nan; }), + }; + foreach (var (name, expected, tol, corrupt) in cases) + { + var a = (float[])A54.Clone(); + var b = (float[])B5.Clone(); + var lo = Fill(-1f, n); + var hi = Fill(1f, n); + corrupt(a, b, lo, hi); + var verdict = BoundedLeastSquares.Validate(m, n, a, b, lo, hi, tol); + Assert.True(expected == verdict, $"{name}: {verdict}"); + + var x = new float[n]; + var status = BoundedLeastSquares.Solve(m, n, a, b, lo, hi, x, new float[BoundedLeastSquares.WorkspaceLength(n)], out _, tol); + Assert.True((status == BoundedLeastSquaresStatus.InvalidInput) == (expected != BoundedLeastSquaresInput.Valid), $"{name}: Solve {status}"); + } + + // The overload without a tolerance validates against the default one. + Assert.Equal(BoundedLeastSquaresInput.Valid, BoundedLeastSquares.Validate(m, n, A54, B5, Fill(-1f, n), Fill(1f, n))); + Assert.Equal(BoundedLeastSquaresInput.InvalidBounds, BoundedLeastSquares.Validate(m, n, A54, B5, Fill(2f, n), Fill(1f, n))); + } + + [Fact] + public void ValidateReadsOnlyTheStatedDimensions() + { + // Entries beyond m * n, m and n are not inputs: a NaN there is not a fault. + const int m = 2, n = 2; + var a = new[] { 1f, 0f, 0f, 1f, float.NaN }; + var b = new[] { 1f, 1f, float.NaN }; + var lo = new[] { -1f, -1f, float.NaN }; + var hi = new[] { 1f, 1f, float.NaN }; + Assert.Equal(BoundedLeastSquaresInput.Valid, BoundedLeastSquares.Validate(m, n, a, b, lo, hi)); + + // A problem with no unknown has no use for b, so a non-finite b is not an invalid input there. + var nanB = new[] { float.NaN, 1f }; + Assert.Equal(BoundedLeastSquaresInput.Valid, BoundedLeastSquares.Validate(2, 0, ReadOnlySpan.Empty, nanB, ReadOnlySpan.Empty, ReadOnlySpan.Empty)); + Assert.Equal(BoundedLeastSquaresStatus.Converged, BoundedLeastSquares.Solve(2, 0, ReadOnlySpan.Empty, nanB, ReadOnlySpan.Empty, ReadOnlySpan.Empty, + Span.Empty, Span.Empty, out _)); + } + + [Fact] + public void ValidateThrowsOnAShortSpanLikeSolve() + { + const int m = 5, n = 3; + var lo = Fill(-1f, n); + var hi = Fill(1f, n); + // The caller-bug contract holds ahead of any value check: a NaN tolerance does not hide it. + Assert.Throws(() => BoundedLeastSquares.Validate(m, n, A54.AsSpan(1), B5, lo, hi, double.NaN)); + Assert.Throws(() => BoundedLeastSquares.Validate(m, n, A54, B5.AsSpan(1), lo, hi)); + Assert.Throws(() => BoundedLeastSquares.Validate(m, n, A54, B5, lo.AsSpan(1), hi)); + Assert.Throws(() => BoundedLeastSquares.Validate(m, n, A54, B5, lo, hi.AsSpan(1))); + Assert.Throws(() => BoundedLeastSquares.Validate(-1, n, A54, B5, lo, hi)); + Assert.Throws(() => BoundedLeastSquares.Validate(m, -1, A54, B5, lo, hi)); + } + + [Fact] + public void ValidateAllocatesNothing() + { + const int m = 5, n = 3; + var bad = (float[])A54.Clone(); + bad[14] = float.NaN; + var lo = Fill(-1f, n); + var hi = Fill(1f, n); + foreach (var (name, a, tol) in new[] { ("valid", A54, 1e-6), ("invalid matrix", bad, 1e-6), ("invalid tolerance", A54, 0.0) }) + { + var bytes = new long[2]; + for (var call = 0; call < 2; call++) + { + var before = GC.GetAllocatedBytesForCurrentThread(); + BoundedLeastSquares.Validate(m, n, a, B5, lo, hi, tol); + bytes[call] = GC.GetAllocatedBytesForCurrentThread() - before; + } + Assert.True(bytes[0] == 0 && bytes[1] == 0, $"{name}: first call {bytes[0]} B, second {bytes[1]} B"); + } + } + + [Fact] + public void SolveReturnsInvalidInputExactlyWhenValidateIsNotValid() + { + var invalid = 0; + for (uint seed = 1; seed <= 300; seed++) + { + var (m, n, a, b, lo, hi) = RandomProblem(seed); + var rng = new CultMath.Random(seed * 104729u); + var tol = 1e-6; + // Corrupt zero to three inputs, so some problems stay clean. + for (var k = rng.NextInt(4); k > 0; k--) + { + switch (rng.NextInt(5)) + { + case 0: tol = rng.NextInt(2) == 0 ? 0.0 : double.NaN; break; + case 1: lo[rng.NextInt(n)] = float.NaN; break; + case 2: { var j = rng.NextInt(n); lo[j] = hi[j] + 1f; } break; + case 3: a[rng.NextInt(m * n)] = rng.NextInt(2) == 0 ? float.NaN : float.NegativeInfinity; break; + default: b[rng.NextInt(m)] = float.PositiveInfinity; break; + } + } + var verdict = BoundedLeastSquares.Validate(m, n, a, b, lo, hi, tol); + var start = Fill(0.5f, n); + var x = (float[])start.Clone(); + var status = BoundedLeastSquares.Solve(m, n, a, b, lo, hi, x, new float[BoundedLeastSquares.WorkspaceLength(n)], out var iterations, tol); + Assert.True((status == BoundedLeastSquaresStatus.InvalidInput) == (verdict != BoundedLeastSquaresInput.Valid), $"seed {seed}: {verdict} but {status}"); + if (verdict != BoundedLeastSquaresInput.Valid) + { + invalid++; + Assert.Equal(0, iterations); + Assert.Equal(start, x); + } + } + Assert.InRange(invalid, 100, 280); + } + [Fact] public void InfiniteBoundsMeanUnbounded() {