In place of 'vector' returns permutation matrices.

[L,U,P] = LU(A,THRESH) controls pivoting in sparse matrices, where

THRESH is a pivot threshold in [0,1]. Pivoting occurs when the

diagonal entry in a column has magnitude less than THRESH times the

magnitude of any sub-diagonal entry in that column. THRESH = 0 forces

diagonal pivoting. THRESH = 1 is the default.

[L,U,P,Q,R] = LU(A,THRESH) controls pivoting in UMFPACK. THRESH is a

one or two element vector which defaults to [0.1 0.001]. If UMFPACK

selects its unsymmetric pivoting strategy, THRESH(2) is not used. It

uses its symmetric pivoting strategy if A is square with a mostly

symmetric nonzero structure and a mostly nonzero diagonal. For its

unsymmetric strategy, the sparsest row i which satisfies the criterion

A(i,j) >= THRESH(1) * max(abs(A(j:m,j))) is selected. A value of 1.0

results in conventional partial pivoting. Entries in L have absolute

value of 1/THRESH(1) or less. For its symmetric strategy, the diagonal

is selected using the same test but with THRESH(2) instead. If the

diagonal entry fails this test, a pivot entry below the diagonal is

selected, using THRESH(1). In this case, L has entries with absolute

value 1/min(THRESH) or less. Smaller values of THRESH(1) and THRESH(2)

tend to lead to sparser LU factors, but the solution can become

inaccurate. Larger values can lead to a more accurate solution (but

not always), and usually an increase in the total work and memory

usage.

[L,U,p] = LU(A,THRESH,'vector') and [L,U,p,q,R] = LU(A,THRESH,'vector')

are also valid for sparse matrices and return permutation vectors.

Using 'matrix' in place of 'vector' returns permutation matrices.

See also colamd, luinc, qr, rref.

Overloaded methods:

gf/lu

codistributed/lu

Reference page in Help browser

doc lu

<luinc> - Incomplete LU factorization.

LUINC Sparse Incomplete LU factorization.

LUINC produces two different kinds of incomplete LU factorizations --

the drop tolerance and the 0 level of fill-in factorizations. These

factors may be useful as preconditioners for a system of linear

equations being solved by iterative methods such as BICG (BiConjugate

Gradients), GMRES (Generalized Minimum Residual Method) or PCG

(Preconditioned Conjugate Gradients).

LUINC(A,DROPTOL) performs the incomplete LU factorization of

A with drop tolerance DROPTOL.

LUINC(A,OPTS) allows additional options to the incomplete LU

factorization. OPTS is a structure with up to four fields:

droptol --- the drop tolerance of incomplete LU

milu --- modified incomplete LU

udiag --- replace zeros on the diagonal of U

thresh --- the pivot threshold (see also LU)

Only the fields of interest need to be set.

droptol is a non-negative scalar used as the drop

tolerance for the incomplete LU factorization. This factorization

is computed in the same (column-oriented) manner as the

LU factorization except after each column of L and U has

been calculated, all entries in that column which are smaller

in magnitude than the local drop tolerance, which is

droptol * NORM of the column of A, are "dropped" from L or U.

The only exception to this dropping rule is the diagonal of the

upper triangular factor U which remains even if it is too small.

Note that entries of the lower triangular factor L are tested

before being scaled by the pivot. Setting droptol = 0

produces the complete LU factorization, which is the default.

milu stands for modified incomplete LU factorization. Its

value is either 0 (unmodified, the default) or 1 (modified).

Instead of discarding those entries from the newly-formed

column of the factors, they are subtracted from the diagonal

of the upper triangular factor, U.

udiag is either 0 or 1. If it is 1, any zero diagonal entries

of the upper triangular factor U are replaced by the local drop

tolerance in an attempt to avoid a singular factor. The default

is 0.

thresh is a pivot threshold in [0,1]. Pivoting occurs

when the diagonal entry in a column has magnitude less

