num_valid/

scalars.rs

#![deny(rustdoc::broken_intra_doc_links)]

//! Type-safe scalar wrappers for numerical tolerances and constrained real values.
//!
//! This module provides strongly-typed wrappers around primitive scalar types to prevent
//! value confusion and enforce mathematical constraints at compile time. These types are
//! fundamental building blocks for numerical computations that require validated tolerances
//! and constrained real number values.
//!
//! # Overview
//!
//! The module provides four primary types:
//!
//! | Type | Constraint | Zero Valid? | Use Cases |
//! |------|------------|-------------|-----------|
//! | [`AbsoluteTolerance<T>`] | `≥ 0` | ✅ Yes | Fixed error bounds for comparisons |
//! | [`RelativeTolerance<T>`] | `≥ 0` | ✅ Yes | Proportional error bounds |
//! | [`PositiveRealScalar<T>`] | `> 0` | ❌ No | Lengths, positive quantities |
//! | [`NonNegativeRealScalar<T>`] | `≥ 0` | ✅ Yes | Distances, magnitudes, absolute values |
//!
//! All types are generic over [`RealScalar`], enabling consistent validation across
//! different numerical backends (native `f64`, arbitrary-precision `rug`, etc.).
//!
//! # Design Philosophy
//!
//! ## Type Safety Through Distinct Types
//!
//! Rather than using raw primitives like `f64` directly, this module provides
//! semantically meaningful types that encode mathematical constraints:
//!
//! ```rust
//! use num_valid::{
//!     backends::native64::validated::RealNative64StrictFinite, RealScalar,
//!     scalars::{AbsoluteTolerance, RelativeTolerance, PositiveRealScalar},
//! };
//! use try_create::TryNew;
//!
//! // These are different types that cannot be confused:
//! let abs_tol = AbsoluteTolerance::try_new(1e-10_f64).unwrap();   // For absolute comparisons
//! let rel_tol = RelativeTolerance::try_new(1e-6_f64).unwrap();    // For relative comparisons
//! let length = PositiveRealScalar::try_new(5.0_f64).unwrap();     // Must be > 0
//!
//! // Type system prevents mixing them up:
//! // let wrong: AbsoluteTolerance<f64> = rel_tol;  // ← Compilation error!
//! ```
//!
//! ## Validation at Construction Time
//!
//! All types validate their input at construction time, failing fast on invalid values:
//!
//! ```rust
//! use num_valid::scalars::{AbsoluteTolerance, PositiveRealScalar, ErrorsTolerance, ErrorsPositiveRealScalar};
//! use try_create::TryNew;
//!
//! // Negative tolerances are rejected
//! let invalid_tol = AbsoluteTolerance::try_new(-1e-6_f64);
//! assert!(matches!(invalid_tol, Err(ErrorsTolerance::NegativeValue { .. })));
//!
//! // Zero is not positive
//! let invalid_pos = PositiveRealScalar::try_new(0.0_f64);
//! assert!(matches!(invalid_pos, Err(ErrorsPositiveRealScalar::ZeroValue { .. })));
//! ```
//!
//! # Tolerance Types
//!
//! ## [`AbsoluteTolerance<T>`]
//!
//! Represents an absolute error bound for numerical comparisons. The tolerance value
//! must be non-negative (≥ 0).
//!
//! ```rust
//! use num_valid::scalars::AbsoluteTolerance;
//! use try_create::TryNew;
//!
//! // Create tolerances
//! let tight = AbsoluteTolerance::try_new(1e-12_f64).unwrap();
//! let loose = AbsoluteTolerance::try_new(1e-6_f64).unwrap();
//! let zero = AbsoluteTolerance::<f64>::zero();       // Exact comparison
//! let epsilon = AbsoluteTolerance::<f64>::epsilon(); // Machine epsilon
//!
//! // Use in approximate comparison
//! fn approximately_equal<T: num_valid::RealScalar + Clone>(
//!     a: T,
//!     b: T,
//!     tolerance: &AbsoluteTolerance<T>
//! ) -> bool {
//!     let diff = (a - b).abs();
//!     &diff <= tolerance.as_ref()
//! }
//!
//! assert!(approximately_equal(1.0, 1.0 + 1e-13, &tight));
//! assert!(!approximately_equal(1.0, 1.0 + 1e-11, &tight));
//! ```
//!
//! ## [`RelativeTolerance<T>`]
//!
//! Represents a relative (proportional) error bound. Can be converted to an absolute
//! tolerance based on a reference value.
//!
//! ```rust
//! use num_valid::scalars::RelativeTolerance;
//! use try_create::TryNew;
//!
//! let rel_tol = RelativeTolerance::try_new(0.01_f64).unwrap(); // 1% tolerance
//!
//! // Convert to absolute tolerance based on reference value
//! let reference = 1000.0_f64;
//! let abs_tol = rel_tol.absolute_tolerance(reference);
//! assert_eq!(*abs_tol.as_ref(), 10.0); // 1% of 1000 = 10
//! ```
//!
//! # Constrained Real Number Types
//!
//! ## [`PositiveRealScalar<T>`]
//!
//! Wraps a real scalar that must be strictly positive (> 0). Zero is **not** valid.
//!
//! ```rust
//! use num_valid::scalars::{PositiveRealScalar, ErrorsPositiveRealScalar};
//! use try_create::TryNew;
//!
//! // Valid positive values
//! let length = PositiveRealScalar::try_new(2.5_f64).unwrap();
//! let tiny = PositiveRealScalar::try_new(f64::MIN_POSITIVE).unwrap();
//!
//! // Zero is NOT positive (x > 0 required)
//! let zero_result = PositiveRealScalar::try_new(0.0_f64);
//! assert!(matches!(zero_result, Err(ErrorsPositiveRealScalar::ZeroValue { .. })));
//!
//! // Negative values rejected
//! let neg_result = PositiveRealScalar::try_new(-1.0_f64);
//! assert!(matches!(neg_result, Err(ErrorsPositiveRealScalar::NegativeValue { .. })));
//! ```
//!
//! ## [`NonNegativeRealScalar<T>`]
//!
//! Wraps a real scalar that must be non-negative (≥ 0). Zero **is** valid.
//!
//! ```rust
//! use num_valid::scalars::{NonNegativeRealScalar, PositiveRealScalar};
//! use try_create::TryNew;
//!
//! // Zero is valid for NonNegativeRealScalar
//! let zero = NonNegativeRealScalar::try_new(0.0_f64).unwrap();
//! assert_eq!(*zero.as_ref(), 0.0);
//!
//! // But NOT for PositiveRealScalar
//! assert!(PositiveRealScalar::try_new(0.0_f64).is_err());
//!
//! // Use case: computing distances (can be zero)
//! fn distance(a: f64, b: f64) -> NonNegativeRealScalar<f64> {
//!     NonNegativeRealScalar::try_new((a - b).abs()).unwrap()
//! }
//!
//! let d = distance(5.0, 5.0); // Zero distance is valid
//! assert_eq!(*d.as_ref(), 0.0);
//! ```
//!
//! # Generic Programming with [`RealScalar`]
//!
//! All types work seamlessly with any scalar type implementing [`RealScalar`]:
//!
//! ```rust
//! use num_valid::{
//!     backends::native64::validated::{RealNative64StrictFinite, RealNative64StrictFiniteInDebug},
//!     RealScalar,
//!     scalars::AbsoluteTolerance
//! };
//! use try_create::TryNew;
//!
//! // Same tolerance type works with different backends
//! type FastTol = AbsoluteTolerance<f64>;
//! type SafeTol = AbsoluteTolerance<RealNative64StrictFinite>;
//! type DebugTol = AbsoluteTolerance<RealNative64StrictFiniteInDebug>;
//!
//! let fast = FastTol::try_new(1e-10).unwrap();
//! let safe = SafeTol::try_new(RealNative64StrictFinite::try_from_f64(1e-10).unwrap()).unwrap();
//! ```
//!
//! # Performance Characteristics
//!
//! All wrapper types are designed as zero-cost abstractions:
//!
//! | Type | Memory Layout | Runtime Overhead |
//! |------|---------------|------------------|
//! | [`AbsoluteTolerance<T>`] | Same as `T` | Zero (validation at construction only) |
//! | [`RelativeTolerance<T>`] | Same as `T` | Zero (validation at construction only) |
//! | [`PositiveRealScalar<T>`] | Same as `T` | Zero (validation at construction only) |
//! | [`NonNegativeRealScalar<T>`] | Same as `T` | Zero (validation at construction only) |
//!
//! The `#[repr(transparent)]` attribute ensures that each wrapper has the exact same
//! memory layout as its underlying type.
//!
//! # Relationship to `approx` Crate
//!
//! These tolerance types complement the [`approx`] crate's comparison traits. While `approx`
//! uses raw `f64` for epsilon values (which can be negative, causing silent failures),
//! these wrappers guarantee non-negativity at construction time:
//!
//! ```rust
//! use num_valid::scalars::AbsoluteTolerance;
//! use num_valid::approx::assert_abs_diff_eq;
//! use try_create::TryNew;
//!
//! // Create a validated tolerance
//! let tol = AbsoluteTolerance::try_new(1e-10_f64).unwrap();
//!
//! // Use with approx (extract the inner value)
//! let a = 1.0_f64;
//! let b = 1.0 + 1e-11;
//! assert_abs_diff_eq!(a, b, epsilon = *tol.as_ref());
//! ```

