grid1d 0.5.0

#![deny(rustdoc::broken_intra_doc_links)]

//! Topology and index spaces for one-dimensional grids and partitions.
//!
//! This module defines the topological types used to model connectivity and
//! adjacency in a one-dimensional partition:
//!
//! - [`Topology1D`]: topological model (`RealLine` or `Circle`).
//! - [`Side`] and [`IntervalSide`]: left/right side and identification of a
//!   specific interval boundary.
//! - [`IndexSpace1D`] and [`Adjacency1D`]: abstractions for cardinality and
//!   neighbor queries.
//! - [`IntervalIndexSpace1D`] and [`CoordIndexSpace1D`]: concrete index spaces
//!   for intervals and vertices; they implement
//!   [`HasIntervalIdRange`] and [`HasCoordIdRange`] respectively.
//! - [`Grid1DIndexSpaces`]: consistent container for both grid index spaces.
//!
//! # Topological Semantics
//!
//! - [`Topology1D::RealLine`]: boundary elements have no external neighbors.
//! - [`Topology1D::Circle`]: boundary elements are connected periodically
//!   (wrap-around).
//!
//! # Example
//!
//! ```rust
//! use grid1d::{Adjacency1D, Grid1D, Grid1DTrait, intervals::*, scalars::NumIntervals};
//! use try_create::TryNew;
//!
//! let grid = Grid1D::uniform(IntervalClosed::new(0.0, 1.0), NumIntervals::try_new(4).unwrap());
//! let interval_space = grid.index_spaces().interval_index_space();
//!
//! use grid1d::scalars::IntervalId;
//! assert_eq!(interval_space.left_neighbor(&IntervalId::new(0)), None);
//! assert_eq!(interval_space.right_neighbor(&IntervalId::new(0)), Some(IntervalId::new(1)));
//! ```

use crate::{
    CoordId, IntervalId,
    grids::{HasCoordIdRange, traits::HasIntervalIdRange},
    scalars::{IndexId, NumIntervals, PositiveIntTrait, PositiveNumPoints1D},
};
use serde::{Deserialize, Serialize};

//----------------------------------------------------------------------------------------------
pub(crate) mod sealed {
    use crate::intervals::{IntervalLowerClosedUpperOpen, IntervalLowerOpenUpperClosed};
    use num_valid::RealScalar;

    pub trait SupportsCircularTopology {}
    impl<T: RealScalar> SupportsCircularTopology for IntervalLowerClosedUpperOpen<T> {}
    impl<T: RealScalar> SupportsCircularTopology for IntervalLowerOpenUpperClosed<T> {}
}
//----------------------------------------------------------------------------------------------

//------------------------------------------------------------------------------------------------------------------------------
#[derive(Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// Runtime topology model for one-dimensional grids.
///
/// [`Topology1D::RealLine`] represents a non-periodic domain with boundary
/// endpoints, while [`Topology1D::Circle`] represents periodic connectivity
/// where the first and last intervals are neighbors.
pub enum Topology1D {
    /// Non-periodic topology on the real line.
    RealLine,
    /// Periodic topology on a circle.
    Circle,
}

impl Topology1D {
    /// Returns `true` if this topology is periodic.
    #[inline(always)]
    pub fn is_periodic(&self) -> bool {
        matches!(self, Topology1D::Circle)
    }
}
//------------------------------------------------------------------------------------------------------------------------------

//------------------------------------------------------------------------------------------------
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
/// Side of an interval with respect to a reference position.
///
/// This enum is primarily used by [`Grid1DTrait`](crate::grids::traits::Grid1DTrait) neighbor APIs
/// to select the left or right adjacent interval.
pub enum Side {
    /// Left side.
    Left,
    /// Right side.
    Right,
}

impl Side {
    /// Returns `true` if the side is [`Side::Left`].
    #[inline(always)]
    pub fn is_left(&self) -> bool {
        matches!(&self, Side::Left)
    }

    /// Returns `true` if the side is [`Side::Right`].
    #[inline(always)]
    pub fn is_right(&self) -> bool {
        matches!(&self, Side::Right)
    }
}
//------------------------------------------------------------------------------------------------

//------------------------------------------------------------------------------------------------------------------------------
/// Trait for types that carry a [`Side`] — i.e. a lower/upper boundary specifier
/// for a fixed normal dimension.
///
/// Implemented by:
/// - [`Side`] itself (the side *is* the data),
/// - [`IntervalSide`] (bundles an interval index with a side).
pub trait HasSide: Copy + Clone + std::fmt::Debug + PartialEq + Eq {
    /// Returns the [`Side`] for this normal dimension.
    fn side(&self) -> Side;
}

impl HasSide for Side {
    #[inline(always)]
    fn side(&self) -> Side {
        *self
    }
}
//------------------------------------------------------------------------------------------------------------------------------

// ================================================================================================
// IntervalSide
// ================================================================================================

/// Bundles an interval index with a [`Side`], identifying one boundary of a specific interval.
///
/// Used to reference a particular boundary point of a grid interval: either the
/// lower vertex ([`Side::Left`]) or the upper vertex ([`Side::Right`]).
///
/// # Coordinate Convention
///
/// Given element index `k` along a normal axis:
///
/// | `side`                | point coordinate (`coord_index`) |
/// |-----------------------|----------------------------------|
/// | [`Side::Left`]  | `k`                              |
/// | [`Side::Right`]  | `k + 1`                          |
///
/// # Example
///
/// ```rust
/// use grid1d::{Side, IntervalSide};
///
/// let left = IntervalSide::new(3, Side::Left);
/// assert_eq!(left.interval_index(), 3);
/// assert_eq!(left.coord_index(), 3); // lower vertex of interval 3
///
/// let right = IntervalSide::new(3, Side::Right);
/// assert_eq!(right.interval_index(), 3);
/// assert_eq!(right.coord_index(), 4); // upper vertex of interval 3
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct IntervalSide {
    /// The interval index along this normal dimension.
    pub interval_index: usize,
    /// Which boundary of interval `interval_index` the restriction touches.
    pub side: Side,
}

impl IntervalSide {
    /// Creates a new [`IntervalSide`] from an interval (interval) index and a [`Side`].
    ///
    /// # Parameters
    ///
    /// - `interval_index`: zero-based interval index along the normal dimension.
    /// - `side`: which boundary of that interval the restriction touches.
    #[inline(always)]
    pub fn new(interval_index: usize, side: Side) -> Self {
        Self {
            interval_index,
            side,
        }
    }

