The recording and debug possiblities make it possible to record nearly any data during the iterations. This tutorial illustrates how to

• record one value during the iterations
• record multiple values during the iterations and access them afterwards
• define an own RecordAction to perform individual recordings.

Several predefined recordings exist, for example RecordCost or RecordGradient, depending on the solver used. For fields of the Options this can be directly done using the RecordEntry. For others, an own RecordAction can be defined.

We illustrate these using the gradient descent used in the introductionary Get Started: Optimize! tutorial example of computing the Riemannian Center of mass and refer to that tutorial for the mathematical details.

using Manopt, Manifolds, Random
Random.seed!(42)
m = 30
M = Sphere(m)
n = 800
σ = π / 8
x = zeros(Float64, m + 1)
x[2] = 1.0
data = [exp(M, x, random_tangent(M, x, Val(:Gaussian), σ)) for i in 1:n];
F(M, y) = sum(1 / (2 * n) * distance.(Ref(M), Ref(y), data) .^ 2)

## Plain examples

For the high level interfaces of the solvers, like gradient_descent we have to set return_options to true to obtain the whole options structure and not only the resulting resulting minimizer.

RecordOptions{GradientDescentOptions{Vector{Float64}, Vector{Float64}, StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}, ConstantStepsize, ExponentialRetraction}, NamedTuple{(:Iteration,), Tuple{RecordCost}}}(GradientDescentOptions{Vector{Float64}, Vector{Float64}, StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}, ConstantStepsize, ExponentialRetraction}([-0.019726443316661877, -0.9981026595386627, 0.01955658867659334, 0.012841365119213698, 0.006886034463205455, -0.002575547367871232, 0.008364897314973115, -0.00879174612335158, -0.026238052383071163, 0.002958797733785121  …  -0.0020583455995372394, 0.0015537606468123669, -0.0030191692672922052, -0.01633880189330779, -0.0007654986229716712, 0.01205846081682446, 0.013875198858606443, -0.013075915829476342, -0.012082061386298401, 0.0071236850703163945], IdentityUpdateRule(), StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}((StopAfterIteration(200, ""), StopWhenGradientNormLess(1.0e-8, "The algorithm reached approximately critical point after 20 iterations; the gradient norm (4.0685524938387935e-9) is less than 1.0e-8.\n")), "The algorithm reached approximately critical point after 20 iterations; the gradient norm (4.0685524938387935e-9) is less than 1.0e-8.\n"), ConstantStepsize(1.0), [-1.4276010178107336e-10, 7.451576365038196e-11, 2.2281392924011333e-11, -3.495999269698298e-10, 1.1116534720198058e-9, -6.117073198750591e-10, -3.98418127211652e-10, 2.0923500106996562e-10, -1.5131837955773605e-9, 5.265178595849004e-10  …  4.1941564560580777e-10, -3.7090792459962274e-11, -2.7207815357253515e-10, -2.5713063498615345e-9, 2.1438278940705963e-10, 5.649575485168132e-11, 7.484010481652315e-11, -9.296560752794893e-10, -1.661503171103331e-11, 2.2863057034063806e-10], ExponentialRetraction()), (Iteration = RecordCost([0.5483548369809805, 0.5381086420978917, 0.5365926945484399, 0.5363693521566143, 0.5363364424922269, 0.5363315909736714, 0.5363308754910993, 0.5363307699403789, 0.5363307543645233, 0.5363307520653806, 0.5363307517259109, 0.5363307516757745, 0.5363307516683673, 0.5363307516672731, 0.5363307516671113, 0.5363307516670872, 0.5363307516670837, 0.5363307516670831, 0.536330751667083, 0.5363307516670831]),))

You can attach different recorders to some operations (:Start. :Stop, :Iteration at time of writing), where :Iteration is the default, so the following is the same as get_record(R, :Iteration). We get

get_record(R)
20-element Vector{Float64}:
0.5483548369809805
0.5381086420978917
0.5365926945484399
0.5363693521566143
0.5363364424922269
0.5363315909736714
0.5363308754910993
0.5363307699403789
0.5363307543645233
0.5363307520653806
0.5363307517259109
0.5363307516757745
0.5363307516683673
0.5363307516672731
0.5363307516671113
0.5363307516670872
0.5363307516670837
0.5363307516670831
0.536330751667083
0.5363307516670831

To record more than one value, you can pass a array of a mix of symbols and RecordAction which gets mapped to a RecordGroup

