Implement most of StopWhenAny and StopWhenAll and their |, & operations.

Author: kellertuer

docs/src/interface.md

@@ -15,7 +15,7 @@ consists of:
 The combination of the static information should be enough to initialize the varying data.
 
 This general scheme is a guiding principle of the package, splitting information into _static_
-or _configuration_ types or data that allows to [`initialize`](@ref) a correspondint _variable_ data type.
+or _configuration_ types or data that allows to [`initialize_state`](@ref) a correspondint _variable_ data type.
 
 The order of arguments is given by two ideas
 

src/AlgorithmsInterface.jl

@@ -18,8 +18,8 @@ include("interface/interface.jl")
 include("stopping_criterion.jl")
 
 export Algorithm, Problem, State
-export StoppingCriterion
-export StopAfter, StopAfterIteration
+export StoppingCriterion, StoppingCriterionState
+export StopAfter, StopAfterIteration, StopWhenAll, StopWhenAny
 export is_finished
 export initialize_state, initialize_state!, is_finished
 export get_iteration

src/stopping_criterion.jl

@@ -66,9 +66,9 @@ function indicates_convergence(sc::StoppingCriterion, scs::StoppingCriterionStat
     return length(get_reason(sc, scs)) > 0 ? indicates_convergence(sc) : false
 end
 
-function get_summary end
+function summary end
 @doc """
-    get_summary(sc::StoppingCriterion, scs::StoppingCriterionState)
+    summary(sc::StoppingCriterion, scs::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
@@ -81,7 +81,230 @@ For the [`StopAfterIteration`](@ref) criterion, the summary looks like
 Max Iterations (15): not reached
 ```
 """
-get_summary(sc::StoppingCriterion, scs::StoppingCriterionState)
+summary(::StoppingCriterion, ::StoppingCriterionState)
+
+#
+#
+# Meta StoppingCriteria
+@doc raw"""
+    StopWhenAll <: StoppingCriterion
+
+store a tuple of [`StoppingCriterion`](@ref)s and indicate to stop,
+when _all_ indicate to stop.
+
+# Constructor
+
+    StopWhenAll(c::NTuple{N,StoppingCriterion} where N)
+    StopWhenAll(c::StoppingCriterion,...)
+"""
+struct StopWhenAll{TCriteria<:Tuple} <: StoppingCriterion
+    criteria::TCriteria
+    StopWhenAll(c::Vector{StoppingCriterion}) = new{typeof(tuple(c...))}(tuple(c...))
+    StopWhenAll(c...) = new{typeof(c)}(c)
+end
+
+function indicates_convergence(sc::StopWhenAll)
+    return any(indicates_convergence(sc_i) for sc_i in sc.criteria)
+end
+
+function show(io::IO, sc::StopWhenAll)
+    s = ""
+    for sc_i in sc.criteria
+        s = s * "\n * " * replace("$(sc_i)", "\n" => "\n    ") #increase indent
+    end
+    return print(io, "StopWhenAll with the Stopping Criteria\n$(s)")
+end
+
+"""
+    &(s1,s2)
+    s1 & s2
+
+Combine two [`StoppingCriterion`](@ref) within an [`StopWhenAll`](@ref).
+If either `s1` (or `s2`) is already an [`StopWhenAll`](@ref), then `s2` (or `s1`) is
+appended to the list of [`StoppingCriterion`](@ref) within `s1` (or `s2`).
+
+# Example
+    a = StopAfterIteration(200) & StopAfter(Minute(1))
+
+Is the same as
+
+    a = StopWhenAll(StopAfterIteration(200), StopAfter(Minute(1))
+"""
+Base.:&(s1::StoppingCriterion, s2::StoppingCriterion) = StopWhenAll(s1, s2)
+Base.:&(s1::StoppingCriterion, s2::StopWhenAll) = StopWhenAll(s1, s2.criteria...)
+Base.:&(s1::StopWhenAll, s2::StoppingCriterion) = StopWhenAll(s1.criteria..., s2)
+Base.:&(s1::StopWhenAll, s2::StopWhenAll) = StopWhenAll(s1.criteria..., s2.criteria...)
+
+@doc raw"""
+    StopWhenAny <: StoppingCriterion
+
+store an array of [`StoppingCriterion`](@ref) 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...)
+"""
+struct StopWhenAny{TCriteria<:Tuple} <: StoppingCriterion
+    criteria::TCriteria
+    StopWhenAny(c::Vector{<:StoppingCriterion}) = new{typeof(tuple(c...))}(tuple(c...))
+    StopWhenAny(c::StoppingCriterion...) = new{typeof(c)}(c)
+end
+
+function indicates_convergence(sc::StopWhenAny)
+    return all(indicates_convergence(ci) for ci in sc.criteria)
+end
+function show(io::IO, sc::StopWhenAny)
+    s = ""
+    for sc_i in sc.criteria
+        s = s * "\n * " * replace("$(sc_i)", "\n" => "\n    ") #increase indent
+    end
+    return print(io, "StopWhenAny with the Stopping Criteria\n$(s)")
+end
+"""
+    |(s1,s2)
+    s1 | s2
+
+Combine two [`StoppingCriterion`](@ref) within an [`StopWhenAny`](@ref).
+If either `s1` (or `s2`) is already an [`StopWhenAny`](@ref), then `s2` (or `s1`) is
+appended to the list of [`StoppingCriterion`](@ref) within `s1` (or `s2`)
+
+# Example
+    a = StopAfterIteration(200) | StopAfter(Minute(1))
+
+Is the same as
+
+    a = StopWhenAny(StopAfterIteration(200), StopAfter(Minute(1)))
+"""
+Base.:|(s1::StoppingCriterion, s2::StoppingCriterion) = StopWhenAny(s1, s2)
+Base.:|(s1::StoppingCriterion, s2::StopWhenAny) = StopWhenAny(s1, s2.criteria...)
+Base.:|(s1::StopWhenAny, s2::StoppingCriterion) = StopWhenAny(s1.criteria..., s2)
+Base.:|(s1::StopWhenAny, s2::StopWhenAny) = StopWhenAny(s1.criteria..., s2.criteria...)
+
+# A common state for stopping criteria working on tuples of stopping criteria
+"""
+    GroupStoppingCriterionState <: StoppingCriterionState
+
+A [`StoppingCriterionState`](@ref) that groups multiple [`StoppingCriterionState`](@ref)s
+internally as a tuple.
+This is for example used in combination with [`StopWhenAny`](@ref) and [`StopWhenAny`](@ref)
+
+# Constructor
+    GroupStoppingCriterionState(c::Vector{N,StoppingCriterionState} where N)
+    GroupStoppingCriterionState(c::StoppingCriterionState...)
+"""
+mutable struct GroupStoppingCriterionState{TCriteriaStates<:Tuple} <: StoppingCriterionState
+    criteria_states::TCriteriaStates
+    at_iteration::Int
+    GroupStoppingCriterionState(c::Vector{<:StoppingCriterionState}) =
+        new{typeof(tuple(c...))}(tuple(c...), -1)
+    GroupStoppingCriterionState(c::StoppingCriterionState...) = new{typeof(c)}(c, -1)
+end
+
+function initialize_state(
+    p::Problem,
+    a::Algorithm,
+    sc::Union{StopWhenAll,StopWhenAny};
+    kwargs...,
+)
+    return GroupStoppingCriterionState([
+        initialize_state(p, a, sc_i; kwargs) for sc_i in sc.criteria
+    ])
+end
+function initialize_state!(
+    scs::GroupStoppingCriterionState,
+    p::Problem,
+    a::Algorithm,
+    sc::Union{StopWhenAll,StopWhenAny};
+    kwargs...,
+)
+    for (scs_i, sc_i) in zip(scs.criteria_states, sc.criteria)
+        initialize_state!(scs_i, p, a, sc_i; kwargs...)
+    end
+    scs.at_iteration = -1
+    return scs
+end
+
+function get_reason(sc::Union{StopWhenAll,StopWhenAny}, scs::GroupStoppingCriterionState)
+    if scs.at_iteration >= 0
+        return string(
+            (
+                get_reason(sc_i, scs_i) for
+                (sc_i, scs_i) in zip(sc.criteria, scs.criteria_states)
+            )...,
+        )
+    end
+    return ""
+end
+
+function summary(sc::StopWhenAny, scs::GroupStoppingCriterionState)
+    has_stopped = (scs.at_iteration >= 0)
+    s = has_stopped ? "reached" : "not reached"
+    r = "Stop When _one_ of the following are fulfilled:\n"
+    for (sc_i, scs_i) in zip(sc.criteria, scs.criteria_states)
+        s = replace(summary(sc_i, scs_i), "\n" => "\n    ")
+        r = "$r    $(s)\n"
+    end
+    return "$(r)Overall: $s"
+end
+function summary(sc::StopWhenAll, scs::GroupStoppingCriterionState)
+    has_stopped = (scs.at_iteration >= 0)
+    s = has_stopped ? "reached" : "not reached"
+    r = "Stop When _all_ of the following are fulfilled:\n"
+    for (sc_i, scs_i) in zip(sc.criteria, scs.criteria_states)
+        s = replace(summary(sc_i, scs_i), "\n" => "\n    ")
+        r = "$r    $(s)\n"
+    end
+    return "$(r)Overall: $s"
+end
+# Meta functors
+function (scs::GroupStoppingCriterionState)(
+    p::Problem,
+    a::Algorithm,
+    s::State,
+    sc::StopWhenAll,
+)
+    k = get_iteration(s)
+    (k == 0) && (scs.at_iteration = -1) # reset on init
+    if all(st -> st[2](p, a, s, st[1]), zip(sc.criteria, scs.criteria_states))
+        scs.at_iteration = k
+        return true
+    end
+    return false
+end
+
+# `_fast_any(f, tup::Tuple)`` is functionally equivalent to `any(f, tup)`` but on Julia 1.10
+# this implementation is faster on heterogeneous tuples
+@inline _fast_any(f, tup::Tuple{}) = true
+@inline _fast_any(f, tup::Tuple{T}) where {T} = f(tup[1])
+@inline function _fast_any(f, tup::Tuple)
+    if f(tup[1])
+        return true
+    else
+        return _fast_any(f, tup[2:end])
+    end
+end
+
+function (scs::GroupStoppingCriterionState)(
+    p::Problem,
+    a::Algorithm,
+    s::State,
+    sc::StopWhenAny,
+)
+    k = get_iteration(s)
+    (k == 0) && (c.at_iteration = -1) # reset on init
+    if _fast_any(st -> st[2](p, a, s, st[1]), zip(sc.criteria, scs.criteria_states))
+        c.at_iteration = k
+        return true
+    end
+    return false
+end
+
+#
+#
+# Concrete Stopping Criteria
 
 @doc raw"""
     StopAfterIteration <: StoppingCriterion
@@ -153,7 +376,7 @@ function get_reason(sc::StopAfterIteration, scs::DefaultStoppingCriterionState)
     return ""
 end
 indicates_convergence(sc::StopAfterIteration) = false
-function get_summary(sc::StopAfterIteration, scs::DefaultStoppingCriterionState)
+function summary(sc::StopAfterIteration, scs::DefaultStoppingCriterionState)
     has_stopped = (scs.at_iteration >= 0)
     s = has_stopped ? "reached" : "not reached"
     return "Max Iteration $(sc.max_iterations):\t$s"
@@ -246,7 +469,7 @@ function get_reason(sc::StopAfter, scs::StopAfterTimePeriodState)
     end
     return ""
 end
-function get_summary(sc::StopAfter, scs::StopAfterTimePeriodState)
+function summary(sc::StopAfter, scs::StopAfterTimePeriodState)
     has_stopped = (scs.at_iteration >= 0)
     s = has_stopped ? "reached" : "not reached"
     return "stopped after $(sc.threshold):\t$s"