    /// Returns the point (vertex) coordinate index for this restriction along this dimension.
    ///
    /// - [`Side::Left`] → `interval_index` (lower vertex of interval `k`).
    /// - [`Side::Right`] → `interval_index + 1` (upper vertex of interval `k`).
    #[inline(always)]
    pub fn coord_index(&self) -> usize {
        match self.side {
            Side::Left => self.interval_index,
            Side::Right => self.interval_index + 1,
        }
    }

    /// Returns the zero-based interval index along this normal dimension.
    #[inline(always)]
    pub fn interval_index(&self) -> usize {
        self.interval_index
    }
}

impl HasSide for IntervalSide {
    #[inline(always)]
    fn side(&self) -> Side {
        self.side
    }
}
//------------------------------------------------------------------------------------------------------------------------------

//--------------------------------------------------------------------------------------------------------
/// Left and right neighbors of an element in a 1D index space.
///
/// Returned by [`Adjacency1D::neighbors`]. Each field is `None` when the
/// element has no neighbor in that direction (boundary of a
/// [`Topology1D::RealLine`] index space), or `Some(id)` with the typed
/// neighbor identifier (always present for [`Topology1D::Circle`]).
///
/// The type parameter `Id` matches [`IndexSpace1D::Id`] of the concrete
/// index space: [`IntervalId`] for
/// [`IntervalIndexSpace1D`] and [`CoordId`] for
/// [`CoordIndexSpace1D`].
///
/// # Example
///
/// ```rust
/// use grid1d::{Grid1D, Adjacency1D, IndexSpace1D, Grid1DTrait, intervals::*, scalars::{NumIntervals, IntervalId}};
/// use try_create::TryNew;
///
/// let grid = Grid1D::uniform(IntervalClosed::new(0.0, 1.0), NumIntervals::try_new(4).unwrap());
/// let neighbors = grid.index_spaces().interval_index_space().neighbors(&IntervalId::new(2));
/// assert_eq!(neighbors.left(), Some(IntervalId::new(1)));
/// assert_eq!(neighbors.right(), Some(IntervalId::new(3)));
///
/// // Boundary element: no left neighbor on the real line
/// let boundary = grid.index_spaces().interval_index_space().neighbors(&IntervalId::new(0));
/// assert_eq!(boundary.left(), None);
/// assert_eq!(boundary.right(), Some(IntervalId::new(1)));
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct Neighbors1D<Id> {
    /// The left neighbor, or `None` if there is no left neighbor (boundary).
    left: Option<Id>,

    /// The right neighbor, or `None` if there is no right neighbor (boundary).
    right: Option<Id>,
}

impl<Id: Copy> Neighbors1D<Id> {
    /// Returns the left neighbor, if it exists.
    #[inline(always)]
    pub fn left(&self) -> Option<Id> {
        self.left
    }

    /// Returns the right neighbor, if it exists.
    #[inline(always)]
    pub fn right(&self) -> Option<Id> {
        self.right
    }
}
//--------------------------------------------------------------------------------------------------------

//--------------------------------------------------------------------------------------------------------
/// An index space along one dimension: associates a count of elements with a [`Topology1D`].
///
/// Implemented by [`CoordIndexSpace1D`] (for grid vertices) and
/// [`IntervalIndexSpace1D`] (for grid intervals).
pub trait IndexSpace1D {
    /// The newtype counter for this index space (e.g. [`PositiveNumPoints1D`] or [`NumIntervals`]).
    type Counter: PositiveIntTrait;

    /// The typed identifier used to address individual elements of this index space.
    ///
    /// - [`IntervalId`] for [`IntervalIndexSpace1D`]
    /// - [`CoordId`] for [`CoordIndexSpace1D`]
    type Id: IndexId;

    /// Returns the topology of this index space.
    fn topology(&self) -> &Topology1D;

    /// Returns the number of elements in this index space.
    fn count(&self) -> Self::Counter;

    /// Returns the first (leftmost) valid ID in this index space.
    fn first_id(&self) -> Self::Id;

    /// Returns the last (rightmost) valid ID in this index space.
    fn last_id(&self) -> Self::Id;
}
//--------------------------------------------------------------------------------------------------------

//--------------------------------------------------------------------------------------------------------
/// Neighbor queries for a one-dimensional index space.
///
/// Provides [`left_neighbor`](Adjacency1D::left_neighbor),
/// [`right_neighbor`](Adjacency1D::right_neighbor) and the combined
/// [`neighbors`](Adjacency1D::neighbors) query.
/// Boundary behaviour depends on the [`Topology1D`]:
/// - [`Topology1D::RealLine`]: returns `None` at the boundaries.
/// - [`Topology1D::Circle`]: wraps around (periodic).
pub trait Adjacency1D: IndexSpace1D {
    /// Returns the neighbor of `id` on the given `side`, or `None` if out of bounds.
    fn neighbor(&self, id: &Self::Id, side: &Side) -> Option<Self::Id> {
        match side {
            Side::Left => self.left_neighbor(id),
            Side::Right => self.right_neighbor(id),
        }
    }

    /// Returns the left neighbor of `id`, or `None` if `id` is the leftmost
    /// element in a [`Topology1D::RealLine`] index space.
    ///
    /// For [`Topology1D::Circle`], wraps around periodically.
    ///
    /// # Panics (debug only)
    ///
    /// Panics if `id` is outside the valid range `[first_id, last_id]` — callers
    /// are responsible for passing valid IDs.
    fn left_neighbor(&self, id: &Self::Id) -> Option<Self::Id> {
        let first = *self.first_id().as_ref();
        let last = *self.last_id().as_ref();
        let raw = *id.as_ref();
        more_asserts::debug_assert_ge!(raw, first, "ID {} is below first_id {}", raw, first);
        more_asserts::debug_assert_le!(raw, last, "ID {} is above last_id {}", raw, last);
        if raw == first {
            match self.topology() {
                Topology1D::RealLine => None,
                Topology1D::Circle => Some(self.last_id()),
            }
        } else {
            Some(Self::Id::new(raw - 1))
        }
    }

    /// Returns the right neighbor of `id`, or `None` if `id` is the rightmost
    /// element in a [`Topology1D::RealLine`] index space.
    ///
    /// For [`Topology1D::Circle`], wraps around periodically.
    ///
    /// # Panics (debug only)
    ///
    /// Panics if `id` is outside the valid range `[first_id, last_id]` — callers
    /// are responsible for passing valid IDs.
    fn right_neighbor(&self, id: &Self::Id) -> Option<Self::Id> {
        let first = *self.first_id().as_ref();
        let last = *self.last_id().as_ref();
        let raw = *id.as_ref();
        more_asserts::debug_assert_ge!(raw, first, "ID {} is below first_id {}", raw, first);
        more_asserts::debug_assert_le!(raw, last, "ID {} is above last_id {}", raw, last);
        if raw == last {
            match self.topology() {
                Topology1D::RealLine => None,
                Topology1D::Circle => Some(self.first_id()),
            }
        } else {
            Some(Self::Id::new(raw + 1))
        }
    }

