SolverForge keeps the native solver and scoring pipeline concrete. Solver, selector, move, provider and scoring generics resolve at compile time, so the compiler can inline across the hot path and lay data out contiguously. There is no garbage collector, so latency is predictable.
- Moves. Values stay concrete and inline. Selector cursors own discovered candidates; the selected move leaves its cursor by value.
- Selectors. GAT-based concrete cursors expose stable candidate IDs and
borrowable moves, with no
Box<dyn Iterator>in selector hot paths. - Scoring. SERIO propagates only changed constraints, and retained scoring state holds no trait-object allocations.
- Runtime carriers. Score directors, deciders, bounders, move carriers and selector carriers are monomorphized. Retained forager state is explicit.
- Order. Canonical list, nearby-list and sublist enumeration is deterministic, so seeded local search is reproducible.
A few boundaries use dynamic dispatch on purpose. They sit at integration edges, not in the move-evaluation loop:
- dynamic scalar and list access and metadata, for host-language models;
- configured candidate metrics for
SortedandProbabilisticselector ordering; - host-language compound providers. Native Rust
ScalarCandidateProviderandRepairProviderfunctions stay concrete function pointers and carry typedScalarEditvalues straight into the shared cursor normalizer; - the object-safe
EntityExtractor, for runtime-erasedSolutionDescriptoraccess only. Generated runtime and scoring-stream paths keep their concrete collection and selector types; the public concrete adapter and selector APIs areEntityCollectionExtractorandMoveSelector; - scorer-agnostic
&dyn Directorcallbacks, real-time problem changes, analysis payloads and preserved panic payloads.
AGENTS.md lists every allowed boundary and is the rule contributors follow.
Typed row operators have their own ownership contract, described in Extending typed relational scoring. Equality conditions use indexed candidates; arbitrary predicates scan the opposite input. The recursive operator tree supports owned non-Clone projection values on either join input through a fresh full-evaluation owner. It does not yet replace every public fluent stream family.
Local search can evaluate candidates on several cores within one solve:
move_thread_count = { count = 4 }Python configs through solverforge-py use {"move_thread_count": {"count": 4}}.
Each step's trials then run on up to four evaluators while one coordinator
keeps the same acceptance order, so results are reproducible at fixed work. The
count is bounded by the solve's Rayon threads and by 32, the size of one
evaluation window.
The default, auto, uses up to four evaluators and decides per step, from
measured costs, whether parallel windows beat sequential evaluation. The result
is the same either way.
Absolute throughput depends on the model, constraints, neighborhood, hardware and termination policy. Use the generated and evaluated throughput a run emits to understand that run, and the controlled benchmark gate below to decide whether a change regressed.
make pre-release is portable across supported development hosts. Release
qualification additionally requires make bench-zero-regression on a
controlled Linux host. A host that cannot run it has not completed release
qualification.
The gate needs taskset, /usr/bin/time, valgrind, readable /sys CPU
topology, the selected BENCH_CPU (CPU 10 by default) and passwordless sudo.
It uses sudo to give that CPU and its hyperthread siblings to the measurement
alone through an isolated cgroup cpuset partition. perf counters are
collected when permitted, each trial's counters averaged over PERF_REPEATS
runs (45 by default).
How it measures:
- It builds an independently linked binary for each case. Both sides share
one package name, so identical sources produce identical symbol mangling
and code layout, and the report records per-case
.textSHA-256 fingerprints for both binaries. - It alternates paired trials.
- It verifies full-enumeration candidate count and order separately from first-fit work.
- It requires exact equality for the deterministic allocation counters.
- It grades wall-time and hardware instruction medians against the
BENCH_TOLERANCE_PERCENTmedian regression budget (5% by default). - It grades cache and branch behavior on Cachegrind's simulated instructions, L1 misses, last-level misses and branch mispredictions against the same budget. The simulation repeats to within a count on a shared machine; the hardware cache and branch counters stay in the report for diagnosis only.
The default cases compile a SolverConfig through the same runtime compilation
a configured solve runs, then enumerate the compiled runtime's own cursors
against an empty constraint set:
- the local-search composition cursor over the compiled list and scalar neighborhood leaves: list change and swap, nearby change and swap, sublist change and swap, k-opt, union, Cartesian, scalar change and scalar ruin/recreate;
- the scalar construction placer;
- a first-fit construction solve through the compiled runtime phase runner.
The opt-in BENCH_CASES="scoring scoring_weights_one scoring_weights_mixed"
cases measure incremental scoring churn through uni, join, shared grouped and
balance constraints, with and without runtime constraint weights. Both sides of
the weighted cases are built with the weight API, so a baseline without it is
refused rather than compared unweighted.
Neighborhood selector cleanup is gated by this benchmark. Shared support code handles exact sizing and reusable bookkeeping, while the move-enumeration hot loops for list and sublist neighborhoods stay explicit and monomorphized.