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:
ValueErrorRaised 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:
objectFresh Solutions adapter over segment-period treatment choices.
- property variable_count: int
Return the number of segment-period choices.
- initial_assignment() dict[int, int][source]
Seed search with a deterministic risk-per-dollar greedy 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.
- 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.