    /// Returns both neighbors of `id` as a [`Neighbors1D`].
    ///
    /// Equivalent to calling [`left_neighbor`](Adjacency1D::left_neighbor) and
    /// [`right_neighbor`](Adjacency1D::right_neighbor) individually.
    ///
    /// # Panics (debug only)
    ///
    /// Panics if `id` is outside the valid range — callers are responsible for
    /// passing valid IDs.
    fn neighbors(&self, id: &Self::Id) -> Neighbors1D<Self::Id> {
        Neighbors1D {
            left: self.left_neighbor(id),
            right: self.right_neighbor(id),
        }
    }

    /// Returns an iterator over all shared borders as `(left_id, right_id)` pairs.
    ///
    /// Each yielded pair represents two adjacent elements that share a boundary:
    /// - **[`Topology1D::RealLine`]**: yields `n − 1` pairs from
    ///   `(first, first+1)` to `(last-1, last)`.
    /// - **[`Topology1D::Circle`]**: yields `n` pairs, including the
    ///   wrap-around pair `(last, first)`.
    ///
    /// Pairs are produced in ascending order of the left element's ID.
    ///
    /// # Example
    ///
    /// ```rust
    /// use grid1d::{Grid1D, Adjacency1D, Grid1DTrait, intervals::*, scalars::NumIntervals};
    /// use try_create::TryNew;
    ///
    /// let grid = Grid1D::uniform(IntervalClosed::new(0.0, 1.0), NumIntervals::try_new(4).unwrap());
    /// let space = grid.index_spaces().interval_index_space();
    ///
    /// let pairs: Vec<_> = space.connectivity().collect();
    /// assert_eq!(pairs.len(), 3); // 4 intervals → 3 shared borders on RealLine
    /// ```
    fn connectivity(&self) -> impl Iterator<Item = (Self::Id, Self::Id)> + '_ {
        let first = *self.first_id().as_ref();
        let last = *self.last_id().as_ref();
        (first..=last).filter_map(move |raw| {
            let id = Self::Id::new(raw);
            self.right_neighbor(&id).map(|right| (id, right))
        })
    }
}
//--------------------------------------------------------------------------------------------------------

//--------------------------------------------------------------------------------------------------------
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
/// Index space for grid points (vertices) in one dimension.
///
/// Stores the [`Topology1D`] and the first/last [`CoordId`] for the active
/// coordinate range. The range depends on the grid type:
///
/// | Constructor | Topology | `first_coord_id` | `last_coord_id` | Active IDs |
/// |-------------|----------|-----------------|-----------------|------------|
/// | [`new_non_periodic`](CoordIndexSpace1D::new_non_periodic) | `RealLine` | `0` | `n` | `0 ..= n` |
/// | `new_periodic_upper_open_interval` `[0,L)` | `Circle` | `0` | `n−2` | `0 ..= n−2` |
/// | `new_periodic_lower_open_interval` `(0,L]` | `Circle` | `1` | `n−1` | `1 ..= n−1` |
///
/// where `n` is the number of intervals.
///
/// # Periodic ID conventions
///
/// For a periodic grid with `n` intervals the raw coordinate array has `n + 1`
/// entries, but one endpoint is identified with the other:
///
/// - **Upper-open `[0, L)`**: the point at index `n` (value `L`) is identified
///   with the point at index `0` (value `0`), so only IDs `0 ..= n−2` are
///   *distinct*. The last active ID is `n−2` (not `n−1`).
/// - **Lower-open `(0, L]`**: the point at index `0` (value `0`) is identified
///   with the point at index `n` (value `L`), so only IDs `1 ..= n−1` are
///   distinct. The first active ID is `1` (not `0`).
///
/// [`Adjacency1D`] is implemented for this type and respects the non-zero
/// `first_coord_id` when computing wrap-around neighbors.
pub struct CoordIndexSpace1D {
    /// The topology of this index space, which determines adjacency behavior.
    topology: Topology1D,

    first_coord_id: CoordId,
    last_coord_id: CoordId,
}

impl CoordIndexSpace1D {
    /// Creates a non-periodic [`CoordIndexSpace1D`] for a grid with the given number of intervals.
    ///
    /// The coordinate range spans `[0, num_intervals]`, yielding `num_intervals + 1` vertices.
    #[must_use]
    pub fn new_non_periodic(num_intervals: NumIntervals) -> Self {
        Self {
            topology: Topology1D::RealLine,
            first_coord_id: CoordId::new(0),
            last_coord_id: CoordId::new(num_intervals.into_inner()), // n intervals → n+1 points
        }
    }

    /// Creates a periodic [`CoordIndexSpace1D`] for a **upper-open** domain `[0, L)`.
    ///
    /// The active IDs are `0 ..= n−2` (count = `n − 1`).
    /// ID `n−1` is excluded because it would equal `L`, which is identified
    /// with `0` on the circle — having both would duplicate the same point.
    pub(crate) fn new_periodic_upper_open_interval(num_intervals: NumIntervals) -> Self {
        let num_coords = num_intervals.into_inner() + 1;
        Self {
            topology: Topology1D::Circle,
            first_coord_id: CoordId::new(0),
            last_coord_id: CoordId::new(num_coords - 2),
        }
    }

    /// Creates a periodic [`CoordIndexSpace1D`] for a **lower-open** domain `(0, L]`.
    ///
    /// The active IDs are `1 ..= n−1` (count = `n − 1`).
    /// ID `0` is excluded because it would equal `0`, which is identified
    /// with `L` (= ID `n`) on the circle — having both would duplicate the same point.
    pub(crate) fn new_periodic_lower_open_interval(num_intervals: NumIntervals) -> Self {
        let num_coords = num_intervals.into_inner() + 1;
        Self {
            topology: Topology1D::Circle,
            first_coord_id: CoordId::new(1),
            last_coord_id: CoordId::new(num_coords - 1),
        }
    }
}

impl HasCoordIdRange for CoordIndexSpace1D {
    fn first_coord_id(&self) -> CoordId {
        self.first_coord_id
    }