RecordOptions{GradientDescentOptions{Vector{Float64}, Vector{Float64}, StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}, ConstantStepsize, ExponentialRetraction}, NamedTuple{(:Iteration,), Tuple{RecordGroup}}}(GradientDescentOptions{Vector{Float64}, Vector{Float64}, StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}, ConstantStepsize, ExponentialRetraction}([-0.019726443316661877, -0.9981026595386627, 0.01955658867659334, 0.012841365119213698, 0.006886034463205455, -0.002575547367871232, 0.008364897314973115, -0.00879174612335158, -0.026238052383071163, 0.002958797733785121  …  -0.0020583455995372394, 0.0015537606468123669, -0.0030191692672922052, -0.01633880189330779, -0.0007654986229716712, 0.01205846081682446, 0.013875198858606443, -0.013075915829476342, -0.012082061386298401, 0.0071236850703163945], IdentityUpdateRule(), StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}((StopAfterIteration(200, ""), StopWhenGradientNormLess(1.0e-8, "The algorithm reached approximately critical point after 20 iterations; the gradient norm (4.0685524938387935e-9) is less than 1.0e-8.\n")), "The algorithm reached approximately critical point after 20 iterations; the gradient norm (4.0685524938387935e-9) is less than 1.0e-8.\n"), ConstantStepsize(1.0), [-1.4276010178107336e-10, 7.451576365038196e-11, 2.2281392924011333e-11, -3.495999269698298e-10, 1.1116534720198058e-9, -6.117073198750591e-10, -3.98418127211652e-10, 2.0923500106996562e-10, -1.5131837955773605e-9, 5.265178595849004e-10  …  4.1941564560580777e-10, -3.7090792459962274e-11, -2.7207815357253515e-10, -2.5713063498615345e-9, 2.1438278940705963e-10, 5.649575485168132e-11, 7.484010481652315e-11, -9.296560752794893e-10, -1.661503171103331e-11, 2.2863057034063806e-10], ExponentialRetraction()), (Iteration = RecordGroup(RecordAction[RecordIteration([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]), RecordCost([0.5483548369809805, 0.5381086420978917, 0.5365926945484399, 0.5363693521566143, 0.5363364424922269, 0.5363315909736714, 0.5363308754910993, 0.5363307699403789, 0.5363307543645233, 0.5363307520653806, 0.5363307517259109, 0.5363307516757745, 0.5363307516683673, 0.5363307516672731, 0.5363307516671113, 0.5363307516670872, 0.5363307516670837, 0.5363307516670831, 0.536330751667083, 0.5363307516670831])], Dict(:Iteration => 1, :Cost => 2)),))

Here, the Symbol :Cost is mapped to using the RecordCost action. The same holds for :Iteration and :Iterate and any member field of the current Options. To access these you can first extract the group of records (of the :Iteration action) and then access the :Cost

ra = get_record_action(R)[:Cost]
20-element Vector{Float64}:
0.5483548369809805
0.5381086420978917
0.5365926945484399
0.5363693521566143
0.5363364424922269
0.5363315909736714
0.5363308754910993
0.5363307699403789
0.5363307543645233
0.5363307520653806
0.5363307517259109
0.5363307516757745
0.5363307516683673
0.5363307516672731
0.5363307516671113
0.5363307516670872
0.5363307516670837
0.5363307516670831
0.536330751667083
0.5363307516670831

Or similarly

get_record(R, :Iteration, :Cost)
20-element Vector{Float64}:
0.5483548369809805
0.5381086420978917
0.5365926945484399
0.5363693521566143
0.5363364424922269
0.5363315909736714
0.5363308754910993
0.5363307699403789
0.5363307543645233
0.5363307520653806
0.5363307517259109
0.5363307516757745
0.5363307516683673
0.5363307516672731
0.5363307516671113
0.5363307516670872
0.5363307516670837
0.5363307516670831
0.536330751667083
0.5363307516670831

Note that the first symbol again refers to the point where we record (not to the thing we record). We can also pass a Tuple as second argument to have our own order (not that now the second :Iteration refers to the recorded iteratons)

