This is linear-algebra.info, produced by makeinfo version 7.2 from
linear-algebra.texi.

INFO-DIR-SECTION Math
START-INFO-DIR-ENTRY
* Octave linear-algebra: (linear-algebra).          linear-algebra package for Octave
END-INFO-DIR-ENTRY


File: linear-algebra.info,  Node: Top,  Next: Overview,  Up: (dir)

Octave linear-algebra package
*****************************

Copyright © The Octave Project Developers

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
* Menu:

* Overview::
* Installing and loading::
* Function Reference::

 -- The Detailed Node Listing --

Function Reference

* Vector functions::
* Matrix functions::
* Matrix factorization::
* Block sparse matrices::
* Kronecker Products::
* Circulant matrices::


File: linear-algebra.info,  Node: Overview,  Next: Installing and loading,  Prev: Top,  Up: Top

1 Overview
**********

The linear-algebra package contains additional linear algebra functions.


File: linear-algebra.info,  Node: Installing and loading,  Next: Function Reference,  Prev: Overview,  Up: Top

2 Installing and loading
************************

The linear-algebra package must be installed and then loaded to be used.

It can be installed in GNU Octave directly from octave-forge,

2.1 Windows install
===================

If running in Windows, the package may already be installed, to check
run:

     pkg list linear-algebra

2.2 Installing
==============

With an internet connection available, the linear-algebra package can be
installed from packages.octave.org using the following command within
GNU Octave:

     pkg install linear-algebra

The latest released version of the package will be downloaded and
installed.

Otherwise, if the package file has already been downloaded it can be
installed using the following command in GNU Octave:

     pkg install linear-algebra-2.2.4.tar.gz

2.3 Loading
===========

Regardless of the method of installing the package, in order to use its
functions, the package must be loaded using the pkg load command:

     pkg load linear-algebra

The package must be loaded on each GNU Octave session.


File: linear-algebra.info,  Node: Function Reference,  Prev: Installing and loading,  Up: Top

3 Function Reference
********************

* Menu:

* Vector functions::
* Matrix functions::
* Matrix factorization::
* Block sparse matrices::
* Kronecker Products::
* Circulant matrices::


File: linear-algebra.info,  Node: Vector functions,  Next: Matrix functions,  Up: Function Reference

3.1 Vector functions
====================

3.1.1 vec_projection
--------------------

 -- Function File: OUT = vec_projection (X, Y)
     Compute the vector projection of a 3-vector onto another.  X : size
     1 x 3 and Y : size 1 x 3 TOL : size 1 x 1

                vec_projection ([1,0,0], [0.5,0.5,0])
                ⇒ 0.7071

     Vector projection of X onto Y, both are 3-vectors, returning the
     value of X along Y.  Function uses dot product, Euclidean norm, and
     angle between vectors to compute the proper length along Y.


File: linear-algebra.info,  Node: Matrix functions,  Next: Matrix factorization,  Prev: Vector functions,  Up: Function Reference

3.2 Matrix functions
====================

3.2.1 cartprod
--------------

 -- 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.

3.2.2 cod
---------

 -- 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.

3.2.3 funm
----------

 -- Function File: B = funm (A, F)
     Compute matrix equivalent of function F; F can be a function name
     or a function handle and A must be a square matrix.

     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 the 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(1, x);
             endfunction
             B = funm (A, besselk1);
             (Compute matrix equivalent of bessel function K1();
              a helper function is needed here to convey extra
              arguments for besselk() )

     Note that a much improved funm.m function has been implemented in
     Octave 11.1.0, so funm.m will be removed from the linear-algebra
     package if that is installed in Octave 11+.

     See also: thfm, expm, logm, sqrtm.

3.2.4 lobpcg
------------

 -- 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.

3.2.5 ndcovlt
-------------

 -- 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.

3.2.6 rotparams
---------------

 -- 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.

3.2.7 rotv
----------

 -- 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.

3.2.8 smwsolve
--------------

 -- 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.

3.2.9 thfm
----------

 -- 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.


File: linear-algebra.info,  Node: Matrix factorization,  Next: Block sparse matrices,  Prev: Matrix functions,  Up: Function Reference

