• float, double, std::complex<float>, std::complex<double>, short, int, long, and unsigned versions of short, int, long

mat()
mat(n_rows, n_cols)
mat(n_rows, n_cols, fill_form)		(elements are initialised according to fill_form)
mat(size(X))
mat(size(X), fill_form)		(elements are initialised according to fill_form)
mat(mat)
mat(vec)
mat(rowvec)
mat(initializer_list)
mat(string)
mat(std::vector)		(treated as a column vector)
mat(sp_mat)		(for converting a sparse matrix to a dense matrix)
cx_mat(mat,mat)		(for constructing a complex matrix out of two real matrices)

fill::zeros	↦	set all elements to 0
fill::ones	↦	set all elements to 1
fill::eye	↦	set the elements on the main diagonal to 1 and off-diagonal elements to 0
fill::randu	↦	set all elements to random values from a uniform distribution in the [0,1] interval
fill::randn	↦	set all elements to random values from a normal/Gaussian distribution with zero mean and unit variance
fill::value(scalar)	↦	set all elements to specified scalar
fill::none	↦	do not initialise the elements   (matrix may have garbage values)

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 or an aliasing event
• 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

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 reserved 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 appending a two digit form of the size to the matrix type; examples: 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>(fill_form)


Create a fixed size matrix, with the elements explicitly initialised according to fill_form

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

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

vec()
vec(n_elem)
vec(n_elem, fill_form)		(elements are initialised according to fill_form)
vec(size(X))
vec(size(X), fill_form)		(elements are initialised according to fill_form)
vec(vec)
vec(mat)		(std::logic_error exception is thrown if the given matrix has more than one column)
vec(initializer_list)
vec(string)		(elements separated by spaces)
vec(std::vector)
cx_vec(vec,vec)		(for constructing a complex vector out of two real vectors)

vec(ptr_aux_mem, number_of_elements, copy_aux_mem = true, strict = false)


Create a column vector using data from writable auxiliary (external) memory, where ptr_aux_mem is a pointer to the memory. By default the vector allocates its own memory and copies data from the auxiliary memory (for safety). However, if copy_aux_mem is set to false, the vector 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 vector is directly using auxiliary memory)
• when strict is set to false, the vector will use the auxiliary memory until a size change or an aliasing event
• when strict is set to true, the vector will be bound to the auxiliary memory for its lifetime; the number of elements in the vector can't be changed

vec(const ptr_aux_mem, number_of_elements)


Create a column vector by copying data from read-only auxiliary memory, where ptr_aux_mem is a pointer to the memory

vec::fixed<number_of_elements>


Create a fixed size column vector, with the size specified via the template argument. Memory for the vector is reserved at compile time. This is generally faster than dynamic memory allocation, but the size of the vector can't be changed afterwards (directly or indirectly).

For convenience, there are several pre-defined typedefs for each vector type (where the types are: uvec, ivec, fvec, vec, cx_fvec, cx_vec as well as the corresponding colvec versions). The pre-defined typedefs specify vector sizes ranging from 2 to 9. The typedefs were defined by appending a single digit form of the size to the vector type; examples: vec3 is equivalent to vec::fixed<3>, while cx_vec4 is equivalent to cx_vec::fixed<4>.

vec::fixed<number_of_elements>(fill_form)


Create a fixed size column vector, with the elements explicitly initialised according to fill_form

vec::fixed<number_of_elements>(const ptr_aux_mem)


Create a fixed size column vector, with the size specified via the template argument; data is copied from auxiliary memory, where ptr_aux_mem is a pointer to the memory

vec x(10);
vec y(10, fill::ones);

mat A(10, 10, fill::randu);
vec z = A.col(5); // extract a column vector

