Skip to main content

solverforge_scoring/stream/
tri_stream.rs

1//! Zero-erasure tri-constraint stream for three-entity constraint patterns.
2//!
3//! A `TriConstraintStream` operates on triples 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 three 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//!     .penalize(SoftScore::of(1))
40//!     .named("Team clustering");
41//!
42//! let solution = Solution {
43//!     tasks: vec![
44//!         Task { team: 1 },
45//!         Task { team: 1 },
46//!         Task { team: 1 },
47//!         Task { team: 2 },
48//!     ],
49//! };
50//!
51//! // One triple on team 1: (0, 1, 2) = -1 penalty
52//! assert_eq!(constraint.evaluate(&solution), SoftScore::of(-1));
53//! ```
54
55use std::hash::Hash;
56
57use solverforge_core::score::Score;
58
59use super::collection_extract::CollectionExtract;
60use super::filter::{FnQuadFilter, QuadFilter, TriFilter};
61use super::joiner::Joiner;
62use super::quad_stream::QuadConstraintStream;
63
64super::arity_stream_macros::impl_arity_stream!(tri, TriConstraintStream, TriConstraintBuilder);
65
66/// join method - transitions to QuadConstraintStream
67impl<S, A, K, E, KE, F, Sc> TriConstraintStream<S, A, K, E, KE, F, Sc>
68where
69    S: Send + Sync + 'static,
70    A: Clone + Hash + PartialEq + Send + Sync + 'static,
71    K: Eq + Hash + Clone + Send + Sync,
72    E: CollectionExtract<S, Item = A>,
73    KE: super::key_extract::KeyExtract<S, A, K>,
74    F: TriFilter<S, A, A, A>,
75    Sc: Score + 'static,
76{
77    /// Joins this stream with a fourth element to create quadruples.
78    ///
79    /// # Example
80    ///
81    /// ```
82    /// use solverforge_core::score::SoftScore;
83    /// use solverforge_scoring::api::constraint_set::IncrementalConstraint;
84    /// use solverforge_scoring::stream::joiner::equal;
85    /// use solverforge_scoring::stream::ConstraintFactory;
86    ///
87    /// #[derive(Clone, Debug, Hash, PartialEq, Eq)]
88    /// struct Task {
89    ///     team: u32,
90    /// }
91    ///
92    /// #[derive(Clone)]
93    /// struct Solution {
94    ///     tasks: Vec<Task>,
95    /// }
96    /// # use solverforge_scoring::stream::{source, ChangeSource, CollectionExtract};
97    /// # impl Solution {
98    /// #     fn tasks() -> impl CollectionExtract<Solution, Item = Task> {
99    /// #         fn tasks(s: &Solution) -> &[Task] {
100    /// #             s.tasks.as_slice()
101    /// #         }
102    /// #         source(tasks as fn(&Solution) -> &[Task], ChangeSource::Descriptor(0))
103    /// #     }
104    /// # }
105    ///
106    /// // Penalize when four tasks are on the same team
107    /// let constraint = ConstraintFactory::<Solution, SoftScore>::new()
108    ///     .for_each(Solution::tasks())
109    ///     .join(equal(|t: &Task| t.team))
110    ///     .join(equal(|t: &Task| t.team))
111    ///     .join(equal(|t: &Task| t.team))
112    ///     .penalize(SoftScore::of(1))
113    ///     .named("Team clustering");
114    ///
115    /// let solution = Solution {
116    ///     tasks: vec![
117    ///         Task { team: 1 },
118    ///         Task { team: 1 },
119    ///         Task { team: 1 },
120    ///         Task { team: 1 },
121    ///         Task { team: 2 },
122    ///     ],
123    /// };
124    ///
125    /// // One quadruple on team 1: (0, 1, 2, 3) = -1 penalty
126    /// assert_eq!(constraint.evaluate(&solution), SoftScore::of(-1));
127    /// ```
128    pub fn join<J>(
129        self,
130        joiner: J,
131    ) -> QuadConstraintStream<S, A, K, E, KE, impl QuadFilter<S, A, A, A, A>, Sc>
132    where
133        J: Joiner<A, A> + 'static,
134        F: 'static,
135    {
136        let combined_filter =
137            crate::stream::closures::self_join_quad_filter::<S, A, _, _>(self.filter, joiner);
138
139        QuadConstraintStream::new_self_join_with_filter(
140            self.extractor,
141            self.key_extractor,
142            FnQuadFilter::new(combined_filter),
143        )
144    }
145}
146
147// Additional doctests for individual methods
148
149#[cfg(doctest)]
150mod doctests {
151    /* # Filter method
152
153    ```
154    use solverforge_scoring::stream::ConstraintFactory;
155    use solverforge_scoring::stream::joiner::equal;
156    use solverforge_scoring::api::constraint_set::IncrementalConstraint;
157    use solverforge_core::score::SoftScore;
158
159    #[derive(Clone, Debug, Hash, PartialEq, Eq)]
160    struct Item { group: u32, value: i32 }
161
162    #[derive(Clone)]
163    struct Solution { items: Vec<Item> }
164
165    let constraint = ConstraintFactory::<Solution, SoftScore>::new()
166    .for_each(Solution::items())
167    .join(equal(|i: &Item| i.group))
168    .join(equal(|i: &Item| i.group))
169    .filter(|a: &Item, b: &Item, c: &Item| a.value + b.value + c.value > 10)
170    .penalize(SoftScore::of(1))
171    .named("High sum triples");
172
173    let solution = Solution {
174    items: vec![
175    Item { group: 1, value: 3 },
176    Item { group: 1, value: 4 },
177    Item { group: 1, value: 5 },
178    ],
179    };
180
181    // 3+4+5=12 > 10, matches
182    assert_eq!(constraint.evaluate(&solution), SoftScore::of(-1));
183    ```
184
185    # Penalize 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 Task { priority: u32 }
195
196    #[derive(Clone)]
197    struct Solution { tasks: Vec<Task> }
198
199    let constraint = ConstraintFactory::<Solution, SoftScore>::new()
200    .for_each(Solution::tasks())
201    .join(equal(|t: &Task| t.priority))
202    .join(equal(|t: &Task| t.priority))
203    .penalize(SoftScore::of(5))
204    .named("Triple priority conflict");
205
206    let solution = Solution {
207    tasks: vec![
208    Task { priority: 1 },
209    Task { priority: 1 },
210    Task { priority: 1 },
211    ],
212    };
213
214    // One triple = -5
215    assert_eq!(constraint.evaluate(&solution), SoftScore::of(-5));
216    ```
217
218    # Penalize with dynamic weight
219
220    ```
221    use solverforge_scoring::stream::ConstraintFactory;
222    use solverforge_scoring::stream::joiner::equal;
223    use solverforge_scoring::api::constraint_set::IncrementalConstraint;
224    use solverforge_core::score::SoftScore;
225
226    #[derive(Clone, Debug, Hash, PartialEq, Eq)]
227    struct Task { team: u32, cost: i64 }
228
229    #[derive(Clone)]
230    struct Solution { tasks: Vec<Task> }
231
232    let constraint = ConstraintFactory::<Solution, SoftScore>::new()
233    .for_each(Solution::tasks())
234    .join(equal(|t: &Task| t.team))
235    .join(equal(|t: &Task| t.team))
236    .penalize(|a: &Task, b: &Task, c: &Task| {
237    SoftScore::of(a.cost + b.cost + c.cost)
238    })
239    .named("Team cost");
240
241    let solution = Solution {
242    tasks: vec![
243    Task { team: 1, cost: 2 },
244    Task { team: 1, cost: 3 },
245    Task { team: 1, cost: 5 },
246    ],
247    };
248
249    // Penalty: 2+3+5 = -10
250    assert_eq!(constraint.evaluate(&solution), SoftScore::of(-10));
251    ```
252
253    # Reward method
254
255    ```
256    use solverforge_scoring::stream::ConstraintFactory;
257    use solverforge_scoring::stream::joiner::equal;
258    use solverforge_scoring::api::constraint_set::IncrementalConstraint;
259    use solverforge_core::score::SoftScore;
260
261    #[derive(Clone, Debug, Hash, PartialEq, Eq)]
262    struct Person { team: u32 }
263
264    #[derive(Clone)]
265    struct Solution { people: Vec<Person> }
266
267    let constraint = ConstraintFactory::<Solution, SoftScore>::new()
268    .for_each(Solution::people())
269    .join(equal(|p: &Person| p.team))
270    .join(equal(|p: &Person| p.team))
271    .reward(SoftScore::of(10))
272    .named("Team synergy");
273
274    let solution = Solution {
275    people: vec![
276    Person { team: 1 },
277    Person { team: 1 },
278    Person { team: 1 },
279    ],
280    };
281
282    // One triple = +10
283    assert_eq!(constraint.evaluate(&solution), SoftScore::of(10));
284    ```
285
286    # named method
287
288    ```
289    use solverforge_scoring::stream::ConstraintFactory;
290    use solverforge_scoring::stream::joiner::equal;
291    use solverforge_scoring::api::constraint_set::IncrementalConstraint;
292    use solverforge_core::score::SoftScore;
293
294    #[derive(Clone, Debug, Hash, PartialEq, Eq)]
295    struct Item { id: usize }
296
297    #[derive(Clone)]
298    struct Solution { items: Vec<Item> }
299
300    let constraint = ConstraintFactory::<Solution, SoftScore>::new()
301    .for_each(Solution::items())
302    .join(equal(|i: &Item| i.id))
303    .join(equal(|i: &Item| i.id))
304    .penalize(SoftScore::of(1))
305    .named("Triple items");
306
307    assert_eq!(constraint.name(), "Triple items");
308    ```
309    */
310}