Skip to content

Latest commit

 

History

History
334 lines (268 loc) · 16.1 KB

configuration.md

File metadata and controls

334 lines (268 loc) · 16.1 KB

Configuration

Solver behavior lives in solver.toml: termination limits, phases, selectors and score-director options. Omit phases and SolverForge picks defaults from the model's shape. This guide covers loading the file, termination, constraint providers and the defaults. Custom phases, selector routing and partitioned search are in Extend the solver; every key is listed in the solverforge-config wireframe.

Loading solver.toml

[termination]
seconds_spent_limit = 30
unimproved_seconds_spent_limit = 5
step_count_limit = 10000

Parsing is strict. A misspelled or unknown key anywhere in the file (for example secnds_spent_limit) fails with a ConfigError::Toml that names the key. It is never silently ignored.

Load it yourself and handle the Result:

let config = SolverConfig::load("solver.toml")?;

Every configuration type is reachable as solverforge::config::*. To solve on the calling thread with exactly that config, without a SolverManager:

let solved = plan.solve_with_config(config)?;

Config embedded in the model

Macro-generated retained solves (the SolverManager path) read configuration only from #[planning_solution(solver_toml = "...")]. The file is embedded at compile time, and the path is relative to the solution's source file. Without solver_toml they start from SolverConfig::default(). Nothing is read from the working directory. An embedded file that does not parse fails the job with a SolverEvent::Failed whose error reads solver configuration invalid: TOML parse error ....

The solution module listed by planning_model! can add config = "..." to adjust that base config per solution instead of replacing it:

#[planning_solution(
    constraints = "define_constraints",
    config = "solver_config_for_solution"
)]
pub struct Schedule {
    #[problem_fact_collection]
    pub nurses: Vec<Nurse>,

    #[planning_entity_collection]
    pub shifts: Vec<Shift>,

    pub time_limit_secs: u64,

    #[planning_score]
    pub score: Option<HardSoftScore>,
}

fn solver_config_for_solution(solution: &Schedule, config: SolverConfig) -> SolverConfig {
    config.with_termination_seconds(solution.time_limit_secs)
}

Termination is always binding

Configured time, step, move, score-calculation and phase limits hold during all construction work, required scalar and list construction included. A configured solve publishes a best solution only after every mandatory list element, required assignment row and non-optional scalar variable is assigned. If a limit is reached first, the solve ends as Failed. An incomplete construction state is never emitted as a best or completed solution.

Choosing a constraint set

Next to constraints, a solution can declare further constraint sets with constraint_provider = "path" (repeatable). A configuration picks one by the path exactly as written in the attribute:

[score_director]
constraint_provider = "relaxed_constraints"
constraint_match_enabled = true
  • Without [score_director], the solve scores with constraints.
  • A name that matches no declared provider fails the solve before it starts with RuntimeBuildError::UnknownConstraintProvider.
  • SolverManager::analyze_snapshot analyzes a job's snapshots with the provider that job selected.
  • constraint_match_enabled = false turns snapshot analysis off for the job; analysis then fails with SolverManagerError::SnapshotAnalysisDisabled.

What runs when you omit phases

Construction

Construction always runs first and is state-aware:

  • list variables use the matching specialized list construction;
  • assignment-backed scalar groups commit the hard-first required allocation through named grouped FirstFit, then run grouped CheapestInsertion for optional slots;
  • remaining scalar variables that no assignment group owns use descriptor-backed single-slot construction.

Each list slot gets the first construction whose declarations it has:

Slot declares Construction Reported reason
element groups (element_group_fn) ListCheapestInsertion with max_group_owners = 4 element_groups_declared
savings hooks (domain = "cvrp" or savings_hooks) ListClarkeWright savings_hooks_declared
precedence, construction order and ownership ListRegretInsertion precedence_construction_order_and_ownership_declared
precedence and construction order ListRoundRobin precedence_and_construction_order_declared
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).

The dense required batch collects independent assignments directly. Bounded augmenting rematches stay with the following required cursor rather than being explored inside a batch that cannot retain multi-entity edits. Keeping an optional assignment unassigned completes that decision without ending the 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.

Local search

One streaming acceptor/forager local-search phase follows construction, but only when top-level termination contains an effective parsed limit. Absent termination, an empty termination object, or invalid score-only termination leaves the solve construction-only. Variable Neighborhood Descent is never added implicitly.

When move_selector is omitted from acceptor_forager local search, the runtime uses explicit streaming defaults instead of broad exhaustive neighborhoods:

  • Scalar slots get nearby scalar change/swap selectors when the matching hooks are declared, then plain ChangeMoveSelector plus SwapMoveSelector for every scalar slot that no assignment group owns.
  • Assignment-backed scalar groups are edited through their owning grouped scalar selector. Generic scalar selectors and conflict-repair defaults leave group-owned slots alone.
  • List slots get capability-matched families in a fixed order:
    1. group change plus group swap, when the slot declares element groups;
    2. precedence repair plus list permutation, when the complete precedence move bundle exists;
    3. nearby change, plus nearby swap when set access exists, with a limit of 20, when a cross-position metric exists;
    4. otherwise plain change, plus plain swap when set access exists;
    5. sublist, reverse and k-opt families, only when their required operations are declared. K-opt uses the nearby metric when available and the unbounded form otherwise;
    6. list ruin for every bound list slot; a slot with element groups gets its own ruin with max_member_distance = 7 and max_group_owners = 4.
  • Mixed models declare list families first, then nearby scalar, grouped scalar, compound conflict-repair and ordinary scalar families.

