Skip to main content

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}