Start redesign

but forgot to pull, so interms commit to merge real quick.

Author: kellertuer

docs/make.jl

@@ -44,6 +44,7 @@ makedocs(;
         "Home" => "index.md",
         "Interface" => "interface.md",
         "Stopping criteria" => "stopping_criterion.md",
+        "Notation" => "notation.md",
         "References" => "references.md",
     ],
     plugins = [bib, links],

docs/src/interface.md

@@ -1,4 +1,28 @@
-# Main Interface types
+# The algorithm interface
+
+## General design ideas
+
+The interface this package provides is based on three ingredients of running an algorithm
+consists of:
+
+* a [`Problem`](@ref) that is to be solved and contains all information that is algorithm independent.
+  This is _static information_ in the sense that it does not change during the runtime of the algorithm
+* an [`Algorithm`](@ref) that includes all of the _settings_ and _parameters_ that an algorithm.
+  this is also information that is _static_
+* a [`State`](@ref) that contains all remaining data, especially data that might vary during the iteration,
+  temporary caches, for example the current iteration the algorithm run is in and the current iterate, respectively.
+
+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.
+
+The order of arguments is given by two ideas
+
+1. for non-mutating functions the order should be from the most fixed data to the most variable one.
+  For example the three types just mentioned would be ordered like `f(problem, algorithm, state)`
+2. For mutating functions the variable that is mutated comes first, for the remainder the guiding principle from 1 continues.
+  The main case here is `f!(state, problem, algorithm)`.
 
 ```@autodocs
 Modules = [AlgorithmsInterface]

docs/src/notation.md

@@ -0,0 +1,13 @@
+# Notation
+
+Throughout the package we use the following abbreviations and variable names,
+where the longer names are usually used in the documentation and as keywords.
+The shorter ones are often used in code when their name does not cause ambiguities.
+
+| Name | Variable | Comment |
+| ---- | -------- | ------- |
+| [`Algorithm`](@ref) | `algorithm`, `a` | |
+| [`Problem`](@ref) | `problem`, `p` | |
+| [`State`](@ref) | `state`, `s` | |
+| [`StoppingCriterion`](@ref) | `stopping_criterion`, `sc` | |
+| [`StoppingCriterionState`](@ref) | `stopping_criterion_state`, `scs` | |

src/interface/algorithm.jl

@@ -7,9 +7,30 @@ A concrete algorithm contains all static parameters that characterise the algori
 Together with a [`Problem`](@ref) an `Algorithm` subtype should be able to initialize
 or reset a [`State`](@ref).
 
+## Usual fields
+
+Usually this should include the following. If you use this naming scheme, default functions
+e.g. as accessors
+
+* `stopping_criterion` a [`StoppingCriterion`](@ref)
+
+## Methods
+
+The following methods should be implemented for an [`Algorithm`](@ref)
+
+* [`get_stopping_criterion`](@ref) to return the algorithms stopping criterion.
 ## Example
 
 For a [gradient descent](https://en.wikipedia.org/wiki/Gradient_descent) algorithm
 the algorithm would specify which step size selection to use.
 """
 abstract type Algorithm end
+
+"""
+    get_stopping_criterion(a::Algorithm)
+
+Return the [`StoppingCriterion`](@ref) of the [`Algorithm`](@ref) `a`.
+
+The default assumes that the criterion is stored in `s.stopping_criterion_state`.
+"""
+get_stopping_criterion(a::Algorithm) = a.stopping_criterion

src/interface/interface.jl

@@ -1,6 +1,6 @@
 _doc_init_state = """
     s = initialize_state(p::Problem, a::Algorithm; kwargs...)
-    initialize_state!(p::Problem, a::Algorithm, s::State; kwargs...)
+    initialize_state!(s::State, p::Problem, a::Algorithm; kwargs...)
 
 Initialize a [`State`](@ref) `s` base on a [`Problem`](@ref) `p` and an [`Algorithm`](@ref).
 The `kwargs...` should allow to initialize for example the initial point.
@@ -19,10 +19,14 @@ initialize_state!(::State, ::Problem, ::Algorithm; kwargs...)
 
 @doc """
     is_finished(p::Problem, a::Algorithm, s::State)
+
+Return `true` if the [`Algorithm`](@ref) `a` solving the [`Problem`](@ref) `p`
+with current [`State`](@ref) `s` is finished
 """
 function is_finished(p::Problem, a::Algorithm, s::State)
-    sc = get_stopping_criterion(s)
-    return sc(p, a, s)
+    scs = get_stopping_criterion_state(s)
+    sc = get_stopping_criterion(a)
+    return scs(p, a, s, sc)
 end
 
 # has to be defined before used in solve but is documented alphabetically after
@@ -46,12 +50,12 @@ end
     solve!(p::Problem, a::Algorithm, s::State; kwargs...)
 
 Solve the [`Problem`](@ref) `p` using the [`Algorithm`](@ref) `a`
-working on the [`State`](@ref).
+modifying on the [`State`](@ref).
 
-All keyword arguments are passed to the [`initialize_state!`](@ref) function.
+All keyword arguments are passed to the [`initialize_state!`](@ref)`(s, p, a)` function.
 """
-function solve!(p::Problem, a::Algorithm, s::State; kwargs...)
-    initialize_state!(p, a, s; kwargs...)
+function solve!(s::State, p::Problem, a::Algorithm; kwargs...)
+    initialize_state!(s, p, a; kwargs...)
     while !is_finished(p, a, s)
         increment!(s)
         step!(p, a, s)
@@ -60,9 +64,9 @@ end
 
 function step! end
 @doc """
-    step!(p::Problem, a::Algorithm, s::State)
+    step!(s::State, p::Problem, a::Algorithm)
 
 Perform the current step of an [`Algorithm`](@ref) `a` solving [`Problem`](@ref) `p`
-starting from [`State`](@ref) `s`.
+modifying the algorithms [`State`](@ref) `s`.
 """
-step!(p::Problem, a::Algorithm, s::State)
+step!(state::State, p::Problem, a::Algorithm)

src/interface/state.jl

@@ -6,22 +6,27 @@ An abstract type to represent the state an iterative algorithm is in.
 The state consists of any information that describes the current step the algorithm is in
 and keeps all information needed from one step to the next.
 
-Usually this should include
+## Usual fields
+
+Usually this should include the following. If you use this naming scheme, default functions
+e.g. as accessors
 
 * `iteration` – the current iteration step ``k`` that is is currently performed or was last performed
-* `stopping_criterion` – a `StoppingCriterion` that indicates whether the algorithm
+* `stopping_criterion_state` – a [`StoppingCriterionState`](@ref) that indicates whether an [`Algorithm`](@ref)
   will stop after this iteration or has stopped.
 * `iterate` the current iterate ``x^{(k)}```.
 
 These variable names given in this list are the defaults for which the accessors are implemented,
 such that if your concrete `MyState <: State` follows this convention, you do not have to reimplement
 their accessors.
 
