Add accessor functions

Author: tkf

docs/src/user/minimization.md

@@ -219,3 +219,22 @@ line search errors if `initial_x` is a stationary point. Notice, that this is on
 a first order check. If `initial_x` is any type of stationary point, `g_converged`
 will be true. This includes local minima, saddle points, and local maxima. If `iterations` is `0`
 and `g_converged` is `true`, the user needs to keep this point in mind.
+
+## Iterator interface
+For multivariable optimizations, iterator interface is provided through `Optim.optimizing`
+function.  Using this interface, `optimize(args...; kwargs...)` is equivalent to
+
+```jl
+let istate
+    for istate′ in Optim.optimizing(args...; kwargs...)
+        istate = istate′
+    end
+    Optim.OptimizationResults(istate)
+end
+```
+
+The iterator returned by `Optim.optimizing` yields an iterator state for each iteration
+step.
+
+Functions that can be called on the result object (e.g. `minimizer`, `iterations`; see
+[Complete list of functions](@ref)) can be used on the iteration state `istate`.

src/multivariate/optimize/optimize.jl

@@ -200,3 +200,25 @@ function optimizing(d::D, initial_x::Tx, method::M,
     end
     return OptimIterator(d, initial_x, method, options, state)
 end
+
+# Derive `IteratorState` accessors from `MultivariateOptimizationResults` accessors.
+for f in [
+    :(Base.summary)
+    :minimizer
+    :minimum
+    :iterations
+    :iteration_limit_reached
+    :trace
+    :x_trace
+    :f_trace
+    :f_calls
+    :converged
+    :g_norm_trace
+    :g_calls
+    :x_converged
+    :f_converged
+    :g_converged
+    :initial_state
+]
+    @eval $f(istate::IteratorState) = $f(OptimizationResults(istate))
+end

test/general/api.jl

@@ -146,9 +146,29 @@
     @test haskey(Optim.trace(res_extended_nm)[1].metadata,"step_type")
 
     local istate
-    for istate′ in Optim.optimizing(f, initial_x, BFGS())
+    for istate′ in Optim.optimizing(f, initial_x, BFGS(),
+                                    Optim.Options(extended_trace = true,
+                                                  store_trace = true))
         istate = istate′
+        break
     end
+    # (smoke) tests for accessor functions:
+    @test summary(istate) == "BFGS"
+    @test Optim.minimizer(istate) == initial_x
+    @test Optim.minimum(istate) == f(initial_x)
+    @test Optim.iterations(istate) == 0
+    @test Optim.iteration_limit_reached(istate) == false
+    @test Optim.trace(istate) isa Vector{<:Optim.OptimizationState}
+    @test Optim.x_trace(istate) == [initial_x]
+    @test Optim.f_trace(istate) == [f(initial_x)]
+    @test Optim.f_calls(istate) == 1
+    @test Optim.converged(istate) == false
+    @test Optim.g_norm_trace(istate) ≈ [215.6] rtol=1e-6
+    @test Optim.g_calls(istate) == 1
+    @test Optim.x_converged(istate) == false
+    @test Optim.f_converged(istate) == false
+    @test Optim.g_converged(istate) == false
+    @test Optim.initial_state(istate) == initial_x
     @test Optim.OptimizationResults(istate) isa Optim.MultivariateOptimizationResults
 end