Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add tolerance context and numerics comparison primitives
Yuechen Li0d981faae0e4
diff --git a/Aetheris.Kernel.Core.Tests/ToleranceContextTests.cs b/Aetheris.Kernel.Core.Tests/ToleranceContextTests.csnew file mode 100644index 00000000..f7ca04bc--- /dev/null+++ b/Aetheris.Kernel.Core.Tests/ToleranceContextTests.cs@@ -0,0 +1,62 @@+using Aetheris.Kernel.Core.Numerics;++namespace Aetheris.Kernel.Core.Tests;++public sealed class ToleranceContextTests+{+ [Fact]+ public void Constructor_WithPositiveFiniteValues_CreatesContext()+ {+ var context = new ToleranceContext(linear: 1e-5, angular: 1e-7, relative: 1e-9);++ Assert.Equal(1e-5, context.Linear);+ Assert.Equal(1e-7, context.Angular);+ Assert.Equal(1e-9, context.Relative);+ }++ [Theory]+ [InlineData(0d)]+ [InlineData(-1d)]+ [InlineData(double.NaN)]+ [InlineData(double.PositiveInfinity)]+ [InlineData(double.NegativeInfinity)]+ public void Constructor_InvalidLinear_Throws(double linear)+ {+ Assert.Throws<ArgumentOutOfRangeException>(() => new ToleranceContext(linear, angular: 1e-7));+ }++ [Theory]+ [InlineData(0d)]+ [InlineData(-1d)]+ [InlineData(double.NaN)]+ [InlineData(double.PositiveInfinity)]+ [InlineData(double.NegativeInfinity)]+ public void Constructor_InvalidAngular_Throws(double angular)+ {+ Assert.Throws<ArgumentOutOfRangeException>(() => new ToleranceContext(linear: 1e-6, angular));+ }++ [Theory]+ [InlineData(0d)]+ [InlineData(-1d)]+ [InlineData(double.NaN)]+ [InlineData(double.PositiveInfinity)]+ [InlineData(double.NegativeInfinity)]+ public void Constructor_InvalidRelative_Throws(double relative)+ {+ Assert.Throws<ArgumentOutOfRangeException>(() => new ToleranceContext(linear: 1e-6, angular: 1e-7, relative));+ }++ [Fact]+ public void Default_HasPositiveFiniteValues()+ {+ var context = ToleranceContext.Default;++ Assert.True(double.IsFinite(context.Linear));+ Assert.True(double.IsFinite(context.Angular));+ Assert.True(double.IsFinite(context.Relative));+ Assert.True(context.Linear > 0);+ Assert.True(context.Angular > 0);+ Assert.True(context.Relative > 0);+ }+}diff --git a/Aetheris.Kernel.Core.Tests/ToleranceMathTests.cs b/Aetheris.Kernel.Core.Tests/ToleranceMathTests.csnew file mode 100644index 00000000..fd6ecb34--- /dev/null+++ b/Aetheris.Kernel.Core.Tests/ToleranceMathTests.cs@@ -0,0 +1,71 @@+using Aetheris.Kernel.Core.Numerics;++namespace Aetheris.Kernel.Core.Tests;++public sealed class ToleranceMathTests+{+ [Fact]+ public void AlmostEqual_WithinTolerance_ReturnsTrue()+ {+ var result = ToleranceMath.AlmostEqual(10, 10.0009, 0.001);++ Assert.True(result);+ }++ [Fact]+ public void AlmostEqual_OutsideTolerance_ReturnsFalse()+ {+ var result = ToleranceMath.AlmostEqual(10, 10.002, 0.001);++ Assert.False(result);+ }++ [Fact]+ public void AlmostZero_UsesInclusiveBoundary()+ {+ Assert.True(ToleranceMath.AlmostZero(0.001, 0.001));+ Assert.False(ToleranceMath.AlmostZero(0.0011, 0.001));+ }++ [Fact]+ public void LessThanOrAlmostEqual_HandlesBelowWithinAndAboveTolerance()+ {+ Assert.True(ToleranceMath.LessThanOrAlmostEqual(9.99, 10, 0.001));+ Assert.True(ToleranceMath.LessThanOrAlmostEqual(10.001, 10, 0.001));+ Assert.False(ToleranceMath.LessThanOrAlmostEqual(10.002, 10, 0.001));+ }++ [Fact]+ public void GreaterThanOrAlmostEqual_HandlesAboveWithinAndBelowTolerance()+ {+ Assert.True(ToleranceMath.GreaterThanOrAlmostEqual(10.01, 10, 0.001));+ Assert.True(ToleranceMath.GreaterThanOrAlmostEqual(9.999, 10, 0.001));+ Assert.False(ToleranceMath.GreaterThanOrAlmostEqual(9.998, 10, 0.001));+ }++ [Theory]+ [InlineData(0d)]+ [InlineData(-0.1)]+ [InlineData(double.NaN)]+ [InlineData(double.PositiveInfinity)]+ [InlineData(double.NegativeInfinity)]+ public void Methods_InvalidTolerance_Throws(double tolerance)+ {+ Assert.Throws<ArgumentOutOfRangeException>(() => ToleranceMath.AlmostEqual(1, 1, tolerance));+ Assert.Throws<ArgumentOutOfRangeException>(() => ToleranceMath.AlmostZero(0, tolerance));+ Assert.Throws<ArgumentOutOfRangeException>(() => ToleranceMath.LessThanOrAlmostEqual(1, 1, tolerance));+ Assert.Throws<ArgumentOutOfRangeException>(() => ToleranceMath.GreaterThanOrAlmostEqual(1, 1, tolerance));+ Assert.Throws<ArgumentOutOfRangeException>(() => ToleranceMath.ClampToZero(0, tolerance));+ }++ [Fact]+ public void ContextOverload_UsesLinearToleranceConsistently()+ {+ var context = new ToleranceContext(linear: 0.001, angular: 1e-8);++ var byContext = ToleranceMath.AlmostEqual(5, 5.0008, context);+ var byLinear = ToleranceMath.AlmostEqual(5, 5.0008, context.Linear);++ Assert.Equal(byLinear, byContext);+ }+}diff --git a/Aetheris.Kernel.Core/Numerics/ToleranceContext.cs b/Aetheris.Kernel.Core/Numerics/ToleranceContext.csnew file mode 100644index 00000000..03699ceb--- /dev/null+++ b/Aetheris.Kernel.Core/Numerics/ToleranceContext.cs@@ -0,0 +1,47 @@+namespace Aetheris.Kernel.Core.Numerics;++/// <summary>+/// Immutable tolerance settings for kernel numeric comparisons.+/// Linear applies to model-space distances and scalar values; Angular applies to radians.+/// </summary>+public readonly record struct ToleranceContext+{+ /// <summary>+ /// Gets a default kernel tolerance profile suitable for general model-space operations.+ /// </summary>+ public static ToleranceContext Default { get; } = CreateDefault();++ public ToleranceContext(double linear, double angular, double relative = 1e-12)+ {+ Linear = EnsurePositiveFinite(linear, nameof(linear));+ Angular = EnsurePositiveFinite(angular, nameof(angular));+ Relative = EnsurePositiveFinite(relative, nameof(relative));+ }++ /// <summary>+ /// Gets the linear (model-space) tolerance.+ /// </summary>+ public double Linear { get; }++ /// <summary>+ /// Gets the angular tolerance in radians.+ /// </summary>+ public double Angular { get; }++ /// <summary>+ /// Gets the relative tolerance for scale-aware comparisons.+ /// </summary>+ public double Relative { get; }++ public static ToleranceContext CreateDefault() => new(linear: 1e-6, angular: 1e-9, relative: 1e-12);++ private static double EnsurePositiveFinite(double value, string paramName)+ {+ if (!double.IsFinite(value) || value <= 0)+ {+ throw new ArgumentOutOfRangeException(paramName, "Tolerance values must be finite and greater than zero.");+ }++ return value;+ }+}diff --git a/Aetheris.Kernel.Core/Numerics/ToleranceMath.cs b/Aetheris.Kernel.Core/Numerics/ToleranceMath.csnew file mode 100644index 00000000..8472a334--- /dev/null+++ b/Aetheris.Kernel.Core/Numerics/ToleranceMath.cs@@ -0,0 +1,50 @@+namespace Aetheris.Kernel.Core.Numerics;++public static class ToleranceMath+{+ public static bool AlmostEqual(double a, double b, double tolerance)+ {+ var validatedTolerance = ValidateTolerance(tolerance);+ return Math.Abs(a - b) <= validatedTolerance;+ }++ public static bool AlmostEqual(double a, double b, ToleranceContext context) => AlmostEqual(a, b, context.Linear);++ public static bool AlmostZero(double value, double tolerance)+ {+ var validatedTolerance = ValidateTolerance(tolerance);+ return Math.Abs(value) <= validatedTolerance;+ }++ public static bool AlmostZero(double value, ToleranceContext context) => AlmostZero(value, context.Linear);++ public static bool LessThanOrAlmostEqual(double a, double b, double tolerance)+ {+ var validatedTolerance = ValidateTolerance(tolerance);+ return a <= b + validatedTolerance;+ }++ public static bool LessThanOrAlmostEqual(double a, double b, ToleranceContext context) =>+ LessThanOrAlmostEqual(a, b, context.Linear);++ public static bool GreaterThanOrAlmostEqual(double a, double b, double tolerance)+ {+ var validatedTolerance = ValidateTolerance(tolerance);+ return a + validatedTolerance >= b;+ }++ public static bool GreaterThanOrAlmostEqual(double a, double b, ToleranceContext context) =>+ GreaterThanOrAlmostEqual(a, b, context.Linear);++ public static double ClampToZero(double value, double tolerance) => AlmostZero(value, tolerance) ? 0d : value;++ private static double ValidateTolerance(double tolerance)+ {+ if (!double.IsFinite(tolerance) || tolerance <= 0)+ {+ throw new ArgumentOutOfRangeException(nameof(tolerance), "Tolerance must be finite and greater than zero.");+ }++ return tolerance;+ }+}diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 2dc542d1..7f7214ef 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -13,5 +13,5 @@## Kernel discipline-- Do not introduce ad hoc epsilon constants; follow `docs/numerics-policy.md`.+- Do not introduce ad hoc epsilon constants; use `ToleranceContext` + `ToleranceMath` and follow `docs/numerics-policy.md`.- Favor diagnostic/result-oriented kernel operations over exceptions for expected operation outcomes (future-facing rule).diff --git a/docs/numerics-policy.md b/docs/numerics-policy.mdindex d5266e94..23b249eb 100644--- a/docs/numerics-policy.md+++ b/docs/numerics-policy.md@@ -6,6 +6,7 @@ This document sets baseline numeric discipline for upcoming milestones.- Centralized tolerance policy: tolerance values must be defined in shared kernel locations.- No ad hoc epsilon literals in random files.+- Use `ToleranceContext` and `ToleranceMath` helpers for tolerance-aware comparisons instead of inline literals like `1e-6`.- `double` precision is the default numeric type unless a milestone explicitly introduces alternatives.- Prefer exact analytic representations where available; use tolerant operations where required by computation.- Diagnostics and failure modes must be deterministic and observable.