Stopping criterion

DefaultStoppingCriterionState <: StoppingCriterionState

A StoppingCriterionState that does not require any information besides storing the iteration number when it (last) indicated to stop).

Field

• at_iteration::Int store the iteration number this state indicated to stop.
  • 0 means already at the start it indicated to stop
  • any negative number means that it did not yet indicate to stop.

GroupStoppingCriterionState <: StoppingCriterionState

A StoppingCriterionState that groups multiple StoppingCriterionStates internally as a tuple. This is for example used in combination with StopWhenAny and StopWhenAny

Constructor

GroupStoppingCriterionState(c::Vector{N,StoppingCriterionState} where N)
GroupStoppingCriterionState(c::StoppingCriterionState...)

StopAfter <: StoppingCriterion

store a threshold when to stop looking at the complete runtime. It uses time_ns() to measure the time and you provide a Period as a time limit, for example Minute(15).

Fields

• threshold stores the Period after which to stop

Constructor

StopAfter(t)

initialize the stopping criterion to a Period t to stop after.

StopAfterIteration <: StoppingCriterion

A simple stopping criterion to stop after a maximal number of iterations.

Fields

• max_iterations stores the maximal iteration number where to stop at

Constructor

StopAfterIteration(maxIter)

initialize the functor to indicate to stop after maxIter iterations.

StopAfterTimePeriodState <: StoppingCriterionState

A state for stopping criteria that are based on time measurements, for example StopAfter.

• start stores the starting time when the algorithm is started, that is a call with i=0.
• time stores the elapsed time
• at_iteration indicates at which iteration (including i=0) the stopping criterion was fulfilled and is -1 while it is not fulfilled.

StopWhenAll <: StoppingCriterion

store a tuple of StoppingCriterions and indicate to stop, when all indicate to stop.

Constructor

StopWhenAll(c::NTuple{N,StoppingCriterion} where N)
StopWhenAll(c::StoppingCriterion,...)

StopWhenAny <: StoppingCriterion

store an array of StoppingCriterion elements and indicates to stop, when any single one indicates to stop. The reason is given by the concatenation of all reasons (assuming that all non-indicating return "").

Constructors

StopWhenAny(c::Vector{N,StoppingCriterion} where N)
StopWhenAny(c::StoppingCriterion...)

StoppingCriterion

An abstract type to represent a stopping criterion of an Algorithm.

A concrete StoppingCriterion should also implement a initialize_state(problem::Problem, algorithm::Algorithm, stopping_criterion::StoppingCriterion; kwargs...) function to create its accompanying StoppingCriterionState. as well as the corresponding mutating variant to reset such a StoppingCriterionState.

It should usually implement

• indicates_convergence(stopping_criterion)
• indicates_convergence(stopping_criterion, stopping_criterion_state)
• is_finished!(problem, algorithm, state, stopping_criterion, stopping_criterion_state)
• is_finished(problem, algorithm, state, stopping_criterion, stopping_criterion_state)

StoppingCriterionState

An abstract type to represent a stopping criterion state within a State. It represents the concrete state a StoppingCriterion is in.

It should usually implement

• get_reason(stopping_criterion, stopping_criterion_state)
• indicates_convergence(stopping_criterion, stopping_criterion_state)
• is_finished!(problem, algorithm, state, stopping_criterion, stopping_criterion_state)
• is_finished(problem, algorithm, state, stopping_criterion, stopping_criterion_state)

get_reason(stopping_criterion::StoppingCriterion, stopping_criterion_state::StoppingCriterionState)

Provide a reason in human readable text as to why a StoppingCriterion with StoppingCriterionState indicated to stop. If it does not indicate to stop, this should return an empty string.

Providing the iteration at which this indicated to stop in the reason would be preferable.

indicates_convergence(stopping_criterion::StoppingCriterion, ::StoppingCriterionState)

Return whether or not a StoppingCriterion indicates convergence when it is in StoppingCriterionState

By default this checks whether the StoppingCriterion has actually stopped. If so it returns whether stopping_criterion itself indicates convergence, otherwise it returns false, since the algorithm has then not yet stopped.

indicates_convergence(stopping_criterion::StoppingCriterion)

Return whether or not a StoppingCriterion indicates convergence.