rowvec()
rowvec(n_elem)
rowvec(n_elem, fill_form)		(elements are initialised according to fill_form)
rowvec(size(X))
rowvec(size(X), fill_form)		(elements are initialised according to fill_form)
rowvec(rowvec)
rowvec(mat)		(std::logic_error exception is thrown if the given matrix has more than one row)
rowvec(initializer_list)
rowvec(string)		(elements separated by spaces)
rowvec(std::vector)
cx_rowvec(rowvec,rowvec)		(for constructing a complex row vector out of two real row vectors)

rowvec(ptr_aux_mem, number_of_elements, copy_aux_mem = true, strict = false)


Create a row vector using data from writable auxiliary (external) memory, where ptr_aux_mem is a pointer to the memory. By default the vector allocates its own memory and copies data from the auxiliary memory (for safety). However, if copy_aux_mem is set to false, the vector 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 vector is directly using auxiliary memory)
• when strict is set to false, the vector will use the auxiliary memory until a size change or an aliasing event
• when strict is set to true, the vector will be bound to the auxiliary memory for its lifetime; the number of elements in the vector can't be changed

rowvec(const ptr_aux_mem, number_of_elements)


Create a row vector by copying data from read-only auxiliary memory, where ptr_aux_mem is a pointer to the memory

rowvec::fixed<number_of_elements>


Create a fixed size row vector, with the size specified via the template argument. Memory for the vector is reserved at compile time. This is generally faster than dynamic memory allocation, but the size of the vector can't be changed afterwards (directly or indirectly).

For convenience, there are several pre-defined typedefs for each vector type (where the types are: urowvec, irowvec, frowvec, rowvec, cx_frowvec, cx_rowvec). The pre-defined typedefs specify vector sizes ranging from 2 to 9. The typedefs were defined by appending a single digit form of the size to the vector type; examples: rowvec3 is equivalent to rowvec::fixed<3>, while cx_rowvec4 is equivalent to cx_rowvec::fixed<4>.

rowvec::fixed<number_of_elements>(fill_form)


Create a fixed size row vector, with the elements explicitly initialised according to fill_form

rowvec::fixed<number_of_elements>(const ptr_aux_mem)


Create a fixed size row vector, with the size specified via the template argument; data is copied from auxiliary memory, where ptr_aux_mem is a pointer to the memory

rowvec x(10);
rowvec y(10, fill::ones);

mat    A(10, 10, fill::randu);
rowvec z = A.row(5); // extract a row vector

• float, double, std::complex<float>, std::complex<double>, short, int, long and unsigned versions of short, int, long

cube()

cube(n_rows, n_cols, n_slices)
cube(n_rows, n_cols, n_slices, fill_form)		(elements are initialised according to fill_form)
cube(size(X))
cube(size(X), fill_form)		(elements are initialised according to fill_form)
cube(cube)
cx_cube(cube, cube)		(for constructing a complex cube out of two real cubes)

fill::zeros	↦	set all elements to 0
fill::ones	↦	set all elements to 1
fill::randu	↦	set all elements to random values from a uniform distribution in the [0,1] interval
fill::randn	↦	set all elements to random values from a normal/Gaussian distribution with zero mean and unit variance
fill::value(scalar)	↦	set all elements to specified scalar
fill::none	↦	do not initialise the elements   (cube may have garbage values)

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 reserved 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 or an aliasing event
• 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

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

cube x(1, 2, 3);
cube y(4, 5, 6, fill::randu);

mat A = y.slice(1);  // extract a slice from the cube
                     // (each slice is a matrix)

mat B(4, 5, fill::randu);
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();

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

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");

• float, double, std::complex<float>, std::complex<double>, short, int, long and unsigned versions of short, int, long

sp_mat()
sp_mat(n_rows, n_cols)
sp_mat(size(X))
sp_mat(sp_mat)
sp_mat(mat)		(for converting a dense matrix to a sparse matrix)
sp_cx_mat(sp_mat,sp_mat)		(for constructing a complex matrix out of two real matrices)

• 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, check_for_zeros = true)


• 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; do not set this to false unless you know what you are doing!


