octave-linear-algebra 2.1.0-1 / usr / share / octave / packages / 3.2 / linear-algebra-2.1.0 / doc-cache

# Created by Octave 3.2.4, Mon Dec 05 13:38:35 2011 UTC <root@yellow>
# name: cache
# type: cell
# rows: 3
# columns: 10
# name: <cell-element>
# type: string
# elements: 1
# length: 8
cartprod
# name: <cell-element>
# type: string
# elements: 1
# length: 771
 -- Function File:  cartprod (VARARGIN )
     Computes the cartesian product of given column vectors ( row
     vectors ).  The vector elements are assumend to be numbers.

     Alternatively the vectors can be specified by as a matrix, by its
     columns.

     To calculate the cartesian product of vectors, P = A x B x C x D
     ... . Requires A, B, C, D be column vectors.  The algorithm is
     iteratively calcualte the products,  ( ( (A x B ) x C ) x D ) x
     etc.

            cartprod(1:2,3:4,0:1)
            ans =   1   3   0
                    2   3   0
                    1   4   0
                    2   4   0
                    1   3   1
                    2   3   1
                    1   4   1
                    2   4   1

   See also: kron


# name: <cell-element>
# type: string
# elements: 1
# length: 71
Computes the cartesian product of given column vectors ( row vectors ).

# name: <cell-element>
# type: string
# elements: 1
# length: 3
cod
# name: <cell-element>
# type: string
# elements: 1
# length: 885
 -- Function File: [Q, R, Z] = cod (A)
 -- Function File: [Q, R, Z, P] = cod (A)
 -- Function File: [...] = cod (A, '0')
     Computes the complete orthogonal decomposition (COD) of the matrix
     A:
            A = Q*R*Z'
     Let A be an M-by-N matrix, and let `K = min(M, N)'.  Then Q is
     M-by-M orthogonal, Z is N-by-N orthogonal, and R is M-by-N such
     that `R(:,1:K)' is upper trapezoidal and `R(:,K+1:N)' is zero.
     The additional P output argument specifies that pivoting should be
     used in the first step (QR decomposition). In this case,
            A*P = Q*R*Z'
     If a second argument of '0' is given, an economy-sized
     factorization is returned so that R is K-by-K.

     NOTE: This is currently implemented by double QR factorization
     plus some tricky manipulations, and is not as efficient as using
     xRZTZF from LAPACK.

     See also: qr



# name: <cell-element>
# type: string
# elements: 1
# length: 80
Computes the complete orthogonal decomposition (COD) of the matrix A:
       A =

# name: <cell-element>
# type: string
# elements: 1
# length: 7
condeig
# name: <cell-element>
# type: string
# elements: 1
# length: 784
 -- Function File: C = condeig (A)
 -- Function File: [V, LAMBDA, C] = condeig (A)
     Compute condition numbers of the eigenvalues of a matrix. The
     condition numbers are the reciprocals of the cosines of the angles
     between the left and right eigenvectors.

Arguments
---------

        * A must be a square numeric matrix.

Return values
-------------

        * C is a vector of condition numbers of the eigenvalue of A.

        * V is the matrix of right eigenvectors of A. The result is the
          same as for `[v, lambda] = eig (a)'.

        * LAMBDA is the diagonal matrix of eigenvalues of A. The result
          is the same as for `[v, lambda] = eig (a)'.

Example
-------

          a = [1, 2; 3, 4];
          c = condeig (a)
          => [1.0150; 1.0150]


# name: <cell-element>
# type: string
# elements: 1
# length: 57
Compute condition numbers of the eigenvalues of a matrix.

