solverforge_scoring/stream/penta_stream.rs
1//! Zero-erasure penta-constraint stream for five-entity constraint patterns.
2//!
3//! A `PentaConstraintStream` operates on quintuples 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 five 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//! .join(equal(|t: &Task| t.team))
41//! .penalize(SoftScore::of(1))
42//! .named("Team clustering");
43//!
44//! let solution = Solution {
45//! tasks: vec![
46//! Task { team: 1 },
47//! Task { team: 1 },
48//! Task { team: 1 },
49//! Task { team: 1 },
50//! Task { team: 1 },
51//! Task { team: 2 },
52//! ],
53//! };
54//!
55//! // One quintuple on team 1: (0, 1, 2, 3, 4) = -1 penalty
56//! assert_eq!(constraint.evaluate(&solution), SoftScore::of(-1));
57//! ```
58
59super::arity_stream_macros::impl_arity_stream!(
60 penta,
61 PentaConstraintStream,
62 PentaConstraintBuilder
63);
64
65// Additional doctests for individual methods
66
67#[cfg(doctest)]
68mod doctests {
69 /* # Filter method
70
71 ```
72 use solverforge_scoring::stream::ConstraintFactory;
73 use solverforge_scoring::stream::joiner::equal;
74 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
75 use solverforge_core::score::SoftScore;
76
77 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
78 struct Item { group: u32, value: i32 }
79
80 #[derive(Clone)]
81 struct Solution { items: Vec<Item> }
82
83 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
84 .for_each(Solution::items())
85 .join(equal(|i: &Item| i.group))
86 .join(equal(|i: &Item| i.group))
87 .join(equal(|i: &Item| i.group))
88 .join(equal(|i: &Item| i.group))
89 .filter(|a: &Item, b: &Item, c: &Item, d: &Item, e: &Item| {
90 a.value + b.value + c.value + d.value + e.value > 20
91 })
92 .penalize(SoftScore::of(1))
93 .named("High sum quintuples");
94
95 let solution = Solution {
96 items: vec![
97 Item { group: 1, value: 3 },
98 Item { group: 1, value: 4 },
99 Item { group: 1, value: 5 },
100 Item { group: 1, value: 6 },
101 Item { group: 1, value: 7 },
102 ],
103 };
104
105 // 3+4+5+6+7=25 > 20, matches
106 assert_eq!(constraint.evaluate(&solution), SoftScore::of(-1));
107 ```
108
109 # Penalize method
110
111 ```
112 use solverforge_scoring::stream::ConstraintFactory;
113 use solverforge_scoring::stream::joiner::equal;
114 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
115 use solverforge_core::score::SoftScore;
116
117 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
118 struct Task { priority: u32 }
119
120 #[derive(Clone)]
121 struct Solution { tasks: Vec<Task> }
122
123 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
124 .for_each(Solution::tasks())
125 .join(equal(|t: &Task| t.priority))
126 .join(equal(|t: &Task| t.priority))
127 .join(equal(|t: &Task| t.priority))
128 .join(equal(|t: &Task| t.priority))
129 .penalize(SoftScore::of(5))
130 .named("Quintuple priority conflict");
131
132 let solution = Solution {
133 tasks: vec![
134 Task { priority: 1 },
135 Task { priority: 1 },
136 Task { priority: 1 },
137 Task { priority: 1 },
138 Task { priority: 1 },
139 ],
140 };
141
142 // One quintuple = -5
143 assert_eq!(constraint.evaluate(&solution), SoftScore::of(-5));
144 ```
145
146 # Penalize with dynamic weight
147
148 ```
149 use solverforge_scoring::stream::ConstraintFactory;
150 use solverforge_scoring::stream::joiner::equal;
151 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
152 use solverforge_core::score::SoftScore;
153
154 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
155 struct Task { team: u32, cost: i64 }
156
157 #[derive(Clone)]
158 struct Solution { tasks: Vec<Task> }
159
160 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
161 .for_each(Solution::tasks())
162 .join(equal(|t: &Task| t.team))
163 .join(equal(|t: &Task| t.team))
164 .join(equal(|t: &Task| t.team))
165 .join(equal(|t: &Task| t.team))
166 .penalize(|a: &Task, b: &Task, c: &Task, d: &Task, e: &Task| {
167 SoftScore::of(a.cost + b.cost + c.cost + d.cost + e.cost)
168 })
169 .named("Team cost");
170
171 let solution = Solution {
172 tasks: vec![
173 Task { team: 1, cost: 1 },
174 Task { team: 1, cost: 2 },
175 Task { team: 1, cost: 3 },
176 Task { team: 1, cost: 4 },
177 Task { team: 1, cost: 5 },
178 ],
179 };
180
181 // Penalty: 1+2+3+4+5 = -15
182 assert_eq!(constraint.evaluate(&solution), SoftScore::of(-15));
183 ```
184
185 # Reward 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 Person { team: u32 }
195
196 #[derive(Clone)]
197 struct Solution { people: Vec<Person> }
198
199 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
200 .for_each(Solution::people())
201 .join(equal(|p: &Person| p.team))
202 .join(equal(|p: &Person| p.team))
203 .join(equal(|p: &Person| p.team))
204 .join(equal(|p: &Person| p.team))
205 .reward(SoftScore::of(10))
206 .named("Team synergy");
207
208 let solution = Solution {
209 people: vec![
210 Person { team: 1 },
211 Person { team: 1 },
212 Person { team: 1 },
213 Person { team: 1 },
214 Person { team: 1 },
215 ],
216 };
217
218 // One quintuple = +10
219 assert_eq!(constraint.evaluate(&solution), SoftScore::of(10));
220 ```
221
222 # named method
223
224 ```
225 use solverforge_scoring::stream::ConstraintFactory;
226 use solverforge_scoring::stream::joiner::equal;
227 use solverforge_scoring::api::constraint_set::IncrementalConstraint;
228 use solverforge_core::score::SoftScore;
229
230 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
231 struct Item { id: usize }
232
233 #[derive(Clone)]
234 struct Solution { items: Vec<Item> }
235
236 let constraint = ConstraintFactory::<Solution, SoftScore>::new()
237 .for_each(Solution::items())
238 .join(equal(|i: &Item| i.id))
239 .join(equal(|i: &Item| i.id))
240 .join(equal(|i: &Item| i.id))
241 .join(equal(|i: &Item| i.id))
242 .penalize(SoftScore::of(1))
243 .named("Quintuple items");
244
245 assert_eq!(constraint.name(), "Quintuple items");
246 ```
247 */
248}