Class NumericUtils

Namespace

SignalSharp.Utilities

Assembly

SignalSharp.dll

Provides utility methods for common numerical operations with generic number support.

public static class NumericUtils

Inheritance

object

NumericUtils

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This utility class implements type-safe numerical operations using the generic math capabilities provided by INumber<TSelf>. It offers consistent ways to handle various numeric comparisons, equality checks, and rounding operations across different numeric types.

Methods

AreApproximatelyEqualRelative<T>(T, T)

Checks if two floating-point values are approximately equal using default relative and absolute tolerances for the type.

public static bool AreApproximatelyEqualRelative<T>(T a, T b) where T : INumber<T>, IFloatingPointIeee754<T>

Parameters

a T

The first value to compare.

b T

The second value to compare.

Returns

bool

True if the values are close enough based on default tolerances.

Type Parameters

T

A numeric type that implements IFloatingPointIeee754<TSelf>.

Remarks

Uses default tolerances obtained from GetDefaultRelativeEpsilon<T>() and GetDefaultEpsilon<T>(). This is often the preferred method for comparing floating-point numbers for equality. See remarks on AreApproximatelyEqualRelative<T>(T, T, T, T).

AreApproximatelyEqualRelative<T>(T, T, T, T)

Checks if two floating-point values are approximately equal using a combined relative and absolute tolerance.

public static bool AreApproximatelyEqualRelative<T>(T a, T b, T relativeTolerance, T absoluteTolerance) where T : INumber<T>, IFloatingPoint<T>

Parameters

a T

The first value to compare.

b T

The second value to compare.

relativeTolerance T

The maximum allowed relative difference (must be non-negative).

absoluteTolerance T

The maximum allowed absolute difference (must be non-negative).

Returns

bool

True if the values are close enough based on the specified tolerances.

Type Parameters

T

A numeric type that implements IFloatingPoint<TSelf>.

Remarks

Implements the check Abs(a - b) <= absoluteTolerance + relativeTolerance * Abs(b). This approach is generally more robust than pure absolute or pure relative tolerance checks, handling both comparisons near zero (where absolute tolerance dominates) and comparisons of large numbers (where relative tolerance dominates). This is often the preferred method for comparing floating-point numbers for equality. Handles NaN correctly (comparison returns false). Handles Infinity correctly (Infinity == Infinity).

Exceptions

ArgumentOutOfRangeException

Thrown if relativeTolerance or absoluteTolerance is negative.

AreApproximatelyEqual<T>(T, T)

Checks if two numeric values are approximately equal using the default absolute tolerance (epsilon) for the type.

public static bool AreApproximatelyEqual<T>(T a, T b) where T : INumber<T>

Parameters

a T

The first value to compare.

b T

The second value to compare.

Returns

bool

True if the absolute difference between a and b is less than or equal to the default absolute epsilon.

Type Parameters

T

A numeric type that implements INumber<TSelf>.

Remarks

Uses a type-specific default absolute epsilon value obtained via GetDefaultEpsilon<T>(). See the remarks on AreApproximatelyEqual<T>(T, T, T) regarding the limitations of absolute tolerance. Consider using AreApproximatelyEqualRelative<T>(T, T) for potentially more robust comparisons.

AreApproximatelyEqual<T>(T, T, T)

Checks if two numeric values are approximately equal using an absolute tolerance (epsilon).

public static bool AreApproximatelyEqual<T>(T a, T b, T absoluteEpsilon) where T : INumber<T>

Parameters

a T

The first value to compare.

b T

The second value to compare.

absoluteEpsilon T

The maximum absolute difference allowed while considering the values equal (must be non-negative).

Returns

bool

True if the absolute difference between a and b is less than or equal to absoluteEpsilon.

Type Parameters

T

A numeric type that implements INumber<TSelf>.

Remarks

Compares using the absolute difference between the values, computed without relying on signed subtraction so that unsigned numeric types are handled correctly. This method uses a fixed absolute tolerance. It may not be suitable for comparing numbers of vastly different magnitudes or numbers very close to zero if the epsilon is relatively large. Consider using AreApproximatelyEqualRelative<T>(T, T, T, T) for a more robust comparison, especially for floating-point types.

Exceptions

ArgumentOutOfRangeException

Thrown if absoluteEpsilon is negative.

GetDefaultEpsilon<T>()

Gets the appropriate default epsilon value for the numeric type.