    fn last_coord_id(&self) -> CoordId {
        self.last_coord_id
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
/// Index space for grid intervals (cells) in one dimension.
///
/// Stores the [`Topology1D`] and the total number of intervals.
/// Unlike [`CoordIndexSpace1D`], the interval IDs **always start from `0`**,
/// regardless of topology. With `n` intervals the active range is `0 ..= n−1`
/// in all cases (non-periodic and both periodic variants).
///
/// This uniformity exists because intervals are indexed by position, not by the
/// scalar coordinate of any endpoint. The periodic identification of endpoints
/// only affects the *coordinate* index space, not the interval index space.
///
/// [`Adjacency1D`] is implemented for this type using the default
/// (0-based) wrap-around logic.
pub struct IntervalIndexSpace1D {
    /// The topology of this index space, which determines adjacency behavior.
    topology: Topology1D,

    /// The number of intervals in this index space.
    count: NumIntervals,
}

impl IntervalIndexSpace1D {
    /// Creates a new [`IntervalIndexSpace1D`] with the given topology and interval count.
    ///
    /// - `topology`: [`Topology1D::RealLine`] for non-periodic grids;
    ///   [`Topology1D::Circle`] for periodic grids.
    /// - `count`: total number of intervals (must be ≥ 1).
    ///
    /// The resulting ID range is always `0 ..= count − 1`.
    #[must_use]
    pub fn new(topology: Topology1D, count: NumIntervals) -> Self {
        Self { topology, count }
    }
}

impl HasIntervalIdRange for IntervalIndexSpace1D {
    /// Always returns [`IntervalId`]`(0)`: interval IDs start at `0` regardless of topology.
    fn first_interval_id(&self) -> IntervalId {
        IntervalId::new(0)
    }

    /// Returns [`IntervalId`]`(n − 1)` where `n` is the interval count.
    fn last_interval_id(&self) -> IntervalId {
        IntervalId::new(*self.count.as_ref() - 1)
    }
}

impl IndexSpace1D for CoordIndexSpace1D {
    type Counter = PositiveNumPoints1D;
    type Id = CoordId;

    /// Returns the topology of this index space (the topology determines adjacency behavior).
    fn topology(&self) -> &Topology1D {
        &self.topology
    }

    fn count(&self) -> Self::Counter {
        self.num_coord_ids()
    }

    #[inline(always)]
    fn first_id(&self) -> CoordId {
        self.first_coord_id
    }

    #[inline(always)]
    fn last_id(&self) -> CoordId {
        self.last_coord_id
    }
}

impl IndexSpace1D for IntervalIndexSpace1D {
    type Counter = NumIntervals;
    type Id = IntervalId;

    /// Returns the topology of this index space (the topology determines adjacency behavior).
    fn topology(&self) -> &Topology1D {
        &self.topology
    }

    fn count(&self) -> Self::Counter {
        self.num_intervals()
    }

    #[inline(always)]
    fn first_id(&self) -> IntervalId {
        IntervalId::new(0)
    }

    #[inline(always)]
    fn last_id(&self) -> IntervalId {
        IntervalId::new(*self.count.as_ref() - 1)
    }
}

impl Adjacency1D for CoordIndexSpace1D {}

impl Adjacency1D for IntervalIndexSpace1D {}
//--------------------------------------------------------------------------------------------------------

//--------------------------------------------------------------------------------------------------------
/// Bundles the [`IntervalIndexSpace1D`] and [`CoordIndexSpace1D`] for a 1D grid.
///
/// A 1D grid with `n` intervals has `n+1` points; this struct keeps both
/// index spaces consistent and derived from the same topology.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Grid1DIndexSpaces {
    /// The interval index space for this grid.
    interval_index_space: IntervalIndexSpace1D,

    /// The coordinate (vertex) index space for this grid.
    coord_index_space: CoordIndexSpace1D,
}

impl Grid1DIndexSpaces {
    pub(crate) fn new_non_periodic(num_intervals: NumIntervals) -> Self {
        let interval_index_space = IntervalIndexSpace1D::new(Topology1D::RealLine, num_intervals);
        let coord_index_space = CoordIndexSpace1D::new_non_periodic(num_intervals);
        Self {
            interval_index_space,
            coord_index_space,
        }
    }

    pub(crate) fn new_periodic_upper_open_interval(num_intervals: NumIntervals) -> Self {
        let interval_index_space = IntervalIndexSpace1D::new(Topology1D::Circle, num_intervals);
        let coord_index_space = CoordIndexSpace1D::new_periodic_upper_open_interval(num_intervals);
        Self {
            interval_index_space,
            coord_index_space,
        }
    }

    pub(crate) fn new_periodic_lower_open_interval(num_intervals: NumIntervals) -> Self {
        let topology = Topology1D::Circle;
        let interval_index_space = IntervalIndexSpace1D::new(topology, num_intervals);
        let coord_index_space = CoordIndexSpace1D::new_periodic_lower_open_interval(num_intervals);
        Self {
            interval_index_space,
            coord_index_space,
        }
    }

    /// Returns the interval index space for this grid.
    #[inline(always)]
    pub fn interval_index_space(&self) -> &IntervalIndexSpace1D {
        &self.interval_index_space
    }

    /// Returns the coordinate (vertex) index space for this grid.
    #[inline(always)]
    pub fn coord_index_space(&self) -> &CoordIndexSpace1D {
        &self.coord_index_space
    }

    /// Returns the [`Topology1D`] shared by both index spaces in this container.
    #[inline(always)]
    pub fn topology(&self) -> &Topology1D {
        self.interval_index_space.topology()
    }
}
//--------------------------------------------------------------------------------------------------------

//--------------------------------------------------------------------------------------------------------
#[cfg(test)]
mod tests {
    use super::*;
    use crate::scalars::{CoordId, IntervalId, NumIntervals};
    use try_create::TryNew;

    // ── helpers ──────────────────────────────────────────────────────────────

    fn interval_space(topology: Topology1D, n: usize) -> IntervalIndexSpace1D {
        IntervalIndexSpace1D {
            topology,
            count: NumIntervals::try_new(n).unwrap(),
        }
    }

    mod side {
        use super::*;

        #[test]
        fn side_equality() {
            assert_eq!(Side::Left, Side::Left);
            assert_eq!(Side::Right, Side::Right);
            assert_ne!(Side::Right, Side::Left);
        }

        #[test]
        fn is_left() {
            assert!(Side::Left.is_left());
            assert!(!Side::Right.is_left());
        }

        #[test]
        fn is_right() {
            assert!(Side::Right.is_right());
            assert!(!Side::Left.is_right());
        }

        #[test]
        fn has_side_for_side_returns_self() {
            assert_eq!(Side::Left.side(), Side::Left);
            assert_eq!(Side::Right.side(), Side::Right);
        }

        #[test]
        fn left_point_index() {
            let data_3 = IntervalSide::new(3, Side::Left);
            assert_eq!(data_3.coord_index(), 3);

            let data_0 = IntervalSide::new(0, Side::Left);
            assert_eq!(data_0.coord_index(), 0);
        }

