Towards the first plain interface.

Author: kellertuer

docs/make.jl

@@ -40,7 +40,12 @@ makedocs(;
     modules = [AlgorithmsInterface],
     authors = "Ronny Bergmann, Lukas Devos, and contributors.",
     sitename = "AlgorithmsInterface.jl",
-    pages = ["Home" => "index.md", "References" => "references.md"],
+    pages = [
+        "Home" => "index.md",
+        "Interface" => "interface.md",
+        "Stopping criteria" => "stopping_criterion.md",
+        "References" => "references.md",
+    ],
     plugins = [bib, links],
 )
 deploydocs(;

docs/src/index.md

@@ -1,9 +1,11 @@
-# IterativeAlgorithms.jl
+# AlgorithmsInterface.jl
+
+Welcome to the Documentation of `LieGAlgorithmsInterface.jl`.
+
+```@meta
+CurrentModule = AlgorithmsInterface
+```
 
 ```@docs
-Algorithm
-Problem
-State
-step!
-get_iteration
+AlgorithmsInterface.AlgorithmsInterface
 ```

docs/src/interface.md

@@ -0,0 +1,35 @@
+# Main Interface types
+
+```@autodocs
+Modules = [AlgorithmsInterface]
+Pages = ["interface/interface.jl"]
+Order = [:type, :function]
+Private = true
+```
+
+## Algorithm
+
+```@autodocs
+Modules = [AlgorithmsInterface]
+Pages = ["interface/algorithm.jl"]
+Order = [:type, :function]
+Private = true
+```
+
+## Problem
+
+```@autodocs
+Modules = [AlgorithmsInterface]
+Pages = ["interface/problem.jl"]
+Order = [:type, :function]
+Private = true
+```
+
+## State
+
+```@autodocs
+Modules = [AlgorithmsInterface]
+Pages = ["interface/state.jl"]
+Order = [:type, :function]
+Private = true
+```

docs/src/stopping_criterion.md

@@ -0,0 +1,8 @@
+# Stopping criterion
+
+```@autodocs
+Modules = [AlgorithmsInterface]
+Pages = ["stopping_criterion.jl"]
+Order = [:type, :function]
+Private = true
+```

src/AlgorithmsInterface.jl

@@ -1,3 +1,11 @@
+@doc raw"""
+🏔️ AlgorithmsInterface.jl: an interface for iterative algorithms in Julia
+
+* 📚 Documentation: [juliamanifolds.github.io/AlgorithmsInterface.jl/](https://juliamanifolds.github.io/AlgorithmsInterface.jl/)
+* 📦 Repository: [github.com/JuliaManifolds/AlgorithmsInterface.jl](https://github.com/JuliaManifolds/AlgorithmsInterface.jl)
+* 💬 Discussions: [github.com/JuliaManifolds/AlgorithmsInterface.jl/discussions](https://github.com/JuliaManifolds/AlgorithmsInterface.jl/discussions)
+* 🎯 Issues: [github.com/JuliaManifolds/AlgorithmsInterface.jl/issues](https://github.com/JuliaManifolds/AlgorithmsInterface.jl/issues)
+"""
 module AlgorithmsInterface
 
 using Dates: Millisecond, Nanosecond, Period, canonicalize, value
@@ -10,7 +18,11 @@ include("interface/interface.jl")
 include("stopping_criterion.jl")
 
 export Algorithm, Problem, State
+export StoppingCriterion
+export StopAfter, StopAfterIteration
+export is_finished
+export initialize_state, initialize_state!, is_finished
 export get_iteration
-export step!
+export step!, solve, solve!
 
 end # module AlgorithmsInterface

src/interface/interface.jl

@@ -1,12 +1,31 @@
-function step! end
-@doc """
-    step!(p::Problem, a::Algorithm, s::State)
+_doc_init_state = """
+    s = initialize_state(p::Problem, a::Algorithm; kwargs...)
+    initialize_state!(p::Problem, a::Algorithm, s::State; kwargs...)
 
-Perform the current step of an [`Algorithm`](@ref) `a` solving [`Problem`](@ref) `p`
-starting from [`State`](@ref) `s`.
+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.
+This can be done in-place of `s`, then only values that did change have to be provided.
 """
-step!(p::Problem, a::Algorithm, s::State)
 
+function initialize_state end
+
+@doc "$(_doc_init_state)"
+initialize_state(::Problem, ::Algorithm; kwargs...)
+
+function initialize_state! end
+
+@doc "$(_doc_init_state)"
+initialize_state!(::State, ::Problem, ::Algorithm; kwargs...)
+
+@doc """
+    is_finished(p::Problem, a::Algorithm, s::State)
+"""
+function is_finished(p::Problem, a::Algorithm, s::State)
+    sc = get_stopping_criterion(s)
+    return sc(p, a, s)
+end
+
+# has to be defined before used in solve but is documented alphabetically after
 
 @doc """
     solve(p::Problem, a::Algorithm; kwargs...)
@@ -19,14 +38,31 @@ returns a state.
 By default this method continues to call [`solve!`](@ref).
 """
 function solve(p::Problem, a::Algorithm; kwargs...)
-    s = initialize_state(p, a)
-    return solve!(p, a, s)
+    s = initialize_state(p, a; kwargs...)
+    return solve!(p, a, s; kwargs...)
 end
 
 @doc """
-    solve!(p::Problem, a::Algorithm, s::State)
+    solve!(p::Problem, a::Algorithm, s::State; kwargs...)
 
 Solve the [`Problem`](@ref) `p` using the [`Algorithm`](@ref) `a`
 working on the [`State`](@ref).
+
+All keyword arguments are passed to the [`initialize_state!`](@ref) function.
+"""
+function solve!(p::Problem, a::Algorithm, s::State; kwargs...)
+    initialize_state!(p, a, s; kwargs...)
+    while !is_finished(p, a, s)
+        increment!(s)
+        step!(p, a, s)
+    end
+end
+
+function step! end
+@doc """
+    step!(p::Problem, a::Algorithm, s::State)
+
+Perform the current step of an [`Algorithm`](@ref) `a` solving [`Problem`](@ref) `p`
+starting from [`State`](@ref) `s`.
 """
-solve!(p::Problem, a::Algorithm, s::State)
+step!(p::Problem, a::Algorithm, s::State)

src/interface/state.jl

@@ -16,24 +16,51 @@ Usually this should include
 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
+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_iterate`](@ref) return the current iterate ``x^{(k)}``.
 """
 abstract type State end
 
+"""
+    get_iterate(s::State)
+
+Return the current iterate ``x^{(k)}`` of a [`State`](@ref) `s`
+
+The default assumes that the current iteration is stored in `s.iterate`.
+"""
+get_iterate(s::State) = s.iterate
+
 """
     get_iteration(s::State)
 
-Return the current iteration a state either is currently performing or was last performed
+Return the current iteration a [`State`](@ref) `s` either is currently performing or was last performed
 
 The default assumes that the current iteration is stored in `s.iteration`.
 """
 get_iteration(s::State) = s.iteration
 
-function initialize_state end
-@doc """
-    initialize_state(p::Problem, a::Algorithm, kwargs...)
+"""
+    increment!(s::State)
+
+Return the current iteration a [`State`](@ref) `s` either is currently performing or was last performed
+
+The default assumes that the current iteration is stored in `s.iteration`.
+"""
+function increment!(s::State)
+    s.iteration += 1
+    return s
+end
+
+"""
+    get_stopping_criterion(s::State)
+
+Return the [`StoppingCriterion`](@ref) of the [`State`](@ref) `s`.
 
-Initialise a [`State`](@ref) `s` for a [`Problem`](@ref) `p` and an [`Algorithm`](@ref) `a`,
-where the keyword arguments should both uniquely identify the state and provide enough
-information to call its constructor.
+The default assumes that the criterion is stored in `s.stopping_criterion`.
 """
-initialize_state(::Problem, ::Algorithm, kwargs...)
+get_stopping_criterion(s::State) = s.stopping_criterion

src/stopping_criterion.jl

@@ -4,10 +4,12 @@
 An abstract type to represent a stopping criterion of an solver.
 
 Any concrete stopping criterion should be implemented as a functor,
-that takes the “usual tuple” `(p, a, s)` of a [`Problem`](@ref),
-an [`algorithm`](@ref) and a [`State`](@ref) as input
+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` `sc` should provide the following functions
 besides the above-mentioned functor is it itself
 
@@ -57,7 +59,7 @@ For the [`StopAfterIteration`](@ref) criterion, the summary looks like
 Max Iterations (15): not reached
 ```
 """
-get_summary(sc::StopAfterIteration)
+get_summary(sc::StoppingCriterion)
 
 @doc raw"""
     StopAfterIteration <: StoppingCriterion