-# Methods
+## Methods
+
 The following methods should be implemented for a state
+
 * [`get_iteration`](@ref)`(s)` to return the current iteration number
 * [`increment!](@ref)`(s)`
-* [`get_stopping_criterion`](@ref) return the [`StoppingCriterion`](@ref)
+* [`get_stopping_criterion_state`](@ref) return the [`StoppingCriterionState`](@ref)
 * [`get_iterate`](@ref) return the current iterate ``x^{(k)}``.
 """
 abstract type State end
@@ -57,10 +62,10 @@ function increment!(s::State)
 end
 
 """
-    get_stopping_criterion(s::State)
+    get_stopping_criterion_state(s::State)
 
-Return the [`StoppingCriterion`](@ref) of the [`State`](@ref) `s`.
+Return the [`StoppingCriterionState`](@ref) of the [`State`](@ref) `s`.
 
-The default assumes that the criterion is stored in `s.stopping_criterion`.
+The default assumes that the criterion is stored in `s.stopping_criterion_state`.
 """
-get_stopping_criterion(s::State) = s.stopping_criterion
+get_stopping_criterion(s::State) = s.stopping_criterion_state

src/stopping_criterion.jl

@@ -1,52 +1,73 @@
 @doc """
     StoppingCriterion
 
-An abstract type to represent a stopping criterion of an solver.
+An abstract type to represent a stopping criterion.
 
-Any concrete stopping criterion should be implemented as a functor,
-that takes the “usual tuple” `(p, a, s)` of a [`Problem`](@ref) `p`,
-an [`Algorithm`](@ref) and a [`State`](@ref) as input, where this criterion
-should usually be part of the [`State`](@ref) itself.
-
-## Methods
+A concrete [`StoppingCriterion`](@ref) `sc` should also implement a
+[`initialize(sc::StoppingCriterion)`](@ref) function to create its accompaying
+[`StoppingCriterionState`](@ref).
+It should usually implement
 
-A concrete `StoppingCriterion` `sc` should provide the following functions
-besides the above-mentioned functor is it itself
-
-* `get_reason(sc)` a human readable text of about one line of length providing a reason
-  why this stopping criterion indicated to stop. An empty string if it did not indicate to stop
-* `get_summary(sc)` a short summary of this stopping criterion, and whether it was reached,
-  e.g. a short string like `"Max Iterations (15): reached"`
 * `indicates_convergence(sc)` a boolean whether or not this stopping criterion would indicate
   that the algorithm has converged, if it indicates to stop.
-* `show(io::IO, sc)` to display its constructor and the `get_summary`
+* `show(io::IO, scs)` for use in REPL and display within an [`Algorithm`](@ref).
 """
 abstract type StoppingCriterion end
 
+@doc """
+    StoppingCriterionState
+
+An abstract type to represent a stopping criterion state withinn a [`State`](@ref).
+
+Any concrete stopping criterion should be implemented as a functor,
+that takes the “usual tuple” `(problem, algorithm, state, stopping_criterion)`
+of a [`Problem`](@ref) `p`, an [`Algorithm`](@ref) and a [`State`](@ref) as input,
+as well as the corresponding [`StoppingCriterion`](@ref). Though this is usually stored¨
+in the [`Algorithm`](@ref) `algorithm`, the extra parameter allows both for more flexibility and
+for multiple dispatch.
+The concrete [`StoppingCriterionState`](@ref) should be part of the [`State`](@ref) `state`.
+
+The functor might modify the stopping criterion state.
+"""
+abstract type StoppingCriterionState end
+
 function get_reason end
 @doc """
-    get_reason(sc::StoppingCriterion)
+    get_reason(sc::StoppingCriterion, scs::StoppingCriterionState)
 
-Provide a reason in human readable text as to why a [`StoppingCriterion`](@ref) indicated
-to stop. If it does not indicate to stop, this should return an empty string.
+Provide a reason in human readable text as to why a [`StoppingCriterion`](@ref) `sc
+with [`StoppingCriterionState`](@ref) `scs` 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 would be preferrable.
+Providing the iteration at which this indicated to stop in the reason would be preferable.
 """
-get_reason(::StoppingCriterion)
+get_reason(::StoppingCriterion, ::StoppingCriterionState)
 
 function indicates_convergence end
 @doc """
     indicates_convergence(sc::StoppingCriterion)
 
-Return whether or not a [`StoppingCriterion`](@ref) indicates convergence of an algorithm
-if it would indicate to stop.
+Return whether or not a [`StoppingCriterion`](@ref) `sc` indicates convergence.
 """
-indicates_convergence(::StoppingCriterion)
+indicates_convergence(sc::StoppingCriterion)
+
+@doc """
+    indicates_convergence(sc::StoppingCriterion, ::StoppingCriterionState)
 
+Return whether or not a [`StoppingCriterion`](@ref) `sc` indicates convergence
+when it is in [`StoppingCriterionState`](@ref)
+
+By default this checks whether the [`StoppingCriterion`](@ref) has actually stopped.
+If so it returns whether `sc` itself indicates convergence, otherwise it returns `false`,
+since the algorithm has then not yet stopped.
+"""
+function indicates_convergence(sc::StoppingCriterion, scs::StoppingCriterionState)
+    return length(get_reason(sc, scs)) > 0 ? indicates_convergence(sc) : false
+end
 
 function get_summary end
 @doc """
-    get_summary(sc::StoppingCriterion)
+    get_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
@@ -59,42 +80,60 @@ For the [`StopAfterIteration`](@ref) criterion, the summary looks like
 Max Iterations (15): not reached
 ```
 """
-get_summary(sc::StoppingCriterion)
+get_summary(sc::StoppingCriterion, scs::StoppingCriterionState)
 
 @doc raw"""
     StopAfterIteration <: StoppingCriterion
 
-A functor for a stopping criterion to stop after a maximal number of iterations.
+A simple stopping criterion to stop after a maximal number of iterations.
 
 # Fields
 
 * `max_iterations`  stores the maximal iteration number where to stop at
-* `at_iteration` indicates at which iteration (including `i=0`) the stopping criterion
-  was fulfilled and is `-1` while it is not fulfilled.
 
 # Constructor
 
     StopAfterIteration(maxIter)
 
 initialize the functor to indicate to stop after `maxIter` iterations.
 """
-mutable struct StopAfterIteration <: StoppingCriterion
-    max_iterations::Int
+struct StopAfterIteration <: StoppingCriterion
+     max_iterations::Int
+end
+
+"""
+DefaultStoppingCriterionState <: StoppingCriterionState
+
+A [`StoppingCriterionState`](@ref) 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.
+"""
+mutable struct DefaultStoppingCriterionState
     at_iteration::Int
-    StopAfterIteration(k::Int) = new(k, -1)
+    DefaultStoppingCriterionState() = new(-1)
+end
+
+initialize(::Problem, ::Algorithm, ::State, ::StopAfterIteration) = DefaultStoppingCriterionState()
+function initialize!(scs::DefaultStoppingCriterionState, ::Problem, ::Algorithm, ::State, ::StopAfterIteration)
+    scs.indicated_convergence_at = -1
+    return scs
 end
-function (sc::StopAfterIteration)(::Problem, ::Algorithm, s::State)
+
+function (sc::DefaultStoppingCriterionState)(::Problem, ::Algorithm, s::State, sc::StopAfterIteration)
     k = get_iteration(s)
-    if k == 0 # reset on init
-        sc.at_iteration = -1
-    end
+    (k == 0) && (sc.at_iteration = -1)
     if k >= sc.max_iterations
         sc.at_iteration = k
         return true
     end
     return false
 end
-function get_reason(c::StopAfterIteration)
+function get_reason(c::StopAfterIteration, scs::DefaultStoppingCriterionState)
     if c.at_iteration >= c.max_iterations
         return "At iteration $(c.at_iteration) the algorithm reached its maximal number of iterations ($(c.max_iterations)).\n"
     end