# Solver state

Given an `AbstractManoptProblem`

, that is a certain optimisation task, the state specifies the solver to use. It contains the parameters of a solver and all fields necessary during the algorithm, for example the current iterate, a `StoppingCriterion`

or a `Stepsize`

.

`Manopt.AbstractManoptSolverState`

— Type`AbstractManoptSolverState`

A general super type for all solver states.

**Fields**

The following fields are assumed to be default. If you use different ones, adapt the the access functions `get_iterate`

and `get_stopping_criterion`

accordingly

`p::P`

: a point on the manifold $\mathcal M$storing the current iterate`stop::StoppingCriterion`

: a functor indicating that the stopping criterion is fulfilled

`Manopt.get_state`

— Function`get_state(s::AbstractManoptSolverState, recursive::Bool=true)`

return the (one step) undecorated `AbstractManoptSolverState`

of the (possibly) decorated `s`

. As long as your decorated state stores the state within `s.state`

and the `dispatch_objective_decorator`

is set to `Val{true}`

, the internal state are extracted automatically.

By default the state that is stored within a decorated state is assumed to be at `s.state`

. Overwrite `_get_state(s, ::Val{true}, recursive) to change this behaviour for your state`

s` for both the recursive and the direct case.

If `recursive`

is set to `false`

, only the most outer decorator is taken away instead of all.

`Manopt.get_count`

— Function`get_count(ams::AbstractManoptSolverState, ::Symbol)`

Obtain the count for a certain countable size, for example the `:Iterations`

. This function returns 0 if there was nothing to count

Available symbols from within the solver state

`:Iterations`

is passed on to the`stop`

field to obtain the iteration at which the solver stopped.

`get_count(co::ManifoldCountObjective, s::Symbol, mode::Symbol=:None)`

Get the number of counts for a certain symbol `s`

.

Depending on the `mode`

different results appear if the symbol does not exist in the dictionary

`:None`

: (default) silent mode, returns`-1`

for non-existing entries`:warn`

: issues a warning if a field does not exist`:error`

: issues an error if a field does not exist

Since every subtype of an `AbstractManoptSolverState`

directly relate to a solver, the concrete states are documented together with the corresponding solvers. This page documents the general features available for every state.

A first example is to obtain or set, the current iterate. This might be useful to continue investigation at the current iterate, or to set up a solver for a next experiment, respectively.

`Manopt.get_iterate`

— Function`get_iterate(O::AbstractManoptSolverState)`

return the (last stored) iterate within `AbstractManoptSolverState`

`s`. This should usually refer to a single point on the manifold the solver is working on`

By default this also removes all decorators of the state beforehand.

`get_iterate(agst::AbstractGradientSolverState)`

return the iterate stored within gradient options. THe default returns `agst.p`

.

`Manopt.set_iterate!`

— Function`set_iterate!(s::AbstractManoptSolverState, M::AbstractManifold, p)`

set the iterate within an `AbstractManoptSolverState`

to some (start) value `p`

.

`set_iterate!(agst::AbstractGradientSolverState, M, p)`

set the (current) iterate stored within an `AbstractGradientSolverState`

to `p`

. The default function modifies `s.p`

.

`Manopt.get_gradient`

— Method`get_gradient(s::AbstractManoptSolverState)`

return the (last stored) gradient within `AbstractManoptSolverState`

`s`. By default also undecorates the state beforehand`

`Manopt.set_gradient!`

— Function`set_gradient!(s::AbstractManoptSolverState, M::AbstractManifold, p, X)`

set the gradient within an (possibly decorated) `AbstractManoptSolverState`

to some (start) value `X`

in the tangent space at `p`

.

`set_gradient!(agst::AbstractGradientSolverState, M, p, X)`

set the (current) gradient stored within an `AbstractGradientSolverState`

to `X`

. The default function modifies `s.X`

.

An internal function working on the state and elements within a state is used to pass messages from (sub) activities of a state to the corresponding `DebugMessages`

`Manopt.get_message`

— Function`get_message(du::AbstractManoptSolverState)`

get a message (String) from internal functors, in a summary. This should return any message a sub-step might have issued as well.

Furthermore, to access the stopping criterion use

`Manopt.get_stopping_criterion`

— Function`get_stopping_criterion(ams::AbstractManoptSolverState)`

Return the `StoppingCriterion`

stored within the `AbstractManoptSolverState`

`ams`

.

For an undecorated state, this is assumed to be in `ams.stop`

. Overwrite `_get_stopping_criterion(yms::YMS)`

to change this for your manopt solver (`yms`

) assuming it has type YMS`.

## Decorators for `AbstractManoptSolverState`

s

A solver state can be decorated using the following trait and function to initialize