use crate::{RealScalar, core::errors::capture_backtrace};
use derive_more::{AsRef, Display, LowerExp};
use into_inner::IntoInner;
use serde::{Deserialize, Serialize};
use std::backtrace::Backtrace;
use thiserror::Error;
use try_create::TryNew;

//------------------------------------------------------------------------------------------------------------
// Error Types
//------------------------------------------------------------------------------------------------------------

/// Error type for tolerance validation failures.
///
/// This enum provides detailed error information when attempting to construct
/// tolerance types ([`AbsoluteTolerance<T>`] and [`RelativeTolerance<T>`]) with
/// invalid input values.
///
/// # Error Variants
///
/// - [`ErrorsTolerance::NegativeValue`]: The input value was negative, which violates
///   the non-negativity constraint required for all tolerance values.
///
/// # Examples
///
/// ```rust
/// use num_valid::scalars::{AbsoluteTolerance, ErrorsTolerance};
/// use try_create::TryNew;
///
/// // Negative values are rejected
/// match AbsoluteTolerance::try_new(-1e-6_f64) {
///     Err(ErrorsTolerance::NegativeValue { value, .. }) => {
///         println!("Rejected negative tolerance: {}", value);
///         assert_eq!(value, -1e-6);
///     }
///     _ => unreachable!(),
/// }
/// ```
///
/// # Backtrace Support
///
/// The error includes backtrace information when the `backtrace` feature is enabled,
/// which can aid in debugging by showing where the invalid value originated.
#[derive(Debug, Error)]
pub enum ErrorsTolerance<RealType: RealScalar> {
    /// The input value was negative (must be ≥ 0).
    #[error("Negative value detected: {value}")]
    NegativeValue {
        /// The negative value that was rejected.
        value: RealType,
        /// Captured backtrace for debugging.
        backtrace: Backtrace,
    },
}

/// Error type for [`PositiveRealScalar<T>`] validation failures.
///
/// This enum provides detailed error information when attempting to construct
/// a [`PositiveRealScalar<T>`] with invalid input values.
///
/// # Error Variants
///
/// - [`ErrorsPositiveRealScalar::NegativeValue`]: The input was negative (< 0).
/// - [`ErrorsPositiveRealScalar::ZeroValue`]: The input was zero (not strictly positive).
///
/// # Mathematical Distinction
///
/// Positive real numbers are defined as `ℝ⁺ = {x ∈ ℝ : x > 0}`, which **excludes** zero.
/// This is distinct from non-negative reals `ℝ₀⁺ = {x ∈ ℝ : x ≥ 0}`.
///
/// # Examples
///
/// ```rust
/// use num_valid::scalars::{PositiveRealScalar, ErrorsPositiveRealScalar};
/// use try_create::TryNew;
///
/// // Zero is NOT positive
/// match PositiveRealScalar::try_new(0.0_f64) {
///     Err(ErrorsPositiveRealScalar::ZeroValue { .. }) => {
///         println!("Zero is not strictly positive (x > 0 required)");
///     }
///     _ => unreachable!(),
/// }
///
/// // Negative values rejected with the value included in the error
/// match PositiveRealScalar::try_new(-2.5_f64) {
///     Err(ErrorsPositiveRealScalar::NegativeValue { value, .. }) => {
///         assert_eq!(value, -2.5);
///     }
///     _ => unreachable!(),
/// }
/// ```
#[derive(Debug, Error)]
pub enum ErrorsPositiveRealScalar<RealType: RealScalar> {
    /// The input value was negative (< 0).
    #[error("Negative value detected: {value}")]
    NegativeValue {
        /// The specific negative value that was rejected.
        value: RealType,
        /// Stack trace for debugging.
        backtrace: Backtrace,
    },

    /// The input value was exactly zero (not strictly positive).
    ///
    /// Zero is NOT positive in mathematical terms. The positive real numbers
    /// are defined as `ℝ⁺ = {x ∈ ℝ : x > 0}`, which excludes zero.
    #[error("Zero value detected")]
    ZeroValue {
        /// Stack trace for debugging.
        backtrace: Backtrace,
    },
}

/// Error type for [`NonNegativeRealScalar<T>`] validation failures.
///
/// This enum provides error information when attempting to construct a
/// [`NonNegativeRealScalar<T>`] with a negative value.
///
/// # Error Variants
///
/// - [`ErrorsNonNegativeRealScalar::NegativeValue`]: The input was negative (< 0).
///
/// Note that zero is **valid** for [`NonNegativeRealScalar`], unlike [`PositiveRealScalar`].
///
/// # Examples
///
/// ```rust
/// use num_valid::scalars::{NonNegativeRealScalar, ErrorsNonNegativeRealScalar};
/// use try_create::TryNew;
///
/// // Zero is valid for NonNegativeRealScalar
/// let zero = NonNegativeRealScalar::try_new(0.0_f64);
/// assert!(zero.is_ok());
///
/// // Negative values are rejected
/// match NonNegativeRealScalar::try_new(-1.0_f64) {
///     Err(ErrorsNonNegativeRealScalar::NegativeValue { value, .. }) => {
///         assert_eq!(value, -1.0);
///     }
///     _ => unreachable!(),
/// }
/// ```
#[derive(Debug, Error)]
pub enum ErrorsNonNegativeRealScalar<RealType: RealScalar> {
    /// The input value was negative (must be ≥ 0).
    #[error("Negative value: {value} (must be non-negative, i.e., ≥ 0)")]
    NegativeValue {
        /// The negative value that was rejected.
        value: RealType,
        /// Stack trace for debugging.
        backtrace: Backtrace,
    },
}

//------------------------------------------------------------------------------------------------------------
// AbsoluteTolerance
//------------------------------------------------------------------------------------------------------------

/// Type-safe wrapper for absolute tolerance values.
///
/// [`AbsoluteTolerance<T>`] represents a non-negative (≥ 0) tolerance value used for
/// absolute error comparisons. It ensures that the tolerance is always valid by
/// rejecting negative values at construction time.
///
/// # Mathematical Definition
///
/// An absolute tolerance `ε` is used in comparisons like:
/// ```text
/// |a - b| ≤ ε
/// ```
///
/// Since `ε` represents a distance or error bound, it must be non-negative.
///
/// # Type Parameters
///
/// - `RealType`: The underlying real scalar type (e.g., `f64`, [`RealNative64StrictFinite`](crate::RealNative64StrictFinite))
///
/// # Examples
///
/// ## Basic Usage
///
/// ```rust
/// use num_valid::scalars::AbsoluteTolerance;
/// use try_create::TryNew;
///
/// // Create from f64
/// let tol = AbsoluteTolerance::try_new(1e-10_f64).unwrap();
/// assert_eq!(*tol.as_ref(), 1e-10);
///
/// // Use convenience constructors
/// let zero = AbsoluteTolerance::<f64>::zero();
/// let eps = AbsoluteTolerance::<f64>::epsilon();
/// ```
///
/// ## In Numerical Comparisons
///
/// ```rust
/// use num_valid::scalars::AbsoluteTolerance;
/// use num_valid::RealScalar;
/// use try_create::TryNew;
///
/// fn approximately_equal<T: RealScalar + Clone>(a: T, b: T, tol: &AbsoluteTolerance<T>) -> bool {
///     let diff = (a - b).abs();
///     &diff <= tol.as_ref()
/// }
///
/// let tol = AbsoluteTolerance::try_new(1e-10_f64).unwrap();
/// assert!(approximately_equal(1.0, 1.0 + 1e-11, &tol));
/// assert!(!approximately_equal(1.0, 1.0 + 1e-9, &tol));
/// ```
///
/// # Zero-Cost Abstraction
///
/// This type uses `#[repr(transparent)]` and has zero runtime overhead beyond
/// the initial validation at construction time.
#[derive(
    Debug, Clone, PartialEq, PartialOrd, AsRef, IntoInner, Display, LowerExp, Serialize, Deserialize,
)]
#[repr(transparent)]
pub struct AbsoluteTolerance<RealType>(RealType);

impl<RealType: RealScalar> AbsoluteTolerance<RealType> {
    /// Creates an absolute tolerance of zero.
    ///
    /// A zero tolerance represents an exact comparison (no error allowed).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_valid::scalars::AbsoluteTolerance;
    ///
    /// let zero_tol = AbsoluteTolerance::<f64>::zero();
    /// assert_eq!(*zero_tol.as_ref(), 0.0);
    /// ```
    #[inline(always)]
    pub fn zero() -> Self {
        AbsoluteTolerance(RealType::zero())
    }

    /// Creates an absolute tolerance equal to machine epsilon.
    ///
    /// Machine epsilon is the smallest value such that `1.0 + epsilon != 1.0`.
    /// This is often a good default tolerance for floating-point comparisons.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_valid::scalars::AbsoluteTolerance;
    ///
    /// let eps_tol = AbsoluteTolerance::<f64>::epsilon();
    /// assert_eq!(*eps_tol.as_ref(), f64::EPSILON);
    /// ```
    #[inline(always)]
    pub fn epsilon() -> Self {
        AbsoluteTolerance(RealType::epsilon())
    }
}