        #[test]
        fn right_point_index() {
            let data_3 = IntervalSide::new(3, Side::Right);
            assert_eq!(data_3.coord_index(), 4);

            let data_0 = IntervalSide::new(0, Side::Right);
            assert_eq!(data_0.coord_index(), 1);
        }

        #[test]
        fn interval_side_interval_index_getter() {
            let s = IntervalSide::new(7, Side::Left);
            assert_eq!(s.interval_index(), 7);

            let s2 = IntervalSide::new(0, Side::Right);
            assert_eq!(s2.interval_index(), 0);
        }

        #[test]
        fn has_side_for_interval_side() {
            let left = IntervalSide::new(2, Side::Left);
            assert_eq!(left.side(), Side::Left);

            let right = IntervalSide::new(5, Side::Right);
            assert_eq!(right.side(), Side::Right);
        }
    }

    // ── Topology1D ───────────────────────────────────────────────────────────
    mod topology {
        use super::*;
        #[test]
        fn topology1d_real_line_eq_self() {
            assert_eq!(Topology1D::RealLine, Topology1D::RealLine);
        }

        #[test]
        fn topology1d_circle_eq_self() {
            assert_eq!(Topology1D::Circle, Topology1D::Circle);
        }

        #[test]
        fn topology1d_real_line_ne_circle() {
            assert_ne!(Topology1D::RealLine, Topology1D::Circle);
        }

        #[test]
        fn topology1d_copy() {
            let t = Topology1D::Circle;
            let t2 = t; // Copy
            assert_eq!(t, t2);
        }

        #[test]
        fn is_periodic_real_line_is_false() {
            assert!(!Topology1D::RealLine.is_periodic());
        }

        #[test]
        fn is_periodic_circle_is_true() {
            assert!(Topology1D::Circle.is_periodic());
        }
    }

    // ── Neighbors1D ──────────────────────────────────────────────────────────
    mod neighbors1d {
        use super::*;

        #[test]
        fn neighbors1d_construction_and_eq() {
            let a = Neighbors1D::<IntervalId> {
                left: Some(IntervalId::new(0)),
                right: Some(IntervalId::new(2)),
            };
            let b = Neighbors1D::<IntervalId> {
                left: Some(IntervalId::new(0)),
                right: Some(IntervalId::new(2)),
            };
            assert_eq!(a, b);
        }

        #[test]
        fn neighbors1d_none_variants() {
            let a = Neighbors1D::<IntervalId> {
                left: None,
                right: None,
            };
            assert_eq!(
                a,
                Neighbors1D::<IntervalId> {
                    left: None,
                    right: None
                }
            );
        }

        #[test]
        fn neighbors1d_copy() {
            let a = Neighbors1D::<IntervalId> {
                left: Some(IntervalId::new(1)),
                right: None,
            };
            let b = a; // Copy
            assert_eq!(a, b);
        }
    }

    // ── IndexSpace1D / count / topology ──────────────────────────────────────

    #[test]
    fn point_index_space_topology_and_count() {
        let s = CoordIndexSpace1D::new_non_periodic(NumIntervals::try_new(4).unwrap());
        assert_eq!(*s.topology(), Topology1D::RealLine);
        assert_eq!(*s.count().as_ref(), 5);
    }

    #[test]
    fn interval_index_space_topology_and_count() {
        let s = interval_space(Topology1D::Circle, 4);
        assert_eq!(*s.topology(), Topology1D::Circle);
        assert_eq!(*s.count().as_ref(), 4);
    }

    // ── Adjacency1D::left_neighbor — Open ────────────────────────────────────

    #[test]
    fn left_neighbor_open_first_element_is_none() {
        let s = interval_space(Topology1D::RealLine, 5);
        assert_eq!(s.left_neighbor(&IntervalId::new(0)), None);
    }

    #[test]
    fn left_neighbor_open_middle() {
        let s = interval_space(Topology1D::RealLine, 5);
        assert_eq!(
            s.left_neighbor(&IntervalId::new(3)),
            Some(IntervalId::new(2))
        );
    }

    #[test]
    fn left_neighbor_open_last_element() {
        let s = interval_space(Topology1D::RealLine, 5);
        assert_eq!(
            s.left_neighbor(&IntervalId::new(4)),
            Some(IntervalId::new(3))
        );
    }

    // ── Adjacency1D::left_neighbor — Periodic ────────────────────────────────

    #[test]
    fn left_neighbor_periodic_first_element_wraps() {
        let s = interval_space(Topology1D::Circle, 5);
        assert_eq!(
            s.left_neighbor(&IntervalId::new(0)),
            Some(IntervalId::new(4))
        );
    }

    #[test]
    fn left_neighbor_periodic_middle() {
        let s = interval_space(Topology1D::Circle, 5);
        assert_eq!(
            s.left_neighbor(&IntervalId::new(2)),
            Some(IntervalId::new(1))
        );
    }

    #[test]
    fn left_neighbor_periodic_last_element() {
        let s = interval_space(Topology1D::Circle, 5);
        assert_eq!(
            s.left_neighbor(&IntervalId::new(4)),
            Some(IntervalId::new(3))
        );
    }

    // ── Adjacency1D::right_neighbor — Open ───────────────────────────────────

    #[test]
    fn right_neighbor_open_first_element() {
        let s = interval_space(Topology1D::RealLine, 5);
        assert_eq!(
            s.right_neighbor(&IntervalId::new(0)),
            Some(IntervalId::new(1))
        );
    }

    #[test]
    fn right_neighbor_open_middle() {
        let s = interval_space(Topology1D::RealLine, 5);
        assert_eq!(
            s.right_neighbor(&IntervalId::new(2)),
            Some(IntervalId::new(3))
        );
    }

    #[test]
    fn right_neighbor_open_last_element_is_none() {
        let s = interval_space(Topology1D::RealLine, 5);
        assert_eq!(s.right_neighbor(&IntervalId::new(4)), None);
    }

    // ── Adjacency1D::right_neighbor — Periodic ───────────────────────────────

    #[test]
    fn right_neighbor_periodic_first_element() {
        let s = interval_space(Topology1D::Circle, 5);
        assert_eq!(
            s.right_neighbor(&IntervalId::new(0)),
            Some(IntervalId::new(1))
        );
    }

    #[test]
    fn right_neighbor_periodic_middle() {
        let s = interval_space(Topology1D::Circle, 5);
        assert_eq!(
            s.right_neighbor(&IntervalId::new(2)),
            Some(IntervalId::new(3))
        );
    }

