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 five 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 |
//! | [`HashableScalar<T>`] | Finite | N/A | Hash-map and hash-set keys for real or complex scalars |
//!
//! [`AbsoluteTolerance<T>`], [`RelativeTolerance<T>`], [`PositiveRealScalar<T>`], and
//! [`NonNegativeRealScalar<T>`] are generic over [`RealScalar`], enabling consistent validation
//! across different numerical backends (native `f64`, arbitrary-precision `rug`, etc.).
//! [`HashableScalar<T>`] is generic over [`FpScalar`] and supports both real and complex scalars.
//!
//! ## Architectural Design
//!
//! - **Tolerance Types** ([`AbsoluteTolerance<T>`], [`RelativeTolerance<T>`]): Semantically specialized
//!   wrappers built on top of [`NonNegativeRealScalar<T>`]. They inherit all validation and provide
//!   tolerance-specific methods like [`RelativeTolerance::absolute_tolerance()`].
//! - **Constrained Scalar Types** ([`PositiveRealScalar<T>`], [`NonNegativeRealScalar<T>`]): Full-featured
//!   types with algebraic operations (addition, multiplication, powers), comparison traits, and immutable
//!   access patterns. They form the foundation for general mathematical computations.
//! - **Hashable Scalars** ([`HashableScalar<T>`]): Finite scalar wrappers that provide [`Eq`] and
//!   [`Hash`] for use as keys in [`std::collections::HashMap`] and members of
//!   [`std::collections::HashSet`].
//! - **Comparative Utilities**: The [`approximately_equal()`] function provides precise, tolerance-aware
//!   value comparisons across all scalar types.
//!
//! # 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::native::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(
//!     RealNative64StrictFinite::try_new(1e-10_f64).unwrap()
//! ).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::*};
//! use try_create::TryNew;
//! use std::assert_matches;
//!
//! // Negative tolerances are rejected
//! let invalid_tol = AbsoluteTolerance::try_new(
//!     RealNative64StrictFinite::try_new(-1e-6_f64).unwrap()
//! ).unwrap_err();
//! assert_matches!(invalid_tol, ErrorsNonNegativeRealScalar::NegativeValue { .. });
//!
//! // Zero is not positive
//! let invalid_pos = PositiveRealScalar::try_new(0.0_f64).unwrap_err();
//! assert_matches!(invalid_pos, ErrorsPositiveRealScalar::ZeroValue { .. });
//! ```
//!
//! # Error Handling
//!
//! Both [`AbsoluteTolerance<T>`] and [`RelativeTolerance<T>`] use [`ErrorsNonNegativeRealScalar`]
//! for error reporting, since they are wrappers around [`NonNegativeRealScalar<T>`]. This provides
//! consistent error semantics:
//!
//! - **No negative values:** Both types reject negative inputs
//! - **Debug validation:** NaN and infinity are panicked on in debug builds
//! - **Backtrace support:** When the `backtrace` feature is enabled
//!
//! # 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::*};
//! 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
//! 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_raw_scalar_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::*};
//! use try_create::TryNew;
//!
//! // Zero is valid for NonNegativeRealScalar
//! let zero = NonNegativeRealScalar::try_new(0.0_f64).unwrap();
//! assert_eq!(*zero.as_raw_scalar_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_raw_scalar_ref(), &0.0);
//! ```
//!
//! # Generic Programming with [`RealScalar`]
//!
//! All types work seamlessly with any scalar type implementing [`RealScalar`]:
//!
//! ```rust
//! use num_valid::{
//!     backends::native::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, approx::assert_abs_diff_eq};
//!
//! // 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_raw_scalar_ref());
//! ```

use crate::{
    FpScalar, Pow, RealScalar, ScalarCore,
    algorithms::accumulators::{NeumaierAddable, neumaier_sum_and_compensation_real},
    core::{errors::capture_backtrace, traits::raw::RawScalarTrait},
    functions::{Max, Min, PowIntExponentErrors},
};
use derive_more::{AsRef, Display, LowerExp};
use duplicate::duplicate_item;
use into_inner::IntoInner;
use num::{One, Zero};
use serde::{Deserialize, Serialize};
use std::{
    backtrace::Backtrace,
    hash::{Hash, Hasher},
    ops::{Add, AddAssign, Mul, MulAssign},
};
use thiserror::Error;
use try_create::TryNew;

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

/// 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} (valid value must be strictly positive, i.e., > 0)")]
    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 (valid value must be strictly positive, i.e., > 0)")]
    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 detected: {value} (valid 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.
///
/// # Implementation
///
/// This type is a `#[repr(transparent)]` wrapper around [`NonNegativeRealScalar<T>`].
/// All validation is performed by the underlying `NonNegativeRealScalar`, and errors
/// are reported as [`ErrorsNonNegativeRealScalar`].
///
/// # 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};
///
/// // Create from f64
/// let tol = AbsoluteTolerance::try_new(1e-10_f64).unwrap();
/// assert_eq!(tol.as_raw_scalar_ref(), &1e-10);
///
/// // Use convenience constructors
/// let zero = AbsoluteTolerance::<f64>::zero();
/// let eps = AbsoluteTolerance::<f64>::epsilon();
/// ```
///
/// ## In Numerical Comparisons
///
/// ```rust
/// use num_valid::{*, scalars::*};
/// use try_create::{IntoInner, TryNew};
///
/// 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.
// `AsRef`/`IntoInner` expose the wrapped `NonNegativeRealScalar<RealType>` as-is; use
// `as_raw_scalar_ref()`/`into_raw_scalar()` to unwrap all the way down to the raw primitive.
#[derive(
    Debug, Clone, PartialEq, PartialOrd, AsRef, IntoInner, Display, LowerExp, Serialize, Deserialize,
)]
#[serde(bound(deserialize = "RealType: for<'a> Deserialize<'a>"))]
#[repr(transparent)]
pub struct AbsoluteTolerance<RealType: RealScalar>(NonNegativeRealScalar<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_raw_scalar_ref(), &0.0);
    /// ```
    #[inline(always)]
    pub fn zero() -> Self {
        AbsoluteTolerance(NonNegativeRealScalar::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_raw_scalar_ref(), &f64::EPSILON);
    /// ```
    #[inline(always)]
    pub fn epsilon() -> Self {
        AbsoluteTolerance(NonNegativeRealScalar(RealType::epsilon()))
    }

    /// Wraps a [`NonNegativeRealScalar<T>`] as an [`AbsoluteTolerance<T>`].
    ///
    /// This constructor allows explicit conversion from a validated non-negative scalar
    /// to a tolerance type, providing semantic clarity.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_valid::{*, scalars::*};
    /// use try_create::TryNew;
    ///
    /// let non_neg = NonNegativeRealScalar::try_new(1e-10_f64).unwrap();
    /// let tol = AbsoluteTolerance::new(non_neg);
    /// assert_eq!(tol.as_raw_scalar_ref(), &1e-10);
    /// ```
    pub fn new(value: NonNegativeRealScalar<RealType>) -> Self {
        AbsoluteTolerance(value)
    }

    /// Attempts to create a [`AbsoluteTolerance`] 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).
    pub fn try_new(value: RealType) -> Result<Self, ErrorsNonNegativeRealScalar<RealType>> {
        NonNegativeRealScalar::try_new(value).map(AbsoluteTolerance)
    }
}

impl<RealType: RealScalar> ScalarCore for AbsoluteTolerance<RealType> {
    type RawScalarType = RealType::RawScalarType;

    #[inline(always)]
    fn as_raw_scalar_ref(&self) -> &Self::RawScalarType {
        self.0.as_raw_scalar_ref()
    }

    fn into_raw_scalar(self) -> Self::RawScalarType {
        self.0.into_raw_scalar()
    }
}

/// Compares two scalar values within an absolute tolerance.
///
/// Tests whether the absolute difference between two values is less than or equal to
/// a specified tolerance. This is the standard approach for approximate floating-point
/// comparisons when the expected magnitude of values is known.
///
/// # Mathematical Definition
///
/// Returns `true` if and only if:
/// ```text
/// |a - b| ≤ tolerance
/// ```
///
/// # Symmetry
///
/// The comparison is symmetric: `approximately_equal(a, b, tol) == approximately_equal(b, a, tol)`
///
/// # Type Parameters
///
/// - `T`: Any scalar type implementing [`RealScalar`]
///
/// # Arguments
///
/// - `a`: First value
/// - `b`: Second value to compare with
/// - `tolerance`: The maximum allowed absolute difference (must be non-negative)
///
/// # Examples
///
/// ## Basic Floating-Point Comparison
///
/// ```rust
/// use num_valid::scalars::{AbsoluteTolerance, approximately_equal};
/// use try_create::TryNew;
///
/// let tol = AbsoluteTolerance::try_new(1e-10_f64).unwrap();
///
/// // Values within tolerance
/// assert!(approximately_equal(1.0, 1.0 + 1e-11, &tol));
///
/// // Values outside tolerance
/// assert!(!approximately_equal(1.0, 1.0 + 1e-9, &tol));
///
/// // Exact match
/// assert!(approximately_equal(1.0, 1.0, &tol));
/// ```
///
/// ## Zero Tolerance (Exact Comparison)
///
/// ```rust
/// use num_valid::scalars::{AbsoluteTolerance, approximately_equal};
///
/// let exact_tol = AbsoluteTolerance::<f64>::zero();
///
/// // Only exact matches pass
/// assert!(approximately_equal(1.0, 1.0, &exact_tol));
/// assert!(!approximately_equal(1.0, 1.0 + 1e-15, &exact_tol));
/// ```
///
/// ## Negative Values
///
/// ```rust
/// use num_valid::scalars::{AbsoluteTolerance, approximately_equal};
/// use try_create::TryNew;
///
/// let tol = AbsoluteTolerance::try_new(0.1_f64).unwrap();
///
/// // Works with negative values
/// assert!(approximately_equal(-5.0, -5.05, &tol));
/// assert!(!approximately_equal(-5.0, -5.2, &tol));
/// ```
///
/// # When to Use
///
/// - **Use `approximately_equal()`** when you have a fixed maximum allowable error (absolute tolerance)
/// - **Use [`RelativeTolerance::absolute_tolerance()`]** when the tolerance is proportional to values
///
/// # See Also
///
/// - [`AbsoluteTolerance`] for creating and managing absolute tolerances
/// - [`RelativeTolerance`] for proportional error bounds
pub fn approximately_equal<T: RealScalar>(a: T, b: T, tolerance: &AbsoluteTolerance<T>) -> bool {
    let diff = (a - b).abs();
    &diff <= tolerance.as_ref()
}