# name: <cell-element>
# type: string
# elements: 1
# length: 4
funm
# name: <cell-element>
# type: string
# elements: 1
# length: 1117
 -- Function File: B = funm (A, F)
     Compute matrix equivalent of function F; F can be a function name
     or a function handle.

     For trigonometric and hyperbolic functions, `thfm' is automatically
     invoked as that is based on `expm' and diagonalization is avoided.
     For other functions diagonalization is invoked, which implies that
     -depending on the properties of input matrix A- the results can be
     very inaccurate _without any warning_. For easy diagonizable and
     stable matrices results of funm will be sufficiently accurate.

     Note that you should not use funm for 'sqrt', 'log' or 'exp';
     instead use sqrtm, logm and expm as these are more robust.

     Examples:

            B = funm (A, sin);
            (Compute matrix equivalent of sin() )

            function bk1 = besselk1 (x)
               bk1 = besselk(x, 1);
            endfunction
            B = funm (A, besselk1);
            (Compute matrix equivalent of bessel function K1(); a helper function
             is needed here to convey extra args for besselk() )

     See also: thfm, expm, logm, sqrtm



# name: <cell-element>
# type: string
# elements: 1
# length: 80
Compute matrix equivalent of function F; F can be a function name or a
function 

# name: <cell-element>
# type: string
# elements: 1
# length: 6
lobpcg
# name: <cell-element>
# type: string
# elements: 1
# length: 9717
 -- Function File: [BLOCKVECTORX, LAMBDA] = lobpcg (BLOCKVECTORX,
          OPERATORA)
 -- Function File: [BLOCKVECTORX, LAMBDA, FAILUREFLAG] = lobpcg
          (BLOCKVECTORX, OPERATORA)
 -- Function File: [BLOCKVECTORX, LAMBDA, FAILUREFLAG, LAMBDAHISTORY,
RESIDUALNORMSHISTORY] = lobpcg (BLOCKVECTORX, OPERATORA, OPERATORB,
          OPERATORT, BLOCKVECTORY, RESIDUALTOLERANCE, MAXITERATIONS,
          VERBOSITYLEVEL)
     Solves Hermitian partial eigenproblems using preconditioning.

     The first form outputs the array of algebraic smallest eigenvalues
     LAMBDA and corresponding matrix of orthonormalized eigenvectors
     BLOCKVECTORX of the Hermitian (full or sparse) operator OPERATORA
     using input matrix BLOCKVECTORX as an initial guess, without
     preconditioning, somewhat similar to:

          # for real symmetric operator operatorA
          opts.issym  = 1; opts.isreal = 1; K = size (blockVectorX, 2);
          [blockVectorX, lambda] = eigs (operatorA, K, 'SR', opts);

          # for Hermitian operator operatorA
          K = size (blockVectorX, 2);
          [blockVectorX, lambda] = eigs (operatorA, K, 'SR');

     The second form returns a convergence flag. If FAILUREFLAG is 0
     then all the eigenvalues converged; otherwise not all converged.

     The third form computes smallest eigenvalues LAMBDA and
     corresponding eigenvectors BLOCKVECTORX of the generalized
     eigenproblem Ax=lambda Bx, where Hermitian operators OPERATORA and
     OPERATORB are given as functions, as well as a preconditioner,
     OPERATORT. The operators OPERATORB and OPERATORT must be in
     addition _positive definite_. To compute the largest eigenpairs of
     OPERATORA, simply apply the code to OPERATORA multiplied by -1.
     The code does not involve _any_ matrix factorizations of OPERATORA
     and OPERATORB, thus, e.g., it preserves the sparsity and the
     structure of OPERATORA and OPERATORB.

     RESIDUALTOLERANCE and MAXITERATIONS control tolerance and max
     number of steps, and VERBOSITYLEVEL = 0, 1, or 2 controls the
     amount of printed info. LAMBDAHISTORY is a matrix with all
     iterative lambdas, and RESIDUALNORMSHISTORY are matrices of the
     history of 2-norms of residuals

     Required input:
        * BLOCKVECTORX (class numeric) - initial approximation to
          eigenvectors, full or sparse matrix n-by-blockSize.
          BLOCKVECTORX must be full rank.

        * OPERATORA (class numeric, char, or function_handle) - the
          main operator of the eigenproblem, can be a matrix, a
          function name, or handle

     Optional function input:
        * OPERATORB (class numeric, char, or function_handle) - the
          second operator, if solving a generalized eigenproblem, can
          be a matrix, a function name, or handle; by default if empty,
          `operatorB = I'.

        * OPERATORT (class char or function_handle) - the
          preconditioner, by default `operatorT(blockVectorX) =
          blockVectorX'.

     Optional constraints input:
        * BLOCKVECTORY (class numeric) - a full or sparse n-by-sizeY
          matrix of constraints, where sizeY < n. BLOCKVECTORY must be
          full rank. The iterations will be performed in the
          (operatorB-) orthogonal complement of the column-space of
          BLOCKVECTORY.

     Optional scalar input parameters:
        * RESIDUALTOLERANCE (class numeric) - tolerance, by default,
          `residualTolerance = n * sqrt (eps)'

        * MAXITERATIONS - max number of iterations, by default,
          `maxIterations = min (n, 20)'

        * VERBOSITYLEVEL - either 0 (no info), 1, or 2 (with pictures);
          by default, `verbosityLevel = 0'.

     Required output:
        * BLOCKVECTORX and LAMBDA (class numeric) both are computed
          blockSize eigenpairs, where `blockSize = size (blockVectorX,
          2)' for the initial guess BLOCKVECTORX if it is full rank.

     Optional output:
        * FAILUREFLAG (class integer) as described above.

        * LAMBDAHISTORY (class numeric) as described above.

        * RESIDUALNORMSHISTORY (class numeric) as described above.

     Functions `operatorA(blockVectorX)', `operatorB(blockVectorX)' and
     `operatorT(blockVectorX)' must support BLOCKVECTORX being a
     matrix, not just a column vector.

     Every iteration involves one application of OPERATORA and
     OPERATORB, and one of OPERATORT.

     Main memory requirements: 6 (9 if `isempty(operatorB)=0') matrices
     of the same size as BLOCKVECTORX, 2 matrices of the same size as
     BLOCKVECTORY (if present), and two square matrices of the size
     3*blockSize.

     In all examples below, we use the Laplacian operator in a 20x20
     square with the mesh size 1 which can be generated in MATLAB by
     running:
          A = delsq (numgrid ('S', 21));
          n = size (A, 1);

     or in MATLAB and Octave by:
          [~,~,A] = laplacian ([19, 19]);
          n = size (A, 1);

     Note that `laplacian' is a function of the specfun octave-forge
     package.

     The following Example:
          [blockVectorX, lambda, failureFlag] = lobpcg (randn (n, 8), A, 1e-5, 50, 2);

     attempts to compute 8 first eigenpairs without preconditioning,
     but not all eigenpairs converge after 50 steps, so failureFlag=1.

     The next Example:
          blockVectorY = [];
          lambda_all = [];
          for j = 1:4
            [blockVectorX, lambda] = lobpcg (randn (n, 2), A, blockVectorY, 1e-5, 200, 2);
            blockVectorY           = [blockVectorY, blockVectorX];
            lambda_all             = [lambda_all' lambda']';
            pause;
          end

     attemps to compute the same 8 eigenpairs by calling the code 4
     times with blockSize=2 using orthogonalization to the previously
     founded eigenvectors.

     The following Example:
          R       = ichol (A, struct('michol', 'on'));
          precfun = @(x)R\(R'\x);
          [blockVectorX, lambda, failureFlag] = lobpcg (randn (n, 8), A, [], @(x)precfun(x), 1e-5, 60, 2);

     computes the same eigenpairs in less then 25 steps, so that
     failureFlag=0 using the preconditioner function `precfun', defined
     inline. If `precfun' is defined as an octave function in a file,
     the function handle `@(x)precfun(x)' can be equivalently replaced
     by the function name `precfun'. Running:

          [blockVectorX, lambda, failureFlag] = lobpcg (randn (n, 8), A, speye (n), @(x)precfun(x), 1e-5, 50, 2);

     produces similar answers, but is somewhat slower and needs more
     memory as technically a generalized eigenproblem with B=I is
     solved here.

     The following example for a mostly diagonally dominant sparse
     matrix A demonstrates different types of preconditioning, compared
     to the standard use of the main diagonal of A:

          clear all; close all;
          n       = 1000;
          M       = spdiags ([1:n]', 0, n, n);
          precfun = @(x)M\x;
          A       = M + sprandsym (n, .1);
          Xini    = randn (n, 5);
          maxiter = 15;
          tol     = 1e-5;
          [~,~,~,~,rnp] = lobpcg (Xini, A, tol, maxiter, 1);
          [~,~,~,~,r]   = lobpcg (Xini, A, [], @(x)precfun(x), tol, maxiter, 1);
          subplot (2,2,1), semilogy (r'); hold on;
          semilogy (rnp', ':>');
          title ('No preconditioning (top)'); axis tight;
          M(1,2)  = 2;
          precfun = @(x)M\x; % M is no longer symmetric
          [~,~,~,~,rns] = lobpcg (Xini, A, [], @(x)precfun(x), tol, maxiter, 1);
          subplot (2,2,2), semilogy (r'); hold on;
          semilogy (rns', '--s');
          title ('Nonsymmetric preconditioning (square)'); axis tight;
          M(1,2)  = 0;
          precfun = @(x)M\(x+10*sin(x)); % nonlinear preconditioning
          [~,~,~,~,rnl] = lobpcg (Xini, A, [], @(x)precfun(x), tol, maxiter, 1);
          subplot (2,2,3),  semilogy (r'); hold on;
          semilogy (rnl', '-.*');
          title ('Nonlinear preconditioning (star)'); axis tight;
          M       = abs (M - 3.5 * speye (n, n));
          precfun = @(x)M\x;
          [~,~,~,~,rs] = lobpcg (Xini, A, [], @(x)precfun(x), tol, maxiter, 1);
          subplot (2,2,4),  semilogy (r'); hold on;
          semilogy (rs', '-d');
          title ('Selective preconditioning (diamond)'); axis tight;

References
==========

     This main function `lobpcg' is a version of the preconditioned
