# The 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, e.g. 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, provide the access functions accordingly

`p`

a point on a manifold with the current iterate`stop`

a`StoppingCriterion`

.

`Manopt.get_state`

— Function`get_state(s::AbstractManoptSolverState)`

return the undecorated `AbstractManoptSolverState`

of the (possibly) decorated `s`

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

and the `dispatch_state_decorator`

is set to `Val{true}`

, the internal state are extracted.

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 functionality available for every state.

A first example is to access, i.e. 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`. By default also undecorates the state beforehand.`

`get_iterate(agst::AbstractGradientSolverState)`

return the iterate stored within gradient options. THe default resturns `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(M::AbstractManifold, sgo::ManifoldStochasticGradientObjective, p, k)
get_gradient!(M::AbstractManifold, sgo::ManifoldStochasticGradientObjective, Y, p, k)
```

Evaluate one of the summands gradients $\operatorname{grad}f_k$, $k∈\{1,…,n\}$, at `x`

(in place of `Y`

).

If you use a single function for the stochastic gradient, that works inplace, then `get_gradient`

is not available, since the length (or number of elements of the gradient required for allocation) can not be determined.

```
get_gradient(M::AbstractManifold, sgo::ManifoldStochasticGradientObjective, p)
get_gradient!(M::AbstractManifold, sgo::ManifoldStochasticGradientObjective, X, p)
```

Evaluate the complete gradient $\operatorname{grad} f = \displaystyle\sum_{i=1}^n \operatorname{grad} f_i(p)$ at `p`

(in place of `X`

).

If you use a single function for the stochastic gradient, that works inplace, then `get_gradient`

is not available, since the length (or number of elements of the gradient required for allocation) can not be determined.

```
X = get_gradient(M::AbstractManifold, p::ManifoldAlternatingGradientObjective, p, k)
get_gradient!(M::AbstractManifold, p::ManifoldAlternatingGradientObjective, X, p, k)
```

Evaluate one of the component gradients $\operatorname{grad}f_k$, $k∈\{1,…,n\}$, at `x`

(in place of `Y`

).

`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`

.

## Decorators for AbstractManoptSolverState

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`

to be of decorating type, i.e. it stores (encapsulates) 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}`

, i.e. by default an 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. A specific one is used to activate certain decorators.

`debug`

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

) a set of symbols representing`DebugAction`

s,`Strings`

used as dividers and a subsampling integer. These are passed as a`DebugGroup`

within`:All`

to the`DebugSolverState`

decorator dictionary. Only excention is`:Stop`

that is passed to`:Stop`

.`record`

– (`Array{Union{Symbol,RecordAction,Int},1}()`

) specify recordings by using`Symbol`

s or`RecordAction`

s directly. The 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 decoraters, 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 posesses the usual interface of functions called during an iteration, i.e. acts on `(p,o,i)`

, where `p`

is a `AbstractManoptProblem`

, `o`

is an `AbstractManoptSolverState`

and `i`

is the current iteration.

**Fields**

`values`

– a dictionary to store interims values based on certain`Symbols`

`keys`

– an`NTuple`

of`Symbols`

to refer to fields of`AbstractManoptSolverState`

`once`

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

– last iterate, where this`AbstractStateAction`

was called (to determine`once`

**Constructiors**

`AbstractStateAction([keys=(), once=true])`

Initialize the Functor to an (empty) set of keys, where `once`

determines whether more that one update per iteration are effective

`AbstractStateAction(keys, once=true])`

Initialize the Functor to a set of keys, where the dictionary is initialized to be empty. Further, `once`

determines whether more that one update per iteration are effective, otherwise only the first update is stored, all others are ignored.

`Manopt.get_storage`

— Function`get_storage(a,key)`

return the internal value of the `AbstractStateAction`

`a`

at the `Symbol`

`key`

.

`Manopt.has_storage`

— Function`get_storage(a,key)`

return whether the `AbstractStateAction`

`a`

has a value stored at the `Symbol`

`key`

.

`Manopt.update_storage!`

— Function`update_storage!(a, s)`

update the `AbstractStateAction`

`a`

internal values to the ones given on the `AbstractManoptSolverState`

`s`

.

`update_storage!(a, d)`

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.

## 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 problems 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