en fr

# Matrix Functions

Addition of two polynomials.

#### Syntax

p = addpol(p1,p2)


#### Description

addpol(p1,p2) adds two polynomials p1 and p2. Each polynomial is given as a vector of coefficients, with the highest power first; e.g., x^2+2x-3 is represented by [1,2,-3]. Row vectors and column vectors are accepted, as well as matrices made of row vectors or column vectors, provided one matrix is not larger in one dimension and smaller in the other one. addpol is equivalent to the plain addition when both arguments have the same size.

#### Examples

addpol([1,2,3], [2,5])
1 4 8
addpol([1,2,3], -[2,5])  % subtraction
1 0 -2
1 2 4
4 5 7


### balance

Diagonal similarity transform for balancing a matrix.

#### Syntax

B = balance(A)
(T, B) = balance(A)


#### Description

balance(A) applies a diagonal similarity transform to the square matrix A to make the rows and columns as close in norm as possible. Balancing may reduce the 1-norm of the matrix, and improves the accuracy of the computed eigenvalues and/or eigenvectors. To avoid round-off errors, balance scales A with powers of 2.

balance returns the balanced matrix B which has the same eigenvalues and singular values as A, and optionally the diagonal scaling matrix T such that T\A*T=B.

#### Example

A = [1,2e6;3e-6,4];
(T,B) = balance(A)
T =
16384       0
0       3.125e-2
B =
1       3.8147
1.5729  4


eig

### care

Continuous-time algebraic Riccati equation.

#### Syntax

(X, L, K) = care(A, B, Q)
(X, L, K) = care(A, B, Q, R)
(X, L, K) = care(A, B, Q, R, S)
(X, L) = care(A, S, Q, true)


#### Description

care(A,B,Q) calculates the stable solution X of the following continuous-time algebraic Riccati equation:

A'X + XA - XBB'X + Q = 0


All matrices are real; Q and X are symmetric.

With four input arguments, care(A,B,Q,R) (with R real symmetric) solves the following Riccati equation:

A'X + XA - XB inv(R) B'X + Q = 0


With five input arguments, care(A,B,Q,R,S) solves the following equation:

A'X + XA - (S + XB) inv(R) (S' + B'X) + Q = 0


With two or three output arguments, (X,L,K) = care(...) also returns the gain matrix K defined as

K = inv(R) B' X


and the column vector of closed-loop eigenvalues

L = eig(A-B*K)


care(A,S,Q,true) with up to two output arguments is equivalent to care(A,B,Q) or care(A,B,Q,false) with S=B*B'.

#### Example

A = [-4,2;1,2];
B = [0;1];
C = [2,-1];
Q = C' * C;
R = 5;
(X, L, K) = care(A, B, Q, R)
X =
1.07    3.5169
3.5169   23.2415
L =
-4.3488
-2.2995
K =
0.7034    4.6483
A' * X + X * A - X * B / R * B' * X + Q
1.7319e-14 1.1369e-13
8.5265e-14 6.2528e-13


dare

### chol

Cholesky decomposition.

#### Syntax

M2 = chol(M1)


#### Description

If a square matrix M1 is symmetric (or hermitian) and positive definite, it can be decomposed into the following product:

M1 = M2' M2

where M2 is an upper triangular matrix. The Cholesky decomposition can be seen as a kind of square root.

The part of M1 below the main diagonal is not used, because M1 is assumed to be symmetric or hermitian. An error occurs if M1 is not positive definite.

#### Example

M = chol([5,3;3,8])
M =
2.2361 1.3416
0      2.4900
M'*M
5 3
3 8


### cond

Condition number of a matrix.

#### Syntax

x = cond(M)


#### Description

cond(M) returns the condition number of matrix M, i.e. the ratio of its largest singular value divided by the smallest one, or infinity for singular matrices. The larger the condition number, the more ill-conditioned the inversion of the matrix.

#### Examples

cond([1, 0; 0, 1])
1
cond([1, 1; 1, 1+1e-3])
4002.0008


### conv

Convolution or polynomial multiplication.

#### Syntax

v = conv(v1,v2)
M = conv(M1,M2)
M = conv(M1,M2,dim)
M = conv(...,kind)


#### Description

conv(v1,v2) convolves the vectors v1 and v2, giving a vector whose length is length(v1)+length(v2)-1, or an empty vector if v1 or v2 is empty. The result is a row vector if both arguments are row vectors, and a column vector if both arguments are column vectors. Otherwise, arguments are considered as matrices.

conv(M1,M2) convolves the matrices M1 and M2 column by columns. conv(M1,M2,dim) convolves along the dimension dim, 1 for columns and 2 for rows. If one of the matrices has only one column, or one row, it is repeated to match the size of the other argument.

Let n1 and n2 be the number of elements in M1 and M2, respectively, along the convolution dimension. By default, the result has n1+n2-1 elements along the convolution dimension. An additional string argument kind can specify a different number of elements in the result: with kind='same', the result has n1 elements (M has the same size as M1, i.e. M1 is filtered by the finite impulse response filter M2). With kind='valid', the result has n1-n2+1 elements, i.e. result elements impacted by boundaries are discarded. kind='full' produce the same result as if kind is missing.

#### Examples

conv([1,2],[1,2,3])
1 4 7 6
conv([1,2],[1,2,3;4,5,6],2)
1  4  7  6
4 13 16 12
conv([1,2,5,8,3],[1,2,1],'full')
1  4 10 20 24 14  3
conv([1,2,5,8,3],[1,2,1],'same')
4 10 20 24 14
conv([1,2,5,8,3],[1,2,1],'valid')
10 20 24


### conv2

Two-dimensions convolution of matrices.

#### Syntax

M = conv2(M1,M2)
M = conv2(M1,M2,kind)


#### Description

conv2(M1,M2) convolves the matrices M1 and M2 along both directions. The optional third argument specifies how to crop the result. Let (nr1,nc1)=size(M1) and (nr2,nc2)=size(M2). With kind='full' (default value), the result M has nr1+nr2-1 lines and nc1+nc2-1 columns. With kind='same', the result M has nr1 lines and nc1 columns; this options is very useful if M1 represents equidistant samples in a plane (e.g. pixels) to be filtered with the finite-impulse response 2-d filter M2. With kind='valid', the result M has nr1-nr2+1 lines and nc1-nc2+1 columns, or is the empty matrix []; if M1 represents data filtered by M2, the borders where the convolution sum is not totally included in M1 are removed.

