diff --git a/crates/solverforge-console/src/format_tests.rs b/crates/solverforge-console/src/format_tests.rs index e3f2f22c..c89eef16 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-core/WIREFRAME.md b/crates/solverforge-core/WIREFRAME.md index 36b7f5a4..d31b601b 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 4d4ec918..c6417ae5 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 00000000..4eb988aa --- /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 cf49cf86..de16821f 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 00000000..982df31f --- /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 8d9c9931..1aa0c76a 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 3326ab0c..2fd38207 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 7b63294b..9da998f8 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 cf728539..097df9ce 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 eaa61611..34402a16 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 00000000..6dc3d9eb --- /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 7b451810..38e32529 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 8cb402df..41a853fe 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 da2f61bc..43e008e6 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 e57cc368..0bd3fc26 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 cd1099c5..52c118f0 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 00000000..9f8fb39c --- /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 00000000..83dccfd0 --- /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 00000000..c2f3ea1e --- /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 00000000..e312e841 --- /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 00000000..384ecc25 --- /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 00000000..929b69f6 --- /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 d3598a1d..f58de90a 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 | @@ -903,7 +913,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 ca8272fd..e2500a6d 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 34641b25..66fe03ca 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/director/score_director/incremental.rs b/crates/solverforge-scoring/src/director/score_director/incremental.rs index 12650f2a..c1d43af9 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 850566ab..75ea7e76 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 00000000..731c6aff --- /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 24cec46a..a5dc438a 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-scoring/src/stream/complemented_stream.rs b/crates/solverforge-scoring/src/stream/complemented_stream.rs index e52aab0d..aad69d4c 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 ffb714a3..cca98a8b 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, diff --git a/crates/solverforge-solver/WIREFRAME.md b/crates/solverforge-solver/WIREFRAME.md index 671cc4a6..2bd7b427 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 68bbd285..809b0a49 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-solver/src/phase/construction/telemetry.rs b/crates/solverforge-solver/src/phase/construction/telemetry.rs index 5d3435a0..19816bfd 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(); diff --git a/crates/solverforge/src/__internal.rs b/crates/solverforge/src/__internal.rs index 523fc4b3..7c165c87 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 00000000..e3cf9035 --- /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 00000000..c2f3ea1e --- /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 00000000..02661065 --- /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 00000000..af1f2508 --- /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 00000000..929b69f6 --- /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 1b43e636..115115d7 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 00000000..c2f3ea1e --- /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 00000000..ccea2fe8 --- /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 00000000..44e523a8 --- /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 00000000..929b69f6 --- /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 8cbad06c..33677eac 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