CultMath BoundedLeastSquares: Validate names the invalid input; Solve's validation has one owner

Adds BoundedLeastSquaresInput and BoundedLeastSquares.Validate (tolerance, bounds, matrix, target; first failure).
Solve calls it and its inline tolerance, bounds and A^T b finiteness checks are deleted. Untested at this commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-10-10 19:24:59 +02:00
commit 004d8bb78a
2 changed files with 211 additions and 15 deletions

View file

@ -11,10 +11,29 @@ public enum BoundedLeastSquaresStatus
/// <summary>The iteration cap was reached. <c>x</c> holds the last feasible iterate, which is never worse than the clamped start.</summary>
IterationLimit,
/// <summary>The input broke the contract; nothing was solved and <c>x</c> is exactly as passed.</summary>
/// <summary>The input broke the contract; nothing was solved and <c>x</c> is exactly as passed. <see cref="BoundedLeastSquares.Validate"/> names which input.</summary>
InvalidInput,
}
/// <summary>Which input of <see cref="BoundedLeastSquares"/> breaks its contract; the first failure in the order of the members.</summary>
public enum BoundedLeastSquaresInput
{
/// <summary>Every input meets the contract; <c>Solve</c> will not return <see cref="BoundedLeastSquaresStatus.InvalidInput"/>.</summary>
Valid,
/// <summary>The KKT tolerance is not finite and greater than zero.</summary>
InvalidTolerance,
/// <summary>Some <c>lo</c> or <c>hi</c> is NaN, <c>lo[j] &gt; hi[j]</c>, <c>lo[j]</c> is <c>+Inf</c> or <c>hi[j]</c> is <c>-Inf</c>.</summary>
InvalidBounds,
/// <summary>Some entry of <c>a</c> is NaN or infinite.</summary>
NonFiniteMatrix,
/// <summary>Some entry of <c>b</c> is NaN or infinite.</summary>
NonFiniteTarget,
}
/// <summary>
/// Dense bounded least squares: <c>min ||A x - b||^2</c> subject to <c>lo &lt;= x &lt;= hi</c>, for small problems
/// (tens of rows and columns). C#-only, like the intercept helpers in <see cref="math"/>; there is no HLSL mirror.
@ -58,7 +77,9 @@ public enum BoundedLeastSquaresStatus
/// <see cref="BoundedLeastSquaresStatus.InvalidInput"/> without throwing, with <c>iterations</c> 0 and
/// <c>x</c> 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 <see cref="ArgumentException"/>.
/// caller bug and throw <see cref="ArgumentException"/>. <see cref="Validate"/> reports which input broke the
/// contract, and <c>Solve</c> returns <c>InvalidInput</c> exactly when it does not return
/// <see cref="BoundedLeastSquaresInput.Valid"/>.
/// </para>
/// </remarks>
public static class BoundedLeastSquares
@ -75,6 +96,44 @@ public static class BoundedLeastSquares
/// <summary>Floats of caller-supplied workspace needed for <paramref name="n"/> columns.</summary>
public static int WorkspaceLength(int n) => 2 * (2 * n * n + 6 * n) + 3 * n;
/// <summary>
/// Checks the inputs of <c>Solve</c> against its contract and names the first one that breaks it, in the order
/// tolerance, bounds, matrix, target. <c>Solve</c> calls this and returns
/// <see cref="BoundedLeastSquaresStatus.InvalidInput"/> for any result but <see cref="BoundedLeastSquaresInput.Valid"/>.
/// It reads its arguments only, allocates nothing and does not throw for a bad value.
/// </summary>
/// <param name="m">Rows of <paramref name="a"/>.</param>
/// <param name="n">Columns of <paramref name="a"/>, and length of <paramref name="lo"/> and <paramref name="hi"/>.</param>
/// <param name="a">Row-major <c>m * n</c> matrix.</param>
/// <param name="b">Length <c>m</c> target. With <c>n = 0</c> there is no unknown and <paramref name="b"/> is not read.</param>
/// <param name="lo">Lower bounds.</param>
/// <param name="hi">Upper bounds.</param>
/// <param name="kktRelativeTolerance">The tolerance <c>Solve</c> will be given.</param>
/// <exception cref="ArgumentException">A span is shorter than the stated dimensions, or <paramref name="m"/> or <paramref name="n"/> is negative: a caller bug, not an invalid input.</exception>
public static BoundedLeastSquaresInput Validate(
int m, int n,
ReadOnlySpan<float> a, ReadOnlySpan<float> b,
ReadOnlySpan<float> lo, ReadOnlySpan<float> 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;
}
/// <summary>
/// Minimises <c>||A x - b||^2</c> subject to <c>lo &lt;= x &lt;= hi</c>. <paramref name="x"/> 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++)
{

View file

@ -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<float[], float[], float[], float[]> 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<float>.Empty, nanB, ReadOnlySpan<float>.Empty, ReadOnlySpan<float>.Empty));
Assert.Equal(BoundedLeastSquaresStatus.Converged, BoundedLeastSquares.Solve(2, 0, ReadOnlySpan<float>.Empty, nanB, ReadOnlySpan<float>.Empty, ReadOnlySpan<float>.Empty,
Span<float>.Empty, Span<float>.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<ArgumentException>(() => BoundedLeastSquares.Validate(m, n, A54.AsSpan(1), B5, lo, hi, double.NaN));
Assert.Throws<ArgumentException>(() => BoundedLeastSquares.Validate(m, n, A54, B5.AsSpan(1), lo, hi));
Assert.Throws<ArgumentException>(() => BoundedLeastSquares.Validate(m, n, A54, B5, lo.AsSpan(1), hi));
Assert.Throws<ArgumentException>(() => BoundedLeastSquares.Validate(m, n, A54, B5, lo, hi.AsSpan(1)));
Assert.Throws<ArgumentException>(() => BoundedLeastSquares.Validate(-1, n, A54, B5, lo, hi));
Assert.Throws<ArgumentException>(() => 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()
{