//------------------------------------------------------------------------------------------------------------
// 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.
///
/// # Implementation
///
/// This type is a `#[repr(transparent)]` wrapper around [`NonNegativeRealScalar<T>`].
/// All validation is performed by the underlying `NonNegativeRealScalar`, and errors
/// are reported as [`ErrorsNonNegativeRealScalar`].
///
/// # 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_raw_scalar_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_raw_scalar_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_raw_scalar_ref(), 5.0); // 1% of |-500| = 5
/// ```
// `AsRef`/`IntoInner` expose the wrapped `NonNegativeRealScalar<RealType>` as-is; use
// `as_raw_scalar_ref()`/`into_raw_scalar()` to unwrap all the way down to the raw primitive.
#[derive(
    Debug, Clone, PartialEq, PartialOrd, AsRef, IntoInner, Display, LowerExp, Serialize, Deserialize,
)]
#[serde(bound(deserialize = "RealType: for<'a> Deserialize<'a>"))]
#[repr(transparent)]
pub struct RelativeTolerance<RealType: RealScalar>(NonNegativeRealScalar<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_raw_scalar_ref(), &0.0);
    /// ```
    #[inline(always)]
    pub fn zero() -> Self {
        RelativeTolerance(NonNegativeRealScalar::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_raw_scalar_ref(), &f64::EPSILON);
    /// ```
    #[inline(always)]
    pub fn epsilon() -> Self {
        RelativeTolerance(NonNegativeRealScalar(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_raw_scalar_ref(), 10.0);
    ///
    /// // 10% of |-50| = 5
    /// let abs_tol_neg = rel_tol.absolute_tolerance(-50.0);
    /// assert_eq!(*abs_tol_neg.as_raw_scalar_ref(), 5.0);
    ///
    /// // 10% of 0 = 0
    /// let abs_tol_zero = rel_tol.absolute_tolerance(0.0);
    /// assert_eq!(*abs_tol_zero.as_raw_scalar_ref(), 0.0);
    /// ```
    #[inline(always)]
    pub fn absolute_tolerance(&self, reference: RealType) -> AbsoluteTolerance<RealType> {
        let abs_tol = reference.abs() * &self.0;
        AbsoluteTolerance(abs_tol)
    }

    /// Wraps a [`NonNegativeRealScalar<T>`] as a [`RelativeTolerance<T>`].
    ///
    /// This constructor allows explicit conversion from a validated non-negative scalar
    /// to a tolerance type, providing semantic clarity.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_valid::{*, scalars::*};
    /// use try_create::TryNew;
    ///
    /// let non_neg = NonNegativeRealScalar::try_new(0.01_f64).unwrap(); // 1%
    /// let tol = RelativeTolerance::new(non_neg);
    /// assert_eq!(tol.as_raw_scalar_ref(), &0.01);
    /// ```
    pub fn new(value: NonNegativeRealScalar<RealType>) -> Self {
        RelativeTolerance(value)
    }

    /// Attempts to create a [`RelativeTolerance`] 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).
    pub fn try_new(value: RealType) -> Result<Self, ErrorsNonNegativeRealScalar<RealType>> {
        NonNegativeRealScalar::try_new(value).map(RelativeTolerance)
    }
}

impl<RealType: RealScalar> ScalarCore for RelativeTolerance<RealType> {
    type RawScalarType = RealType::RawScalarType;

    #[inline(always)]
    fn as_raw_scalar_ref(&self) -> &Self::RawScalarType {
        self.0.as_raw_scalar_ref()
    }

    fn into_raw_scalar(self) -> Self::RawScalarType {
        self.0.into_raw_scalar()
    }
}

//------------------------------------------------------------------------------------------------------------
// 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());
/// ```
///
/// ## Algebraic and Ordering Operations
///
/// [`PositiveRealScalar`] supports:
/// - **Addition**: Sum of positive values is positive
/// - **Multiplication**: Product of positive values is positive  
/// - **Integer powers**: Raising positive to any integer exponent yields positive
/// - **Square root**: Preserves positivity (√x > 0 if x > 0)
/// - **Multiplicative identity** ([`One`]): For neutral multiplication operations
/// - **Comparison** ([`Max`], [`Min`]): Ordering and selection helpers
///
/// ```rust
/// use num::One;
/// use num_valid::{
///     *,
///     functions::{Max, Min, Pow},
///     scalars::PositiveRealScalar,
/// };
/// use try_create::{IntoInner, TryNew};
///
/// let a = PositiveRealScalar::try_new(2.0_f64).unwrap();
/// let b = PositiveRealScalar::try_new(3.0_f64).unwrap();
///
/// // Add preserves positivity for valid operands.
/// let sum = a.clone() + b.clone();
/// assert_eq!(*sum.as_raw_scalar_ref(), 5.0);
///
/// // Multiply preserves positivity
/// let product = a.clone() * b.clone();
/// assert_eq!(*product.as_raw_scalar_ref(), 6.0);
///
/// // Integer powers preserve positivity
/// let squared = a.clone().pow(2u32);
/// assert_eq!(*squared.as_raw_scalar_ref(), 4.0);
///
/// // Square root preserves positivity
/// let sqrt = PositiveRealScalar::try_new(4.0_f64).unwrap().sqrt();
/// assert_eq!(*sqrt.as_raw_scalar_ref(), 2.0);
///
/// // One is the multiplicative identity.
/// let one = PositiveRealScalar::<f64>::one();
/// let result = a.clone() * one;
/// assert_eq!(*result.as_raw_scalar_ref(), 2.0);
///
/// let x = PositiveRealScalar::try_new(1.0_f64).unwrap();
/// let y = PositiveRealScalar::try_new(3.0_f64).unwrap();
/// assert_eq!(*Max::max_by_ref(&x, &y).as_raw_scalar_ref(), 3.0);
/// assert_eq!(*Min::min_by_value(x, y).as_raw_scalar_ref(), 1.0);
/// ```
// `AsRef`/`IntoInner` expose the wrapped `RealType` (still a validated scalar); use
// `as_raw_scalar_ref()`/`into_raw_scalar()` to unwrap all the way down to the raw primitive.
#[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> PositiveRealScalar<RealType> {
    /// Computes the square root of this positive scalar.
    ///
    /// Since the input is guaranteed to be positive, the result is always defined
    /// and remains positive.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_valid::{*, scalars::PositiveRealScalar};
    /// use try_create::TryNew;
    ///
    /// let value = PositiveRealScalar::try_new(4.0_f64).unwrap();
    /// let sqrt = value.sqrt();
    /// assert_eq!(sqrt.as_raw_scalar_ref(), &2.0);
    /// ```
    pub fn sqrt(self) -> Self {
        PositiveRealScalar(self.0.sqrt())
    }

    #[inline(always)]
    pub fn new(value: RealType) -> Self {
        #[cfg(debug_assertions)]
        {
            Self::try_new(value)
                .expect("Error in the creation of the positive real scalar in debug mode")
        }
        #[cfg(not(debug_assertions))]
        {
            Self(value)
        }
    }
}

impl<RealType: RealScalar> ScalarCore for PositiveRealScalar<RealType> {
    type RawScalarType = RealType::RawScalarType;

    #[inline(always)]
    fn as_raw_scalar_ref(&self) -> &Self::RawScalarType {
        self.0.as_raw_scalar_ref()
    }

    fn into_raw_scalar(self) -> Self::RawScalarType {
        self.0.into_raw_scalar()
    }
}

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))
        }
    }
}

/// Implements additive composition for [`PositiveRealScalar`].
///
/// Since both operands are guaranteed to be positive, their sum is also positive.
impl<RealType: RealScalar> Add for PositiveRealScalar<RealType> {
    type Output = Self;

    fn add(self, other: Self) -> Self {
        PositiveRealScalar(self.0 + other.0)
    }
}

/// Implements multiplicative composition for [`PositiveRealScalar`].
///
/// Since both operands are guaranteed to be positive, their product is also positive.
impl<RealType: RealScalar> Mul for PositiveRealScalar<RealType> {
    type Output = Self;

    fn mul(self, other: Self) -> Self {
        PositiveRealScalar(self.0 * other.0)
    }
}

/// Implements reference-based addition for [`PositiveRealScalar`].
///
/// This allows adding a reference to a positive scalar without consuming it.
/// Since both operands are guaranteed to be positive, their sum is also positive.
impl<'a, RealType: RealScalar> Add<&'a PositiveRealScalar<RealType>>
    for PositiveRealScalar<RealType>
{
    type Output = PositiveRealScalar<RealType>;

    fn add(self, other: &'a PositiveRealScalar<RealType>) -> PositiveRealScalar<RealType> {
        PositiveRealScalar(self.0 + other.0.clone())
    }
}

/// Implements reference-based multiplication for [`PositiveRealScalar`].
///
/// This allows multiplying a positive scalar by a reference to another positive scalar
/// without consuming it. Since both operands are guaranteed to be positive, their product is also positive.
impl<'a, RealType: RealScalar> Mul<&'a PositiveRealScalar<RealType>>
    for PositiveRealScalar<RealType>
{
    type Output = PositiveRealScalar<RealType>;

    fn mul(self, other: &'a PositiveRealScalar<RealType>) -> PositiveRealScalar<RealType> {
        PositiveRealScalar(self.0 * other.0.clone())
    }
}

/// Implements in-place reference-based addition for [`PositiveRealScalar`].
///
/// This allows adding a reference to a positive scalar to `self` without consuming `self`.
impl<'a, RealType: RealScalar> AddAssign<&'a PositiveRealScalar<RealType>>
    for PositiveRealScalar<RealType>
{
    fn add_assign(&mut self, other: &'a PositiveRealScalar<RealType>) {
        self.0 += &other.0;
    }
}

/// Implements in-place addition for [`PositiveRealScalar`] by value.
///
/// This allows adding a positive scalar value to `self`.
impl<RealType: RealScalar> AddAssign<PositiveRealScalar<RealType>>
    for PositiveRealScalar<RealType>
{
    fn add_assign(&mut self, other: PositiveRealScalar<RealType>) {
        self.0 += other.0;
    }
}

/// Implements in-place reference-based multiplication for [`PositiveRealScalar`].
///
/// This allows multiplying `self` by a reference to another positive scalar without consuming `self`.
impl<'a, RealType: RealScalar> MulAssign<&'a PositiveRealScalar<RealType>>
    for PositiveRealScalar<RealType>
{
    fn mul_assign(&mut self, other: &'a PositiveRealScalar<RealType>) {
        self.0 *= &other.0;
    }
}

