From 542f94fd87d0a39ecea7ff9f509ab89e5e1a4cd7 Mon Sep 17 00:00:00 2001 From: Vittorio Distefano Date: Tue, 17 Nov 2026 16:29:08 +0100 Subject: [PATCH 1/3] fix(construction): complete fixed fleets after Clarke-Wright and bound default savings When strict savings hooks reject merges and the Clarke-Wright routes outnumber the vehicles that can take them, construction discarded every route, so a fixed fleet ended construction with every element unassigned and the default solve failed its completion gate. Clarke-Wright now commits the routes it matched, and the default construction runs a list cheapest insertion over the elements left unassigned (reason list_elements_remain_unassigned). The completion stage reads the unassigned count only for a slot whose Clarke-Wright ran, against the source that construction already bound. The default Clarke-Wright keeps 40 savings per element when the slot declares a savings neighbour hook, so its memory grows linearly with the stop count instead of with its square. Refs #253 --- .../list_clarke_wright/kernel.rs | 10 +- .../src/runtime/compiler/defaults.rs | 2 + .../compiler/defaults/list_completion.rs | 75 +++++++ .../src/runtime/compiler/defaults/stages.rs | 37 +++- .../compiler/executor/default_construction.rs | 189 ++++++++++++++++++ .../src/runtime/compiler/executor/execute.rs | 112 +---------- .../src/runtime/compiler/executor/mod.rs | 4 +- .../compiler/executor/prepared/types.rs | 20 ++ .../src/runtime/compiler/executor/trace.rs | 10 +- .../tests/list_clarke_wright_fixed_fleet.rs | 77 +++++++ .../domain/customer.rs | 7 + .../domain/fleet_plan.rs | 128 ++++++++++++ .../domain/mod.rs | 12 ++ .../domain/route.rs | 20 ++ .../domain/strict_savings_hooks.rs | 19 ++ docs/configuration.md | 15 ++ 16 files changed, 617 insertions(+), 120 deletions(-) create mode 100644 crates/solverforge-solver/src/runtime/compiler/defaults/list_completion.rs create mode 100644 crates/solverforge-solver/src/runtime/compiler/executor/default_construction.rs create mode 100644 crates/solverforge/tests/list_clarke_wright_fixed_fleet.rs create mode 100644 crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/customer.rs create mode 100644 crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/fleet_plan.rs create mode 100644 crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/mod.rs create mode 100644 crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/route.rs create mode 100644 crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/strict_savings_hooks.rs diff --git a/crates/solverforge-solver/src/manager/phase_factory/list_clarke_wright/kernel.rs b/crates/solverforge-solver/src/manager/phase_factory/list_clarke_wright/kernel.rs index 5438fbe09..6bbfb82f9 100644 --- a/crates/solverforge-solver/src/manager/phase_factory/list_clarke_wright/kernel.rs +++ b/crates/solverforge-solver/src/manager/phase_factory/list_clarke_wright/kernel.rs @@ -423,16 +423,16 @@ fn run_clarke_wright_in_phase( }; if matched_count < assignable_routes.len() && completion_routes.is_none() { - tracing::warn!( + // The matched routes stay: a route the fleet cannot take leaves its + // elements unassigned for a completing construction, instead of + // discarding every route that did fit. + tracing::info!( constructed_routes = constructed_route_count, owner_ineligible_routes, available_slots = available_entity_slots.len(), matched_routes = matched_count, - "ListClarkeWright could not match every constructed route to a feasible empty entity" + "ListClarkeWright committed the routes it could match to a feasible empty entity" ); - pending_move_telemetry.record_discarded(phase_scope); - phase_scope.calculate_score(); - return; } if let Some(completed_routes) = completion_routes { diff --git a/crates/solverforge-solver/src/runtime/compiler/defaults.rs b/crates/solverforge-solver/src/runtime/compiler/defaults.rs index f68da0a94..8ca35584b 100644 --- a/crates/solverforge-solver/src/runtime/compiler/defaults.rs +++ b/crates/solverforge-solver/src/runtime/compiler/defaults.rs @@ -19,8 +19,10 @@ use super::default_local_search::{ use super::slots::{matching_list_slots, resolved_scalar_bindings}; use super::types::{CompiledListSlot, CompiledScalarSlot, RuntimeCompileError}; +mod list_completion; mod stages; +pub(crate) use list_completion::resolve_default_list_completion; pub(crate) use stages::{ resolve_default_postconstruction_kopt, resolve_default_preconstruction_stage, }; diff --git a/crates/solverforge-solver/src/runtime/compiler/defaults/list_completion.rs b/crates/solverforge-solver/src/runtime/compiler/defaults/list_completion.rs new file mode 100644 index 000000000..ccb3b5704 --- /dev/null +++ b/crates/solverforge-solver/src/runtime/compiler/defaults/list_completion.rs @@ -0,0 +1,75 @@ +//! The list completion stage of the omitted-construction profile. + +use std::fmt; + +use solverforge_config::{ConstructionHeuristicConfig, ConstructionHeuristicType}; +use solverforge_core::domain::PlanningSolution; + +use crate::heuristic::selector::nearby_list_change::CrossEntityDistanceMeter; + +use super::super::graph::{CompiledConstruction, ListConstructionKind}; +use super::super::types::CompiledListSlot; +use super::stages::{ + list_config, list_policies, DefaultConstructionReason, DefaultConstructionStage, + DefaultConstructionStepKind, DefaultPreconstructionStage, ResolvedDefaultConstructionPlan, + ResolvedDefaultConstructionStep, +}; +use super::DefaultRuntimeBindings; + +/// Resolves the list completion stage: one list cheapest insertion for every +/// list slot whose `needs_completion` entry is true, in binding order. +pub(crate) fn resolve_default_list_completion( + bindings: &DefaultRuntimeBindings, + needs_completion: &[bool], +) -> ResolvedDefaultConstructionPlan +where + S: PlanningSolution + Clone + Send + Sync + 'static, + V: Clone + PartialEq + Send + Sync + fmt::Debug + 'static, + DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, +{ + let steps = bindings + .list_slots + .iter() + .zip(needs_completion) + .filter(|(_, &needs)| needs) + .map(|(slot, _)| list_completion_step(slot)) + .collect(); + ResolvedDefaultConstructionPlan { + stage: DefaultConstructionStage::Preconstruction( + DefaultPreconstructionStage::ListCompletion, + ), + steps, + } +} + +fn list_completion_step( + slot: &CompiledListSlot, +) -> ResolvedDefaultConstructionStep +where + S: PlanningSolution + Clone + Send + Sync + 'static, + V: Clone + PartialEq + Send + Sync + fmt::Debug + 'static, + DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, +{ + let heuristic = ConstructionHeuristicType::ListCheapestInsertion; + let target = slot.identity(); + ResolvedDefaultConstructionStep { + kind: DefaultConstructionStepKind::ListCompletion, + reason: DefaultConstructionReason::ListElementsRemainUnassigned, + construction: CompiledConstruction::List { + kind: ListConstructionKind::CheapestInsertion, + config: ConstructionHeuristicConfig { + max_group_owners: slot + .element_group_policy() + .is_explicit() + .then_some(crate::list_groups::DEFAULT_GROUP_OWNERS), + ..list_config(heuristic, &target) + }, + slots: vec![slot.clone()], + }, + required_only: false, + target: Some(target), + list_policies: Some(list_policies(slot)), + } +} diff --git a/crates/solverforge-solver/src/runtime/compiler/defaults/stages.rs b/crates/solverforge-solver/src/runtime/compiler/defaults/stages.rs index 0c9f9778d..6eb395a73 100644 --- a/crates/solverforge-solver/src/runtime/compiler/defaults/stages.rs +++ b/crates/solverforge-solver/src/runtime/compiler/defaults/stages.rs @@ -32,14 +32,19 @@ use super::{DefaultAssignmentBinding, DefaultRuntimeBindings, DefaultScalarBindi #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) enum DefaultPreconstructionStage { ListConstruction, + /// Places the list elements the primary list construction left + /// unassigned. Resolved by the executor, which knows each slot's + /// remaining source work. + ListCompletion, AssignmentRequired, AssignmentOptional, ScalarFirstFit, } impl DefaultPreconstructionStage { - pub(crate) const ORDERED: [Self; 4] = [ + pub(crate) const ORDERED: [Self; 5] = [ Self::ListConstruction, + Self::ListCompletion, Self::AssignmentRequired, Self::AssignmentOptional, Self::ScalarFirstFit, @@ -57,6 +62,9 @@ pub(crate) enum DefaultConstructionStage { #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) enum DefaultConstructionStepKind { ListConstruction(ConstructionHeuristicType), + /// List cheapest insertion over the elements the primary list + /// construction left unassigned. + ListCompletion, AssignmentRequired, AssignmentOptional, ScalarFirstFit, @@ -77,6 +85,8 @@ pub(crate) enum DefaultConstructionReason { PrecedenceAndOrder, /// The list slot declares none of the specialized construction policies. NoSpecializedListPolicy, + /// List elements remain unassigned after the primary list construction. + ListElementsRemainUnassigned, /// The assignment group still has required rows unassigned. RequiredAssignmentsRemain, /// Every required row is assigned; optional rows remain. @@ -97,6 +107,7 @@ impl DefaultConstructionReason { } Self::PrecedenceAndOrder => "precedence_and_construction_order_declared", Self::NoSpecializedListPolicy => "no_specialized_list_policy_declared", + Self::ListElementsRemainUnassigned => "list_elements_remain_unassigned", Self::RequiredAssignmentsRemain => "required_assignments_remain", Self::OnlyOptionalAssignmentsRemain => "only_optional_assignments_remain", Self::UngroupedScalarSlot => "scalar_slot_outside_assignment_groups", @@ -154,6 +165,9 @@ where .iter() .map(list_construction_step) .collect(), + DefaultPreconstructionStage::ListCompletion => { + unreachable!("the executor resolves list completion from each slot's source work") + } DefaultPreconstructionStage::AssignmentRequired => bindings .assignment_groups .iter() @@ -236,6 +250,7 @@ where config: ConstructionHeuristicConfig { max_group_owners: (reason == DefaultConstructionReason::ElementGroupsDeclared) .then_some(crate::list_groups::DEFAULT_GROUP_OWNERS), + savings_neighbors: default_savings_neighbors(slot, heuristic), ..list_config(heuristic, &target) }, slots: vec![slot.clone()], @@ -306,6 +321,22 @@ where (0..slot.entity_count(solution)).any(|entity| slot.list_len(solution, entity) > 0) } +/// Savings each element keeps in a default Clarke-Wright construction whose +/// slot declares a savings neighbour source: the savings list then grows +/// linearly with the element count instead of with its square. +const DEFAULT_SAVINGS_NEIGHBORS: std::num::NonZeroU32 = std::num::NonZeroU32::new(40).unwrap(); + +fn default_savings_neighbors( + slot: &CompiledListSlot, + heuristic: ConstructionHeuristicType, +) -> Option { + use crate::builder::context::list_access::ListAccessCapability; + + (heuristic == ConstructionHeuristicType::ListClarkeWright + && slot.supports(ListAccessCapability::SavingsNeighbors)) + .then_some(DEFAULT_SAVINGS_NEIGHBORS) +} + fn default_list_construction_heuristic( slot: &CompiledListSlot, ) -> (ConstructionHeuristicType, DefaultConstructionReason) { @@ -395,7 +426,7 @@ fn scalar_first_fit_config(slot: &RuntimeScalarSlotId) -> ConstructionHeuristicC } } -fn list_config( +pub(super) fn list_config( heuristic: ConstructionHeuristicType, slot: &RuntimeScalarSlotId, ) -> ConstructionHeuristicConfig { @@ -413,7 +444,7 @@ fn target_config(slot: &RuntimeScalarSlotId) -> VariableTargetConfig { } } -fn list_policies( +pub(super) fn list_policies( slot: &CompiledListSlot, ) -> DefaultListPolicyProvenance { DefaultListPolicyProvenance { diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/default_construction.rs b/crates/solverforge-solver/src/runtime/compiler/executor/default_construction.rs new file mode 100644 index 000000000..3614cb669 --- /dev/null +++ b/crates/solverforge-solver/src/runtime/compiler/executor/default_construction.rs @@ -0,0 +1,189 @@ +//! Staged execution of the omitted-construction profile. +//! +//! Each default boundary is resolved against the current working solution +//! and run through the same prepared dispatcher as explicit construction. + +use std::fmt; + +use solverforge_core::domain::PlanningSolution; +use solverforge_core::score::{ParseableScore, Score}; +use solverforge_scoring::Director; + +use crate::builder::context::list_access::ListAccess; +use crate::heuristic::selector::nearby_list_change::CrossEntityDistanceMeter; +use crate::runtime::compiler::DefaultConstructionStepKind; +use crate::scope::{ProgressCallback, SolverScope}; + +use super::execute::execute_prepared_construction; +use super::{ + DefaultConstructionStageExecutionRecord, DefaultRuntimeConstructionExecution, + PreparedDefaultRuntime, PreparedRuntimeExecution, ResolvedConstructionExecutionOutcome, + ResolvedConstructionExecutionStep, RuntimeInstantiationError, +}; + +/// Executes the staged omitted-construction profile through the same prepared +/// dispatcher as an explicitly configured construction phase. +/// +/// Each boundary is resolved against the current working solution. Structural +/// list declarations were registered before phase execution, but a reached +/// source-backed child binds and validates its source before deciding whether +/// work remains. Stage resolution can therefore choose Clarke-Wright, +/// assignment, or K-opt without rebuilding model metadata. In particular, the +/// post-construction K-opt boundary observes routes only after preceding +/// construction stages. +pub(crate) fn execute_prepared_default_construction( + execution: &mut PreparedRuntimeExecution, + default: &PreparedDefaultRuntime, + solver_scope: &mut SolverScope<'_, S, D, ProgressCb>, +) -> Result +where + S: PlanningSolution + Clone + Send + Sync + 'static, + S::Score: Score + Copy + Ord + ParseableScore, + V: Clone + PartialEq + Into + Send + Sync + fmt::Debug + 'static, + DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + D: Director, + ProgressCb: ProgressCallback, +{ + let mut record = DefaultRuntimeConstructionExecution::default(); + for stage in crate::runtime::compiler::DefaultPreconstructionStage::ORDERED { + let resolved = + if stage == crate::runtime::compiler::DefaultPreconstructionStage::ListCompletion { + let needs_completion = list_slots_needing_completion( + execution, + default, + record.stages.last(), + solver_scope.working_solution(), + )?; + super::super::defaults::resolve_default_list_completion( + &default.bindings, + &needs_completion, + ) + } else { + super::super::defaults::resolve_default_preconstruction_stage( + &default.bindings, + stage, + solver_scope.working_solution(), + ) + }; + record.push(execute_resolved_default_construction_plan( + execution, + default, + &resolved, + solver_scope, + )?); + } + + let resolved = super::super::defaults::resolve_default_postconstruction_kopt( + &default.bindings, + solver_scope.working_solution(), + ); + record.push(execute_resolved_default_construction_plan( + execution, + default, + &resolved, + solver_scope, + )?); + Ok(record) +} + +/// Which list slots the list completion stage must place, from the list +/// construction stage that just ran: only Clarke-Wright can leave elements +/// unassigned without being terminated, so only a slot whose Clarke-Wright +/// child executed has its remaining source work read. +fn list_slots_needing_completion( + execution: &mut PreparedRuntimeExecution, + default: &PreparedDefaultRuntime, + list_construction: Option<&DefaultConstructionStageExecutionRecord>, + solution: &S, +) -> Result, RuntimeInstantiationError> +where + S: PlanningSolution + Clone + Send + Sync + 'static, + V: Clone + PartialEq + Into + Send + Sync + fmt::Debug + 'static, + DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, +{ + let steps = list_construction.map_or(&[][..], |stage| stage.steps.as_slice()); + let mut needs_completion = vec![false; default.bindings.list_slots.len()]; + for (needs, (slot, step)) in needs_completion + .iter_mut() + .zip(default.bindings.list_slots.iter().zip(steps)) + { + let clarke_wright_ran = step.kind + == DefaultConstructionStepKind::ListConstruction( + solverforge_config::ConstructionHeuristicType::ListClarkeWright, + ) + && step.outcome == ResolvedConstructionExecutionOutcome::Executed; + if clarke_wright_ran { + // The source is bound by the construction that just ran, so + // comparing list lengths with it reads no element keys. + *needs = match execution.bound_list_source_len(default.phase_index, slot)? { + Some(source_len) => { + let assigned: usize = (0..ListAccess::entity_count(slot, solution)) + .map(|entity| ListAccess::list_len(slot, solution, entity)) + .sum(); + assigned < source_len + } + None => { + execution.current_list_unassigned_count(default.phase_index, slot, solution)? + > 0 + } + }; + } + } + Ok(needs_completion) +} + +fn execute_resolved_default_construction_plan( + execution: &mut PreparedRuntimeExecution, + default: &PreparedDefaultRuntime, + resolved: &crate::runtime::compiler::ResolvedDefaultConstructionPlan, + solver_scope: &mut SolverScope<'_, S, D, ProgressCb>, +) -> Result +where + S: PlanningSolution + Clone + Send + Sync + 'static, + S::Score: Score + Copy + Ord + ParseableScore, + V: Clone + PartialEq + Into + Send + Sync + fmt::Debug + 'static, + DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, + D: Director, + ProgressCb: ProgressCallback, +{ + let mut steps = Vec::with_capacity(resolved.steps.len()); + for step in &resolved.steps { + let construction = + execution.prepare_resolved_construction(default.phase_index, &step.construction)?; + let execution = execute_prepared_construction( + execution, + &construction, + step.required_only, + solver_scope, + )?; + steps.push(ResolvedConstructionExecutionStep { + kind: step.kind, + reason: step.reason, + required_only: step.required_only, + target: step.target.clone(), + list_policies: step.list_policies.clone(), + outcome: execution.outcome, + }); + } + let outcome = if steps + .iter() + .any(|step| step.outcome == ResolvedConstructionExecutionOutcome::Executed) + { + ResolvedConstructionExecutionOutcome::Executed + } else if steps + .iter() + .any(|step| step.outcome == ResolvedConstructionExecutionOutcome::SkippedTerminated) + { + ResolvedConstructionExecutionOutcome::SkippedTerminated + } else { + ResolvedConstructionExecutionOutcome::SkippedNoWork + }; + Ok(DefaultConstructionStageExecutionRecord { + stage: resolved.stage, + outcome, + steps, + }) +} diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/execute.rs b/crates/solverforge-solver/src/runtime/compiler/executor/execute.rs index 8bc5c1205..feac7ad9c 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/execute.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/execute.rs @@ -30,10 +30,8 @@ use super::list_construction::{ execute_runtime_list_round_robin, }; use super::{ - ConstructionExecution, DefaultConstructionStageExecutionRecord, - DefaultRuntimeConstructionExecution, PreparedConstruction, PreparedDefaultRuntime, - PreparedListSlot, PreparedRuntimeExecution, ResolvedConstructionExecutionOutcome, - ResolvedConstructionExecutionStep, RuntimeInstantiationError, + ConstructionExecution, PreparedConstruction, PreparedListSlot, PreparedRuntimeExecution, + RuntimeInstantiationError, }; /// Executes one explicitly prepared construction node. @@ -296,112 +294,6 @@ where }) } -/// Executes the staged omitted-construction profile through the same prepared -/// dispatcher as an explicitly configured construction phase. -/// -/// Each boundary is resolved against the current working solution. Structural -/// list declarations were registered before phase execution, but a reached -/// source-backed child binds and validates its source before deciding whether -/// work remains. Stage resolution can therefore choose Clarke-Wright, -/// assignment, or K-opt without rebuilding model metadata. In particular, the -/// post-construction K-opt boundary observes routes only after preceding -/// construction stages. -pub(crate) fn execute_prepared_default_construction( - execution: &mut PreparedRuntimeExecution, - default: &PreparedDefaultRuntime, - solver_scope: &mut SolverScope<'_, S, D, ProgressCb>, -) -> Result -where - S: PlanningSolution + Clone + Send + Sync + 'static, - S::Score: Score + Copy + Ord + ParseableScore, - V: Clone + PartialEq + Into + Send + Sync + fmt::Debug + 'static, - DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, - IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, - D: Director, - ProgressCb: ProgressCallback, -{ - let mut record = DefaultRuntimeConstructionExecution::default(); - for stage in crate::runtime::compiler::DefaultPreconstructionStage::ORDERED { - let resolved = super::super::defaults::resolve_default_preconstruction_stage( - &default.bindings, - stage, - solver_scope.working_solution(), - ); - record.push(execute_resolved_default_construction_plan( - execution, - default, - &resolved, - solver_scope, - )?); - } - - let resolved = super::super::defaults::resolve_default_postconstruction_kopt( - &default.bindings, - solver_scope.working_solution(), - ); - record.push(execute_resolved_default_construction_plan( - execution, - default, - &resolved, - solver_scope, - )?); - Ok(record) -} - -fn execute_resolved_default_construction_plan( - execution: &mut PreparedRuntimeExecution, - default: &PreparedDefaultRuntime, - resolved: &crate::runtime::compiler::ResolvedDefaultConstructionPlan, - solver_scope: &mut SolverScope<'_, S, D, ProgressCb>, -) -> Result -where - S: PlanningSolution + Clone + Send + Sync + 'static, - S::Score: Score + Copy + Ord + ParseableScore, - V: Clone + PartialEq + Into + Send + Sync + fmt::Debug + 'static, - DM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, - IDM: Clone + Send + Sync + fmt::Debug + CrossEntityDistanceMeter, - D: Director, - ProgressCb: ProgressCallback, -{ - let mut steps = Vec::with_capacity(resolved.steps.len()); - for step in &resolved.steps { - let construction = - execution.prepare_resolved_construction(default.phase_index, &step.construction)?; - let execution = execute_prepared_construction( - execution, - &construction, - step.required_only, - solver_scope, - )?; - steps.push(ResolvedConstructionExecutionStep { - kind: step.kind, - reason: step.reason, - required_only: step.required_only, - target: step.target.clone(), - list_policies: step.list_policies.clone(), - outcome: execution.outcome, - }); - } - let outcome = if steps - .iter() - .any(|step| step.outcome == ResolvedConstructionExecutionOutcome::Executed) - { - ResolvedConstructionExecutionOutcome::Executed - } else if steps - .iter() - .any(|step| step.outcome == ResolvedConstructionExecutionOutcome::SkippedTerminated) - { - ResolvedConstructionExecutionOutcome::SkippedTerminated - } else { - ResolvedConstructionExecutionOutcome::SkippedNoWork - }; - Ok(DefaultConstructionStageExecutionRecord { - stage: resolved.stage, - outcome, - steps, - }) -} - /// Executes one configured list construction family in declaration order. /// /// The callback type is monomorphized at the call site. It is not a phase diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/mod.rs b/crates/solverforge-solver/src/runtime/compiler/executor/mod.rs index 5aed3fcf8..c42daf4a9 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/mod.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/mod.rs @@ -4,6 +4,7 @@ //! the shared neighborhood kernels and executes the resulting phase sequence. mod completion; +mod default_construction; mod execute; mod execution_record; pub(crate) mod list_construction; @@ -17,7 +18,8 @@ mod trace; #[cfg(test)] mod trace_tests; -pub(crate) use execute::{execute_prepared_construction, execute_prepared_default_construction}; +pub(crate) use default_construction::execute_prepared_default_construction; +pub(crate) use execute::execute_prepared_construction; pub(crate) use execution_record::{ ConstructionExecution, DefaultConstructionStageExecutionRecord, DefaultRuntimeConstructionExecution, ResolvedConstructionExecutionOutcome, diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/prepared/types.rs b/crates/solverforge-solver/src/runtime/compiler/executor/prepared/types.rs index d647b1567..b7c7e45d1 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/prepared/types.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/prepared/types.rs @@ -195,6 +195,26 @@ where .map(|unassigned| unassigned.len()) } + /// The element count of a slot's source when a construction already + /// bound it; `None` while unbound. + pub(crate) fn bound_list_source_len( + &self, + phase_index: usize, + slot: &CompiledListSlot, + ) -> Result, RuntimeInstantiationError> { + let target = slot.identity(); + let catalog_index = + self.list_source_catalog + .index_for(slot) + .ok_or(RuntimeInstantiationError { + phase_index, + kind: super::RuntimeInstantiationErrorKind::MissingRegisteredSource { target }, + })?; + Ok(self.list_source_indices[catalog_index] + .as_ref() + .map(|source_index| source_index.source_count())) + } + /// Borrows an already-bound source without a map lookup or rebinding. pub(crate) fn bound_list_source( &self, diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/trace.rs b/crates/solverforge-solver/src/runtime/compiler/executor/trace.rs index 0392c4c9e..fe5b6890f 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/trace.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/trace.rs @@ -168,7 +168,8 @@ fn default_step_plan(step: &ResolvedConstructionExecutionStep) -> CandidateTrace policies.savings_metric_class.to_string(), ), ]), - DefaultConstructionStepKind::ListConstruction(_) => attributes.extend([ + DefaultConstructionStepKind::ListConstruction(_) + | DefaultConstructionStepKind::ListCompletion => attributes.extend([ ( "construction_order".to_string(), policies.construction_order.to_string(), @@ -270,6 +271,9 @@ fn default_stage_label(stage: DefaultConstructionStage) -> &'static str { DefaultConstructionStage::Preconstruction( crate::runtime::compiler::DefaultPreconstructionStage::ListConstruction, ) => "list_construction", + DefaultConstructionStage::Preconstruction( + crate::runtime::compiler::DefaultPreconstructionStage::ListCompletion, + ) => "list_completion", DefaultConstructionStage::Preconstruction( crate::runtime::compiler::DefaultPreconstructionStage::AssignmentRequired, ) => "assignment_required", @@ -296,6 +300,7 @@ fn default_step_kind_label(kind: DefaultConstructionStepKind) -> &'static str { solverforge_config::ConstructionHeuristicType::ListClarkeWright => "list_clarke_wright", other => panic!("default list construction retained invalid heuristic {other:?}"), }, + DefaultConstructionStepKind::ListCompletion => "list_completion_cheapest_insertion", DefaultConstructionStepKind::AssignmentRequired => "assignment_required", DefaultConstructionStepKind::AssignmentOptional => "assignment_optional", DefaultConstructionStepKind::ScalarFirstFit => "scalar_first_fit", @@ -317,6 +322,9 @@ fn default_step_kind_trace_name(kind: DefaultConstructionStepKind) -> &'static s DefaultConstructionStepKind::ListConstruction( solverforge_config::ConstructionHeuristicType::ListRegretInsertion, ) => "solverforge.runtime.construction.regret_insertion", + DefaultConstructionStepKind::ListCompletion => { + "solverforge.runtime.construction.cheapest_insertion" + } DefaultConstructionStepKind::AssignmentRequired | DefaultConstructionStepKind::AssignmentOptional => { "solverforge.runtime.construction.grouped_scalar" diff --git a/crates/solverforge/tests/list_clarke_wright_fixed_fleet.rs b/crates/solverforge/tests/list_clarke_wright_fixed_fleet.rs new file mode 100644 index 000000000..d6f620c08 --- /dev/null +++ b/crates/solverforge/tests/list_clarke_wright_fixed_fleet.rs @@ -0,0 +1,77 @@ +//! Clarke-Wright construction on a fixed fleet: when the savings routes +//! outnumber the vehicles, the routes the fleet can take stay committed and +//! the default construction places the remaining customers, so a fixed fleet +//! never ends construction with every customer unassigned. + +use solverforge::SolverConfig; + +#[path = "list_clarke_wright_fixed_fleet/domain/mod.rs"] +mod domain; + +use domain::{build_fleet_plan, FleetPlan}; + +const CUSTOMERS: usize = 20; + +fn solve(plan: FleetPlan, toml: &str) -> FleetPlan { + let config = SolverConfig::from_toml_str(toml).expect("config parses"); + plan.solve_with_config(config).expect("solve completes") +} + +fn assigned_customers(plan: &FleetPlan) -> Vec { + let mut assigned: Vec = plan + .routes + .iter() + .flat_map(|route| route.visits.iter().copied()) + .collect(); + assigned.sort_unstable(); + assigned +} + +fn every_customer() -> Vec { + (1..=CUSTOMERS).collect() +} + +const DEFAULT_POLICY: &str = "environment_mode = \"reproducible\"\n\ + random_seed = 42\n\ + [termination]\n\ + step_count_limit = 20\n"; + +#[test] +fn default_construction_completes_a_fleet_smaller_than_the_savings_routes() { + // Capacity 5 over 20 unit demands needs four routes; two vehicles exist. + let solved = solve(build_fleet_plan(CUSTOMERS, 2, 5, None), DEFAULT_POLICY); + assert_eq!(assigned_customers(&solved), every_customer()); + assert_eq!(solved.score.map(|score| score.hard()), Some(0)); +} + +#[test] +fn default_construction_completes_a_fixed_fleet_with_time_windows() { + let solved = solve(build_fleet_plan(CUSTOMERS, 3, 4, Some(12)), DEFAULT_POLICY); + assert_eq!(assigned_customers(&solved), every_customer()); +} + +#[test] +fn explicit_clarke_wright_keeps_the_routes_the_fleet_can_take() { + let solved = solve( + build_fleet_plan(CUSTOMERS, 2, 5, None), + "environment_mode = \"reproducible\"\n\ + random_seed = 42\n\ + [[phases]]\n\ + type = \"construction_heuristic\"\n\ + construction_heuristic_type = \"list_clarke_wright\"\n\ + [[phases]]\n\ + type = \"construction_heuristic\"\n\ + construction_heuristic_type = \"list_cheapest_insertion\"\n", + ); + assert_eq!(assigned_customers(&solved), every_customer()); + assert!( + solved.routes.iter().all(|route| !route.visits.is_empty()), + "both vehicles carry a committed route" + ); +} + +#[test] +fn a_fleet_that_fits_the_savings_routes_is_unchanged_by_completion() { + let solved = solve(build_fleet_plan(CUSTOMERS, 4, 5, None), DEFAULT_POLICY); + assert_eq!(assigned_customers(&solved), every_customer()); +} diff --git a/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/customer.rs b/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/customer.rs new file mode 100644 index 000000000..86993619b --- /dev/null +++ b/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/customer.rs @@ -0,0 +1,7 @@ +use solverforge::prelude::*; + +#[problem_fact] +pub struct Customer { + #[planning_id] + pub id: usize, +} diff --git a/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/fleet_plan.rs b/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/fleet_plan.rs new file mode 100644 index 000000000..9391bcf0e --- /dev/null +++ b/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/fleet_plan.rs @@ -0,0 +1,128 @@ +use std::sync::Arc; + +use solverforge::cvrp::{DenseMatrix, ProblemData}; +use solverforge::prelude::*; +use solverforge::stream::joiner::equal_bi; +use solverforge::stream::ConstraintFactory; +use solverforge::SolverConfig; + +use super::{Customer, Route}; + +#[planning_solution( + constraints = "define_constraints", + config = "solver_config_for_plan" +)] +pub struct FleetPlan { + #[problem_fact_collection] + pub customers: Vec, + + #[planning_list_element_collection(owner = "routes")] + pub customer_values: Vec, + + #[planning_entity_collection] + pub routes: Vec, + + #[planning_score] + pub score: Option, + + pub shared: Arc, + pub time_limit_secs: u64, +} + +impl solverforge::cvrp::VrpSolution for FleetPlan { + type Metric = DenseMatrix; + + fn vehicle_data(&self, _entity_idx: usize) -> Option<&ProblemData> { + Some(&self.shared) + } + + fn vehicle_visits(&self, entity_idx: usize) -> &[usize] { + &self.routes[entity_idx].visits + } + + fn vehicle_visits_mut(&mut self, entity_idx: usize) -> &mut Vec { + &mut self.routes[entity_idx].visits + } + + fn vehicle_count(&self) -> usize { + self.routes.len() + } +} + +fn define_constraints() -> impl ConstraintSet { + (ConstraintFactory::::new() + .for_each(FleetPlan::customers()) + .if_not_exists(( + ConstraintFactory::::new() + .for_each(FleetPlan::routes()) + .flattened(|route: &Route| &route.visits), + equal_bi( + |customer: &Customer| customer.id, + |assigned: &usize| *assigned, + ), + )) + .penalize(HardSoftScore::ONE_HARD) + .named("all_customers_assigned"),) +} + +fn solver_config_for_plan(plan: &FleetPlan, config: SolverConfig) -> SolverConfig { + config.with_termination_seconds(plan.time_limit_secs) +} + +/// A fleet of `vehicle_count` routes with `capacity` each over unit demands; +/// `window_end` closes every even customer's time window at that time. +pub fn build_fleet_plan( + customer_count: usize, + vehicle_count: usize, + capacity: i64, + window_end: Option, +) -> FleetPlan { + let dimension = customer_count + 1; + let mut distance_matrix = vec![vec![0_i64; dimension]; dimension]; + for (i, row) in distance_matrix.iter_mut().enumerate() { + for (j, cell) in row.iter_mut().enumerate() { + let gap = i.abs_diff(j) as i64; + *cell = if i == j { 0 } else { gap + 1 }; + } + } + let travel_times = distance_matrix.clone(); + let time_windows = (0..dimension) + .map(|node| match window_end { + Some(end) if node > 0 && node % 2 == 0 => (0, end), + _ => (0, i64::MAX), + }) + .collect(); + + let shared = Arc::new(ProblemData { + capacity, + depot: 0, + demands: std::iter::once(0) + .chain(std::iter::repeat_n(1, customer_count)) + .collect(), + metric: DenseMatrix::new(distance_matrix, travel_times), + time_windows, + service_durations: vec![0; dimension], + vehicle_departure_time: 0, + }); + let data_addr = Arc::as_ptr(&shared) as usize; + let customer_values: Vec = (1..=customer_count).collect(); + + FleetPlan { + customers: customer_values + .iter() + .copied() + .map(|id| Customer { id }) + .collect(), + customer_values, + routes: (0..vehicle_count) + .map(|id| Route { + id, + visits: Vec::new(), + data_addr, + }) + .collect(), + score: None, + shared, + time_limit_secs: 30, + } +} diff --git a/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/mod.rs b/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/mod.rs new file mode 100644 index 000000000..10b082de4 --- /dev/null +++ b/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/mod.rs @@ -0,0 +1,12 @@ +solverforge::planning_model! { + root = "crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain"; + + mod customer; + mod fleet_plan; + mod route; + pub mod strict_savings_hooks; + + pub use customer::Customer; + pub use fleet_plan::{build_fleet_plan, FleetPlan}; + pub use route::Route; +} diff --git a/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/route.rs b/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/route.rs new file mode 100644 index 000000000..40335e204 --- /dev/null +++ b/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/route.rs @@ -0,0 +1,20 @@ +use solverforge::prelude::*; + +#[planning_entity] +pub struct Route { + #[planning_id] + pub id: usize, + + #[planning_list_variable( + element_collection = "customer_values", + solution_trait = "solverforge::cvrp::VrpSolution", + distance_meter = "solverforge::cvrp::MatrixDistanceMeter", + intra_distance_meter = "solverforge::cvrp::MatrixIntraDistanceMeter", + route_hooks = "solverforge::cvrp::route_hooks", + savings_hooks = "super::strict_savings_hooks", + savings_metric_class_fn = "solverforge::cvrp::savings_metric_class" + )] + pub visits: Vec, + + pub data_addr: usize, +} diff --git a/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/strict_savings_hooks.rs b/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/strict_savings_hooks.rs new file mode 100644 index 000000000..8f9c60f77 --- /dev/null +++ b/crates/solverforge/tests/list_clarke_wright_fixed_fleet/domain/strict_savings_hooks.rs @@ -0,0 +1,19 @@ +//! Clarke-Wright hooks that reject a merge breaking capacity or a time +//! window, so the savings routes can outnumber a fixed fleet. + +use solverforge::cvrp::VrpSolution; + +/// The depot of the route's vehicle. +pub fn depot(plan: &S, entity_idx: usize) -> usize { + solverforge::cvrp::savings_depot_for_entity(plan, entity_idx) +} + +/// The leg distance the savings are computed from. +pub fn distance(plan: &S, entity_idx: usize, from: usize, to: usize) -> i64 { + solverforge::cvrp::savings_distance(plan, entity_idx, from, to) +} + +/// Admits a merged route only when it keeps capacity and time windows. +pub fn feasible(plan: &S, entity_idx: usize, route: &[usize]) -> bool { + solverforge::cvrp::route_feasible(plan, entity_idx, route) +} diff --git a/docs/configuration.md b/docs/configuration.md index 0eb6bea41..1d333b051 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -121,6 +121,21 @@ Each list slot gets the first construction whose declarations it has: | precedence and construction order | `ListRoundRobin` | `precedence_and_construction_order_declared` | | none of these | `ListCheapestInsertion` | `no_specialized_list_policy_declared` | +The default `ListClarkeWright` keeps 40 savings per element when the slot +declares a savings neighbour hook (the `domain = "cvrp"` profile does), so its +memory grows linearly with the stop count; without the hook it scores every +pair. + +Clarke-Wright builds its routes before it knows the fleet. When the savings +hooks reject merges (capacity or time windows in custom `savings_hooks`) and +the routes outnumber the vehicles that can take them, the routes that fit stay +committed and the rest of their elements stay unassigned. The default +construction then runs `ListCheapestInsertion` over those elements +(`list_elements_remain_unassigned`), so a fixed fleet always ends construction +with every element placed. An explicit `list_clarke_wright` phase does the +same partial commit; follow it with a `list_cheapest_insertion` phase on a +fixed fleet. + After list construction, a slot with route hooks and a non-empty route runs `ListKOpt` (`route_hooks_declared_and_route_non_empty`). From d3661a11b98b1d2afcf6e663221ae94d3d4ec34e Mon Sep 17 00:00:00 2001 From: Vittorio Distefano Date: Tue, 17 Nov 2026 19:07:18 +0100 Subject: [PATCH 2/3] feat(policy): measure default search effort and weight families by candidate cost The default local search collected 256 accepted moves before every step, whatever the model, so a rostering solve made about 220 steps in 10 s and a CVRP solve about 600. Five-seed solverforge-bench runs at 10 s pick a count per model shape: list variables collect 4, scalar groups and scalar models with nearby or repair moves collect 32, and the precedence forager's ceiling is 32. On CVRP the new default now matches the hand-tuned configuration; job shop and rostering improve on every instance. The default union also stopped giving every family an equal share of the step. List ruin and unbounded k-opt rebuild or scan whole routes per candidate (48 ms per ruin move at 10k stops), so they draw weight 1 against 4 for every other family; they stay available for diversification. The resolved plan reports the weights as weighting = fixed:[...]. Refs #253 --- .../runtime/compiler/default_local_search.rs | 27 +++++++++++++++++++ .../compiler/default_local_search/policy.rs | 21 +++++++++++---- .../compiler/default_local_search/trace.rs | 9 +++++-- .../default_local_search_scalar_tests.rs | 4 +-- .../selector_groups.rs | 2 +- .../compiler/defaults_tests/selection.rs | 7 ++++- .../compiler/executor/local_search/lower.rs | 9 +++++-- .../compiler/executor/runner/lowering.rs | 2 ++ .../tests/resolved_policy_telemetry.rs | 10 +++---- docs/configuration.md | 20 +++++++++----- 10 files changed, 87 insertions(+), 24 deletions(-) diff --git a/crates/solverforge-solver/src/runtime/compiler/default_local_search.rs b/crates/solverforge-solver/src/runtime/compiler/default_local_search.rs index ed0f5a31d..3fe09fd2d 100644 --- a/crates/solverforge-solver/src/runtime/compiler/default_local_search.rs +++ b/crates/solverforge-solver/src/runtime/compiler/default_local_search.rs @@ -92,6 +92,17 @@ pub(crate) enum DefaultLocalSearchSelectorFamily { } impl DefaultLocalSearchSelectorFamily { + /// Share of the default union's candidate draws. Ruin-and-recreate and + /// unbounded k-opt rebuild or scan whole routes per candidate (48 ms per + /// ruin move at 10k stops), so they draw a quarter as often as the + /// families whose candidates touch a few positions. + pub(crate) fn cost_weight(self) -> u64 { + match self { + Self::UnboundedKOpt | Self::ListRuin => 1, + _ => 4, + } + } + pub(crate) fn trace_label(self) -> &'static str { match self { Self::ListGroupChange => "list_group_change", @@ -176,6 +187,22 @@ pub(crate) struct DefaultLocalSearchPlan { pub excluded: Vec, } +impl DefaultLocalSearchPlan { + /// One cost weight per selector, or `None` when every family weighs the + /// same and the union stays equally weighted. + pub(crate) fn family_weights(&self) -> Option> { + let weights: Vec = self + .selectors + .iter() + .map(|selector| selector.family.cost_weight()) + .collect(); + weights + .windows(2) + .any(|pair| pair[0] != pair[1]) + .then_some(weights) + } +} + pub(super) fn target_for(slot: &RuntimeScalarSlotId) -> VariableTargetConfig { VariableTargetConfig { entity_class: Some(slot.entity_class.to_string()), diff --git a/crates/solverforge-solver/src/runtime/compiler/default_local_search/policy.rs b/crates/solverforge-solver/src/runtime/compiler/default_local_search/policy.rs index 0fca0e771..0943f033b 100644 --- a/crates/solverforge-solver/src/runtime/compiler/default_local_search/policy.rs +++ b/crates/solverforge-solver/src/runtime/compiler/default_local_search/policy.rs @@ -17,7 +17,16 @@ mod list; mod scalar; const DEFAULT_LOCAL_SEARCH_LATE_ACCEPTANCE_SIZE: usize = 400; -const DEFAULT_LOCAL_SEARCH_ACCEPTED_COUNT: usize = 256; +/// Accepted moves a list-variable step collects before it picks one. Few +/// accepted moves per step buy many more steps: on the CVRP bench, 4 beats +/// 32 and 256 at every instance size. +const DEFAULT_LIST_ACCEPTED_COUNT: usize = 4; +/// Accepted moves a scalar step with grouped, nearby or repair moves +/// collects. On the rostering bench, 32 beats both 4 and 256. +const DEFAULT_SCALAR_ACCEPTED_COUNT: usize = 32; +/// The accepted-count ceiling under the precedence forager: on job shop, 32 +/// beats both 4 and 256. +const DEFAULT_PRECEDENCE_ACCEPTED_COUNT: usize = 32; const DEFAULT_SIMULATED_ANNEALING_DECAY_RATE: f64 = 0.999_985; pub(crate) fn compile_default_local_search_components( @@ -63,16 +72,18 @@ where let forager = if has_groups && !has_lists { DefaultLocalSearchForagerPolicy::AcceptedCount { - limit: DEFAULT_LOCAL_SEARCH_ACCEPTED_COUNT, + limit: DEFAULT_SCALAR_ACCEPTED_COUNT, } } else if has_precedence { DefaultLocalSearchForagerPolicy::FirstLastStepScoreImproving { - accepted_count_limit: Some(DEFAULT_LOCAL_SEARCH_ACCEPTED_COUNT), + accepted_count_limit: Some(DEFAULT_PRECEDENCE_ACCEPTED_COUNT), } } else { DefaultLocalSearchForagerPolicy::AcceptedCount { - limit: if has_lists || has_nearby_scalar || has_conflict_repairs { - DEFAULT_LOCAL_SEARCH_ACCEPTED_COUNT + limit: if has_lists { + DEFAULT_LIST_ACCEPTED_COUNT + } else if has_nearby_scalar || has_conflict_repairs { + DEFAULT_SCALAR_ACCEPTED_COUNT } else { 1 }, diff --git a/crates/solverforge-solver/src/runtime/compiler/default_local_search/trace.rs b/crates/solverforge-solver/src/runtime/compiler/default_local_search/trace.rs index fbf58abee..17e5d46af 100644 --- a/crates/solverforge-solver/src/runtime/compiler/default_local_search/trace.rs +++ b/crates/solverforge-solver/src/runtime/compiler/default_local_search/trace.rs @@ -21,8 +21,13 @@ impl DefaultLocalSearchPlan { selection_order_label(self.selection_order).to_string(), ), ("selector_count", self.selectors.len().to_string()), - // Every default union weighs its families equally. - ("weighting", "equal".to_string()), + ( + "weighting", + self.family_weights().map_or_else( + || "equal".to_string(), + |weights| format!("fixed:{weights:?}"), + ), + ), ("excluded_families", self.excluded_families_signature()), ]; match self.components.acceptor { diff --git a/crates/solverforge-solver/src/runtime/compiler/default_local_search_scalar_tests.rs b/crates/solverforge-solver/src/runtime/compiler/default_local_search_scalar_tests.rs index b13aad678..ea69f5b91 100644 --- a/crates/solverforge-solver/src/runtime/compiler/default_local_search_scalar_tests.rs +++ b/crates/solverforge-solver/src/runtime/compiler/default_local_search_scalar_tests.rs @@ -380,7 +380,7 @@ fn typed_and_dynamic_scalar_capabilities_have_identical_default_policy() { ); assert_eq!( typed.components.forager, - DefaultLocalSearchForagerPolicy::AcceptedCount { limit: 256 } + DefaultLocalSearchForagerPolicy::AcceptedCount { limit: 32 } ); assert_eq!( trace_value(&typed, "simulated_annealing_decay_rate_bits"), @@ -392,7 +392,7 @@ fn typed_and_dynamic_scalar_capabilities_have_identical_default_policy() { ); assert_eq!( trace_value(&typed, "forager_accepted_count_limit"), - Some("256".to_string()) + Some("32".to_string()) ); } diff --git a/crates/solverforge-solver/src/runtime/compiler/default_local_search_scalar_tests/selector_groups.rs b/crates/solverforge-solver/src/runtime/compiler/default_local_search_scalar_tests/selector_groups.rs index 6fc48787d..3cb692021 100644 --- a/crates/solverforge-solver/src/runtime/compiler/default_local_search_scalar_tests/selector_groups.rs +++ b/crates/solverforge-solver/src/runtime/compiler/default_local_search_scalar_tests/selector_groups.rs @@ -81,7 +81,7 @@ fn typed_and_dynamic_assignment_groups_hide_scalar_leaves_and_keep_group_policy( ); assert_eq!( plan.components.forager, - DefaultLocalSearchForagerPolicy::AcceptedCount { limit: 256 } + DefaultLocalSearchForagerPolicy::AcceptedCount { limit: 32 } ); assert!(plan.candidate_trace_plan().is_complete()); } diff --git a/crates/solverforge-solver/src/runtime/compiler/defaults_tests/selection.rs b/crates/solverforge-solver/src/runtime/compiler/defaults_tests/selection.rs index b70a8923a..f501bbd5c 100644 --- a/crates/solverforge-solver/src/runtime/compiler/defaults_tests/selection.rs +++ b/crates/solverforge-solver/src/runtime/compiler/defaults_tests/selection.rs @@ -217,7 +217,12 @@ fn equivalent_typed_and_dynamic_cvrp_capabilities_freeze_the_same_default_local_ ); assert_eq!( typed.components.forager, - DefaultLocalSearchForagerPolicy::AcceptedCount { limit: 256 } + DefaultLocalSearchForagerPolicy::AcceptedCount { limit: 4 } + ); + assert_eq!( + typed.family_weights(), + Some(vec![4, 4, 4, 4, 4, 4, 1]), + "ruin keeps its family but draws a quarter as often" ); let typed_excluded = typed .excluded diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/local_search/lower.rs b/crates/solverforge-solver/src/runtime/compiler/executor/local_search/lower.rs index 0e643099d..80b18af1f 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/local_search/lower.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/local_search/lower.rs @@ -120,6 +120,7 @@ where pub(crate) fn lower_default_selector_union( solver_config: &SolverConfig, selection_order: UnionSelectionOrder, + family_weights: Option>, graphs: Vec>, ) -> Result, RuntimeLocalSearchLoweringError> where @@ -145,8 +146,12 @@ where .collect::, _>>()?; composition.push(SelectorCompositionNode::Union { selection_order, - weighting: solverforge_config::UnionWeighting::Equal, - weights: Vec::new(), + weighting: if family_weights.is_some() { + solverforge_config::UnionWeighting::Fixed + } else { + solverforge_config::UnionWeighting::Equal + }, + weights: family_weights.unwrap_or_default(), children, }); Ok(SelectorCompositionState::new(composition)) diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/runner/lowering.rs b/crates/solverforge-solver/src/runtime/compiler/executor/runner/lowering.rs index 49ae2ef99..610fc0bdd 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/runner/lowering.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/runner/lowering.rs @@ -75,6 +75,7 @@ where let selector = lower_default_selector_union( solver_config, plan.selection_order, + plan.family_weights(), std::mem::take(&mut mandatory_bindings.local_search_nodes), ) .map_err(|error| lowering_error(phase_index, error))?; @@ -151,6 +152,7 @@ where lower_default_selector_union( solver_config, plan.selection_order, + plan.family_weights(), std::mem::take(&mut mandatory.local_search_nodes), ) .map_err(|error| lowering_error(phase_index, error))?, diff --git a/crates/solverforge/tests/resolved_policy_telemetry.rs b/crates/solverforge/tests/resolved_policy_telemetry.rs index 710436b60..4988f0cee 100644 --- a/crates/solverforge/tests/resolved_policy_telemetry.rs +++ b/crates/solverforge/tests/resolved_policy_telemetry.rs @@ -77,11 +77,11 @@ fn final_telemetry_names_the_default_construction_and_why() { let local_search = find(&plan, "solverforge.runtime.default_local_search") .unwrap_or_else(|| panic!("default local search is reported: {plan:#?}")); assert_eq!(attribute(local_search, "acceptor"), "late_acceptance"); + assert_eq!(attribute(local_search, "forager_accepted_count_limit"), "4"); assert_eq!( - attribute(local_search, "forager_accepted_count_limit"), - "256" + attribute(local_search, "weighting"), + "fixed:[4, 4, 4, 4, 4, 4, 1]" ); - assert_eq!(attribute(local_search, "weighting"), "equal"); assert_eq!( attribute(local_search, "selection_order"), "stratified_random" @@ -121,11 +121,11 @@ fn an_omitted_forager_inherits_the_default_policy() { let local_search = explicit_local_search_plan(""); assert_eq!( attribute(&local_search, "forager"), - "default:AcceptedCount { limit: 256 }" + "default:AcceptedCount { limit: 4 }" ); assert_eq!( attribute(&local_search, "forager_accepted_count_limit"), - "256" + "4" ); } diff --git a/docs/configuration.md b/docs/configuration.md index 1d333b051..2a25b0345 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -184,7 +184,11 @@ neighborhoods: scalar, compound conflict-repair and ordinary scalar families. Leaf order is seeded `Random`. A single family uses `Sequential`; a -multi-family union uses `StratifiedRandom` with equal family weights. +multi-family union uses `StratifiedRandom`, weighted by candidate cost: list +ruin and unbounded k-opt rebuild or scan whole routes per candidate, so they +draw weight 1 against 4 for every other family. They stay in the +neighborhood for diversification without taking an equal share of the step. +`telemetry.resolved_phase_plan` reports the weights as `weighting`. `limited_neighborhood` remains the explicit cap for configured exhaustive selectors. @@ -192,12 +196,16 @@ The acceptor and forager follow the model's shape: | Model | Acceptor | Forager | |---|---|---| -| list variables, precedence moves available | Late Acceptance, history 400 | first last-step-score improving, accepted-count ceiling 256 | -| list variables | Late Acceptance, history 400 | accepted count 256 | -| scalar groups, no list variables | Diversified Late Acceptance, history 400 | accepted count 256 | -| scalar variables with nearby hooks or conflict repairs | Simulated Annealing, auto-calibrated | accepted count 256 | +| list variables, precedence moves available | Late Acceptance, history 400 | first last-step-score improving, accepted-count ceiling 32 | +| list variables | Late Acceptance, history 400 | accepted count 4 | +| scalar groups, no list variables | Diversified Late Acceptance, history 400 | accepted count 32 | +| scalar variables with nearby hooks or conflict repairs | Simulated Annealing, auto-calibrated | accepted count 32 | | other scalar variables | Simulated Annealing, auto-calibrated | accepted count 1 | +The accepted counts come from five-seed runs of the solverforge-bench CVRP, +rostering and job-shop suites at a 10 s budget: fewer accepted moves per step +buy more steps, and each model shape has its own best count. + ### Omitted and explicit components An omitted value takes the documented default; an explicit value is used as @@ -215,7 +223,7 @@ written: - **An explicit forager with omitted fields** uses that forager's own field defaults, not the default policy's: `type = "accepted_count"` without `limit` collects 1 accepted move per step, while an omitted forager on a list - model collects 256. + model collects 4. `telemetry.resolved_phase_plan` reports the resolved choice for every phase, including the families a slot did not receive and the capability each was From aca3167deb73d92117af34099098a19a0fea5b17 Mon Sep 17 00:00:00 2001 From: Vittorio Distefano Date: Tue, 17 Nov 2026 19:07:18 +0100 Subject: [PATCH 3/3] feat(policy): keep local search's share of a time-limited budget The optional assignment pass is the one default construction step that can run long without being needed. On the rostering bench it takes about 7 s, so a 10 s solve was left with 2 s and a few dozen search steps. The pass now stops once a fifth of the solve's time limit has passed and leaves optional rows to local search's optional-assignment moves. A fifth still lets the pass finish inside a 60 s solve, where a tenth measurably costs quality. Required construction is never capped, and a solve without a time limit runs the pass to completion. The step reports the seconds it was allowed as time_budget_seconds. Closes #253 --- crates/solverforge-solver/WIREFRAME.md | 8 +++- .../compiler/executor/default_construction.rs | 43 +++++++++++++++++-- .../compiler/executor/execution_record.rs | 3 ++ .../executor/prepared/tests/defaults.rs | 25 +++++++++++ .../src/runtime/compiler/executor/trace.rs | 3 ++ .../runtime/compiler/executor/trace_tests.rs | 29 +++++++++++++ .../src/scope/solver/scope_termination.rs | 5 +++ docs/configuration.md | 12 ++++++ 8 files changed, 123 insertions(+), 5 deletions(-) diff --git a/crates/solverforge-solver/WIREFRAME.md b/crates/solverforge-solver/WIREFRAME.md index 2996da94b..1a1078bf0 100644 --- a/crates/solverforge-solver/WIREFRAME.md +++ b/crates/solverforge-solver/WIREFRAME.md @@ -974,9 +974,13 @@ carry a `reason` attribute naming the model declaration that selected them (`savings_hooks_declared`, `precedence_construction_order_and_ownership_declared`, `precedence_and_construction_order_declared`, `no_specialized_list_policy_declared`, `required_assignments_remain`, `only_optional_assignments_remain`, -`scalar_slot_outside_assignment_groups`, `route_hooks_declared_and_route_non_empty`). +`scalar_slot_outside_assignment_groups`, `route_hooks_declared_and_route_non_empty`, +`element_groups_declared`, `list_elements_remain_unassigned`). The optional +assignment step of a time-limited solve also carries `time_budget_seconds`, +the share of the time limit it was allowed. The default local-search node carries acceptor, forager, -`forager_accepted_count_limit`, `selection_order`, `weighting` and +`forager_accepted_count_limit`, `selection_order`, `weighting` (`equal`, or +`fixed:[...]` with one cost weight per selector) and `excluded_families` (`family@slot:missing=capability+...`, or `none`); an explicit local-search node carries the configured or inherited acceptor and forager plus the effective `forager_accepted_count_limit` (`none` for variable diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/default_construction.rs b/crates/solverforge-solver/src/runtime/compiler/executor/default_construction.rs index 3614cb669..8b9a3be64 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/default_construction.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/default_construction.rs @@ -17,8 +17,9 @@ use crate::scope::{ProgressCallback, SolverScope}; use super::execute::execute_prepared_construction; use super::{ DefaultConstructionStageExecutionRecord, DefaultRuntimeConstructionExecution, - PreparedDefaultRuntime, PreparedRuntimeExecution, ResolvedConstructionExecutionOutcome, - ResolvedConstructionExecutionStep, RuntimeInstantiationError, + PreparedConstruction, PreparedDefaultRuntime, PreparedRuntimeExecution, + ResolvedConstructionExecutionOutcome, ResolvedConstructionExecutionStep, + RuntimeInstantiationError, }; /// Executes the staged omitted-construction profile through the same prepared @@ -134,6 +135,31 @@ where Ok(needs_completion) } +/// Share of a time-limited solve, in percent, after which the optional +/// assignment pass stops so local search keeps the rest of the budget. On +/// the rostering bench a fifth lets the pass finish in a 60 s solve, where a +/// tenth already costs quality, and still frees a 10 s solve for search. +/// Optional rows stay reachable to local search's optional-assignment moves. +const OPTIONAL_CONSTRUCTION_BUDGET_PERCENT: u32 = 20; + +/// The optional pass's remaining share of the solve's time limit, rounded up +/// to whole seconds, or `None` when the solve has no time limit. +pub(super) fn optional_construction_termination( + solver_scope: &SolverScope<'_, S, D, ProgressCb>, +) -> Option +where + S: PlanningSolution, + D: Director, + ProgressCb: ProgressCallback, +{ + let share = solver_scope.time_limit()? * OPTIONAL_CONSTRUCTION_BUDGET_PERCENT / 100; + let remaining = share.saturating_sub(solver_scope.elapsed().unwrap_or_default()); + Some(solverforge_config::TerminationConfig { + seconds_spent_limit: Some(remaining.as_millis().div_ceil(1000) as u64), + ..solverforge_config::TerminationConfig::default() + }) +} + fn execute_resolved_default_construction_plan( execution: &mut PreparedRuntimeExecution, default: &PreparedDefaultRuntime, @@ -151,8 +177,18 @@ where { let mut steps = Vec::with_capacity(resolved.steps.len()); for step in &resolved.steps { - let construction = + let mut construction = execution.prepare_resolved_construction(default.phase_index, &step.construction)?; + let mut time_budget_seconds = None; + if step.kind == DefaultConstructionStepKind::AssignmentOptional { + if let PreparedConstruction::GroupedScalar { config, .. } = &mut construction { + config.termination = optional_construction_termination(solver_scope); + time_budget_seconds = config + .termination + .as_ref() + .and_then(|termination| termination.seconds_spent_limit); + } + } let execution = execute_prepared_construction( execution, &construction, @@ -165,6 +201,7 @@ where required_only: step.required_only, target: step.target.clone(), list_policies: step.list_policies.clone(), + time_budget_seconds, outcome: execution.outcome, }); } diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/execution_record.rs b/crates/solverforge-solver/src/runtime/compiler/executor/execution_record.rs index 19619e042..fd0806f27 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/execution_record.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/execution_record.rs @@ -70,6 +70,9 @@ pub(crate) struct ResolvedConstructionExecutionStep { pub(crate) required_only: bool, pub(crate) target: Option, pub(crate) list_policies: Option, + /// Whole seconds of the solve's time limit this step was allowed, when + /// the default policy bounded it. + pub(crate) time_budget_seconds: Option, pub(crate) outcome: ResolvedConstructionExecutionOutcome, } diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/prepared/tests/defaults.rs b/crates/solverforge-solver/src/runtime/compiler/executor/prepared/tests/defaults.rs index 2fb400747..5ff2ff87c 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/prepared/tests/defaults.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/prepared/tests/defaults.rs @@ -224,3 +224,28 @@ fn eager_extension_preparation_precedes_lazy_source_binding() { )); assert_eq!(EXTENSION_BUILD_CALLS.load(Ordering::SeqCst), 1); } + +#[test] +fn optional_construction_keeps_its_share_of_a_time_limited_solve() { + use crate::runtime::compiler::executor::default_construction::optional_construction_termination; + + let input = plan(vec![7], vec![Vec::new()]); + let director = ScoreDirector::simple(input, descriptor(), |plan, _| entity_count(plan)); + let mut scope = SolverScope::new(director); + assert!( + optional_construction_termination(&scope).is_none(), + "a solve without a time limit leaves the optional pass unbounded" + ); + scope.set_time_limit(std::time::Duration::from_secs(60)); + assert_eq!( + optional_construction_termination(&scope).and_then(|config| config.seconds_spent_limit), + Some(12), + "a fifth of a 60 s solve" + ); + scope.set_time_limit(std::time::Duration::from_secs(4)); + assert_eq!( + optional_construction_termination(&scope).and_then(|config| config.seconds_spent_limit), + Some(1), + "the 0.8 s share rounds up to whole seconds" + ); +} diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/trace.rs b/crates/solverforge-solver/src/runtime/compiler/executor/trace.rs index fe5b6890f..686eeea7a 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/trace.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/trace.rs @@ -148,6 +148,9 @@ fn default_step_plan(step: &ResolvedConstructionExecutionStep) -> CandidateTrace .map_or_else(|| "none".to_string(), slot_signature), ), ]; + if let Some(seconds) = step.time_budget_seconds { + attributes.push(("time_budget_seconds".to_string(), seconds.to_string())); + } if let Some(policies) = &step.list_policies { match step.kind { DefaultConstructionStepKind::ListConstruction( diff --git a/crates/solverforge-solver/src/runtime/compiler/executor/trace_tests.rs b/crates/solverforge-solver/src/runtime/compiler/executor/trace_tests.rs index 1e96d42aa..1ebb1d639 100644 --- a/crates/solverforge-solver/src/runtime/compiler/executor/trace_tests.rs +++ b/crates/solverforge-solver/src/runtime/compiler/executor/trace_tests.rs @@ -24,6 +24,7 @@ fn executed_stage( required_only: false, target: None, list_policies: None, + time_budget_seconds: None, outcome: ResolvedConstructionExecutionOutcome::Executed, }], } @@ -89,3 +90,31 @@ fn default_terminal_trace_keeps_clarke_wright_then_k_opt_exactly() { "terminal construction trace must not be opaque" ); } + +#[test] +fn default_trace_reports_the_optional_pass_time_budget() { + let mut stage = executed_stage( + DefaultConstructionStage::Preconstruction(DefaultPreconstructionStage::AssignmentOptional), + DefaultConstructionStepKind::AssignmentOptional, + DefaultConstructionReason::OnlyOptionalAssignmentsRemain, + ); + stage.steps[0].time_budget_seconds = Some(2); + let execution = DefaultRuntimeConstructionExecution { + ran_child_phase: true, + stages: vec![stage], + }; + + let plan = default_construction_plan(&execution); + let budget = plan + .children + .iter() + .flat_map(|stage| stage.children.iter()) + .filter_map(|step| { + step.attributes + .iter() + .find(|attribute| attribute.key == "time_budget_seconds") + .map(|attribute| attribute.value.as_str()) + }) + .collect::>(); + assert_eq!(budget, ["2"]); +} diff --git a/crates/solverforge-solver/src/scope/solver/scope_termination.rs b/crates/solverforge-solver/src/scope/solver/scope_termination.rs index e9f3d5310..f3ffb04fc 100644 --- a/crates/solverforge-solver/src/scope/solver/scope_termination.rs +++ b/crates/solverforge-solver/src/scope/solver/scope_termination.rs @@ -73,6 +73,11 @@ impl<'t, S: PlanningSolution, D: Director, ProgressCb: ProgressCallback> || self.inphase_score_calc_count_limit_reached() } + /// The solve's time limit, when it has one. + pub(crate) fn time_limit(&self) -> Option { + self.time_limit + } + /// Stops the solve once this much solver-active time has elapsed. pub fn set_time_limit(&mut self, limit: Duration) { self.time_limit = Some(limit); diff --git a/docs/configuration.md b/docs/configuration.md index 2a25b0345..ac9b50dca 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -147,6 +147,18 @@ optional pass. Completed optional roots are skipped before candidate-domain reads or move generation, so the candidate budget stays available for later rows. +Construction and local search share a time-limited budget. Required work is +not capped: every list element, required assignment and non-optional scalar +must be placed before local search starts, and a solve whose limits end first +fails rather than publish a partial plan. The optional assignment pass is the +one construction step that can run long without being needed, so it stops once +a fifth of the solve's time limit has passed (rounded up to whole seconds) and +leaves the rest to local search, whose optional-assignment moves keep filling +optional rows. The step reports the share it got as `time_budget_seconds`. On +the rostering bench the pass needs about 7 s: uncapped it leaves a 10 s solve +2 s of search, and capped at a tenth it costs a 60 s solve quality; a fifth +does neither. A solve without a time limit runs the pass to completion. + An explicit scalar construction target that names an assignment-owned variable must use the owning `group_name`.