Core

Core building blocks shared by all heuristics.

InfeasibleError

Bases: RuntimeError

A strategy could not produce a feasible solution.

Problem dataclass

Domain-agnostic optimization problem; heuristics only use this.

OptimizationResult dataclass

Outcome of an optimization run.

history holds one record per iteration (e.g. best value, or a dict of stats); its shape is up to the algorithm. elapsed is in seconds. metadata carries extras such as the termination reason.

State dataclass

Snapshot of a run, built by the heuristic once per iteration.

better(value, other, direction)

True if a is strictly better than b.

oriented(value, direction)

Value where lower is always better.

counting(problem)

Return a copy of problem whose evaluate is counted, plus a zero-arg function reading the count so far.

penalty(problem, penalty_fn)

Problem whose evaluate is worsened by penalty_fn(solution) (>= 0, zero when feasible); infeasible solutions are then allowed.

generate is intentionally left unchanged. To also change it, compose: dataclasses.replace(penalty(p, f), generate=g).

reject(produce, feasible, max_tries=1000)

Call produce until feasible, at most max_tries times.

repair(produce, fix, feasible=None)

Pass every produced solution through fix; if feasible is given, raise InfeasibleError when the repaired solution is still infeasible.

run(problem, *, stop, init, step, extras=None)

Run init then step until stop; both see the counted problem. stop is checked before every step. metadata holds evaluations, termination ('stop'), state (the final State) and extras(final_carry) if given.

target_value(value, direction=None)

Stop once best_value reaches value; compares under state.direction unless direction overrides it.