public static T GetDefaultEpsilon<T>() where T : INumber<T>

Returns

T

A type-appropriate default epsilon value.

Type Parameters

T

A numeric type that implements INumber<TSelf>.

Remarks

Provides type-specific epsilon values optimized for each numeric type's precision characteristics. Falls back to a reasonable default for other numeric types.

GetDefaultRelativeEpsilon<T>()

Gets the appropriate default relative epsilon value for floating-point types.

public static T GetDefaultRelativeEpsilon<T>() where T : INumber<T>, IFloatingPointIeee754<T>

Returns

T

A type-appropriate default relative epsilon value.

Type Parameters

T

A numeric type that implements IFloatingPointIeee754<TSelf>.

Remarks

Provides type-specific relative epsilon values for use in relative comparisons. Returns T.Zero for non-floating point types or if relative tolerance is not applicable.

GetStrictEpsilon<T>()

Gets the appropriate strict epsilon value for the numeric type.

public static T GetStrictEpsilon<T>() where T : INumber<T>

Returns

T

A type-appropriate strict epsilon value for high-precision operations.

Type Parameters

T

A numeric type that implements INumber<TSelf>.

Remarks

Provides stricter tolerance values for operations requiring higher precision. Use this for numerically sensitive calculations like model fitting or matrix operations.

GetVarianceEpsilon<T>()

Gets the appropriate variance epsilon value for the numeric type.

public static T GetVarianceEpsilon<T>() where T : INumber<T>

Returns

T

A type-appropriate epsilon value for variance calculations.

Type Parameters

T

A numeric type that implements INumber<TSelf>.

Remarks

Provides epsilon values specifically calibrated for variance calculations to prevent division by zero and logarithm of zero errors in statistical models. For integral types the value saturates to zero; variance floors are only meaningful for floating-point types.

IsEffectivelyInteger<T>(T)

Checks if a floating-point value is effectively an integer using the default epsilon for the type.

public static bool IsEffectivelyInteger<T>(T value) where T : INumber<T>, IFloatingPoint<T>

Parameters

value T

The value to check.

Returns

bool

True if the value is within the default epsilon of an integer.

Type Parameters

T

A numeric type that implements both INumber<TSelf> and IFloatingPoint<TSelf>.

Remarks

Uses a type-specific default epsilon value appropriate for the numeric type T.

IsEffectivelyInteger<T>(T, T)

Checks if a floating-point value is effectively an integer within the specified epsilon.

public static bool IsEffectivelyInteger<T>(T value, T epsilon) where T : INumber<T>, IFloatingPoint<T>

Parameters

value T

The value to check.

epsilon T

The maximum allowed difference from a whole number.

Returns

bool

True if the value is within epsilon of an integer.

Type Parameters

T

A numeric type that implements both INumber<TSelf> and IFloatingPoint<TSelf>.

Remarks

This is useful for determining if a floating-point value should be treated as an integer, accounting for potential rounding errors in floating-point arithmetic.

Exceptions

ArgumentOutOfRangeException

Thrown if epsilon is negative.

IsEffectivelyZero<T>(T)

Checks if a value is effectively zero using the default absolute tolerance (epsilon) for the type.

public static bool IsEffectivelyZero<T>(T value) where T : INumber<T>

Parameters

value T

The value to check.

Returns

bool

True if the absolute value is less than or equal to the default absolute epsilon.

Type Parameters

T

A numeric type that implements INumber<TSelf>.

Remarks

Uses a type-specific default absolute epsilon value obtained via GetDefaultEpsilon<T>(). See remarks on IsEffectivelyZero<T>(T, T).

IsEffectivelyZero<T>(T, T)

Checks if a value is effectively zero using an absolute tolerance (epsilon).

public static bool IsEffectivelyZero<T>(T value, T absoluteEpsilon) where T : INumber<T>

Parameters

value T

The value to check.

absoluteEpsilon T

The maximum absolute value to consider as effectively zero (must be non-negative).

Returns

bool

True if the absolute value is less than or equal to absoluteEpsilon.

Type Parameters

T

A numeric type that implements INumber<TSelf>.

Remarks

Compares using Abs(value) <= absoluteEpsilon. This method is useful for handling values that should be zero but might have small non-zero values due to arithmetic imprecisions or intentional thresholds. This performs an absolute tolerance check against zero.

Exceptions

ArgumentOutOfRangeException

Thrown if absoluteEpsilon is negative.