• If check_for_zeros is set to false, the values vector is assumed to contain no zero values; do not set this to false unless you know what you are doing!

• fundamental arithmetic operations (such as addition and multiplication)
• submatrix views: most contiguous forms and the non-contiguous form of X.cols(vector_of_column_indices)
• diagonal views
• saving and loading (using arma_binary, coord_ascii, and csv_ascii formats)
• element-wise functions: abs(), cbrt(), ceil(), conj(), floor(), imag(), real(), round(), sign(), sqrt(), square(), trunc()
• scalar functions of matrices: accu(), as_scalar(), dot(), norm(), norm2est(), trace()
• vector valued functions of matrices: diagvec(), min(), max(), nonzeros(), sum(), mean(), stddev(), var(), vecnorm(), vectorise()
• matrix valued functions of matrices: clamp(), diagmat(), spdiags(), flipud()/fliplr(), join_rows(), join_cols(), kron(), normalise(), repelem(), replace(), repmat(), reshape(), resize(), reverse(), circshift(), symmatu()/symmatl(), trimatu()/trimatl(), .t(), trans()
• generated matrices: speye(), spones(), sprandu(), sprandn(), zeros()
• eigen decompositions and SVD: eigs_sym(), eigs_gen(), svds()
• solution of sparse linear systems: spsolve()
• miscellaneous: approx_equal(), element access, element iterators, .as_col() / .as_row(), .as_dense(), .for_each(), .print(), .clean(), .replace(), .transform(), .is_finite(), .is_symmetric(), .is_hermitian(), .is_trimatu(), .is_trimatl(), .is_diagmat()

sp_mat A = sprandu(1000, 2000, 0.01);
sp_mat B = sprandu(2000, 1000, 0.01);

sp_mat C = 2*B;
sp_mat D = A*C;

sp_mat E(1000,1000);
E(1,2) = 123;


// batch insertion of 3 values at
// locations (1, 2), (7, 8), (9, 9)

umat locations = { { 1, 7, 9 },
                   { 2, 8, 9 } };

vec values = { 1.0, 2.0, 3.0 };

sp_mat X(locations, values);

+		addition of two objects
−		subtraction of one object from another or negation of an object
*		matrix multiplication of two objects; not applicable to the Cube class unless multiplying by a scalar
%		element-wise multiplication of two objects (Schur product)
/		element-wise division of an object by another object or a scalar
==		element-wise equality evaluation of two objects; generates a matrix/cube of type umat/ucube
!=		element-wise non-equality evaluation of two objects; generates a matrix/cube of type umat/ucube
>=		element-wise "greater than or equal to" evaluation of two objects; generates a matrix/cube of type umat/ucube
<=		element-wise "less than or equal to" evaluation of two objects; generates a matrix/cube of type umat/ucube
>		element-wise "greater than" evaluation of two objects; generates a matrix/cube of type umat/ucube
<		element-wise "less than" evaluation of two objects; generates a matrix/cube of type umat/ucube
&&		element-wise logical AND evaluation of two objects; generates a matrix/cube of type umat/ucube
||		element-wise logical OR evaluation of two objects; generates a matrix/cube of type umat/ucube

mat A(5, 10, fill::randu);
mat B(5, 10, fill::randu);
mat C(10, 5, fill::randu);

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);

mat X(4,5);
cout << "X has " << X.n_cols << " columns" << endl;

(i)		For vec and rowvec, access the element stored at index i. For mat, cube and field, access the element/object stored at index i under the assumption of a flat layout, with column-major ordering of data (ie. column by column). An exception is thrown if the requested element is out of bounds.
(r,c)		For mat and 2D field classes, access the element/object stored at row r and column c. An exception is thrown if the requested element is out of bounds.
(r,c,s)		For cube and 3D field classes, access the element/object stored at row r, column c, and slice s. An exception is thrown if the requested element is out of bounds.
.at(i)  or  [i]		As for (i), but without a bounds check; not recommended; see the caveats below
.at(r,c)		As for (r,c), but without a bounds check; not recommended; see the caveats below
.at(r,c,s)		As for (r,c,s), but without a bounds check; not recommended; see the caveats below

