Home > manopt > tools > tangentorthobasis.m

# tangentorthobasis

## PURPOSE

Returns an orthonormal basis of tangent vectors in the Manopt framework.

## SYNOPSIS

function orthobasis = tangentorthobasis(M, x, n, basis_vecs)

## DESCRIPTION

``` Returns an orthonormal basis of tangent vectors in the Manopt framework.

function orthobasis = tangentorthobasis(M, x)
function orthobasis = tangentorthobasis(M, x, n)
function orthobasis = tangentorthobasis(M, x, n, basis_vecs)

Inputs:
M is a Manopt manifold structure obtained from a factory.
x is a point on the manifold M.
n (optional) is the dimension of the random subspace to span; by default,
n = M.dim() so that the returned basis spans the whole tangent space.
basis_vecs (optional) is a cell of tangent vectors that are assumed to be
linearly independent. Their independence is not checked.

Output:
orthobasis is a cell of n tangent vectors at x.
With high probability, they form an orthonormal basis of the tangent
space at x. If necessary, this can be checked by calling
G = grammatrix(M, x, orthobasis)
and verifying that norm(G - eye(size(G))) is close to zero.

If basis_vecs is not specified then n vectors are taken at random in
the tangent space, then orthonormalized using Gram-Schmidt.

If basis_vecs is specified, then:
If length(basis_vecs) >= n, the first n vectors in basis_vecs are
passed are orthogonalized and returned.
If length(basis_vecs) < n, we append n - length(basis_vecs) random
vectors to basis_vecs, and we orthogonalize
then return the resulting cell.

Therefore if basis_vecs is provided, the span of the first
min(n, length(basis_vecs)) vectors in basis_vecs is always a
subspace of the span of the returned orthobasis.

Note: if extra accuracy is required, it may help to re-orthogonalize the
basis returned by this function once, as follows:
B = tangentorthobasis(M, x, ...);
B = orthogonalize(M, x, B);

## CROSS-REFERENCE INFORMATION

This function calls:
• orthogonalize ORTHOGONALIZE Orthogonalize tensor.
• round ROUND Approximate TTeMPS tensor within a prescribed tolerance.
• orthogonalize ORTHOGONALIZE Orthogonalize TT/MPS Block-mu tensor.
• round ROUND Approximate TTeMPS tensor within a prescribed tolerance.
• round ROUND Approximate TTeMPS operator within a prescribed tolerance.
• orthogonalize Orthonormalizes a basis of tangent vectors in the Manopt framework.
This function is called by:
• getGradientFD Computes an approx. of the gradient w/ finite differences of the cost.
• approxgradientFD Gradient approx. fnctn handle based on finite differences of the cost.
• trs_gep Solves trust-region subproblem with TRSgep in a subspace of tangent space.
• hessianmatrix Computes a matrix which represents the Hessian in some tangent basis.
• operator2matrix Forms a matrix representing a linear operator between two tangent spaces

## SOURCE CODE

```0001 function orthobasis = tangentorthobasis(M, x, n, basis_vecs)
0002 % Returns an orthonormal basis of tangent vectors in the Manopt framework.
0003 %
0004 % function orthobasis = tangentorthobasis(M, x)
0005 % function orthobasis = tangentorthobasis(M, x, n)
0006 % function orthobasis = tangentorthobasis(M, x, n, basis_vecs)
0007 %
0008 % Inputs:
0009 % M is a Manopt manifold structure obtained from a factory.
0010 % x is a point on the manifold M.
0011 % n (optional) is the dimension of the random subspace to span; by default,
0012 %   n = M.dim() so that the returned basis spans the whole tangent space.
0013 % basis_vecs (optional) is a cell of tangent vectors that are assumed to be
0014 %   linearly independent. Their independence is not checked.
0015 %
0016 % Output:
0017 % orthobasis is a cell of n tangent vectors at x.
0018 % With high probability, they form an orthonormal basis of the tangent
0019 % space at x. If necessary, this can be checked by calling
0020 %   G = grammatrix(M, x, orthobasis)
0021 % and verifying that norm(G - eye(size(G))) is close to zero.
0022 %
0023 % If basis_vecs is not specified then n vectors are taken at random in
0024 % the tangent space, then orthonormalized using Gram-Schmidt.
0025 %
0026 % If basis_vecs is specified, then:
0027 %   If length(basis_vecs) >= n, the first n vectors in basis_vecs are
0028 %                               passed are orthogonalized and returned.
0029 %   If length(basis_vecs) < n, we append n - length(basis_vecs) random
0030 %                              vectors to basis_vecs, and we orthogonalize
0031 %                              then return the resulting cell.
0032 %
0033 % Therefore if basis_vecs is provided, the span of the first
0034 % min(n, length(basis_vecs)) vectors in basis_vecs is always a
0035 % subspace of the span of the returned orthobasis.
0036 %
0037 % Note: if extra accuracy is required, it may help to re-orthogonalize the
0038 % basis returned by this function once, as follows:
0039 %  B = tangentorthobasis(M, x, ...);
0040 %  B = orthogonalize(M, x, B);
0041 %
0043
0044 % This file is part of Manopt: www.manopt.org.
0045 % Original author: Nicolas Boumal, April 28, 2016.
0046 % Contributors:
0047 % Change log:
0048 %
0049 %   VL July 17, 2022:
0050 %       Added the option to input basis_vecs to specify a linearly
0051 %       independent set of tangent vectors to pass to orthogonalize.
0052
0053
0054     dim = M.dim();
0055     if ~exist('n', 'var') || isempty(n)
0056         n = dim;
0057     end
0058     assert(n >= 0 && n <= dim && n == round(n), ...
0059            'n must be an integer between 0 and M.dim().');
0060
0061     basis = cell(n, 1);
0062
0063     % With high probability, vectors taken at random in the tangent space
0064     % are linearly independent of basis_vecs
0065     for k = 1 : n
0066         if exist('basis_vecs', 'var') && k <= length(basis_vecs)
0067             basis(k, 1) = basis_vecs(k, 1);
0068         else
0069             basis{k} = M.randvec(x);
0070         end
0071     end
0072
0073     % The Gram-Schmidt process transforms any n linearly independent
0074     % vectors into n orthonormal vectors spanning the same subspace.
0075     orthobasis = orthogonalize(M, x, basis);
0076
0077 end```

Generated on Fri 30-Sep-2022 13:18:25 by m2html © 2005