than thresh times the magnitude of any sub-diagonal entry in

that column. thresh = 0 forces diagonal pivoting. thresh = 1 is

the default.

[L,U,p] = LUINC(A,OPTS,'vector') returns the permutation information

as a row vector instead of as a permutation matrix so that L and U are

the incomplete factors of A(p,:). [L,U,P] = LUINC(A,OPTS,'matrix')

may be used to get a permutation matrix. This is the default behavior.

Example:

load west0479

A = west0479;

nnz(A)

nnz(lu(A))

nnz(luinc(A,1e-6))

This shows that A has 1887 nonzeros, its complete LU factorization

has 16777 nonzeros, and its incomplete LU factorization with a

drop tolerance of 1e-6 has 10311 nonzeros.

[L,U,P] = LUINC(A,'0') produces the incomplete LU factors of a sparse

matrix with 0 level of fill-in (i.e. no fill-in). L is unit lower

triangular, U is upper triangular and P is a permutation matrix. U has

the same sparsity pattern as triu(P*A). L has the same sparsity

pattern as tril(P*A), except for 1's on the diagonal of L where P*A may

be zero. Both L and U may have a zero because of cancellation where

P*A is nonzero. L*U differs from P*A only outside of the sparsity

pattern of P*A.

[L,U,p] = LUINC(A,'0','vector') returns a permutation vector instead of

a permutation matrix. The flag 'matrix' may be used in place of

'vector' to get a permutation matrix.

[L,U] = LUINC(A,'0') produces upper triangular U and L is a permutation

of unit lower triangular matrix. Thus no comparison can be made

between the sparsity patterns of L,U and A, although nnz(L) + nnz(U) =

nnz(A) + n. L*U differs from A only outside of its sparsity pattern.

LU = LUINC(A,'0') returns "L+U-I", where L is unit lower triangular, U

is upper triangular and the permutation information is lost.

Example:

load west0479

A = west0479;

[L,U,P] = luinc(A,'0');

isequal(spones(U),spones(triu(P*A)))

spones(L) ~= spones(tril(P*A))

D = (L*U) .* spones(P*A) - P*A

spones(L) differs from spones(tril(P*A)) at some positions on the

diagonal and at one position in L where cancellation zeroed out a

nonzero element of P*A. The entries of D are of the order of eps.

LUINC works only for sparse matrices.

See also lu, cholinc, bicg, gmres, pcg.

Reference page in Help browser

doc luinc

<qr> - Orthogonal-triangular decomposition.

QR Orthogonal-triangular decomposition.

[Q,R] = QR(A), where A is m-by-n, produces an m-by-n upper triangular

matrix R and an m-by-m unitary matrix Q so that A = Q*R.

[Q,R] = QR(A,0) produces the "economy size" decomposition.

If m>n, only the first n columns of Q and the first n rows of R are

computed. If m<=n, this is the same as [Q,R] = QR(A).

If A is full:

[Q,R,E] = QR(A) produces unitary Q, upper triangular R and a

permutation matrix E so that A*E = Q*R. The column permutation E is

chosen so that ABS(DIAG(R)) is decreasing.

[Q,R,E] = QR(A,0) produces an "economy size" decomposition in which E

is a permutation vector, so that A(:,E) = Q*R.

X = QR(A) and X = QR(A,0) return the output of LAPACK's *GEQRF routine.

TRIU(X) is the upper triangular factor R.

If A is sparse:

R = QR(A) computes a "Q-less QR decomposition" and returns the upper

