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:
ProtocolAny 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.
_computeis written once, here: it derives one seed per start from the seed received, runs every start to convergence withiterate, 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 aftermax_iterationssteps.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