hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_eigen_real_gen_partialsvd (f02wg)

 Contents

    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example

Purpose

nag_eigen_real_gen_partialsvd (f02wg) returns leading terms in the singular value decomposition (SVD) of a real general matrix and computes the corresponding left and right singular vectors.

Syntax

[nconv, sigma, u, v, resid, user, ifail] = f02wg(m, n, k, ncv, av, 'user', user)
[nconv, sigma, u, v, resid, user, ifail] = nag_eigen_real_gen_partialsvd(m, n, k, ncv, av, 'user', user)

Description

nag_eigen_real_gen_partialsvd (f02wg) computes a few, k, of the largest singular values and corresponding vectors of an m by n matrix A. The value of k should be small relative to m and n, for example kOminm,n. The full singular value decomposition (SVD) of an m by n matrix A is given by
A=UΣVT ,  
where U and V are orthogonal and Σ is an m by n diagonal matrix with real diagonal elements, σi, such that
σ1 σ2 σ minm,n 0 .  
The σi are the singular values of A and the first minm,n columns of U and V are the left and right singular vectors of A.
If Uk, Vk denote the leading k columns of U and V respectively, and if Σk denotes the leading principal submatrix of Σ, then
Ak Uk Σk VTk  
is the best rank-k approximation to A in both the 2-norm and the Frobenius norm.
The singular values and singular vectors satisfy
Avi = σi ui   and   ATui = σi vi   so that   ATA νi = σi2 νi ​ and ​ A AT ui = σ i 2 u i ,  
where ui and vi are the ith columns of Uk and Vk respectively.
Thus, for mn, the largest singular values and corresponding right singular vectors are computed by finding eigenvalues and eigenvectors for the symmetric matrix ATA. For m<n, the largest singular values and corresponding left singular vectors are computed by finding eigenvalues and eigenvectors for the symmetric matrix AAT. These eigenvalues and eigenvectors are found using functions from Chapter F12. You should read the F12 Chapter Introduction for full details of the method used here.
The real matrix A is not explicitly supplied to nag_eigen_real_gen_partialsvd (f02wg). Instead, you are required to supply a function, av, that must calculate one of the requested matrix-vector products Ax or ATx for a given real vector x (of length n or m respectively).

References

Wilkinson J H (1978) Singular Value Decomposition – Basic Aspects Numerical Software – Needs and Availability (ed D A H Jacobs) Academic Press

Parameters

Compulsory Input Parameters

1:     m int64int32nag_int scalar
m, the number of rows of the matrix A.
Constraint: m0.
If m=0, an immediate return is effected.
2:     n int64int32nag_int scalar
n, the number of columns of the matrix A.
Constraint: n0.
If n=0, an immediate return is effected.
3:     k int64int32nag_int scalar
k, the number of singular values to be computed.
Constraint: 0<k<minm,n-1.
4:     ncv int64int32nag_int scalar
The dimension of the arrays sigma and resid and the second dimension of the arrays u and v. this is the number of Lanczos basis vectors to use during the computation of the largest eigenvalues of ATA (mn) or AAT (m<n).
At present there is no a priori analysis to guide the selection of ncv relative to k. However, it is recommended that ncv2×k+1. If many problems of the same type are to be solved, you should experiment with varying ncv while keeping k fixed for a given test problem. This will usually decrease the required number of matrix-vector operations but it also increases the internal storage required to maintain the orthogonal basis vectors. The optimal ‘cross-over’ with respect to CPU time is problem dependent and must be determined empirically.
Constraint: k<ncvminm,n.
5:     av – function handle or string containing name of m-file
av must return the vector result of the matrix-vector product Ax or ATx, as indicated by the input value of iflag, for the given vector x.
av is called from nag_eigen_real_gen_partialsvd (f02wg) with the argument user as supplied to nag_eigen_real_gen_partialsvd (f02wg). You are free to use these arrays to supply information to av.
[iflag, ax, user] = av(iflag, m, n, x, user)

Input Parameters

1:     iflag int64int32nag_int scalar
If iflag=1, ax must return the m-vector result of the matrix-vector product Ax.
If iflag=2, ax must return the n-vector result of the matrix-vector product ATx.
2:     m int64int32nag_int scalar
The number of rows of the matrix A.
3:     n int64int32nag_int scalar
The number of columns of the matrix A.
4:     x: – double array
The vector to be pre-multiplied by the matrix A or AT.
5:     user – Any MATLAB object
av is called from nag_eigen_real_gen_partialsvd (f02wg) with the object supplied to nag_eigen_real_gen_partialsvd (f02wg).

Output Parameters