/// Implements in-place multiplication for [`PositiveRealScalar`] by value.
///
/// This allows multiplying `self` by a positive scalar value.
impl<RealType: RealScalar> MulAssign<PositiveRealScalar<RealType>>
    for PositiveRealScalar<RealType>
{
    fn mul_assign(&mut self, other: PositiveRealScalar<RealType>) {
        self.0 *= other.0;
    }
}

impl<RealType: RealScalar> One for PositiveRealScalar<RealType> {
    fn one() -> Self {
        PositiveRealScalar(RealType::one())
    }
}

#[duplicate_item(
    exponent_type;
    [u8];
    [i8];
    [u16];
    [i16];
    [u32];
    [i32];
    [u64];
    [i64];
    [u128];
    [i128];
    [usize];
    [isize];
)]
impl<RealType: RealScalar> Pow<exponent_type> for PositiveRealScalar<RealType> {
    type Error = PowIntExponentErrors<<RealType as IntoInner>::InnerType, exponent_type>;

    fn try_pow(self, exponent: exponent_type) -> Result<Self, Self::Error> {
        self.0.try_pow(exponent).map(PositiveRealScalar)
    }

    #[inline(always)]
    /// Raises the number `self` to the power `exponent`.
    fn pow(self, exponent: exponent_type) -> Self {
        #[cfg(debug_assertions)]
        {
            self.try_pow(exponent).unwrap()
        }
        #[cfg(not(debug_assertions))]
        {
            PositiveRealScalar(self.0.pow(exponent))
        }
    }
}

/// Implements [`Max`] for [`PositiveRealScalar`].
///
/// Maximum selection is delegated to the default trait behavior based on [`PartialOrd`].
impl<RealType: RealScalar> Max for PositiveRealScalar<RealType> {}
/// Implements [`Min`] for [`PositiveRealScalar`].
///
/// Minimum selection is delegated to the default trait behavior based on [`PartialOrd`].
impl<RealType: RealScalar> Min for PositiveRealScalar<RealType> {}

/// Implements Neumaier compensated summation for [`PositiveRealScalar`].
///
/// This implementation delegates to the underlying real scalar type's Neumaier
/// compensated sum operation, preserving numerical stability for sums of positive values.
impl<RealType: RealScalar> NeumaierAddable for PositiveRealScalar<RealType> {
    #[inline(always)]
    fn neumaier_compensated_sum(value: Self, sum: &mut Self, compensation: &mut Self) {
        neumaier_sum_and_compensation_real(value.into_inner(), &mut sum.0, &mut compensation.0)
    }
}

//------------------------------------------------------------------------------------------------------------
// 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::*};
/// use try_create::TryNew;
///
/// // Zero is valid
/// let zero = NonNegativeRealScalar::try_new(0.0_f64).unwrap();
/// assert_eq!(zero.as_raw_scalar_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_raw_scalar_ref(), 5.0);
///
/// // Same point (zero distance is valid!)
/// let d2 = distance(3.0, 3.0);
/// assert_eq!(d2.as_raw_scalar_ref(), &0.0);
/// ```
///
/// ## Algebraic and Ordering Operations
///
/// [`NonNegativeRealScalar`] supports:
/// - **Addition**: Sum of non-negative values is non-negative
/// - **Multiplication**: Product of non-negative values is non-negative  
/// - **Integer powers**: Raising non-negative to any integer exponent yields non-negative
/// - **Additive identity** ([`Zero`]): For neutral addition operations
/// - **Multiplicative identity** ([`One`]): For neutral multiplication operations
/// - **Comparison** ([`Max`], [`Min`]): Ordering and selection helpers
///
/// ```rust
/// use num::{One, Zero};
/// use num_valid::{
///     *,
///     functions::{Max, Min, Pow},
///     scalars::NonNegativeRealScalar,
/// };
/// use try_create::TryNew;
///
/// let a = NonNegativeRealScalar::try_new(1.25_f64).unwrap();
/// let b = NonNegativeRealScalar::try_new(2.75_f64).unwrap();
///
/// // Add preserves non-negativity for valid operands.
/// let sum = a.clone() + &b;
/// assert_eq!(*sum.as_raw_scalar_ref(), 4.0);
///
/// // Multiply preserves non-negativity
/// let product = a * b;
/// assert!(*product.as_raw_scalar_ref() > 0.0);
///
/// // Integer powers preserve non-negativity
/// let base = NonNegativeRealScalar::try_new(2.0_f64).unwrap();
/// let squared = base.clone().pow(2u32);
/// assert_eq!(*squared.as_raw_scalar_ref(), 4.0);
///
/// // Zero is the additive identity.
/// let z = NonNegativeRealScalar::<f64>::zero();
/// assert!(z.is_zero());
/// assert_eq!(*(sum + z).as_raw_scalar_ref(), 4.0);
///
/// // One is the multiplicative identity.
/// let one = NonNegativeRealScalar::<f64>::one();
/// let result = base.clone() * one;
/// assert_eq!(*result.as_raw_scalar_ref(), 2.0);
///
/// let x = NonNegativeRealScalar::try_new(1.0_f64).unwrap();
/// let y = NonNegativeRealScalar::try_new(3.0_f64).unwrap();
/// assert_eq!(*Max::max_by_ref(&x, &y).as_raw_scalar_ref(), 3.0);
/// assert_eq!(*Min::min_by_value(x, y).as_raw_scalar_ref(), 1.0);
/// ```
// `AsRef`/`IntoInner` expose the wrapped `RealType` (still a validated scalar); use
// `as_raw_scalar_ref()`/`into_raw_scalar()` to unwrap all the way down to the raw primitive.
#[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> NonNegativeRealScalar<RealType> {
    /// Computes the square root of this non-negative scalar.
    ///
    /// Since the input is guaranteed to be non-negative, the result is always defined
    /// and remains non-negative.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_valid::{*, scalars::NonNegativeRealScalar};
    /// use try_create::TryNew;
    ///
    /// let value = NonNegativeRealScalar::try_new(4.0_f64).unwrap();
    /// let sqrt = value.sqrt();
    /// assert_eq!(sqrt.as_raw_scalar_ref(), &2.0);
    /// ```
    pub fn sqrt(self) -> Self {
        NonNegativeRealScalar(self.0.sqrt())
    }

    #[inline(always)]
    pub fn new(value: RealType) -> Self {
        #[cfg(debug_assertions)]
        {
            Self::try_new(value)
                .expect("Error in the creation of the non-negative real scalar in debug mode")
        }
        #[cfg(not(debug_assertions))]
        {
            Self(value)
        }
    }
}

impl<RealType: RealScalar> ScalarCore for NonNegativeRealScalar<RealType> {
    type RawScalarType = RealType::RawScalarType;

    #[inline(always)]
    fn as_raw_scalar_ref(&self) -> &Self::RawScalarType {
        self.0.as_raw_scalar_ref()
    }

    fn into_raw_scalar(self) -> Self::RawScalarType {
        self.0.into_raw_scalar()
    }
}

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))
        }
    }
}

/// Implements additive composition for [`NonNegativeRealScalar`].
///
/// Since both operands are guaranteed to be non-negative, their sum is also non-negative.
impl<RealType: RealScalar> Add for NonNegativeRealScalar<RealType> {
    type Output = Self;

    fn add(self, other: Self) -> Self {
        NonNegativeRealScalar(self.0 + other.0)
    }
}

/// Implements multiplicative composition for [`NonNegativeRealScalar`].
///
/// Since both operands are guaranteed to be non-negative, their product is also non-negative.
impl<RealType: RealScalar> Mul for NonNegativeRealScalar<RealType> {
    type Output = Self;

    fn mul(self, other: Self) -> Self {
        NonNegativeRealScalar(self.0 * other.0)
    }
}

/// Implements reference-based addition for [`NonNegativeRealScalar`].
///
/// This allows adding a reference to a non-negative scalar without consuming it.
/// Since both operands are guaranteed to be non-negative, their sum is also non-negative.
impl<'a, RealType: RealScalar> Add<&'a NonNegativeRealScalar<RealType>>
    for NonNegativeRealScalar<RealType>
{
    type Output = NonNegativeRealScalar<RealType>;

    fn add(self, other: &'a NonNegativeRealScalar<RealType>) -> NonNegativeRealScalar<RealType> {
        NonNegativeRealScalar(self.0 + other.0.clone())
    }
}

/// Implements reference-based multiplication for [`NonNegativeRealScalar`].
///
/// This allows multiplying a non-negative scalar by a reference to another non-negative scalar
/// without consuming it. Since both operands are guaranteed to be non-negative, their product is also non-negative.
impl<'a, RealType: RealScalar> Mul<&'a NonNegativeRealScalar<RealType>>
    for NonNegativeRealScalar<RealType>
{
    type Output = NonNegativeRealScalar<RealType>;

    fn mul(self, other: &'a NonNegativeRealScalar<RealType>) -> NonNegativeRealScalar<RealType> {
        NonNegativeRealScalar(self.0 * other.0.clone())
    }
}

/// Implements in-place reference-based addition for [`NonNegativeRealScalar`].
///
/// This allows adding a reference to a non-negative scalar to `self` without consuming `self`.
impl<'a, RealType: RealScalar> AddAssign<&'a NonNegativeRealScalar<RealType>>
    for NonNegativeRealScalar<RealType>
{
    fn add_assign(&mut self, other: &'a NonNegativeRealScalar<RealType>) {
        self.0 += &other.0;
    }
}

/// Implements in-place addition for [`NonNegativeRealScalar`] by value.
///
/// This allows adding a non-negative scalar value to `self`.
impl<RealType: RealScalar> AddAssign<NonNegativeRealScalar<RealType>>
    for NonNegativeRealScalar<RealType>
{
    fn add_assign(&mut self, other: NonNegativeRealScalar<RealType>) {
        self.0 += other.0;
    }
}

/// Implements in-place reference-based multiplication for [`NonNegativeRealScalar`].
///
/// This allows multiplying `self` by a reference to another non-negative scalar without consuming `self`.
impl<'a, RealType: RealScalar> MulAssign<&'a NonNegativeRealScalar<RealType>>
    for NonNegativeRealScalar<RealType>
{
    fn mul_assign(&mut self, other: &'a NonNegativeRealScalar<RealType>) {
        self.0 *= &other.0;
    }
}

/// Implements in-place multiplication for [`NonNegativeRealScalar`] by value.
///
/// This allows multiplying `self` by a non-negative scalar value.
impl<RealType: RealScalar> MulAssign<NonNegativeRealScalar<RealType>>
    for NonNegativeRealScalar<RealType>
{
    fn mul_assign(&mut self, other: NonNegativeRealScalar<RealType>) {
        self.0 *= other.0;
    }
}