conjugate gradient method (Algorithm 5.1) described in A. V. Knyazev,
Toward the Optimal Preconditioned Eigensolver: Locally Optimal Block
Preconditioned Conjugate Gradient Method, SIAM Journal on Scientific
Computing 23 (2001), no. 2, pp. 517-541.
`http://dx.doi.org/10.1137/S1064827500366124'

Known bugs/features
===================

        * an excessively small requested tolerance may result in often
          restarts and instability. The code is not written to produce
          an eps-level accuracy! Use common sense.

        * the code may be very sensitive to the number of eigenpairs
          computed, if there is a cluster of eigenvalues not completely
          included, cf.
               operatorA = diag ([1 1.99 2:99]);
               [blockVectorX, lambda] = lobpcg (randn (100, 1),operatorA, 1e-10, 80, 2);
               [blockVectorX, lambda] = lobpcg (randn (100, 2),operatorA, 1e-10, 80, 2);
               [blockVectorX, lambda] = lobpcg (randn (100, 3),operatorA, 1e-10, 80, 2);

Distribution
============

     The main distribution site: `http://math.ucdenver.edu/~aknyazev/'

     A C-version of this code is a part of the
`http://code.google.com/p/blopex/' package and is directly available,
e.g., in PETSc and HYPRE.


# name: <cell-element>
# type: string
# elements: 1
# length: 61
Solves Hermitian partial eigenproblems using preconditioning.

# name: <cell-element>
# type: string
# elements: 1
# length: 7
ndcovlt
# name: <cell-element>
# type: string
# elements: 1
# length: 771
 -- Function File: Y = ndcovlt (X, T1, T2, ...)
     Computes an n-dimensional covariant linear transform of an n-d
     tensor, given a transformation matrix for each dimension. The
     number of columns of each transformation matrix must match the
     corresponding extent of X, and the number of rows determines the
     corresponding extent of Y. For example:

            size (X, 2) == columns (T2)
            size (Y, 2) == rows (T2)

     The element `Y(i1, i2, ...)' is defined as a sum of

            X(j1, j2, ...) * T1(i1, j1) * T2(i2, j2) * ...

     over all j1, j2, .... For two dimensions, this reduces to
            Y = T1 * X * T2.'

     [] passed as a transformation matrix is converted to identity
     matrix for the corresponding dimension.



