delaunay 0.8.0

//! Coordinate traits and implementations for geometric computations.
//!
//! This module provides a comprehensive set of traits for working with coordinates
//! in d-dimensional space, including the main `Coordinate` trait that unifies all
//! coordinate-related functionality, along with supporting traits for validation,
//! hashing, and equality comparison of floating-point coordinate values.
//!
//! # Overview
//!
//! The coordinate system is built around several key traits that work together:
//!
//! ## Core Traits
//!
//! - **`Coordinate<D>`**: Main abstraction for coordinate storage and operations
//! - **`FiniteCheck`**: Validation of coordinate values (no NaN or infinity)
//! - **`OrderedEq`**: NaN-aware equality that treats NaN values as equal to themselves
//! - **`HashCoordinate`**: Consistent hashing of floating-point values
//!
//! ## Key Features
//!
//! - **Generic dimensions**: Supports arbitrary dimensions via `const D: usize`
//! - **Scalar type contract**: Coordinate geometry currently supports `f64` scalars only.
//! - **Storage abstraction**: Abstracts arrays, vectors, and other storage mechanisms
//! - **Special value handling**: Proper handling of NaN, infinity, and zero values
//! - **Serialization support**: Built-in serde serialization/deserialization
//!
//! # Benefits
//!
//! 1. **Unified Interface**: All coordinate operations through a single trait system
//! 2. **Type Safety**: Strong type bounds ensure correct usage at compile time
//! 3. **Flexible Storage**: Abstract storage mechanism allows future extensibility
//! 4. **Robust Equality**: NaN-aware comparisons enable use in hash collections
//! 5. **Validation**: Built-in finite value checking prevents geometric errors
//!
//! # Usage Examples
//!
//! ```rust
//! use delaunay::prelude::geometry::*;
//! use delaunay::prelude::geometry::Point;
//!
//! # fn main() -> Result<(), delaunay::prelude::geometry::CoordinateConversionError> {
//! // Create coordinates using Point (which implements Coordinate)
//! let coord: Point<3> = Point::try_from([1.0, 2.0, 3.0])?;
//!
//! // All coordinate operations are available
//! assert_eq!(coord.dim(), 3);
//! assert_eq!(coord.to_array(), [1.0, 2.0, 3.0]);
//! assert!(coord.validate().is_ok());
//!
//! // Point parsing rejects non-finite coordinates at the boundary.
//! assert!(Point::<2>::try_from([f64::NAN, 1.0]).is_err());
//!
//! // Scalar helper traits still provide explicit special-value semantics.
//! assert!(f64::NAN.ordered_eq(&f64::NAN));
//! assert!(!f64::NAN.is_finite_generic());
//! # Ok(())
//! # }
//! ```
//!
//! The coordinate trait system enables geometric structures (`Point`, `Vertex`,
//! `Simplex`, etc.) to keep storage and geometric operations orthogonal while
//! maintaining mathematical correctness and type safety. The public coordinate
//! scalar contract is intentionally narrow today: `f64` is the only supported
//! caller-visible coordinate scalar. Exact arithmetic is used internally for
//! predicate fallbacks, and any future exact-coordinate input support will be added
//! through an explicit documented API rather than implicit arbitrary scalar support.

#![forbid(unsafe_code)]

use crate::geometry::matrix::{LaError, MatrixError, StackMatrixDispatchError};
use ordered_float::OrderedFloat;
use serde::{Serialize, de::DeserializeOwned};
use std::{
    fmt::{self, Debug, Display},
    hash::{Hash, Hasher},
};

/// A non-finite coordinate value category.
///
/// This keeps recognized non-finite coordinate diagnostics typed while
/// preserving a fallback for future/custom scalar representations whose debug
/// form is outside the built-in floating-point spellings.
///
/// # Examples
///
/// ```rust
/// use delaunay::prelude::geometry::{FiniteCoordinateValue, InvalidCoordinateValue};
///
/// assert_eq!(
///     FiniteCoordinateValue::try_new(f64::NAN),
///     Err(InvalidCoordinateValue::Nan)
/// );
/// assert_eq!(
///     FiniteCoordinateValue::try_new(f64::INFINITY),
///     Err(InvalidCoordinateValue::PositiveInfinity)
/// );
/// ```
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum InvalidCoordinateValue {
    /// Not-a-number.
    Nan,
    /// Positive infinity.
    PositiveInfinity,
    /// Negative infinity.
    NegativeInfinity,
    /// A custom non-finite value representation.
    Other(String),
}

impl InvalidCoordinateValue {
    /// Classifies a non-finite coordinate from its debug representation.
    pub(crate) fn from_debug<T: Debug>(value: &T) -> Self {
        let value = format!("{value:?}");
        match value.as_str() {
            "NaN" => Self::Nan,
            "inf" => Self::PositiveInfinity,
            "-inf" => Self::NegativeInfinity,
            _ => Self::Other(value),
        }
    }
}

impl fmt::Display for InvalidCoordinateValue {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Nan => f.write_str("NaN"),
            Self::PositiveInfinity => f.write_str("inf"),
            Self::NegativeInfinity => f.write_str("-inf"),
            Self::Other(value) => f.write_str(value),
        }
    }
}

/// A finite `f64` coordinate diagnostic value.
///
/// This is the finite-scalar proof carried by
/// [`CoordinateConversionValue::Scalar`]. Construct it with [`Self::try_new`]
/// at raw numeric boundaries; after construction, [`Self::get`] is infallible.
///
/// # Examples
///
/// ```rust
/// use delaunay::prelude::geometry::{FiniteCoordinateValue, InvalidCoordinateValue};
///
/// let value = FiniteCoordinateValue::try_new(1.25)?;
/// assert_eq!(value.get(), 1.25);
/// assert_eq!(
///     FiniteCoordinateValue::try_new(f64::NAN),
///     Err(InvalidCoordinateValue::Nan)
/// );
///
/// # Ok::<(), InvalidCoordinateValue>(())
/// ```
#[derive(Clone, Copy, Debug, PartialEq, PartialOrd)]
#[must_use]
pub struct FiniteCoordinateValue(f64);

impl FiniteCoordinateValue {
    /// Parses a raw `f64` into a finite coordinate diagnostic value.
    ///
    /// # Errors
    ///
    /// Returns [`InvalidCoordinateValue`] when `value` is `NaN` or infinite.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use delaunay::prelude::geometry::{FiniteCoordinateValue, InvalidCoordinateValue};
    ///
    /// let value = FiniteCoordinateValue::try_new(4.0)?;
    /// assert_eq!(value.get(), 4.0);
    ///
    /// assert_eq!(
    ///     FiniteCoordinateValue::try_new(f64::INFINITY),
    ///     Err(InvalidCoordinateValue::PositiveInfinity)
    /// );
    ///
    /// # Ok::<(), InvalidCoordinateValue>(())
    /// ```
    pub fn try_new(value: f64) -> Result<Self, InvalidCoordinateValue> {
        if value.is_finite() {
            Ok(Self(value))
        } else {
            Err(InvalidCoordinateValue::from_debug(&value))
        }
    }

    /// Returns the validated finite scalar.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use delaunay::prelude::geometry::{FiniteCoordinateValue, InvalidCoordinateValue};
    ///
    /// let value = FiniteCoordinateValue::try_new(-2.5)?;
    /// assert_eq!(value.get(), -2.5);
    ///
    /// # Ok::<(), InvalidCoordinateValue>(())
    /// ```
    #[must_use]
    pub const fn get(self) -> f64 {
        self.0
    }
}