• accessing elements without bounds checks is slightly faster, but is not recommended until your code has been thoroughly debugged first
• indexing in C++ starts at 0
• accessing elements via [r,c] and [r,c,s] does not work correctly in C++; instead use (r,c) and (r,c,s)

mat M(10, 10, fill::randu);
M(9,9) = 123.0;
double x = M(1,2);

vec v(10, fill::randu);
v(9) = 123.0;
double y = v(0);

vec v = { 1, 2, 3 };

mat A = { {1, 3, 5},
          {2, 4, 6} };

mat A;
A.zeros(5, 10);   // or:  mat A(5, 10, fill::zeros);

mat B;
B.zeros( size(A) );

mat C(5, 10, fill::randu);
C.zeros();

mat A;
A.ones(5, 10);   // or:  mat A(5, 10, fill::ones);

mat B;
B.ones( size(A) );

mat C(5, 10, fill::randu);
C.ones();

mat A;
A.eye(5, 5);  // or:  mat A(5, 5, fill::eye);

mat B;
B.eye( size(A) );

mat C(5, 5, fill::randu);
C.eye();

mat A;
A.randu(5, 10);   // or:  mat A(5, 10, fill::randu);

mat B;
B.randu( size(A) );

mat C(5, 10, fill::zeros);
C.randu();

mat A(5, 6);

A.fill(123.0);   // or:  mat A(5, 6, fill::value(123.0));

std::mt19937 engine;  // Mersenne twister random number engine

std::uniform_real_distribution<double> distr(0.0, 1.0);
  
mat A(4, 5, fill::none);
  
A.imbue( [&]() { return distr(engine); } );

sp_mat A;

A.sprandu(1000, 1000, 0.01);

A(12,34) =  datum::eps;
A(56,78) = -datum::eps;

A.clean(datum::eps);

• 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

mat A(5, 6, fill::randu);

A.diag().fill(datum::nan);

A.replace(datum::nan, 0);  // replace each NaN with 0

mat A(5, 6, fill::randu);

A.clamp(0.2, 0.8);

mat A(4, 5, fill::ones);

// add 123 to every element
A.transform( [](double val) { return (val + 123.0); } );

// add 123 to each element in a dense matrix

mat A(4, 5, fill::ones);

A.for_each( [](mat::elem_type& val) { val += 123.0; } );  // NOTE: the '&' is crucial!


// add 123 to each non-zero element in a sparse matrix

sp_mat S; S.sprandu(1000, 2000, 0.1);

S.for_each( [](sp_mat::elem_type& val) { val += 123.0; } );  // NOTE: the '&' is crucial!


// set the size of all matrices in field F

field<mat> F(2,3);

F.for_each( [](mat& X) { X.zeros(4,5); } );  // NOTE: the '&' is crucial!

mat A;
A.set_size(5, 10);      // or:  mat A(5, 10, fill::none);

mat B;
B.set_size( size(A) );  // or:  mat B(size(A), fill::none);

vec v;
v.set_size(100);        // or:  vec v(100, fill::none);

• to change the size without preserving data, use .set_size() instead, which is much faster
• to grow/shrink the object while preserving the elements as well as the layout of the elements, use .resize() instead
• to flatten a matrix into a vector, use vectorise() or .as_col() / .as_row() instead

mat A(4, 5, fill::randu);

A.reshape(5,4);

mat A(4, 5, fill::randu);

A.resize(7,6);

mat A(5, 6, fill::randu);

mat B;
B.copy_size(A);

cout << B.n_rows << endl;
cout << B.n_cols << endl;

mat A(5, 5, fill::randu);
A.reset();

mat A(5, 10, fill::zeros);

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(5, 5, fill::randu);

