diff --git a/crates/solverforge-core/WIREFRAME.md b/crates/solverforge-core/WIREFRAME.md index e1842765..95270b6e 100644 --- a/crates/solverforge-core/WIREFRAME.md +++ b/crates/solverforge-core/WIREFRAME.md @@ -50,6 +50,9 @@ src/ │ ├── 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 +│ ├── cascade/ +│ │ ├── cycles.rs — Dependency cycles among the nodes of a stalled propagation +│ │ └── groups.rs — Joint groups: peers joined into nodes computed together │ ├── dynamic.rs — DynamicModelBackend, scalar/list access contracts, explicit list access/metadata capabilities │ ├── dynamic/ │ │ ├── assignment.rs — Dynamic scalar-assignment metadata contract and structural capabilities @@ -157,6 +160,7 @@ Additionally, `pub mod constraint`, `pub mod constraint_weights`, `pub mod domai | `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_peers` | `fn cascading_peers(&self, element: usize, peers: &mut Vec)` | Default: none; appends the elements computed together with `element`. Peers join transitively into a joint group that propagation computes as one node. Peers 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 | @@ -341,12 +345,14 @@ Derives: `Debug, Clone` 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`. +dependencies, the joint groups of declared peers, plus per-node scratch. +Propagation works on nodes: a joint group, or an element of none; without +peers every element is its own node. `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. +- `new(&S) -> Self` — state with the dependency index and groups built. +- `rebuild_dependencies(&mut self, &S)` — rebuilds the index and the groups and resizes scratch; panics on a dependency or peer 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. +- `propagate(&mut self, &mut S, changed: I, before_write: W)` with `I: IntoIterator`, `W: FnMut(&S, usize)` — recomputes the downstream cone of the nodes of the `changed` elements in dependency order: each node at most once, after the inputs of all its members in the cone, its members in ascending element order, and only when a member is changed, an input changed value, or a member is held by a list but unset; elements on a dependency cycle are unset. `before_write` sees the solution before each write. #### `EntityCollectionExtractor` diff --git a/crates/solverforge-core/public-api.txt b/crates/solverforge-core/public-api.txt index c6417ae5..29752b59 100644 --- a/crates/solverforge-core/public-api.txt +++ b/crates/solverforge-core/public-api.txt @@ -296,7 +296,7 @@ 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; 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 { ... } } +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 17 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_peers(&self, _element: usize, _peers: &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 @@ -312,6 +312,7 @@ trait domain::PlanningSolution: pub trait PlanningSolution: Clone + Send + Sync 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_peers(&self, _element: usize, _peers: &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, ) diff --git a/crates/solverforge-core/src/domain/cascade.rs b/crates/solverforge-core/src/domain/cascade.rs index 4eb988aa..64c6fb76 100644 --- a/crates/solverforge-core/src/domain/cascade.rs +++ b/crates/solverforge-core/src/domain/cascade.rs @@ -2,14 +2,20 @@ //! //! 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 +//! may hold. Elements that declare each other peers form a joint group, +//! computed together: two technicians that start a visit together each wait +//! on the other's arrival. Propagation works on nodes, a node being a joint +//! group or an element of none. The graph has an edge to a node from the +//! previous element and from each dependency of every member. After list //! changes, [`CascadePropagation::propagate`] visits the downstream cone of -//! the changed elements and recomputes it in dependency order: an element is +//! the changed elements and recomputes it in dependency order: a node 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. +//! only when an input value changed (or a member is a changed element), so +//! propagation stops where recomputed values equal the old ones. Elements on +//! a dependency cycle have no defined value and are unset. + +mod cycles; +mod groups; use super::PlanningSolution; @@ -17,17 +23,24 @@ 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. +/// Holds the reverse index of the declared dependencies and the joint +/// groups, built by [`rebuild_dependencies`](Self::rebuild_dependencies) and +/// valid while the dependencies, the peers and the element count stay +/// unchanged, plus per-node 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. + // Joint groups, empty when no element declares peers. A group is the + // node of its lowest element, `node[e]`; its members are + // `members[member_offsets[n]..member_offsets[n + 1]]`, empty for an + // element that is not a node. + node: Vec, + member_offsets: Vec, + members: Vec, + // Per-node scratch, cleared after each propagation. in_cone: Vec, dirty: Vec, done: Vec, @@ -50,13 +63,12 @@ impl CascadePropagation { propagation } - /// Rebuilds the reverse dependency index from `solution` and sizes the - /// per-element scratch to its element count. + /// Rebuilds the reverse dependency index and the joint groups from + /// `solution` and sizes the per-node scratch to its element count. /// /// # Panics /// - /// When an element declares a dependency on an element index that does - /// not exist. + /// When an element declares a dependency or a peer that does not exist. pub fn rebuild_dependencies(&mut self, solution: &S) { let count = solution.cascading_element_count(); self.offsets.clear(); @@ -87,6 +99,7 @@ impl CascadePropagation { } } self.scratch.clear(); + self.rebuild_groups(solution, count); for flags in [ &mut self.in_cone, &mut self.dirty, @@ -115,33 +128,57 @@ impl CascadePropagation { /// 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) + /// Every member of a node holding an element of `changed` is recomputed; + /// another node of the downstream cone is recomputed when one of its + /// inputs changed value, or when a member is held by a list but unset (it + /// may have left a dependency cycle). Each node is recomputed at most + /// once, after all of its inputs in the cone, its members in ascending + /// element order. 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, before_write: W) where S: PlanningSolution, I: IntoIterator, W: FnMut(&S, usize), + { + // A model without peers runs the element-per-node instance, which + // compiles the group lookups away. + if self.node.is_empty() { + self.propagate_nodes::(solution, changed, before_write); + } else { + self.propagate_nodes::(solution, changed, before_write); + } + } + + fn propagate_nodes( + &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); + let node = self.node_of::(element); + self.dirty[node] = true; + if !self.in_cone[node] { + self.in_cone[node] = true; + self.cone.push(node); + self.stack.push(node); } } - 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]); + while let Some(node) = self.stack.pop() { + for index in 0..self.member_count::(node) { + let member = self.member::(node, index); + if let Some(next) = solution.cascading_next(member) { + self.reach(self.node_of::(next)); + } + for position in self.offsets[member]..self.offsets[member + 1] { + self.reach(self.node_of::(self.dependents[position])); + } } } @@ -149,179 +186,117 @@ impl CascadePropagation { self.cone .iter() .copied() - .filter(|&element| self.pending_inputs[element] == 0), + .filter(|&node| self.pending_inputs[node] == 0), ); let mut finished = 0; loop { - while let Some(element) = self.ready.pop() { - self.done[element] = true; + while let Some(node) = self.ready.pop() { + self.done[node] = 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); + let stale = self.dirty[node] + || (0..self.member_count::(node)).any(|index| { + let member = self.member::(node, index); + solution.cascading_assigned(member) && solution.cascading_unset(member) + }); + if stale { + for index in 0..self.member_count::(node) { + let member = self.member::(node, index); + let assigned = solution.cascading_assigned(member); + if solution.update_cascading_shadow(member, assigned, |solution| { + before_write(solution, member) + }) { + self.mark_outputs_dirty::(solution, member); + } + } } - self.release_outputs(solution, element); + self.release_outputs::(solution, node); } 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. + // The remaining nodes wait on a dependency cycle. Cycle members + // are unset; the nodes 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; + for position in 0..self.cone.len() { + let node = self.cone[position]; + if self.cycle[node] && !self.done[node] { + self.done[node] = 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.member_count::(node) { + let member = self.member::(node, index); + if solution.update_cascading_shadow(member, false, |solution| { + before_write(solution, member) + }) { + self.mark_outputs_dirty::(solution, member); + } } } } - for index in 0..self.cone.len() { - let element = self.cone[index]; - if self.cycle[element] { - self.release_outputs(solution, element); + for position in 0..self.cone.len() { + let node = self.cone[position]; + if self.cycle[node] { + self.release_outputs::(solution, node); } } } - 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; + for &node in &self.cone { + self.in_cone[node] = false; + self.dirty[node] = false; + self.done[node] = false; + self.cycle[node] = false; + self.pending_inputs[node] = 0; + self.order[node] = UNVISITED; + self.low[node] = 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 reach(&mut self, node: usize) { + self.pending_inputs[node] += 1; + if !self.in_cone[node] { + self.in_cone[node] = true; + self.cone.push(node); + self.stack.push(node); } } - fn release_outputs(&mut self, solution: &S, element: usize) { + fn mark_outputs_dirty( + &mut self, + solution: &S, + element: usize, + ) { if let Some(next) = solution.cascading_next(element) { - self.release(next); + let node = self.node_of::(next); + self.dirty[node] = true; } 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; - } - } - } + let node = self.node_of::(self.dependents[position]); + self.dirty[node] = true; } } - fn enter( + fn release_outputs( &mut self, solution: &S, - element: usize, - next_order: &mut usize, - components: &mut Vec, - frames: &mut Vec<(usize, Vec)>, + node: usize, ) { - 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); + for index in 0..self.member_count::(node) { + let member = self.member::(node, index); + if let Some(next) = solution.cascading_next(member) { + self.release(self.node_of::(next)); + } + for position in self.offsets[member]..self.offsets[member + 1] { + self.release(self.node_of::(self.dependents[position])); + } } - 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) + fn release(&mut self, node: usize) { + self.pending_inputs[node] -= 1; + if self.pending_inputs[node] == 0 && !self.done[node] && !self.cycle[node] { + self.ready.push(node); + } } } diff --git a/crates/solverforge-core/src/domain/cascade/cycles.rs b/crates/solverforge-core/src/domain/cascade/cycles.rs new file mode 100644 index 00000000..dbc55209 --- /dev/null +++ b/crates/solverforge-core/src/domain/cascade/cycles.rs @@ -0,0 +1,112 @@ +//! Dependency cycles among the nodes of a stalled propagation. + +use super::{CascadePropagation, UNVISITED}; +use crate::domain::PlanningSolution; + +impl CascadePropagation { + /// Marks the members of every dependency cycle among the unfinished + /// nodes of the cone (strongly connected components with more than one + /// node, or a node that depends on itself). Runs only when propagation + /// stalls on a cycle. + #[cold] + pub(super) fn mark_cycles(&mut self, solution: &S) { + let mut next_order = 0; + let mut components = Vec::new(); + // Each frame holds a node 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((node, outputs)) = frames.last_mut() { + let node = *node; + 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[node] = self.low[node].min(self.order[output]); + } + continue; + } + frames.pop(); + if let Some((parent, _)) = frames.last() { + self.low[*parent] = self.low[*parent].min(self.low[node]); + } + if self.low[node] == self.order[node] { + let start = components + .iter() + .rposition(|&member| member == node) + .expect("component root is on the stack"); + let self_loop = self.outputs(solution, node).contains(&node); + 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, + node: usize, + next_order: &mut usize, + components: &mut Vec, + frames: &mut Vec<(usize, Vec)>, + ) { + self.order[node] = *next_order; + self.low[node] = *next_order; + *next_order += 1; + self.on_stack[node] = true; + components.push(node); + let mut outputs = self.outputs(solution, node); + outputs.retain(|&output| self.in_cone[output] && !self.done[output]); + frames.push((node, outputs)); + } + + /// The nodes that the next elements and the dependents of `node`'s + /// members belong to. + fn outputs(&self, solution: &S, node: usize) -> Vec { + if self.node.is_empty() { + self.outputs_of::(solution, node) + } else { + self.outputs_of::(solution, node) + } + } + + fn outputs_of( + &self, + solution: &S, + node: usize, + ) -> Vec { + let mut outputs = Vec::new(); + for index in 0..self.member_count::(node) { + let member = self.member::(node, index); + if let Some(next) = solution.cascading_next(member) { + outputs.push(self.node_of::(next)); + } + outputs.extend( + self.dependents[self.offsets[member]..self.offsets[member + 1]] + .iter() + .map(|&dependent| self.node_of::(dependent)), + ); + } + outputs + } +} diff --git a/crates/solverforge-core/src/domain/cascade/groups.rs b/crates/solverforge-core/src/domain/cascade/groups.rs new file mode 100644 index 00000000..30137423 --- /dev/null +++ b/crates/solverforge-core/src/domain/cascade/groups.rs @@ -0,0 +1,95 @@ +//! Joint groups: elements computed together because each waits on the +//! others' inputs. + +use super::CascadePropagation; +use crate::domain::PlanningSolution; + +impl CascadePropagation { + /// Joins every element with its declared peers, transitively, and lays + /// the groups out as compressed rows keyed by each group's lowest + /// element. Leaves the group index empty when no element declares a + /// peer, so a model without groups maps every element to itself. + pub(super) fn rebuild_groups(&mut self, solution: &S, count: usize) { + self.node.clear(); + self.member_offsets.clear(); + self.members.clear(); + // A union-find forest whose roots are the lowest element of their + // tree, allocated on the first declared peer. + let mut parent: Vec = Vec::new(); + for element in 0..count { + self.scratch.clear(); + solution.cascading_peers(element, &mut self.scratch); + for &peer in &self.scratch { + assert!( + peer < count, + "cascading element {element} declares peer {peer}, but there are only {count} elements" + ); + if parent.is_empty() { + parent = (0..count).collect(); + } + let (a, b) = (root(&mut parent, element), root(&mut parent, peer)); + parent[a.max(b)] = a.min(b); + } + } + self.scratch.clear(); + if parent.is_empty() { + return; + } + self.node = (0..count) + .map(|element| root(&mut parent, element)) + .collect(); + self.member_offsets.resize(count + 1, 0); + for &node in &self.node { + self.member_offsets[node + 1] += 1; + } + for node in 0..count { + self.member_offsets[node + 1] += self.member_offsets[node]; + } + self.members.resize(count, 0); + let mut fill = self.member_offsets.clone(); + for element in 0..count { + let node = self.node[element]; + self.members[fill[node]] = element; + fill[node] += 1; + } + } + + /// The node holding `element`: its group's lowest element, or itself. + /// `GROUPED` is whether any element declares peers. + #[inline(always)] + pub(super) fn node_of(&self, element: usize) -> usize { + if !GROUPED { + element + } else { + self.node[element] + } + } + + /// Number of elements of `node`. + #[inline(always)] + pub(super) fn member_count(&self, node: usize) -> usize { + if !GROUPED { + 1 + } else { + self.member_offsets[node + 1] - self.member_offsets[node] + } + } + + /// The `index`th element of `node`, in ascending element order. + #[inline(always)] + pub(super) fn member(&self, node: usize, index: usize) -> usize { + if !GROUPED { + node + } else { + self.members[self.member_offsets[node] + index] + } + } +} + +fn root(parent: &mut [usize], mut element: usize) -> usize { + while parent[element] != element { + parent[element] = parent[parent[element]]; + element = parent[element]; + } + element +} diff --git a/crates/solverforge-core/src/domain/tests/cascade_group_tests.rs b/crates/solverforge-core/src/domain/tests/cascade_group_tests.rs new file mode 100644 index 00000000..1c65ee26 --- /dev/null +++ b/crates/solverforge-core/src/domain/tests/cascade_group_tests.rs @@ -0,0 +1,411 @@ +// Joint groups in cascading shadow propagation: visits that two or three +// technicians start together, each in its own technician's list. Checked +// against an independent fixed point of the per-visit compute. + +use crate::domain::{CascadePropagation, PlanningSolution}; +use crate::score::SoftScore; + +#[derive(Clone, Debug, Default)] +struct Visit { + duration: i64, + waits_on: Vec, + peers: Vec, + technician: Option, + previous: Option, + next: Option, + start: Option, +} + +#[derive(Clone, Debug)] +struct Crew { + technicians: Vec>, + visits: Vec, + computes: usize, + score: Option, +} + +impl Crew { + fn new( + technicians: Vec>, + durations: &[i64], + groups: &[&[usize]], + waits_on: &[(usize, usize)], + ) -> Self { + let mut visits: Vec = durations + .iter() + .map(|&duration| Visit { + duration, + ..Visit::default() + }) + .collect(); + for group in groups { + for &member in group.iter() { + visits[member].peers = group.iter().copied().filter(|&p| p != member).collect(); + } + } + for &(visit, dependency) in waits_on { + visits[visit].waits_on.push(dependency); + } + let mut crew = Self { + technicians, + visits, + computes: 0, + score: None, + }; + crew.refresh_structure_all(); + CascadePropagation::refresh_all(&mut crew); + crew + } + + fn end(&self, visit: usize) -> Option { + self.visits[visit] + .start + .map(|start| start + self.visits[visit].duration) + } + + // When the visit's technician can be there: after the previous visit, + // one unit of travel, and every visit it waits on. + fn arrival(&self, visit: usize) -> Option { + let mut arrival = 0; + if let Some(previous) = self.visits[visit].previous { + arrival = arrival.max(self.end(previous)? + 1); + } + for &dependency in &self.visits[visit].waits_on { + arrival = arrival.max(self.end(dependency)?); + } + Some(arrival) + } + + // A visit starts when the last assigned technician of its group arrives. + // It reads its peers' inputs, never their starts. + fn compute_start(&self, visit: usize) -> Option { + let mut start = self.arrival(visit)?; + for &peer in &self.visits[visit].peers { + if self.visits[peer].technician.is_some() { + start = start.max(self.arrival(peer)?); + } + } + Some(start) + } + + fn refresh_structure(&mut self, technician: usize) { + let list = self.technicians[technician].clone(); + for (position, &visit) in list.iter().enumerate() { + let visit = &mut self.visits[visit]; + visit.technician = Some(technician); + visit.previous = position.checked_sub(1).map(|previous| list[previous]); + visit.next = list.get(position + 1).copied(); + } + } + + fn refresh_structure_all(&mut self) { + for visit in &mut self.visits { + visit.technician = None; + visit.previous = None; + visit.next = None; + } + for technician in 0..self.technicians.len() { + self.refresh_structure(technician); + } + } + + fn starts(&self) -> Vec> { + self.visits.iter().map(|visit| visit.start).collect() + } + + // The least fixed point of the compute from all-unset values: what the + // propagation must produce, found without it. A visit on a cycle never + // gets a value. + fn fixed_point(&self) -> Vec> { + let mut crew = self.clone(); + crew.refresh_structure_all(); + for visit in &mut crew.visits { + visit.start = None; + } + loop { + let starts: Vec> = (0..crew.visits.len()) + .map(|visit| { + crew.visits[visit] + .technician + .and_then(|_| crew.compute_start(visit)) + }) + .collect(); + if starts == crew.starts() { + return starts; + } + for (visit, start) in starts.into_iter().enumerate() { + crew.visits[visit].start = start; + } + } + } +} + +impl PlanningSolution for Crew { + 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.visits.len() + } + + fn cascading_assigned(&self, element: usize) -> bool { + self.visits[element].technician.is_some() + } + + fn cascading_next(&self, element: usize) -> Option { + self.visits[element].next + } + + fn cascading_dependencies(&self, element: usize, dependencies: &mut Vec) { + dependencies.extend_from_slice(&self.visits[element].waits_on); + } + + fn cascading_peers(&self, element: usize, peers: &mut Vec) { + peers.extend_from_slice(&self.visits[element].peers); + } + + fn cascading_unset(&self, element: usize) -> bool { + self.visits[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.visits[element].start == start { + return false; + } + before_write(self); + self.visits[element].start = start; + true + } +} + +/// Applies a list change to `technicians`, refreshes their structure, +/// clears visits no list holds any more, and propagates from every visit the +/// changed technicians held before or after. Returns the elements written. +fn change( + crew: &mut Crew, + propagation: &mut CascadePropagation, + technicians: &[usize], + edit: impl FnOnce(&mut Vec>), +) -> Vec { + let mut changed: Vec = technicians + .iter() + .flat_map(|&technician| crew.technicians[technician].clone()) + .collect(); + edit(&mut crew.technicians); + for &technician in technicians { + changed.extend(crew.technicians[technician].iter().copied()); + } + changed.sort_unstable(); + changed.dedup(); + for &visit in &changed { + if !crew.technicians.iter().any(|list| list.contains(&visit)) { + let visit = &mut crew.visits[visit]; + visit.technician = None; + visit.previous = None; + visit.next = None; + } + } + for &technician in technicians { + crew.refresh_structure(technician); + } + let mut written = Vec::new(); + propagation.propagate(crew, changed, |_, element| written.push(element)); + written +} + +fn assert_fixed_point(crew: &Crew) { + assert_eq!( + crew.starts(), + crew.fixed_point(), + "technicians {:?}", + crew.technicians + ); +} + +// Ann: visit 0 (4 long), then the joint visit 2. Bob: the joint visit 3, +// then visit 1. Visits 2 and 3 start together. +fn ann_and_bob() -> Crew { + Crew::new(vec![vec![0, 2], vec![3, 1]], &[4, 3, 6, 6], &[&[2, 3]], &[]) +} + +#[test] +fn a_joint_visit_starts_when_the_last_technician_arrives() { + let crew = ann_and_bob(); + // Ann arrives at 5, Bob at 0: both start at 5 and Bob's next visit + // follows at 12. + assert_eq!(crew.starts(), vec![Some(0), Some(12), Some(5), Some(5)]); + assert_fixed_point(&crew); +} + +#[test] +fn a_move_on_one_route_retimes_the_partner_and_the_partners_route() { + let mut crew = ann_and_bob(); + let mut propagation = CascadePropagation::new(&crew); + // Ann goes to the joint visit first: both start at 0 and Bob's next + // visit at 7. + let mut written = change(&mut crew, &mut propagation, &[0], |technicians| { + technicians[0].swap(0, 1) + }); + assert_eq!(crew.starts(), vec![Some(7), Some(7), Some(0), Some(0)]); + assert_fixed_point(&crew); + written.sort_unstable(); + assert_eq!(written, vec![0, 1, 2, 3]); +} + +#[test] +fn an_unchanged_group_stops_propagation() { + // Ann's first visit is already late enough to hold the group back. + let mut crew = Crew::new( + vec![vec![0, 4, 2], vec![3, 1]], + &[4, 3, 6, 6, 1], + &[&[2, 3]], + &[], + ); + let mut propagation = CascadePropagation::new(&crew); + assert_eq!(crew.visits[2].start, Some(7)); + // Swapping Ann's first two visits leaves her arrival at the joint + // visit at 7: the group is recomputed, unchanged, and Bob's next visit + // is not. + crew.computes = 0; + let mut written = change(&mut crew, &mut propagation, &[0], |technicians| { + technicians[0].swap(0, 1) + }); + assert_fixed_point(&crew); + written.sort_unstable(); + assert_eq!(written, vec![0, 4]); + // Ann's three visits and the partner visit 3. + assert_eq!(crew.computes, 4); +} + +#[test] +fn a_group_on_one_route_is_a_cycle_and_is_unset() { + // Both members on Ann's route: the second waits on the first's end and + // the first on the second's arrival. + let crew = Crew::new(vec![vec![0, 2, 3, 1]], &[4, 3, 6, 6], &[&[2, 3]], &[]); + assert_eq!(crew.starts(), vec![Some(0), None, None, None]); + assert_fixed_point(&crew); + + let mut crew = crew; + crew.technicians.push(Vec::new()); + let mut propagation = CascadePropagation::new(&crew); + change(&mut crew, &mut propagation, &[0, 1], |technicians| { + technicians[0].retain(|&visit| visit != 3); + technicians[1].push(3); + }); + assert_eq!(crew.starts(), vec![Some(0), Some(12), Some(5), Some(5)]); + assert_fixed_point(&crew); +} + +#[test] +fn a_member_left_unassigned_frees_its_partner() { + let mut crew = ann_and_bob(); + let mut propagation = CascadePropagation::new(&crew); + change(&mut crew, &mut propagation, &[0], |technicians| { + technicians[0].retain(|&visit| visit != 2) + }); + assert_eq!(crew.starts(), vec![Some(0), Some(7), None, Some(0)]); + assert_fixed_point(&crew); +} + +#[test] +fn propagation_without_peers_keeps_every_element_its_own_node() { + let crew = Crew::new(vec![vec![0, 1], vec![2]], &[4, 3, 2], &[], &[(2, 1)]); + assert_eq!(crew.starts(), vec![Some(0), Some(5), Some(8)]); + assert_fixed_point(&crew); +} + +// 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_with_groups_and_dependencies_match_the_fixed_point() { + let durations: Vec = (0..24).map(|visit| (visit % 4 + 1) as i64).collect(); + // Pairs and a triple across routes, plus visits that wait on others. + let groups: &[&[usize]] = &[&[0, 8], &[3, 11, 19], &[5, 14], &[9, 20]]; + let waits = [(16, 2), (12, 0), (21, 3), (6, 17), (10, 5)]; + let technicians = vec![ + (0..6).collect::>(), + (6..12).collect(), + (12..18).collect(), + (18..22).collect(), + ]; + for seed in [7, 21, 1234] { + let mut crew = Crew::new(technicians.clone(), &durations, groups, &waits); + assert_fixed_point(&crew); + let mut propagation = CascadePropagation::new(&crew); + let mut random = Lcg(seed); + for step in 0..500 { + let from = random.below(4); + let to = random.below(4); + let touched: Vec = if from == to { + vec![from] + } else { + vec![from, to] + }; + let computes_before = crew.computes; + match random.below(3) { + 0 if !crew.technicians[from].is_empty() => { + let visit = crew.technicians[from][random.below(crew.technicians[from].len())]; + let position = random.below(crew.technicians[to].len() + 1); + change(&mut crew, &mut propagation, &touched, |technicians| { + technicians[from].retain(|&held| held != visit); + let position = position.min(technicians[to].len()); + technicians[to].insert(position, visit); + }); + } + 1 if !crew.technicians[from].is_empty() => { + let position = random.below(crew.technicians[from].len()); + change(&mut crew, &mut propagation, &[from], |technicians| { + technicians[from].remove(position); + }); + } + _ => { + let unassigned: Vec = (0..crew.visits.len()) + .filter(|&visit| crew.visits[visit].technician.is_none()) + .collect(); + if let Some(&visit) = unassigned.get(random.below(unassigned.len().max(1))) { + let position = random.below(crew.technicians[to].len() + 1); + change(&mut crew, &mut propagation, &[to], |technicians| { + technicians[to].insert(position, visit) + }); + } + } + } + assert!( + crew.computes - computes_before <= crew.visits.len(), + "seed {seed} step {step}: an element was computed more than once" + ); + assert_fixed_point(&crew); + } + } +} diff --git a/crates/solverforge-core/src/domain/tests/mod.rs b/crates/solverforge-core/src/domain/tests/mod.rs index 1aa0c76a..5ecc54e6 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_group_tests; mod cascade_tests; mod dynamic_list_tests; mod entity_ref_tests; diff --git a/crates/solverforge-core/src/domain/traits.rs b/crates/solverforge-core/src/domain/traits.rs index 2fd38207..58878a16 100644 --- a/crates/solverforge-core/src/domain/traits.rs +++ b/crates/solverforge-core/src/domain/traits.rs @@ -149,6 +149,14 @@ pub trait PlanningSolution: Clone + Send + Sync + 'static { /// problem facts: moves never change them. fn cascading_dependencies(&self, _element: usize, _dependencies: &mut Vec) {} + /// Appends the peers of `element` to `peers`: elements computed together + /// with it, joined transitively into a joint group. A member's value is + /// computed after the previous elements and dependencies of every member + /// hold their final values, so it may read them; it must not read + /// another member's cascading value. Peers are problem facts: moves + /// never change them. + fn cascading_peers(&self, _element: usize, _peers: &mut Vec) {} + /// Whether `element`'s cascading value is unset. fn cascading_unset(&self, _element: usize) -> bool { true diff --git a/crates/solverforge-macros/WIREFRAME.md b/crates/solverforge-macros/WIREFRAME.md index 7b15268d..cea01297 100644 --- a/crates/solverforge-macros/WIREFRAME.md +++ b/crates/solverforge-macros/WIREFRAME.md @@ -242,6 +242,7 @@ arguments are compile errors. - `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 +- `cascading_peers = "method"` — solution method returning the elements computed together with an element (a joint group, joined transitively), as `IntoIterator`; optional **`#[planning_list_variable]` parameters:** - `element_collection = "field"` — solution field with all list elements diff --git a/crates/solverforge-macros/src/attr_validation.rs b/crates/solverforge-macros/src/attr_validation.rs index 097df9ce..905ec527 100644 --- a/crates/solverforge-macros/src/attr_validation.rs +++ b/crates/solverforge-macros/src/attr_validation.rs @@ -112,6 +112,7 @@ const SHADOW_UPDATES_ARGS: &[AttributeArgSpec] = &[ AttributeArgSpec::string("cascading_field"), AttributeArgSpec::string("cascading_compute"), AttributeArgSpec::string("cascading_dependencies"), + AttributeArgSpec::string("cascading_peers"), AttributeArgSpec::string("post_update_listener"), AttributeArgSpec::repeated_string("entity_aggregate"), AttributeArgSpec::repeated_string("entity_compute"), diff --git a/crates/solverforge-macros/src/planning_model/cascade.rs b/crates/solverforge-macros/src/planning_model/cascade.rs index 6dc3d9eb..145bc97e 100644 --- a/crates/solverforge-macros/src/planning_model/cascade.rs +++ b/crates/solverforge-macros/src/planning_model/cascade.rs @@ -14,9 +14,12 @@ struct CascadeContext<'a> { 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() { + if config.cascading_compute.is_some() + || config.cascading_dependencies.is_some() + || config.cascading_peers.is_some() + { return error( - "#[shadow_variable_updates(...)] `cascading_compute` and `cascading_dependencies` require `cascading_field = \"element_field\"`", + "#[shadow_variable_updates(...)] `cascading_compute`, `cascading_dependencies` and `cascading_peers` require `cascading_field = \"element_field\"`", ); } return Ok(()); @@ -65,6 +68,14 @@ fn generate_cascade_hooks(config: &ShadowConfig, context: &CascadeContext<'_>) - quote! { dependencies.extend(solution.#method(element)); } }) .unwrap_or_default(); + let peers = config + .cascading_peers + .as_deref() + .map(|method| { + let method = Ident::new(method, span); + quote! { peers.extend(solution.#method(element)); } + }) + .unwrap_or_default(); quote! { fn cascading_element_count(solution: &Self) -> usize { #solution_path::#element_accessor(solution).len() @@ -87,6 +98,11 @@ fn generate_cascade_hooks(config: &ShadowConfig, context: &CascadeContext<'_>) - #dependencies } + #[allow(unused_variables)] + fn cascading_peers(solution: &Self, element: usize, peers: &mut ::std::vec::Vec) { + #peers + } + fn cascading_unset(solution: &Self, element: usize) -> bool { #solution_path::#element_accessor(solution)[element].#field.is_none() } diff --git a/crates/solverforge-macros/src/planning_model/manifest.rs b/crates/solverforge-macros/src/planning_model/manifest.rs index 38e32529..55364652 100644 --- a/crates/solverforge-macros/src/planning_model/manifest.rs +++ b/crates/solverforge-macros/src/planning_model/manifest.rs @@ -132,6 +132,7 @@ struct ShadowConfig { cascading_field: Option, cascading_compute: Option, cascading_dependencies: Option, + cascading_peers: 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 41a853fe..3822cbe1 100644 --- a/crates/solverforge-macros/src/planning_model/metadata.rs +++ b/crates/solverforge-macros/src/planning_model/metadata.rs @@ -79,6 +79,7 @@ fn parse_shadow_config(attrs: &[Attribute]) -> Result { 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.cascading_peers = parse_attribute_string(attr, "cascading_peers"); 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/config.rs b/crates/solverforge-macros/src/planning_solution/config.rs index 0bd3fc26..94763c7a 100644 --- a/crates/solverforge-macros/src/planning_solution/config.rs +++ b/crates/solverforge-macros/src/planning_solution/config.rs @@ -14,6 +14,7 @@ pub(super) struct ShadowConfig { pub(super) cascading_field: Option, pub(super) cascading_compute: Option, pub(super) cascading_dependencies: Option, + pub(super) cascading_peers: Option, pub(super) post_update_listener: Option, pub(super) entity_aggregates: Vec, pub(super) entity_computes: Vec, @@ -135,6 +136,7 @@ pub(super) fn parse_shadow_config(attrs: &[syn::Attribute]) -> ShadowConfig { 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.cascading_peers = parse_attribute_string(attr, "cascading_peers"); 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 52c118f0..fb022678 100644 --- a/crates/solverforge-macros/src/planning_solution/shadow.rs +++ b/crates/solverforge-macros/src/planning_solution/shadow.rs @@ -64,6 +64,13 @@ pub(super) fn generate_shadow_support( ) } + #[inline] + fn cascading_peers(&self, element: usize, peers: &mut ::std::vec::Vec) { + ::cascading_peers( + self, element, peers, + ) + } + #[inline] fn cascading_unset(&self, element: usize) -> bool { ::cascading_unset(self, element) diff --git a/crates/solverforge-solver/WIREFRAME.md b/crates/solverforge-solver/WIREFRAME.md index 70f0745a..69b4299d 100644 --- a/crates/solverforge-solver/WIREFRAME.md +++ b/crates/solverforge-solver/WIREFRAME.md @@ -1061,7 +1061,7 @@ Runtime helpers: 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 + `cascading_peers`, `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 809b0a49..f8d69994 100644 --- a/crates/solverforge-solver/src/model_support.rs +++ b/crates/solverforge-solver/src/model_support.rs @@ -105,6 +105,10 @@ pub trait PlanningModelSupport: PlanningSolution + Sized + 'static { /// Appends the declared dependencies of `element`; none by default. fn cascading_dependencies(_solution: &Self, _element: usize, _dependencies: &mut Vec) {} + /// Appends the peers of `element`, the elements computed together with + /// it; none by default. + fn cascading_peers(_solution: &Self, _element: usize, _peers: &mut Vec) {} + /// Whether `element`'s cascading value is unset; `true` by default. fn cascading_unset(_solution: &Self, _element: usize) -> bool { true diff --git a/crates/solverforge/tests/joint_cascading_shadows.rs b/crates/solverforge/tests/joint_cascading_shadows.rs new file mode 100644 index 00000000..df06298e --- /dev/null +++ b/crates/solverforge/tests/joint_cascading_shadows.rs @@ -0,0 +1,148 @@ +//! Visits that several technicians start together follow every move +//! incrementally: a move on one route re-times the partner visits on the +//! other routes and everything after them, and rescores exactly those rows. + +#[path = "joint_cascading_shadows/domain/mod.rs"] +mod domain; + +use domain::{define_constraints, Crew, Technician, Visit}; +use solverforge::prelude::*; +use solverforge::{ + PlanningSolution, ScoreDirector, SolverEvent, SolverManager, SolverTerminalReason, +}; + +fn visit(id: usize, duration: i64, partners: &[usize]) -> Visit { + Visit { + id, + duration, + partners: partners.to_vec(), + technician: None, + previous: None, + next: None, + start: None, + } +} + +fn starts(crew: &Crew) -> Vec> { + crew.visits.iter().map(|visit| visit.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()); +} + +// Ann: visit 0, then the joint visit 2. Bob: the joint visit 3, then +// visit 1. Visit 4 is long and unassigned. +fn ann_and_bob() -> Crew { + Crew { + technicians: vec![ + Technician { + id: 0, + visits: vec![0, 2], + }, + Technician { + id: 1, + visits: vec![3, 1], + }, + ], + visits: vec![ + visit(0, 4, &[]), + visit(1, 3, &[]), + visit(2, 6, &[3]), + visit(3, 6, &[2]), + visit(4, 10, &[]), + ], + score: None, + } +} + +#[test] +fn a_long_visit_on_one_route_holds_back_the_partner_on_the_other() { + let mut director = ScoreDirector::new(ann_and_bob(), define_constraints()); + director.calculate_score(); + // Ann arrives at the joint visit at 5, Bob at 0: both start at 5. + assert_eq!( + starts(director.working_solution()), + vec![Some(0), Some(12), Some(5), Some(5), None] + ); + + director.before_variable_changed(0, 0); + director.working_solution_mut().technicians[0] + .visits + .insert(0, 4); + director.after_variable_changed(0, 0); + + // Ann now reaches the joint visit at 16; Bob waits for her. + assert_eq!( + starts(director.working_solution()), + vec![Some(11), Some(23), Some(16), Some(16), Some(0)] + ); + assert_fresh(&mut director); + + // Undo through the same path. + director.before_variable_changed(0, 0); + director.working_solution_mut().technicians[0] + .visits + .remove(0); + director.after_variable_changed(0, 0); + assert_eq!( + starts(director.working_solution()), + vec![Some(0), Some(12), Some(5), Some(5), None] + ); + assert_fresh(&mut director); +} + +#[test] +fn a_solve_with_full_assert_keeps_every_joint_score_fresh() { + static MANAGER: SolverManager = SolverManager::new(); + let technicians = (0..3) + .map(|id| Technician { + id, + visits: Vec::new(), + }) + .collect(); + // Two pairs and a triple among twelve visits. + let jobs: [&[usize]; 3] = [&[0, 5], &[2, 7, 10], &[4, 9]]; + let visits = (0..12) + .map(|id| { + let partners: Vec = jobs + .iter() + .find(|job| job.contains(&id)) + .map(|job| job.iter().copied().filter(|&p| p != id).collect()) + .unwrap_or_default(); + visit(id, (id as i64 % 4) + 1, &partners) + }) + .collect(); + let (_, mut receiver) = MANAGER + .solve(Crew { + technicians, + visits, + 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.visits.iter().all(|visit| visit.technician.is_some())); +} diff --git a/crates/solverforge/tests/joint_cascading_shadows/domain/crew.rs b/crates/solverforge/tests/joint_cascading_shadows/domain/crew.rs new file mode 100644 index 00000000..12caf568 --- /dev/null +++ b/crates/solverforge/tests/joint_cascading_shadows/domain/crew.rs @@ -0,0 +1,98 @@ +use solverforge::prelude::*; +use solverforge::stream::ConstraintFactory; +use solverforge::SolverConfig; + +use super::{Technician, Visit}; + +/// Technicians whose jobs may need several of them at once. +#[planning_solution(constraints = "define_constraints", config = "crew_config")] +#[shadow_variable_updates( + list_owner = "technicians", + inverse_field = "technician", + previous_field = "previous", + next_field = "next", + cascading_field = "start", + cascading_compute = "compute_start", + cascading_peers = "visit_partners" +)] +pub struct Crew { + /// The technicians. + #[planning_entity_collection] + pub technicians: Vec, + + /// The visits the technicians make. + #[problem_fact_collection] + pub visits: Vec, + + /// The crew's score. + #[planning_score] + pub score: Option, +} + +impl Crew { + // When the technician can be at `visit`: one unit of travel after the + // previous visit ends. + fn arrival(&self, visit: usize) -> Option { + match self.visits[visit].previous { + Some(previous) => { + let previous = &self.visits[previous]; + Some(previous.start? + previous.duration + 1) + } + None => Some(0), + } + } + + /// A visit starts when the last assigned technician of its job arrives. + pub fn compute_start(&self, visit: usize) -> Option { + let mut start = self.arrival(visit)?; + for &partner in &self.visits[visit].partners { + if self.visits[partner].technician.is_some() { + start = start.max(self.arrival(partner)?); + } + } + Some(start) + } + + /// The visits started together with `visit`. + pub fn visit_partners(&self, visit: usize) -> Vec { + self.visits[visit].partners.clone() + } +} + +/// Unassigned and unscheduled visits are hard; every visit's end is soft, +/// so any stale start changes the score. +pub fn define_constraints() -> impl ConstraintSet { + ( + ConstraintFactory::::new() + .for_each(Crew::visits()) + .filter(|visit: &Visit| visit.start.is_none()) + .penalize(HardSoftScore::ONE_HARD) + .named("unscheduled visit"), + ConstraintFactory::::new() + .for_each(Crew::visits()) + .filter(|visit: &Visit| visit.start.is_some()) + .penalize(|visit: &Visit| { + HardSoftScore::of_soft(visit.start.unwrap_or(0) + visit.duration) + }) + .named("visit end"), + ) +} + +// Full assert checks every incremental score against a fresh calculation. +const CREW_TOML: &str = r#" +environment_mode = "full_assert" +random_seed = 9 + +[[phases]] +type = "construction_heuristic" + +[[phases]] +type = "local_search" + +[phases.termination] +step_count_limit = 80 +"#; + +fn crew_config(_solution: &Crew, _base: SolverConfig) -> SolverConfig { + SolverConfig::from_toml_str(CREW_TOML).expect("crew fixture config must parse") +} diff --git a/crates/solverforge/tests/joint_cascading_shadows/domain/mod.rs b/crates/solverforge/tests/joint_cascading_shadows/domain/mod.rs new file mode 100644 index 00000000..3a4b9582 --- /dev/null +++ b/crates/solverforge/tests/joint_cascading_shadows/domain/mod.rs @@ -0,0 +1,11 @@ +solverforge::planning_model! { + root = "crates/solverforge/tests/joint_cascading_shadows/domain"; + + mod crew; + mod technician; + mod visit; + + pub use crew::{define_constraints, Crew}; + pub use technician::Technician; + pub use visit::Visit; +} diff --git a/crates/solverforge/tests/joint_cascading_shadows/domain/technician.rs b/crates/solverforge/tests/joint_cascading_shadows/domain/technician.rs new file mode 100644 index 00000000..1606b453 --- /dev/null +++ b/crates/solverforge/tests/joint_cascading_shadows/domain/technician.rs @@ -0,0 +1,13 @@ +use solverforge::prelude::*; + +/// A technician who drives to the visits in list order. +#[planning_entity] +pub struct Technician { + /// Stable technician id. + #[planning_id] + pub id: usize, + + /// The visits the technician makes, in order. + #[planning_list_variable(element_collection = "visits")] + pub visits: Vec, +} diff --git a/crates/solverforge/tests/joint_cascading_shadows/domain/visit.rs b/crates/solverforge/tests/joint_cascading_shadows/domain/visit.rs new file mode 100644 index 00000000..e95e0988 --- /dev/null +++ b/crates/solverforge/tests/joint_cascading_shadows/domain/visit.rs @@ -0,0 +1,21 @@ +use solverforge::prelude::*; + +/// A visit, possibly one of several that technicians start together. +#[problem_fact] +pub struct Visit { + /// Stable visit id. + #[planning_id] + pub id: usize, + /// Service time. + pub duration: i64, + /// The other visits of the same job, started together with this one. + pub partners: Vec, + /// The technician making the visit (list shadow). + pub technician: Option, + /// The visit before this one on the technician's route (list shadow). + pub previous: Option, + /// The visit after this one on the technician's route (list shadow). + pub next: Option, + /// When service starts (cascading list shadow). + pub start: Option, +} diff --git a/crates/solverforge/tests/readme_examples.rs b/crates/solverforge/tests/readme_examples.rs index 115115d7..3ef3f403 100644 --- a/crates/solverforge/tests/readme_examples.rs +++ b/crates/solverforge/tests/readme_examples.rs @@ -8,6 +8,8 @@ // Documented code is shown as written: shadowed `let`s, ignored results. #![allow(dead_code, unused_variables, unused_must_use, unused_mut)] +#[path = "readme_examples/crew/mod.rs"] +mod crew; #[path = "readme_examples/nurses/mod.rs"] mod nurses; #[path = "readme_examples/routes/mod.rs"] @@ -71,6 +73,7 @@ const SOURCES: &[(&str, &str)] = &[ "configured.rs", include_str!("readme_examples/configured.rs"), ), + ("crew/plan.rs", include_str!("readme_examples/crew/plan.rs")), ("manager.rs", include_str!("readme_examples/manager.rs")), ( "night_shift.rs", diff --git a/crates/solverforge/tests/readme_examples/crew/mod.rs b/crates/solverforge/tests/readme_examples/crew/mod.rs new file mode 100644 index 00000000..1f00b800 --- /dev/null +++ b/crates/solverforge/tests/readme_examples/crew/mod.rs @@ -0,0 +1,11 @@ +solverforge::planning_model! { + root = "crates/solverforge/tests/readme_examples/crew"; + + mod plan; + mod technician; + mod visit; + + pub use plan::Crew; + pub use technician::Technician; + pub use visit::Visit; +} diff --git a/crates/solverforge/tests/readme_examples/crew/plan.rs b/crates/solverforge/tests/readme_examples/crew/plan.rs new file mode 100644 index 00000000..f5d5990e --- /dev/null +++ b/crates/solverforge/tests/readme_examples/crew/plan.rs @@ -0,0 +1,54 @@ +use solverforge::prelude::*; + +use super::{Technician, Visit}; + +// readme:begin +#[planning_solution] +#[shadow_variable_updates( + list_owner = "technicians", + inverse_field = "technician", + previous_field = "previous", + next_field = "next", + cascading_field = "start", + cascading_compute = "compute_start", + cascading_peers = "visit_partners" +)] +pub struct Crew { + #[planning_entity_collection] + pub technicians: Vec, + + #[problem_fact_collection] + pub visits: Vec, + + #[planning_score] + pub score: Option, +} + +impl Crew { + // When the technician can be at the visit. + fn arrival(&self, visit: usize) -> Option { + match self.visits[visit].previous { + Some(previous) => { + let left = self.visits[previous].start? + self.visits[previous].duration; + Some(left + self.visits[visit].travel_from[previous]) + } + None => Some(0), + } + } + + // When the last assigned technician of the job arrives. + pub fn compute_start(&self, visit: usize) -> Option { + let mut start = self.arrival(visit)?; + for &partner in &self.visits[visit].partners { + if self.visits[partner].technician.is_some() { + start = start.max(self.arrival(partner)?); + } + } + Some(start) + } + + pub fn visit_partners(&self, visit: usize) -> Vec { + self.visits[visit].partners.clone() + } +} +// readme:end diff --git a/crates/solverforge/tests/readme_examples/crew/technician.rs b/crates/solverforge/tests/readme_examples/crew/technician.rs new file mode 100644 index 00000000..1606b453 --- /dev/null +++ b/crates/solverforge/tests/readme_examples/crew/technician.rs @@ -0,0 +1,13 @@ +use solverforge::prelude::*; + +/// A technician who drives to the visits in list order. +#[planning_entity] +pub struct Technician { + /// Stable technician id. + #[planning_id] + pub id: usize, + + /// The visits the technician makes, in order. + #[planning_list_variable(element_collection = "visits")] + pub visits: Vec, +} diff --git a/crates/solverforge/tests/readme_examples/crew/visit.rs b/crates/solverforge/tests/readme_examples/crew/visit.rs new file mode 100644 index 00000000..60f01056 --- /dev/null +++ b/crates/solverforge/tests/readme_examples/crew/visit.rs @@ -0,0 +1,23 @@ +use solverforge::prelude::*; + +/// A visit, possibly one of several that technicians start together. +#[problem_fact] +pub struct Visit { + /// Stable visit id. + #[planning_id] + pub id: usize, + /// Service time. + pub duration: i64, + /// Travel time from every visit, indexed by visit. + pub travel_from: Vec, + /// The other visits of the same job, started together with this one. + pub partners: Vec, + /// The technician making the visit (list shadow). + pub technician: Option, + /// The visit before this one on the technician's route (list shadow). + pub previous: Option, + /// The visit after this one on the technician's route (list shadow). + pub next: Option, + /// When service starts (cascading list shadow). + pub start: Option, +} diff --git a/docs/modeling.md b/docs/modeling.md index 33677eac..2f2b0c51 100644 --- a/docs/modeling.md +++ b/docs/modeling.md @@ -171,6 +171,9 @@ impl Shop { `Option`, a slice, a `Vec`). Dependencies are problem facts; moves never change them, and a problem change that does is applied through a reset. +- `cascading_peers` (optional) names a solution method returning the + elements computed together with `element`, as any + `IntoIterator`. See [Joint groups](#joint-groups). - `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 @@ -186,6 +189,77 @@ 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. +#### Joint groups + +Some elements in different lists must be timed together: a job that needs +two technicians starts when the later of them arrives, so each technician's +visit waits on the other's arrival. Declaring that as two dependencies would +be a cycle. Declare the visits peers instead: + +```rust +#[planning_solution] +#[shadow_variable_updates( + list_owner = "technicians", + inverse_field = "technician", + previous_field = "previous", + next_field = "next", + cascading_field = "start", + cascading_compute = "compute_start", + cascading_peers = "visit_partners" +)] +pub struct Crew { + #[planning_entity_collection] + pub technicians: Vec, + + #[problem_fact_collection] + pub visits: Vec, + + #[planning_score] + pub score: Option, +} + +impl Crew { + // When the technician can be at the visit. + fn arrival(&self, visit: usize) -> Option { + match self.visits[visit].previous { + Some(previous) => { + let left = self.visits[previous].start? + self.visits[previous].duration; + Some(left + self.visits[visit].travel_from[previous]) + } + None => Some(0), + } + } + + // When the last assigned technician of the job arrives. + pub fn compute_start(&self, visit: usize) -> Option { + let mut start = self.arrival(visit)?; + for &partner in &self.visits[visit].partners { + if self.visits[partner].technician.is_some() { + start = start.max(self.arrival(partner)?); + } + } + Some(start) + } + + pub fn visit_partners(&self, visit: usize) -> Vec { + self.visits[visit].partners.clone() + } +} +``` + +Peers are joined transitively into a joint group, and propagation treats +the group as one node: it waits until the previous element and every +dependency of every member hold their final values, then computes the +members once each, in ascending element order. A member's compute may read +those inputs of its peers; it must not read a peer's cascading value, which +is being computed in the same step. Peers are problem facts, like +dependencies. + +A group whose members wait on each other through their lists (two +members on one route, or a member after an element that waits on its peer) +is a cycle, and its members are unset. A model without peers maps every +element to its own node and pays nothing for the feature. + ### Fixed element owners A list variable can pin elements to owners with