impl TryFrom<f64> for FiniteCoordinateValue {
    type Error = InvalidCoordinateValue;

    fn try_from(value: f64) -> Result<Self, Self::Error> {
        Self::try_new(value)
    }
}

impl fmt::Display for FiniteCoordinateValue {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{:?}", self.0)
    }
}

/// Structured reason why a predicate classified a simplex as geometrically degenerate.
///
/// Values of this enum appear in
/// [`CoordinateConversionError::DegenerateSimplex`] so callers can distinguish
/// an exactly zero orientation determinant from a symbolic-perturbation tie.
///
/// # Examples
///
/// ```rust
/// use delaunay::prelude::geometry::DegenerateSimplexReason;
///
/// let reason = DegenerateSimplexReason::ZeroOrientation;
/// assert_eq!(reason.to_string(), "zero orientation");
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum DegenerateSimplexReason {
    /// The simplex orientation determinant is exactly zero.
    ZeroOrientation,
    /// All symbolic-perturbation cofactors vanished, usually because the input
    /// points are identical in the evaluated coordinate representation.
    VanishingSosCofactors,
}

impl fmt::Display for DegenerateSimplexReason {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::ZeroOrientation => f.write_str("zero orientation"),
            Self::VanishingSosCofactors => f.write_str("vanishing SoS cofactors"),
        }
    }
}

/// Typed value payload for coordinate conversion diagnostics.
///
/// Conversion errors use this instead of preformatted scalar strings so callers
/// can match finite scalar values and discrete counts directly. Formatting is
/// deferred to [`Display`].
///
/// # Examples
///
/// ```rust
/// use delaunay::prelude::geometry::{
///     CoordinateConversionValue, FiniteCoordinateValue, InvalidCoordinateValue,
/// };
///
/// assert_eq!(
///     CoordinateConversionValue::from_f64(2.5),
///     CoordinateConversionValue::Scalar(FiniteCoordinateValue::try_new(2.5)?)
/// );
/// assert_eq!(
///     CoordinateConversionValue::from_f64(f64::INFINITY),
///     CoordinateConversionValue::NonFinite(InvalidCoordinateValue::PositiveInfinity)
/// );
///
/// # Ok::<(), InvalidCoordinateValue>(())
/// ```
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub enum CoordinateConversionValue {
    /// A finite scalar value represented in the supported `f64` coordinate model.
    Scalar(FiniteCoordinateValue),
    /// A discrete unsigned count or index value.
    UnsignedInteger(usize),
    /// A non-finite coordinate category.
    NonFinite(InvalidCoordinateValue),
    /// Non-scalar diagnostic context.
    Other(String),
}

impl CoordinateConversionValue {
    /// Builds a typed payload from a supported coordinate scalar.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use delaunay::prelude::geometry::{CoordinateConversionValue, InvalidCoordinateValue};
    ///
    /// std::assert_matches!(
    ///     CoordinateConversionValue::from_f64(1.0),
    ///     CoordinateConversionValue::Scalar(_)
    /// );
    /// assert_eq!(
    ///     CoordinateConversionValue::from_f64(f64::NAN),
    ///     CoordinateConversionValue::NonFinite(InvalidCoordinateValue::Nan)
    /// );
    /// ```
    #[must_use]
    pub fn from_f64(value: f64) -> Self {
        FiniteCoordinateValue::try_new(value).map_or_else(Self::NonFinite, Self::Scalar)
    }

    /// Builds a typed payload from a discrete unsigned integer.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use delaunay::prelude::geometry::CoordinateConversionValue;
    ///
    /// assert_eq!(
    ///     CoordinateConversionValue::from_usize(7),
    ///     CoordinateConversionValue::UnsignedInteger(7)
    /// );
    /// ```
    #[must_use]
    pub const fn from_usize(value: usize) -> Self {
        Self::UnsignedInteger(value)
    }

    /// Builds a best-effort typed payload from a numeric value.
    pub(crate) fn from_numeric_debug<T>(value: &T) -> Self
    where
        T: Debug + num_traits::ToPrimitive,
    {
        value
            .to_f64()
            .map_or_else(|| Self::Other(format!("{value:?}")), Self::from_f64)
    }
}

impl Display for CoordinateConversionValue {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Scalar(value) => write!(f, "{value}"),
            Self::UnsignedInteger(value) => write!(f, "{value}"),
            Self::NonFinite(value) => write!(f, "{value}"),
            Self::Other(value) => f.write_str(value),
        }
    }
}

/// A coordinate tuple captured as typed diagnostic values.
///
/// This is used by error variants that need to report coordinates without
/// collapsing scalar values into display-oriented strings. Today supported
/// caller-visible coordinates are `f64`; exact coordinate payloads can be added
/// here later without changing every downstream error enum.
///
/// # Examples
///
/// ```rust
/// use delaunay::prelude::geometry::{
///     CoordinateConversionValue, CoordinateValues, InvalidCoordinateValue,
/// };
///
/// let coordinates = CoordinateValues::from([1.0, f64::NAN]);
/// std::assert_matches!(
///     coordinates.as_slice()[0],
///     CoordinateConversionValue::Scalar(_)
/// );
/// assert_eq!(
///     coordinates.as_slice()[1],
///     CoordinateConversionValue::NonFinite(InvalidCoordinateValue::Nan)
/// );
/// ```
#[derive(Clone, Debug, PartialEq)]
#[must_use]
pub struct CoordinateValues(Vec<CoordinateConversionValue>);

impl CoordinateValues {
    /// Builds a duplicate-coordinate diagnostic tuple from numeric coordinate values.
    ///
    /// This supports public duplicate-coordinate errors by preserving typed
    /// coordinate payloads after duplicate detection instead of preformatting
    /// them as display strings.
    pub(crate) fn from_numeric_slice<T>(values: &[T]) -> Self
    where
        T: Debug + num_traits::ToPrimitive,
    {
        Self(
            values
                .iter()
                .map(CoordinateConversionValue::from_numeric_debug)
                .collect(),
        )
    }

    /// Returns the typed coordinate payloads.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use delaunay::prelude::geometry::{CoordinateConversionValue, CoordinateValues};
    ///
    /// let coordinates = CoordinateValues::from([0.0, 1.0]);
    /// std::assert_matches!(
    ///     coordinates.as_slice(),
    ///     [CoordinateConversionValue::Scalar(_), CoordinateConversionValue::Scalar(_)]
    /// );
    /// ```
    #[must_use]
    pub fn as_slice(&self) -> &[CoordinateConversionValue] {
        &self.0
    }

    /// Consumes the wrapper and returns the underlying typed payloads.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use delaunay::prelude::geometry::{CoordinateConversionValue, CoordinateValues};
    ///
    /// let payloads = CoordinateValues::from([0.0, 1.0]).into_vec();
    /// std::assert_matches!(
    ///     payloads.as_slice(),
    ///     [CoordinateConversionValue::Scalar(_), CoordinateConversionValue::Scalar(_)]
    /// );
    /// ```
    #[must_use]
    pub fn into_vec(self) -> Vec<CoordinateConversionValue> {
        self.0
    }
}

impl<const D: usize> From<[f64; D]> for CoordinateValues {
    fn from(values: [f64; D]) -> Self {
        Self(
            values
                .into_iter()
                .map(CoordinateConversionValue::from_f64)
                .collect(),
        )
    }
}

impl fmt::Display for CoordinateValues {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("[")?;
        for (idx, value) in self.0.iter().enumerate() {
            if idx != 0 {
                f.write_str(", ")?;
            }
            write!(f, "{value}")?;
        }
        f.write_str("]")
    }
}