`Manopt.dispatch_state_decorator`

— Function`dispatch_state_decorator(s::AbstractManoptSolverState)`

Indicate internally, whether an `AbstractManoptSolverState`

`s`

is of decorating type, and stores (encapsulates) a state in itself, by default in the field `s.state`

.

Decorators indicate this by returning `Val{true}`

for further dispatch.

The default is `Val{false}`

, so by default a state is not decorated.

`Manopt.is_state_decorator`

— Function`is_state_decorator(s::AbstractManoptSolverState)`

Indicate, whether `AbstractManoptSolverState`

`s`

are of decorator type.

`Manopt.decorate_state!`

— Function`decorate_state!(s::AbstractManoptSolverState)`

decorate the `AbstractManoptSolverState`

`s`

with specific decorators.

**Optional arguments**

optional arguments provide necessary details on the decorators.

`debug=Array{Union{Symbol,DebugAction,String,Int},1}()`

: a set of symbols representing`DebugAction`

s,`Strings`

used as dividers and a sub-sampling integer. These are passed as a`DebugGroup`

within`:Iteration`

to the`DebugSolverState`

decorator dictionary. Only exception is`:Stop`

that is passed to`:Stop`

.`record=Array{Union{Symbol,RecordAction,Int},1}()`

: specify recordings by using`Symbol`

s or`RecordAction`

s directly. An integer can again be used for only recording every $i$th iteration.`return_state=false`

: indicate whether to wrap the options in a`ReturnSolverState`

, indicating that the solver should return options and not (only) the minimizer.

other keywords are ignored.

**See also**

A simple example is the

`Manopt.ReturnSolverState`

— Type`ReturnSolverState{O<:AbstractManoptSolverState} <: AbstractManoptSolverState`

This internal type is used to indicate that the contained `AbstractManoptSolverState`

`state`

should be returned at the end of a solver instead of the usual minimizer.

**See also**

as well as `DebugSolverState`

and `RecordSolverState`

.

## State actions

A state action is a struct for callback functions that can be attached within for example the just mentioned debug decorator or the record decorator.

`Manopt.AbstractStateAction`

— Type`AbstractStateAction`

a common `Type`

for `AbstractStateActions`

that might be triggered in decorators, for example within the `DebugSolverState`

or within the `RecordSolverState`

.

Several state decorators or actions might store intermediate values like the (last) iterate to compute some change or the last gradient. In order to minimise the storage of these, there is a generic `StoreStateAction`

that acts as generic common storage that can be shared among different actions.

`Manopt.StoreStateAction`

— Type`StoreStateAction <: AbstractStateAction`

internal storage for `AbstractStateAction`

s to store a tuple of fields from an `AbstractManoptSolverState`

s

This functor possesses the usual interface of functions called during an iteration and acts on `(p, s, k)`

, where `p`

is a `AbstractManoptProblem`

, `s`

is an `AbstractManoptSolverState`

and `k`

is the current iteration.

**Fields**

`values`

: a dictionary to store interim values based on certain`Symbols`

`keys`

: a`Vector`

of`Symbols`

to refer to fields of`AbstractManoptSolverState`

`point_values`

: a`NamedTuple`

of mutable values of points on a manifold to be stored in`StoreStateAction`

. Manifold is later determined by`AbstractManoptProblem`

passed to`update_storage!`

.`point_init`

: a`NamedTuple`

of boolean values indicating whether a point in`point_values`

with matching key has been already initialized to a value. When it is false, it corresponds to a general value not being stored for the key present in the vector`keys`

.`vector_values`

: a`NamedTuple`

of mutable values of tangent vectors on a manifold to be stored in`StoreStateAction`

. Manifold is later determined by`AbstractManoptProblem`

passed to`update_storage!`

. It is not specified at which point the vectors are tangent but for storage it should not matter.`vector_init`

: a`NamedTuple`

of boolean values indicating whether a tangent vector in`vector_values`

: with matching key has been already initialized to a value. When it is false, it corresponds to a general value not being stored for the key present in the vector`keys`

.`once`

: whether to update the internal values only once per iteration`lastStored`

: last iterate, where this`AbstractStateAction`

was called (to determine`once`

)

To handle the general storage, use `get_storage`

and `has_storage`

with keys as `Symbol`

s. For the point storage use `PointStorageKey`

. For tangent vector storage use `VectorStorageKey`

. Point and tangent storage have been optimized to be more efficient.

**Constructors**

StoreStateAction(s::Vector{Symbol})

This is equivalent as providing `s`

to the keyword `store_fields`

, just that here, no manifold is necessity for the construction.

`StoreStateAction(M)`

**Keyword arguments**

`store_fields`

(`Symbol[]`

)`store_points`

