1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
//! Grid operations for transformation, combination, and refinement.
//!
//! This module provides advanced operations on 1D grids that go beyond basic
//! construction and access. These operations are essential for adaptive algorithms,
//! multi-physics coupling, and hierarchical numerical methods.
//!
//! ## Module Organization
//!
//! | Module | Purpose | Key Types |
//! |--------|---------|-----------|
//! | [`refinement`] | Grid subdivision and AMR | [`refinement::Grid1DRefinement`], [`refinement::Grid1DUniformRefinement`], [`refinement::Grid1DNonUniformRefinement`] |
//! | [`union`] | Grid combination with mappings | [`union::Grid1DUnion`], [`union::ErrorsGrid1DUnion`] |
//! | [`point_classification`] | Coordinate-to-interval classification | [`point_classification::CoordsByIntervalClassification`], [`point_classification::CoordIdsByInterval`] |
//!
//! ## Core Concepts
//!
//! ### Grid Refinement
//! Refinement operations subdivide existing grid intervals to create higher-resolution
//! grids while maintaining bidirectional mappings between original and refined intervals.
//!
//! ```rust
//! use grid1d::{*, intervals::*, scalars::*};
//! use std::collections::BTreeMap;
//! use try_create::TryNew;
//!
//! let grid = Grid1D::uniform(IntervalClosed::new(0.0, 1.0), NumIntervals::try_new(4).unwrap());
//!
//! // Uniform refinement: all intervals subdivided equally
//! let uniform = grid.refine_uniform(&PositiveNumPoints1D::try_new(1).unwrap());
//! assert_eq!(uniform.refined_grid().num_intervals().as_ref(), &8);
//!
//! // Selective refinement: only specific intervals
//! let plan = BTreeMap::from([
//! (IntervalId::new(0), PositiveNumPoints1D::try_new(2).unwrap()),
//! (IntervalId::new(2), PositiveNumPoints1D::try_new(1).unwrap()),
//! ]);
//! let selective = uniform.into_refined_grid().refine(&plan);
//! ```
//!
//! ### Grid Union
//! Union operations combine two grids over the same domain into a unified partition
//! that contains all coordinate points from both grids, with mappings back to the
//! original intervals.
//!
//! ```rust
//! use grid1d::{*, intervals::*, scalars::*};
//! use sorted_vec::partial::SortedSet;
//! use try_create::TryNew;
//!
//! let domain = IntervalClosed::new(0.0, 2.0);
//! let grid_a = Grid1D::uniform(domain.clone(), NumIntervals::try_new(4).unwrap());
//! let grid_b = Grid1D::<IntervalClosed<f64>>::try_from_sorted(
//! SortedSet::from_unsorted(vec![0.0, 0.3, 0.7, 1.5, 2.0])
//! ).unwrap();
//!
//! let union = Grid1DUnion::try_new(&grid_a, &grid_b).unwrap();
//!
//! // Each unified interval maps back to both original grids
//! for (unified_id, a_id, b_id) in union.iter_interval_mappings() {
//! println!("Unified {} → A[{}], B[{}]",
//! *unified_id.as_ref(), *a_id.as_ref(), *b_id.as_ref());
//! }
//! ```
//!
//! ### Point Classification
//! Point classification assigns each coordinate in a slice to the grid interval that
//! contains it, collecting results into dense (`Vec`-backed) or sparse
//! (`BTreeMap`-backed) buckets. Points outside the domain are tracked separately.
//!
//! ```rust
//! use grid1d::{*, intervals::*, scalars::*};
//! use try_create::TryNew;
//!
//! let grid = Grid1D::uniform(IntervalClosed::new(0.0, 1.0), NumIntervals::try_new(4).unwrap());
//! let coords: Vec<f64> = vec![-0.1, 0.1, 0.3, 0.6, 0.9, 1.5];
//!
//! // Dense: one bucket per grid interval (O(1) bucket lookup)
//! let classification = CoordsByIntervalClassification::try_new_dense_from_coords(
//! &coords, &grid,
//! ).unwrap();
//!
//! assert_eq!(classification.point_ids_outside().as_slice(), &[0, 5]);
//! ```
//!
//! ## Use Cases
//!
//! ### Adaptive Mesh Refinement (AMR)
//! The refinement module provides the foundation for adaptive algorithms that
//! dynamically adjust grid resolution based on solution features:
//!
//! - **Error-driven refinement**: Refine intervals where error estimates exceed thresholds
//! - **Feature tracking**: Increase resolution near discontinuities or steep gradients
//! - **Multi-level methods**: Build grid hierarchies for multigrid solvers
//!
//! ### Multi-Physics Coupling
//! The union module enables coupling between different physics simulations
//! that may use different grid resolutions:
//!
//! - **Data transfer**: Map quantities between grids with different resolutions
//! - **Consistent discretization**: Create a unified grid that respects both discretizations
//! - **Conservation**: Maintain integral quantities during grid transfers
//!
//! ### FEM Assembly and Interpolation
//! The point classification module is the fundamental building block for operations
//! that need to locate coordinates within a grid:
//!
//! - **FEM assembly**: Determine which element each quadrature point belongs to
//! - **Interpolation**: Find the support interval for each evaluation point
//! - **Data transfer**: Assign source-grid values to target-grid intervals
//! - **Parallel classification**: Use `_par` variants for large coordinate sets via Rayon
//!
//! ## Performance Characteristics
//!
//! | Operation | Time Complexity | Space Complexity |
//! |-----------|-----------------|------------------|
//! | Uniform refinement | O(n) | O(n) |
//! | Selective refinement | O(n + k·m) | O(n + k·m) |
//! | Grid union | O(n + m) | O(n + m) |
//! | Mapping lookup | O(1) | - |
//! | Data transfer | O(n) | O(n) |
//! | Dense classification | O(p · log n) | O(n + p) |
//! | Sparse classification | O(p · log n) | O(p) |
//! | Dense classification (par) | O(p · log n / t) | O(n + p) |
//! | Sparse classification (par) | O(p · log n / t) | O(p) |
//!
//! Where n, m are interval counts, k is the average refinement factor,
//! p is the number of points to classify, and t is the number of threads.
//!
//! ## Mathematical Properties
//!
//! All operations in this module preserve the fundamental grid invariants:
//!
//! - **Domain preservation**: Refined/unified grids have the same domain as inputs
//! - **Partition completeness**: Output grids completely partition their domains
//! - **Ordering preservation**: Coordinate ordering is maintained
//! - **Mapping consistency**: Bidirectional mappings are mathematically consistent
//!
//! ## See Also
//!
//! - [`Grid1D`](crate::Grid1D): The main grid type supporting these operations
//! - [`Grid1DTrait`](crate::Grid1DTrait): The trait implemented by all grids
//! - [`scalars`](crate::scalars): Types for interval IDs and counts
pub use ;