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:
BaseModelThe 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:
ValueErrorRaised 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:
BaseModelThe 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:
report (TinyValidationReport) – Report.
path (str or Path) – Destination.
- Returns:
Path – Written path.