brushline.optimization.budget

Quality-versus-budget, seed variance, scaling, checkpoint/resume, and the no-optimality statement.

Search-budget, seed-variance, scaling, and checkpoint certification.

The report never hides a seed or a budget: every point names the requested budget, actual exact evaluations, seed outcomes, replay flag, and stopping rule. A realistic-corridor global-optimality claim is explicitly out of scope.

exception brushline.optimization.budget.BudgetError[source]

Bases: ValueError

Raised when a budget experiment is inconsistent.

class brushline.optimization.budget.BudgetPoint(*, budget: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)], runs: ~typing.Annotated[int, ~annotated_types.Ge(ge=1)], feasible_runs: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)], best_objective: float | None = None, median_objective: float | None = None, worst_objective: float | None = None, reach_optimum: bool | None = None, seed_results: list[~brushline.optimization.budget.SeedResult] = <factory>)[source]

Bases: BaseModel

Quality at one budget across seeds.

Parameters:
  • budget (int) – Requested budget.

  • runs (int) – Number of seeds.

  • feasible_runs (int) – Feasible seeds.

  • best_objective (float or None) – Best feasible objective.

  • median_objective (float or None) – Median feasible objective.

  • worst_objective (float or None) – Worst feasible objective.

  • reach_optimum (bool or None) – Whether every feasible seed reaches a supplied optimum.

  • seed_results (list of SeedResult) – Per-seed results.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.optimization.budget.BudgetReport(*, schema_version: str = 'brushline.optimization-budget-report.v1', quality: QualityBudgetReport, scaling: list[ScalingPoint] = <factory>, checkpoint: CheckpointMeasurement | None = None, adapter_version: str = 'p5.4', fresh_solutions_version: str, no_optimality: str = 'Brushline reports a search incumbent with its budget, seed, and stopping rule; it does not claim global optimality on realistic corridors.', created_utc: datetime)[source]

Bases: BaseModel

The complete budget and performance report.

Parameters:
  • schema_version ({"brushline.optimization-budget-report.v1"}) – Schema version.

  • quality (QualityBudgetReport) – Quality and seed evidence.

  • scaling (list of ScalingPoint) – Scaling evidence.

  • checkpoint (CheckpointMeasurement or None) – Checkpoint evidence.

  • adapter_version (str) – Adapter version.

  • fresh_solutions_version (str) – Fresh Solutions version.

  • no_optimality (str) – No-optimality statement.

  • created_utc (datetime) – Timezone-aware creation time.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.optimization.budget.CheckpointMeasurement(*, path: str, size_bytes: Annotated[int, Ge(ge=0)], save_seconds: Annotated[float, Ge(ge=0)], load_seconds: Annotated[float, Ge(ge=0)], replay_ok: bool, objective: float)[source]

Bases: BaseModel

Checkpoint/resume timing and replay.

Parameters:
  • path (str) – Checkpoint path.

  • size_bytes (int) – File size.

  • save_seconds (float) – Save time.

  • load_seconds (float) – Load and replay time.

  • replay_ok (bool) – Replay flag.

  • objective (float) – Replayed objective.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.optimization.budget.QualityBudgetReport(*, schema_version: str = 'brushline.optimization-budget.v1', instance_id: Annotated[str, MinLen(min_length=1)], mode: str, scalarization: str, optimum: float | None = None, points: Annotated[list[BudgetPoint], MinLen(min_length=1)], no_optimality: str = 'Brushline reports a search incumbent with its budget, seed, and stopping rule; it does not claim global optimality on realistic corridors.', created_utc: datetime)[source]

Bases: BaseModel

Quality-versus-budget and seed-variance evidence.

Parameters:
  • schema_version ({"brushline.optimization-budget.v1"}) – Schema version.

  • instance_id (str) – Instance id.

  • mode (str) – Search mode.

  • scalarization (str) – Scalarization name.

  • optimum (float or None) – Known optimum, when supplied.

  • points (list of BudgetPoint) – Budget points.

  • no_optimality (str) – No-optimality statement.

  • created_utc (datetime) – Timezone-aware creation time.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.optimization.budget.ScalingPoint(*, name: Annotated[str, MinLen(min_length=1)], variables: Annotated[int, Ge(ge=0)], runs: Annotated[int, Ge(ge=1)], best_objective: float | None = None, median_seconds: Annotated[float, Ge(ge=0)], max_seconds: Annotated[float, Ge(ge=0)], peak_bytes: Annotated[int, Ge(ge=0)], replay_ok: bool)[source]

