solverforge_scoring/stream/tri_stream.rs
1//! Zero-erasure tri-constraint stream for three-entity constraint patterns.
2//!
3//! A `TriConstraintStream` operates on triples 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 three 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//! .penalize(SoftScore::of(1))
40//! .named("Team clustering");
41//!
42//! let solution = Solution {
43//! tasks: vec![
44//! Task { team: 1 },
45//! Task { team: 1 },
46//! Task { team: 1 },
47//! Task { team: 2 },
48//! ],
49//! };
50//!
51//! // One triple on team 1: (0, 1, 2) = -1 penalty
52//! assert_eq!(constraint.evaluate(&solution), SoftScore::of(-1));
53//! ```
54
55use std::hash::Hash;
56
57use solverforge_core::score::Score;
58
59use super::collection_extract::CollectionExtract;
60use super::filter::{FnQuadFilter, QuadFilter, TriFilter};
61use super::joiner::Joiner;
62use super::quad_stream::QuadConstraintStream;
63
64super::arity_stream_macros::impl_arity_stream!(tri, TriConstraintStream, TriConstraintBuilder);
65
66/// join method - transitions to QuadConstraintStream
67impl<S, A, K, E, KE, F, Sc> TriConstraintStream<S, A, K, E, KE, F, Sc>
68where
69 S: Send + Sync + 'static,
70 A: Clone + Hash + PartialEq + Send + Sync + 'static,
71 K: Eq + Hash + Clone + Send + Sync,
72 E: CollectionExtract<S, Item = A>,
73 KE: super::key_extract::KeyExtract<S, A, K>,
74 F: TriFilter<S, A, A, A>,
75 Sc: Score + 'static,
76{
77 /// Joins this stream with a fourth element to create quadruples.
78 ///
79 /// # Example
80 ///
81 /// ```
82 /// use solverforge_core::score::SoftScore;
83 /// use solverforge_scoring::api::constraint_set::IncrementalConstraint;
84 /// use solverforge_scoring::stream::joiner::equal;
85 /// use solverforge_scoring::stream::ConstraintFactory;
86 ///
87 /// #[derive(Clone, Debug, Hash, PartialEq, Eq)]
88 /// struct Task {
89 /// team: u32,
90 /// }
91 ///
92 /// #[derive(Clone)]
93 /// struct Solution {
94 /// tasks: Vec<Task>,
95 /// }
96 /// # use solverforge_scoring::stream::{source, ChangeSource, CollectionExtract};
97 /// # impl Solution {
98 /// # fn tasks() -> impl CollectionExtract<Solution, Item = Task> {
99 /// # fn tasks(s: &Solution) -> &[Task] {
100 /// # s.tasks.as_slice()
101 /// # }
102 /// # source(tasks as fn(&Solution) -> &[Task], ChangeSource::Descriptor(0))
103 /// # }
104 /// # }
105 ///
106 /// // Penalize when four tasks are on the same team
107 /// let constraint = ConstraintFactory::<Solution, SoftScore>::new()
108 /// .for_each(Solution::tasks())
109 /// .join(equal(|t: &Task| t.team))
110 /// .join(equal(|t: &Task| t.team))
111 /// .join(equal(|t: &Task| t.team))
112 /// .penalize(SoftScore::of(1))
113 /// .named("Team clustering");
114 ///
115 /// let solution = Solution {
116 /// tasks: vec![
117 /// Task { team: 1 },
118 /// Task { team: 1 },
119 /// Task { team: 1 },
120 /// Task { team: 1 },
121 /// Task { team: 2 },
122 /// ],
123 /// };
124 ///
125 /// // One quadruple on team 1: (0, 1, 2, 3) = -1 penalty
126 /// assert_eq!(constraint.evaluate(&solution), SoftScore::of(-1));
127 /// ```
128 pub fn join<J>(
129 self,
130 joiner: J,
131 ) -> QuadConstraintStream<S, A, K, E, KE, impl QuadFilter<S, A, A, A, A>, Sc>
132 where
133 J: Joiner<A, A> + 'static,
134 F: 'static,
135 {
136 let combined_filter =
137 crate::stream::closures::self_join_quad_filter::<S, A, _, _>(self.filter, joiner);
138
139 QuadConstraintStream::new_self_join_with_filter(
140 self.extractor,
141 self.key_extractor,
142 FnQuadFilter::new(combined_filter),
143 )
144 }
145}
146
147// Additional doctests for individual methods
148
149#[cfg(doctest)]
150mod doctests {
151 /* # Filter method
152
153 ```
154 use solverforge_scoring::stream::ConstraintFactory;
155 use solverforge_scoring::stream::joiner::equal;
156 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
157 use solverforge_core::score::SoftScore;
158
159 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
160 struct Item { group: u32, value: i32 }
161
162 #[derive(Clone)]
163 struct Solution { items: Vec<Item> }
164
165 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
166 .for_each(Solution::items())
167 .join(equal(|i: &Item| i.group))
168 .join(equal(|i: &Item| i.group))
169 .filter(|a: &Item, b: &Item, c: &Item| a.value + b.value + c.value > 10)
170 .penalize(SoftScore::of(1))
171 .named("High sum triples");
172
173 let solution = Solution {
174 items: vec![
175 Item { group: 1, value: 3 },
176 Item { group: 1, value: 4 },
177 Item { group: 1, value: 5 },
178 ],
179 };
180
181 // 3+4+5=12 > 10, matches
182 assert_eq!(constraint.evaluate(&solution), SoftScore::of(-1));
183 ```
184
185 # Penalize method
186
187 ```
188 use solverforge_scoring::stream::ConstraintFactory;
189 use solverforge_scoring::stream::joiner::equal;
190 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
191 use solverforge_core::score::SoftScore;
192
193 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
194 struct Task { priority: u32 }
195
196 #[derive(Clone)]
197 struct Solution { tasks: Vec<Task> }
198
199 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
200 .for_each(Solution::tasks())
201 .join(equal(|t: &Task| t.priority))
202 .join(equal(|t: &Task| t.priority))
203 .penalize(SoftScore::of(5))
204 .named("Triple priority conflict");
205
206 let solution = Solution {
207 tasks: vec![
208 Task { priority: 1 },
209 Task { priority: 1 },
210 Task { priority: 1 },
211 ],
212 };
213
214 // One triple = -5
215 assert_eq!(constraint.evaluate(&solution), SoftScore::of(-5));
216 ```
217
218 # Penalize with dynamic weight
219
220 ```
221 use solverforge_scoring::stream::ConstraintFactory;
222 use solverforge_scoring::stream::joiner::equal;
223 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
224 use solverforge_core::score::SoftScore;
225
226 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
227 struct Task { team: u32, cost: i64 }
228
229 #[derive(Clone)]
230 struct Solution { tasks: Vec<Task> }
231
232 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
233 .for_each(Solution::tasks())
234 .join(equal(|t: &Task| t.team))
235 .join(equal(|t: &Task| t.team))
236 .penalize(|a: &Task, b: &Task, c: &Task| {
237 SoftScore::of(a.cost + b.cost + c.cost)
238 })
239 .named("Team cost");
240
241 let solution = Solution {
242 tasks: vec![
243 Task { team: 1, cost: 2 },
244 Task { team: 1, cost: 3 },
245 Task { team: 1, cost: 5 },
246 ],
247 };
248
249 // Penalty: 2+3+5 = -10
250 assert_eq!(constraint.evaluate(&solution), SoftScore::of(-10));
251 ```
252
253 # Reward method
254
255 ```
256 use solverforge_scoring::stream::ConstraintFactory;
257 use solverforge_scoring::stream::joiner::equal;
258 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
259 use solverforge_core::score::SoftScore;
260
261 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
262 struct Person { team: u32 }
263
264 #[derive(Clone)]
265 struct Solution { people: Vec<Person> }
266
267 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
268 .for_each(Solution::people())
269 .join(equal(|p: &Person| p.team))
270 .join(equal(|p: &Person| p.team))
271 .reward(SoftScore::of(10))
272 .named("Team synergy");
273
274 let solution = Solution {
275 people: vec![
276 Person { team: 1 },
277 Person { team: 1 },
278 Person { team: 1 },
279 ],
280 };
281
282 // One triple = +10
283 assert_eq!(constraint.evaluate(&solution), SoftScore::of(10));
284 ```
285
286 # named method
287
288 ```
289 use solverforge_scoring::stream::ConstraintFactory;
290 use solverforge_scoring::stream::joiner::equal;
291 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
292 use solverforge_core::score::SoftScore;
293
294 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
295 struct Item { id: usize }
296
297 #[derive(Clone)]
298 struct Solution { items: Vec<Item> }
299
300 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
301 .for_each(Solution::items())
302 .join(equal(|i: &Item| i.id))
303 .join(equal(|i: &Item| i.id))
304 .penalize(SoftScore::of(1))
305 .named("Triple items");
306
307 assert_eq!(constraint.name(), "Triple items");
308 ```
309 */
310}