/// Implements [`Zero`] for [`NonNegativeRealScalar`].
///
/// The zero value is always valid, and acts as the additive identity.
impl<RealType: RealScalar> Zero for NonNegativeRealScalar<RealType> {
    fn is_zero(&self) -> bool {
        self.0.is_zero()
    }

    fn zero() -> Self {
        NonNegativeRealScalar(RealType::zero())
    }
}

impl<RealType: RealScalar> One for NonNegativeRealScalar<RealType> {
    fn one() -> Self {
        NonNegativeRealScalar(RealType::one())
    }
}

#[duplicate_item(
    exponent_type;
    [u8];
    [i8];
    [u16];
    [i16];
    [u32];
    [i32];
    [u64];
    [i64];
    [u128];
    [i128];
    [usize];
    [isize];
)]
impl<RealType: RealScalar> Pow<exponent_type> for NonNegativeRealScalar<RealType> {
    type Error = PowIntExponentErrors<<RealType as IntoInner>::InnerType, exponent_type>;

    fn try_pow(self, exponent: exponent_type) -> Result<Self, Self::Error> {
        self.0.try_pow(exponent).map(NonNegativeRealScalar)
    }

    #[inline(always)]
    /// Raises the number `self` to the power `exponent`.
    fn pow(self, exponent: exponent_type) -> Self {
        #[cfg(debug_assertions)]
        {
            self.try_pow(exponent).unwrap()
        }
        #[cfg(not(debug_assertions))]
        {
            NonNegativeRealScalar(self.0.pow(exponent))
        }
    }
}

/// Implements [`Max`] for [`NonNegativeRealScalar`].
///
/// Maximum selection is delegated to the default trait behavior based on [`PartialOrd`].
impl<RealType: RealScalar> Max for NonNegativeRealScalar<RealType> {}
/// Implements [`Min`] for [`NonNegativeRealScalar`].
///
/// Minimum selection is delegated to the default trait behavior based on [`PartialOrd`].
impl<RealType: RealScalar> Min for NonNegativeRealScalar<RealType> {}

/// Implements Neumaier compensated summation for [`NonNegativeRealScalar`].
///
/// This implementation delegates to the underlying real scalar type's Neumaier
/// compensated sum operation, preserving numerical stability for sums of non-negative values.
impl<RealType: RealScalar> NeumaierAddable for NonNegativeRealScalar<RealType> {
    #[inline(always)]
    fn neumaier_compensated_sum(value: Self, sum: &mut Self, compensation: &mut Self) {
        neumaier_sum_and_compensation_real(value.into_inner(), &mut sum.0, &mut compensation.0)
    }
}

//------------------------------------------------------------------------------------------------------------
// Conversions
//------------------------------------------------------------------------------------------------------------

/// Converts a [`PositiveRealScalar<T>`] to a [`NonNegativeRealScalar<T>`].
///
/// This conversion is mathematically valid because every positive number (x > 0) is
/// also non-negative (x ≥ 0). The conversion is infallible and zero-cost.
///
/// # Examples
///
/// ```rust
/// use num_valid::{*, scalars::*};
/// use try_create::TryNew;
///
/// let positive = PositiveRealScalar::try_new(5.0_f64).unwrap();
/// let non_negative: NonNegativeRealScalar<f64> = positive.into();
///
/// assert_eq!(non_negative.as_raw_scalar_ref(), &5.0);
/// ```
impl<RealType: RealScalar> From<PositiveRealScalar<RealType>> for NonNegativeRealScalar<RealType> {
    fn from(positive: PositiveRealScalar<RealType>) -> Self {
        NonNegativeRealScalar(positive.into_inner())
    }
}

//------------------------------------------------------------------------------------------------------------
// Cross-type arithmetic operations
//------------------------------------------------------------------------------------------------------------

/// Adds a [`NonNegativeRealScalar`] to a [`PositiveRealScalar`], yielding a [`PositiveRealScalar`].
///
/// Since `self` is strictly positive (x > 0) and `other` is non-negative (y ≥ 0),
/// their sum is strictly positive: x + y > 0.
///
/// # Examples
///
/// ```rust
/// use num_valid::{*, scalars::*};
/// use try_create::TryNew;
///
/// let pos = PositiveRealScalar::try_new(2.0_f64).unwrap();
/// let non_neg = NonNegativeRealScalar::try_new(3.0_f64).unwrap();
///
/// let result: PositiveRealScalar<f64> = pos + non_neg;
/// assert_eq!(result.as_raw_scalar_ref(), &5.0);
/// ```
impl<RealType: RealScalar> Add<NonNegativeRealScalar<RealType>> for PositiveRealScalar<RealType> {
    type Output = PositiveRealScalar<RealType>;

    fn add(self, other: NonNegativeRealScalar<RealType>) -> PositiveRealScalar<RealType> {
        PositiveRealScalar(self.0 + other.0)
    }
}

/// Adds a [`NonNegativeRealScalar`] by reference to a [`PositiveRealScalar`], yielding a [`PositiveRealScalar`].
///
/// Since `self` is strictly positive (x > 0) and `other` is non-negative (y ≥ 0),
/// their sum is strictly positive: x + y > 0.
impl<'a, RealType: RealScalar> Add<&'a NonNegativeRealScalar<RealType>>
    for PositiveRealScalar<RealType>
{
    type Output = PositiveRealScalar<RealType>;

    fn add(self, other: &'a NonNegativeRealScalar<RealType>) -> PositiveRealScalar<RealType> {
        PositiveRealScalar(self.0 + &other.0)
    }
}

/// Adds a [`PositiveRealScalar`] to a [`NonNegativeRealScalar`], yielding a [`PositiveRealScalar`].
///
/// Since `other` is strictly positive (x > 0) and `self` is non-negative (y ≥ 0),
/// their sum is strictly positive: x + y > 0.
///
/// # Examples
///
/// ```rust
/// use num_valid::{*, scalars::*};
/// use try_create::TryNew;
///
/// let non_neg = NonNegativeRealScalar::try_new(0.0_f64).unwrap(); // zero!
/// let pos = PositiveRealScalar::try_new(5.0_f64).unwrap();
///
/// let result: PositiveRealScalar<f64> = non_neg + pos;
/// assert_eq!(result.as_raw_scalar_ref(), &5.0);
/// ```
impl<RealType: RealScalar> Add<PositiveRealScalar<RealType>> for NonNegativeRealScalar<RealType> {
    type Output = PositiveRealScalar<RealType>;

    fn add(self, other: PositiveRealScalar<RealType>) -> PositiveRealScalar<RealType> {
        PositiveRealScalar(self.0 + other.0)
    }
}

/// Adds a [`PositiveRealScalar`] by reference to a [`NonNegativeRealScalar`], yielding a [`PositiveRealScalar`].
///
/// Since `other` is strictly positive (x > 0) and `self` is non-negative (y ≥ 0),
/// their sum is strictly positive: x + y > 0.
impl<'a, RealType: RealScalar> Add<&'a PositiveRealScalar<RealType>>
    for NonNegativeRealScalar<RealType>
{
    type Output = PositiveRealScalar<RealType>;

    fn add(self, other: &'a PositiveRealScalar<RealType>) -> PositiveRealScalar<RealType> {
        PositiveRealScalar(self.0 + &other.0)
    }
}

//-----------------------------------------------------------------------------------

/// Error returned when constructing a [`HashableScalar`] from an invalid value.
///
/// Hash-based collections require keys to implement [`Eq`] and [`Hash`]. Floating-point
/// NaN values do not satisfy the reflexive equality requirement because `NaN != NaN`,
/// so they cannot safely be used as hash keys. This error preserves that invariant by
/// rejecting non-finite values during [`HashableScalar::try_new`].
///
/// # Examples
///
/// ```rust
/// use num_valid::scalars::{ErrorsHashableScalar, HashableScalar};
///
/// let result = HashableScalar::try_new(f64::NAN);
/// assert!(matches!(
///     result,
///     Err(ErrorsHashableScalar::NonFiniteValue { .. })
/// ));
/// ```
///
/// # See Also
///
/// - [`HashableScalar`] for the validated hash-key wrapper.
/// - [`HashableScalar::try_new`] for fallible construction.
#[derive(Debug, Error)]
pub enum ErrorsHashableScalar {
    /// The supplied scalar is NaN or infinite.
    ///
    /// Non-finite values cannot satisfy the equality contract required by hash-based
    /// collections, so [`HashableScalar::try_new`] rejects them.
    #[error("HashableScalar can only be constructed from finite scalar values")]
    NonFiniteValue {
        /// Stack backtrace captured at the invalid construction site.
        backtrace: Backtrace,
    },
}

