Optimization adapter and exact replay
P5.4 maps Brushline onto the released fresh-solutions problem-adapter contract and records an exactly replayable incumbent. Brushline supplies variables, options, exact evaluation, single-variable proposals, apply/undo, and evidence. Fresh Solutions supplies local, population, hybrid, and convergence search.
The core install does not require the optimizer. Install the optional extra before planning:
python -m pip install -e '.[opt]'
The adapter module itself imports without the extra; a search call imports Fresh Solutions.
Adapter contract
BrushlineAdapter implements:
variable_countandoption_count;option_atreturning the stable Brushline option id;initial_assignment,random_assignment,mutate, andcrossover;exact
evaluateandevaluate_batch;single-variable
proposeplus the typedpropose_movefor compound Brushline moves;reversible
applyandundo.
Random, mutated, and crossed assignments are passed through the P5.3 feasibility repair. Access and locked-variable rules are honored.
Scalarization
Fresh Solutions needs a scalar. The adapter uses a declared Scalarization and converts
service_attainment to a loss (1 - value). The four objective values remain in
Evaluation.details and in the final SearchRun.objective_vector.
The portfolio is cost_first, risk_first, service_first, uncertainty_first, and
balanced. A scalarization is a search weighting, not a replacement for the Pareto archive.
An infeasible assignment gets 1e9 per hard violation on top of its scalar. Feasibility is still
reported explicitly; the penalty only discourages the search from preferring an infeasible incumbent.
Search modes
Mode |
Fresh Solutions path |
|---|---|
|
Simulated-annealing local search with |
|
Batched population search with population, generations, mutation, elite fraction, tournament, and random fraction. |
|
Population search followed by exact local refinement. |
|
Population search followed by local rounds with patience, improvement threshold, round cap, and evaluation cap. |
SearchSpec.requested_budget records the requested evaluation budget; SearchRun.evaluations
records the actual exact evaluations.
Replay and evidence
Every run re-evaluates the reported assignment through the exact evaluator. The run fails if the
scalar, feasibility, or assignment coverage does not match. SearchRun carries:
the seed, requested budget, mode, adapter name, and Fresh Solutions version;
the assignment, scalar objective, four-objective vector, feasibility, evaluations, and history;
the stop reason and optional checkpoint path;
a Fresh Solutions
EvidenceRecordmapping andreplay_ok.
SearchRun rejects a record whose replay flag is false. replay_checkpoint loads a
SearchCheckpoint, verifies its objective, and returns a verified run.
from brushline.optimization.adapter import SearchSpec, run_search
run = run_search(
evaluator,
SearchSpec(mode="local", instance_id="tiny", seed=7, iterations=100),
checkpoint_path="runs/tiny/checkpoint.json",
)
assert run.replay_ok
Limits
A scalar run does not enumerate the Pareto frontier; P5.5 owns the archive.
Fresh Solutions search is a metaheuristic; no realistic-corridor optimality claim is made.
The checkpoint stores the assignment, objective, seed, generation, and metadata; it does not store the full evaluator state.
The adapter’s compound moves are available through
propose_move; Fresh Solutions receives one reversible change at a time.