impl<RealType: RealScalar> TryNew for AbsoluteTolerance<RealType> {
    type Error = ErrorsTolerance<RealType>;

    /// Attempts to create an [`AbsoluteTolerance`] from a value.
    ///
    /// # Errors
    ///
    /// Returns [`ErrorsTolerance::NegativeValue`] if the input is negative.
    ///
    /// # Panics (Debug Mode Only)
    ///
    /// In debug builds, panics if the input is not finite (NaN or infinity).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_valid::scalars::{AbsoluteTolerance, ErrorsTolerance};
    /// use try_create::TryNew;
    ///
    /// // Valid tolerances
    /// assert!(AbsoluteTolerance::try_new(1e-10_f64).is_ok());
    /// assert!(AbsoluteTolerance::try_new(0.0_f64).is_ok());
    ///
    /// // Invalid (negative)
    /// assert!(matches!(
    ///     AbsoluteTolerance::try_new(-1e-10_f64),
    ///     Err(ErrorsTolerance::NegativeValue { .. })
    /// ));
    /// ```
    fn try_new(value: RealType) -> Result<Self, Self::Error> {
        debug_assert!(value.is_finite(), "The input value {value} is not finite!");
        if value.kernel_is_sign_negative() {
            Err(ErrorsTolerance::NegativeValue {
                value,
                backtrace: capture_backtrace(),
            })
        } else {
            Ok(Self(value))
        }
    }
}

//------------------------------------------------------------------------------------------------------------
// RelativeTolerance
//------------------------------------------------------------------------------------------------------------

/// Type-safe wrapper for relative tolerance values.
///
/// [`RelativeTolerance<T>`] represents a non-negative (≥ 0) tolerance value used for
/// relative (proportional) error comparisons. It can be converted to an absolute
/// tolerance based on a reference value.
///
/// # Mathematical Definition
///
/// A relative tolerance `ε_rel` is used in comparisons like:
/// ```text
/// |a - b| ≤ ε_rel × |reference|
/// ```
///
/// Common relative tolerances:
/// - `0.01` = 1% tolerance
/// - `0.001` = 0.1% tolerance
/// - `1e-6` = one part per million
///
/// # Examples
///
/// ## Basic Usage
///
/// ```rust
/// use num_valid::scalars::RelativeTolerance;
/// use try_create::TryNew;
///
/// let one_percent = RelativeTolerance::try_new(0.01_f64).unwrap();
/// assert_eq!(*one_percent.as_ref(), 0.01);
/// ```
///
/// ## Converting to Absolute Tolerance
///
/// ```rust
/// use num_valid::scalars::RelativeTolerance;
/// use try_create::TryNew;
///
/// let rel_tol = RelativeTolerance::try_new(0.01_f64).unwrap(); // 1%
///
/// // Convert based on reference value
/// let abs_tol = rel_tol.absolute_tolerance(1000.0);
/// assert_eq!(*abs_tol.as_ref(), 10.0); // 1% of 1000 = 10
///
/// // Works with negative references (uses absolute value)
/// let abs_tol_neg = rel_tol.absolute_tolerance(-500.0);
/// assert_eq!(*abs_tol_neg.as_ref(), 5.0); // 1% of |-500| = 5
/// ```
#[derive(
    Debug, Clone, PartialEq, PartialOrd, AsRef, IntoInner, Display, LowerExp, Serialize, Deserialize,
)]
#[repr(transparent)]
pub struct RelativeTolerance<RealType>(RealType);

impl<RealType: RealScalar> RelativeTolerance<RealType> {
    /// Creates a relative tolerance of zero.
    ///
    /// A zero relative tolerance represents an exact comparison.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_valid::scalars::RelativeTolerance;
    ///
    /// let zero_tol = RelativeTolerance::<f64>::zero();
    /// assert_eq!(*zero_tol.as_ref(), 0.0);
    /// ```
    #[inline(always)]
    pub fn zero() -> Self {
        RelativeTolerance(RealType::zero())
    }

    /// Creates a relative tolerance equal to machine epsilon.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_valid::scalars::RelativeTolerance;
    ///
    /// let eps_tol = RelativeTolerance::<f64>::epsilon();
    /// assert_eq!(*eps_tol.as_ref(), f64::EPSILON);
    /// ```
    #[inline(always)]
    pub fn epsilon() -> Self {
        RelativeTolerance(RealType::epsilon())
    }

    /// Converts this relative tolerance to an absolute tolerance based on a reference value.
    ///
    /// The absolute tolerance is computed as:
    /// ```text
    /// absolute_tolerance = relative_tolerance × |reference|
    /// ```
    ///
    /// # Parameters
    ///
    /// - `reference`: The reference value to scale by. The absolute value is used.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_valid::scalars::RelativeTolerance;
    /// use try_create::TryNew;
    ///
    /// let rel_tol = RelativeTolerance::try_new(0.1_f64).unwrap(); // 10%
    ///
    /// // 10% of 100 = 10
    /// let abs_tol = rel_tol.absolute_tolerance(100.0);
    /// assert_eq!(*abs_tol.as_ref(), 10.0);
    ///
    /// // 10% of |-50| = 5
    /// let abs_tol_neg = rel_tol.absolute_tolerance(-50.0);
    /// assert_eq!(*abs_tol_neg.as_ref(), 5.0);
    ///
    /// // 10% of 0 = 0
    /// let abs_tol_zero = rel_tol.absolute_tolerance(0.0);
    /// assert_eq!(*abs_tol_zero.as_ref(), 0.0);
    /// ```
    #[inline(always)]
    pub fn absolute_tolerance(&self, reference: RealType) -> AbsoluteTolerance<RealType> {
        let abs_tol = reference.abs() * &self.0;
        AbsoluteTolerance(abs_tol)
    }
}

impl<RealType: RealScalar> TryNew for RelativeTolerance<RealType> {
    type Error = ErrorsTolerance<RealType>;

    /// Attempts to create a [`RelativeTolerance`] from a value.
    ///
    /// # Errors
    ///
    /// Returns [`ErrorsTolerance::NegativeValue`] if the input is negative.
    ///
    /// # Panics (Debug Mode Only)
    ///
    /// In debug builds, panics if the input is not finite (NaN or infinity).
    fn try_new(value: RealType) -> Result<Self, Self::Error> {
        debug_assert!(value.is_finite(), "The input value {value} is not finite!");
        if value.kernel_is_sign_negative() {
            Err(ErrorsTolerance::NegativeValue {
                value,
                backtrace: capture_backtrace(),
            })
        } else {
            Ok(Self(value))
        }
    }
}

//------------------------------------------------------------------------------------------------------------
// PositiveRealScalar
//------------------------------------------------------------------------------------------------------------

/// Type-safe wrapper for strictly positive real scalar values.
///
/// [`PositiveRealScalar<T>`] guarantees that wrapped values are strictly greater than zero.
/// Zero is **not** valid for this type. For values that can be zero, use [`NonNegativeRealScalar`].
///
/// # Mathematical Definition
///
/// ```text
/// PositiveRealScalar<T> = { x ∈ T : x > 0 }
/// ```
///
/// This is the set of positive real numbers `ℝ⁺`, which **excludes** zero.
///
/// # Use Cases
///
/// - Lengths and distances that cannot be zero
/// - Positive tolerances
/// - Scaling factors that must be positive
/// - Any quantity that is mathematically required to be > 0
///
/// # Examples
///
/// ## Basic Usage
///
/// ```rust
/// use num_valid::scalars::{PositiveRealScalar, ErrorsPositiveRealScalar};
/// use try_create::TryNew;
///
/// // Valid positive values
/// let length = PositiveRealScalar::try_new(2.5_f64).unwrap();
/// let tiny = PositiveRealScalar::try_new(f64::MIN_POSITIVE).unwrap();
///
/// // Zero is NOT positive
/// assert!(matches!(
///     PositiveRealScalar::try_new(0.0_f64),
///     Err(ErrorsPositiveRealScalar::ZeroValue { .. })
/// ));
///
/// // Negative values rejected
/// assert!(matches!(
///     PositiveRealScalar::try_new(-1.0_f64),
///     Err(ErrorsPositiveRealScalar::NegativeValue { .. })
/// ));
/// ```
///
/// ## Difference from [`NonNegativeRealScalar`]
///
/// ```rust
/// use num_valid::scalars::{PositiveRealScalar, NonNegativeRealScalar};
/// use try_create::TryNew;
///
/// // Zero is INVALID for PositiveRealScalar (x > 0)
/// assert!(PositiveRealScalar::try_new(0.0_f64).is_err());
///
/// // Zero is VALID for NonNegativeRealScalar (x ≥ 0)
/// assert!(NonNegativeRealScalar::try_new(0.0_f64).is_ok());
/// ```
#[derive(
    Debug, Clone, PartialEq, PartialOrd, AsRef, IntoInner, Display, Serialize, Deserialize,
)]
#[repr(transparent)]
#[serde(bound(deserialize = "RealType: for<'a> Deserialize<'a>"))]
pub struct PositiveRealScalar<RealType: RealScalar>(RealType);