#### Examples

conv2([1,2,3;4,5,6;7,8,9],[1,1,1;1,1,1;1,1,1])
1  3  6  5  3
5 12 21 16  9
12 27 45 33 18
11 24 39 28 15
7 15 24 17  9
conv2([1,2,3;4,5,6;7,8,9],[1,1,1;1,1,1;1,1,1],'same')
12 21 16
27 45 33
24 39 28
conv2([1,2,3;4,5,6;7,8,9],[1,1,1;1,1,1;1,1,1],'valid')
45


conv

### cov

Covariance.

#### Syntax

M = cov(data)
M = cov(data, false)
M = cov(data, true)


#### Description

cov(data) returns the best unbiased estimate m-by-m covariance matrix of the n-by-m matrix data for a normal distribution. Each row of data is an observation where n quantities were measured. The covariance matrix is symmetric if data is real, and hermitian if data is complex (i.e. M==M'). The diagonal is the variance of each column of data.

cov(data,false) is the same as cov(data).

cov(data,true) returns the m-by-m covariance matrix of the n-by-m matrix data which contains the whole population.

#### Example

A = [1,2;2,4;3,5];
cov(A)
1 1.5
1.5 2.3333


The diagonal elements are the variance of the columns of A:

var(A)
1 2.3333


The covariance matrix can be computed as follows:

n = size(A, 1);
A1 = A - repmat(mean(A, 1), n, 1);
(A1' * A1) / (n - 1)
1 1.5
1.5 2.3333


### cross

Cross product.

#### Syntax

v3 = cross(v1, v2)
v3 = cross(v1, v2, dim)


#### Description

cross(v1,v2) gives the cross products of vectors v1 and v2. v1 and v2 must be row or columns vectors of three components, or arrays of the same size containing several such vectors. When there is ambiguity, a third argument dim may be used to specify the dimension of vectors: 1 for column vectors, 2 for row vectors, and so on.

#### Examples

cross([1; 2; 3], [0; 0; 1])
2
-1
0
cross([1, 2, 3; 7, 1, -3], [4, 0, 0; 0, 2, 0], 2)
0  12  -8
6   0  14


### cummax

Cumulative maximum.

#### Syntax

M2 = cummax(M1)
M2 = cummax(M1,dim)
M2 = cummax(...,dir)


#### Description

cummax(M1) returns a matrix M2 of the same size as M1, whose elements M2(i,j) are the maximum of all the elements M1(k,j) with k<=i. cummax(M1,dim) operates along the dimension dim (column-wise if dim is 1, row-wise if dim is 2).

An optional string argument dir specifies the processing direction. If it is 'reverse' or begins with 'r', cummax processes elements in reverse order, from the last one to the first one, along the processing dimension. If it is 'forward' or begins with 'f', it processes elements as if not specified, in the forward direction.

#### Examples

cummax([1,2,3;5,1,4;2,8,7])
1  2  3
5  2  4
5  8  7
cummax([1,2,3;5,1,4;2,8,7], 2)
1  2  3
5  5  5
2  8  8


### cummin

Cumulative minimum.

#### Syntax

M2 = cummin(M1)
M2 = cummin(M1,dim)
M2 = cummin(...,dir)


#### Description

cummin(M1) returns a matrix M2 of the same size as M1, whose elements M2(i,j) are the minimum of all the elements M1(k,j) with k<=i. cummin(M1,dim) operates along the dimension dim (column-wise if dim is 1, row-wise if dim is 2).

An optional string argument dir specifies the processing direction. If it is 'reverse' or begins with 'r', cummin processes elements in reverse order, from the last one to the first one, along the processing dimension. If it is 'forward' or begins with 'f', it processes elements as if not specified, in the forward direction.

### cumprod

Cumulative products.

#### Syntax

M2 = cumprod(M1)
M2 = cumprod(M1,dim)
M2 = cumprod(...,dir)


#### Description

cumprod(M1) returns a matrix M2 of the same size as M1, whose elements M2(i,j) are the product of all the elements M1(k,j) with k<=i. cumprod(M1,dim) operates along the dimension dim (column-wise if dim is 1, row-wise if dim is 2).

An optional string argument dir specifies the processing direction. If it is 'reverse' or begins with 'r', cumprod processes elements in reverse order, from the last one to the first one, along the processing dimension. If it is 'forward' or begins with 'f', it processes elements as if not specified, in the forward direction.

#### Examples

cumprod([1,2,3;4,5,6])
1  2  3
4 10 18
cumprod([1,2,3;4,5,6],2)
1  2   6
4 20 120


### cumsum

Cumulative sums.

#### Syntax

M2 = cumsum(M1)
M2 = cumsum(M1,dim)
M2 = cumsum(...,dir)


#### Description

cumsum(M1) returns a matrix M2 of the same size as M1, whose elements M2(i,j) are the sum of all the elements M1(k,j) with k<=i. cumsum(M1,dim) operates along the dimension dim (column-wise if dim is 1, row-wise if dim is 2).

An optional string argument dir specifies the processing direction. If it is 'reverse' or begins with 'r', cumsum processes elements in reverse order, from the last one to the first one, along the processing dimension. If it is 'forward' or begins with 'f', it processes elements as if not specified, in the forward direction.

#### Examples

cumsum([1,2,3;4,5,6])
1 2 3
5 7 9
cumsum([1,2,3;4,5,6],2)
1 3  6
4 9 15
cumsum([1,2,3;4,5,6],2,'r')
6   5 3
15 11 6


### dare

Discrete-time algebraic Riccati equation.

#### Syntax

(X, L, K) = dare(A, B, Q)
(X, L, K) = dare(A, B, Q, R)


#### Description

dare(A,B,Q) calculates the stable solution X of the following discrete-time algebraic Riccati equation:

X = A'XA - A'XB inv(B'XB+I) B'XA + Q


All matrices are real; Q and X are symmetric.

With four input arguments, dare(A,B,Q,R) (with R real symmetric) solves the following Riccati equation:

X = A'XA - A'XB inv(B'XB + R) B'XA + Q


With two or three output arguments, (X,L,K) = dare(...) also returns the gain matrix K defined as

K = inv(B'XB + R) B'XA


and the column vector of closed-loop eigenvalues

L = eig(A-B*K)


#### Example

A = [-4,2;1,2];
B = [0;1];
C = [2,-1];
Q = C' * C;
R = 5;
(X, L, K) = dare(A, B, Q, R)
X =
2327.9552 -1047.113
-1047.113    496.0624
L =
-0.2315
0.431
K =
9.3492   -2.1995
-X + A'*X*A - A'*X*B/(B'*X*B+R)*B'*X*A + Q
1.0332e-9  -4.6384e-10
-4.8931e-10  2.2101e-10


care

### deconv

Deconvolution or polynomial division.

#### Syntax

q = deconv(a,b)
(q,r) = deconv(a,b)


#### Description

(q,r)=deconv(a,b) divides the polynomial a by the polynomial b, resulting in the quotient q and the remainder r. All polynomials are given as vectors of coefficients, highest power first. The degree of the remainder is strictly smaller than the degree of b. deconv is the inverse of conv: a = addpol(conv(b,q),r).

#### Examples

[q,r] = deconv([1,2,3,4,5],[1,3,2])
q =
1 -1 4
r =
-6 -3
1 2 3 4 5


### det

Determinant of a square matrix.

#### Syntax

d = det(M)


#### Description

det(M) is the determinant of the square matrix M, which is 0 (up to the rounding errors) if M is singular. The function rank is a numerically more robust test for singularity.

#### Examples

det([1,2;3,4])
-2
det([1,2;1,2])
0


### diff

Differences.

#### Syntax

dm = diff(A)
dm = diff(A,n)
dm = diff(A,n,dim)
dm = diff(A,[],dim)


#### Description

diff(A) calculates the differences between each elements of the columns of matrix A, or between each elements of A if it is a row vector.

diff(A,n) calculates the n:th order differences, i.e. it repeats n times the same operation. Up to a scalar factor, the result is an approximation of the n:th order derivative based on equidistant samples.

diff(A,n,dim) operates along dimension dim. If the second argument n is the empty matrix [], the default value of 1 is assumed.

#### Examples

diff([1,3,5,4,8])
2 2 -1 4
diff([1,3,5,4,8],2)
0 -3 5
diff([1,3,5;4,8,2;3,9,8],1,2)
2  2
4 -6
6 -1


cumsum

### dlyap

Discrete-time Lyapunov equation.

#### Syntax

X = dlyap(A, C)


#### Description

dlyap(A,C) calculates the solution X of the following discrete-time Lyapunov equation:

AXA' - X + C = 0


All matrices are real.

#### Example

A = [3,1,2;1,3,5;6,2,1];
C = [7,1,2;4,3,5;1,2,1];
X = dlyap(A, C)
X =
-1.0505    3.2222   -1.2117
3.2317   -11.213    4.8234
-1.4199     5.184   -2.7424


### dot

Scalar product.

#### Syntax

v3 = dot(v1, v2)
v3 = dot(v1, v2, dim)


#### Description

dot(v1,v2) gives the scalar products of vectors v1 and v2. v1 and v2 must be row or columns vectors of same length, or arrays of the same size; then the scalar product is performed along the first dimension not equal to 1. A third argument dim may be used to specify the dimension the scalar product is performed along.

With complex values, complex conjugate values of the first array are multiplied with values of the second array.

#### Examples

dot([1; 2; 3], [0; 0; 1])
3
dot([1, 2, 3; 7, 1, -3], [4, 0, 0; 0, 2, 0], 2)
4
2
dot([1; 2i], [3i; 5])
0 - 7i


### eig

Eigenvalues and eigenvectors of a matrix.

#### Syntax

e = eig(M)
(V,D) = eig(M)


#### Description

eig(M) returns the vector of eigenvalues of the square matrix M.

(V,D) = eig(M) returns a diagonal matrix D of eigenvalues and a matrix V whose columns are the corresponding eigenvectors. They are such that M*V = V*D.

#### Examples

Eigenvalues as a vector:

eig([1,2;3,4])
-0.3723
5.3723


Eigenvectors, and eigenvalues as a diagonal matrix:

(V,D) = eig([1,2;2,1])
V =
0.7071 0.7071
-0.7071 0.7071
D =
-1 0
0 3


Checking that the result is correct:

[1,2;2,1] * V
-0.7071 2.1213
0.7071 2.1213
V * D
-0.7071 2.1213
0.7071 2.1213


### expm

Exponential of a square matrix.

#### Syntax

M2 = expm(M1)


#### Description

expm(M) is the exponential of the square matrix M, which is usually different from the element-wise exponential of M given by exp.

#### Examples

expm([1,1;1,1])
4.1945 3.1945
3.1945 4.1945
exp([1,1;1,1])
2.7183 2.7183
2.7183 2.7183


### fft

Fast Fourier Transform.

#### Syntax

F = fft(f)
F = fft(f,n)
F = fft(f,n,dim)


#### Description

fft(f) returns the discrete Fourier transform (DFT) of the vector f, or the DFT's of each columns of the array f. With a second argument n, the n first values are used; if n is larger than the length of the data, zeros are added for padding. An optional argument dim gives the dimension along which the DFT is performed; it is 1 for calculating the DFT of the columns of f, 2 for its rows, and so on. fft(f,[],dim) specifies the dimension without resizing the array.

fft is based on a mixed-radix Fast Fourier Transform if the data length is non-prime. It can be very slow if the data length has large prime factors or is a prime number.

The coefficients of the DFT are given from the zero frequency to the largest frequency (one point less than the inverse of the sampling period). If the input f is real, its DFT has symmetries, and the first half contain all the relevant information.

#### Examples

fft(1:4)
10 -2+2j -2 -2-2j
fft(1:4, 3)
6 -1.5+0.866j -1.5-0.866j


ifft

### fft2

2-d Fast Fourier Transform.

#### Syntax

F = fft2(f)
F = fft2(f, size)
F = fft2(f, nr, nc)
F = fft2(f, n)


#### Description

fft2(f) returns the 2-d Discrete Fourier Transform (DFT along dimensions 1 and 2) of array f.

With two or three input arguments, fft2 resizes the two first dimensions by cropping or by padding with zeros. fft2(f,nr,nc) resizes first dimension to nr rows and second dimension to nc columns. In fft2(f,size), the new size is given as a two-element vector [nr,nc]. fft2(F,n) is equivalent to fft2(F,n,n).

If the first argument is an array with more than two dimensions, fft2 performs the 2-d DFT along dimensions 1 and 2 separately for each plane along remaining dimensions; fftn performs an DFT along each dimension.

### fftn

n-dimension Fast Fourier Transform.

#### Syntax

F = fftn(f)
F = fftn(f, size)


#### Description

fftn(f) returns the n-dimension Discrete Fourier Transform of array f (DFT along each dimension of f).

With two input arguments, fftn(f,size) resizes f by cropping or by padding f with zeros.

### filter

Digital filtering of data.

#### Syntax

y = filter(b,a,u)
y = filter(b,a,u,x0)
y = filter(b,a,u,x0,dim)
(y, xf) = filter(...)


#### Description

filter(b,a,u) filters vector u with the digital filter whose coefficients are given by polynomials b and a. The filtered data can also be an array, filtered along the first non-singleton dimension or along the dimension specified with a fifth input argument. The fourth argument, if provided and different than the empty matrix [], is a matrix whose columns contain the initial state of the filter and have max(length(a),length(b))-1 element. Each column correspond to a signal along the dimension of filtering. The result y, which has the same size as the input, can be computed with the following code if u is a vector:

b = b / a(1);
a = a / a(1);
if length(a) > length(b)
b = [b, zeros(1, length(a)-length(b))];
else
a = [a, zeros(1, length(b)-length(a))];
end
n = length(x);
for i = 1:length(u)
y(i) = b(1) * u(i) + x(1);
for j = 1:n-1
x(j) = b(j + 1) * u(i) + x(j + 1) - a(j + 1) * y(i);
end
x(n) = b(n + 1) * u(i) - a(n + 1) * y(i);
end


The optional second output argument is set to the final state of the filter.

#### Examples

filter([1,2], [1,2,3], ones(1,10))
1 1 -2 4 1 -11 22 -8 -47 121

u = [5,6,5,6,5,6,5];
p = 0.8;
filter(1-p, [1,-p], u, p*u(1))
% low-pass with matching initial state
5 5.2 5.16 5.328 5.2624 5.4099 5.3279


### funm

Matrix function.

#### Syntax

Y = funm(X, fun)
(Y, err) = funm(X, fun)


#### Description

funm(X,fun) returns the matrix function of square matrix X specified by function fun. fun takes a scalar input argument and gives a scalar output. It is either specified by its name or given as an anonymous or inline function or a function reference.

With a second output argument err, funm also returns an estimate of the relative error.

#### Examples

funm([1,2;3,4], @sin)
-0.4656  -0.1484
-0.2226  -0.6882
X = [1,2;3,4];
funm(X, @(x) (1+x)/(2-x))
-0.25  -0.75
-1.125  -1.375
(eye(2)+X)/(2*eye(2)-X)
-0.25  -0.75
-1.125  -1.375


### householder

Householder transform.

#### Syntax

(nu, beta) = householder(x)


#### Description

The householder transform is an orthogonal matrix transform which sets all the elements of a column to zero, except the first one. It is the elementary step used by QR decomposition.

The matrix transform can be written as a product by an orthogonal square matrix P=I-beta*nu*nu', where I is the identity matrix, beta is a scalar, and nu is a column vector where nu(1) is 1. householder(x), where x is a real or complex non-empty column vector, gives nu and beta such that P*x=[y;Z], where y is a scalar and Z a zero column vector.

#### Example

x = [2; 5; 10];
(nu, beta) = householder(x)
nu =
1.0000
0.3743
0.7486
beta =
1.1761
P = eye(3) - beta * nu * nu'
P =
-0.1761 -0.4402 -0.8805
-0.4402  0.8352 -0.3296
-0.8805 -0.3296  0.3409
P * x
ans =
-11.3578
0.0000
0.0000


It is more efficient to avoid calculating P explicitly. Multiplication by P, either as P*A (to set elements to zero) or B*P' (to accumulate transforms), can be performed by passing nu and beta to householderapply:

householderapply(x, nu, beta)
ans =
-11.3578
0.0000
0.0000


### householderapply

Apply Householder transform.

#### Syntax

B = householderapply(A, nu, beta)
B = householderapply(A, nu, beta, 'r')


#### Description

householderapply(A,nu,beta) apply the Householder transform defined by column vector nu (where nu(1) is 1) and real scalar beta, as obtained by householder, to matrix A; i.e. it computes A-nu*beta*nu'*A.

householderapply(A,nu,beta,'r') apply the inverse Householder transform to matrix A; i.e. it computes A-A*nu*beta*nu'.

householder

### ifft

Inverse Fast Fourier Transform.

#### Syntax

f = ifft(F)
f = ifft(F, n)
f = ifft(F, n, dim)


#### Description

ifft returns the inverse Discrete Fourier Transform (inverse DFT). Up to the sign and a scaling factor, the inverse DFT and the DFT are the same operation: for a vector, ifft(d) = conj(fft(d))/length(d). ifft has the same syntax as fft.

#### Examples

F = fft([1,2,3,4])
F =
10 -2+2j -2 -2-2j
ifft(F)
1 2 3 4


### ifft2

Inverse 2-d Fast Fourier Transform.

#### Syntax

f = ifft2(F)
f = ifft2(F, size)
f = ifft2(F, nr, nc)
f = ifft2(F, n)


#### Description

ifft2 returns the inverse 2-d Discrete Fourier Transform (inverse DFT along dimensions 1 and 2).

With two or three input arguments, ifft2 resizes the two first dimensions by cropping or by padding with zeros. ifft2(F,nr,nc) resizes first dimension to nr rows and second dimension to nc columns. In ifft2(F,size), the new size is given as a two-element vector [nr,nc]. ifft2(F,n) is equivalent to ifft2(F,n,n).

If the first argument is an array with more than two dimensions, ifft2 performs the inverse 2-d DFT along dimensions 1 and 2 separately for each plane along remaining dimensions; ifftn performs an inverse DFT along each dimension.

Up to the sign and a scaling factor, the inverse 2-d DFT and the 2-d DFT are the same operation. ifft2 has the same syntax as fft2.

### ifftn

Inverse n-dimension Fast Fourier Transform.

#### Syntax

f = ifftn(F)
f = ifftn(F, size)


#### Description

ifftn(F) returns the inverse n-dimension Discrete Fourier Transform of array F (inverse DFT along each dimension of F).

With two input arguments, ifftn(F,size) resizes F by cropping or by padding F with zeros.

Up to the sign and a scaling factor, the inverse n-dimension DFT and the n-dimension DFT are the same operation. ifftn has the same syntax as fftn.

### hess

Hessenberg reduction.

#### Syntax

(P,H) = hess(A)
H = hess(A)


#### Description

hess(A) reduces the square matrix A A to the upper Hessenberg form H using an orthogonal similarity transformation P*H*P'=A. The result H is zero below the first subdiagonal and has the same eigenvalues as A.

#### Example

(P,H)=hess([1,2,3;4,5,6;7,8,9])
P =
1        0       0
0       -0.4961 -0.8682
0       -0.8682  0.4961
H =
1       -3.597  -0.2481
-8.0623 14.0462  2.8308
0        0.8308 -4.6154e-2
P*H*P'
ans =
1        2       3
4        5       6
7        8       9


### inv

Inverse of a square matrix.

#### Syntax

M2 = inv(M1)


#### Description

inv(M1) returns the inverse M2 of the square matrix M1, i.e. a matrix of the same size such that M2*M1 = M1*M2 = eye(size(M1)). M1 must not be singular; otherwise, its elements are infinite.

To solve a set of linear of equations, the operator \ is more efficient.

#### Example

inv([1,2;3,4])
-2 1
1.5 -0.5


### kron

Kronecker product.

#### Syntax

M = kron(A, B)


#### Description

kron(A,B) returns the Kronecker product of matrices A (size m1 by n1) and B (size m2 by n2), i.e. an m1*m2-by-n1*n2 matrix made of m1 by n1 submatrices which are the products of each element of A with B.

#### Example

kron([1,2;3,4],ones(2))
1  1  2  2
1  1  2  2
3  3  4  4
3  3  4  4


repmat

### kurtosis

Kurtosis of a set of values.

#### Syntax

k = kurtosis(A)
k = kurtosis(A, dim)


#### Description

kurtosis(A) gives the kurtosis of the columns of array A or of the row vector A. The dimension along which kurtosis proceeds may be specified with a second argument.

The kurtosis measures how much values are far away from the mean. It is 3 for a normal distribution, and positive for a distribution which has more values far away from the mean.

#### Example

kurtosis(rand(1, 10000))
1.8055


### linprog

Linear programming.

#### Syntax

x = linprog(c, A, b)
x = linprog(c, A, b, xlb, xub)


#### Description

linprog(c,A,b) solves the following linear programming problem:

min c x
s.t. A x <= b


The optimum x is either finite, infinite if there is no bounded solution, or not a number if there is no feasible solution.

Additional arguments may be used to constrain x between lower and upper bounds. linprog(c,A,b,xlb,xub) solves the following linear programming problem:

min c x
s.t. A x <= b
x >= xlb
x <= xub


If xub is missing, there is no upper bound. xlb and xub may have less elements than x, or contain -inf or +inf; corresponding elements have no lower and/or upper bounds.

#### Examples

Maximize 3x+2y subject to x+y<=9, 3x+y<=18, x<=7, and y<=6:

c = [-3,-2];
A = [1,1; 3,1; 1,0; 0,1];
b = [9; 18; 7; 6];
x = linprog(c, A, b)
x =
4.5
4.5


A more efficient way to solve the problem, with bounds on variables:

c = [-3,-2];
A = [1,1; 3,1];
b = [9; 18];
xlb = [];
xub = [7; 6];
x = linprog(c, A, b, xlb, xub)
x =
4.5
4.5


Check that the solution is feasible and bounded:

all(isfinite(x))
true


### logm

Matrix logarithm.

#### Syntax

Y = logm(X)
(Y, err) = logm(X)


#### Description

logm(X) returns the matrix logarithm of X, the inverse of the matrix exponential. X must be square. The matrix logarithm does not always exist.

With a second output argument err, logm also returns an estimate of the relative error norm(expm(logm(X))-X)/norm(X).

#### Example

Y = logm([1,2;3,4])
Y =
-0.3504 + 2.3911j  0.9294 - 1.0938j
1.394 - 1.6406j  1.0436 + 0.7505j
expm(Y)
1 - 5.5511e-16j  2 -7.7716e-16j
3 - 8.3267e-16j  4


### lu

LU decomposition.

#### Syntax

(L, U, P) = lu(A)
(L2, U) = lu(A)
Y = lu(A)


#### Description

With three output arguments, lu(A) computes the LU decomposition of matrix A with partial pivoting, i.e. a lower triangular matrix L, an upper triangular matrix U, and a permutation matrix P such that P*A=L*U. If A in an m-by-n mytrix, L is m-by-min(m,n), U is min(m,n)-by-n and P is m-by-m. A can be rank-deficient.

With two output arguments, lu(A) permutes the lower triangular matrix and gives L2=P'*L, such that A=L2*U.

With a single output argument, lu gives Y=L+U-eye(n).

#### Example

X = [1,2,3;4,5,6;7,8,8];
(L,U,P) = lu(X)
L =
1     0     0
0.143 1     0
0.571 0.5   1
U =
7     8     8
0     0.857 1.857
0     0     0.5
P =
0 0 1
1 0 0
0 1 0
P*X-L*U
ans =
0 0 0
0 0 0
0 0 0


inv, qr, svd

### lyap

Continuous-time Lyapunov equation.

#### Syntax

X = lyap(A, B, C)
X = lyap(A, C)


#### Description

lyap(A,B,C) calculates the solution X of the following continuous-time Lyapunov equation:

AX + XB + C = 0


All matrices are real.

With two input arguments, lyap(A,C) solves the following Lyapunov equation:

AX + XA' + C = 0


#### Example

A = [3,1,2;1,3,5;6,2,1];
B = [2,7;8,3];
C = [2,1;4,5;8,9];
X = lyap(A, B, C)
X =
0.1635   -0.1244
-0.2628    0.1311
-0.7797   -0.7645


### max

Maximum value of a vector or of two arguments.

#### Syntax

x = max(v)
(v,ind) = max(v)
v = max(M,[],dim)
(v,ind) = max(M,[],dim)
M3 = max(M1,M2)


#### Description

max(v) returns the largest number of vector v. NaN's are ignored. The optional second output argument is the index of the maximum in v; if several elements have the same maximum value, only the first one is obtained. The argument type can be double, single, or integer of any size.

max(M) operates on the columns of the matrix M and returns a row vector. max(M,[],dim) operates along dimension dim (1 for columns, 2 for rows).

max(M1,M2) returns a matrix whose elements are the maximum between the corresponding elements of the matrices M1 and M2. M1 and M2 must have the same size, or be a scalar which can be compared against any matrix.

#### Examples

(mx,ix) = max([1,3,2,5,8,7])
mx =
8
ix =
5
max([1,3;5,nan], [], 2)
3
5
max([1,3;5,nan], 2)
2 3
5 2


min

### mean

Arithmetic mean of a vector.

#### Syntax

x = mean(v)
v = mean(M)
v = mean(M,dim)


#### Description

mean(v) returns the arithmetic mean of the elements of vector v. mean(M) returns a row vector whose elements are the means of the corresponding columns of matrix M. mean(M,dim) returns the mean of matrix M along dimension dim; the result is a row vector if dim is 1, or a column vector if dim is 2.

#### Examples

mean(1:5)
7.5
mean((1:5)')
7.5
mean([1,2,3;5,6,7])
3 4 5
mean([1,2,3;5,6,7],1)
3 4 5
mean([1,2,3;5,6,7],2)
2
6


### median

Median.

#### Syntax

x = median(v)
v = median(M)
v = median(M, dim)


#### Description

median(v) gives the median of vector v, i.e. the value x such that half of the elements of v are smaller and half of the elements are larger. The result is NaN if any value is NaN.

median(M) gives a row vector which contains the median of the columns of M. With a second argument, median(M,dim) operates along dimension dim.

#### Example

median([1, 2, 5, 6, inf])
5


### min

Minimum value of a vector or of two arguments.

#### Syntax

x = min(v)
(v,ind) = min(v)
v = min(M,[],dim)
(v,ind) = min(M,[],dim)
M3 = min(M1,M2)


#### Description

min(v) returns the largest number of vector v. NaN's are ignored. The optional second smallest argument is the index of the minimum in v; if several elements have the same minimum value, only the first one is obtained. The argument type can be double, single, or integer of any size.

min(M) operates on the columns of the matrix M and returns a row vector. min(M,[],dim) operates along dimension dim (1 for columns, 2 for rows).

min(M1,M2) returns a matrix whose elements are the minimum between the corresponding elements of the matrices M1 and M2. M1 and M2 must have the same size, or be a scalar which can be compared against any matrix.

#### Examples

(mx,ix) = min([1,3,2,5,8,7])
mx =
1
ix =
1
min([1,3;5,nan], [], 2)
1
5
min([1,3;5,nan], 2)
1 2
2 2


max

### moment

Central moment of a set of values.

#### Syntax

m = moment(A, order)
m = moment(A, order, dim)


#### Description

moment(A,order) gives the central moment (moment about the mean) of the specified order of the columns of array A or of the row vector A. The dimension along which moment proceeds may be specified with a third argument.

#### Example

moment(randn(1, 10000), 3)
3.011


### norm

Norm of a vector or matrix.

#### Syntax

x = norm(v)
x = norm(v,kind)
x = norm(M)
x = norm(M,kind)


#### Description

With one argument, norm calculates the 2-norm of a vector or the induced 2-norm of a matrix. The optional second argument specifies the kind of norm.

KindVectorMatrix
none or 2sqrt(sum(abs(v).^2))largest singular value
(induced 2-norm)
1sum(abs(V))largest column sum of abs
inf or 'inf'max(abs(v))largest row sum of abs
-infmin(abs(v))invalid
psum(abs(V).^p)^(1/p)invalid
'fro'sqrt(sum(abs(v).^2))sqrt(sum(diag(M'*M)))

#### Examples

norm([3,4])
5
norm([2,5;9,3])
10.2194
norm([2,5;9,3],1)
11


### null

Null space.

#### Syntax

Z = null(A)
Z = null(A, tol=tol)


#### Description

null(A) returns a matrix Z whose columns are an orthonormal basis for the null space of m-by-n matrix A. Z has n-rank(A) columns, which are the last right singular values of A; that is, those corresponding to the singular values below a small tolerance. This tolerance can be specified with a named argument tol.

Without input argument, null gives the null value (the unique value of the special null type, not related to linear algebra).

#### Example

null([1,2,3;1,2,4;1,2,5])
-0.8944
0.4472
8.0581e-17


svd, orth, null (null value)

### orth

Orthogonalization.

#### Syntax

Q = orth(A)
Q = orth(A, tol=tol)


#### Description

orth(A) returns a matrix Q whose columns are an orthonormal basis for the range of those of matrix A. Q has rank(A) columns, which are the first left singular vectors of A (that is, those corresponding to the largest singular values).

Orthogonalization is based on the singular-value decomposition, where only the singular values larger than some small threshold are considered. This threshold can be specified with an optional named argument.

#### Example

orth([1,2,3;1,2,4;1,2,5])
-0.4609 0.788
-0.5704 8.9369e-2
-0.6798 -0.6092


### pinv

Pseudo-inverse of a matrix.

#### Syntax

M2 = pinv(M1)
M2 = pinv(M1, tol)
M2 = pinv(M1, tol=tol)


#### Description

pinv(M1) returns the pseudo-inverse of matrix M. For a nonsingular square matrix, the pseudo-inverse is the same as the inverse. For an arbitrary matrix (possibly nonsquare), the pseudo-inverse M2 has the following properties: size(M2) = size(M1'), M1*M2*M1 = M1, M2*M1*M2 = M2, and the norm of M2 is minimum. The pseudo-inverse is based on the singular-value decomposition, where only the singular values larger than some small threshold are considered. This threshold can be specified with an optional second argument tol or as a named argument.

If M1 is a full-rank matrix with more rows than columns, pinv returns the least-square solution pinv(M1)*y = (M1'*M1)\M1'*y of the over-determined system M1*x = y.

#### Examples

pinv([1,2;3,4])
-2    1
1.5 -0.5
M2 = pinv([1;2])
M2 =
0.2 0.4
[1;2] * M2 * [1;2]
1
2
M2 * [1;2] * M2
0.2 0.4


### poly

Characteristic polynomial of a square matrix or polynomial coefficients based on its roots.

#### Syntax

pol = poly(M)
pol = poly(r)


#### Description

With a matrix argument, poly(M) returns the characteristic polynomial det(x*eye(size(M))-M) of the square matrix M. The roots of the characteristic polynomial are the eigenvalues of M.

With a vector argument, poly(r) returns the polynomial whose roots are the elements of the vector r. The first coefficient of the polynomial is 1. If the complex roots form conjugate pairs, the result is real.

#### Examples

poly([1,2;3,4]
1 -5 -2
roots(poly([1,2;3,4]))
5.3723
-0.3723
eig([1,2;3,4])
-0.3723
5.3723
poly(1:3)
1 -6 11 -6


### polyder

Derivative of a polynomial or a polynomial product or ratio.

#### Syntax

A1 = polyder(A)
C1 = polyder(A, B)
(N1, D1) = polyder(N, D)


#### Description

polyder(A) returns the polynomial which is the derivative of the polynomial A. Both polynomials are given as vectors of coefficients, highest power first. The result is a row vector.

With a single output argument, polyder(A,B) returns the derivative of the product of polynomials A and B. It is equivalent to polyder(conv(A,B)).

With two output arguments, (N1,D1)=polyder(N,D) returns the derivative of the polynomial ratio N/D as N1/D1. Input and output arguments are polynomial coefficients.

#### Examples

Derivative of x^3+2x^2+5x+2:

polyder([1, 2, 5, 2])
3 4 5


Derivative of (x^3+2x^2+5x+2)/(2x+3):

(N, D) = polyder([1, 2, 5, 2], [2, 3])
N =
4 13 12 11
D =
4 12  9


### polyint

Integral of a polynomial.

#### Syntax

pol2 = polyint(pol1)
pol2 = polyint(pol1, c)


#### Description

polyint(pol1) returns the polynomial which is the integral of the polynomial pol1, whose zero-order coefficient is 0. Both polynomials are given as vectors of coefficients, highest power first. The result is a row vector. A second input argument can be used to specify the integration constant.

#### Example

Y = polyint([1, 2, 3, 4, 5])
Y =
0.2   0.5   1     2     5     0
y = polyder(Y)
y =
1     2     3     4     5
Y = polyint([1, 2, 3, 4, 5], 10)
Y =
0.2   0.5   1     2     5     10


### polyval

Numeric value of a polynomial evaluated at some point.

#### Syntax

y = polyval(pol, x)


#### Description

polyval(pol,x) evaluates the polynomial pol at x, which can be a scalar or a matrix of arbitrary size. The polynomial is given as a vector of coefficients, highest power first. The result has the same size as x.

#### Examples

polyval([1,3,8], 2)
18
polyval([1,2], 1:5)
3 4 5 6 7


### prod

Product of the elements of a vector.

#### Syntax

x = prod(v)
v = prod(M)
v = prod(M,dim)


#### Description

prod(v) returns the product of the elements of vector v. prod(M) returns a row vector whose elements are the products of the corresponding columns of matrix M. prod(M,dim) returns the product of matrix M along dimension dim; the result is a row vector if dim is 1, or a column vector if dim is 2.

#### Examples

prod(1:5)
120
prod((1:5)')
120
prod([1,2,3;5,6,7])
5 12 21
prod([1,2,3;5,6,7],1)
5 12 21
prod([1,2,3;5,6,7],2)
6
210


### qr

QR decomposition.

#### Syntax

(Q, R, E) = qr(A)
(Q, R) = qr(A)
R = qr(A)
(Qe, Re, e) = qr(A, false)
(Qe, Re) = qr(A, false)
Re = qr(A, false)


#### Description

With three output arguments, qr(A) computes the QR decomposition of matrix A with column pivoting, i.e. a square unitary matrix Q and an upper triangular matrix R such that A*E=Q*R. With two output arguments, qr(A) computes the QR decomposition without pivoting, such that A=Q*R. With a single output argument, qr gives R.

With a second input argument with the value false, if A has m rows and n columns with m>n, qr produces an m-by-n Q and an n-by-n R. Bottom rows of zeros of R, and the corresponding columns of Q, are discarded. With column pivoting, the third output argument e is a permutation vector: A(:,e)=Q*R.

#### Example

(Q,R) = qr([1,2;3,4;5,6])
Q =
-0.169     0.8971   0.4082
-0.5071    0.276   -0.8165
-0.8452   -0.345    0.4082
R =
-5.9161   -7.4374
0    0.8281
0         0
(Q,R) = qr([1,2;3,4;5,6],false)
Q =
0.169     0.8971
0.5071    0.276
0.8452   -0.345
R =
5.9161    7.4374
0         0.8281


### rank

Rank of a matrix.

#### Syntax

x = rank(M)
x = rank(M, tol)
x = rank(M, tol=tol)


#### Description

rank(M) returns the rank of matrix M, i.e. the number of lines or columns linearly independent. To obtain it, the singular values are computed and the number of values significantly larger than 0 is counted. The value below which they are considered to be 0 can be specified with the optional second argument or named argument.

#### Examples

rank([1,1;0,0])
1
rank([1,1;0,1j])
2


### roots

Roots of a polynomial.

#### Syntax

r = roots(pol)
r = roots(M)
r = roots(M,dim)


#### Description

roots(pol) calculates the roots of the polynomial pol. The polynomial is given by the vector of its coefficients, highest power first, while the result is a column vector.

With a matrix as argument, roots(M) calculates the roots of the polynomials corresponding to each column of M. An optional second argument is used to specify in which dimension roots operates (1 for columns, 2 for rows). The roots of the i:th polynomial are in the i:th column of the result, whatever the value of dim is.

#### Examples

roots([1, 0, -1])
1
-1
roots([1, 0, -1]')
1
-1
roots([1, 1; 0, 5; -1, 6])
1 -2
-1 -3
roots([1, 0, -1]', 2)
[]


### schur

Schur factorization.

#### Syntax

(U,T) = schur(A)
T = schur(A)
(U,T) = schur(A, 'c')
T = schur(A, 'c')


#### Description

schur(A) computes the Schur factorization of square matrix A, i.e. a unitary matrix U and a square matrix T (the Schur matrix) such that A=U*T*U'. If A is complex, the Schur matrix is upper triangular, and its diagonal contains the eigenvalues of A; if A is real, the Schur matrix is real upper triangular, except that there may be 2-by-2 blocks on the main diagonal which correspond to the complex eigenvalues of A. To force a complex Schur factorization with an upper triangular matrix T, schur is given a second input argument 'c' or 'complex'.

#### Examples

Schur factorization:

A = [1,2;3,4];
(U,T) = schur(A)
U =
-0.8246   -0.5658
0.5658   -0.8246
T =
-0.3723   -1
0    5.3723


Since T is upper triangular, its diagonal contains the eigenvalues of A:

eig(A)
ans =
-0.3723
5.3723


For a matrix with complex eigenvalues, the real Schur factorization has 2x2 blocks on its diagonal:

T = schur([1,0,0;0,1,2;0,-3,1])
T =
1     0     0
0     1     2
0    -3     1
T = schur([1,0,0;0,1,2;0,-3,1],'c')
T =
1             0             0
0             1 + 2.4495j   1
0             0             1 - 2.4495j


lu, hess, qr, eig

### skewness

Skewness of a set of values.

#### Syntax

s = skewness(A)
s = skewness(A, dim)


#### Description

skewness(A) gives the skewness of the columns of array A or of the row vector A. The dimension along which skewness proceeds may be specified with a second argument.

The skewness measures how asymmetric a distribution is. It is 0 for a symmetric distribution, and positive for a distribution which has more values much larger than the mean.

#### Example

skewness(randn(1, 10000).^2)
2.6833


### sqrtm

Matrix square root.

#### Syntax

Y = sqrtm(X)
(Y, err) = sqrtm(X)


#### Description

sqrtm(X) returns the matrix square root of X, such that sqrtm(X)^2=X. X must be square. The matrix square root does not always exist.

With a second output argument err, sqrtm also returns an estimate of the relative error norm(sqrtm(X)^2-X)/norm(X).

#### Example

Y = sqrtm([1,2;3,4])
Y =
0.5537 + 0.4644j   0.807 - 0.2124j
1.2104 - 0.3186j  1.7641 + 0.1458j
Y^2
1   2
3   4


### std

Standard deviation.

#### Syntax

x = std(v)
x = std(v, p)
v = std(M)
v = std(M, p)
v = std(M, p, dim)


#### Description

std(v) gives the standard deviation of vector v, normalized by length(v)-1. With a second argument, std(v,p) normalizes by length(v)-1 if p is false, or by length(v) if p is true.

std(M) gives a row vector which contains the standard deviation of the columns of M. With a third argument, std(M,p,dim) operates along dimension dim.

#### Example

std([1, 2, 5, 6, 10, 12])
4.3359


### sum

Sum of the elements of a vector.

#### Syntax

x = sum(v)
v = sum(M)
v = sum(M,dim)


#### Description

sum(v) returns the sum of the elements of vector v. sum(M) returns a row vector whose elements are the sums of the corresponding columns of matrix M. sum(M,dim) returns the sum of matrix M along dimension dim; the result is a row vector if dim is 1, or a column vector if dim is 2.

#### Examples

sum(1:5)
15
sum((1:5)')
15
sum([1,2,3;5,6,7])
6 8 10
sum([1,2,3;5,6,7],1)
6 8 10
sum([1,2,3;5,6,7],2)
6
18


### svd

Singular value decomposition.

#### Syntax

s = svd(M)
(U,S,V) = svd(M)
(U,S,V) = svd(M,false)


#### Description

The singular value decomposition (U,S,V) = svd(M) decomposes the m-by-n matrix M such that M = U*S*V', where S is an m-by-n diagonal matrix with decreasing positive diagonal elements (the singular values of M), U is an m-by-m unitary matrix, and V is an n-by-n unitary matrix. The number of non-zero diagonal elements of S (up to rounding errors) gives the rank of M.

When M is rectangular, in expression U*S*V', some columns of U or V are multiplied by rows or columns of zeros in S, respectively. (U,S,V) = svd(M,false) produces U, S and V where these columns or rows are discarded (relationship M = U*S*V' still holds):

Size of A Size of U Size of S Size of V
m by n, m <= nm by mm by mn by m
m by n, m > nm by nn by nn by n

svd(M,true) produces the same result as svd(M).

With one output argument, s = svd(M) returns the vector of singular values s=diag(S).

The singular values of M can also be computed with s = sqrt(eig(M'*M)), but svd is faster and more robust.

#### Examples

(U,S,V)=svd([1,2;3,4])
U =
0.4046 0.9145
0.9145 -0.4046
S =
5.465 0
0 0.366
V =
0.576 -0.8174
0.8174 0.576
U*S*V'
1 2
3 4
svd([1,2;1,2])
3.1623
3.4697e-19


### trace

Trace of a matrix.

#### Syntax

tr = trace(M)


#### Description

trace(M) returns the trace of the matrix M, i.e. the sum of its diagonal elements.

#### Example

trace([1,2;3,4])
5


### var

Variance of a set of values.

#### Syntax

s2 = var(A)
s2 = var(A, p)
s2 = var(A, p, dim)


#### Description

var(A) gives the variance of the columns of array A or of the row vector A. The variance is normalized with the number of observations minus 1, or by the number of observations if a second argument is true. The dimension along which var proceeds may be specified with a third argument.