/// Errors that can occur during coordinate conversion in geometric predicates.
///
/// # Examples
///
/// ```rust
/// use delaunay::prelude::geometry::{CoordinateConversionError, CoordinateConversionValue};
///
/// let err = CoordinateConversionError::ConversionFailed {
///     coordinate_index: 0,
///     coordinate_value: CoordinateConversionValue::from_usize(9_007_199_254_740_992),
///     from_type: "usize",
///     to_type: "f64",
/// };
/// std::assert_matches!(err, CoordinateConversionError::ConversionFailed { .. });
/// ```
#[derive(Clone, Debug, thiserror::Error, PartialEq)]
#[non_exhaustive]
pub enum CoordinateConversionError {
    /// Coordinate conversion failed during matrix operations
    #[error(
        "Failed to convert coordinate at index {coordinate_index} from {from_type} to {to_type}: {coordinate_value}"
    )]
    ConversionFailed {
        /// Index of the coordinate that failed to convert.
        coordinate_index: usize,
        /// Problematic coordinate, count, or index value.
        coordinate_value: CoordinateConversionValue,
        /// Source type name
        from_type: &'static str,
        /// Target type name
        to_type: &'static str,
    },
    /// Non-finite value (NaN or infinity) encountered during coordinate conversion
    #[error(
        "Non-finite value (NaN or infinity) at coordinate index {coordinate_index}: {coordinate_value}"
    )]
    NonFiniteValue {
        /// Index of the coordinate that contains the non-finite value
        coordinate_index: usize,
        /// Non-finite coordinate value.
        coordinate_value: InvalidCoordinateValue,
    },
    /// A predicate received the wrong number of points for a D-dimensional simplex.
    #[error(
        "Invalid simplex point count for dimension {dimension}: expected {expected}, got {actual}"
    )]
    InvalidSimplexPointCount {
        /// Number of points provided.
        actual: usize,
        /// Number of points required to form a D-dimensional simplex.
        expected: usize,
        /// Dimension of the simplex.
        dimension: usize,
    },
    /// A predicate received a simplex whose geometry cannot determine a sign.
    #[error("Degenerate simplex in dimension {dimension}: {reason}")]
    DegenerateSimplex {
        /// Dimension of the degenerate simplex.
        dimension: usize,
        /// Structured reason the simplex was classified as degenerate.
        reason: DegenerateSimplexReason,
    },
    /// Strict robust-insphere consistency check failed.
    #[error("Insphere consistency check failed: {details}")]
    InsphereInconsistency {
        /// Debug representation of simplex points participating in the check.
        simplex_points: String,
        /// Debug representation of the test point participating in the check.
        test_point: String,
        /// Detailed inconsistency message.
        details: String,
    },
    /// A runtime-dispatched stack matrix exceeded the supported dimension.
    #[error("Unsupported stack matrix dimension {requested} (maximum supported is {max})")]
    UnsupportedMatrixDimension {
        /// Requested matrix dimension.
        requested: usize,
        /// Maximum supported matrix dimension.
        max: usize,
    },
    /// Internal matrix dispatch requested an active block whose size does not
    /// match the concrete stack matrix.
    ///
    /// Public predicate APIs surface this as a typed error rather than silently
    /// classifying structurally invalid predicate state as degenerate geometry.
    #[error(
        "Active matrix block size {active} does not match concrete matrix dimension {matrix_dimension}"
    )]
    MatrixDimensionMismatch {
        /// Requested active matrix dimension.
        active: usize,
        /// Concrete matrix dimension.
        matrix_dimension: usize,
    },
    /// A linear algebra backend operation failed.
    #[error("Linear algebra failure: {source}")]
    LinearAlgebraFailure {
        /// Typed source error from the linear algebra backend.
        #[source]
        source: LaError,
    },
    /// Matrix operation failed while building or inspecting a predicate matrix.
    #[error("Matrix error: {source}")]
    MatrixError {
        /// Typed source error from matrix operations.
        #[from]
        source: MatrixError,
    },
}

impl From<StackMatrixDispatchError> for CoordinateConversionError {
    fn from(source: StackMatrixDispatchError) -> Self {
        match source {
            StackMatrixDispatchError::UnsupportedDim { k, max } => {
                Self::UnsupportedMatrixDimension { requested: k, max }
            }
            StackMatrixDispatchError::ActiveBlockDimensionMismatch { k, dim } => {
                Self::MatrixDimensionMismatch {
                    active: k,
                    matrix_dimension: dim,
                }
            }
            StackMatrixDispatchError::La { source } => Self::LinearAlgebraFailure { source },
            StackMatrixDispatchError::Matrix { source } => Self::MatrixError { source },
        }
    }
}

impl From<LaError> for CoordinateConversionError {
    fn from(source: LaError) -> Self {
        Self::from(StackMatrixDispatchError::from(source))
    }
}

/// Errors that can occur during coordinate validation.
///
/// # Examples
///
/// ```rust
/// use delaunay::prelude::geometry::{CoordinateValidationError, InvalidCoordinateValue};
///
/// let err = CoordinateValidationError::InvalidCoordinate {
///     coordinate_index: 1,
///     coordinate_value: InvalidCoordinateValue::Nan,
///     dimension: 3,
/// };
/// std::assert_matches!(err, CoordinateValidationError::InvalidCoordinate { .. });
/// ```
#[derive(Clone, Debug, thiserror::Error, PartialEq, Eq)]
#[non_exhaustive]
pub enum CoordinateValidationError {
    /// A coordinate value is invalid (NaN or infinite).
    #[error(
        "Invalid coordinate at index {coordinate_index} in dimension {dimension}: {coordinate_value}"
    )]
    InvalidCoordinate {
        /// Index of the invalid coordinate.
        coordinate_index: usize,
        /// Non-finite coordinate value.
        coordinate_value: InvalidCoordinateValue,
        /// The dimensionality of the coordinate system.
        dimension: usize,
    },
}

/// Default tolerance for f64 floating-point comparisons.
///
/// This value is set to 1e-15, which is appropriate for f64 precision and provides
/// a reasonable margin for floating-point comparison errors.
pub const DEFAULT_TOLERANCE_F64: f64 = 1e-15;

// =============================================================================
// SUPPORTING TRAITS
// =============================================================================

/// Helper trait for checking finiteness of coordinates.
///
/// This trait provides a unified interface for checking whether a numeric value
/// is finite (not NaN or infinite). It's primarily used to validate coordinate
/// values in geometric types like points and vectors.
///
/// # Examples
///
/// ```
/// use delaunay::prelude::geometry::FiniteCheck;
///
/// let valid_value = 3.14f64;
/// assert!(valid_value.is_finite_generic());
///
/// let invalid_nan = f64::NAN;
/// assert!(!invalid_nan.is_finite_generic());
///
/// let invalid_inf = f64::INFINITY;
/// assert!(!invalid_inf.is_finite_generic());
/// ```
pub trait FiniteCheck {
    /// Returns true if the value is finite (not NaN or infinite).
    ///
    /// This method provides a consistent way to check finiteness for the
    /// supported floating-point coordinate scalar, where `NaN` and infinity
    /// values are possible.
    ///
    /// # Returns
    ///
    /// - `true` if the value is finite
    /// - `false` if the value is NaN, positive infinity, or negative infinity
    ///
    /// # Examples
    ///
    /// ```
    /// use delaunay::prelude::geometry::FiniteCheck;
    ///
    /// // Valid finite values
    /// assert!(1.0f64.is_finite_generic());
    /// assert!((-42.5f64).is_finite_generic());
    /// assert!(0.0f64.is_finite_generic());
    /// assert!(f64::MAX.is_finite_generic());
    /// assert!(f64::MIN.is_finite_generic());
    ///
    /// // Invalid non-finite values
    /// assert!(!f64::NAN.is_finite_generic());
    /// assert!(!f64::INFINITY.is_finite_generic());
    /// assert!(!f64::NEG_INFINITY.is_finite_generic());
    /// ```
    fn is_finite_generic(&self) -> bool;
}

