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
//! 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`] |
//!
//! ## 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());
//! }
//! ```
//!
//! ## 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
//!
//! ## 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) |
//!
//! Where n, m are interval counts and k is the average refinement factor.
//!
//! ## 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
//! - [`IntervalPartition`](crate::IntervalPartition): The trait implemented by all grids
//! - [`scalars`](crate::scalars): Types for interval IDs and counts