# name: <cell-element>
# type: string
# elements: 1
# length: 80
Computes an n-dimensional covariant linear transform of an n-d tensor,
given a t

# name: <cell-element>
# type: string
# elements: 1
# length: 9
rotparams
# name: <cell-element>
# type: string
# elements: 1
# length: 466
 -- Function File: [VSTACKED, ASTACKED] =  rotparams ( rstacked )
     The function w = rotparams (r)            - Inverse to rotv().
     Using, W    = rotparams(R)  is such that  rotv(w)*r' == eye(3).

     If used as, [v,a]=rotparams(r) ,  idem, with v (1 x 3) s.t. w ==
     a*v.

     0 <= norm(w)==a <= pi

     :-O !!  Does not check if 'r' is a rotation matrix.

     Ignores matrices with zero rows or with NaNs. (returns 0 for them)

     See also: rotv



# name: <cell-element>
# type: string
# elements: 1
# length: 62
The function w = rotparams (r)            - Inverse to rotv().

# name: <cell-element>
# type: string
# elements: 1
# length: 4
rotv
# name: <cell-element>
# type: string
# elements: 1
# length: 500
 -- Function File: R =  rotv ( v, ang )
     The functionrotv calculates a Matrix of rotation about V w/ angle
     |v| r = rotv(v [,ang])

     Returns the rotation matrix w/ axis v, and angle, in radians,
     norm(v) or ang (if present).

     rotv(v) == w'*w + cos(a) * (eye(3)-w'*w) - sin(a) * crossmat(w)

     where a = norm (v) and w = v/a.

     v and ang may be vertically stacked : If 'v' is 2x3, then rotv( v
     ) == [rotv(v(1,:)); rotv(v(2,:))]


     See also: rotparams, rota, rot



