Adding manifolds to Manopt

[Nicolas Boumal]

To add a manifold to Manopt, you only need to create one file: they are called "factories", because they are Matlab functions that return a structure representing the manifold. The structure contains functions such as the metric, retraction, etc.: enough information to describe and work with the manifold.

It is a good start to have a look at spherefactory.m for an example.

There is also a brief description of the various functions on this page: https://www.manopt.org/tutorial.html#manifolds.

Important things to decide before getting started are: how are points on the manifold represented (what kind of matrix for example)? How are tangent vectors represented? If the manifold is embedded in a linear space, how are points/vectors in that embedding space represented? This last point is important to make proper sense of functions such as proj (orthogonal projection from the embedding space to a tangent space) and egrad2rgrad, ehess2rhess (which convert gradients and Hessians in the embedding space to their counter-parts on the manifold).

If you have any questions along the way, don't hesitate to post on the forum: that's the best place to discuss these matters.

[Nicolas Boumal]

There is a whole chapter in my book detailing examples of manifolds and how to work out all the tools necessary to build a factory:

https://groups.google.com/forum/#!topic/manopttoolbox/kL7G_KsM6aQ

[Oleg Kachan]

What if the manifold admits different metrics, i.e. different sets of log/exp maps? I know there are many metrics one could associate with SPD matrices for example.

How is it managed by Manopt?

[Nicolas Boumal]

Hello Oleg,

> What if the manifold admits different metrics?

You can handle this in at least two ways:

Either create one factory for each metric (thinking of a factory as corresponding to one Riemannian manifold, so: different metric means different Riemannian manifold means different factory).

Or allow your factory to take an extra input to choose a specific metric (an optional flag if you will).

Either way, the factory should output one structure M that consistently describes one Riemannian manifold, with one specific metric. If you need to work with two metrics on a manifold, then create two structures, say, M1 and M2.

Best,

Nicolas