Solver state

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

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

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

get_iterate(O::AbstractManoptSolverState)

return the (last stored) iterate within AbstractManoptSolverStates`. 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.

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.

get_gradient(s::AbstractManoptSolverState)

return the (last stored) gradient within AbstractManoptSolverStates`. By default also undecorates the state beforehand

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.

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.

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

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.

is_state_decorator(s::AbstractManoptSolverState)

Indicate, whether AbstractManoptSolverState s are of decorator type.

decorate_state!(s::AbstractManoptSolverState)

decorate the AbstractManoptSolverStates with specific decorators.

Optional arguments

optional arguments provide necessary details on the decorators.

• callback=missing add an arbitrary (simple) callback function cb() to be called every iteration.
• debug=Array{Union{Symbol,DebugAction,String,Int, Function},1}(): a set of symbols representing DebugActions, Strings used as dividers and a sub-sampling integer. These are passed as a DebugGroup within :Iteration to the DebugSolverState decorator dictionary. A function is added as a (non-simple) callback within a DebugCallback. Only exception is :Stop that is passed to :Stop.
• record=Array{Union{Symbol,RecordAction,Int},1}(): specify recordings by using Symbols or RecordActions 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

DebugSolverState, RecordSolverState, ReturnSolverState

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

get_solver_result

AbstractStateAction

a common Type for AbstractStateActions that might be triggered in decorators, for example within the DebugSolverState or within the RecordSolverState.

StoreStateAction <: AbstractStateAction

internal storage for AbstractStateActions to store a tuple of fields from an AbstractManoptSolverStates

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 Symbols. 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

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.

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.

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.

struct PointStorageKey{key} end

Refer to point storage of StoreStateAction in get_storage and has_storage functions

struct VectorStorageKey{key} end

Refer to tangent storage of StoreStateAction in get_storage and has_storage functions

_storage_copy_vector(M::AbstractManifold, X)

Make a copy of tangent vector X from manifold M for storage in StoreStateAction.

_storage_copy_point(M::AbstractManifold, p)

Make a copy of point p from manifold M for storage in StoreStateAction.

AbstractSubProblemSolverState <: AbstractManoptSolverState

An abstract type for solvers that involve a subsolver.

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.

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)$

AbstractPrimalDualSolverState

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

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.

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.