en fr

Disponible uniquement en anglais

Sysquake Pro – Table of Contents

Sysquake – Table of Contents

Sysquake for LaTeX – Table of Contents

Array Functions

arrayfun

Function evaluation for each element of an array.

Syntax

(B1, ...) = arrayfun(fun, A1, ...)

Description

arrayfun(fun,A) evaluates function fun for each element of numeric array A. Each evaluation must give a scalar result of numeric (or logical or char) type; results are returned as a numeric array the same size as A. First argument is a function reference, an inline function, or the name of a function as a string.

With more than two input arguments, arrayfun calls function fun as feval(fun,A1(i),A2(i),...). All array arguments must have the same size, but their type can be different.

With two output arguments or more, arrayfun evaluates function fun with the same number of output arguments and builds a separate array for each output. Without output argument, arrayfun evaluates fun without output argument.

arrayfun differs from cellfun: all input arguments of arrayfun are arrays of any type (not necessarily cell arrays), and corresponding elements are provided provided to fun. With map, input arguments as well as output arguments are cell arrays.

Examples

arrayfun(@isempty, {1, ''; {}, ones(5)})
  F T
  T F
map(@isempty, {1, ''; {}, ones(5)})
  2x2 cell array
(m, n) = arrayfun(@size, {1, ''; {}, ones(2, 5)})
  m =
    1  0
    0  2
  n =
    1  0
    0  5

See also

cellfun, map, fevalx

cat

Array concatenation.

Syntax

cat(dim, A1, A2, ...)

Description

cat(dim,A1,A2,...) concatenates arrays A1, A2, etc. along dimension dim. Other dimensions must match. cat is a generalization of the comma and the semicolon inside brackets.

Examples

cat(2, [1,2;3,4], [5,6;7,8])
  1  2  5  6
  3  4  7  8
cat(3, [1,2;3,4], [5,6;7,8])
  2x2x2 array
    (:,:,1) =
      1  2
      3  4
    (:,:,2) =
      5  6
      7  8

See also

operator [], operator ;, operator ,

cell

Cell array of empty arrays.

Syntax

C = cell(n)
C = cell(n1,n2,...)
C = cell([n1,n2,...])

Description

cell builds a cell array whose elements are empty arrays []. The size of the cell array is specified by one integer for a square array, or several integers (either as separate arguments or in a vector) for a cell array of any size.

Example

cell(2, 3)
  2x3 cell array

See also

zeros, operator {}, iscell

cellfun

Function evaluation for each cell of a cell array.

Syntax

A = cellfun(fun, C)
A = cellfun(fun, C, ...)
A = cellfun(fun, S)
A = cellfun(fun, S, ...)

Description

cellfun(fun,C) evaluates function fun for each cell of cell array C. Each evaluation must give a scalar result of numeric, logical, or character type; results are returned as a non-cell array the same size as C. First argument is a function reference, an inline function, or the name of a function as a string.

With more than two input arguments, cellfun calls function fun as feval(fun,C{i},other), where C{i} is each cell of C in turn, and other stands for the remaining arguments of cellfun.

The second argument can be a structure array S instead of a cell array. In that case, fun is called with S(i).

cellfun differs from map in two ways: the result is a non-cell array, and remaining arguments of cellfun are provided directly to fun.

Examples

cellfun(@isempty, {1, ''; {}, ones(5)})
  F T
  T F
map(@isempty, {1, ''; {}, ones(5)})
  2x2 cell array
cellfun(@size, {1, ''; {}, ones(5)}, 2)
  1 0
  0 5

See also

map, arrayfun

diag

Creation of a diagonal matrix or extraction of the diagonal elements of a matrix.

Syntax

M = diag(v)
M = diag(v,k)
v = diag(M)
v = diag(M,k)

Description

With a vector input argument, diag(v) creates a square diagonal matrix whose main diagonal is given by v. With a second argument, the diagonal is moved by that amount in the upper right direction for positive values, and in the lower left direction for negative values.

With a matrix input argument, the main diagonal is extracted and returned as a column vector. A second argument can be used to specify another diagonal.

Examples

diag(1:3)
  1 0 0
  0 2 0
  0 0 3
diag(1:3,1)
  0 1 0 0
  0 0 2 0
  0 0 0 3
  0 0 0 0
M = magic(3)
M =
  8 1 6
  3 5 7
  4 9 2
diag(M)
  8
  5
  2
diag(M,1)
  1
  7

See also

tril, triu, eye, trace

eye

Identity matrix.

Syntax

M = eye(n)
M = eye(m,n)
M = eye([m,n])
M = eye(..., type)

Description

eye builds a matrix whose diagonal elements are 1 and other elements 0. The size of the matrix is specified by one integer for a square matrix, or two integers (either as two arguments or in a vector of two elements) for a rectangular matrix.

An additional input argument can be used to specify the type of the result. It must be the string 'double', 'single', 'int8', 'int16', 'int32', 'int64', 'uint8', 'uint16', 'uint32', or 'uint64' (64-bit arrays are not supported on all platforms).

Examples

eye(3)
  1 0 0
  0 1 0
  0 0 1
eye(2, 3)
  1 0 0
  0 1 0
eye(2, 'int8')
  2x2 int8 array
    1 0
    0 1

See also

ones, zeros, diag

fevalx

Function evaluation with array expansion.

Syntax

(Y1,...) = fevalx(fun,X1,...)

Description

