[top]
API Documentation for Armadillo 7.500
Preamble
|
|
|
-
Please cite the following article if you use Armadillo in your research and/or software.
Citations are useful for the continued development and maintenance of the library.
Conrad Sanderson and Ryan Curtin.
Armadillo: a template-based C++ library for linear algebra.
Journal of Open Source Software, Vol. 1, pp. 26, 2016.
|
Overview
Matrix, Vector, Cube and Field Classes
Member Functions & Variables
Generated Vectors/Matrices/Cubes
eye | | generate identity matrix |
linspace | | generate vector with linearly spaced elements |
logspace | | generate vector with logarithmically spaced elements |
ones | | generate object filled with ones |
randi | | generate object with random integer values in specified interval |
randu / randn | | generate object with random values (uniform and normal distributions) |
randg | | generate object with random values (gamma distribution) |
regspace | | generate vector with regularly spaced elements |
speye | | generate sparse identity matrix |
spones | | generate sparse matrix with non-zero elements set to one |
sprandu / sprandn | | generate sparse matrix with non-zero elements set to random values |
toeplitz | | generate Toeplitz matrix |
zeros | | generate object filled with zeros |
Functions of Vectors/Matrices/Cubes
abs | | obtain magnitude of each element |
accu | | accumulate (sum) all elements |
all | | check whether all elements are non-zero, or satisfy a relational condition |
any | | check whether any element is non-zero, or satisfies a relational condition |
approx_equal | | approximate equality |
as_scalar | | convert 1x1 matrix to pure scalar |
clamp | | obtain clamped elements according to given limits |
cond | | condition number of matrix |
conj | | obtain complex conjugate of each element |
conv_to | | convert between matrix types |
cross | | cross product |
cumsum | | cumulative sum |
cumprod | | cumulative product |
det / log_det | | determinant |
diagmat | | generate diagonal matrix from given matrix or vector |
diagvec | | extract specified diagonal |
diff | | differences between adjacent elements |
dot/cdot/norm_dot | | dot product |
eps | | obtain distance of each element to next largest floating point representation |
expmat | | matrix exponential |
expmat_sym | | matrix exponential (symmetric) |
find | | find indices of non-zero elements, or elements satisfying a relational condition |
find_finite | | find indices of finite elements |
find_nonfinite | | find indices of non-finite elements |
find_unique | | find indices of unique elements |
fliplr / flipud | | reverse order of columns or rows |
imag / real | | extract imaginary/real part |
ind2sub | | convert linear index to subscripts |
index_min / index_max | | indices of extremum values |
inplace_trans | | in-place transpose |
is_finite | | check whether all elements are finite |
join_rows / join_cols | | concatenation of matrices |
join_slices | | concatenation of cubes |
kron | | Kronecker tensor product |
logmat | | matrix logarithm |
logmat_sympd | | matrix logarithm (symmetric) |
min / max | | return extremum values |
nonzeros | | return non-zero values |
norm | | various norms of vectors and matrices |
normalise | | normalise vectors to unit p-norm |
prod | | product of elements |
rank | | rank of matrix |
rcond | | reciprocal of condition number |
repmat | | replicate matrix in block-like fashion |
reshape | | change size while keeping elements |
resize | | change size while keeping elements and preserving layout |
shift | | shift elements |
shuffle | | randomly shuffle elements |
size | | obtain dimensions of given object |
sort | | sort elements |
sort_index | | vector describing sorted order of elements |
sqrtmat | | square root of matrix |
sqrtmat_sympd | | square root of matrix (symmetric) |
sum | | sum of elements |
sub2ind | | convert subscripts to linear index |
symmatu / symmatl | | generate symmetric matrix from given matrix |
trace | | sum of diagonal elements |
trans | | transpose of matrix |
trapz | | trapezoidal numerical integration |
trimatu / trimatl | | generate triangular matrix from given matrix |
unique | | return unique elements |
vectorise | | convert matrix to vector |
misc functions | | miscellaneous element-wise functions: exp, log, pow, sqrt, round, sign, ... |
trig functions | | trigonometric element-wise functions: cos, sin, ... |
Decompositions, Factorisations, Inverses and Equation Solvers (Dense Matrices)
chol | | Cholesky decomposition |
eig_sym | | eigen decomposition of dense symmetric/hermitian matrix |
eig_gen | | eigen decomposition of dense general square matrix |
eig_pair | | eigen decomposition for pair of general dense square matrices |
inv | | inverse of general square matrix |
inv_sympd | | inverse of symmetric positive definite matrix |
lu | | lower-upper decomposition |
null | | orthonormal basis of null space |
orth | | orthonormal basis of range space |
pinv | | pseudo-inverse |
qr | | QR decomposition |
qr_econ | | economical QR decomposition |
qz | | generalised Schur decomposition |
schur | | Schur decomposition |
solve | | solve systems of linear equations |
svd | | singular value decomposition |
svd_econ | | economical singular value decomposition |
syl | | Sylvester equation solver |
Decompositions, Factorisations and Equation Solvers (Sparse Matrices)
eigs_sym | | limited number of eigenvalues & eigenvectors of sparse symmetric real matrix |
eigs_gen | | limited number of eigenvalues & eigenvectors of sparse general square matrix |
spsolve | | solve sparse systems of linear equations |
svds | | limited number of singular values & singular vectors of sparse matrix |
Signal & Image Processing
Statistics & Clustering
stats functions | | mean, median, standard deviation, variance |
cov | | covariance |
cor | | correlation |
hist | | histogram of counts |
histc | | histogram of counts with user specified edges |
princomp | | principal component analysis |
running_stat | | running statistics of one dimensional process/signal |
running_stat_vec | | running statistics of multi-dimensional process/signal |
kmeans | | cluster data into disjoint sets |
gmm_diag | | model data as a Gaussian Mixture Model (GMM) |
Miscellaneous
Matrix, Vector, Cube and Field Classes
Mat<type>
mat
cx_mat
-
The root matrix class is Mat<type>, where type is one of:
-
float, double, std::complex<float>, std::complex<double>,
short, int, long, and unsigned versions of short, int, long
-
For convenience the following typedefs have been defined:
-
In this documentation the mat type is used for convenience;
it is possible to use other types instead, eg. fmat
-
Functions which use LAPACK or ATLAS (generally matrix decompositions) are only valid for the following types:
mat, fmat, cx_mat, cx_fmat
-
Elements are stored with column-major ordering (ie. column by column)
-
Constructors:
mat()
mat(n_rows, n_cols)
mat(n_rows, n_cols, fill_type)
mat(size(X))
mat(size(X), fill_type)
mat(mat)
mat(sp_mat)
mat(vec)
mat(rowvec)
mat(initializer_list)
mat(string)
mat(std::vector) (treated as a column vector)
cx_mat(mat,mat) (for constructing a complex matrix out of two real matrices)
-
When specifying the size with n_rows and n_cols, by default the memory is uninitialised;
memory can be initialised by specifying the fill_type,
which is one of:
fill::zeros,
fill::ones,
fill::eye,
fill::randu,
fill::randn,
fill::none,
with the following meanings:
fill::zeros | = | set all elements to 0 |
fill::ones | = | set all elements to 1 |
fill::eye | = | set the elements along the main diagonal to 1 and off-diagonal elements to 0 |
fill::randu | = | set each element to a random value from a uniform distribution in the [0,1] interval |
fill::randn | = | set each element to a random value from a normal/Gaussian distribution with zero mean and unit variance |
fill::none | = | do not modify the elements |
-
The string format for the constructor is elements separated by spaces, and rows denoted by semicolons.
For example, the 2x2 identity matrix can be created using
"1 0; 0 1" .
Caveat: string based initialisation is slower than directly setting the elements or using element initialisation.
-
Advanced constructors:
mat(ptr_aux_mem, n_rows, n_cols, copy_aux_mem = true, strict = false)
Create a matrix using data from writable auxiliary (external) memory, where ptr_aux_mem is a pointer to the memory.
By default the matrix allocates its own memory and copies data from the auxiliary memory (for safety).
However, if copy_aux_mem is set to false,
the matrix will instead directly use the auxiliary memory (ie. no copying);
this is faster, but can be dangerous unless you know what you are doing!
The strict parameter comes into effect only when copy_aux_mem is set to false
(ie. the matrix is directly using auxiliary memory)
-
when strict is set to false, the matrix will use the auxiliary memory until a size change
-
when strict is set to true, the matrix will be bound to the auxiliary memory for its lifetime;
the number of elements in the matrix can't be changed
- the default setting of strict in versions 6.000+ is false
- the default setting of strict in versions 5.600 and earlier is true
mat(const ptr_aux_mem, n_rows, n_cols)
Create a matrix by copying data from read-only auxiliary memory,
where ptr_aux_mem is a pointer to the memory
mat::fixed<n_rows, n_cols>
Create a fixed size matrix, with the size specified via template arguments.
Memory for the matrix is allocated at compile time.
This is generally faster than dynamic memory allocation, but the size of the matrix can't be changed afterwards (directly or indirectly).
For convenience, there are several pre-defined typedefs for each matrix type
(where the types are: umat, imat, fmat, mat, cx_fmat, cx_mat).
The typedefs specify a square matrix size, ranging from 2x2 to 9x9.
The typedefs were defined by simply appending a two digit form of the size to the matrix type
-- for example, mat33 is equivalent to mat::fixed<3,3>,
while cx_mat44 is equivalent to cx_mat::fixed<4,4>.
mat::fixed<n_rows, n_cols>(const ptr_aux_mem)
Create a fixed size matrix, with the size specified via template arguments;
data is copied from auxiliary memory, where ptr_aux_mem is a pointer to the memory
-
Examples:
mat A(5, 5, fill::randu);
double x = A(1,2);
mat B = A + A;
mat C = A * B;
mat D = A % B;
cx_mat X(A,B);
B.zeros();
B.set_size(10,10);
B.ones(5,6);
B.print("B:");
mat::fixed<5,6> F;
double aux_mem[24];
mat H(&aux_mem[0], 4, 6, false); // use auxiliary memory
Caveat:
For mathematical correctness, scalars are treated as 1x1 matrices during initialisation.
As such, the code below will not generate a 5x5 matrix with every element equal to 123.0:
mat A(5,5); A = 123.0;
Use the following code instead:
mat A(5,5); A.fill(123.0);
See also:
Col<type>
vec
cx_vec
Caveat:
For mathematical correctness, scalars are treated as 1x1 matrices during initialisation.
As such, the code below will not generate a column vector with every element equal to 123.0:
vec a(5); a = 123.0;
Use the following code instead:
vec a(5); a.fill(123.0);
See also:
Row<type>
rowvec
cx_rowvec
Caveat:
For mathematical correctness, scalars are treated as 1x1 matrices during initialisation.
As such, the code below will not generate a row vector with every element equal to 123.0:
rowvec r(5); r = 123.0;
Use the following code instead:
rowvec r(5); r.fill(123.0);
See also:
Cube<type>
cube
cx_cube
-
Classes for cubes, also known as "3D matrices" or 3rd order tensors
-
The cube class is Cube<type>, where type is one of:
-
float, double, std::complex<float>, std::complex<double>,
short, int, long and unsigned versions of short, int, long
-
For convenience the following typedefs have been defined:
-
In this documentation the cube type is used for convenience;
it is possible to use other types instead, eg. fcube
-
Cube data is stored as a set of slices (matrices) stored contiguously within memory.
Within each slice, elements are stored with column-major ordering (ie. column by column)
-
Each slice can be interpreted as a matrix, hence functions which take Mat as input can generally also take cube slices as input
-
Constructors:
cube()
cube(n_rows, n_cols, n_slices)
cube(n_rows, n_cols, n_slices, fill_type)
cube(size(X))
cube(size(X), fill_type)
cube(cube)
cx_cube(cube, cube) (for constructing a complex cube out of two real cubes)
-
When specifying the cube size with n_rows, n_cols and n_slices, by default the memory is uninitialised;
memory can be initialised by specifying the fill_type,
as per the Mat class (except for fill::eye)
-
Advanced constructors:
cube::fixed<n_rows, n_cols, n_slices>
Create a fixed size cube, with the size specified via template arguments.
Memory for the cube is allocated at compile time.
This is generally faster than dynamic memory allocation, but the size of the cube can't be changed afterwards (directly or indirectly).
cube(ptr_aux_mem, n_rows, n_cols, n_slices, copy_aux_mem = true, strict = false)
Create a cube using data from writable auxiliary (external) memory, where ptr_aux_mem is a pointer to the memory.
By default the cube allocates its own memory and copies data from the auxiliary memory (for safety).
However, if copy_aux_mem is set to false,
the cube will instead directly use the auxiliary memory (ie. no copying);
this is faster, but can be dangerous unless you know what you are doing!
The strict parameter comes into effect only when copy_aux_mem is set to false
(ie. the cube is directly using auxiliary memory)
-
when strict is set to false, the cube will use the auxiliary memory until a size change
-
when strict is set to true, the cube will be bound to the auxiliary memory for its lifetime;
the number of elements in the cube can't be changed
- the default setting of strict in versions 6.000+ is false
- the default setting of strict in versions 5.600 and earlier is true
cube(const ptr_aux_mem, n_rows, n_cols, n_slices)
Create a cube by copying data from read-only auxiliary memory,
where ptr_aux_mem is a pointer to the memory
-
Examples:
cube x(1,2,3);
cube y = randu<cube>(4,5,6);
mat A = y.slice(1); // extract a slice from the cube
// (each slice is a matrix)
mat B = randu<mat>(4,5);
y.slice(2) = B; // set a slice in the cube
cube q = y + y; // cube addition
cube r = y % y; // element-wise cube multiplication
cube::fixed<4,5,6> f;
f.ones();
Caveats:
For mathematical correctness, scalars are treated as 1x1x1 cubes during initialisation.
As such, the code below will not generate a cube with every element equal to 123.0:
cube c(5,6,7); c = 123.0;
Use the following code instead:
cube c(5,6,7); c.fill(123.0);
See also:
field<object_type>
-
Class for storing arbitrary objects in matrix-like or cube-like layouts
-
Somewhat similar to a matrix or cube, but instead of each element being a scalar,
each element can be a vector, or matrix, or cube
-
Each element can have an arbitrary size (eg. in a field of matrices, each matrix can have a different size)
-
Constructors, where object_type is another class, eg. vec, mat, std::string, etc:
field<object_type>()
field<object_type>(n_elem)
field<object_type>(n_rows, n_cols)
field<object_type>(n_rows, n_cols, n_slices)
field<object_type>(size(X))
field<object_type>(field<object_type>)
-
Caveat: to store a set of matrices of the same size, the Cube class is more efficient
-
Examples:
mat A = randn(2,3);
mat B = randn(4,5);
field<mat> F(2,1);
F(0,0) = A;
F(1,0) = B;
F.print("F:");
F.save("mat_field");
See also:
SpMat<type>
sp_mat
sp_cx_mat
-
The root sparse matrix class is SpMat<type>, where type is one of:
-
float, double, std::complex<float>, std::complex<double>,
short, int, long and unsigned versions of short, int, long
-
For convenience the following typedefs have been defined:
sp_mat
|
=
|
SpMat<double>
|
sp_fmat
|
=
|
SpMat<float>
|
sp_cx_mat
|
=
|
SpMat<cx_double>
|
sp_cx_fmat
|
=
|
SpMat<cx_float>
|
sp_umat
|
=
|
SpMat<uword>
|
sp_imat
|
=
|
SpMat<sword>
|
-
In this documentation the sp_mat type is used for convenience;
it is possible to use other types instead, eg. sp_fmat
-
Constructors:
sp_mat()
sp_mat(n_rows, n_cols)
sp_mat(size(X))
sp_mat(sp_mat)
sp_mat(mat)
sp_mat(string)
sp_cx_mat(sp_mat,sp_mat) (for constructing a complex matrix out of two real matrices)
-
Elements are stored in the compressed sparse column (CSC) format
-
All elements are treated as zero by default (ie. the matrix is initialised to contain zeros)
-
This class behaves in a similar manner to the Mat class,
however, member functions which set all elements to non-zero values (and hence do not make sense for sparse matrices) have been deliberately omitted;
examples of omitted functions: .fill(), .ones(), += scalar, etc.
-
Batch insertion constructors:
- form 1:
sp_mat(locations, values, sort_locations = true)
- form 2:
sp_mat(locations, values, n_rows, n_cols, sort_locations = true, check_for_zeros = true)
- form 3:
sp_mat(add_values, locations, values, n_rows, n_cols, sort_locations = true, check_for_zeros = true)
- form 4:
sp_mat(rowind, colptr, values, n_rows, n_cols)
-
Using batch insertion constructors is generally much faster than consecutively inserting values using element access operators
-
For forms 1, 2, 3,
locations is a dense matrix of type umat, with a size of 2 x N, where N is the number of values to be inserted;
the location of the i-th element is specified by the contents of the i-th column of the locations matrix,
where the row is in locations(0,i), and the column is in locations(1,i)
-
For form 4,
rowind is a dense column vector of type uvec containing the row indices of the values to be inserted,
and
colptr is a dense column vector of type uvec (with length n_cols + 1) containing indices of values corresponding to the start of new columns;
the vectors correspond to the arrays used by the compressed sparse column format;
this form is useful for copying data from other CSC sparse matrix containers
-
For all forms, values is a dense column vector containing the values to be inserted;
it must have the same element type as the sparse matrix.
For forms 1 and 2, the value in values[i] will be inserted at the location specified by the i-th column of the locations matrix.
-
For form 3,
add_values is either true or false; when set to true, identical locations are allowed, and the values at identical locations are added
-
The size of the constructed matrix is either
automatically determined from the maximal locations in the locations matrix (form 1),
or
manually specified via n_rows and n_cols (forms 2, 3, 4)
-
If sort_locations is set to false, the locations matrix is assumed to contain locations that are already sorted according to column-major ordering
-
If check_for_zeros is set to false, the values vector is assumed to contain no zero values
-
Caveats:
- support for sparse matrices in this version is preliminary
- the following subset of operations currently works with sparse matrices:
- element access
- fundamental arithmetic operations (such as addition and multiplication)
- submatrix views (contiguous forms only)
- diagonal views
- saving and loading (using arma_binary format only)
- element-wise functions: abs(), imag(), real(), conj(), sqrt(), square()
- scalar functions of matrices: accu(), as_scalar(), dot(), norm(), trace()
- vector valued functions of matrices: min(), max(), nonzeros(), sum(), mean(), var()
- matrix valued functions of matrices: diagmat(), join_rows(), join_cols(), repmat(), reshape(), resize(), .t(), trans()
- generated matrices: speye(), spones(), sprandu()/sprandn()
- eigen and svd decomposition: eigs_sym(), eigs_gen(), svds()
- solution of sparse linear systems: spsolve()
- miscellaneous: print()
-
Examples:
sp_mat A(5,6);
sp_mat B(6,5);
A(0,0) = 1;
A(1,0) = 2;
B(0,0) = 3;
B(0,1) = 4;
sp_mat C = 2*B;
sp_mat D = A*C;
// batch insertion of two values at (5, 6) and (9, 9)
umat locations;
locations << 5 << 9 << endr
<< 6 << 9 << endr;
vec values;
values << 1.5 << 3.2 << endr;
sp_mat X(locations, values);
See also:
operators: + − * / % == != <= >= < >
-
Overloaded operators for Mat, Col, Row and Cube classes
-
Meanings:
+ |
|
Addition of two objects |
− |
|
Subtraction of one object from another or negation of an object |
|
|
|
/ |
|
Element-wise division of an object by another object or a scalar |
* |
|
Matrix multiplication of two objects; not applicable to the Cube class unless multiplying a cube by a scalar |
|
|
|
% |
|
Schur product: element-wise multiplication of two objects |
|
|
|
== |
|
Element-wise equality evaluation of two objects; generates a matrix of type umat with entries that indicate whether at a given position the two elements from the two objects are equal (1) or not equal (0) |
!= |
|
Element-wise non-equality evaluation of two objects |
|
|
|
>= |
|
As for == , but the check is for "greater than or equal to" |
<= |
|
As for == , but the check is for "less than or equal to" |
|
|
|
> |
|
As for == , but the check is for "greater than" |
< |
|
As for == , but the check is for "less than" |
-
Caveat: operators involving an equality comparison (ie.
== , != , >= , <= )
are not recommended for matrices of type mat or fmat, due to the necessarily limited precision of the underlying element types;
you may wish to use approx_equal() instead
-
A std::logic_error exception is thrown if incompatible object sizes are used
-
If the
+ , − and % operators are chained, Armadillo will try to avoid the generation of temporaries;
no temporaries are generated if all given objects are of the same type and size
-
If the
* operator is chained, Armadillo will try to find an efficient ordering of the matrix multiplications
-
Examples:
mat A = randu<mat>(5,10);
mat B = randu<mat>(5,10);
mat C = randu<mat>(10,5);
mat P = A + B;
mat Q = A - B;
mat R = -B;
mat S = A / 123.0;
mat T = A % B;
mat U = A * C;
// V is constructed without temporaries
mat V = A + B + A + B;
imat AA = "1 2 3; 4 5 6; 7 8 9;";
imat BB = "3 2 1; 6 5 4; 9 8 7;";
// compare elements
umat ZZ = (AA >= BB);
See also:
Member Functions & Variables
attributes
.n_rows
|
|
number of rows; present in Mat, Col, Row, Cube, field and SpMat
|
.n_cols
|
|
number of columns; present in Mat, Col, Row, Cube, field and SpMat
|
.n_elem
|
|
total number of elements; present in Mat, Col, Row, Cube, field and SpMat
|
.n_slices
|
|
number of slices; present in Cube
|
.n_nonzero
|
|
number of non-zero elements; present in SpMat
|
See also:
element/object access via (), [] and .at()
-
Provide access to individual elements or objects stored in a container object
(ie. Mat, Col, Row, Cube, field)
(n)
|
|
For vec and rowvec, access the n-th element.
For mat, cube and field, access the n-th element/object under the assumption of a flat layout,
with column-major ordering of data (ie. column by column).
A std::logic_error exception is thrown if the requested element is out of bounds.
The bounds check can be optionally disabled at compile-time to get more speed.
|
|
|
|
.at(n) or [n]
|
|
As for (n), but without a bounds check.
Not recommended for use unless your code has been thoroughly debugged.
|
|
|
|
(i,j)
|
|
For mat and 2D field classes, access the element/object stored at the i-th row and j-th column.
A std::logic_error exception is thrown if the requested element is out of bounds.
The bounds check can be optionally disabled at compile-time to get more speed.
|
|
|
|
.at(i,j)
|
|
As for (i,j), but without a bounds check.
Not recommended for use unless your code has been thoroughly debugged.
|
|
|
|
|
(i,j,k)
|
|
For cube and 3D field classes, access the element/object stored at the i-th row, j-th column and k-th slice.
A std::logic_error exception is thrown if the requested element is out of bounds.
The bounds check can be optionally disabled at compile-time to get more speed.
|
|
|
|
.at(i,j,k)
|
|
As for (i,j,k), but without a bounds check.
Not recommended for use unless your code has been thoroughly debugged. |
-
The bounds checks used by the (n), (i,j) and (i,j,k) access forms
can be disabled by defining the ARMA_NO_DEBUG macro
before including the armadillo header file (eg. #define ARMA_NO_DEBUG).
Disabling the bounds checks is not recommended until your code has been thoroughly debugged
-- it's better to write correct code first, and then maximise its speed.
-
The indices of elements are specified via the uword type, which is a typedef for an unsigned integer type.
When using loops to access elements, it's best to use uword instead of int.
For example:
for(uword i=0; i<X.n_elem; ++i) { X(i) = ... }
-
Caveat: for sparse matrices, using element access operators to insert values via loops can be inefficient;
you may wish to use batch insertion constructors instead
-
Examples:
mat A = randu<mat>(10,10);
A(9,9) = 123.0;
double x = A.at(9,9);
double y = A[99];
vec p = randu<vec>(10,1);
p(9) = 123.0;
double z = p[9];
See also:
element initialisation
-
When using the C++11 standard, elements in Mat, Col, Row can be set via initialiser lists
-
When using the old C++98 standard, elements can be set via the
<< operator; special element endr indicates "end of row" (conceptually similar to std::endl)
-
Caveat: using the
<< operator is slower than using initialiser lists
-
Examples:
// C++11
vec v = { 1, 2, 3 };
mat A = { {1, 3, 5},
{2, 4, 6} };
// C++98
mat B;
B << 1 << 3 << 5 << endr
<< 2 << 4 << 6 << endr;
See also:
.zeros() |
|
|
(member function of Mat, Col, Row, SpMat, Cube)
|
.zeros( n_elem ) |
|
|
(member function of Col and Row)
|
.zeros( n_rows, n_cols ) |
|
|
(member function of Mat and SpMat)
|
.zeros( n_rows, n_cols, n_slices ) |
|
|
(member function of Cube)
|
.zeros( size(X) ) |
|
|
(member function of Mat, Col, Row, Cube, SpMat)
|
-
Set the elements of an object to zero,
optionally first changing the size to specified dimensions
-
Examples:
mat A(5,10); A.zeros(); // or: mat A(5,10,fill::zeros);
mat B; B.zeros(10,20);
mat C; C.zeros( size(B) );
See also:
.ones() |
|
|
(member function of Mat, Col, Row, Cube)
|
.ones( n_elem ) |
|
|
(member function of Col and Row)
|
.ones( n_rows, n_cols ) |
|
|
(member function of Mat)
|
.ones( n_rows, n_cols, n_slices ) |
|
|
(member function of Cube)
|
.ones( size(X) ) |
|
|
(member function of Mat, Col, Row, Cube)
|
-
Set all the elements of an object to one,
optionally first changing the size to specified dimensions
-
Examples:
mat A(5,10); A.ones(); // or: mat A(5,10,fill::ones);
mat B; B.ones(10,20);
mat C; C.ones( size(B) );
See also:
.eye()
.eye( n_rows, n_cols )
.eye( size(X) )
-
Member functions of Mat and SpMat
-
Set the elements along the main diagonal to one and off-diagonal elements to zero,
optionally first changing the size to specified dimensions
-
An identity matrix is generated when n_rows = n_cols
-
Examples:
mat A(5,5); A.eye(); // or: mat A(5,5,fill::eye);
mat B; B.eye(5,5);
mat C; C.eye( size(B) );
See also:
.randu() |
|
|
(member function of Mat, Col, Row, Cube)
|
.randu( n_elem ) |
|
|
(member function of Col and Row)
|
.randu( n_rows, n_cols ) |
|
|
(member function of Mat)
|
.randu( n_rows, n_cols, n_slices ) |
|
|
(member function of Cube)
|
.randu( size(X) ) |
|
|
(member function of Mat, Col, Row, Cube)
|
.randn() |
|
|
(member function of Mat, Col, Row, Cube)
|
.randn( n_elem ) |
|
|
(member function of Col and Row)
|
.randn( n_rows, n_cols ) |
|
|
(member function of Mat)
|
.randn( n_rows, n_cols, n_slices ) |
|
|
(member function of Cube)
|
.randn( size(X) ) |
|
|
(member function of Mat, Col, Row, Cube)
|
-
Set all the elements to random values,
optionally first changing the size to specified dimensions
- .randu() uses a uniform distribution in the [0,1] interval
- .randn() uses a normal/Gaussian distribution with zero mean and unit variance
-
To change the RNG seed, use arma_rng::set_seed(value) or arma_rng::set_seed_random() functions
-
Examples:
mat A(5,10); A.randu(); // or: mat A(5,10,fill::randu);
mat B; B.randu(10,20);
mat C; C.randu( size(B) );
arma_rng::set_seed_random(); // set the seed to a random value
See also:
.fill( value )
See also:
.imbue( functor )
.imbue( lambda_function ) (C++11 only)
-
Member functions of Mat, Col, Row and Cube
-
Imbue (fill) with values provided by a functor or lambda function
-
For matrices, filling is done column-by-column (ie. column 0 is filled, then column 1, ...)
-
For cubes, filling is done slice-by-slice, with each slice treated as a matrix
-
Examples:
// C++11 only example
// need to include <random>
std::mt19937 engine; // Mersenne twister random number engine
std::uniform_real_distribution<double> distr(0.0, 1.0);
mat A(4,5);
A.imbue( [&]() { return distr(engine); } );
See also:
.replace( old_value, new_value )
-
Member function of Mat, Col, Row, Cube and SpMat
- For all elements equal to old_value, set them to new_value
- The type of old_value and new_value must match the type of elements used by the container object (eg. for mat the type is double)
-
Caveats:
- floating point numbers (float and double) are approximations due to their necessarily limited precision
- for sparse matrices (SpMat), replacement is not done when old_value = 0
-
Examples:
mat A(5,6,fill::randu);
A.diag().fill(datum::nan);
A.replace(datum::nan, 0); // replace each NaN with 0
See also:
.transform( functor )
.transform( lambda_function ) (C++11 only)
See also:
.for_each( functor )
.for_each( lambda_function ) (C++11 only)
-
Member functions of Mat, Col, Row, Cube and field
-
For each element, pass its reference to a functor or lambda function
-
For matrices, the processing is done column-by-column
-
For cubes, processing is done slice-by-slice, with each slice treated as a matrix
-
Examples:
// C++11 only examples
mat A = ones<mat>(4,5);
// add 123 to each element
A.for_each( [](mat::elem_type& val) { val += 123.0; } ); // NOTE: the '&' is crucial!
field<mat> F(2,3);
// set the size of all matrices in field F
F.for_each( [](mat& X) { X.zeros(4,5); } ); // NOTE: the '&' is crucial!
See also:
.set_size( n_elem ) |
|
|
(member function of Col, Row, field)
|
.set_size( n_rows, n_cols ) |
|
|
(member function of Mat, SpMat, field)
|
.set_size( n_rows, n_cols, n_slices ) |
|
|
(member function of Cube and field)
|
.set_size( size(X) ) |
|
|
(member function of Mat, Col, Row, Cube, SpMat, field)
|
See also:
.reshape( n_rows, n_cols ) |
|
|
(member function of Mat and SpMat)
|
.reshape( n_rows, n_cols, n_slices ) |
|
|
(member function of Cube)
|
.reshape( size(X) ) |
|
|
(member function of Mat, Cube, SpMat)
|
See also:
.resize( n_elem ) |
|
|
(member function of Col, Row)
|
.resize( n_rows, n_cols ) |
|
|
(member function of Mat and SpMat)
|
.resize( n_rows, n_cols, n_slices ) |
|
|
(member function of Cube)
|
.resize( size(X) ) |
|
|
(member function of Mat, Col, Row, Cube, SpMat)
|
See also:
.copy_size( A )
See also:
.reset()
See also:
submatrix views
- A collection of member functions of Mat, Col and Row classes that provide read/write access to submatrix views
- contiguous views for matrix X:
X.col( col_number )
X.row( row_number )
X.cols( first_col, last_col )
X.rows( first_row, last_row )
X.submat( first_row, first_col, last_row, last_col )
X( span(first_row, last_row), span(first_col, last_col) )
X( first_row, first_col, size(n_rows, n_cols) )
X( first_row, first_col, size(Y) ) (Y is a mat)
X( span(first_row, last_row), col_number )
X( row_number, span(first_col, last_col) )
X.head_cols( number_of_cols )
X.head_rows( number_of_rows )
X.tail_cols( number_of_cols )
X.tail_rows( number_of_rows )
X.unsafe_col( col_number )
-
contiguous views for vector V:
V( span(first_index, last_index) )
V.subvec( first_index, last_index )
V.subvec( first_index, size(W) ) (W is a vector)
V.head( number_of_elements )
V.tail( number_of_elements )
|
|
|
|
|
- non-contiguous views for matrix or vector X:
X.elem( vector_of_indices )
X( vector_of_indices )
X.cols( vector_of_column_indices )
X.rows( vector_of_row_indices )
X.submat( vector_of_row_indices, vector_of_column_indices )
X( vector_of_row_indices, vector_of_column_indices )
- related views (documented separately)
|
|
-
Instances of span(start,end) can be replaced by span::all to indicate the entire range
-
For functions requiring one or more vector of indices,
eg. X.submat(vector_of_row_indices, vector_of_column_indices),
each vector of indices must be of type uvec
-
In the function X.elem(vector_of_indices),
elements specified in vector_of_indices are accessed.
X is interpreted as one long vector,
with column-by-column ordering of the elements of X.
The vector_of_indices must evaluate to a vector of type uvec
(eg. generated by the find() function).
The aggregate set of the specified elements is treated as a column vector
(ie. the output of X.elem() is always a column vector).
-
The function .unsafe_col() is provided for speed reasons and should be used only if you know what you are doing.
It creates a seemingly independent Col vector object (eg. vec),
but uses memory from the existing matrix object.
As such, the created vector is not alias safe,
and does not take into account that the underlying matrix memory could be freed
(eg. due to any operation involving a size change of the matrix).
-
Examples:
mat A = zeros<mat>(5,10);
A.submat( 0,1, 2,3 ) = randu<mat>(3,3);
A( span(0,2), span(1,3) ) = randu<mat>(3,3);
A( 0,1, size(3,3) ) = randu<mat>(3,3);
mat B = A.submat( 0,1, 2,3 );
mat C = A( span(0,2), span(1,3) );
mat D = A( 0,1, size(3,3) );
A.col(1) = randu<mat>(5,1);
A(span::all, 1) = randu<mat>(5,1);
mat X = randu<mat>(5,5);
// get all elements of X that are greater than 0.5
vec q = X.elem( find(X > 0.5) );
// add 123 to all elements of X greater than 0.5
X.elem( find(X > 0.5) ) += 123.0;
// set four specific elements of X to 1
uvec indices;
indices << 2 << 3 << 6 << 8;
X.elem(indices) = ones<vec>(4);
// add 123 to the last 5 elements of vector a
vec a(10, fill::randu);
a.tail(5) += 123.0;
// add 123 to the first 3 elements of column 2 of X
X.col(2).head(3) += 123;
See also:
subcube views and slices
- A collection of member functions of the Cube class that provide subcube views
- contiguous views for cube Q:
Q.slice( slice_number )
Q.slices( first_slice, last_slice )
Q.subcube( first_row, first_col, first_slice, last_row, last_col, last_slice )
Q( span(first_row, last_row), span(first_col, last_col), span(first_slice, last_slice) )
Q( first_row, first_col, first_slice, size(n_rows, n_cols, n_slices) )
Q( first_row, first_col, first_slice, size(R) ) (R is a cube)
Q.head_slices( number_of_slices )
Q.tail_slices( number_of_slices )
Q.tube( row, col )
Q.tube( first_row, first_col, last_row, last_col )
Q.tube( span(first_row, last_row), span(first_col, last_col) )
Q.tube( first_row, first_col, size(n_rows, n_cols) )
|
|
|
|
- non-contiguous views for cube Q:
Q.elem( vector_of_indices )
Q( vector_of_indices )
- related views (documented separately)
|
-
Instances of span(a,b) can be replaced by:
- span() or span::all, to indicate the entire range
- span(a), to indicate a particular row, column or slice
-
An individual slice, accessed via .slice(), is an instance of the Mat class
(a reference to a matrix is provided)
-
All .tube() forms are variants of .subcube(), using first_slice = 0 and last_slice = Q.n_slices-1
-
The .tube(row,col) form uses row = first_row = last_row, and col = first_col = last_col
-
In the function Q.elem(vector_of_indices),
elements specified in vector_of_indices are accessed.
Q is interpreted as one long vector,
with slice-by-slice and column-by-column ordering of the elements of Q.
The vector_of_indices must evaluate to a vector of type uvec
(eg. generated by the find() function).
The aggregate set of the specified elements is treated as a column vector
(ie. the output of Q.elem() is always a column vector).
-
Examples:
cube A = randu<cube>(2,3,4);
mat B = A.slice(1); // each slice is a matrix
A.slice(0) = randu<mat>(2,3);
A.slice(0)(1,2) = 99.0;
A.subcube(0,0,1, 1,1,2) = randu<cube>(2,2,2);
A( span(0,1), span(0,1), span(1,2) ) = randu<cube>(2,2,2);
A( 0,0,1, size(2,2,2) ) = randu<cube>(2,2,2);
// add 123 to all elements of A greater than 0.5
A.elem( find(A > 0.5) ) += 123.0;
cube C = A.head_slices(2); // get first two slices
A.head_slices(2) += 123.0;
See also:
subfield views
- A collection of member functions of the field class that provide subfield views
- For a 2D field F, the subfields are accessed as:
F.row( row_number )
F.col( col_number )
F.rows( first_row, last_row )
F.cols( first_col, last_col )
F.subfield( first_row, first_col, last_row, last_col )
F( span(first_row, last_row), span(first_col, last_col) )
F( first_row, first_col, size(G) ) (G is a 2D field)
F( first_row, first_col, size(n_rows, n_cols) )
- For a 3D field F, the subfields are accessed as:
F.slice( slice_number )
F.slices( first_slice, last_slice )
F.subfield( first_row, first_col, first_slice, last_row, last_col, last_slice )
F( span(first_row, last_row), span(first_col, last_col), span(first_slice, last_slice) )
F( first_row, first_col, first_slice, size(G) ) (G is a 3D field)
F( first_row, first_col, first_slice, size(n_rows, n_cols, n_slices) )
-
Instances of span(a,b) can be replaced by:
- span() or span::all, to indicate the entire range
- span(a), to indicate a particular row or column
-
See also:
.diag()
.diag( k )
See also:
.each_col()
.each_row()
.each_col( vector_of_indices )
.each_row( vector_of_indices )
.each_col( lambda_function ) (C++11 only)
.each_row( lambda_function ) (C++11 only)
-
Member functions of Mat
-
Repeat a vector operation on each column or row of a matrix
-
Supported operations for .each_col() / .each_row() and .each_col(vector_of_indices) / .each_row(vector_of_indices) forms:
+ | | addition | | += | | in-place addition |
- | | subtraction | | -= | | in-place subtraction |
% | | element-wise multiplication | | %= | | in-place element-wise multiplication |
/ | | element-wise division | | /= | | in-place element-wise division |
= | | assignment (copy) | | | | |
- The argument vector_of_indices is optional; by default all columns or rows are used
-
If the argument vector_of_indices is specified, it must evaluate to a vector of type uvec;
the vector contains a list of indices of the columns or rows to be used
-
If the lambda_function is specified,
the function must accept a reference to a Col or Row object with the same element type as the underlying matrix
-
Examples:
mat X = ones<mat>(6,5);
vec v = linspace<vec>(10,15,6);
X.each_col() += v; // in-place addition of v to each column vector of X
mat Y = X.each_col() + v; // generate Y by adding v to each column vector of X
// subtract v from columns 0 through to 3 in X
X.cols(0,3).each_col() -= v;
uvec indices(2);
indices(0) = 2;
indices(1) = 4;
X.each_col(indices) = v; // copy v to columns 2 and 4 in X
X.each_col( [](vec& a){ a.print(); } ); // lambda function with non-const vector
const mat& XX = X;
XX.each_col( [](const vec& b){ b.print(); } ); // lambda function with const vector
See also:
.each_slice()
.each_slice( vector_of_indices )
.each_slice( lambda_function ) (C++11 only)
-
Member function of Cube
-
Repeat a matrix operation on each slice of a cube, with each slice treated as a matrix
-
Supported operations for the .each_slice() form:
+ | | addition | | += | | in-place addition |
- | | subtraction | | -= | | in-place subtraction |
% | | element-wise multiplication | | %= | | in-place element-wise multiplication |
/ | | element-wise division | | /= | | in-place element-wise division |
* | | matrix multiplication | | *= | | in-place matrix multiplication |
= | | assignment (copy) | | | | |
-
The .each_slice(vector_of_indices) form also supports the above operations, except for
* and *= (ie. matrix multiplication)
- The argument vector_of_indices is optional; by default all slices are used
-
If the argument vector_of_indices is specified, it must evaluate to a vector of type uvec;
the vector contains a list of indices of the slices to be used
-
If the lambda_function is specified,
the function must accept a reference to a Mat object with the same element type as the underlying cube
-
Examples:
cube C(4,5,6, fill::randu);
mat M = repmat(linspace<vec>(1,4,4), 1, 5);
C.each_slice() += M; // in-place addition of M to each slice of C
cube D = C.each_slice() + M; // generate D by adding M to each slice of C
uvec indices(2);
indices(0) = 2;
indices(1) = 4;
C.each_slice(indices) = M; // copy M to slices 2 and 4 in C
C.each_slice( [](mat& X){ X.print(); } ); // lambda function with non-const matrix
const cube& CC = C;
CC.each_slice( [](const mat& X){ X.print(); } ); // lambda function with const matrix
See also:
.set_imag( X )
.set_real( X )
-
Set the imaginary/real part of an object
-
X must have the same size as the recipient object
-
Examples:
mat A = randu<mat>(4,5);
mat B = randu<mat>(4,5);
cx_mat C = zeros<cx_mat>(4,5);
C.set_real(A);
C.set_imag(B);
Caveat:
to directly construct a complex matrix out of two real matrices,
the following code is faster:
mat A = randu<mat>(4,5);
mat B = randu<mat>(4,5);
cx_mat C = cx_mat(A,B);
See also:
.insert_rows( row_number, X )
.insert_rows( row_number, number_of_rows )
.insert_rows( row_number, number_of_rows, set_to_zero )
|
|
(member functions of Mat and Col)
|
|
.insert_cols( col_number, X )
.insert_cols( col_number, number_of_cols )
.insert_cols( col_number, number_of_cols, set_to_zero )
|
|
(member functions of Mat and Row)
|
|
.insert_slices( slice_number, X )
.insert_slices( slice_number, number_of_slices )
.insert_slices( slice_number, number_of_slices, set_to_zero )
|
|
(member functions of Cube)
|
-
Functions with the X argument: insert a copy of X at the specified row/column/slice
- if inserting rows, X must have the same number of columns as the recipient object
- if inserting columns, X must have the same number of rows as the recipient object
- if inserting slices, X must have the same number of rows and columns as the recipient object (ie. all slices must have the same size)
-
Functions with the number_of_... argument: expand the object by creating new rows/columns/slices.
By default, the new rows/columns/slices are set to zero.
If set_to_zero is false, the memory used by the new rows/columns/slices will not be initialised.
-
Examples:
mat A = randu<mat>(5,10);
mat B = ones<mat>(5,2);
// at column 2, insert a copy of B;
// A will now have 12 columns
A.insert_cols(2, B);
// at column 1, insert 5 zeroed columns;
// B will now have 7 columns
B.insert_cols(1, 5);
See also:
.shed_row( row_number )
.shed_rows( first_row, last_row )
|
|
(member functions of Mat, Col and SpMat)
|
|
.shed_col( column_number )
.shed_cols( first_column, last_column )
|
|
(member functions of Mat, Row and SpMat)
|
|
.shed_slice( slice_number )
.shed_slices( first_slice, last_slice )
|
|
(member functions of Cube)
|
See also:
.swap_rows( row1, row2 )
.swap_cols( col1, col2 )
See also:
.swap( X )
See also:
.memptr()
See also:
.colptr( col_number )
See also:
iterators (matrices & vectors)
-
STL-style iterators and associated member functions of Mat, Col, Row and SpMat
-
Member functions:
.begin()
|
|
iterator referring to the first element
|
.end()
|
|
iterator referring to the past-the-end element
|
|
.begin_row( row_number )
|
|
iterator referring to the first element of the specified row
|
.end_row( row_number )
|
|
iterator referring to the past-the-end element of the specified row
|
|
.begin_col( col_number )
|
|
iterator referring to the first element of the specified column
|
.end_col( col_number )
|
|
iterator referring to the past-the-end element of the specified column
|
-
Iterator types:
mat::iterator
vec::iterator
rowvec::iterator
sp_mat::iterator
|
|
random access iterators, for read/write access to elements
(which are stored column by column)
|
|
|
|
mat::const_iterator
vec::const_iterator
rowvec::const_iterator
sp_mat::const_iterator
|
|
random access iterators, for read-only access to elements
(which are stored column by column)
|
|
|
|
mat::col_iterator
vec::col_iterator
rowvec::col_iterator
|
|
random access iterators, for read/write access to the elements of a specific column
|
|
|
|
mat::const_col_iterator
vec::const_col_iterator
rowvec::const_col_iterator
|
|
random access iterators, for read-only access to the elements of a specific column
|
|
|
|
mat::row_iterator
sp_mat::row_iterator
|
|
rudimentary forward iterator, for read/write access to the elements of a specific row
|
|
|
|
mat::const_row_iterator
sp_mat::const_row_iterator
|
|
rudimentary forward iterator, for read-only access to the elements of a specific row
|
|
|
|
vec::row_iterator
rowvec::row_iterator
|
|
random access iterators, for read/write access to the elements of a specific row
|
|
|
|
vec::const_row_iterator
rowvec::const_row_iterator
|
|
random access iterators, for read-only access to the elements of a specific row
|
-
Examples:
mat X = randu<mat>(5,5);
mat::iterator a = X.begin();
mat::iterator b = X.end();
for(mat::iterator i=a; i!=b; ++i)
{
cout << *i << endl;
}
mat::col_iterator c = X.begin_col(1); // start of column 1
mat::col_iterator d = X.end_col(3); // end of column 3
for(mat::col_iterator i=c; i!=d; ++i)
{
cout << *i << endl;
(*i) = 123.0;
}
See also:
iterators (cubes)
-
STL-style iterators and associated member functions of Cube
-
Member functions:
.begin()
|
|
iterator referring to the first element
|
.end()
|
|
iterator referring to the past-the-end element
|
|
.begin_slice( slice_number )
|
|
iterator referring to the first element of the specified slice
|
.end_slice( slice_number )
|
|
iterator referring to the past-the-end element of the specified slice
|
-
Iterator types:
cube::iterator
|
|
random access iterator, for read/write access to elements;
the elements are ordered slice by slice;
the elements within each slice are ordered column by column
|
|
|
|
cube::const_iterator
|
|
random access iterators, for read-only access to elements
|
|
|
|
cube::slice_iterator
|
|
random access iterator, for read/write access to the elements of a particular slice;
the elements are ordered column by column
|
|
|
|
cube::const_slice_iterator
|
|
random access iterators, for read-only access to the elements of a particular slice
|
-
Examples:
cube X = randu<cube>(2,3,4);
cube::iterator a = X.begin();
cube::iterator b = X.end();
for(cube::iterator i=a; i!=b; ++i)
{
cout << *i << endl;
}
cube::slice_iterator c = X.begin_slice(1); // start of slice 1
cube::slice_iterator d = X.end_slice(2); // end of slice 2
for(cube::slice_iterator i=c; i!=d; ++i)
{
cout << *i << endl;
(*i) = 123.0;
}
See also:
STL-style container functions
See also:
.t()
.st()
See also:
.i()
See also:
.min()
.max()
See also:
.index_min()
.index_max()
See also:
.eval()
-
Member function of any matrix or vector expression
-
Explicitly forces the evaluation of a delayed expression and outputs a matrix
-
This function should be used sparingly and only in cases where it is absolutely necessary; indiscriminate use can cause slow downs
-
Examples:
cx_mat A( randu<mat>(4,4), randu<mat>(4,4) );
real(A).eval().save("A_real.dat", raw_ascii);
imag(A).eval().save("A_imag.dat", raw_ascii);
See also:
.in_range( i ) |
|
|
(member of Mat, Col, Row, Cube, SpMat, field)
|
.in_range( span(start, end) ) |
|
|
(member of Mat, Col, Row, Cube, SpMat, field)
|
|
.in_range( row, col ) |
|
|
(member of Mat, Col, Row, SpMat, field)
|
.in_range( span(start_row, end_row), span(start_col, end_col) ) |
|
|
(member of Mat, Col, Row, SpMat, field)
|
|
.in_range( row, col, slice ) |
|
|
(member of Cube and field)
|
.in_range( span(start_row, end_row), span(start_col, end_col), span(start_slice, end_slice) ) |
|
|
(member of Cube and field)
|
|
.in_range( first_row, first_col, size(X) ) (X is a matrix or field) |
|
|
(member of Mat, Col, Row, SpMat, field)
|
.in_range( first_row, first_col, size(n_rows, n_cols) ) |
|
|
(member of Mat, Col, Row, SpMat, field)
|
|
.in_range( first_row, first_col, first_slice, size(Q) ) (Q is a cube or field) |
|
|
(member of Cube and field)
|
.in_range( first_row, first_col, first_slice, size(n_rows, n_cols n_slices) ) |
|
|
(member of Cube and field)
|
- Returns true if the given location or span is currently valid
- Returns false if the object is empty, the location is out of bounds, or the span is out of bounds
-
Instances of span(a,b) can be replaced by:
- span() or span::all, to indicate the entire range
- span(a), to indicate a particular row, column or slice
-
Examples:
mat A = randu<mat>(4,5);
cout << A.in_range(0,0) << endl; // true
cout << A.in_range(3,4) << endl; // true
cout << A.in_range(4,5) << endl; // false
See also:
.is_empty()
See also:
.is_square()
See also:
.is_vec()
.is_colvec()
.is_rowvec()
-
Member functions of Mat and SpMat
- .is_vec():
- returns true if the matrix can be interpreted as a vector (either column or row vector)
- returns false if the matrix does not have exactly one column or one row
- .is_colvec():
- returns true if the matrix can be interpreted as a column vector
- returns false if the matrix does not have exactly one column
- .is_rowvec():
- returns true if the matrix can be interpreted as a row vector
- returns false if the matrix does not have exactly one row
- Caveat: do not assume that the vector has elements if these functions return true; it is possible to have an empty vector (eg. 0x1)
-
Examples:
mat A = randu<mat>(1,5);
mat B = randu<mat>(5,1);
mat C = randu<mat>(5,5);
cout << A.is_vec() << endl;
cout << B.is_vec() << endl;
cout << C.is_vec() << endl;
See also:
.is_sorted()
.is_sorted( sort_direction )
.is_sorted( sort_direction, dim )
-
Member function of Mat, Row and Col
-
If the object is a vector, return a bool indicating whether the elements are sorted
-
If the object is a matrix, return a bool indicating whether the elements are sorted in each column (dim=0), or each row (dim=1)
-
The sort_direction argument is optional; sort_direction is either
"ascend" or "descend" ; by default "ascend" is used
-
The dim argument is optional; by default dim=0 is used
-
For matrices and vectors with complex numbers, order is checked via absolute values
-
Examples:
vec a = randu<vec>(10);
vec b = sort(a);
bool check1 = a.is_sorted();
bool check2 = b.is_sorted();
mat A = randu<mat>(10,10);
// check whether each column is sorted in descending manner
cout << A.is_sorted("descend") << endl;
// check whether each row is sorted in ascending manner
cout << A.is_sorted("ascend", 1) << endl;
See also:
.is_finite()
-
Member function of Mat, Col, Row, Cube, SpMat
- Returns true if all elements of the object are finite
- Returns false if at least one of the elements of the object is non-finite (±infinity or NaN)
-
Examples:
mat A = randu<mat>(5,5);
mat B = randu<mat>(5,5);
B(1,1) = datum::inf;
cout << A.is_finite() << endl;
cout << B.is_finite() << endl;
See also:
.has_inf()
-
Member function of Mat, Col, Row, Cube, SpMat
- Returns true if at least one of the elements of the object is ±infinity
- Returns false otherwise
-
Examples:
mat A = randu<mat>(5,5);
mat B = randu<mat>(5,5);
B(1,1) = datum::inf;
cout << A.has_inf() << endl;
cout << B.has_inf() << endl;
See also:
.has_nan()
-
Member function of Mat, Col, Row, Cube, SpMat
- Returns true if at least one of the elements of the object is NaN (not-a-number)
- Returns false otherwise
-
Caveat:
NaN is not equal to anything, even itself
-
Examples:
mat A = randu<mat>(5,5);
mat B = randu<mat>(5,5);
B(1,1) = datum::nan;
cout << A.has_nan() << endl;
cout << B.has_nan() << endl;
See also:
.print()
.print( header )
.print( stream )
.print( stream, header )
-
Member functions of Mat, Col, Row, SpMat, Cube and field
-
Print the contents of an object to the std::cout stream (default),
or a user specified stream, with an optional header string
-
Objects can also be printed using the << stream operator
-
Elements of a field can only be printed if there is an associated operator<< function defined
-
Examples:
mat A = randu<mat>(5,5);
mat B = randu<mat>(6,6);
A.print();
// print a transposed version of A
A.t().print();
// "B:" is the optional header line
B.print("B:");
cout << A << endl;
cout << "B:" << endl;
cout << B << endl;
See also:
.raw_print()
.raw_print( header )
.raw_print( stream )
.raw_print( stream, header )
See also:
saving/loading matrices & cubes
.save( name )
.save( name, file_type )
.save( stream )
.save( stream, file_type )
|
|
.load( name )
.load( name, file_type )
.load( stream )
.load( stream, file_type )
|
- Member functions of Mat, Col, Row and Cube
-
Store/retrieve data in a file or stream
- caveat: the stream must be opened in binary mode
-
The default file_type for .save() is arma_binary (see below)
-
The default file_type for .load() is auto_detect (see below)
- On success, .save() and .load() will return a bool set to true
- .save() will return a bool set to false if the saving process fails
-
.load() will return a bool set to false if the loading process fails;
additionally, the object will be reset so it has no elements
-
file_type can be one of the following:
auto_detect |
|
Used by .load() only:
try to automatically detect the file type as one of the formats described below.
This is the default operation.
|
raw_ascii |
|
Numerical data stored in raw ASCII format, without a header.
The numbers are separated by whitespace.
The number of columns must be the same in each row.
Cubes are loaded as one slice.
Data which was saved in Matlab/Octave using the -ascii option can be read in Armadillo, except for complex numbers.
Complex numbers are stored in standard C++ notation, which is a tuple surrounded by brackets: eg. (1.23,4.56) indicates 1.24 + 4.56i.
|
raw_binary |
|
Numerical data stored in machine dependent raw binary format, without a header.
Matrices are loaded to have one column,
while cubes are loaded to have one slice with one column.
The .reshape() function can be used to alter the size of the loaded matrix/cube without losing data.
|
arma_ascii |
|
Numerical data stored in human readable text format, with a simple header to speed up loading.
The header indicates the type of matrix as well as the number of rows and columns.
For cubes, the header additionally specifies the number of slices.
|
arma_binary |
|
Numerical data stored in machine dependent binary format, with a simple header to speed up loading.
The header indicates the type of matrix as well as the number of rows and columns.
For cubes, the header additionally specifies the number of slices.
arma_binary is the default file_type for .save()
|
csv_ascii |
|
Numerical data stored in comma separated value (CSV) text format, without a header.
Applicable to Mat only.
|
hdf5_binary |
|
Numerical data stored in portable HDF5 binary format.
Caveat:
support for HDF5 must be enabled within Armadillo's configuration;
the hdf5.h header file must be available on your system and you will need to link with the hdf5 library (eg. -lhdf5)
|
hdf5_binary_trans |
|
As per hdf5_binary, but save/load the data with columns transposed to rows (and vice versa)
|
pgm_binary |
|
Image data stored in Portable Gray Map (PGM) format.
Applicable to Mat only.
Saving int, float or double matrices is a lossy operation, as each element is copied and converted to an 8 bit representation.
As such the matrix should have values in the [0,255] interval, otherwise the resulting image may not display correctly.
|
ppm_binary |
|
Image data stored in Portable Pixel Map (PPM) format.
Applicable to Cube only.
Saving int, float or double matrices is a lossy operation, as each element is copied and converted to an 8 bit representation.
As such the cube/field should have values in the [0,255] interval, otherwise the resulting image may not display correctly.
|
-
Examples:
mat A = randu<mat>(5,5);
A.save("A1.mat"); // default save format is arma_binary
A.save("A2.mat", arma_ascii); // force saving in arma_ascii format
mat B;
B.load("A1.mat"); // automatically detect format type
mat C;
C.load("A2.mat", arma_ascii); // force loading in arma_ascii format
// example of testing for success
mat D;
bool status = D.load("A2.mat");
if(status == true)
{
cout << "loaded okay" << endl;
}
else
{
cout << "problem with loading" << endl;
}
See also:
saving/loading fields
.save( name )
.save( name, file_type )
.save( stream )
.save( stream, file_type )
|
|
.load( name )
.load( name, file_type )
.load( stream )
.load( stream, file_type )
|
-
Store/retrieve data in a file or stream
- caveat: the stream must be opened in binary mode
- On success, .save() and .load() will return a bool set to true
- .save() will return a bool set to false if the saving process fails
-
.load() will return a bool set to false if the loading process fails;
additionally, the field will be reset so it has no elements
-
Fields with objects of type std::string are saved and loaded as raw text files.
The text files do not have a header.
Each string is separated by a whitespace.
load() will only accept text files that have the same number of strings on each line.
The strings can have variable lengths.
-
Other than storing string fields as text files, the following file formats are supported:
auto_detect |
|
-
.load(): try to automatically detect the field format type as one of the formats described below;
this is the default operation.
|
arma_binary |
|
-
Objects are stored in machine dependent binary format
-
Default type for fields of type Mat, Col, Row or Cube
-
Only applicable to fields of type Mat, Col, Row or Cube
|
ppm_binary |
|
-
Image data stored in Portable Pixmap Map (PPM) format.
-
Only applicable to fields of type Mat, Col or Row
-
.load(): loads the specified image and stores the red, green and blue components as three separate matrices;
the resulting field is comprised of the three matrices,
with the red, green and blue components in the first, second and third matrix, respectively
-
.save(): saves a field with exactly three matrices of equal size as an image;
it is assumed that the red, green and blue components are stored in the first, second and third matrix, respectively;
saving int, float or double matrices is a lossy operation,
as each matrix element is copied and converted to an 8 bit representation
|
- See also:
Generated Vectors/Matrices
eye( n_rows, n_cols )
eye( size(X) )
-
Generate a matrix with the elements along the main diagonal set to one
and off-diagonal elements set to zero
-
An identity matrix is generated when n_rows = n_cols
-
Usage:
- matrix_type X = eye<matrix_type>( n_rows, n_cols )
- matrix_type Y = eye<matrix_type>( size(X) )
-
Examples:
mat A = eye<mat>(5,5); // or: mat A(5,5,fill::eye);
mat B = 123.0 * eye<mat>(5,5);
mat C = eye<mat>( size(B) );
See also:
linspace( start, end )
linspace( start, end, N )
-
Generate a vector with N elements;
the values of the elements are linearly spaced from start to (and including) end
-
The argument N is optional; by default N = 100
-
Usage:
- vector_type v = linspace<vector_type>(start, end, N)
-
Caveat: if N ≤ 1, the generated vector will have a size of one, with the single element equal to end
-
Examples:
vec a = linspace<vec>(0, 5, 6);
vec b = linspace<vec>(5, 0, 6);
See also:
logspace( A, B )
logspace( A, B, N )
-
Generate a vector with N elements;
the values of the elements are logarithmically spaced from 10A to (and including) 10B
-
The argument N is optional; by default N = 50
-
Usage:
- vector_type v = logspace<vector_type>(A, B, N)
-
Examples:
vec a = logspace<vec>(0, 5, 6);
vec b = logspace<vec>(5, 0, 6);
See also:
ones( n_elem )
ones( n_rows, n_cols )
ones( n_rows, n_cols, n_slices )
ones( size(X) )
-
Generate a vector, matrix or cube with all elements set to one
-
Usage:
- vector_type v = ones<vector_type>( n_elem )
- matrix_type X = ones<matrix_type>( n_rows, n_cols )
- matrix_type Y = ones<matrix_type>( size(X) )
- cube_type Q = ones<cube_type>( n_rows, n_cols, n_slices )
- cube_type R = ones<cube_type>( size(Q) )
-
Examples:
vec v = ones<vec>(10);
uvec u = ones<uvec>(11);
mat A = ones<mat>(5,6);
cube Q = ones<cube>(5,6,7);
mat B = 123.0 * ones<mat>(5,6);
See also:
randi( n_elem )
randi( n_elem, distr_param(a,b) )
randi( n_rows, n_cols )
randi( n_rows, n_cols, distr_param(a,b) )
randi( n_rows, n_cols, n_slices )
randi( n_rows, n_cols, n_slices, distr_param(a,b) )
randi( size(X) )
randi( size(X), distr_param(a,b) )
-
Generate a vector, matrix or cube with the elements set to random integer values in the [a,b] interval
- The default distribution parameters are a=0 and b=maximum_int
-
Usage:
- vector_type v = randi<vector_type>( n_elem )
- vector_type v = randi<vector_type>( n_elem, distr_param(a,b) )
- matrix_type X = randi<matrix_type>( n_rows, n_cols )
- matrix_type X = randi<matrix_type>( n_rows, n_cols, distr_param(a,b) )
- matrix_type Y = randi<matrix_type>( size(X) )
- matrix_type Y = randi<matrix_type>( size(X), distr_param(a,b) )
- cube_type Q = randi<cube_type>( n_rows, n_cols, n_slices )
- cube_type Q = randi<cube_type>( n_rows, n_cols, n_slices, distr_param(a,b) )
- cube_type R = randi<cube_type>( size(Q) )
- cube_type R = randi<cube_type>( size(Q), distr_param(a,b) )
-
To change the RNG seed, use arma_rng::set_seed(value) or arma_rng::set_seed_random() functions
-
Caveat: to generate a continuous distribution with floating point values (ie. float or double),
use randu() or randn() instead
-
Examples:
imat A = randi<imat>(5, 6);
imat A = randi<imat>(6, 7, distr_param(-10, +20));
arma_rng::set_seed_random(); // set the seed to a random value
See also:
randu( n_elem )
randu( n_rows, n_cols )
randu( n_rows, n_cols, n_slices )
randu( size(X) )
randn( n_elem )
randn( n_rows, n_cols )
randn( n_rows, n_cols, n_slices )
randn( size(X) )
-
Generate a vector, matrix or cube with the elements set to random floating point values
- randu() uses a uniform distribution in the [0,1] interval
- randn() uses a normal/Gaussian distribution with zero mean and unit variance
-
Usage:
- vector_type v = randu<vector_type>( n_elem )
- matrix_type X = randu<matrix_type>( n_rows, n_cols )
- matrix_type Y = randu<matrix_type>( size(X) )
- cube_type Q = randu<cube_type>( n_rows, n_cols, n_slices )
- cube_type R = randu<cube_type>( size(Q) )
-
To change the RNG seed, use arma_rng::set_seed(value) or arma_rng::set_seed_random() functions
-
Caveat: to generate a matrix with random integer values instead of floating point values,
use randi() instead
-
Examples:
vec v = randu<vec>(5);
mat A = randu<mat>(5,6);
cube Q = randu<cube>(5,6,7);
arma_rng::set_seed_random(); // set the seed to a random value
See also:
randg( n_elem )
randg( n_elem, distr_param(a,b) )
randg( n_rows, n_cols )
randg( n_rows, n_cols, distr_param(a,b) )
randg( n_rows, n_cols, n_slices )
randg( n_rows, n_cols, n_slices, distr_param(a,b) )
randg( size(X) )
randg( size(X), distr_param(a,b) )
-
Generate a vector, matrix or cube with the elements set to random values from a gamma distribution:
| | x a-1 exp( -x / b ) |
p(x|a,b) | = |
|
| | b a Γ(a) |
- The default distribution parameters are a=1 and b=1
-
Usage:
- vector_type v = randg<vector_type>( n_elem )
- vector_type v = randg<vector_type>( n_elem, distr_param(a,b) )
- matrix_type X = randg<matrix_type>( n_rows, n_cols )
- matrix_type X = randg<matrix_type>( n_rows, n_cols, distr_param(a,b) )
- matrix_type Y = randg<matrix_type>( size(X) )
- matrix_type Y = randg<matrix_type>( size(X), distr_param(a,b) )
- cube_type Q = randg<cube_type>( n_rows, n_cols, n_slices )
- cube_type Q = randg<cube_type>( n_rows, n_cols, n_slices, distr_param(a,b) )
- cube_type R = randg<cube_type>( size(Q) )
- cube_type R = randg<cube_type>( size(Q), distr_param(a,b) )
-
Caveat: randg() is available only when using a C++11 compiler
-
To change the RNG seed, use arma_rng::set_seed(value) or arma_rng::set_seed_random() functions
-
Examples:
vec v = randg<vec>(100, distr_param(2,1));
mat X = randg<mat>(10, 10, distr_param(2,1));
See also:
regspace( start, end )
regspace( start, delta, end )
-
Generate a vector with regularly spaced elements:
[ (start + 0*delta), (start + 1*delta), (start + 2*delta), ⋯, (start + M*delta) ]
where M = floor((end-start)/delta), so that (start + M*delta) ≤ end
-
Similar in operation to the Matlab/Octave colon operator, ie. start:end and start:delta:end
-
If delta is not specified:
- delta = +1, if start ≤ end
- delta = −1, if start > end (caveat: this is different to Matlab/Octave)
-
An empty vector is generated when one of the following conditions is true:
- start < end, and delta < 0
- start > end, and delta > 0
- delta = 0
-
Usage:
- vector_type v = regspace<vector_type>(start, end)
- vector_type v = regspace<vector_type>(start, delta, end)
-
Examples:
vec a = regspace< vec>(0, 9); // 0, 1, ..., 9
uvec b = regspace<uvec>(2, 2, 10); // 2, 4, ..., 10
ivec c = regspace<ivec>(0, -1, -10); // 0, -1, ..., -10
Caveat: do not use regspace() to specify ranges for contiguous submatrix views; use span() instead
See also:
speye( n_rows, n_cols )
speye( size(X) )
See also:
spones( A )
See also:
sprandu( n_rows, n_cols, density )
sprandn( n_rows, n_cols, density )
sprandu( size(X), density )
sprandn( size(X), density )
See also:
toeplitz( A )
toeplitz( A, B )
circ_toeplitz( A )
See also:
zeros( n_elem )
zeros( n_rows, n_cols )
zeros( n_rows, n_cols, n_slices )
zeros( size(X) )
-
Generate a vector, matrix or cube with the elements set to zero
-
Usage:
- vector_type v = zeros<vector_type>( n_elem )
- matrix_type X = zeros<matrix_type>( n_rows, n_cols )
- matrix_type Y = zeros<matrix_type>( size(X) )
- cube_type Q = zeros<cube_type>( n_rows, n_cols, n_slices )
- cube_type R = zeros<cube_type>( size(Q) )
-
Examples:
vec v = zeros<vec>(10);
uvec u = zeros<uvec>(11);
mat A = zeros<mat>(5,6);
cube Q = zeros<cube>(5,6,7);
See also:
Functions of Vectors/Matrices/Cubes
abs( X )
See also:
accu( X )
-
Accumulate (sum) all elements of a vector, matrix or cube
-
Examples:
mat A(5, 6, fill::randu);
mat B(5, 6, fill::randu);
double x = accu(A);
double y = accu(A % B);
// accu(A % B) is a "multiply-and-accumulate" operation
// as operator % performs element-wise multiplication
See also:
all( V )
all( X )
all( X, dim )
- For vector V, return true if all elements of the vector are non-zero or satisfy a relational condition
-
For matrix X and
-
dim=0, return a row vector (of type urowvec or umat),
with each element (0 or 1) indicating whether the corresponding column of X has all non-zero elements
-
dim=1, return a column vector (of type ucolvec or umat),
with each element (0 or 1) indicating whether the corresponding row of X has all non-zero elements
-
The dim argument is optional; by default dim=0 is used
-
Relational operators can be used instead of V or X, eg. A > 0.5
-
Examples:
vec V = randu<vec>(10);
mat X = randu<mat>(5,5);
// status1 will be set to true if vector V has all non-zero elements
bool status1 = all(V);
// status2 will be set to true if vector V has all elements greater than 0.5
bool status2 = all(V > 0.5);
// status3 will be set to true if matrix X has all elements greater than 0.6;
// note the use of vectorise()
bool status3 = all(vectorise(X) > 0.6);
// generate a row vector indicating which columns of X have all elements greater than 0.7
umat A = all(X > 0.7);
See also:
any( V )
any( X )
any( X, dim )
- For vector V, return true if any element of the vector is non-zero or satisfies a relational condition
-
For matrix X and
-
dim=0, return a row vector (of type urowvec or umat),
with each element (0 or 1) indicating whether the corresponding column of X has any non-zero elements
-
dim=1, return a column vector (of type ucolvec or umat),
with each element (0 or 1) indicating whether the corresponding row of X has any non-zero elements
-
The dim argument is optional; by default dim=0 is used
-
Relational operators can be used instead of V or X, eg. A > 0.9
-
Examples:
vec V = randu<vec>(10);
mat X = randu<mat>(5,5);
// status1 will be set to true if vector V has any non-zero elements
bool status1 = any(V);
// status2 will be set to true if vector V has any elements greater than 0.5
bool status2 = any(V > 0.5);
// status3 will be set to true if matrix X has any elements greater than 0.6;
// note the use of vectorise()
bool status3 = any(vectorise(X) > 0.6);
// generate a row vector indicating which columns of X have elements greater than 0.7
umat A = any(X > 0.7);
See also:
approx_equal( A, B, method, tol )
approx_equal( A, B, method, abs_tol, rel_tol )
-
Return true if all corresponding elements in A and B are approximately equal
-
Return false if any of the corresponding elements in A and B are not approximately equal, or if A and B have different dimensions
-
The argument method controls how the approximate equality is determined; it is one of:
"absdiff" | ↦ | scalars x and y are considered equal if |x − y| ≤ tol |
"reldiff" | ↦ | scalars x and y are considered equal if |x − y| / max( |x|, |y| ) ≤ tol |
"both" | ↦ | scalars x and y are considered equal if |x − y| ≤ abs_tol or |x − y| / max( |x|, |y| ) ≤ rel_tol |
-
Examples:
mat A = randu<mat>(5,5);
mat B = A + 0.001;
bool same1 = approx_equal(A, B, "absdiff", 0.002);
mat C = 1000 * randu<mat>(5,5);
mat D = C + 1;
bool same2 = approx_equal(C, D, "reldiff", 0.1);
bool same3 = approx_equal(C, D, "both", 2, 0.1);
See also:
as_scalar( expression )
See also:
clamp( X, min_val, max_val )
-
Create a copy of X with each element clamped to be between min_val and max_val
-
Examples:
mat A = randu<mat>(5,5);
mat B = clamp(A, 0.2, 0.8);
mat C = clamp(A, A.min(), 0.8);
mat D = clamp(A, 0.2, A.max());
See also:
cond( A )
See also:
conj( X )
See also:
conv_to< type >::from( X )
See also:
cross( A, B )
See also:
cumsum( V )
cumsum( X )
cumsum( X, dim )
See also:
cumprod( V )
cumprod( X )
cumprod( X, dim )
See also:
det( A )
log_det( val, sign, A )
See also:
diagmat( V )
diagmat( V, k )
diagmat( X )
diagmat( X, k )
-
Generate a diagonal matrix from vector V or matrix X
-
Given vector V, generate a square matrix with the k-th diagonal containing a copy of the vector; all other elements are set to zero
-
Given matrix X, generate a matrix with the k-th diagonal containing a copy of the k-th diagonal of X; all other elements are set to zero
-
The argument k is optional; by default the main diagonal is used (k=0)
-
For k > 0, the k-th super-diagonal is used (top-right corner)
-
For k < 0, the k-th sub-diagonal is used (bottom-left corner)
-
Examples:
mat A = randu<mat>(5,5);
mat B = diagmat(A);
mat C = diagmat(A,1);
vec v = randu<vec>(5);
mat D = diagmat(v);
mat E = diagmat(v,1);
See also:
diagvec( A )
diagvec( A, k )
See also:
diff( V )
diff( V, k )
diff( X )
diff( X, k )
diff( X, k, dim )
See also:
dot( A, B )
cdot( A, B )
norm_dot( A, B )
See also:
eps( X )
See also:
B = expmat(A)
expmat(B, A)
See also:
B = expmat_sym(A)
expmat_sym(B, A)
See also:
find( X )
find( X, k )
find( X, k, s )
- Return a column vector containing the indices of elements of X that are non-zero or satisfy a relational condition
- The output vector must have the type uvec
(ie. the indices are stored as unsigned integers of type uword)
-
X is interpreted as a vector, with column-by-column ordering of the elements of X
- Relational operators can be used instead of X, eg. A > 0.5
- If k=0 (default), return the indices of all non-zero elements, otherwise return at most k of their indices
- If s="first" (default), return at most the first k indices of the non-zero elements
- If s="last", return at most the last k indices of the non-zero elements
-
Examples:
mat A = randu<mat>(5,5);
mat B = randu<mat>(5,5);
uvec q1 = find(A > B);
uvec q2 = find(A > 0.5);
uvec q3 = find(A > 0.5, 3, "last");
// change elements of A greater than 0.5 to 1
A.elem( find(A > 0.5) ).ones();
See also:
find_finite( X )
See also:
find_nonfinite( X )
See also:
find_unique( X )
find_unique( X, ascending_indices )
See also:
fliplr( X )
flipud( X )
See also:
imag( X )
real( X )
Caveat: versions 4.4, 4.5 and 4.6 of the GCC C++ compiler have a bug when using the -std=c++0x compiler option (ie. experimental support for C++11);
to work around this bug, preface Armadillo's imag() and real() with the arma namespace qualification, eg. arma::imag(C)
See also:
uvec | sub = ind2sub( size(X), index ) |
umat | sub = ind2sub( size(X), vector_of_indices ) |
-
Convert a linear index, or a vector of indices, to subscript notation
-
The argument size(X) can be replaced with size(n_rows, n_cols) or size(n_rows, n_cols, n_slices)
-
A std::logic_error exception is thrown if an index is out of range
-
When only one index is given, the subscripts are returned in a vector of type uvec
-
When a vector of indices (of type uvec) is given, the corresponding subscripts are returned in each column of an m x n matrix of type umat;
m=2 for matrix subscripts, while m=3 for cube subscripts
-
Examples:
mat M(4, 5, fill::randu);
uvec s = ind2sub( size(M), 6 );
cout << "row: " << s(0) << endl;
cout << "col: " << s(1) << endl;
uvec indices = find(M > 0.5);
umat t = ind2sub( size(M), indices );
cube Q(2,3,4);
uvec u = ind2sub( size(Q), 8 );
cout << "row: " << u(0) << endl;
cout << "col: " << u(1) << endl;
cout << "slice: " << u(2) << endl;
See also:
index_min( V )
index_min( M )
index_min( M, dim )
|
|
index_max( V )
index_max( M )
index_max( M, dim )
|
-
For vector V, return the linear index of the extremum value; the returned index is of type uword
-
For matrix M and:
-
dim=0, return a row vector (of type urowvec or umat),
with each column containing the index of the extremum value in the corresponding column of M
-
dim=1, return a column vector (of type uvec or umat),
with each row containing the index of the extremum value in the corresponding row of M
-
For each column and row, the index starts at zero
-
The dim argument is optional; by default dim=0 is used
-
For objects with complex numbers, absolute values are used for comparison
-
Examples:
vec v = randu<vec>(10);
uword i = index_max(v);
double max_val_in_v = v(i);
mat M = randu<mat>(5,6);
urowvec ii = index_max(M);
ucolvec jj = index_max(M,1);
double max_val_in_col_2 = M( ii(2), 2 );
double max_val_in_row_4 = M( 4, jj(4) );
See also:
inplace_trans( X )
inplace_trans( X, method )
inplace_strans( X )
inplace_strans( X, method )
-
In-place / in-situ transpose of matrix X
-
For real (non-complex) matrix:
- inplace_trans() performs a normal transpose
- inplace_strans() not applicable
-
For complex matrix:
- inplace_trans() performs a Hermitian transpose (ie. the conjugate of the elements is taken during the transpose)
- inplace_strans() provides a transposed copy without taking the conjugate of the elements
-
The argument method is optional
-
By default, a greedy transposition algorithm is used; a low-memory algorithm can be used instead by explicitly setting method to
"lowmem"
-
The low-memory algorithm is considerably slower than the greedy algorithm;
using the low-memory algorithm is only recommended for cases where X takes up more than half of available memory (ie. very large X)
-
Examples:
mat X = randu<mat>(4,5);
mat Y = randu<mat>(20000,30000);
inplace_trans(X); // use greedy algorithm by default
inplace_trans(Y, "lowmem"); // use low-memory (and slow) algorithm
See also:
is_finite( X )
-
Returns true if all elements in X are finite
-
Returns false if at least one element in X is non-finite (±infinity or NaN)
-
X can be a scalar (eg. double), vector, matrix or cube
-
Examples:
mat A = randu<mat>(5,5);
mat B = randu<mat>(5,5);
B(1,1) = datum::inf;
cout << is_finite(A) << endl;
cout << is_finite(B) << endl;
cout << is_finite( 0.123456789 ) << endl;
cout << is_finite( datum::nan ) << endl;
cout << is_finite( datum::inf ) << endl;
See also:
join_rows( A, B )
join_horiz( A, B )
join_cols( A, B )
join_vert( A, B )
-
join_rows() and join_horiz(): horizontal concatenation;
for two matrices A and B, join each row of A with the corresponding row of B;
matrices A and B must have the same number of rows
-
join_cols() and join_vert(): vertical concatenation;
for two matrices A and B, join each column of A with the corresponding column of B;
matrices A and B must have the same number of columns
-
Examples:
mat A = randu<mat>(4,5);
mat B = randu<mat>(4,6);
mat C = randu<mat>(6,5);
mat X = join_rows(A,B);
mat Y = join_cols(A,C);
See also:
join_slices( cube C, cube D )
join_slices( mat M, mat N )
join_slices( mat M, cube C )
join_slices( cube C, mat M )
-
for two cubes C and D: join the slices of C with the slices of D;
cubes C and D must have the same number of rows and columns (ie. all slices must have the same size)
-
for two matrices M and N: treat M and N as cube slices and join them to form a cube with 2 slices;
matrices M and N must have the same number of rows and columns
-
for matrix M and cube C: treat M as a cube slice and join it with the slices of C;
matrix M and cube C must have the same number of rows and columns
-
Examples:
cube C(5, 10, 3, fill::randu);
cube D(5, 10, 4, fill::randu);
cube E = join_slices(C,D);
mat M(10, 20, fill::randu);
mat N(10, 20, fill::randu);
cube Q = join_slices(M,N);
cube R = join_slices(Q,M);
cube S = join_slices(M,Q);
See also:
kron( A, B )
See also:
B = logmat(A)
logmat(B, A)
See also:
B = logmat_sympd(A)
logmat_sympd(B, A)
See also:
min( V )
min( M )
min( M, dim )
min( Q )
min( Q, dim )
min( A, B )
|
|
max( V )
max( M )
max( M, dim )
max( Q )
max( Q, dim )
max( A, B )
|
-
For vector V, return the extremum value
-
For matrix M, return the extremum value for each column (dim=0), or each row (dim=1)
-
For cube Q, return the extremum values of elements along dimension dim, where dim ∈ { 0, 1, 2 }
-
The dim argument is optional; by default dim=0 is used
-
For two matrices/cubes A and B, return a matrix/cube containing element-wise extremum values
-
For objects with complex numbers, absolute values are used for comparison
-
Examples:
colvec v = randu<colvec>(10,1);
double x = max(v);
mat M = randu<mat>(10,10);
rowvec a = max(M);
rowvec b = max(M,0);
colvec c = max(M,1);
// element-wise maximum
mat X = randu<mat>(5,6);
mat Y = randu<mat>(5,6);
mat Z = arma::max(X,Y); // use arma:: prefix to distinguish from std::max()
See also:
nonzeros(X)
-
Return a column vector containing the non-zero values of X
-
X can be a sparse or dense matrix
-
Examples:
sp_mat A = sprandu<sp_mat>(100, 100, 0.1);
vec a = nonzeros(A);
mat B(100, 100, fill::eye);
vec b = nonzeros(B);
See also:
norm( X )
norm( X, p )
See also:
normalise( V )
normalise( V, p )
normalise( X )
normalise( X, p )
normalise( X, p, dim )
- For vector V, return its normalised version (ie. having unit p-norm)
-
For matrix X, return its normalised version, where each column (dim=0) or row (dim=1) has been normalised to have unit p-norm
-
The p argument is optional; by default p=2 is used
-
The dim argument is optional; by default dim=0 is used
-
Examples:
vec A = randu<vec>(10);
vec B = normalise(A);
vec C = normalise(A, 1);
mat X = randu<mat>(5,6);
mat Y = normalise(X);
mat Z = normalise(X, 2, 1);
See also:
prod( V )
prod( M )
prod( M, dim )
-
For vector V, return the product of all elements
-
For matrix M, return the product of elements in each column (dim=0), or each row (dim=1)
-
The dim argument is optional; by default dim=0 is used
-
Examples:
colvec v = randu<colvec>(10,1);
double x = prod(v);
mat M = randu<mat>(10,10);
rowvec a = prod(M);
rowvec b = prod(M,0);
colvec c = prod(M,1);
See also:
rank( X )
rank( X, tolerance )
See also:
rcond( A )
See also:
repmat( A, num_copies_per_row, num_copies_per_col )
See also:
reshape( mat, n_rows, n_cols )
reshape( mat, size(X) )
reshape( cube, n_rows, n_cols, n_slices )
reshape( cube, size(X) )
See also:
resize( mat, n_rows, n_cols )
resize( mat, size(X) )
resize( cube, n_rows, n_cols, n_slices )
resize( cube, size(X) )
See also:
shift( V, N )
shift( X, N )
shift( X, N, dim )
See also:
shuffle( V )
shuffle( X )
shuffle( X, dim )
See also:
size( X )
size( n_rows, n_cols )
size( n_rows, n_cols, n_slices )
-
Obtain the dimensions of object X, or explicitly specify the dimensions
-
The dimensions can be used in conjunction with:
-
The dimensions support simple arithmetic operations; they can also be printed and compared for equality/inequality
-
Examples:
mat A(5,6);
mat B(size(A), fill::zeros);
mat C; C.randu(size(A));
mat D = ones<mat>(size(A));
mat E(10,20, fill::ones);
E(3,4,size(C)) = C; // access submatrix of E
mat F( size(A) + size(E) );
mat G( size(A) * 2 );
cout << "size of A: " << size(A) << endl;
bool is_same_size = (size(A) == size(E));
See also:
sort( V )
sort( V, sort_direction )
sort( X )
sort( X, sort_direction )
sort( X, sort_direction, dim )
See also:
sort_index( X )
sort_index( X, sort_direction )
stable_sort_index( X )
stable_sort_index( X, sort_direction )
See also:
B = sqrtmat(A)
sqrtmat(B,A)
See also:
B = sqrtmat_sympd(A)
sqrtmat_sympd(B,A)
See also:
sum( V )
sum( M )
sum( M, dim )
sum( Q )
sum( Q, dim )
-
For vector V, return the sum of all elements
-
For matrix M, return the sum of elements in each column (dim=0), or each row (dim=1)
-
For cube Q, return the sums of elements along dimension dim, where dim ∈ { 0, 1, 2 };
for example, dim=0 indicates the sum of elements in each column within each slice
-
The dim argument is optional; by default dim=0 is used
-
Caveat: to get a sum of all the elements regardless of the object type (ie. vector, or matrix, or cube), use accu() instead
-
Examples:
colvec v = randu<colvec>(10,1);
double x = sum(v);
mat M = randu<mat>(10,10);
rowvec a = sum(M);
rowvec b = sum(M,0);
colvec c = sum(M,1);
double y = accu(M); // find the overall sum regardless of object type
See also:
uword | index | = sub2ind( size(M), row, col ) | (M is a matrix) |
uvec | indices | = sub2ind( size(M), matrix_of_subscripts ) | |
| | | |
uword | index | = sub2ind( size(Q), row, col, slice ) | (Q is a cube) |
uvec | indices | = sub2ind( size(Q), matrix_of_subscripts ) | |
-
Convert subscripts to a linear index
-
The argument size(X) can be replaced with size(n_rows, n_cols) or size(n_rows, n_cols, n_slices)
-
For the matrix_of_subscripts argument, the subscripts must be stored in each column of an m x n matrix of type umat;
m=2 for matrix subscripts, while m=3 for cube subscripts
-
A std::logic_error exception is thrown if a subscript is out of range
-
Examples:
mat M(4,5);
cube Q(4,5,6);
uword i = sub2ind( size(M), 2, 3 );
uword j = sub2ind( size(Q), 2, 3, 4 );
See also:
symmatu( A )
symmatu( A, do_conj )
symmatl( A )
symmatl( A, do_conj )
See also:
trace( X )
See also:
trans( A )
strans( A )
See also:
trapz( X, Y )
trapz( X, Y, dim )
trapz( Y )
trapz( Y, dim )
See also:
trimatu( A )
trimatl( A )
See also:
unique( A )
See also:
vectorise( A )
vectorise( A, dim )
See also:
miscellaneous element-wise functions:
exp | | exp2 | | exp10 | | trunc_exp |
log | | log2 | | log10 | | trunc_log |
pow | | square | | sqrt | | |
floor | | ceil | | round | | trunc |
erf | | erfc | | | | |
lgamma | | | | | | |
sign | | | | | | |
See also:
trigonometric element-wise functions (cos, sin, tan, ...)
See also:
Decompositions, Factorisations, Inverses and Equation Solvers (Dense Matrices)
R = chol( X )
R = chol( X, layout )
chol( R, X )
chol( R, X, layout )
See also:
vec eigval = eig_sym( X )
eig_sym( eigval, X )
eig_sym( eigval, eigvec, X )
eig_sym( eigval, eigvec, X, method )
- Eigen decomposition of dense symmetric/hermitian matrix X
- The eigenvalues and corresponding eigenvectors are stored in eigval and eigvec, respectively
- The eigenvalues are in ascending order
- If X is not square sized, a std::logic_error exception is thrown
-
The method argument is optional; method is either
"dc" or "std"
-
"dc" indicates divide-and-conquer method (default setting)
-
"std" indicates standard method
-
the divide-and-conquer method provides slightly different results than the standard method, but is considerably faster for large matrices
- If the decomposition fails:
- eigval = eig_sym(X) resets eigval and throws a std::runtime_error exception
- eig_sym(eigval,X) resets eigval and returns a bool set to false (exception is not thrown)
- eig_sym(eigval,eigvec,X) resets eigval & eigvec and returns a bool set to false (exception is not thrown)
- Caveat: there is currently no check whether X is symmetric
-
Examples:
// for matrices with real elements
mat A = randu<mat>(50,50);
mat B = A.t()*A; // generate a symmetric matrix
vec eigval;
mat eigvec;
eig_sym(eigval, eigvec, B);
// for matrices with complex elements
cx_mat C = randu<cx_mat>(50,50);
cx_mat D = C.t()*C;
vec eigval2;
cx_mat eigvec2;
eig_sym(eigval2, eigvec2, D);
See also:
cx_vec eigval = eig_gen( X )
eig_gen( eigval, X )
eig_gen( eigval, eigvec, X )
See also:
cx_vec eigval = eig_pair( A, B )
eig_pair( eigval, A, B )
eig_pair( eigval, eigvec, A, B )
-
Eigen decomposition for pair of general dense square matrices A and B of the same size,
such that A*eigvec = B*eigvec*diagmat(eigval)
- The eigenvalues and corresponding eigenvectors are stored in eigval and eigvec, respectively
- If A or B is not square sized, a std::logic_error exception is thrown
- If the decomposition fails:
- eigval = eig_pair(A,B) resets eigval and throws a std::runtime_error exception
- eig_pair(eigval,A,B) resets eigval and returns a bool set to false (exception is not thrown)
- eig_pair(eigval,eigvec,A,B) resets eigval & eigvec and returns a bool set to false (exception is not thrown)
-
Examples:
mat A = randu<mat>(10,10);
mat B = randu<mat>(10,10);
cx_vec eigval;
cx_mat eigvec;
eig_pair(eigval, eigvec, A, B);
See also:
B = inv( A )
inv( B, A )
See also:
B = inv_sympd( A )
inv_sympd( B, A )
See also:
lu( L, U, P, X )
lu( L, U, X )
-
Lower-upper decomposition (with partial pivoting) of matrix X
-
The first form provides
a lower-triangular matrix L,
an upper-triangular matrix U,
and a permutation matrix P,
such that P.t()*L*U = X
-
The second form provides permuted L and U, such that L*U = X;
note that in this case L is generally not lower-triangular
-
If the decomposition fails:
- lu(L,U,P,X) resets L, U, P and returns a bool set to false (exception is not thrown)
- lu(L,U,X) resets L, U and returns a bool set to false (exception is not thrown)
-
Examples:
mat A = randu<mat>(5,5);
mat L, U, P;
lu(L, U, P, A);
mat B = P.t()*L*U;
See also:
B = null( A )
B = null( A, tolerance )
null( B, A )
null( B, A, tolerance )
See also:
B = orth( A )
B = orth( A, tolerance )
orth( B, A )
orth( B, A, tolerance )
See also:
B = pinv( A )
B = pinv( A, tolerance )
B = pinv( A, tolerance, method )
pinv( B, A )
pinv( B, A, tolerance )
pinv( B, A, tolerance, method )
See also:
qr( Q, R, X )
-
Decomposition of X into an orthogonal matrix Q and a right triangular matrix R, such that Q*R = X
-
If the decomposition fails, Q and R are reset and the function returns a bool set to false (exception is not thrown)
-
Examples:
mat X = randu<mat>(5,5);
mat Q, R;
qr(Q,R,X);
See also:
qr_econ( Q, R, X )
-
Economical decomposition of X (with size m x n) into an orthogonal matrix Q and a right triangular matrix R, such that Q*R = X
-
If m > n, only the first n rows of R and the first n columns of Q are calculated
(ie. the zero rows of R and the corresponding columns of Q are omitted)
-
If the decomposition fails, Q and R are reset and the function returns a bool set to false (exception is not thrown)
-
Examples:
mat X = randu<mat>(6,5);
mat Q, R;
qr_econ(Q,R,X);
See also:
qz( AA, BB, Q, Z, A, B )
qz( AA, BB, Q, Z, A, B, select )
-
Generalised Schur decomposition for pair of general square matrices A and B of the same size,
such that A = Q.t()*AA*Z.t() and B = Q.t()*BB*Z.t()
- The select argument is optional and specifies the ordering of the top left of the Schur form; it is one of the following:
"none" | | no selection (default operation) |
"lhp" | | left-half-plane: eigenvalues with real part < 0 |
"rhp" | | right-half-plane: eigenvalues with real part > 0 |
"iuc" | | inside-unit-circle: eigenvalues with absolute value < 1 |
"ouc" | | outside-unit-circle: eigenvalues with absolute value > 1 |
- The left and right Schur vectors are stored in Q and Z, respectively
- In the complex-valued problem, the generalised eigenvalues are found in diagvec(AA) / diagvec(BB)
- If A or B is not square sized, a std::logic_error exception is thrown
- If the decomposition fails, AA, BB, Q and Z are reset, and the function returns a bool set to false (exception is not thrown)
-
Examples:
mat A = randu<mat>(10,10);
mat B = randu<mat>(10,10);
mat AA;
mat BB;
mat Q;
mat Z;
qz(AA, BB, Q, Z, A, B);
See also:
S = schur( X )
schur( S, X )
schur( U, S, X )
- Schur decomposition of square matrix X, such that X = U*S*U.t()
- U is a unitary matrix containing the Schur vectors
- S is an upper triangular matrix, called the Schur form of X
- If X is not square sized, a std::logic_error exception is thrown
- If the decomposition fails:
- S = schur(X) resets S and throws a std::runtime_error exception
- schur(S,X) resets S and returns a bool set to false (exception is not thrown)
- schur(U,S,X) resets U & S and returns a bool set to false (exception is not thrown)
-
Caveat: in general, Schur decomposition is not unique
-
Examples:
mat X(20,20, fill::randu);
mat U;
mat S;
schur(U, S, X);
See also:
X = solve( A, B )
X = solve( A, B, settings )
solve( X, A, B )
solve( X, A, B, settings )
- Solve a dense system of linear equations, A*X = B, where X is unknown;
similar functionality to the \ operator in Matlab/Octave, ie. X = A \ B
- A can be square (critically determined system), or non-square (under/over-determined system)
-
B can be a vector or matrix
-
The number of rows in A and B must be the same
- The settings argument is optional; it is one of the following, or a combination thereof:
solve_opts::fast | | fast mode: do not apply iterative refinement and/or equilibration |
solve_opts::equilibrate | | equilibrate the system before solving (matrix A must be square) |
solve_opts::no_approx | | do not find approximate solutions for rank deficient systems |
the above settings can be combined using the + operator; for example: solve_opts::fast + solve_opts::no_approx
-
Caveat: using
solve_opts::fast will speed up finding the solution, but for poorly conditioned systems the solution may have lower quality
-
If A is known to be a triangular matrix,
the solution can be computed faster by explicitly indicating that A is triangular through trimatu() or trimatl();
indicating a triangular matrix also implies that solve_opts::fast is enabled
-
If no solution is found:
- X = solve(A,B) resets X and throws a std::runtime_error exception
- solve(X,A,B) resets X and returns a bool set to false (exception is not thrown)
-
Examples:
mat A = randu<mat>(5,5);
vec b = randu<vec>(5);
mat B = randu<mat>(5,5);
vec x1 = solve(A, b);
vec x2;
bool status = solve(x2, A, b);
mat X1 = solve(A, B);
mat X2 = solve(A, B, solve_opts::fast); // enable fast mode
mat X3 = solve(trimatu(A), B); // indicate that A is triangular
See also:
vec s = svd( X )
svd( vec s, X )
svd( mat U, vec s, mat V, mat X )
svd( mat U, vec s, mat V, mat X, method )
svd( cx_mat U, vec s, cx_mat V, cx_mat X )
svd( cx_mat U, vec s, cx_mat V, cx_mat X, method )
-
Singular value decomposition of dense matrix X
- If X is square, it can be reconstructed using X = U*diagmat(s)*V.t()
-
The singular values are in descending order
-
The method argument is optional; method is either
"dc" or "std"
-
"dc" indicates divide-and-conquer method (default setting)
-
"std" indicates standard method
-
the divide-and-conquer method provides slightly different results than the standard method, but is considerably faster for large matrices
-
If the decomposition fails, the output objects are reset and:
- s = svd(X) resets s and throws a std::runtime_error exception
- svd(s,X) resets s and returns a bool set to false (exception is not thrown)
- svd(U,s,V,X) resets U, s, V and returns a bool set to false (exception is not thrown)
-
Examples:
mat X = randu<mat>(5,5);
mat U;
vec s;
mat V;
svd(U,s,V,X);
See also:
svd_econ( mat U, vec s, mat V, mat X )
svd_econ( mat U, vec s, mat V, mat X, mode )
svd_econ( mat U, vec s, mat V, mat X, mode, method )
svd_econ( cx_mat U, vec s, cx_mat V, cx_mat X )
svd_econ( cx_mat U, vec s, cx_mat V, cx_mat X, mode )
svd_econ( cx_mat U, vec s, cx_mat V, cx_mat X, mode, method )
-
Economical singular value decomposition of dense matrix X
-
The singular values are in descending order
-
The mode argument is optional; mode is one of:
| "both" | = | compute both left and right singular vectors (default operation) |
| "left" | = | compute only left singular vectors |
| "right" | = | compute only right singular vectors |
-
The method argument is optional; method is either
"dc" or "std"
-
"dc" indicates divide-and-conquer method (default setting)
-
"std" indicates standard method
-
the divide-and-conquer method provides slightly different results than the standard method, but is considerably faster for large matrices
-
If the decomposition fails, U, s, V are reset and a bool set to false is returned (exception is not thrown)
-
Examples:
mat X = randu<mat>(4,5);
mat U;
vec s;
mat V;
svd_econ(U, s, V, X);
See also:
X = syl( A, B, C )
syl( X, A, B, C )
- Solve the Sylvester equation, ie. AX + XB + C = 0, where X is unknown
- Matrices A, B and C must be square sized
-
If no solution is found:
- syl(A,B,C) resets X and throws a std::runtime_error exception
- syl(X,A,B,C) resets X and returns a bool set to false (exception is not thrown)
-
Examples:
mat A = randu<mat>(5,5);
mat B = randu<mat>(5,5);
mat C = randu<mat>(5,5);
mat X1 = syl(A, B, C);
mat X2;
syl(X2, A, B, C);
See also:
Decompositions, Factorisations and Equation Solvers (Sparse Matrices)
vec eigval = eigs_sym( X, k )
vec eigval = eigs_sym( X, k, form )
vec eigval = eigs_sym( X, k, form, tol )
eigs_sym( eigval, X, k )
eigs_sym( eigval, X, k, form )
eigs_sym( eigval, X, k, form, tol )
eigs_sym( eigval, eigvec, X, k )
eigs_sym( eigval, eigvec, X, k, form )
eigs_sym( eigval, eigvec, X, k, form, tol )
- Obtain a limited number of eigenvalues and eigenvectors of sparse symmetric real matrix X
-
k specifies the number of eigenvalues and eigenvectors
- The argument form is optional; form is one of:
"lm" | = | obtain eigenvalues with largest magnitude (default operation) |
"sm" | = | obtain eigenvalues with smallest magnitude |
"la" | = | obtain eigenvalues with largest algebraic value |
"sa" | = | obtain eigenvalues with smallest algebraic value |
-
The argument tol is optional; it specifies the tolerance for convergence
- The eigenvalues and corresponding eigenvectors are stored in eigval and eigvec, respectively
- If X is not square sized, a std::logic_error exception is thrown
- If the decomposition fails:
- eigval = eigs_sym(X,k) resets eigval and throws a std::runtime_error exception
- eigs_sym(eigval,X,k) resets eigval and returns a bool set to false (exception is not thrown)
- eigs_sym(eigval,eigvec,X,k) resets eigval & eigvec and returns a bool set to false (exception is not thrown)
- Caveat: there is currently no check whether X is symmetric
-
Examples:
// generate sparse matrix
sp_mat A = sprandu<sp_mat>(1000, 1000, 0.1);
sp_mat B = A.t()*A;
vec eigval;
mat eigvec;
eigs_sym(eigval, eigvec, B, 5); // find 5 eigenvalues/eigenvectors
See also:
cx_vec eigval = eigs_gen( X, k )
cx_vec eigval = eigs_gen( X, k, form )
cx_vec eigval = eigs_gen( X, k, form, tol )
eigs_gen( eigval, X, k )
eigs_gen( eigval, X, k, form )
eigs_gen( eigval, X, k, form, tol )
eigs_gen( eigval, eigvec, X, k )
eigs_gen( eigval, eigvec, X, k, form )
eigs_gen( eigval, eigvec, X, k, form, tol )
-
Obtain a limited number of eigenvalues and eigenvectors of sparse general (non-symmetric/non-hermitian) square matrix X
-
k specifies the number of eigenvalues and eigenvectors
- The argument form is optional; form is one of:
"lm" | = | obtain eigenvalues with largest magnitude (default operation) |
"sm" | = | obtain eigenvalues with smallest magnitude |
"lr" | = | obtain eigenvalues with largest real part |
"sr" | = | obtain eigenvalues with smallest real part |
"li" | = | obtain eigenvalues with largest imaginary part |
"si" | = | obtain eigenvalues with smallest imaginary part |
-
The argument tol is optional; it specifies the tolerance for convergence
-
The eigenvalues and corresponding eigenvectors are stored in eigval and eigvec, respectively
-
If X is not square sized, a std::logic_error exception is thrown
- If the decomposition fails:
- eigval = eigs_gen(X,k) resets eigval and throws a std::runtime_error exception
- eigs_gen(eigval,X,k) resets eigval and returns a bool set to false (exception is not thrown)
- eigs_gen(eigval,eigvec,X,k) resets eigval & eigvec and returns a bool set to false (exception is not thrown)
-
Examples:
// generate sparse matrix
sp_mat A = sprandu<sp_mat>(1000, 1000, 0.1);
cx_vec eigval;
cx_mat eigvec;
eigs_gen(eigval, eigvec, A, 5); // find 5 eigenvalues/eigenvectors
See also:
X = spsolve( A, B )
X = spsolve( A, B, solver )
X = spsolve( A, B, solver, settings )
spsolve( X, A, B )
spsolve( X, A, B, solver )
spsolve( X, A, B, solver, settings )
-
Solve a sparse system of linear equations, A*X = B, where A is a sparse matrix, B is a dense matrix or vector, and X is unknown
-
The number of rows in A and B must be the same
-
If no solution is found:
- X = spsolve(A, B) resets X and throws a std::runtime_error exception
- spsolve(X, A, B) resets X and returns a bool set to false (no exception is thrown)
-
The solver argument is optional; solver is either
"superlu" or "lapack" ; by default "superlu" is used
-
For
"superlu" , ARMA_USE_SUPERLU must be enabled in config.hpp
-
For
"lapack" , sparse matrix A is converted to a dense matrix before using the LAPACK solver; this considerably increases memory usage
-
The settings argument is optional
-
Examples:
sp_mat A = sprandu<sp_mat>(1000, 1000, 0.1);
vec b = randu<vec>(1000);
mat B = randu<mat>(1000, 5);
vec x = spsolve(A, b); // solve one system
mat X = spsolve(A, B); // solve several systems
bool status = spsolve(x, A, b); // use default solver
if(status == false) { cout << "no solution" << endl; }
spsolve(x, A, b, "lapack"); // use LAPACK solver
spsolve(x, A, b, "superlu"); // use SuperLU solver
superlu_opts settings;
settings.permutation = superlu_opts::NATURAL;
settings.refine = superlu_opts::REF_NONE;
spsolve(x, A, b, "superlu", settings);
See also:
vec s = svds( X, k )
vec s = svds( X, k, tol )
svds( vec s, X, k )
svds( vec s, X, k, tol )
svds( mat U, vec s, mat V, sp_mat X, k )
svds( mat U, vec s, mat V, sp_mat X, k, tol )
svds( cx_mat U, vec s, cx_mat V, sp_cx_mat X, k )
svds( cx_mat U, vec s, cx_mat V, sp_cx_mat X, k, tol )
-
Obtain a limited number of singular values and singular vectors of sparse matrix X
-
k specifies the number of singular values and singular vectors
-
The argument tol is optional; it specifies the tolerance for convergence
-
The singular values are calculated via sparse eigen decomposition of:
⎡ | zeros(X.n_rows, X.n_rows) | | X | ⎤ |
⎣ | X.t() | | zeros(X.n_cols, X.n_cols) | ⎦ |
-
The singular values are in descending order
-
If the decomposition fails, the output objects are reset and:
- s = svds(X,k) resets s and throws a std::runtime_error exception
- svds(s,X,k) resets s and returns a bool set to false (exception is not thrown)
- svds(U,s,V,X,k) resets U, s, V and returns a bool set to false (exception is not thrown)
-
Caveat: svds() is intended only for finding a few singular values from a large sparse matrix;
to find all singular values, use svd() instead
-
Examples:
sp_mat X = sprandu<sp_mat>(100, 200, 0.1);
mat U;
vec s;
mat V;
svds(U, s, V, X, 10);
See also:
Signal & Image Processing
conv( A, B )
conv( A, B, shape )
-
1D convolution of vectors A and B
-
The orientation of the result vector is the same as the orientation of A (ie. either column or row vector)
-
The shape argument is optional; it is one of:
"full" | = | return the full convolution (default setting), with the size equal to A.n_elem + B.n_elem - 1 |
"same" | = | return the central part of the convolution, with the same size as vector A |
-
The convolution operation is also equivalent to FIR filtering
-
Examples:
vec A(256, fill::randu);
vec B(16, fill::randu);
vec C = conv(A, B);
vec D = conv(A, B, "same");
See also:
conv2( A, B )
conv2( A, B, shape )
-
2D convolution of matrices A and B
-
The shape argument is optional; it is one of:
"full" | = | return the full convolution (default setting), with the size equal to size(A) + size(B) - 1 |
"same" | = | return the central part of the convolution, with the same size as matrix A |
- The implementation of 2D convolution in this version is preliminary; it is not yet fully optimised
-
Examples:
mat A(256, 256, fill::randu);
mat B(16, 16, fill::randu);
mat C = conv2(A, B);
mat D = conv2(A, B, "same");
See also:
cx_mat Y = fft( X )
cx_mat Y = fft( X, n )
cx_mat Z = ifft( cx_mat Y )
cx_mat Z = ifft( cx_mat Y, n )
See also:
cx_mat Y = fft2( X )
cx_mat Y = fft2( X, n_rows, n_cols )
cx_mat Z = ifft2( cx_mat Y )
cx_mat Z = ifft2( cx_mat Y, n_rows, n_cols )
See also:
interp1( X, Y, XI, YI )
interp1( X, Y, XI, YI, method )
interp1( X, Y, XI, YI, method, extrapolation_value )
-
1D data interpolation
-
Given a 1D function specified in vectors X and Y
(where X specifies locations and Y specifies the corresponding values),
generate vector YI which contains interpolated values at locations XI
-
The method argument is optional; it is one of:
"nearest" | = | interpolate using single nearest neighbour |
"linear" | = | linear interpolation between two nearest neighbours (default setting) |
"*nearest" | = | as per "nearest" , but faster by assuming that X and XI are monotonically increasing |
"*linear" | = | as per "linear" , but faster by assuming that X and XI are monotonically increasing |
-
If a location in XI is outside the domain of X, the corresponding value in YI is set to extrapolation_value
-
The extrapolation_value argument is optional; by default it is datum::nan (not-a-number)
-
Examples:
vec x = linspace<vec>(0, 3, 20);
vec y = square(x);
vec xx = linspace<vec>(0, 3, 100);
vec yy;
interp1(x, y, xx, yy); // use linear interpolation by default
interp1(x, y, xx, yy, "*linear"); // faster than "linear"
interp1(x, y, xx, yy, "nearest");
See also:
Statistics & Clustering
mean, median, stddev, var
See also:
cov( X, Y )
cov( X, Y, norm_type )
cov( X )
cov( X, norm_type )
-
For two matrix arguments X and Y,
if each row of X and Y is an observation and each column is a variable,
the (i,j)-th entry of cov(X,Y) is the covariance between the i-th variable in X and the j-th variable in Y
-
For vector arguments, the type of vector is ignored and each element in the vector is treated as an observation
-
For matrices, X and Y must have the same dimensions
-
For vectors, X and Y must have the same number of elements
-
cov(X) is equivalent to cov(X, X)
-
The default norm_type=0 performs normalisation using N-1 (where N is the number of observations),
providing the best unbiased estimation of the covariance matrix (if the observations are from a normal distribution).
Using norm_type=1 causes normalisation to be done using N, which provides the second moment matrix of the observations about their mean
-
Examples:
mat X = randu<mat>(4,5);
mat Y = randu<mat>(4,5);
mat C = cov(X,Y);
mat D = cov(X,Y, 1);
See also:
cor( X, Y )
cor( X, Y, norm_type )
cor( X )
cor( X, norm_type )
-
For two matrix arguments X and Y,
if each row of X and Y is an observation and each column is a variable,
the (i,j)-th entry of cor(X,Y) is the correlation coefficient between the i-th variable in X and the j-th variable in Y
-
For vector arguments, the type of vector is ignored and each element in the vector is treated as an observation
-
For matrices, X and Y must have the same dimensions
-
For vectors, X and Y must have the same number of elements
-
cor(X) is equivalent to cor(X, X)
-
The default norm_type=0 performs normalisation of the correlation matrix using N-1 (where N is the number of observations).
Using norm_type=1 causes normalisation to be done using N
-
Examples:
mat X = randu<mat>(4,5);
mat Y = randu<mat>(4,5);
mat R = cor(X,Y);
mat S = cor(X,Y, 1);
See also:
hist( V )
hist( V, n_bins )
hist( V, centers )
hist( X, centers )
hist( X, centers, dim )
-
For vector V,
produce an unsigned vector of the same orientation as V (ie. either uvec or urowvec)
that represents a histogram of counts
-
For matrix X,
produce a umat matrix containing either
column histogram counts (for dim=0, default),
or
row histogram counts (for dim=1)
-
The bin centers can be automatically determined from the data, with the number of bins specified via n_bins (default is 10);
the range of the bins is determined by the range of the data
-
The bin centers can also be explicitly specified via the centers vector;
the vector must contain monotonically increasing values (eg. 0.1, 0.2, 0.3, ...)
-
Examples:
vec v = randn<vec>(1000); // Gaussian distribution
uvec h1 = hist(v, 11);
uvec h2 = hist(v, linspace<vec>(-2,2,11));
See also:
histc( V, edges )
histc( X, edges )
histc( X, edges, dim )
See also:
mat coeff = princomp( mat X )
cx_mat coeff = princomp( cx_mat X )
princomp( mat coeff, mat X )
princomp( cx_mat coeff, cx_mat X )
princomp( mat coeff, mat score, mat X )
princomp( cx_mat coeff, cx_mat score, cx_mat X )
princomp( mat coeff, mat score, vec latent, mat X )
princomp( cx_mat coeff, cx_mat score, vec latent, cx_mat X )
princomp( mat coeff, mat score, vec latent, vec tsquared, mat X )
princomp( cx_mat coeff, cx_mat score, vec latent, cx_vec tsquared, cx_mat X )
- Principal component analysis of matrix X
- Each row of X is an observation and each column is a variable
- output objects:
- coeff: principal component coefficients
- score: projected data
- latent: eigenvalues of the covariance matrix of X
- tsquared: Hotteling's statistic for each sample
-
The computation is based on singular value decomposition
- If the decomposition fails:
- coeff = princomp(X) resets coeff and throws a std::runtime_error exception
- remaining forms of princomp() reset all output matrices and return a bool set to false (exception is not thrown)
-
Examples:
mat A = randu<mat>(5,4);
mat coeff;
mat score;
vec latent;
vec tsquared;
princomp(coeff, score, latent, tsquared, A);
See also:
running_stat<type>
See also:
running_stat_vec<vec_type>
running_stat_vec<vec_type>(calc_cov)
See also:
kmeans( means, data, k, seed_mode, n_iter, print_mode )
-
Cluster given data into k disjoint sets
-
The means parameter is the output matrix for storing the resulting centroids of the sets, with each centroid stored as a column vector
-
The data parameter is the input data matrix, with each sample stored as a column vector
-
The k parameter indicates the number of centroids
-
The seed_mode parameter specifies how the initial centroids are seeded; it is one of:
keep_existing | | use the centroids specified in the means matrix as the starting point |
static_subset | | use a subset of the data vectors (repeatable) |
random_subset | | use a subset of the data vectors (random) |
static_spread | | use a maximally spread subset of data vectors (repeatable) |
random_spread | | use a maximally spread subset of data vectors (random start) |
-
The n_iter parameter specifies the number of clustering iterations; about 10 is typically sufficient
-
The print_mode parameter is either true or false, indicating whether progress is printed during clustering
-
If the clustering fails, the means matrix is reset and a bool set to false is returned
-
The clustering will run faster on multi-core machines when OpenMP is enabled in your compiler (eg. -fopenmp in GCC)
-
Caveats:
-
the number of data vectors (number of columns in the data matrix) should be much larger than k (number of centroids)
-
seeding the initial centroids with
static_spread and random_spread
can be much more time consuming than with static_subset and random_subset
-
Examples:
uword d = 5; // dimensionality
uword N = 10000; // number of vectors
mat data(d, N, fill::randu);
mat means;
bool status = kmeans(means, data, 2, random_subset, 10, true);
if(status == false)
{
cout << "clustering failed" << endl;
}
means.print("means:");
See also:
gmm_diag
-
Class for modelling data as a Gaussian Mixture Model (GMM), under the assumption of diagonal covariance matrices
-
Can also be used for clustering and vector quantisation (VQ)
-
Provides associated parameter estimation algorithms: k-means clustering and Expectation-Maximisation (EM)
-
The k-means and EM algorithms are parallelised (multi-threaded) when compiling with OpenMP enabled (eg. the -fopenmp option in gcc)
-
Data is modelled as:
| | n_gaus-1 | |
p(x) | = | ∑ |
hg N( x | mg , Cg ) |
| | g=0 | |
where:
- n_gaus is the number of Gaussians
- N( x | mg , Cg ) represents a Gaussian (normal) distribution
- for each Gaussian g:
- hg is the heft (weight), with hg ≥ 0 and ∑hg = 1
- mg is the mean (centroid) vector with dimensionality n_dims
- Cg is the diagonal covariance matrix
-
For an instance of gmm_diag named as M, the member functions and variables are:
M.log_p(V)
|
|
return a scalar representing the log-likelihood of vector V
|
M.log_p(V, g)
|
|
return a scalar representing the log-likelihood of vector V, according to Gaussian g
|
|
|
|
M.log_p(X)
|
|
return a row vector (of type rowvec ) containing log-likelihoods of each column vector in matrix X
|
M.log_p(X, g)
|
|
return a row vector (of type rowvec ) containing log-likelihoods of each column vector in matrix X, according to Gaussian g
|
|
|
|
M.avg_log_p(X)
|
|
return a scalar representing the average log-likelihood of all column vectors in matrix X
|
M.avg_log_p(X, g)
|
|
return a scalar representing the average log-likelihood of all column vectors in matrix X, according to Gaussian g
|
|
|
|
M.assign(V, dist_mode)
|
|
return the index of the closest mean (or Gaussian) to vector V;
dist_mode is one of:
eucl_dist | | Euclidean distance (takes only means into account) |
prob_dist | | probabilistic "distance", defined as the inverse likelihood (takes into account means, covariances and hefts) |
|
M.assign(X, dist_mode)
|
|
return a row vector containing the indices of the closest means (or Gaussians) to each column vector in matrix X
|
|
|
|
M.raw_hist(X, dist_mode)
|
|
return a row vector (of type urowvec ) representing the raw histogram of counts;
each entry is the number of counts corresponding to a Gaussian;
each count is the number times the corresponding Gaussian was the closest to each column vector in matrix X;
parameter dist_mode is either eucl_dist or prob_dist (as per the .assign() function above)
|
M.norm_hist(X, dist_mode)
|
|
return a row vector (of type rowvec ) containing normalised counts;
the vector sums to one
|
|
|
|
M.generate()
|
|
return a column vector representing a random sample generated according to the model's parameters
|
M.generate(N)
|
|
return a matrix containing N column vectors, with each vector representing a random sample generated according to the model's parameters
|
|
|
|
M.save(filename)
|
|
save the model to the given filename
|
M.load(filename)
|
|
load the model from the given filename
|
|
|
|
M.n_gaus()
|
|
return the number of means/Gaussians in the model
|
M.n_dims()
|
|
return the dimensionality of the means/Gaussians in the model
|
|
|
|
M.reset(n_dims, n_gaus)
|
|
set the model to have dimensionality n_dims, with n_gaus number of Gaussians;
all the means are set to zero, all diagonal covariances are set to one, and all the hefts (weights) are set to be uniform
|
|
|
|
M.means
|
|
read-only matrix containing the means (centroids), stored as column vectors
|
M.dcovs
|
|
read-only matrix containing the diagonal covariance matrices,
stored as column vectors
|
M.hefts
|
|
read-only row vector containing the hefts (weights)
|
|
|
|
M.set_means(X)
|
|
set the means to be as specified in matrix X;
the number of means and their dimensionality must match the existing model
|
M.set_dcovs(X)
|
|
set the diagonal covariances matrices to be as specified in matrix X;
the number of diagonal covariance matrices and their dimensionality must match the existing model
|
M.set_hefts(V)
|
|
set the hefts (weights) of the model to be as specified in row vector V;
the number of hefts must match the existing model
|
|
|
|
M.set_params(means, dcovs, hefts)
|
|
set all the parameters in one hit;
the number of Gaussians and dimensionality can be different from the existing model
|
|
|
|
M.learn(data, n_gaus, dist_mode, seed_mode, km_iter, em_iter, var_floor, print_mode)
|
|
|
learn the model parameters via the k-means and/or EM algorithms,
and return a bool variable, with true indicating success, and false indicating failure
|
-
Parameters for the
.learn() member function:
|
|
|
data |
|
matrix containing training samples; each sample is stored as a column vector
|
|
|
|
n_gaus |
|
set the number of Gaussians to n_gaus
|
|
|
|
dist_mode |
|
specifies the distance used during the seeding of initial means and k-means clustering:
eucl_dist | | Euclidean distance |
maha_dist | | Mahalanobis distance, which uses a global diagonal covariance matrix estimated from the training samples |
|
|
|
|
seed_mode |
|
specifies how the initial means are seeded prior to running k-means and/or EM algorithms:
keep_existing | | keep the existing model (do not modify the means, covariances and hefts) |
static_subset | | a subset of the training samples (repeatable) |
random_subset | | a subset of the training samples (random) |
static_spread | | a maximally spread subset of training samples (repeatable) |
random_spread | | a maximally spread subset of training samples (random start) |
|
|
|
|
km_iter |
|
the number of iterations of the k-means algorithm
|
|
|
|
em_iter |
|
the number of iterations of the EM algorithm
|
|
|
|
var_floor |
|
the variance floor (smallest allowed value) for the diagonal covariances
|
|
|
|
print_mode |
|
either true or false ;
enable or disable printing of progress during the k-means and EM algorithms
|
-
Notes:
-
for probabilistic applications,
better model parameters are typically learned with dist_mode set to
maha_dist
-
for vector quantisation applications,
model parameters should be learned with dist_mode set to
eucl_dist ,
and the number of EM iterations set to zero
-
in general, a sufficient number of k-means and EM iterations is typically about 10
-
the number of training samples should be much larger than the number of Gaussians
-
seeding the initial means with
static_spread and random_spread
can be much more time consuming than with static_subset and random_subset
-
the k-means and EM algorithms will run faster on multi-core machines when OpenMP is enabled in your compiler (eg. -fopenmp in GCC)
-
Examples:
// create synthetic data with 2 Gaussians
uword d = 5; // dimensionality
uword N = 10000; // number of vectors
mat data(d, N, fill::zeros);
vec mean0 = linspace<vec>(1,d,d);
vec mean1 = mean0 + 2;
uword i = 0;
while(i < N)
{
if(i < N) { data.col(i) = mean0 + randn<vec>(d); ++i; }
if(i < N) { data.col(i) = mean0 + randn<vec>(d); ++i; }
if(i < N) { data.col(i) = mean1 + randn<vec>(d); ++i; }
}
// model the data as a GMM with 2 Gaussians
gmm_diag model;
bool status = model.learn(data, 2, maha_dist, random_subset, 10, 5, 1e-10, true);
if(status == false)
{
cout << "learning failed" << endl;
}
model.means.print("means:");
double scalar_likelihood = model.log_p( data.col(0) );
rowvec set_likelihood = model.log_p( data.cols(0,9) );
double overall_likelihood = model.avg_log_p(data);
uword gaus_id = model.assign( data.col(0), eucl_dist );
urowvec gaus_ids = model.assign( data.cols(0,9), prob_dist );
urowvec hist1 = model.raw_hist (data, prob_dist);
rowvec hist2 = model.norm_hist(data, eucl_dist);
model.save("my_model.gmm");
See also:
Miscellaneous
constants (pi, inf, speed of light, ...)
See also:
wall_clock
-
Simple wall clock timer class for measuring the number of elapsed seconds
-
Examples:
wall_clock timer;
mat A = randu<mat>(100,100);
mat B = randu<mat>(100,100);
mat C;
timer.tic();
for(uword i=0; i<100000; ++i)
{
C = A + B + A + B;
}
double n = timer.toc();
cout << "number of seconds: " << n << endl;
logging of warnings and errors
set_stream_err1( user_stream )
set_stream_err2( user_stream )
std::ostream& x = get_stream_err1()
std::ostream& x = get_stream_err2()
-
By default, warnings and messages associated with exceptions are printed to the std::cout stream
- the printing can be disabled by defining ARMA_DONT_PRINT_ERRORS before including the armadillo header
- detailed information about errors is always reported via the base std::exception class
- set_stream_err1(): change the stream for messages associated with std::logic_error exceptions (eg. out of bounds accesses)
- set_stream_err2(): change the stream for warnings and messages associated with std::runtime_error and std::bad_alloc exceptions (eg. failed decompositions, out of memory)
- get_stream_err1(): get a reference to the stream for messages associated with std::logic_error exceptions
- get_stream_err2(): get a reference to the stream for warnings and messages associated with std::runtime_error exceptions
-
Examples:
// print "hello" to the current err1 stream
get_stream_err1() << "hello" << endl;
// change the err2 stream to be a file
ofstream f("my_log.txt");
set_stream_err2(f);
// trying to invert a singular matrix
// will print a message to the err2 stream
// and throw an exception
mat X = zeros<mat>(5,5);
mat Y = inv(X);
// disable messages being printed to the err2 stream
std::ostream nullstream(0);
set_stream_err2(nullstream);
Caveat: set_stream_err1() and set_stream_err2() will not change the stream used by .print()
See also:
uword, sword
- uword is a typedef for an unsigned integer type; it is used for matrix indices as well as all internal counters and loops
- sword is a typedef for a signed integer type
- The minimum width of both uword and sword is either 32 or 64 bits:
- when using the old C++98 / C++03 standards, the default width is 32 bits
- when using the new C++11 / C++14 standards, the default width is 64 bits on 64-bit platforms
- The width can also be forcefully set to 64 bits by enabling ARMA_64BIT_WORD via editing include/armadillo_bits/config.hpp
- See also:
cx_double, cx_float
See also:
Examples of Matlab/Octave syntax and conceptually corresponding Armadillo syntax
Matlab/Octave
|
|
Armadillo
|
|
Notes
|
|
|
|
|
|
A(1, 1)
|
|
A(0, 0)
|
|
indexing in Armadillo starts at 0
|
A(k, k)
|
|
A(k-1, k-1)
|
|
|
|
|
|
|
|
size(A,1)
|
|
A.n_rows
|
|
read only
|
size(A,2)
|
|
A.n_cols
|
|
|
size(Q,3)
|
|
Q.n_slices
|
|
Q is a cube (3D array)
|
numel(A)
|
|
A.n_elem
|
|
|
|
|
|
|
|
A(:, k)
|
|
A.col(k)
|
|
this is a conceptual example only;
exact conversion from Matlab/Octave to Armadillo syntax
will require taking into account that indexing starts at 0
|
A(k, :)
|
|
A.row(k)
|
|
|
A(:, p:q)
|
|
A.cols(p, q)
|
|
|
A(p:q, :)
|
|
A.rows(p, q)
|
|
|
A(p:q, r:s)
|
|
A( span(p,q), span(r,s) )
|
|
A( span(first_row, last_row), span(first_col, last_col) )
|
|
|
|
|
|
Q(:, :, k)
|
|
Q.slice(k)
|
|
Q is a cube (3D array)
|
Q(:, :, t:u)
|
|
Q.slices(t, u)
|
|
|
Q(p:q, r:s, t:u)
|
|
Q( span(p,q), span(r,s), span(t,u) )
|
|
|
|
|
|
|
|
A'
|
|
A.t() or trans(A)
|
|
matrix transpose / Hermitian transpose
(for complex matrices, the conjugate of each element is taken)
|
|
|
|
|
|
A = zeros(size(A))
|
|
A.zeros()
|
|
|
A = ones(size(A))
|
|
A.ones()
|
|
|
A = zeros(k)
|
|
A = zeros<mat>(k,k)
|
|
|
A = ones(k)
|
|
A = ones<mat>(k,k)
|
|
|
|
|
|
|
|
C = complex(A,B)
|
|
cx_mat C = cx_mat(A,B)
|
|
|
|
|
|
|
|
A .* B
|
|
A % B
|
|
element-wise multiplication
|
A ./ B
|
|
A / B
|
|
element-wise division
|
A \ B
|
|
solve(A,B)
|
|
conceptually similar to inv(A)*B, but more efficient
|
A = A + 1;
|
|
A++
|
|
|
A = A - 1;
|
|
A--
|
|
|
|
|
|
|
|
A = [ 1 2; 3 4; ]
|
|
A << 1 << 2 << endr
<< 3 << 4 << endr;
|
|
element initialisation,
with special element endr indicating end of row
|
|
|
|
|
|
X = A(:)
|
|
X = vectorise(A)
|
|
|
X = [ A B ]
|
|
X = join_horiz(A,B)
|
|
|
X = [ A; B ]
|
|
X = join_vert(A,B)
|
|
|
|
|
|
|
|
A
|
|
cout << A << endl;
or
A.print("A =");
|
|
|
|
|
|
|
|
save ‑ascii 'A.dat' A
|
|
A.save("A.dat", raw_ascii);
|
|
Matlab/Octave matrices saved as ascii are readable by Armadillo (and vice-versa)
|
load ‑ascii 'A.dat'
|
|
A.load("A.dat", raw_ascii);
|
|
|
|
|
|
|
|
A = randn(2,3);
B = randn(4,5);
F = { A; B }
|
|
mat A = randn(2,3);
mat B = randn(4,5);
field<mat> F(2,1);
F(0,0) = A;
F(1,0) = B;
|
|
fields store arbitrary objects, such as matrices
|
example program
#include <iostream>
#include <armadillo>
using namespace std;
using namespace arma;
int main()
{
mat A = randu<mat>(4,5);
mat B = randu<mat>(4,5);
cout << A*B.t() << endl;
return 0;
}
If you save the above program as example.cpp,
under Linux and Mac OS X it can be compiled using:
g++ example.cpp -o example -O2 -larmadillo
As Armadillo is a template library, we strongly recommend to enable optimisation when compiling programs
(eg. when compiling with GCC or clang, use the -O2 or -O3 options)
See also the example program that comes with the Armadillo archive
config.hpp
-
Armadillo can be configured via editing the file include/armadillo_bits/config.hpp.
Specific functionality can be enabled or disabled by uncommenting or commenting out a particular #define, listed below.
ARMA_DONT_USE_WRAPPER
|
|
Disable going through the run-time Armadillo wrapper library (libarmadillo.so) when calling LAPACK, BLAS, ARPACK, SuperLU and HDF5 functions.
You will need to directly link with BLAS, LAPACK, etc (eg. -lblas -llapack )
|
|
|
|
ARMA_USE_LAPACK
|
|
Enable use of LAPACK, or a high-speed replacement for LAPACK (eg. Intel MKL, AMD ACML or the Accelerate framework).
Armadillo requires LAPACK for functions such as svd(), inv(), eig_sym(), solve(), etc.
|
|
|
|
ARMA_DONT_USE_LAPACK
|
|
Disable use of LAPACK. Overrides ARMA_USE_LAPACK
|
|
|
|
ARMA_USE_BLAS
|
|
Enable use of BLAS, or a high-speed replacement for BLAS (eg. OpenBLAS, Intel MKL, AMD ACML or the Accelerate framework).
BLAS is used for matrix multiplication.
Without BLAS, Armadillo will use a built-in matrix multiplication routine, which might be slower for large matrices.
|
|
|
|
ARMA_DONT_USE_BLAS
|
|
Disable use of BLAS. Overrides ARMA_USE_BLAS
|
|
|
|
ARMA_USE_NEWARP
|
|
Enable use of the built-in reimplementation of ARPACK (Armadillo 7.x).
This is used for the eigen decomposition of real (non-complex) sparse matrices, ie. eigs_gen(), eigs_sym() and svds().
Requires ARMA_USE_LAPACK to be enabled.
|
|
|
|
ARMA_DONT_USE_NEWARP
|
|
Disable use of the built-in reimplementation of ARPACK. Overrides ARMA_USE_NEWARP
|
|
|
|
ARMA_USE_ARPACK
|
|
Enable use of ARPACK, or a high-speed replacement for ARPACK.
Armadillo requires ARPACK for the eigen decomposition of complex sparse matrices, ie. eigs_gen(), eigs_sym() and svds()
|
|
|
|
ARMA_DONT_USE_ARPACK
|
|
Disable use of ARPACK. Overrides ARMA_USE_ARPACK
|
|
|
|
ARMA_USE_SUPERLU
|
|
Enable use of SuperLU, which is used by spsolve() for finding the solutions of sparse systems;
you will need to link with the superlu library, for example -lsuperlu
Caveat: Armadillo 6.x requires SuperLU 4.3, while Armadillo 7.x requires SuperLU 5.2
|
|
|
|
ARMA_DONT_USE_SUPERLU
|
|
Disable use of SuperLU. Overrides ARMA_USE_SUPERLU
|
|
|
|
ARMA_USE_HDF5
|
|
Enable the ability to save and load matrices stored in the HDF5 format;
the hdf5.h header file must be available on your system and you will need to link with the hdf5 library (eg. -lhdf5)
|
|
|
|
ARMA_DONT_USE_HDF5
|
|
Disable the use of the HDF5 library. Overrides ARMA_USE_HDF5
|
|
|
|
ARMA_USE_CXX11
|
|
Use C++11 features, such as initialiser lists;
automatically enabled when using a compiler in C++11 mode, for example, g++ -std=c++11
|
|
|
|
ARMA_DONT_USE_CXX11
|
|
Disable use of C++11 features. Overrides ARMA_USE_CXX11
|
|
|
|
ARMA_BLAS_CAPITALS
|
|
Use capitalised (uppercase) BLAS and LAPACK function names (eg. DGEMM vs dgemm)
|
|
|
|
ARMA_BLAS_UNDERSCORE
|
|
Append an underscore to BLAS and LAPACK function names (eg. dgemm_ vs dgemm). Enabled by default.
|
|
|
|
ARMA_BLAS_LONG
|
|
Use "long" instead of "int" when calling BLAS and LAPACK functions
|
|
|
|
ARMA_BLAS_LONG_LONG
|
|
Use "long long" instead of "int" when calling BLAS and LAPACK functions
|
|
|
|
ARMA_USE_TBB_ALLOC
|
|
Use Intel TBB scalable_malloc() and scalable_free() instead of standard malloc() and free() for managing matrix memory
|
|
|
|
ARMA_USE_MKL_ALLOC
|
|
Use Intel MKL mkl_malloc() and mkl_free() instead of standard malloc() and free() for managing matrix memory
|
|
|
|
ARMA_64BIT_WORD
|
|
Use 64 bit integers.
Automatically enabled when using a C++11 compiler on 64-bit platforms.
Useful if you require matrices/vectors capable of holding more than 4 billion elements.
Your machine and compiler must have support for 64 bit integers (eg. via "long" or "long long").
This can also be enabled by adding #define ARMA_64BIT_WORD before each instance of #include <armadillo>
|
|
|
|
ARMA_NO_DEBUG
|
|
Disable all run-time checks, such as bounds checking.
This will result in faster code, but you first need to make sure that your code runs correctly!
We strongly recommend to have the run-time checks enabled during development,
as this greatly aids in finding mistakes in your code, and hence speeds up development.
We recommend that run-time checks be disabled only for the shipped version of your program
(ie. final release build).
|
|
|
|
ARMA_EXTRA_DEBUG
|
|
Print out the trace of internal functions used for evaluating expressions.
Not recommended for normal use.
This is mainly useful for debugging the library.
|
|
|
|
ARMA_MAT_PREALLOC
|
|
The number of pre-allocated elements used by matrices and vectors.
Must be always enabled and set to an integer that is at least 1.
By default set to 16.
If you mainly use lots of very small vectors (eg. ≤ 4 elements), change the number to the size of your vectors.
|
|
|
|
ARMA_DEFAULT_OSTREAM
|
|
The default stream used for printing error messages and by .print().
Must be always enabled.
By default defined to std::cout
|
|
|
|
ARMA_PRINT_ERRORS
|
|
Print errors and warnings encountered during program execution
|
|
|
|
ARMA_DONT_PRINT_ERRORS
|
|
Do not print errors or warnings. Overrides ARMA_PRINT_ERRORS
|
|
|
|
-
See also:
History of API Additions, Changes and Deprecations
API Version Policy
-
Armadillo's version number is A.B.C, where A is a major version, B is a minor version, and C is the patch level (indicating bug fixes)
-
Within each major version (eg. 4.x), minor versions are backwards compatible with earlier minor versions.
For example, code written for version 4.000 will work with version 4.100, 4.120, 4.200, etc.
However, as each minor version may have more features (ie. API extensions) than earlier versions,
code specifically written for version 4.100 doesn't necessarily work with 4.000
-
We don't like changes to existing APIs and strongly prefer not to break any user software.
However, to allow evolution, we reserve the right to alter the APIs in future major versions of Armadillo
while remaining backwards compatible in as many cases as possible
(eg. version 5.x may have slightly different APIs than 4.x).
In a rare instance the user API may need to be tweaked if a bug fix absolutely requires it
-
This policy is applicable to the APIs described in this documentation; it is not applicable to internal functions
(ie. the underlying internal implementation details may change across consecutive minor versions)
List of additions and changes for each version:
- Version 7.500:
- expanded qz() to optionally specify ordering of the Schur form
- expanded each_slice() to support matrix multiplication
- Version 7.400:
- Version 7.300:
- Version 7.200:
- Version 7.100:
- Version 6.700:
- added trapz() for numerical integration
- added logmat() for calculating the matrix logarithm
- added regspace() for generating vectors with regularly spaced elements
- added logspace() for generating vectors with logarithmically spaced elements
- added approx_equal() for determining approximate equality
- expanded .save() and .load() with hdf5_binary_trans file type, to save/load data with columns transposed to rows
- Version 6.600:
- expanded sum(), mean(), min(), max() to handle cubes
- expanded Cube class to handle arbitrarily sized empty cubes (eg. 0x5x2)
- added shift() for circular shifts of elements
- added sqrtmat() for finding the square root of a matrix
- Version 6.500:
- added conv2() for 2D convolution
- added stand-alone kmeans() function for clustering data
- added trunc()
- extended conv() to optionally provide central convolution
- faster handling of multiply-and-accumulate by accu() when using Intel MKL, ATLAS or OpenBLAS
- Version 6.400:
- Version 6.300:
- Version 6.200:
- expanded diagmat() to handle non-square matrices and arbitrary diagonals
- expanded trace() to handle non-square matrices
- Version 6.100:
- Version 5.600:
- Version 5.500:
- expanded object constructors and generators to handle size() based specification of dimensions
- Version 5.400:
- added find_unique() for finding indices of unique values
- added diff() for calculating differences between consecutive elements
- added cumprod() for calculating cumulative product
- added null() for finding the orthonormal basis of null space
- expanded interp1() to handle repeated locations
- expanded unique() to handle complex numbers
- faster flipud()
- faster row-wise cumsum()
- Version 5.300:
- Version 5.200:
- added orth() for finding the orthonormal basis of the range space of a matrix
- expanded element initialisation to handle nested initialiser lists (C++11)
- Version 5.100:
- Version 5.000:
- Version 4.650:
- added randg() for generating random values from gamma distributions (C++11 only)
- added .head_rows() and .tail_rows() to submatrix views
- added .head_cols() and .tail_cols() to submatrix views
- expanded eigs_sym() to optionally calculate eigenvalues with smallest/largest algebraic values
- Version 4.600:
- added .head() and .tail() to submatrix views
- faster matrix transposes within compound expressions
- faster in-place matrix multiplication
- faster accu() and norm() when compiling with -O3 -ffast-math -march=native (gcc and clang)
- Version 4.550:
- added matrix exponential function: expmat()
- faster .log_p() and .avg_log_p() functions in the gmm_diag class when compiling with OpenMP enabled
- faster handling of in-place addition/subtraction of expressions with an outer product
- Version 4.500:
- faster handling of complex vectors by norm()
- expanded chol() to optionally specify output matrix as upper or lower triangular
- better handling of non-finite values when saving matrices as text files
- Version 4.450:
- faster handling of matrix transposes within compound expressions
- expanded symmatu()/symmatl() to optionally disable taking the complex conjugate of elements
- expanded sort_index() to handle complex vectors
- expanded the gmm_diag class with functions to generate random samples
- Version 4.400:
- faster handling of subvectors by dot()
- faster handling of aliasing by submatrix views
- added clamp() for clamping values to be between lower and upper limits
- added gmm_diag class for statistical modelling of data using Gaussian Mixture Models
- expanded batch insertion constructors for sparse matrices to add values at repeated locations
- Version 4.320:
- expanded eigs_sym() and eigs_gen() to use an optional tolerance parameter
- expanded eig_sym() to automatically fall back to standard decomposition method if divide-and-conquer fails
- cmake-based installer enables use of C++11 random number generator when using gcc 4.8.3+ in C++11 mode
- Version 4.300:
- Version 4.200:
- faster transpose of sparse matrices
- more efficient handling of aliasing during matrix multiplication
- faster inverse of matrices marked as diagonal
- Version 4.100:
- added normalise() for normalising vectors to unit p-norm
- extended the field class to handle 3D layout
- extended eigs_sym() and eigs_gen() to obtain eigenvalues of various forms (eg. largest or smallest magnitude)
- automatic SIMD vectorisation of elementary expressions (eg. matrix addition) when using Clang 3.4+ with -O3 optimisation
- faster handling of sparse submatrix views
- Version 4.000:
- Version 3.930:
- Version 3.920:
- faster .zeros()
- faster round(), exp2() and log2() when using C++11
- added signum function: sign()
- added move constructors when using C++11
- added 2D fast Fourier transform: fft2()
- added .tube() for easier extraction of vectors and subcubes from cubes
- added specification of a fill type during construction of Mat, Col, Row and Cube classes,
eg. mat X(4, 5, fill::zeros)
- Version 3.910:
- faster multiplication of a matrix with a transpose of itself, ie. X*X.t() and X.t()*X
- added vectorise() for reshaping matrices into vectors
- added all() and any() for indicating presence of elements satisfying a relational condition
- Version 3.900:
- added automatic SSE2 vectorisation of elementary expressions (eg. matrix addition) when using GCC 4.7+ with -O3 optimisation
- faster median()
- faster handling of compound expressions with transposes of submatrix rows
- faster handling of compound expressions with transposes of complex vectors
- added support for saving & loading of cubes in HDF5 format
- Version 3.820:
- faster as_scalar() for compound expressions
- faster transpose of small vectors
- faster matrix-vector product for small vectors
- faster multiplication of small fixed size matrices
- Version 3.810:
- Version 3.800:
- Version 3.6:
- faster handling of compound expressions with submatrices and subcubes
- faster trace()
- added support for loading matrices as text files with NaN and Inf elements
- added stable_sort_index(), which preserves the relative order of elements with equivalent values
- added handling of sparse matrices by mean(), var(), norm(), abs(), square(), sqrt()
- added saving and loading of sparse matrices in arma_binary format
- Version 3.4:
- Version 3.2:
- added unique(), for finding unique elements of a matrix
- added .eval(), for forcing the evaluation of delayed expressions
- faster eigen decomposition via optional use of divide-and-conquer algorithm
- faster transpose of vectors and compound expressions
- faster handling of diagonal views
- faster handling of tiny fixed size vectors (≤ 4 elements)
- Version 3.0:
- added shorthand for inverse: .i()
- added datum class
- added hist() and histc()
- added non-contiguous submatrix views
- faster handling of submatrix views with a single row or column
- faster element access in fixed size matrices
- faster repmat()
- expressions X=inv(A)*B and X=A.i()*B are automatically converted to X=solve(A,B)
- better detection of vector expressions by sum(), cumsum(), prod(), min(), max(), mean(), median(), stddev(), var()
- faster generation of random numbers
(eg. randu() and randn()),
via an algorithm that produces slightly different numbers than in 2.x
-
support for tying writable auxiliary (external) memory to fixed size matrices has been removed;
instead, you can use standard matrices with writable auxiliary memory,
or initialise fixed size matrices by copying the memory;
using auxiliary memory with standard matrices is unaffected
-
.print_trans() and .raw_print_trans() have been removed;
instead, you can chain .t() and .print() to achieve a similar result: X.t().print()
- Version 2.4:
- added shorter forms of transposes: .t() and .st()
- added .resize() and resize()
- added optional use of 64 bit indices (allowing matrices to have more than 4 billion elements), enabled via ARMA_64BIT_WORD in include/armadillo_bits/config.hpp
- added experimental support for C++11 initialiser lists, enabled via ARMA_USE_CXX11 in include/armadillo_bits/config.hpp
- refactored code to eliminate warnings when using the Clang C++ compiler
- umat, uvec, .min() and .max()
have been changed to use the uword type instead of the u32 type;
by default the uword and u32 types are equivalent (ie. unsigned integer type with a minimum width 32 bits);
however, when the use of 64 bit indices is enabled via ARMA_64BIT_WORD in include/armadillo_bits/config.hpp,
the uword type then has a minimum width of 64 bits
- Version 2.2:
- Version 2.0:
- det(), inv() and solve() can be forced to use more precise algorithms for tiny matrices (≤ 4x4)
- added syl(), for solving Sylvester's equation
- added strans(), for transposing a complex matrix without taking the complex conjugate
- added symmatu() and symmatl()
- added submatrices of submatrices
- faster inverse of symmetric positive definite matrices
- faster element access for fixed size matrices
- faster multiplication of tiny matrices (eg. 4x4)
- faster compound expressions containing submatrices
- added handling of arbitrarily sized empty matrices (eg. 5x0)
- added .count() member function in running_stat and running_stat_vec
- added loading & saving of matrices as CSV text files
- trans() now takes the complex conjugate when transposing a complex matrix
- forms of
chol(), eig_sym(), eig_gen(),
inv(), lu(), pinv(), princomp(),
qr(), solve(), svd(), syl()
that do not return a bool indicating success now throw std::runtime_error exceptions when failures are detected
- princomp_cov() has been removed; eig_sym() in conjunction with cov() can be used instead
- .is_vec() now outputs true for empty vectors (eg. 0x1)
- set_log_stream() & get_log_stream() have been replaced by set_stream_err1() & get_stream_err1()
- Version 1.2:
- added .min() & .max() member functions of Mat and Cube
- added floor() and ceil()
- added representation of “not a number”: math::nan()
- added representation of infinity: math::inf()
- added standalone is_finite()
- .in_range() expanded to use span() arguments
- fixed size matrices and vectors can use auxiliary (external) memory
- submatrices and subfields can be accessed via X( span(a,b), span(c,d) )
- subcubes can be accessed via X( span(a,b), span(c,d), span(e,f) )
- the two argument version of span can be replaced by
span::all or span(), to indicate an entire range
- for cubes, the two argument version of span can be replaced by
a single argument version, span(a), to indicate a single column, row or slice
- arbitrary "flat" subcubes can be interpreted as matrices; for example:
cube Q = randu<cube>(5,3,4);
mat A = Q( span(1), span(1,2), span::all );
// A has a size of 2x4
vec v = ones<vec>(4);
Q( span(1), span(1), span::all ) = v;
- added interpretation of matrices as triangular through trimatu() / trimatl()
- added explicit handling of triangular matrices by solve() and inv()
- extended syntax for submatrices, including access to elements whose indices are specified in a vector
- added ability to change the stream used for logging of errors and warnings
- added ability to save/load matrices in raw binary format
- added cumulative sum function: cumsum()
Changed in 1.0 (compared to earlier 0.x development versions):
-
the 3 argument version of lu(),
eg. lu(L,U,X),
provides L and U which should be the same as produced by Octave 3.2
(this was not the case in versions prior to 0.9.90)
-
rand() has been replaced by randu();
this has been done to avoid confusion with std::rand(),
which generates random numbers in a different interval
-
In versions earlier than 0.9.0,
some multiplication operations directly converted result matrices with a size of 1x1 into scalars.
This is no longer the case.
If you know the result of an expression will be a 1x1 matrix and wish to treat it as a pure scalar,
use the as_scalar() wrapping function
-
Almost all functions have been placed in the delayed operations framework (for speed purposes).
This may affect code which assumed that the output of some functions was a pure matrix.
The solution is easy, as explained below.
In general, Armadillo queues operations before executing them.
As such, the direct output of an operation or function cannot be assumed to be a directly accessible matrix.
The queued operations are executed when the output needs to be stored in a matrix,
eg. mat B = trans(A) or mat B(trans(A)).
If you need to force the execution of the delayed operations,
place the operation or function inside the corresponding Mat constructor.
For example, if your code assumed that the output of some functions was a pure matrix,
eg. chol(m).diag(), change the code to mat(chol(m)).diag().
Similarly, if you need to pass the result of an operation such as A+B to one of your own functions,
use my_function( mat(A+B) ).
|