Skip to content

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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.md
index 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.md
index 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.