// 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 = { 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;

• span() or span::all, to indicate the entire range
• span(a), to indicate a particular row, column or slice

cube A(2, 3, 4, fill::randu);

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;

• span() or span::all, to indicate the entire range
• span(a), to indicate a particular row or column

• .in_range()
• size()
• submatrix views
• subcube views

• k = 0 indicates the main diagonal (default setting)
• k < 0 indicates the k-th sub-diagonal (below main diagonal, towards bottom-left corner)
• k > 0 indicates the k-th super-diagonal (above main diagonal, towards top-right corner)

mat X(5, 5, fill::randu);

vec a = X.diag();
vec b = X.diag(1);
vec c = X.diag(-2);

X.diag() = randu<vec>(5);
X.diag() += 6;
X.diag().ones();

sp_mat S = sprandu<sp_mat>(10,10,0.1);

vec v(S.diag());  // copy sparse diagonal to dense vector

+		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 contains a list of indices of the columns/rows to be used; it must evaluate to a vector of type uvec
• arithmetic operations as per form 1 are supported

• apply the given lambda_function to each column vector or row vector
• the function must accept a reference to a Col or Row object with the same element type as the underlying matrix

mat X(6, 5, fill::ones);
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

+		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 argument vector_of_indices contains a list of indices of the slices to be used; it must evaluate to a vector of type uvec
• arithmetic operations as per form 1 are supported, except for * and *= (ie. matrix multiplication)

• apply the given lambda_function to each slice
• the function must accept a reference to a Mat object with the same element type as the underlying cube

• apply the given lambda_function to each slice, as per form 3
• the argument use_mp is a bool to enable the use of OpenMP for multi-threaded execution of lambda_function on multiple slices at the same time
• the order of processing the slices is not deterministic (eg. slice 2 can be processed before slice 1)
• lambda_function must be thread-safe, ie. it must not write to variables outside of its scope

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

   mat A(4, 5, fill::randu);
   mat B(4, 5, fill::randu);

cx_mat C(4, 5, fill::zeros);

C.set_real(A);
C.set_imag(B);

• if inserting rows, X must have the same number of columns (and slices) as the recipient object
• if inserting columns, X must have the same number of rows (and slices) 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)

• expand the object by creating new rows/columns/slices
• the elements in the new rows/columns/slices are set to zero

mat A(5, 10, fill::randu);
mat B(5,  2, fill::ones );

// 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);

mat A(5, 10, fill::randu);
mat B(5, 10, fill::randu);

A.shed_row(2);
A.shed_cols(2,4);

uvec indices = {4, 6, 8};
B.shed_cols(indices);

mat X(5, 5, fill::randu);
X.swap_rows(0,4);

mat A(4, 5, fill::zeros);
mat B(6, 7, fill::ones );

A.swap(B);

      mat A(5, 5, fill::randu);
const mat B(5, 5, fill::randu);

      double* A_mem = A.memptr();
const double* B_mem = B.memptr();

mat A(5, 5, fill::randu);

double* mem = A.colptr(2);

.begin()		iterator referring to the first element
.end()		iterator referring to the past-the-end element
.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
.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

mat::iterator vec::iterator rowvec::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		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 specified columns
mat::const_col_iterator vec::const_col_iterator rowvec::const_col_iterator		random access iterators, for read-only access to the elements of specified columns
mat::row_iterator		bidirectional iterator, for read/write access to the elements of specified rows
mat::const_row_iterator		bidirectional iterator, for read-only access to the elements of specified rows
vec::row_iterator rowvec::row_iterator		random access iterators, for read/write access to the elements of specified rows
vec::const_row_iterator rowvec::const_row_iterator		random access iterators, for read-only access to the elements of specified rows

mat X(5, 6, fill::randu);

mat::iterator it     = X.begin();
mat::iterator it_end = X.end();

for(; it != it_end; ++it)
  {
  cout << (*it) << endl;
  }