// Unified macro for implementing FiniteCheck for floating-point types
macro_rules! impl_finite_check {
    (float: $($t:ty),*) => {
        $(
            impl FiniteCheck for $t {
                #[inline(always)]
                fn is_finite_generic(&self) -> bool {
                    self.is_finite()
                }
            }
        )*
    };
}

// Implement FiniteCheck for the supported coordinate scalar.
impl_finite_check!(float: f64);

/// Helper trait for OrderedFloat-based equality comparison that handles NaN properly.
///
/// This trait provides a way to compare floating-point numbers that treats
/// NaN values as equal to themselves, which is different from the default
/// floating-point equality comparison where NaN != NaN.
///
/// # Examples
///
/// ```
/// use delaunay::prelude::geometry::OrderedEq;
///
/// // Normal values work as expected
/// assert!(1.0f64.ordered_eq(&1.0f64));
/// assert!(!1.0f64.ordered_eq(&2.0f64));
///
/// // NaN values are treated as equal to themselves
/// assert!(f64::NAN.ordered_eq(&f64::NAN));
///
/// // Infinity values work correctly
/// assert!(f64::INFINITY.ordered_eq(&f64::INFINITY));
/// assert!(f64::NEG_INFINITY.ordered_eq(&f64::NEG_INFINITY));
/// assert!(!f64::INFINITY.ordered_eq(&f64::NEG_INFINITY));
/// assert!(0.0f64.ordered_eq(&(-0.0f64))); // 0.0 == -0.0
/// ```
pub trait OrderedEq {
    /// Compares two values for equality using ordered comparison semantics.
    ///
    /// This method provides a way to compare floating-point numbers that treats
    /// NaN values as equal to themselves, which is different from the default
    /// floating-point equality comparison where NaN != NaN.
    ///
    /// # Arguments
    ///
    /// * `other` - The other value to compare with
    ///
    /// # Returns
    ///
    /// Returns `true` if the values are equal according to ordered comparison,
    /// `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```
    /// use delaunay::prelude::geometry::OrderedEq;
    ///
    /// // Standard comparisons
    /// assert!(1.0f64.ordered_eq(&1.0f64));
    /// assert!(!1.0f64.ordered_eq(&2.0f64));
    ///
    /// // NaN comparison (key difference from standard ==)
    /// assert!(f64::NAN.ordered_eq(&f64::NAN)); // This is true!
    ///
    /// // Zero comparisons
    /// assert!(0.0f64.ordered_eq(&(-0.0f64))); // 0.0 == -0.0
    /// ```
    fn ordered_eq(&self, other: &Self) -> bool;
}

// Unified macro for implementing OrderedEq
macro_rules! impl_ordered_eq {
    (float: $($t:ty),*) => {
        $(
            impl OrderedEq for $t {
                #[inline(always)]
                fn ordered_eq(&self, other: &Self) -> bool {
                    OrderedFloat(*self) == OrderedFloat(*other)
                }
            }
        )*
    };
}

// Implement OrderedEq for the supported coordinate scalar.
impl_ordered_eq!(float: f64);

/// Helper trait for OrderedFloat-based partial comparison that handles NaN properly.
///
/// This trait provides a way to compare floating-point numbers using `OrderedFloat`
/// semantics, which ensures consistent ordering even with special values like NaN
/// and infinity. This is different from the default floating-point comparison where
/// NaN comparisons always return None.
///
/// # Examples
///
/// ```
/// use delaunay::prelude::geometry::OrderedCmp;
/// use std::cmp::Ordering;
///
/// // Normal values work as expected
/// assert_eq!(1.0f64.ordered_partial_cmp(&2.0f64), Some(Ordering::Less));
/// assert_eq!(2.0f64.ordered_partial_cmp(&1.0f64), Some(Ordering::Greater));
/// assert_eq!(1.0f64.ordered_partial_cmp(&1.0f64), Some(Ordering::Equal));
///
/// // NaN values have consistent ordering
/// assert_eq!(f64::NAN.ordered_partial_cmp(&f64::NAN), Some(Ordering::Equal));
/// assert_eq!(f64::NAN.ordered_partial_cmp(&1.0f64), Some(Ordering::Greater)); // NaN > all other values in OrderedFloat
/// assert_eq!(1.0f64.ordered_partial_cmp(&f64::NAN), Some(Ordering::Less));
///
/// // Infinity values work correctly
/// assert_eq!(f64::INFINITY.ordered_partial_cmp(&f64::NEG_INFINITY), Some(Ordering::Greater));
/// assert_eq!(f64::NEG_INFINITY.ordered_partial_cmp(&1.0f64), Some(Ordering::Less));
/// ```
pub trait OrderedCmp {
    /// Performs a partial comparison using `OrderedFloat` semantics.
    ///
    /// This method provides consistent comparison results for all floating-point
    /// values, including NaN and infinity. Unlike standard floating-point
    /// `partial_cmp` which returns None for NaN comparisons, this method always
    /// returns Some(Ordering) by using `OrderedFloat`'s total ordering.
    ///
    /// # Arguments
    ///
    /// * `other` - The other value to compare with
    ///
    /// # Returns
    ///
    /// Returns Some(Ordering) indicating the relationship between self and other.
    /// In `OrderedFloat` semantics:
    /// - NaN is considered equal to NaN
    /// - NaN is greater than all other values (including positive infinity)
    /// - Normal ordering applies to all other values
    ///
    /// # Examples
    ///
    /// ```
    /// use delaunay::prelude::geometry::OrderedCmp;
    /// use std::cmp::Ordering;
    ///
    /// // Standard comparisons
    /// assert_eq!(1.0f64.ordered_partial_cmp(&2.0f64), Some(Ordering::Less));
    /// assert_eq!(2.0f64.ordered_partial_cmp(&1.0f64), Some(Ordering::Greater));
    ///
    /// // NaN comparison (key difference from standard partial_cmp)
    /// assert_eq!(f64::NAN.ordered_partial_cmp(&f64::NAN), Some(Ordering::Equal));
    ///
    /// // Zero comparisons
    /// assert_eq!(0.0f64.ordered_partial_cmp(&(-0.0f64)), Some(Ordering::Equal)); // 0.0 == -0.0
    /// ```
    fn ordered_partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering>;
}

// Unified macro for implementing OrderedCmp
macro_rules! impl_ordered_cmp {
    (float: $($t:ty),*) => {
        $(
            impl OrderedCmp for $t {
                #[inline(always)]
                fn ordered_partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
                    Some(OrderedFloat(*self).cmp(&OrderedFloat(*other)))
                }
            }
        )*
    };
}

// Implement OrderedCmp for the supported coordinate scalar.
impl_ordered_cmp!(float: f64);