get_record(R, :Iteration, (:Cost, :Iteration))
20-element Vector{Tuple{Float64, Int64}}:
(0.5483548369809805, 1)
(0.5381086420978917, 2)
(0.5365926945484399, 3)
(0.5363693521566143, 4)
(0.5363364424922269, 5)
(0.5363315909736714, 6)
(0.5363308754910993, 7)
(0.5363307699403789, 8)
(0.5363307543645233, 9)
(0.5363307520653806, 10)
(0.5363307517259109, 11)
(0.5363307516757745, 12)
(0.5363307516683673, 13)
(0.5363307516672731, 14)
(0.5363307516671113, 15)
(0.5363307516670872, 16)
(0.5363307516670837, 17)
(0.5363307516670831, 18)
(0.536330751667083, 19)
(0.5363307516670831, 20)

## A more complex example

To illustrate a complicated example let's record

• the iteration number, cost and gradient field, but only every sixth iteration
• the iteration at which we stop

We first generate the problem and the options

M,
copy(data[1]);
)
GradientDescentOptions{Vector{Float64}, Vector{Float64}, StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}, ConstantStepsize, ExponentialRetraction}([-0.04212873279875011, -0.8635968235645907, 0.002057490434595255, -0.022691142751318387, 0.13470398350606114, -0.08674625774453522, -0.03550506791072288, 0.011830590387022107, -0.2001768943389432, 0.0760182224389436  …  0.03804127501994119, -0.016384557851231208, -0.05352395843234491, -0.32167568658089696, 0.01275478671203627, 0.021537581713645372, 0.04317445778410474, -0.10774576265218669, -0.028215860892348097, 0.027958964475994337], IdentityUpdateRule(), StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}((StopAfterIteration(200, ""), StopWhenGradientNormLess(1.0e-9, "")), #undef), ConstantStepsize(1.0), [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0  …  0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], ExponentialRetraction())

and now decorate these with RecordOptions

rI = RecordEvery(
RecordGroup([
:Iteration => RecordIteration(),
:Cost => RecordCost(),
]),
6,
)
sI = RecordIteration()
r = RecordOptions(o, Dict(:Iteration => rI, :Stop => sI))
r2 = solve(p, r)
RecordOptions{GradientDescentOptions{Vector{Float64}, Vector{Float64}, StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}, ConstantStepsize, ExponentialRetraction}, NamedTuple{(:Iteration, :Stop), Tuple{RecordEvery, RecordIteration}}}(GradientDescentOptions{Vector{Float64}, Vector{Float64}, StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}, ConstantStepsize, ExponentialRetraction}([-0.019726443242656478, -0.9981026595782577, 0.01955658865909005, 0.01284136530699147, 0.006886033870099039, -0.00257554704588227, 0.00836489752814526, -0.008791746236551944, -0.02623805157677355, 0.002958797456906779  …  -0.002058345826372028, 0.0015537606627842528, -0.0030191691278792492, -0.016338800524635495, -0.0007654987407232315, 0.012058460787588947, 0.01387519882547504, -0.013075915329928082, -0.01208206138238119, 0.007123684946969769], IdentityUpdateRule(), StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}((StopAfterIteration(200, ""), StopWhenGradientNormLess(1.0e-9, "The algorithm reached approximately critical point after 22 iterations; the gradient norm (6.023948123056778e-10) is less than 1.0e-9.\n")), "The algorithm reached approximately critical point after 22 iterations; the gradient norm (6.023948123056778e-10) is less than 1.0e-9.\n"), ConstantStepsize(1.0), [-2.0244094836728265e-11, 1.098540363357733e-11, 5.747601925106503e-12, -5.240549876375008e-11, 1.6493117738517957e-10, -8.884978602190837e-11, -5.936915363621495e-11, 3.1725402754628935e-11, -2.240500135408923e-10, 7.635936582475397e-11  …  6.356206658014382e-11, -3.849237226703772e-12, -3.787031411660487e-11, -3.800972999887242e-10, 3.326979815775066e-11, 7.990584376896953e-12, 8.15080544291219e-12, -1.3946886358209409e-10, -3.11132087975341e-13, 3.4513017986050054e-11], ExponentialRetraction()), (Iteration = RecordEvery(RecordGroup(RecordAction[RecordIteration([6, 12, 18]), RecordCost([0.5363315909736714, 0.5363307516757745, 0.5363307516670831]), RecordEntry{Vector{Float64}}([[-0.00012277887133171092, 6.114386800772579e-5, -6.0625679757341415e-5, -0.0001988315013940286, 0.0007078595202252684, -0.0004454101722301678, -0.00024232068574758792, 0.00011343500740630337, -0.0009748330015168162, 0.00038700419735796876  …  0.0002297320393751911, -7.972471678754147e-5, -0.00025298366077364617, -0.0016799111915708161, 8.923182955365044e-5, 5.0582622549721326e-5, 0.00014058020498070858, -0.000543711198660699, -7.390483116950151e-5, 0.00012657088077202086], [-3.5209885117269387e-7, 1.5848714421744543e-7, -9.167733325735587e-8, -6.846214281511882e-7, 2.3004589073232764e-6, -1.3707545247476627e-6, -8.057849142534832e-7, 3.955905940377849e-7, -3.154400677923976e-6, 1.1865536584466973e-6  …  7.964877669005568e-7, -1.7641418458913885e-7, -7.078228673053192e-7, -5.399777595418238e-6, 3.5809572045835975e-7, 1.420689832518497e-7, 3.2482377576212827e-7, -1.8356762746900822e-6, -1.532333583050341e-7, 4.386943524777346e-7], [-1.0064334253511585e-9, 5.056502510133358e-10, 3.871942350753112e-11, -2.3297372639597596e-9, 7.494677196071605e-9, -4.210291441075526e-9, -2.672989884826022e-9, 1.3798550543074974e-9, -1.0221697163863351e-8, 3.629318090525059e-9  …  2.767941284054047e-9, -3.2759809784604216e-10, -1.949569701720699e-9, -1.739925769737513e-8, 1.377586928102796e-9, 3.997302044488754e-10, 6.404886932235773e-10, -6.19695953135279e-9, -2.095272195763026e-10, 1.5140272032507056e-9]], :gradient)], Dict(:Iteration => 1, :Gradient => 3, :Cost => 2)), 6, true), Stop = RecordIteration([22])))