mat::col_iterator col_it     = X.begin_col(1);  // start of column 1
mat::col_iterator col_it_end = X.end_col(3);    //   end of column 3

for(; col_it != col_it_end; ++col_it)
  {
  cout << (*col_it) << endl;
  (*col_it) = 123.0;
  }

.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

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 iterator, 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 iterator, for read-only access to the elements of a particular slice

cube X(2, 3, 4, fill::randu);

cube::iterator it     = X.begin();
cube::iterator it_end = X.end();

for(; it != it_end; ++it)
  {
  cout << (*it) << endl;
  }

cube::slice_iterator s_it     = X.begin_slice(1);  // start of slice 1
cube::slice_iterator s_it_end = X.end_slice(2);    // end of slice 2

for(; s_it != s_it_end; ++s_it)
  {
  cout << (*s_it) << endl;
  (*s_it) = 123.0;
  }

• writing a zero value into a sparse matrix through an iterator will invalidate all current iterators associated with the sparse matrix
• to modify the non-zero elements in a safer manner, use .transform() or .for_each() instead of iterators

.begin()		iterator referring to the first element
.end()		iterator referring to the past-the-end element
.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
.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

sp_mat::iterator		bidirectional iterator, for read/write access to elements (which are stored column by column)
sp_mat::const_iterator		bidirectional iterator, for read-only access to elements (which are stored column by column)
sp_mat::col_iterator		bidirectional iterator, for read/write access to the elements of a specific column
sp_mat::const_col_iterator		bidirectional iterator, for read-only access to the elements of a specific column
sp_mat::row_iterator		bidirectional iterator, for read/write access to the elements of a specific row
sp_mat::const_row_iterator		bidirectional iterator, for read-only access to the elements of a specific row

sp_mat X = sprandu<sp_mat>(1000, 2000, 0.1);

sp_mat::const_iterator it     = X.begin();
sp_mat::const_iterator it_end = X.end();

for(; it != it_end; ++it)
  {
  cout << "val: " << (*it)    << endl;
  cout << "row: " << it.row() << endl;
  cout << "col: " << it.col() << endl;
  }

mat X(100, 200, fill::randu);

for( double& val : X(span(40,60), span(50,100)) )
  {
  cout << val << endl;
  val = 123.0;
  }

mat A(5, 5, fill::randu);
cout << A.size() << endl;

A.clear();
cout << A.empty() << endl;

mat X(4, 5, fill::randu);
vec v = X.as_col();

• return a matrix representation of the specified cube column
• the number of rows is preserved
• given a cube with size R x C x S, the resultant matrix size is R x S

• return a matrix representation of the specified cube row
• the number of columns is preserved
• given a cube with size R x C x S, the resultant matrix size is S x C

cube Q(5, 4, 3, fill::randu);

mat A = Q.col_as_mat(2);  // size of A: 5x3

mat B = Q.row_as_mat(2);  // size of B: 3x4

sp_mat A; A.sprandu(1000, 1000, 0.1);

// store the sum of each column of A directly in dense row vector 
rowvec r = sum(A).as_dense();      

// extract column 123 of A directly into dense column vector
colvec c = A.col(123).as_dense();  

• .t() provides a transposed copy of the matrix
• .st() is not applicable

• .t() provides a Hermitian (conjugate) transposed copy (ie. signs of imaginary components are flipped)
• .st() provides a simple transposed copy (ie. signs of imaginary components are not flipped)

mat A(4, 5, fill::randu);
mat B = A.t();

• if the given matrix is know to be symmetric positive definite, inv_sympd() is faster
• to solve a system of linear equations, such as X = A.i() * B, solve() can be faster and/or more accurate

mat A(4, 4, fill::randu);

mat X = A.i();

mat Y = (A+A).i();

mat A(5, 5, fill::randu);

double max_val = A.max();

mat A(5, 5, fill::randu);

uword i = A.index_max();