/// Helper trait for hashing individual coordinates for non-hashable coordinate scalars.
///
/// This trait provides consistent hashing of floating-point coordinate values,
/// including proper handling of special values like NaN and infinity. It uses
/// `OrderedFloat` internally to ensure that NaN values hash consistently.
///
/// # Examples
///
/// ```
/// use delaunay::prelude::geometry::HashCoordinate;
/// use std::collections::hash_map::DefaultHasher;
/// use std::hash::Hasher;
///
///     // NaN values hash consistently
///     let mut hasher1 = DefaultHasher::new();
///     let mut hasher2 = DefaultHasher::new();
///     f64::NAN.hash_scalar(&mut hasher1);
///
///     f64::NAN.hash_scalar(&mut hasher2);
///
///     assert_eq!(hasher1.finish(), hasher2.finish());
/// ```
pub trait HashCoordinate {
    /// Hashes a single coordinate value using the provided hasher.
    ///
    /// This method provides a consistent way to hash coordinate values,
    /// including the supported floating-point coordinate scalar, which does not
    /// normally implement [`Hash`]. For `f64`, this uses [`OrderedFloat`] to
    /// ensure consistent hashing behavior, including proper handling of `NaN`
    /// values.
    ///
    /// # Arguments
    ///
    /// * `state` - The hasher state to write the hash value to
    ///
    /// # Examples
    ///
    /// ```
    /// use delaunay::prelude::geometry::HashCoordinate;
    /// use std::collections::hash_map::DefaultHasher;
    /// use std::hash::Hasher;
    ///
    ///     // Hash a normal floating-point value
    ///     let mut hasher = DefaultHasher::new();
    ///     let value = 42.0f64;
    ///     value.hash_scalar(&mut hasher);
    ///     let hash1 = hasher.finish();
    ///
    ///     // Hash the same value again
    ///     let mut hasher = DefaultHasher::new();
    ///     let value = 42.0f64;
    ///     value.hash_scalar(&mut hasher);
    ///     let hash2 = hasher.finish();
    ///
    ///     assert_eq!(hash1, hash2); // Same values produce same hash
    ///
    ///     // NaN values also hash consistently
    ///     let mut hasher1 = DefaultHasher::new();
    ///     let mut hasher2 = DefaultHasher::new();
    ///     f64::NAN.hash_scalar(&mut hasher1);
    ///     f64::NAN.hash_scalar(&mut hasher2);
    ///     assert_eq!(hasher1.finish(), hasher2.finish());
    /// ```
    fn hash_scalar<H: Hasher>(&self, state: &mut H);
}

// Unified macro for implementing HashCoordinate
macro_rules! impl_hash_coordinate {
    (float: $($t:ty),*) => {
        $(
            impl HashCoordinate for $t {
                #[inline(always)]
                fn hash_scalar<H: Hasher>(&self, state: &mut H) {
                    OrderedFloat(*self).hash(state);
                }
            }
        )*
    };
}

// Implement HashCoordinate for the supported coordinate scalar.
impl_hash_coordinate!(float: f64);

/// Number of mantissa digits in the supported `f64` coordinate scalar.
pub const F64_MANTISSA_DIGITS: u32 = f64::MANTISSA_DIGITS;

/// Storage and formatting requirements for coordinate container types.
///
/// This names the representation contract separately from geometric scalar
/// arithmetic, so APIs that only store, copy, or serialize coordinates can use
/// a narrower bound than the full [`Coordinate`] interface.
pub trait CoordinateRepresentation: Copy + Default + Debug + Serialize + DeserializeOwned {}

impl<T> CoordinateRepresentation for T where T: Copy + Default + Debug + Serialize + DeserializeOwned
{}

/// Identity and ordering requirements for coordinate container types.
///
/// This names the comparison/hash contract separately from validation and
/// arithmetic, which keeps map/set requirements explicit at call sites.
pub trait CoordinateIdentity: Eq + Hash + PartialOrd {}

impl<T> CoordinateIdentity for T where T: Eq + Hash + PartialOrd {}

/// Coordinate storage and access over the supported `f64` scalar model.
///
/// This trait provides the coordinate operations used by geometric code without
/// forcing unrelated serde, formatting, hash, or ordering bounds onto every
/// implementation. APIs that need those contracts should add
/// [`CoordinateRepresentation`] or [`CoordinateIdentity`] explicitly.
///
/// # Type Parameters
///
/// * `const D: usize` - The dimension of the coordinate system
///
/// # Required Functionality
///
/// The trait requires implementors to support coordinate access, validation,
/// hashing, ordered equality, and origin creation over finite `f64`
/// coordinates.
///
/// # Examples
///
/// ```
/// use delaunay::prelude::geometry::{Coordinate, Point};
///
/// # fn main() -> Result<(), delaunay::prelude::geometry::CoordinateConversionError> {
/// // Create coordinates using Point (which implements Coordinate)
/// let coord1: Point<3> = Point::try_from([1.0, 2.0, 3.0])?;
/// let coord2: Point<3> = Point::try_from([1.0, 2.0, 3.0])?;
///
/// // f64 coordinates implement the coordinate trait
/// assert_eq!(coord1.dim(), 3);
/// assert_eq!(coord1.to_array(), [1.0, 2.0, 3.0]);
/// assert_eq!(coord1, coord2);
///
/// // Validate coordinates
/// assert!(coord1.validate().is_ok());
///
/// // Create origin coordinate
/// let origin: Point<3> = Point::origin();
/// assert_eq!(origin.to_array(), [0.0, 0.0, 0.0]);
/// # Ok(())
/// # }
/// ```
///
/// # Future Storage Implementations
///
/// The trait is designed to support various storage mechanisms:
///
/// ```
/// // Example of how future implementations could work:
/// use delaunay::prelude::geometry::{Coordinate, Point};
/// use std::collections::HashMap;
///
/// # fn main() -> Result<(), delaunay::prelude::geometry::CoordinateConversionError> {
/// // Current Point implementation uses arrays
/// let point_coord: Point<2> = Point::try_from([1.0, 2.0])?;
/// assert_eq!(point_coord.dim(), 2);
/// assert_eq!(point_coord.to_array(), [1.0, 2.0]);
///
/// // Future implementations could use other storage types
/// // while maintaining the same Coordinate trait interface
/// # Ok(())
/// # }
/// ```
pub trait Coordinate<const D: usize>: Sized {
    /// Get the dimensionality of the coordinate system.
    ///
    /// # Returns
    ///
    /// The number of dimensions (D) in the coordinate system.
    ///
    /// # Examples
    ///
    /// ```
    /// use delaunay::prelude::geometry::{Coordinate, Point};
    ///
    /// # fn main() -> Result<(), delaunay::prelude::geometry::CoordinateConversionError> {
    /// let coord: Point<3> = Point::try_from([1.0, 2.0, 3.0])?;
    /// assert_eq!(coord.dim(), 3);
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    fn dim(&self) -> usize {
        D
    }

    /// Try to create a new coordinate from an array of scalar values.
    ///
    /// # Arguments
    ///
    /// * `coords` - Array of `f64` coordinates with dimension D
    ///
    /// # Returns
    ///
    /// A new coordinate instance with the specified values.
    ///
    /// # Errors
    ///
    /// Returns [`CoordinateValidationError`] if the raw coordinate values violate
    /// the coordinate type's storage invariants.
    fn try_new(coords: [f64; D]) -> Result<Self, CoordinateValidationError>;

    /// Convert the coordinate to an array of scalar values.
    ///
    /// # Returns
    ///
    /// An array containing the coordinate values.
    #[must_use]
    fn to_array(&self) -> [f64; D];

