brushline.optimization.adapter
The Fresh Solutions adapter, scalarizations, search settings, replayable runs, and checkpoint replay.
Fresh Solutions adapter and exact replay for Brushline schedules.
The adapter maps the Brushline formulation onto the Fresh Solutions ProblemAdapter contract
and scalarizes the four-objective vector for single-objective search. Every reported incumbent is
replayed through the exact evaluator; a mismatch is an error, not a warning.
Fresh Solutions is optional. Importing this module does not import it; search calls do.
- exception brushline.optimization.adapter.AdapterError[source]
Bases:
ValueErrorRaised when the adapter, search, or replay is inconsistent.
- class brushline.optimization.adapter.BrushlineAdapter(evaluator: ScheduleEvaluator, scalarization: Scalarization | None = None, operator_config: OperatorConfig | None = None, name: str = 'brushline.optimization.adapter.v1')[source]
Bases:
objectFresh Solutions adapter over a Brushline formulation and evaluator.
- Parameters:
evaluator (ScheduleEvaluator) – Exact evaluator.
scalarization (Scalarization, optional) – Objective weights. Defaults to balanced.
operator_config (OperatorConfig, optional) – Operator settings.
name (str, optional) – Adapter name. Defaults to
ADAPTER_NAME.
- property variable_count: int
Return the variable count.
- Returns:
int – Number of variables.
- option_count(variable: int) int[source]
Return the option count for a variable.
- Parameters:
variable (int) – Variable index.
- Returns:
int – Option count.
- option_at(variable: int, option: int) str[source]
Return the option id at a position.
- Parameters:
variable (int) – Variable index.
option (int) – Option index.
- Returns:
str – Option id.
- initial_assignment() dict[int, int][source]
Return the no-action assignment.
- Returns:
dict of int to int – Assignment.
- random_assignment(rng: Random) dict[int, int][source]
Return a repaired random assignment.
- Parameters:
rng (random.Random) – Random source.
- Returns:
dict of int to int – Assignment.
- mutate(assignment: Mapping[int, int], rate: float, rng: Random) dict[int, int][source]
Mutate a repaired assignment.
- Parameters:
assignment (dict of int to int) – Starting assignment.
rate (float) – Per-variable mutation probability.
rng (random.Random) – Random source.
- Returns:
dict of int to int – Mutated and repaired assignment.
- Raises:
AdapterError – When the rate is outside [0, 1].
- crossover(left: Mapping[int, int], right: Mapping[int, int], rng: Random) dict[int, int][source]
Uniformly cross two assignments and repair the child.
- Parameters:
left (dict of int to int) – First parent.
right (dict of int to int) – Second parent.
rng (random.Random) – Random source.
- Returns:
dict of int to int – Child assignment.
- evaluate(assignment: Mapping[int, int]) Evaluation[source]
Return the scalarized exact evaluation.
- Parameters:
assignment (dict of int to int) – Assignment.
- Returns:
Evaluation – Fresh Solutions evaluation.
- evaluate_batch(assignments: Sequence[Mapping[int, int]]) list[Evaluation][source]
Return exact batch evaluations.
- Parameters:
assignments (list of dict of int to int) – Assignments.
- Returns:
list of Evaluation – Evaluations in input order.
- propose(assignment: Mapping[int, int], rng: random.Random) Change | None[source]
Propose one single-variable reversible change.
- Parameters:
assignment (mapping of int to int) – Assignment.
rng (random.Random) – Random source.
- Returns:
Change or None – Change, or None when no single-variable move exists.
- propose_move(assignment: Mapping[int, int], rng: Random) Move | None[source]
Propose any typed Brushline move, including compound moves.
- Parameters:
assignment (mapping of int to int) – Assignment.
rng (random.Random) – Random source.
- Returns:
Move or None – Move, or None.
- apply(assignment: Mapping[int, int], change: Change) dict[int, int][source]
Apply one change.
- Parameters:
assignment (dict of int to int) – Assignment.
change (Change) – Change.
- Returns:
dict of int to int – New assignment.
- undo(assignment: Mapping[int, int], change: Change) dict[int, int][source]
Undo one change.
- Parameters:
assignment (dict of int to int) – Assignment.
change (Change) – Change.
- Returns:
dict of int to int – Restored assignment.
- class brushline.optimization.adapter.Scalarization(*, name: Annotated[str, MinLen(min_length=1)], weights: dict[str, float])[source]
Bases:
BaseModelOne non-negative objective weighting.
- Parameters:
name (str) – Scalarization name.
weights (dict of str to float) – Weights for the four objectives.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.optimization.adapter.SearchRun(*, schema_version: ~typing.Literal['brushline.optimization-search.v1'] = 'brushline.optimization-search.v1', mode: str, instance_id: str, adapter: str, fresh_solutions_version: str, seed: int, budget: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)], assignment: dict[int, int], objective: float, objective_vector: dict[str, float], feasible: bool, evaluations: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)], history: list[float] = <factory>, stop_reason: str, checkpoint_path: str | None = None, evidence: dict[str, ~typing.Any], replay_ok: bool)[source]
Bases:
BaseModelA replayable search result.
- Parameters:
schema_version ({"brushline.optimization-search.v1"}) – Schema version.
mode (str) – Search mode.
instance_id (str) – Instance id.
adapter (str) – Adapter name and version.
fresh_solutions_version (str) – Fresh Solutions version.
seed (int) – Seed.
budget (int) – Requested budget.
assignment (dict of int to int) – Incumbent assignment.
objective (float) – Scalarized objective.
objective_vector (dict of str to float) – Four objective values.
feasible (bool) – Feasibility.
evaluations (int) – Exact evaluations.
history (list of float) – Best objective history.
stop_reason (str) – Stopping reason.
checkpoint_path (str or None) – Checkpoint path.
evidence (dict) – Replayable evidence record.
replay_ok (bool) – Whether exact replay matched.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.optimization.adapter.SearchSpec(*, mode: Literal['local', 'population', 'hybrid', 'convergence'] = 'local', instance_id: Annotated[str, MinLen(min_length=1)], seed: int = 1, iterations: Annotated[int, Ge(ge=0)] = 100, temperature: Annotated[float, Gt(gt=0)] = 1.0, cooling: Annotated[float, Gt(gt=0), Le(le=1)] = 0.999, population: Annotated[int, Ge(ge=2)] = 16, generations: Annotated[int, Ge(ge=0)] = 5, mutation_rate: Annotated[float, Ge(ge=0), Le(le=1)] = 0.1, elite_fraction: Annotated[float, Ge(ge=0), Lt(lt=1)] = 0.1, tournament_size: Annotated[int, Ge(ge=1)] = 3, random_fraction: Annotated[float, Ge(ge=0), Le(le=1)] = 0.2, local_iterations: Annotated[int, Ge(ge=1)] = 30, patience_rounds: Annotated[int, Ge(ge=1)] = 2, min_relative_improvement: Annotated[float, Ge(ge=0)] = 0.0001, max_rounds: Annotated[int, Ge(ge=1)] = 3, max_evaluations: Annotated[int, Ge(ge=1)] = 1000)[source]
Bases:
BaseModelSearch budget and stopping settings.
- Parameters:
mode ({"local", "population", "hybrid", "convergence"}) – Search mode.
instance_id (str) – Stable instance id.
seed (int) – Random seed.
iterations (int) – Local-search iterations.
temperature (float) – Initial temperature.
cooling (float) – Cooling factor.
population (int) – Population size.
generations (int) – Generations.
mutation_rate (float) – Mutation rate.
elite_fraction (float) – Elite fraction.
tournament_size (int) – Tournament size.
random_fraction (float) – Random initial population fraction.
local_iterations (int) – Local-refinement iterations per convergence round.
patience_rounds (int) – Convergence patience.
min_relative_improvement (float) – Convergence improvement threshold.
max_rounds (int) – Maximum convergence rounds.
max_evaluations (int) – Maximum convergence evaluations.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- property requested_budget: int
Return the requested evaluation budget.
- Returns:
int – Requested iterations, population work, or convergence cap.
- brushline.optimization.adapter.fresh_solutions_version() str[source]
Return the installed Fresh Solutions version.
- Returns:
str – Version, or
not-installed.
- brushline.optimization.adapter.replay_checkpoint(evaluator: ScheduleEvaluator, checkpoint_path: str | Path, *, scalarization: Scalarization | None = None) SearchRun[source]
Load a checkpoint and build a replayable, verified search run.
- Parameters:
evaluator (ScheduleEvaluator) – Exact evaluator.
checkpoint_path (str or Path) – Checkpoint path.
scalarization (Scalarization, optional) – Objective weights.
- Returns:
SearchRun – Verified replay result.
- brushline.optimization.adapter.run_search(evaluator: ScheduleEvaluator, spec: SearchSpec, *, scalarization: Scalarization | None = None, operator_config: OperatorConfig | None = None, checkpoint_path: str | Path | None = None) SearchRun[source]
Run a Fresh Solutions search and replay the incumbent exactly.
- Parameters:
evaluator (ScheduleEvaluator) – Exact evaluator.
spec (SearchSpec) – Search settings.
scalarization (Scalarization, optional) – Objective weights.
operator_config (OperatorConfig, optional) – Operator settings.
checkpoint_path (str or Path, optional) – Checkpoint destination.
- Returns:
SearchRun – Replayable result.
- Raises:
AdapterError – When Fresh Solutions is unavailable or replay does not match.