triangular factor R. Note that R = CHOL(A'*A). Since Q is often nearly

full, this is preferred to [Q,R] = QR(A).

R = QR(A,0) produces "economy size" R. If m>n, R has only n rows. If

m<=n, this is the same as R = QR(A).

[Q,R,E] = QR(A) produces unitary Q, upper triangular R and a

permutation matrix E so that A*E = Q*R. The column permutation E is

chosen to reduce fill-in in R.

[Q,R,E] = QR(A,0) produces an "economy size" decomposition in which E

is a permutation vector, so that A(:,E) = Q*R.

[C,R] = QR(A,B), where B has as many rows as A, returns C = Q'*B.

The least-squares solution to A*X = B is X = R\C.

[C,R,E] = QR(A,B), also returns a fill-reducing ordering.

The least-squares solution to A*X = B is X = E*(R\C).

[C,R] = QR(A,B,0) produces "economy size" results. If m>n, C and R have

only n rows. If m<=n, this is the same as [C,R] = QR(A,B).

[C,R,E] = QR(A,B,0) additionally produces a fill-reducing permutation

vector E. In this case, the least-squares solution to A*X = B is

X(E,:) = R\C.

Example: The least squares approximate solution to A*x = b can be found

with the Q-less QR decomposition and one step of iterative refinement:

if issparse(A), R = qr(A); else R = triu(qr(A)); end

x = R\(R'\(A'*b));

r = b - A*x;

e = R\(R'\(A'*r));

x = x + e;

See also lu, null, orth, qrdelete, qrinsert, qrupdate.

Overloaded methods:

codistributed/qr

Reference page in Help browser

doc qr

<lsqnonneg> - Linear least squares with nonnegativity constraints.

LSQNONNEG Linear least squares with nonnegativity constraints.

X = LSQNONNEG(C,d) returns the vector X that minimizes NORM(d-C*X)

subject to X >= 0. C and d must be real.

X = LSQNONNEG(C,d,OPTIONS) minimizes with the default optimization

parameters replaced by values in the structure OPTIONS, an argument

created with the OPTIMSET function. See OPTIMSET for details. Used

options are Display and TolX. (A default tolerance TolX of

10*MAX(SIZE(C))*NORM(C,1)*EPS is used.)

X = LSQNONNEG(PROBLEM) finds the minimum for PROBLEM. PROBLEM is a

structure with the matrix 'C' in PROBLEM.C, the vector 'd' in

PROBLEM.d, the options structure in PROBLEM.options, and solver name

'lsqnonneg' in PROBLEM.solver. The structure PROBLEM must have all the

fields.

[X,RESNORM] = LSQNONNEG(...) also returns the value of the squared 2-norm of

the residual: norm(d-C*X)^2.

[X,RESNORM,RESIDUAL] = LSQNONNEG(...) also returns the value of the

residual: d-C*X.

[X,RESNORM,RESIDUAL,EXITFLAG] = LSQNONNEG(...) returns an EXITFLAG that

describes the exit condition of LSQNONNEG. Possible values of EXITFLAG and

the corresponding exit conditions are

1 LSQNONNEG converged with a solution X.

0 Iteration count was exceeded. Increasing the tolerance

(OPTIONS.TolX) may lead to a solution.

[X,RESNORM,RESIDUAL,EXITFLAG,OUTPUT] = LSQNONNEG(...) returns a structure

OUTPUT with the number of steps taken in OUTPUT.iterations, the type of

algorithm used in OUTPUT.algorithm, and the exit message in OUTPUT.message.

[X,RESNORM,RESIDUAL,EXITFLAG,OUTPUT,LAMBDA] = LSQNONNEG(...) returns

the dual vector LAMBDA where LAMBDA(i) <= 0 when X(i) is (approximately) 0

and LAMBDA(i) is (approximately) 0 when X(i) > 0.

See also lscov, slash.

Reference page in Help browser

doc lsqnonneg

<pinv> - Pseudoinverse.

PINV Pseudoinverse.

X = PINV(A) produces a matrix X of the same dimensions

as A' so that A*X*A = A, X*A*X = X and A*X and X*A

are Hermitian. The computation is based on SVD(A) and any

singular values less than a tolerance are treated as zero.

The default tolerance is MAX(SIZE(A)) * NORM(A) * EPS(class(A)).