    /// Get a specific coordinate by index.
    ///
    /// # Arguments
    ///
    /// * `index` - The index of the coordinate to retrieve (0-based)
    ///
    /// # Returns
    ///
    /// The coordinate value at the specified index, or None if index is out of bounds.
    ///
    /// # Examples
    ///
    /// ```
    /// use delaunay::prelude::geometry::{Coordinate, Point};
    ///
    /// # fn main() -> Result<(), delaunay::prelude::geometry::CoordinateConversionError> {
    /// let coord: Point<3> = Point::try_from([1.0, 2.0, 3.0])?;
    /// assert_eq!(coord.get(0), Some(1.0));
    /// assert_eq!(coord.get(3), None);
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    fn get(&self, index: usize) -> Option<f64>;

    /// Create a coordinate at the origin (all zeros).
    ///
    /// # Returns
    ///
    /// A new coordinate with all values set to zero.
    ///
    /// # Examples
    ///
    /// ```
    /// use delaunay::prelude::geometry::{Coordinate, Point};
    ///
    /// let origin: Point<3> = Coordinate::origin();
    /// assert_eq!(origin.to_array(), [0.0, 0.0, 0.0]);
    /// ```
    #[must_use]
    fn origin() -> Self {
        Self::try_new([0.0; D]).expect("zero coordinates satisfy Coordinate::origin")
    }

    /// Validate that all coordinate values are finite.
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` if all coordinates are finite (not NaN or infinite),
    /// otherwise returns an error describing which coordinate is invalid.
    ///
    /// # Errors
    ///
    /// Returns `CoordinateValidationError::InvalidCoordinate` if any coordinate
    /// is NaN, infinite, or otherwise not finite. The error includes details about
    /// which coordinate index is invalid, its value, and the coordinate dimension.
    ///
    /// # Examples
    ///
    /// ```
    /// use delaunay::prelude::geometry::{Coordinate, Point};
    ///
    /// # fn main() -> Result<(), delaunay::prelude::geometry::CoordinateConversionError> {
    /// let valid: Point<3> = Point::try_from([1.0, 2.0, 3.0])?;
    /// assert!(valid.validate().is_ok());
    ///
    /// assert!(Point::<3>::try_from([1.0, f64::NAN, 3.0]).is_err());
    /// # Ok(())
    /// # }
    /// ```
    fn validate(&self) -> Result<(), CoordinateValidationError>;

    /// Compute the hash of this coordinate.
    ///
    /// This method provides consistent hashing across different coordinate
    /// implementations, including proper handling of special floating-point values.
    ///
    /// # Arguments
    ///
    /// * `state` - The hasher state to write to
    fn hash_coordinate<H: Hasher>(&self, state: &mut H);

    /// Test equality with another coordinate using ordered comparison.
    ///
    /// This method uses ordered comparison semantics that treat NaN values
    /// as equal to themselves, enabling coordinates with NaN to be used in
    /// hash-based collections.
    ///
    /// # Arguments
    ///
    /// * `other` - The other coordinate to compare with
    ///
    /// # Returns
    ///
    /// True if coordinates are equal using ordered comparison.
    #[must_use]
    fn ordered_equals(&self, other: &Self) -> bool;
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::geometry::point::Point;
    use approx::assert_relative_eq;
    use std::assert_matches;
    use std::collections::{HashSet, hash_map::DefaultHasher};
    use std::error::Error;
    use std::hash::Hasher;

    // Use the global tolerance constants

    #[test]
    fn coordinate_conversion_error_preserves_matrix_error_sources() {
        let matrix_error = MatrixError::OutOfBounds {
            row: 2,
            column: 1,
            dimension: 2,
        };
        let converted = CoordinateConversionError::from(matrix_error.clone());

        assert_eq!(
            converted,
            CoordinateConversionError::MatrixError {
                source: matrix_error
            }
        );
        assert!(converted.source().is_some());
    }

    #[test]
    fn stack_matrix_dispatch_errors_map_to_coordinate_conversion_errors() {
        let unsupported =
            CoordinateConversionError::from(StackMatrixDispatchError::UnsupportedDim {
                k: 8,
                max: 7,
            });
        assert_eq!(
            unsupported,
            CoordinateConversionError::UnsupportedMatrixDimension {
                requested: 8,
                max: 7,
            }
        );

        let mismatch = CoordinateConversionError::from(
            StackMatrixDispatchError::ActiveBlockDimensionMismatch { k: 4, dim: 3 },
        );
        assert_eq!(
            mismatch,
            CoordinateConversionError::MatrixDimensionMismatch {
                active: 4,
                matrix_dimension: 3,
            }
        );

        let matrix_error = MatrixError::OutOfBounds {
            row: 3,
            column: 1,
            dimension: 3,
        };
        let converted = CoordinateConversionError::from(StackMatrixDispatchError::Matrix {
            source: matrix_error.clone(),
        });
        assert_eq!(
            converted,
            CoordinateConversionError::MatrixError {
                source: matrix_error
            }
        );
    }

    #[test]
    fn coordinate_conversion_error_clones_linear_algebra_source() {
        let source = LaError::non_finite_input_matrix(1, 2);
        let converted = CoordinateConversionError::LinearAlgebraFailure { source };

        assert_eq!(converted.clone(), converted);
        assert!(converted.source().is_some());
    }

    #[test]
    fn la_errors_map_to_public_coordinate_conversion_errors() {
        let unsupported = CoordinateConversionError::from(LaError::unsupported_dimension(9, 7));
        assert_eq!(
            unsupported,
            CoordinateConversionError::UnsupportedMatrixDimension {
                requested: 9,
                max: 7,
            }
        );

        let index_error = CoordinateConversionError::from(LaError::index_out_of_bounds(3, 4, 2));
        assert_eq!(
            index_error,
            CoordinateConversionError::MatrixError {
                source: MatrixError::OutOfBounds {
                    row: 3,
                    column: 4,
                    dimension: 2,
                },
            }
        );
    }

    #[test]
    fn degenerate_simplex_reason_display_covers_all_variants() {
        assert_eq!(
            DegenerateSimplexReason::ZeroOrientation.to_string(),
            "zero orientation"
        );
        assert_eq!(
            DegenerateSimplexReason::VanishingSosCofactors.to_string(),
            "vanishing SoS cofactors"
        );
    }

    #[test]
    fn finite_coordinate_value_rejects_non_finite_input() {
        assert_relative_eq!(
            FiniteCoordinateValue::try_new(1.25).unwrap().get(),
            1.25,
            epsilon = f64::EPSILON
        );
        assert_eq!(
            FiniteCoordinateValue::try_new(f64::NAN),
            Err(InvalidCoordinateValue::Nan)
        );
        assert_eq!(
            FiniteCoordinateValue::try_new(f64::INFINITY),
            Err(InvalidCoordinateValue::PositiveInfinity)
        );
        assert_eq!(
            FiniteCoordinateValue::try_new(f64::NEG_INFINITY),
            Err(InvalidCoordinateValue::NegativeInfinity)
        );
    }

    #[test]
    fn finite_coordinate_value_try_from_parses_at_raw_boundary() {
        assert_relative_eq!(
            FiniteCoordinateValue::try_from(-3.5).unwrap().get(),
            -3.5,
            epsilon = f64::EPSILON
        );
        assert_eq!(
            FiniteCoordinateValue::try_from(f64::NEG_INFINITY),
            Err(InvalidCoordinateValue::NegativeInfinity)
        );
    }

    #[test]
    fn invalid_coordinate_value_display_preserves_custom_payload() {
        assert_eq!(
            InvalidCoordinateValue::Other("not finite".to_owned()).to_string(),
            "not finite"
        );
    }

