diff --git a/AGENTS.md b/AGENTS.md index 87435c64..22fdc99b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -301,6 +301,10 @@ runs: - The descriptor-placement scalar construction placer (`RuntimeScalarConstructionPlacer`) and the compiled runtime phase runner that solves first-fit construction. +- Route moves executed against a scored model: the score director's + cascading list-shadow row maintenance (`route_rows`), and grouped list + ruin-and-recreate with joint placement of each element group + (`group_ruin`), each candidate done, scored and undone. The standalone `heuristic/selector` selectors, decorators, and `QueuedEntityPlacer` are test oracles only; no production path runs them. diff --git a/crates/solverforge-core/WIREFRAME.md b/crates/solverforge-core/WIREFRAME.md index 7df4b59f..7bdba0d7 100644 --- a/crates/solverforge-core/WIREFRAME.md +++ b/crates/solverforge-core/WIREFRAME.md @@ -161,6 +161,7 @@ Additionally, `pub mod constraint`, `pub mod constraint_weights`, `pub mod domai | `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 | +| `list_structure_unchanged` | `fn list_structure_unchanged(&self, element: usize, owner_descriptor: usize, owner_index: usize, index: usize, previous: Option, next: Option) -> bool` | Default: `false`; whether the element's owner, previous and next (and index, when declared) shadows already hold the given place. A score director with a cascading shadow asks it before rewriting an owner's structure and keeps the row of an element that answers `true` and whose cascading value is unchanged | | `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 | diff --git a/crates/solverforge-core/public-api.txt b/crates/solverforge-core/public-api.txt index 29752b59..d9a3bafd 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 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 { ... } } +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 18 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 list_structure_unchanged( &self, _element: usize, _owner_descriptor: usize, _owner_index: usize, _index: usize, _previous: Option, _next: Option, ) -> bool { ... } 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 @@ -313,6 +313,7 @@ trait domain::PlanningSolution: pub trait PlanningSolution: Clone + Send + Sync 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 list_structure_unchanged( &self, _element: usize, _owner_descriptor: usize, _owner_index: usize, _index: usize, _previous: Option, _next: Option, ) -> bool 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/traits.rs b/crates/solverforge-core/src/domain/traits.rs index 58878a16..851344fb 100644 --- a/crates/solverforge-core/src/domain/traits.rs +++ b/crates/solverforge-core/src/domain/traits.rs @@ -157,6 +157,28 @@ pub trait PlanningSolution: Clone + Send + Sync + 'static { /// never change them. fn cascading_peers(&self, _element: usize, _peers: &mut Vec) {} + /// Whether `element`'s list structure shadows already describe the place + /// `owner_descriptor`/`owner_index`, position `index`, between `previous` + /// and `next`: its owner, previous and next shadows (and index shadow, + /// when declared) hold those values. + /// + /// A score director with a cascading shadow asks this before rewriting an + /// owner's structure and keeps the stream row of an element that answers + /// `true` and whose cascading value does not change. `false` (the default) + /// rescores the element. `#[shadow_variable_updates(cascading_field = + /// ...)]` generates it from the configured structure fields. + fn list_structure_unchanged( + &self, + _element: usize, + _owner_descriptor: usize, + _owner_index: usize, + _index: usize, + _previous: Option, + _next: Option, + ) -> bool { + false + } + /// 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 319d5428..967c10cb 100644 --- a/crates/solverforge-macros/WIREFRAME.md +++ b/crates/solverforge-macros/WIREFRAME.md @@ -397,7 +397,8 @@ element shadows score incrementally. With `cascading_field`, the generated support sets `PlanningSolution::HAS_CASCADING_SHADOWS = true` and implements the -`cascading_*` hooks, `update_cascading_shadow` and +`cascading_*` hooks, `list_structure_unchanged` (comparing the inverse, +previous, next and, when configured, index fields), `update_cascading_shadow` and `update_list_structure_shadows` (the owner update without the cascading shadow). `update_entity_shadows` refreshes the owner's structure, then propagates the cascading values from its elements with `CascadePropagation`; diff --git a/crates/solverforge-macros/src/planning_model/cascade.rs b/crates/solverforge-macros/src/planning_model/cascade.rs index 145bc97e..4573ac02 100644 --- a/crates/solverforge-macros/src/planning_model/cascade.rs +++ b/crates/solverforge-macros/src/planning_model/cascade.rs @@ -7,6 +7,8 @@ propagation itself, its ordering and its change reporting are SolverForge's. struct CascadeContext<'a> { solution_path: &'a TokenStream, + // The list owner's descriptor index. + descriptor_index: usize, element_accessor: &'a Ident, element_mut_accessor: &'a Ident, } @@ -53,6 +55,7 @@ fn generate_cascade_hooks(config: &ShadowConfig, context: &CascadeContext<'_>) - let span = proc_macro2::Span::call_site(); let CascadeContext { solution_path, + descriptor_index, element_accessor, element_mut_accessor, } = context; @@ -60,6 +63,15 @@ fn generate_cascade_hooks(config: &ShadowConfig, context: &CascadeContext<'_>) - let compute = Ident::new(config.cascading_compute.as_deref().unwrap(), span); let inverse = Ident::new(config.inverse_field.as_deref().unwrap(), span); let next = Ident::new(config.next_field.as_deref().unwrap(), span); + let previous = Ident::new(config.previous_field.as_deref().unwrap(), span); + let index_matches = config + .index_field + .as_deref() + .map(|field| { + let field = Ident::new(field, span); + quote! { && stored.#field == ::core::option::Option::Some(index) } + }) + .unwrap_or_default(); let dependencies = config .cascading_dependencies .as_deref() @@ -103,6 +115,24 @@ fn generate_cascade_hooks(config: &ShadowConfig, context: &CascadeContext<'_>) - #peers } + #[allow(unused_variables)] + fn list_structure_unchanged( + solution: &Self, + element: usize, + owner_descriptor: usize, + owner_index: usize, + index: usize, + previous: ::core::option::Option, + next: ::core::option::Option, + ) -> bool { + let stored = &#solution_path::#element_accessor(solution)[element]; + owner_descriptor == #descriptor_index + && stored.#inverse == ::core::option::Option::Some(owner_index) + && stored.#previous == previous + && stored.#next == next + #index_matches + } + 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/shadows.rs b/crates/solverforge-macros/src/planning_model/shadows.rs index 43e008e6..1a789912 100644 --- a/crates/solverforge-macros/src/planning_model/shadows.rs +++ b/crates/solverforge-macros/src/planning_model/shadows.rs @@ -308,6 +308,7 @@ fn generate_list_shadow_update( config, &CascadeContext { solution_path, + descriptor_index, element_accessor: &element_accessor, element_mut_accessor: &element_mut_accessor, }, diff --git a/crates/solverforge-macros/src/planning_solution/shadow.rs b/crates/solverforge-macros/src/planning_solution/shadow.rs index fb022678..91df1a9c 100644 --- a/crates/solverforge-macros/src/planning_solution/shadow.rs +++ b/crates/solverforge-macros/src/planning_solution/shadow.rs @@ -71,6 +71,27 @@ pub(super) fn generate_shadow_support( ) } + #[inline] + fn list_structure_unchanged( + &self, + element: usize, + owner_descriptor: usize, + owner_index: usize, + index: usize, + previous: ::core::option::Option, + next: ::core::option::Option, + ) -> bool { + ::list_structure_unchanged( + self, + element, + owner_descriptor, + owner_index, + index, + previous, + next, + ) + } + #[inline] fn cascading_unset(&self, element: usize) -> bool { ::cascading_unset(self, element) diff --git a/crates/solverforge-scoring/WIREFRAME.md b/crates/solverforge-scoring/WIREFRAME.md index dc4de5e2..6e2a207b 100644 --- a/crates/solverforge-scoring/WIREFRAME.md +++ b/crates/solverforge-scoring/WIREFRAME.md @@ -250,7 +250,7 @@ src/ │ │ ├── score_director/incremental.rs — ScoreDirector (zero-erasure incremental) │ │ ├── score_director/constructors.rs — ScoreDirector constructors, weighted constructors, replica-forking constructors, into_weight_mode │ │ ├── score_director/descriptor.rs — DirectorDescriptor (owned or borrowed SolutionDescriptor) -│ │ ├── score_director/list_shadows.rs — Retract/insert of list-shadowed element rows around owner shadow updates +│ │ ├── score_director/list_shadows.rs — Retract/insert of list-shadowed element rows around owner shadow updates; with a cascading shadow, only rows whose structure or cascading value changes │ │ ├── score_director/weight_mode.rs — WeightMode (sealed), UnweightedMode, WeightedMode, requires_weighted_mode, static per-mode scoring dispatch │ │ ├── score_director/analysis.rs — ScoreDirector constraint_results/constraint_analyses/constraint_match_totals │ │ └── score_director/adapters.rs — Debug and Director trait impls for ScoreDirector @@ -501,14 +501,20 @@ inserts the owner and every element it now holds, and clears and re-inserts elements that left the owner without joining another list. Element rows therefore always hold the shadows they were inserted with. -When `S::HAS_CASCADING_SHADOWS` is `true`, element rows are deferred to the -end of the move: each `after_variable_changed` refreshes only the owner's list -structure (`update_list_structure_shadows`) and inserts the owner, and when the -move's last notified owner has been refreshed the director propagates the -cascading values (`CascadePropagation`) from every element those owners held -before or after the move. An element written during propagation is retracted -before its write unless it is already pending, and every pending element is -inserted once. The branch is on the associated constant, so other solutions +When `S::HAS_CASCADING_SHADOWS` is `true`, only rows whose shadows change are +rescored, and they are deferred to the end of the move. +`before_variable_changed` records the elements the owner holds and retracts +no element row. Each `after_variable_changed` retracts the rows of the +owner's elements whose structure shadows do not already describe their new +place (`list_structure_unchanged`, asked before the rewrite), arrivals from +no list included, then +refreshes only the owner's list structure (`update_list_structure_shadows`) +and inserts the owner. When the move's last notified owner has been +refreshed, an element that was held and is now in no list is retracted and +cleared, the director propagates the cascading values (`CascadePropagation`) +from the retracted elements, an element written during propagation is +retracted before its write unless it is already pending, and every pending +element is inserted once. The branch is on the associated constant, so other solutions compile none of it. ### `SolvableSolution` — `: PlanningSolution` diff --git a/crates/solverforge-scoring/src/director/score_director/incremental.rs b/crates/solverforge-scoring/src/director/score_director/incremental.rs index c1d43af9..1b4da1b6 100644 --- a/crates/solverforge-scoring/src/director/score_director/incremental.rs +++ b/crates/solverforge-scoring/src/director/score_director/incremental.rs @@ -208,19 +208,24 @@ where entity_index, descriptor_index, ); - let element_delta = self.list_shadow_rows.retract_held( - &self.working_solution, - &mut ModeRows { - constraints: &mut self.constraints, - mode: &self.weight_mode, - }, - descriptor_index, - entity_index, - ); - if S::HAS_CASCADING_SHADOWS { - self.list_shadow_rows - .begin_cascading_change(&self.working_solution); - } + let element_delta = if S::HAS_CASCADING_SHADOWS { + self.list_shadow_rows.begin_cascading_change( + &self.working_solution, + descriptor_index, + entity_index, + ); + S::Score::zero() + } else { + self.list_shadow_rows.retract_held( + &self.working_solution, + &mut ModeRows { + constraints: &mut self.constraints, + mode: &self.weight_mode, + }, + descriptor_index, + entity_index, + ) + }; let mut score = ScoreSum::new(); score.add(self.cached_score); score.add(delta); diff --git a/crates/solverforge-scoring/src/director/score_director/list_shadows.rs b/crates/solverforge-scoring/src/director/score_director/list_shadows.rs index 0e93a5c9..864a44a6 100644 --- a/crates/solverforge-scoring/src/director/score_director/list_shadows.rs +++ b/crates/solverforge-scoring/src/director/score_director/list_shadows.rs @@ -18,13 +18,25 @@ //! element count grows. //! //! A solution with a cascading shadow (`PlanningSolution::HAS_CASCADING_SHADOWS`) -//! defers element rows to the end of the move instead: owners refresh only -//! their list structure, and once every owner the move notified has been -//! refreshed, the cascading values are propagated from the elements those -//! owners held before or after the move. Each element written along the way is -//! retracted before its write unless it is already pending, and every pending -//! element is inserted exactly once at the end. Solutions without a cascading -//! shadow never reach that code: the branch is on an associated constant. +//! rescores only the elements whose shadows change, and defers their rows to +//! the end of the move. Its element rows read nothing but the list structure +//! (owner, previous, next and, when declared, index) and the cascading value, +//! so an element keeps its row while those stay equal: +//! +//! - before an owner's list changes, the elements it holds are recorded, and +//! no row is retracted; +//! - after the change, an element whose structure shadows differ from its new +//! place (`PlanningSolution::list_structure_unchanged`, read before the +//! structure is rewritten), including an arrival from no list, is retracted +//! while it still holds its old shadows, then the structure is rewritten; +//! - once every owner the move notified has been refreshed, an element that +//! was held and is now in no list is retracted and cleared, the cascading +//! values are propagated from the retracted elements, each element whose +//! value changes is retracted before its write, and every retracted +//! element is inserted exactly once. +//! +//! Solutions without a cascading shadow never reach that code: the branch is +//! on an associated constant. use solverforge_core::domain::{CascadePropagation, PlanningSolution}; use solverforge_core::score::Score; @@ -55,8 +67,11 @@ struct CascadeRows { open_changes: usize, // The change source of element rows. source: usize, - // Elements a refreshed owner holds after the move. + // Elements a refreshed owner holds after the move, and the list of them. held: Vec, + held_elements: Vec, + // Elements the notified owners held before the move. + recorded: Vec, // The elements propagation starts from, reused across moves. seeds: Vec, } @@ -163,25 +178,42 @@ impl ListShadowRows { delta } - /// Opens one owner notification of a cascading move. - pub(super) fn begin_cascading_change(&mut self, solution: &S) { + /// Opens one owner notification of a cascading move and records the + /// elements the owner holds before it changes. No row is retracted yet: + /// only the elements whose structure the change rewrites are. + pub(super) fn begin_cascading_change( + &mut self, + solution: &S, + owner_descriptor: usize, + owner_index: usize, + ) { let cascade = self.cascade.get_or_insert_with(|| { + let count = solution.cascading_element_count(); Box::new(CascadeRows { propagation: CascadePropagation::new(solution), open_changes: 0, source: 0, - held: vec![false; solution.cascading_element_count()], + held: vec![false; count], + held_elements: Vec::new(), + recorded: Vec::new(), seeds: Vec::new(), }) }); cascade.open_changes += 1; + let Some((source, elements)) = solution.list_shadow_elements(owner_descriptor, owner_index) + else { + return; + }; + cascade.source = source; + cascade.recorded.extend_from_slice(elements); } - /// Retracts the owner's arrivals from no list, refreshes its list - /// structure for a cascading move and inserts the owner's row; element - /// rows stay retracted until the move's last owner is refreshed, when the - /// cascading values are propagated and every pending element is inserted - /// once. + /// Retracts the rows of the owner's elements whose structure changes + /// (moved, re-linked, or arrived from no list), refreshes the owner's + /// list structure for a cascading move and inserts the owner's row; + /// element rows stay retracted until the move's last owner is refreshed, + /// when the cascading values are propagated and every pending element is + /// inserted once. pub(super) fn refresh_cascading_owner( &mut self, solution: &mut S, @@ -194,8 +226,6 @@ impl ListShadowRows { C: RowDeltas, { let mut delta = S::Score::zero(); - // The list already holds its arrivals; their structure shadows are - // rewritten only below, so their rows are retracted first. if let Some((source, elements)) = solution.list_shadow_elements(owner_descriptor, owner_index) { @@ -204,23 +234,36 @@ impl ListShadowRows { .as_mut() .expect("a cascading change was opened"); cascade.source = source; - for &element in elements { - cascade.held[element] = true; - if !self.is_pending.get(element).copied().unwrap_or(false) { - // An arrival from no list: its row still holds the - // shadows it was inserted with. - delta = delta + constraints.retract_row(solution, element, source); - if element >= self.is_pending.len() { - self.is_pending.resize(element + 1, false); - } - self.is_pending[element] = true; - self.pending.push(PendingElement { + for (index, &element) in elements.iter().enumerate() { + if !cascade.held[element] { + cascade.held[element] = true; + cascade.held_elements.push(element); + } + if self.is_pending.get(element).copied().unwrap_or(false) + || solution.list_structure_unchanged( element, - source, owner_descriptor, owner_index, - }); + index, + index.checked_sub(1).map(|previous| elements[previous]), + elements.get(index + 1).copied(), + ) + { + continue; } + // The structure is rewritten below: an element that is not + // pending still holds the structure its row was inserted with. + delta = delta + constraints.retract_row(solution, element, source); + if element >= self.is_pending.len() { + self.is_pending.resize(element + 1, false); + } + self.is_pending[element] = true; + self.pending.push(PendingElement { + element, + source, + owner_descriptor, + owner_index, + }); } } solution.update_list_structure_shadows(owner_descriptor, owner_index); @@ -246,21 +289,39 @@ impl ListShadowRows { .cascade .as_mut() .expect("a cascading change was opened"); - // Elements that left their owner and joined no refreshed owner are in - // no list. - for entry in &self.pending { - if !cascade.held[entry.element] { - solution.clear_list_shadows(entry.element); - } - } let CascadeRows { propagation, source, held, + held_elements, + recorded, seeds, .. } = &mut **cascade; let source = *source; + // Elements that left their owner and joined no refreshed owner are in + // no list: their rows still hold their old structure. + for &element in recorded.iter() { + if !held[element] && !self.is_pending.get(element).copied().unwrap_or(false) { + delta = delta + constraints.retract_row(solution, element, source); + if element >= self.is_pending.len() { + self.is_pending.resize(element + 1, false); + } + self.is_pending[element] = true; + self.pending.push(PendingElement { + element, + source, + owner_descriptor: usize::MAX, + owner_index: usize::MAX, + }); + } + } + recorded.clear(); + for entry in &self.pending { + if !held[entry.element] { + solution.clear_list_shadows(entry.element); + } + } seeds.clear(); seeds.extend(self.pending.iter().map(|entry| entry.element)); let pending = &mut self.pending; @@ -283,8 +344,11 @@ impl ListShadowRows { for entry in self.pending.drain(..) { delta = delta + constraints.insert_row(solution, entry.element, entry.source); self.is_pending[entry.element] = false; - held[entry.element] = false; } + for &element in held_elements.iter() { + held[element] = false; + } + held_elements.clear(); delta } } diff --git a/crates/solverforge-scoring/src/director/tests/cascading_shadows.rs b/crates/solverforge-scoring/src/director/tests/cascading_shadows.rs index 33b512f1..29ed14e4 100644 --- a/crates/solverforge-scoring/src/director/tests/cascading_shadows.rs +++ b/crates/solverforge-scoring/src/director/tests/cascading_shadows.rs @@ -112,6 +112,22 @@ impl PlanningSolution for Shop { dependencies.extend(self.tasks[element].waits_on); } + fn list_structure_unchanged( + &self, + element: usize, + owner_descriptor: usize, + owner_index: usize, + _index: usize, + previous: Option, + next: Option, + ) -> bool { + let task = &self.tasks[element]; + owner_descriptor == MACHINES + && task.machine == Some(owner_index) + && task.previous == previous + && task.next == next + } + fn cascading_unset(&self, element: usize) -> bool { self.tasks[element].start.is_none() } @@ -158,6 +174,11 @@ type StartCost = IncrementalUniConstraint< SoftScore, >; +thread_local! { + // Rows weighed by `start_cost`, to count which rows a move rescores. + static COST_CALLS: std::cell::Cell = const { std::cell::Cell::new(0) }; +} + // Each task costs its start, with its position and machine folded in so a // stale previous pointer would also show. An unset start costs 1000 in no // list and 5000 on a machine (a dependency cycle), so a row retracted after @@ -170,6 +191,7 @@ fn start_cost() -> StartCost { true } fn cost(task: &Task) -> SoftScore { + COST_CALLS.with(|calls| calls.set(calls.get() + 1)); match task.start { Some(start) => SoftScore::of( start * 10 @@ -294,6 +316,24 @@ fn a_move_that_closes_a_dependency_cycle_unsets_it_and_its_undo_restores_it() { assert_matches_fresh(&mut director); } +#[test] +fn a_task_appended_to_a_route_rescores_only_the_rows_whose_shadows_change() { + // Saw (0): tasks 0 to 5. Task 6 is unassigned. + let mut director = director(vec![(0..6).collect()], &[2, 3, 2, 4, 1, 3, 5], &[]); + assert_matches_fresh(&mut director); + COST_CALLS.with(|calls| calls.set(0)); + + // Only task 5 (a new next) and task 6 (placed) change; tasks 0 to 4 + // keep their structure and start, so their rows stay. + change(&mut director, &[0], |machines| machines[0].push(6)); + let rescored = COST_CALLS.with(|calls| calls.get()); + assert!( + rescored <= 4, + "{rescored} row weighings for two changed rows" + ); + assert_matches_fresh(&mut director); +} + // A deterministic pseudo-random sequence (64-bit LCG). struct Lcg(u64); diff --git a/crates/solverforge-solver/WIREFRAME.md b/crates/solverforge-solver/WIREFRAME.md index 79ae751a..2d2055aa 100644 --- a/crates/solverforge-solver/WIREFRAME.md +++ b/crates/solverforge-solver/WIREFRAME.md @@ -1074,7 +1074,8 @@ Runtime helpers: updates without proc-macro registries. Its cascading hooks (`update_list_structure_shadows`, `cascading_element_count`, `cascading_assigned`, `cascading_next`, `cascading_dependencies`, - `cascading_peers`, `cascading_unset`, `update_cascading_shadow`) mirror the + `cascading_peers`, `list_structure_unchanged`, `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/benches/selector_cursor_gate.rs b/crates/solverforge-solver/benches/selector_cursor_gate.rs index 5ebacc6c..d2768b4d 100644 --- a/crates/solverforge-solver/benches/selector_cursor_gate.rs +++ b/crates/solverforge-solver/benches/selector_cursor_gate.rs @@ -149,6 +149,8 @@ include!("selector_cursor_gate/list_cases.rs"); include!("selector_cursor_gate/scalar_cases.rs"); include!("selector_cursor_gate/construction_cases.rs"); include!("selector_cursor_gate/scoring_cases.rs"); +include!("selector_cursor_gate/route_model.rs"); +include!("selector_cursor_gate/route_cases.rs"); include!("selector_cursor_gate/case_dispatch.rs"); @@ -187,6 +189,8 @@ fn main() { "construction_first_fit", construction_first_fit ); + run_case!(case, matched, "route_rows", route_rows); + run_case!(case, matched, "group_ruin", group_ruin); run_case!(case, matched, "scoring", scoring); run_case!(case, matched, "scoring_weights_one", scoring_weights_one); run_case!( diff --git a/crates/solverforge-solver/benches/selector_cursor_gate/route_cases.rs b/crates/solverforge-solver/benches/selector_cursor_gate/route_cases.rs new file mode 100644 index 00000000..4dfcc791 --- /dev/null +++ b/crates/solverforge-solver/benches/selector_cursor_gate/route_cases.rs @@ -0,0 +1,160 @@ +/* Route cases: a routing model whose element rows carry list shadows and a +cascading arrival time, and whose stops come in pick-up and drop-off pairs +(element groups). Unlike the selector cases, these execute moves against +a director with constraints, so they measure what a route model's solve +pays per move: +- `route_rows`: list changes on a route through the score director, each + rescoring the stop rows whose shadows the change touched; +- `group_ruin`: the compiled grouped ruin-and-recreate neighborhood, every + candidate done, scored and undone, with joint recreate of each pair. + +The cross-tree order hash covers only the change or candidate sequence; +scores feed the per-tree identity hash. */ + +fn mix_route_score(hash: &mut u64, score: HardSoftScore) { + mix_u64(hash, score.hard() as u64); + mix_u64(hash, score.soft() as u64); +} + +/* Moves one stop to another position of its route or of the next route, +then back, through the director: two owner changes per direction. */ +fn route_rows() { + let mut director = route_director(); + black_box(director.calculate_score()); + emit("route_rows", ROUTE_CHANGES, || { + let mut count = 0; + let mut order = FNV_OFFSET; + let mut scores = FNV_OFFSET; + for _ in 0..iterations() { + for change in 0..ROUTE_CHANGES { + let from = change % ROUTE_VEHICLES; + let to = if change % 3 == 0 { + (from + 1) % ROUTE_VEHICLES + } else { + from + }; + let len = director.working_solution().vehicles[from].visits.len(); + let position = change.wrapping_mul(7) % len; + let target = change.wrapping_mul(13) % len; + director.before_variable_changed(0, from); + if to != from { + director.before_variable_changed(0, to); + } + let stop = director.working_solution_mut().vehicles[from] + .visits + .remove(position); + director.working_solution_mut().vehicles[to] + .visits + .insert(target, stop); + director.after_variable_changed(0, from); + if to != from { + director.after_variable_changed(0, to); + } + mix_route_score(&mut scores, director.get_score()); + director.before_variable_changed(0, from); + if to != from { + director.before_variable_changed(0, to); + } + let stop = director.working_solution_mut().vehicles[to] + .visits + .remove(target); + director.working_solution_mut().vehicles[from] + .visits + .insert(position, stop); + director.after_variable_changed(0, from); + if to != from { + director.after_variable_changed(0, to); + } + mix(&mut order, from); + mix(&mut order, to); + mix(&mut order, position); + mix(&mut order, target); + mix_route_score(&mut scores, director.get_score()); + count += 1; + } + } + (count, order, scores) + }); +} + +/// Does, scores and undoes a candidate, folding its score. +struct DoScoreUndo<'a, D>(&'a mut D, &'a mut u64); + +impl> CandidateVisitor for DoScoreUndo<'_, D> { + type Output = (); + + fn visit>(self, candidate: MoveCandidateRef<'_, RoutePlan, M>) { + let undo = candidate.do_move(self.0); + mix_route_score(self.1, self.0.calculate_score()); + candidate.undo_move(self.0, undo); + } +} + +/// Folds a route candidate's logical-coordinate identity into the order hash. +struct RouteTraceFold<'a>(&'a mut u64); + +impl CandidateVisitor for RouteTraceFold<'_> { + type Output = (); + + fn visit>(self, candidate: MoveCandidateRef<'_, RoutePlan, M>) { + let identity = candidate + .candidate_trace_identity() + .expect("compiled runtime candidates expose a logical identity"); + mix_trace_identity(self.0, &identity); + } +} + +fn group_ruin_neighborhood() -> RouteNeighborhood { + let config = local_search_config(MoveSelectorConfig::ListRuinMoveSelector( + ListRuinMoveSelectorConfig { + min_ruin_count: 4, + max_ruin_count: 8, + moves_per_step: Some(GROUP_RUIN_MOVES), + selection_order: CANONICAL, + max_member_distance: std::num::NonZeroU8::new(7), + max_group_owners: std::num::NonZeroU8::new(4), + ..ListRuinMoveSelectorConfig::default() + }, + )); + RouteRunner::compile(&config, route_context()) + .expect("the group ruin configuration must compile") + .into_local_search_neighborhood() + .expect("the group ruin configuration's first phase is a local search") +} + +fn group_ruin() { + let mut director = route_director(); + black_box(director.calculate_score()); + let mut neighborhood = group_ruin_neighborhood(); + let mut order_hash = FNV_OFFSET; + { + let mut count = 0; + let mut cursor = neighborhood.open_cursor(&director, step_context()); + while let Some(candidate_id) = cursor.next_candidate(&mut director) { + cursor + .visit_candidate(candidate_id, RouteTraceFold(&mut order_hash)) + .expect("a pulled candidate stays live until released"); + assert!(cursor.release_candidate(candidate_id)); + count += 1; + } + assert_eq!( + count, GROUP_RUIN_MOVES, + "group_ruin candidate count changed" + ); + } + emit("group_ruin", GROUP_RUIN_MOVES, || { + let mut count = 0; + let mut scores = FNV_OFFSET; + for _ in 0..iterations() { + let mut cursor = neighborhood.open_cursor(&director, step_context()); + while let Some(candidate_id) = cursor.next_candidate(&mut director) { + cursor + .visit_candidate(candidate_id, DoScoreUndo(&mut director, &mut scores)) + .expect("a pulled candidate stays live until released"); + assert!(cursor.release_candidate(candidate_id)); + count += 1; + } + } + (count, order_hash, scores) + }); +} diff --git a/crates/solverforge-solver/benches/selector_cursor_gate/route_model.rs b/crates/solverforge-solver/benches/selector_cursor_gate/route_model.rs new file mode 100644 index 00000000..928986a5 --- /dev/null +++ b/crates/solverforge-solver/benches/selector_cursor_gate/route_model.rs @@ -0,0 +1,439 @@ +/* The route gate model: stops in pick-up and drop-off pairs (element +groups) on vehicle lists, with list shadows and a cascading arrival time, +and constraints over every stop row. Declared by hand, the way generated +model code declares one. */ + +use solverforge_config::ListRuinMoveSelectorConfig; +use solverforge_core::domain::CascadePropagation; +use solverforge_scoring::Director; + +const ROUTE_VEHICLES: usize = 12; +const ROUTE_PAIRS_PER_VEHICLE: usize = 10; +const ROUTE_CHANGES: usize = 2_048; +const GROUP_RUIN_MOVES: usize = 4; + +#[derive(Clone, Debug)] +struct RouteVehicle { + visits: Vec, +} + +#[derive(Clone, Debug, PartialEq, Eq, Hash)] +struct RouteStop { + pair: usize, + duration: i64, + ready: i64, + due: i64, + vehicle: Option, + previous: Option, + next: Option, + arrival: Option, +} + +#[derive(Clone, Debug)] +struct RoutePlan { + vehicles: Vec, + stops: Vec, + score: Option, +} + +// Stop rows are a fact collection, reported past the one entity descriptor. +const ROUTE_STOP_SOURCE: usize = 1; + +fn route_travel(from: usize, to: usize) -> i64 { + ((from * 31 + to * 17) % 23) as i64 + 1 +} + +impl RoutePlan { + fn end(&self, stop: usize) -> Option { + let stop = &self.stops[stop]; + stop.arrival.map(|arrival| arrival + stop.duration) + } + + fn compute_arrival(&self, stop: usize) -> Option { + let ready = self.stops[stop].ready; + match self.stops[stop].previous { + Some(previous) => Some(ready.max(self.end(previous)? + route_travel(previous, stop))), + None => Some(ready.max(route_travel(stop, stop))), + } + } + + fn write_structure(&mut self, vehicle: usize) { + let visits = std::mem::take(&mut self.vehicles[vehicle].visits); + for (position, &stop) in visits.iter().enumerate() { + let stop = &mut self.stops[stop]; + stop.vehicle = Some(vehicle); + stop.previous = position.checked_sub(1).map(|previous| visits[previous]); + stop.next = visits.get(position + 1).copied(); + } + self.vehicles[vehicle].visits = visits; + } +} + +impl PlanningSolution for RoutePlan { + type Score = HardSoftScore; + + fn score(&self) -> Option { + self.score + } + + fn set_score(&mut self, score: Option) { + self.score = score; + } + + fn update_entity_shadows(&mut self, descriptor_index: usize, entity_index: usize) { + self.update_list_structure_shadows(descriptor_index, entity_index); + let changed = self.vehicles[entity_index].visits.clone(); + CascadePropagation::new(&*self).propagate(self, changed, |_, _| {}); + } + + fn update_all_shadows(&mut self) { + for stop in &mut self.stops { + stop.vehicle = None; + stop.previous = None; + stop.next = None; + } + for vehicle in 0..self.vehicles.len() { + self.write_structure(vehicle); + } + CascadePropagation::refresh_all(self); + } + + fn list_shadow_elements( + &self, + descriptor_index: usize, + entity_index: usize, + ) -> Option<(usize, &[usize])> { + (descriptor_index == 0) + .then(|| self.vehicles.get(entity_index)) + .flatten() + .map(|vehicle| (ROUTE_STOP_SOURCE, vehicle.visits.as_slice())) + } + + fn clear_list_shadows(&mut self, element: usize) { + let stop = &mut self.stops[element]; + stop.vehicle = None; + stop.previous = None; + stop.next = None; + } + + fn list_shadow_source(collection: &str) -> Option { + (collection == "stops").then_some(ROUTE_STOP_SOURCE) + } + + const HAS_CASCADING_SHADOWS: bool = true; + + fn cascading_element_count(&self) -> usize { + self.stops.len() + } + + fn cascading_assigned(&self, element: usize) -> bool { + self.stops[element].vehicle.is_some() + } + + fn cascading_next(&self, element: usize) -> Option { + self.stops[element].next + } + + // The structure hook exists from the candidate tree on; a baseline + // without it rescores every element of a changed owner. + #[cfg(feature = "candidate")] + fn list_structure_unchanged( + &self, + element: usize, + owner_descriptor: usize, + owner_index: usize, + _index: usize, + previous: Option, + next: Option, + ) -> bool { + let stop = &self.stops[element]; + owner_descriptor == 0 + && stop.vehicle == Some(owner_index) + && stop.previous == previous + && stop.next == next + } + + fn cascading_unset(&self, element: usize) -> bool { + self.stops[element].arrival.is_none() + } + + fn update_cascading_shadow( + &mut self, + element: usize, + computable: bool, + before_write: W, + ) -> bool { + let arrival = if computable { + self.compute_arrival(element) + } else { + None + }; + if self.stops[element].arrival == arrival { + return false; + } + before_write(self); + self.stops[element].arrival = arrival; + true + } + + fn update_list_structure_shadows(&mut self, descriptor_index: usize, entity_index: usize) { + if descriptor_index == 0 && entity_index < self.vehicles.len() { + self.write_structure(entity_index); + } + } +} + +impl CrossEntityDistanceMeter for PositionDistanceMeter { + fn distance( + &self, + _solution: &RoutePlan, + source_entity: usize, + source_position: usize, + destination_entity: usize, + destination_position: usize, + ) -> f64 { + source_entity.abs_diff(destination_entity) as f64 * 100.0 + + source_position.abs_diff(destination_position) as f64 + } +} + +type RouteContext = SearchContext; +type RouteRunner = + CompiledRuntimeRunner; +type RouteNeighborhood = + CompiledNeighborhood; +type RouteSlot = VariableSlot; + +fn route_stops(plan: &RoutePlan) -> &[RouteStop] { + plan.stops.as_slice() +} + +/* Rows of every stop: late arrivals (hard), split pairs (hard, a join on +the pair), each route's service load (grouped), and arrival times (soft). */ +fn route_constraints() -> impl ConstraintSet { + let stops = || { + source( + route_stops as fn(&RoutePlan) -> &[RouteStop], + ChangeSource::Descriptor(ROUTE_STOP_SOURCE), + ) + }; + let factory = ConstraintFactory::::new; + ( + factory() + .for_each(stops()) + .filter(|stop: &RouteStop| stop.arrival.is_some_and(|arrival| arrival > stop.due)) + .penalize(|stop: &RouteStop| { + HardSoftScore::of_hard(stop.arrival.unwrap_or(0) - stop.due) + }) + .named("Late"), + factory() + .for_each(stops()) + .join(( + stops(), + equal_bi(|stop: &RouteStop| stop.pair, |other: &RouteStop| other.pair), + )) + .filter(|stop: &RouteStop, other: &RouteStop| { + stop.duration < other.duration && stop.vehicle != other.vehicle + }) + .penalize(HardSoftScore::of_hard(1)) + .named("Split pair"), + factory() + .for_each(stops()) + .group_by( + |stop: &RouteStop| stop.vehicle.unwrap_or(usize::MAX), + sum(|stop: &RouteStop| stop.duration), + ) + .penalize(|_vehicle: &usize, load: &i64| HardSoftScore::of_soft(load * load / 64)) + .named("Load"), + factory() + .for_each(stops()) + .penalize(|stop: &RouteStop| HardSoftScore::of_soft(stop.arrival.unwrap_or(1_000))) + .named("Arrival"), + ) +} + +/* Pair `p` is stops `2p` (pick-up) and `2p + 1` (drop-off), one vehicle's +pairs in order; the drop-off is one unit longer, which orients the pair +join. */ +fn route_plan() -> RoutePlan { + let pairs = ROUTE_VEHICLES * ROUTE_PAIRS_PER_VEHICLE; + let stops = (0..2 * pairs) + .map(|stop| { + let pair = stop / 2; + let ready = ((pair * 37) % 90) as i64; + RouteStop { + pair, + duration: (pair % 4) as i64 + 2 + (stop % 2) as i64, + ready, + due: ready + 160 + (pair % 7) as i64 * 20, + vehicle: None, + previous: None, + next: None, + arrival: None, + } + }) + .collect(); + let vehicles = (0..ROUTE_VEHICLES) + .map(|vehicle| RouteVehicle { + visits: (0..2 * ROUTE_PAIRS_PER_VEHICLE) + .map(|offset| vehicle * 2 * ROUTE_PAIRS_PER_VEHICLE + offset) + .collect(), + }) + .collect(); + let mut plan = RoutePlan { + vehicles, + stops, + score: None, + }; + plan.update_all_shadows(); + plan +} + +fn route_vehicles(plan: &RoutePlan) -> &Vec { + &plan.vehicles +} + +fn route_vehicles_mut(plan: &mut RoutePlan) -> &mut Vec { + &mut plan.vehicles +} + +fn route_descriptor() -> SolutionDescriptor { + let extractor = Box::new(EntityCollectionExtractor::new( + "Vehicle", + "vehicles", + route_vehicles, + route_vehicles_mut, + )); + let entity = EntityDescriptor::new("Vehicle", TypeId::of::(), "vehicles") + .with_extractor(extractor) + .with_variable(VariableDescriptor::list("visits")); + SolutionDescriptor::new("RoutePlan", TypeId::of::()).with_entity(entity) +} + +fn route_director( +) -> ScoreDirector, SolutionDescriptor> { + ScoreDirector::with_descriptor( + route_plan(), + route_constraints(), + route_descriptor(), + |plan, _| plan.vehicles.len(), + ) +} + +fn route_entity_count(plan: &RoutePlan) -> usize { + plan.vehicles.len() +} + +fn route_element_count(plan: &RoutePlan) -> usize { + plan.stops.len() +} + +fn route_assigned(plan: &RoutePlan) -> Vec { + plan.vehicles + .iter() + .flat_map(|vehicle| vehicle.visits.iter().copied()) + .collect() +} + +fn route_list_len(plan: &RoutePlan, entity: usize) -> usize { + plan.vehicles[entity].visits.len() +} + +fn route_list_get(plan: &RoutePlan, entity: usize, position: usize) -> Option { + plan.vehicles.get(entity)?.visits.get(position).copied() +} + +fn route_list_set(plan: &mut RoutePlan, entity: usize, position: usize, value: usize) { + plan.vehicles[entity].visits[position] = value; +} + +fn route_list_remove(plan: &mut RoutePlan, entity: usize, position: usize) -> Option { + let visits = &mut plan.vehicles[entity].visits; + (position < visits.len()).then(|| visits.remove(position)) +} + +fn route_list_take(plan: &mut RoutePlan, entity: usize, position: usize) -> usize { + plan.vehicles[entity].visits.remove(position) +} + +fn route_list_insert(plan: &mut RoutePlan, entity: usize, position: usize, value: usize) { + plan.vehicles[entity].visits.insert(position, value); +} + +fn route_list_reverse(plan: &mut RoutePlan, entity: usize, start: usize, end: usize) { + plan.vehicles[entity].visits[start..end].reverse(); +} + +fn route_sublist_remove( + plan: &mut RoutePlan, + entity: usize, + start: usize, + end: usize, +) -> Vec { + plan.vehicles[entity].visits.drain(start..end).collect() +} + +fn route_sublist_insert(plan: &mut RoutePlan, entity: usize, position: usize, values: Vec) { + plan.vehicles[entity] + .visits + .splice(position..position, values); +} + +fn route_index_to_element(_plan: &RoutePlan, index: usize) -> usize { + index +} + +fn route_source_key(_plan: &RoutePlan, element: &usize) -> usize { + *element +} + +fn route_pair(plan: &RoutePlan, stop: usize, members: &mut Vec) { + let pair = plan.stops[stop].pair; + members.extend([2 * pair, 2 * pair + 1]); +} + +fn route_slot() -> RouteSlot { + VariableSlot::List( + ListVariableSlot::new( + "Vehicle", + route_element_count, + route_assigned, + route_list_len, + route_list_remove, + route_list_insert, + route_list_get, + route_list_set, + route_list_reverse, + route_sublist_remove, + route_sublist_insert, + route_list_take, + route_list_insert, + route_index_to_element, + route_source_key, + route_entity_count, + PositionDistanceMeter, + PositionDistanceMeter, + "visits", + 0, + None, + None, + None, + None, + None, + None, + None, + None, + None, + ) + .with_element_group_fn(Some(route_pair)), + ) +} + +fn route_context() -> RouteContext { + SearchContext::new( + route_descriptor(), + RuntimeModel::new(vec![route_slot()]), + Some(SEED), + ) + .expect("the route gate model must bind to its descriptor") +} 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 index 68c4ba2d..485df74a 100644 --- a/crates/solverforge-solver/src/heuristic/move/list_kernel/group_ruin.rs +++ b/crates/solverforge-solver/src/heuristic/move/list_kernel/group_ruin.rs @@ -1,11 +1,10 @@ //! 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. +//! Recreate then inserts the units in the plan's order, each at its best +//! bounded joint placement on the owners all its members allow, given the +//! units placed before it. 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; @@ -164,121 +163,181 @@ where 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()]; + // One pass in the plan's unit order: each unit takes its best bounded + // joint placement given the units placed before it. 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()] + for (unit_index, unit) in plan.units().enumerate() { + 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 trial = JointTrial::new( + 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)); - } + .collect(), + ); + let search = search_joint_placement( + &owners, + unit.len(), + |entity| lens[entity], + plan.bounds, + |entity, positions| Some(trial.score(access, entity, positions, score_director)), + ); + for (slot, member) in values[unit.clone()] + .iter_mut() + .zip(trial.into_members(access, score_director)) + { + *slot = Some(member); } - let Some((unit_index, entity, positions, _)) = best else { + let JointSearch::Done { + best: Some(choice), .. + } = search + 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()) { + score_director.before_variable_changed(descriptor_index, choice.entity); + for (removed_index, &position) in unit.zip(choice.positions.iter()) { access.list_insert( score_director.working_solution_mut(), - entity, + choice.entity, position, values[removed_index] .take() - .expect("the winning unit's members are held"), + .expect("the placed unit's members are held"), ); - placements.push((entity, position, removed_index)); + placements.push((choice.entity, position, removed_index)); } - score_director.after_variable_changed(descriptor_index, entity); - placed[unit_index] = true; + score_director.after_variable_changed(descriptor_index, choice.entity); } 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, - ); +/// The members of one unit while its joint placements are scored. +/// +/// Members stay in the list between trials: the search enumerates an +/// owner's placements in lexicographic order of positions, so consecutive +/// placements usually share the positions of their first members, and only +/// the members after the shared prefix are taken out and put back, in one +/// owner change per trial. +struct JointTrial { + // Each member, or `None` while it sits in `entity`'s list. + members: SmallVec<[Option; 4]>, + entity: Option, + // Positions of the inserted members, a prefix of the unit. + positions: SmallVec<[usize; 4]>, +} + +impl JointTrial { + fn new(members: SmallVec<[E; 4]>) -> Self { + Self { + members: members.into_iter().map(Some).collect(), + entity: None, + positions: SmallVec::new(), + } + } + + /// Places the members at `positions` of `entity` and scores the result. + fn score( + &mut self, + access: &A, + entity: usize, + positions: &[usize], + score_director: &mut D, + ) -> S::Score + where + S: PlanningSolution, + A: ListRuinAccess, + D: Director, + { + if self.entity != Some(entity) { + self.take_out(access, score_director); + } + let shared = self + .positions + .iter() + .zip(positions) + .take_while(|(inserted, wanted)| inserted == wanted) + .count(); + let descriptor_index = access.descriptor_index(); + score_director.before_variable_changed(descriptor_index, entity); + // Later members sit at higher positions, so they leave first. + for member in (shared..self.positions.len()).rev() { + self.members[member] = Some(access.list_remove( + score_director.working_solution_mut(), + entity, + self.positions[member], + )); + } + self.positions.truncate(shared); + for (member, &position) in positions.iter().enumerate().skip(shared) { + access.list_insert( + score_director.working_solution_mut(), + entity, + position, + self.members[member] + .take() + .expect("a member outside the list is held"), + ); + self.positions.push(position); + } + score_director.after_variable_changed(descriptor_index, entity); + self.entity = Some(entity); + score_director.calculate_score() } - 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)); + + /// Takes every inserted member out of the list. + fn take_out(&mut self, access: &A, score_director: &mut D) + where + S: PlanningSolution, + A: ListRuinAccess, + D: Director, + { + let Some(entity) = self.entity.take() else { + return; + }; + if self.positions.is_empty() { + return; + } + let descriptor_index = access.descriptor_index(); + score_director.before_variable_changed(descriptor_index, entity); + for member in (0..self.positions.len()).rev() { + self.members[member] = Some(access.list_remove( + score_director.working_solution_mut(), + entity, + self.positions[member], + )); + } + score_director.after_variable_changed(descriptor_index, entity); + self.positions.clear(); + } + + /// Takes every member out of the list and hands them back in order. + fn into_members(mut self, access: &A, score_director: &mut D) -> SmallVec<[E; 4]> + where + S: PlanningSolution, + A: ListRuinAccess, + D: Director, + { + self.take_out(access, score_director); + self.members + .into_iter() + .map(|member| member.expect("every member is out of the list")) + .collect() } - members.reverse(); - score_director.after_variable_changed(descriptor_index, entity); - score } /// Takes back the placements already made, then restores every removed diff --git a/crates/solverforge-solver/src/model_support.rs b/crates/solverforge-solver/src/model_support.rs index f8d69994..240b45c2 100644 --- a/crates/solverforge-solver/src/model_support.rs +++ b/crates/solverforge-solver/src/model_support.rs @@ -109,6 +109,20 @@ pub trait PlanningModelSupport: PlanningSolution + Sized + 'static { /// it; none by default. fn cascading_peers(_solution: &Self, _element: usize, _peers: &mut Vec) {} + /// Whether `element`'s list structure shadows already describe the given + /// place; `false` by default. + fn list_structure_unchanged( + _solution: &Self, + _element: usize, + _owner_descriptor: usize, + _owner_index: usize, + _index: usize, + _previous: Option, + _next: Option, + ) -> bool { + false + } + /// Whether `element`'s cascading value is unset; `true` by default. fn cascading_unset(_solution: &Self, _element: usize) -> bool { true diff --git a/docs/modeling.md b/docs/modeling.md index 5c8177bb..b34eaf54 100644 --- a/docs/modeling.md +++ b/docs/modeling.md @@ -183,7 +183,11 @@ impl Shop { After each move the score director recomputes the downstream cone of the changed elements in dependency order: each element once, after its inputs, and only when an input changed, so propagation stops where a value is -unchanged. Every element whose value changes is rescored exactly once. An +unchanged. Every element whose value changes is rescored exactly once, and +so is every element whose owner, previous or next element changes (or whose +index changes, when `index_field` is configured); the other elements keep +their stream rows, so a change near the end of a long route rescores only +what it touches. An element in no list, or on a dependency cycle a move creates (a task that waits on a task queued after it), is unset (`None`), which constraints can penalize. Models without a cascading shadow compile none of this into their @@ -318,8 +322,9 @@ elements may sit between them, as a shared ride needs: 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_ruin_move_selector` ruins whole groups and recreates them in one + pass, each group jointly at its best placement given the groups placed + before it, 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. diff --git a/scripts/bench-zero-regression.sh b/scripts/bench-zero-regression.sh index ab55d99e..77514adb 100755 --- a/scripts/bench-zero-regression.sh +++ b/scripts/bench-zero-regression.sh @@ -79,13 +79,18 @@ FIRST_FIT_MEASURE_ITERATIONS=${FIRST_FIT_MEASURE_ITERATIONS:-1024} # millions of instructions while 51 trials x 45 counter repeats finish in # hours rather than a day. FULL_LIST_MEASURE_ITERATIONS=${FULL_LIST_MEASURE_ITERATIONS:-4} +# The route cases execute moves against a scored route model: two churn +# passes for `route_rows`, one pass of grouped ruin-and-recreate moves for +# `group_ruin`. +ROUTE_ROWS_MEASURE_ITERATIONS=${ROUTE_ROWS_MEASURE_ITERATIONS:-2} +GROUP_RUIN_MEASURE_ITERATIONS=${GROUP_RUIN_MEASURE_ITERATIONS:-1} TOOLCHAIN=${TOOLCHAIN:-1.95.0} RESULTS=${RESULTS:-"/tmp/solverforge-zero-regression-$(date +%Y%m%d-%H%M%S)"} # Opt-in scoring cases (not in the default selector set): BENCH_CASES="scoring # scoring_weights_one scoring_weights_mixed" measures incremental score-director # churn through uni, join, shared grouped, and balance constraints; see # crates/solverforge-solver/benches/selector_cursor_gate/scoring_cases.rs. -DEFAULT_CASES=(list_change list_swap nearby_change nearby_swap sublist_change sublist_swap union cartesian k_opt ruin scalar_change scalar_swap construction_full construction_first_fit) +DEFAULT_CASES=(list_change list_swap nearby_change nearby_swap sublist_change sublist_swap union cartesian k_opt ruin scalar_change scalar_swap construction_full construction_first_fit route_rows group_ruin) if [[ -n ${BENCH_CASES:-} ]]; then read -r -a CASES <<<"$BENCH_CASES" else @@ -142,6 +147,10 @@ measure_iterations_for_case() { printf '%s\n' "$FIRST_FIT_MEASURE_ITERATIONS" elif [[ $case_name =~ ^(list_change|list_swap|sublist_change|sublist_swap|union)$ ]]; then printf '%s\n' "$FULL_LIST_MEASURE_ITERATIONS" + elif [[ $case_name == route_rows ]]; then + printf '%s\n' "$ROUTE_ROWS_MEASURE_ITERATIONS" + elif [[ $case_name == group_ruin ]]; then + printf '%s\n' "$GROUP_RUIN_MEASURE_ITERATIONS" else printf '%s\n' "$MEASURE_ITERATIONS" fi @@ -387,7 +396,7 @@ if [[ $BENCH_ISOLATE == 1 ]]; then fi cat >"$RESULTS/environment.json" <