Decorators for Objectives

AbstractDecoratedManifoldObjective{E<:AbstractEvaluationType,O<:AbstractManifoldObjective}

A common supertype for all decorators of AbstractManifoldObjectives to simplify dispatch. The second parameter should refer to the undecorated objective (the most inner one).

dispatch_objective_decorator(o::AbstractManoptSolverState)

Indicate internally, whether an AbstractManifoldObjective o to be of decorating type, it stores (encapsulates) an object in itself, by default in the field o.objective.

Decorators indicate this by returning Val{true} for further dispatch.

The default is Val{false}, so by default an state is not decorated.

is_object_decorator(s::AbstractManifoldObjective)

Indicate, whether AbstractManifoldObjective s are of decorator type.

decorate_objective!(M, o::AbstractManifoldObjective)

decorate the AbstractManifoldObjectiveo with specific decorators.

Optional arguments

optional arguments provide necessary details on the decorators. A specific one is used to activate certain decorators.

• cache=missing: specify a cache. Currently :Simple is supported and :LRU if you load LRUCache.jl. For this case a tuple specifying what to cache and how many can be provided, has to be specified. For example (:LRU, [:Cost, :Gradient], 10) states that the last 10 used cost function evaluations and gradient evaluations should be stored. See objective_cache_factory for details.
• count=missing: specify calls to the objective to be called, see ManifoldCountObjective for the full list
• objective_type=:Riemannian: specify that an objective is :Riemannian or :Euclidean. The :Euclidean symbol is equivalent to specifying it as :Embedded, since in the end, both refer to converting an objective from the embedding (whether its Euclidean or not) to the Riemannian one.

See also

objective_cache_factory

EmbeddedManifoldObjective{P, T, E, O2, O1<:AbstractManifoldObjective{E}} <:
   AbstractDecoratedManifoldObjective{E,O2}

Declare an objective to be defined in the embedding. This also declares the gradient to be defined in the embedding, and especially being the Riesz representer with respect to the metric in the embedding. The types can be used to still dispatch on also the undecorated objective type O2.

Fields

• objective: the objective that is defined in the embedding
• p=nothing: a point in the embedding.
• X=nothing: a tangent vector in the embedding

When a point in the embedding p is provided, embed! is used in place of this point to reduce memory allocations. Similarly X is used when embedding tangent vectors

ScaledManifoldObjective{E, O2, O1<:AbstractManifoldObjective{E},F} <:
   AbstractDecoratedManifoldObjective{E,O2}

Declare an objective to be defined as a scaled version of an existing objective.

This rescales all involved functions.

For now the functions rescaled are

• the cost
• the gradient
• the Hessian

Fields

• objective: the objective that is defined in the embedding
• scale=1: the scaling applied

Constructors

ScaledManifoldObjective(objective, scale::Real=1)

Generate a scaled manifold objective based on objective with scale being 1 by default in the first, scale=-1 in the second case. The multiplication from the left with a scalar is also overloaded.

-objective

The single-parameter minus is overloaded to have a short notation turning a maximization problem into a minimization one, which would fit the framework provided within Manopt.jl

scale * objective

Equivalent to the first constructor, but might be nicer to write in a few places.

reset_counters(co::ManifoldCountObjective, value::Integer=0)

Reset all values in the count objective to value.

objective_cache_factory(M::AbstractManifold, o::AbstractManifoldObjective, cache::Symbol)

Generate a cached variant of the AbstractManifoldObjective o on the AbstractManifold M based on the symbol cache.

The following caches are available

• :Simple generates a SimpleManifoldCachedObjective
• :LRU generates a ManifoldCachedObjective where you should use the form (:LRU, [:Cost, :Gradient]) to specify what should be cached or (:LRU, [:Cost, :Gradient], 100) to specify the cache size. Here this variant defaults to (:LRU, [:Cost, :Gradient], 100), caching up to 100 cost and gradient values.^[1]

objective_cache_factory(M::AbstractManifold, o::AbstractManifoldObjective, cache::Tuple{Symbol, Array, Array})
objective_cache_factory(M::AbstractManifold, o::AbstractManifoldObjective, cache::Tuple{Symbol, Array})

Generate a cached variant of the AbstractManifoldObjective o on the AbstractManifold M based on the symbol cache[1], where the second element cache[2] are further arguments to the cache and the optional third is passed down as keyword arguments.