    #[test]
    fn coordinate_conversion_value_parses_raw_f64_at_boundary() {
        assert_matches!(
            CoordinateConversionValue::from_f64(2.5),
            CoordinateConversionValue::Scalar(value)
                if (value.get() - 2.5).abs() < f64::EPSILON
        );
        assert_matches!(
            CoordinateConversionValue::from_f64(f64::NAN),
            CoordinateConversionValue::NonFinite(InvalidCoordinateValue::Nan)
        );
        assert_matches!(
            CoordinateConversionValue::from_f64(f64::INFINITY),
            CoordinateConversionValue::NonFinite(InvalidCoordinateValue::PositiveInfinity)
        );
    }

    #[test]
    fn coordinate_values_preserve_typed_payloads() {
        let coordinates = CoordinateValues::from([2.5, f64::NEG_INFINITY]);

        assert_matches!(
            coordinates.as_slice(),
            [
                CoordinateConversionValue::Scalar(value),
                CoordinateConversionValue::NonFinite(InvalidCoordinateValue::NegativeInfinity)
            ] if (value.get() - 2.5).abs() < f64::EPSILON
        );
        assert_eq!(coordinates.to_string(), "[2.5, -inf]");

        assert_eq!(
            CoordinateConversionValue::from_usize(3),
            CoordinateConversionValue::UnsignedInteger(3)
        );
        assert_eq!(
            coordinates.into_vec(),
            vec![
                CoordinateConversionValue::from_f64(2.5),
                CoordinateConversionValue::NonFinite(InvalidCoordinateValue::NegativeInfinity),
            ]
        );
    }

    #[test]
    fn coordinate_trait_basic_functionality() {
        // Test through Point implementation of Coordinate trait with multiple dimensions.
        let coord: Point<3> = Point::try_new([1.0, 2.0, 3.0]).expect("finite point coordinates");
        assert_eq!(coord.dim(), 3);
        assert_relative_eq!(
            coord.to_array().as_slice(),
            [1.0, 2.0, 3.0].as_slice(),
            epsilon = DEFAULT_TOLERANCE_F64
        );
        assert_relative_eq!(coord.get(0).unwrap(), 1.0, epsilon = DEFAULT_TOLERANCE_F64);
        assert_relative_eq!(coord.get(1).unwrap(), 2.0, epsilon = DEFAULT_TOLERANCE_F64);
        assert_relative_eq!(coord.get(2).unwrap(), 3.0, epsilon = DEFAULT_TOLERANCE_F64);
        assert_eq!(coord.get(3), None);
        assert_eq!(coord.get(10), None);

        // Test with different dimensions
        let coord_single: Point<1> = Point::try_new([42.0]).expect("finite point coordinates");
        assert_eq!(coord_single.dim(), 1);
        assert_relative_eq!(
            coord_single.get(0).unwrap(),
            42.0,
            epsilon = DEFAULT_TOLERANCE_F64
        );
        assert_eq!(coord_single.get(1), None);

        // Test zero-dimensional
        let coord_zero: Point<0> = Point::try_new([]).expect("finite point coordinates");
        assert_eq!(coord_zero.dim(), 0);
        assert_eq!(coord_zero.to_array().len(), 0);
        assert_eq!(coord_zero.get(0), None);
        assert!(coord_zero.validate().is_ok());

        // Test large dimension
        let coord_large: Point<10> =
            Point::try_new([1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0])
                .expect("finite point coordinates");
        assert_eq!(coord_large.dim(), 10);
        assert_eq!(coord_large.get(10), None);
        assert!(coord_large.validate().is_ok());
    }

    #[test]
    fn coordinate_trait_new() {
        // Test new() method
        let coord1: Point<2> = Point::try_new([5.0, 6.0]).expect("finite point coordinates");
        assert_relative_eq!(
            coord1.to_array().as_slice(),
            [5.0, 6.0].as_slice(),
            epsilon = DEFAULT_TOLERANCE_F64
        );

        // Test multiple creations with new()
        let coord2: Point<2> = Point::try_new([5.0, 6.0]).expect("finite point coordinates");
        assert_relative_eq!(
            coord2.to_array().as_slice(),
            [5.0, 6.0].as_slice(),
            epsilon = DEFAULT_TOLERANCE_F64
        );

        // They should be equal
        assert_eq!(coord1, coord2);
    }

    #[test]
    fn coordinate_trait_origin() {
        // Test origin for different dimensions.
        let origin_single: Point<1> = Point::origin();
        assert_relative_eq!(
            origin_single.to_array().as_slice(),
            [0.0].as_slice(),
            epsilon = DEFAULT_TOLERANCE_F64
        );

        let origin_triple: Point<3> = Point::origin();
        assert_relative_eq!(
            origin_triple.to_array().as_slice(),
            [0.0, 0.0, 0.0].as_slice(),
            epsilon = DEFAULT_TOLERANCE_F64
        );

        // Test zero-dimensional edge case
        let origin_zero: Point<0> = Point::origin();
        assert_eq!(origin_zero.to_array().len(), 0);

        // Test large dimension
        let origin_large: Point<10> = Point::origin();
        assert_relative_eq!(
            origin_large.to_array().as_slice(),
            [0.0; 10].as_slice(),
            epsilon = DEFAULT_TOLERANCE_F64
        );
    }

    #[test]
    fn coordinate_trait_validate_comprehensive() {
        // Test valid coordinates
        let valid_cases = [
            ([1.0, 2.0, 3.0], "positive values"),
            ([-1.0, -2.0, -3.0], "negative values"),
            ([0.0, 0.0, 0.0], "zeros"),
            ([1e10, 2e10, 3e10], "large values"),
            ([1e-10, 2e-10, 3e-10], "small values"),
        ];

        for &(coords, description) in &valid_cases {
            let coord: Point<3> = Point::try_new(coords).expect("finite point coordinates");
            assert!(coord.validate().is_ok(), "Valid case failed: {description}");
        }

        // Test invalid coordinates with position and dimension validation
        let invalid_cases = [
            ([f64::NAN, 2.0, 3.0], 0, 3, "NaN at start"),
            ([1.0, f64::NAN, 3.0], 1, 3, "NaN in middle"),
            ([1.0, 2.0, f64::NAN], 2, 3, "NaN at end"),
            ([f64::INFINITY, 2.0, 3.0], 0, 3, "positive infinity"),
            ([1.0, f64::NEG_INFINITY, 3.0], 1, 3, "negative infinity"),
        ];

        for &(coords, expected_index, expected_dim, description) in &invalid_cases {
            let result = Point::<3>::try_new(coords);
            assert!(result.is_err(), "Invalid case should fail: {description}");

            if let Err(CoordinateValidationError::InvalidCoordinate {
                coordinate_index,
                dimension,
                ..
            }) = result
            {
                assert_eq!(
                    coordinate_index, expected_index,
                    "Wrong index for: {description}"
                );
                assert_eq!(
                    dimension, expected_dim,
                    "Wrong dimension for: {description}"
                );
            }
        }

        // Test first invalid coordinate is reported when multiple are invalid
        let multi_invalid = Point::<4>::try_new([f64::NAN, f64::INFINITY, f64::NAN, 1.0]);
        if let Err(CoordinateValidationError::InvalidCoordinate {
            coordinate_index,
            dimension,
            ..
        }) = multi_invalid
        {
            assert_eq!(
                coordinate_index, 0,
                "Should report first invalid coordinate"
            );
            assert_eq!(dimension, 4);
        }

        // Test different dimensions
        let invalid_1d = Point::<1>::try_new([f64::NAN]);
        if let Err(CoordinateValidationError::InvalidCoordinate { dimension, .. }) = invalid_1d {
            assert_eq!(dimension, 1);
        }

        let invalid_5d = Point::<5>::try_new([1.0, 2.0, f64::INFINITY, 4.0, 5.0]);
        if let Err(CoordinateValidationError::InvalidCoordinate {
            coordinate_index,
            dimension,
            ..
        }) = invalid_5d
        {
            assert_eq!(coordinate_index, 2);
            assert_eq!(dimension, 5);
        }
    }

