From aa944f3c12c39720fd2f5a86250e395b1d7bb03e Mon Sep 17 00:00:00 2001 From: Vittorio Distefano Date: Mon, 16 Nov 2026 20:46:58 +0100 Subject: [PATCH 1/3] feat(shadows): compute joint groups of cascading elements together A cascading_peers hook joins elements, transitively, into joint groups that propagation computes as one node: after the previous element and every dependency of every member are final, each member once. Two technicians that start a visit together each wait on the other's arrival, which a pair of dependencies would make a cycle. Models without peers run an instance with the group lookups compiled away. Closes #272 --- crates/solverforge-core/WIREFRAME.md | 14 +- crates/solverforge-core/public-api.txt | 3 +- crates/solverforge-core/src/domain/cascade.rs | 317 +++++++------- .../src/domain/cascade/cycles.rs | 112 +++++ .../src/domain/cascade/groups.rs | 95 ++++ .../src/domain/tests/cascade_group_tests.rs | 411 ++++++++++++++++++ .../solverforge-core/src/domain/tests/mod.rs | 1 + crates/solverforge-core/src/domain/traits.rs | 8 + crates/solverforge-macros/WIREFRAME.md | 1 + .../solverforge-macros/src/attr_validation.rs | 1 + .../src/planning_model/cascade.rs | 20 +- .../src/planning_model/manifest.rs | 1 + .../src/planning_model/metadata.rs | 1 + .../src/planning_solution/config.rs | 2 + .../src/planning_solution/shadow.rs | 7 + crates/solverforge-solver/WIREFRAME.md | 2 +- .../solverforge-solver/src/model_support.rs | 4 + .../tests/joint_cascading_shadows.rs | 148 +++++++ .../joint_cascading_shadows/domain/crew.rs | 98 +++++ .../joint_cascading_shadows/domain/mod.rs | 11 + .../domain/technician.rs | 13 + .../joint_cascading_shadows/domain/visit.rs | 21 + crates/solverforge/tests/readme_examples.rs | 3 + .../tests/readme_examples/crew/mod.rs | 11 + .../tests/readme_examples/crew/plan.rs | 54 +++ .../tests/readme_examples/crew/technician.rs | 13 + .../tests/readme_examples/crew/visit.rs | 23 + docs/modeling.md | 74 ++++ 28 files changed, 1290 insertions(+), 179 deletions(-) create mode 100644 crates/solverforge-core/src/domain/cascade/cycles.rs create mode 100644 crates/solverforge-core/src/domain/cascade/groups.rs create mode 100644 crates/solverforge-core/src/domain/tests/cascade_group_tests.rs create mode 100644 crates/solverforge/tests/joint_cascading_shadows.rs create mode 100644 crates/solverforge/tests/joint_cascading_shadows/domain/crew.rs create mode 100644 crates/solverforge/tests/joint_cascading_shadows/domain/mod.rs create mode 100644 crates/solverforge/tests/joint_cascading_shadows/domain/technician.rs create mode 100644 crates/solverforge/tests/joint_cascading_shadows/domain/visit.rs create mode 100644 crates/solverforge/tests/readme_examples/crew/mod.rs create mode 100644 crates/solverforge/tests/readme_examples/crew/plan.rs create mode 100644 crates/solverforge/tests/readme_examples/crew/technician.rs create mode 100644 crates/solverforge/tests/readme_examples/crew/visit.rs 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 From 1d8dbbeb0001bcf46a0d3afee3a0f050588e59a6 Mon Sep 17 00:00:00 2001 From: Vittorio Distefano Date: Mon, 16 Nov 2026 22:46:18 +0100 Subject: [PATCH 2/3] test(readme): exercise the documented joint cascade so its model is used The crew example's re-exports were unused, which failed the readme_examples build under -D warnings. A test now builds the documented crew and checks that partner visits start together when the later technician arrives. --- crates/solverforge/tests/readme_examples.rs | 39 +++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/crates/solverforge/tests/readme_examples.rs b/crates/solverforge/tests/readme_examples.rs index 3ef3f403..41423486 100644 --- a/crates/solverforge/tests/readme_examples.rs +++ b/crates/solverforge/tests/readme_examples.rs @@ -254,3 +254,42 @@ fn the_documented_cascading_shadow_follows_a_dependency_across_machines() { let starts: Vec<_> = plan.tasks.iter().map(|task| task.start).collect(); assert_eq!(starts, vec![Some(0), Some(4), Some(0)]); } + +#[test] +fn the_documented_joint_cascade_starts_partner_visits_together() { + use crew::{Crew, Technician, Visit}; + use solverforge::PlanningSolution; + let visit = |id, duration, travel_from: Vec, partners: Vec| Visit { + id, + duration, + travel_from, + partners, + technician: None, + previous: None, + next: None, + start: None, + }; + let mut crew = Crew { + technicians: vec![ + Technician { + id: 0, + visits: vec![0, 2], + }, + Technician { + id: 1, + visits: vec![1, 3], + }, + ], + visits: vec![ + visit(0, 2, vec![0, 0, 0, 0], vec![]), + visit(1, 7, vec![0, 0, 0, 0], vec![]), + visit(2, 1, vec![3, 0, 0, 0], vec![3]), + visit(3, 1, vec![0, 1, 0, 0], vec![2]), + ], + score: None, + }; + crew.update_all_shadows(); + let starts: Vec<_> = crew.visits.iter().map(|visit| visit.start).collect(); + // Visit 2 is reachable at 5 and visit 3 at 8: both start at 8. + assert_eq!(starts, vec![Some(0), Some(0), Some(8), Some(8)]); +} From c2676b1606efd5d670109b76b575c06e8ae8835b Mon Sep 17 00:00:00 2001 From: Vittorio Distefano Date: Tue, 17 Nov 2026 00:02:04 +0100 Subject: [PATCH 3/3] feat(list): move and construct list element groups as units `#[planning_list_variable(element_group_fn = "path")]` declares element groups: the hook appends an element's group members in order. Groups of two or more members share one owner and keep their order, with other elements allowed between members. - `list_group_change_move_selector` relocates a whole group to joint positions of one owner; `list_group_swap_move_selector` exchanges equally sized groups on two owners. - `list_ruin_move_selector` ruins whole groups and recreates each one jointly. - `list_cheapest_insertion` and `list_regret_insertion` place each group as one unit; other construction heuristics reject a grouped list. - Single-element list moves keep grouped elements on their owner. - `max_member_distance` and `max_group_owners` (`Option`) bound joint placement. Grouped lists get defaults for construction, group moves and ruin. - Group selectors and ruin bounds require the element-groups capability. `element_group_fn` with precedence hooks is a macro error. Ungrouped models keep the same hot path and every touched struct keeps its size: the precedence-successor and group hooks share one slot field with a kind byte in existing padding, and the bounds are single bytes. Closes #270 BREAKING CHANGE: `ListVariableSlot::precedence_successors_fn` is now a method (`element_group_fn()` shares its private field). `ListRuinMoveSelectorConfig` and `ConstructionHeuristicConfig` gain `max_member_distance` and `max_group_owners`, and `MoveSelectorConfig` gains `ListGroupChangeMoveSelector` and `ListGroupSwapMoveSelector`. Update struct literals and exhaustive matches. --- crates/solverforge-config/WIREFRAME.md | 37 ++ crates/solverforge-config/src/lib.rs | 15 +- .../solverforge-config/src/move_selector.rs | 15 +- .../src/move_selector/list.rs | 53 +++ crates/solverforge-config/src/phase.rs | 17 +- crates/solverforge-macros/WIREFRAME.md | 5 +- .../solverforge-macros/src/attr_validation.rs | 1 + .../src/planning_model/manifest.rs | 1 + .../src/planning_model/metadata.rs | 13 + .../src/planning_model/support.rs | 25 ++ .../ui/fail/element_groups_with_precedence.rs | 4 + .../element_groups_with_precedence.stderr | 13 + .../domain/mod.rs | 11 + .../domain/plan.rs | 15 + .../domain/route.rs | 19 + .../domain/stop.rs | 7 + ...ning_list_variable_unknown_argument.stderr | 2 +- crates/solverforge-solver/WIREFRAME.md | 21 +- crates/solverforge-solver/public-api.txt | 5 +- .../solverforge-solver/src/builder/context.rs | 4 +- .../src/builder/context/list.rs | 61 ++- .../builder/context/list_access/dynamic.rs | 7 +- .../context/list_access/static_access.rs | 2 +- .../src/builder/context/list_access/types.rs | 1 + .../src/builder/context/runtime_list.rs | 3 +- .../builder/context/runtime_list/groups.rs | 54 +++ .../builder/context/runtime_list_binding.rs | 20 +- .../src/builder/context/runtime_list_debug.rs | 4 + .../context/runtime_list_metadata_policy.rs | 24 +- .../builder/context/runtime_list_policy.rs | 21 + .../src/heuristic/move/list_kernel/group.rs | 369 ++++++++++++++++ .../heuristic/move/list_kernel/group/swap.rs | 164 +++++++ .../heuristic/move/list_kernel/group_ruin.rs | 415 ++++++++++++++++++ .../src/heuristic/move/list_kernel/mod.rs | 12 + .../src/heuristic/move/list_kernel/ruin.rs | 6 +- .../heuristic/selector/list_kernel/group.rs | 377 ++++++++++++++++ .../src/heuristic/selector/list_kernel/mod.rs | 4 + crates/solverforge-solver/src/lib.rs | 1 + crates/solverforge-solver/src/list_groups.rs | 17 + .../src/list_groups/index.rs | 171 ++++++++ .../src/list_groups/joint.rs | 246 +++++++++++ .../src/list_groups/tests.rs | 146 ++++++ crates/solverforge-solver/src/manager/mod.rs | 5 +- .../phase_factory/list_construction.rs | 5 +- .../list_construction/cheapest.rs | 2 + .../list_construction/cheapest/grouped.rs | 125 ++++++ .../cheapest/tests/parity.rs | 1 + .../phase_factory/list_construction/groups.rs | 272 ++++++++++++ .../phase_factory/list_construction/regret.rs | 2 +- .../regret/kernel/grouped.rs | 212 +++++++++ .../list_construction/regret/kernel/mod.rs | 2 + .../list_construction/regret/tests/parity.rs | 3 + .../src/manager/phase_factory/mod.rs | 4 +- .../src/runtime/compiler/construction.rs | 48 ++ .../runtime/compiler/default_local_search.rs | 4 + .../default_local_search/policy/exclusions.rs | 1 + .../default_local_search/policy/list.rs | 60 ++- .../compiler/default_local_search/trace.rs | 12 +- .../src/runtime/compiler/defaults/stages.rs | 17 +- .../src/runtime/compiler/executor/execute.rs | 28 +- .../executor/list_construction/phase.rs | 21 +- .../executor/list_construction/regret.rs | 19 +- .../compiler/executor/list_leaf/cursor.rs | 1 + .../executor/list_leaf/cursor/groups.rs | 93 ++++ .../executor/list_leaf/cursor/probe.rs | 91 +++- .../executor/list_leaf/cursor/slot.rs | 26 +- .../executor/list_leaf/cursor/slot/open.rs | 41 +- .../compiler/executor/list_leaf/emission.rs | 13 +- .../executor/list_leaf/group_emission.rs | 146 ++++++ .../compiler/executor/list_leaf/mod.rs | 1 + .../compiler/executor/list_leaf/move.rs | 63 ++- .../executor/list_leaf/move_access.rs | 2 +- .../compiler/executor/list_leaf/recipe.rs | 11 +- .../executor/list_leaf/recipe_identity.rs | 26 +- .../compiler/executor/list_leaf/spec.rs | 38 +- .../compiler/executor/list_leaf/tests.rs | 1 + .../executor/list_leaf/tests/groups.rs | 216 +++++++++ .../executor/list_leaf/tests/parity.rs | 5 + .../executor/list_leaf/tests/support.rs | 14 + .../src/runtime/compiler/graph.rs | 2 + .../src/runtime/compiler/selector_tree.rs | 22 + .../src/runtime/compiler/selector_values.rs | 22 + .../src/runtime/compiler/slots.rs | 13 +- .../src/runtime/compiler/types.rs | 2 + .../solverforge/tests/list_element_groups.rs | 113 +++++ .../list_element_groups/domain/deliveries.rs | 129 ++++++ .../tests/list_element_groups/domain/mod.rs | 11 + .../tests/list_element_groups/domain/stop.rs | 21 + .../list_element_groups/domain/vehicle.rs | 22 + crates/solverforge/tests/readme_examples.rs | 6 + docs/configuration.md | 43 +- docs/modeling.md | 61 +++ 92 files changed, 4418 insertions(+), 88 deletions(-) create mode 100644 crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence.rs create mode 100644 crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence.stderr create mode 100644 crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/mod.rs create mode 100644 crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/plan.rs create mode 100644 crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/route.rs create mode 100644 crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/stop.rs create mode 100644 crates/solverforge-solver/src/builder/context/runtime_list/groups.rs create mode 100644 crates/solverforge-solver/src/heuristic/move/list_kernel/group.rs create mode 100644 crates/solverforge-solver/src/heuristic/move/list_kernel/group/swap.rs create mode 100644 crates/solverforge-solver/src/heuristic/move/list_kernel/group_ruin.rs create mode 100644 crates/solverforge-solver/src/heuristic/selector/list_kernel/group.rs create mode 100644 crates/solverforge-solver/src/list_groups.rs create mode 100644 crates/solverforge-solver/src/list_groups/index.rs create mode 100644 crates/solverforge-solver/src/list_groups/joint.rs create mode 100644 crates/solverforge-solver/src/list_groups/tests.rs create mode 100644 crates/solverforge-solver/src/manager/phase_factory/list_construction/cheapest/grouped.rs create mode 100644 crates/solverforge-solver/src/manager/phase_factory/list_construction/groups.rs create mode 100644 crates/solverforge-solver/src/manager/phase_factory/list_construction/regret/kernel/grouped.rs create mode 100644 crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/groups.rs create mode 100644 crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/group_emission.rs create mode 100644 crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests/groups.rs create mode 100644 crates/solverforge/tests/list_element_groups.rs create mode 100644 crates/solverforge/tests/list_element_groups/domain/deliveries.rs create mode 100644 crates/solverforge/tests/list_element_groups/domain/mod.rs create mode 100644 crates/solverforge/tests/list_element_groups/domain/stop.rs create mode 100644 crates/solverforge/tests/list_element_groups/domain/vehicle.rs diff --git a/crates/solverforge-config/WIREFRAME.md b/crates/solverforge-config/WIREFRAME.md index dc2401fe..aab6bbc8 100644 --- a/crates/solverforge-config/WIREFRAME.md +++ b/crates/solverforge-config/WIREFRAME.md @@ -144,6 +144,8 @@ Derives: `Debug, Clone, Default, Deserialize, Serialize`. | `group_name` | `Option` | `None` | | `group_candidate_limit` | `Option` | `None`; valid: `>= 1` when set; requires `group_name`; list heuristics reject it | | `savings_neighbors` | `Option` | `None` (every pair scored); `0` does not parse; `ListClarkeWright` only, which then scores a pair only when one element is among the other's `savings_neighbors` nearest; other heuristics reject it | +| `max_member_distance` | `Option` | `None` (every placement); `0` does not parse; `ListCheapestInsertion` and `ListRegretInsertion` on a list with element groups only, capping the positions from one member of a jointly placed group to the next (`1` keeps members adjacent); other heuristics and lists without groups reject it | +| `max_group_owners` | `Option` | `None` (every allowed owner); `0` does not parse; same heuristics and lists as `max_member_distance`, trying every placement of a group only on that many owners, best contiguous fit first | | `termination` | `Option` | `None` | `target` is flattened in serde, so configuration files still use top-level @@ -560,9 +562,42 @@ Derives: `Debug, Clone, Deserialize, Serialize`. Manual `Default`. | `moves_per_step` | `Option` | `None`; valid: `>= 1` when set | | `max_source_list_len` | `Option` | `None`; valid: `>= 1` when set | | `skip_empty_destinations` | `bool` | `false` | +| `max_member_distance` | `Option` | `None` (every placement); `0` does not parse; with element groups, most positions from one member of a jointly recreated group to the next | +| `max_group_owners` | `Option` | `None` (every allowed owner); `0` does not parse; with element groups, owners tried per recreated group, best contiguous fit first | | `entity_class` | `Option` | `None` | | `variable_name` | `Option` | `None` | +Either group bound requires a targeted list variable with `element_group_fn`. + +### `ListGroupChangeMoveConfig` + +Derives: `Debug, Clone, Default, Deserialize, Serialize`. + +| Field | Type | Default | +|-------|------|---------| +| `selection_order` | `Option` | `None` | +| `max_member_distance` | `Option` | `None` (every placement); `0` does not parse | +| `entity_class` | `Option` | `None` | +| `variable_name` | `Option` | `None` | + +`list_group_change_move_selector` moves a whole element group, keeping its +members' order, to positions of one owner. It requires a list variable with +`element_group_fn`. + +### `ListGroupSwapMoveConfig` + +Derives: `Debug, Clone, Default, Deserialize, Serialize`. + +| Field | Type | Default | +|-------|------|---------| +| `selection_order` | `Option` | `None` | +| `entity_class` | `Option` | `None` | +| `variable_name` | `Option` | `None` | + +`list_group_swap_move_selector` exchanges two element groups of the same size +on different owners, member slot for member slot. It requires a list variable +with `element_group_fn`. + ### `RecreateHeuristicType` Enum: `FirstFit` (default), `CheapestInsertion`. @@ -888,6 +923,8 @@ Derives: `Debug, Clone, Deserialize, Serialize`. Tagged `#[serde(tag = "type", r | `ListReverseMoveSelector` | `ListReverseMoveConfig` | | `KOptMoveSelector` | `KOptMoveSelectorConfig` | | `ListRuinMoveSelector` | `ListRuinMoveSelectorConfig` | +| `ListGroupChangeMoveSelector` | `ListGroupChangeMoveConfig` | +| `ListGroupSwapMoveSelector` | `ListGroupSwapMoveConfig` | | `ConflictRepairMoveSelector` | `ConflictRepairMoveSelectorConfig` | | `CompoundConflictRepairMoveSelector` | `CompoundConflictRepairMoveSelectorConfig` | | `LimitedNeighborhood` | `LimitedNeighborhoodConfig` | diff --git a/crates/solverforge-config/src/lib.rs b/crates/solverforge-config/src/lib.rs index 8b5add39..834966c4 100644 --- a/crates/solverforge-config/src/lib.rs +++ b/crates/solverforge-config/src/lib.rs @@ -61,13 +61,14 @@ pub use forager::{AcceptedCountForagerConfig, ForagerConfig, ScoreTieBreak}; pub use move_selector::{ CartesianProductConfig, ChangeMoveConfig, CompoundConflictRepairMoveSelectorConfig, ConflictRepairMoveSelectorConfig, GroupedScalarMoveSelectorConfig, KOptMoveSelectorConfig, - LimitedNeighborhoodConfig, ListChangeMoveConfig, ListPermuteMoveConfig, - ListPrecedenceMoveConfig, ListReverseMoveConfig, ListRuinMoveSelectorConfig, - ListSwapMoveConfig, MoveSelectorConfig, NearbyChangeMoveConfig, NearbyListChangeMoveConfig, - NearbyListSwapMoveConfig, NearbySwapMoveConfig, PillarChangeMoveConfig, PillarSwapMoveConfig, - RecreateHeuristicType, RuinRecreateMoveSelectorConfig, SelectionOrder, SublistChangeMoveConfig, - SublistSwapMoveConfig, SwapMoveConfig, UnionMoveSelectorConfig, UnionSelectionOrder, - UnionWeighting, VariableTargetConfig, + LimitedNeighborhoodConfig, ListChangeMoveConfig, ListGroupChangeMoveConfig, + ListGroupSwapMoveConfig, ListPermuteMoveConfig, ListPrecedenceMoveConfig, + ListReverseMoveConfig, ListRuinMoveSelectorConfig, ListSwapMoveConfig, MoveSelectorConfig, + NearbyChangeMoveConfig, NearbyListChangeMoveConfig, NearbyListSwapMoveConfig, + NearbySwapMoveConfig, PillarChangeMoveConfig, PillarSwapMoveConfig, RecreateHeuristicType, + RuinRecreateMoveSelectorConfig, SelectionOrder, SublistChangeMoveConfig, SublistSwapMoveConfig, + SwapMoveConfig, UnionMoveSelectorConfig, UnionSelectionOrder, UnionWeighting, + VariableTargetConfig, }; pub use phase::{ ConstructionHeuristicConfig, ConstructionHeuristicType, ConstructionObligation, diff --git a/crates/solverforge-config/src/move_selector.rs b/crates/solverforge-config/src/move_selector.rs index 9409efa5..bd0333e5 100644 --- a/crates/solverforge-config/src/move_selector.rs +++ b/crates/solverforge-config/src/move_selector.rs @@ -10,7 +10,8 @@ pub use composite::{ UnionSelectionOrder, UnionWeighting, }; pub use list::{ - KOptMoveSelectorConfig, ListChangeMoveConfig, ListPermuteMoveConfig, ListPrecedenceMoveConfig, + KOptMoveSelectorConfig, ListChangeMoveConfig, ListGroupChangeMoveConfig, + ListGroupSwapMoveConfig, ListPermuteMoveConfig, ListPrecedenceMoveConfig, ListReverseMoveConfig, ListRuinMoveSelectorConfig, ListSwapMoveConfig, NearbyListChangeMoveConfig, NearbyListSwapMoveConfig, SublistChangeMoveConfig, SublistSwapMoveConfig, @@ -129,6 +130,14 @@ pub enum MoveSelectorConfig { /// List ruin move selector (LNS) — removes elements for reinsertion. ListRuinMoveSelector(ListRuinMoveSelectorConfig), + /// List group change move selector — moves a whole element group to + /// joint positions of one owner. + ListGroupChangeMoveSelector(ListGroupChangeMoveConfig), + + /// List group swap move selector — exchanges two equally sized element + /// groups on different owners. + ListGroupSwapMoveSelector(ListGroupSwapMoveConfig), + /// Neighborhood that limits the number of yielded candidates from a child selector while /// preserving selector order. LimitedNeighborhood(LimitedNeighborhoodConfig), @@ -172,6 +181,8 @@ impl MoveSelectorConfig { Self::ListReverseMoveSelector(config) => config.selection_order, Self::KOptMoveSelector(config) => config.selection_order, Self::ListRuinMoveSelector(config) => config.selection_order, + Self::ListGroupChangeMoveSelector(config) => config.selection_order, + Self::ListGroupSwapMoveSelector(config) => config.selection_order, Self::ConflictRepairMoveSelector(config) => config.selection_order, Self::CompoundConflictRepairMoveSelector(config) => config.selection_order, Self::LimitedNeighborhood(_) @@ -203,6 +214,8 @@ impl MoveSelectorConfig { Self::ListReverseMoveSelector(config) => config.selection_metric.as_deref(), Self::KOptMoveSelector(config) => config.selection_metric.as_deref(), Self::ListRuinMoveSelector(config) => config.selection_metric.as_deref(), + Self::ListGroupChangeMoveSelector(config) => config.selection_metric.as_deref(), + Self::ListGroupSwapMoveSelector(config) => config.selection_metric.as_deref(), Self::ConflictRepairMoveSelector(config) => config.selection_metric.as_deref(), Self::CompoundConflictRepairMoveSelector(config) => config.selection_metric.as_deref(), Self::LimitedNeighborhood(_) diff --git a/crates/solverforge-config/src/move_selector/list.rs b/crates/solverforge-config/src/move_selector/list.rs index c3e0b218..c39871b5 100644 --- a/crates/solverforge-config/src/move_selector/list.rs +++ b/crates/solverforge-config/src/move_selector/list.rs @@ -1,3 +1,5 @@ +use std::num::NonZeroU8; + use super::*; /// Configuration for `ListChangeMoveSelector`. @@ -316,6 +318,14 @@ pub struct ListRuinMoveSelectorConfig { /// Whether recreate should skip currently empty destination lists. #[serde(default)] pub skip_empty_destinations: bool, + /// With element groups: most positions from one member of a jointly + /// recreated group to the next; `1` keeps members adjacent. Omitted: + /// every placement. + pub max_member_distance: Option, + /// With element groups: tries every placement of a recreated group on at + /// most this many owners, the ones where it fits best contiguously. + /// Omitted: every owner the group allows. + pub max_group_owners: Option, /// Restricts the selector to one planning variable through the top-level /// `entity_class` and `variable_name` keys; both omitted means every matching /// variable. @@ -333,7 +343,50 @@ impl Default for ListRuinMoveSelectorConfig { moves_per_step: None, max_source_list_len: None, skip_empty_destinations: false, + max_member_distance: None, + max_group_owners: None, target: VariableTargetConfig::default(), } } } + +/// Configuration for `ListGroupChangeMoveSelector`: moves a whole element +/// group, keeping its members' order, to positions of one owner. +#[derive(Debug, Clone, Default, Deserialize, Serialize)] +#[serde(rename_all = "snake_case", deny_unknown_fields)] +pub struct ListGroupChangeMoveConfig { + /// Order in which this selector's candidates are tried. Omitted, the runtime + /// supplies the surrounding default (`random` in local search). + #[serde(default)] + pub selection_order: Option, + /// Name of a registered candidate metric. Required with `sorted` and + /// `probabilistic` order; rejected with any other order. + pub selection_metric: Option, + /// Most positions from one member of a moved group to the next; `1` + /// keeps members adjacent. Omitted: every placement. + pub max_member_distance: Option, + /// Restricts the selector to one planning variable through the top-level + /// `entity_class` and `variable_name` keys; both omitted means every matching + /// variable. + #[serde(flatten)] + pub target: VariableTargetConfig, +} + +/// Configuration for `ListGroupSwapMoveSelector`: exchanges two element +/// groups of the same size on different owners, member slot for member slot. +#[derive(Debug, Clone, Default, Deserialize, Serialize)] +#[serde(rename_all = "snake_case", deny_unknown_fields)] +pub struct ListGroupSwapMoveConfig { + /// Order in which this selector's candidates are tried. Omitted, the runtime + /// supplies the surrounding default (`random` in local search). + #[serde(default)] + pub selection_order: Option, + /// Name of a registered candidate metric. Required with `sorted` and + /// `probabilistic` order; rejected with any other order. + pub selection_metric: Option, + /// Restricts the selector to one planning variable through the top-level + /// `entity_class` and `variable_name` keys; both omitted means every matching + /// variable. + #[serde(flatten)] + pub target: VariableTargetConfig, +} diff --git a/crates/solverforge-config/src/phase.rs b/crates/solverforge-config/src/phase.rs index 8ddd75f8..f32fb886 100644 --- a/crates/solverforge-config/src/phase.rs +++ b/crates/solverforge-config/src/phase.rs @@ -1,4 +1,4 @@ -use std::num::NonZeroU32; +use std::num::{NonZeroU32, NonZeroU8}; use serde::{Deserialize, Serialize}; @@ -70,6 +70,19 @@ pub struct ConstructionHeuristicConfig { /// every pair is scored. Zero does not parse; other heuristics reject it. pub savings_neighbors: Option, + /// With element groups: most positions from one member of a group placed + /// jointly by `list_cheapest_insertion` or `list_regret_insertion` to the + /// next; `1` keeps members adjacent. Omitted: every placement. Other + /// heuristics, and lists without groups, reject it. + pub max_member_distance: Option, + + /// With element groups: tries every placement of a group on at most this + /// many owners, the ones where it fits best contiguously, in + /// `list_cheapest_insertion` or `list_regret_insertion`. Omitted: every + /// owner the group allows. Other heuristics, and lists without groups, + /// reject it. + pub max_group_owners: Option, + /// Phase termination configuration. pub termination: Option, } @@ -85,6 +98,8 @@ impl Default for ConstructionHeuristicConfig { group_name: None, group_candidate_limit: None, savings_neighbors: None, + max_member_distance: None, + max_group_owners: None, termination: None, } } diff --git a/crates/solverforge-macros/WIREFRAME.md b/crates/solverforge-macros/WIREFRAME.md index cea01297..00da93de 100644 --- a/crates/solverforge-macros/WIREFRAME.md +++ b/crates/solverforge-macros/WIREFRAME.md @@ -182,7 +182,9 @@ Internal module responsibilities: `precedence_duration_fn = "path"` and `precedence_successors_fn = "path"` declare plain `fn(&Solution, element) -> usize` and `fn(&Solution, element, &mut Vec)` hooks for stock list-precedence - scoring/selectors. + scoring/selectors. Optional `element_group_fn = "path"` declares a + `fn(&Solution, element, &mut Vec)` hook appending an element's group + members in order; it cannot be combined with the precedence hooks. - `#[planning_pin]` — boolean field preserving an entity's input genuine variables during solving. Pinned required scalars must already be assigned; optional unassigned scalars may stay unassigned. A pinned list owner retains its input list. - `#[inverse_relation_shadow_variable(source_variable_name = "field")]` — inverse relation shadow - `#[index_shadow_variable(source_variable_name = "field")]` — list index shadow @@ -258,6 +260,7 @@ arguments are compile errors. - `construction_element_order_key = "path"` — optional list-construction ordering hook, `fn(&Solution, element) -> i64`; it flows through existing generated list metadata and runtime list slots - `precedence_duration_fn = "path"` — optional precedence duration hook, `fn(&Solution, element) -> usize`; paired with `precedence_successors_fn` - `precedence_successors_fn = "path"` — optional fixed-precedence successor hook, `fn(&Solution, element, &mut Vec)`; paired with `precedence_duration_fn` +- `element_group_fn = "path"` — optional element-group hook, `fn(&Solution, element, &mut Vec)`; appends the members of the element's group in order, including the element, or nothing; groups of two or more members move and are constructed as units; rejected together with the precedence hooks When `domain = "cvrp"` is present, the profiled defaults above must be used as a coherent stock bundle. Overriding `distance_meter`, `intra_distance_meter`, diff --git a/crates/solverforge-macros/src/attr_validation.rs b/crates/solverforge-macros/src/attr_validation.rs index 905ec527..86294ee1 100644 --- a/crates/solverforge-macros/src/attr_validation.rs +++ b/crates/solverforge-macros/src/attr_validation.rs @@ -96,6 +96,7 @@ const PLANNING_LIST_VARIABLE_ARGS: &[AttributeArgSpec] = &[ AttributeArgSpec::string("construction_element_order_key"), AttributeArgSpec::string("precedence_duration_fn"), AttributeArgSpec::string("precedence_successors_fn"), + AttributeArgSpec::string("element_group_fn"), AttributeArgSpec::string("solution_trait"), ]; diff --git a/crates/solverforge-macros/src/planning_model/manifest.rs b/crates/solverforge-macros/src/planning_model/manifest.rs index 55364652..09889520 100644 --- a/crates/solverforge-macros/src/planning_model/manifest.rs +++ b/crates/solverforge-macros/src/planning_model/manifest.rs @@ -97,6 +97,7 @@ struct EntityMetadata { list_construction_element_order_key: Option, list_precedence_duration_fn: Option, list_precedence_successors_fn: Option, + list_element_group_fn: Option, } struct SolutionCollection { diff --git a/crates/solverforge-macros/src/planning_model/metadata.rs b/crates/solverforge-macros/src/planning_model/metadata.rs index 3822cbe1..130e3b90 100644 --- a/crates/solverforge-macros/src/planning_model/metadata.rs +++ b/crates/solverforge-macros/src/planning_model/metadata.rs @@ -100,6 +100,7 @@ fn parse_entity(module: &ModuleSource, item_struct: &ItemStruct) -> Result Result Result Result { } }); } + + if let (Some(variable_name), Some(path)) = + (&entity.list_variable_name, &entity.list_element_group_fn) + { + let runtime_helper = format_ident!( + "__solverforge_runtime_list_element_group_{}", + entity_field + ); + list_runtime_helpers.push(quote! { + fn #runtime_helper( + solution: &#solution_path, + element: usize, + members: &mut ::std::vec::Vec, + ) { + #path(solution, element, members) + } + }); + list_runtime_attachments.push(quote! { + if slot.descriptor_index == #descriptor_index + && slot.variable_name == #variable_name + { + slot = slot.with_element_group_fn(::core::option::Option::Some(#runtime_helper)); + } + }); + } } let ScalarHookTokens { diff --git a/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence.rs b/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence.rs new file mode 100644 index 00000000..4da707d1 --- /dev/null +++ b/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence.rs @@ -0,0 +1,4 @@ +#[path = "element_groups_with_precedence/domain/mod.rs"] +mod domain; + +fn main() {} diff --git a/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence.stderr b/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence.stderr new file mode 100644 index 00000000..45590f1c --- /dev/null +++ b/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence.stderr @@ -0,0 +1,13 @@ +error: #[planning_list_variable] cannot combine `element_group_fn` with precedence hooks: group moves and joint construction do not follow precedence routes + --> tests/ui/fail/element_groups_with_precedence/domain/mod.rs + | + | / solverforge::planning_model! { + | | root = "crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain"; + | | + | | mod plan; +... | + | | pub use stop::Stop; + | | } + | |_^ + | + = 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/element_groups_with_precedence/domain/mod.rs b/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/mod.rs new file mode 100644 index 00000000..1fbaeda8 --- /dev/null +++ b/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/mod.rs @@ -0,0 +1,11 @@ +solverforge::planning_model! { + root = "crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain"; + + mod plan; + mod route; + mod stop; + + pub use plan::Plan; + pub use route::Route; + pub use stop::Stop; +} diff --git a/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/plan.rs b/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/plan.rs new file mode 100644 index 00000000..69474efc --- /dev/null +++ b/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/plan.rs @@ -0,0 +1,15 @@ +use solverforge::prelude::*; + +use super::{Route, Stop}; + +#[planning_solution] +pub struct Plan { + #[planning_entity_collection] + pub routes: Vec, + + #[problem_fact_collection] + pub stops: Vec, + + #[planning_score] + pub score: Option, +} diff --git a/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/route.rs b/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/route.rs new file mode 100644 index 00000000..f21f360a --- /dev/null +++ b/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/route.rs @@ -0,0 +1,19 @@ +use solverforge::prelude::*; + +// Group moves do not follow precedence routes, so the hooks exclude each other. +#[planning_entity] +pub struct Route { + #[planning_id] + pub id: usize, + + #[planning_list_variable( + element_collection = "stops", + precedence_successors_fn = "stop_successors", + element_group_fn = "stop_group" + )] + pub stops: Vec, +} + +pub(super) fn stop_successors(_: &super::Plan, _: usize, _: &mut Vec) {} + +pub(super) fn stop_group(_: &super::Plan, _: usize, _: &mut Vec) {} diff --git a/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/stop.rs b/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/stop.rs new file mode 100644 index 00000000..54a5328d --- /dev/null +++ b/crates/solverforge-macros/tests/ui/fail/element_groups_with_precedence/domain/stop.rs @@ -0,0 +1,7 @@ +use solverforge::prelude::*; + +#[problem_fact] +pub struct Stop { + #[planning_id] + pub id: usize, +} diff --git a/crates/solverforge-macros/tests/ui/fail/planning_list_variable_unknown_argument.stderr b/crates/solverforge-macros/tests/ui/fail/planning_list_variable_unknown_argument.stderr index d5d1f129..c59886a2 100644 --- a/crates/solverforge-macros/tests/ui/fail/planning_list_variable_unknown_argument.stderr +++ b/crates/solverforge-macros/tests/ui/fail/planning_list_variable_unknown_argument.stderr @@ -1,4 +1,4 @@ -error: unsupported planning_list_variable argument `unexpected`; supported arguments are element_collection, domain, distance_meter, intra_distance_meter, route_hooks, savings_hooks, savings_metric_class_fn, savings_neighbors_fn, element_owner_fn, construction_element_order_key, precedence_duration_fn, precedence_successors_fn, solution_trait +error: unsupported planning_list_variable argument `unexpected`; supported arguments are element_collection, domain, distance_meter, intra_distance_meter, route_hooks, savings_hooks, savings_metric_class_fn, savings_neighbors_fn, element_owner_fn, construction_element_order_key, precedence_duration_fn, precedence_successors_fn, element_group_fn, solution_trait --> tests/ui/fail/planning_list_variable_unknown_argument.rs:8:61 | 8 | #[planning_list_variable(element_collection = "visits", unexpected = "value")] diff --git a/crates/solverforge-solver/WIREFRAME.md b/crates/solverforge-solver/WIREFRAME.md index 69b4299d..a1487cc4 100644 --- a/crates/solverforge-solver/WIREFRAME.md +++ b/crates/solverforge-solver/WIREFRAME.md @@ -44,6 +44,9 @@ src/ ├── model_support.rs — Hidden `PlanningModelSupport` bridge implemented by `planning_model!` for model-owned scalar hook attachment, scalar group attachment, model/solution validation, and shadow updates ├── pinning.rs — Internal descriptor-backed pin checks for solver-generated moves and entity mutations ├── list_placement.rs — Private partial fixed-owner restriction helpers for list construction, ruin/recreate, Clarke-Wright, and list selectors; detects all-selected-elements-fixed-to-current so intra-owner reordering still streams while cross-owner moves are filtered +├── list_groups.rs — Private element-group module root for list variables with `element_group_fn` +├── list_groups/index.rs — Per-step group index (groups of two or more members, in declared order) and member placement lookup +├── list_groups/joint.rs — Bounded joint placement of a group's members on one owner (`max_member_distance`, owner shortlist) and its search ├── descriptor.rs — Re-exports descriptor bindings, selectors, move types, and internal construction/runtime helpers ├── descriptor/ │ ├── bindings.rs — Scalar-variable binding module root and public/internal re-exports @@ -119,7 +122,7 @@ src/ │ │ ├── composite/preview.rs — Internal owned preview director for read-only sequential checks and ordinary Cartesian selectors │ │ ├── list_union.rs — ListMoveUnion enum │ │ ├── list_multi_swap.rs — ListMultiSwapMove for independent same-step intra-list swaps -│ │ ├── list_kernel/ — Shared typed/dynamic list mutation kernels used by public moves and the compiled executor +│ │ ├── list_kernel/ — Shared typed/dynamic list mutation kernels used by public moves and the compiled executor, including group change (`group.rs`), group swap (`group/swap.rs`) and grouped ruin with joint recreate (`group_ruin.rs`) │ │ └── tests/ — Additional test modules │ │ ├── mod.rs │ │ ├── change.rs @@ -166,7 +169,7 @@ src/ │ ├── nearby_list_support.rs — Private selected-entity snapshots and bounded stable top-k nearby candidate ordering │ ├── nearby_list_swap.rs — Test-only NearbyListSwapMoveSelector oracle │ ├── nearby_support.rs — Shared nearest-candidate ordering and bounded stable top-k helpers for nearby neighborhoods -│ ├── list_kernel/ — Shared list candidate enumeration/emission kernels, including precedence and k-opt +│ ├── list_kernel/ — Shared list candidate enumeration/emission kernels, including precedence, k-opt, and group change/swap cursors │ ├── decorator/ │ │ ├── mod.rs — Re-exports │ │ ├── cartesian_product.rs — Test-only CartesianProductCursor and CartesianProductSelector oracles @@ -337,13 +340,15 @@ src/ │ │ ├── mod.rs — Re-exports │ │ ├── list_construction.rs — Re-exports │ │ ├── list_construction/access.rs — Source-indexed scored-list access shared by cheapest and regret kernels +│ │ ├── list_construction/groups.rs — Construction units of a list with element groups, joint trials, and group commits │ │ ├── list_construction/round_robin.rs — Explicit-source-key public facade for mandatory-construction round robin │ │ ├── list_construction/round_robin/kernel.rs — Canonical round-robin enumeration shared by public/static/dynamic adapters │ │ ├── list_construction/cheapest.rs — Explicit-source-key public facade for canonical cheapest insertion │ │ ├── list_construction/cheapest/kernel.rs — Source-indexed cheapest candidate ordering, precedence, and owner filtering │ │ ├── list_construction/cheapest/live.rs — Live score/trace/commit observer for the one cheapest kernel +│ │ ├── list_construction/cheapest/grouped.rs — Cheapest insertion placing each element group jointly │ │ ├── list_construction/regret.rs — Explicit-source-key public facade for canonical regret insertion -│ │ ├── list_construction/regret/kernel/ — Source-indexed regret evaluation, precedence, fallback, and execution kernel (`budgets.rs` work budgets, `choice.rs` regret values and comparisons) +│ │ ├── list_construction/regret/kernel/ — Source-indexed regret evaluation, precedence, fallback, and execution kernel (`budgets.rs` work budgets, `choice.rs` regret values and comparisons, `grouped.rs` regret insertion of whole element groups) │ │ ├── list_clarke_wright.rs — ListClarkeWrightPhase │ │ ├── list_clarke_wright/kernel.rs — Canonical savings merge and route assignment (savings.rs generates and sorts savings) shared by public/static/dynamic adapters │ │ ├── list_clarke_wright/tests.rs — Tests @@ -1050,7 +1055,15 @@ Runtime helpers: starts absent and is attached with `with_savings_neighbors_fn(...)`; it is the nearest-neighbour source bounded Clarke-Wright (`savings_neighbors`) requires, and the compiler rejects a bounded `ListClarkeWright` on a slot - without it. `ListVariableSlot` carries the same fields and builders. + without it. `ListVariableSlot` carries the same fields and builders. Its + precedence-successor and element-group hooks share one private field, read + through `precedence_successors_fn()` and `element_group_fn()`; they are set + with `with_precedence_hooks(...)` and `with_element_group_fn(...)`, which + panic when both are declared. The group hook appends the members of an + element's group, in order and including the element; a list with it gets + group change, group swap, grouped ruin and joint cheapest/regret + construction, and its single-element moves keep grouped elements on their + owner. - `ListVariableEntity` — list-variable accessors plus `HAS_LIST_VARIABLE`, `LIST_VARIABLE_NAME`, and `LIST_ELEMENT_SOURCE` - `runtime/compiler/` — compiles one value-owned `RuntimeModel` into an immutable graph, prepares solve-owned sources, and runs every configured or default phase through `CompiledRuntimePhaseRunner` - `PlanningModelSupport` — `#[doc(hidden)]` support trait (and `#[doc(hidden)]` diff --git a/crates/solverforge-solver/public-api.txt b/crates/solverforge-solver/public-api.txt index 21779074..d7bb927d 100644 --- a/crates/solverforge-solver/public-api.txt +++ b/crates/solverforge-solver/public-api.txt @@ -81,13 +81,16 @@ struct ListVariableMetadata: pub struct ListVariableMetadata {Show 1 ListVariableMetadata: pub fn with_savings_feasible_shared_by_metric_class(self, shared: bool) -> Self ListVariableMetadata: pub fn with_savings_neighbors_fn( self, savings_neighbors_fn: Option)>, ) -> Self ListVariableMetadata: pub fn with_element_owner_fn( self, element_owner_fn: Option Option>, ) -> Self -struct ListVariableSlot: pub struct ListVariableSlot {Show 35 fields pub entity_type_name: &'static str, pub element_count: fn(&S) -> usize, pub assigned_elements: fn(&S) -> Vec, pub list_len: fn(&S, usize) -> usize, pub list_remove: fn(&mut S, usize, usize) -> Option, pub list_insert: fn(&mut S, usize, usize, V), pub list_get: fn(&S, usize, usize) -> Option, pub list_set: fn(&mut S, usize, usize, V), pub list_reverse: fn(&mut S, usize, usize, usize), pub sublist_remove: fn(&mut S, usize, usize, usize) -> Vec, pub sublist_insert: fn(&mut S, usize, usize, Vec), pub ruin_remove: fn(&mut S, usize, usize) -> V, pub ruin_insert: fn(&mut S, usize, usize, V), pub index_to_element: fn(&S, usize) -> V, pub element_source_key: fn(&S, &V) -> usize, pub entity_count: fn(&S) -> usize, pub cross_distance_meter: DM, pub intra_distance_meter: IDM, pub variable_name: &'static str, pub descriptor_index: usize, pub route_get_fn: Option Vec>, pub route_set_fn: Option)>, pub route_depot_fn: Option usize>, pub route_distance_fn: Option i64>, pub route_feasible_fn: Option bool>, pub savings_depot_fn: Option usize>, pub savings_metric_class_fn: Option usize>, pub savings_distance_fn: Option i64>, pub savings_feasible_fn: Option bool>, pub savings_feasible_shared_by_metric_class: bool, pub savings_neighbors_fn: Option)>, pub element_owner_fn: Option Option>, pub construction_element_order_key: Option i64>, pub precedence_duration_fn: Option usize>, pub precedence_successors_fn: Option)>, /* private fields */ } +struct ListVariableSlot: pub struct ListVariableSlot {Show 34 fields pub entity_type_name: &'static str, pub element_count: fn(&S) -> usize, pub assigned_elements: fn(&S) -> Vec, pub list_len: fn(&S, usize) -> usize, pub list_remove: fn(&mut S, usize, usize) -> Option, pub list_insert: fn(&mut S, usize, usize, V), pub list_get: fn(&S, usize, usize) -> Option, pub list_set: fn(&mut S, usize, usize, V), pub list_reverse: fn(&mut S, usize, usize, usize), pub sublist_remove: fn(&mut S, usize, usize, usize) -> Vec, pub sublist_insert: fn(&mut S, usize, usize, Vec), pub ruin_remove: fn(&mut S, usize, usize) -> V, pub ruin_insert: fn(&mut S, usize, usize, V), pub index_to_element: fn(&S, usize) -> V, pub element_source_key: fn(&S, &V) -> usize, pub entity_count: fn(&S) -> usize, pub cross_distance_meter: DM, pub intra_distance_meter: IDM, pub variable_name: &'static str, pub descriptor_index: usize, pub route_get_fn: Option Vec>, pub route_set_fn: Option)>, pub route_depot_fn: Option usize>, pub route_distance_fn: Option i64>, pub route_feasible_fn: Option bool>, pub savings_depot_fn: Option usize>, pub savings_metric_class_fn: Option usize>, pub savings_distance_fn: Option i64>, pub savings_feasible_fn: Option bool>, pub savings_feasible_shared_by_metric_class: bool, pub savings_neighbors_fn: Option)>, pub element_owner_fn: Option Option>, pub construction_element_order_key: Option i64>, pub precedence_duration_fn: Option usize>, /* private fields */ } ListVariableSlot: pub fn new( entity_type_name: &'static str, element_count: fn(&S) -> usize, assigned_elements: fn(&S) -> Vec, list_len: fn(&S, usize) -> usize, list_remove: fn(&mut S, usize, usize) -> Option, list_insert: fn(&mut S, usize, usize, V), list_get: fn(&S, usize, usize) -> Option, list_set: fn(&mut S, usize, usize, V), list_reverse: fn(&mut S, usize, usize, usize), sublist_remove: fn(&mut S, usize, usize, usize) -> Vec, sublist_insert: fn(&mut S, usize, usize, Vec), ruin_remove: fn(&mut S, usize, usize) -> V, ruin_insert: fn(&mut S, usize, usize, V), index_to_element: fn(&S, usize) -> V, element_source_key: fn(&S, &V) -> usize, entity_count: fn(&S) -> usize, cross_distance_meter: DM, intra_distance_meter: IDM, variable_name: &'static str, descriptor_index: usize, route_get_fn: Option Vec>, route_set_fn: Option)>, route_depot_fn: Option usize>, route_distance_fn: Option i64>, route_feasible_fn: Option bool>, savings_depot_fn: Option usize>, savings_metric_class_fn: Option usize>, savings_distance_fn: Option i64>, savings_feasible_fn: Option bool>, ) -> Self ListVariableSlot: pub fn with_savings_feasible_shared_by_metric_class(self, shared: bool) -> Self ListVariableSlot: pub fn with_savings_neighbors_fn( self, savings_neighbors_fn: Option)>, ) -> Self ListVariableSlot: pub fn with_element_owner_fn( self, element_owner_fn: Option Option>, ) -> Self ListVariableSlot: pub fn with_construction_element_order_key( self, construction_element_order_key: Option i64>, ) -> Self ListVariableSlot: pub fn with_precedence_hooks( self, duration_fn: Option usize>, successors_fn: Option)>, ) -> Self + ListVariableSlot: pub fn with_element_group_fn( self, element_group_fn: Option)>, ) -> Self + ListVariableSlot: pub fn precedence_successors_fn(&self) -> Option)> + ListVariableSlot: pub fn element_group_fn(&self) -> Option)> ListVariableSlot: pub fn matches_target( &self, entity_class: Option<&str>, variable_name: Option<&str>, ) -> bool ListVariableSlot: pub fn has_unassigned_elements(&self, solution: &S) -> bool ListVariableSlot: pub fn has_list_content(&self, solution: &S) -> bool diff --git a/crates/solverforge-solver/src/builder/context.rs b/crates/solverforge-solver/src/builder/context.rs index 6fd9b6c7..2e4b1764 100644 --- a/crates/solverforge-solver/src/builder/context.rs +++ b/crates/solverforge-solver/src/builder/context.rs @@ -37,8 +37,8 @@ pub(crate) use provider::{ }; pub(crate) use runtime_list::{RuntimeListElement, RuntimeListSlot}; pub(crate) use runtime_list_policy::{ - ConstructionOrderPolicy, OwnershipPolicy, PrecedencePolicy, RouteFeasibilityPolicy, - RouteReadPolicy, RouteReplacePolicy, SavingsMetricClassPolicy, + ConstructionOrderPolicy, ElementGroupPolicy, OwnershipPolicy, PrecedencePolicy, + RouteFeasibilityPolicy, RouteReadPolicy, RouteReplacePolicy, SavingsMetricClassPolicy, }; pub(crate) use runtime_list_source::{ bind_runtime_list_source, unassigned_from_current_assignment, ListConstructionKernelError, diff --git a/crates/solverforge-solver/src/builder/context/list.rs b/crates/solverforge-solver/src/builder/context/list.rs index 96d52aa0..59e78f5a 100644 --- a/crates/solverforge-solver/src/builder/context/list.rs +++ b/crates/solverforge-solver/src/builder/context/list.rs @@ -98,11 +98,20 @@ pub struct ListVariableSlot { pub construction_element_order_key: Option i64>, /// Duration of an element for precedence-aware list moves. pub precedence_duration_fn: Option usize>, - /// Appends the precedence successors of an element to the buffer. - pub precedence_successors_fn: Option)>, + /// The precedence-successor or element-group hook; the two exclude each + /// other, so they share one field read through `element_relation`. + element_relation_fn: Option)>, + element_relation: ElementRelation, _phantom: PhantomData<(fn() -> S, fn() -> V)>, } +/// Which relation the shared element-relation hook of a slot declares. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum ElementRelation { + Precedence, + Groups, +} + impl Clone for ListVariableSlot { fn clone(&self) -> Self { Self { @@ -140,7 +149,8 @@ impl Clone for ListVariableSlot { element_owner_fn: self.element_owner_fn, construction_element_order_key: self.construction_element_order_key, precedence_duration_fn: self.precedence_duration_fn, - precedence_successors_fn: self.precedence_successors_fn, + element_relation_fn: self.element_relation_fn, + element_relation: self.element_relation, _phantom: PhantomData, } } @@ -217,7 +227,8 @@ impl ListVariableSlot { element_owner_fn: None, construction_element_order_key: None, precedence_duration_fn: None, - precedence_successors_fn: None, + element_relation_fn: None, + element_relation: ElementRelation::Precedence, _phantom: PhantomData, } } @@ -262,11 +273,49 @@ impl ListVariableSlot { duration_fn: Option usize>, successors_fn: Option)>, ) -> Self { + assert!( + successors_fn.is_none() || self.element_group_fn().is_none(), + "a list variable cannot combine precedence successors with element groups" + ); self.precedence_duration_fn = duration_fn; - self.precedence_successors_fn = successors_fn; + if successors_fn.is_some() || self.element_relation == ElementRelation::Precedence { + self.element_relation_fn = successors_fn; + self.element_relation = ElementRelation::Precedence; + } self } + /// Sets the element group hook: it appends the members of an element's + /// group, in order and including the element, and nothing for an element + /// without a group. Members of one group move together and share one + /// owner. + pub fn with_element_group_fn( + mut self, + element_group_fn: Option)>, + ) -> Self { + assert!( + element_group_fn.is_none() || self.precedence_successors_fn().is_none(), + "a list variable cannot combine element groups with precedence successors" + ); + if element_group_fn.is_some() || self.element_relation == ElementRelation::Groups { + self.element_relation_fn = element_group_fn; + self.element_relation = ElementRelation::Groups; + } + self + } + + /// The hook appending an element's precedence successors, if declared. + pub fn precedence_successors_fn(&self) -> Option)> { + self.element_relation_fn + .filter(|_| self.element_relation == ElementRelation::Precedence) + } + + /// The hook appending an element's group members, if declared. + pub fn element_group_fn(&self) -> Option)> { + self.element_relation_fn + .filter(|_| self.element_relation == ElementRelation::Groups) + } + /// Whether this slot matches the given entity class and variable name; /// `None` matches any. pub fn matches_target(&self, entity_class: Option<&str>, variable_name: Option<&str>) -> bool { @@ -310,7 +359,7 @@ impl ListVariableSlot { /// Whether both precedence hooks are present. pub fn supports_precedence_moves(&self) -> bool { - self.precedence_duration_fn.is_some() && self.precedence_successors_fn.is_some() + self.precedence_duration_fn.is_some() && self.precedence_successors_fn().is_some() } } diff --git a/crates/solverforge-solver/src/builder/context/list_access/dynamic.rs b/crates/solverforge-solver/src/builder/context/list_access/dynamic.rs index 3cfac330..c250bf13 100644 --- a/crates/solverforge-solver/src/builder/context/list_access/dynamic.rs +++ b/crates/solverforge-solver/src/builder/context/list_access/dynamic.rs @@ -31,7 +31,8 @@ pub(super) fn dynamic_access_has( | ListAccessCapability::IntraPositionDistance | ListAccessCapability::Route | ListAccessCapability::Savings - | ListAccessCapability::SavingsNeighbors => false, + | ListAccessCapability::SavingsNeighbors + | ListAccessCapability::ElementGroups => false, } } @@ -52,8 +53,10 @@ pub(super) fn dynamic_metadata_has( ListAccessCapability::IntraPositionDistance => capabilities.intra_position_distance, ListAccessCapability::Route => capabilities.route, ListAccessCapability::Savings => capabilities.savings, - // Host-language metadata declares no savings neighbour source. + // Host-language metadata declares no savings neighbour source and no + // element groups. ListAccessCapability::SavingsNeighbors + | ListAccessCapability::ElementGroups | ListAccessCapability::Set | ListAccessCapability::Replace | ListAccessCapability::Reverse diff --git a/crates/solverforge-solver/src/builder/context/list_access/static_access.rs b/crates/solverforge-solver/src/builder/context/list_access/static_access.rs index ba3960a8..e296112b 100644 --- a/crates/solverforge-solver/src/builder/context/list_access/static_access.rs +++ b/crates/solverforge-solver/src/builder/context/list_access/static_access.rs @@ -137,7 +137,7 @@ where element: Self::Element, successors: &mut Vec, ) -> Result<(), ListAccessError> { - let Some(successors_fn) = self.precedence_successors_fn else { + let Some(successors_fn) = self.precedence_successors_fn() else { return Err(typed_error(self, ListAccessCapability::Precedence)); }; successors_fn(solution, element, successors); diff --git a/crates/solverforge-solver/src/builder/context/list_access/types.rs b/crates/solverforge-solver/src/builder/context/list_access/types.rs index 372a8a30..5200e659 100644 --- a/crates/solverforge-solver/src/builder/context/list_access/types.rs +++ b/crates/solverforge-solver/src/builder/context/list_access/types.rs @@ -15,6 +15,7 @@ pub(crate) enum ListAccessCapability { Route, Savings, SavingsNeighbors, + ElementGroups, } #[derive(Debug, Clone, PartialEq, Eq)] diff --git a/crates/solverforge-solver/src/builder/context/runtime_list.rs b/crates/solverforge-solver/src/builder/context/runtime_list.rs index d14c95d2..e18fddb5 100644 --- a/crates/solverforge-solver/src/builder/context/runtime_list.rs +++ b/crates/solverforge-solver/src/builder/context/runtime_list.rs @@ -19,6 +19,7 @@ use super::{ ListVariableSlot, }; +mod groups; mod meter; /// Element payload carried by a runtime list move. @@ -364,7 +365,7 @@ where )); } let mut values = Vec::new(); - (metadata_bindings.precedence_successors)( + (metadata_bindings.element_relation)( solution, static_element(element), &mut values, diff --git a/crates/solverforge-solver/src/builder/context/runtime_list/groups.rs b/crates/solverforge-solver/src/builder/context/runtime_list/groups.rs new file mode 100644 index 00000000..38f9f715 --- /dev/null +++ b/crates/solverforge-solver/src/builder/context/runtime_list/groups.rs @@ -0,0 +1,54 @@ +use super::*; +use crate::list_groups::{ListElementGroups, ListGroupPlacement}; + +impl RuntimeListSlot +where + S: Clone + Send + Sync + 'static, + V: Clone + PartialEq + Send + Sync + fmt::Debug + 'static, + DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, +{ + /// The slot's element groups, or `None` when it declares no group hook + /// or the hook forms no group of two or more members. + pub(crate) fn element_groups(&self, solution: &S) -> Option { + let Self::Static { + metadata_bindings, .. + } = self + else { + return None; + }; + if !metadata_bindings.element_group_policy.is_explicit() { + return None; + } + let element_group = metadata_bindings.element_relation; + let mut values = Vec::new(); + let groups = ListElementGroups::from_hook( + ListAccess::element_count(self, solution), + |index| ListAccess::index_to_element(self, solution, index), + |element| ListAccess::element_source_key(self, solution, element), + |element, members| { + values.clear(); + element_group(solution, static_element(element.clone()), &mut values); + members.extend(values.drain(..).map(RuntimeListElement::Static)); + }, + ); + (!groups.is_empty()).then_some(groups) + } + + /// Locates every grouped element in the current lists. + pub(crate) fn locate_group_members( + &self, + groups: &ListElementGroups, + solution: &S, + ) -> ListGroupPlacement { + ListGroupPlacement::locate( + groups, + ListAccess::entity_count(self, solution), + |entity| ListAccess::list_len(self, solution, entity), + |entity, position| { + ListAccess::list_get(self, solution, entity, position) + .map(|element| ListAccess::element_source_key(self, solution, &element)) + }, + ) + } +} diff --git a/crates/solverforge-solver/src/builder/context/runtime_list_binding.rs b/crates/solverforge-solver/src/builder/context/runtime_list_binding.rs index ca17e494..e2bc5432 100644 --- a/crates/solverforge-solver/src/builder/context/runtime_list_binding.rs +++ b/crates/solverforge-solver/src/builder/context/runtime_list_binding.rs @@ -10,8 +10,8 @@ use super::list_access::ListAccessCapability; use super::runtime_list_metadata_policy::StaticListMetadataBindings; use super::runtime_list_route_policy::{RuntimeDynamicListSlot, StaticRouteBindings}; use super::{ - ConstructionOrderPolicy, ListVariableSlot, OwnershipPolicy, PrecedencePolicy, - RouteFeasibilityPolicy, RouteReadPolicy, RouteReplacePolicy, RuntimeListSlot, + ConstructionOrderPolicy, ElementGroupPolicy, ListVariableSlot, OwnershipPolicy, + PrecedencePolicy, RouteFeasibilityPolicy, RouteReadPolicy, RouteReplacePolicy, RuntimeListSlot, RuntimeScalarSlotId, SavingsMetricClassPolicy, }; @@ -115,6 +115,16 @@ impl RuntimeListSlot { } } + /// Element groups are a typed list feature: dynamic slots declare none. + pub(crate) fn element_group_policy(&self) -> ElementGroupPolicy { + match self { + Self::Static { + metadata_bindings, .. + } => metadata_bindings.element_group_policy, + Self::Dynamic(_) => ElementGroupPolicy::Absent, + } + } + pub(crate) fn identity(&self) -> RuntimeScalarSlotId { match self { Self::Static { @@ -166,6 +176,9 @@ impl RuntimeListSlot { ListAccessCapability::Route => route_bindings.supports_route(), ListAccessCapability::Savings => route_bindings.supports_savings(), ListAccessCapability::SavingsNeighbors => self.savings_neighbors_fn().is_some(), + ListAccessCapability::ElementGroups => { + metadata_bindings.element_group_policy.is_explicit() + } }, Self::Dynamic(slot) => { let access = slot.access_capabilities(); @@ -193,7 +206,8 @@ impl RuntimeListSlot { && metadata.savings && slot.savings_metric_class_policy().is_dynamic_explicit() } - ListAccessCapability::SavingsNeighbors => false, + ListAccessCapability::SavingsNeighbors + | ListAccessCapability::ElementGroups => false, } } } diff --git a/crates/solverforge-solver/src/builder/context/runtime_list_debug.rs b/crates/solverforge-solver/src/builder/context/runtime_list_debug.rs index 5bac2fad..deca0d42 100644 --- a/crates/solverforge-solver/src/builder/context/runtime_list_debug.rs +++ b/crates/solverforge-solver/src/builder/context/runtime_list_debug.rs @@ -41,6 +41,10 @@ impl fmt::Debug for RuntimeListSlot f .debug_struct("RuntimeListSlot::Dynamic") diff --git a/crates/solverforge-solver/src/builder/context/runtime_list_metadata_policy.rs b/crates/solverforge-solver/src/builder/context/runtime_list_metadata_policy.rs index 014836ca..e2e401bb 100644 --- a/crates/solverforge-solver/src/builder/context/runtime_list_metadata_policy.rs +++ b/crates/solverforge-solver/src/builder/context/runtime_list_metadata_policy.rs @@ -2,7 +2,9 @@ use std::fmt; -use super::runtime_list_policy::{ConstructionOrderPolicy, OwnershipPolicy, PrecedencePolicy}; +use super::runtime_list_policy::{ + ConstructionOrderPolicy, ElementGroupPolicy, OwnershipPolicy, PrecedencePolicy, +}; use super::ListVariableSlot; fn declared_unrestricted(_: &S, _: &V) -> Option { @@ -32,10 +34,14 @@ pub(crate) struct StaticListMetadataBindings { pub(super) ownership_policy: OwnershipPolicy, pub(super) construction_order_policy: ConstructionOrderPolicy, pub(super) precedence_policy: PrecedencePolicy, + pub(super) element_group_policy: ElementGroupPolicy, pub(super) element_owner: fn(&S, &V) -> Option, pub(super) construction_order: fn(&S, V) -> i64, pub(super) precedence_duration: fn(&S, V) -> usize, - pub(super) precedence_successors: fn(&S, V, &mut Vec), + /// Precedence successors under a precedence policy with successors, the + /// element group hook under an explicit group policy; the two exclude + /// each other. + pub(super) element_relation: fn(&S, V, &mut Vec), } impl fmt::Debug for StaticListMetadataBindings { @@ -47,6 +53,10 @@ impl fmt::Debug for StaticListMetadataBindings { &self.construction_order_policy.trace_label(), ) .field("precedence_policy", &self.precedence_policy.trace_label()) + .field( + "element_group_policy", + &self.element_group_policy.trace_label(), + ) .finish() } } @@ -78,7 +88,7 @@ impl StaticListMetadataBindings { PrecedencePolicy, fn(&S, V) -> usize, fn(&S, V, &mut Vec), - ) = match (slot.precedence_duration_fn, slot.precedence_successors_fn) { + ) = match (slot.precedence_duration_fn, slot.precedence_successors_fn()) { (Some(duration), Some(successors)) => { (PrecedencePolicy::Explicit, duration, successors) } @@ -93,14 +103,20 @@ impl StaticListMetadataBindings { unavailable_precedence_successors::, ), }; + let (element_group_policy, element_relation): (ElementGroupPolicy, fn(&S, V, &mut Vec)) = + match slot.element_group_fn() { + Some(element_group) => (ElementGroupPolicy::ExplicitStaticProvider, element_group), + None => (ElementGroupPolicy::Absent, precedence_successors), + }; Self { ownership_policy, construction_order_policy, precedence_policy, + element_group_policy, element_owner, construction_order, precedence_duration, - precedence_successors, + element_relation, } } } diff --git a/crates/solverforge-solver/src/builder/context/runtime_list_policy.rs b/crates/solverforge-solver/src/builder/context/runtime_list_policy.rs index 9b7c05b4..b47707b0 100644 --- a/crates/solverforge-solver/src/builder/context/runtime_list_policy.rs +++ b/crates/solverforge-solver/src/builder/context/runtime_list_policy.rs @@ -186,3 +186,24 @@ impl PrecedencePolicy { } } } + +/// Source of a list variable's element groups. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) enum ElementGroupPolicy { + /// No group hook: every element moves alone. + Absent, + ExplicitStaticProvider, +} + +impl ElementGroupPolicy { + pub(crate) const fn is_explicit(self) -> bool { + matches!(self, Self::ExplicitStaticProvider) + } + + pub(crate) const fn trace_label(self) -> &'static str { + match self { + Self::Absent => "absent", + Self::ExplicitStaticProvider => "explicit", + } + } +} diff --git a/crates/solverforge-solver/src/heuristic/move/list_kernel/group.rs b/crates/solverforge-solver/src/heuristic/move/list_kernel/group.rs new file mode 100644 index 00000000..35c6631f --- /dev/null +++ b/crates/solverforge-solver/src/heuristic/move/list_kernel/group.rs @@ -0,0 +1,369 @@ +//! Shared group change and group swap mechanics. +//! +//! A group's members move together and keep their declared order. Group +//! change takes every member out, wherever it is, and inserts the members at +//! increasing final positions of one destination list; other elements may +//! sit between them. Group swap exchanges two equally sized groups on two +//! owners, each taking the other's member slots. + +use smallvec::{smallvec, SmallVec}; +use solverforge_core::domain::PlanningSolution; +use solverforge_scoring::Director; + +use crate::heuristic::r#move::metadata::{ + encode_usize, hash_str, MoveTabuScope, ScopedEntityTabuToken, ScopedValueTabuToken, +}; +use crate::heuristic::r#move::MoveTabuSignature; +use crate::list_groups::JointPositions; +use crate::stats::CandidateTraceIdentity; + +use super::{ListChangeAccess, ListMoveAccess}; + +mod swap; + +pub(crate) use swap::{ + group_swap_candidate_trace_identity, group_swap_do_move, group_swap_is_doable, + group_swap_tabu_signature, group_swap_undo_move, +}; + +/// `(entity, position)` of every member of a group, in declared order. +pub(crate) type MemberCoordinates = SmallVec<[(usize, usize); 4]>; + +/// One group relocated to joint positions of a destination list. +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) struct GroupChangeCoordinates { + /// Where every member sits before the move, in declared order. + pub(crate) sources: MemberCoordinates, + pub(crate) destination_entity: usize, + /// The members' final positions in the destination list, increasing in + /// declared order. + pub(crate) destination_positions: JointPositions, +} + +/// Two equally sized groups exchanging their member slots. +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) struct GroupSwapCoordinates { + pub(crate) first_entity: usize, + /// Positions of the first group's members, in declared order. + pub(crate) first_positions: JointPositions, + pub(crate) second_entity: usize, + /// Positions of the second group's members, in declared order. + pub(crate) second_positions: JointPositions, +} + +impl GroupChangeCoordinates { + /// Every entity the move touches, ascending. + pub(crate) fn entities(&self) -> SmallVec<[usize; 8]> { + let mut entities: SmallVec<[usize; 8]> = + self.sources.iter().map(|&(entity, _)| entity).collect(); + entities.push(self.destination_entity); + entities.sort_unstable(); + entities.dedup(); + entities + } + + /// Whether the move leaves every member where it is. + pub(crate) fn is_identity(&self) -> bool { + self.sources.iter().zip(&self.destination_positions).all( + |(&(entity, position), &destination)| { + entity == self.destination_entity && position == destination + }, + ) + } +} + +impl GroupSwapCoordinates { + pub(crate) fn entities(&self) -> SmallVec<[usize; 8]> { + let mut entities: SmallVec<[usize; 8]> = smallvec![self.first_entity, self.second_entity]; + entities.sort_unstable(); + entities + } +} + +fn sorted(positions: &[usize]) -> JointPositions { + let mut sorted = JointPositions::from_slice(positions); + sorted.sort_unstable(); + sorted +} + +fn entities_are_free>( + score_director: &D, + descriptor_index: usize, + entities: &[usize], +) -> bool { + entities + .iter() + .all(|&entity| !crate::pinning::entity_is_pinned(score_director, descriptor_index, entity)) +} + +fn positions_are_distinct_and_in_bounds(positions: &[usize], len: usize) -> bool { + let sorted = sorted(positions); + sorted.last().is_some_and(|&last| last < len) && sorted.windows(2).all(|w| w[0] < w[1]) +} + +pub(crate) fn group_change_is_doable( + access: &A, + coordinates: &GroupChangeCoordinates, + score_director: &D, +) -> bool +where + S: PlanningSolution, + A: ListChangeAccess, + D: Director, +{ + let member_count = coordinates.sources.len(); + if member_count == 0 + || coordinates.destination_positions.len() != member_count + || coordinates.is_identity() + { + return false; + } + let solution = score_director.working_solution(); + let mut sources = coordinates.sources.clone(); + sources.sort_unstable(); + if sources.windows(2).any(|pair| pair[0] == pair[1]) + || sources + .iter() + .any(|&(entity, position)| position >= access.list_len(solution, entity)) + { + return false; + } + let staying = sources + .iter() + .filter(|&&(entity, _)| entity == coordinates.destination_entity) + .count(); + let final_len = + access.list_len(solution, coordinates.destination_entity) - staying + member_count; + coordinates + .destination_positions + .windows(2) + .all(|pair| pair[0] < pair[1]) + && coordinates + .destination_positions + .last() + .is_some_and(|&last| last < final_len) + && entities_are_free( + score_director, + access.descriptor_index(), + &coordinates.entities(), + ) +} + +fn notify_before>( + score_director: &mut D, + descriptor_index: usize, + entities: &[usize], +) { + for &entity in entities { + score_director.before_variable_changed(descriptor_index, entity); + } +} + +fn notify_after>( + score_director: &mut D, + descriptor_index: usize, + entities: &[usize], +) { + for &entity in entities { + score_director.after_variable_changed(descriptor_index, entity); + } +} + +/// Removes the members at `sources` and returns them in declared order. +fn take_members( + access: &A, + sources: &[(usize, usize)], + score_director: &mut D, +) -> SmallVec<[A::Element; 4]> +where + S: PlanningSolution, + A: ListChangeAccess, + D: Director, +{ + let mut order: SmallVec<[usize; 4]> = (0..sources.len()).collect(); + // Later positions first, so earlier positions stay valid. + order.sort_unstable_by(|&left, &right| { + let (left_entity, left_position) = sources[left]; + let (right_entity, right_position) = sources[right]; + left_entity + .cmp(&right_entity) + .then(right_position.cmp(&left_position)) + }); + let mut values: SmallVec<[Option; 4]> = (0..sources.len()).map(|_| None).collect(); + for member in order { + let (entity, position) = sources[member]; + values[member] = Some( + access + .list_remove(score_director.working_solution_mut(), entity, position) + .expect("group member position must hold the member"), + ); + } + values + .into_iter() + .map(|value| value.expect("every member was taken")) + .collect() +} + +/// Inserts `values` (declared order) at `targets`, earlier positions first +/// within each entity, so each value lands exactly at its target. +fn place_members( + access: &A, + values: SmallVec<[A::Element; 4]>, + targets: &[(usize, usize)], + score_director: &mut D, +) where + S: PlanningSolution, + A: ListChangeAccess, + D: Director, +{ + let mut slots: SmallVec<[Option; 4]> = values.into_iter().map(Some).collect(); + let mut order: SmallVec<[usize; 4]> = (0..targets.len()).collect(); + order.sort_unstable_by_key(|&member| targets[member]); + for member in order { + let (entity, position) = targets[member]; + access.list_insert( + score_director.working_solution_mut(), + entity, + position, + slots[member].take().expect("each member is placed once"), + ); + } +} + +fn destination_targets(coordinates: &GroupChangeCoordinates) -> MemberCoordinates { + coordinates + .destination_positions + .iter() + .map(|&position| (coordinates.destination_entity, position)) + .collect() +} + +pub(crate) fn group_change_do_move( + access: &A, + coordinates: &GroupChangeCoordinates, + score_director: &mut D, +) where + S: PlanningSolution, + A: ListChangeAccess, + D: Director, +{ + let descriptor_index = access.descriptor_index(); + let entities = coordinates.entities(); + notify_before(score_director, descriptor_index, &entities); + let values = take_members(access, &coordinates.sources, score_director); + place_members( + access, + values, + &destination_targets(coordinates), + score_director, + ); + notify_after(score_director, descriptor_index, &entities); +} + +pub(crate) fn group_change_undo_move( + access: &A, + coordinates: &GroupChangeCoordinates, + score_director: &mut D, +) where + S: PlanningSolution, + A: ListChangeAccess, + D: Director, +{ + let descriptor_index = access.descriptor_index(); + let entities = coordinates.entities(); + notify_before(score_director, descriptor_index, &entities); + let values = take_members(access, &destination_targets(coordinates), score_director); + place_members(access, values, &coordinates.sources, score_director); + notify_after(score_director, descriptor_index, &entities); +} + +fn member_value_ids( + access: &A, + targets: &[(usize, usize)], + score_director: &D, +) -> SmallVec<[u64; 4]> +where + S: PlanningSolution, + A: ListMoveAccess, + D: Director, +{ + let solution = score_director.working_solution(); + targets + .iter() + .map(|&(entity, position)| { + access.tabu_value_id( + solution, + access.list_get(solution, entity, position).as_ref(), + ) + }) + .collect() +} + +fn entity_tokens(scope: MoveTabuScope, entities: &[usize]) -> SmallVec<[ScopedEntityTabuToken; 2]> { + entities + .iter() + .map(|&entity| scope.entity_token(encode_usize(entity))) + .collect() +} + +fn value_tokens(scope: MoveTabuScope, ids: &[u64]) -> SmallVec<[ScopedValueTabuToken; 2]> { + ids.iter().map(|&id| scope.value_token(id)).collect() +} + +fn push_coordinates(id: &mut SmallVec<[u64; 8]>, coordinates: &[(usize, usize)]) { + for &(entity, position) in coordinates { + id.push(encode_usize(entity)); + id.push(encode_usize(position)); + } +} + +pub(crate) fn group_change_tabu_signature( + access: &A, + coordinates: &GroupChangeCoordinates, + score_director: &D, +) -> MoveTabuSignature +where + S: PlanningSolution, + A: ListMoveAccess, + D: Director, +{ + let value_ids = member_value_ids(access, &coordinates.sources, score_director); + let scope = MoveTabuScope::new(access.descriptor_index(), access.variable_name()); + let header: SmallVec<[u64; 8]> = smallvec![ + encode_usize(access.descriptor_index()), + hash_str(access.variable_name()), + encode_usize(coordinates.sources.len()) + ]; + let targets = destination_targets(coordinates); + let mut forward = header.clone(); + push_coordinates(&mut forward, &coordinates.sources); + push_coordinates(&mut forward, &targets); + forward.extend(value_ids.iter().copied()); + let mut backward = header; + push_coordinates(&mut backward, &targets); + push_coordinates(&mut backward, &coordinates.sources); + backward.extend(value_ids.iter().copied()); + MoveTabuSignature::from_identity(scope, forward, backward) + .with_entity_tokens(entity_tokens(scope, &coordinates.entities())) + .with_destination_value_tokens(value_tokens(scope, &value_ids)) +} + +pub(crate) fn group_change_candidate_trace_identity( + access: &A, + coordinates: &GroupChangeCoordinates, +) -> CandidateTraceIdentity +where + A: ListMoveAccess, +{ + CandidateTraceIdentity::logical_move( + access.descriptor_index(), + access.variable_name(), + "list_group_change", + coordinates + .sources + .iter() + .flat_map(|&(entity, position)| [entity, position]) + .chain(std::iter::once(coordinates.destination_entity)) + .chain(coordinates.destination_positions.iter().copied()), + ) +} diff --git a/crates/solverforge-solver/src/heuristic/move/list_kernel/group/swap.rs b/crates/solverforge-solver/src/heuristic/move/list_kernel/group/swap.rs new file mode 100644 index 00000000..3969c84c --- /dev/null +++ b/crates/solverforge-solver/src/heuristic/move/list_kernel/group/swap.rs @@ -0,0 +1,164 @@ +//! Group swap: two equally sized groups on two owners exchange their member +//! slots. + +use smallvec::{smallvec, SmallVec}; +use solverforge_core::domain::PlanningSolution; +use solverforge_scoring::Director; + +use crate::heuristic::r#move::metadata::{encode_usize, hash_str, MoveTabuScope}; +use crate::heuristic::r#move::MoveTabuSignature; +use crate::stats::CandidateTraceIdentity; + +use super::super::{ListChangeAccess, ListMoveAccess}; +use super::{ + entities_are_free, entity_tokens, member_value_ids, notify_after, notify_before, place_members, + positions_are_distinct_and_in_bounds, push_coordinates, sorted, take_members, value_tokens, + GroupSwapCoordinates, MemberCoordinates, +}; + +fn swap_sides(coordinates: &GroupSwapCoordinates) -> (MemberCoordinates, MemberCoordinates) { + let first = coordinates + .first_positions + .iter() + .map(|&position| (coordinates.first_entity, position)) + .collect(); + let second = coordinates + .second_positions + .iter() + .map(|&position| (coordinates.second_entity, position)) + .collect(); + (first, second) +} + +/// Member slots of one side, taken over in declared order by the other +/// group: its `i`-th member gets the `i`-th lowest slot. +fn exchanged_slots(entity: usize, positions: &[usize]) -> MemberCoordinates { + sorted(positions) + .into_iter() + .map(|position| (entity, position)) + .collect() +} + +pub(crate) fn group_swap_is_doable( + access: &A, + coordinates: &GroupSwapCoordinates, + score_director: &D, +) -> bool +where + S: PlanningSolution, + A: ListChangeAccess, + D: Director, +{ + let solution = score_director.working_solution(); + !coordinates.first_positions.is_empty() + && coordinates.first_positions.len() == coordinates.second_positions.len() + && coordinates.first_entity != coordinates.second_entity + && positions_are_distinct_and_in_bounds( + &coordinates.first_positions, + access.list_len(solution, coordinates.first_entity), + ) + && positions_are_distinct_and_in_bounds( + &coordinates.second_positions, + access.list_len(solution, coordinates.second_entity), + ) + && entities_are_free( + score_director, + access.descriptor_index(), + &coordinates.entities(), + ) +} + +pub(crate) fn group_swap_do_move( + access: &A, + coordinates: &GroupSwapCoordinates, + score_director: &mut D, +) where + S: PlanningSolution, + A: ListChangeAccess, + D: Director, +{ + let descriptor_index = access.descriptor_index(); + let entities = coordinates.entities(); + let (first, second) = swap_sides(coordinates); + notify_before(score_director, descriptor_index, &entities); + let first_values = take_members(access, &first, score_director); + let second_values = take_members(access, &second, score_director); + let first_slots = exchanged_slots(coordinates.first_entity, &coordinates.first_positions); + let second_slots = exchanged_slots(coordinates.second_entity, &coordinates.second_positions); + place_members(access, second_values, &first_slots, score_director); + place_members(access, first_values, &second_slots, score_director); + notify_after(score_director, descriptor_index, &entities); +} + +pub(crate) fn group_swap_undo_move( + access: &A, + coordinates: &GroupSwapCoordinates, + score_director: &mut D, +) where + S: PlanningSolution, + A: ListChangeAccess, + D: Director, +{ + let descriptor_index = access.descriptor_index(); + let entities = coordinates.entities(); + let (first, second) = swap_sides(coordinates); + let first_slots = exchanged_slots(coordinates.first_entity, &coordinates.first_positions); + let second_slots = exchanged_slots(coordinates.second_entity, &coordinates.second_positions); + notify_before(score_director, descriptor_index, &entities); + let second_values = take_members(access, &first_slots, score_director); + let first_values = take_members(access, &second_slots, score_director); + place_members(access, first_values, &first, score_director); + place_members(access, second_values, &second, score_director); + notify_after(score_director, descriptor_index, &entities); +} + +pub(crate) fn group_swap_tabu_signature( + access: &A, + coordinates: &GroupSwapCoordinates, + score_director: &D, +) -> MoveTabuSignature +where + S: PlanningSolution, + A: ListMoveAccess, + D: Director, +{ + let (first, second) = swap_sides(coordinates); + let first_ids = member_value_ids(access, &first, score_director); + let second_ids = member_value_ids(access, &second, score_director); + let scope = MoveTabuScope::new(access.descriptor_index(), access.variable_name()); + let mut header: SmallVec<[u64; 8]> = smallvec![ + encode_usize(access.descriptor_index()), + hash_str(access.variable_name()), + encode_usize(first.len()) + ]; + push_coordinates(&mut header, &first); + push_coordinates(&mut header, &second); + let mut forward = header.clone(); + forward.extend(first_ids.iter().copied()); + forward.extend(second_ids.iter().copied()); + let mut backward = header; + backward.extend(second_ids.iter().copied()); + backward.extend(first_ids.iter().copied()); + let moved: SmallVec<[u64; 8]> = first_ids.iter().chain(&second_ids).copied().collect(); + MoveTabuSignature::from_identity(scope, forward, backward) + .with_entity_tokens(entity_tokens(scope, &coordinates.entities())) + .with_destination_value_tokens(value_tokens(scope, &moved)) +} + +pub(crate) fn group_swap_candidate_trace_identity( + access: &A, + coordinates: &GroupSwapCoordinates, +) -> CandidateTraceIdentity +where + A: ListMoveAccess, +{ + CandidateTraceIdentity::logical_move( + access.descriptor_index(), + access.variable_name(), + "list_group_swap", + std::iter::once(coordinates.first_entity) + .chain(coordinates.first_positions.iter().copied()) + .chain(std::iter::once(coordinates.second_entity)) + .chain(coordinates.second_positions.iter().copied()), + ) +} diff --git a/crates/solverforge-solver/src/heuristic/move/list_kernel/group_ruin.rs b/crates/solverforge-solver/src/heuristic/move/list_kernel/group_ruin.rs new file mode 100644 index 00000000..68c4ba2d --- /dev/null +++ b/crates/solverforge-solver/src/heuristic/move/list_kernel/group_ruin.rs @@ -0,0 +1,415 @@ +//! Ruin and recreate of whole element groups. +//! +//! A ruin removes every member of each selected group, wherever it sits. +//! Recreate then inserts one unit at a time, greedily: each round scores +//! every remaining unit's bounded joint placements on every owner all its +//! members allow, and commits the best. Units are whole groups or single +//! ungrouped elements; members of a unit always land on one owner, in +//! declared order. + +use smallvec::{smallvec, SmallVec}; +use solverforge_core::domain::PlanningSolution; +use solverforge_scoring::Director; + +use crate::heuristic::r#move::metadata::{encode_usize, hash_str, MoveTabuScope}; +use crate::heuristic::r#move::MoveTabuSignature; +use crate::list_groups::{search_joint_placement, JointBounds, JointSearch}; +use crate::list_placement::OwnerRestriction; +use crate::stats::CandidateTraceIdentity; + +use super::ruin::{final_positions_after_ordered_insertions, restore_values}; +use super::{ListMoveAccess, ListRuinAccess, RuinUndo}; + +/// The elements one group ruin removes, grouped into recreate units. +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) struct GroupRuinPlan { + /// `(entity, position)` of every removed element: units one after + /// another, each unit's members in declared order. + pub(crate) removed: SmallVec<[(usize, usize); 8]>, + /// End offset in `removed` of each unit. + pub(crate) unit_ends: SmallVec<[u16; 8]>, + pub(crate) bounds: JointBounds, + pub(crate) skip_empty_destinations: bool, +} + +impl GroupRuinPlan { + pub(crate) fn entities(&self) -> SmallVec<[usize; 8]> { + let mut entities: SmallVec<[usize; 8]> = + self.removed.iter().map(|&(entity, _)| entity).collect(); + entities.sort_unstable(); + entities.dedup(); + entities + } + + fn units(&self) -> impl Iterator> + '_ { + let mut start = 0; + self.unit_ends.iter().map(move |&end| { + let range = start..usize::from(end); + start = usize::from(end); + range + }) + } +} + +pub(crate) fn group_ruin_is_doable( + access: &A, + plan: &GroupRuinPlan, + score_director: &D, +) -> bool +where + S: PlanningSolution, + A: ListRuinAccess, + D: Director, +{ + if plan.removed.is_empty() { + return false; + } + let solution = score_director.working_solution(); + let descriptor_index = access.descriptor_index(); + let mut removed = plan.removed.clone(); + removed.sort_unstable(); + if removed.windows(2).any(|pair| pair[0] == pair[1]) + || removed + .iter() + .any(|&(entity, position)| position >= access.list_len(solution, entity)) + || plan.entities().iter().any(|&entity| { + crate::pinning::entity_is_pinned(score_director, descriptor_index, entity) + }) + { + return false; + } + let entity_count = access.entity_count(solution); + plan.units().all(|unit| { + let restriction = unit_restriction(access, solution, entity_count, &plan.removed[unit]); + (0..entity_count).any(|destination| { + restriction.allows(destination) + && !crate::pinning::entity_is_pinned(score_director, descriptor_index, destination) + }) + }) +} + +fn unit_restriction( + access: &A, + solution: &S, + entity_count: usize, + members: &[(usize, usize)], +) -> OwnerRestriction +where + S: PlanningSolution, + A: ListRuinAccess, +{ + if !access.has_owner_binding() { + return OwnerRestriction::Unrestricted; + } + members.iter().fold( + OwnerRestriction::Unrestricted, + |restriction, &(entity, position)| { + let element = access + .list_get(solution, entity, position) + .expect("a ruined member position holds the member"); + restriction.and(access.owner_restriction(solution, entity_count, &element)) + }, + ) +} + +pub(crate) fn group_ruin_do_move( + access: &A, + plan: &GroupRuinPlan, + score_director: &mut D, +) -> RuinUndo +where + S: PlanningSolution, + A: ListRuinAccess, + D: Director, +{ + let descriptor_index = access.descriptor_index(); + let entity_count = access.entity_count(score_director.working_solution()); + let restrictions: SmallVec<[OwnerRestriction; 8]> = plan + .units() + .map(|unit| { + unit_restriction( + access, + score_director.working_solution(), + entity_count, + &plan.removed[unit], + ) + }) + .collect(); + + // Remove every member, later positions of an entity first. + let mut order: SmallVec<[usize; 8]> = (0..plan.removed.len()).collect(); + order.sort_unstable_by(|&left, &right| { + let (left_entity, left_position) = plan.removed[left]; + let (right_entity, right_position) = plan.removed[right]; + left_entity + .cmp(&right_entity) + .then(right_position.cmp(&left_position)) + }); + let mut values: SmallVec<[Option; 8]> = + (0..plan.removed.len()).map(|_| None).collect(); + let mut current_entity = None; + for index in order { + let (entity, position) = plan.removed[index]; + if current_entity != Some(entity) { + if let Some(previous) = current_entity { + score_director.after_variable_changed(descriptor_index, previous); + } + score_director.before_variable_changed(descriptor_index, entity); + current_entity = Some(entity); + } + values[index] = + Some(access.list_remove(score_director.working_solution_mut(), entity, position)); + } + if let Some(entity) = current_entity { + score_director.after_variable_changed(descriptor_index, entity); + } + + let units: SmallVec<[std::ops::Range; 8]> = plan.units().collect(); + let mut placed: SmallVec<[bool; 8]> = smallvec![false; units.len()]; + let mut placements = RuinUndo::new(); + while placed.iter().any(|done| !done) { + let mut best: Option<(usize, usize, SmallVec<[usize; 4]>, S::Score)> = None; + for (unit_index, unit) in units.iter().enumerate() { + if placed[unit_index] { + continue; + } + let owners: SmallVec<[usize; 16]> = (0..entity_count) + .filter(|&destination| { + restrictions[unit_index].allows(destination) + && !crate::pinning::entity_is_pinned( + score_director, + descriptor_index, + destination, + ) + && !(plan.skip_empty_destinations + && !access.has_owner_binding() + && access.list_len(score_director.working_solution(), destination) == 0) + }) + .collect(); + let lens: SmallVec<[usize; 16]> = (0..entity_count) + .map(|entity| access.list_len(score_director.working_solution(), entity)) + .collect(); + let mut members: SmallVec<[A::Element; 4]> = values[unit.clone()] + .iter_mut() + .map(|value| value.take().expect("an unplaced member is held")) + .collect(); + let search = search_joint_placement( + &owners, + members.len(), + |entity| lens[entity], + plan.bounds, + |entity, positions| { + Some(score_joint_trial( + access, + &mut members, + entity, + positions, + score_director, + )) + }, + ); + for (slot, member) in values[unit.clone()].iter_mut().zip(members) { + *slot = Some(member); + } + let JointSearch::Done { + best: Some(choice), .. + } = search + else { + continue; + }; + if best + .as_ref() + .is_none_or(|(_, _, _, best_score)| choice.score > *best_score) + { + best = Some((unit_index, choice.entity, choice.positions, choice.score)); + } + } + let Some((unit_index, entity, positions, _)) = best else { + restore_unplaced(access, plan, &placements, &mut values, score_director); + return RuinUndo::new(); + }; + let unit = units[unit_index].clone(); + score_director.before_variable_changed(descriptor_index, entity); + for (removed_index, &position) in unit.clone().zip(positions.iter()) { + access.list_insert( + score_director.working_solution_mut(), + entity, + position, + values[removed_index] + .take() + .expect("the winning unit's members are held"), + ); + placements.push((entity, position, removed_index)); + } + score_director.after_variable_changed(descriptor_index, entity); + placed[unit_index] = true; + } + placements +} + +/// Inserts `members` at `positions` of `entity`, scores, and takes them back. +fn score_joint_trial( + access: &A, + members: &mut SmallVec<[A::Element; 4]>, + entity: usize, + positions: &[usize], + score_director: &mut D, +) -> S::Score +where + S: PlanningSolution, + A: ListRuinAccess, + D: Director, +{ + let descriptor_index = access.descriptor_index(); + score_director.before_variable_changed(descriptor_index, entity); + for (member, &position) in std::mem::take(members).into_iter().zip(positions) { + access.list_insert( + score_director.working_solution_mut(), + entity, + position, + member, + ); + } + score_director.after_variable_changed(descriptor_index, entity); + let score = score_director.calculate_score(); + score_director.before_variable_changed(descriptor_index, entity); + for &position in positions.iter().rev() { + members.push(access.list_remove(score_director.working_solution_mut(), entity, position)); + } + members.reverse(); + score_director.after_variable_changed(descriptor_index, entity); + score +} + +/// Takes back the placements already made, then restores every removed +/// element to its original position. +fn restore_unplaced( + access: &A, + plan: &GroupRuinPlan, + placements: &RuinUndo, + values: &mut SmallVec<[Option; 8]>, + score_director: &mut D, +) where + S: PlanningSolution, + A: ListRuinAccess, + D: Director, +{ + take_back_placements(access, placements, values, score_director); + let restored = values + .iter_mut() + .enumerate() + .map(|(index, value)| { + let (entity, position) = plan.removed[index]; + ( + entity, + position, + value.take().expect("every removed element is held"), + ) + }) + .collect(); + restore_values(access, restored, score_director); +} + +fn take_back_placements( + access: &A, + placements: &RuinUndo, + values: &mut SmallVec<[Option; 8]>, + score_director: &mut D, +) where + S: PlanningSolution, + A: ListRuinAccess, + D: Director, +{ + let descriptor_index = access.descriptor_index(); + let mut current_positions = final_positions_after_ordered_insertions(placements); + for i in (0..placements.len()).rev() { + let (entity, _, removed_index) = placements[i]; + let actual_position = current_positions[i]; + score_director.before_variable_changed(descriptor_index, entity); + values[removed_index] = Some(access.list_remove( + score_director.working_solution_mut(), + entity, + actual_position, + )); + score_director.after_variable_changed(descriptor_index, entity); + for j in 0..i { + let (other_entity, _, _) = placements[j]; + if other_entity == entity && current_positions[j] > actual_position { + current_positions[j] -= 1; + } + } + } +} + +pub(crate) fn group_ruin_undo_move( + access: &A, + plan: &GroupRuinPlan, + placements: RuinUndo, + score_director: &mut D, +) where + S: PlanningSolution, + A: ListRuinAccess, + D: Director, +{ + let mut values: SmallVec<[Option; 8]> = + (0..plan.removed.len()).map(|_| None).collect(); + restore_unplaced(access, plan, &placements, &mut values, score_director); +} + +pub(crate) fn group_ruin_tabu_signature( + access: &A, + plan: &GroupRuinPlan, + score_director: &D, +) -> MoveTabuSignature +where + S: PlanningSolution, + A: ListMoveAccess, + D: Director, +{ + let solution = score_director.working_solution(); + let value_ids: SmallVec<[u64; 8]> = plan + .removed + .iter() + .map(|&(entity, position)| { + access.tabu_value_id( + solution, + access.list_get(solution, entity, position).as_ref(), + ) + }) + .collect(); + let scope = MoveTabuScope::new(access.descriptor_index(), access.variable_name()); + let mut move_id: SmallVec<[u64; 8]> = smallvec![ + encode_usize(access.descriptor_index()), + hash_str(access.variable_name()), + encode_usize(plan.removed.len()) + ]; + for &(entity, position) in &plan.removed { + move_id.push(encode_usize(entity)); + move_id.push(encode_usize(position)); + } + move_id.extend(value_ids.iter().copied()); + MoveTabuSignature::from_self_undoing_identity(scope, move_id) + .with_entity_tokens( + plan.entities() + .into_iter() + .map(|entity| scope.entity_token(encode_usize(entity))), + ) + .with_destination_value_tokens(value_ids.iter().map(|&id| scope.value_token(id))) +} + +pub(crate) fn group_ruin_candidate_trace_identity( + access: &A, + plan: &GroupRuinPlan, +) -> CandidateTraceIdentity +where + A: ListMoveAccess, +{ + CandidateTraceIdentity::logical_move( + access.descriptor_index(), + access.variable_name(), + "list_group_ruin", + plan.removed + .iter() + .flat_map(|&(entity, position)| [entity, position]), + ) +} diff --git a/crates/solverforge-solver/src/heuristic/move/list_kernel/mod.rs b/crates/solverforge-solver/src/heuristic/move/list_kernel/mod.rs index d558d3c0..b9c83310 100644 --- a/crates/solverforge-solver/src/heuristic/move/list_kernel/mod.rs +++ b/crates/solverforge-solver/src/heuristic/move/list_kernel/mod.rs @@ -6,6 +6,8 @@ mod access; mod change; +mod group; +mod group_ruin; mod k_opt; mod multi_swap; mod permute; @@ -26,6 +28,16 @@ pub(crate) use change::{ change_candidate_trace_identity, change_do_move, change_is_doable, change_tabu_signature, change_undo_move, ChangeCoordinates, }; +pub(crate) use group::{ + group_change_candidate_trace_identity, group_change_do_move, group_change_is_doable, + group_change_tabu_signature, group_change_undo_move, group_swap_candidate_trace_identity, + group_swap_do_move, group_swap_is_doable, group_swap_tabu_signature, group_swap_undo_move, + GroupChangeCoordinates, GroupSwapCoordinates, MemberCoordinates, +}; +pub(crate) use group_ruin::{ + group_ruin_candidate_trace_identity, group_ruin_do_move, group_ruin_is_doable, + group_ruin_tabu_signature, group_ruin_undo_move, GroupRuinPlan, +}; pub(crate) use k_opt::{ k_opt_do_move, k_opt_do_move_into, k_opt_is_doable, k_opt_tabu_signature, k_opt_undo_move, }; diff --git a/crates/solverforge-solver/src/heuristic/move/list_kernel/ruin.rs b/crates/solverforge-solver/src/heuristic/move/list_kernel/ruin.rs index 78e9e31e..5ef76bf6 100644 --- a/crates/solverforge-solver/src/heuristic/move/list_kernel/ruin.rs +++ b/crates/solverforge-solver/src/heuristic/move/list_kernel/ruin.rs @@ -68,7 +68,9 @@ pub(crate) fn final_positions_after_insertions( current_positions } -fn final_positions_after_ordered_insertions(placements: &RuinUndo) -> SmallVec<[usize; 8]> { +pub(super) fn final_positions_after_ordered_insertions( + placements: &RuinUndo, +) -> SmallVec<[usize; 8]> { let mut current_positions = SmallVec::with_capacity(placements.len()); for i in 0..placements.len() { let (entity, insert_position, _) = placements[i]; @@ -419,7 +421,7 @@ fn restore_remaining_elements( restore_values(access, values, score_director); } -fn restore_values( +pub(super) fn restore_values( access: &A, mut values: SmallVec<[(usize, usize, A::Element); 8]>, score_director: &mut D, diff --git a/crates/solverforge-solver/src/heuristic/selector/list_kernel/group.rs b/crates/solverforge-solver/src/heuristic/selector/list_kernel/group.rs new file mode 100644 index 00000000..02500416 --- /dev/null +++ b/crates/solverforge-solver/src/heuristic/selector/list_kernel/group.rs @@ -0,0 +1,377 @@ +//! Streamed group change and group swap cursors. +//! +//! Both cursors read one frozen per-step snapshot of the assigned groups: +//! each group's member coordinates in declared order and the owners every +//! member allows. They choose coordinates only; emitters build the moves. + +use std::fmt::Debug; + +use smallvec::SmallVec; +use solverforge_core::domain::PlanningSolution; + +use crate::heuristic::r#move::list_kernel::{ + GroupChangeCoordinates, GroupSwapCoordinates, MemberCoordinates, +}; +use crate::heuristic::r#move::Move; +use crate::heuristic::selector::list_support::ordered_index; +use crate::heuristic::selector::move_selector::{ + CandidateId, CandidateStore, MoveCandidateRef, MoveCursor, MoveStreamContext, +}; +use crate::list_groups::JointPositions; +use crate::list_placement::OwnerRestriction; + +const GROUP_SALT: u64 = 0x6A0F_C4A4_6E00_0001; +const DESTINATION_SALT: u64 = 0x6A0F_C4A4_6E00_0002; +const PLACEMENT_SALT: u64 = 0x6A0F_C4A4_6E00_0003; +const PARTNER_SALT: u64 = 0x6A0F_C4A4_6E00_0004; +const MIX: u64 = 0x9E37_79B9_7F4A_7C15; + +/// Emits one group change for already-approved coordinates. +pub(crate) trait GroupChangeEmitter: Send + Sync + Debug { + type Move: Move; + + fn emit_group_change(&self, coordinates: GroupChangeCoordinates) -> Self::Move; +} + +/// Emits one group swap for already-approved coordinates. +pub(crate) trait GroupSwapEmitter: Send + Sync + Debug { + type Move: Move; + + fn emit_group_swap(&self, coordinates: GroupSwapCoordinates) -> Self::Move; +} + +/// One fully assigned group as the group cursors see it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) struct GroupSnapshot { + /// `(entity, position)` of every member, in declared order. + pub(crate) members: MemberCoordinates, + /// The owners every member allows. + pub(crate) restriction: OwnerRestriction, +} + +impl GroupSnapshot { + /// The one owner holding every member, if there is one. + fn owner(&self) -> Option { + let (owner, _) = *self.members.first()?; + self.members + .iter() + .all(|&(entity, _)| entity == owner) + .then_some(owner) + } + + fn positions(&self) -> JointPositions { + self.members.iter().map(|&(_, position)| position).collect() + } +} + +/// Joint placements of `member_count` members into a list of `list_len` +/// other elements, chosen level by level: the first member's position, then +/// each gap to the next member. Canonical order is lexicographic; random +/// orders permute every level, keyed by the choices before it. +#[derive(Debug)] +struct PlacementStream { + member_count: usize, + list_len: usize, + max_gap: usize, + salt: u64, + offsets: SmallVec<[usize; 4]>, + values: SmallVec<[usize; 4]>, + started: bool, +} + +impl PlacementStream { + fn new(member_count: usize, list_len: usize, max_gap: Option, salt: u64) -> Self { + Self { + member_count, + list_len, + max_gap: max_gap.unwrap_or(usize::MAX), + salt, + offsets: SmallVec::from_elem(0, member_count), + values: SmallVec::from_elem(0, member_count), + started: false, + } + } + + fn range(&self, level: usize) -> usize { + if level == 0 { + return self.list_len + 1; + } + let used: usize = self.values[..level].iter().sum(); + self.max_gap.min(self.list_len - used) + 1 + } + + fn value_at(&self, level: usize, offset: usize, context: MoveStreamContext) -> usize { + let prefix = self.values[..level] + .iter() + .fold(self.salt ^ level as u64, |salt, &value| { + (salt ^ value as u64).wrapping_mul(MIX) + }); + ordered_index(offset, self.range(level), context, prefix) + } + + fn fill_from(&mut self, level: usize, context: MoveStreamContext) { + for deeper in level..self.member_count { + self.offsets[deeper] = 0; + self.values[deeper] = self.value_at(deeper, 0, context); + } + } + + fn positions(&self) -> JointPositions { + let mut positions = JointPositions::with_capacity(self.member_count); + let mut position = self.values[0]; + positions.push(position); + for &gap in &self.values[1..] { + position += gap + 1; + positions.push(position); + } + positions + } + + fn next(&mut self, context: MoveStreamContext) -> Option { + if self.member_count == 0 { + return None; + } + if !self.started { + self.started = true; + self.fill_from(0, context); + return Some(self.positions()); + } + let mut level = self.member_count; + while level > 0 { + level -= 1; + if self.offsets[level] + 1 < self.range(level) { + self.offsets[level] += 1; + self.values[level] = self.value_at(level, self.offsets[level], context); + self.fill_from(level + 1, context); + return Some(self.positions()); + } + } + None + } +} + +/// Streams every bounded joint relocation of every assigned group. +pub(crate) struct GroupChangeCursor +where + S: PlanningSolution, + E: GroupChangeEmitter, +{ + store: CandidateStore, + emitter: E, + groups: Vec, + entity_lens: Vec, + context: MoveStreamContext, + max_member_gap: Option, + salt: u64, + group_offset: usize, + destination_offset: usize, + current: Option<(usize, usize, PlacementStream)>, +} + +impl GroupChangeCursor +where + S: PlanningSolution, + E: GroupChangeEmitter, +{ + pub(crate) fn new( + emitter: E, + groups: Vec, + entity_lens: Vec, + context: MoveStreamContext, + max_member_gap: Option, + descriptor_index: usize, + ) -> Self { + Self { + store: CandidateStore::new(), + emitter, + groups, + entity_lens, + context, + max_member_gap, + salt: GROUP_SALT ^ descriptor_index as u64, + group_offset: 0, + destination_offset: 0, + current: None, + } + } + + fn next_move(&mut self) -> Option { + loop { + if let Some((group, destination, stream)) = &mut self.current { + let snapshot = &self.groups[*group]; + while let Some(positions) = stream.next(self.context) { + let identity = snapshot.members.iter().zip(&positions).all( + |(&(entity, position), &target)| { + entity == *destination && position == target + }, + ); + if identity { + continue; + } + return Some(self.emitter.emit_group_change(GroupChangeCoordinates { + sources: snapshot.members.clone(), + destination_entity: *destination, + destination_positions: positions, + })); + } + self.current = None; + self.destination_offset += 1; + } + if self.group_offset >= self.groups.len() { + return None; + } + if self.destination_offset >= self.entity_lens.len() { + self.group_offset += 1; + self.destination_offset = 0; + continue; + } + let group = ordered_index( + self.group_offset, + self.groups.len(), + self.context, + self.salt, + ); + let destination = ordered_index( + self.destination_offset, + self.entity_lens.len(), + self.context, + (self.salt ^ DESTINATION_SALT ^ group as u64).wrapping_mul(MIX), + ); + let snapshot = &self.groups[group]; + if !snapshot.restriction.allows(destination) { + self.destination_offset += 1; + continue; + } + let staying = snapshot + .members + .iter() + .filter(|&&(entity, _)| entity == destination) + .count(); + let stream = PlacementStream::new( + snapshot.members.len(), + self.entity_lens[destination] - staying, + self.max_member_gap, + (self.salt ^ PLACEMENT_SALT ^ group as u64) + .wrapping_mul(MIX) + .wrapping_add(destination as u64), + ); + self.current = Some((group, destination, stream)); + } + } +} + +/// Streams every exchange of two equally sized groups on different owners. +pub(crate) struct GroupSwapCursor +where + S: PlanningSolution, + E: GroupSwapEmitter, +{ + store: CandidateStore, + emitter: E, + groups: Vec, + owners: Vec>, + context: MoveStreamContext, + salt: u64, + first_offset: usize, + second_offset: usize, +} + +impl GroupSwapCursor +where + S: PlanningSolution, + E: GroupSwapEmitter, +{ + pub(crate) fn new( + emitter: E, + groups: Vec, + context: MoveStreamContext, + descriptor_index: usize, + ) -> Self { + let owners = groups.iter().map(GroupSnapshot::owner).collect(); + Self { + store: CandidateStore::new(), + emitter, + groups, + owners, + context, + salt: GROUP_SALT ^ PARTNER_SALT ^ descriptor_index as u64, + first_offset: 0, + second_offset: 0, + } + } + + fn next_move(&mut self) -> Option { + let count = self.groups.len(); + while self.first_offset < count { + let first = ordered_index(self.first_offset, count, self.context, self.salt); + while self.second_offset < count { + let second = ordered_index( + self.second_offset, + count, + self.context, + (self.salt ^ first as u64).wrapping_mul(MIX), + ); + self.second_offset += 1; + // Each unordered pair once, from its lower group index. + if second <= first { + continue; + } + let (Some(first_owner), Some(second_owner)) = + (self.owners[first], self.owners[second]) + else { + continue; + }; + let (first_group, second_group) = (&self.groups[first], &self.groups[second]); + if first_owner == second_owner + || first_group.members.len() != second_group.members.len() + || !first_group.restriction.allows(second_owner) + || !second_group.restriction.allows(first_owner) + { + continue; + } + return Some(self.emitter.emit_group_swap(GroupSwapCoordinates { + first_entity: first_owner, + first_positions: first_group.positions(), + second_entity: second_owner, + second_positions: second_group.positions(), + })); + } + self.first_offset += 1; + self.second_offset = 0; + } + None + } +} + +macro_rules! group_move_cursor { + ($cursor:ident, $emitter:ident) => { + impl MoveCursor for $cursor + where + S: PlanningSolution, + E: $emitter, + { + fn next_candidate(&mut self, _solution: &S) -> Option { + self.next_move().map(|mov| self.store.push(mov)) + } + + fn candidate(&self, id: CandidateId) -> Option> { + self.store.candidate(id) + } + + fn take_candidate(&mut self, id: CandidateId) -> E::Move { + self.store.take_candidate(id) + } + + fn next_owned_candidate(&mut self, _solution: &S) -> Option { + self.next_move() + } + + fn release_candidate(&mut self, id: CandidateId) -> bool { + self.store.release_candidate(id) + } + } + }; +} + +group_move_cursor!(GroupChangeCursor, GroupChangeEmitter); +group_move_cursor!(GroupSwapCursor, GroupSwapEmitter); diff --git a/crates/solverforge-solver/src/heuristic/selector/list_kernel/mod.rs b/crates/solverforge-solver/src/heuristic/selector/list_kernel/mod.rs index d5040d90..23c2cce0 100644 --- a/crates/solverforge-solver/src/heuristic/selector/list_kernel/mod.rs +++ b/crates/solverforge-solver/src/heuristic/selector/list_kernel/mod.rs @@ -8,6 +8,7 @@ mod change; #[cfg(test)] mod dynamic_change_emission; mod emission; +mod group; mod k_opt; #[cfg(test)] mod native_ruin_emission; @@ -31,6 +32,9 @@ pub(crate) use dynamic_change_emission::DynamicChangeEmitter; pub(crate) use emission::{ChangeEmitter, SwapEmitter}; #[cfg(test)] pub(crate) use emission::{NativeChangeEmitter, NativeSwapEmitter}; +pub(crate) use group::{ + GroupChangeCursor, GroupChangeEmitter, GroupSnapshot, GroupSwapCursor, GroupSwapEmitter, +}; #[cfg(test)] pub(crate) use k_opt::NativeKOptEmitter; pub(crate) use k_opt::{KOptCursor, KOptDistanceProbe, KOptEmitter, NearbyKOptCursor}; diff --git a/crates/solverforge-solver/src/lib.rs b/crates/solverforge-solver/src/lib.rs index b8a7d312..d983bd49 100644 --- a/crates/solverforge-solver/src/lib.rs +++ b/crates/solverforge-solver/src/lib.rs @@ -24,6 +24,7 @@ mod builder; mod constraint_weights; mod descriptor; mod heuristic; +mod list_groups; mod list_placement; mod manager; mod model_support; diff --git a/crates/solverforge-solver/src/list_groups.rs b/crates/solverforge-solver/src/list_groups.rs new file mode 100644 index 00000000..62631642 --- /dev/null +++ b/crates/solverforge-solver/src/list_groups.rs @@ -0,0 +1,17 @@ +//! Element groups of list variables: members that share one owner and move +//! together, placed jointly by group moves, ruin and recreate, and scored +//! list construction. + +mod index; +mod joint; + +#[cfg(test)] +mod tests; + +pub(crate) use index::{ListElementGroups, ListGroupPlacement}; +#[cfg(test)] +pub(crate) use joint::JointPlacements; +pub(crate) use joint::{ + member_gap, search_joint_placement, JointBounds, JointChoice, JointPositions, JointSearch, + DEFAULT_GROUP_MEMBER_DISTANCE, DEFAULT_GROUP_OWNERS, +}; diff --git a/crates/solverforge-solver/src/list_groups/index.rs b/crates/solverforge-solver/src/list_groups/index.rs new file mode 100644 index 00000000..13cda644 --- /dev/null +++ b/crates/solverforge-solver/src/list_groups/index.rs @@ -0,0 +1,171 @@ +//! Declared element groups of one list variable, keyed by element source key. + +use std::collections::HashMap; + +/// The groups a list variable's `element_group_fn` declares. +/// +/// Only groups of two or more members are kept: an element whose hook +/// answer is empty, or only the element itself, moves alone exactly as +/// without groups. Members keep the hook's order. +#[derive(Debug, Default)] +pub(crate) struct ListElementGroups { + group_by_key: HashMap, + member_offsets: Vec, + member_keys: Vec, +} + +impl ListElementGroups { + /// Reads every element's group through `members_of`. + /// + /// `element_at` yields the element of a source index, `key_of` its source + /// key, and `members_of` appends the members of its group. Panics when + /// two elements disagree about a group, because moves keyed on one + /// answer would then split or duplicate members of the other. + pub(crate) fn from_hook( + element_count: usize, + mut element_at: impl FnMut(usize) -> Option, + mut key_of: impl FnMut(&E) -> usize, + mut members_of: impl FnMut(&E, &mut Vec), + ) -> Self { + let mut groups = Self::default(); + let mut scratch = Vec::new(); + let mut keys = Vec::new(); + for index in 0..element_count { + let Some(element) = element_at(index) else { + continue; + }; + let key = key_of(&element); + scratch.clear(); + members_of(&element, &mut scratch); + keys.clear(); + keys.extend(scratch.iter().map(&mut key_of)); + if let Some(&group) = groups.group_by_key.get(&key) { + assert!( + keys.as_slice() == groups.members(group), + "element group of element {key} lists members {keys:?}, but another member \ + declared {:?}", + groups.members(group) + ); + continue; + } + if keys.len() < 2 { + assert!( + keys.is_empty() || keys[0] == key, + "element {key} declares a one-member group of element {}", + keys[0] + ); + continue; + } + assert!( + keys.contains(&key), + "element group of element {key} does not contain it: {keys:?}" + ); + let group = groups.member_offsets.len().saturating_sub(1); + if groups.member_offsets.is_empty() { + groups.member_offsets.push(0); + } + for (position, &member) in keys.iter().enumerate() { + assert!( + !keys[..position].contains(&member), + "element group of element {key} lists member {member} twice" + ); + let previous = groups.group_by_key.insert(member, group); + assert!( + previous.is_none(), + "element {member} belongs to two element groups" + ); + } + groups.member_keys.extend_from_slice(&keys); + groups.member_offsets.push(groups.member_keys.len()); + } + groups + } + + /// Whether no group has two or more members. + pub(crate) fn is_empty(&self) -> bool { + self.member_keys.is_empty() + } + + /// Number of groups. + pub(crate) fn group_count(&self) -> usize { + self.member_offsets.len().saturating_sub(1) + } + + /// The group holding the element with this source key. + pub(crate) fn group_of_key(&self, key: usize) -> Option { + self.group_by_key.get(&key).copied() + } + + /// The source keys of a group's members, in declared order. + pub(crate) fn members(&self, group: usize) -> &[usize] { + &self.member_keys[self.member_offsets[group]..self.member_offsets[group + 1]] + } + + /// Offset of a group's first member in the flat member order. + pub(crate) fn member_offset(&self, group: usize) -> usize { + self.member_offsets[group] + } + + /// Total number of grouped elements. + pub(crate) fn member_count(&self) -> usize { + self.member_keys.len() + } +} + +/// Where every grouped element sits in the current solution. +/// +/// Built once per cursor or phase from a [`ListElementGroups`]; slot `i` +/// holds the `(entity, position)` of the `i`-th member in the groups' flat +/// member order, or `None` while that member is unassigned. +#[derive(Debug, Default)] +pub(crate) struct ListGroupPlacement { + member_positions: Vec>, +} + +impl ListGroupPlacement { + /// Scans every list once, through `key_at`, to locate each member. + pub(crate) fn locate( + groups: &ListElementGroups, + entity_count: usize, + mut list_len: impl FnMut(usize) -> usize, + mut key_at: impl FnMut(usize, usize) -> Option, + ) -> Self { + let mut member_positions = vec![None; groups.member_count()]; + for entity in 0..entity_count { + for position in 0..list_len(entity) { + let Some(key) = key_at(entity, position) else { + continue; + }; + let Some(group) = groups.group_of_key(key) else { + continue; + }; + let offset = groups.member_offset(group); + let member = groups + .members(group) + .iter() + .position(|&member| member == key) + .expect("a grouped key is one of its group's members"); + member_positions[offset + member] = Some((entity, position)); + } + } + Self { member_positions } + } + + /// The `(entity, position)` of a group's `member`-th member. + pub(crate) fn member_position( + &self, + groups: &ListElementGroups, + group: usize, + member: usize, + ) -> Option<(usize, usize)> { + self.member_positions[groups.member_offset(group) + member] + } + + /// Whether every member of a group is assigned. + pub(crate) fn group_is_assigned(&self, groups: &ListElementGroups, group: usize) -> bool { + let offset = groups.member_offset(group); + self.member_positions[offset..offset + groups.members(group).len()] + .iter() + .all(Option::is_some) + } +} diff --git a/crates/solverforge-solver/src/list_groups/joint.rs b/crates/solverforge-solver/src/list_groups/joint.rs new file mode 100644 index 00000000..273b8c54 --- /dev/null +++ b/crates/solverforge-solver/src/list_groups/joint.rs @@ -0,0 +1,246 @@ +//! Joint placement of a group's members into one list. +//! +//! A placement is the members' final positions in the destination list, +//! strictly increasing in declared order: inserting the members in that +//! order at those positions produces exactly that list. Other elements may +//! sit between members. + +use std::num::NonZeroU8; + +use smallvec::SmallVec; + +/// Final positions of a group's members in one destination list. +pub(crate) type JointPositions = SmallVec<[usize; 4]>; + +/// Member distance of the default grouped ruin and recreate. +pub(crate) const DEFAULT_GROUP_MEMBER_DISTANCE: NonZeroU8 = NonZeroU8::new(7).unwrap(); +/// Owner shortlist of the default grouped ruin and recreate, and of the +/// default construction of a list with element groups. +pub(crate) const DEFAULT_GROUP_OWNERS: NonZeroU8 = NonZeroU8::new(4).unwrap(); + +/// Bounds on the joint placements tried for one group. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +/// +/// Stored as the configured bytes, so specs and plans holding it keep their +/// size. +pub(crate) struct JointBounds { + /// Most positions from one member to the next; `None` tries every + /// placement. + max_member_distance: Option, + /// Most destination owners tried with every placement. When it is + /// smaller than the candidate owners, each owner first gets the group + /// placed contiguously at every position, and only the owners with the + /// best contiguous score go on to the full search. + max_owners: Option, +} + +impl JointBounds { + /// Bounds from the configured member distance and owner shortlist. + pub(crate) fn from_config( + max_member_distance: Option, + max_group_owners: Option, + ) -> Self { + Self { + max_member_distance, + max_owners: max_group_owners, + } + } + + /// Most other elements between two consecutive members. + pub(crate) fn max_member_gap(self) -> Option { + self.max_member_distance.map(member_gap) + } + + /// Most owners tried with every placement. + pub(crate) fn max_owners(self) -> Option { + self.max_owners.map(|owners| usize::from(owners.get())) + } +} + +/// The other elements allowed between two members `distance` positions apart. +pub(crate) fn member_gap(distance: NonZeroU8) -> usize { + usize::from(distance.get()) - 1 +} + +/// Every joint placement of `member_count` members into a list holding +/// `list_len` other elements, in lexicographic order of positions. +#[derive(Debug)] +pub(crate) struct JointPlacements { + list_len: usize, + max_gap: usize, + positions: JointPositions, + started: bool, +} + +impl JointPlacements { + pub(crate) fn new(member_count: usize, list_len: usize, max_member_gap: Option) -> Self { + Self { + list_len, + max_gap: max_member_gap.unwrap_or(usize::MAX), + positions: (0..member_count).collect(), + started: false, + } + } + + /// The next placement, or `None` once every placement was yielded. + #[allow(clippy::should_implement_trait)] + pub(crate) fn next(&mut self) -> Option<&[usize]> { + let count = self.positions.len(); + if count == 0 { + return None; + } + if !self.started { + self.started = true; + return Some(&self.positions); + } + // The last member may sit at most `list_len + i` for member `i`. + let mut index = count; + while index > 0 { + index -= 1; + let raised = self.positions[index] + 1; + let within_list = raised <= self.list_len + index; + let within_gap = index == 0 || raised - self.positions[index - 1] - 1 <= self.max_gap; + if within_list && within_gap { + self.positions[index] = raised; + for later in index + 1..count { + self.positions[later] = self.positions[later - 1] + 1; + } + return Some(&self.positions); + } + } + None + } + + /// Whether a placement keeps every member next to the previous one. + pub(crate) fn is_contiguous(positions: &[usize]) -> bool { + positions.windows(2).all(|pair| pair[1] == pair[0] + 1) + } +} + +/// The best placement found for a group. +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) struct JointChoice { + pub(crate) entity: usize, + pub(crate) positions: JointPositions, + pub(crate) score: Sc, +} + +/// Outcome of a joint placement search. +#[derive(Debug, PartialEq, Eq)] +pub(crate) enum JointSearch { + /// `eval` asked to stop. + Interrupted, + /// Every bounded placement was scored: the best one, and the best score + /// of every other placement (for regret). + Done { + best: Option>, + second: Option, + }, +} + +struct Tracker { + best: Option>, + second: Option, +} + +impl Tracker { + fn record(&mut self, entity: usize, positions: &[usize], score: Sc) { + match &self.best { + Some(best) if score <= best.score => { + if self.second.is_none_or(|second| score > second) { + self.second = Some(score); + } + } + _ => { + if let Some(previous) = self.best.take() { + self.second = Some(previous.score); + } + self.best = Some(JointChoice { + entity, + positions: SmallVec::from_slice(positions), + score, + }); + } + } + } +} + +/// Scores the bounded joint placements of a `member_count`-member group on +/// `owners`, best first by score; ties keep the earliest placement. +/// +/// `eval(entity, positions)` scores one placement, or returns `None` to stop +/// the search. +pub(crate) fn search_joint_placement( + owners: &[usize], + member_count: usize, + mut list_len: impl FnMut(usize) -> usize, + bounds: JointBounds, + mut eval: impl FnMut(usize, &[usize]) -> Option, +) -> JointSearch { + let mut tracker = Tracker { + best: None, + second: None, + }; + let shortlist = bounds + .max_owners() + .filter(|&max_owners| member_count > 1 && max_owners < owners.len()); + let Some(max_owners) = shortlist else { + for &entity in owners { + let mut placements = + JointPlacements::new(member_count, list_len(entity), bounds.max_member_gap()); + while let Some(positions) = placements.next() { + let Some(score) = eval(entity, positions) else { + return JointSearch::Interrupted; + }; + tracker.record(entity, positions, score); + } + } + return JointSearch::Done { + best: tracker.best, + second: tracker.second, + }; + }; + + // Contiguous placements rank the owners. + let mut ranked: SmallVec<[(Sc, usize); 16]> = SmallVec::new(); + let mut positions = JointPositions::new(); + for (rank, &entity) in owners.iter().enumerate() { + let len = list_len(entity); + let mut owner_best = None; + for start in 0..=len { + positions.clear(); + positions.extend(start..start + member_count); + let Some(score) = eval(entity, &positions) else { + return JointSearch::Interrupted; + }; + tracker.record(entity, &positions, score); + if owner_best.is_none_or(|best| score > best) { + owner_best = Some(score); + } + } + if let Some(score) = owner_best { + ranked.push((score, rank)); + } + } + ranked.sort_by(|left, right| right.0.cmp(&left.0).then(left.1.cmp(&right.1))); + ranked.truncate(max_owners); + ranked.sort_by_key(|&(_, rank)| rank); + for (_, rank) in ranked { + let entity = owners[rank]; + let mut placements = + JointPlacements::new(member_count, list_len(entity), bounds.max_member_gap()); + while let Some(positions) = placements.next() { + if JointPlacements::is_contiguous(positions) { + continue; + } + let Some(score) = eval(entity, positions) else { + return JointSearch::Interrupted; + }; + tracker.record(entity, positions, score); + } + } + JointSearch::Done { + best: tracker.best, + second: tracker.second, + } +} diff --git a/crates/solverforge-solver/src/list_groups/tests.rs b/crates/solverforge-solver/src/list_groups/tests.rs new file mode 100644 index 00000000..b13a308f --- /dev/null +++ b/crates/solverforge-solver/src/list_groups/tests.rs @@ -0,0 +1,146 @@ +//! Group index and joint placement coverage. + +use super::*; + +fn placements(member_count: usize, list_len: usize, gap: Option) -> Vec> { + let mut all = Vec::new(); + let mut placements = JointPlacements::new(member_count, list_len, gap); + while let Some(positions) = placements.next() { + all.push(positions.to_vec()); + } + all +} + +#[test] +fn unbounded_pairs_cover_every_increasing_position_pair() { + let all = placements(2, 3, None); + assert_eq!(all.len(), 10); + assert_eq!(all.first(), Some(&vec![0, 1])); + assert_eq!(all.last(), Some(&vec![3, 4])); + assert!(all.iter().all(|pair| pair[0] < pair[1] && pair[1] <= 4)); +} + +#[test] +fn member_gap_bounds_the_elements_between_members() { + assert_eq!( + placements(2, 3, Some(0)), + vec![vec![0, 1], vec![1, 2], vec![2, 3], vec![3, 4]] + ); + assert_eq!(placements(2, 3, Some(1)).len(), 7); + let triples = placements(3, 2, Some(1)); + assert!(triples + .iter() + .all(|triple| triple[1] - triple[0] <= 2 && triple[2] - triple[1] <= 2)); + assert_eq!(triples.len(), 8); +} + +#[test] +fn a_single_member_tries_every_position() { + assert_eq!(placements(1, 2, Some(0)), vec![vec![0], vec![1], vec![2]]); +} + +fn route_score(entity: usize, positions: &[usize]) -> i64 { + // Owner 2 is best, and members far apart score better. + let spread = positions.last().unwrap() - positions[0]; + (entity as i64) * 100 + spread as i64 - positions[0] as i64 +} + +#[test] +fn search_finds_the_best_placement_and_the_runner_up() { + let JointSearch::Done { best, second } = search_joint_placement( + &[0, 1, 2], + 2, + |_| 3, + JointBounds::default(), + |entity, positions| Some(route_score(entity, positions)), + ) else { + panic!("search was not interrupted"); + }; + let best = best.expect("a placement exists"); + assert_eq!((best.entity, best.positions.to_vec()), (2, vec![0, 4])); + assert_eq!(best.score, 204); + assert_eq!(second, Some(203)); +} + +#[test] +fn the_owner_shortlist_searches_only_the_best_contiguous_owners() { + let mut evaluated = Vec::new(); + let bounds = JointBounds::from_config(None, std::num::NonZeroU8::new(1)); + let JointSearch::Done { best, .. } = search_joint_placement( + &[0, 1, 2], + 2, + |_| 3, + bounds, + |entity, positions| { + evaluated.push((entity, positions.to_vec())); + Some(route_score(entity, positions)) + }, + ) else { + panic!("search was not interrupted"); + }; + assert_eq!(best.expect("a placement exists").entity, 2); + // Four contiguous placements per owner, then owner 2's six others. + assert_eq!(evaluated.len(), 3 * 4 + 6); + assert!(evaluated[12..].iter().all(|(entity, _)| *entity == 2)); +} + +#[test] +fn search_stops_when_eval_does() { + let mut calls = 0; + let outcome = search_joint_placement( + &[0], + 2, + |_| 3, + JointBounds::default(), + |_, _| { + calls += 1; + (calls < 3).then_some(0) + }, + ); + assert_eq!(outcome, JointSearch::::Interrupted); + assert_eq!(calls, 3); +} + +fn pairs(element: &usize, members: &mut Vec) { + // Elements 0..4 pair up as (0, 1) and (2, 3); 4 is alone. + if *element < 4 { + let first = element - element % 2; + members.extend([first, first + 1]); + } +} + +#[test] +fn the_index_keeps_multi_member_groups_in_declared_order() { + let groups = ListElementGroups::from_hook(5, Some, |element| *element, pairs); + assert_eq!(groups.group_count(), 2); + assert_eq!(groups.members(0), &[0, 1]); + assert_eq!(groups.members(1), &[2, 3]); + assert_eq!(groups.group_of_key(3), Some(1)); + assert_eq!(groups.group_of_key(4), None); + + let routes = [vec![0, 4, 1], vec![2], vec![]]; + let placement = ListGroupPlacement::locate( + &groups, + routes.len(), + |entity| routes[entity].len(), + |entity, position| routes[entity].get(position).copied(), + ); + assert_eq!(placement.member_position(&groups, 0, 1), Some((0, 2))); + assert!(placement.group_is_assigned(&groups, 0)); + assert!(!placement.group_is_assigned(&groups, 1)); +} + +#[test] +#[should_panic(expected = "another member declared")] +fn members_that_disagree_about_their_group_are_rejected() { + ListElementGroups::from_hook( + 3, + Some, + |element| *element, + |element: &usize, members: &mut Vec| match element { + 0 => members.extend([0, 1]), + 1 => members.extend([1, 2]), + _ => {} + }, + ); +} diff --git a/crates/solverforge-solver/src/manager/mod.rs b/crates/solverforge-solver/src/manager/mod.rs index 216752bb..6b719b37 100644 --- a/crates/solverforge-solver/src/manager/mod.rs +++ b/crates/solverforge-solver/src/manager/mod.rs @@ -14,8 +14,9 @@ pub(crate) mod solver_manager; mod mod_tests_integration; pub(crate) use phase_factory::{ - run_cheapest, run_clarke_wright, run_list_k_opt, run_regret, run_round_robin, - PhaseCheapestInsertionObserver, ScoredListConstructionAccess, + run_cheapest, run_cheapest_grouped, run_clarke_wright, run_list_k_opt, run_regret, + run_regret_grouped, run_round_robin, PhaseCheapestInsertionObserver, + ScoredListConstructionAccess, }; #[cfg(test)] pub(crate) use phase_factory::{CheapestInsertionObserver, CheapestInsertionTrial}; diff --git a/crates/solverforge-solver/src/manager/phase_factory/list_construction.rs b/crates/solverforge-solver/src/manager/phase_factory/list_construction.rs index f57635b1..9e319dd3 100644 --- a/crates/solverforge-solver/src/manager/phase_factory/list_construction.rs +++ b/crates/solverforge-solver/src/manager/phase_factory/list_construction.rs @@ -2,12 +2,13 @@ mod access; pub(crate) mod cheapest; +mod groups; pub(crate) mod regret; pub(crate) mod round_robin; pub(crate) use access::ScoredListConstructionAccess; -pub(crate) use cheapest::{run_cheapest, PhaseCheapestInsertionObserver}; +pub(crate) use cheapest::{run_cheapest, run_cheapest_grouped, PhaseCheapestInsertionObserver}; #[cfg(test)] pub(crate) use cheapest::{CheapestInsertionObserver, CheapestInsertionTrial}; -pub(crate) use regret::run_regret; +pub(crate) use regret::{run_regret, run_regret_grouped}; pub(crate) use round_robin::run_round_robin; diff --git a/crates/solverforge-solver/src/manager/phase_factory/list_construction/cheapest.rs b/crates/solverforge-solver/src/manager/phase_factory/list_construction/cheapest.rs index 595791a5..e1094731 100644 --- a/crates/solverforge-solver/src/manager/phase_factory/list_construction/cheapest.rs +++ b/crates/solverforge-solver/src/manager/phase_factory/list_construction/cheapest.rs @@ -2,11 +2,13 @@ #[cfg(test)] mod facade; +mod grouped; mod kernel; mod live; #[cfg(test)] pub(crate) use facade::ListCheapestInsertionPhase; +pub(crate) use grouped::run_cheapest_grouped; pub(crate) use kernel::run_cheapest; #[cfg(test)] pub(crate) use kernel::{CheapestInsertionObserver, CheapestInsertionTrial}; diff --git a/crates/solverforge-solver/src/manager/phase_factory/list_construction/cheapest/grouped.rs b/crates/solverforge-solver/src/manager/phase_factory/list_construction/cheapest/grouped.rs new file mode 100644 index 00000000..d662fea6 --- /dev/null +++ b/crates/solverforge-solver/src/manager/phase_factory/list_construction/cheapest/grouped.rs @@ -0,0 +1,125 @@ +//! Cheapest insertion of a list with element groups. +//! +//! Units go in construction order; each unit takes its best bounded joint +//! placement over every owner it allows, so a group's members are always +//! placed together. + +use solverforge_core::domain::PlanningSolution; +use solverforge_scoring::Director; + +use super::super::groups::{ + commit_group, construction_units, evaluate_group_trial, keep_best_token, unit_owners, +}; +use super::super::ScoredListConstructionAccess; +use crate::builder::context::{RuntimeListSourceIndex, SourceElement}; +use crate::list_groups::{ + search_joint_placement, JointBounds, JointSearch, ListElementGroups, ListGroupPlacement, +}; +use crate::phase::construction::run_construction_phase; +use crate::scope::{ProgressCallback, SolverScope, StepControlPolicy}; +use crate::stats::{CandidateTraceDisposition, CandidateTraceSource}; + +/// Runs grouped cheapest insertion as one construction phase. +#[allow(clippy::too_many_arguments)] +pub(crate) fn run_cheapest_grouped( + access: &A, + source_index: &RuntimeListSourceIndex, + bound_unassigned: &[SourceElement], + groups: &ListElementGroups, + placement: &ListGroupPlacement, + bounds: JointBounds, + control_policy: StepControlPolicy, + solver_scope: &mut SolverScope<'_, S, D, BestCb>, +) where + S: PlanningSolution, + S::Score: Copy + Ord, + A: ScoredListConstructionAccess, + D: Director, + BestCb: ProgressCallback, +{ + run_construction_phase( + solver_scope, + 0, + "Cheapest-Insertion Construction", + |phase_scope| { + let solution = phase_scope.score_director().working_solution(); + let mut ordered = bound_unassigned.to_vec(); + ordered.sort_by_key(|entry| { + ( + access.construction_order_key(solution, &entry.element), + entry.source_index, + ) + }); + let units = + construction_units(access, solution, source_index, &ordered, groups, placement); + if units.is_empty() || access.entity_count(solution) == 0 { + phase_scope.calculate_score(); + phase_scope.update_best_solution(); + return; + } + for unit in &units { + if control_policy.should_terminate_construction(phase_scope.solver_scope_mut()) { + break; + } + let (owners, lens) = unit_owners(access, unit.restriction, phase_scope); + let first_source = unit.members[0].source_index; + let mut members = unit.elements(); + let mut best_token = None; + let mut trial = 0; + let search = search_joint_placement( + &owners, + members.len(), + |entity| lens[entity], + bounds, + |entity, positions| { + if control_policy + .should_terminate_construction(phase_scope.solver_scope_mut()) + { + return None; + } + let (score, token) = evaluate_group_trial( + access, + &mut members, + first_source, + entity, + positions, + CandidateTraceSource::ListCheapestInsertionTrial, + trial, + phase_scope, + ); + trial += 1; + keep_best_token(&mut best_token, score, token, phase_scope); + Some(score) + }, + ); + let token = best_token.and_then(|(_, token)| token); + match search { + JointSearch::Done { + best: Some(choice), .. + } => commit_group( + access, + members, + choice.entity, + &choice.positions, + choice.score, + token, + control_policy, + phase_scope, + ), + JointSearch::Done { best: None, .. } => {} + JointSearch::Interrupted => { + if let Some(token) = token { + phase_scope.record_candidate_trace_disposition( + token, + CandidateTraceDisposition::ForagerIgnored, + ); + } + break; + } + } + } + phase_scope.update_best_solution(); + phase_scope.promote_current_solution_on_score_tie(); + }, + ); +} diff --git a/crates/solverforge-solver/src/manager/phase_factory/list_construction/cheapest/tests/parity.rs b/crates/solverforge-solver/src/manager/phase_factory/list_construction/cheapest/tests/parity.rs index abbc86f0..e338ee14 100644 --- a/crates/solverforge-solver/src/manager/phase_factory/list_construction/cheapest/tests/parity.rs +++ b/crates/solverforge-solver/src/manager/phase_factory/list_construction/cheapest/tests/parity.rs @@ -208,6 +208,7 @@ fn run_runtime(slot: Slot) -> (Vec>, CandidateTraceTelemetry) { &slot, &source_index, &unassigned, + crate::list_groups::JointBounds::default(), crate::scope::StepControlPolicy::ObserveConfigLimits, &mut scope, ) diff --git a/crates/solverforge-solver/src/manager/phase_factory/list_construction/groups.rs b/crates/solverforge-solver/src/manager/phase_factory/list_construction/groups.rs new file mode 100644 index 00000000..41880bab --- /dev/null +++ b/crates/solverforge-solver/src/manager/phase_factory/list_construction/groups.rs @@ -0,0 +1,272 @@ +//! Construction units of a list with element groups, and their joint trials. +//! +//! A unit is a whole group (its unassigned members, in declared order) or a +//! single ungrouped element. A unit's owner restriction combines every +//! member's restriction; members already assigned pin the unit to their +//! owner, so a partly assigned group completes on that owner. + +use std::time::Instant; + +use smallvec::SmallVec; +use solverforge_core::domain::PlanningSolution; +use solverforge_scoring::Director; + +use super::ScoredListConstructionAccess; +use crate::builder::context::{RuntimeListSourceIndex, SourceElement}; +use crate::list_groups::{ListElementGroups, ListGroupPlacement}; +use crate::list_placement::OwnerRestriction; +use crate::phase::construction::record_construction_candidate; +use crate::scope::{PhaseScope, ProgressCallback, StepControlPolicy, StepScope}; +use crate::stats::{ + CandidateTraceConstructionTarget, CandidateTraceDisposition, CandidateTracePullToken, + CandidateTraceSource, +}; + +/// Elements placed together by grouped construction. +pub(crate) struct ConstructionUnit { + /// Unassigned members in declared order. + pub(crate) members: SmallVec<[SourceElement; 4]>, + pub(crate) restriction: OwnerRestriction, +} + +impl ConstructionUnit { + pub(crate) fn elements(&self) -> SmallVec<[E; 4]> { + self.members + .iter() + .map(|member| member.element.clone()) + .collect() + } +} + +/// Splits `ordered` unassigned elements into units, each unit at the place +/// of its first member in `ordered`. +pub(crate) fn construction_units( + access: &A, + solution: &S, + source_index: &RuntimeListSourceIndex, + ordered: &[SourceElement], + groups: &ListElementGroups, + placement: &ListGroupPlacement, +) -> Vec> +where + S: PlanningSolution, + A: ScoredListConstructionAccess, +{ + let entity_count = access.entity_count(solution); + let source_count = source_index.source_count(); + let mut entry_by_source = vec![None; source_count]; + for (entry, element) in ordered.iter().enumerate() { + entry_by_source[element.source_index] = Some(entry); + } + let mut group_by_source = vec![None; source_count]; + for group in 0..groups.group_count() { + for &key in groups.members(group) { + if let Some(source) = source_index.source_index_for_key(key) { + group_by_source[source] = Some(group); + } + } + } + let mut emitted = vec![false; groups.group_count()]; + let mut units = Vec::new(); + for element in ordered { + let Some(group) = group_by_source[element.source_index] else { + units.push(ConstructionUnit { + members: SmallVec::from_elem(element.clone(), 1), + restriction: access.owner_restriction(solution, entity_count, &element.element), + }); + continue; + }; + if std::mem::replace(&mut emitted[group], true) { + continue; + } + let mut members = SmallVec::new(); + let mut restriction = OwnerRestriction::Unrestricted; + for (member, &key) in groups.members(group).iter().enumerate() { + let entry = source_index + .source_index_for_key(key) + .and_then(|source| entry_by_source[source]); + match entry { + Some(entry) => { + let member = &ordered[entry]; + restriction = restriction.and(access.owner_restriction( + solution, + entity_count, + &member.element, + )); + members.push(member.clone()); + } + None => { + if let Some((owner, _)) = placement.member_position(groups, group, member) { + restriction = restriction.and(OwnerRestriction::Fixed(owner)); + } + } + } + } + units.push(ConstructionUnit { + members, + restriction, + }); + } + units +} + +/// The unpinned owners a unit may go to, and every owner's list length. +pub(crate) fn unit_owners( + access: &A, + unit_restriction: OwnerRestriction, + phase_scope: &PhaseScope<'_, '_, S, D, BestCb>, +) -> (SmallVec<[usize; 16]>, SmallVec<[usize; 16]>) +where + S: PlanningSolution, + A: ScoredListConstructionAccess, + D: Director, + BestCb: ProgressCallback, +{ + let solution = phase_scope.score_director().working_solution(); + let entity_count = access.entity_count(solution); + let owners = unit_restriction + .candidates(entity_count) + .filter(|&entity| { + !crate::pinning::entity_is_pinned( + phase_scope.score_director(), + access.descriptor_index(), + entity, + ) + }) + .collect(); + let lens = (0..entity_count) + .map(|entity| access.list_len(solution, entity)) + .collect(); + (owners, lens) +} + +/// Scores one joint placement of `members` and takes them back. +#[allow(clippy::too_many_arguments)] +pub(crate) fn evaluate_group_trial( + access: &A, + members: &mut SmallVec<[A::Element; 4]>, + first_source: usize, + entity: usize, + positions: &[usize], + source: CandidateTraceSource, + candidate_index: usize, + phase_scope: &mut PhaseScope<'_, '_, S, D, BestCb>, +) -> (S::Score, Option) +where + S: PlanningSolution, + A: ScoredListConstructionAccess, + D: Director, + BestCb: ProgressCallback, +{ + let descriptor_index = access.descriptor_index(); + let generation_started = Instant::now(); + let token = phase_scope.record_candidate_operation( + source, + None, + candidate_index, + Some(CandidateTraceConstructionTarget { + descriptor_index, + entity_index: entity, + }), + descriptor_index, + "list_group_insertion_trial", + [first_source as u64, entity as u64, positions[0] as u64], + ); + let generation_duration = generation_started.elapsed(); + let evaluation_started = Instant::now(); + let score_state = phase_scope.score_director().snapshot_score_state(); + let director = phase_scope.score_director_mut(); + director.before_variable_changed(descriptor_index, entity); + for (member, &position) in std::mem::take(members).into_iter().zip(positions) { + access.insert_element(director.working_solution_mut(), entity, position, member); + } + director.after_variable_changed(descriptor_index, entity); + let score = director.calculate_score(); + director.before_variable_changed(descriptor_index, entity); + for &position in positions.iter().rev() { + members.push( + access + .remove_element(director.working_solution_mut(), entity, position) + .expect("a group trial removes the members it inserted"), + ); + } + members.reverse(); + director.after_variable_changed(descriptor_index, entity); + phase_scope + .score_director_mut() + .restore_score_state(score_state); + phase_scope.record_score_calculation(); + if let Some(token) = token { + phase_scope.record_candidate_trace_disposition(token, CandidateTraceDisposition::Evaluated); + } + record_construction_candidate( + phase_scope, + generation_duration, + evaluation_started.elapsed(), + ); + (score, token) +} + +/// Keeps the trace token of the best trial so far and marks every other +/// trial ignored; ties keep the earlier trial. +pub(crate) fn keep_best_token( + best: &mut Option<(Sc, Option)>, + score: Sc, + token: Option, + phase_scope: &mut PhaseScope<'_, '_, S, D, BestCb>, +) where + S: PlanningSolution, + D: Director, + BestCb: ProgressCallback, +{ + let ignored = match best { + Some((best_score, _)) if score <= *best_score => token, + _ => best.replace((score, token)).and_then(|(_, token)| token), + }; + if let Some(token) = ignored { + phase_scope + .record_candidate_trace_disposition(token, CandidateTraceDisposition::ForagerIgnored); + } +} + +/// Commits a unit's members at `positions` of `entity` as one step. +#[allow(clippy::too_many_arguments)] +pub(crate) fn commit_group( + access: &A, + members: SmallVec<[A::Element; 4]>, + entity: usize, + positions: &[usize], + score: S::Score, + token: Option, + control_policy: StepControlPolicy, + phase_scope: &mut PhaseScope<'_, '_, S, D, BestCb>, +) where + S: PlanningSolution, + A: ScoredListConstructionAccess, + D: Director, + BestCb: ProgressCallback, +{ + let descriptor_index = access.descriptor_index(); + let mut step_scope = StepScope::new_with_control_policy(phase_scope, control_policy); + step_scope.phase_scope_mut().record_move_accepted(); + if let Some(token) = token { + step_scope + .phase_scope_mut() + .record_candidate_trace_disposition(token, CandidateTraceDisposition::Selected); + } + step_scope.apply_committed_change(|director| { + director.before_variable_changed(descriptor_index, entity); + for (member, &position) in members.into_iter().zip(positions) { + access.insert_element(director.working_solution_mut(), entity, position, member); + } + director.after_variable_changed(descriptor_index, entity); + }); + step_scope.phase_scope_mut().record_move_applied(); + if let Some(token) = token { + step_scope + .phase_scope_mut() + .record_candidate_trace_disposition(token, CandidateTraceDisposition::Applied); + } + step_scope.set_step_score(score); + step_scope.complete(); +} diff --git a/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret.rs b/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret.rs index e7abfd29..b131f762 100644 --- a/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret.rs +++ b/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret.rs @@ -6,7 +6,7 @@ mod kernel; #[cfg(test)] pub(crate) use facade::ListRegretInsertionPhase; -pub(crate) use kernel::run_regret; +pub(crate) use kernel::{run_regret, run_regret_grouped}; #[cfg(test)] #[path = "regret/tests.rs"] diff --git a/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret/kernel/grouped.rs b/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret/kernel/grouped.rs new file mode 100644 index 00000000..06316b73 --- /dev/null +++ b/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret/kernel/grouped.rs @@ -0,0 +1,212 @@ +//! Regret insertion of a list with element groups. +//! +//! Each round scores every remaining unit's bounded joint placements and +//! commits the unit whose best placement beats its runner-up by the most, so +//! a group's members are always placed together. + +use solverforge_core::domain::PlanningSolution; +use solverforge_scoring::Director; + +use super::super::super::groups::{ + commit_group, construction_units, evaluate_group_trial, keep_best_token, unit_owners, + ConstructionUnit, +}; +use super::choice::regret_choice_is_better; +use super::{RegretAccess, RegretValue}; +use crate::builder::context::{RuntimeListSourceIndex, SourceElement}; +use crate::list_groups::{ + search_joint_placement, JointBounds, JointChoice, JointSearch, ListElementGroups, + ListGroupPlacement, +}; +use crate::phase::construction::run_construction_phase; +use crate::scope::{PhaseScope, ProgressCallback, SolverScope, StepControlPolicy}; +use crate::stats::{CandidateTraceDisposition, CandidateTracePullToken, CandidateTraceSource}; + +struct UnitChoice { + unit: usize, + regret: RegretValue, + choice: JointChoice, + token: Option, +} + +/// Runs grouped regret insertion as one construction phase. +#[allow(clippy::too_many_arguments)] +pub(crate) fn run_regret_grouped( + access: &A, + source_index: &RuntimeListSourceIndex, + bound_unassigned: &[SourceElement], + groups: &ListElementGroups, + placement: &ListGroupPlacement, + bounds: JointBounds, + control_policy: StepControlPolicy, + solver_scope: &mut SolverScope<'_, S, D, BestCb>, +) where + S: PlanningSolution, + A: RegretAccess, + D: Director, + BestCb: ProgressCallback, +{ + run_construction_phase( + solver_scope, + 0, + "Regret-Insertion Construction", + |phase_scope| { + let solution = phase_scope.score_director().working_solution(); + let mut ordered = bound_unassigned.to_vec(); + ordered.sort_by_key(|entry| { + ( + access.construction_order_key(solution, &entry.element), + entry.source_index, + ) + }); + let mut units = + construction_units(access, solution, source_index, &ordered, groups, placement); + if access.entity_count(solution) == 0 { + units.clear(); + } + while !units.is_empty() { + if control_policy.should_terminate_construction(phase_scope.solver_scope_mut()) { + break; + } + let mut best: Option> = None; + let mut interrupted = false; + for (index, unit) in units.iter().enumerate() { + let Some(outcome) = + unit_regret(access, unit, bounds, control_policy, phase_scope) + else { + interrupted = true; + break; + }; + let Some((regret, choice, token)) = outcome else { + continue; + }; + let better = best.as_ref().is_none_or(|best| { + regret_choice_is_better( + regret, + choice.score, + best.regret, + best.choice.score, + ) + }); + let ignored = if better { + best.replace(UnitChoice { + unit: index, + regret, + choice, + token, + }) + .and_then(|previous| previous.token) + } else { + token + }; + if let Some(token) = ignored { + phase_scope.record_candidate_trace_disposition( + token, + CandidateTraceDisposition::ForagerIgnored, + ); + } + } + if interrupted { + if let Some(token) = best.and_then(|best| best.token) { + phase_scope.record_candidate_trace_disposition( + token, + CandidateTraceDisposition::ForagerIgnored, + ); + } + break; + } + let Some(best) = best else { + tracing::warn!("No valid insertion found for remaining groups, stopping"); + break; + }; + let unit = units.remove(best.unit); + commit_group( + access, + unit.elements(), + best.choice.entity, + &best.choice.positions, + best.choice.score, + best.token, + control_policy, + phase_scope, + ); + } + phase_scope.update_best_solution(); + }, + ); +} + +/// A unit's best placement and its regret; `None` when interrupted, and +/// `Some(None)` when no owner admits it. +#[allow(clippy::type_complexity)] +fn unit_regret( + access: &A, + unit: &ConstructionUnit, + bounds: JointBounds, + control_policy: StepControlPolicy, + phase_scope: &mut PhaseScope<'_, '_, S, D, BestCb>, +) -> Option< + Option<( + RegretValue, + JointChoice, + Option, + )>, +> +where + S: PlanningSolution, + A: RegretAccess, + D: Director, + BestCb: ProgressCallback, +{ + let (owners, lens) = unit_owners(access, unit.restriction, phase_scope); + let first_source = unit.members[0].source_index; + let mut members = unit.elements(); + let mut best_token = None; + let mut trial = 0; + let search = search_joint_placement( + &owners, + members.len(), + |entity| lens[entity], + bounds, + |entity, positions| { + if control_policy.should_terminate_construction(phase_scope.solver_scope_mut()) { + return None; + } + let (score, token) = evaluate_group_trial( + access, + &mut members, + first_source, + entity, + positions, + CandidateTraceSource::ListRegretInsertionTrial, + trial, + phase_scope, + ); + trial += 1; + keep_best_token(&mut best_token, score, token, phase_scope); + Some(score) + }, + ); + let token = best_token.and_then(|(_, token)| token); + match search { + JointSearch::Interrupted => { + if let Some(token) = token { + phase_scope.record_candidate_trace_disposition( + token, + CandidateTraceDisposition::ForagerIgnored, + ); + } + None + } + JointSearch::Done { best: None, .. } => Some(None), + JointSearch::Done { + best: Some(choice), + second, + } => { + let regret = second.map_or(RegretValue::Forced, |second| { + RegretValue::Finite(choice.score - second) + }); + Some(Some((regret, choice, token))) + } + } +} diff --git a/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret/kernel/mod.rs b/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret/kernel/mod.rs index f1833f87..5f4fc717 100644 --- a/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret/kernel/mod.rs +++ b/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret/kernel/mod.rs @@ -10,10 +10,12 @@ mod choice; mod evaluation; mod execute; mod fallback; +mod grouped; mod precedence; pub(crate) use super::super::ScoredListConstructionAccess as RegretAccess; pub(crate) use execute::run_regret; +pub(crate) use grouped::run_regret_grouped; use budgets::{OWNER_RESTRICTED_BEST_INSERTION_WORK_BUDGET, OWNER_RESTRICTED_REGRET_TRIAL_BUDGET}; use choice::{ diff --git a/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret/tests/parity.rs b/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret/tests/parity.rs index 913b6b6f..ea6c62a9 100644 --- a/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret/tests/parity.rs +++ b/crates/solverforge-solver/src/manager/phase_factory/list_construction/regret/tests/parity.rs @@ -208,6 +208,7 @@ fn run_runtime(slot: Slot) -> (Vec>, CandidateTraceTelemetry) { &slot, &source_index, &unassigned, + crate::list_groups::JointBounds::default(), crate::scope::StepControlPolicy::ObserveConfigLimits, &mut scope, ) @@ -245,6 +246,7 @@ fn compiled_regret_refreshes_current_assignment_before_a_second_execution() { &slot, &source_index, &unassigned, + crate::list_groups::JointBounds::default(), crate::scope::StepControlPolicy::ObserveConfigLimits, &mut scope, ) @@ -257,6 +259,7 @@ fn compiled_regret_refreshes_current_assignment_before_a_second_execution() { &slot, &source_index, &unassigned, + crate::list_groups::JointBounds::default(), crate::scope::StepControlPolicy::ObserveConfigLimits, &mut scope, ) diff --git a/crates/solverforge-solver/src/manager/phase_factory/mod.rs b/crates/solverforge-solver/src/manager/phase_factory/mod.rs index 4705913d..1a7b0fec 100644 --- a/crates/solverforge-solver/src/manager/phase_factory/mod.rs +++ b/crates/solverforge-solver/src/manager/phase_factory/mod.rs @@ -5,8 +5,8 @@ pub(crate) mod list_k_opt; pub(crate) use list_clarke_wright::run_clarke_wright; pub(crate) use list_construction::{ - run_cheapest, run_regret, run_round_robin, PhaseCheapestInsertionObserver, - ScoredListConstructionAccess, + run_cheapest, run_cheapest_grouped, run_regret, run_regret_grouped, run_round_robin, + PhaseCheapestInsertionObserver, ScoredListConstructionAccess, }; #[cfg(test)] pub(crate) use list_construction::{CheapestInsertionObserver, CheapestInsertionTrial}; diff --git a/crates/solverforge-solver/src/runtime/compiler/construction.rs b/crates/solverforge-solver/src/runtime/compiler/construction.rs index af9dd2bf..3e0e439b 100644 --- a/crates/solverforge-solver/src/runtime/compiler/construction.rs +++ b/crates/solverforge-solver/src/runtime/compiler/construction.rs @@ -114,6 +114,33 @@ where | ListConstructionKind::CheapestInsertion | ListConstructionKind::RegretInsertion => {} } + let grouped = slots + .iter() + .any(|slot| slot.element_group_policy().is_explicit()); + match kind { + ListConstructionKind::RoundRobin | ListConstructionKind::ClarkeWright if grouped => { + return Err(grouped_list_construction(path, heuristic)); + } + ListConstructionKind::CheapestInsertion | ListConstructionKind::RegretInsertion + if !grouped => + { + for (field, set) in [ + ("max_member_distance", config.max_member_distance.is_some()), + ("max_group_owners", config.max_group_owners.is_some()), + ] { + if set { + return Err(construction_shape( + path, + format!( + "`{field}` bounds joint placement of element groups, and no \ + targeted list variable declares `element_group_fn`" + ), + )); + } + } + } + _ => {} + } return Ok(CompiledConstruction::List { kind, config: config.clone(), @@ -135,6 +162,12 @@ where require_scalar_capability(&scalar_slots, RuntimeCapability::ScalarCandidates, path)?; } let list_slots = matching_list_slots(model, descriptor, &config.target, path)?; + if list_slots + .iter() + .any(|slot| slot.element_group_policy().is_explicit()) + { + return Err(grouped_list_construction(path, heuristic)); + } if scalar_slots.is_empty() && list_slots.is_empty() && (!model.variables().is_empty() @@ -313,6 +346,21 @@ pub(super) fn grouped_requires_value_order(heuristic: ConstructionHeuristicType) ) } +/// Heuristics that place list elements one at a time would split a group. +fn grouped_list_construction( + path: &str, + heuristic: ConstructionHeuristicType, +) -> RuntimeCompileError { + construction_shape( + path, + format!( + "construction heuristic {heuristic:?} places list elements one at a time and would \ + split element groups; a list variable with `element_group_fn` is constructed by \ + `list_cheapest_insertion` or `list_regret_insertion`" + ), + ) +} + pub(super) fn construction_shape(path: &str, message: String) -> RuntimeCompileError { RuntimeCompileError { path: path.to_string(), diff --git a/crates/solverforge-solver/src/runtime/compiler/default_local_search.rs b/crates/solverforge-solver/src/runtime/compiler/default_local_search.rs index 5d9f7434..ed0f5a31 100644 --- a/crates/solverforge-solver/src/runtime/compiler/default_local_search.rs +++ b/crates/solverforge-solver/src/runtime/compiler/default_local_search.rs @@ -69,6 +69,8 @@ pub(crate) struct DefaultLocalSearchComponents { /// The default selector family, in canonical execution order. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) enum DefaultLocalSearchSelectorFamily { + ListGroupChange, + ListGroupSwap, ListPrecedence, ListPermute, NearbyListChange, @@ -92,6 +94,8 @@ pub(crate) enum DefaultLocalSearchSelectorFamily { impl DefaultLocalSearchSelectorFamily { pub(crate) fn trace_label(self) -> &'static str { match self { + Self::ListGroupChange => "list_group_change", + Self::ListGroupSwap => "list_group_swap", Self::ListPrecedence => "list_precedence", Self::ListPermute => "list_permute", Self::NearbyListChange => "nearby_list_change", diff --git a/crates/solverforge-solver/src/runtime/compiler/default_local_search/policy/exclusions.rs b/crates/solverforge-solver/src/runtime/compiler/default_local_search/policy/exclusions.rs index d02694e8..a2d4caec 100644 --- a/crates/solverforge-solver/src/runtime/compiler/default_local_search/policy/exclusions.rs +++ b/crates/solverforge-solver/src/runtime/compiler/default_local_search/policy/exclusions.rs @@ -114,5 +114,6 @@ fn list_capability_label(capability: ListAccessCapability) -> &'static str { ListAccessCapability::Route => "route", ListAccessCapability::Savings => "savings", ListAccessCapability::SavingsNeighbors => "savings_neighbors", + ListAccessCapability::ElementGroups => "element_groups", } } diff --git a/crates/solverforge-solver/src/runtime/compiler/default_local_search/policy/list.rs b/crates/solverforge-solver/src/runtime/compiler/default_local_search/policy/list.rs index b34edcc4..3028c710 100644 --- a/crates/solverforge-solver/src/runtime/compiler/default_local_search/policy/list.rs +++ b/crates/solverforge-solver/src/runtime/compiler/default_local_search/policy/list.rs @@ -1,7 +1,8 @@ //! The explicit list capability-policy table for omitted local search. use solverforge_config::{ - KOptMoveSelectorConfig, ListChangeMoveConfig, ListPermuteMoveConfig, ListPrecedenceMoveConfig, + KOptMoveSelectorConfig, ListChangeMoveConfig, ListGroupChangeMoveConfig, + ListGroupSwapMoveConfig, ListPermuteMoveConfig, ListPrecedenceMoveConfig, ListReverseMoveConfig, ListRuinMoveSelectorConfig, ListSwapMoveConfig, MoveSelectorConfig, NearbyListChangeMoveConfig, NearbyListSwapMoveConfig, SelectionOrder, SublistChangeMoveConfig, SublistSwapMoveConfig, VariableTargetConfig, @@ -9,6 +10,7 @@ use solverforge_config::{ use crate::builder::context::list_access::ListAccessCapability; use crate::builder::RuntimeScalarSlotId; +use crate::list_groups::{DEFAULT_GROUP_MEMBER_DISTANCE, DEFAULT_GROUP_OWNERS}; use super::super::super::types::CompiledListSlot; use super::super::{ @@ -21,7 +23,8 @@ const DEFAULT_LIST_NEARBY_LIMIT: usize = 20; /// Typed and dynamic slots consume these rows in exactly this order. A named /// reduced-capability row is legal only when it is a distinct selector with /// its own immutable provenance. -const LIST_POLICY_TABLE: [DefaultListPolicyRule; 8] = [ +const LIST_POLICY_TABLE: [DefaultListPolicyRule; 9] = [ + DefaultListPolicyRule::GroupPair, DefaultListPolicyRule::PrecedencePair, DefaultListPolicyRule::NearbyChange, DefaultListPolicyRule::NearbySwap, @@ -34,6 +37,7 @@ const LIST_POLICY_TABLE: [DefaultListPolicyRule; 8] = [ #[derive(Clone, Copy, Debug)] enum DefaultListPolicyRule { + GroupPair, PrecedencePair, NearbyChange, NearbySwap, @@ -59,6 +63,36 @@ fn append_rule( declarations: &mut Vec, ) { match rule { + DefaultListPolicyRule::GroupPair => { + for slot in list_slots + .iter() + .filter(|slot| slot.supports(ListAccessCapability::ElementGroups)) + { + let target = target_for(&slot.identity()); + push_list( + declarations, + DefaultLocalSearchSelectorFamily::ListGroupChange, + DefaultSelectorCapabilityPolicy::DeclaredCapabilities, + MoveSelectorConfig::ListGroupChangeMoveSelector(ListGroupChangeMoveConfig { + selection_order: Some(SelectionOrder::Random), + target: target.clone(), + ..ListGroupChangeMoveConfig::default() + }), + vec![slot.identity()], + ); + push_list( + declarations, + DefaultLocalSearchSelectorFamily::ListGroupSwap, + DefaultSelectorCapabilityPolicy::DeclaredCapabilities, + MoveSelectorConfig::ListGroupSwapMoveSelector(ListGroupSwapMoveConfig { + selection_order: Some(SelectionOrder::Random), + target, + ..ListGroupSwapMoveConfig::default() + }), + vec![slot.identity()], + ); + } + } DefaultListPolicyRule::PrecedencePair => { for slot in list_slots .iter() @@ -190,6 +224,28 @@ fn append_rule( }), ); } + DefaultListPolicyRule::Ruin + if list_slots + .iter() + .any(|slot| slot.supports(ListAccessCapability::ElementGroups)) => + { + // One ruin per list, so grouped lists get bounded joint recreate. + for slot in list_slots { + let grouped = slot.supports(ListAccessCapability::ElementGroups); + push_list( + declarations, + DefaultLocalSearchSelectorFamily::ListRuin, + DefaultSelectorCapabilityPolicy::DeclaredCapabilities, + MoveSelectorConfig::ListRuinMoveSelector(ListRuinMoveSelectorConfig { + max_member_distance: grouped.then_some(DEFAULT_GROUP_MEMBER_DISTANCE), + max_group_owners: grouped.then_some(DEFAULT_GROUP_OWNERS), + target: target_for(&slot.identity()), + ..ListRuinMoveSelectorConfig::default() + }), + vec![slot.identity()], + ); + } + } DefaultListPolicyRule::Ruin => push_list_if_any( declarations, DefaultLocalSearchSelectorFamily::ListRuin, diff --git a/crates/solverforge-solver/src/runtime/compiler/default_local_search/trace.rs b/crates/solverforge-solver/src/runtime/compiler/default_local_search/trace.rs index 5b791bc3..fbf58abe 100644 --- a/crates/solverforge-solver/src/runtime/compiler/default_local_search/trace.rs +++ b/crates/solverforge-solver/src/runtime/compiler/default_local_search/trace.rs @@ -233,14 +233,24 @@ pub(crate) fn selector_config_signature(config: &MoveSelectorConfig) -> String { target_signature(&config.target) ), MoveSelectorConfig::ListRuinMoveSelector(config) => format!( - "list_ruin(min_ruin_count={},max_ruin_count={},moves_per_step={:?},max_source_list_len={:?},skip_empty_destinations={},target={})", + "list_ruin(min_ruin_count={},max_ruin_count={},moves_per_step={:?},max_source_list_len={:?},skip_empty_destinations={},max_member_distance={:?},max_group_owners={:?},target={})", config.min_ruin_count, config.max_ruin_count, config.moves_per_step, config.max_source_list_len, config.skip_empty_destinations, + config.max_member_distance, + config.max_group_owners, target_signature(&config.target) ), + MoveSelectorConfig::ListGroupChangeMoveSelector(config) => format!( + "list_group_change(max_member_distance={:?},target={})", + config.max_member_distance, + target_signature(&config.target) + ), + MoveSelectorConfig::ListGroupSwapMoveSelector(config) => { + format!("list_group_swap(target={})", target_signature(&config.target)) + } MoveSelectorConfig::LimitedNeighborhood(config) => format!( "limited(selected_count_limit={},selector={})", config.selected_count_limit, diff --git a/crates/solverforge-solver/src/runtime/compiler/defaults/stages.rs b/crates/solverforge-solver/src/runtime/compiler/defaults/stages.rs index 4119b950..0c9f9778 100644 --- a/crates/solverforge-solver/src/runtime/compiler/defaults/stages.rs +++ b/crates/solverforge-solver/src/runtime/compiler/defaults/stages.rs @@ -66,6 +66,9 @@ pub(crate) enum DefaultConstructionStepKind { /// The model fact that selected a default construction step. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) enum DefaultConstructionReason { + /// The list slot declares element groups, which only joint insertion + /// keeps together. + ElementGroupsDeclared, /// The list slot declares savings hooks. SavingsDeclared, /// Precedence, construction order and ownership are all declared. @@ -87,6 +90,7 @@ pub(crate) enum DefaultConstructionReason { impl DefaultConstructionReason { pub(crate) fn trace_label(self) -> &'static str { match self { + Self::ElementGroupsDeclared => "element_groups_declared", Self::SavingsDeclared => "savings_hooks_declared", Self::PrecedenceOrderAndOwnership => { "precedence_construction_order_and_ownership_declared" @@ -229,7 +233,11 @@ where construction: CompiledConstruction::List { kind: ListConstructionKind::from_heuristic(heuristic) .expect("default list construction must map to a compiled list kind"), - config: list_config(heuristic, &target), + config: ConstructionHeuristicConfig { + max_group_owners: (reason == DefaultConstructionReason::ElementGroupsDeclared) + .then_some(crate::list_groups::DEFAULT_GROUP_OWNERS), + ..list_config(heuristic, &target) + }, slots: vec![slot.clone()], }, required_only: false, @@ -303,7 +311,12 @@ fn default_list_construction_heuristic( ) -> (ConstructionHeuristicType, DefaultConstructionReason) { use crate::builder::context::list_access::ListAccessCapability; - if slot.supports(ListAccessCapability::Savings) { + if slot.element_group_policy().is_explicit() { + ( + ConstructionHeuristicType::ListCheapestInsertion, + DefaultConstructionReason::ElementGroupsDeclared, + ) + } else if slot.supports(ListAccessCapability::Savings) { ( ConstructionHeuristicType::ListClarkeWright, DefaultConstructionReason::SavingsDeclared, diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/execute.rs b/crates/solverforge-solver/src/runtime/compiler/executor/execute.rs index a626ed3f..8bc5c120 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/execute.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/execute.rs @@ -15,6 +15,7 @@ use solverforge_scoring::Director; use crate::builder::context::{ListConstructionKernelError, RuntimeListElement, SourceElement}; use crate::heuristic::selector::nearby_list_change::CrossEntityDistanceMeter; +use crate::list_groups::JointBounds; use crate::phase::construction::{ build_scalar_group_construction, record_scalar_assignment_remaining, scalar_group_work_remaining, FrozenRuntimeListConstructionSlot, @@ -152,7 +153,16 @@ where slots, control_policy, solver_scope, - execute_runtime_list_cheapest_insertion, + |slot, source_index, unassigned, control_policy, solver_scope| { + execute_runtime_list_cheapest_insertion( + slot, + source_index, + unassigned, + joint_bounds(config), + control_policy, + solver_scope, + ) + }, ) }, ) @@ -168,7 +178,16 @@ where slots, control_policy, solver_scope, - execute_runtime_list_regret_insertion, + |slot, source_index, unassigned, control_policy, solver_scope| { + execute_runtime_list_regret_insertion( + slot, + source_index, + unassigned, + joint_bounds(config), + control_policy, + solver_scope, + ) + }, ) }, ) @@ -441,3 +460,8 @@ where } Ok(ran) } + +/// Joint placement bounds a list construction phase gives element groups. +fn joint_bounds(config: &ConstructionHeuristicConfig) -> JointBounds { + JointBounds::from_config(config.max_member_distance, config.max_group_owners) +} diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_construction/phase.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_construction/phase.rs index b7b716bb..c5c5e35e 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_construction/phase.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_construction/phase.rs @@ -11,7 +11,8 @@ use crate::builder::context::{ SourceElement, }; use crate::heuristic::selector::nearby_list_change::CrossEntityDistanceMeter; -use crate::manager::{run_cheapest, PhaseCheapestInsertionObserver}; +use crate::list_groups::JointBounds; +use crate::manager::{run_cheapest, run_cheapest_grouped, PhaseCheapestInsertionObserver}; use crate::phase::construction::run_construction_phase; use crate::scope::{ProgressCallback, SolverScope, StepControlPolicy}; @@ -27,6 +28,7 @@ pub(crate) fn execute_runtime_list_cheapest_insertion, source_index: &RuntimeListSourceIndex>, unassigned: &[SourceElement>], + bounds: JointBounds, control_policy: StepControlPolicy, solver_scope: &mut SolverScope<'_, S, D, ProgressCb>, ) -> Result<(), ListConstructionKernelError> @@ -39,6 +41,21 @@ where D: Director, ProgressCb: ProgressCallback, { + let solution = solver_scope.working_solution(); + if let Some(groups) = slot.element_groups(solution) { + let placement = slot.locate_group_members(&groups, solution); + run_cheapest_grouped( + slot, + source_index, + unassigned, + &groups, + &placement, + bounds, + control_policy, + solver_scope, + ); + return Ok(()); + } run_construction_phase( solver_scope, 0, @@ -179,6 +196,7 @@ mod tests { &slot, &source_index, &unassigned, + JointBounds::default(), StepControlPolicy::ObserveConfigLimits, &mut scope, ) @@ -194,6 +212,7 @@ mod tests { &slot, &source_index, &unassigned, + JointBounds::default(), StepControlPolicy::ObserveConfigLimits, &mut scope, ) diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_construction/regret.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_construction/regret.rs index db530226..a3af2a47 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_construction/regret.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_construction/regret.rs @@ -10,7 +10,8 @@ use crate::builder::context::{ SourceElement, }; use crate::heuristic::selector::nearby_list_change::CrossEntityDistanceMeter; -use crate::manager::run_regret; +use crate::list_groups::JointBounds; +use crate::manager::{run_regret, run_regret_grouped}; use crate::scope::{ProgressCallback, SolverScope, StepControlPolicy}; /// Executes canonical regret insertion against a borrowed prepared source @@ -19,6 +20,7 @@ pub(crate) fn execute_runtime_list_regret_insertion, source_index: &RuntimeListSourceIndex>, unassigned: &[SourceElement>], + bounds: JointBounds, control_policy: StepControlPolicy, solver_scope: &mut SolverScope<'_, S, D, ProgressCb>, ) -> Result<(), ListConstructionKernelError> @@ -30,6 +32,21 @@ where D: Director, ProgressCb: ProgressCallback, { + let solution = solver_scope.working_solution(); + if let Some(groups) = slot.element_groups(solution) { + let placement = slot.locate_group_members(&groups, solution); + run_regret_grouped( + slot, + source_index, + unassigned, + &groups, + &placement, + bounds, + control_policy, + solver_scope, + ); + return Ok(()); + } run_regret(slot, source_index, unassigned, control_policy, solver_scope); Ok(()) } diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor.rs index 694a2d76..2ec7c96b 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor.rs @@ -1,5 +1,6 @@ //! One streamed cursor for every compiled runtime list neighborhood. +mod groups; mod probe; mod slot; diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/groups.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/groups.rs new file mode 100644 index 00000000..ed12caca --- /dev/null +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/groups.rs @@ -0,0 +1,93 @@ +//! Per-step group snapshots for the group cursors and grouped ruin. + +use std::fmt; + +use solverforge_core::domain::PlanningSolution; + +use crate::builder::context::{list_access::ListAccess, RuntimeListSlot}; +use crate::heuristic::r#move::list_kernel::MemberCoordinates; +use crate::heuristic::selector::list_kernel::GroupSnapshot; +use crate::heuristic::selector::nearby_list_change::CrossEntityDistanceMeter; +use crate::list_groups::{JointBounds, ListElementGroups, ListGroupPlacement}; +use crate::list_placement::OwnerRestriction; + +use super::super::emission::RuntimeListEmitter; +use super::super::group_emission::GroupedRuinEmitter; + +/// Every fully assigned group with its members' coordinates and the owners +/// every member allows. +pub(super) fn runtime_group_snapshots( + slot: &RuntimeListSlot, + solution: &S, +) -> Vec +where + S: PlanningSolution + Clone + Send + Sync + 'static, + V: Clone + PartialEq + Send + Sync + fmt::Debug + 'static, + DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, +{ + let Some(groups) = slot.element_groups(solution) else { + return Vec::new(); + }; + let placement = slot.locate_group_members(&groups, solution); + let entity_count = ListAccess::entity_count(slot, solution); + let explicit = slot.ownership_policy().is_explicit(); + (0..groups.group_count()) + .filter(|&group| placement.group_is_assigned(&groups, group)) + .map(|group| { + let members: MemberCoordinates = (0..groups.members(group).len()) + .map(|member| { + placement + .member_position(&groups, group, member) + .expect("an assigned group has every member placed") + }) + .collect(); + let restriction = if explicit { + members.iter().fold( + OwnerRestriction::Unrestricted, + |restriction, &(entity, position)| { + let element = ListAccess::list_get(slot, solution, entity, position) + .expect("a located member is in its list"); + let owner = ListAccess::element_owner(slot, solution, &element).expect( + "compiled owner-aware list leaf requires validated owner metadata", + ); + restriction.and(OwnerRestriction::from_hook_owner(owner, entity_count)) + }, + ) + } else { + OwnerRestriction::Unrestricted + }; + GroupSnapshot { + members, + restriction, + } + }) + .collect() +} + +/// The ruin emitter of a slot with element groups, or `None` without them. +pub(super) fn runtime_grouped_ruin_emitter( + slot: &RuntimeListSlot, + solution: &S, + skip_empty_destinations: bool, + bounds: JointBounds, +) -> Option> +where + S: PlanningSolution + Clone + Send + Sync + 'static, + V: Clone + PartialEq + Send + Sync + fmt::Debug + 'static, + DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, +{ + let groups: ListElementGroups = slot.element_groups(solution)?; + let placement: ListGroupPlacement = slot.locate_group_members(&groups, solution); + let list_lens: Vec = (0..ListAccess::entity_count(slot, solution)) + .map(|entity| ListAccess::list_len(slot, solution, entity)) + .collect(); + Some(GroupedRuinEmitter::new( + RuntimeListEmitter::new(slot, skip_empty_destinations), + groups, + placement, + &list_lens, + bounds, + )) +} diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/probe.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/probe.rs index 03c8361c..01ab6de3 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/probe.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/probe.rs @@ -11,11 +11,19 @@ use crate::heuristic::selector::nearby_list_change::CrossEntityDistanceMeter; use crate::heuristic::selector::precedence_route::{ build_precedence_route_graph, PrecedenceRouteGraph, }; +use crate::list_groups::ListElementGroups; use crate::list_placement::OwnerRestriction; /// Immutable nearby probe over the one compiled list carrier. +/// +/// `groups` holds the slot's element groups for this step: a grouped element +/// stays on its current owner, because only group moves relocate a group. pub(super) struct RuntimeNearbyProbe<'a, S, V, DM, IDM> { slot: &'a RuntimeListSlot, + groups: Option>, + /// Whether candidates carry an owner restriction: an owner hook or + /// element groups. Frozen at construction, read per candidate. + owner_binding: bool, } /// Intra-route metric probe borrowed from the immutable selector declaration. @@ -43,9 +51,20 @@ where } } -impl<'a, S, V, DM, IDM> RuntimeNearbyProbe<'a, S, V, DM, IDM> { - pub(super) fn new(slot: &'a RuntimeListSlot) -> Self { - Self { slot } +impl<'a, S, V, DM, IDM> RuntimeNearbyProbe<'a, S, V, DM, IDM> +where + S: PlanningSolution + Clone + Send + Sync + 'static, + V: Clone + PartialEq + Send + Sync + fmt::Debug + 'static, + DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, +{ + pub(super) fn new(slot: &'a RuntimeListSlot, solution: &S) -> Self { + let groups = slot.element_groups(solution).map(Box::new); + Self { + slot, + owner_binding: slot.ownership_policy().is_explicit() || groups.is_some(), + groups, + } } } @@ -75,19 +94,55 @@ where entity: usize, position: usize, ) -> Option { - if !self.slot.ownership_policy().is_explicit() { + if !self.owner_binding { return None; } + let explicit = self.slot.ownership_policy().is_explicit(); let element = ListAccess::list_get(self.slot, solution, entity, position)?; - Some(owner_restriction( + let restriction = if explicit { + owner_restriction(self.slot, solution, entity_count, &element) + } else { + OwnerRestriction::Unrestricted + }; + Some(pin_grouped( self.slot, solution, - entity_count, + self.groups.as_deref(), + restriction, + entity, &element, )) } } +/// A grouped element keeps its current owner: only a group move may take a +/// group to another owner. +fn pin_grouped( + slot: &RuntimeListSlot, + solution: &S, + groups: Option<&ListElementGroups>, + restriction: OwnerRestriction, + entity: usize, + element: & as ListAccess>::Element, +) -> OwnerRestriction +where + S: PlanningSolution + Clone + Send + Sync + 'static, + V: Clone + PartialEq + Send + Sync + fmt::Debug + 'static, + DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, +{ + match groups { + Some(groups) + if groups + .group_of_key(ListAccess::element_source_key(slot, solution, element)) + .is_some() => + { + restriction.and(OwnerRestriction::Fixed(entity)) + } + _ => restriction, + } +} + impl crate::heuristic::selector::list_kernel::NearbyChangeProbe for RuntimeNearbyProbe<'_, S, V, DM, IDM> where @@ -116,7 +171,7 @@ where } fn has_owner_binding(&self) -> bool { - self.slot.ownership_policy().is_explicit() + self.owner_binding } fn owner_restriction( @@ -157,7 +212,7 @@ where } fn has_owner_binding(&self) -> bool { - self.slot.ownership_policy().is_explicit() + self.owner_binding } fn owner_restriction( @@ -183,7 +238,9 @@ where DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, { - if !slot.ownership_policy().is_explicit() { + let explicit = slot.ownership_policy().is_explicit(); + let groups = slot.element_groups(solution); + if !explicit && groups.is_none() { return SelectedListOwners::Absent; } let entity_count = ListAccess::entity_count(slot, solution); @@ -195,7 +252,21 @@ where (0..route_len) .map(|position| { let restriction = ListAccess::list_get(slot, solution, entity, position) - .map(|element| owner_restriction(slot, solution, entity_count, &element)) + .map(|element| { + let restriction = if explicit { + owner_restriction(slot, solution, entity_count, &element) + } else { + OwnerRestriction::Unrestricted + }; + pin_grouped( + slot, + solution, + groups.as_ref(), + restriction, + entity, + &element, + ) + }) .unwrap_or(OwnerRestriction::Invalid); fixed_to_current &= matches!(restriction, OwnerRestriction::Fixed(owner) if owner == entity); diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/slot.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/slot.rs index 6c0ff97d..78ef6ca4 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/slot.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/slot.rs @@ -6,9 +6,9 @@ use solverforge_core::score::Score; use crate::builder::context::{list_access::ListAccess, RuntimeListSlot}; use crate::heuristic::r#move::k_opt_reconnection::KOptReconnection; use crate::heuristic::selector::list_kernel::{ - ChangeCursor, KOptCursor, NearbyChangeCursor, NearbyKOptCursor, NearbySwapCursor, - PermuteCursor, PrecedenceCursor, ReverseCursor, RuinCursor, SublistChangeCursor, - SublistSwapCursor, SwapCursor, DYNAMIC_CHANGE_SALTS, STATIC_CHANGE_SALTS, + ChangeCursor, GroupChangeCursor, GroupSwapCursor, KOptCursor, NearbyChangeCursor, + NearbyKOptCursor, NearbySwapCursor, PermuteCursor, PrecedenceCursor, ReverseCursor, RuinCursor, + SublistChangeCursor, SublistSwapCursor, SwapCursor, DYNAMIC_CHANGE_SALTS, STATIC_CHANGE_SALTS, STATIC_NEARBY_CHANGE_ENTITY_SALT, STATIC_NEARBY_CHANGE_SOURCE_SALT, STATIC_NEARBY_SWAP_ENTITY_SALT, STATIC_NEARBY_SWAP_SOURCE_SALT, STATIC_REVERSE_ENTITY_SALT, STATIC_SUBLIST_CHANGE_SALTS, STATIC_SUBLIST_SWAP_ENTITY_SALT, STATIC_SWAP_SALTS, @@ -19,8 +19,10 @@ use crate::heuristic::selector::move_selector::{ use crate::heuristic::selector::nearby_list_change::CrossEntityDistanceMeter; use super::super::emission::RuntimeListEmitter; +use super::super::group_emission::GroupedRuinEmitter; use super::super::spec::RuntimeListNeighborhoodSpec; use super::super::RuntimeListMove; +use super::groups::{runtime_group_snapshots, runtime_grouped_ruin_emitter}; use super::probe::{ runtime_precedence_analysis, runtime_precedence_graph, runtime_ruin_source_pool, runtime_selected_owners, RuntimeKOptProbe, RuntimeNearbyProbe, @@ -68,6 +70,9 @@ where >, ), Ruin(RuinCursor>), + GroupRuin(RuinCursor>), + GroupChange(GroupChangeCursor>), + GroupSwap(GroupSwapCursor>), Empty, } @@ -93,6 +98,9 @@ where Self::KOpt(cursor) => cursor.next_owned_candidate(solution), Self::NearbyKOpt(cursor) => cursor.next_owned_candidate(solution), Self::Ruin(cursor) => cursor.next_owned_candidate(solution), + Self::GroupRuin(cursor) => cursor.next_owned_candidate(solution), + Self::GroupChange(cursor) => cursor.next_owned_candidate(solution), + Self::GroupSwap(cursor) => cursor.next_owned_candidate(solution), Self::Empty => None, } } @@ -121,6 +129,9 @@ where Self::KOpt(cursor) => cursor.next_candidate(solution), Self::NearbyKOpt(cursor) => cursor.next_candidate(solution), Self::Ruin(cursor) => cursor.next_candidate(solution), + Self::GroupRuin(cursor) => cursor.next_candidate(solution), + Self::GroupChange(cursor) => cursor.next_candidate(solution), + Self::GroupSwap(cursor) => cursor.next_candidate(solution), Self::Empty => None, } } @@ -142,6 +153,9 @@ where Self::KOpt(cursor) => cursor.candidate(id), Self::NearbyKOpt(cursor) => cursor.candidate(id), Self::Ruin(cursor) => cursor.candidate(id), + Self::GroupRuin(cursor) => cursor.candidate(id), + Self::GroupChange(cursor) => cursor.candidate(id), + Self::GroupSwap(cursor) => cursor.candidate(id), Self::Empty => None, } } @@ -160,6 +174,9 @@ where Self::KOpt(cursor) => cursor.take_candidate(id), Self::NearbyKOpt(cursor) => cursor.take_candidate(id), Self::Ruin(cursor) => cursor.take_candidate(id), + Self::GroupRuin(cursor) => cursor.take_candidate(id), + Self::GroupChange(cursor) => cursor.take_candidate(id), + Self::GroupSwap(cursor) => cursor.take_candidate(id), Self::Empty => panic!("empty runtime list slot has no candidate to take"), } } @@ -182,6 +199,9 @@ where Self::KOpt(cursor) => cursor.release_candidate(id), Self::NearbyKOpt(cursor) => cursor.release_candidate(id), Self::Ruin(cursor) => cursor.release_candidate(id), + Self::GroupRuin(cursor) => cursor.release_candidate(id), + Self::GroupChange(cursor) => cursor.release_candidate(id), + Self::GroupSwap(cursor) => cursor.release_candidate(id), Self::Empty => false, } } diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/slot/open.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/slot/open.rs index 53503f88..b1e988a8 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/slot/open.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/cursor/slot/open.rs @@ -1,4 +1,5 @@ use super::*; +use crate::list_groups::member_gap; #[allow(clippy::too_many_arguments)] pub(in super::super) fn open_slot_cursor<'a, S, V, DM, IDM>( @@ -64,7 +65,7 @@ where RuntimeListSlotCursor::NearbyChange( NearbyChangeCursor::new( RuntimeListEmitter::new(slot, false), - RuntimeNearbyProbe::new(slot), + RuntimeNearbyProbe::new(slot, solution), entities, route_lens, entity_count, @@ -149,7 +150,7 @@ where RuntimeListSlotCursor::NearbySwap( NearbySwapCursor::new( RuntimeListEmitter::new(slot, false), - RuntimeNearbyProbe::new(slot), + RuntimeNearbyProbe::new(slot, solution), entities, route_lens, entity_count, @@ -275,11 +276,24 @@ where moves_per_step, max_source_list_len, skip_empty_destinations, + bounds, } => { let Some(seed) = ruin_seed else { return RuntimeListSlotCursor::Empty; }; let source_pool = runtime_ruin_source_pool(slot, solution, max_source_list_len); + if let Some(emitter) = + runtime_grouped_ruin_emitter(slot, solution, skip_empty_destinations, bounds) + { + return RuntimeListSlotCursor::GroupRuin(RuinCursor::new( + emitter, + SmallRng::seed_from_u64(seed), + source_pool, + moves_per_step, + min_ruin_count, + max_ruin_count, + )); + } RuntimeListSlotCursor::Ruin(RuinCursor::new( RuntimeListEmitter::new(slot, skip_empty_destinations), SmallRng::seed_from_u64(seed), @@ -289,6 +303,29 @@ where max_ruin_count, )) } + RuntimeListNeighborhoodSpec::GroupChange { + max_member_distance, + } => { + let entity_lens = (0..ListAccess::entity_count(slot, solution)) + .map(|entity| ListAccess::list_len(slot, solution, entity)) + .collect(); + RuntimeListSlotCursor::GroupChange(GroupChangeCursor::new( + RuntimeListEmitter::new(slot, false), + runtime_group_snapshots(slot, solution), + entity_lens, + context, + max_member_distance.map(member_gap), + descriptor_index, + )) + } + RuntimeListNeighborhoodSpec::GroupSwap => { + RuntimeListSlotCursor::GroupSwap(GroupSwapCursor::new( + RuntimeListEmitter::new(slot, false), + runtime_group_snapshots(slot, solution), + context, + descriptor_index, + )) + } } } diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/emission.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/emission.rs index 665e3874..bcaa977b 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/emission.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/emission.rs @@ -57,9 +57,20 @@ where } } - fn move_from_recipe(&self, recipe: RuntimeListRecipe) -> RuntimeListMove { + pub(super) fn move_from_recipe( + &self, + recipe: RuntimeListRecipe, + ) -> RuntimeListMove { RuntimeListMove::new(recipe) } + + pub(super) fn move_access(&self) -> &RuntimeListMoveAccess { + &self.move_access + } + + pub(super) fn skip_empty_destinations(&self) -> bool { + self.skip_empty_destinations + } } impl fmt::Debug for RuntimeListEmitter diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/group_emission.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/group_emission.rs new file mode 100644 index 00000000..e4b08ea5 --- /dev/null +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/group_emission.rs @@ -0,0 +1,146 @@ +//! Group move emission over the shared runtime list emitter. + +use std::fmt; + +use smallvec::SmallVec; +use solverforge_core::domain::PlanningSolution; +use solverforge_core::score::Score; + +use crate::heuristic::r#move::list_kernel::{ + GroupChangeCoordinates, GroupRuinPlan, GroupSwapCoordinates, +}; +use crate::heuristic::selector::list_kernel::{GroupChangeEmitter, GroupSwapEmitter, RuinEmitter}; +use crate::heuristic::selector::nearby_list_change::CrossEntityDistanceMeter; +use crate::list_groups::{JointBounds, ListElementGroups, ListGroupPlacement}; + +use super::emission::RuntimeListEmitter; +use super::{RuntimeListMove, RuntimeListRecipe}; + +impl GroupChangeEmitter for RuntimeListEmitter +where + S: PlanningSolution + Clone + Send + Sync + 'static, + S::Score: Score, + V: Clone + PartialEq + Send + Sync + fmt::Debug + 'static, + DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, +{ + type Move = RuntimeListMove; + + fn emit_group_change(&self, coordinates: GroupChangeCoordinates) -> Self::Move { + self.move_from_recipe(RuntimeListRecipe::GroupChange { + access: self.move_access().clone(), + coordinates, + }) + } +} + +impl GroupSwapEmitter for RuntimeListEmitter +where + S: PlanningSolution + Clone + Send + Sync + 'static, + S::Score: Score, + V: Clone + PartialEq + Send + Sync + fmt::Debug + 'static, + DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, +{ + type Move = RuntimeListMove; + + fn emit_group_swap(&self, coordinates: GroupSwapCoordinates) -> Self::Move { + self.move_from_recipe(RuntimeListRecipe::GroupSwap { + access: self.move_access().clone(), + coordinates, + }) + } +} + +/// Ruin emission for a list with element groups: every ruined element takes +/// its whole group along, and recreate places each group jointly. +pub(super) struct GroupedRuinEmitter { + inner: RuntimeListEmitter, + groups: ListElementGroups, + placement: ListGroupPlacement, + /// Group of the element at `[entity][position]`, `u32::MAX` if none. + group_at: Vec>, + bounds: JointBounds, +} + +impl GroupedRuinEmitter { + pub(super) fn new( + inner: RuntimeListEmitter, + groups: ListElementGroups, + placement: ListGroupPlacement, + list_lens: &[usize], + bounds: JointBounds, + ) -> Self { + let mut group_at: Vec> = + list_lens.iter().map(|&len| vec![u32::MAX; len]).collect(); + for group in 0..groups.group_count() { + for member in 0..groups.members(group).len() { + if let Some((entity, position)) = placement.member_position(&groups, group, member) + { + group_at[entity][position] = + u32::try_from(group).expect("group count fits in u32"); + } + } + } + Self { + inner, + groups, + placement, + group_at, + bounds, + } + } +} + +impl fmt::Debug for GroupedRuinEmitter { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("GroupedRuinEmitter") + .field("group_count", &self.groups.group_count()) + .field("bounds", &self.bounds) + .finish_non_exhaustive() + } +} + +impl RuinEmitter for GroupedRuinEmitter +where + S: PlanningSolution + Clone + Send + Sync + 'static, + S::Score: Score, + V: Clone + PartialEq + Send + Sync + fmt::Debug + 'static, + DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, +{ + type Move = RuntimeListMove; + + fn emit_ruin(&self, entity: usize, indices: &[usize]) -> Self::Move { + let mut removed = SmallVec::new(); + let mut unit_ends = SmallVec::new(); + let mut seen: SmallVec<[u32; 8]> = SmallVec::new(); + let mut sorted: SmallVec<[usize; 8]> = SmallVec::from_slice(indices); + sorted.sort_unstable(); + for index in sorted { + let group = self.group_at[entity][index]; + if group == u32::MAX { + removed.push((entity, index)); + } else if seen.contains(&group) { + continue; + } else { + seen.push(group); + let group = group as usize; + removed.extend((0..self.groups.members(group).len()).filter_map(|member| { + self.placement.member_position(&self.groups, group, member) + })); + } + unit_ends.push(u16::try_from(removed.len()).expect("a ruin removes few elements")); + } + self.inner.move_from_recipe(RuntimeListRecipe::GroupRuin { + access: self.inner.move_access().clone(), + plan: GroupRuinPlan { + removed, + unit_ends, + bounds: self.bounds, + skip_empty_destinations: self.inner.skip_empty_destinations(), + }, + }) + } +} diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/mod.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/mod.rs index 7ba4b962..18269f90 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/mod.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/mod.rs @@ -8,6 +8,7 @@ mod compiled_leaf; mod cursor; mod emission; +mod group_emission; mod r#move; mod move_access; mod recipe; diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/move.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/move.rs index ad2d42fc..25d1201c 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/move.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/move.rs @@ -9,12 +9,15 @@ use solverforge_scoring::Director; use crate::builder::context::RuntimeListElement; use crate::heuristic::r#move::list_kernel::{ - change_do_move, change_is_doable, change_undo_move, k_opt_do_move, k_opt_do_move_into, - k_opt_is_doable, k_opt_undo_move, multi_swap_do_move, multi_swap_is_doable, - multi_swap_undo_move, permute_do_move, permute_is_doable, permute_undo_move, reverse_do_move, - reverse_is_doable, ruin_do_move, ruin_is_doable, ruin_undo_move, sublist_change_do_move, - sublist_change_is_doable, sublist_change_undo_move, sublist_swap_do_move, - sublist_swap_is_doable, sublist_swap_undo_move, swap_do_move, swap_is_doable, ListMoveAccess, + change_do_move, change_is_doable, change_undo_move, group_change_do_move, + group_change_is_doable, group_change_undo_move, group_ruin_do_move, group_ruin_is_doable, + group_ruin_undo_move, group_swap_do_move, group_swap_is_doable, group_swap_undo_move, + k_opt_do_move, k_opt_do_move_into, k_opt_is_doable, k_opt_undo_move, multi_swap_do_move, + multi_swap_is_doable, multi_swap_undo_move, permute_do_move, permute_is_doable, + permute_undo_move, reverse_do_move, reverse_is_doable, ruin_do_move, ruin_is_doable, + ruin_undo_move, sublist_change_do_move, sublist_change_is_doable, sublist_change_undo_move, + sublist_swap_do_move, sublist_swap_is_doable, sublist_swap_undo_move, swap_do_move, + swap_is_doable, ListMoveAccess, }; use crate::heuristic::r#move::{ListUndoJournal, Move, MoveTabuSignature}; use crate::heuristic::selector::nearby_list_change::CrossEntityDistanceMeter; @@ -181,6 +184,17 @@ where coordinates, .. } => multi_swap_is_doable(access, coordinates, score_director), + RuntimeListRecipe::GroupChange { + access, + coordinates, + } => group_change_is_doable(access, coordinates, score_director), + RuntimeListRecipe::GroupSwap { + access, + coordinates, + } => group_swap_is_doable(access, coordinates, score_director), + RuntimeListRecipe::GroupRuin { access, plan } => { + group_ruin_is_doable(access, plan, score_director) + } } } @@ -290,6 +304,23 @@ where multi_swap_do_move(access, coordinates, &self.entity_indices, score_director); RuntimeListMoveUndo::None } + RuntimeListRecipe::GroupChange { + access, + coordinates, + } => { + group_change_do_move(access, coordinates, score_director); + RuntimeListMoveUndo::None + } + RuntimeListRecipe::GroupSwap { + access, + coordinates, + } => { + group_swap_do_move(access, coordinates, score_director); + RuntimeListMoveUndo::None + } + RuntimeListRecipe::GroupRuin { access, plan } => { + RuntimeListMoveUndo::Ruin(group_ruin_do_move(access, plan, score_director)) + } } } @@ -360,6 +391,23 @@ where }, RuntimeListMoveUndo::None, ) => multi_swap_undo_move(access, coordinates, &self.entity_indices, score_director), + ( + RuntimeListRecipe::GroupChange { + access, + coordinates, + }, + RuntimeListMoveUndo::None, + ) => group_change_undo_move(access, coordinates, score_director), + ( + RuntimeListRecipe::GroupSwap { + access, + coordinates, + }, + RuntimeListMoveUndo::None, + ) => group_swap_undo_move(access, coordinates, score_director), + (RuntimeListRecipe::GroupRuin { access, plan }, RuntimeListMoveUndo::Ruin(undo)) => { + group_ruin_undo_move(access, plan, undo, score_director) + } _ => panic!("runtime list move undo shape must match recipe"), } } @@ -387,6 +435,9 @@ where RuntimeListRecipe::KOpt { .. } => "runtime_k_opt", RuntimeListRecipe::Ruin { .. } => "runtime_list_ruin", RuntimeListRecipe::MultiSwap { .. } => "runtime_list_multi_swap", + RuntimeListRecipe::GroupChange { .. } => "runtime_list_group_change", + RuntimeListRecipe::GroupSwap { .. } => "runtime_list_group_swap", + RuntimeListRecipe::GroupRuin { .. } => "runtime_list_group_ruin", } } diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/move_access.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/move_access.rs index 87b4e94f..02466a09 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/move_access.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/move_access.rs @@ -89,7 +89,7 @@ impl RuntimeListMoveAccess { sublist_remove: slot.sublist_remove, sublist_insert: slot.sublist_insert, element_owner: slot.element_owner_fn, - precedence_successors: slot.precedence_successors_fn, + precedence_successors: slot.precedence_successors_fn(), }), RuntimeListSlot::Dynamic(dynamic) => Self::Dynamic { slot: (**dynamic).clone(), diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/recipe.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/recipe.rs index ff0081b5..b383aa46 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/recipe.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/recipe.rs @@ -29,7 +29,10 @@ pub(super) fn recipe_access( | RuntimeListRecipe::SublistSwap { access, .. } | RuntimeListRecipe::KOpt { access, .. } | RuntimeListRecipe::Ruin { access, .. } - | RuntimeListRecipe::MultiSwap { access, .. } => access, + | RuntimeListRecipe::MultiSwap { access, .. } + | RuntimeListRecipe::GroupChange { access, .. } + | RuntimeListRecipe::GroupSwap { access, .. } + | RuntimeListRecipe::GroupRuin { access, .. } => access, } } @@ -62,6 +65,9 @@ pub(super) fn recipe_entity_indices( RuntimeListRecipe::MultiSwap { coordinates, .. } => { multi_swap_entity_indices(coordinates).into_iter().collect() } + RuntimeListRecipe::GroupChange { coordinates, .. } => coordinates.entities(), + RuntimeListRecipe::GroupSwap { coordinates, .. } => coordinates.entities(), + RuntimeListRecipe::GroupRuin { plan, .. } => plan.entities(), }; entities.sort_unstable(); entities.dedup(); @@ -79,5 +85,8 @@ pub(super) fn recipe_family(recipe: &RuntimeListRecipe) -> &'static RuntimeListRecipe::KOpt { .. } => "k_opt", RuntimeListRecipe::Ruin { .. } => "ruin", RuntimeListRecipe::MultiSwap { .. } => "multi_swap", + RuntimeListRecipe::GroupChange { .. } => "group_change", + RuntimeListRecipe::GroupSwap { .. } => "group_swap", + RuntimeListRecipe::GroupRuin { .. } => "group_ruin", } } diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/recipe_identity.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/recipe_identity.rs index ad200d30..1839abfa 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/recipe_identity.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/recipe_identity.rs @@ -7,7 +7,9 @@ use solverforge_core::score::Score; use solverforge_scoring::Director; use crate::heuristic::r#move::list_kernel::{ - change_candidate_trace_identity, change_tabu_signature, k_opt_tabu_signature, + change_candidate_trace_identity, change_tabu_signature, group_change_candidate_trace_identity, + group_change_tabu_signature, group_ruin_candidate_trace_identity, group_ruin_tabu_signature, + group_swap_candidate_trace_identity, group_swap_tabu_signature, k_opt_tabu_signature, multi_swap_tabu_signature, permute_candidate_trace_identity, permute_tabu_signature, reverse_candidate_trace_identity, reverse_tabu_signature, ruin_tabu_signature, sublist_change_candidate_trace_identity, sublist_change_tabu_signature, @@ -84,6 +86,17 @@ where coordinates, .. } => multi_swap_tabu_signature(access, coordinates, entity_indices, score_director), + RuntimeListRecipe::GroupChange { + access, + coordinates, + } => group_change_tabu_signature(access, coordinates, score_director), + RuntimeListRecipe::GroupSwap { + access, + coordinates, + } => group_swap_tabu_signature(access, coordinates, score_director), + RuntimeListRecipe::GroupRuin { access, plan } => { + group_ruin_tabu_signature(access, plan, score_director) + } } } @@ -164,6 +177,17 @@ where .iter() .flat_map(|&(entity, first, second)| [entity, first, second]), ), + RuntimeListRecipe::GroupChange { + access, + coordinates, + } => group_change_candidate_trace_identity(access, coordinates), + RuntimeListRecipe::GroupSwap { + access, + coordinates, + } => group_swap_candidate_trace_identity(access, coordinates), + RuntimeListRecipe::GroupRuin { access, plan } => { + group_ruin_candidate_trace_identity(access, plan) + } }; Some(identity) } diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/spec.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/spec.rs index 3ad886d3..490129d0 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/spec.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/spec.rs @@ -1,18 +1,21 @@ use std::fmt; use smallvec::SmallVec; +use std::num::NonZeroU8; + use solverforge_config::MoveSelectorConfig; use solverforge_core::domain::PlanningSolution; use crate::heuristic::r#move::list_kernel::{ - ChangeCoordinates, MultiSwapCoordinates, PermuteCoordinates, ReverseCoordinates, RuinSources, - SwapCoordinates, + ChangeCoordinates, GroupChangeCoordinates, GroupRuinPlan, GroupSwapCoordinates, + MultiSwapCoordinates, PermuteCoordinates, ReverseCoordinates, RuinSources, SwapCoordinates, }; use crate::heuristic::r#move::{ k_opt_reconnection::{enumerate_reconnections, KOptReconnection, THREE_OPT_RECONNECTIONS}, CutPoint, MAX_LIST_PERMUTE_WINDOW_SIZE, }; use crate::heuristic::r#move::{SegmentRelocationCoords, SegmentSwapCoords}; +use crate::list_groups::JointBounds; use crate::runtime::compiler::graph::ListLeafKind; use crate::runtime::compiler::types::CompiledListSlot; @@ -80,7 +83,13 @@ pub(super) enum RuntimeListNeighborhoodSpec { moves_per_step: usize, max_source_list_len: Option, skip_empty_destinations: bool, + /// Joint placement bounds for recreating element groups. + bounds: JointBounds, + }, + GroupChange { + max_member_distance: Option, }, + GroupSwap, } /// One owned move recipe emitted by the common list cursor. @@ -129,6 +138,18 @@ pub(crate) enum RuntimeListRecipe { coordinates: MultiSwapCoordinates, require_score_improvement: bool, }, + GroupChange { + access: RuntimeListMoveAccess, + coordinates: GroupChangeCoordinates, + }, + GroupSwap { + access: RuntimeListMoveAccess, + coordinates: GroupSwapCoordinates, + }, + GroupRuin { + access: RuntimeListMoveAccess, + plan: GroupRuinPlan, + }, } impl RuntimeListNeighborhoodPlan @@ -245,8 +266,21 @@ impl RuntimeListNeighborhoodSpec { moves_per_step: config.moves_per_step.unwrap_or(10), max_source_list_len: config.max_source_list_len, skip_empty_destinations: config.skip_empty_destinations, + bounds: JointBounds::from_config( + config.max_member_distance, + config.max_group_owners, + ), } } + ( + ListLeafKind::GroupChange, + MoveSelectorConfig::ListGroupChangeMoveSelector(config), + ) => Self::GroupChange { + max_member_distance: config.max_member_distance, + }, + (ListLeafKind::GroupSwap, MoveSelectorConfig::ListGroupSwapMoveSelector(_)) => { + Self::GroupSwap + } _ => return Err(RuntimeListNeighborhoodPlanError::ConfigFamilyMismatch { kind }), }; Ok(spec) diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests.rs index 3c9c9b28..3e663485 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests.rs @@ -1,6 +1,7 @@ //! Non-routed compiled list leaf regression coverage. mod clone_tracking; +mod groups; mod leaf_adapter; mod moves; mod parity; diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests/groups.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests/groups.rs new file mode 100644 index 00000000..6c6b5e94 --- /dev/null +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests/groups.rs @@ -0,0 +1,216 @@ +//! Group change, group swap, grouped ruin and the pinning of grouped +//! elements in the other list families. + +use std::num::NonZeroU8; + +use solverforge_config::{ + ListGroupChangeMoveConfig, ListRuinMoveSelectorConfig, MoveSelectorConfig, SelectionOrder, +}; + +use crate::heuristic::r#move::Move; +use crate::heuristic::selector::move_selector::{MoveCursor, MoveStreamContext}; + +use super::super::super::super::graph::ListLeafKind; +use super::super::spec::RuntimeListRecipe; +use super::super::{RuntimeListNeighborhoodPlan, RuntimeListNeighborhoodSelector}; +use super::support::{director, initial_plan, native_slot, ListPlan, PositionMetric, Slot}; + +/// Elements below `GROUPED` pair up as (0, 1), (2, 3); the rest are alone. +const GROUPED: usize = 8; + +fn pairs(_: &ListPlan, element: usize, members: &mut Vec) { + if element < GROUPED { + let first = element - element % 2; + members.extend([first, first + 1]); + } +} + +fn first_pair_only(_: &ListPlan, element: usize, members: &mut Vec) { + if element < 2 { + members.extend([0, 1]); + } +} + +fn grouped_slot(hook: fn(&ListPlan, usize, &mut Vec)) -> Slot { + Slot::from_static(native_slot().with_element_group_fn(Some(hook)), 0) +} + +type Selector = RuntimeListNeighborhoodSelector; + +fn selector(kind: ListLeafKind, config: MoveSelectorConfig, slot: Slot) -> Selector { + RuntimeListNeighborhoodSelector::new( + RuntimeListNeighborhoodPlan::from_compiled(kind, &config, vec![slot], Some(7)) + .expect("test list plan compiles"), + ) +} + +fn group_change(max_member_distance: Option) -> MoveSelectorConfig { + MoveSelectorConfig::ListGroupChangeMoveSelector(ListGroupChangeMoveConfig { + selection_order: Some(SelectionOrder::Original), + max_member_distance: max_member_distance.and_then(NonZeroU8::new), + ..ListGroupChangeMoveConfig::default() + }) +} + +/// Every pair sits on one route with its first member first. +fn assert_pairs_together(routes: &[Vec], pair_count: usize) { + for pair in 0..pair_count { + let (first, second) = (2 * pair, 2 * pair + 1); + let route = routes + .iter() + .find(|route| route.contains(&first)) + .expect("every element stays assigned"); + let first_position = route.iter().position(|&element| element == first).unwrap(); + let second_position = route.iter().position(|&element| element == second); + assert!( + second_position.is_some_and(|second_position| first_position < second_position), + "pair ({first}, {second}) split or reordered in {routes:?}" + ); + } + let mut all: Vec = routes.iter().flatten().copied().collect(); + all.sort_unstable(); + assert_eq!( + all, + (0..8).collect::>(), + "every element exactly once" + ); +} + +/// Applies and undoes every doable candidate; returns how many there were. +fn exercise(selector: &Selector, pair_count: usize, kind: &str) -> usize { + let mut score_director = director(initial_plan()); + let initial = score_director.working_solution().routes.clone(); + let mut stream_state = selector.new_stream_state(); + let mut cursor = selector.open_cursor_with_stream_state( + &mut stream_state, + &score_director, + MoveStreamContext::default(), + ); + let mut moves = Vec::new(); + while let Some(candidate) = cursor.next_owned_candidate(score_director.working_solution()) { + moves.push(candidate); + } + let mut doable = 0; + for candidate in moves { + if !candidate.is_doable(&score_director) { + continue; + } + doable += 1; + let undo = candidate.do_move(&mut score_director); + assert_pairs_together(&score_director.working_solution().routes, pair_count); + assert_ne!( + score_director.working_solution().routes, + initial, + "{kind} candidate {candidate:?} changed nothing" + ); + candidate.undo_move(&mut score_director, undo); + assert_eq!( + score_director.working_solution().routes, + initial, + "{kind} undo restores the lists" + ); + } + doable +} + +#[test] +fn group_change_moves_every_pair_jointly_to_every_placement() { + // Per pair: 5 other placements on its own route, 15 on the other one. + let all = selector( + ListLeafKind::GroupChange, + group_change(None), + grouped_slot(pairs), + ); + assert_eq!(exercise(&all, 4, "group change"), 4 * (5 + 15)); + // Adjacent members only: 2 on its own route, 5 on the other one. + let adjacent = selector( + ListLeafKind::GroupChange, + group_change(Some(1)), + grouped_slot(pairs), + ); + assert_eq!(exercise(&adjacent, 4, "adjacent group change"), 4 * (2 + 5)); +} + +#[test] +fn group_swap_exchanges_equal_groups_between_owners() { + let swap = selector( + ListLeafKind::GroupSwap, + MoveSelectorConfig::ListGroupSwapMoveSelector(Default::default()), + grouped_slot(pairs), + ); + // Pairs (0, 1) and (2, 3) on route 0 against (4, 5) and (6, 7). + assert_eq!(exercise(&swap, 4, "group swap"), 4); +} + +#[test] +fn grouped_ruin_takes_whole_groups_and_recreates_them_together() { + let ruin = selector( + ListLeafKind::Ruin, + MoveSelectorConfig::ListRuinMoveSelector(ListRuinMoveSelectorConfig { + min_ruin_count: 1, + max_ruin_count: 3, + moves_per_step: Some(12), + max_member_distance: NonZeroU8::new(2), + ..ListRuinMoveSelectorConfig::default() + }), + grouped_slot(first_pair_only), + ); + let mut score_director = director(initial_plan()); + let initial = score_director.working_solution().routes.clone(); + let mut stream_state = ruin.new_stream_state(); + let mut cursor = ruin.open_cursor_with_stream_state( + &mut stream_state, + &score_director, + MoveStreamContext::default(), + ); + let mut grouped_ruins = 0; + while let Some(candidate) = cursor.next_owned_candidate(score_director.working_solution()) { + let RuntimeListRecipe::GroupRuin { plan, .. } = candidate.clone().into_recipe() else { + panic!("a grouped slot ruins through grouped plans"); + }; + // A ruined member brings its partner along as one unit. + let ruined: Vec = plan + .removed + .iter() + .map(|&(entity, position)| initial[entity][position]) + .collect(); + if ruined.contains(&0) || ruined.contains(&1) { + grouped_ruins += 1; + assert!(ruined.contains(&0) && ruined.contains(&1), "{ruined:?}"); + } + assert!(candidate.is_doable(&score_director)); + let undo = candidate.do_move(&mut score_director); + assert_pairs_together(&score_director.working_solution().routes, 1); + candidate.undo_move(&mut score_director, undo); + assert_eq!(score_director.working_solution().routes, initial); + } + assert!(grouped_ruins > 0, "some ruin drew the pair"); +} + +#[test] +fn single_element_moves_keep_grouped_elements_on_their_owner() { + let change = selector( + ListLeafKind::Change, + super::support::config(ListLeafKind::Change), + grouped_slot(first_pair_only), + ); + let score_director = director(initial_plan()); + let mut stream_state = change.new_stream_state(); + let mut cursor = change.open_cursor_with_stream_state( + &mut stream_state, + &score_director, + MoveStreamContext::default(), + ); + let mut crossings = 0; + while let Some(candidate) = cursor.next_owned_candidate(score_director.working_solution()) { + let RuntimeListRecipe::Change { coordinates, .. } = candidate.into_recipe() else { + panic!("list change emits change recipes"); + }; + let element = initial_plan().routes[coordinates.source_entity][coordinates.source_position]; + if coordinates.source_entity != coordinates.destination_entity { + assert!(element >= 2, "grouped element {element} left its owner"); + crossings += 1; + } + } + assert!(crossings > 0, "ungrouped elements still change owner"); +} diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests/parity.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests/parity.rs index e10c6f13..89f18993 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests/parity.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests/parity.rs @@ -104,6 +104,11 @@ fn signatures( RuntimeListRecipe::MultiSwap { coordinates, .. } => { RecipeSignature::MultiSwap(coordinates.into_vec()) } + RuntimeListRecipe::GroupChange { .. } + | RuntimeListRecipe::GroupSwap { .. } + | RuntimeListRecipe::GroupRuin { .. } => { + unreachable!("parity fixtures declare no element groups") + } }; signatures.push(signature); } diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests/support.rs b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests/support.rs index 8d91aad7..374052ca 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests/support.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/list_leaf/tests/support.rs @@ -295,9 +295,23 @@ pub(super) fn config(kind: ListLeafKind) -> MoveSelectorConfig { moves_per_step: Some(3), max_source_list_len: None, skip_empty_destinations: false, + max_member_distance: None, + max_group_owners: None, target, }) } + ListLeafKind::GroupChange => MoveSelectorConfig::ListGroupChangeMoveSelector( + solverforge_config::ListGroupChangeMoveConfig { + target, + ..Default::default() + }, + ), + ListLeafKind::GroupSwap => MoveSelectorConfig::ListGroupSwapMoveSelector( + solverforge_config::ListGroupSwapMoveConfig { + target, + ..Default::default() + }, + ), } } diff --git a/crates/solverforge-solver/src/runtime/compiler/graph.rs b/crates/solverforge-solver/src/runtime/compiler/graph.rs index f7196b4c..ec29ebea 100644 --- a/crates/solverforge-solver/src/runtime/compiler/graph.rs +++ b/crates/solverforge-solver/src/runtime/compiler/graph.rs @@ -59,6 +59,8 @@ pub(crate) enum ListLeafKind { Reverse, KOpt, Ruin, + GroupChange, + GroupSwap, } /// Exhaustive compiled list-construction family. diff --git a/crates/solverforge-solver/src/runtime/compiler/selector_tree.rs b/crates/solverforge-solver/src/runtime/compiler/selector_tree.rs index d0a1b5d7..f644d5d7 100644 --- a/crates/solverforge-solver/src/runtime/compiler/selector_tree.rs +++ b/crates/solverforge-solver/src/runtime/compiler/selector_tree.rs @@ -221,6 +221,28 @@ where descriptor, model, )?), + MoveSelectorConfig::ListGroupChangeMoveSelector(selector) => { + builder.push(compile_list_leaf( + ListLeafKind::GroupChange, + config, + candidate_order, + candidate_metric.clone(), + &selector.target, + path, + descriptor, + model, + )?) + } + MoveSelectorConfig::ListGroupSwapMoveSelector(selector) => builder.push(compile_list_leaf( + ListLeafKind::GroupSwap, + config, + candidate_order, + candidate_metric.clone(), + &selector.target, + path, + descriptor, + model, + )?), MoveSelectorConfig::GroupedScalarMoveSelector(grouped) => { compile_grouped_or_provider_selector( config, diff --git a/crates/solverforge-solver/src/runtime/compiler/selector_values.rs b/crates/solverforge-solver/src/runtime/compiler/selector_values.rs index 81451158..45d72c8c 100644 --- a/crates/solverforge-solver/src/runtime/compiler/selector_values.rs +++ b/crates/solverforge-solver/src/runtime/compiler/selector_values.rs @@ -94,6 +94,26 @@ fn validate_construction( "applies only to `list_clarke_wright` construction".to_string(), )); } + if !matches!( + config.construction_heuristic_type, + ConstructionHeuristicType::ListCheapestInsertion + | ConstructionHeuristicType::ListRegretInsertion + ) { + for (field, set) in [ + ("max_member_distance", config.max_member_distance.is_some()), + ("max_group_owners", config.max_group_owners.is_some()), + ] { + if set { + return Err(invalid( + path, + field, + "applies only to `list_cheapest_insertion` and `list_regret_insertion` \ + construction" + .to_string(), + )); + } + } + } positive_limit(path, "value_candidate_limit", config.value_candidate_limit)?; positive_limit(path, "group_candidate_limit", config.group_candidate_limit) } @@ -197,6 +217,8 @@ fn validate_selector(config: &MoveSelectorConfig, path: &str) -> Result<(), Runt config.max_moves_per_step, ), MoveSelectorConfig::SwapMoveSelector(_) + | MoveSelectorConfig::ListGroupChangeMoveSelector(_) + | MoveSelectorConfig::ListGroupSwapMoveSelector(_) | MoveSelectorConfig::ListChangeMoveSelector(_) | MoveSelectorConfig::ListSwapMoveSelector(_) | MoveSelectorConfig::ListPrecedenceMoveSelector(_) diff --git a/crates/solverforge-solver/src/runtime/compiler/slots.rs b/crates/solverforge-solver/src/runtime/compiler/slots.rs index b982820c..7f74135e 100644 --- a/crates/solverforge-solver/src/runtime/compiler/slots.rs +++ b/crates/solverforge-solver/src/runtime/compiler/slots.rs @@ -267,6 +267,7 @@ pub(super) fn require_list_capability( RuntimeCapability::ListRoute => ListAccessCapability::Route, RuntimeCapability::ListSavings => ListAccessCapability::Savings, RuntimeCapability::ListSavingsNeighbors => ListAccessCapability::SavingsNeighbors, + RuntimeCapability::ListElementGroups => ListAccessCapability::ElementGroups, _ => unreachable!("list capability validation received a scalar capability"), }; if let Some(slot) = slots.iter().find(|slot| !slot.supports(access_capability)) { @@ -346,7 +347,17 @@ where )?; let mut required = Vec::new(); match kind { - ListLeafKind::Change | ListLeafKind::Ruin => {} + ListLeafKind::Change => {} + ListLeafKind::Ruin => { + if let MoveSelectorConfig::ListRuinMoveSelector(ruin) = config { + if ruin.max_member_distance.is_some() || ruin.max_group_owners.is_some() { + required.push(RuntimeCapability::ListElementGroups); + } + } + } + ListLeafKind::GroupChange | ListLeafKind::GroupSwap => { + required.push(RuntimeCapability::ListElementGroups) + } ListLeafKind::NearbyChange => { required.push(RuntimeCapability::ListCrossPositionDistance); } diff --git a/crates/solverforge-solver/src/runtime/compiler/types.rs b/crates/solverforge-solver/src/runtime/compiler/types.rs index cfd57337..fdd1afdd 100644 --- a/crates/solverforge-solver/src/runtime/compiler/types.rs +++ b/crates/solverforge-solver/src/runtime/compiler/types.rs @@ -50,6 +50,7 @@ pub(crate) enum RuntimeCapability { ListRoute, ListSavings, ListSavingsNeighbors, + ListElementGroups, } impl fmt::Display for RuntimeCapability { @@ -69,6 +70,7 @@ impl fmt::Display for RuntimeCapability { Self::ListRoute => "route bundle (read/replace/depot/distance/feasible)", Self::ListSavings => "savings bundle (replace/depot/metric_class/distance/feasible)", Self::ListSavingsNeighbors => "savings neighbour source (savings_neighbors_fn)", + Self::ListElementGroups => "list element groups (element_group_fn)", }; f.write_str(name) } diff --git a/crates/solverforge/tests/list_element_groups.rs b/crates/solverforge/tests/list_element_groups.rs new file mode 100644 index 00000000..35033d80 --- /dev/null +++ b/crates/solverforge/tests/list_element_groups.rs @@ -0,0 +1,113 @@ +//! A pick-up and its drop-off form one element group: construction places +//! them together, and group change, group swap and grouped ruin move them +//! together, keeping the pick-up first. + +#[path = "list_element_groups/domain/mod.rs"] +mod domain; + +use domain::{Deliveries, Stop, Vehicle}; +use solverforge::{SolverEvent, SolverManager, SolverTerminalReason}; + +fn stop(id: usize, job: Option, pickup: bool, location: i64) -> Stop { + Stop { + id, + job, + pickup, + location, + vehicle: None, + index: None, + previous: None, + } +} + +/// Six jobs whose drop-offs lie far from their pick-ups, then three single +/// stops; nothing is assigned. +fn deliveries(scenario: usize) -> Deliveries { + let routes = [(5, 60), (70, 12), (33, 90), (8, 41), (95, 20), (50, 52)]; + let mut stops = Vec::new(); + for (job, (from, to)) in routes.into_iter().enumerate() { + stops.push(stop(2 * job, Some(job), true, from)); + stops.push(stop(2 * job + 1, Some(job), false, to)); + } + for (offset, location) in [25, 77, 64].into_iter().enumerate() { + stops.push(stop(12 + offset, None, false, location)); + } + Deliveries { + vehicles: (0..3) + .map(|id| Vehicle { + id, + stops: Vec::new(), + }) + .collect(), + stops, + score: None, + scenario, + } +} + +fn solve(plan: Deliveries) -> Result { + static MANAGER: SolverManager = SolverManager::new(); + let (_, mut receiver) = MANAGER.solve(plan).map_err(|error| error.to_string())?; + while let Some(event) = receiver.blocking_recv() { + match event { + SolverEvent::Completed { metadata, solution } => { + assert!(matches!( + metadata.terminal_reason, + Some( + SolverTerminalReason::Completed | SolverTerminalReason::TerminatedByConfig + ) + )); + return Ok(solution); + } + SolverEvent::Failed { error, .. } => return Err(error.to_string()), + _ => {} + } + } + Err("the solve ended without a result".to_string()) +} + +/// Every stop on exactly one vehicle; each job on one vehicle, pick-up first. +fn assert_jobs_intact(solved: &Deliveries) { + let mut seen: Vec = solved + .vehicles + .iter() + .flat_map(|vehicle| vehicle.stops.iter().copied()) + .collect(); + seen.sort_unstable(); + assert_eq!(seen, (0..solved.stops.len()).collect::>()); + for job in 0..6 { + let vehicle = solved + .vehicles + .iter() + .find(|vehicle| vehicle.stops.contains(&(2 * job))) + .expect("every pick-up is assigned"); + let at = |stop| vehicle.stops.iter().position(|&made| made == stop); + assert!( + at(2 * job + 1).is_some_and(|dropoff| at(2 * job).unwrap() < dropoff), + "job {job} split or reversed: {:?}", + solved.vehicles.iter().map(|v| &v.stops).collect::>() + ); + } + assert_eq!(solved.score.map(|score| score.hard()), Some(0)); +} + +#[test] +fn default_construction_and_search_keep_every_job_together() { + let solved = solve(deliveries(0)).expect("the default solve completes"); + assert_jobs_intact(&solved); +} + +#[test] +fn regret_construction_and_group_moves_keep_every_job_together() { + let solved = solve(deliveries(1)).expect("the explicit solve completes"); + assert_jobs_intact(&solved); +} + +#[test] +fn round_robin_construction_is_rejected_for_element_groups() { + let error = solve(deliveries(2)).expect_err("round robin would split jobs"); + assert!( + error.contains("element groups"), + "unexpected error: {error}" + ); +} diff --git a/crates/solverforge/tests/list_element_groups/domain/deliveries.rs b/crates/solverforge/tests/list_element_groups/domain/deliveries.rs new file mode 100644 index 00000000..a1074893 --- /dev/null +++ b/crates/solverforge/tests/list_element_groups/domain/deliveries.rs @@ -0,0 +1,129 @@ +use solverforge::prelude::*; +use solverforge::stream::joiner::equal_bi; +use solverforge::stream::ConstraintFactory; +use solverforge::SolverConfig; + +use super::{Stop, Vehicle}; + +/// Vehicles carrying jobs from a pick-up to a drop-off. +#[planning_solution(constraints = "define_constraints", config = "deliveries_config")] +#[shadow_variable_updates( + list_owner = "vehicles", + inverse_field = "vehicle", + index_field = "index", + previous_field = "previous" +)] +pub struct Deliveries { + /// The vehicles. + #[planning_entity_collection] + pub vehicles: Vec, + + /// The stops: every job's pick-up and drop-off, then single stops. + #[problem_fact_collection] + pub stops: Vec, + + /// The plan's score. + #[planning_score] + pub score: Option, + + /// Which solver configuration the fixture runs. + pub scenario: usize, +} + +/// Every stop is made; a job stays on one vehicle with its pick-up first; +/// driving distance is soft. +pub fn define_constraints() -> impl ConstraintSet { + ( + ConstraintFactory::::new() + .for_each(Deliveries::stops()) + .filter(|stop: &Stop| stop.vehicle.is_none()) + .penalize(HardSoftScore::ONE_HARD) + .named("unassigned stop"), + ConstraintFactory::::new() + .for_each(Deliveries::stops()) + .filter(|stop: &Stop| stop.pickup) + .join(( + ConstraintFactory::::new() + .for_each(Deliveries::stops()), + equal_bi(|pickup: &Stop| pickup.job, |stop: &Stop| stop.job), + )) + .filter(|pickup: &Stop, dropoff: &Stop| { + !dropoff.pickup + && (pickup.vehicle != dropoff.vehicle || pickup.index > dropoff.index) + }) + .penalize(HardSoftScore::ONE_HARD) + .named("broken job"), + ConstraintFactory::::new() + .for_each(Deliveries::stops()) + .join(( + ConstraintFactory::::new() + .for_each(Deliveries::stops()), + equal_bi(|stop: &Stop| stop.previous, |before: &Stop| Some(before.id)), + )) + .penalize(|stop: &Stop, before: &Stop| { + HardSoftScore::of_soft((stop.location - before.location).abs()) + }) + .named("driving"), + ConstraintFactory::::new() + .for_each(Deliveries::stops()) + .filter(|stop: &Stop| stop.vehicle.is_some() && stop.previous.is_none()) + .penalize(|stop: &Stop| HardSoftScore::of_soft(stop.location.abs())) + .named("leaving the depot"), + ) +} + +// Every scenario checks each incremental score against a fresh one. +const DEFAULTS: &str = r#" +environment_mode = "full_assert" +random_seed = 11 + +[termination] +step_count_limit = 40 +"#; + +const EXPLICIT: &str = r#" +environment_mode = "full_assert" +random_seed = 13 + +[[phases]] +type = "construction_heuristic" +construction_heuristic_type = "list_regret_insertion" +max_member_distance = 3 + +[[phases]] +type = "local_search" + +[phases.move_selector] +type = "union_move_selector" + +[[phases.move_selector.selectors]] +type = "list_group_change_move_selector" +max_member_distance = 4 + +[[phases.move_selector.selectors]] +type = "list_group_swap_move_selector" + +[[phases.move_selector.selectors]] +type = "list_ruin_move_selector" +min_ruin_count = 1 +max_ruin_count = 3 +moves_per_step = 4 +max_group_owners = 1 + +[[phases.move_selector.selectors]] +type = "list_change_move_selector" + +[phases.termination] +step_count_limit = 40 +"#; + +const ROUND_ROBIN: &str = r#" +[[phases]] +type = "construction_heuristic" +construction_heuristic_type = "list_round_robin" +"#; + +fn deliveries_config(plan: &Deliveries, _base: SolverConfig) -> SolverConfig { + let toml = [DEFAULTS, EXPLICIT, ROUND_ROBIN][plan.scenario]; + SolverConfig::from_toml_str(toml).expect("deliveries fixture config must parse") +} diff --git a/crates/solverforge/tests/list_element_groups/domain/mod.rs b/crates/solverforge/tests/list_element_groups/domain/mod.rs new file mode 100644 index 00000000..714bdc9e --- /dev/null +++ b/crates/solverforge/tests/list_element_groups/domain/mod.rs @@ -0,0 +1,11 @@ +solverforge::planning_model! { + root = "crates/solverforge/tests/list_element_groups/domain"; + + mod deliveries; + mod stop; + mod vehicle; + + pub use deliveries::Deliveries; + pub use stop::Stop; + pub use vehicle::Vehicle; +} diff --git a/crates/solverforge/tests/list_element_groups/domain/stop.rs b/crates/solverforge/tests/list_element_groups/domain/stop.rs new file mode 100644 index 00000000..37b9536e --- /dev/null +++ b/crates/solverforge/tests/list_element_groups/domain/stop.rs @@ -0,0 +1,21 @@ +use solverforge::prelude::*; + +/// A pick-up, a drop-off, or a single stop on a line. +#[problem_fact] +pub struct Stop { + /// Stable stop id; job `j` is stops `2j` (pick-up) and `2j + 1`. + #[planning_id] + pub id: usize, + /// The job the stop belongs to, if any. + pub job: Option, + /// Whether the stop is its job's pick-up. + pub pickup: bool, + /// Where the stop is. + pub location: i64, + /// The vehicle making the stop (list shadow). + pub vehicle: Option, + /// The stop's position on its vehicle (list shadow). + pub index: Option, + /// The stop before this one on its vehicle (list shadow). + pub previous: Option, +} diff --git a/crates/solverforge/tests/list_element_groups/domain/vehicle.rs b/crates/solverforge/tests/list_element_groups/domain/vehicle.rs new file mode 100644 index 00000000..e05901ca --- /dev/null +++ b/crates/solverforge/tests/list_element_groups/domain/vehicle.rs @@ -0,0 +1,22 @@ +use solverforge::prelude::*; + +// readme:begin +/// A vehicle that drives to its stops in list order. +#[planning_entity] +pub struct Vehicle { + /// Stable vehicle id. + #[planning_id] + pub id: usize, + + /// The stops the vehicle makes, in order. + #[planning_list_variable(element_collection = "stops", element_group_fn = "job_stops")] + pub stops: Vec, +} + +/// A job's pick-up and drop-off, in that order; a single stop has no group. +pub(super) fn job_stops(plan: &super::Deliveries, stop: usize, members: &mut Vec) { + if let Some(job) = plan.stops[stop].job { + members.extend([2 * job, 2 * job + 1]); + } +} +// readme:end diff --git a/crates/solverforge/tests/readme_examples.rs b/crates/solverforge/tests/readme_examples.rs index 41423486..ec6a5527 100644 --- a/crates/solverforge/tests/readme_examples.rs +++ b/crates/solverforge/tests/readme_examples.rs @@ -12,6 +12,8 @@ mod crew; #[path = "readme_examples/nurses/mod.rs"] mod nurses; +#[path = "list_element_groups/domain/mod.rs"] +mod pickup_delivery; #[path = "readme_examples/routes/mod.rs"] mod routes; #[path = "readme_examples/shop/mod.rs"] @@ -74,6 +76,10 @@ const SOURCES: &[(&str, &str)] = &[ include_str!("readme_examples/configured.rs"), ), ("crew/plan.rs", include_str!("readme_examples/crew/plan.rs")), + ( + "list_element_groups/domain/vehicle.rs", + include_str!("list_element_groups/domain/vehicle.rs"), + ), ("manager.rs", include_str!("readme_examples/manager.rs")), ( "night_shift.rs", diff --git a/docs/configuration.md b/docs/configuration.md index 1993f331..0eb6bea4 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -115,6 +115,7 @@ Each list slot gets the first construction whose declarations it has: | Slot declares | Construction | Reported `reason` | |---|---|---| +| element groups (`element_group_fn`) | `ListCheapestInsertion` with `max_group_owners = 4` | `element_groups_declared` | | savings hooks (`domain = "cvrp"` or `savings_hooks`) | `ListClarkeWright` | `savings_hooks_declared` | | precedence, construction order and ownership | `ListRegretInsertion` | `precedence_construction_order_and_ownership_declared` | | precedence and construction order | `ListRoundRobin` | `precedence_and_construction_order_declared` | @@ -153,15 +154,17 @@ neighborhoods: scalar selector. Generic scalar selectors and conflict-repair defaults leave group-owned slots alone. - **List slots** get capability-matched families in a fixed order: - 1. precedence repair plus list permutation, when the complete precedence move + 1. group change plus group swap, when the slot declares element groups; + 2. precedence repair plus list permutation, when the complete precedence move bundle exists; - 2. nearby change, plus nearby swap when set access exists, with a limit of + 3. nearby change, plus nearby swap when set access exists, with a limit of 20, when a cross-position metric exists; - 3. otherwise plain change, plus plain swap when set access exists; - 4. sublist, reverse and k-opt families, only when their required operations + 4. otherwise plain change, plus plain swap when set access exists; + 5. sublist, reverse and k-opt families, only when their required operations are declared. K-opt uses the nearby metric when available and the unbounded form otherwise; - 5. list ruin for every bound list slot. + 6. list ruin for every bound list slot; a slot with element groups gets its + own ruin with `max_member_distance = 7` and `max_group_owners = 4`. - **Mixed models** declare list families first, then nearby scalar, grouped scalar, compound conflict-repair and ordinary scalar families. @@ -223,13 +226,13 @@ type = "change_move_selector" | Area | What ships (selectors by their `type` key in `solver.toml`) | |------|------------| -| Construction | `FirstFit` and `CheapestInsertion` through one compiled runtime graph: scalar-only targets use its descriptor-placement schedule, mixed and list-bearing targets its declaration-order global scan. Specialized list phases: `ListRoundRobin`, `ListCheapestInsertion`, `ListRegretInsertion`, owner-aware `ListClarkeWright`, `ListKOpt` | +| Construction | `FirstFit` and `CheapestInsertion` through one compiled runtime graph: scalar-only targets use its descriptor-placement schedule, mixed and list-bearing targets its declaration-order global scan. Specialized list phases: `ListRoundRobin`, `ListCheapestInsertion` and `ListRegretInsertion` (both placing element groups jointly), owner-aware `ListClarkeWright`, `ListKOpt` | | Grouped scalar construction | Named `ScalarGroup` declarations, candidate-backed compound edits, assignment-backed nullable construction with required-slot handling, capacity repair and ordering hooks | | Local search | `acceptor_forager` with Hill Climbing, Simulated Annealing (level-aware), Tabu Search, Late Acceptance, Great Deluge, Step Counting Hill Climbing or Diversified Late Acceptance; or `variable_neighborhood_descent` with ordered neighborhoods | | Exhaustive search | Exact search over small finite scalar spaces | | Partitioned search | Explicit user-defined decomposition with optional Rayon parallelism, see [Extend the solver](extend-solver.md#partitioned-search) | | Scalar selectors | `change_move_selector`, `swap_move_selector`, `nearby_change_move_selector`, `nearby_swap_move_selector`, `pillar_change_move_selector`, `pillar_swap_move_selector`, `ruin_recreate_move_selector`, `grouped_scalar_move_selector`, `conflict_repair_move_selector`, `compound_conflict_repair_move_selector` | -| List selectors | `list_change_move_selector`, `nearby_list_change_move_selector`, `list_swap_move_selector`, `nearby_list_swap_move_selector`, `list_permute_move_selector`, `list_precedence_move_selector`, `sublist_change_move_selector`, `sublist_swap_move_selector`, `list_reverse_move_selector`, `k_opt_move_selector`, `list_ruin_move_selector` | +| List selectors | `list_change_move_selector`, `nearby_list_change_move_selector`, `list_swap_move_selector`, `nearby_list_swap_move_selector`, `list_permute_move_selector`, `list_precedence_move_selector`, `sublist_change_move_selector`, `sublist_swap_move_selector`, `list_reverse_move_selector`, `k_opt_move_selector`, `list_ruin_move_selector`, `list_group_change_move_selector`, `list_group_swap_move_selector` | | Composition | `union_move_selector`, `cartesian_product_move_selector`, `limited_neighborhood`; native and host-backed compound scalar moves; nearby selection for scalar and list neighborhoods | ### Bounded Clarke-Wright savings @@ -255,6 +258,32 @@ Without the setting, savings, their order and the merges are unchanged, and a bound of at least the element count minus one gives the same routes as no bound. +### Element groups + +A list variable with `element_group_fn` (see +[Modeling](modeling.md#element-groups)) is constructed by +`list_cheapest_insertion` by default, with `max_group_owners = 4`. Both +insertion heuristics accept the joint-placement bounds: + +```toml +[[phases]] +type = "construction_heuristic" +construction_heuristic_type = "list_regret_insertion" +max_member_distance = 5 +max_group_owners = 6 +``` + +`max_member_distance` caps the positions from one member of a group to the +next (`1` keeps members adjacent), and `max_group_owners` tries every +placement only on that many owners, the ones where the group fits best +contiguously. Both take 1 to 255; omitted, each is unbounded. +Other heuristics, and lists without groups, reject both keys. + +Local search moves groups through `list_group_change_move_selector` +(`max_member_distance`) and `list_group_swap_move_selector`, and +`list_ruin_move_selector` takes the same two bounds for its joint recreate. +These selectors, and ruin bounds, require a targeted list with element groups. + The configuration surface also covers bounded candidate tracing, per-selector ordering and host metrics, weighted union scheduling, score tie-breaking, and grouped scalar and conflict-repair selectors. diff --git a/docs/modeling.md b/docs/modeling.md index 2f2b0c51..5c8177bb 100644 --- a/docs/modeling.md +++ b/docs/modeling.md @@ -276,6 +276,67 @@ from the manifest root module. Construction, Clarke-Wright construction, ruin/recreate and owner-changing list neighborhoods honor the hook. Moves that only reorder within one owner stay available. +### Element groups + +Some elements must travel together: the pick-up and drop-off of one job, or +every stop of a multi-stop job. Declare them with +`#[planning_list_variable(element_collection = "...", element_group_fn = "...")]`. +The hook has the signature `fn(&Solution, usize, &mut Vec)` and appends +the members of the element's group, in order and including the element, or +nothing for an element without a group: + +```rust +/// A vehicle that drives to its stops in list order. +#[planning_entity] +pub struct Vehicle { + /// Stable vehicle id. + #[planning_id] + pub id: usize, + + /// The stops the vehicle makes, in order. + #[planning_list_variable(element_collection = "stops", element_group_fn = "job_stops")] + pub stops: Vec, +} + +/// A job's pick-up and drop-off, in that order; a single stop has no group. +pub(super) fn job_stops(plan: &super::Deliveries, stop: usize, members: &mut Vec) { + if let Some(job) = plan.stops[stop].job { + members.extend([2 * job, 2 * job + 1]); + } +} +``` + +Only groups of two or more members count, and every member must report the +same group; a conflicting answer panics. Groups are read once per step and +once per construction phase. + +A group's members share one owner and keep their declared order. Other +elements may sit between them, as a shared ride needs: + +- `list_group_change_move_selector` moves a whole group to positions of one + owner, its own included; `max_member_distance` caps the positions from + one member to the next. +- `list_group_swap_move_selector` exchanges two groups of the same size on + different owners, member slot for member slot. +- `list_ruin_move_selector` ruins whole groups and recreates each group + jointly, choosing all of its members' positions together. +- `list_cheapest_insertion` and `list_regret_insertion` place a group as one + unit. A member is never placed alone; members already assigned pin the rest + of their group to that owner. +- The single-element list moves keep a grouped element on its owner, so they + can still reorder it within its route but never split a group. + +A group moves only to an owner that every member allows under +`element_owner_fn` and that is not pinned. Joint placement of a group of `m` +members tries O(L^m) position tuples per owner; `max_member_distance` and +`max_group_owners` (an owner shortlist, by best contiguous fit) bound it. See +[Configuration](configuration.md#element-groups) for the defaults. + +`element_group_fn` cannot be combined with precedence hooks, and +`list_round_robin`, `list_clarke_wright` and the global `first_fit` and +`cheapest_insertion` construction reject a list with groups, since they place +elements one at a time. A list without the hook compiles none of this. + ### Source identity in list construction Cheapest insertion, regret insertion and Clarke-Wright key every declared