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:
parent
dbcb2a8ea8
commit
004d8bb78a
2 changed files with 211 additions and 15 deletions
|
|
@ -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] > 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 <= x <= 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 <= x <= 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++)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in a new issue