3.3 Matrix factorization
========================

3.3.1 nmf_bpas
--------------

 -- Function File: [W, H, ITER, HIS] = nmf_bpas (A, K)
     Nonnegative Matrix Factorization by Alternating Nonnegativity
     Constrained Least Squares using Block Principal Pivoting/Active Set
     method.

     This function solves one the following problems: given A and K,
     find W and H such that

     (1) minimize 1/2 * || A-WH ||_F^2

     (2) minimize 1/2 * ( || A-WH ||_F^2 + alpha * || W ||_F^2 + beta *
     || H ||_F^2 )

     (3) minimize 1/2 * ( || A-WH ||_F^2 + alpha * || W ||_F^2 + beta *
     (sum_(i=1)^n || H(:,i) ||_1^2 ) )

     where W>=0 and H>=0 elementwise.  The input arguments are A : Input
     data matrix (m x n) and K : Target low-rank.

     *Optional Inputs*
     ‘Type’
          Default is 'regularized', which is recommended for quick
          application testing unless 'sparse' or 'plain' is explicitly
          needed.  If sparsity is needed for 'W' factor, then apply this
          function for the transpose of 'A' with formulation (3).  Then,
          exchange 'W' and 'H' and obtain the transpose of them.
          Imposing sparsity for both factors is not recommended and thus
          not included in this software.
          'plain'
               to use formulation (1)
          'regularized'
               to use formulation (2)
          'sparse'
               to use formulation (3)

     ‘NNLSSolver’
          Default is 'bp', which is in general faster.
          'bp'
               to use the algorithm in [1]
          'as'
               to use the algorithm in [2]

     ‘Alpha’
          Parameter alpha in the formulation (2) or (3).  Default is the
          average of all elements in A. No good justfication for this
          default value, and you might want to try other values.
     ‘Beta’
          Parameter beta in the formulation (2) or (3).  Default is the
          average of all elements in A. No good justfication for this
          default value, and you might want to try other values.
     ‘MaxIter’
          Maximum number of iterations.  Default is 100.
     ‘MinIter’
          Minimum number of iterations.  Default is 20.
     ‘MaxTime’
          Maximum amount of time in seconds.  Default is 100,000.
     ‘Winit’
          (m x k) initial value for W.
     ‘Hinit’
          (k x n) initial value for H.
     ‘Tol’
          Stopping tolerance.  Default is 1e-3.  If you want to obtain a
          more accurate solution, decrease TOL and increase MAX_ITER at
          the same time.
     ‘Verbose’
          If present the function will show information during the
          calculations.

     *Outputs*
     ‘W’
          Obtained basis matrix (m x k)
     ‘H’
          Obtained coefficients matrix (k x n)
     ‘iter’
          Number of iterations
     ‘HIS’
          If present the history of computation is returned.

     Usage Examples:
            nmf_bpas (A,10)
            nmf_bpas (A,20,'verbose')
            nmf_bpas (A,30,'verbose','nnlssolver','as')
            nmf_bpas (A,5,'verbose','type','sparse')
            nmf_bpas (A,60,'verbose','type','plain','Winit',rand(size(A,1),60))
            nmf_bpas (A,70,'verbose','type','sparse','nnlssolver','bp','alpha',1.1,'beta',1.3)

     References: [1] For using this software, please cite:
     Jingu Kim and Haesun Park, Toward Faster Nonnegative Matrix
     Factorization: A New Algorithm and Comparisons,
     In Proceedings of the 2008 Eighth IEEE International Conference on
     Data Mining (ICDM'08), 353-362, 2008
     [2] If you use 'nnls_solver'='as' (see below), please cite:
     Hyunsoo Kim and Haesun Park, Nonnegative Matrix Factorization Based

     on Alternating Nonnegativity Constrained Least Squares and Active
     Set Method,
     SIAM Journal on Matrix Analysis and Applications, 2008, 30, 713-730

     Check original code at <http://www.cc.gatech.edu/~jingu>

     See also: nmf_pg.

3.3.2 nmf_pg
------------

 -- Function File: [W, H] = nmf_pg (V, WINIT, HINIT, TOL, TIMELIMIT,
          MAXITER)

     Non-negative matrix factorization by alternative non-negative least
     squares using projected gradients.

     The matrix V is factorized into two possitive matrices W and H such
     that ‘V = W*H + U’.  Where U is a matrix of residuals that can be
     negative or positive.  When the matrix V is positive the order of
     the elements in U is bounded by the optional named argument TOL
     (default value ‘1e-9’).

     The factorization is not unique and depends on the inital guess for
     the matrices W and H.  You can pass this initalizations using the
     optional named arguments WINIT and HINIT.

     timelimit, maxiter: limit of time and iterations

     Examples:

             A     = rand(10,5);
             [W H] = nmf_pg(A,tol=1e-3);
             U     = W*H -A;
             disp(max(abs(U)));


File: linear-algebra.info,  Node: Block sparse matrices,  Next: Kronecker Products,  Prev: Matrix factorization,  Up: Function Reference

3.4 Block sparse matrices
=========================

3.4.1 @blksparse/blksize
------------------------

 -- Function File: blksize (X)
     Returns the block size of the matrix.

3.4.2 @blksparse/blksparse
--------------------------

 -- Function File: S = blksparse (I, J, SV)
 -- Function File: S = blksparse (I, J, SV, M, N)
 -- Function File: S = blksparse (..., MODE)

     Construct a block sparse matrix.  The meaning of arguments is
     analogous to the built-in ‘sparse’ function, except that I, J are
     indices of blocks rather than elements, and SV is a 3-dimensional
     array, the first two dimensions determining the block size.
     Optionally, M and N can be specified as the true block dimensions;
     if not, the maximum values of I, J are taken instead.  The
     resulting sparse matrix has the size

             [M*P, N*Q]

     where

             P = size (SV, 1)
             Q = size (SV, 2)

     The blocks are located so that

          S(I(k):I(k)+P-1, J(k):J(K)+Q-1) = SV(:,:,k)

     Multiple blocks corresponding to the same pair of indices are
     summed, unless MODE is "unique", in which case the last of them is
     used.

3.4.3 @blksparse/ctranspose
---------------------------

 -- Function File: ctranspose (X)
     Returns the conjugate transpose of a block sparse matrix X.

3.4.4 @blksparse/display
------------------------

 -- Function File: display (X)
     Displays the block sparse matrix.

3.4.5 @blksparse/full
---------------------

 -- Function File: full (X)
     Converts a block sparse matrix to full.

3.4.6 @blksparse/ismatrix
-------------------------

 -- Function File: ismatrix (S)
     Returns true (a blksparse object is a matrix).

3.4.7 @blksparse/isreal
-----------------------

 -- Function File: isreal (S)
     Returns true if the array is non-complex.

3.4.8 @blksparse/issparse
-------------------------

 -- Function File: issparse (S)
     Returns true since a blksparse is sparse by definition.

3.4.9 @blksparse/minus
----------------------

 -- Function File: minus (S1, S2)
     Subtract two blksparse objects.

3.4.10 @blksparse/mldivide
--------------------------

 -- Function File: mldivide (X, Y)
     Performs a left division with a block sparse matrix.  If X is a
     block sparse matrix, it must be either diagonal or triangular, and
     Y must be full.  If X is built-in sparse or full, Y is converted
     accordingly, then the built-in division is used.

3.4.11 @blksparse/mrdivide
--------------------------

 -- Function File: mrdivide (X, Y)
     Performs a left division with a block sparse matrix.  If Y is a
     block sparse matrix, it must be either diagonal or triangular, and
     X must be full.  If Y is built-in sparse or full, X is converted
     accordingly, then the built-in division is used.

3.4.12 @blksparse/mtimes
------------------------

 -- Function File: mtimes (X, Y)
     Multiplies a block sparse matrix with a full matrix, or two block
     sparse matrices.  Multiplication of block sparse * sparse is not
     implemented.  If one of arguments is a scalar, it's a scalar
     multiply.

3.4.13 @blksparse/plus
----------------------

 -- Function File: plus (S1, S2)
     Add two blksparse objects.

3.4.14 @blksparse/size
----------------------

 -- Function File: size (X)
     Returns the size of the matrix.

3.4.15 @blksparse/sparse
------------------------

 -- Function File: sparse (X)
     Converts a block sparse matrix to (built-in) sparse.

3.4.16 @blksparse/subsref
-------------------------

 -- Function File: subsref (S, SUBS)
     Index elements from a blksparse object.

3.4.17 @blksparse/transpose
---------------------------

 -- Function File: transpose (X)
     Returns the transpose of a block sparse matrix X.

3.4.18 @blksparse/uminus
------------------------

 -- Function File: uminus (X)
     Returns the negative of a block sparse matrix X.

3.4.19 @blksparse/uplus
-----------------------

 -- Function File: uplus (X)
     Returns the unary plus of a block sparse matrix X.  Effectively the
     matrix itself, except signs of zeros.


File: linear-algebra.info,  Node: Kronecker Products,  Next: Circulant matrices,  Prev: Block sparse matrices,  Up: Function Reference

3.5 Kronecker Products
======================

3.5.1 @kronprod/columns
-----------------------

 -- Function File: columns (KP)
     Return the number of columns in the Kronecker product KP.

     See also: @kronprod/rows, @kronprod/size, @kronprod/numel.

3.5.2 @kronprod/ctranspose
--------------------------

 -- Function File: ctranspose (KP)
     The complex conjugate transpose of a Kronecker product.  This is
     equivalent to

          KP'

     See also: ctranspose, @kronprod/transpose.

3.5.3 @kronprod/det
-------------------

 -- Function File: det (KP)
     Compute the determinant of a Kronecker product.

     If KP is the Kronecker product of the N-by-N matrix A and the
     Q-by-Q matrix B, then the determinant is computed as

           det (A)^q * det (B)^n

     If KP is not a Kronecker product of square matrices the determinant
     is computed by forming the full matrix and then computing the
     determinant.

     See also: det, @kronprod/trace, @kronprod/rank, @kronprod/full.

3.5.4 @kronprod/disp
--------------------

 -- Function File: disp (KP)
     Show the content of the Kronecker product KP.  To avoid evaluating
     the Kronecker product, this function displays the two matrices
     defining the product.  To display the actual values of KP, use
     ‘disp (full (KP))’.

     This function is equivalent to ‘@kronprod/display’.

     See also: @kronprod/display, @kronprod/full.

3.5.5 @kronprod/display
-----------------------

 -- Function File: display (KP)
     Show the content of the Kronecker product KP.  To avoid evaluating
     the Kronecker product, this function displays the two matrices
     defining the product.  To display the actual values of KP, use
     ‘display (full (KP))’.

     See also: @kronprod/displ, @kronprod/full.

3.5.6 @kronprod/full
--------------------

 -- Function File: full (KP)
     Return the full matrix representation of the Kronecker product KP.

     If KP is the Kronecker product of an N-by-M matrix and a Q-by-R
     matrix, then the result is a NQ-by-MR matrix.  Thus, the result can
     require vast amount of memory, so this function should be avoided
     whenever possible.

     See also: full, @kronprod/sparse.

3.5.7 @kronprod/inv
-------------------

 -- Function File: inv (KP)
     Return the inverse of the Kronecker product KP.

     If KP is the Kronecker product of two square matrices A and B, the
     inverse will be computed as the Kronecker product of the inverse of
     A and B.

     If KP is square but not a Kronecker product of square matrices, the
     inverse will be computed using the SVD

     See also: @kronprod/sparse.

3.5.8 @kronprod/iscomplex
-------------------------

 -- Function File: iscomplex (KP)
     Return true if the Kronecker product KP contains any complex
     values.

     See also: iscomplex, @kronprod/isreal.

3.5.9 @kronprod/ismatrix
------------------------

 -- Function File: ismatrix (KP)
     Return true to indicate that the Kronecker product KP always is a
     matrix.

3.5.10 @kronprod/isreal
-----------------------

 -- Function File: isreal (KP)
     Return true if the Kronecker product KP is real, i.e.  has no
     imaginary components.

     See also: isreal, @kronprod/iscomplex.

3.5.11 @kronprod/issparse
-------------------------

 -- Function File: issparse (KP)
     Return true if one of the matrices in the Kronecker product KP is
     sparse.

     See also: @kronprod/sparse.

3.5.12 @kronprod/issquare
-------------------------

 -- Function File: issquare (KP)
     Return true if the Kronecker product KP is a square matrix.

     See also: @kronprod/size.

3.5.13 @kronprod/kronprod
-------------------------

 -- Function File: kronprod (A, B)
 -- Function File: kronprod (A, B, P)
     Construct a Kronecker product object.  XXX: Write proper
     documentation

     With two input arguments, the following matrix is represented: kron
     (A, B);

     With three input arguments, the following matrix is represented: P
     * kron (A, B) * P' (P must be a permutation matrix)

3.5.14 @kronprod/minus
----------------------

 -- Function File: minus (A, A)
     Return the difference between a Kronecker product and another
     matrix.  This is performed by forming the full matrix of both
     inputs and is as such a potential expensive operation.

     See also: minus, @kronprod/plus.

3.5.15 @kronprod/mldivide
-------------------------

 -- Function File: mldivide (M1, M2)
     Perform matrix left division.

3.5.16 @kronprod/mpower
-----------------------

 -- Function File: mpower (KP, K)
     Perform matrix power operation.

3.5.17 @kronprod/mtimes
-----------------------

 -- Function File: mtimes (KP1, KP2)
     Perform matrix multiplication operation.

3.5.18 @kronprod/numel
----------------------

 -- Function File: numel (KP)
     Return the number of elements in the Kronecker product KP.

     See also: numel, @kronprod/rows, @kronprod/columns, @kronprod/size.

3.5.19 @kronprod/plus
---------------------

 -- Function File: plus (A, A)
     Return the sum of a Kronecker product and another matrix.  This is
     performed by forming the full matrix of both inputs and is as such
     a potential expensive operation.

     See also: plus, @kronprod/minus.

3.5.20 @kronprod/rank
---------------------

 -- Function File: rank (KP)
     Return the rank of the Kronecker product KP.  This is computed as
     the product of the ranks of the matrices forming the product.

     See also: rank, @kronprod/det, @kronprod/trace.

3.5.21 @kronprod/rdivide
------------------------

 -- Function File: rdivide (A, B)
     Perform element-by-element right division.

3.5.22 @kronprod/rows
---------------------

 -- Function File: rows (KP)
     Return the number of rows in the Kronecker product KP.

     See also: rows, @kronprod/size, @kronprod/columns, @kronprod/numel.

3.5.23 @kronprod/size
---------------------

 -- Function File: size (KP)
 -- Function File: size (KP, DIM)
     Return the size of the Kronecker product KP as a vector.

     See also: size, @kronprod/rows, @kronprod/columns, @kronprod/numel.

3.5.24 @kronprod/size_equal
---------------------------

 -- Function File: size_equal (...)
     True if all input have same dimensions.

3.5.25 @kronprod/sparse
-----------------------

 -- Function File: sparse (KP)
     Return the Kronecker product KP represented as a sparse matrix.

     See also: sparse, @kronprod/issparse, @kronprod/full.

3.5.26 @kronprod/times
----------------------

 -- Function File: times (KP, KP2)
     Perform elemtn-by-element multiplication.

3.5.27 @kronprod/trace
----------------------

 -- Function File: trace (KP)
     Returns the trace of the Kronecker product KP.

     If KP is a Kronecker product of two square matrices, the trace is
     computed as the product of the trace of these two matrices.
     Otherwise the trace is computed by forming the full matrix.

     See also: @kronprod/det, @kronprod/rank, @kronprod/full.

3.5.28 @kronprod/transpose
--------------------------

 -- Function File: transpose (KP)
     Returns the transpose of the Kronecker product KP.  This is
     equivalent to

          KP.'

     See also: transpose, @kronprod/ctranspose.

3.5.29 @kronprod/uminus
-----------------------

 -- Function File: uminus (KP)
     Returns the unary minus operator working on the Kronecker product
     KP.  This corresponds to ‘-KP’ and simply returns the Kronecker
     product with the sign of the smallest matrix in the product
     reversed.

     See also: @kronprod/uminus.

3.5.30 @kronprod/uplus
----------------------

 -- Function File: uplus (KP)
     Returns the unary plus operator working on the Kronecker product
     KP.  This corresponds to ‘+KP’ and simply returns the Kronecker
     product unchanged.

     See also: @kronprod/uminus.


File: linear-algebra.info,  Node: Circulant matrices,  Prev: Kronecker Products,  Up: Function Reference

3.6 Circulant matrices
======================

3.6.1 circulant_eig
-------------------

 -- Function File: LAMBDA = circulant_eig (V)
 -- Function File: [VS, LAMBDA] = circulant_eig (V)

     Fast, compact calculation of eigenvalues and eigenvectors of a
     circulant matrix
     Given an N*1 vector V, return the eigenvalues LAMBDA and optionally
     eigenvectors VS of the N*N circulant matrix C that has V as its
     first column

     Theoretically same as ‘eig(make_circulant_matrix(v))’, but many
     fewer computations; does not form C explicitly

     Reference: Robert M. Gray, Toeplitz and Circulant Matrices: A
     Review, Now Publishers, http://ee.stanford.edu/~gray/toeplitz.pdf,
     Chapter 3

     See also: gallery, circulant_matrix_vector_product, circulant_inv.

3.6.2 circulant_inv
-------------------

 -- Function File: C = circulant_inv (V)

     Fast, compact calculation of inverse of a circulant matrix
     Given an N*1 vector V, return the inverse C of the N*N circulant
     matrix C that has V as its first column The returned C is the first
     column of the inverse, which is also circulant - to get the full
     matrix, use 'circulant_make_matrix(c)'

     Theoretically same as ‘inv(make_circulant_matrix(v))(:, 1)’, but
     requires many fewer computations and does not form matrices
     explicitly

     Roundoff may induce a small imaginary component in C even if V is
     real - use ‘real(c)’ to remedy this

     Reference: Robert M. Gray, Toeplitz and Circulant Matrices: A
     Review, Now Publishers, http://ee.stanford.edu/~gray/toeplitz.pdf,
     Chapter 3

     See also: gallery, circulant_matrix_vector_product, circulant_eig.

3.6.3 circulant_make_matrix
---------------------------

 -- Function File: C = circulant_make_matrix (V)
     Produce a full circulant matrix given the first column.

     _Note:_ this function has been deprecated and will be removed in
     the future.  Instead, use ‘gallery’ with the the ‘circul’ option.
     To obtain the exactly same matrix, transpose the result, i.e.,
     replace ‘circulant_make_matrix (V)’ with ‘gallery ("circul", V)'’.

     Given an N*1 vector V, returns the N*N circulant matrix C where V
     is the left column and all other columns are downshifted versions
     of V.

     Note: If the first row R of a circulant matrix is given, the first
     column V can be obtained as ‘v = r([1 end:-1:2])’.

     Reference: Gene H. Golub and Charles F. Van Loan, Matrix
     Computations, 3rd Ed., Section 4.7.7

     See also: gallery, circulant_matrix_vector_product, circulant_eig,
     circulant_inv.

3.6.4 circulant_matrix_vector_product
-------------------------------------

 -- Function File: Y = circulant_matrix_vector_product (V, X)

     Fast, compact calculation of the product of a circulant matrix with
     a vector
     Given N*1 vectors V and X, return the matrix-vector product Y = CX,
     where C is the N*N circulant matrix that has V as its first column

     Theoretically the same as ‘make_circulant_matrix(x) * v’, but does
     not form C explicitly; uses the discrete Fourier transform

     Because of roundoff, the returned Y may have a small imaginary
     component even if V and X are real (use ‘real(y)’ to remedy this)

     Reference: Gene H. Golub and Charles F. Van Loan, Matrix
     Computations, 3rd Ed., Section 4.7.7

     See also: gallery, circulant_eig, circulant_inv.


Tag Table:
Node: Top238
Node: Overview1236
Node: Installing and loading1432
Node: Function Reference2598
Node: Vector functions2887
Node: Matrix functions3536
Node: Matrix factorization20010
Node: Block sparse matrices25123
Node: Kronecker Products29362
Node: Circulant matrices37373

End Tag Table


Local Variables:
coding: utf-8
End:
