Skip to main content

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}