Bases: BaseModel

Timing for one instance size.

Parameters:
  • name (str) – Instance label.

  • variables (int) – Variable count.

  • runs (int) – Seed runs.

  • best_objective (float or None) – Best feasible objective.

  • median_seconds (float) – Median wall time.

  • max_seconds (float) – Maximum wall time.

  • peak_bytes (int) – Peak traced memory across runs.

  • replay_ok (bool) – All runs replay.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.optimization.budget.SeedResult(*, seed: int, budget: Annotated[int, Ge(ge=0)], objective: float, feasible: bool, evaluations: Annotated[int, Ge(ge=0)], replay_ok: bool, stop_reason: str)[source]

Bases: BaseModel

One seed at one budget.

Parameters:
  • seed (int) – Seed.

  • budget (int) – Requested budget.

  • objective (float) – Scalar objective.

  • feasible (bool) – Feasibility.

  • evaluations (int) – Exact evaluations.

  • replay_ok (bool) – Exact replay flag.

  • stop_reason (str) – Stop reason.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

brushline.optimization.budget.measure_checkpoint(evaluator: ScheduleEvaluator, *, path: str | Path, instance_id: str, seed: int, iterations: int, scalarization: Scalarization | None = None) → CheckpointMeasurement[source]

Save, load, and replay one checkpoint.

Parameters:
  • evaluator (ScheduleEvaluator) – Exact evaluator.

  • path (str or Path) – Destination.

  • instance_id (str) – Instance id.

  • seed (int) – Seed.

  • iterations (int) – Local iterations.

  • scalarization (Scalarization, optional) – Objective weights.

Returns:

CheckpointMeasurement – Timing, size, and replay evidence.

brushline.optimization.budget.run_budget_curve(evaluator: ScheduleEvaluator, *, instance_id: str, budgets: list[int], seeds: list[int], scalarization: Scalarization | None = None, mode: Literal['local'] = 'local', optimum: float | None = None, created_utc: datetime | None = None) → QualityBudgetReport[source]

Run a local-search budget curve across seeds.

Parameters:
  • evaluator (ScheduleEvaluator) – Exact evaluator.

  • instance_id (str) – Instance id.

  • budgets (list of int) – Requested local iterations.

  • seeds (list of int) – Seeds.

  • scalarization (Scalarization, optional) – Objective weights.

  • mode (str, optional) – Search mode. Defaults to local.

  • optimum (float or None, optional) – Known optimum.

  • created_utc (datetime, optional) – Creation time.

Returns:

QualityBudgetReport – Budget and seed evidence.

brushline.optimization.budget.run_budget_report(evaluator: ScheduleEvaluator, *, instance_id: str, budgets: list[int], seeds: list[int], scaling_cases: list[tuple[str, ScheduleEvaluator]] | None = None, checkpoint_path: str | Path | None = None, scalarization: Scalarization | None = None, optimum: float | None = None, created_utc: datetime | None = None) → BudgetReport[source]

Build the complete budget, scaling, and checkpoint report.

Parameters:
  • evaluator (ScheduleEvaluator) – Exact evaluator.

  • instance_id (str) – Instance id.

  • budgets (list of int) – Local budgets.

  • seeds (list of int) – Seeds.

  • scaling_cases (list of (str, ScheduleEvaluator) or None, optional) – Scaling cases. Defaults to the primary case.

  • checkpoint_path (str or Path, optional) – Checkpoint path.

  • scalarization (Scalarization, optional) – Objective weights.

  • optimum (float or None, optional) – Known optimum.

  • created_utc (datetime, optional) – Creation time.

Returns:

BudgetReport – Complete evidence.

brushline.optimization.budget.run_scaling(cases: list[tuple[str, ScheduleEvaluator]], *, instance_id: str, seeds: list[int], budget: int, scalarization: Scalarization | None = None) → list[ScalingPoint][source]

Measure deterministic local-search timing for each case.

Parameters:
  • cases (list of (str, ScheduleEvaluator)) – Label and evaluator pairs.

  • instance_id (str) – Instance id.

  • seeds (list of int) – Seeds.

  • budget (int) – Local iterations.

  • scalarization (Scalarization, optional) – Objective weights.

Returns:

list of ScalingPoint – Timing and memory by case.