From 1a62bfbd5e93e090c1d359131c5d604b64d5d85e Mon Sep 17 00:00:00 2001 From: Vittorio Distefano Date: Tue, 17 Nov 2026 09:08:02 +0100 Subject: [PATCH 1/3] test(bench): gate route rows and grouped ruin-and-recreate moves The zero-regression gate generated candidates only, against an empty constraint set, and no case declared element groups or list shadows, so neither the score director row maintenance of a route model nor the joint recreate of grouped ruin moves was measured. route_rows changes routes of a model with cascading arrival times through the director; group_ruin does, scores and undoes the compiled grouped ruin candidates. On v0.31.0 one grouped ruin move of a 12-vehicle, 20-stop route costs about 200 ms. --- AGENTS.md | 4 + .../benches/selector_cursor_gate.rs | 4 + .../selector_cursor_gate/route_cases.rs | 160 +++++++ .../selector_cursor_gate/route_model.rs | 420 ++++++++++++++++++ scripts/bench-zero-regression.sh | 13 +- 5 files changed, 599 insertions(+), 2 deletions(-) create mode 100644 crates/solverforge-solver/benches/selector_cursor_gate/route_cases.rs create mode 100644 crates/solverforge-solver/benches/selector_cursor_gate/route_model.rs 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-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..c0d293b4 --- /dev/null +++ b/crates/solverforge-solver/benches/selector_cursor_gate/route_model.rs @@ -0,0 +1,420 @@ +/* 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 + } + + 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/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" < Date: Tue, 17 Nov 2026 09:18:19 +0100 Subject: [PATCH 2/3] perf(scoring): rescore only the list-shadow rows a cascading move changes With a cascading shadow, every owner change retracted and re-inserted the row of every element the owner held, so one insertion into a route rescored the whole route. The director now records the elements of each notified owner without retracting them, and after the change retracts only elements whose structure shadows do not already describe their new place, arrivals from no list, elements left in no list, and elements whose cascading value changes. The new PlanningSolution::list_structure_unchanged hook answers the structure question from the element's own shadow fields before they are rewritten, so the director keeps no per-element record; #[shadow_variable_updates(cascading_field = ...)] generates it, and the default (false) keeps the previous behaviour for hand-written solutions. route_rows against v0.31.0: 96 ms to 57 ms, allocations 492k to 262k, peak live bytes 107,632 to 96,256, identical scores on all 4,096 changes. --- crates/solverforge-core/WIREFRAME.md | 1 + crates/solverforge-core/public-api.txt | 3 +- crates/solverforge-core/src/domain/traits.rs | 22 +++ crates/solverforge-macros/WIREFRAME.md | 3 +- .../src/planning_model/cascade.rs | 30 ++++ .../src/planning_model/shadows.rs | 1 + .../src/planning_solution/shadow.rs | 21 +++ crates/solverforge-scoring/WIREFRAME.md | 24 +-- .../director/score_director/incremental.rs | 31 ++-- .../director/score_director/list_shadows.rs | 142 +++++++++++++----- .../src/director/tests/cascading_shadows.rs | 40 +++++ crates/solverforge-solver/WIREFRAME.md | 3 +- .../selector_cursor_gate/route_model.rs | 19 +++ .../solverforge-solver/src/model_support.rs | 14 ++ docs/modeling.md | 6 +- 15 files changed, 295 insertions(+), 65 deletions(-) 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/route_model.rs b/crates/solverforge-solver/benches/selector_cursor_gate/route_model.rs index c0d293b4..928986a5 100644 --- a/crates/solverforge-solver/benches/selector_cursor_gate/route_model.rs +++ b/crates/solverforge-solver/benches/selector_cursor_gate/route_model.rs @@ -134,6 +134,25 @@ impl PlanningSolution for RoutePlan { 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() } 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..374f2d8f 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 From bfd0ef4a46f4ce581fec7048b0d6a321210d6db0 Mon Sep 17 00:00:00 2001 From: Vittorio Distefano Date: Tue, 17 Nov 2026 09:18:19 +0100 Subject: [PATCH 3/3] perf(list): recreate ruined groups in one pass with shared trial prefixes Grouped ruin recreate searched every remaining unit's joint placements in every round and committed only the best, about k(k+1)/2 searches for k units, and each scored placement inserted and removed every member in two owner changes. Recreate now places the units in one pass in the plan's order, each at its best placement given those before it, the standard ruin-and-recreate order. A placement search keeps the unit's members in the list between trials and moves only the members after the positions consecutive placements share, in one owner change per trial. group_ruin against v0.31.0 (with the row change): 1,361 ms to 107 ms for two passes, allocations 6.58M to 443k. --- .../heuristic/move/list_kernel/group_ruin.rs | 259 +++++++++++------- docs/modeling.md | 5 +- 2 files changed, 162 insertions(+), 102 deletions(-) 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/docs/modeling.md b/docs/modeling.md index 374f2d8f..b34eaf54 100644 --- a/docs/modeling.md +++ b/docs/modeling.md @@ -322,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.