brushline.optimization.validation

Exhaustive tiny-instance enumeration, exact/batch agreement, committed optimum, search gap, and replay validation.

Tiny-instance exhaustive validation for the Brushline optimizer.

The validator enumerates every discrete assignment on a small formulation, finds the best feasible scalar value, checks exact and batch evaluation agreement, and records a search run’s gap and exact replay. It is a correctness check, not a realistic-corridor optimality claim.

class brushline.optimization.validation.TinyOptimum(*, schema_version: Literal['brushline.tiny-optimum.v1'] = 'brushline.tiny-optimum.v1', formulation_id: Annotated[str, MinLen(min_length=1)], weights: dict[str, float], total_assignments: Annotated[int, Ge(ge=1)], feasible_assignments: Annotated[int, Ge(ge=0)], best_assignment: dict[int, int] | None = None, objective: float | None = None, objective_vector: dict[str, float] | None = None, ties: Annotated[int, Ge(ge=0)] = 0, batch_agreement: bool = True)[source]

Bases: BaseModel

The exhaustive optimum of one tiny formulation.

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

  • formulation_id (str) – Formulation id.

  • weights (dict of str to float) – Scalarization weights.

  • total_assignments (int) – Enumerated assignments.

  • feasible_assignments (int) – Feasible assignments.

  • best_assignment (dict of int to int or None) – Best assignment, or None without a feasible assignment.

  • objective (float or None) – Best scalar objective.

  • objective_vector (dict of str to float or None) – Best four-objective vector.

  • ties (int) – Number of feasible assignments at the best scalar value.

  • batch_agreement (bool) – Whether exact and batch evaluation agreed for every assignment.

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

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

exception brushline.optimization.validation.TinyValidationError[source]

Bases: ValueError

Raised when a tiny validation request is inconsistent.

class brushline.optimization.validation.TinyValidationReport(*, schema_version: Literal['brushline.tiny-validation.v1'] = 'brushline.tiny-validation.v1', instance_id: Annotated[str, MinLen(min_length=1)], optimum: TinyOptimum, search: SearchRun | None = None, gap: float | None = None, reaches_optimum: bool = False, replay_ok: bool = True, expected_ok: bool | None = None)[source]

Bases: BaseModel

The exhaustive optimum plus optional search evidence.

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

  • instance_id (str) – Instance id.

  • optimum (TinyOptimum) – Exhaustive optimum.

  • search (SearchRun or None) – Search result.

  • gap (float or None) – Search scalar minus optimum scalar.

  • reaches_optimum (bool) – Whether the gap is zero.

  • replay_ok (bool) – Whether the search assignment replays.

  • expected_ok (bool or None) – Whether a committed optimum matched.

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

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

brushline.optimization.validation.enumerate_assignments(formulation: Formulation) → list[dict[int, int]][source]

Enumerate every discrete assignment.

Parameters:

formulation (Formulation) – Optimization formulation.

Returns:

list of dict of int to int – Every assignment in stable variable order.

brushline.optimization.validation.exhaustive_optimum(evaluator: ScheduleEvaluator, weights: dict[str, float]) → TinyOptimum[source]

Enumerate every assignment and return the best feasible scalar value.

Parameters:
  • evaluator (ScheduleEvaluator) – Exact evaluator.

  • weights (dict of str to float) – Scalarization weights.

Returns:

TinyOptimum – Exhaustive optimum and exact/batch agreement.

brushline.optimization.validation.load_tiny_optimum(path: str | Path) → TinyOptimum[source]

Load a tiny optimum.

Parameters:

path (str or Path) – Source.

Returns:

TinyOptimum – Loaded optimum.

brushline.optimization.validation.load_tiny_validation(path: str | Path) → TinyValidationReport[source]

Load a tiny validation report.

Parameters:

path (str or Path) – Source.

Returns:

TinyValidationReport – Loaded report.

brushline.optimization.validation.validate_tiny_instance(evaluator: ScheduleEvaluator, *, weights: dict[str, float], instance_id: str = 'tiny', search: SearchRun | None = None, expected: TinyOptimum | None = None) → TinyValidationReport[source]

Validate exhaustive and optional search results on a tiny instance.

Parameters:
  • evaluator (ScheduleEvaluator) – Exact evaluator.

  • weights (dict of str to float) – Scalarization weights.

  • instance_id (str, optional) – Instance id. Defaults to tiny.

  • search (SearchRun or None, optional) – Search result to compare.

  • expected (TinyOptimum or None, optional) – Committed optimum to compare.

Returns:

TinyValidationReport – Optimum, gap, replay, and expected-match evidence.

brushline.optimization.validation.write_tiny_optimum(optimum: TinyOptimum, path: str | Path) → Path[source]

Write a tiny optimum as JSON.

Parameters:
  • optimum (TinyOptimum) – Optimum.

  • path (str or Path) – Destination.

Returns:

Path – Written path.

brushline.optimization.validation.write_tiny_validation(report: TinyValidationReport, path: str | Path) → Path[source]

Write a tiny validation report.

Parameters:
Returns:

Path – Written path.