and we see

get_record(r2, :Stop)
1-element Vector{Int64}:
22

as well as

get_record(r2, :Iteration, (:Iteration, :Cost))
3-element Vector{Tuple{Int64, Float64}}:
(6, 0.5363315909736714)
(12, 0.5363307516757745)
(18, 0.5363307516670831)

Here it is interesting to see, that a meta-record like RecordEvery just passes the tuple further on, so we can again also do

3-element Vector{Vector{Float64}}:
[-0.00012277887133171092, 6.114386800772579e-5, -6.0625679757341415e-5, -0.0001988315013940286, 0.0007078595202252684, -0.0004454101722301678, -0.00024232068574758792, 0.00011343500740630337, -0.0009748330015168162, 0.00038700419735796876  …  0.0002297320393751911, -7.972471678754147e-5, -0.00025298366077364617, -0.0016799111915708161, 8.923182955365044e-5, 5.0582622549721326e-5, 0.00014058020498070858, -0.000543711198660699, -7.390483116950151e-5, 0.00012657088077202086]
[-3.5209885117269387e-7, 1.5848714421744543e-7, -9.167733325735587e-8, -6.846214281511882e-7, 2.3004589073232764e-6, -1.3707545247476627e-6, -8.057849142534832e-7, 3.955905940377849e-7, -3.154400677923976e-6, 1.1865536584466973e-6  …  7.964877669005568e-7, -1.7641418458913885e-7, -7.078228673053192e-7, -5.399777595418238e-6, 3.5809572045835975e-7, 1.420689832518497e-7, 3.2482377576212827e-7, -1.8356762746900822e-6, -1.532333583050341e-7, 4.386943524777346e-7]
[-1.0064334253511585e-9, 5.056502510133358e-10, 3.871942350753112e-11, -2.3297372639597596e-9, 7.494677196071605e-9, -4.210291441075526e-9, -2.672989884826022e-9, 1.3798550543074974e-9, -1.0221697163863351e-8, 3.629318090525059e-9  …  2.767941284054047e-9, -3.2759809784604216e-10, -1.949569701720699e-9, -1.739925769737513e-8, 1.377586928102796e-9, 3.997302044488754e-10, 6.404886932235773e-10, -6.19695953135279e-9, -2.095272195763026e-10, 1.5140272032507056e-9]

## Writing an own RecordActions

Let's investigate where we want to count the number of function evaluations, again just to illustrate, since for the gradient this is just one evaluation per iteration. We first define a cost, that counts it's own calls.

mutable struct MyCost{T}
data::T
count::Int
end
MyCost(data::T) where {T} = MyCost{T}(data, 0)
function (c::MyCost)(M, x)
c.count += 1
return sum(1 / (2 * length(c.data)) * distance.(Ref(M), Ref(x), c.data) .^ 2)
end

and we define the following RecordAction,