double max_val = A(i);

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);

• span() or span::all, to indicate the entire range
• span(a), to indicate a particular row, column or slice

mat A(4, 5, fill::randu);

cout << A.in_range(0,0) << endl;  // true
cout << A.in_range(3,4) << endl;  // true
cout << A.in_range(4,5) << endl;  // false

mat A(5, 5, fill::randu);
cout << A.is_empty() << endl;

A.reset();
cout << A.is_empty() << endl;

• 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

• returns true if the matrix can be interpreted as a column vector
• returns false if the matrix does not have exactly one column

• returns true if the matrix can be interpreted as a row vector
• returns false if the matrix does not have exactly one row

mat A(1, 5, fill::randu);
mat B(5, 1, fill::randu);
mat C(5, 5, fill::randu);

cout << A.is_vec() << endl;
cout << B.is_vec() << endl;
cout << C.is_vec() << endl;

"ascend"	↦	elements are ascending; consecutive elements can be equal; this is the default operation
"descend"	↦	elements are descending; consecutive elements can be equal
"strictascend"	↦	elements are strictly ascending; consecutive elements cannot be equal
"strictdescend"	↦	elements are strictly descending; consecutive elements cannot be equal

vec a(10, fill::randu);
vec b = sort(a);

bool check1 = a.is_sorted();
bool check2 = b.is_sorted();


mat A(10, 10, fill::randu);

// 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;

• return true if the matrix is upper triangular, ie. the matrix is square sized and all elements below the main diagonal are zero; return false otherwise
• caveat: if this function returns true, do not assume that the matrix contains non-zero elements on or above the main diagonal

• return true if the matrix is lower triangular, ie. the matrix is square sized and all elements above the main diagonal are zero; return false otherwise
• caveat: if this function returns true, do not assume that the matrix contains non-zero elements on or below the main diagonal

mat A(5, 5, fill::randu);
mat B = trimatl(A);

cout << A.is_trimatu() << endl;
cout << B.is_trimatl() << endl;

mat A(5, 5, fill::randu);
mat B = diagmat(A);

cout << A.is_diagmat() << endl;
cout << B.is_diagmat() << endl;

mat A(5, 5, fill::randu);
mat B(6, 7, fill::randu);

cout << A.is_square() << endl;
cout << B.is_square() << endl;

mat A(5, 5, fill::randu);
mat B = A.t() * A;

cout << A.is_symmetric() << endl;
cout << B.is_symmetric() << endl;

cx_mat A(5, 5, fill::randu);
cx_mat B = A.t() * A;

cout << A.is_hermitian() << endl;
cout << B.is_hermitian() << endl;

mat A(5, 5, fill::randu);

mat B = A.t() * A;

cout << A.is_sympd() << endl;
cout << B.is_sympd() << endl;

mat A(5, 5, fill::zeros);

A(0,0) = datum::eps;

cout << A.is_zero()           << endl;
cout << A.is_zero(datum::eps) << endl;

mat A(5, 5, fill::randu);
mat B(5, 5, fill::randu);

B(1,1) = datum::inf;

cout << A.is_finite() << endl;
cout << B.is_finite() << endl;

mat A(5, 5, fill::randu);
mat B(5, 5, fill::randu);

B(1,1) = datum::inf;

cout << A.has_inf() << endl;
cout << B.has_inf() << endl;

mat A(5, 5, fill::randu);
mat B(5, 5, fill::randu);

B(1,1) = datum::nan;

cout << A.has_nan() << endl;
cout << B.has_nan() << endl;

mat A(5, 5, fill::randu);
mat B(6, 6, fill::randu);

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;

mat A(5, 5, fill::randu);

cout.precision(11);
cout.setf(ios::fixed);

A.raw_print(cout, "A:");

mat A(123, 456, fill::randu);

A.brief_print("A:");

