From 23f091399d9450ff514166077c129e36bad742c7 Mon Sep 17 00:00:00 2001 From: Vittorio Distefano Date: Sun, 15 Nov 2026 17:32:54 +0100 Subject: [PATCH 1/3] fix(test): rebuild tracing interest after installing capture subscribers Tracing caches callsite interest process-wide. A callsite another test thread registers while a scoped capture subscriber is being installed can keep the 'never' interest it computed without that subscriber, so the capturing test misses the event. Both capture helpers now rebuild the interest cache once their dispatcher is installed. Closes #263 --- crates/solverforge-console/src/format_tests.rs | 8 +++++++- .../src/phase/construction/telemetry.rs | 6 ++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/crates/solverforge-console/src/format_tests.rs b/crates/solverforge-console/src/format_tests.rs index e3f2f22c5..c89eef167 100644 --- a/crates/solverforge-console/src/format_tests.rs +++ b/crates/solverforge-console/src/format_tests.rs @@ -28,7 +28,13 @@ fn capture_events(f: impl FnOnce()) -> Vec { outputs: outputs.clone(), }); - tracing::subscriber::with_default(subscriber, f); + tracing::subscriber::with_default(subscriber, || { + // Callsite interest is cached process-wide; rebuild it once this + // thread's dispatcher is installed so a callsite another test thread + // registered concurrently cannot keep a "never" interest. + tracing::callsite::rebuild_interest_cache(); + f(); + }); let captured = outputs.lock().unwrap().clone(); captured } diff --git a/crates/solverforge-solver/src/phase/construction/telemetry.rs b/crates/solverforge-solver/src/phase/construction/telemetry.rs index 5d3435a02..19816bfd6 100644 --- a/crates/solverforge-solver/src/phase/construction/telemetry.rs +++ b/crates/solverforge-solver/src/phase/construction/telemetry.rs @@ -235,6 +235,12 @@ mod tests { solver_scope.start_solving(); tracing::subscriber::with_default(subscriber, || { + // Callsite interest is cached process-wide. A callsite another + // test thread registered while this dispatcher was being + // installed can keep the "never" interest it computed without + // it; rebuilding after the install makes this thread's + // dispatcher see every callsite. + tracing::callsite::rebuild_interest_cache(); run_construction_phase(&mut solver_scope, 3, "Test Construction", |phase_scope| { phase_scope.calculate_score(); phase_scope.update_best_solution(); From 432adf159579b6d9a5da4e8e1931ec8cfa6256e2 Mon Sep 17 00:00:00 2001 From: Vittorio Distefano Date: Sun, 15 Nov 2026 17:35:23 +0100 Subject: [PATCH 2/3] fix(scoring): apply the stream filter to uni grouped complements GroupedConstraintStream::complement and complement_with_key built their ComplementedConstraintStream from the extractor, key and collector but dropped the stream's accumulated filter, so rows a .filter(..) before .group_by(..) rejected were grouped and scored, and a key closure relying on the filter could panic. The complemented stream now carries the filter (type parameter Fi) and groups through a FilterNode, like the plain grouped stream. Closes #266 BREAKING CHANGE: ComplementedConstraintStream and ComplementedConstraintBuilder gain a filter type parameter Fi after EA. Code naming these types spells the extra parameter. --- crates/solverforge-scoring/WIREFRAME.md | 2 +- crates/solverforge-scoring/public-api.txt | 14 ++-- .../src/constraint/tests/complemented.rs | 82 +++++++++++++++++++ .../src/stream/complemented_stream.rs | 44 ++++++---- .../src/stream/grouped_stream/base.rs | 5 +- 5 files changed, 123 insertions(+), 24 deletions(-) diff --git a/crates/solverforge-scoring/WIREFRAME.md b/crates/solverforge-scoring/WIREFRAME.md index d3598a1d0..a2c01032f 100644 --- a/crates/solverforge-scoring/WIREFRAME.md +++ b/crates/solverforge-scoring/WIREFRAME.md @@ -903,7 +903,7 @@ further joins); low-level constructors are `new_self_join()` and **`BalanceConstraintStream/Builder`** — Balance stream. `penalize(weight)`, `reward(weight)`, `named()` → `BalanceConstraint` -**`ComplementedConstraintStream/Builder`** — Complemented stream. `penalize(weight_or_fn)`, `reward(weight_or_fn)`, `named()` → `SharedOperatorTerminal` over a `ComplementNode` + `GroupNode` tree. Dynamic weighted operations receive the real or complemented key as `Fn(&K, &R) -> Sc`. +**`ComplementedConstraintStream/Builder`** — Complemented stream. `penalize(weight_or_fn)`, `reward(weight_or_fn)`, `named()` → `SharedOperatorTerminal` over a `ComplementNode` + `GroupNode` tree. The group reads the source stream through its accumulated filter (type parameter `Fi`, after `EA`), so rows a `.filter(..)` before `.group_by(..)` rejects are never grouped. Dynamic weighted operations receive the real or complemented key as `Fn(&K, &R) -> Sc`. **`stream::projected::ComplementedGrouped/Builder`** — Projected grouped complement stream. `penalize(weight_or_fn)`, `reward(weight_or_fn)`, `named()` → `SharedOperatorTerminal` over `ComplementNode(CollectionNode, GroupNode)`. Complement defaults are produced from the complement entity and weighted by key plus collector result. diff --git a/crates/solverforge-scoring/public-api.txt b/crates/solverforge-scoring/public-api.txt index ca8272fd3..e2500a6d9 100644 --- a/crates/solverforge-scoring/public-api.txt +++ b/crates/solverforge-scoring/public-api.txt @@ -111,11 +111,11 @@ struct stream::BiConstraintStream: pub struct BiConstraintStream( self, weight: W, ) -> BiConstraintBuilder Sc + Send + Sync, Sc> where W: for<'w> ConstraintWeight<(&'w A, &'w A), Sc> + Send + Sync, stream::BiConstraintStream: pub fn reward( self, weight: W, ) -> BiConstraintBuilder Sc + Send + Sync, Sc> where W: for<'w> ConstraintWeight<(&'w A, &'w A), Sc> + Send + Sync, stream::BiConstraintStream: pub fn join( self, joiner: J, ) -> TriConstraintStream, Sc> where J: Joiner + 'static, F: 'static, -struct stream::ComplementedConstraintBuilder: pub struct ComplementedConstraintBuilder where Sc: Score,{ /* private fields */ } - stream::ComplementedConstraintBuilder: pub fn named( self, name: &str, ) -> SharedOperatorTerminal, GroupNode, impl for<'l> Fn(&Leaf<'l, A>) -> Option + Send + Sync, LeafCollector, Option, Acc, V, R>, ViewEqualPlan, OptionalEntityKey, GroupKey>, impl for<'l> Fn(&S, &Leaf<'l, B>) -> R + Send + Sync, R>, OptionalComplementAdapter, OperatorScorer, Sc>, Sc> -struct stream::ComplementedConstraintStream: pub struct ComplementedConstraintStream where Sc: Score,{ /* private fields */ } - stream::ComplementedConstraintStream: pub fn penalize( self, weight: W, ) -> ComplementedConstraintBuilder Sc + Send + Sync, Sc> where W: for<'w> ConstraintWeight<(&'w K, &'w R), Sc> + Send + Sync, - stream::ComplementedConstraintStream: pub fn reward( self, weight: W, ) -> ComplementedConstraintBuilder Sc + Send + Sync, Sc> where W: for<'w> ConstraintWeight<(&'w K, &'w R), Sc> + Send + Sync, +struct stream::ComplementedConstraintBuilder: pub struct ComplementedConstraintBuilder where Sc: Score,{ /* private fields */ } + stream::ComplementedConstraintBuilder: pub fn named( self, name: &str, ) -> SharedOperatorTerminal, GroupNode, LeafFilter>, impl for<'l> Fn(&Leaf<'l, A>) -> Option + Send + Sync, LeafCollector, Option, Acc, V, R>, ViewEqualPlan, OptionalEntityKey, GroupKey>, impl for<'l> Fn(&S, &Leaf<'l, B>) -> R + Send + Sync, R>, OptionalComplementAdapter, OperatorScorer, Sc>, Sc> +struct stream::ComplementedConstraintStream: pub struct ComplementedConstraintStream where Sc: Score,{ /* private fields */ } + stream::ComplementedConstraintStream: pub fn penalize( self, weight: W, ) -> ComplementedConstraintBuilder Sc + Send + Sync, Sc> where W: for<'w> ConstraintWeight<(&'w K, &'w R), Sc> + Send + Sync, + stream::ComplementedConstraintStream: pub fn reward( self, weight: W, ) -> ComplementedConstraintBuilder Sc + Send + Sync, Sc> where W: for<'w> ConstraintWeight<(&'w K, &'w R), Sc> + Send + Sync, struct stream::ConstraintFactory: pub struct ConstraintFactory { /* private fields */ } stream::ConstraintFactory: pub fn new() -> Self stream::ConstraintFactory: pub fn for_each( self, extractor: E, ) -> UniConstraintStream where A: Send + Sync + 'static, E: CollectionExtract, @@ -138,9 +138,9 @@ struct stream::GroupedConstraintBuilder: pub struct GroupedConstraintBuilder where Sc: Score,{ /* private fields */ } stream::GroupedConstraintStream: pub fn penalize( self, weight: W, ) -> GroupedConstraintBuilder Sc + Send + Sync, Sc> where W: for<'w> ConstraintWeight<(&'w K, &'w R), Sc> + Send + Sync, stream::GroupedConstraintStream: pub fn reward( self, weight: W, ) -> GroupedConstraintBuilder Sc + Send + Sync, Sc> where W: for<'w> ConstraintWeight<(&'w K, &'w R), Sc> + Send + Sync, - stream::GroupedConstraintStream: pub fn complement( self, extractor_b: EB, key_b: KB, default_fn: D, ) -> ComplementedConstraintStream Option + Send + Sync, KB, C, V, R, Acc, D, Sc> where B: Send + Sync + 'static, EB: CollectionExtract, KB: Fn(&B) -> K + Send + Sync, D: Fn(&B) -> R + Send + Sync + 'static, + stream::GroupedConstraintStream: pub fn complement( self, extractor_b: EB, key_b: KB, default_fn: D, ) -> ComplementedConstraintStream Option + Send + Sync, KB, C, V, R, Acc, D, Sc> where B: Send + Sync + 'static, EB: CollectionExtract, KB: Fn(&B) -> K + Send + Sync, D: Fn(&B) -> R + Send + Sync + 'static, stream::GroupedConstraintStream: pub fn join( self, target: (EB, KB), ) -> GroupedJoinedStream where B: Send + Sync + 'static, EB: CollectionExtract + 'static, KB: Fn(&B) -> K + Send + Sync + 'static, - stream::GroupedConstraintStream: pub fn complement_with_key( self, extractor_b: EB, key_a: KA2, key_b: KB, default_fn: D, ) -> ComplementedConstraintStream where B: Send + Sync + 'static, EB: CollectionExtract, KA2: Fn(&A) -> Option + Send + Sync, KB: Fn(&B) -> K + Send + Sync, D: Fn(&B) -> R + Send + Sync + 'static, + stream::GroupedConstraintStream: pub fn complement_with_key( self, extractor_b: EB, key_a: KA2, key_b: KB, default_fn: D, ) -> ComplementedConstraintStream where B: Send + Sync + 'static, EB: CollectionExtract, KA2: Fn(&A) -> Option + Send + Sync, KB: Fn(&B) -> K + Send + Sync, D: Fn(&B) -> R + Send + Sync + 'static, struct stream::HardWeight: pub struct HardWeight { /* private fields */ } struct stream::JoinedGroupedBuilder: pub struct JoinedGroupedBuilder, W, Sc> { /* private fields */ } stream::JoinedGroupedBuilder: pub fn named( self, name: &str, ) -> SharedOperatorTerminal, GroupAdapter, OperatorScorer< as AdaptWeight, W, Sc>>::RowWeight, Sc>, Sc> diff --git a/crates/solverforge-scoring/src/constraint/tests/complemented.rs b/crates/solverforge-scoring/src/constraint/tests/complemented.rs index 34641b259..66fe03ca1 100644 --- a/crates/solverforge-scoring/src/constraint/tests/complemented.rs +++ b/crates/solverforge-scoring/src/constraint/tests/complemented.rs @@ -221,3 +221,85 @@ fn only_grouped_side_notifications_change_group_keys() { assert_eq!(constraint.update_count(), 3); assert_eq!(constraint.changed_key_count(), 2); } + +fn shift_source() -> crate::stream::collection_extract::SourceExtract &[Shift]> { + source( + shifts as fn(&Schedule) -> &[Shift], + ChangeSource::Descriptor(0), + ) +} + +fn employee_source( +) -> crate::stream::collection_extract::SourceExtract &[Employee]> { + source( + employees as fn(&Schedule) -> &[Employee], + ChangeSource::Descriptor(1), + ) +} + +/// The filter applies before the group: the key closure may rely on it, and +/// filtered-out shifts are never counted, on the evaluation path, after +/// initialization and across a mutation that crosses the filter. +fn assert_filtered_complement(mut constraint: impl IncrementalConstraint) { + let mut plan = Schedule { + employees: vec![Employee { id: 0 }, Employee { id: 1 }], + shifts: vec![ + Shift { + employee_id: Some(0), + }, + Shift { employee_id: None }, + Shift { + employee_id: Some(1), + }, + ], + }; + // Employee 0: 1 shift, employee 1: 1 shift; the unassigned one is filtered. + assert_eq!(constraint.evaluate(&plan), SoftScore::of(-2)); + let mut total = constraint.initialize(&plan); + assert_eq!(total, SoftScore::of(-2)); + + // The unassigned shift becomes assigned to employee 0: it now passes. + total = total + constraint.on_retract(&plan, 1, 0); + plan.shifts[1].employee_id = Some(0); + total = total + constraint.on_insert(&plan, 1, 0); + assert_eq!(total, SoftScore::of(-3)); + assert_eq!(constraint.evaluate(&plan), total); + + // Employee 1's shift leaves the filter: employee 1 falls back to 0. + total = total + constraint.on_retract(&plan, 2, 0); + plan.shifts[2].employee_id = None; + total = total + constraint.on_insert(&plan, 2, 0); + assert_eq!(total, SoftScore::of(-2)); + assert_eq!(constraint.evaluate(&plan), total); +} + +#[test] +fn complement_applies_the_stream_filter_before_grouping() { + assert_filtered_complement( + ConstraintFactory::::new() + .for_each(shift_source()) + .filter(|shift: &Shift| shift.employee_id.is_some()) + .group_by(|shift: &Shift| shift.employee_id.unwrap(), count()) + .complement(employee_source(), |e: &Employee| e.id, |_e| 0usize) + .penalize(|_id: &usize, count: &usize| SoftScore::of(*count as i64)) + .named("Assigned shift count"), + ); +} + +#[test] +fn complement_with_key_applies_the_stream_filter_before_grouping() { + assert_filtered_complement( + ConstraintFactory::::new() + .for_each(shift_source()) + .filter(|shift: &Shift| shift.employee_id.is_some()) + .group_by(|shift: &Shift| shift.employee_id.unwrap(), count()) + .complement_with_key( + employee_source(), + |shift: &Shift| Some(shift.employee_id.unwrap()), + |e: &Employee| e.id, + |_e| 0usize, + ) + .penalize(|_id: &usize, count: &usize| SoftScore::of(*count as i64)) + .named("Assigned shift count"), + ); +} diff --git a/crates/solverforge-scoring/src/stream/complemented_stream.rs b/crates/solverforge-scoring/src/stream/complemented_stream.rs index e52aab0d8..aad69d4cf 100644 --- a/crates/solverforge-scoring/src/stream/complemented_stream.rs +++ b/crates/solverforge-scoring/src/stream/complemented_stream.rs @@ -11,8 +11,9 @@ use solverforge_core::ImpactType; use super::collection_extract::CollectionExtract; use super::collector::{Accumulator, Collector}; -use super::relational::leaf_collector::{leaf_key, LeafCollector, OptionalEntityKey}; -use super::relational::operator::{CollectionNode, ComplementNode, GroupNode}; +use super::filter::UniFilter; +use super::relational::leaf_collector::{leaf_key, LeafCollector, LeafFilter, OptionalEntityKey}; +use super::relational::operator::{CollectionNode, ComplementNode, FilterNode, GroupNode}; use super::relational::view_plan::{GroupKey, ViewEqualPlan}; use super::relational::Leaf; use super::weighting_support::ConstraintWeight; @@ -37,6 +38,7 @@ use crate::constraint::relational::{ /// - `B` - Complement entity type (e.g., Employee) /// - `K` - Group key type /// - `EA` - Extractor for A entities +/// - `Fi` - Filter on A entities, from the stream the group was built on /// - `EB` - Extractor for B entities (complement source) /// - `KA` - Key function for A (returns `Option` to allow filtering) /// - `KB` - Key function for B @@ -109,11 +111,12 @@ use crate::constraint::relational::{ /// // Employee 0: 2, Employee 1: 0, Employee 2: 0 → Total: -2 /// assert_eq!(constraint.evaluate(&schedule), SoftScore::of(-2)); /// ``` -pub struct ComplementedConstraintStream +pub struct ComplementedConstraintStream where Sc: Score, { extractor_a: EA, + filter: Fi, extractor_b: EB, key_a: KA, key_b: KB, @@ -131,14 +134,15 @@ where )>, } -impl - ComplementedConstraintStream +impl + ComplementedConstraintStream where S: Send + Sync + 'static, A: Send + Sync + 'static, B: Send + Sync + 'static, K: Clone + Eq + Hash + Send + Sync + 'static, EA: CollectionExtract, + Fi: UniFilter, EB: CollectionExtract, KA: Fn(&A) -> Option + Send + Sync, KB: Fn(&B) -> K + Send + Sync, @@ -154,12 +158,13 @@ where impact_type: ImpactType, weight_fn: W, is_hard: bool, - ) -> ComplementedConstraintBuilder + ) -> ComplementedConstraintBuilder where W: Fn(&K, &R) -> Sc + Send + Sync, { ComplementedConstraintBuilder { extractor_a: self.extractor_a, + filter: self.filter, extractor_b: self.extractor_b, key_a: self.key_a, key_b: self.key_b, @@ -175,6 +180,7 @@ where /// Creates a new complemented constraint stream. pub(crate) fn new( extractor_a: EA, + filter: Fi, extractor_b: EB, key_a: KA, key_b: KB, @@ -183,6 +189,7 @@ where ) -> Self { Self { extractor_a, + filter, extractor_b, key_a, key_b, @@ -206,6 +213,7 @@ where B, K, EA, + Fi, EB, KA, KB, @@ -242,6 +250,7 @@ where B, K, EA, + Fi, EB, KA, KB, @@ -265,8 +274,8 @@ where } } -impl std::fmt::Debug - for ComplementedConstraintStream +impl std::fmt::Debug + for ComplementedConstraintStream { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { f.debug_struct("ComplementedConstraintStream").finish() @@ -274,11 +283,12 @@ impl std::fmt::Debug } /// Zero-erasure builder for finalizing a complemented constraint. -pub struct ComplementedConstraintBuilder +pub struct ComplementedConstraintBuilder where Sc: Score, { extractor_a: EA, + filter: Fi, extractor_b: EB, key_a: KA, key_b: KB, @@ -299,14 +309,15 @@ where )>, } -impl - ComplementedConstraintBuilder +impl + ComplementedConstraintBuilder where S: Send + Sync + 'static, A: std::fmt::Debug + Send + Sync + 'static, B: std::fmt::Debug + Send + Sync + 'static, K: Clone + Eq + Hash + Send + Sync + 'static, EA: CollectionExtract + 'static, + Fi: UniFilter + 'static, EB: CollectionExtract + 'static, KA: Fn(&A) -> Option + Send + Sync + 'static, KB: Fn(&B) -> K + Send + Sync + Clone + 'static, @@ -330,7 +341,7 @@ where S, CollectionNode, GroupNode< - CollectionNode, + FilterNode, LeafFilter>, impl for<'l> Fn(&Leaf<'l, A>) -> Option + Send + Sync, LeafCollector, Option, @@ -350,7 +361,10 @@ where let key_b = self.key_b; let default_fn = self.default_fn; let group = GroupNode::new( - CollectionNode::new(self.extractor_a, 0), + FilterNode::new( + CollectionNode::new(self.extractor_a, 0), + LeafFilter::new(self.filter), + ), leaf_key(key_a), LeafCollector::new(self.collector), ); @@ -374,8 +388,8 @@ where // Finalizes the builder into a `Grouped`. } -impl std::fmt::Debug - for ComplementedConstraintBuilder +impl std::fmt::Debug + for ComplementedConstraintBuilder { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { f.debug_struct("ComplementedConstraintBuilder") diff --git a/crates/solverforge-scoring/src/stream/grouped_stream/base.rs b/crates/solverforge-scoring/src/stream/grouped_stream/base.rs index ffb714a3d..cca98a8b3 100644 --- a/crates/solverforge-scoring/src/stream/grouped_stream/base.rs +++ b/crates/solverforge-scoring/src/stream/grouped_stream/base.rs @@ -159,6 +159,7 @@ where B, K, E, + Fi, EB, impl Fn(&A) -> Option + Send + Sync, KB, @@ -179,6 +180,7 @@ where let wrapped_key_fn = crate::stream::closures::some_key::(key_fn); ComplementedConstraintStream::new( self.extractor, + self.filter, extractor_b, wrapped_key_fn, key_b, @@ -219,7 +221,7 @@ where key_a: KA2, key_b: KB, default_fn: D, - ) -> ComplementedConstraintStream + ) -> ComplementedConstraintStream where B: Send + Sync + 'static, EB: CollectionExtract, @@ -229,6 +231,7 @@ where { ComplementedConstraintStream::new( self.extractor, + self.filter, extractor_b, key_a, key_b, From 53d86875ebd50476625a96bc43ac8a3a6536d871 Mon Sep 17 00:00:00 2001 From: Vittorio Distefano Date: Sun, 15 Nov 2026 17:56:19 +0100 Subject: [PATCH 3/3] feat(shadows): propagate cascading list shadows across list owners A list shadow could only depend on the list holding its element. A start time that waits on a task in another owner's list (job shop, flow shop, transfers between vehicles) could not stay correct incrementally: the director refreshed only the changed owner's elements. #[shadow_variable_updates] gains `cascading_field` (an Option<_> element field), `cascading_compute` (a solution method computing it from the previous element and the dependencies) and `cascading_dependencies` (the elements an element waits on). SolverForge owns ordering, propagation, change reporting and undo: - CascadePropagation (solverforge-core) recomputes the downstream cone of the changed elements in dependency order: each element at most once, after its inputs, and only when an input changed, so propagation stops where a value is unchanged. Elements on a dependency cycle are unset. - The score director defers element rows to the end of the move when PlanningSolution::HAS_CASCADING_SHADOWS is true: owners refresh their list structure, the last owner of the move propagates, every written element is retracted before its write and inserted exactly once. - Solutions without a cascading shadow keep their path: the branch is on an associated constant, and the director carries one pointer for it. Tests: engine against a full refresh (cycles, pruning, 400 random moves), the director over random moves and undos, a planning_model! saw/mill model through the director and through a full_assert solve, a documented compiled example, and a compile-fail case. Closes #268 --- crates/solverforge-core/WIREFRAME.md | 20 + crates/solverforge-core/public-api.txt | 15 +- crates/solverforge-core/src/domain/cascade.rs | 327 ++++++++++++++++ crates/solverforge-core/src/domain/mod.rs | 2 + .../src/domain/tests/cascade_tests.rs | 364 +++++++++++++++++ .../solverforge-core/src/domain/tests/mod.rs | 1 + crates/solverforge-core/src/domain/traits.rs | 58 +++ crates/solverforge-macros/WIREFRAME.md | 12 + .../solverforge-macros/src/attr_validation.rs | 3 + .../solverforge-macros/src/planning_model.rs | 1 + .../src/planning_model/cascade.rs | 179 +++++++++ .../src/planning_model/manifest.rs | 3 + .../src/planning_model/metadata.rs | 3 + .../src/planning_model/shadows.rs | 44 ++- .../src/planning_solution/config.rs | 6 + .../src/planning_solution/shadow.rs | 68 ++++ ...cascading_shadow_without_list_structure.rs | 4 + ...ading_shadow_without_list_structure.stderr | 13 + .../domain/machine.rs | 13 + .../domain/mod.rs | 11 + .../domain/shop.rs | 30 ++ .../domain/task.rs | 21 + crates/solverforge-scoring/WIREFRAME.md | 10 + .../director/score_director/incremental.rs | 32 +- .../director/score_director/list_shadows.rs | 151 +++++++- .../src/director/tests/cascading_shadows.rs | 366 ++++++++++++++++++ .../src/director/tests/mod.rs | 1 + crates/solverforge-solver/WIREFRAME.md | 6 +- .../solverforge-solver/src/model_support.rs | 50 +++ crates/solverforge/src/__internal.rs | 6 +- .../tests/cascading_list_shadows.rs | 137 +++++++ .../cascading_list_shadows/domain/machine.rs | 13 + .../cascading_list_shadows/domain/mod.rs | 11 + .../cascading_list_shadows/domain/shop.rs | 91 +++++ .../cascading_list_shadows/domain/task.rs | 21 + crates/solverforge/tests/readme_examples.rs | 35 ++ .../tests/readme_examples/shop/machine.rs | 13 + .../tests/readme_examples/shop/mod.rs | 11 + .../tests/readme_examples/shop/plan.rs | 49 +++ .../tests/readme_examples/shop/task.rs | 21 + docs/modeling.md | 80 ++++ 41 files changed, 2281 insertions(+), 21 deletions(-) create mode 100644 crates/solverforge-core/src/domain/cascade.rs create mode 100644 crates/solverforge-core/src/domain/tests/cascade_tests.rs create mode 100644 crates/solverforge-macros/src/planning_model/cascade.rs create mode 100644 crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure.rs create mode 100644 crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure.stderr create mode 100644 crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/machine.rs create mode 100644 crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/mod.rs create mode 100644 crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/shop.rs create mode 100644 crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/task.rs create mode 100644 crates/solverforge-scoring/src/director/tests/cascading_shadows.rs create mode 100644 crates/solverforge/tests/cascading_list_shadows.rs create mode 100644 crates/solverforge/tests/cascading_list_shadows/domain/machine.rs create mode 100644 crates/solverforge/tests/cascading_list_shadows/domain/mod.rs create mode 100644 crates/solverforge/tests/cascading_list_shadows/domain/shop.rs create mode 100644 crates/solverforge/tests/cascading_list_shadows/domain/task.rs create mode 100644 crates/solverforge/tests/readme_examples/shop/machine.rs create mode 100644 crates/solverforge/tests/readme_examples/shop/mod.rs create mode 100644 crates/solverforge/tests/readme_examples/shop/plan.rs create mode 100644 crates/solverforge/tests/readme_examples/shop/task.rs diff --git a/crates/solverforge-core/WIREFRAME.md b/crates/solverforge-core/WIREFRAME.md index 36b7f5a48..d31b601b0 100644 --- a/crates/solverforge-core/WIREFRAME.md +++ b/crates/solverforge-core/WIREFRAME.md @@ -49,6 +49,7 @@ src/ ├── domain/ │ ├── mod.rs — Module declarations and re-exports for domain types │ ├── traits.rs — PlanningSolution, PlanningEntity, ProblemFact, PlanningId +│ ├── cascade.rs — CascadePropagation: cascading list shadow propagation across list owners │ ├── dynamic.rs — DynamicModelBackend, scalar/list access contracts, explicit list access/metadata capabilities │ ├── dynamic/ │ │ ├── assignment.rs — Dynamic scalar-assignment metadata contract and structural capabilities @@ -151,6 +152,14 @@ Additionally, `pub mod constraint`, `pub mod constraint_weights`, `pub mod domai | `list_shadow_elements` | `fn list_shadow_elements(&self, descriptor_index: usize, entity_index: usize) -> Option<(usize, &[usize])>` | Default: `None`; the elements an owner's shadow update writes, with the change source their stream rows use | | `clear_list_shadows` | `fn clear_list_shadows(&mut self, element: usize)` | Default: no-op; clears the list shadows of an element no list holds | | `list_shadow_source` | `fn list_shadow_source(collection: &str) -> Option` | Default: `None`; change source of a collection whose rows carry list shadows | +| `HAS_CASCADING_SHADOWS` | `const HAS_CASCADING_SHADOWS: bool` | Default: `false`; `true` when the list shadows include a cascading shadow (`#[shadow_variable_updates(cascading_field = ...)]`). A score director compiles cascading propagation into its variable-change path only when it is `true` | +| `cascading_element_count` | `fn cascading_element_count(&self) -> usize` | Default: `0`; elements of the collection carrying the cascading shadow | +| `cascading_assigned` | `fn cascading_assigned(&self, element: usize) -> bool` | Default: `false`; whether a list holds `element` | +| `cascading_next` | `fn cascading_next(&self, element: usize) -> Option` | Default: `None`; the element after `element` in its list | +| `cascading_dependencies` | `fn cascading_dependencies(&self, element: usize, dependencies: &mut Vec)` | Default: none; appends the elements `element` waits on besides its previous element. Dependencies are problem facts | +| `cascading_unset` | `fn cascading_unset(&self, element: usize) -> bool` | Default: `true`; whether the cascading value is unset | +| `update_cascading_shadow` | `fn update_cascading_shadow(&mut self, element: usize, computable: bool, before_write: W) -> bool` | Default: `false`; recomputes (or, when `computable` is `false`, unsets) the value, calls `before_write` before writing a changed value, returns whether it changed | +| `update_list_structure_shadows` | `fn update_list_structure_shadows(&mut self, descriptor_index: usize, entity_index: usize)` | Default: `update_entity_shadows`; refreshes one owner's inverse, index, previous and next shadows without the cascading shadow | | `is_initialized` | `fn is_initialized(&self) -> bool` | Default: `true` | **Associated type:** `type Score: Score` @@ -328,6 +337,17 @@ pub struct EntityRef { Derives: `Debug, Clone` +#### `CascadePropagation` + +Reusable propagation state for a solution's cascading list shadow (see +`PlanningSolution::HAS_CASCADING_SHADOWS`): the reverse index of the declared +dependencies plus per-element scratch. `Default`. + +- `new(&S) -> Self` — state with the dependency index built. +- `rebuild_dependencies(&mut self, &S)` — rebuilds the index and resizes scratch; panics on a dependency to a missing element. +- `refresh_all(&mut S)` — recomputes every cascading value. +- `propagate(&mut self, &mut S, changed: I, before_write: W)` with `I: IntoIterator`, `W: FnMut(&S, usize)` — recomputes the downstream cone of the `changed` elements in dependency order: each element at most once, after its inputs in the cone, and only when it is changed, an input changed value, or it is held by a list but unset; elements on a dependency cycle are unset. `before_write` sees the solution before each write. + #### `EntityCollectionExtractor` ```rust diff --git a/crates/solverforge-core/public-api.txt b/crates/solverforge-core/public-api.txt index 4d4ec9180..c6417ae5c 100644 --- a/crates/solverforge-core/public-api.txt +++ b/crates/solverforge-core/public-api.txt @@ -11,6 +11,11 @@ struct constraint_weights::ConstraintWeights: pub struct ConstraintWeights { /* constraint_weights::ConstraintWeights: pub fn len(&self) -> usize constraint_weights::ConstraintWeights: pub fn iter(&self) -> impl Iterator constraint_weights::ConstraintWeights: pub fn validate<'a>( &self, known: impl IntoIterator, ) -> Result<(), ConstraintWeightError> +struct domain::CascadePropagation: pub struct CascadePropagation { /* private fields */ } + domain::CascadePropagation: pub fn new(solution: &S) -> Self + domain::CascadePropagation: pub fn rebuild_dependencies(&mut self, solution: &S) + domain::CascadePropagation: pub fn refresh_all(solution: &mut S) + domain::CascadePropagation: pub fn propagate( &mut self, solution: &mut S, changed: I, before_write: W, ) where S: PlanningSolution, I: IntoIterator, W: FnMut(&S, usize), struct domain::DynamicListAccessCapabilities: pub struct DynamicListAccessCapabilities { pub set: bool, pub replace: bool, pub reverse: bool, pub sublist: bool, } struct domain::DynamicListMetadataCapabilities: pub struct DynamicListMetadataCapabilities { pub element_owner: bool, pub construction_order_key: bool, pub precedence_duration: bool, pub precedence_successors: bool, pub cross_position_distance: bool, pub intra_position_distance: bool, pub route: bool, pub savings: bool, } struct domain::DynamicListVariableSlot: pub struct DynamicListVariableSlot { pub entity: EntityClassId, pub variable: VariableId, pub entity_type_name: &'static str, pub variable_name: &'static str, /* private fields */ } @@ -291,8 +296,9 @@ trait domain::PlanningEntity: pub trait PlanningEntity: Clone + Send + Sync + An trait domain::PlanningId: pub trait PlanningId { type Id: Eq + Hash + Clone + Send + Sync + 'static; // Required method fn planning_id(&self) -> Self::Id; } domain::PlanningId: type Id: Eq + Hash + Clone + Send + Sync + 'static domain::PlanningId: fn planning_id(&self) -> Self::Id -trait domain::PlanningSolution: pub trait PlanningSolution: Clone + Send + Sync + 'static { type Score: Score; const HAS_CONSTRAINT_WEIGHTS: bool = false; // Required methods fn score(&self) -> Option; fn set_score(&mut self, score: Option); // Provided methods fn update_entity_shadows( &mut self, _descriptor_index: usize, _entity_index: usize, ) { ... } fn update_all_shadows(&mut self) { ... } fn constraint_weights(&self) -> Option<&ConstraintWeights> { ... } fn list_shadow_elements( &self, _descriptor_index: usize, _entity_index: usize, ) -> Option<(usize, &[usize])> { ... } fn clear_list_shadows(&mut self, _element: usize) { ... } fn list_shadow_source(_collection: &str) -> Option { ... } fn is_initialized(&self) -> bool { ... } } +trait domain::PlanningSolution: pub trait PlanningSolution: Clone + Send + Sync + 'static { type Score: Score; const HAS_CONSTRAINT_WEIGHTS: bool = false; const HAS_CASCADING_SHADOWS: bool = false; Show 16 methods // Required methods fn score(&self) -> Option; fn set_score(&mut self, score: Option); // Provided methods fn update_entity_shadows( &mut self, _descriptor_index: usize, _entity_index: usize, ) { ... } fn update_all_shadows(&mut self) { ... } fn constraint_weights(&self) -> Option<&ConstraintWeights> { ... } fn list_shadow_elements( &self, _descriptor_index: usize, _entity_index: usize, ) -> Option<(usize, &[usize])> { ... } fn clear_list_shadows(&mut self, _element: usize) { ... } fn list_shadow_source(_collection: &str) -> Option { ... } fn cascading_element_count(&self) -> usize { ... } fn cascading_assigned(&self, _element: usize) -> bool { ... } fn cascading_next(&self, _element: usize) -> Option { ... } fn cascading_dependencies( &self, _element: usize, _dependencies: &mut Vec, ) { ... } fn cascading_unset(&self, _element: usize) -> bool { ... } fn update_cascading_shadow( &mut self, _element: usize, _computable: bool, _before_write: W, ) -> bool { ... } fn update_list_structure_shadows( &mut self, descriptor_index: usize, entity_index: usize, ) { ... } fn is_initialized(&self) -> bool { ... } } domain::PlanningSolution: const HAS_CONSTRAINT_WEIGHTS: bool = false + domain::PlanningSolution: const HAS_CASCADING_SHADOWS: bool = false domain::PlanningSolution: type Score: Score domain::PlanningSolution: fn score(&self) -> Option domain::PlanningSolution: fn set_score(&mut self, score: Option) @@ -302,6 +308,13 @@ trait domain::PlanningSolution: pub trait PlanningSolution: Clone + Send + Sync domain::PlanningSolution: fn list_shadow_elements( &self, _descriptor_index: usize, _entity_index: usize, ) -> Option<(usize, &[usize])> domain::PlanningSolution: fn clear_list_shadows(&mut self, _element: usize) domain::PlanningSolution: fn list_shadow_source(_collection: &str) -> Option + domain::PlanningSolution: fn cascading_element_count(&self) -> usize + domain::PlanningSolution: fn cascading_assigned(&self, _element: usize) -> bool + domain::PlanningSolution: fn cascading_next(&self, _element: usize) -> Option + domain::PlanningSolution: fn cascading_dependencies( &self, _element: usize, _dependencies: &mut Vec, ) + domain::PlanningSolution: fn cascading_unset(&self, _element: usize) -> bool + domain::PlanningSolution: fn update_cascading_shadow( &mut self, _element: usize, _computable: bool, _before_write: W, ) -> bool + domain::PlanningSolution: fn update_list_structure_shadows( &mut self, descriptor_index: usize, entity_index: usize, ) domain::PlanningSolution: fn is_initialized(&self) -> bool trait domain::ProblemFact: pub trait ProblemFact: Clone + Send + Sync + Any + 'static { // Required method fn as_any(&self) -> &dyn Any; } domain::ProblemFact: fn as_any(&self) -> &dyn Any diff --git a/crates/solverforge-core/src/domain/cascade.rs b/crates/solverforge-core/src/domain/cascade.rs new file mode 100644 index 000000000..4eb988aa2 --- /dev/null +++ b/crates/solverforge-core/src/domain/cascade.rs @@ -0,0 +1,327 @@ +//! Propagation of cascading list shadows across list owners. +//! +//! A cascading value depends on the element's previous element in its list +//! and on the elements it declares it depends on, which other owners' lists +//! may hold. The dependency graph has an edge from an element's previous +//! element and from each of its dependencies to the element. After list +//! changes, [`CascadePropagation::propagate`] visits the downstream cone of +//! the changed elements and recomputes it in dependency order: an element is +//! recomputed at most once, only after every input in the cone is final, and +//! only when an input value changed (or it is a changed element itself), so +//! propagation stops where a recomputed value equals the old one. Elements +//! on a dependency cycle have no defined value and are unset. + +use super::PlanningSolution; + +const UNVISITED: usize = usize::MAX; + +/// Reusable propagation state for one solution's cascading shadow. +/// +/// Holds the reverse index of the declared dependencies, built by +/// [`rebuild_dependencies`](Self::rebuild_dependencies) and valid while the +/// dependencies and the element count stay unchanged, plus per-element +/// scratch that every propagation leaves cleared. +#[derive(Default)] +pub struct CascadePropagation { + // Elements that declare a dependency on each element, as compressed + // rows: the dependents of `e` are `dependents[offsets[e]..offsets[e + 1]]`. + offsets: Vec, + dependents: Vec, + // Per-element scratch, cleared after each propagation. + in_cone: Vec, + dirty: Vec, + done: Vec, + cycle: Vec, + pending_inputs: Vec, + order: Vec, + low: Vec, + on_stack: Vec, + cone: Vec, + stack: Vec, + ready: Vec, + scratch: Vec, +} + +impl CascadePropagation { + /// Propagation state for `solution`, with its dependency index built. + pub fn new(solution: &S) -> Self { + let mut propagation = Self::default(); + propagation.rebuild_dependencies(solution); + propagation + } + + /// Rebuilds the reverse dependency index from `solution` and sizes the + /// per-element scratch to its element count. + /// + /// # Panics + /// + /// When an element declares a dependency on an element index that does + /// not exist. + pub fn rebuild_dependencies(&mut self, solution: &S) { + let count = solution.cascading_element_count(); + self.offsets.clear(); + self.offsets.resize(count + 1, 0); + for element in 0..count { + self.scratch.clear(); + solution.cascading_dependencies(element, &mut self.scratch); + for &dependency in &self.scratch { + assert!( + dependency < count, + "cascading element {element} depends on element {dependency}, but there are only {count} elements" + ); + self.offsets[dependency + 1] += 1; + } + } + for element in 0..count { + self.offsets[element + 1] += self.offsets[element]; + } + self.dependents.clear(); + self.dependents.resize(self.offsets[count], 0); + let mut fill = self.offsets.clone(); + for element in 0..count { + self.scratch.clear(); + solution.cascading_dependencies(element, &mut self.scratch); + for &dependency in &self.scratch { + self.dependents[fill[dependency]] = element; + fill[dependency] += 1; + } + } + self.scratch.clear(); + for flags in [ + &mut self.in_cone, + &mut self.dirty, + &mut self.done, + &mut self.cycle, + &mut self.on_stack, + ] { + flags.clear(); + flags.resize(count, false); + } + self.pending_inputs.clear(); + self.pending_inputs.resize(count, 0); + self.order.clear(); + self.order.resize(count, UNVISITED); + self.low.clear(); + self.low.resize(count, UNVISITED); + } + + /// Recomputes every cascading value of `solution` from scratch. + pub fn refresh_all(solution: &mut S) { + let mut propagation = Self::new(solution); + let count = solution.cascading_element_count(); + propagation.propagate(solution, 0..count, |_, _| {}); + } + + /// Recomputes the cascading values downstream of `changed`, the elements + /// whose list position or list membership changed. + /// + /// Every element of `changed` is recomputed; another element of the + /// downstream cone is recomputed when one of its inputs changed value, or + /// when it is held by a list but unset (it may have left a dependency + /// cycle). Each element is recomputed at most once, after all of its + /// inputs in the cone. Before an element's value is written, + /// `before_write` is called with the solution still holding the old value + /// and the element index. + pub fn propagate(&mut self, solution: &mut S, changed: I, mut before_write: W) + where + S: PlanningSolution, + I: IntoIterator, + W: FnMut(&S, usize), + { + for element in changed { + self.dirty[element] = true; + if !self.in_cone[element] { + self.in_cone[element] = true; + self.cone.push(element); + self.stack.push(element); + } + } + while let Some(element) = self.stack.pop() { + if let Some(next) = solution.cascading_next(element) { + self.reach(next); + } + for position in self.offsets[element]..self.offsets[element + 1] { + self.reach(self.dependents[position]); + } + } + + self.ready.extend( + self.cone + .iter() + .copied() + .filter(|&element| self.pending_inputs[element] == 0), + ); + let mut finished = 0; + loop { + while let Some(element) = self.ready.pop() { + self.done[element] = true; + finished += 1; + let assigned = solution.cascading_assigned(element); + if (self.dirty[element] || (assigned && solution.cascading_unset(element))) + && solution.update_cascading_shadow(element, assigned, |solution| { + before_write(solution, element) + }) + { + self.mark_outputs_dirty(solution, element); + } + self.release_outputs(solution, element); + } + if finished == self.cone.len() { + break; + } + // The remaining elements wait on a dependency cycle. Cycle + // members are unset; the elements downstream of them are then + // computed from the unset values. + self.mark_cycles(solution); + for index in 0..self.cone.len() { + let element = self.cone[index]; + if self.cycle[element] && !self.done[element] { + self.done[element] = true; + finished += 1; + if solution.update_cascading_shadow(element, false, |solution| { + before_write(solution, element) + }) { + self.mark_outputs_dirty(solution, element); + } + } + } + for index in 0..self.cone.len() { + let element = self.cone[index]; + if self.cycle[element] { + self.release_outputs(solution, element); + } + } + } + + for &element in &self.cone { + self.in_cone[element] = false; + self.dirty[element] = false; + self.done[element] = false; + self.cycle[element] = false; + self.pending_inputs[element] = 0; + self.order[element] = UNVISITED; + self.low[element] = UNVISITED; + } + self.cone.clear(); + } + + fn reach(&mut self, element: usize) { + self.pending_inputs[element] += 1; + if !self.in_cone[element] { + self.in_cone[element] = true; + self.cone.push(element); + self.stack.push(element); + } + } + + fn mark_outputs_dirty(&mut self, solution: &S, element: usize) { + if let Some(next) = solution.cascading_next(element) { + self.dirty[next] = true; + } + for position in self.offsets[element]..self.offsets[element + 1] { + self.dirty[self.dependents[position]] = true; + } + } + + fn release_outputs(&mut self, solution: &S, element: usize) { + if let Some(next) = solution.cascading_next(element) { + self.release(next); + } + for position in self.offsets[element]..self.offsets[element + 1] { + self.release(self.dependents[position]); + } + } + + fn release(&mut self, element: usize) { + self.pending_inputs[element] -= 1; + if self.pending_inputs[element] == 0 && !self.done[element] && !self.cycle[element] { + self.ready.push(element); + } + } + + /// Marks the members of every dependency cycle among the unfinished + /// elements of the cone (strongly connected components with more than + /// one element, or an element that depends on itself). Runs only when + /// propagation stalls on a cycle. + #[cold] + fn mark_cycles(&mut self, solution: &S) { + let mut next_order = 0; + let mut components = Vec::new(); + // Each frame holds an element and its unfinished outputs still to visit. + let mut frames: Vec<(usize, Vec)> = Vec::new(); + for index in 0..self.cone.len() { + let root = self.cone[index]; + if self.done[root] || self.order[root] != UNVISITED { + continue; + } + self.enter( + solution, + root, + &mut next_order, + &mut components, + &mut frames, + ); + while let Some((element, outputs)) = frames.last_mut() { + let element = *element; + if let Some(output) = outputs.pop() { + if self.order[output] == UNVISITED { + self.enter( + solution, + output, + &mut next_order, + &mut components, + &mut frames, + ); + } else if self.on_stack[output] { + self.low[element] = self.low[element].min(self.order[output]); + } + continue; + } + frames.pop(); + if let Some((parent, _)) = frames.last() { + self.low[*parent] = self.low[*parent].min(self.low[element]); + } + if self.low[element] == self.order[element] { + let start = components + .iter() + .rposition(|&member| member == element) + .expect("component root is on the stack"); + let self_loop = self.depends_on_itself(solution, element); + let is_cycle = components.len() - start > 1 || self_loop; + for member in components.drain(start..) { + self.on_stack[member] = false; + self.cycle[member] = is_cycle; + } + } + } + } + } + + fn enter( + &mut self, + solution: &S, + element: usize, + next_order: &mut usize, + components: &mut Vec, + frames: &mut Vec<(usize, Vec)>, + ) { + self.order[element] = *next_order; + self.low[element] = *next_order; + *next_order += 1; + self.on_stack[element] = true; + components.push(element); + let mut outputs = Vec::new(); + if let Some(next) = solution.cascading_next(element) { + outputs.push(next); + } + outputs + .extend_from_slice(&self.dependents[self.offsets[element]..self.offsets[element + 1]]); + outputs.retain(|&output| self.in_cone[output] && !self.done[output]); + frames.push((element, outputs)); + } + + fn depends_on_itself(&self, solution: &S, element: usize) -> bool { + solution.cascading_next(element) == Some(element) + || self.dependents[self.offsets[element]..self.offsets[element + 1]].contains(&element) + } +} diff --git a/crates/solverforge-core/src/domain/mod.rs b/crates/solverforge-core/src/domain/mod.rs index cf49cf86d..de16821f1 100644 --- a/crates/solverforge-core/src/domain/mod.rs +++ b/crates/solverforge-core/src/domain/mod.rs @@ -6,6 +6,7 @@ //! - `ProblemFact`: Immutable input data //! - `PlanningId`: Unique identification for entities +mod cascade; mod descriptor; mod dynamic; mod entity_ref; @@ -15,6 +16,7 @@ mod variable; #[cfg(test)] mod tests; +pub use cascade::CascadePropagation; pub use descriptor::{ EntityClassId, EntityDescriptor, ProblemFactClassId, ProblemFactDescriptor, SolutionDescriptor, UsizeCandidateValues, UsizeConstructionEntityOrderKey, UsizeConstructionValueOrderKey, diff --git a/crates/solverforge-core/src/domain/tests/cascade_tests.rs b/crates/solverforge-core/src/domain/tests/cascade_tests.rs new file mode 100644 index 000000000..982df31f2 --- /dev/null +++ b/crates/solverforge-core/src/domain/tests/cascade_tests.rs @@ -0,0 +1,364 @@ +// Cascading shadow propagation across list owners, checked against a full +// refresh: a two-machine shop whose tasks wait on tasks in the other +// machine's list. + +use crate::domain::{CascadePropagation, PlanningSolution}; +use crate::score::SoftScore; + +#[derive(Clone, Debug, Default)] +struct Task { + duration: i64, + waits_on: Vec, + machine: Option, + previous: Option, + next: Option, + start: Option, +} + +#[derive(Clone, Debug)] +struct Shop { + machines: Vec>, + tasks: Vec, + computes: usize, + score: Option, +} + +impl Shop { + fn new(machines: Vec>, durations: &[i64], waits_on: &[(usize, usize)]) -> Self { + let mut tasks: Vec = durations + .iter() + .map(|&duration| Task { + duration, + ..Task::default() + }) + .collect(); + for &(task, dependency) in waits_on { + tasks[task].waits_on.push(dependency); + } + let mut shop = Self { + machines, + tasks, + computes: 0, + score: None, + }; + shop.refresh(); + shop + } + + fn end(&self, task: usize) -> Option { + self.tasks[task] + .start + .map(|start| start + self.tasks[task].duration) + } + + // The later of the previous task's end and every dependency's end; + // unset when any of them is unset. + fn compute_start(&self, task: usize) -> Option { + let mut start = 0; + if let Some(previous) = self.tasks[task].previous { + start = start.max(self.end(previous)?); + } + for &dependency in &self.tasks[task].waits_on { + start = start.max(self.end(dependency)?); + } + Some(start) + } + + fn refresh_structure(&mut self, machine: usize) { + let list = self.machines[machine].clone(); + for (position, &task) in list.iter().enumerate() { + let task = &mut self.tasks[task]; + task.machine = Some(machine); + task.previous = position.checked_sub(1).map(|previous| list[previous]); + task.next = list.get(position + 1).copied(); + } + } + + fn refresh(&mut self) { + for task in &mut self.tasks { + task.machine = None; + task.previous = None; + task.next = None; + } + for machine in 0..self.machines.len() { + self.refresh_structure(machine); + } + CascadePropagation::refresh_all(self); + } + + fn starts(&self) -> Vec> { + self.tasks.iter().map(|task| task.start).collect() + } +} + +impl PlanningSolution for Shop { + type Score = SoftScore; + + fn score(&self) -> Option { + self.score + } + + fn set_score(&mut self, score: Option) { + self.score = score; + } + + const HAS_CASCADING_SHADOWS: bool = true; + + fn cascading_element_count(&self) -> usize { + self.tasks.len() + } + + fn cascading_assigned(&self, element: usize) -> bool { + self.tasks[element].machine.is_some() + } + + fn cascading_next(&self, element: usize) -> Option { + self.tasks[element].next + } + + fn cascading_dependencies(&self, element: usize, dependencies: &mut Vec) { + dependencies.extend_from_slice(&self.tasks[element].waits_on); + } + + fn cascading_unset(&self, element: usize) -> bool { + self.tasks[element].start.is_none() + } + + fn update_cascading_shadow( + &mut self, + element: usize, + computable: bool, + before_write: W, + ) -> bool { + let start = if computable { + self.computes += 1; + self.compute_start(element) + } else { + None + }; + if self.tasks[element].start == start { + return false; + } + before_write(self); + self.tasks[element].start = start; + true + } +} + +/// Applies a list change to `machines`, refreshes their structure, clears +/// tasks no list holds any more, and propagates from every task the changed +/// machines held before or after. Returns the elements written. +fn change( + shop: &mut Shop, + propagation: &mut CascadePropagation, + machines: &[usize], + edit: impl FnOnce(&mut Vec>), +) -> Vec { + let mut changed: Vec = machines + .iter() + .flat_map(|&machine| shop.machines[machine].clone()) + .collect(); + edit(&mut shop.machines); + for &machine in machines { + changed.extend(shop.machines[machine].iter().copied()); + } + changed.sort_unstable(); + changed.dedup(); + for &task in &changed { + if !shop.machines.iter().any(|list| list.contains(&task)) { + let task = &mut shop.tasks[task]; + task.machine = None; + task.previous = None; + task.next = None; + } + } + for &machine in machines { + shop.refresh_structure(machine); + } + let mut written = Vec::new(); + propagation.propagate(shop, changed, |_, element| written.push(element)); + written +} + +fn assert_fresh(shop: &Shop) { + let mut fresh = shop.clone(); + fresh.refresh(); + assert_eq!( + shop.starts(), + fresh.starts(), + "machines {:?}", + shop.machines + ); +} + +// saw = machine 0, mill = machine 1. Task 1 (milling) waits on task 0 +// (cutting). +fn saw_and_mill() -> Shop { + Shop::new(vec![vec![0, 2], vec![1, 3]], &[4, 3, 5, 2], &[(1, 0)]) +} + +#[test] +fn a_full_refresh_follows_dependencies_across_lists() { + let shop = saw_and_mill(); + // Saw: cut 0..4, task 2 4..9. Mill: milling waits on the cut, 4..7, task 3 7..9. + assert_eq!(shop.starts(), vec![Some(0), Some(4), Some(4), Some(7)]); +} + +#[test] +fn a_change_in_one_list_retimes_the_dependents_in_another() { + let mut shop = saw_and_mill(); + let mut propagation = CascadePropagation::new(&shop); + shop.tasks.push(Task { + duration: 10, + ..Task::default() + }); + propagation.rebuild_dependencies(&shop); + + // A long task 4 goes before the cut: the cut, the milling and the task + // after the milling all start later. + let written = change(&mut shop, &mut propagation, &[0], |machines| { + machines[0].insert(0, 4) + }); + assert_eq!( + shop.starts(), + vec![Some(10), Some(14), Some(14), Some(17), Some(0)] + ); + assert_fresh(&shop); + let mut written = written; + written.sort_unstable(); + assert_eq!(written, vec![0, 1, 2, 3, 4]); +} + +#[test] +fn propagation_stops_where_a_value_does_not_change() { + // Mill: task 3 (long) then the milling task 1, which waits on the cut 0 + // but is already held back by task 3. + let mut shop = Shop::new( + vec![vec![0, 2], vec![3, 1, 4]], + &[4, 3, 5, 20, 2], + &[(1, 0)], + ); + let mut propagation = CascadePropagation::new(&shop); + assert_eq!(shop.tasks[1].start, Some(20)); + + // Swapping the saw's tasks moves the cut's end from 4 to 9, still before + // 20: the milling task is recomputed, unchanged, and task 4 is not. + shop.computes = 0; + let written = change(&mut shop, &mut propagation, &[0], |machines| { + machines[0].swap(0, 1) + }); + assert_fresh(&shop); + assert_eq!(written, vec![2, 0]); + // Tasks 0 and 2 (changed) and task 1 (an input changed). + assert_eq!(shop.computes, 3); +} + +#[test] +fn a_dependency_cycle_is_unset_and_its_dependents_follow() { + // Saw: 0 then 2. Task 0 waits on task 2, which comes after it. + let shop = Shop::new(vec![vec![0, 2], vec![1]], &[4, 3, 5], &[(0, 2), (1, 2)]); + assert_eq!(shop.starts(), vec![None, None, None]); + + // Breaking the cycle by moving task 2 to the mill's front gives every + // task a start again. + let mut shop = shop; + let mut propagation = CascadePropagation::new(&shop); + change(&mut shop, &mut propagation, &[0, 1], |machines| { + machines[0].retain(|&task| task != 2); + machines[1].insert(0, 2); + }); + assert_eq!(shop.starts(), vec![Some(5), Some(5), Some(0)]); + assert_fresh(&shop); + + // And creating it again unsets them. + change(&mut shop, &mut propagation, &[0, 1], |machines| { + machines[1].retain(|&task| task != 2); + machines[0].push(2); + }); + assert_eq!(shop.starts(), vec![None, None, None]); + assert_fresh(&shop); +} + +#[test] +fn an_element_that_depends_on_itself_is_unset() { + let shop = Shop::new(vec![vec![0, 1]], &[4, 3], &[(0, 0)]); + assert_eq!(shop.starts(), vec![None, None]); +} + +// A deterministic pseudo-random sequence (64-bit LCG). +struct Lcg(u64); + +impl Lcg { + fn below(&mut self, bound: usize) -> usize { + self.0 = self + .0 + .wrapping_mul(6364136223846793005) + .wrapping_add(1442695040888963407); + ((self.0 >> 33) as usize) % bound + } +} + +#[test] +fn random_moves_across_three_machines_match_a_full_refresh() { + let durations: Vec = (0..18).map(|task| (task % 5 + 1) as i64).collect(); + // Each task after the first six waits on one or two earlier tasks. + let waits: Vec<(usize, usize)> = (6..18) + .flat_map(|task| [(task, task - 6), (task, (task * 7 + 3) % task)]) + .filter(|&(task, dependency)| task != dependency) + .collect(); + let machines = vec![ + (0..6).collect::>(), + (6..12).collect(), + (12..16).collect(), + ]; + let mut shop = Shop::new(machines, &durations, &waits); + let mut propagation = CascadePropagation::new(&shop); + let mut random = Lcg(7); + + for step in 0..400 { + let from = random.below(3); + let to = random.below(3); + let touched: Vec = if from == to { + vec![from] + } else { + vec![from, to] + }; + let written_before = shop.computes; + match random.below(3) { + // Move a task between (or within) machines. + 0 if !shop.machines[from].is_empty() => { + let task = shop.machines[from][random.below(shop.machines[from].len())]; + let position = random.below(shop.machines[to].len() + 1); + change(&mut shop, &mut propagation, &touched, |machines| { + machines[from].retain(|&held| held != task); + let position = position.min(machines[to].len()); + machines[to].insert(position, task); + }); + } + // Unassign a task. + 1 if !shop.machines[from].is_empty() => { + let position = random.below(shop.machines[from].len()); + change(&mut shop, &mut propagation, &[from], |machines| { + machines[from].remove(position); + }); + } + // Assign an unassigned task. + _ => { + let unassigned: Vec = (0..shop.tasks.len()) + .filter(|&task| shop.tasks[task].machine.is_none()) + .collect(); + if let Some(&task) = unassigned.get(random.below(unassigned.len().max(1))) { + let position = random.below(shop.machines[to].len() + 1); + change(&mut shop, &mut propagation, &[to], |machines| { + machines[to].insert(position, task) + }); + } + } + } + assert!( + shop.computes - written_before <= shop.tasks.len(), + "step {step}: an element was computed more than once" + ); + assert_fresh(&shop); + } +} diff --git a/crates/solverforge-core/src/domain/tests/mod.rs b/crates/solverforge-core/src/domain/tests/mod.rs index 8d9c99316..1aa0c76a4 100644 --- a/crates/solverforge-core/src/domain/tests/mod.rs +++ b/crates/solverforge-core/src/domain/tests/mod.rs @@ -1,5 +1,6 @@ // Tests for domain types (entity_ref, variable). +mod cascade_tests; mod dynamic_list_tests; mod entity_ref_tests; mod variable_tests; diff --git a/crates/solverforge-core/src/domain/traits.rs b/crates/solverforge-core/src/domain/traits.rs index 3326ab0cb..2fd38207e 100644 --- a/crates/solverforge-core/src/domain/traits.rs +++ b/crates/solverforge-core/src/domain/traits.rs @@ -117,6 +117,64 @@ pub trait PlanningSolution: Clone + Send + Sync + 'static { None } + /// Whether the list shadows include a cascading shadow: an element value + /// computed from the element's previous element in its list and from the + /// elements it declares it depends on, which may sit in other owners' + /// lists. + /// + /// `#[shadow_variable_updates(cascading_field = ...)]` sets it to `true` + /// and generates the `cascading_*` hooks below. When it is `false` + /// (the default) a score director compiles no cascading code into its + /// variable-change path. + const HAS_CASCADING_SHADOWS: bool = false; + + /// Number of elements in the collection that carries the cascading + /// shadow. + fn cascading_element_count(&self) -> usize { + 0 + } + + /// Whether `element` is held by a list. + fn cascading_assigned(&self, _element: usize) -> bool { + false + } + + /// The element after `element` in its list, if any. + fn cascading_next(&self, _element: usize) -> Option { + None + } + + /// Appends the elements `element`'s cascading value depends on, besides + /// its previous element in its list, to `dependencies`. Dependencies are + /// problem facts: moves never change them. + fn cascading_dependencies(&self, _element: usize, _dependencies: &mut Vec) {} + + /// Whether `element`'s cascading value is unset. + fn cascading_unset(&self, _element: usize) -> bool { + true + } + + /// Recomputes `element`'s cascading value, or unsets it when + /// `computable` is `false` (the element is in no list, or on a + /// dependency cycle). When the value changes, calls `before_write` with + /// the solution still holding the old value, then writes the new one and + /// returns `true`. + fn update_cascading_shadow( + &mut self, + _element: usize, + _computable: bool, + _before_write: W, + ) -> bool { + false + } + + /// Updates the list shadows of one owner that describe list structure + /// (inverse, index, previous, next) without the cascading shadow, which + /// the caller propagates afterwards. Defaults to `update_entity_shadows`. + fn update_list_structure_shadows(&mut self, descriptor_index: usize, entity_index: usize) { + self.update_entity_shadows(descriptor_index, entity_index); + } + /// Returns true if this solution is fully initialized. /// /// A solution is initialized when all planning variables have been assigned. diff --git a/crates/solverforge-macros/WIREFRAME.md b/crates/solverforge-macros/WIREFRAME.md index 7b63294b3..9da998f86 100644 --- a/crates/solverforge-macros/WIREFRAME.md +++ b/crates/solverforge-macros/WIREFRAME.md @@ -239,6 +239,9 @@ arguments are compile errors. - `post_update_listener = "method"` — method name called after all shadow updates per entity - `entity_aggregate = "target:sum:source"` — aggregate element field onto entity (sum only) - `entity_compute = "target:method"` — compute entity field via method +- `cascading_field = "field"` — `Option<_>` element field computed from the previous element in its list and the element's dependencies, propagated across list owners; requires `cascading_compute`, `inverse_field`, `previous_field` and `next_field`, and rejects `cascading_listener`, `post_update_listener`, `entity_aggregate` and `entity_compute` +- `cascading_compute = "method"` — solution method `fn(&self, element: usize) -> Option<_>` computing the cascading value of an element held by a list +- `cascading_dependencies = "method"` — solution method returning the elements an element waits on, as `IntoIterator`; optional **`#[planning_list_variable]` parameters:** - `element_collection = "field"` — solution field with all list elements @@ -388,6 +391,15 @@ descriptors. Stream sources of `#[problem_fact_collection]` and react to that source instead of staying static, so constraints that read element shadows score incrementally. +With `cascading_field`, the generated support sets +`PlanningSolution::HAS_CASCADING_SHADOWS = true` and implements the +`cascading_*` hooks, `update_cascading_shadow` and +`update_list_structure_shadows` (the owner update without the cascading +shadow). `update_entity_shadows` refreshes the owner's structure, then +propagates the cascading values from its elements with `CascadePropagation`; +`update_all_shadows()` clears the structure fields, refreshes every owner's +structure, then recomputes every cascading value. + ## Test Coverage - `tests/trybuild.rs` — compile-pass and compile-fail coverage for the public macros, including rejection of removed field arguments, unsupported shadow annotations, and duplicate, mistyped, or argument-carrying `#[constraint_weights]` fields diff --git a/crates/solverforge-macros/src/attr_validation.rs b/crates/solverforge-macros/src/attr_validation.rs index cf728539c..097df9cee 100644 --- a/crates/solverforge-macros/src/attr_validation.rs +++ b/crates/solverforge-macros/src/attr_validation.rs @@ -109,6 +109,9 @@ const SHADOW_UPDATES_ARGS: &[AttributeArgSpec] = &[ AttributeArgSpec::string("previous_field"), AttributeArgSpec::string("next_field"), AttributeArgSpec::string("cascading_listener"), + AttributeArgSpec::string("cascading_field"), + AttributeArgSpec::string("cascading_compute"), + AttributeArgSpec::string("cascading_dependencies"), AttributeArgSpec::string("post_update_listener"), AttributeArgSpec::repeated_string("entity_aggregate"), AttributeArgSpec::repeated_string("entity_compute"), diff --git a/crates/solverforge-macros/src/planning_model.rs b/crates/solverforge-macros/src/planning_model.rs index eaa616112..34402a16f 100644 --- a/crates/solverforge-macros/src/planning_model.rs +++ b/crates/solverforge-macros/src/planning_model.rs @@ -28,5 +28,6 @@ include!("planning_model/support.rs"); include!("planning_model/scalar_candidate_hooks.rs"); include!("planning_model/scalar_order_hooks.rs"); include!("planning_model/shadows.rs"); +include!("planning_model/cascade.rs"); #[cfg(test)] include!("planning_model/tests.rs"); diff --git a/crates/solverforge-macros/src/planning_model/cascade.rs b/crates/solverforge-macros/src/planning_model/cascade.rs new file mode 100644 index 000000000..6dc3d9eb5 --- /dev/null +++ b/crates/solverforge-macros/src/planning_model/cascade.rs @@ -0,0 +1,179 @@ +/* Cascading list shadows: an element field computed from the element's +previous element in its list and from the elements it declares it depends +on, which other owners' lists may hold. The generated hooks give +`CascadePropagation` the dependency graph and the per-element update; the +propagation itself, its ordering and its change reporting are SolverForge's. +*/ + +struct CascadeContext<'a> { + solution_path: &'a TokenStream, + element_accessor: &'a Ident, + element_mut_accessor: &'a Ident, +} + +fn validate_cascade_config(config: &ShadowConfig) -> Result<()> { + let error = |message: &str| Err(Error::new(proc_macro2::Span::call_site(), message)); + if config.cascading_field.is_none() { + if config.cascading_compute.is_some() || config.cascading_dependencies.is_some() { + return error( + "#[shadow_variable_updates(...)] `cascading_compute` and `cascading_dependencies` require `cascading_field = \"element_field\"`", + ); + } + return Ok(()); + } + if config.cascading_compute.is_none() { + return error( + "#[shadow_variable_updates(cascading_field = ...)] requires `cascading_compute = \"solution_method\"`, a `fn(&self, element: usize) -> Option<_>` on the solution", + ); + } + if config.inverse_field.is_none() + || config.previous_field.is_none() + || config.next_field.is_none() + { + return error( + "#[shadow_variable_updates(cascading_field = ...)] requires `inverse_field`, `previous_field` and `next_field`: propagation follows each element's list position", + ); + } + if config.cascading_listener.is_some() + || config.post_update_listener.is_some() + || !config.entity_aggregates.is_empty() + || !config.entity_computes.is_empty() + { + return error( + "#[shadow_variable_updates(cascading_field = ...)] cannot be combined with `cascading_listener`, `post_update_listener`, `entity_aggregate` or `entity_compute`: those run per changed owner and would not see cascading values that a move changes in other owners' lists", + ); + } + Ok(()) +} + +fn generate_cascade_hooks(config: &ShadowConfig, context: &CascadeContext<'_>) -> TokenStream { + let span = proc_macro2::Span::call_site(); + let CascadeContext { + solution_path, + element_accessor, + element_mut_accessor, + } = context; + let field = Ident::new(config.cascading_field.as_deref().unwrap(), span); + let compute = Ident::new(config.cascading_compute.as_deref().unwrap(), span); + let inverse = Ident::new(config.inverse_field.as_deref().unwrap(), span); + let next = Ident::new(config.next_field.as_deref().unwrap(), span); + let dependencies = config + .cascading_dependencies + .as_deref() + .map(|method| { + let method = Ident::new(method, span); + quote! { dependencies.extend(solution.#method(element)); } + }) + .unwrap_or_default(); + quote! { + fn cascading_element_count(solution: &Self) -> usize { + #solution_path::#element_accessor(solution).len() + } + + fn cascading_assigned(solution: &Self, element: usize) -> bool { + #solution_path::#element_accessor(solution)[element].#inverse.is_some() + } + + fn cascading_next(solution: &Self, element: usize) -> ::core::option::Option { + #solution_path::#element_accessor(solution)[element].#next + } + + #[allow(unused_variables)] + fn cascading_dependencies( + solution: &Self, + element: usize, + dependencies: &mut ::std::vec::Vec, + ) { + #dependencies + } + + fn cascading_unset(solution: &Self, element: usize) -> bool { + #solution_path::#element_accessor(solution)[element].#field.is_none() + } + + fn update_cascading_shadow( + solution: &mut Self, + element: usize, + computable: bool, + before_write: W, + ) -> bool { + let value = if computable { + solution.#compute(element) + } else { + ::core::option::Option::None + }; + if #solution_path::#element_accessor(solution)[element].#field == value { + return false; + } + before_write(solution); + #solution_path::#element_mut_accessor(solution)[element].#field = value; + true + } + } +} + +/* Shadow methods for a model with a cascading shadow: the owner update +refreshes list structure only, `update_entity_shadows` then propagates the +cascading values from the owner's elements, and `update_all_shadows` +refreshes every owner's structure before recomputing every value. +*/ +fn generate_cascading_shadow_methods( + generated: &GeneratedListShadowUpdate, + solution_path: &TokenStream, + descriptor_index: usize, + owner_accessor: &Ident, +) -> TokenStream { + let list_update = &generated.update; + let list_reset = &generated.reset; + let list_elements = &generated.elements; + let cascade_hooks = &generated.cascade; + let list_variable = &generated.list_variable; + quote! { + fn update_list_structure_shadows( + solution: &mut Self, + descriptor_index: usize, + entity_index: usize, + ) -> bool { + let mut updated = false; + #list_update + updated + } + + fn update_entity_shadows( + solution: &mut Self, + descriptor_index: usize, + entity_index: usize, + ) -> bool { + let updated = ::update_list_structure_shadows( + solution, + descriptor_index, + entity_index, + ); + if updated { + let changed = #solution_path::#owner_accessor(solution)[entity_index] + .#list_variable + .to_vec(); + ::solverforge::__internal::CascadePropagation::new(&*solution) + .propagate(solution, changed, |_, _| {}); + } + updated + } + + fn update_all_shadows(solution: &mut Self) -> bool { + #list_reset + for entity_index in 0..#solution_path::#owner_accessor(solution).len() { + let _ = ::update_list_structure_shadows( + solution, + #descriptor_index, + entity_index, + ); + } + ::solverforge::__internal::CascadePropagation::refresh_all(solution); + true + } + + #list_elements + + #cascade_hooks + } +} diff --git a/crates/solverforge-macros/src/planning_model/manifest.rs b/crates/solverforge-macros/src/planning_model/manifest.rs index 7b451810a..38e325291 100644 --- a/crates/solverforge-macros/src/planning_model/manifest.rs +++ b/crates/solverforge-macros/src/planning_model/manifest.rs @@ -129,6 +129,9 @@ struct ShadowConfig { previous_field: Option, next_field: Option, cascading_listener: Option, + cascading_field: Option, + cascading_compute: Option, + cascading_dependencies: Option, post_update_listener: Option, entity_aggregates: Vec, entity_computes: Vec, diff --git a/crates/solverforge-macros/src/planning_model/metadata.rs b/crates/solverforge-macros/src/planning_model/metadata.rs index 8cb402df6..41a853fe7 100644 --- a/crates/solverforge-macros/src/planning_model/metadata.rs +++ b/crates/solverforge-macros/src/planning_model/metadata.rs @@ -76,6 +76,9 @@ fn parse_shadow_config(attrs: &[Attribute]) -> Result { config.previous_field = parse_attribute_string(attr, "previous_field"); config.next_field = parse_attribute_string(attr, "next_field"); config.cascading_listener = parse_attribute_string(attr, "cascading_listener"); + config.cascading_field = parse_attribute_string(attr, "cascading_field"); + config.cascading_compute = parse_attribute_string(attr, "cascading_compute"); + config.cascading_dependencies = parse_attribute_string(attr, "cascading_dependencies"); config.post_update_listener = parse_attribute_string(attr, "post_update_listener"); config.entity_aggregates = parse_attribute_list(attr, "entity_aggregate"); config.entity_computes = parse_attribute_list(attr, "entity_compute"); diff --git a/crates/solverforge-macros/src/planning_model/shadows.rs b/crates/solverforge-macros/src/planning_model/shadows.rs index da2f61bcc..43e008e67 100644 --- a/crates/solverforge-macros/src/planning_model/shadows.rs +++ b/crates/solverforge-macros/src/planning_model/shadows.rs @@ -4,6 +4,10 @@ struct GeneratedListShadowUpdate { descriptor: Option<(usize, Ident)>, // Element reporting, present when the update writes element fields. elements: TokenStream, + // Cascading shadow hooks, present when `cascading_field` is configured. + cascade: TokenStream, + // The owner's list variable field. + list_variable: TokenStream, } fn generate_shadow_methods(model: &ModelMetadata) -> Result { @@ -11,11 +15,11 @@ fn generate_shadow_methods(model: &ModelMetadata) -> Result { let solution_ident = &model.solution.ident; let solution_path = quote! { #solution_module::#solution_ident }; let generated = generate_list_shadow_update(model, &solution_path)?; - let list_update = generated.update; - let list_reset = generated.reset; - let list_elements = generated.elements; + let list_update = generated.update.clone(); + let list_reset = generated.reset.clone(); + let list_elements = generated.elements.clone(); - let Some((descriptor_index, collection_accessor)) = generated.descriptor else { + let Some((descriptor_index, collection_accessor)) = generated.descriptor.clone() else { return Ok(quote! { fn update_entity_shadows( _solution: &mut Self, @@ -31,6 +35,15 @@ fn generate_shadow_methods(model: &ModelMetadata) -> Result { }); }; + if model.solution.shadow_config.cascading_field.is_some() { + return Ok(generate_cascading_shadow_methods( + &generated, + &solution_path, + descriptor_index, + &collection_accessor, + )); + } + Ok(quote! { fn update_entity_shadows( solution: &mut Self, @@ -63,12 +76,15 @@ fn generate_list_shadow_update( solution_path: &TokenStream, ) -> Result { let config = &model.solution.shadow_config; + validate_cascade_config(config)?; if !list_shadow_updates_requested(config) { return Ok(GeneratedListShadowUpdate { update: TokenStream::new(), reset: TokenStream::new(), descriptor: None, elements: TokenStream::new(), + cascade: TokenStream::new(), + list_variable: TokenStream::new(), }); } @@ -246,7 +262,8 @@ fn generate_list_shadow_update( || config.index_field.is_some() || config.previous_field.is_some() || config.next_field.is_some() - || config.cascading_listener.is_some(); + || config.cascading_listener.is_some() + || config.cascading_field.is_some(); let element_source = element_collection.descriptor_index.unwrap_or_else(|| { model .solution @@ -286,11 +303,25 @@ fn generate_list_shadow_update( } else { TokenStream::new() }; + let cascade = if config.cascading_field.is_some() { + generate_cascade_hooks( + config, + &CascadeContext { + solution_path, + element_accessor: &element_accessor, + element_mut_accessor: &element_mut_accessor, + }, + ) + } else { + TokenStream::new() + }; Ok(GeneratedListShadowUpdate { update, reset: element_reset.unwrap_or_default(), descriptor: Some((descriptor_index, owner_accessor)), elements, + cascade, + list_variable: quote! { #list_variable_ident }, }) } @@ -345,7 +376,8 @@ fn generate_list_compute_updates( } fn list_shadow_updates_requested(config: &ShadowConfig) -> bool { - config.inverse_field.is_some() + config.cascading_field.is_some() + || config.inverse_field.is_some() || config.index_field.is_some() || config.previous_field.is_some() || config.next_field.is_some() diff --git a/crates/solverforge-macros/src/planning_solution/config.rs b/crates/solverforge-macros/src/planning_solution/config.rs index e57cc3685..0bd3fc26c 100644 --- a/crates/solverforge-macros/src/planning_solution/config.rs +++ b/crates/solverforge-macros/src/planning_solution/config.rs @@ -11,6 +11,9 @@ pub(super) struct ShadowConfig { pub(super) previous_field: Option, pub(super) next_field: Option, pub(super) cascading_listener: Option, + pub(super) cascading_field: Option, + pub(super) cascading_compute: Option, + pub(super) cascading_dependencies: Option, pub(super) post_update_listener: Option, pub(super) entity_aggregates: Vec, pub(super) entity_computes: Vec, @@ -129,6 +132,9 @@ pub(super) fn parse_shadow_config(attrs: &[syn::Attribute]) -> ShadowConfig { config.previous_field = parse_attribute_string(attr, "previous_field"); config.next_field = parse_attribute_string(attr, "next_field"); config.cascading_listener = parse_attribute_string(attr, "cascading_listener"); + config.cascading_field = parse_attribute_string(attr, "cascading_field"); + config.cascading_compute = parse_attribute_string(attr, "cascading_compute"); + config.cascading_dependencies = parse_attribute_string(attr, "cascading_dependencies"); config.post_update_listener = parse_attribute_string(attr, "post_update_listener"); config.entity_aggregates = parse_attribute_list(attr, "entity_aggregate"); config.entity_computes = parse_attribute_list(attr, "entity_compute"); diff --git a/crates/solverforge-macros/src/planning_solution/shadow.rs b/crates/solverforge-macros/src/planning_solution/shadow.rs index cd1099c58..52c118f06 100644 --- a/crates/solverforge-macros/src/planning_solution/shadow.rs +++ b/crates/solverforge-macros/src/planning_solution/shadow.rs @@ -10,6 +10,7 @@ fn shadow_updates_requested(config: &ShadowConfig) -> bool { || config.previous_field.is_some() || config.next_field.is_some() || config.cascading_listener.is_some() + || config.cascading_field.is_some() || config.post_update_listener.is_some() || !config.entity_aggregates.is_empty() || !config.entity_computes.is_empty() @@ -31,7 +32,74 @@ pub(super) fn generate_shadow_support( )); } + let cascading = if config.cascading_field.is_some() { + quote! { + const HAS_CASCADING_SHADOWS: bool = true; + + #[inline] + fn cascading_element_count(&self) -> usize { + ::cascading_element_count(self) + } + + #[inline] + fn cascading_assigned(&self, element: usize) -> bool { + ::cascading_assigned(self, element) + } + + #[inline] + fn cascading_next(&self, element: usize) -> ::core::option::Option { + ::cascading_next(self, element) + } + + #[inline] + fn cascading_dependencies( + &self, + element: usize, + dependencies: &mut ::std::vec::Vec, + ) { + ::cascading_dependencies( + self, + element, + dependencies, + ) + } + + #[inline] + fn cascading_unset(&self, element: usize) -> bool { + ::cascading_unset(self, element) + } + + #[inline] + fn update_cascading_shadow( + &mut self, + element: usize, + computable: bool, + before_write: W, + ) -> bool { + ::update_cascading_shadow( + self, + element, + computable, + before_write, + ) + } + + #[inline] + fn update_list_structure_shadows(&mut self, descriptor_index: usize, entity_idx: usize) { + let _ = ::update_list_structure_shadows( + self, + descriptor_index, + entity_idx, + ); + } + } + } else { + TokenStream::new() + }; + Ok(quote! { + #cascading + #[inline] fn update_entity_shadows(&mut self, descriptor_index: usize, entity_idx: usize) { let _ = ::update_entity_shadows( diff --git a/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure.rs b/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure.rs new file mode 100644 index 000000000..9f8fb39ce --- /dev/null +++ b/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure.rs @@ -0,0 +1,4 @@ +#[path = "cascading_shadow_without_list_structure/domain/mod.rs"] +mod domain; + +fn main() {} diff --git a/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure.stderr b/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure.stderr new file mode 100644 index 000000000..83dccfd09 --- /dev/null +++ b/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure.stderr @@ -0,0 +1,13 @@ +error: #[shadow_variable_updates(cascading_field = ...)] requires `inverse_field`, `previous_field` and `next_field`: propagation follows each element's list position + --> tests/ui/fail/cascading_shadow_without_list_structure/domain/mod.rs + | + | / solverforge::planning_model! { + | | root = "crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain"; + | | + | | mod machine; +... | + | | pub use task::Task; + | | } + | |_^ + | + = note: this error originates in the macro `solverforge::planning_model` (in Nightly builds, run with -Z macro-backtrace for more info) diff --git a/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/machine.rs b/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/machine.rs new file mode 100644 index 000000000..c2f3ea1e4 --- /dev/null +++ b/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/machine.rs @@ -0,0 +1,13 @@ +use solverforge::prelude::*; + +/// A machine that processes its tasks in list order. +#[planning_entity] +pub struct Machine { + /// Stable machine id. + #[planning_id] + pub id: usize, + + /// The tasks the machine processes, in order. + #[planning_list_variable(element_collection = "tasks")] + pub tasks: Vec, +} diff --git a/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/mod.rs b/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/mod.rs new file mode 100644 index 000000000..e312e841e --- /dev/null +++ b/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/mod.rs @@ -0,0 +1,11 @@ +solverforge::planning_model! { + root = "crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain"; + + mod machine; + mod shop; + mod task; + + pub use machine::Machine; + pub use shop::Shop; + pub use task::Task; +} diff --git a/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/shop.rs b/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/shop.rs new file mode 100644 index 000000000..384ecc25f --- /dev/null +++ b/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/shop.rs @@ -0,0 +1,30 @@ +use solverforge::prelude::*; + +use super::{Machine, Task}; + +// Cascading shadows follow each element's list position, so the next field +// is required. +#[planning_solution] +#[shadow_variable_updates( + list_owner = "machines", + inverse_field = "machine", + previous_field = "previous", + cascading_field = "start", + cascading_compute = "compute_start" +)] +pub struct Shop { + #[planning_entity_collection] + pub machines: Vec, + + #[problem_fact_collection] + pub tasks: Vec, + + #[planning_score] + pub score: Option, +} + +impl Shop { + pub fn compute_start(&self, _task: usize) -> Option { + Some(0) + } +} diff --git a/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/task.rs b/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/task.rs new file mode 100644 index 000000000..929b69f66 --- /dev/null +++ b/crates/solverforge-macros/tests/ui/fail/cascading_shadow_without_list_structure/domain/task.rs @@ -0,0 +1,21 @@ +use solverforge::prelude::*; + +/// A task with a duration that may wait on a task of another machine. +#[problem_fact] +pub struct Task { + /// Stable task id. + #[planning_id] + pub id: usize, + /// Processing time. + pub duration: i64, + /// The task that must end before this one starts. + pub waits_on: Option, + /// The machine holding the task (list shadow). + pub machine: Option, + /// The task before this one on its machine (list shadow). + pub previous: Option, + /// The task after this one on its machine (list shadow). + pub next: Option, + /// When the task starts (cascading list shadow). + pub start: Option, +} diff --git a/crates/solverforge-scoring/WIREFRAME.md b/crates/solverforge-scoring/WIREFRAME.md index a2c01032f..f58de90ac 100644 --- a/crates/solverforge-scoring/WIREFRAME.md +++ b/crates/solverforge-scoring/WIREFRAME.md @@ -501,6 +501,16 @@ inserts the owner and every element it now holds, and clears and re-inserts elements that left the owner without joining another list. Element rows therefore always hold the shadows they were inserted with. +When `S::HAS_CASCADING_SHADOWS` is `true`, element rows are deferred to the +end of the move: each `after_variable_changed` refreshes only the owner's list +structure (`update_list_structure_shadows`) and inserts the owner, and when the +move's last notified owner has been refreshed the director propagates the +cascading values (`CascadePropagation`) from every element those owners held +before or after the move. An element written during propagation is retracted +before its write unless it is already pending, and every pending element is +inserted once. The branch is on the associated constant, so other solutions +compile none of it. + ### `SolvableSolution` — `: PlanningSolution` | Method | Signature | Note | diff --git a/crates/solverforge-scoring/src/director/score_director/incremental.rs b/crates/solverforge-scoring/src/director/score_director/incremental.rs index 12650f2a6..c1d43af98 100644 --- a/crates/solverforge-scoring/src/director/score_director/incremental.rs +++ b/crates/solverforge-scoring/src/director/score_director/incremental.rs @@ -217,6 +217,10 @@ where descriptor_index, entity_index, ); + if S::HAS_CASCADING_SHADOWS { + self.list_shadow_rows + .begin_cascading_change(&self.working_solution); + } let mut score = ScoreSum::new(); score.add(self.cached_score); score.add(delta); @@ -232,15 +236,25 @@ where if !self.initialized { return; } - let delta = self.list_shadow_rows.refresh_owner( - &mut self.working_solution, - &mut ModeRows { - constraints: &mut self.constraints, - mode: &self.weight_mode, - }, - descriptor_index, - entity_index, - ); + let mut rows = ModeRows { + constraints: &mut self.constraints, + mode: &self.weight_mode, + }; + let delta = if S::HAS_CASCADING_SHADOWS { + self.list_shadow_rows.refresh_cascading_owner( + &mut self.working_solution, + &mut rows, + descriptor_index, + entity_index, + ) + } else { + self.list_shadow_rows.refresh_owner( + &mut self.working_solution, + &mut rows, + descriptor_index, + entity_index, + ) + }; self.cached_score = self.cached_score + delta; } diff --git a/crates/solverforge-scoring/src/director/score_director/list_shadows.rs b/crates/solverforge-scoring/src/director/score_director/list_shadows.rs index 850566aba..75ea7e76e 100644 --- a/crates/solverforge-scoring/src/director/score_director/list_shadows.rs +++ b/crates/solverforge-scoring/src/director/score_director/list_shadows.rs @@ -16,8 +16,17 @@ //! //! Pending marks are reused across moves, so tracking allocates only while the //! element count grows. +//! +//! A solution with a cascading shadow (`PlanningSolution::HAS_CASCADING_SHADOWS`) +//! defers element rows to the end of the move instead: owners refresh only +//! their list structure, and once every owner the move notified has been +//! refreshed, the cascading values are propagated from the elements those +//! owners held before or after the move. Each element written along the way is +//! retracted before its write unless it is already pending, and every pending +//! element is inserted exactly once at the end. Solutions without a cascading +//! shadow never reach that code: the branch is on an associated constant. -use solverforge_core::domain::PlanningSolution; +use solverforge_core::domain::{CascadePropagation, PlanningSolution}; use solverforge_core::score::Score; use super::weight_mode::RowDeltas; @@ -34,12 +43,30 @@ struct PendingElement { pub(super) struct ListShadowRows { pending: Vec, is_pending: Vec, + // Present only for solutions with a cascading shadow, from their first + // notified change; boxed so other solutions pay one pointer. + cascade: Option>, +} + +struct CascadeRows { + propagation: CascadePropagation, + // Owner notifications of the current move still waiting for their + // `after` half. + open_changes: usize, + // The change source of element rows. + source: usize, + // Elements a refreshed owner holds after the move. + held: Vec, + // The elements propagation starts from, reused across moves. + seeds: Vec, } impl ListShadowRows { pub(super) fn clear(&mut self) { self.pending.clear(); self.is_pending.fill(false); + // The dependency index is rebuilt from the next solution. + self.cascade = None; } fn mark(&mut self, element: usize, pending: bool) { @@ -135,4 +162,126 @@ impl ListShadowRows { } delta } + + /// Opens one owner notification of a cascading move. + pub(super) fn begin_cascading_change(&mut self, solution: &S) { + let cascade = self.cascade.get_or_insert_with(|| { + Box::new(CascadeRows { + propagation: CascadePropagation::new(solution), + open_changes: 0, + source: 0, + held: vec![false; solution.cascading_element_count()], + seeds: Vec::new(), + }) + }); + cascade.open_changes += 1; + } + + /// Refreshes one owner's list structure for a cascading move and inserts + /// the owner's row; element rows stay retracted until the move's last + /// owner is refreshed, when the cascading values are propagated and every + /// pending element is inserted once. + pub(super) fn refresh_cascading_owner( + &mut self, + solution: &mut S, + constraints: &mut C, + owner_descriptor: usize, + owner_index: usize, + ) -> S::Score + where + S: PlanningSolution, + C: RowDeltas, + { + let mut delta = S::Score::zero(); + solution.update_list_structure_shadows(owner_descriptor, owner_index); + delta = delta + constraints.insert_row(solution, owner_index, owner_descriptor); + if let Some((source, elements)) = + solution.list_shadow_elements(owner_descriptor, owner_index) + { + let cascade = self + .cascade + .as_mut() + .expect("a cascading change was opened"); + cascade.source = source; + for &element in elements { + cascade.held[element] = true; + if !self.is_pending.get(element).copied().unwrap_or(false) { + // An arrival from no list: its row still holds the + // shadows it was inserted with. + delta = delta + constraints.retract_row(solution, element, source); + if element >= self.is_pending.len() { + self.is_pending.resize(element + 1, false); + } + self.is_pending[element] = true; + self.pending.push(PendingElement { + element, + source, + owner_descriptor, + owner_index, + }); + } + } + } + let cascade = self + .cascade + .as_mut() + .expect("a cascading change was opened"); + cascade.open_changes -= 1; + if cascade.open_changes == 0 { + delta = delta + self.finish_cascading_move(solution, constraints); + } + delta + } + + fn finish_cascading_move(&mut self, solution: &mut S, constraints: &mut C) -> S::Score + where + S: PlanningSolution, + C: RowDeltas, + { + let mut delta = S::Score::zero(); + let cascade = self + .cascade + .as_mut() + .expect("a cascading change was opened"); + // Elements that left their owner and joined no refreshed owner are in + // no list. + for entry in &self.pending { + if !cascade.held[entry.element] { + solution.clear_list_shadows(entry.element); + } + } + let CascadeRows { + propagation, + source, + held, + seeds, + .. + } = &mut **cascade; + let source = *source; + seeds.clear(); + seeds.extend(self.pending.iter().map(|entry| entry.element)); + let pending = &mut self.pending; + let is_pending = &mut self.is_pending; + propagation.propagate(solution, seeds.iter().copied(), |solution, element| { + if !is_pending.get(element).copied().unwrap_or(false) { + delta = delta + constraints.retract_row(solution, element, source); + if element >= is_pending.len() { + is_pending.resize(element + 1, false); + } + is_pending[element] = true; + pending.push(PendingElement { + element, + source, + owner_descriptor: usize::MAX, + owner_index: usize::MAX, + }); + } + }); + for entry in self.pending.drain(..) { + delta = delta + constraints.insert_row(solution, entry.element, entry.source); + self.is_pending[entry.element] = false; + held[entry.element] = false; + } + delta + } } diff --git a/crates/solverforge-scoring/src/director/tests/cascading_shadows.rs b/crates/solverforge-scoring/src/director/tests/cascading_shadows.rs new file mode 100644 index 000000000..731c6aff6 --- /dev/null +++ b/crates/solverforge-scoring/src/director/tests/cascading_shadows.rs @@ -0,0 +1,366 @@ +// Cascading list shadows scored through ScoreDirector: tasks on several +// machines wait on tasks in other machines' lists, and the incremental score +// must equal a fresh score after every move and every undo. + +use solverforge_core::domain::{CascadePropagation, PlanningSolution}; +use solverforge_core::score::SoftScore; +use solverforge_core::{ConstraintRef, ImpactType}; + +use crate::api::constraint_set::IncrementalConstraint; +use crate::constraint::incremental::IncrementalUniConstraint; +use crate::director::score_director::ScoreDirector; +use crate::stream::collection_extract::{source, ChangeSource, SourceExtract}; + +const MACHINES: usize = 0; +const TASKS: usize = 1; + +#[derive(Clone, Debug, Default)] +struct Task { + duration: i64, + waits_on: Option, + machine: Option, + previous: Option, + next: Option, + start: Option, +} + +#[derive(Clone, Debug)] +struct Shop { + machines: Vec>, + tasks: Vec, + score: Option, +} + +impl Shop { + fn end(&self, task: usize) -> Option { + self.tasks[task] + .start + .map(|start| start + self.tasks[task].duration) + } + + fn compute_start(&self, task: usize) -> Option { + let mut start = 0; + if let Some(previous) = self.tasks[task].previous { + start = start.max(self.end(previous)?); + } + if let Some(dependency) = self.tasks[task].waits_on { + start = start.max(self.end(dependency)?); + } + Some(start) + } +} + +impl PlanningSolution for Shop { + type Score = SoftScore; + + fn score(&self) -> Option { + self.score + } + + fn set_score(&mut self, score: Option) { + self.score = score; + } + + fn update_entity_shadows(&mut self, descriptor_index: usize, entity_index: usize) { + self.update_list_structure_shadows(descriptor_index, entity_index); + if descriptor_index == MACHINES { + let changed = self.machines[entity_index].clone(); + CascadePropagation::new(self).propagate(self, changed, |_, _| {}); + } + } + + fn update_all_shadows(&mut self) { + for task in 0..self.tasks.len() { + self.clear_list_shadows(task); + } + for machine in 0..self.machines.len() { + self.update_list_structure_shadows(MACHINES, machine); + } + CascadePropagation::refresh_all(self); + } + + fn list_shadow_elements( + &self, + descriptor_index: usize, + entity_index: usize, + ) -> Option<(usize, &[usize])> { + (descriptor_index == MACHINES).then(|| (TASKS, self.machines[entity_index].as_slice())) + } + + fn clear_list_shadows(&mut self, element: usize) { + let task = &mut self.tasks[element]; + task.machine = None; + task.previous = None; + task.next = None; + } + + const HAS_CASCADING_SHADOWS: bool = true; + + fn cascading_element_count(&self) -> usize { + self.tasks.len() + } + + fn cascading_assigned(&self, element: usize) -> bool { + self.tasks[element].machine.is_some() + } + + fn cascading_next(&self, element: usize) -> Option { + self.tasks[element].next + } + + fn cascading_dependencies(&self, element: usize, dependencies: &mut Vec) { + dependencies.extend(self.tasks[element].waits_on); + } + + fn cascading_unset(&self, element: usize) -> bool { + self.tasks[element].start.is_none() + } + + fn update_cascading_shadow( + &mut self, + element: usize, + computable: bool, + before_write: W, + ) -> bool { + let start = if computable { + self.compute_start(element) + } else { + None + }; + if self.tasks[element].start == start { + return false; + } + before_write(self); + self.tasks[element].start = start; + true + } + + fn update_list_structure_shadows(&mut self, descriptor_index: usize, entity_index: usize) { + if descriptor_index != MACHINES { + return; + } + let list = &self.machines[entity_index]; + for (position, &task) in list.iter().enumerate() { + let task = &mut self.tasks[task]; + task.machine = Some(entity_index); + task.previous = position.checked_sub(1).map(|previous| list[previous]); + task.next = list.get(position + 1).copied(); + } + } +} + +type StartCost = IncrementalUniConstraint< + Shop, + Task, + SourceExtract &[Task]>, + fn(&Shop, &Task) -> bool, + fn(&Task) -> SoftScore, + SoftScore, +>; + +// Each task costs its start, with its position and machine folded in so a +// stale previous pointer would also show; an unset start costs 1000. +fn start_cost() -> StartCost { + fn tasks(shop: &Shop) -> &[Task] { + &shop.tasks + } + fn every(_: &Shop, _: &Task) -> bool { + true + } + fn cost(task: &Task) -> SoftScore { + match task.start { + Some(start) => SoftScore::of( + start * 10 + + task.machine.map_or(0, |machine| machine as i64 + 1) + + task.previous.map_or(0, |previous| previous as i64 * 100), + ), + None => SoftScore::of(1000), + } + } + IncrementalUniConstraint::new( + ConstraintRef::new("", "start cost"), + ImpactType::Penalty, + source( + tasks as fn(&Shop) -> &[Task], + ChangeSource::Descriptor(TASKS), + ), + every as fn(&Shop, &Task) -> bool, + cost as fn(&Task) -> SoftScore, + false, + ) +} + +type Director = ScoreDirector; + +fn director(machines: Vec>, durations: &[i64], waits_on: &[(usize, usize)]) -> Director { + let mut tasks: Vec = durations + .iter() + .map(|&duration| Task { + duration, + ..Task::default() + }) + .collect(); + for &(task, dependency) in waits_on { + tasks[task].waits_on = Some(dependency); + } + let mut director = ScoreDirector::new( + Shop { + machines, + tasks, + score: None, + }, + (start_cost(),), + ); + director.calculate_score(); + director +} + +fn assert_matches_fresh(director: &mut Director) { + let mut fresh = director.working_solution().clone(); + fresh.update_all_shadows(); + let starts = |shop: &Shop| shop.tasks.iter().map(|task| task.start).collect::>(); + assert_eq!( + starts(director.working_solution()), + starts(&fresh), + "machines {:?}", + director.working_solution().machines + ); + assert_eq!( + director.calculate_score(), + start_cost().evaluate(&fresh), + "machines {:?}", + director.working_solution().machines + ); +} + +/// Rewrites the lists of `owners` through the variable-change protocol. +fn change(director: &mut Director, owners: &[usize], edit: impl FnOnce(&mut Vec>)) { + for &owner in owners { + director.before_variable_changed(MACHINES, owner); + } + edit(&mut director.working_solution_mut().machines); + for &owner in owners { + director.after_variable_changed(MACHINES, owner); + } +} + +#[test] +fn a_task_pushed_later_on_the_saw_retimes_its_milling_on_the_mill() { + // Saw (0): cut 0. Mill (1): milling 1, which waits on the cut, then 2. + // Task 3 is a long unassigned task. + let mut director = director(vec![vec![0], vec![1, 2]], &[4, 3, 2, 10], &[(1, 0)]); + assert_matches_fresh(&mut director); + assert_eq!(director.working_solution().tasks[1].start, Some(4)); + + change(&mut director, &[0], |machines| machines[0].insert(0, 3)); + assert_eq!(director.working_solution().tasks[1].start, Some(14)); + assert_eq!(director.working_solution().tasks[2].start, Some(17)); + assert_matches_fresh(&mut director); + + // Undo: the same path restores every start. + change(&mut director, &[0], |machines| { + machines[0].remove(0); + }); + assert_eq!(director.working_solution().tasks[1].start, Some(4)); + assert_matches_fresh(&mut director); +} + +#[test] +fn a_move_that_closes_a_dependency_cycle_unsets_it_and_its_undo_restores_it() { + // Task 0 waits on task 2. Moving 2 after 0 on the saw closes a cycle. + let mut director = director(vec![vec![0], vec![2, 1]], &[4, 3, 5], &[(0, 2), (1, 0)]); + assert_matches_fresh(&mut director); + + change(&mut director, &[1, 0], |machines| { + machines[1].retain(|&task| task != 2); + machines[0].push(2); + }); + let starts: Vec<_> = director + .working_solution() + .tasks + .iter() + .map(|task| task.start) + .collect(); + assert_eq!(starts, vec![None, None, None]); + assert_matches_fresh(&mut director); + + change(&mut director, &[0, 1], |machines| { + machines[0].retain(|&task| task != 2); + machines[1].insert(0, 2); + }); + assert_matches_fresh(&mut director); +} + +// A deterministic pseudo-random sequence (64-bit LCG). +struct Lcg(u64); + +impl Lcg { + fn below(&mut self, bound: usize) -> usize { + self.0 = self + .0 + .wrapping_mul(6364136223846793005) + .wrapping_add(1442695040888963407); + ((self.0 >> 33) as usize) % bound + } +} + +#[test] +fn random_moves_and_undos_on_three_machines_keep_the_score_fresh() { + let durations: Vec = (0..15).map(|task| (task % 4 + 1) as i64).collect(); + let waits: Vec<(usize, usize)> = (5..15) + .map(|task| (task, (task * 3) % 5 + task / 5 - 1)) + .collect(); + let mut director = director( + vec![(0..5).collect(), (5..10).collect(), (10..13).collect()], + &durations, + &waits, + ); + assert_matches_fresh(&mut director); + let mut random = Lcg(11); + + for _ in 0..300 { + let before = director.working_solution().machines.clone(); + let from = random.below(3); + let to = random.below(3); + let owners: Vec = if from == to { + vec![from] + } else { + vec![from, to] + }; + let unassigned: Vec = (0..15) + .filter(|&task| director.working_solution().tasks[task].machine.is_none()) + .collect(); + match random.below(3) { + 0 if !before[from].is_empty() => { + let task = before[from][random.below(before[from].len())]; + let position = random.below(before[to].len() + 1); + change(&mut director, &owners, |machines| { + machines[from].retain(|&held| held != task); + let position = position.min(machines[to].len()); + machines[to].insert(position, task); + }); + } + 1 if !before[from].is_empty() => { + let position = random.below(before[from].len()); + change(&mut director, &[from], |machines| { + machines[from].remove(position); + }); + } + _ if !unassigned.is_empty() => { + let task = unassigned[random.below(unassigned.len())]; + let position = random.below(before[to].len() + 1); + change(&mut director, &[to], |machines| { + machines[to].insert(position, task) + }); + } + _ => continue, + } + assert_matches_fresh(&mut director); + + // Undo every other move by restoring the touched lists. + if random.below(2) == 0 { + change(&mut director, &[0, 1, 2], |machines| *machines = before); + assert_matches_fresh(&mut director); + } + } +} diff --git a/crates/solverforge-scoring/src/director/tests/mod.rs b/crates/solverforge-scoring/src/director/tests/mod.rs index 24cec46af..a5dc438a8 100644 --- a/crates/solverforge-scoring/src/director/tests/mod.rs +++ b/crates/solverforge-scoring/src/director/tests/mod.rs @@ -1,4 +1,5 @@ mod bench; +mod cascading_shadows; mod fixtures; mod list_shadows; mod score_director; diff --git a/crates/solverforge-solver/WIREFRAME.md b/crates/solverforge-solver/WIREFRAME.md index 671cc4a61..2bd7b427b 100644 --- a/crates/solverforge-solver/WIREFRAME.md +++ b/crates/solverforge-solver/WIREFRAME.md @@ -1058,7 +1058,11 @@ Runtime helpers: `planning_model!` so solution derives can attach descriptor hooks, runtime scalar/list hooks, resolve list element owners, attach scalar groups, validate the manifest-backed model, and delegate configured list-shadow - updates without proc-macro registries. + updates without proc-macro registries. Its cascading hooks + (`update_list_structure_shadows`, `cascading_element_count`, + `cascading_assigned`, `cascading_next`, `cascading_dependencies`, + `cascading_unset`, `update_cascading_shadow`) mirror the + `PlanningSolution` ones and default to no cascading shadow. Scalar-only, list-only, mixed, and zero-variable planning models target the same compiled runtime layer through `RuntimeModel`. Generic construction order is the descriptor-backed variable order emitted by the macros, and scalar runtime assembly does not depend on Rust module declaration order. Scalar construction is single-slot by default for non-assignment-owned slots; grouped scalar construction is explicit, named, and atomic. Assignment-owned scalar slots are constructed and searched only through their owning grouped scalar path. Specialized list algorithms are compiled nodes that call their existing kernels directly. diff --git a/crates/solverforge-solver/src/model_support.rs b/crates/solverforge-solver/src/model_support.rs index 68bbd285f..809b0a49c 100644 --- a/crates/solverforge-solver/src/model_support.rs +++ b/crates/solverforge-solver/src/model_support.rs @@ -71,4 +71,54 @@ pub trait PlanningModelSupport: PlanningSolution + Sized + 'static { fn list_shadow_source(_collection: &str) -> Option { None } + + /// Updates the list structure shadows (inverse, index, previous, next) + /// of one owner without the cascading shadow; returns whether anything + /// was updated. Defaults to `update_entity_shadows`. + fn update_list_structure_shadows( + solution: &mut Self, + descriptor_index: usize, + entity_index: usize, + ) -> bool { + ::update_entity_shadows( + solution, + descriptor_index, + entity_index, + ) + } + + /// Number of elements carrying the cascading shadow; `0` by default. + fn cascading_element_count(_solution: &Self) -> usize { + 0 + } + + /// Whether `element` is held by a list; `false` by default. + fn cascading_assigned(_solution: &Self, _element: usize) -> bool { + false + } + + /// The element after `element` in its list; `None` by default. + fn cascading_next(_solution: &Self, _element: usize) -> Option { + None + } + + /// Appends the declared dependencies of `element`; none by default. + fn cascading_dependencies(_solution: &Self, _element: usize, _dependencies: &mut Vec) {} + + /// Whether `element`'s cascading value is unset; `true` by default. + fn cascading_unset(_solution: &Self, _element: usize) -> bool { + true + } + + /// Recomputes (or, when `computable` is `false`, unsets) `element`'s + /// cascading value, calling `before_write` before writing a changed + /// value; returns whether it changed. `false` by default. + fn update_cascading_shadow( + _solution: &mut Self, + _element: usize, + _computable: bool, + _before_write: W, + ) -> bool { + false + } } diff --git a/crates/solverforge/src/__internal.rs b/crates/solverforge/src/__internal.rs index 523fc4b32..7c165c878 100644 --- a/crates/solverforge/src/__internal.rs +++ b/crates/solverforge/src/__internal.rs @@ -10,9 +10,9 @@ pub use solverforge_macros::{PlanningEntityImpl, PlanningSolutionImpl, ProblemFa // Domain types pub use solverforge_core::domain::{ - EntityCollectionExtractor, EntityDescriptor, PlanningEntity, PlanningId, PlanningSolution, - ProblemFact, ProblemFactDescriptor, ShadowVariableKind, SolutionDescriptor, ValueRangeType, - VariableDescriptor, + CascadePropagation, EntityCollectionExtractor, EntityDescriptor, PlanningEntity, PlanningId, + PlanningSolution, ProblemFact, ProblemFactDescriptor, ShadowVariableKind, SolutionDescriptor, + ValueRangeType, VariableDescriptor, }; // Scoring diff --git a/crates/solverforge/tests/cascading_list_shadows.rs b/crates/solverforge/tests/cascading_list_shadows.rs new file mode 100644 index 000000000..e3cf90352 --- /dev/null +++ b/crates/solverforge/tests/cascading_list_shadows.rs @@ -0,0 +1,137 @@ +//! A start time that depends on the previous task on the same machine and on +//! a task of another machine follows every move incrementally: the director +//! re-times the dependent tasks on other machines and rescores exactly their +//! rows. + +#[path = "cascading_list_shadows/domain/mod.rs"] +mod domain; + +use domain::{define_constraints, Machine, Shop, Task}; +use solverforge::prelude::*; +use solverforge::{ + PlanningSolution, ScoreDirector, SolverEvent, SolverManager, SolverTerminalReason, +}; + +fn task(id: usize, duration: i64, waits_on: Option) -> Task { + Task { + id, + duration, + waits_on, + machine: None, + previous: None, + next: None, + start: None, + } +} + +fn starts(shop: &Shop) -> Vec> { + shop.tasks.iter().map(|task| task.start).collect() +} + +fn assert_fresh>(director: &mut ScoreDirector) { + let mut fresh = director.working_solution().clone(); + fresh.update_all_shadows(); + assert_eq!(starts(director.working_solution()), starts(&fresh)); + let incremental = director.calculate_score(); + let mut rescored = ScoreDirector::new(fresh, define_constraints()); + assert_eq!(incremental, rescored.calculate_score()); +} + +// Saw (machine 0): cut (0). Mill (machine 1): milling (1), which waits on +// the cut, then task 2. Task 3 is long and unassigned. +fn saw_and_mill() -> Shop { + Shop { + machines: vec![ + Machine { + id: 0, + tasks: vec![0], + }, + Machine { + id: 1, + tasks: vec![1, 2], + }, + ], + tasks: vec![ + task(0, 4, None), + task(1, 3, Some(0)), + task(2, 2, None), + task(3, 10, None), + ], + score: None, + } +} + +#[test] +fn inserting_a_long_task_before_the_cut_retimes_the_milling_on_the_other_machine() { + let mut director = ScoreDirector::new(saw_and_mill(), define_constraints()); + director.calculate_score(); + assert_eq!( + starts(director.working_solution()), + vec![Some(0), Some(4), Some(7), None] + ); + + director.before_variable_changed(0, 0); + director.working_solution_mut().machines[0] + .tasks + .insert(0, 3); + director.after_variable_changed(0, 0); + + assert_eq!( + starts(director.working_solution()), + vec![Some(10), Some(14), Some(17), Some(0)] + ); + assert_fresh(&mut director); + + // Undo through the same path. + director.before_variable_changed(0, 0); + director.working_solution_mut().machines[0].tasks.remove(0); + director.after_variable_changed(0, 0); + assert_eq!( + starts(director.working_solution()), + vec![Some(0), Some(4), Some(7), None] + ); + assert_fresh(&mut director); +} + +#[test] +fn a_solve_with_full_assert_keeps_every_cascading_score_fresh() { + static MANAGER: SolverManager = SolverManager::new(); + let machines = (0..3) + .map(|id| Machine { + id, + tasks: Vec::new(), + }) + .collect(); + // Every task from 3 on waits on the task three before it, so a chain + // spans the machines whatever the solver assigns. + let tasks = (0..12) + .map(|id| task(id, (id as i64 % 4) + 1, id.checked_sub(3))) + .collect(); + let (_, mut receiver) = MANAGER + .solve(Shop { + machines, + tasks, + score: None, + }) + .expect("job should start"); + let mut completed = None; + while let Some(event) = receiver.blocking_recv() { + match event { + SolverEvent::Completed { metadata, solution } => { + assert_eq!( + metadata.terminal_reason, + Some(SolverTerminalReason::Completed) + ); + completed = Some(solution); + break; + } + SolverEvent::Failed { error, .. } => panic!("the solve failed: {error}"), + _ => {} + } + } + let solved = completed.expect("expected a completed solution"); + let mut fresh = solved.clone(); + fresh.update_all_shadows(); + assert_eq!(starts(&solved), starts(&fresh)); + assert!(solved.tasks.iter().all(|task| task.machine.is_some())); +} diff --git a/crates/solverforge/tests/cascading_list_shadows/domain/machine.rs b/crates/solverforge/tests/cascading_list_shadows/domain/machine.rs new file mode 100644 index 000000000..c2f3ea1e4 --- /dev/null +++ b/crates/solverforge/tests/cascading_list_shadows/domain/machine.rs @@ -0,0 +1,13 @@ +use solverforge::prelude::*; + +/// A machine that processes its tasks in list order. +#[planning_entity] +pub struct Machine { + /// Stable machine id. + #[planning_id] + pub id: usize, + + /// The tasks the machine processes, in order. + #[planning_list_variable(element_collection = "tasks")] + pub tasks: Vec, +} diff --git a/crates/solverforge/tests/cascading_list_shadows/domain/mod.rs b/crates/solverforge/tests/cascading_list_shadows/domain/mod.rs new file mode 100644 index 000000000..026610659 --- /dev/null +++ b/crates/solverforge/tests/cascading_list_shadows/domain/mod.rs @@ -0,0 +1,11 @@ +solverforge::planning_model! { + root = "crates/solverforge/tests/cascading_list_shadows/domain"; + + mod machine; + mod shop; + mod task; + + pub use machine::Machine; + pub use shop::{define_constraints, Shop}; + pub use task::Task; +} diff --git a/crates/solverforge/tests/cascading_list_shadows/domain/shop.rs b/crates/solverforge/tests/cascading_list_shadows/domain/shop.rs new file mode 100644 index 000000000..af1f2508d --- /dev/null +++ b/crates/solverforge/tests/cascading_list_shadows/domain/shop.rs @@ -0,0 +1,91 @@ +use solverforge::prelude::*; +use solverforge::stream::ConstraintFactory; +use solverforge::SolverConfig; + +use super::{Machine, Task}; + +/// Machines whose tasks wait on tasks of other machines. +#[planning_solution(constraints = "define_constraints", config = "shop_config")] +#[shadow_variable_updates( + list_owner = "machines", + inverse_field = "machine", + previous_field = "previous", + next_field = "next", + cascading_field = "start", + cascading_compute = "compute_start", + cascading_dependencies = "task_dependencies" +)] +pub struct Shop { + /// The machines. + #[planning_entity_collection] + pub machines: Vec, + + /// The tasks the machines process. + #[problem_fact_collection] + pub tasks: Vec, + + /// The shop's score. + #[planning_score] + pub score: Option, +} + +impl Shop { + fn end(&self, task: usize) -> Option { + let task = &self.tasks[task]; + task.start.map(|start| start + task.duration) + } + + /// A task starts when the previous task on its machine and the task it + /// waits on have both ended; unset while either is unset. + pub fn compute_start(&self, task: usize) -> Option { + let mut start = 0; + if let Some(previous) = self.tasks[task].previous { + start = start.max(self.end(previous)?); + } + if let Some(dependency) = self.tasks[task].waits_on { + start = start.max(self.end(dependency)?); + } + Some(start) + } + + /// The task `task` waits on, if any. + pub fn task_dependencies(&self, task: usize) -> Option { + self.tasks[task].waits_on + } +} + +/// Unassigned and unscheduled tasks are hard; every task's end is soft, so +/// any stale start changes the score. +pub fn define_constraints() -> impl ConstraintSet { + ( + ConstraintFactory::::new() + .for_each(Shop::tasks()) + .filter(|task: &Task| task.start.is_none()) + .penalize(HardSoftScore::ONE_HARD) + .named("unscheduled task"), + ConstraintFactory::::new() + .for_each(Shop::tasks()) + .filter(|task: &Task| task.start.is_some()) + .penalize(|task: &Task| HardSoftScore::of_soft(task.start.unwrap_or(0) + task.duration)) + .named("task end"), + ) +} + +// Full assert checks every incremental score against a fresh calculation. +const SHOP_TOML: &str = r#" +environment_mode = "full_assert" +random_seed = 5 + +[[phases]] +type = "construction_heuristic" + +[[phases]] +type = "local_search" + +[phases.termination] +step_count_limit = 60 +"#; + +fn shop_config(_solution: &Shop, _base: SolverConfig) -> SolverConfig { + SolverConfig::from_toml_str(SHOP_TOML).expect("shop fixture config must parse") +} diff --git a/crates/solverforge/tests/cascading_list_shadows/domain/task.rs b/crates/solverforge/tests/cascading_list_shadows/domain/task.rs new file mode 100644 index 000000000..929b69f66 --- /dev/null +++ b/crates/solverforge/tests/cascading_list_shadows/domain/task.rs @@ -0,0 +1,21 @@ +use solverforge::prelude::*; + +/// A task with a duration that may wait on a task of another machine. +#[problem_fact] +pub struct Task { + /// Stable task id. + #[planning_id] + pub id: usize, + /// Processing time. + pub duration: i64, + /// The task that must end before this one starts. + pub waits_on: Option, + /// The machine holding the task (list shadow). + pub machine: Option, + /// The task before this one on its machine (list shadow). + pub previous: Option, + /// The task after this one on its machine (list shadow). + pub next: Option, + /// When the task starts (cascading list shadow). + pub start: Option, +} diff --git a/crates/solverforge/tests/readme_examples.rs b/crates/solverforge/tests/readme_examples.rs index 1b43e636a..115115d7f 100644 --- a/crates/solverforge/tests/readme_examples.rs +++ b/crates/solverforge/tests/readme_examples.rs @@ -12,6 +12,8 @@ mod nurses; #[path = "readme_examples/routes/mod.rs"] mod routes; +#[path = "readme_examples/shop/mod.rs"] +mod shop; #[path = "readme_examples/staffing/mod.rs"] mod staffing; #[path = "readme_examples/weighted/mod.rs"] @@ -83,6 +85,7 @@ const SOURCES: &[(&str, &str)] = &[ include_str!("readme_examples/routes/plan.rs"), ), ("scores.rs", include_str!("readme_examples/scores.rs")), + ("shop/plan.rs", include_str!("readme_examples/shop/plan.rs")), ("streams.rs", include_str!("readme_examples/streams.rs")), ( "weighted/schedule.rs", @@ -216,3 +219,35 @@ fn readme_join_example_scores_night_shifts_with_a_matching_employee() { assert_eq!(constraint.match_count(&schedule), 1); assert_eq!(constraint.evaluate(&schedule), SoftScore::of(-1)); } + +#[test] +fn the_documented_cascading_shadow_follows_a_dependency_across_machines() { + use shop::{Machine, Shop, Task}; + use solverforge::PlanningSolution; + let task = |id, duration, waits_on| Task { + id, + duration, + waits_on, + machine: None, + previous: None, + next: None, + start: None, + }; + let mut plan = Shop { + machines: vec![ + Machine { + id: 0, + tasks: vec![0], + }, + Machine { + id: 1, + tasks: vec![2, 1], + }, + ], + tasks: vec![task(0, 4, None), task(1, 3, Some(0)), task(2, 2, None)], + score: None, + }; + plan.update_all_shadows(); + let starts: Vec<_> = plan.tasks.iter().map(|task| task.start).collect(); + assert_eq!(starts, vec![Some(0), Some(4), Some(0)]); +} diff --git a/crates/solverforge/tests/readme_examples/shop/machine.rs b/crates/solverforge/tests/readme_examples/shop/machine.rs new file mode 100644 index 000000000..c2f3ea1e4 --- /dev/null +++ b/crates/solverforge/tests/readme_examples/shop/machine.rs @@ -0,0 +1,13 @@ +use solverforge::prelude::*; + +/// A machine that processes its tasks in list order. +#[planning_entity] +pub struct Machine { + /// Stable machine id. + #[planning_id] + pub id: usize, + + /// The tasks the machine processes, in order. + #[planning_list_variable(element_collection = "tasks")] + pub tasks: Vec, +} diff --git a/crates/solverforge/tests/readme_examples/shop/mod.rs b/crates/solverforge/tests/readme_examples/shop/mod.rs new file mode 100644 index 000000000..ccea2fe80 --- /dev/null +++ b/crates/solverforge/tests/readme_examples/shop/mod.rs @@ -0,0 +1,11 @@ +solverforge::planning_model! { + root = "crates/solverforge/tests/readme_examples/shop"; + + mod machine; + mod plan; + mod task; + + pub use machine::Machine; + pub use plan::Shop; + pub use task::Task; +} diff --git a/crates/solverforge/tests/readme_examples/shop/plan.rs b/crates/solverforge/tests/readme_examples/shop/plan.rs new file mode 100644 index 000000000..44e523a8a --- /dev/null +++ b/crates/solverforge/tests/readme_examples/shop/plan.rs @@ -0,0 +1,49 @@ +use solverforge::prelude::*; + +use super::{Machine, Task}; + +// readme:begin +#[planning_solution] +#[shadow_variable_updates( + list_owner = "machines", + inverse_field = "machine", + previous_field = "previous", + next_field = "next", + cascading_field = "start", + cascading_compute = "compute_start", + cascading_dependencies = "task_dependencies" +)] +pub struct Shop { + #[planning_entity_collection] + pub machines: Vec, + + #[problem_fact_collection] + pub tasks: Vec, + + #[planning_score] + pub score: Option, +} + +impl Shop { + fn end(&self, task: usize) -> Option { + let task = &self.tasks[task]; + task.start.map(|start| start + task.duration) + } + + // After the previous task on the machine and the task it waits on. + pub fn compute_start(&self, task: usize) -> Option { + let mut start = 0; + if let Some(previous) = self.tasks[task].previous { + start = start.max(self.end(previous)?); + } + if let Some(dependency) = self.tasks[task].waits_on { + start = start.max(self.end(dependency)?); + } + Some(start) + } + + pub fn task_dependencies(&self, task: usize) -> Option { + self.tasks[task].waits_on + } +} +// readme:end diff --git a/crates/solverforge/tests/readme_examples/shop/task.rs b/crates/solverforge/tests/readme_examples/shop/task.rs new file mode 100644 index 000000000..929b69f66 --- /dev/null +++ b/crates/solverforge/tests/readme_examples/shop/task.rs @@ -0,0 +1,21 @@ +use solverforge::prelude::*; + +/// A task with a duration that may wait on a task of another machine. +#[problem_fact] +pub struct Task { + /// Stable task id. + #[planning_id] + pub id: usize, + /// Processing time. + pub duration: i64, + /// The task that must end before this one starts. + pub waits_on: Option, + /// The machine holding the task (list shadow). + pub machine: Option, + /// The task before this one on its machine (list shadow). + pub previous: Option, + /// The task after this one on its machine (list shadow). + pub next: Option, + /// When the task starts (cascading list shadow). + pub start: Option, +} diff --git a/docs/modeling.md b/docs/modeling.md index 8cbad06c9..33677eac7 100644 --- a/docs/modeling.md +++ b/docs/modeling.md @@ -106,6 +106,86 @@ element and is enabled on the planning solution with A model can mix scalar variables with any number of independent list owners. +### Cascading shadows across lists + +A cascading shadow is an element value computed from the element's previous +element in its list and from elements it waits on, which other owners' lists +may hold: a start time with precedence across machines, employees or +vehicles. Declare the field, the per-element compute and the dependencies, +and SolverForge owns the ordering, propagation and change reporting: + +```rust +#[planning_solution] +#[shadow_variable_updates( + list_owner = "machines", + inverse_field = "machine", + previous_field = "previous", + next_field = "next", + cascading_field = "start", + cascading_compute = "compute_start", + cascading_dependencies = "task_dependencies" +)] +pub struct Shop { + #[planning_entity_collection] + pub machines: Vec, + + #[problem_fact_collection] + pub tasks: Vec, + + #[planning_score] + pub score: Option, +} + +impl Shop { + fn end(&self, task: usize) -> Option { + let task = &self.tasks[task]; + task.start.map(|start| start + task.duration) + } + + // After the previous task on the machine and the task it waits on. + pub fn compute_start(&self, task: usize) -> Option { + let mut start = 0; + if let Some(previous) = self.tasks[task].previous { + start = start.max(self.end(previous)?); + } + if let Some(dependency) = self.tasks[task].waits_on { + start = start.max(self.end(dependency)?); + } + Some(start) + } + + pub fn task_dependencies(&self, task: usize) -> Option { + self.tasks[task].waits_on + } +} +``` + +- `cascading_field` names an `Option<_>` element field; its value type must + implement `PartialEq`. +- `cascading_compute` names a solution method `fn(&self, element: usize) -> + Option<_>`. It runs only for an element held by a list, after the previous + element in that list and every dependency hold their final values for the + move. +- `cascading_dependencies` (optional) names a solution method returning the + elements `element` waits on, as any `IntoIterator` (an + `Option`, a slice, a `Vec`). Dependencies are problem facts; moves + never change them, and a problem change that does is applied through a + reset. +- `inverse_field`, `previous_field` and `next_field` are required. + `cascading_listener`, `post_update_listener`, `entity_aggregate` and + `entity_compute` cannot be combined with a cascading shadow: they run per + changed owner and would not see the values a move changes in other + owners' lists. + +After each move the score director recomputes the downstream cone of the +changed elements in dependency order: each element once, after its inputs, +and only when an input changed, so propagation stops where a value is +unchanged. Every element whose value changes is rescored exactly once. An +element in no list, or on a dependency cycle a move creates (a task that +waits on a task queued after it), is unset (`None`), which constraints can +penalize. Models without a cascading shadow compile none of this into their +move path. + ### Fixed element owners A list variable can pin elements to owners with