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.

 See also: hessianextreme

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

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 %
0018 % See also: hessianextreme
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;
0045     N.egrad2rgrad = 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 Sat 12-Nov-2016 14:11:22 by m2html © 2005