Refactor interface to have problem, algorithm, state

Author: lkdvos

src/interface/interface.jl

@@ -1,10 +1,10 @@
 _doc_init_state = """
-    s = initialize_state(p::Problem, a::Algorithm; kwargs...)
-    initialize_state!(s::State, p::Problem, a::Algorithm; kwargs...)
+    state = initialize_state(problem::Problem, algorithm::Algorithm; kwargs...)
+    state = initialize_state!(state::State, problem::Problem, algorithm::Algorithm; kwargs...)
 
-Initialize a [`State`](@ref) `s` base on a [`Problem`](@ref) `p` and an [`Algorithm`](@ref).
+Initialize a [`State`](@ref) based on a [`Problem`](@ref) 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.
+This can be done in-place for `state`, then only values that did change have to be provided.
 """
 
 function initialize_state end
@@ -15,59 +15,58 @@ initialize_state(::Problem, ::Algorithm; kwargs...)
 function initialize_state! end
 
 @doc "$(_doc_init_state)"
-initialize_state!(::State, ::Problem, ::Algorithm; kwargs...)
+initialize_state!(::Problem, ::Algorithm, ::State; kwargs...)
 
 @doc """
-    is_finished(p::Problem, a::Algorithm, s::State)
+    is_finished(problem::Problem, algorithm::Algorithm, state::State) -> Bool
 
-Return `true` if the [`Algorithm`](@ref) `a` solving the [`Problem`](@ref) `p`
-with current [`State`](@ref) `s` is finished
+Return `true` if the [`Algorithm`](@ref) solving the [`Problem`](@ref) at the current [`State`](@ref) is finished.
 """
-function is_finished(p::Problem, a::Algorithm, s::State)
-    scs = get_stopping_criterion_state(s)
-    sc = get_stopping_criterion(a)
-    return scs(p, a, s, sc)
+function is_finished(problem::Problem, algorithm::Algorithm, state::State)
+    scs = get_stopping_criterion_state(state)
+    sc = get_stopping_criterion(algorithm)
+    return scs(problem, algorithm, state, sc)
 end
 
 # has to be defined before used in solve but is documented alphabetically after
 
 @doc """
-    solve(p::Problem, a::Algorithm; kwargs...)
+    solve(problem::Problem, algorithm::Algorithm; kwargs...)
 
-Solve the [`Problem`](@ref) `p` using the [`Algorithm`](@ref) `a`.
+Solve the [`Problem`](@ref) using an [`Algorithm`](@ref).
 The keyword arguments `kwargs...` have to provide enough details such that
-the corresponding state initialisation [`initialize_state`](@ref)`(p,a)`
+the corresponding state initialisation [`initialize_state`](@ref)`(problem, algorithm)`
 returns a state.
 
 By default this method continues to call [`solve!`](@ref).
 """
-function solve(p::Problem, a::Algorithm; kwargs...)
-    s = initialize_state(p, a; kwargs...)
-    return solve!(s, p, a; kwargs...)
+function solve(problem::Problem, algorithm::Algorithm; kwargs...)
+    state = initialize_state(problem, algorithm; kwargs...)
+    return solve!(state, problem, algorithm; kwargs...)
 end
 
 @doc """
-    solve!(p::Problem, a::Algorithm, s::State; kwargs...)
+    solve!(problem::Problem, algorithm::Algorithm, state::State; kwargs...)
 
-Solve the [`Problem`](@ref) `p` using the [`Algorithm`](@ref) `a`
-modifying on the [`State`](@ref).
+Solve the [`Problem`](@ref) using an [`Algorithm`](@ref), starting from a given [`State`](@ref).
+The state is modified in-place.
 
-All keyword arguments are passed to the [`initialize_state!`](@ref)`(s, p, a)` function.
+All keyword arguments are passed to the [`initialize_state!`](@ref)`(problem, algorithm, state)` function.
 """
-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)
+function solve!(problem::Problem, algorithm::Algorithm, state::State; kwargs...)
+    initialize_state!(problem, algorithm, state; kwargs...)
+    while !is_finished(problem, algorithm, state)
+        increment!(state)
+        step!(problem, algorithm, state)
     end
-    return s
+    return state
 end
 
 function step! end
 @doc """
-    step!(s::State, p::Problem, a::Algorithm)
+    step!(problem::Problem, algorithm::Algorithm, state::State)
 
-Perform the current step of an [`Algorithm`](@ref) `a` solving [`Problem`](@ref) `p`
-modifying the algorithms [`State`](@ref) `s`.
+Perform the current step of an [`Algorithm`](@ref) solving a [`Problem`](@ref)
+modifying the algorithm's [`State`](@ref).
 """
-step!(s::State, p::Problem, a::Algorithm)
+step!(problem::Problem, algorithm::Algorithm, state::State)