Solver

The solver takes your domain model and constraints, then searches for the best solution using metaheuristic algorithms. Configuration controls which algorithms run, how long to search, and how moves are selected.

Quick Start

use solverforge::prelude::*;
use solverforge::{SolverEvent, SolverManager};

static MANAGER: SolverManager<Schedule> = SolverManager::new();

let (job_id, mut rx) = MANAGER.solve(problem).expect("solver job should start");

while let Some(event) = rx.blocking_recv() {
    match event {
        SolverEvent::Progress { metadata } => {
            println!("best so far: {:?}", metadata.best_score);
        }
        SolverEvent::BestSolution { metadata, .. } => {
            println!("new best at snapshot {:?}", metadata.snapshot_revision);
        }
        SolverEvent::Completed { metadata, .. } => {
            println!("finished with reason {:?}", metadata.terminal_reason);
            break;
        }
        SolverEvent::Cancelled { .. } | SolverEvent::Failed { .. } => break,
        SolverEvent::PauseRequested { .. } | SolverEvent::Paused { .. } | SolverEvent::Resumed { .. } => {}
    }
}

MANAGER.delete(job_id).expect("delete retained job");

The stock generated solve path loads solver.toml automatically from the current working directory. solverforge-config also exposes parsing APIs when you want to inspect or construct configs directly.

The current release uses one RuntimeModel per planning model. Generic construction heuristics share that model for mixed/list-bearing work, while pure scalar construction uses the descriptor boundary. Local search uses explicit streaming defaults when move_selector is omitted, and scalar candidate limits, assignment-backed grouped scalar selectors, conflict repair selectors, list permutation, precedence-list selectors, and score-level simulated annealing are expressed in solver.toml.

The facade exports the configuration surface directly from solverforge, including SolverConfig, PhaseConfig, MoveSelectorConfig, AcceptorConfig, ForagerConfig, SolverConfigOverride, and related enums. Application code no longer needs a separate solverforge-config dependency for normal configuration construction or parsing.

Assignment-backed grouped scalar construction is available for required nullable scalar slots through named ScalarGroup::assignment(...) declarations. Pair it with grouped_scalar_move_selector when local search should prioritize uncovered required slots, capacity conflicts, bounded reassignments, same-sequence run-gap repairs, value-window swaps, optional occupant releases, block reassignments, or value rotations from the same group.

SolverManager now exposes a retained job lifecycle rather than a fire-and-forget channel. In addition to Progress and BestSolution, you can observe PauseRequested, Paused, Resumed, Completed, Cancelled, and Failed, inspect SolverStatus, and fetch or analyze retained snapshots by snapshot_revision.

Retained telemetry carries exact generated, evaluated, accepted, not-doable, acceptor-rejected, forager-ignored, hard-delta, conflict-repair, and construction-slot counters plus generation and evaluation durations. The current runtime also carries per-move-label telemetry and a bounded applied-move trace with selected candidate index, per-step candidate counts, score delta, and hard-feasibility before/after. User-facing rates such as moves/s are display-only derived values.

Sections

• Configuration — SolverConfig, solver.toml, and YAML parsing
• Construction — construction heuristics, nullable obligations, and grouped scalar construction
• Local Search — acceptors, foragers, selectors, and score-level annealing
• Phases — Construction heuristic, local search, VND, typed exact search, and partitioned search
• Moves — selector-family guide with scalar, list, and composite subsections
• Termination — When to stop solving
• SolverManager — Running and managing solver instances