solverforge_scoring/stream/quad_stream.rs
1//! Zero-erasure quad-constraint stream for four-entity constraint patterns.
2//!
3//! A `QuadConstraintStream` operates on quadruples of entities and supports
4//! filtering, weighting, and constraint finalization. All type information
5//! is preserved at compile time - no Arc, no dyn.
6//!
7//! # Example
8//!
9//! ```
10//! use solverforge_core::score::SoftScore;
11//! use solverforge_scoring::api::constraint_set::IncrementalConstraint;
12//! use solverforge_scoring::stream::joiner::equal;
13//! use solverforge_scoring::stream::ConstraintFactory;
14//!
15//! #[derive(Clone, Debug, Hash, PartialEq, Eq)]
16//! struct Task {
17//! team: u32,
18//! }
19//!
20//! #[derive(Clone)]
21//! struct Solution {
22//! tasks: Vec<Task>,
23//! }
24//! # use solverforge_scoring::stream::{source, ChangeSource, CollectionExtract};
25//! # impl Solution {
26//! # fn tasks() -> impl CollectionExtract<Solution, Item = Task> {
27//! # fn tasks(s: &Solution) -> &[Task] {
28//! # s.tasks.as_slice()
29//! # }
30//! # source(tasks as fn(&Solution) -> &[Task], ChangeSource::Descriptor(0))
31//! # }
32//! # }
33//!
34//! // Penalize when four tasks are on the same team
35//! let constraint = ConstraintFactory::<Solution, SoftScore>::new()
36//! .for_each(Solution::tasks())
37//! .join(equal(|t: &Task| t.team))
38//! .join(equal(|t: &Task| t.team))
39//! .join(equal(|t: &Task| t.team))
40//! .penalize(SoftScore::of(1))
41//! .named("Team clustering");
42//!
43//! let solution = Solution {
44//! tasks: vec![
45//! Task { team: 1 },
46//! Task { team: 1 },
47//! Task { team: 1 },
48//! Task { team: 1 },
49//! Task { team: 2 },
50//! ],
51//! };
52//!
53//! // One quadruple on team 1: (0, 1, 2, 3) = -1 penalty
54//! assert_eq!(constraint.evaluate(&solution), SoftScore::of(-1));
55//! ```
56
57use std::hash::Hash;
58
59use solverforge_core::score::Score;
60
61use super::collection_extract::CollectionExtract;
62use super::filter::{FnPentaFilter, PentaFilter, QuadFilter};
63use super::joiner::Joiner;
64use super::penta_stream::PentaConstraintStream;
65
66super::arity_stream_macros::impl_arity_stream!(quad, QuadConstraintStream, QuadConstraintBuilder);
67
68/// join method - transitions to PentaConstraintStream
69impl<S, A, K, E, KE, F, Sc> QuadConstraintStream<S, A, K, E, KE, F, Sc>
70where
71 S: Send + Sync + 'static,
72 A: Clone + Hash + PartialEq + Send + Sync + 'static,
73 K: Eq + Hash + Clone + Send + Sync,
74 E: CollectionExtract<S, Item = A>,
75 KE: super::key_extract::KeyExtract<S, A, K>,
76 F: QuadFilter<S, A, A, A, A>,
77 Sc: Score + 'static,
78{
79 /// Joins this stream with a fifth element to create quintuples.
80 ///
81 /// # Example
82 ///
83 /// ```
84 /// use solverforge_core::score::SoftScore;
85 /// use solverforge_scoring::api::constraint_set::IncrementalConstraint;
86 /// use solverforge_scoring::stream::joiner::equal;
87 /// use solverforge_scoring::stream::ConstraintFactory;
88 ///
89 /// #[derive(Clone, Debug, Hash, PartialEq, Eq)]
90 /// struct Task {
91 /// team: u32,
92 /// }
93 ///
94 /// #[derive(Clone)]
95 /// struct Solution {
96 /// tasks: Vec<Task>,
97 /// }
98 /// # use solverforge_scoring::stream::{source, ChangeSource, CollectionExtract};
99 /// # impl Solution {
100 /// # fn tasks() -> impl CollectionExtract<Solution, Item = Task> {
101 /// # fn tasks(s: &Solution) -> &[Task] {
102 /// # s.tasks.as_slice()
103 /// # }
104 /// # source(tasks as fn(&Solution) -> &[Task], ChangeSource::Descriptor(0))
105 /// # }
106 /// # }
107 ///
108 /// // Penalize when five tasks are on the same team
109 /// let constraint = ConstraintFactory::<Solution, SoftScore>::new()
110 /// .for_each(Solution::tasks())
111 /// .join(equal(|t: &Task| t.team))
112 /// .join(equal(|t: &Task| t.team))
113 /// .join(equal(|t: &Task| t.team))
114 /// .join(equal(|t: &Task| t.team))
115 /// .penalize(SoftScore::of(1))
116 /// .named("Team clustering");
117 ///
118 /// let solution = Solution {
119 /// tasks: vec![
120 /// Task { team: 1 },
121 /// Task { team: 1 },
122 /// Task { team: 1 },
123 /// Task { team: 1 },
124 /// Task { team: 1 },
125 /// Task { team: 2 },
126 /// ],
127 /// };
128 ///
129 /// // One quintuple on team 1: (0, 1, 2, 3, 4) = -1 penalty
130 /// assert_eq!(constraint.evaluate(&solution), SoftScore::of(-1));
131 /// ```
132 pub fn join<J>(
133 self,
134 joiner: J,
135 ) -> PentaConstraintStream<S, A, K, E, KE, impl PentaFilter<S, A, A, A, A, A>, Sc>
136 where
137 J: Joiner<A, A> + 'static,
138 F: 'static,
139 {
140 let filter = self.filter;
141 let combined_filter = move |s: &S,
142 a: &A,
143 b: &A,
144 c: &A,
145 d: &A,
146 e: &A,
147 a_idx: usize,
148 b_idx: usize,
149 c_idx: usize,
150 d_idx: usize,
151 _e_idx: usize| {
152 filter.test(s, a, b, c, d, a_idx, b_idx, c_idx, d_idx) && joiner.matches(a, e)
153 };
154
155 PentaConstraintStream::new_self_join_with_filter(
156 self.extractor,
157 self.key_extractor,
158 FnPentaFilter::new(combined_filter),
159 )
160 }
161}
162
163// Additional doctests for individual methods
164
165#[cfg(doctest)]
166mod doctests {
167 /* # Filter method
168
169 ```
170 use solverforge_scoring::stream::ConstraintFactory;
171 use solverforge_scoring::stream::joiner::equal;
172 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
173 use solverforge_core::score::SoftScore;
174
175 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
176 struct Item { group: u32, value: i32 }
177
178 #[derive(Clone)]
179 struct Solution { items: Vec<Item> }
180
181 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
182 .for_each(Solution::items())
183 .join(equal(|i: &Item| i.group))
184 .join(equal(|i: &Item| i.group))
185 .join(equal(|i: &Item| i.group))
186 .filter(|a: &Item, b: &Item, c: &Item, d: &Item| {
187 a.value + b.value + c.value + d.value > 15
188 })
189 .penalize(SoftScore::of(1))
190 .named("High sum quadruples");
191
192 let solution = Solution {
193 items: vec![
194 Item { group: 1, value: 3 },
195 Item { group: 1, value: 4 },
196 Item { group: 1, value: 5 },
197 Item { group: 1, value: 6 },
198 ],
199 };
200
201 // 3+4+5+6=18 > 15, matches
202 assert_eq!(constraint.evaluate(&solution), SoftScore::of(-1));
203 ```
204
205 # Penalize method
206
207 ```
208 use solverforge_scoring::stream::ConstraintFactory;
209 use solverforge_scoring::stream::joiner::equal;
210 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
211 use solverforge_core::score::SoftScore;
212
213 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
214 struct Task { priority: u32 }
215
216 #[derive(Clone)]
217 struct Solution { tasks: Vec<Task> }
218
219 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
220 .for_each(Solution::tasks())
221 .join(equal(|t: &Task| t.priority))
222 .join(equal(|t: &Task| t.priority))
223 .join(equal(|t: &Task| t.priority))
224 .penalize(SoftScore::of(5))
225 .named("Quadruple priority conflict");
226
227 let solution = Solution {
228 tasks: vec![
229 Task { priority: 1 },
230 Task { priority: 1 },
231 Task { priority: 1 },
232 Task { priority: 1 },
233 ],
234 };
235
236 // One quadruple = -5
237 assert_eq!(constraint.evaluate(&solution), SoftScore::of(-5));
238 ```
239
240 # named method
241
242 ```
243 use solverforge_scoring::stream::ConstraintFactory;
244 use solverforge_scoring::stream::joiner::equal;
245 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
246 use solverforge_core::score::SoftScore;
247
248 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
249 struct Item { id: usize }
250
251 #[derive(Clone)]
252 struct Solution { items: Vec<Item> }
253
254 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
255 .for_each(Solution::items())
256 .join(equal(|i: &Item| i.id))
257 .join(equal(|i: &Item| i.id))
258 .join(equal(|i: &Item| i.id))
259 .penalize(SoftScore::of(1))
260 .named("Quadruple items");
261
262 assert_eq!(constraint.name(), "Quadruple items");
263 ```
264 */
265}