Stateful heuristic API

Fresh Solutions heuristic for the stateful strategic problem.

The adapter exposes one discrete treatment choice per segment-period. Evaluation simulates the linear risk state, budget, and crew-hour constraints. The heuristic is used when the exact MILP is too large for the available time; its result is explicitly marked feasible, not optimal.

exception brushline.strategic.heuristic.HeuristicError[source]

Bases: ValueError

Raised when heuristic inputs or a replayed result are inconsistent.

class brushline.strategic.heuristic.StatefulHeuristicAdapter(segments: list[StatefulSegment], methods: list[StatefulMethod], periods: list[StatefulPeriod], config: StatefulConfig)[source]

Bases: object

Fresh Solutions adapter over segment-period treatment choices.

property variable_count: int

Return the number of segment-period choices.

option_count(variable: int) → int[source]

Return the option count for one segment-period variable.

option_at(variable: int, option: int) → object[source]

Return the method name for an option.

initial_assignment() → dict[int, int][source]

Seed search with a deterministic risk-per-dollar greedy assignment.

random_assignment(rng: Random) → dict[int, int][source]

Return a random complete assignment.

mutate(assignment: Mapping[int, int], rate: float, rng: Random) → dict[int, int][source]

Mutate a fraction of variables without leaving the option range.

crossover(left: Mapping[int, int], right: Mapping[int, int], rng: Random) → dict[int, int][source]

Create a random child from two complete assignments.

evaluate(assignment: Mapping[int, int]) → Evaluation[source]

Evaluate feasibility, risk, cost, and hours with exact state replay.

evaluate_batch(assignments: Sequence[Mapping[int, int]]) → list[Evaluation][source]

Evaluate a batch of assignments.

propose(assignment: Mapping[int, int], rng: random.Random) → Change | None[source]

Propose one variable-option change.

apply(assignment: Mapping[int, int], change: Change) → dict[int, int][source]

Apply one validated change.

undo(assignment: Mapping[int, int], change: Change) → dict[int, int][source]

Undo one validated change.

brushline.strategic.heuristic.build_stateful_heuristic(*, instance_id: str, segments: list[StatefulSegment], methods: list[StatefulMethod], periods: list[StatefulPeriod], config: StatefulConfig | None = None, iterations: int = 1200, seed: int = 7, temperature: float = 2.0, cooling: float = 0.997, created_utc: datetime | None = None) → StatefulPlan[source]

Run Fresh Solutions local search over the stateful assignment.

Parameters:
  • instance_id (str) – Instance id.

  • segments (list) – Stateful problem inputs.

  • methods (list) – Stateful problem inputs.

  • periods (list) – Stateful problem inputs.

  • config (StatefulConfig, optional) – Risk growth and objective weights.

  • iterations (int, optional) – Local-search iterations.

  • seed (int, optional) – Deterministic search seed.

  • temperature (float, optional) – Annealing schedule.

  • cooling (float, optional) – Annealing schedule.

  • created_utc (datetime, optional) – Creation time.

Returns:

StatefulPlan – Feasible heuristic plan and search provenance.

Raises:

HeuristicError – If the search cannot produce a feasible assignment.