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 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}