Leaf order is seeded Random. A single family uses Sequential; a 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.

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 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 written:

  • No phases: construction as above, then the default local search when termination has an effective limit.
  • An explicit phase list replaces the defaults. It does not add a construction phase in front.
  • An explicit local_search phase without move_selector gets the default families above.
  • Without acceptor or forager, that phase takes the default acceptor and forager for the model. An omitted forager after a Tabu Search acceptor is the best-score forager.
  • 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 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 missing; see Running solves.

Extend the solver explains how these defaults interact with explicit selector configuration.

Variable Neighborhood Descent

VND is a local-search type you opt into:

[[phases]]
type = "local_search"
local_search_type = "variable_neighborhood_descent"

[[phases.neighborhoods]]
type = "change_move_selector"

Available phases and moves

Area What ships (selectors by their type key in solver.toml)
Construction FirstFit and CheapestInsertion through one compiled runtime graph: scalar-only targets use its descriptor-placement schedule, mixed and list-bearing targets its declaration-order global scan. Specialized list phases: ListRoundRobin, ListCheapestInsertion and ListRegretInsertion (both placing element groups jointly), owner-aware ListClarkeWright, ListKOpt
Grouped scalar construction Named ScalarGroup declarations, candidate-backed compound edits, assignment-backed nullable construction with required-slot handling, capacity repair and ordering hooks
Local search acceptor_forager with Hill Climbing, Simulated Annealing (level-aware), Tabu Search, Late Acceptance, Great Deluge, Step Counting Hill Climbing or Diversified Late Acceptance; or variable_neighborhood_descent with ordered neighborhoods
Exhaustive search Exact search over small finite scalar spaces
Partitioned search Explicit user-defined decomposition with optional Rayon parallelism, see Extend the solver
Scalar selectors change_move_selector, swap_move_selector, nearby_change_move_selector, nearby_swap_move_selector, pillar_change_move_selector, pillar_swap_move_selector, ruin_recreate_move_selector, grouped_scalar_move_selector, conflict_repair_move_selector, compound_conflict_repair_move_selector
List selectors list_change_move_selector, nearby_list_change_move_selector, list_swap_move_selector, nearby_list_swap_move_selector, list_permute_move_selector, list_precedence_move_selector, sublist_change_move_selector, sublist_swap_move_selector, list_reverse_move_selector, k_opt_move_selector, list_ruin_move_selector, list_group_change_move_selector, list_group_swap_move_selector
Composition union_move_selector, cartesian_product_move_selector, limited_neighborhood; native and host-backed compound scalar moves; nearby selection for scalar and list neighborhoods

Bounded Clarke-Wright savings

list_clarke_wright scores every pair of unassigned elements by default, so its savings list grows with the square of the element count (32 bytes per pair; 1.6 GB at 10k stops). savings_neighbors scores a pair only when one element is among the other's nearest:

[[phases]]
type = "construction_heuristic"
construction_heuristic_type = "list_clarke_wright"
savings_neighbors = 40

The list then holds about savings_neighbors entries per element. The variable must declare a savings neighbour hook (savings_neighbors_fn); the domain = "cvrp" profile supplies one that asks the vehicles' RouteMetric. With EuclideanMetric the neighbours come from a spatial grid, so memory stays linear in the stops; see Modeling. Without the setting, savings, their order and the merges are unchanged, and a bound of at least the element count minus one gives the same routes as no bound.

Element groups

A list variable with element_group_fn (see Modeling) is constructed by list_cheapest_insertion by default, with max_group_owners = 4. Both insertion heuristics accept the joint-placement bounds:

[[phases]]
type = "construction_heuristic"
construction_heuristic_type = "list_regret_insertion"
max_member_distance = 5
max_group_owners = 6

max_member_distance caps the positions from one member of a group to the next (1 keeps members adjacent), and max_group_owners tries every placement only on that many owners, the ones where the group fits best contiguously. Both take 1 to 255; omitted, each is unbounded. Other heuristics, and lists without groups, reject both keys.

Local search moves groups through list_group_change_move_selector (max_member_distance) and list_group_swap_move_selector, and list_ruin_move_selector takes the same two bounds for its joint recreate. These selectors, and ruin bounds, require a targeted list with element groups.

The configuration surface also covers bounded candidate tracing, per-selector ordering and host metrics, weighted union scheduling, score tie-breaking, and grouped scalar and conflict-repair selectors.

Cargo features

Feature Description
console Colored console output with progress tracking
verbose-logging Console output at DEBUG level (implies console): construction and local-search progress, prompt first work, then about once a second during long phases
serde Serialization support for score types

What the console prints is shown in Running solves.