/// Wrapper type that makes floating-point scalars hashable for use in hash-based collections.
///
/// # Purpose
///
/// Real or complex floating-point types (`f32`, `f64`, `Complex<f32>`, `Complex<f64>` and validated wrappers like
/// [`RealNative64StrictFinite`](crate::RealNative64StrictFinite),
/// [`ComplexNative64StrictFinite`](crate::ComplexNative64StrictFinite), `RealRugStrictFinite<PRECISION>`,
/// `ComplexRugStrictFinite<PRECISION>`, etc.) are not hashable by default
/// in Rust because of the presence of `NaN` values, which violate the requirements for hashing. Specifically, IEEE 754 defines that `NaN != NaN`, which means that two identical `NaN` values would not be considered equal, leading to inconsistent hashing behavior.
/// do not implement [`Hash`] by default because IEEE 754 defines `NaN != NaN`, violating the
/// requirement that `a == b` implies `hash(a) == hash(b)`. This type enforces that only
/// **finite** floating-point values can be hashed, making them safe for use in:
///
/// - [`HashMap`](std::collections::HashMap) and [`HashSet`](std::collections::HashSet)
/// - [`DashMap`](https://docs.rs/dashmap) for concurrent caching
/// - Any algorithm requiring consistent hashing of numerical values
///
/// # Invariants
///
/// - **Only finite values allowed**: [`HashableScalar::try_new()`] rejects values
///   that are not finite (not `NaN` or `±∞`).
/// - **Hash consistency**: Values are hashed via their raw bit representation
///   ([`RawScalarTrait::compute_hash_raw_scalar`]), ensuring bitwise-identical values produce identical hashes.
/// - **Equality semantics**: Implements [`Eq`] by delegating to the underlying scalar's
///   [`PartialEq`], which is safe because we exclude `NaN`.
///
/// # Type Parameters
///
/// - `ScalarType`: Any real or complex floating-point type implementing [`FpScalar`] (e.g., `f64`, `Complex<f64>`,
///   [`RealNative64StrictFinite`](crate::RealNative64StrictFinite),
///   [`ComplexNative64StrictFinite`](crate::ComplexNative64StrictFinite),
///   `RealRugStrictFinite<PRECISION>`, `ComplexRugStrictFinite<PRECISION>`, etc.).
///
/// # Examples
///
/// ## Basic Usage with `f64` and `Complex<f64>`
///
/// ```rust
/// use num_valid::scalars::HashableScalar;
/// use num::Complex;
/// use std::collections::HashSet;
///
/// let x = HashableScalar::new(3.14);
/// let y = HashableScalar::new(2.71);
/// let z = HashableScalar::new(3.14);
///
/// let mut set_real = HashSet::new();
/// set_real.insert(x);
/// set_real.insert(y);
/// set_real.insert(z); // Duplicate, won't be added
///
/// assert_eq!(set_real.len(), 2);
///
/// let a = HashableScalar::new(Complex::new(3.14, 2.0));
/// let b = HashableScalar::new(Complex::new(2.71, 1.0));
/// let c = HashableScalar::new(Complex::new(3.14, 2.0));
///
/// let mut set_complex = HashSet::new();
/// set_complex.insert(a);
/// set_complex.insert(b);
/// set_complex.insert(c); // Duplicate, won't be added
///
/// assert_eq!(set_complex.len(), 2);
/// ```
///
/// ## Use in Caching Structures
///
/// ```rust
/// use num_valid::scalars::HashableScalar;
/// use std::collections::HashMap;
///
/// // Cache computed values indexed by floating-point parameters
/// let mut cache: HashMap<HashableScalar<f64>, String> = HashMap::new();
///
/// let key = HashableScalar::new(1.5);
/// cache.insert(key, "result_for_1.5".to_string());
///
/// let retrieved = cache.get(&HashableScalar::new(1.5));
/// assert_eq!(retrieved, Some(&"result_for_1.5".to_string()));
/// ```
///
/// ## With Validated Scalar Types
///
/// The wrapper works with any type implementing [`FpScalar`], including validated types
/// from the `num_valid` crate:
///
/// ```rust
/// use num_valid::scalars::HashableScalar;
/// use std::collections::HashSet;
///
/// // Works with any FpScalar type
/// let mut set = HashSet::new();
/// set.insert(HashableScalar::new(1.0_f64));
/// set.insert(HashableScalar::new(2.0_f64));
/// set.insert(HashableScalar::new(1.0_f64)); // Duplicate
///
/// assert_eq!(set.len(), 2);
/// ```
///
/// # Invalid Values
///
/// Fallible construction rejects non-finite values:
///
/// ```rust
/// use num_valid::scalars::HashableScalar;
///
/// let invalid = HashableScalar::try_new(f64::NAN);
/// assert!(invalid.is_err());
/// ```
///
/// # Implementation Notes
///
/// - **Serialization**: Supports `serde` serialization/deserialization with bounds to ensure
///   the wrapped type can be serialized.
/// - **Extraction**: Implements [`IntoInner`] for consuming the wrapper and extracting the
///   underlying scalar via `.into_inner()`.
/// - **Zero-cost abstraction**: The wrapper is `#[repr(transparent)]` equivalent (single field),
///   so there is no runtime overhead.
///
/// # See Also
///
/// - [`FpScalar`] for the trait bounds on wrapped types
/// - [`RawScalarTrait::compute_hash_raw_scalar`] for the hashing mechanism
/// - Caching examples in `numerics-core/src/math/chebyshev/cache.rs`
#[derive(Debug, Clone, PartialEq, PartialOrd, AsRef, Serialize, Deserialize)]
#[serde(bound(deserialize = "ScalarType: for<'a> Deserialize<'a>"))]
pub struct HashableScalar<ScalarType: FpScalar> {
    value: ScalarType,
}

impl<ScalarType: FpScalar> Eq for HashableScalar<ScalarType> {}

impl<ScalarType: FpScalar> HashableScalar<ScalarType> {
    /// Creates a new hashable scalar from a finite value.
    ///
    /// # Panics
    ///
    /// Panics if the value is not finite (NaN or infinite). Use [`Self::try_new`]
    /// when the input is not already trusted.
    #[must_use]
    pub fn new(value: ScalarType) -> Self {
        Self::try_new(value)
            .expect("HashableScalar can only be constructed from finite scalar values")
    }

    /// Attempts to create a hashable scalar from a finite value.
    ///
    /// Returns [`ErrorsHashableScalar::NonFiniteValue`] when `value` is NaN or infinite.
    pub fn try_new(value: ScalarType) -> Result<Self, ErrorsHashableScalar> {
        if value.is_finite() {
            Ok(Self { value })
        } else {
            Err(ErrorsHashableScalar::NonFiniteValue {
                backtrace: capture_backtrace(),
            })
        }
    }
}

impl<ScalarType: FpScalar> Hash for HashableScalar<ScalarType> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.value
            .as_raw_scalar_ref()
            .compute_hash_raw_scalar(state);
    }
}

impl<ScalarType: FpScalar> IntoInner for HashableScalar<ScalarType> {
    type InnerType = ScalarType;

