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: object

Set a contiguous period block for one segment to one treatment option.

propose(assignment: dict[int, int], rng: Random) → Move | None[source]

Propose a block move.

Parameters:
  • assignment (dict of int to int) – Current assignment.

  • rng (random.Random) – Random source.

Returns:

Move or None – Block move, or None.

class brushline.optimization.operators.MethodChangeOperator(state: OperatorState)[source]

Bases: object

Change one selected treatment to an option with a different method.

propose(assignment: dict[int, int], rng: Random) → Move | None[source]

Propose a method change.

Parameters:
  • assignment (dict of int to int) – Current assignment.

  • rng (random.Random) – Random source.

Returns:

Move or None – Method change, or None.

class brushline.optimization.operators.MonitoringMoveOperator(state: OperatorState)[source]

Bases: object

Change one monitoring option.

propose(assignment: dict[int, int], rng: Random) → Move | None[source]

Propose a monitoring move.

Parameters:
  • assignment (dict of int to int) – Current assignment.

  • rng (random.Random) – Random source.

Returns:

Move or None – Monitoring move, or None.

class brushline.optimization.operators.Move(*, kind: Annotated[str, MinLen(min_length=1)], changes: Annotated[tuple[AssignmentChange, ...], MinLen(min_length=1)], description: str = '')[source]

Bases: BaseModel

A 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: Protocol

Protocol for a deterministic, seed-driven operator.

propose(assignment: dict[int, int], rng: Random) → Move | None[source]

Propose one move, or None when no eligible variable exists.

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: BaseModel

Operator 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: ValueError

Raised when a move or repair request is inconsistent.

class brushline.optimization.operators.OperatorState(formulation: Formulation, config: OperatorConfig | None = None)[source]

Bases: object

Shared eligibility and option helpers.

Parameters:
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 treatment or monitoring.

  • selected (bool, optional) – Require a non-none selection.

  • 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: object

Reset a random subset and repair feasibility.

propose(assignment: dict[int, int], rng: Random) → Move | None[source]

Propose a destroy-repair move.

Parameters:
  • assignment (dict of int to int) – Current assignment.

  • rng (random.Random) – Random source.

Returns:

Move or None – Destroy-repair move, or None.

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: BaseModel

The 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: object

Shift one selected treatment to the adjacent period for the same segment.

propose(assignment: dict[int, int], rng: Random) → Move | None[source]

Propose a period shift.

Parameters:
  • assignment (dict of int to int) – Current assignment.

  • rng (random.Random) – Random source.

Returns:

Move or None – Period shift, or None.

class brushline.optimization.operators.SwapOperator(state: OperatorState)[source]

Bases: object

Swap options between two eligible variables of the same kind.

propose(assignment: dict[int, int], rng: Random) → Move | None[source]

Propose a swap.

Parameters:
  • assignment (dict of int to int) – Current assignment.

  • rng (random.Random) – Random source.

Returns:

Move or None – Swap, or None.

class brushline.optimization.operators.ToggleOperator(state: OperatorState)[source]

Bases: object

Toggle one variable to a random alternative option.

propose(assignment: dict[int, int], rng: Random) → Move | None[source]

Propose a toggle move.

Parameters:
  • assignment (dict of int to int) – Current assignment.

  • rng (random.Random) – Random source.

Returns:

Move or None – Toggle move, or None.

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:
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.