1:     iflag int64int32nag_int scalar
May be used as a flag to indicate a failure in the computation of Ax or ATx. If iflag is negative on exit from av, nag_eigen_real_gen_partialsvd (f02wg) will exit immediately with ifail set to iflag.
2:     ax: – double array
If iflag=1, contains the m-vector result of the matrix-vector product Ax.
If iflag=2, contains the n-vector result of the matrix-vector product ATx.
3:     user – Any MATLAB object

Optional Input Parameters

1:     user – Any MATLAB object
user is not used by nag_eigen_real_gen_partialsvd (f02wg), but is passed to av. Note that for large objects it may be more efficient to use a global variable which is accessible from the m-files than to use user.

Output Parameters

1:     nconv int64int32nag_int scalar
The number of converged singular values found.
2:     sigmancv – double array
The nconv converged singular values are stored in the first nconv elements of sigma.
3:     ulduncv – double array
The left singular vectors corresponding to the singular values stored in sigma.
The ith element of the jth left singular vector uj is stored in uij, for i=1,2,,m and j=1,2,,nconv.
4:     vldvncv – double array
The right singular vectors corresponding to the singular values stored in sigma.
The ith element of the jth right singular vector vj is stored in vij, for i=1,2,,n and j=1,2,,nconv.
5:     residncv – double array
The residual A vj - σj uj , for mn, or AT uj - σj vj , for m<n, for each of the converged singular values σj and corresponding left and right singular vectors uj and vj.
6:     user – Any MATLAB object
7:     ifail int64int32nag_int scalar
ifail=0 unless the function detects an error (see Error Indicators and Warnings).
nag_eigen_real_gen_partialsvd (f02wg) returns with ifail=0 if at least k singular values have converged and the corresponding left and right singular vectors have been computed.

Error Indicators and Warnings

Errors or warnings detected by the function:
   ifail=1
Constraint: m0.
   ifail=2
Constraint: n0.
   ifail=3
Constraint: k>0.
   ifail=4
Constraint: k<ncvminm,n.
   ifail=5
Constraint: ldum.
   ifail=6
Constraint: ldvn.
   ifail=8
The maximum number of iterations has been reached.
   ifail=9
No shifts could be applied during a cycle of the implicitly restarted Lanczos iteration.
   ifail=10
Could not build a full Lanczos factorization.
   ifail=11
The number of eigenvalues found to sufficient accuracy is zero.
   ifail=20
An error occurred during an internal call. Consider increasing the size of ncv relative to k.
   ifail<0
On output from user-defined function av, iflag was set to a negative value, .
   ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
   ifail=-399
Your licence key may have expired or may not have been installed correctly.
   ifail=-999
Dynamic memory allocation failed.

Accuracy

See The singular value decomposition in the F08 Chapter Introduction.

Further Comments

None.

Example

This example finds the four largest singular values (σ) and corresponding right and left singular vectors for the matrix A, where A is the m by n real matrix derived from the simplest finite difference discretization of the two-dimensional kernal ks,tdt where
ks,t = st-1 if ​0st 1 ts-1 if ​0t<s1 .  
function f02wg_example


fprintf('f02wg example results\n\n');

m = int64(100);
n = int64(500);
k = int64(4);
ncv = int64(10);

[nconv, sigma, u, v, resid, user, ifail] = ...
f02wg(m, n, k, ncv, @av);

res = [sigma(1:nconv) resid(1:nconv)];
fprintf('  Singular Value   Residual\n');
fprintf('   %10.5f  %12.2e\n',res');



function [iflag, ax, user] = av(iflag, m, n, x, user)
  if (iflag == 1)
    ax = zeros(m, 1);
  else
    ax = zeros(n, 1);
  end

  % Computes  w <- A*x or w <- Trans(A)*x.
  h = 1/(double(m)+1);
  k = 1/(double(n)+1);
  if (iflag == 1)
    t = 0;
    for j = 1:n
      t = t + k;
      s = 0;
      ktx = k*(t-1)*x(j);
      for i = 1:min(j,m)
        s = s + h;
        ax(i) = ax(i) + ktx*s;
      end
      ktx = k*t*x(j);
      for i = j+1:m
        s = s + h;
        ax(i) = ax(i) + ktx*(s-1);
      end
    end
  else
    t = 0;
    for j = 1:n
      t = t + k;
      s = 0;
      for i = 1:min(j,m)
        s = s + h;
        ax(j) = ax(j) + k*s*(t-1)*x(i);
      end
      for i = j+1:m
        s = s + h;
        ax(j) = ax(j) + k*t*(s-1)*x(i);
      end
    end
  end
f02wg example results

  Singular Value   Residual
      0.00830      1.82e-18
      0.01223      3.95e-18
      0.02381      1.95e-17
      0.11274      2.53e-17

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015