    #[inline(always)]
    fn into_inner(self) -> ScalarType {
        self.value
    }
}
//-----------------------------------------------------------------------------------

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

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

    mod hashable_scalar {
        use super::*;

        #[test]
        fn try_new_rejects_non_finite_values() {
            assert!(matches!(
                HashableScalar::try_new(f64::NAN),
                Err(ErrorsHashableScalar::NonFiniteValue { .. })
            ));
            assert!(matches!(
                HashableScalar::try_new(f64::INFINITY),
                Err(ErrorsHashableScalar::NonFiniteValue { .. })
            ));
        }
    }

    mod absolute_tolerance {
        use super::*;

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

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

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

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

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

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

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

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

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

        #[test]
        fn serialize_deserialize() {
            let tol = AbsoluteTolerance::new(NonNegativeRealScalar::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::new(NonNegativeRealScalar::try_new(val).unwrap());
            assert_eq!(tol.as_raw_scalar_ref(), &1e-10);
        }

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

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

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

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

        #[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::new(NonNegativeRealScalar::try_new(f64::INFINITY).unwrap());
        }

        #[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::new(NonNegativeRealScalar::try_new(f64::NAN).unwrap());
        }

        #[test]
        fn epsilon() {
            // Test creating an AbsoluteTolerance instance with epsilon value
            let epsilon_tol = AbsoluteTolerance::<f64>::epsilon();
            assert_eq!(*epsilon_tol.as_raw_scalar_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::new(NonNegativeRealScalar::try_new(1.0).unwrap());
            let d = AbsoluteTolerance::new(NonNegativeRealScalar::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::new(NonNegativeRealScalar::try_new(1.0).unwrap());
            assert!(a != b);

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

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

        #[test]
        fn clone_trait() {
            // Test the Clone trait
            let tolerance = AbsoluteTolerance::new(NonNegativeRealScalar::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::new(NonNegativeRealScalar::try_new(0.5).unwrap());
            let tolerance2 = AbsoluteTolerance::new(NonNegativeRealScalar::try_new(0.5).unwrap());
            assert_eq!(tolerance1, tolerance2);
        }

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

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

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

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

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

        #[test]
        fn approximately_equal_exact_match() {
            let a = 1.0_f64;
            let b = 1.0_f64;
            let tol = AbsoluteTolerance::try_new(1e-10_f64).unwrap();
            assert!(approximately_equal(a, b, &tol));
        }

        #[test]
        fn approximately_equal_within_tolerance() {
            let a = 1.0_f64;
            let b = 1.0 + 1e-11_f64;
            let tol = AbsoluteTolerance::try_new(1e-10_f64).unwrap();
            assert!(approximately_equal(a, b, &tol));
        }

        #[test]
        fn approximately_equal_outside_tolerance() {
            let a = 1.0_f64;
            let b = 1.0 + 1e-9_f64;
            let tol = AbsoluteTolerance::try_new(1e-10_f64).unwrap();
            assert!(!approximately_equal(a, b, &tol));
        }

        #[test]
        fn approximately_equal_negative_values() {
            let a = -5.0_f64;
            let b = -5.0 + 1e-12_f64;
            let tol = AbsoluteTolerance::try_new(1e-10_f64).unwrap();
            assert!(approximately_equal(a, b, &tol));
        }

        #[test]
        fn approximately_equal_zero_tolerance() {
            let a = 1.0_f64;
            let b = 1.0_f64;
            let tol = AbsoluteTolerance::<f64>::zero();
            assert!(approximately_equal(a, b, &tol));

            let c = 1.0_f64 + 1e-15;
            assert!(!approximately_equal(a, c, &tol)); // Even tiny difference fails with zero tolerance
        }

        #[test]
        fn approximately_equal_large_difference_outside_tolerance() {
            let a = 1.0_f64;
            let b = 2.0_f64;
            let tol = AbsoluteTolerance::try_new(0.1_f64).unwrap();
            assert!(!approximately_equal(a, b, &tol));
        }

        #[test]
        fn approximately_equal_symmetric() {
            let a = 1.0_f64;
            let b = 1.0 + 1e-12_f64;
            let tol = AbsoluteTolerance::try_new(1e-10_f64).unwrap();
            assert_eq!(
                approximately_equal(a, b, &tol),
                approximately_equal(b, a, &tol)
            );
        }

        #[test]
        fn approximately_equal_with_validated_type() {
            let a = RealNative64StrictFinite::try_from_f64(1.0).unwrap();
            let b = RealNative64StrictFinite::try_from_f64(1.0 + 1e-11).unwrap();
            let tol = AbsoluteTolerance::new(
                NonNegativeRealScalar::try_new(
                    RealNative64StrictFinite::try_from_f64(1e-10).unwrap(),
                )
                .unwrap(),
            );
            assert!(approximately_equal(a, b, &tol));
        }
    }

    mod relative_tolerance {
        use super::*;

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

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

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

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

        #[test]
        fn epsilon_constructor() {
            let tol = RelativeTolerance::<f64>::epsilon();
            assert_eq!(*tol.as_raw_scalar_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_raw_scalar_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_raw_scalar_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_raw_scalar_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.as_raw_scalar_ref(), &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_raw_scalar_ref(), 0.0);

            // Test creating a RelativeTolerance instance with a positive value
            let v = RelativeTolerance::try_new(2.0).unwrap();
            assert_eq!(*v.as_raw_scalar_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(ErrorsNonNegativeRealScalar::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_raw_scalar_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_raw_scalar_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_raw_scalar_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_raw_scalar_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(NonNegativeRealScalar(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_raw_scalar_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.as_raw_scalar_ref()), "1e-5");
        }
    }

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

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

        #[test]
        fn try_new_min_positive() {
            let val = PositiveRealScalar::try_new(f64::MIN_POSITIVE).unwrap();
            assert_eq!(*val.as_raw_scalar_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_raw_scalar_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_raw_scalar_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_raw_scalar_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_raw_scalar_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_raw_scalar_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_raw_scalar_ref(), f64::MIN_POSITIVE);

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

            // Test with epsilon
            let epsilon_scalar = PositiveRealScalar::try_new(f64::EPSILON).unwrap();
            assert_eq!(*epsilon_scalar.as_raw_scalar_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_raw_scalar_ref(), &5.0);

            // 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"),
            }
        }

        #[test]
        fn sqrt_preserves_positivity() {
            // Test that sqrt of a positive value is also positive
            let base = PositiveRealScalar::try_new(4.0_f64).unwrap();
            let result = base.sqrt();
            assert_eq!(*result.as_raw_scalar_ref(), 2.0);

            // Test with other values
            let base = PositiveRealScalar::try_new(9.0_f64).unwrap();
            let result = base.sqrt();
            assert_eq!(*result.as_raw_scalar_ref(), 3.0);
        }

        #[test]
        fn sqrt_with_small_base() {
            // Test sqrt with very small positive value
            let base = PositiveRealScalar::try_new(0.01_f64).unwrap();
            let result = base.sqrt();
            assert_eq!(*result.as_raw_scalar_ref(), 0.1);
        }

        #[test]
        fn sqrt_with_generic_types() {
            // Test sqrt with validated types
            let base_val = RealNative64StrictFiniteInDebug::try_new(4.0).unwrap();
            let base = PositiveRealScalar::try_new(base_val).unwrap();

            let result = base.sqrt();
            assert_eq!(*result.as_raw_scalar_ref(), 2.0);
        }

        #[test]
        fn new_constructor_debug_validates() {
            // Test the new() constructor (validates in debug, skips in release)
            // In debug mode, new() should behave like try_new().unwrap()
            #[cfg(debug_assertions)]
            {
                let val = PositiveRealScalar::new(2.5_f64);
                assert_eq!(*val.as_raw_scalar_ref(), 2.5);
            }

            #[cfg(not(debug_assertions))]
            {
                // In release mode, new() trusts the input
                let val = PositiveRealScalar::new(2.5_f64);
                assert_eq!(*val.as_raw_scalar_ref(), 2.5);
            }
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic(expected = "Error in the creation")]
        fn new_constructor_panics_on_zero_debug() {
            // In debug mode, new() should panic on zero
            let _ = PositiveRealScalar::new(0.0_f64);
        }

        #[test]
        #[cfg(debug_assertions)]
        #[should_panic(expected = "Error in the creation")]
        fn new_constructor_panics_on_negative_debug() {
            // In debug mode, new() should panic on negative
            let _ = PositiveRealScalar::new(-1.0_f64);
        }

        #[test]
        fn one_trait_identity() {
            // Test the One trait: one() should return PositiveRealScalar(1.0)
            let one = PositiveRealScalar::<f64>::one();
            assert_eq!(*one.as_raw_scalar_ref(), 1.0);
        }

        #[test]
        fn one_trait_multiplicative_identity() {
            // Test that one acts as multiplicative identity
            let value = PositiveRealScalar::try_new(5.5_f64).unwrap();
            let one = PositiveRealScalar::<f64>::one();

            let result = value.clone() * one.clone();
            assert_eq!(*result.as_raw_scalar_ref(), 5.5);

            let result = one * value;
            assert_eq!(*result.as_raw_scalar_ref(), 5.5);
        }

        #[test]
        fn one_trait_with_generic_types() {
            // Test One trait with validated types
            let one = PositiveRealScalar::<RealNative64StrictFiniteInDebug>::one();
            assert_eq!(*one.as_raw_scalar_ref(), 1.0);
        }

        #[test]
        fn pow_integer_exponents() {
            // Test Pow trait with different integer exponent types
            let base = PositiveRealScalar::try_new(2.0_f64).unwrap();

            // Test with u32
            let result = base.clone().pow(3u32);
            assert_eq!(*result.as_raw_scalar_ref(), 8.0);

            // Test with u8
            let result = base.clone().pow(2u8);
            assert_eq!(*result.as_raw_scalar_ref(), 4.0);

            // Test with i32 (positive)
            let result = base.clone().pow(2i32);
            assert_eq!(*result.as_raw_scalar_ref(), 4.0);
        }

        #[test]
        fn pow_zero_exponent() {
            // Test that any number raised to power 0 equals 1
            let base = PositiveRealScalar::try_new(5.5_f64).unwrap();

            let result = base.pow(0u32);
            assert_eq!(*result.as_raw_scalar_ref(), 1.0);
        }

        #[test]
        fn pow_one_exponent() {
            // Test that any number raised to power 1 equals itself
            let base = PositiveRealScalar::try_new(3.7_f64).unwrap();

            let result = base.clone().pow(1u32);
            assert_eq!(*result.as_raw_scalar_ref(), 3.7);
        }

        #[test]
        fn pow_preserves_positivity() {
            // Test that raising positive to any integer power preserves positivity
            let base = PositiveRealScalar::try_new(2.5_f64).unwrap();

            let result = base.clone().pow(5u32);
            assert!(*result.as_raw_scalar_ref() > 0.0);
            assert_eq!(*result.as_raw_scalar_ref(), 2.5_f64.powi(5));
        }

        #[test]
        fn pow_with_try_pow() {
            // Test the try_pow method
            let base = PositiveRealScalar::try_new(3.0_f64).unwrap();

            let result = base.clone().try_pow(2u32);
            assert!(result.is_ok());
            assert_eq!(*result.unwrap().as_raw_scalar_ref(), 9.0);

            // Test with different exponent types
            let result = base.try_pow(3i32);
            assert!(result.is_ok());
            assert_eq!(*result.unwrap().as_raw_scalar_ref(), 27.0);
        }

        #[test]
        fn pow_large_exponents() {
            // Test with large exponents
            let base = PositiveRealScalar::try_new(1.1_f64).unwrap();
            let result = base.pow(10u32);
            let expected = 1.1_f64.powi(10);
            assert!((result.as_raw_scalar_ref() - expected).abs() < 1e-10);
        }

        #[test]
        fn pow_small_base() {
            // Test with small base values
            let base = PositiveRealScalar::try_new(0.5_f64).unwrap();

            let result = base.clone().pow(2u32);
            assert_eq!(*result.as_raw_scalar_ref(), 0.25);

            let result = base.pow(3u32);
            assert_eq!(*result.as_raw_scalar_ref(), 0.125);
        }

        #[test]
        fn pow_with_generic_types() {
            // Test Pow with validated types
            let base_val = RealNative64StrictFiniteInDebug::try_new(2.0).unwrap();
            let base = PositiveRealScalar::try_new(base_val).unwrap();

            let result = base.pow(3u32);
            assert_eq!(*result.as_raw_scalar_ref(), 8.0);
        }

        #[test]
        fn pow_chain_operations() {
            // Test chaining pow operations
            let base = PositiveRealScalar::try_new(2.0_f64).unwrap();

            // (2^3)^2 = 2^6 = 64
            let result = base.pow(3u32).pow(2u32);
            assert_eq!(*result.as_raw_scalar_ref(), 64.0);
        }

        #[test]
        fn add_trait_value_semantics() {
            // Test Add trait for by-value operands
            let a = PositiveRealScalar::try_new(2.0_f64).unwrap();
            let b = PositiveRealScalar::try_new(3.0_f64).unwrap();

            let sum = a + b;
            assert_eq!(*sum.as_raw_scalar_ref(), 5.0);
            assert!(*sum.as_raw_scalar_ref() > 0.0);
        }

        #[test]
        fn add_trait_reference_semantics() {
            // Test Add trait with reference operand
            let a = PositiveRealScalar::try_new(2.0_f64).unwrap();
            let b = PositiveRealScalar::try_new(3.0_f64).unwrap();

            let sum = a + &b;
            assert_eq!(*sum.as_raw_scalar_ref(), 5.0);
        }

        #[test]
        fn mul_trait_value_semantics() {
            // Test Mul trait for by-value operands
            let a = PositiveRealScalar::try_new(2.5_f64).unwrap();
            let b = PositiveRealScalar::try_new(4.0_f64).unwrap();

            let product = a * b;
            assert_eq!(*product.as_raw_scalar_ref(), 10.0);
            assert!(*product.as_raw_scalar_ref() > 0.0);
        }

        #[test]
        fn mul_trait_reference_semantics() {
            // Test Mul trait with reference operand
            let a = PositiveRealScalar::try_new(2.5_f64).unwrap();
            let b = PositiveRealScalar::try_new(4.0_f64).unwrap();

            let product = a * &b;
            assert_eq!(*product.as_raw_scalar_ref(), 10.0);
        }

        #[test]
        fn add_assign_value_semantics() {
            // Test AddAssign trait for by-value operand
            let mut a = PositiveRealScalar::try_new(2.0_f64).unwrap();
            let b = PositiveRealScalar::try_new(3.0_f64).unwrap();

            a += b;
            assert_eq!(*a.as_raw_scalar_ref(), 5.0);
        }

        #[test]
        fn add_assign_reference_semantics() {
            // Test AddAssign trait with reference operand
            let mut a = PositiveRealScalar::try_new(2.0_f64).unwrap();
            let b = PositiveRealScalar::try_new(3.0_f64).unwrap();

            a += &b;
            assert_eq!(*a.as_raw_scalar_ref(), 5.0);
        }

        #[test]
        fn mul_assign_value_semantics() {
            // Test MulAssign trait for by-value operand
            let mut a = PositiveRealScalar::try_new(2.0_f64).unwrap();
            let b = PositiveRealScalar::try_new(3.0_f64).unwrap();

            a *= b;
            assert_eq!(*a.as_raw_scalar_ref(), 6.0);
        }

        #[test]
        fn mul_assign_reference_semantics() {
            // Test MulAssign trait with reference operand
            let mut a = PositiveRealScalar::try_new(2.0_f64).unwrap();
            let b = PositiveRealScalar::try_new(3.0_f64).unwrap();

            a *= &b;
            assert_eq!(*a.as_raw_scalar_ref(), 6.0);
        }

        #[test]
        fn max_min_traits() {
            // Test Max/Min traits (delegated to default behavior)
            let a = PositiveRealScalar::try_new(1.0_f64).unwrap();
            let b = PositiveRealScalar::try_new(3.0_f64).unwrap();

            let max_val = Max::max_by_ref(&a, &b);
            assert_eq!(*max_val.as_raw_scalar_ref(), 3.0);

            let min_val = Min::min_by_ref(&a, &b);
            assert_eq!(*min_val.as_raw_scalar_ref(), 1.0);
        }
    }

    mod non_negative_real_scalar {
        use super::*;
        use crate::backends::native::validated::RealNative64StrictFiniteInDebug;
        use crate::functions::{Max, Min};
        use num::Zero;

        #[test]
        fn add_trait_preserves_non_negativity() {
            let a = NonNegativeRealScalar::try_new(2.0_f64).unwrap();
            let b = NonNegativeRealScalar::try_new(3.5_f64).unwrap();

            let sum = a + b;
            assert_eq!(*sum.as_raw_scalar_ref(), 5.5);
            assert!(*sum.as_raw_scalar_ref() >= 0.0);
        }

        #[test]
        fn add_trait_zero_is_identity() {
            let value = NonNegativeRealScalar::try_new(4.25_f64).unwrap();
            let zero = NonNegativeRealScalar::<f64>::zero();

            assert_eq!(*(value.clone() + zero.clone()).as_raw_scalar_ref(), 4.25);
            assert_eq!(*(zero + value).as_raw_scalar_ref(), 4.25);
        }

        #[test]
        fn zero_trait_methods() {
            let zero = NonNegativeRealScalar::<f64>::zero();
            let non_zero = NonNegativeRealScalar::try_new(0.5_f64).unwrap();

            assert!(zero.is_zero());
            assert!(!non_zero.is_zero());
            assert_eq!(*zero.as_raw_scalar_ref(), 0.0);
        }

        #[test]
        fn max_trait_by_ref_and_by_value() {
            let small = NonNegativeRealScalar::try_new(1.0_f64).unwrap();
            let large = NonNegativeRealScalar::try_new(3.0_f64).unwrap();

            let by_ref = Max::max_by_ref(&small, &large);
            assert_eq!(*by_ref.as_raw_scalar_ref(), 3.0);

            let by_value = Max::max_by_value(small, large);
            assert_eq!(*by_value.as_raw_scalar_ref(), 3.0);
        }

        #[test]
        fn min_trait_by_ref_and_by_value() {
            let small = NonNegativeRealScalar::try_new(1.0_f64).unwrap();
            let large = NonNegativeRealScalar::try_new(3.0_f64).unwrap();

            let by_ref = Min::min_by_ref(&small, &large);
            assert_eq!(*by_ref.as_raw_scalar_ref(), 1.0);

            let by_value = Min::min_by_value(small, large);
            assert_eq!(*by_value.as_raw_scalar_ref(), 1.0);
        }

        #[test]
        fn max_min_by_ref_equal_values_returns_left_operand() {
            let left_max = NonNegativeRealScalar::try_new(2.0_f64).unwrap();
            let right_max = NonNegativeRealScalar::try_new(2.0_f64).unwrap();
            let selected_max = Max::max_by_ref(&left_max, &right_max);
            assert!(std::ptr::eq(selected_max, &left_max));

            let left_min = NonNegativeRealScalar::try_new(2.0_f64).unwrap();
            let right_min = NonNegativeRealScalar::try_new(2.0_f64).unwrap();
            let selected_min = Min::min_by_ref(&left_min, &right_min);
            assert!(std::ptr::eq(selected_min, &left_min));
        }

        #[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_raw_scalar_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_raw_scalar_ref(), 2.5);

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

            // Test with large positive value
            let v = NonNegativeRealScalar::try_new(1e100).unwrap();
            assert_eq!(*v.as_raw_scalar_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_raw_scalar_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_raw_scalar_ref();
            assert_eq!(*inner, 2.0);

            let zero = NonNegativeRealScalar::try_new(0.0).unwrap();
            let inner: &f64 = zero.as_raw_scalar_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_raw_scalar_ref(), 0.0);

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

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

            // Test with epsilon
            let epsilon_scalar = NonNegativeRealScalar::try_new(f64::EPSILON).unwrap();
            assert_eq!(*epsilon_scalar.as_raw_scalar_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_raw_scalar_ref(), &5.0);

            // 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_raw_scalar_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_raw_scalar_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_raw_scalar_ref(), 5.0);
            assert_eq!(*safe_abs(0.0).as_raw_scalar_ref(), 0.0); // Zero is valid!
            assert_eq!(*safe_abs(3.0).as_raw_scalar_ref(), 3.0);
        }

        #[test]
        fn one_trait_identity() {
            // Test the One trait: one() should return NonNegativeRealScalar(1.0)
            let one = NonNegativeRealScalar::<f64>::one();
            assert_eq!(*one.as_raw_scalar_ref(), 1.0);
        }

        #[test]
        fn one_trait_multiplicative_identity() {
            // Test that one acts as multiplicative identity
            let value = NonNegativeRealScalar::try_new(5.5_f64).unwrap();
            let one = NonNegativeRealScalar::<f64>::one();

            let result = value.clone() * one.clone();
            assert_eq!(*result.as_raw_scalar_ref(), 5.5);

            let result = one * value;
            assert_eq!(*result.as_raw_scalar_ref(), 5.5);
        }

        #[test]
        fn one_trait_with_generic_types() {
            // Test One trait with validated types
            let one = NonNegativeRealScalar::<RealNative64StrictFiniteInDebug>::one();
            assert_eq!(*one.as_raw_scalar_ref(), 1.0);
        }

        #[test]
        fn pow_integer_exponents() {
            // Test Pow trait with different integer exponent types
            let base = NonNegativeRealScalar::try_new(2.0_f64).unwrap();

            // Test with u32
            let result = base.clone().pow(3u32);
            assert_eq!(*result.as_raw_scalar_ref(), 8.0);

            // Test with u8
            let result = base.clone().pow(2u8);
            assert_eq!(*result.as_raw_scalar_ref(), 4.0);

            // Test with i32 (positive)
            let result = base.clone().pow(2i32);
            assert_eq!(*result.as_raw_scalar_ref(), 4.0);
        }

        #[test]
        fn pow_zero_exponent() {
            // Test that any number raised to power 0 equals 1
            let base = NonNegativeRealScalar::try_new(5.5_f64).unwrap();

            let result = base.clone().pow(0u32);
            assert_eq!(*result.as_raw_scalar_ref(), 1.0);

            // Even 0 raised to power 0 should be 1
            let zero = NonNegativeRealScalar::try_new(0.0_f64).unwrap();
            let result = zero.pow(0u32);
            assert_eq!(*result.as_raw_scalar_ref(), 1.0);
        }

        #[test]
        fn pow_one_exponent() {
            // Test that any number raised to power 1 equals itself
            let base = NonNegativeRealScalar::try_new(3.7_f64).unwrap();

            let result = base.clone().pow(1u32);
            assert_eq!(*result.as_raw_scalar_ref(), 3.7);
        }

        #[test]
        fn pow_preserves_non_negativity() {
            // Test that raising non-negative to any integer power preserves non-negativity
            let base = NonNegativeRealScalar::try_new(2.5_f64).unwrap();

            let result = base.clone().pow(5u32);
            assert!(*result.as_raw_scalar_ref() >= 0.0);
            assert_eq!(*result.as_raw_scalar_ref(), 2.5_f64.powi(5));

            // Even 0 raised to positive power stays non-negative
            let zero = NonNegativeRealScalar::try_new(0.0_f64).unwrap();
            let result = zero.pow(10u32);
            assert_eq!(*result.as_raw_scalar_ref(), 0.0);
        }

        #[test]
        fn pow_with_try_pow() {
            // Test the try_pow method
            let base = NonNegativeRealScalar::try_new(3.0_f64).unwrap();

            let result = base.clone().try_pow(2u32);
            assert!(result.is_ok());
            assert_eq!(*result.unwrap().as_raw_scalar_ref(), 9.0);

            // Test with different exponent types
            let result = base.clone().try_pow(3i32);
            assert!(result.is_ok());
            assert_eq!(*result.unwrap().as_raw_scalar_ref(), 27.0);
        }

        #[test]
        fn pow_large_exponents() {
            // Test with large exponents
            let base = NonNegativeRealScalar::try_new(1.1_f64).unwrap();
            let result = base.pow(10u32);
            let expected = 1.1_f64.powi(10);
            assert!((result.as_raw_scalar_ref() - expected).abs() < 1e-10);
        }

        #[test]
        fn pow_small_base() {
            // Test with small base values
            let base = NonNegativeRealScalar::try_new(0.5_f64).unwrap();

            let result = base.clone().pow(2u32);
            assert_eq!(*result.as_raw_scalar_ref(), 0.25);

            let result = base.clone().pow(3u32);
            assert_eq!(*result.as_raw_scalar_ref(), 0.125);
        }

        #[test]
        fn pow_with_generic_types() {
            // Test Pow with validated types
            let base_val = RealNative64StrictFiniteInDebug::try_new(2.0).unwrap();
            let base = NonNegativeRealScalar::try_new(base_val).unwrap();

            let result = base.pow(3u32);
            assert_eq!(*result.as_raw_scalar_ref(), 8.0);
        }

        #[test]
        fn pow_chain_operations() {
            // Test chaining pow operations
            let base = NonNegativeRealScalar::try_new(2.0_f64).unwrap();

            // (2^3)^2 = 2^6 = 64
            let result = base.clone().pow(3u32).pow(2u32);
            assert_eq!(*result.as_raw_scalar_ref(), 64.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());
        }
    }

    mod conversion_tests {
        use super::*;
        use crate::backends::native::validated::RealNative64StrictFiniteInDebug;

        #[test]
        fn from_positive_to_non_negative() {
            // Test basic conversion from PositiveRealScalar to NonNegativeRealScalar
            let positive = PositiveRealScalar::try_new(5.0_f64).unwrap();
            let non_negative: NonNegativeRealScalar<f64> = positive.into();

            assert_eq!(*non_negative.as_raw_scalar_ref(), 5.0);
        }

        #[test]
        fn from_positive_to_non_negative_min_positive() {
            // Test conversion with f64::MIN_POSITIVE (smallest positive value)
            let positive = PositiveRealScalar::try_new(f64::MIN_POSITIVE).unwrap();
            let non_negative: NonNegativeRealScalar<f64> = positive.into();

            assert_eq!(*non_negative.as_raw_scalar_ref(), f64::MIN_POSITIVE);
        }

        #[test]
        fn from_positive_to_non_negative_large_value() {
            // Test conversion with large value
            let positive = PositiveRealScalar::try_new(f64::MAX).unwrap();
            let non_negative: NonNegativeRealScalar<f64> = positive.into();

            assert_eq!(*non_negative.as_raw_scalar_ref(), f64::MAX);
        }

        #[test]
        fn from_positive_to_non_negative_one() {
            // Test conversion with the multiplicative identity
            let positive = PositiveRealScalar::try_new(1.0_f64).unwrap();
            let non_negative: NonNegativeRealScalar<f64> = positive.into();

            assert_eq!(*non_negative.as_raw_scalar_ref(), 1.0);
        }

        #[test]
        fn from_positive_to_non_negative_preserves_value() {
            // Test that the conversion preserves the exact value
            let test_values = vec![0.5, 1.0, 2.5, 10.0, 99.9, 1e10, 1e-10];

            for value in test_values {
                let positive = PositiveRealScalar::try_new(value).unwrap();
                let non_negative: NonNegativeRealScalar<f64> = positive.into();

                assert_eq!(*non_negative.as_raw_scalar_ref(), value);
            }
        }

        #[test]
        fn from_positive_to_non_negative_with_generic_type() {
            // Test conversion with validated types
            let inner = RealNative64StrictFiniteInDebug::try_new(5.0).unwrap();
            let positive = PositiveRealScalar::try_new(inner).unwrap();
            let non_negative: NonNegativeRealScalar<RealNative64StrictFiniteInDebug> =
                positive.into();

            assert_eq!(*non_negative.as_raw_scalar_ref(), 5.0);
        }

        #[test]
        fn from_positive_consumed_by_conversion() {
            // Test that the conversion consumes the PositiveRealScalar
            let positive = PositiveRealScalar::try_new(5.0_f64).unwrap();
            let _non_negative: NonNegativeRealScalar<f64> = positive.into();

            // If we try to use `positive` here, it would be a compile error
            // because it was consumed by the conversion.
            // This test just documents the behavior.
        }

        #[test]
        fn from_positive_creates_valid_non_negative() {
            // Test that the converted value is indeed non-negative
            let positive = PositiveRealScalar::try_new(3.5_f64).unwrap();
            let non_negative: NonNegativeRealScalar<f64> = positive.into();

            // The converted value should pass all non-negative validation
            assert!(*non_negative.as_raw_scalar_ref() >= 0.0);
            assert!(!non_negative.is_zero()); // Since it came from a positive value
        }

        #[test]
        fn from_positive_mathematical_properties() {
            // Test that mathematical properties are preserved after conversion
            let positive_a = PositiveRealScalar::try_new(2.0_f64).unwrap();
            let positive_b = PositiveRealScalar::try_new(3.0_f64).unwrap();

            let non_neg_a: NonNegativeRealScalar<f64> = positive_a.into();
            let non_neg_b: NonNegativeRealScalar<f64> = positive_b.into();

            // Arithmetic should work the same way after conversion
            let sum = non_neg_a + non_neg_b;
            assert_eq!(*sum.as_raw_scalar_ref(), 5.0);
        }

        #[test]
        fn from_positive_with_chained_operations() {
            // Test conversion followed by operations
            let positive = PositiveRealScalar::try_new(2.0_f64).unwrap();
            let non_negative: NonNegativeRealScalar<f64> = positive.into();

            // Test that we can use trait methods on the converted value
            let one = NonNegativeRealScalar::<f64>::one();
            let result = non_negative * one;

            assert_eq!(*result.as_raw_scalar_ref(), 2.0);
        }

        #[test]
        fn from_positive_comparison_after_conversion() {
            // Test comparison operations work correctly after conversion
            let positive_small = PositiveRealScalar::try_new(1.0_f64).unwrap();
            let positive_large = PositiveRealScalar::try_new(3.0_f64).unwrap();

            let non_neg_small: NonNegativeRealScalar<f64> = positive_small.into();
            let non_neg_large: NonNegativeRealScalar<f64> = positive_large.into();

            assert!(non_neg_small < non_neg_large);
            assert!(non_neg_large > non_neg_small);
        }

        #[test]
        fn from_positive_pow_after_conversion() {
            // Test that Pow trait works correctly after conversion
            let positive = PositiveRealScalar::try_new(2.0_f64).unwrap();
            let non_negative: NonNegativeRealScalar<f64> = positive.into();

            let squared = non_negative.pow(2u32);
            assert_eq!(*squared.as_raw_scalar_ref(), 4.0);
        }

        #[test]
        fn from_positive_sqrt_after_conversion() {
            // Test that sqrt works correctly after conversion
            let positive = PositiveRealScalar::try_new(4.0_f64).unwrap();
            let non_negative: NonNegativeRealScalar<f64> = positive.into();

            let sqrt = non_negative.sqrt();
            assert_eq!(*sqrt.as_raw_scalar_ref(), 2.0);
        }
    }

    mod cross_type_arithmetic_tests {
        use super::*;
        use crate::backends::native::validated::RealNative64StrictFiniteInDebug;

        // --- Pos + NonNeg → Pos ---

        #[test]
        fn pos_add_non_neg_value() {
            // PositiveRealScalar + NonNegativeRealScalar (by value) → PositiveRealScalar
            let pos = PositiveRealScalar::try_new(2.0_f64).unwrap();
            let non_neg = NonNegativeRealScalar::try_new(3.0_f64).unwrap();

            let result: PositiveRealScalar<f64> = pos + non_neg;
            assert_eq!(*result.as_raw_scalar_ref(), 5.0);
        }

        #[test]
        fn pos_add_non_neg_ref() {
            // PositiveRealScalar + &NonNegativeRealScalar (by reference) → PositiveRealScalar
            let pos = PositiveRealScalar::try_new(2.0_f64).unwrap();
            let non_neg = NonNegativeRealScalar::try_new(3.0_f64).unwrap();

            let result: PositiveRealScalar<f64> = pos + &non_neg;
            assert_eq!(*result.as_raw_scalar_ref(), 5.0);
            // non_neg is still usable here (not consumed)
            assert_eq!(*non_neg.as_raw_scalar_ref(), 3.0);
        }

        #[test]
        fn pos_add_non_neg_zero_preserves_positivity() {
            // Adding zero (NonNeg) to a positive value should remain positive
            let pos = PositiveRealScalar::try_new(5.0_f64).unwrap();
            let zero = NonNegativeRealScalar::<f64>::zero();

            let result: PositiveRealScalar<f64> = pos + zero;
            assert_eq!(*result.as_raw_scalar_ref(), 5.0);
            assert!(*result.as_raw_scalar_ref() > 0.0);
        }

        #[test]
        fn pos_add_non_neg_zero_ref_preserves_positivity() {
            // Adding zero (NonNeg ref) to a positive value should remain positive
            let pos = PositiveRealScalar::try_new(5.0_f64).unwrap();
            let zero = NonNegativeRealScalar::<f64>::zero();

            let result: PositiveRealScalar<f64> = pos + &zero;
            assert_eq!(*result.as_raw_scalar_ref(), 5.0);
        }

        // --- NonNeg + Pos → Pos ---

        #[test]
        fn non_neg_add_pos_value() {
            // NonNegativeRealScalar + PositiveRealScalar (by value) → PositiveRealScalar
            let non_neg = NonNegativeRealScalar::try_new(3.0_f64).unwrap();
            let pos = PositiveRealScalar::try_new(2.0_f64).unwrap();

            let result: PositiveRealScalar<f64> = non_neg + pos;
            assert_eq!(*result.as_raw_scalar_ref(), 5.0);
        }

        #[test]
        fn non_neg_add_pos_ref() {
            // NonNegativeRealScalar + &PositiveRealScalar (by reference) → PositiveRealScalar
            let non_neg = NonNegativeRealScalar::try_new(3.0_f64).unwrap();
            let pos = PositiveRealScalar::try_new(2.0_f64).unwrap();

            let result: PositiveRealScalar<f64> = non_neg + &pos;
            assert_eq!(*result.as_raw_scalar_ref(), 5.0);
            // pos is still usable here (not consumed)
            assert_eq!(*pos.as_raw_scalar_ref(), 2.0);
        }

        #[test]
        fn zero_add_pos_value() {
            // Zero (NonNeg) + PositiveRealScalar → PositiveRealScalar
            // Key test: zero + positive should give the positive value
            let zero = NonNegativeRealScalar::<f64>::zero();
            let pos = PositiveRealScalar::try_new(5.0_f64).unwrap();

            let result: PositiveRealScalar<f64> = zero + pos;
            assert_eq!(*result.as_raw_scalar_ref(), 5.0);
            assert!(*result.as_raw_scalar_ref() > 0.0);
        }

        #[test]
        fn zero_add_pos_ref() {
            // Zero (NonNeg) + &PositiveRealScalar → PositiveRealScalar
            let zero = NonNegativeRealScalar::<f64>::zero();
            let pos = PositiveRealScalar::try_new(5.0_f64).unwrap();

            let result: PositiveRealScalar<f64> = zero + &pos;
            assert_eq!(*result.as_raw_scalar_ref(), 5.0);
        }

        // --- Commutativity ---

        #[test]
        fn commutativity() {
            // Pos + NonNeg and NonNeg + Pos should give the same numeric value
            let pos = PositiveRealScalar::try_new(2.0_f64).unwrap();
            let non_neg = NonNegativeRealScalar::try_new(3.0_f64).unwrap();

            let left: PositiveRealScalar<f64> = pos.clone() + non_neg.clone();
            let right: PositiveRealScalar<f64> = non_neg + pos;

            assert_eq!(*left.as_raw_scalar_ref(), *right.as_raw_scalar_ref());
        }

        // --- Generic types ---

        #[test]
        fn cross_type_add_with_generic_type() {
            let pos_inner = RealNative64StrictFiniteInDebug::try_new(2.0).unwrap();
            let non_neg_inner = RealNative64StrictFiniteInDebug::try_new(3.0).unwrap();

            let pos = PositiveRealScalar::try_new(pos_inner).unwrap();
            let non_neg = NonNegativeRealScalar::try_new(non_neg_inner).unwrap();

            let result: PositiveRealScalar<RealNative64StrictFiniteInDebug> = pos + non_neg;
            assert_eq!(*result.as_raw_scalar_ref(), 5.0);
        }
    }
}