For all available caches see the simpler variant with symbols.

 SimpleManifoldCachedObjective{O<:AbstractManifoldFirstOrderObjective{E}, P, T,C} <: AbstractDecoratedManifoldObjective{E,O}

Provide a simple cache for an AbstractManifoldFirstOrderObjective that is, this cache stores a point p and a gradient $\operatorname{grad} f(p)$ in X as well as a cost value $f(p)$ in c. It can also easily evaluate the differential based on the cached gradient.

Both X and c are accompanied by booleans to keep track of their validity.

While this does not provide a cache for the differential, it uses the cached gradient as a help to evaluate the differential, if an up-to-date gradient is available. It otherwise does call the original differential.

This simple cache does not take into account, that some first order objectives have a common function for cost & grad. It only caches the function that is actually called.

Constructors

SimpleManifoldCachedObjective(M::AbstractManifold, obj::AbstractManifoldFirstOrderObjective; kwargs...)

Keyword arguments

• p=rand(M): a point on the manifold to initialize the cache with
• X=get_gradient(M, obj, p) or zero_vector(M,p): a tangent vector to store the gradient in, see also initialize=
• c=[get_cost](@ref)(M, obj, p)or0.0: a value to store the cost function ininitialize`
• initialized=true: whether to initialize the cached X and c or not.

where both for p and X copies are generated before they are stored.

SimpleManifoldCachedObjective(obj::AbstractManifoldFirstOrderObjective, p, X, c; initialized = false)

Similar as above but initialising all fields directly and without copies and initialized indicated whether the three values correspond to an evaluation from obj.

ManifoldCachedObjective{E,P,O<:AbstractManifoldObjective{<:E},C<:NamedTuple{}} <: AbstractDecoratedManifoldObjective{E,P}

Create a cache for an objective, based on a NamedTuple that stores some kind of cache.

Constructor

ManifoldCachedObjective(M, o::AbstractManifoldObjective, caches::Vector{Symbol}; kwargs...)

Create a cache for the AbstractManifoldObjective where the Symbols in caches indicate, which function evaluations to cache.

Supported symbols

Keyword arguments

• p=rand(M): the type of the keys to be used in the caches. Defaults to the default representation on M.
• value=get_cost(M, objective, p): the type of values for numeric values in the cache
• X=zero_vector(M,p): the type of values to be cached for gradient and Hessian calls.
• cache=[:Cost]: a vector of symbols indicating which function calls should be cached.
• cache_size=10: number of (least recently used) calls to cache
• cache_sizes=Dict{Symbol,Int}(): a named tuple or dictionary specifying the sizes individually for each cache.

init_caches(caches, T::Type{LRU}; kwargs...)

Given a vector of symbols caches, this function sets up the NamedTuple of caches, where T is the type of cache to use.

Keyword arguments

• p=rand(M): a point on a manifold, to both infer its type for keys and initialize caches
• value=0.0: a value both typing and initialising number-caches, the default is for (Float) values like the cost.
• X=zero_vector(M, p): a tangent vector at p to both type and initialize tangent vector caches
• cache_size=10: a default cache size to use
• cache_sizes=Dict{Symbol,Int}(): a dictionary of sizes for the caches to specify different (non-default) sizes

init_caches(M::AbstractManifold, caches, T; kwargs...)

Given a vector of symbols caches, this function sets up the NamedTuple of caches for points/vectors on M, where T is the type of cache to use.

ManifoldCountObjective{E,P,O<:AbstractManifoldObjective,I<:Integer} <: AbstractDecoratedManifoldObjective{E,P}

A wrapper for any AbstractManifoldObjective of type O to count different calls to parts of the objective.

Fields

• counts a dictionary of symbols mapping to integers keeping the counted values
• objective the wrapped objective

Supported symbols

Constructors

ManifoldCountObjective(objective::AbstractManifoldObjective, counts::Dict{Symbol, <:Integer})

Initialise the ManifoldCountObjective to wrap objective initializing the set of counts

ManifoldCountObjective(M::AbstractManifold, objective::AbstractManifoldObjective, count::AbstractVecor{Symbol}, init=0)

Count function calls on objective using the symbols in count initialising all entries to init.

ReturnManifoldObjective{E,O2,O1<:AbstractManifoldObjective{E}} <: AbstractDecoratedManifoldObjective{E,O2}

A wrapper to indicate that get_solver_result should return the inner objective.

The types are such that one can still dispatch on the undecorated type O2 of the original objective as well.