Home > manopt > tools > tangentspherefactory.m

# tangentspherefactory

## PURPOSE Returns a manifold struct. for the sphere on the tangent space to M at x.

## SYNOPSIS function N = tangentspherefactory(M, x)

## DESCRIPTION ``` Returns a manifold struct. for the sphere on the tangent space to M at x.

N = tangentspherefactory(M, x)

N defines a manifold that is the unit sphere on the tangent space to M
at x. Points are represented as tangent vectors of unit norm. Tangent
vectors are represented as tangent vectors orthogonal to the root point,
with respect to the Riemannian metric on the tangent space.

This is chiefly useful to solve optimization problems involving unit norm
tangent vectors to M at x, which notably comes up when looking for
extreme eigenvectors of the Hessian of a cost function on M at x, for
example. The Riemannian structure on this sphere is that of a Riemannian
submanifold of the (Euclidean) tangent space, equipped with the
Riemannian metric of M at that point.

## CROSS-REFERENCE INFORMATION This function calls:
• hashmd5 Computes the MD5 hash of input data.
This function is called by:
• hessianextreme Compute an extreme eigenvector / eigenvalue of the Hessian of a problem.

## SOURCE CODE ```0001 function N = tangentspherefactory(M, x)
0002 % Returns a manifold struct. for the sphere on the tangent space to M at x.
0003 %
0004 % N = tangentspherefactory(M, x)
0005 %
0006 % N defines a manifold that is the unit sphere on the tangent space to M
0007 % at x. Points are represented as tangent vectors of unit norm. Tangent
0008 % vectors are represented as tangent vectors orthogonal to the root point,
0009 % with respect to the Riemannian metric on the tangent space.
0010 %
0011 % This is chiefly useful to solve optimization problems involving unit norm
0012 % tangent vectors to M at x, which notably comes up when looking for
0013 % extreme eigenvectors of the Hessian of a cost function on M at x, for
0014 % example. The Riemannian structure on this sphere is that of a Riemannian
0015 % submanifold of the (Euclidean) tangent space, equipped with the
0016 % Riemannian metric of M at that point.
0017 %
0019
0020 % This file is part of Manopt: www.manopt.org.
0021 % Original author: Nicolas Boumal, March 16, 2015.
0022 % Contributors:
0023 % Change log:
0024 %
0025 %   Nov 27, 2015 (NB):
0026 %       Extra projection added in the retraction, to prevent numerical
0027 %       drift.
0028
0029     % N is the manifold we build. y will be a point on N, thus also a
0030     % tangent vector to M at x. This is a typical Riemannian submanifold of
0031     % a Euclidean space, hence it will be easy to describe in terms of the
0032     % tools available for M.
0033     N = struct();
0034
0035     % u, u1 and u2 will be tangent vectors to N at y. The tangent space to
0036     % N at y is a subspace of the tangent space to M at x, thus u, u1 and
0037     % u2 are also tangent vectors to M at x.
0038
0039     N.dim   = @() M.dim() - 1;
0040     N.inner = @(y, u1, u2) M.inner(x, u1, u2);
0041     N.norm  = @(y, u)      M.norm(x, u);
0042     N.proj  = @(y, v) M.lincomb(x, 1, v, -M.inner(x, v, y), y);
0043     N.typicaldist = @() 1;
0044     N.tangent = N.proj;
0046     N.retr = @retraction;
0047     N.exp = N.retr;
0048     function yy = retraction(y, u, t)
0049         if nargin == 2
0050             t = 1;
0051         end
0052         y_plus_tu = M.lincomb(x, 1, y, t, u);
0053         % This extra projection is not required mathematically,
0054         % but appears to be necessary numerically, sometimes.
0055         % The reason is that, as many retractions are operated,
0056         % there is a risk that the points generated would leave
0057         % the tangent space. If this proves to be a huge slow down,
0058         % one could consider adding a type of counter that only
0059         % executes this extra projection every so often, instead
0060         % of at every call.
0061         y_plus_tu = M.proj(x, y_plus_tu);
0062         nrm = M.norm(x, y_plus_tu);
0063         yy = M.lincomb(x, 1/nrm, y_plus_tu);
0064     end
0065     N.rand = @random;
0066     function y = random()
0067         y = M.randvec(x);
0068         nrm = M.norm(x, y);
0069         y = M.lincomb(x, 1/nrm, y);
0070     end
0071     N.randvec = @randvec;
0072     function u = randvec(y)
0073         u = N.proj(y, N.rand());
0074         nrm = N.norm(y, u);
0075         u = M.lincomb(x, 1/nrm, u);
0076     end
0077     N.zerovec = M.zerovec;
0078     N.lincomb = M.lincomb;
0079     N.transp = @(y1, y2, u) N.proj(y2, u);
0080     N.hash = @(y) ['z' hashmd5(M.vec(x, y))];
0081
0082 end```

Generated on Mon 10-Sep-2018 11:48:06 by m2html © 2005