    #[test]
    fn right_neighbor_periodic_last_element_wraps() {
        let s = interval_space(Topology1D::Circle, 5);
        assert_eq!(
            s.right_neighbor(&IntervalId::new(4)),
            Some(IntervalId::new(0))
        );
    }

    // ── Adjacency1D::neighbors — combined ────────────────────────────────────

    #[test]
    fn neighbors_open_interior() {
        let s = interval_space(Topology1D::RealLine, 5);
        assert_eq!(
            s.neighbors(&IntervalId::new(2)),
            Neighbors1D {
                left: Some(IntervalId::new(1)),
                right: Some(IntervalId::new(3))
            }
        );
    }

    #[test]
    fn neighbors_open_left_boundary() {
        let s = interval_space(Topology1D::RealLine, 5);
        assert_eq!(
            s.neighbors(&IntervalId::new(0)),
            Neighbors1D {
                left: None,
                right: Some(IntervalId::new(1))
            }
        );
    }

    #[test]
    fn neighbors_open_right_boundary() {
        let s = interval_space(Topology1D::RealLine, 5);
        assert_eq!(
            s.neighbors(&IntervalId::new(4)),
            Neighbors1D {
                left: Some(IntervalId::new(3)),
                right: None
            }
        );
    }

    #[test]
    fn neighbors_periodic_wraps_at_boundaries() {
        let s = interval_space(Topology1D::Circle, 5);
        assert_eq!(
            s.neighbors(&IntervalId::new(0)),
            Neighbors1D {
                left: Some(IntervalId::new(4)),
                right: Some(IntervalId::new(1))
            }
        );
        assert_eq!(
            s.neighbors(&IntervalId::new(4)),
            Neighbors1D {
                left: Some(IntervalId::new(3)),
                right: Some(IntervalId::new(0))
            }
        );
    }

    // ── Edge cases: n = 1 ────────────────────────────────────────────────────

    #[test]
    fn neighbors_open_single_element_both_none() {
        let s = interval_space(Topology1D::RealLine, 1);
        assert_eq!(
            s.neighbors(&IntervalId::new(0)),
            Neighbors1D {
                left: None,
                right: None
            }
        );
    }

    #[test]
    fn neighbors_periodic_single_element_wraps_to_itself() {
        let s = interval_space(Topology1D::Circle, 1);
        assert_eq!(
            s.neighbors(&IntervalId::new(0)),
            Neighbors1D {
                left: Some(IntervalId::new(0)),
                right: Some(IntervalId::new(0))
            }
        );
    }

    // ── Adjacency1D::neighbor dispatch ───────────────────────────────────────

    #[test]
    fn neighbor_dispatch_left_and_right_open() {
        let s = interval_space(Topology1D::RealLine, 5);
        assert_eq!(
            s.neighbor(&IntervalId::new(2), &Side::Left),
            s.left_neighbor(&IntervalId::new(2))
        );
        assert_eq!(
            s.neighbor(&IntervalId::new(2), &Side::Right),
            s.right_neighbor(&IntervalId::new(2))
        );
        // boundary cases
        assert_eq!(s.neighbor(&IntervalId::new(0), &Side::Left), None);
        assert_eq!(s.neighbor(&IntervalId::new(4), &Side::Right), None);
    }

    #[test]
    fn neighbor_dispatch_left_and_right_periodic() {
        let s = interval_space(Topology1D::Circle, 4);
        assert_eq!(
            s.neighbor(&IntervalId::new(0), &Side::Left),
            Some(IntervalId::new(3))
        ); // wraps
        assert_eq!(
            s.neighbor(&IntervalId::new(0), &Side::Right),
            Some(IntervalId::new(1))
        );
        assert_eq!(
            s.neighbor(&IntervalId::new(3), &Side::Right),
            Some(IntervalId::new(0))
        ); // wraps
    }

    // ── Constructors ::new ───────────────────────────────────────────────────

    #[test]
    fn point_index_space_new_constructor() {
        let num_intervals = NumIntervals::try_new(7).unwrap();

        let s = CoordIndexSpace1D::new_non_periodic(num_intervals);
        assert_eq!(*s.topology(), Topology1D::RealLine);
        assert_eq!(*s.count().as_ref(), 8); // n intervals → n+1 points
        assert_eq!(s.first_coord_id(), CoordId::new(0));
        assert_eq!(s.last_coord_id(), CoordId::new(7));

        let s = CoordIndexSpace1D::new_periodic_upper_open_interval(num_intervals);
        assert_eq!(*s.topology(), Topology1D::Circle);
        assert_eq!(*s.count().as_ref(), 7);
        assert_eq!(s.first_coord_id(), CoordId::new(0));
        assert_eq!(s.last_coord_id(), CoordId::new(6));

        let s = CoordIndexSpace1D::new_periodic_lower_open_interval(num_intervals);
        assert_eq!(*s.topology(), Topology1D::Circle);
        assert_eq!(*s.count().as_ref(), 7);
        assert_eq!(s.first_coord_id(), CoordId::new(1));
        assert_eq!(s.last_coord_id(), CoordId::new(7));
    }

    #[test]
    fn interval_index_space_new_constructor() {
        let count = NumIntervals::try_new(3).unwrap();
        let s = IntervalIndexSpace1D::new(Topology1D::RealLine, count);
        assert_eq!(*s.topology(), Topology1D::RealLine);
        assert_eq!(*s.count().as_ref(), 3);
    }

    // ── Grid1DIndexSpaces ────────────────────────────────────────────────────

    mod grid1d_index_spaces {
        use super::*;

        #[test]
        fn new_sets_correct_interval_count() {
            let g = Grid1DIndexSpaces::new_non_periodic(NumIntervals::try_new(4).unwrap());
            assert_eq!(*g.interval_index_space().count().as_ref(), 4);
        }

        #[test]
        fn new_sets_point_count_as_n_plus_1() {
            let g = Grid1DIndexSpaces::new_non_periodic(NumIntervals::try_new(4).unwrap());
            assert_eq!(*g.coord_index_space().count().as_ref(), 5);
        }

        #[test]
        fn topology_is_propagated_to_both_spaces() {
            let g = Grid1DIndexSpaces::new_periodic_lower_open_interval(
                NumIntervals::try_new(3).unwrap(),
            );
            assert_eq!(*g.interval_index_space().topology(), Topology1D::Circle);
            assert_eq!(*g.coord_index_space().topology(), Topology1D::Circle);

            let g = Grid1DIndexSpaces::new_periodic_upper_open_interval(
                NumIntervals::try_new(3).unwrap(),
            );
            assert_eq!(*g.interval_index_space().topology(), Topology1D::Circle);
            assert_eq!(*g.coord_index_space().topology(), Topology1D::Circle);
        }

