brushline.optimization.operators
Typed reversible moves, the operator portfolio, access and lock rules, and deterministic feasibility repair.
Typed move operators and feasibility repair for optimization assignments.
Operators propose reversible bundles of assignment changes. Each bundle records the exact before and after option for every touched variable, so apply and undo are deterministic. Repair removes access, budget, monitoring-budget, and capacity violations, and tries a treatment option for a service miss; it never invents a fix for a blocked growth or treatment model.
- class brushline.optimization.operators.BlockMoveOperator(state: OperatorState)[source]
Bases:
objectSet a contiguous period block for one segment to one treatment option.
- class brushline.optimization.operators.MethodChangeOperator(state: OperatorState)[source]
Bases:
objectChange one selected treatment to an option with a different method.
- class brushline.optimization.operators.MonitoringMoveOperator(state: OperatorState)[source]
Bases:
objectChange one monitoring option.
- class brushline.optimization.operators.Move(*, kind: Annotated[str, MinLen(min_length=1)], changes: Annotated[tuple[AssignmentChange, ...], MinLen(min_length=1)], description: str = '')[source]
Bases:
BaseModelA reversible bundle of assignment changes.
- Parameters:
kind (str) – Move kind.
changes (tuple of AssignmentChange) – Changes in application order.
description (str, optional) – Human explanation.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- apply(assignment: dict[int, int]) dict[int, int][source]
Apply the move to an assignment.
- Parameters:
assignment (dict of int to int) – Current assignment.
- Returns:
dict of int to int – New assignment.
- Raises:
OperatorError – When a before value does not match.
- undo(assignment: dict[int, int]) dict[int, int][source]
Undo the move on an assignment.
- Parameters:
assignment (dict of int to int) – Current assignment.
- Returns:
dict of int to int – Restored assignment.
- Raises:
OperatorError – When an after value does not match.
- class brushline.optimization.operators.MoveOperator(*args, **kwargs)[source]
Bases:
ProtocolProtocol for a deterministic, seed-driven operator.
- class brushline.optimization.operators.OperatorConfig(*, max_block_periods: Annotated[int, ~annotated_types.Ge(ge=1), ~annotated_types.Le(le=10)] = 3, destroy_fraction: Annotated[float, ~annotated_types.Gt(gt=0), ~annotated_types.Le(le=1)] = 0.2, max_repair_steps: Annotated[int, ~annotated_types.Ge(ge=1), ~annotated_types.Le(le=1000)] = 100, respect_access: bool = True, locked_variables: list[int] = <factory>)[source]
Bases:
BaseModelOperator and repair settings.
- Parameters:
max_block_periods (int, optional) – Maximum periods in one block move. Defaults to 3.
destroy_fraction (float, optional) – Share of variables destroyed before repair. Defaults to 0.2.
max_repair_steps (int, optional) – Maximum repair changes. Defaults to 100.
respect_access (bool, optional) – Skip treatment variables in inaccessible periods. Defaults to True.
locked_variables (list of int, optional) – Variable indices that operators must not change.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- exception brushline.optimization.operators.OperatorError[source]
Bases:
ValueErrorRaised when a move or repair request is inconsistent.
- class brushline.optimization.operators.OperatorState(formulation: Formulation, config: OperatorConfig | None = None)[source]
Bases:
objectShared eligibility and option helpers.
- Parameters:
formulation (Formulation) – Optimization formulation.
config (OperatorConfig, optional) – Operator settings.
- eligible(assignment: dict[int, int], *, kind: str | None = None, selected: bool = False, multiple_options: bool = False) list[int][source]
Return eligible variable indices.
- Parameters:
assignment (dict of int to int) – Current assignment.
kind (str or None, optional) – Restrict to
treatmentormonitoring.selected (bool, optional) – Require a non-
noneselection.multiple_options (bool, optional) – Require at least two options.
- Returns:
list of int – Sorted eligible indices.
- option_ids(index: int) list[str][source]
Return option ids for one variable.
- Parameters:
index (int) – Variable index.
- Returns:
list of str – Option ids.
- alternative(index: int, assignment: dict[int, int], rng: Random, *, different_method: bool = False) int | None[source]
Choose an alternative option index.
- Parameters:
index (int) – Variable index.
assignment (dict of int to int) – Current assignment.
rng (random.Random) – Random source.
different_method (bool, optional) – Prefer a treatment option with a different method.
- Returns:
int or None – Alternative option index, or None.
- class brushline.optimization.operators.RepairOperator(state: OperatorState, evaluator: ScheduleEvaluator)[source]
Bases:
objectReset a random subset and repair feasibility.
- class brushline.optimization.operators.RepairResult(*, assignment: dict[int, int], changes: list[~brushline.optimization.evaluator.AssignmentChange] = <factory>, feasible: bool, remaining: list[~brushline.optimization.evaluator.EvaluationViolation] = <factory>)[source]
Bases:
BaseModelThe result of a deterministic feasibility repair.
- Parameters:
assignment (dict of int to int) – Repaired assignment.
changes (list of AssignmentChange) – Applied repair changes.
feasible (bool) – Whether all hard violations were removed.
remaining (list of EvaluationViolation) – Remaining hard violations.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.optimization.operators.ShiftOperator(state: OperatorState)[source]
Bases:
objectShift one selected treatment to the adjacent period for the same segment.
- class brushline.optimization.operators.SwapOperator(state: OperatorState)[source]
Bases:
objectSwap options between two eligible variables of the same kind.
- class brushline.optimization.operators.ToggleOperator(state: OperatorState)[source]
Bases:
objectToggle one variable to a random alternative option.
- brushline.optimization.operators.apply_move(assignment: dict[int, int], move: Move) dict[int, int][source]
Apply a move.
- Parameters:
assignment (dict of int to int) – Current assignment.
move (Move) – Move to apply.
- Returns:
dict of int to int – New assignment.
- brushline.optimization.operators.default_operators(evaluator: ScheduleEvaluator, config: OperatorConfig | None = None) tuple[MoveOperator, ...][source]
Return the default operator portfolio.
- Parameters:
evaluator (ScheduleEvaluator) – Exact evaluator.
config (OperatorConfig, optional) – Operator settings.
- Returns:
tuple of MoveOperator – Toggle, method change, shift, swap, block, monitoring, and repair operators.
- brushline.optimization.operators.repair_assignment(evaluator: ScheduleEvaluator, assignment: dict[int, int], config: OperatorConfig | None = None) RepairResult[source]
Repair resource and access violations deterministically.
- Parameters:
evaluator (ScheduleEvaluator) – Exact evaluator.
assignment (dict of int to int) – Starting assignment.
config (OperatorConfig, optional) – Repair settings.
- Returns:
RepairResult – Repaired assignment, changes, feasibility, and remaining violations.
- brushline.optimization.operators.undo_move(assignment: dict[int, int], move: Move) dict[int, int][source]
Undo a move.
- Parameters:
assignment (dict of int to int) – Current assignment.
move (Move) – Move to undo.
- Returns:
dict of int to int – Restored assignment.
- brushline.optimization.operators.validate_move(formulation: Formulation, move: Move) ContractValidation[source]
Validate that every touched option exists.
- Parameters:
formulation (Formulation) – Formulation.
move (Move) – Move to validate.
- Returns:
ContractValidation – Errors and counts.