civiqhub_selene.blocks.iterative

Base class of the estimators that run an iterative algorithm.

IterativeEstimator knows how to run an iterative algorithm: several starts, one seed per start, convergence, and the choice of the best start. A concrete estimator writes three hooks and never writes a loop nor draws a seed:

_start(data, rng)                           -> a starting state
_step(data, state)                          -> the state after one full iteration
_finish(data, state, history, computation)  -> the public value
class civiqhub_selene.blocks.iterative.HasObjective(*args, **kwargs)[source]

Bases: Protocol

Any state that carries the quantity its algorithm maximises.

property objective: float

The quantity the algorithm maximises, at this state.

class civiqhub_selene.blocks.iterative.IterativeEstimator[source]

Bases: Estimator[DataT_contra, ValueT_co], Generic[DataT_contra, StateT, ValueT_co]

An estimator that maximises an objective from several random starts.

_compute is written once, here: it derives one seed per start from the seed received, runs every start to convergence with iterate, the only convergence loop of the package, keeps the start whose final objective is the largest (the first one on a tie) and hands it to _finish().

A step must not lower the objective. A start stops as soon as its gain of objective goes under tolerance, or after max_iterations steps.

Fields a concrete subclass declares:

n_starts

Number of random starts; the best one is kept.

Type:

int

max_iterations

Largest number of iterations of a start.

Type:

int

tolerance

Gain of objective under which a start stops.

Type:

float

abstractmethod _start(data, rng)[source]

Return a starting state. Called once per start, with the generator of the start.

Parameters:
  • data (DataT_contra)

  • rng (Generator)

Return type:

StateT

abstractmethod _step(data, state)[source]

Return the state after one full iteration. It must not lower objective.

Parameters:
  • data (DataT_contra)

  • state (StateT)

Return type:

StateT

abstractmethod _finish(data, state, history, computation)[source]

Return the public value drawn from the best final state.

Parameters:
  • data (DataT_contra) – The input.

  • state (StateT) – The final state of the start that was kept.

  • history (History) – The objective after each iteration of that start, and whether it converged.

  • computation (str) – Fingerprint the result will carry.

Return type:

ValueT_co