        #[test]
        fn interval_index_space_adjacency_uses_topology() {
            let g = Grid1DIndexSpaces::new_periodic_lower_open_interval(
                NumIntervals::try_new(4).unwrap(),
            );
            // periodic: right of last interval (idx 3) wraps to 0
            assert_eq!(
                g.interval_index_space().right_neighbor(&IntervalId::new(3)),
                Some(IntervalId::new(0))
            );

            let g = Grid1DIndexSpaces::new_periodic_upper_open_interval(
                NumIntervals::try_new(4).unwrap(),
            );
            // periodic: right of last interval (idx 3) wraps to 0
            assert_eq!(
                g.interval_index_space().right_neighbor(&IntervalId::new(3)),
                Some(IntervalId::new(0))
            );
        }

        // ── CoordIndexSpace1D Adjacency1D ─────────────────────────────────
        mod coord_adjacency {
            use super::*;

            // n = 4 intervals throughout

            // Non-periodic: IDs 0..=4
            #[test]
            fn non_periodic_interior() {
                let s = CoordIndexSpace1D::new_non_periodic(NumIntervals::try_new(4).unwrap());
                assert_eq!(s.left_neighbor(&CoordId::new(2)), Some(CoordId::new(1)));
                assert_eq!(s.right_neighbor(&CoordId::new(2)), Some(CoordId::new(3)));
            }

            #[test]
            fn non_periodic_left_boundary_is_none() {
                let s = CoordIndexSpace1D::new_non_periodic(NumIntervals::try_new(4).unwrap());
                assert_eq!(s.left_neighbor(&CoordId::new(0)), None);
            }

            #[test]
            fn non_periodic_right_boundary_is_none() {
                let s = CoordIndexSpace1D::new_non_periodic(NumIntervals::try_new(4).unwrap());
                assert_eq!(s.right_neighbor(&CoordId::new(4)), None);
            }

            // Periodic upper-open [0,1): IDs 0..=3
            #[test]
            fn periodic_upper_open_interior() {
                let s = CoordIndexSpace1D::new_periodic_upper_open_interval(
                    NumIntervals::try_new(4).unwrap(),
                );
                assert_eq!(s.left_neighbor(&CoordId::new(2)), Some(CoordId::new(1)));
                assert_eq!(s.right_neighbor(&CoordId::new(2)), Some(CoordId::new(3)));
            }

            #[test]
            fn periodic_upper_open_left_wraps() {
                let s = CoordIndexSpace1D::new_periodic_upper_open_interval(
                    NumIntervals::try_new(4).unwrap(),
                );
                // first=0, last=3: left of 0 → 3
                assert_eq!(s.left_neighbor(&CoordId::new(0)), Some(CoordId::new(3)));
            }

            #[test]
            fn periodic_upper_open_right_wraps() {
                let s = CoordIndexSpace1D::new_periodic_upper_open_interval(
                    NumIntervals::try_new(4).unwrap(),
                );
                // first=0, last=3: right of 3 → 0
                assert_eq!(s.right_neighbor(&CoordId::new(3)), Some(CoordId::new(0)));
            }

            // Periodic lower-open (0,1]: IDs 1..=4
            #[test]
            fn periodic_lower_open_interior() {
                let s = CoordIndexSpace1D::new_periodic_lower_open_interval(
                    NumIntervals::try_new(4).unwrap(),
                );
                assert_eq!(s.left_neighbor(&CoordId::new(2)), Some(CoordId::new(1)));
                assert_eq!(s.right_neighbor(&CoordId::new(2)), Some(CoordId::new(3)));
            }

            #[test]
            fn periodic_lower_open_left_wraps() {
                let s = CoordIndexSpace1D::new_periodic_lower_open_interval(
                    NumIntervals::try_new(4).unwrap(),
                );
                // first=1, last=4: left of 1 → 4
                assert_eq!(s.left_neighbor(&CoordId::new(1)), Some(CoordId::new(4)));
            }

            #[test]
            fn periodic_lower_open_right_wraps() {
                let s = CoordIndexSpace1D::new_periodic_lower_open_interval(
                    NumIntervals::try_new(4).unwrap(),
                );
                // first=1, last=4: right of 4 → 1
                assert_eq!(s.right_neighbor(&CoordId::new(4)), Some(CoordId::new(1)));
            }

            #[test]
            fn neighbors_combined_non_periodic_interior() {
                let s = CoordIndexSpace1D::new_non_periodic(NumIntervals::try_new(4).unwrap());
                assert_eq!(
                    s.neighbors(&CoordId::new(2)),
                    Neighbors1D {
                        left: Some(CoordId::new(1)),
                        right: Some(CoordId::new(3))
                    }
                );
            }

            #[test]
            fn neighbors_combined_periodic_lower_open_boundary() {
                let s = CoordIndexSpace1D::new_periodic_lower_open_interval(
                    NumIntervals::try_new(4).unwrap(),
                );
                assert_eq!(
                    s.neighbors(&CoordId::new(1)),
                    Neighbors1D {
                        left: Some(CoordId::new(4)),
                        right: Some(CoordId::new(2))
                    }
                );
                assert_eq!(
                    s.neighbors(&CoordId::new(4)),
                    Neighbors1D {
                        left: Some(CoordId::new(3)),
                        right: Some(CoordId::new(1))
                    }
                );
            }

            #[test]
            #[cfg(debug_assertions)]
            #[should_panic]
            fn panics_on_id_above_last() {
                let s = CoordIndexSpace1D::new_non_periodic(NumIntervals::try_new(4).unwrap());
                let _ = s.left_neighbor(&CoordId::new(5)); // last=4: 5 > 4 → panics
            }

            #[test]
            #[cfg(debug_assertions)]
            #[should_panic]
            fn panics_on_id_below_first_lower_open() {
                let s = CoordIndexSpace1D::new_periodic_lower_open_interval(
                    NumIntervals::try_new(4).unwrap(),
                );
                let _ = s.right_neighbor(&CoordId::new(0)); // first=1: 0 < 1 → panics
            }
        }

        #[test]
        fn clone_and_equality() {
            let g1 = Grid1DIndexSpaces::new_periodic_lower_open_interval(
                NumIntervals::try_new(5).unwrap(),
            );
            let g2 = g1.clone();
            assert_eq!(g1, g2);
        }
    }

    // ── debug_assert: out-of-bounds IDs ─────────────────────────────────────
    // These tests run only in debug mode (cargo test compiles with debug_assertions).
    // In release mode the assert is elided, so the tests are excluded via #[cfg].

