diff --git a/crates/solverforge-solver/WIREFRAME.md b/crates/solverforge-solver/WIREFRAME.md index 2996da94..1a1078bf 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/manager/phase_factory/list_clarke_wright/kernel.rs b/crates/solverforge-solver/src/manager/phase_factory/list_clarke_wright/kernel.rs index 5438fbe0..6bbfb82f 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/default_local_search.rs b/crates/solverforge-solver/src/runtime/compiler/default_local_search.rs index ed0f5a31..3fe09fd2 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 0fca0e77..0943f033 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 fbf58abe..17e5d46a 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 b13aad67..ea69f5b9 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 6fc48787..3cb69202 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.rs b/crates/solverforge-solver/src/runtime/compiler/defaults.rs index f68da0a9..8ca35584 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 00000000..ccb3b570 --- /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 0c9f9778..6eb395a7 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/defaults_tests/selection.rs b/crates/solverforge-solver/src/runtime/compiler/defaults_tests/selection.rs index b70a8923..f501bbd5 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/default_construction.rs b/crates/solverforge-solver/src/runtime/compiler/executor/default_construction.rs new file mode 100644 index 00000000..8b9a3be6 --- /dev/null +++ b/crates/solverforge-solver/src/runtime/compiler/executor/default_construction.rs @@ -0,0 +1,226 @@ +//! 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, + PreparedConstruction, 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) +} + +/// 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, + 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 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, + 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(), + time_budget_seconds, + 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 8bc5c120..feac7ad9 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/execution_record.rs b/crates/solverforge-solver/src/runtime/compiler/executor/execution_record.rs index 19619e04..fd0806f2 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/local_search/lower.rs b/crates/solverforge-solver/src/runtime/compiler/executor/local_search/lower.rs index 0e643099..80b18af1 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/mod.rs b/crates/solverforge-solver/src/runtime/compiler/executor/mod.rs index 5aed3fcf..c42daf4a 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/tests/defaults.rs b/crates/solverforge-solver/src/runtime/compiler/executor/prepared/tests/defaults.rs index 2fb40074..5ff2ff87 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/prepared/types.rs b/crates/solverforge-solver/src/runtime/compiler/executor/prepared/types.rs index d647b156..b7c7e45d 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/runner/lowering.rs b/crates/solverforge-solver/src/runtime/compiler/executor/runner/lowering.rs index 49ae2ef9..610fc0bd 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-solver/src/runtime/compiler/executor/trace.rs b/crates/solverforge-solver/src/runtime/compiler/executor/trace.rs index 0392c4c9..686eeea7 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( @@ -168,7 +171,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 +274,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 +303,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 +325,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-solver/src/runtime/compiler/executor/trace_tests.rs b/crates/solverforge-solver/src/runtime/compiler/executor/trace_tests.rs index 1e96d42a..1ebb1d63 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 e9f3d531..f3ffb04f 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/crates/solverforge/tests/list_clarke_wright_fixed_fleet.rs b/crates/solverforge/tests/list_clarke_wright_fixed_fleet.rs new file mode 100644 index 00000000..d6f620c0 --- /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 00000000..86993619 --- /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 00000000..9391bcf0 --- /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 00000000..10b082de --- /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 00000000..40335e20 --- /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 00000000..8f9c60f7 --- /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/crates/solverforge/tests/resolved_policy_telemetry.rs b/crates/solverforge/tests/resolved_policy_telemetry.rs index 710436b6..4988f0ce 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 0eb6bea4..ac9b50dc 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`). @@ -132,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`. @@ -169,7 +196,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. @@ -177,12 +208,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 @@ -200,7 +235,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