(`Symbol[]`

)`store_vectors`

(`Symbol[]`

)

as vectors of symbols each referring to fields of the state (lower case symbols) or semantic ones (upper case).

`p_init`

(`rand(M)`

) but making sure this is not a number but a (mutatable) array`X_init`

(`zero_vector(M, p_init)`

)

are used to initialize the point and vector storage, change these if you use other types (than the default) for your points/vectors on `M`

.

`once`

(`true`

) whether to update internal storage only once per iteration or on every update call

`Manopt.get_storage`

— Function`get_storage(a::AbstractStateAction, key::Symbol)`

Return the internal value of the `AbstractStateAction`

`a`

at the `Symbol`

`key`

.

`get_storage(a::AbstractStateAction, ::PointStorageKey{key}) where {key}`

Return the internal value of the `AbstractStateAction`

`a`

at the `Symbol`

`key`

that represents a point.

`get_storage(a::AbstractStateAction, ::VectorStorageKey{key}) where {key}`

Return the internal value of the `AbstractStateAction`

`a`

at the `Symbol`

`key`

that represents a vector.

`Manopt.has_storage`

— Function`has_storage(a::AbstractStateAction, key::Symbol)`

Return whether the `AbstractStateAction`

`a`

has a value stored at the `Symbol`

`key`

.

`has_storage(a::AbstractStateAction, ::PointStorageKey{key}) where {key}`

Return whether the `AbstractStateAction`

`a`

has a point value stored at the `Symbol`

`key`

.

`has_storage(a::AbstractStateAction, ::VectorStorageKey{key}) where {key}`

Return whether the `AbstractStateAction`

`a`

has a point value stored at the `Symbol`

`key`

.

`Manopt.update_storage!`

— Function`update_storage!(a::AbstractStateAction, amp::AbstractManoptProblem, s::AbstractManoptSolverState)`

Update the `AbstractStateAction`

`a`

internal values to the ones given on the `AbstractManoptSolverState`

`s`

. Optimized using the information from `amp`

`update_storage!(a::AbstractStateAction, d::Dict{Symbol,<:Any})`

Update the `AbstractStateAction`

`a`

internal values to the ones given in the dictionary `d`

. The values are merged, where the values from `d`

are preferred.

`Manopt.PointStorageKey`

— Type`struct PointStorageKey{key} end`

Refer to point storage of `StoreStateAction`

in `get_storage`

and `has_storage`

functions

`Manopt.VectorStorageKey`

— Type`struct VectorStorageKey{key} end`

Refer to tangent storage of `StoreStateAction`

in `get_storage`

and `has_storage`

functions

as well as two internal functions

`Manopt._storage_copy_vector`

— Function`_storage_copy_vector(M::AbstractManifold, X)`

Make a copy of tangent vector `X`

from manifold `M`

for storage in `StoreStateAction`

.

`Manopt._storage_copy_point`

— Function`_storage_copy_point(M::AbstractManifold, p)`

Make a copy of point `p`

from manifold `M`

for storage in `StoreStateAction`

.

## Abstract states

In a few cases it is useful to have a hierarchy of types. These are

`Manopt.AbstractSubProblemSolverState`

— Type`AbstractSubProblemSolverState <: AbstractManoptSolverState`

An abstract type for solvers that involve a subsolver.

`Manopt.AbstractGradientSolverState`

— Type`AbstractGradientSolverState <: AbstractManoptSolverState`

A generic `AbstractManoptSolverState`

type for gradient based options data.

It assumes that

- the iterate is stored in the field
`p`

- the gradient at
`p`

is stored in`X`

.

**See also**

`GradientDescentState`

, `StochasticGradientDescentState`

, `SubGradientMethodState`

, `QuasiNewtonState`

.

`Manopt.AbstractHessianSolverState`

— Type`AbstractHessianSolverState <: AbstractGradientSolverState`

An `AbstractManoptSolverState`

type to represent algorithms that employ the Hessian. These options are assumed to have a field (`gradient`

) to store the current gradient $\operatorname{grad}f(x)$

`Manopt.AbstractPrimalDualSolverState`

— Type`AbstractPrimalDualSolverState`

A general type for all primal dual based options to be used within primal dual based algorithms

For the sub problem state, there are two access functions

`Manopt.get_sub_problem`

— Function`get_sub_problem(ams::AbstractSubProblemSolverState)`

Access the sub problem of a solver state that involves a sub optimisation task. By default this returns `ams.sub_problem`

.

`Manopt.get_sub_state`

— Function`get_sub_state(ams::AbstractSubProblemSolverState)`

Access the sub state of a solver state that involves a sub optimisation task. By default this returns `ams.sub_state`

.