# name: <cell-element>
# type: string
# elements: 1
# length: 80
The functionrotv calculates a Matrix of rotation about V w/ angle |v| r
= rotv(v

# name: <cell-element>
# type: string
# elements: 1
# length: 8
smwsolve
# name: <cell-element>
# type: string
# elements: 1
# length: 614
 -- Function File: X = smwsolve (A, U, V, B)
 -- Function File:  smwsolve (SOLVER, U, V, B)
     Solves the square system `(A + U*V')*X == B', where U and V are
     matrices with several columns, using the Sherman-Morrison-Woodbury
     formula, so that a system with A as left-hand side is actually
     solved. This is especially advantageous if A is diagonal, sparse,
     triangular or positive definite.  A can be sparse or full, the
     other matrices are expected to be full.  Instead of a matrix A, a
     user may alternatively provide a function SOLVER that performs the
     left division operation.


# name: <cell-element>
# type: string
# elements: 1
# length: 80
Solves the square system `(A + U*V')*X == B', where U and V are
matrices with se

# name: <cell-element>
# type: string
# elements: 1
# length: 4
thfm
# name: <cell-element>
# type: string
# elements: 1
# length: 692
 -- Function File: Y = thfm (X, MODE)
     Trigonometric/hyperbolic functions of square matrix X.

     MODE must be the name of a function. Valid functions are 'sin',
     'cos', 'tan', 'sec', 'csc', 'cot' and all their inverses and/or
     hyperbolic variants, and 'sqrt', 'log' and 'exp'.

     The code `thfm (x, 'cos')' calculates matrix cosinus _even if_
     input matrix X is _not_ diagonalizable.

     _Important note_: This algorithm does _not_ use an eigensystem
     similarity transformation. It maps the MODE functions to functions
     of `expm', `logm' and `sqrtm', which are known to be robust with
     respect to non-diagonalizable ('defective') X.

     See also: funm



# name: <cell-element>
# type: string
# elements: 1
# length: 54
Trigonometric/hyperbolic functions of square matrix X.