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:
ValueErrorRaised 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:
BaseModelQuality 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:
BaseModelThe 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:
BaseModelCheckpoint/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:
BaseModelQuality-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:
BaseModelTiming 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:
BaseModelOne 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.