// possible output:
// 
// A:
// [matrix size: 123x456]
//    0.8402   0.7605   0.6218      ...   0.9744
//    0.3944   0.9848   0.0409      ...   0.7799
//    0.7831   0.9350   0.4140      ...   0.8835
//         :        :        :        :        :        
//    0.4954   0.1826   0.9848      ...   0.1918

auto_detect		Used only by .load() only: attempt to automatically detect the file type as one of the formats described below; [ default operation for .load() ]
arma_binary		Numerical data stored in machine dependent binary format, with a simple header to speed up loading. The header indicates the type and size of matrix/cube. [ default operation for .save() ]
arma_ascii		Numerical data stored in human readable text format, with a simple header to speed up loading. The header indicates the type and size of matrix/cube.
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.
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.
csv_ascii		Numerical data stored in comma separated value (CSV) text format, without a header. To save/load with a header, use the csv_name(filename,header) specification instead (more details below). Handles complex numbers stored in the compound form of 1.24+4.56i. Applicable to Mat and SpMat.
coord_ascii		Numerical data stored as a text file in coordinate list format, without a header. Only non-zero values are stored. For real matrices, each line contains information in the following format:  row column value For complex matrices, each line contains information in the following format:  row column real_value imag_value The rows and columns start at zero. Armadillo ≥ 10.3: applicable to Mat and SpMat; Armadillo ≤ 10.2: applicable to SpMat only. Caveat: not supported by auto_detect.
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.
hdf5_binary		Numerical data stored in portable HDF5 binary format. for saving, the default dataset name within the HDF5 file is "dataset" for loading, the order of operations is: (1) try loading a dataset named "dataset", (2) try loading a dataset named "value", (3) try loading the first available dataset to explicitly control the dataset name, specify it via the hdf5_name() argument (more details below)

• the dataset argument specifies an HDF5 dataset name (eg. "my_dataset") that can include a full path (eg. "/group_name/my_dataset"); if a blank dataset name is specified (ie. ""), it is assumed to be "dataset"
  
  
• the settings argument is optional; it is one of the following, or a combination thereof:
  
  

  hdf5_opts::trans		save/load the data with columns transposed to rows (and vice versa)
  hdf5_opts::append		instead of overwriting the file, append the specified dataset to the file; the specified dataset must not already exist in the file
  hdf5_opts::replace		instead of overwriting the file, replace the specified dataset in the file caveat: HDF5 may not automatically reclaim deleted space; use h5repack to clean HDF5 files

  
  the above settings can be combined using the + operator; for example: hdf5_opts::trans + hdf5_opts::append

• the header argument specifies the object which stores the separate elements of the header line; it must have the type field<std::string>
  
  
• the optional settings argument is one of the following, or a combination thereof:
  
  

  csv_opts::trans		save/load the data with columns transposed to rows (and vice versa)
  csv_opts::no_header		assume there is no header line; the header argument is not referenced
  csv_opts::semicolon		use semicolon (;) instead of comma (,) as the separator character
  csv_opts::strict		interpret missing values as NaN (not applicable to sparse matrices)

  
  the above settings can be combined using the + operator; for example: csv_opts::trans + csv_opts::no_header

mat A(5, 6, fill::randu);

// default save format is arma_binary
A.save("A.bin");

// save in raw_ascii format
A.save("A.txt", raw_ascii);

// save in CSV format without a header
A.save("A.csv", csv_ascii);

// save in CSV format with a header
field<std::string> header(A.n_cols);
header(0) = "foo";
header(1) = "bar";  // etc
A.save( csv_name("A.csv", header) );

// save in HDF5 format with internal dataset named as "my_data"
A.save(hdf5_name("A.h5", "my_data"));

// automatically detect format type while loading
mat B;
B.load("A.bin");

// force loading in arma_ascii format
mat C;
C.load("A.txt", arma_ascii);


// example of testing for success
mat D;
bool ok = D.load("A.bin");

if(ok == false)
  {
  cout << "problem with loading" << endl;
  }