impl<RealType: RealScalar> TryNew for PositiveRealScalar<RealType> {
    type Error = ErrorsPositiveRealScalar<RealType>;

    /// Attempts to create a [`PositiveRealScalar`] from a value.
    ///
    /// # Errors
    ///
    /// - [`ErrorsPositiveRealScalar::NegativeValue`]: If the input is negative (< 0).
    /// - [`ErrorsPositiveRealScalar::ZeroValue`]: If the input is zero.
    ///
    /// # Panics (Debug Mode Only)
    ///
    /// In debug builds, panics if the input is not finite (NaN or infinity).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_valid::scalars::{PositiveRealScalar, ErrorsPositiveRealScalar};
    /// use try_create::TryNew;
    ///
    /// // Positive value succeeds
    /// assert!(PositiveRealScalar::try_new(1.0_f64).is_ok());
    ///
    /// // Zero fails
    /// assert!(matches!(
    ///     PositiveRealScalar::try_new(0.0_f64),
    ///     Err(ErrorsPositiveRealScalar::ZeroValue { .. })
    /// ));
    ///
    /// // Negative fails
    /// assert!(matches!(
    ///     PositiveRealScalar::try_new(-1.0_f64),
    ///     Err(ErrorsPositiveRealScalar::NegativeValue { value: v, .. }) if v == -1.0
    /// ));
    /// ```
    fn try_new(value: RealType) -> Result<Self, Self::Error> {
        debug_assert!(value.is_finite(), "The input value {value} is not finite!");
        if value.kernel_is_sign_negative() {
            Err(ErrorsPositiveRealScalar::NegativeValue {
                value,
                backtrace: capture_backtrace(),
            })
        } else if value.is_zero() {
            Err(ErrorsPositiveRealScalar::ZeroValue {
                backtrace: capture_backtrace(),
            })
        } else {
            Ok(Self(value))
        }
    }
}

//------------------------------------------------------------------------------------------------------------
// NonNegativeRealScalar
//------------------------------------------------------------------------------------------------------------

/// Type-safe wrapper for non-negative real scalar values.
///
/// [`NonNegativeRealScalar<T>`] guarantees that wrapped values are greater than or equal to zero.
/// Zero **is** valid for this type. For values that must be strictly positive, use [`PositiveRealScalar`].
///
/// # Mathematical Definition
///
/// ```text
/// NonNegativeRealScalar<T> = { x ∈ T : x ≥ 0 }
/// ```
///
/// This is the set of non-negative real numbers `ℝ₀⁺`, which **includes** zero.
///
/// # Use Cases
///
/// - Distances (can be zero when comparing a value to itself)
/// - Absolute values
/// - Magnitudes
/// - Any quantity that is mathematically required to be ≥ 0
///
/// # Examples
///
/// ## Basic Usage
///
/// ```rust
/// use num_valid::scalars::{NonNegativeRealScalar, ErrorsNonNegativeRealScalar};
/// use try_create::TryNew;
///
/// // Zero is valid
/// let zero = NonNegativeRealScalar::try_new(0.0_f64).unwrap();
/// assert_eq!(*zero.as_ref(), 0.0);
///
/// // Positive values are valid
/// let positive = NonNegativeRealScalar::try_new(5.0_f64).unwrap();
///
/// // Negative values are rejected
/// assert!(matches!(
///     NonNegativeRealScalar::try_new(-1.0_f64),
///     Err(ErrorsNonNegativeRealScalar::NegativeValue { .. })
/// ));
/// ```
///
/// ## Use Case: Computing Distances
///
/// ```rust
/// use num_valid::scalars::NonNegativeRealScalar;
/// use try_create::TryNew;
///
/// fn distance(a: f64, b: f64) -> NonNegativeRealScalar<f64> {
///     NonNegativeRealScalar::try_new((a - b).abs()).unwrap()
/// }
///
/// // Different points
/// let d1 = distance(0.0, 5.0);
/// assert_eq!(*d1.as_ref(), 5.0);
///
/// // Same point (zero distance is valid!)
/// let d2 = distance(3.0, 3.0);
/// assert_eq!(*d2.as_ref(), 0.0);
/// ```
#[derive(
    Debug, Clone, PartialEq, PartialOrd, AsRef, IntoInner, Display, Serialize, Deserialize,
)]
#[repr(transparent)]
#[serde(bound(deserialize = "RealType: for<'a> Deserialize<'a>"))]
pub struct NonNegativeRealScalar<RealType: RealScalar>(RealType);

impl<RealType: RealScalar> TryNew for NonNegativeRealScalar<RealType> {
    type Error = ErrorsNonNegativeRealScalar<RealType>;

    /// Attempts to create a [`NonNegativeRealScalar`] from a value.
    ///
    /// # Errors
    ///
    /// Returns [`ErrorsNonNegativeRealScalar::NegativeValue`] if the input is negative.
    ///
    /// # Panics (Debug Mode Only)
    ///
    /// In debug builds, panics if the input is not finite (NaN or infinity).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_valid::scalars::{NonNegativeRealScalar, ErrorsNonNegativeRealScalar};
    /// use try_create::TryNew;
    ///
    /// // Zero is valid
    /// assert!(NonNegativeRealScalar::try_new(0.0_f64).is_ok());
    ///
    /// // Positive is valid
    /// assert!(NonNegativeRealScalar::try_new(1.0_f64).is_ok());
    ///
    /// // Negative is rejected
    /// assert!(matches!(
    ///     NonNegativeRealScalar::try_new(-1.0_f64),
    ///     Err(ErrorsNonNegativeRealScalar::NegativeValue { .. })
    /// ));
    /// ```
    fn try_new(value: RealType) -> Result<Self, Self::Error> {
        debug_assert!(value.is_finite(), "The input value {value} is not finite!");
        if value.kernel_is_sign_negative() {
            Err(ErrorsNonNegativeRealScalar::NegativeValue {
                value,
                backtrace: capture_backtrace(),
            })
        } else {
            Ok(Self(value))
        }
    }
}