(Y1,Y2,...)=fevalx(fun,X1,X2,...) evaluates function fun with input arguments X1, X2, etc. Arguments must be arrays, which are expanded if necessary along singleton dimensions so that all dimensions match. For instance, three arguments of size 3x1x2, 1x5 and 1x1 are replicated into arrays of size 3x5x2. Output arguments are assigned to Y1, Y2, etc. Function fun is specified either by its name as a string, by a function reference, or by an inline or anonymous function.

Example

fevalx(@plus, 1:5, (10:10:30)')
    11    12    13    14    15
    21    22    23    24    25
    31    32    33    34    35

See also

feval, meshgrid, repmat, inline, operator @

find

Find the indices of the non-null elements of an array.

Syntax

ix = find(v)
[s1,s2] = find(M)
[s1,s2,x] = find(M)
... = find(..., n)
... = find(..., n, dir)

Description

With one output argument, find(v) returns a vector containing the indices of the nonzero elements of v. v can be an array of any dimension; the indices correspond to the internal storage ordering and can be used to access the elements with a single subscript.

With two output arguments, find(M) returns two vectors containing the subscripts (row in the first output argument, column in the second output argument) of the nonzero elements of 2-dim array M. To obtain subscripts for an array of higher dimension, you can convert the single output argument of find to subscripts with ind2sub.

With three output arguments, find(M) returns in addition the nonzero values themselves in the third output argument.

With a second input argument n, find limits the maximum number of elements found. It searches forward by default; with a third input argument dir, find gives the n first nonzero values if dir is 'first' or 'f', and the n last nonzero values if dir is 'last' or 'l'.

Examples

ix = find([1.2,0;0,3.6])
ix =
  1
  4
[s1,s2] = find([1.2,0;0,3.6])
s1 =
  1
  2
s2 =
  1
  2
[s1,s2,x] = find([1.2,0;0,3.6])
s1 =
  1
  2
s2 =
  1
  2
x =
  1.2
  3.6
A = rand(3)
  A =
    0.5599    0.3074    0.5275
    0.3309    0.8077    0.3666
    0.7981    0.6424    0.6023
find(A > 0.7, 2, 'last')
  7
  5

See also

nnz, sort

flipdim

Flip an array along any dimension.

Syntax

B = flipdim(A, dim)

Description

flipdim(A,dim) gives an array which has the same size as A, but where indices of dimension dim are reversed.

Examples

flipdim(cat(3, [1,2;3,4], [5,6;7,8]), 3)
  2x2x2 array
    (:,:,1) =
      5  6
      7  8
  (:,:,2) =
      1  2
      3  4

See also

fliplr, flipud, rot90, reshape

fliplr

Flip an array or a list around its vertical axis.

Syntax

A2 = fliplr(A1)
list2 = fliplr(list1)

Description

fliplr(A1) gives an array A2 which has the same size as A1, but where all columns are placed in reverse order.

fliplr(list1) gives a list list2 which has the same length as list1, but where all top-level elements are placed in reverse order. Elements themselves are left unchanged.

Examples

fliplr([1,2;3,4])
  2 1
  4 3
fliplr({1, 'x', {1,2,3}})
  {{1,2,3}, 'x', 1}

See also

flipud, flipdim, rot90, reshape

flipud

Flip an array upside-down.

Syntax

A2 = flipud(A1)

Description

flipud(A1) gives an array A2 which has the same size as A1, but where all lines are placed in reverse order.

Example

flipud([1,2;3,4])
  3 4
  1 2

See also

fliplr, flipdim, rot90, reshape

ind2sub

Conversion from single index to row/column subscripts.

Syntax

(i, j, ...) = ind2sub(size, ind)

Description

ind2sub(size,ind) gives the subscripts of the element which would be retrieved from an array whose size is specified by size by the single index ind. size must be either a scalar for square matrices or a vector of two elements or more for arrays. ind can be an array; the result is calculated separately for each element and has the same size.

Example

M = [3, 6; 8, 9];
M(3)
  8
(i, j) = ind2sub(size(M), 3)
  i =
    2
  j =
    1
M(i, j)
  8

See also

sub2ind, size

interp1

1D interpolation.

Syntax

yi = interp1(x, y, xi)
yi = interp1(x, y, xi, method)
yi = interp1(y, xi)
yi = interp1(y, xi, method)
yi = interp1(..., method, extraval)

Description

interp1(x,y,xi) interpolates data along one dimension. Input data are defined by vector y, where element y(i) corresponds to coordinates x(i). Interpolation is performed at points defined in vector xi; the result is a vector of the same size as xi.

If y is an array, interpolation is performed along dimension 1 (i.e. along its columns), and size(y,1) must be equal to length(x). Then if xi is a vector, interpolation is performed at the same points for each remaining dimensions of y, and the result is an array of size [length(xi),size(y)(2:end)]; if xi is an array, all sizes must match y except for the first one.

If x is missing, it defaults to 1:size(y,1).

The default interpolation method is piecewise linear. An additional input argument can be provided to specify it with a string (only the first character is considered):

ArgumentMeaning
'0' or 'nearest'nearest value
'<'lower coordinate
'>'higher coordinate
'1' or 'linear'piecewise linear
'3' or 'cubic'piecewise cubic
'p' or 'pchip'pchip

Cubic interpolation gives continuous values and first derivatives, and null second derivatives at end points. Pchip (piecewise cubic Hermite interpolation) also gives continuous values and first derivatives, but guarantees that the interpolant stays within the limits of the data in each interval (in particular monotonicity is preserved) at the cost of larger second derivatives.

With vectors, interp1 produces the same result as interpn; vector orientations do not have to match, though.

When the method is followed by a scalar number extraval, that value is assigned to all values outside the range defined by x (i.e. extrapolated values). The default is NaN.

Examples

One-dimension interpolation:

interp1([1, 2, 5, 8], [0.1, 0.2, 0.5, 1], [0, 2, 3, 7])
  nan   0.2000   0.3000   0.8333
interp1([1, 2, 5, 8], [0.1, 0.2, 0.5, 1], [0, 2, 3, 7], '0')
  nan   0.2000   0.2000   1.0000

Interpolation of multiple values:

t = 0:10;
y = [sin(t'), cos(t')];
tnew = 0:0.4:8;
ynew = interp1(t, y, tnew)
  ynew =
    0.0000  1.0000
    0.3366  0.8161
    ...
    0.8564  0.2143
    0.9894 -0.1455

See also

interpn

interpn

Multidimensional interpolation.

Syntax

Vi = interpn(x1, ..., xn, V, xi1, ..., xin)
Vi = interpn(x1, ..., xn, V, xi1, ..., xin, method)
Vi = interpn(..., method, extraval)

Description

interpn(x1,...,xn,V,xi1,...,xin) interpolates data in a space of n dimensions. Input data are defined by array V, where element V(i,j,...) corresponds to coordinates x1(i), x2(j), etc. Interpolation is performed for each coordinates defined by arrays xi1, xi2, etc., which must all have the same size; the result is an array of the same size.

Length of vectors x1, x2, ... must match the size of V along the corresponding dimension. Vectors x1, x2, ... must be sorted (monotonically increasing or decreasing), but they do not have to be spaced uniformly. Interpolated points outside the input volume are set to nan. Input and output data can be complex. Imaginary parts of coordinates are ignored.

The default interpolation method is multilinear. An additional input argument can be provided to specify it with a string (only the first character is considered):

ArgumentMeaning
'0' or 'nearest'nearest value
'<'lower coordinates
'>'higher coordinates
'1' or 'linear'multilinear

Method '<' takes the sample where each coordinate has its index as large as possible, lower or equal to the interpolated value, and smaller than the last coordinate. Method '>' takes the sample where each coordinate has its index greater or equal to the interpolated value.

When the method is followed by a scalar number extraval, that value is assigned to all values outside the input volume (i.e. extrapolated values). The default is NaN.

Examples

One-dimension interpolation:

interpn([1, 2, 5, 8], [0.1, 0.2, 0.5, 1], [0, 2, 3, 7])
  nan   0.2000   0.3000   0.8333
interpn([1, 2, 5, 8], [0.1, 0.2, 0.5, 1], [0, 2, 3, 7], '0')
  nan   0.2000   0.2000   1.0000

Three-dimension interpolation:

D = cat(3,[0,1;2,3],[4,5;6,7]);
interpn([0,1], [0,1], [0,1], D, 0.2, 0.7, 0.5)
  3.1000

Image rotation (we define original coordinates between -0.5 and 0.5 in vector c and arrays X and Y, and the image as a linear gradient between 0 and 1):

c = -0.5:0.01:0.5;
X = repmat(c, 101, 1);
Y = X';
phi = 0.2;
Xi = cos(phi) * X - sin(phi) * Y;
Yi = sin(phi) * X + cos(phi) * Y;
D = 0.5 + X;
E = interpn(c, c, D, Xi, Yi);
E(isnan(E)) = 0.5;

See also

interp1

intersect

Set intersection.

Syntax

c = intersect(a, b)
(c, ia, ib) = intersect(a, b)

Description

intersect(a,b) gives the intersection of sets a and b, i.e. it gives the set of members of both sets a and b. Sets are any type of numeric, character or logical arrays, or lists or cell arrays of character strings. Multiple elements of input arguments are considered as single members; the result is always sorted and has unique elements.

The optional second and third output arguments are vectors of indices such that if (c,ia,ib)=intersect(a,b), then c is a(ia) as well as b(ib).

Example

a = {'a','bc','bbb','de'};
b = {'z','bc','aa','bbb'};
(c, ia, ib) = intersect(a, b)
  c =
    {'bbb','bc'}
  ia =
    3 2
  ib =
    4 2
a(ia)
  {'bbb','bc'}
b(ib)
  {'bbb','bc'}

Set exclusive or can also be computed as the union of a and b minus the intersection of a and b:

setdiff(union(a, b), intersect(a, b))
  {'a','aa','de','z'}

See also

unique, union, setdiff, setxor, ismember

inthist

Histogram of an integer array.

Syntax

h = inthist(A, n)

Description

inthist(A,n) computes the histogram of the elements of integer array A between 0 and n-1. A must have an integer type (int8/16/32/64 or uint8/16/32/64). The result is a row vector h of length n, where h(i) is the number of elements in A with value i-1.

Example

A = map2int(rand(100), 0, 1, 'uint8');
h = inthist(A, 10)
  h =
    37 31 34 34 32 35 38 36 36 32

See also

hist

ipermute

Inverse permutation of the dimensions of an array.

Syntax

B = ipermute(A, perm)

Description

ipermute(A,perm) returns an array with the same elements as A, but where dimensions are permuted according to the vector of dimensions perm. It performs the inverse permutation of permute. perm must contain integers from 1 to n; dimension i in A becomes dimension perm(i) in the result.

Example

size(ipermute(rand(3,4,5), [2,3,1]))
  5 3 4

See also

permute, ndims, squeeze

isempty

Test for empty array, list or struct.

Syntax

b = isempty(A)
b = isempty(list)
b = isempty(S)

Description

isempty(obj) gives true if obj is the empty array [] of any type (numeric, char, logical or cell array) or the empty struct, and false otherwise.

Examples

isempty([])
  true
isempty(0)
  false
isempty('')
  true
isempty({})
  true
isempty({{}})
  false
isempty(struct)
  true

See also

size, length

iscell

Test for cell arrays.

Syntax

b = iscell(X)

Description

iscell(X) gives true if X is a cell array or a list, and false otherwise.

Examples

iscell({1;2})
  true
iscell({1,2})
  true
islist({1;2})
  false

See also

islist

ismember

Test for set membership.

Syntax

b = ismember(m, s)
(b, ix) = ismember(m, s)

Description

ismember(m,s) tests if elements of array m are members of set s. The result is a logical array the same size as m; each element is true if the corresponding element of m is a member of s, or false otherwise. m must be a numeric array or a cell array, matching type of set s.

With a second output argument ix, ismember also gives the index of the corresponding element of m in s, or 0 if the element is not a member of s.

Example

s = {'a','bc','bbb','de'};
m = {'d','a','x';'de','a','z'};
(b, ix) = ismember(m, s)
  b =
    F T F
    T T F
  ix =
    0 1 0
	4 1 0

See also

intersect, union, setdiff, setxor

length

Length of a vector or a list.

Syntax

n = length(v)
n = length(list)

Description

length(v) gives the length of vector v. length(A) gives the number of elements along the largest dimension of array A. length(list) gives the number of elements in a list.

Examples

length(1:5)
  5
length((1:5)')
  5
length(ones(2,3))
  3
length({1, 1:6, 'abc'})
  3
length({{}})
  1

See also

size, numel, end

linspace

Sequence of linearly-spaced elements.

Syntax

v = linspace(x1, x2)
v = linspace(x1, x2, n)

Description

linspace(x1,x2) produces a row vector of 50 values spaced linearly from x1 to x2 inclusive. With a third argument, linspace(x1,x2,n) produces a row vector of n values.

Examples

linspace(1,10)
  1.0000 1.1837 1.3673 ... 9.8163 10.0000
linspace(1,2,6)
  1.0  1.2  1.4  1.6  1.8  2.0

See also

logspace, operator :

logspace

Sequence of logarithmically-spaced elements.

Syntax

v = logspace(x1, x2)
v = logspace(x1, x2, n)

Description

logspace(x1,x2) produces a row vector of 50 values spaced logarithmically from 10^x1 to 10^x2 inclusive. With a third argument, logspace(x1,x2,n) produces a row vector of n values.

Example

logspace(0,1)
  1.0000 1.0481 1.0985 ... 9.1030 9.5410 10.0000

See also

linspace, operator :

magic

Magic square.

Syntax

M = magic(n)

Description

A magic square is a square array of size n-by-n which contains each integer between 1 and n^2, and whose sum of each column and of each line is equal. magic(n) returns magic square of size n-by-n.

There is no 2-by-2 magic square. If the size is 2, the matrix [1,3;4,2] is returned instead.

Example

magic(3)
  8 1 6
  3 5 7
  4 9 2

See also

zeros, ones, eye, rand, randn

meshgrid

Arrays of X-Y coordinates.

Syntax

(X, Y) = meshgrid(x, y)
(X, Y) = meshgrid(x)

Description

meshgrid(x,y) produces two arrays of x and y coordinates suitable for the evaluation of a function of two variables. The input argument x is copied to the rows of the first output argument, and the input argument y is copied to the columns of the second output argument, so that both arrays have the same size. meshgrid(x) is equivalent to meshgrid(x,x).

Example

(X, Y) = meshgrid(1:5, 2:4)
  X =
    1  2  3  4  5
    1  2  3  4  5
    1  2  3  4  5
  Y =
    2  2  2  2  2
    3  3  3  3  3
    4  4  4  4  4
Z = atan2(X, Y)
  Z =
    0.4636    0.7854    0.9828    1.1071    1.1903
    0.3218    0.5880    0.7854    0.9273    1.0304
    0.2450    0.4636    0.6435    0.7854    0.8961

See also

ndgrid, repmat

ndgrid

Arrays of N-dimension coordinates.

Syntax

(X1, ..., Xn) = ndgrid(x1, ..., xn)
(X1, ..., Xn) = ndgrid(x)

Description

ndgrid(x1,...,xn) produces n arrays of n dimensions. Array i is obtained by reshaping input argument i as a vector along dimension i and replicating it along all other dimensions to match the length of other input vectors. All output arguments have the same size.

With one input argument, ndgrid reuses it to match the number of output arguments.

(Y,X)=ndgrid(y,x) is equivalent to (X,Y)=meshgrid(x,y).

Example

(X1, X2) = ndgrid(1:3)
  X1 =
    1   1   1
    2   2   2
    3   3   3
  X2 =
    1   2   3
    1   2   3
    1   2   3

See also

meshgrid, repmat

ndims

Number of dimensions of an array.

Syntax

n = ndims(A)

Description

ndims(A) returns the number of dimensions of array A, which is at least 2. Scalars, row and column vectors, and matrices have 2 dimensions.

Examples

ndims(magic(3))
  2
ndims(rand(3,4,5))
  3

See also

size, squeeze, permute, ipermute

nnz

Number of nonzero elements.

Syntax

n = nnz(A)

Description

nnz(A) returns the number of nonzero elements of array A. Argument A must be a numeric, char or logical array.

Examples

nnz(-2:2)
  4
nnz(magic(3) > 3)
  6

See also

find

num2cell

Conversion from numeric array to cell array.

Syntax

C = num2cell(A)
C = num2cell(A, dims)

Description

num2cell(A) creates a cell array the same size as numeric array A. The value of each cell is the corresponding elements of A.

num2cell(A,dims) cuts array A along the dimensions not in dims and creates a cell array with the result. Dimensions of cell array are the same as dimensions of A for dimensions not in dims, and 1 for dimensions in dims; dimensions of cells are the same as dimensions of A for dimensions in dims, and 1 for dimensions not in dims.

Argument A can be a numeric array of any dimension and class, a logical array, or a char array.

Examples

num2cell([1, 2; 3, 4])
  {1, 2; 3, 4}
num2cell([1, 2; 3, 4], 1)
  {[1; 3], [2; 4]}
num2cell([1, 2; 3, 4], 2)
  {[1, 2]; [3, 4]}

See also

num2list, permute

numel

Number of elements of an array.

Syntax

n = numel(A)

Description

numel(A) gives the number of elements of array A. It is equivalent to prod(size(A)).

Examples

numel(1:5)
  5
numel(ones(2, 3))
  6
numel({1, 1:6; 'abc', []})
  4
numel({2, 'vwxyz'})
  2

See also

size, length

ones

Array of ones.

Syntax

A = ones(n)
A = ones(n1, n2, ...)
A = ones([n1, n2, ...])
A = ones(..., type)

Description

ones builds an array whose elements are 1. The size of the array is specified by one integer for a square matrix, or several integers (either as separate arguments or in a vector) for an array of any size.

An additional input argument can be used to specify the type of the result. It must be the string 'double', 'single', 'int8', 'int16', 'int32', 'int64', 'uint8', 'uint16', 'uint32', or 'uint64' (64-bit arrays are not supported on all platforms).

Examples

ones(2,3)
  1 1 1
  1 1 1
ones(2, 'int32')
  2x2 int32 array
    1 1
    1 1

See also

zeros, eye, rand, randn, repmat

permute

Permutation of the dimensions of an array.

Syntax

B = permute(A, perm)

Description

permute(A,perm) returns an array with the same elements as A, but where dimensions are permuted according to the vector of dimensions perm. It is a generalization of the matrix transpose operator. perm must contain integers from 1 to n; dimension perm(i) in A becomes dimension i in the result.

Example

size(permute(rand(3,4,5), [2,3,1]))
  4 5 3

See also

ndims, squeeze, ipermute, num2cell

rand

Uniformly-distributed random number.

Syntax

x = rand
A = rand(n)
A = rand(n1, n2, ...)
A = rand([n1, n2, ...])
A = rand(..., type)
rand('seed', s);

Description

rand builds a scalar pseudo-random number uniformly distributed between 0 and 1. The lower bound 0 may be reached, but the upper bound 1 is never. The default generator is based on a scalar 64-bit seed, which theoretically has a period of 2^64-2^32 numbers. This seed can be set with the arguments rand('seed',s), where s is a scalar. rand('seed',s) returns the empty array [] as output argument. To discard it, the statement should be followed by a semicolon. The generator can be changed with rng.

rand(n), rand(n1,n2,...) and rand([n1,n2,...]) return an n-by-n square array or an array of arbitrary size whose elements are pseudo-random numbers uniformly distributed between 0 and 1.

An additional input argument can be used to specify the type of the result, 'double' (default) or 'single'. With the special value 'raw', rand returns an unscaled integer result of type double which corresponds to the uniform output of the random generator before it is mapped to the range between 0 and 1. The scaling factor can be retrieved in the field rawmax of the structure returned by rng.

Examples

rand
  0.2361
rand(1, 3)
  0.6679 0.8195 0.2786
rand('seed',0);
rand
  0.2361

See also

randn, randi, rng

randi

Uniformly-distributed integer random number.

Syntax

x = randi(nmax)
x = randi(range)
M = randi(..., n)
M = randi(..., n1, n2, ...)
M = randi(..., [n1, n2, ...])
M = randi(..., class)

Description

randi(nmax) produces a scalar pseudo-random integer number uniformly distributed between 1 and nmax. randi(range), where range is a two-element vector [nmin,nmax], produces a scalar pseudo-random integer number uniformly distributed between nmin and nmax.

With more numeric input arguments, randi produces arrays of pseudo-random integer numbers. randi(range,n) produces an n-by-n square array, and randi(range,[n1,n2,...]) or randi(range,n1,n2,...) produces an array of the specified size.

The number class of the result can be specified with a final string argument. The default is 'double'.

Examples

randi(10)
  3
randi(10, [1, 5])
  3 4 6 8 1
randi([10,15], [1, 5])
  12 14 13 10 13
randi(8, [1, 5], 'uint8')
  1x5 uint8 array
    3 4 5 7 2

See also

rand, randn, rng

randn

Normally-distributed random number

Syntax

x = randn
A = randn(n)
A = randn(n1, n2, ...)
A = randn([n1, n2, ...])
A = randn(..., type)
randn('seed', s);

Description

randn builds a scalar pseudo-random number chosen from a normal distribution with zero mean and unit variance. The default generator is based on a scalar 64-bit seed, which theoretically has a period of 2^64-2^32 numbers. This seed can be set with the arguments randn('seed',s), where s is a scalar. The seed is the same as the seed of rand and rng. randn('seed',s) returns the empty array [] as output argument. To discard it, the statement should be followed by a semicolon. The generator can be changed with rng.

randn(n), randn(n1,n2,...) and randn([n1,n2,...]) return an n-by-n square array or an array of arbitrary size whose elements are pseudo-random numbers chosen from a normal distribution.

An additional input argument can be used to specify the type of the result. It must be the string 'double' (default) or 'single'.

Examples

randn
  1.5927
randn(1, 3)
  0.7856 0.6489 -0.8141
randn('seed',0);
randn
  1.5927

See also

rand, randi, rng

repmat

Replicate an array.

Syntax

B = repmat(A, n)
B = repmat(A, m, n)
B = repmat(A, [n1,...])

Description

repmat creates an array with multiple copies of its first argument. It can be seen as an extended version of ones, where 1 is replaced by an arbitrary array.

With 3 input arguments, repmat(A,m,n) replicates array A m times vertically and n times horizontally. The type of the first argument (number, character, logical, cell, or structure array) is preserved.

With two input arguments, repmat(A,n) produces the same result as repmat(A,n,n).

With a vector as second argument, the array can be replicated along more than two dimensions; repmat(A,m,n) produces the same result as repmat(A,[m,n]).

Examples

repmat([1,2;3,4], 1, 2)
  1 2 1 2
  3 4 3 4
repmat('abc', 3)
  abcabcabc
  abcabcabc
  abcabcabc

See also

zeros, ones, operator :, kron, replist

reshape

Rearrange the elements of an array to change its shape.

Syntax

A2 = reshape(A1)
A2 = reshape(A1, n1, n2, ...)
A2 = reshape(A1, [n1, n2, ...])

Description

reshape(A1) gives a column vector with all the elements of array A1. If A1 is a variable, reshape(A1) is the same as A1(:).

reshape(A1,n1,n2,...) or reshape(A1,[n1,n2,...]) changes the dimensions of array A1 so that the result has m rows and n columns. A1 must have n1*n2*... elements; read row-wise, both A1 and the result have the same elements.

When dimensions are given as separate elements, one of them can be replaced with the empty array []; it is replaced by the value such that the number of elements of the result matches the size of input array.

Remark: code should not rely on the internal data layout. Array elements are currently stored row-wise, but this may change in the future. reshape will remain consistant with indexing, though; reshape(A,s)(i)==A(i) for any compatible size s.

Example

reshape([1,2,3;10,20,30], 3, 2)
  1  2
  3  10
  20 30
reshape(1:12, 3, [])
  1  2  3  4
  5  6  7  8
  9 10 11 12

See also

operator ()

rng

State of random number generator.

Syntax

rng(type)
rng(seed)
rng(seed, type)
rng(state)
state = rng

Description

Random (actually pseudo-random) number generators produce sequences of numbers whose statistics make them difficult to distinguish from true random numbers. They are used by functions rand, randi, randn and random. They are characterized by a type string and a state.

With a numeric input argument, rng(seed) sets the state based on a seed. The state is usually an array of unsigned 32-bit integer numbers. rng uses the seed to produce an internal state which is valid for the type of random number generator. The default seed is 0.

With a string input argument, rng(type) sets the type of the random number generator and resets the state to its initial value (default seed). The following types are recognized:

'original'
Original generator used until LME 6.
'mcg16807'
Multiplicative congruential generator. The state is defined by s(i+1)=mod(a*s(i),m) with a=7^5 and m=2^31-1, and the generated value is s(i)/m.
'mwc'
Concatenation of two 16-bit multiply-with-carry generators. The period is about 2^60.
'kiss' or 'default'
Combination of mwc, a 3-shift register, and a congruential generator. The period is about 2^123.

With two input arguments, rng(seed,type) sets both the seed and the type of the random number generator.

With an output argument, state=rng gets the current state, which can be restored later by calling rng(state). The state is a structure.

Examples

rng(123);
R = rand(1,2)
  R =
    0.2838    0.4196
s = rng
  s =
    type: 'original'
    state: real 2x1
    rawmax: 4294967296
R = rand
  R =
    0.5788
rng(s)
R = rand
  R =
    0.5788

Reference

The MWC and KISS generators are described in George Marsaglia, Random numbers for C: The END?, Usenet, sci.stat.math, 20 Jan 1999.

See also

rand, randn, randi

rot90

Array rotation.

Syntax

A2 = rot90(A1)
A2 = rot90(A1, k)

Description

rot90(A1) rotates array A1 90 degrees counter-clockwise; the top left element of A1 becomes the bottom left element of A2. If A1 is an array with more than two dimensions, each plane corresponding to the first two dimensions is rotated.

In rot90(A1,k), the second argument is the number of times the array is rotated 90 degrees counter-clockwise. With k = 2, the array is rotated by 180 degrees; with k = 3 or k = -1, the array is rotated by 90 degrees clockwise.

Examples

rot90([1,2,3;4,5,6])
  3 6
  2 5
  1 4
rot90([1,2,3;4,5,6], -1)
  4 1
  5 2
  6 3
rot90([1,2,3;4,5,6], -1)
  6 5 4
  3 2 1
fliplr(flipud([1,2,3;4,5,6]))
  6 5 4
  3 2 1

See also

fliplr, flipud, reshape

setdiff

Set difference.

Syntax

c = setdiff(a, b)
(c, ia) = setdiff(a, b)

Description

setdiff(a,b) gives the difference between sets a and b, i.e. the set of members of set a which do not belong to b. Sets are any type of numeric, character or logical arrays, or lists or cell arrays of character strings. Multiple elements of input arguments are considered as single members; the result is always sorted and has unique elements.

The optional second output argument is a vector of indices such that if (c,ia)=setdiff(a,b), then c is a(ia).

Example

a = {'a','bc','bbb','de'};
b = {'z','bc','aa','bbb'};
(c, ia) = setdiff(a, b)
  c =
    {'a','de'}
  ia =
    1 4
a(ia)
  {'a','de'}

See also

unique, union, intersect, setxor, ismember

setxor

Set exclusive or.

Syntax

c = setxor(a, b)
(c, ia, ib) = setxor(a, b)

Description

setxor(a,b) performs an exclusive or operation between sets a and b, i.e. it gives the set of members of sets a and b which are not members of the intersection of a and b. Sets are any type of numeric, character or logical arrays, or lists or cell arrays of character strings. Multiple elements of input arguments are considered as single members; the result is always sorted and has unique elements.

The optional second and third output arguments are vectors of indices such that if (c,ia,ib)=setxor(a,b), then c is the union of a(ia) and b(ib).

Example

a = {'a','bc','bbb','de'};
b = {'z','bc','aa','bbb'};
(c, ia, ib) = setxor(a, b)
  c =
    {'a','aa','de','z'}
  ia =
    1 4
  ib =
    3 1
union(a(ia),b(ib))
  {'a','aa','de','z'}

Set exclusive or can also be computed as the union of a and b minus the intersection of a and b:

setdiff(union(a, b), intersect(a, b))
  {'a','aa','de','z'}

See also

unique, union, intersect, setdiff, ismember

size

Size of an array.

Syntax

v = size(A)
(m, n) = size(A)
m = size(A, i)

Description

size(A) returns the number of rows and the number of elements along each dimension of array A, either in a row vector or as scalars if there are two output arguments or more.

size(A,i) gives the number of elements in array A along dimension i: size(A,1) gives the number of rows and size(A,2) the number of columns.

Examples

M = ones(3, 5);
size(M)
  3 5
(m, n) = size(M)
  m =
    3
  n =
    5
size(M, 1)
  3
size(M, 2)
  5

See also

length, numel, ndims, end

sort

Array sort.

Syntax

(A_sorted, ix) = sort(A)
(A_sorted, ix) = sort(A, dim)
(A_sorted, ix) = sort(A, dir)
(A_sorted, ix) = sort(A, dim, dir)
(list_sorted, ix) = sort(list)
(list_sorted, ix) = sort(list, dir)

Description

sort(A) sorts separately the elements of each column of array A, or the elements of A if it is a row vector. The result has the same size as A. Elements are sorted in ascending order, with NaNs at the end. For complex arrays, numbers are sorted by magnitude.

The optional second output argument gives the permutation array which transforms A into the sorted array. It can be used to reorder elements in another array or to sort the rows of a matrix with respect to one of its columns, as shown in the last example below. Order of consecutive identical elements is preserved.

If a second numeric argument dim is provided, the sort is performed along dimension dim (columns if dim is 1, rows if 2, etc.)

An additional argument can specify the ordering direction. It must be the string 'ascending' (or 'a') for ascending order, or 'descending' (or 'd') for descending order. In both cases, NaNs are moved to the end.

sort(list) sorts the elements of a list, which must be strings. Cell arrays are sorted like lists, not column-wise like numeric arrays. The second output argument is a row vector. The direction can be specified with a second input argument.

Examples

sort([3,6,2,3,9,1,2])
  1 2 2 3 3 6 9
sort([2,5,3;nan,4,2;6,1,1])
  2   1   1
  6   4   2
  nan 5   3
sort([2,5,3;nan,4,2;6,1,1], 'd')
  6   5   3
  2   4   2
  nan 1   1
sort({'def', 'abcd', 'abc'})
  {'abc', 'abcd', 'def'}

To sort the rows of an array after the first column, one can obtain the permutation vector by sorting the first column, and use it as subscripts on the array rows:

M = [2,4; 5,1; 3,9; 4,0]
  2 4
  5 1
  3 9
  4 0
(Ms, ix) = sort(M(:,1));
M(ix,:)
  2 4
  3 9
  4 0
  5 1

Algorithm

Shell sort.

See also

unique

squeeze

Suppression of singleton dimensions of an array.

Syntax

B = squeeze(A)

Description

squeeze(A) returns an array with the same elements as A, but where dimensions equal to 1 are removed. The result has at least 2 dimensions; row and column vectors keep their dimensions.

Examples

size(squeeze(rand(1,2,3,1,4)))
  2 3 4
size(squeeze(1:5))
  1 5

See also

permute, ndims

sub2ind

Conversion from row/column subscripts to single index.

Syntax

ind = sub2ind(size, i, j)
ind = sub2ind(size, i, j, k, ...)

Description

sub2ind(size,i,j) gives the single index which can be used to retrieve the element corresponding to the i:th row and the j:th column of an array whose size is specified by size. size must be either a scalar for square matrices or a vector of two elements or more for other arrays. If i and j are arrays, they must have the same size: the result is calculated separately for each element and has the same size.

sub2ind also accepts sizes and subscripts for arrays with more than 2 dimensions. The number of indices must match the length of size.

Example

M = [3, 6; 8, 9];
M(2, 1)
  8
sub2ind(size(M), 2, 1)
  7
M(3)
  8

See also

ind2sub, size

tril

Extraction of the lower triangular part of a matrix.

Syntax

L = tril(M)
L = tril(M,k)

Description

tril(M) extracts the lower triangular part of a matrix; the result is a matrix of the same size where all the elements above the main diagonal are set to zero. A second argument can be used to specify another diagonal: 0 is the main diagonal, positive values are above and negative values below.

Examples

M = magic(3)
M =
  8 1 6
  3 5 7
  4 9 2
tril(M)
  8 0 0
  3 5 0
  4 9 2
tril(M,1)
  8 1 0
  3 5 7
  4 9 2

See also

triu, diag

triu

Extraction of the upper triangular part of a matrix.

Syntax

U = triu(M)
U = triu(M,k)

Description

tril(M) extracts the upper triangular part of a matrix; the result is a matrix of the same size where all the elements below the main diagonal are set to zero. A second argument can be used to specify another diagonal; 0 is the main diagonal, positive values are above and negative values below.

Examples

M = magic(3)
M =
  8 1 6
  3 5 7
  4 9 2
triu(M)
  8 1 6
  0 5 7
  0 0 2
triu(M,1)
  0 1 6
  0 0 7
  0 0 0

See also

tril, diag

union

Set union.

Syntax

c = union(a, b)
(c, ia, ib) = union(a, b)

Description

union(a,b) gives the union of sets a and b, i.e. it gives the set of members of sets a or b or both. Sets are any type of numeric, character or logical arrays, or lists or cell arrays of character strings. Multiple elements of input arguments are considered as single members; the result is always sorted and has unique elements.

The optional second and third output arguments are vectors of indices such that if (c,ia,ib)=union(a,b), then elements of c are the elements of a(ia) or b(ib); the intersection of a(ia) and b(ib) is empty.

Example

a = {'a','bc','bbb','de'};
b = {'z','bc','aa','bbb'};
(c, ia, ib) = union(a, b)
  c =
    {'a','aa','bbb','bc','de','z'}
  ia =
    1 3 2 4
  ib =
    3 1
a(ia)
  {'a','bbb','bc','de'}
b(ib)
  {'aa','z'}

Set exclusive or can also be computed as the union of a and b minus the intersection of a and b:

setdiff(union(a, b), intersect(a, b))
  {'a','aa','de','z'}

See also

unique, intersect, setdiff, setxor, ismember

unique

Keep unique elements.

Syntax

v2 = unique(v1)
list2 = unique(list1)
(b, ia, ib) = unique(a)

Description

With an array argument, unique(v1) sorts its elements and removes duplicate elements. Unless v1 is a row vector, v1 is considered as a column vector.

With an argument which is a list of strings, unique(list) sorts its elements and removes duplicate elements.

The optional second output argument is set to a vector of indices such that if (b,ia)=unique(a), then b is a(ia).

The optional third output argument is set to a vector of indices such that if (b,ia,ib)=unique(a), then a is b(ib).

Examples

(b,ia,ib) = unique([4,7,3,8,7,1,3])
  b =
    1 3 4 7 8
  ia =
    6 3 1 2 4
  ib =
    3 4 2 5 4 1 2
unique({'def', 'ab', 'def', 'abc'})
  {'ab', 'abc', 'def'}

See also

sort, union, intersect, setdiff, setxor, ismember

unwrap

Unwrap angle sequence.

Syntax

a2 = unwrap(a1)
a2 = unwrap(a1, tol)
A2 = unwrap(A1, tol, dim)

Description

unwrap(a1), where a1 is a vector of angles in radians, returns a vector a2 of the same length, with the same values modulo 2 pi, starting with the same value, and where differences between consecutive values do not exceed pi. It is useful for interpolation in a discrete set of angles and for plotting.

With two input arguments, unwrap(a1,tol) reduces the difference between two consecutive values only if it is larger (in absolute value) than tol. If tol is smaller than pi, or the empty array [], the default value of pi is used.

With three input arguments, unwrap(A1,tol,dim) operates along dimension dim. The result is an array of the same size as A1. The default dimension for arrays is 1.

Example

unwrap([0, 2, 4, 6, 0, 2])
  0.00  2.00  4.00  6.00  6.28  8.28

See also

mod, rem

zeros

Zero array.

Syntax

A = zeros(n)
A = zeros(n1,n2,...)
A = zeros([n1,n2,...])
A = zeros(..., type)

Description

zeros builds an array whose elements are 0. The size of the array is specified by one integer for a square matrix, or several integers (either as separate arguments or in a vector) for an array of any size.

An additional input argument can be used to specify the type of the result. It must be the string 'double', 'single', 'int8', 'int16', 'int32', 'int64', 'uint8', 'uint16', 'uint32', or 'uint64' (64-bit arrays are not supported on all platforms).

Examples

zeros([2,3])
  0 0 0
  0 0 0
zeros(2)
  0 0
  0 0
zeros(1, 5, 'uint16')
  1x5 uint16 array
    0 0 0 0 0

See also

ones, cell, eye, rand, randn, repmat