PINV(A,TOL) uses the tolerance TOL instead of the default.

Class support for input A:

float: double, single

See also rank.

Reference page in Help browser

doc pinv

<lscov> - Least squares with known covariance.

LSCOV Least squares with known covariance.

X = LSCOV(A,B) returns the ordinary least squares solution to the

linear system of equations A*X = B, i.e., X is the N-by-1 vector that

minimizes the sum of squared errors (B - A*X)'*(B - A*X), where A is

M-by-N, and B is M-by-1. B can also be an M-by-K matrix, and LSCOV

returns one solution for each column of B. When rank(A) < N, LSCOV

sets the maximum possible number of elements of X to zero to obtain a

"basic solution".

X = LSCOV(A,B,W), where W is a vector length M of real positive weights,

returns the weighted least squares solution to the linear system A*X =

B, i.e., X minimizes (B - A*X)'*diag(W)*(B - A*X). W typically

contains either counts or inverse variances.

X = LSCOV(A,B,V), where V is an M-by-M symmetric (or hermitian) positive

definite matrix, returns the generalized least squares solution to the

linear system A*X = B with covariance matrix proportional to V, i.e., X

minimizes (B - A*X)'*inv(V)*(B - A*X).

More generally, if V is full, it can be positive semidefinite, and LSCOV

returns X that is a solution to the constrained minimization problem

minimize E'*E subject to A*X + T*E = B

E,X

where T*T' = V. When V is semidefinite, this problem will have a

solution only if B is consistent with A and V (i.e., in the column

space of [A T]), otherwise LSCOV returns an error.

By default, LSCOV computes the Cholesky decomposition of V and, in

effect, inverts that factor to transform the problem into ordinary

least squares. However, if LSCOV determines that V is semidefinite, it

uses an orthogonal decomposition algorithm that avoids inverting V.

X = LSCOV(A,B,V,ALG) allows you to explicitly choose the algorithm used

to compute X when V is a matrix. LSCOV(A,B,V,'chol') uses the Cholesky

decomposition of V. LSCOV(A,B,V,'orth') uses orthogonal decompositions,

and is more appropriate when V is ill-conditioned or singular, but is

computationally more expensive. 'orth' is not allowed when any of the

inputs are sparse.

[X,STDX] = LSCOV(...) returns the estimated standard errors of X. When

A is rank deficient, STDX contains zeros in the elements corresponding

to the necessarily zero elements of X.

[X,STDX,MSE] = LSCOV(...) returns the mean squared error. If B is assumed

to have covariance matrix SIGMA^2 * V (or SIGMA^2 * DIAG(1./W)), then MSE

is an estimate of SIGMA^2.

[X,STDX,MSE,S] = LSCOV(...) returns the estimated covariance matrix

of X. When A is rank deficient, S contains zeros in the rows and

columns corresponding to the necessarily zero elements of X. LSCOV

cannot return S if it is called with multiple right-hand sides (i.e.,

size(B,2) > 1).

The standard formulas for these quantities, when A and V are full rank,

are:

X = inv(A'*inv(V)*A)*A'*inv(V)*B

MSE = B'*(inv(V) - inv(V)*A*inv(A'*inv(V)*A)*A'*inv(V))*B./(M-N)

S = inv(A'*inv(V)*A)*MSE

STDX = sqrt(diag(S))

However, LSCOV uses methods that are faster and more stable, and are

applicable to rank deficient cases.

LSCOV assumes that the covariance matrix of B is known only up to a

scale factor. MSE is an estimate of that unknown scale factor, and

LSCOV scales the outputs S and STDX appropriately. However, if V is

known to be exactly the covariance matrix of B, then that scaling is

unnecessary. To get the appropriate estimates in this case, you should

rescale S and STDX by 1/MSE and sqrt(1/MSE), respectively.

Class support for inputs A,B,V,W:

float: double, single

See also mldivide, slash, lsqnonneg, qr.

Reference page in Help browser

doc lscov