    #[test]
    fn coordinate_trait_hash_coordinate_comprehensive() {
        // Test normal coordinates - same values should produce same hash
        let coord1: Point<3> = Point::try_new([1.0, 2.0, 3.0]).expect("finite point coordinates");
        let coord2: Point<3> = Point::try_new([1.0, 2.0, 3.0]).expect("finite point coordinates");
        let coord3: Point<3> = Point::try_new([1.0, 2.0, 4.0]).expect("finite point coordinates");

        let mut hasher1 = DefaultHasher::new();
        let mut hasher2 = DefaultHasher::new();
        let mut hasher3 = DefaultHasher::new();
        coord1.hash_coordinate(&mut hasher1);
        coord2.hash_coordinate(&mut hasher2);
        coord3.hash_coordinate(&mut hasher3);

        assert_eq!(
            hasher1.finish(),
            hasher2.finish(),
            "Same coordinates should have same hash"
        );
        assert_ne!(
            hasher1.finish(),
            hasher3.finish(),
            "Different coordinates should have different hash"
        );

        assert!(Point::<2>::try_new([f64::NAN, 1.0]).is_err());
        assert!(Point::<2>::try_new([f64::INFINITY, 1.0]).is_err());
    }

    #[test]
    fn coordinate_trait_ordered_equals_comprehensive() {
        // Test normal values
        let coord1: Point<3> = Point::try_new([1.0, 2.0, 3.0]).expect("finite point coordinates");
        let coord2: Point<3> = Point::try_new([1.0, 2.0, 3.0]).expect("finite point coordinates");
        let coord3: Point<3> = Point::try_new([1.0, 2.0, 4.0]).expect("finite point coordinates");
        assert!(coord1.ordered_equals(&coord2));
        assert!(coord2.ordered_equals(&coord1));
        assert!(!coord1.ordered_equals(&coord3));

        assert!(Point::<3>::try_new([f64::NAN, 2.0, 3.0]).is_err());
        assert!(Point::<2>::try_new([f64::INFINITY, 2.0]).is_err());
        assert!(Point::<4>::try_new([f64::NAN, f64::INFINITY, f64::NEG_INFINITY, 1.0]).is_err());
    }

    #[test]
    fn coordinate_validation_error_properties() {
        // Test CoordinateValidationError properties
        let error = CoordinateValidationError::InvalidCoordinate {
            coordinate_index: 1,
            coordinate_value: InvalidCoordinateValue::Nan,
            dimension: 3,
        };

        // Test Debug trait
        let debug_str = format!("{error:?}");
        assert!(debug_str.contains("InvalidCoordinate"));
        assert!(debug_str.contains("coordinate_index: 1"));
        assert!(debug_str.contains("dimension: 3"));

        // Test Display trait (from Error trait)
        let display_str = format!("{error}");
        assert!(display_str.contains("Invalid coordinate at index 1 in dimension 3: NaN"));

        // Test Clone and PartialEq
        let error_clone = error.clone();
        assert_eq!(error, error_clone);

        let different_error = CoordinateValidationError::InvalidCoordinate {
            coordinate_index: 2,
            coordinate_value: InvalidCoordinateValue::PositiveInfinity,
            dimension: 3,
        };
        assert_ne!(error, different_error);
    }

    #[test]
    fn coordinate_default_tolerance_constant() {
        // Test that the tolerance value is reasonable
        assert_relative_eq!(DEFAULT_TOLERANCE_F64, 1e-15_f64, epsilon = f64::EPSILON);

        // Test with f64
        let a_f64 = 1.0f64;
        let b_f64 = 1.0f64 + DEFAULT_TOLERANCE_F64 / 2.0;
        assert!((a_f64 - b_f64).abs() < DEFAULT_TOLERANCE_F64);
    }

    #[test]
    fn coordinate_trait_hash_collision_resistance() {
        // Test that different coordinates produce different hashes (basic collision resistance)
        let mut hashes = HashSet::new();

        // Generate diverse coordinates to test hash distribution
        let test_coords = [
            [1.0, 2.0, 3.0],
            [1.1, 2.0, 3.0],
            [1.0, 2.1, 3.0],
            [1.0, 2.0, 3.1],
            [0.0, 0.0, 0.0],
            [-1.0, -2.0, -3.0],
            [1e10, 1e-10, 0.0],
        ];

        for coords in test_coords {
            let coord: Point<3> = Point::try_new(coords).expect("finite point coordinates");
            let mut hash_builder = DefaultHasher::new();
            coord.hash_coordinate(&mut hash_builder);
            hashes.insert(hash_builder.finish());
        }

        // All test coordinates should produce unique hashes
        assert_eq!(
            hashes.len(),
            test_coords.len(),
            "Hash collision detected in basic test set"
        );
    }

    #[test]
    fn coordinate_constants_correctness() {
        // Test that the tolerance constants are reasonable
        // (These are compile-time constants, so the assertions are about correctness, not runtime behavior)
        const _F64_POSITIVE: () = assert!(DEFAULT_TOLERANCE_F64 > 0.0);

        // Test exact values using relative comparison to avoid float_cmp clippy warnings
        assert_relative_eq!(DEFAULT_TOLERANCE_F64, 1e-15, epsilon = f64::EPSILON);
    }

    #[test]
    fn coordinate_f64_helper_traits_are_consistent() {
        const _: () = assert!(DEFAULT_TOLERANCE_F64 > 0.0);

        let zero = 0.0_f64;
        let nan = f64::NAN;

        assert!(zero.ordered_eq(&0.0));
        assert!(nan.ordered_eq(&f64::NAN));
        assert!(zero.is_finite_generic());
        assert!(!nan.is_finite_generic());
        assert_relative_eq!(f64::default(), 0.0, epsilon = f64::EPSILON);
        assert_eq!(F64_MANTISSA_DIGITS, 53);
    }

    #[test]
    fn coordinate_validation_error_source_trait() {
        // Test that CoordinateValidationError implements source() from std::error::Error
        let error = CoordinateValidationError::InvalidCoordinate {
            coordinate_index: 1,
            coordinate_value: InvalidCoordinateValue::Nan,
            dimension: 3,
        };

        // Test source() method - should return None for this error type
        assert!(error.source().is_none());

        // Test error trait handling without erasing the concrete type.
        assert!(Error::source(&error).is_none());
        assert_eq!(format!("{error}"), error.to_string());
    }

    #[test]
    fn coordinate_trait_dimension_consistency() {
        // Test that dimension is compile-time constant
        const DIM_1D: usize = 1;
        const DIM_7D: usize = 7;

        // Test that dimension methods are consistent across supported coordinate dimensions.

        // Test various dimensions to ensure const generic consistency
        let coord_1d: Point<1> = Point::try_new([42.0]).expect("finite point coordinates");
        assert_eq!(coord_1d.dim(), 1);
        assert_eq!(coord_1d.to_array().len(), 1);

        let coord_7d: Point<7> =
            Point::try_new([1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0]).expect("finite point coordinates");
        assert_eq!(coord_7d.dim(), 7);
        assert_eq!(coord_7d.to_array().len(), 7);

        // Test dimension consistency with compile-time constants
        assert_eq!(coord_1d.dim(), DIM_1D);
        assert_eq!(coord_7d.dim(), DIM_7D);
    }
}