    #[test]
    #[cfg(debug_assertions)]
    #[should_panic]
    fn left_neighbor_panics_on_out_of_bounds_open() {
        let s = interval_space(Topology1D::RealLine, 5);
        let _ = s.left_neighbor(&IntervalId::new(5)); // id == count → debug_assert fires
    }

    #[test]
    #[cfg(debug_assertions)]
    #[should_panic]
    fn left_neighbor_panics_on_out_of_bounds_periodic() {
        let s = interval_space(Topology1D::Circle, 4);
        let _ = s.left_neighbor(&IntervalId::new(4)); // id == count → debug_assert fires
    }

    #[test]
    #[cfg(debug_assertions)]
    #[should_panic]
    fn left_neighbor_panics_on_far_out_of_bounds() {
        let s = interval_space(Topology1D::RealLine, 3);
        let _ = s.left_neighbor(&IntervalId::new(100));
    }

    #[test]
    #[cfg(debug_assertions)]
    #[should_panic]
    fn right_neighbor_panics_on_out_of_bounds_open() {
        let s = interval_space(Topology1D::RealLine, 5);
        let _ = s.right_neighbor(&IntervalId::new(5)); // id == count → debug_assert fires
    }

    #[test]
    #[cfg(debug_assertions)]
    #[should_panic]
    fn right_neighbor_panics_on_out_of_bounds_periodic() {
        let s = interval_space(Topology1D::Circle, 4);
        let _ = s.right_neighbor(&IntervalId::new(4)); // id == count → debug_assert fires
    }

    #[test]
    #[cfg(debug_assertions)]
    #[should_panic]
    fn right_neighbor_panics_on_far_out_of_bounds() {
        let s = interval_space(Topology1D::RealLine, 3);
        let _ = s.right_neighbor(&IntervalId::new(100));
    }

    // ── Adjacency1D::first_id / last_id ─────────────────────────────────────

    #[test]
    fn interval_space_first_and_last_id() {
        let s = interval_space(Topology1D::RealLine, 5);
        assert_eq!(s.first_id(), IntervalId::new(0));
        assert_eq!(s.last_id(), IntervalId::new(4));
    }

    #[test]
    fn coord_space_non_periodic_first_and_last_id() {
        let s = CoordIndexSpace1D::new_non_periodic(NumIntervals::try_new(4).unwrap());
        assert_eq!(s.first_id(), CoordId::new(0));
        assert_eq!(s.last_id(), CoordId::new(4));
    }

    #[test]
    fn coord_space_periodic_upper_open_first_and_last_id() {
        // [0, L): active IDs 0..=n−2
        let s =
            CoordIndexSpace1D::new_periodic_upper_open_interval(NumIntervals::try_new(4).unwrap());
        assert_eq!(s.first_id(), CoordId::new(0));
        assert_eq!(s.last_id(), CoordId::new(3));
    }

    #[test]
    fn coord_space_periodic_lower_open_first_and_last_id() {
        // (0, L]: active IDs 1..=n−1
        let s =
            CoordIndexSpace1D::new_periodic_lower_open_interval(NumIntervals::try_new(4).unwrap());
        assert_eq!(s.first_id(), CoordId::new(1));
        assert_eq!(s.last_id(), CoordId::new(4));
    }

    // ── Adjacency1D::connectivity ────────────────────────────────────────────

    #[test]
    fn interval_connectivity_real_line() {
        // n=4: expected pairs (0,1), (1,2), (2,3) — 3 edges
        let s = interval_space(Topology1D::RealLine, 4);
        let pairs: Vec<_> = s.connectivity().collect();
        assert_eq!(
            pairs,
            vec![
                (IntervalId::new(0), IntervalId::new(1)),
                (IntervalId::new(1), IntervalId::new(2)),
                (IntervalId::new(2), IntervalId::new(3)),
            ]
        );
    }

    #[test]
    fn interval_connectivity_circle() {
        // n=4: expected pairs (0,1), (1,2), (2,3), (3,0) — 4 edges
        let s = interval_space(Topology1D::Circle, 4);
        let pairs: Vec<_> = s.connectivity().collect();
        assert_eq!(
            pairs,
            vec![
                (IntervalId::new(0), IntervalId::new(1)),
                (IntervalId::new(1), IntervalId::new(2)),
                (IntervalId::new(2), IntervalId::new(3)),
                (IntervalId::new(3), IntervalId::new(0)), // wrap-around
            ]
        );
    }

    #[test]
    fn interval_connectivity_single_element_real_line() {
        // n=1: no edges on RealLine (only one interval, no shared borders)
        let s = interval_space(Topology1D::RealLine, 1);
        let pairs: Vec<_> = s.connectivity().collect();
        assert!(pairs.is_empty());
    }

    #[test]
    fn interval_connectivity_single_element_circle() {
        // n=1: self-loop (0,0) on Circle
        let s = interval_space(Topology1D::Circle, 1);
        let pairs: Vec<_> = s.connectivity().collect();
        assert_eq!(pairs, vec![(IntervalId::new(0), IntervalId::new(0))]);
    }

    #[test]
    fn coord_connectivity_non_periodic() {
        // 4 intervals → coord IDs 0..=4: pairs (0,1)…(3,4) — 4 edges
        let s = CoordIndexSpace1D::new_non_periodic(NumIntervals::try_new(4).unwrap());
        let pairs: Vec<_> = s.connectivity().collect();
        assert_eq!(pairs.len(), 4);
        assert_eq!(pairs[0], (CoordId::new(0), CoordId::new(1)));
        assert_eq!(pairs[3], (CoordId::new(3), CoordId::new(4)));
    }

    #[test]
    fn coord_connectivity_periodic_upper_open() {
        // 4 intervals, [0,L): active IDs 0..=3, 4 edges including (3,0)
        let s =
            CoordIndexSpace1D::new_periodic_upper_open_interval(NumIntervals::try_new(4).unwrap());
        let pairs: Vec<_> = s.connectivity().collect();
        assert_eq!(pairs.len(), 4);
        assert_eq!(pairs[3], (CoordId::new(3), CoordId::new(0))); // wrap-around
    }

    #[test]
    fn coord_connectivity_periodic_lower_open() {
        // 4 intervals, (0,L]: active IDs 1..=4, 4 edges including (4,1)
        let s =
            CoordIndexSpace1D::new_periodic_lower_open_interval(NumIntervals::try_new(4).unwrap());
        let pairs: Vec<_> = s.connectivity().collect();
        assert_eq!(pairs.len(), 4);
        assert_eq!(pairs[0], (CoordId::new(1), CoordId::new(2)));
        assert_eq!(pairs[3], (CoordId::new(4), CoordId::new(1))); // wrap-around
    }
}