default output state.iterate

Author: lkdvos

docs/src/interface.md

@@ -128,13 +128,14 @@ With these definitions in place you can already run (assuming you also choose a
 function heron_sqrt(x; maxiter = 10)
     prob = SqrtProblem(x)
     alg  = HeronAlgorithm(StopAfterIteration(maxiter))
-    state = solve(prob, alg)  # allocates & runs
-    return state.iterate
+    return solve(prob, alg)  # allocates & runs
 end
 
 println("Approximate sqrt: ", heron_sqrt(16.0))
 ```
 
+Note that [`solve`](@ref) will default to returning `state.iterate`.
+If desired, this can be customized by altering [`finalize_state!`](@ref).
 We will refine this example with better halting logic and logging shortly.
 
 ## Reference: Core interface types & functions

docs/src/logging.md

@@ -75,8 +75,7 @@ end
 function heron_sqrt(x; stopping_criterion = StopAfterIteration(10))
     prob = SqrtProblem(x)
     alg  = HeronAlgorithm(stopping_criterion)
-    state = solve(prob, alg)  # allocates & runs
-    return state.iterate
+    return solve(prob, alg)  # allocates & runs
 end
 nothing # hide
 ```
@@ -329,7 +328,7 @@ function solve!(problem::Problem, algorithm::Algorithm, state::State; kwargs...)
 
     emit_message(problem, algorithm, state, :Stop)
 
-    return state
+    return finalize_state!(problem, algorithm, state)
 end
 ```
 

docs/src/stopping_criterion.md

@@ -112,8 +112,7 @@ We can again combine everything into a single function, but now make the stoppin
 function heron_sqrt(x; stopping_criterion)
     prob = SqrtProblem(x)
     alg  = HeronAlgorithm(stopping_criterion)
-    state = solve(prob, alg)  # allocates & runs
-    return state.iterate, state.iteration
+    return solve(prob, alg)  # allocates & runs
 end
 
 heron_sqrt(2; stopping_criterion = StopAfterIteration(10))

src/interface/interface.jl

@@ -22,10 +22,10 @@ initialize_state!(::Problem, ::Algorithm, ::State; kwargs...)
     output = finalize_state!(problem::Problem, algorithm::Algorithm, state::State)
 
 Finalize the solver and decide what values get returned from the [`solve!`](@ref) call.
-By default, this is a no-op and returns the `state`, but this allows for customization
-in cases where the details of the `state` can remain hidden.
+By default, this is a no-op and returns the `state.iterate`, but this allows for further
+customization in other cases, for example to clean up used resources or output other data.
 """
-finalize_state!(problem::Problem, algorithm::Algorithm, state::State) = state
+finalize_state!(problem::Problem, algorithm::Algorithm, state::State) = state.iterate
 
 # has to be defined before used in solve but is documented alphabetically after
 

test/newton.jl

@@ -60,9 +60,9 @@ end
     problem = RootFindingProblem(x -> f(x, a), x -> df(x, a))
     algorithm1 = NewtonMethod(StopAfterIteration(8))
     solution1 = solve(problem, algorithm1)
-    @test solution1.iterate ≈ sqrt(a)
+    @test solution1 ≈ sqrt(a)
     algorithm2 = NewtonMethod(StopAfterIteration(10))
     solution2 = solve(problem, algorithm2)
-    @test solution2.iterate ≈ sqrt(a)
-    @test abs(solution2.iterate - sqrt(a)) < abs(solution1.iterate - sqrt(a))
+    @test solution2 ≈ sqrt(a)
+    @test abs(solution2 - sqrt(a)) < abs(solution1 - sqrt(a))
 end