mutable struct RecordCount <: RecordAction
recorded_values::Vector{Int}
RecordCount() = new(Vector{Int}())
end
function (r::RecordCount)(p::Problem, ::Options, i)
if i > 0
push!(r.recorded_values, p.cost.count)
elseif i < 0 # reset if negative
r.recorded_values = Vector{Int}()
end
end

And now we can initialize the new cost and call the gradient descent. Note that this illustrates also the last use case – you can pass symbol-Action pairs into the record=array.

F2 = MyCost(data)
M,
F2,
data[1];
record=[:Iteration, :Count => RecordCount(), :Cost],
return_options=true,
)
RecordOptions{GradientDescentOptions{Vector{Float64}, Vector{Float64}, StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}, ConstantStepsize, ExponentialRetraction}, NamedTuple{(:Iteration,), Tuple{RecordGroup}}}(GradientDescentOptions{Vector{Float64}, Vector{Float64}, StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}, ConstantStepsize, ExponentialRetraction}([-0.019726443316661877, -0.9981026595386627, 0.01955658867659334, 0.012841365119213698, 0.006886034463205455, -0.002575547367871232, 0.008364897314973115, -0.00879174612335158, -0.026238052383071163, 0.002958797733785121  …  -0.0020583455995372394, 0.0015537606468123669, -0.0030191692672922052, -0.01633880189330779, -0.0007654986229716712, 0.01205846081682446, 0.013875198858606443, -0.013075915829476342, -0.012082061386298401, 0.0071236850703163945], IdentityUpdateRule(), StopWhenAny{Tuple{StopAfterIteration, StopWhenGradientNormLess}}((StopAfterIteration(200, ""), StopWhenGradientNormLess(1.0e-8, "The algorithm reached approximately critical point after 20 iterations; the gradient norm (4.0685524938387935e-9) is less than 1.0e-8.\n")), "The algorithm reached approximately critical point after 20 iterations; the gradient norm (4.0685524938387935e-9) is less than 1.0e-8.\n"), ConstantStepsize(1.0), [-1.4276010178107336e-10, 7.451576365038196e-11, 2.2281392924011333e-11, -3.495999269698298e-10, 1.1116534720198058e-9, -6.117073198750591e-10, -3.98418127211652e-10, 2.0923500106996562e-10, -1.5131837955773605e-9, 5.265178595849004e-10  …  4.1941564560580777e-10, -3.7090792459962274e-11, -2.7207815357253515e-10, -2.5713063498615345e-9, 2.1438278940705963e-10, 5.649575485168132e-11, 7.484010481652315e-11, -9.296560752794893e-10, -1.661503171103331e-11, 2.2863057034063806e-10], ExponentialRetraction()), (Iteration = RecordGroup(RecordAction[RecordIteration([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]), Main.ex-HowToRecord.RecordCount([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]), RecordCost([0.5483548369809805, 0.5381086420978917, 0.5365926945484399, 0.5363693521566143, 0.5363364424922269, 0.5363315909736714, 0.5363308754910993, 0.5363307699403789, 0.5363307543645233, 0.5363307520653806, 0.5363307517259109, 0.5363307516757745, 0.5363307516683673, 0.5363307516672731, 0.5363307516671113, 0.5363307516670872, 0.5363307516670837, 0.5363307516670831, 0.536330751667083, 0.5363307516670831])], Dict(:Iteration => 1, :Count => 2, :Cost => 3)),))

We can again access the whole sets of records

get_record(R)
20-element Vector{Tuple{Int64, Int64, Float64}}:
(1, 0, 0.5483548369809805)
(2, 1, 0.5381086420978917)
(3, 2, 0.5365926945484399)
(4, 3, 0.5363693521566143)
(5, 4, 0.5363364424922269)
(6, 5, 0.5363315909736714)
(7, 6, 0.5363308754910993)
(8, 7, 0.5363307699403789)
(9, 8, 0.5363307543645233)
(10, 9, 0.5363307520653806)
(11, 10, 0.5363307517259109)
(12, 11, 0.5363307516757745)
(13, 12, 0.5363307516683673)
(14, 13, 0.5363307516672731)
(15, 14, 0.5363307516671113)
(16, 15, 0.5363307516670872)
(17, 16, 0.5363307516670837)
(18, 17, 0.5363307516670831)
(19, 18, 0.536330751667083)
(20, 19, 0.5363307516670831)

this is equivalent to calling R[:Iteration. Note that since we introduced :Count we can also access a single recorded value using

R[:Iteration, :Count]
20-element Vector{Int64}:
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19