//------------------------------------------------------------------------------------------------------------
// Tests
//------------------------------------------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use crate::backends::native64::validated::RealNative64StrictFinite;

    mod absolute_tolerance {
        use super::*;

        #[test]
        fn try_new_valid() {
            let tol = AbsoluteTolerance::try_new(1e-10_f64).unwrap();
            assert_eq!(*tol.as_ref(), 1e-10);
        }

        #[test]
        fn try_new_zero() {
            let tol = AbsoluteTolerance::try_new(0.0_f64).unwrap();
            assert_eq!(*tol.as_ref(), 0.0);
        }

        #[test]
        fn try_new_negative() {
            let result = AbsoluteTolerance::try_new(-1e-10_f64);
            assert!(
                matches!(result, Err(ErrorsTolerance::NegativeValue { value, .. }) if value == -1e-10)
            );
        }

        #[test]
        fn zero_constructor() {
            let tol = AbsoluteTolerance::<f64>::zero();
            assert_eq!(*tol.as_ref(), 0.0);
        }

        #[test]
        fn epsilon_constructor() {
            let tol = AbsoluteTolerance::<f64>::epsilon();
            assert_eq!(*tol.as_ref(), f64::EPSILON);
        }

        #[test]
        fn display_trait() {
            let tol = AbsoluteTolerance::try_new(0.5_f64).unwrap();
            assert_eq!(format!("{}", tol), "0.5");
        }

        #[test]
        fn lower_exp_trait() {
            let tol = AbsoluteTolerance::try_new(0.00001_f64).unwrap();
            assert_eq!(format!("{:e}", tol), "1e-5");
        }

        #[test]
        fn into_inner() {
            let tol = AbsoluteTolerance::try_new(0.5_f64).unwrap();
            let inner = tol.into_inner();
            assert_eq!(inner, 0.5);
        }

        #[test]
        fn clone_and_partial_eq() {
            let tol1 = AbsoluteTolerance::try_new(1e-10_f64).unwrap();
            let tol2 = tol1.clone();
            assert_eq!(tol1, tol2);
        }

        #[test]
        fn partial_ord() {
            let tol1 = AbsoluteTolerance::try_new(1e-10_f64).unwrap();
            let tol2 = AbsoluteTolerance::try_new(1e-9_f64).unwrap();
            assert!(tol1 < tol2);
        }

        #[test]
        fn serialize_deserialize() {
            let tol = AbsoluteTolerance::try_new(0.5_f64).unwrap();
            let serialized = serde_json::to_string(&tol).unwrap();
            let deserialized: AbsoluteTolerance<f64> = serde_json::from_str(&serialized).unwrap();
            assert_eq!(tol, deserialized);
        }

        #[test]
        fn with_validated_type() {
            let val = RealNative64StrictFinite::try_from_f64(1e-10).unwrap();
            let tol = AbsoluteTolerance::try_new(val).unwrap();
            assert_eq!(*tol.as_ref().as_ref(), 1e-10);
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic(expected = "is not finite")]
        fn debug_panics_on_nan() {
            let _ = AbsoluteTolerance::try_new(f64::NAN);
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic(expected = "is not finite")]
        fn debug_panics_on_infinity() {
            let _ = AbsoluteTolerance::try_new(f64::INFINITY);
        }

        #[test]
        fn try_new() {
            // Test creating an AbsoluteTolerance instance with a value of 0.0
            let v = AbsoluteTolerance::<f64>::zero();
            assert_eq!(*v.as_ref(), 0.0);

            // Test creating an AbsoluteTolerance instance with a positive value
            let v = AbsoluteTolerance::try_new(2.0).unwrap();
            assert_eq!(*v.as_ref(), 2.0);
        }

        #[test]
        fn try_new_invalid_negative() {
            // Test creating an invalid AbsoluteTolerance instance with a negative value
            let tol = AbsoluteTolerance::try_new(-0.1);
            assert!(matches!(tol, Err(ErrorsTolerance::NegativeValue { .. })));
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic = "The input value inf is not finite!"]
        fn try_new_invalid_infinite() {
            // Test creating an invalid AbsoluteTolerance instance with an infinite value
            let _tol = AbsoluteTolerance::try_new(f64::INFINITY);
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic = "The input value NaN is not finite!"]
        fn try_new_invalid_nan() {
            // Test creating an invalid AbsoluteTolerance instance with a NaN value
            let _tol = AbsoluteTolerance::try_new(f64::NAN);
        }

        #[test]
        fn epsilon() {
            // Test creating an AbsoluteTolerance instance with epsilon value
            let epsilon_tol = AbsoluteTolerance::<f64>::epsilon();
            assert_eq!(*epsilon_tol.as_ref(), f64::EPSILON);
        }

        #[test]
        fn equality_operator() {
            // Test equality operator for AbsoluteTolerance instances
            let a = AbsoluteTolerance::<f64>::zero();
            let b = AbsoluteTolerance::<f64>::zero();
            assert!(a == b);

            let c = AbsoluteTolerance::try_new(1.0).unwrap();
            let d = AbsoluteTolerance::try_new(1.0).unwrap();
            assert!(c == d);
        }

        #[test]
        fn inequality_operator() {
            // Test inequality operator for AbsoluteTolerance instances
            let a = AbsoluteTolerance::<f64>::zero();
            let b = AbsoluteTolerance::try_new(1.0).unwrap();
            assert!(a != b);

            let c = AbsoluteTolerance::try_new(1.0).unwrap();
            let d = AbsoluteTolerance::try_new(2.0).unwrap();
            assert!(c != d);
        }

        #[test]
        fn debug_trait() {
            // Test the Debug trait
            let tolerance = AbsoluteTolerance::try_new(0.5).unwrap();
            assert_eq!(format!("{:?}", tolerance), "AbsoluteTolerance(0.5)");
        }

        #[test]
        fn clone_trait() {
            // Test the Clone trait
            let tolerance = AbsoluteTolerance::try_new(0.5).unwrap();
            let cloned_tolerance = tolerance.clone();
            assert_eq!(tolerance, cloned_tolerance);
        }

        #[test]
        fn partial_eq_trait() {
            // Test the PartialEq trait
            let tolerance1 = AbsoluteTolerance::try_new(0.5).unwrap();
            let tolerance2 = AbsoluteTolerance::try_new(0.5).unwrap();
            assert_eq!(tolerance1, tolerance2);
        }

        #[test]
        fn partial_ord_trait() {
            // Test the PartialOrd trait
            let tolerance1 = AbsoluteTolerance::try_new(0.5).unwrap();
            let tolerance2 = AbsoluteTolerance::try_new(1.0).unwrap();
            assert!(tolerance1 < tolerance2);
        }

        #[test]
        fn as_ref_trait() {
            // Test the AsRef trait
            let tolerance = AbsoluteTolerance::try_new(0.5).unwrap();
            let inner: &f64 = tolerance.as_ref();
            assert_eq!(*inner, 0.5);
        }

        #[test]
        fn zero() {
            // Test the zero constructor
            let zero_tol = AbsoluteTolerance::<f64>::zero();
            assert_eq!(*zero_tol.as_ref(), 0.0);
        }

        #[test]
        fn edge_cases() {
            // Test with very small positive values
            let tiny_tol = AbsoluteTolerance::try_new(f64::MIN_POSITIVE).unwrap();
            assert_eq!(*tiny_tol.as_ref(), f64::MIN_POSITIVE);

            // Test with large positive values
            let large_tol = AbsoluteTolerance::try_new(1e100).unwrap();
            assert_eq!(*large_tol.as_ref(), 1e100);
        }
    }

    mod relative_tolerance {
        use super::*;

        #[test]
        fn try_new_valid() {
            let tol = RelativeTolerance::try_new(0.01_f64).unwrap();
            assert_eq!(*tol.as_ref(), 0.01);
        }

        #[test]
        fn try_new_zero() {
            let tol = RelativeTolerance::try_new(0.0_f64).unwrap();
            assert_eq!(*tol.as_ref(), 0.0);
        }

        #[test]
        fn try_new_negative() {
            let result = RelativeTolerance::try_new(-0.01_f64);
            assert!(matches!(result, Err(ErrorsTolerance::NegativeValue { .. })));
        }

        #[test]
        fn zero_constructor() {
            let tol = RelativeTolerance::<f64>::zero();
            assert_eq!(*tol.as_ref(), 0.0);
        }

        #[test]
        fn epsilon_constructor() {
            let tol = RelativeTolerance::<f64>::epsilon();
            assert_eq!(*tol.as_ref(), f64::EPSILON);
        }

        #[test]
        fn absolute_tolerance_positive_reference() {
            let rel_tol = RelativeTolerance::try_new(0.1_f64).unwrap();
            let abs_tol = rel_tol.absolute_tolerance(100.0);
            assert_eq!(*abs_tol.as_ref(), 10.0);
        }

        #[test]
        fn absolute_tolerance_negative_reference() {
            let rel_tol = RelativeTolerance::try_new(0.1_f64).unwrap();
            let abs_tol = rel_tol.absolute_tolerance(-50.0);
            assert_eq!(*abs_tol.as_ref(), 5.0);
        }

        #[test]
        fn absolute_tolerance_zero_reference() {
            let rel_tol = RelativeTolerance::try_new(0.1_f64).unwrap();
            let abs_tol = rel_tol.absolute_tolerance(0.0);
            assert_eq!(*abs_tol.as_ref(), 0.0);
        }

        #[test]
        fn display_trait() {
            let tol = RelativeTolerance::try_new(0.5_f64).unwrap();
            assert_eq!(format!("{}", tol), "0.5");
        }

        #[test]
        fn into_inner() {
            let tol = RelativeTolerance::try_new(0.01_f64).unwrap();
            let inner = tol.into_inner();
            assert_eq!(inner, 0.01);
        }

        #[test]
        fn serialize_deserialize() {
            let tol = RelativeTolerance::try_new(0.01_f64).unwrap();
            let serialized = serde_json::to_string(&tol).unwrap();
            let deserialized: RelativeTolerance<f64> = serde_json::from_str(&serialized).unwrap();
            assert_eq!(tol, deserialized);
        }

        #[test]
        fn try_new() {
            // Test creating a RelativeTolerance instance with a value of 0.0
            let v = RelativeTolerance::<f64>::zero();
            assert_eq!(*v.as_ref(), 0.0);

            // Test creating a RelativeTolerance instance with a positive value
            let v = RelativeTolerance::try_new(2.0).unwrap();
            assert_eq!(*v.as_ref(), 2.0);
        }

        #[test]
        fn try_new_invalid_negative() {
            // Test creating an invalid RelativeTolerance instance with a negative value
            let tol = RelativeTolerance::try_new(-0.1);
            assert!(matches!(tol, Err(ErrorsTolerance::NegativeValue { .. })));
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic = "The input value inf is not finite!"]
        fn try_new_invalid_infinite() {
            // Test creating an invalid RelativeTolerance instance with an infinite value
            let _tol = RelativeTolerance::try_new(f64::INFINITY);
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic = "The input value NaN is not finite!"]
        fn try_new_invalid_nan() {
            // Test creating an invalid RelativeTolerance instance with a NaN value
            let _tol = RelativeTolerance::try_new(f64::NAN);
        }

        #[test]
        fn epsilon() {
            // Test creating a RelativeTolerance instance with epsilon value
            let epsilon_tol = RelativeTolerance::<f64>::epsilon();
            assert_eq!(*epsilon_tol.as_ref(), f64::EPSILON);
        }

        #[test]
        fn absolute_tolerance() {
            // Test converting relative tolerance to absolute tolerance
            let rel_tol = RelativeTolerance::try_new(0.1).unwrap();
            let reference = 10.0;
            let abs_tol = rel_tol.absolute_tolerance(reference);
            assert_eq!(*abs_tol.as_ref(), 1.0); // 0.1 * |10.0| = 1.0

            // Test with negative reference value
            let reference = -5.0;
            let abs_tol = rel_tol.absolute_tolerance(reference);
            assert_eq!(*abs_tol.as_ref(), 0.5); // 0.1 * |-5.0| = 0.5

            // Test with zero reference value
            let reference = 0.0;
            let abs_tol = rel_tol.absolute_tolerance(reference);
            assert_eq!(*abs_tol.as_ref(), 0.0); // 0.1 * |0.0| = 0.0
        }

        #[test]
        fn equality_operator() {
            // Test equality operator for RelativeTolerance instances
            let a = RelativeTolerance::<f64>::zero();
            let b = RelativeTolerance::<f64>::zero();
            assert!(a == b);

            let c = RelativeTolerance::try_new(1.0).unwrap();
            let d = RelativeTolerance::try_new(1.0).unwrap();
            assert!(c == d);
        }

        #[test]
        fn inequality_operator() {
            // Test inequality operator for RelativeTolerance instances
            let a = RelativeTolerance::<f64>::zero();
            let b = RelativeTolerance::try_new(1.0).unwrap();
            assert!(a != b);

            let c = RelativeTolerance::try_new(1.0).unwrap();
            let d = RelativeTolerance::try_new(2.0).unwrap();
            assert!(c != d);
        }

        #[test]
        fn debug_trait() {
            // Test the Debug trait
            let tolerance = RelativeTolerance::try_new(0.5).unwrap();
            assert_eq!(format!("{:?}", tolerance), "RelativeTolerance(0.5)");
        }

        #[test]
        fn clone_trait() {
            // Test the Clone trait
            let tolerance = RelativeTolerance::try_new(0.5).unwrap();
            let cloned_tolerance = tolerance.clone();
            assert_eq!(tolerance, cloned_tolerance);
        }

        #[test]
        fn partial_eq_trait() {
            // Test the PartialEq trait
            let tolerance1 = RelativeTolerance::try_new(0.5).unwrap();
            let tolerance2 = RelativeTolerance::try_new(0.5).unwrap();
            assert_eq!(tolerance1, tolerance2);
        }

        #[test]
        fn partial_ord_trait() {
            // Test the PartialOrd trait
            let tolerance1 = RelativeTolerance::try_new(0.5).unwrap();
            let tolerance2 = RelativeTolerance::try_new(1.0).unwrap();
            assert!(tolerance1 < tolerance2);
        }

        #[test]
        fn as_ref_trait() {
            // Test the AsRef trait
            let tolerance = RelativeTolerance::try_new(0.5).unwrap();
            let inner: &f64 = tolerance.as_ref();
            assert_eq!(*inner, 0.5);
        }

        #[test]
        fn lower_exp_trait() {
            // Test the LowerExp trait (scientific notation formatting)
            let tolerance = RelativeTolerance::try_new(0.00001).unwrap();
            assert_eq!(format!("{:e}", tolerance), "1e-5");
        }
    }

    mod positive_real_scalar {
        use super::*;
        use crate::backends::native64::validated::RealNative64StrictFiniteInDebug;

        #[test]
        fn try_new_positive() {
            let val = PositiveRealScalar::try_new(2.5_f64).unwrap();
            assert_eq!(*val.as_ref(), 2.5);
        }

        #[test]
        fn try_new_min_positive() {
            let val = PositiveRealScalar::try_new(f64::MIN_POSITIVE).unwrap();
            assert_eq!(*val.as_ref(), f64::MIN_POSITIVE);
        }

        #[test]
        fn try_new_zero_fails() {
            let result = PositiveRealScalar::try_new(0.0_f64);
            assert!(matches!(
                result,
                Err(ErrorsPositiveRealScalar::ZeroValue { .. })
            ));
        }

        #[test]
        fn try_new_negative_fails() {
            let result = PositiveRealScalar::try_new(-1.0_f64);
            assert!(
                matches!(result, Err(ErrorsPositiveRealScalar::NegativeValue { value, .. }) if value == -1.0)
            );
        }

        #[test]
        fn display_trait() {
            let val = PositiveRealScalar::try_new(1.618_f64).unwrap();
            assert_eq!(format!("{}", val), "1.618");
        }

        #[test]
        fn into_inner() {
            let val = PositiveRealScalar::try_new(42.0_f64).unwrap();
            let inner = val.into_inner();
            assert_eq!(inner, 42.0);
        }

        #[test]
        fn partial_ord() {
            let a = PositiveRealScalar::try_new(1.0_f64).unwrap();
            let b = PositiveRealScalar::try_new(2.0_f64).unwrap();
            assert!(a < b);
        }

        #[test]
        fn serialize_deserialize() {
            let val = PositiveRealScalar::try_new(3.0_f64).unwrap();
            let serialized = serde_json::to_string(&val).unwrap();
            let deserialized: PositiveRealScalar<f64> = serde_json::from_str(&serialized).unwrap();
            assert_eq!(val, deserialized);
        }

        #[test]
        fn with_validated_type() {
            let inner = RealNative64StrictFinite::try_from_f64(5.0).unwrap();
            let val = PositiveRealScalar::try_new(inner).unwrap();
            assert_eq!(*val.as_ref().as_ref(), 5.0);
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic(expected = "is not finite")]
        fn debug_panics_on_nan() {
            let _ = PositiveRealScalar::try_new(f64::NAN);
        }

        #[test]
        fn try_new() {
            // Test creating a PositiveRealScalar instance with a positive value
            let v = PositiveRealScalar::try_new(2.5).unwrap();
            assert_eq!(*v.as_ref(), 2.5);

            // Test creating a PositiveRealScalar instance with a very small positive value
            let v = PositiveRealScalar::try_new(f64::MIN_POSITIVE).unwrap();
            assert_eq!(*v.as_ref(), f64::MIN_POSITIVE);

            // Test creating a PositiveRealScalar instance with a large positive value
            let v = PositiveRealScalar::try_new(1e100).unwrap();
            assert_eq!(*v.as_ref(), 1e100);
        }

        #[test]
        fn try_new_invalid_negative() {
            // Test creating an invalid PositiveRealScalar instance with a negative value
            let scalar = PositiveRealScalar::try_new(-0.1);
            assert!(matches!(
                scalar,
                Err(ErrorsPositiveRealScalar::NegativeValue { .. })
            ));

            // Test with a negative value close to zero
            let scalar = PositiveRealScalar::try_new(-f64::EPSILON);
            assert!(matches!(
                scalar,
                Err(ErrorsPositiveRealScalar::NegativeValue { .. })
            ));
        }

        #[test]
        fn try_new_invalid_zero() {
            // Test creating an invalid PositiveRealScalar instance with zero
            let scalar = PositiveRealScalar::try_new(0.0);
            assert!(matches!(
                scalar,
                Err(ErrorsPositiveRealScalar::ZeroValue { .. })
            ));
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic = "The input value inf is not finite!"]
        fn try_new_invalid_infinite() {
            // Test creating an invalid PositiveRealScalar instance with an infinite value
            let _scalar = PositiveRealScalar::try_new(f64::INFINITY);
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic = "The input value -inf is not finite!"]
        fn try_new_invalid_negative_infinite() {
            // Test creating an invalid PositiveRealScalar instance with negative infinity
            let _scalar = PositiveRealScalar::try_new(f64::NEG_INFINITY);
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic = "The input value NaN is not finite!"]
        fn try_new_invalid_nan() {
            // Test creating an invalid PositiveRealScalar instance with a NaN value
            let _scalar = PositiveRealScalar::try_new(f64::NAN);
        }

        #[test]
        fn equality_operator() {
            // Test equality operator for PositiveRealScalar instances
            let a = PositiveRealScalar::try_new(1.5).unwrap();
            let b = PositiveRealScalar::try_new(1.5).unwrap();
            assert!(a == b);

            let c = PositiveRealScalar::try_new(3.1).unwrap();
            let d = PositiveRealScalar::try_new(3.1).unwrap();
            assert!(c == d);
        }

        #[test]
        fn inequality_operator() {
            // Test inequality operator for PositiveRealScalar instances
            let a = PositiveRealScalar::try_new(1.0).unwrap();
            let b = PositiveRealScalar::try_new(2.0).unwrap();
            assert!(a != b);

            let c = PositiveRealScalar::try_new(0.5).unwrap();
            let d = PositiveRealScalar::try_new(1.5).unwrap();
            assert!(c != d);
        }

        #[test]
        fn debug_trait() {
            // Test the Debug trait
            let scalar = PositiveRealScalar::try_new(2.7).unwrap();
            assert_eq!(format!("{:?}", scalar), "PositiveRealScalar(2.7)");
        }

        #[test]
        fn clone_trait() {
            // Test the Clone trait
            let scalar = PositiveRealScalar::try_new(1.414).unwrap();
            let cloned_scalar = scalar.clone();
            assert_eq!(scalar, cloned_scalar);
        }

        #[test]
        fn partial_eq_trait() {
            // Test the PartialEq trait
            let scalar1 = PositiveRealScalar::try_new(0.577).unwrap();
            let scalar2 = PositiveRealScalar::try_new(0.577).unwrap();
            assert_eq!(scalar1, scalar2);
        }

        #[test]
        fn partial_ord_trait() {
            // Test the PartialOrd trait
            let scalar1 = PositiveRealScalar::try_new(1.0).unwrap();
            let scalar2 = PositiveRealScalar::try_new(2.0).unwrap();
            assert!(scalar1 < scalar2);

            let scalar3 = PositiveRealScalar::try_new(3.0).unwrap();
            let scalar4 = PositiveRealScalar::try_new(3.0).unwrap();
            assert!(scalar3 <= scalar4);
            assert!(scalar4 >= scalar3);
        }

        #[test]
        fn as_ref_trait() {
            // Test the AsRef trait
            let scalar = PositiveRealScalar::try_new(2.0).unwrap();
            let inner: &f64 = scalar.as_ref();
            assert_eq!(*inner, 2.0);
        }

        #[test]
        fn edge_cases() {
            // Test with very small positive values
            let tiny_scalar = PositiveRealScalar::try_new(f64::MIN_POSITIVE).unwrap();
            assert_eq!(*tiny_scalar.as_ref(), f64::MIN_POSITIVE);

            // Test with large positive values
            let large_scalar = PositiveRealScalar::try_new(f64::MAX).unwrap();
            assert_eq!(*large_scalar.as_ref(), f64::MAX);

            // Test with epsilon
            let epsilon_scalar = PositiveRealScalar::try_new(f64::EPSILON).unwrap();
            assert_eq!(*epsilon_scalar.as_ref(), f64::EPSILON);
        }

        #[test]
        fn generic_scalar_types() {
            // Test with RealNative64StrictFiniteInDebug type
            let scalar =
                PositiveRealScalar::try_new(RealNative64StrictFiniteInDebug::try_new(5.0).unwrap())
                    .unwrap();
            assert_eq!(
                *scalar.as_ref(),
                RealNative64StrictFiniteInDebug::try_new(5.0).unwrap()
            );

            // Test error case with generic type
            let zero_value = RealNative64StrictFiniteInDebug::try_new(0.0).unwrap();
            let scalar_result = PositiveRealScalar::try_new(zero_value);
            assert!(matches!(
                scalar_result,
                Err(ErrorsPositiveRealScalar::ZeroValue { .. })
            ));
        }

        #[test]
        fn mathematical_operations() {
            // Test that the wrapped values behave correctly in mathematical contexts
            let scalar1 = PositiveRealScalar::try_new(2.0).unwrap();
            let scalar2 = PositiveRealScalar::try_new(3.0).unwrap();

            // Test comparison operations
            assert!(scalar1 < scalar2);
            assert!(scalar2 > scalar1);
            assert_eq!(
                scalar1.partial_cmp(&scalar2),
                Some(std::cmp::Ordering::Less)
            );
        }

        #[test]
        fn error_messages() {
            // Test that error messages are descriptive
            let negative_result = PositiveRealScalar::try_new(-1.0);
            match negative_result {
                Err(ErrorsPositiveRealScalar::NegativeValue { value, .. }) => {
                    assert_eq!(value, -1.0);
                }
                _ => panic!("Expected NegativeValue error"),
            }

            let zero_result = PositiveRealScalar::try_new(0.0);
            match zero_result {
                Err(ErrorsPositiveRealScalar::ZeroValue { .. }) => {
                    // Expected
                }
                _ => panic!("Expected ZeroValue error"),
            }
        }
    }

    mod non_negative_real_scalar {
        use super::*;
        use crate::backends::native64::validated::RealNative64StrictFiniteInDebug;

        #[test]
        fn try_new_negative_fails() {
            let result = NonNegativeRealScalar::try_new(-1.0_f64);
            assert!(
                matches!(result, Err(ErrorsNonNegativeRealScalar::NegativeValue { value, .. }) if value == -1.0)
            );
        }

        #[test]
        fn display_trait() {
            let val = NonNegativeRealScalar::try_new(2.7_f64).unwrap();
            assert_eq!(format!("{}", val), "2.7");

            let zero = NonNegativeRealScalar::try_new(0.0_f64).unwrap();
            assert_eq!(format!("{}", zero), "0");
        }

        #[test]
        fn partial_ord() {
            let zero = NonNegativeRealScalar::try_new(0.0_f64).unwrap();
            let positive = NonNegativeRealScalar::try_new(1.0_f64).unwrap();
            assert!(zero < positive);
        }

        #[test]
        fn serialize_deserialize() {
            let val = NonNegativeRealScalar::try_new(3.0_f64).unwrap();
            let serialized = serde_json::to_string(&val).unwrap();
            let deserialized: NonNegativeRealScalar<f64> =
                serde_json::from_str(&serialized).unwrap();
            assert_eq!(val, deserialized);
        }

        #[test]
        fn with_validated_type() {
            let inner = RealNative64StrictFinite::try_from_f64(0.0).unwrap();
            let val = NonNegativeRealScalar::try_new(inner).unwrap();
            assert_eq!(*val.as_ref().as_ref(), 0.0);
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic(expected = "is not finite")]
        fn debug_panics_on_nan() {
            let _ = NonNegativeRealScalar::try_new(f64::NAN);
        }

        #[test]
        fn try_new_positive() {
            // Test creating a NonNegativeRealScalar instance with positive values
            let v = NonNegativeRealScalar::try_new(2.5).unwrap();
            assert_eq!(*v.as_ref(), 2.5);

            // Test with very small positive value
            let v = NonNegativeRealScalar::try_new(f64::MIN_POSITIVE).unwrap();
            assert_eq!(*v.as_ref(), f64::MIN_POSITIVE);

            // Test with large positive value
            let v = NonNegativeRealScalar::try_new(1e100).unwrap();
            assert_eq!(*v.as_ref(), 1e100);
        }

        #[test]
        fn try_new_zero() {
            // Test creating a NonNegativeRealScalar instance with zero (VALID case)
            let v = NonNegativeRealScalar::try_new(0.0).unwrap();
            assert_eq!(*v.as_ref(), 0.0);

            // This is the key difference from PositiveRealScalar:
            // Zero is VALID for NonNegativeRealScalar (x ≥ 0)
            // but INVALID for PositiveRealScalar (x > 0)
        }

        #[test]
        fn try_new_invalid_negative() {
            // Test creating an invalid NonNegativeRealScalar instance with negative values
            let scalar = NonNegativeRealScalar::try_new(-0.1);
            assert!(matches!(
                scalar,
                Err(ErrorsNonNegativeRealScalar::NegativeValue { .. })
            ));

            // Test with negative value close to zero
            let scalar = NonNegativeRealScalar::try_new(-f64::EPSILON);
            assert!(matches!(
                scalar,
                Err(ErrorsNonNegativeRealScalar::NegativeValue { .. })
            ));

            // Test with large negative value
            let scalar = NonNegativeRealScalar::try_new(-100.0);
            assert!(matches!(
                scalar,
                Err(ErrorsNonNegativeRealScalar::NegativeValue { .. })
            ));
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic = "The input value inf is not finite!"]
        fn try_new_invalid_infinite() {
            // Test creating an invalid NonNegativeRealScalar instance with infinity
            let _scalar = NonNegativeRealScalar::try_new(f64::INFINITY);
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic = "The input value -inf is not finite!"]
        fn try_new_invalid_negative_infinite() {
            // Test creating an invalid NonNegativeRealScalar instance with negative infinity
            let _scalar = NonNegativeRealScalar::try_new(f64::NEG_INFINITY);
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic = "The input value NaN is not finite!"]
        fn try_new_invalid_nan() {
            // Test creating an invalid NonNegativeRealScalar instance with NaN
            let _scalar = NonNegativeRealScalar::try_new(f64::NAN);
        }

        #[test]
        fn equality_operator() {
            // Test equality operator for NonNegativeRealScalar instances
            let a = NonNegativeRealScalar::try_new(1.5).unwrap();
            let b = NonNegativeRealScalar::try_new(1.5).unwrap();
            assert!(a == b);

            let c = NonNegativeRealScalar::try_new(0.0).unwrap();
            let d = NonNegativeRealScalar::try_new(0.0).unwrap();
            assert!(c == d);
        }

        #[test]
        fn inequality_operator() {
            // Test inequality operator for NonNegativeRealScalar instances
            let a = NonNegativeRealScalar::try_new(0.0).unwrap();
            let b = NonNegativeRealScalar::try_new(1.0).unwrap();
            assert!(a != b);

            let c = NonNegativeRealScalar::try_new(0.5).unwrap();
            let d = NonNegativeRealScalar::try_new(1.5).unwrap();
            assert!(c != d);
        }

        #[test]
        fn debug_trait() {
            // Test the Debug trait
            let scalar = NonNegativeRealScalar::try_new(2.7).unwrap();
            assert_eq!(format!("{:?}", scalar), "NonNegativeRealScalar(2.7)");

            let zero = NonNegativeRealScalar::try_new(0.0).unwrap();
            assert_eq!(format!("{:?}", zero), "NonNegativeRealScalar(0.0)");
        }

        #[test]
        fn clone_trait() {
            // Test the Clone trait
            let scalar = NonNegativeRealScalar::try_new(1.414).unwrap();
            let cloned_scalar = scalar.clone();
            assert_eq!(scalar, cloned_scalar);
        }

        #[test]
        fn partial_eq_trait() {
            // Test the PartialEq trait
            let scalar1 = NonNegativeRealScalar::try_new(0.577).unwrap();
            let scalar2 = NonNegativeRealScalar::try_new(0.577).unwrap();
            assert_eq!(scalar1, scalar2);

            // Test with zero
            let zero1 = NonNegativeRealScalar::try_new(0.0).unwrap();
            let zero2 = NonNegativeRealScalar::try_new(0.0).unwrap();
            assert_eq!(zero1, zero2);
        }

        #[test]
        fn partial_ord_trait() {
            // Test the PartialOrd trait
            let scalar1 = NonNegativeRealScalar::try_new(0.0).unwrap();
            let scalar2 = NonNegativeRealScalar::try_new(1.0).unwrap();
            assert!(scalar1 < scalar2);

            let scalar3 = NonNegativeRealScalar::try_new(3.0).unwrap();
            let scalar4 = NonNegativeRealScalar::try_new(3.0).unwrap();
            assert!(scalar3 <= scalar4);
            assert!(scalar4 >= scalar3);

            // Test that zero is less than positive values
            let zero = NonNegativeRealScalar::try_new(0.0).unwrap();
            let positive = NonNegativeRealScalar::try_new(0.001).unwrap();
            assert!(zero < positive);
        }

        #[test]
        fn as_ref_trait() {
            // Test the AsRef trait
            let scalar = NonNegativeRealScalar::try_new(2.0).unwrap();
            let inner: &f64 = scalar.as_ref();
            assert_eq!(*inner, 2.0);

            let zero = NonNegativeRealScalar::try_new(0.0).unwrap();
            let inner: &f64 = zero.as_ref();
            assert_eq!(*inner, 0.0);
        }

        #[test]
        fn into_inner() {
            // Test converting a NonNegativeRealScalar instance into its inner value
            let scalar = NonNegativeRealScalar::try_new(42.0).unwrap();
            let inner = scalar.into_inner();
            assert_eq!(inner, 42.0);

            // Test with zero
            let zero = NonNegativeRealScalar::try_new(0.0).unwrap();
            let inner = zero.into_inner();
            assert_eq!(inner, 0.0);

            // Test with very small positive value
            let scalar = NonNegativeRealScalar::try_new(f64::MIN_POSITIVE).unwrap();
            let inner = scalar.into_inner();
            assert_eq!(inner, f64::MIN_POSITIVE);
        }

        #[test]
        fn edge_cases() {
            // Test with zero (key edge case)
            let zero_scalar = NonNegativeRealScalar::try_new(0.0).unwrap();
            assert_eq!(*zero_scalar.as_ref(), 0.0);

            // Test with very small positive values
            let tiny_scalar = NonNegativeRealScalar::try_new(f64::MIN_POSITIVE).unwrap();
            assert_eq!(*tiny_scalar.as_ref(), f64::MIN_POSITIVE);

            // Test with large positive values
            let large_scalar = NonNegativeRealScalar::try_new(f64::MAX).unwrap();
            assert_eq!(*large_scalar.as_ref(), f64::MAX);

            // Test with epsilon
            let epsilon_scalar = NonNegativeRealScalar::try_new(f64::EPSILON).unwrap();
            assert_eq!(*epsilon_scalar.as_ref(), f64::EPSILON);
        }

        #[test]
        fn generic_scalar_types() {
            // Test with RealNative64StrictFiniteInDebug type
            let scalar = NonNegativeRealScalar::try_new(
                RealNative64StrictFiniteInDebug::try_new(5.0).unwrap(),
            )
            .unwrap();
            assert_eq!(
                *scalar.as_ref(),
                RealNative64StrictFiniteInDebug::try_new(5.0).unwrap()
            );

            // Test with zero (valid for NonNegativeRealScalar)
            let zero_value = RealNative64StrictFiniteInDebug::try_new(0.0).unwrap();
            let scalar_result = NonNegativeRealScalar::try_new(zero_value);
            assert!(scalar_result.is_ok()); // Should succeed!

            // Test error case with generic type
            let negative_value = RealNative64StrictFiniteInDebug::try_new(-1.0).unwrap();
            let scalar_result = NonNegativeRealScalar::try_new(negative_value);
            assert!(matches!(
                scalar_result,
                Err(ErrorsNonNegativeRealScalar::NegativeValue { .. })
            ));
        }

        #[test]
        fn mathematical_operations() {
            // Test that the wrapped values behave correctly in mathematical contexts
            let scalar1 = NonNegativeRealScalar::try_new(0.0).unwrap();
            let scalar2 = NonNegativeRealScalar::try_new(2.0).unwrap();
            let scalar3 = NonNegativeRealScalar::try_new(3.0).unwrap();

            // Test comparison operations
            assert!(scalar1 < scalar2);
            assert!(scalar2 < scalar3);
            assert!(scalar3 > scalar1);
            assert_eq!(
                scalar1.partial_cmp(&scalar2),
                Some(std::cmp::Ordering::Less)
            );
            assert_eq!(
                scalar2.partial_cmp(&scalar1),
                Some(std::cmp::Ordering::Greater)
            );
        }

        #[test]
        fn error_messages() {
            // Test that error messages are descriptive
            let negative_result = NonNegativeRealScalar::try_new(-1.0);
            match negative_result {
                Err(ErrorsNonNegativeRealScalar::NegativeValue { value, .. }) => {
                    assert_eq!(value, -1.0);
                }
                _ => panic!("Expected NegativeValue error"),
            }

            let large_negative_result = NonNegativeRealScalar::try_new(-100.5);
            match large_negative_result {
                Err(ErrorsNonNegativeRealScalar::NegativeValue { value, .. }) => {
                    assert_eq!(value, -100.5);
                }
                _ => panic!("Expected NegativeValue error"),
            }
        }

        #[test]
        fn distinction_from_positive_real_scalar() {
            // Critical test: demonstrate the key difference between
            // NonNegativeRealScalar (x ≥ 0) and PositiveRealScalar (x > 0)

            // Zero is VALID for NonNegativeRealScalar
            let non_neg_zero = NonNegativeRealScalar::try_new(0.0);
            assert!(
                non_neg_zero.is_ok(),
                "Zero should be valid for NonNegativeRealScalar (x ≥ 0)"
            );

            // Zero is INVALID for PositiveRealScalar
            let pos_zero = PositiveRealScalar::try_new(0.0);
            assert!(
                pos_zero.is_err(),
                "Zero should be invalid for PositiveRealScalar (x > 0)"
            );
            assert!(matches!(
                pos_zero,
                Err(ErrorsPositiveRealScalar::ZeroValue { .. })
            ));

            // Positive values are valid for both
            let non_neg_positive = NonNegativeRealScalar::try_new(1.0);
            let pos_positive = PositiveRealScalar::try_new(1.0);
            assert!(non_neg_positive.is_ok());
            assert!(pos_positive.is_ok());

            // Negative values are invalid for both
            let non_neg_negative = NonNegativeRealScalar::try_new(-1.0);
            let pos_negative = PositiveRealScalar::try_new(-1.0);
            assert!(non_neg_negative.is_err());
            assert!(pos_negative.is_err());
        }

        #[test]
        fn use_case_distance() {
            // Real-world use case: computing distances (which can be zero)
            fn compute_distance(x1: f64, x2: f64) -> NonNegativeRealScalar<f64> {
                let diff = (x2 - x1).abs();
                NonNegativeRealScalar::try_new(diff).unwrap()
            }

            // Distance between different points
            let dist1 = compute_distance(0.0, 5.0);
            assert_eq!(*dist1.as_ref(), 5.0);

            // Distance from a point to itself (zero distance is valid!)
            let dist2 = compute_distance(3.0, 3.0);
            assert_eq!(*dist2.as_ref(), 0.0);
        }

        #[test]
        fn use_case_absolute_value() {
            // Real-world use case: absolute values (which can be zero)
            fn safe_abs(x: f64) -> NonNegativeRealScalar<f64> {
                NonNegativeRealScalar::try_new(x.abs()).unwrap()
            }

            assert_eq!(*safe_abs(-5.0).as_ref(), 5.0);
            assert_eq!(*safe_abs(0.0).as_ref(), 0.0); // Zero is valid!
            assert_eq!(*safe_abs(3.0).as_ref(), 3.0);
        }
    }

    mod distinction_tests {
        use super::*;

        #[test]
        fn positive_vs_non_negative_zero() {
            // This is the KEY difference between the two types

            // Zero is INVALID for PositiveRealScalar (x > 0)
            assert!(PositiveRealScalar::try_new(0.0_f64).is_err());

            // Zero is VALID for NonNegativeRealScalar (x ≥ 0)
            assert!(NonNegativeRealScalar::try_new(0.0_f64).is_ok());
        }

        #[test]
        fn both_accept_positive() {
            let positive = 1.0_f64;
            assert!(PositiveRealScalar::try_new(positive).is_ok());
            assert!(NonNegativeRealScalar::try_new(positive).is_ok());
        }

        #[test]
        fn both_reject_negative() {
            let negative = -1.0_f64;
            assert!(PositiveRealScalar::try_new(negative).is_err());
            assert!(NonNegativeRealScalar::try_new(negative).is_err());
        }
    }
}