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: 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 combined_filter =
141 crate::stream::closures::self_join_penta_filter::<S, A, _, _>(self.filter, joiner);
142
143 PentaConstraintStream::new_self_join_with_filter(
144 self.extractor,
145 self.key_extractor,
146 FnPentaFilter::new(combined_filter),
147 )
148 }
149}
150
151// Additional doctests for individual methods
152
153#[cfg(doctest)]
154mod doctests {
155 /* # Filter method
156
157 ```
158 use solverforge_scoring::stream::ConstraintFactory;
159 use solverforge_scoring::stream::joiner::equal;
160 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
161 use solverforge_core::score::SoftScore;
162
163 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
164 struct Item { group: u32, value: i32 }
165
166 #[derive(Clone)]
167 struct Solution { items: Vec<Item> }
168
169 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
170 .for_each(Solution::items())
171 .join(equal(|i: &Item| i.group))
172 .join(equal(|i: &Item| i.group))
173 .join(equal(|i: &Item| i.group))
174 .filter(|a: &Item, b: &Item, c: &Item, d: &Item| {
175 a.value + b.value + c.value + d.value > 15
176 })
177 .penalize(SoftScore::of(1))
178 .named("High sum quadruples");
179
180 let solution = Solution {
181 items: vec![
182 Item { group: 1, value: 3 },
183 Item { group: 1, value: 4 },
184 Item { group: 1, value: 5 },
185 Item { group: 1, value: 6 },
186 ],
187 };
188
189 // 3+4+5+6=18 > 15, matches
190 assert_eq!(constraint.evaluate(&solution), SoftScore::of(-1));
191 ```
192
193 # Penalize method
194
195 ```
196 use solverforge_scoring::stream::ConstraintFactory;
197 use solverforge_scoring::stream::joiner::equal;
198 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
199 use solverforge_core::score::SoftScore;
200
201 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
202 struct Task { priority: u32 }
203
204 #[derive(Clone)]
205 struct Solution { tasks: Vec<Task> }
206
207 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
208 .for_each(Solution::tasks())
209 .join(equal(|t: &Task| t.priority))
210 .join(equal(|t: &Task| t.priority))
211 .join(equal(|t: &Task| t.priority))
212 .penalize(SoftScore::of(5))
213 .named("Quadruple priority conflict");
214
215 let solution = Solution {
216 tasks: vec![
217 Task { priority: 1 },
218 Task { priority: 1 },
219 Task { priority: 1 },
220 Task { priority: 1 },
221 ],
222 };
223
224 // One quadruple = -5
225 assert_eq!(constraint.evaluate(&solution), SoftScore::of(-5));
226 ```
227
228 # named method
229
230 ```
231 use solverforge_scoring::stream::ConstraintFactory;
232 use solverforge_scoring::stream::joiner::equal;
233 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
234 use solverforge_core::score::SoftScore;
235
236 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
237 struct Item { id: usize }
238
239 #[derive(Clone)]
240 struct Solution { items: Vec<Item> }
241
242 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
243 .for_each(Solution::items())
244 .join(equal(|i: &Item| i.id))
245 .join(equal(|i: &Item| i.id))
246 .join(equal(|i: &Item| i.id))
247 .penalize(SoftScore::of(1))
248 .named("Quadruple items");
249
250 assert_eq!(constraint.name(), "Quadruple items");
251 ```
252 */
253}