is_finished(problem::Problem, algorithm::Algorithm, state::State)
is_finished(problem::Problem, algorithm::Algorithm, state::State, stopping_criterion::StoppingCriterion, stopping_criterion_state::StoppingCriterionState)
is_finished!(problem::Problem, algorithm::Algorithm, state::State)
is_finished!(problem::Problem, algorithm::Algorithm, state::State, stopping_criterion::StoppingCriterion, stopping_criterion_state::StoppingCriterionState)

Indicate whether an Algorithm solving Problem is finished having reached a certain State. The variant with three arguments by default extracts the StoppingCriterion and its StoppingCriterionState and their actual checks are performed in the implementation with five arguments.

The mutating variant does alter the stopping_criterion_state and and should only be called once per iteration, the other one merely inspects the current status without mutation.

is_finished(problem::Problem, algorithm::Algorithm, state::State)
is_finished(problem::Problem, algorithm::Algorithm, state::State, stopping_criterion::StoppingCriterion, stopping_criterion_state::StoppingCriterionState)
is_finished!(problem::Problem, algorithm::Algorithm, state::State)
is_finished!(problem::Problem, algorithm::Algorithm, state::State, stopping_criterion::StoppingCriterion, stopping_criterion_state::StoppingCriterionState)

Indicate whether an Algorithm solving Problem is finished having reached a certain State. The variant with three arguments by default extracts the StoppingCriterion and its StoppingCriterionState and their actual checks are performed in the implementation with five arguments.

The mutating variant does alter the stopping_criterion_state and and should only be called once per iteration, the other one merely inspects the current status without mutation.

is_finished(problem::Problem, algorithm::Algorithm, state::State)
is_finished(problem::Problem, algorithm::Algorithm, state::State, stopping_criterion::StoppingCriterion, stopping_criterion_state::StoppingCriterionState)
is_finished!(problem::Problem, algorithm::Algorithm, state::State)
is_finished!(problem::Problem, algorithm::Algorithm, state::State, stopping_criterion::StoppingCriterion, stopping_criterion_state::StoppingCriterionState)

Indicate whether an Algorithm solving Problem is finished having reached a certain State. The variant with three arguments by default extracts the StoppingCriterion and its StoppingCriterionState and their actual checks are performed in the implementation with five arguments.

The mutating variant does alter the stopping_criterion_state and and should only be called once per iteration, the other one merely inspects the current status without mutation.

is_finished(problem::Problem, algorithm::Algorithm, state::State)
is_finished(problem::Problem, algorithm::Algorithm, state::State, stopping_criterion::StoppingCriterion, stopping_criterion_state::StoppingCriterionState)
is_finished!(problem::Problem, algorithm::Algorithm, state::State)
is_finished!(problem::Problem, algorithm::Algorithm, state::State, stopping_criterion::StoppingCriterion, stopping_criterion_state::StoppingCriterionState)

Indicate whether an Algorithm solving Problem is finished having reached a certain State. The variant with three arguments by default extracts the StoppingCriterion and its StoppingCriterionState and their actual checks are performed in the implementation with five arguments.

The mutating variant does alter the stopping_criterion_state and and should only be called once per iteration, the other one merely inspects the current status without mutation.

&(s1,s2)
s1 & s2

Combine two StoppingCriterion within an StopWhenAll. If either s1 (or s2) is already an StopWhenAll, then s2 (or s1) is appended to the list of StoppingCriterion within s1 (or s2).

Example

a = StopAfterIteration(200) & StopAfter(Minute(1))

Is the same as

a = StopWhenAll(StopAfterIteration(200), StopAfter(Minute(1))

|(s1,s2)
s1 | s2

Combine two StoppingCriterion within an StopWhenAny. If either s1 (or s2) is already an StopWhenAny, then s2 (or s1) is appended to the list of StoppingCriterion within s1 (or s2)

Example

a = StopAfterIteration(200) | StopAfter(Minute(1))

Is the same as

a = StopWhenAny(StopAfterIteration(200), StopAfter(Minute(1)))

summary(io::IO, stopping_criterion::StoppingCriterion, stopping_criterion_state::StoppingCriterionState)

Provide a summary of the status of a stopping criterion – its parameters and whether it currently indicates to stop. It should not be longer than one line

Example

For the StopAfterIteration criterion, the summary looks like

Max Iterations (15): not reached