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.
[termination]
seconds_spent_limit = 30
unimproved_seconds_spent_limit = 5
step_count_limit = 10000Parsing 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)?;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)
}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.
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 withconstraints. - A name that matches no declared provider fails the solve before it starts
with
RuntimeBuildError::UnknownConstraintProvider. SolverManager::analyze_snapshotanalyzes a job's snapshots with the provider that job selected.constraint_match_enabled = falseturns snapshot analysis off for the job; analysis then fails withSolverManagerError::SnapshotAnalysisDisabled.
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 groupedCheapestInsertionfor 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.
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
ChangeMoveSelectorplusSwapMoveSelectorfor 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:
- group change plus group swap, when the slot declares element groups;
- precedence repair plus list permutation, when the complete precedence move bundle exists;
- nearby change, plus nearby swap when set access exists, with a limit of 20, when a cross-position metric exists;
- otherwise plain change, plus plain swap when set access exists;
- 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;
- list ruin for every bound list slot; a slot with element groups gets its
own ruin with
max_member_distance = 7andmax_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.
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_searchphase withoutmove_selectorgets the default families above. - Without
acceptororforager, 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"withoutlimitcollects 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.
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"| 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 |
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 = 40The 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.
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 = 6max_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.
| 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.