• float, double, short, int, long, and unsigned versions of short, int, long
• Bandicoot provides convenient u32, u64, s32, and s64 types that can also be used
• Important: not all types are supported on all devices; runtime exceptions will be thrown if a type is not supported

fmat	=	Mat<float>
mat	=	Mat<double>		note: not supported on all devices
dmat	=	Mat<double>		note: not supported on all devices
umat	=	Mat<uword>
imat	=	Mat<sword>
u32_mat	=	Mat<u32>
s32_mat	=	Mat<s32>
u64_mat	=	Mat<u64>
s64_mat	=	Mat<s64>

fmat()
fmat(n_rows, n_cols)
fmat(n_rows, n_cols, fill_form)		(elements are initialised according to fill_form)
fmat(size(X))
fmat(size(X), fill_form)		(elements are initialised according to fill_form)
fmat(fmat)
fmat(arma::fmat)		(convert from CPU-based Armadillo matrix)
fmat(fvec)
fmat(frowvec)

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::none	↦	do not initialise the elements

• the elements are initialised to zero if fill_form is not specified; use fill::none to disable initialisation of elements
• setting the elements one by one is generally very inefficient and should be avoided if possible

fmat(ptr_aux_mem, n_rows, n_cols)


Create a matrix using data from writable auxiliary (external) GPU memory, where ptr_aux_mem is a pointer to the memory. This matrix will use the auxiliary memory directly (i.e., no copying); this can be dangerous unless you know what you are doing!

The ptr_aux_mem argument should be one of:
• a memory pointer from another Bandicoot matrix obtained with .get_dev_mem()
• a cl_mem object, if using the OpenCL backend
• a CUDA memory pointer (e.g. a float* for an fmat), if using the CUDA backend

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

float x = A(1, 2); // note: try to avoid repeated individual element accesses!

fmat B = A + A;
fmat C = A * B;
fmat D = A % B;

B.zeros();
B.set_size(10, 10);
B.ones(5, 6);

B.print("B:");

// convert from Armadillo
arma::fmat C(10, 10, arma::fill::randu);
fmat D(C);

// advanced constructors

// when using the OpenCL backend
cl_mem m_cl = clCreateBuffer(get_rt().cl_rt.get_context(), CL_MEM_READ_WRITE, sizeof(float) * 24, NULL, NULL);
fmat H(wrap_mem_cl(m_cl), 4, 6);  // use auxiliary memory

// when using the CUDA backend
float* m_cuda;
cudaMalloc(&m_cuda, sizeof(float) * 24);
fmat J(wrap_mem_cuda(m_cuda), 4, 6);  // use auxiliary memory

// make an alias of another matrix
arma::fmat K(D.get_dev_mem(), D.n_rows, D.n_cols);

• matrix attributes
• accessing elements
• math & relational operators
• submatrix views
• printing matrices
• .get_dev_mem()
• .eval()
• conv_to() (convert between matrix types)
• explanation of typedef (cplusplus.com)
• Col class
• Row class
• config.hpp

fvec	=	fcolvec	=	Col<float>
vec	=	colvec	=	Col<double>		note: not supported on all devices
dvec	=	dcolvec	=	Col<double>		note: not supported on all devices
uvec	=	ucolvec	=	Col<uword>
ivec	=	icolvec	=	Col<sword>
u32_vec	=	u32_colvec	=	Col<u32>
s32_vec	=	s32_colvec	=	Col<s32>
u64_vec	=	u64_colvec	=	Col<u64>
s64_vec	=	s64_colvec	=	Col<s64>

fvec()
fvec(n_elem)
fvec(n_elem, fill_form)		(elements are initialised according to fill_form)
fvec(size(X))
fvec(size(X), fill_form)		(elements are initialised according to fill_form)
fvec(fvec)
fvec(arma::fvec)		(convert from CPU-based Armadillo vector)
fvec(fmat)		(std::logic_error exception is thrown if the given matrix has more than one column)

• the elements are initialised to zero if fill_form is not specified; see the Mat class for details on fill_form
• setting the elements one by one is generally very inefficient and should be avoided if possible

fvec(ptr_aux_mem, number_of_elements)


Create a column vector using data from writable auxiliary (external) GPU memory, where ptr_aux_mem is a pointer to the memory. This vector will directly use the auxiliary memory (ie. no copying); this can be dangerous unless you know what you are doing!

The ptr_aux_mem argument should be one of:
• a memory pointer from another Bandicoot matrix obtained with .get_dev_mem()
• a cl_mem object, if using the OpenCL backend
• a CUDA memory pointer (e.g. a float* for an fmat), if using the CUDA backend

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

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

// convert from Armadillo
arma::fvec d(100, arma::fill::randu);
fvec e(d);

• Mat class
• Row class

frowvec	=	Row<float>
rowvec	=	Row<double>		note: not supported on all devices
drowvec	=	Row<double>		note: not supported on all devices
urowvec	=	Row<uword>
irowvec	=	Row<sword>
u32_rowvec	=	Row<u32>
s32_rowvec	=	Row<s32>
u64_rowvec	=	Row<u64>
s64_rowvec	=	Row<s64>

frowvec()
frowvec(n_elem)
frowvec(n_elem, fill_form)		(elements are initialised according to fill_form)
frowvec(size(X))
frowvec(size(X), fill_form)		(elements are initialised according to fill_form)
frowvec(frowvec)
frowvec(arma::frowvec)		(convert from CPU-based Armadillo row vector)
frowvec(fmat)		(std::logic_error exception is thrown if the given matrix has more than one row)

• the elements are initialised to zero if fill_form is not specified; see the Mat class for details on fill_form
• setting the elements one by one is generally very inefficient and should be avoided if possible

frowvec(ptr_aux_mem, number_of_elements)


Create a row vector using data from writable auxiliary (external) GPU memory, where ptr_aux_mem is a pointer to the memory. This vector will directly use the auxiliary memory (ie. no copying); this can be dangerous unless you know what you are doing!

The ptr_aux_mem argument should be one of:
• a memory pointer from another Bandicoot matrix obtained with .get_dev_mem()
• a cl_mem object, if using the OpenCL backend
• a CUDA memory pointer (e.g. a float* for an fmat), if using the CUDA backend

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

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

// convert from Armadillo
arma::frowvec d(100, arma::fill::randu);
fvec e(d);

• Mat class
• Col class

+		addition of two objects
−		subtraction of one object from another or negation of an object
*		matrix multiplication of two objects
%		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 of type umat
!=		element-wise non-equality evaluation of two objects; generates a matrix of type umat
>=		element-wise "greater than or equal to" evaluation of two objects; generates a matrix of type umat
<=		element-wise "less than or equal to" evaluation of two objects; generates a matrix of type umat
>		element-wise "greater than" evaluation of two objects; generates a matrix of type umat
<		element-wise "less than" evaluation of two objects; generates a matrix of type umat
&&		element-wise logical AND evaluation of two objects; generates a matrix of type umat
||		element-wise logical OR evaluation of two objects; generates a matrix of type umat

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

fmat P = A + B;
fmat Q = A - B;
fmat R = -B;
fmat S = A / 123.0;
fmat T = A % B;
fmat U = A * C;

fmat V = A + B + A + B;

imat AA = linspace<imat>(1, 9, 9);
imat BB = linspace<imat>(9, 1, 9);

// compare elements
umat ZZ = (AA >= BB);

• pow()
• any()
• all()
• accu()
• as_scalar()
• find()
• miscellaneous element-wise functions   (exp, log, sqrt, square, round, ...)
• floating point arithmetic in Wikipedia
• floating point representation in MathWorld

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

• .set_size()
• .zeros()
• .ones()
• .reset()
• size()

(i)		For fvec and frowvec, access the element stored at index i. For fmat, access the element/object stored at index i under the assumption of a flat layout, with column-major ordering of data (i.e. column by column). 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
(r,c)		For fmat, access the element/object stored at row r and column c. An exception is thrown if the requested element is out of bounds.
.at(r,c)		As for (r,c), 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] does not work correctly in C++; instead use (r,c)

// remember that individual element accesses are slow and should be avoided;
// when possible, operate in batch instead of on individual elements!
fmat M(10, 10, fill::randu);

M(9, 9) = 123.0;
float x = M(1, 2);

fvec v(10, fill::randu);

v(9) = 123.0;
float y = v(0);

• Armadillo adaptation guide
• submatrix views
• .get_dev_mem()
• config.hpp

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

fvec B;
B.zeros(100);

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

• zeros() (standalone function)
• .ones()
• .randu()
• .fill()
• .reset()
• .set_size()
• size()

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

fvec B;
B.ones(100);

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

• ones() (standalone function)
• .eye()
• .zeros()
• .fill()
• .randu()
• size()

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

fmat B(5, 5, fill::randu);
B.eye();

• .ones()
• .diag()
• diagmat()
• diagvec()
• eye() (standalone function)
• size()

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

fvec B;
B.randu(100);

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

coot_rng::set_seed_random(); // set the seed to a random value
coot_rng::set_seed(42);      // set the seed to a specific value 

• randu() (standalone function)
• randn() (standalone function with extended functionality)
• .fill()
• .ones()
• .zeros()
• size()
• uniform distribution in Wikipedia
• normal distribution in Wikipedia

fmat A(5, 6);

A.fill(123.0);

• .ones()
• .zeros()
• .randu() & .randn()
• constants (pi, nan, inf, ...)

fmat A(5, 6);
A.randu();

A.clamp(0.2, 0.8);

• clamp() (standalone function)
• relational operators

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

fmat B;
B.set_size( size(A) );  // or:  mat B(size(A));

fvec v;
v.set_size(100);        // or:  vec v(100);

• .reset()
• .reshape()
• .resize()
• .zeros()
• size()

• 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() instead

fmat A(4, 5);
A.randu();

A.reshape(5, 4);

• .resize()
• .set_size()
• .zeros()
• .reset()
• reshape() (standalone function)
• vectorise()
• size()

fmat A(4, 5);
A.randu();

A.resize(7, 6);

• .reshape()
• .set_size()
• .zeros()
• .reset()
• resize() (standalone function)
• vectorise()
• size()

fmat A(5, 5);
A.randu();

A.reset();

• .set_size()
• .is_empty()
• .zeros()

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 matrix ]

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 )

V.subvec( first_index, last_index )

V.subvec( first_index, size(W) )    [ W is a vector ]

X.diag()

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

A.submat( 0,1, 2,3 )      = randu<fmat>(3, 3);
A( span(0,2), span(1,3) ) = randu<fmat>(3, 3);
A( 0,1, size(3,3) )       = randu<fmat>(3, 3);

fmat B = A.submat( 0,1, 2,3 );
fmat C = A( span(0,2), span(1,3) );
fmat D = A( 0,1, size(3,3) );

A.col(1)        = randu<fmat>(5,1);
A(span::all, 1) = randu<fmat>(5,1);

// add 123 to the last 5 elements of vector a
vec a(10);
a.randu();
a.subvec(a.n_elem - 5, a.n_elem - 1) += 123.0;

// add 123 to the first 3 elements of column 2 of X
X.col(2).subvec(0, 2) += 123;

• diagonal views
• find()
• join_rows / cols / slices
• size()

• .get_dev_mem().cl_mem_ptr for the OpenCL backend; this has type cl_mem
• .get_dev_mem().cuda_mem_ptr for the CUDA backend; for a matrix type Mat<eT>, this has type eT* (e.g. for fmat the type will be float*)

// when using the OpenCL backend
fmat A(3, 4, fill::randu);
cl_mem A_mem = A.get_dev_mem().cl_mem_ptr;

// when using the CUDA backend
fmat B(3, 4, fill::randu);
float* B_mem = B.get_dev_mem().cuda_mem_ptr;

• backend configuration
• advanced constructors (matrices)
• advanced constructors (vectors)

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

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

• matrix and vector attributes
• .is_empty()
• .reset()

fmat X(5, 5);
X.randu();

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

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

• .eye()
• diagvec()
• diagmat()
• submatrix views
• trace()

fmat A(4, 5);
A.randu();

fmat B = A.t();

• trans()
• transpose in Wikipedia
• transpose in MathWorld

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

A.t().eval().print("A.t()");

• as_scalar()
• Mat class

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

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

• .is_square()
• .is_vec()
• .reset()

• 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

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

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

• .is_empty()
• .is_square()

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

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

• .is_empty()
• .is_vec()

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

• .raw_print()
• output streams

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

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

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

• .print()
• std::ios_base::fmtflags (cppreference.com)
• std::ios_base::fmtflags (cplusplus.com)

• fvec v = linspace(start, end, N)
• vector_type v = linspace<vector_type>(start, end, N)

   fvec a = linspace(0, 5, 6);

frowvec b = linspace<frowvec>(5, 0, 6);

• ones()

• mat X = eye( n_rows, n_cols )
• matrix_type X = eye<matrix_type>( n_rows, n_cols )
• matrix_type Y = eye<matrix_type>( size(X) )

  fmat A = eye(5,5);

  fmat B = 123.0 * eye<fmat>(5,5);

  imat C = eye<imat>( size(B) );

• .eye() (member function of Mat)
• .diag()
• ones()
• diagmat()
• diagvec()
• size()

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

   fvec v = ones(10);
   uvec u = ones<uvec>(10);
frowvec r = ones<frowvec>(10);

fmat A = ones(5,6);
imat B = ones<imat>(5,6);
umat C = ones<umat>(5,6);

• .ones() (member function of Mat, Col, and Row)
• .fill()
• eye()
• linspace()
• zeros()
• randu()

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

   fvec v = zeros(10);
   uvec u = zeros<uvec>(10);
frowvec r = zeros<rowvec>(10);

fmat A = zeros(5,6);
imat B = zeros<imat>(5,6);
umat C = zeros<umat>(5,6);

• .zeros() (member function of Mat, Col, and Row)
• .fill()
• ones()
• randu()
• size()

• vector_type v = randu<vector_type>( n_elem )


• matrix_type X = randu<matrix_type>( n_rows, n_cols )

fvec v1 = randu(5);

frowvec r1 = randu<rowvec>(5);

fmat A1 = randu(5, 6);

mat B1 = randu<mat>(5, 6);
mat B2 = randu<mat>(5, 6, distr_param(10,20));

coot_rng::set_seed_random(); // set the seed to a random value
coot_rng::set_seed(42);      // set the seed to a specific value

• .randu() (member function)
• randn()
• randi()
• ones()
• zeros()
• size()
• uniform distribution in Wikipedia

• vector_type v = randn<vector_type>( n_elem )
• vector_type v = randn<vector_type>( n_elem, distr_param(mu,sd) )


• matrix_type X = randn<matrix_type>( n_rows, n_cols )
• matrix_type X = randn<matrix_type>( n_rows, n_cols, distr_param(mu,sd) )

fvec v1 = randn(5);
fvec v2 = randn(5, distr_param(10,5));

frowvec r1 = randn<rowvec>(5);
frowvec r2 = randn<rowvec>(5, distr_param(10,5));

fmat A1 = randn(5, 6);
fmat A2 = randn(5, 6, distr_param(10,5));

mat B1 = randn<mat>(5, 6);
mat B2 = randn<mat>(5, 6, distr_param(10,5));

coot_rng::set_seed_random(); // set the seed to a random value
coot_rng::set_seed(42);      // set the seed to a specific value

• .randn() (member function)
• randu()
• randi()
• size()
• normal distribution in Wikipedia

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

imat A1 = randi(5, 6);
imat A2 = randi(5, 6, distr_param(-10, +20));

fmat B1 = randi<fmat>(5, 6);
fmat B2 = randi<fmat>(5, 6, distr_param(-10, +20));

coot_rng::set_seed_random(); // set the seed to a random value
coot_rng::set_seed(42);      // set the seed to a specific value

• randu()
• ones()
• zeros()
• size()

fmat A = randu<fmat>(5, 5);
fmat B = abs(A);

fvec X = linspace<fvec>(-5, 5, 11);
fvec Y = abs(X);

• pow()
• miscellaneous element-wise functions

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

float x = accu(A);

float y = accu(A % B);

• sum()
• trace()
• mean()
• dot()
• as_scalar()

• 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

fvec V(10, fill::randu);
fmat X(5, 5, fill::randu);

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

• any()
• find()
• conv_to() (convert between matrix/vector types)
• vectorise()

• 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

fvec V(10, fill::randu);
fmat X(5, 5, fill::randu);

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

• all()
• find()
• conv_to() (convert between matrix/vector types)
• vectorise()

"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

• all()
• any()
• find()
• relational operators

frowvec r(5, fill::randu);
fcolvec q(5, fill::randu);

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

// examples of expressions which have optimised implementations

float a = as_scalar(r*q);
float b = as_scalar(r*X*q);
float c = as_scalar(r*diagmat(X)*q);
float d = as_scalar(r*inv(diagmat(X))*q);

• vectorise()
• accu()
• trace()
• dot()
• norm()
• conv_to()

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

fmat B = clamp(A, 0.2,         0.8);
fmat C = clamp(A, min(min(A)), 0.8);
fmat D = clamp(A, 0.2, max(max(A)));

• .clamp() (member function)
• find()

fmat A(5, 5, fill::randu);
 mat B = conv_to<mat>::from(A);

fmat C(10, 1, fill::randu);
fcolvec x = conv_to< fcolvec >::from(C);

// convert from Armadillo object
arma::fmat D = conv_to<arma::fmat>::from(A);

• as_scalar()
• abs()
• advanced constructors (matrices)
• Armadillo/Bandicoot adaptation guide

fvec a(3, fill::randu);
fvec b(3, fill::randu);

fvec c = cross(a, b);

• dot()
• Cross product in Wikipedia
• Cross product in MathWorld

• val = det(A) throws a std::runtime_error exception
• det(val,A) returns a bool set to false (exception is not thrown)

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

float val1 = det(A);         // form 1

float val2;
bool success = det(val2, A); // form 2

• determinant in MathWorld
• determinant in Wikipedia

fmat A = randu<fmat>(5, 5);
fmat B = diagmat(A);
fmat C = diagmat(A,1);

fvec v = randu<fvec>(5);
fmat D = diagmat(v);
fmat E = diagmat(v,1);

• .diag()
• diagvec()
• trace()
• symmatu() / symmatl()
• reshape()
• vectorise()
• diagonal matrix in Wikipedia

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

fvec d = diagvec(A);

• .diag()
• diagmat()
• trace()
• vectorise()

fvec a(10, fill::randu);
fvec b(10, fill::randu);

float x = dot(a,b);

• norm()
• as_scalar()
• cross()

• to clamp values to an interval, clamp() is more efficient

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

uvec q1 = find(A > B);
uvec q2 = find(A > 0.5);
uvec q3 = find(A > 0.5, 3, "last");

• all()
• any()
• clamp()
• find_finite()
• find_nonfinite()
• find_nan()
• sort_index()
• submatrix views

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

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

// find only finite elements
uvec f = find_finite(A);

• find()
• find_nonfinite()
• find_nan()
• submatrix views
• constants (pi, nan, inf, ...)

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

A(1, 1) = datum::inf;
A(2, 2) = datum::nan;

// return indices of two non-finite elements
uvec f = find_nonfinite(A);

• find()
• find_finite()
• find_nan()
• submatrix views
• constants (pi, nan, inf, ...)

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

A(2, 3) = datum::nan;

// indices will be { 17 }
uvec indices = find_nan(A);

• find()
• find_finite()
• find_nonfinite()
• constants (pi, nan, inf, ...)
• NaN in Wikipedia

fmat A(4, 5, fill::randu);
fmat B(4, 6, fill::randu);
fmat C(6, 5, fill::randu);

fmat AB = join_rows(A, B);
fmat AC = join_cols(A, C);

• submatrix views

fcolvec v(10, fill::randu);
float x = max(v);

fmat M(10, 10, fill::randu);

frowvec a = max(M);
frowvec b = max(M, 0);
fcolvec c = max(M, 1);

// element-wise maximum
fmat X(5, 6, fill::randu);
fmat Y(5, 6, fill::randu);
fmat Z = coot::max(X, Y); // use coot:: prefix to distinguish from std::max()

• clamp()
• statistics functions

• to obtain the zero/Hamming pseudo-norm (the number of non-zero elements), use this expression: accu(X != 0)
• matrix 2-norm (spectral norm) is based on SVD, which is computationally intensive for large matrices

fvec q(5, fill::randu);

float x = norm(q, 2);
float y = norm(q, "inf");

• normalise()
• dot()
• vector norm in Wikipedia
• vector norm in MathWorld
• matrix norm in Wikipedia
• matrix norm in MathWorld

fvec A(10, fill::randu);
fvec B = normalise(A);
fvec C = normalise(A, 1);

fmat X(5, 6, fill::randu);
fmat Y = normalise(X);
fmat Z = normalise(X, 2, 1);

• norm()
• dot()
• Normalised vector in MathWorld
• Unit vector in Wikipedia

• to raise all elements to the power 2, use square() instead

fmat A(5, 6, fill::randu);
fmat B = pow(A, 3.45);

frowvec R(6, fill::randu);
frowvec S = pow(R, -1.0);

• abs()
• miscellaneous element-wise functions

n_rows	=	num_copies_per_row	×	A.n_rows
n_cols	=	num_copies_per_col	×	A.n_cols

fmat A(2, 3, fill::randu);

fmat B = repmat(A, 4, 5);

• reshape()
• resize()

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

fmat A(10, 5, fill::randu);

fmat B = reshape(A, 5, 10);

• .reshape() (member function)
• .set_size()
• resize()
• vectorise()
• as_scalar()
• conv_to()
• diagmat()
• repmat()
• size()

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

fmat B = resize(A, 7, 6);

• .resize() (member function of Mat)
• .set_size() (member function of Mat)
• reshape()
• vectorise()
• as_scalar()
• conv_to()
• repmat()
• size()

• object constructors: Mat, Col, Row
• functions for changing size: set_size(), reshape(), resize(), etc.
• submatrix views

fmat A(5,6);

fmat B = zeros<fmat>(size(A));

fmat C;
C.randu(size(A));

fmat D = ones<fmat>(size(A));

fmat E = ones<fmat>(10, 20);
E(3, 4, size(C)) = C;    // access submatrix of E

fmat F( size(A) + size(E) );

fmat G( size(A) * 2 );

cout << "size of A: " << size(A) << endl;

bool is_same_size = (size(A) == size(E));

• attributes

fmat A(10, 10, fill::randu);
fmat B = sort(A);

• sort_index()
• randi()

fvec q(10, fill::randu);

uvec indices = sort_index(q);

• sort()
• find()

fcolvec v(10, fill::randu);
float x = sum(v);

fmat M(10, 10, fill::randu);

frowvec a = sum(M);
frowvec b = sum(M, 0);
fcolvec c = sum(M, 1);

float y = accu(M);   // find the overall sum regardless of object type

• accu()
• trace()
• mean()
• as_scalar()

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

fmat B = symmatu(A);
fmat C = symmatl(A);

• diagmat()
• Symmetric matrix in Wikipedia

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

float x = trace(A);

• accu()
• as_scalar()
• .diag()
• diagvec()
• diagmat()
• sum()

fmat A(5, 10, fill::randu);

fmat B = trans(A);
fmat C = A.t();    // equivalent to trans(A), but more compact

• .t()
• transpose in Wikipedia
• transpose in MathWorld

fmat X(4, 5, fill::randu);

fvec v = vectorise(X);

• reshape()
• resize()
• diagvec()
• as_scalar()

• B = fn(A), where fn(A) is one of the functions below
• A and B must have the same matrix or vector type, such as fmat or ivec

fmat A(5, 5, fill::randu);
fmat B = exp(A);

• abs()
• pow()
• clamp()
• trigonometric functions
• statistics functions
• miscellaneous constants

• cos, acos, cosh, acosh
• sin, asin, sinh, asinh
• tan, atan, tanh, atanh
• sinc, defined as sinc(x) = sin(πx) / (πx) for x ≠ 0, and sinc(x) = 1 for x = 0

• Z = atan2(Y, X)
• Z = hypot(X, Y)

fmat X(5, 5, fill::randu);
fmat Y = cos(X);

• miscellaneous element-wise functions
• trigonometric functions in Wikipedia
• atan2 function in Wikipedia
• hypot function in Wikipedia
• sinc function in Wikipedia

• the form R = chol(X) resets R and throws a std::runtime_error exception
• the form chol(X, R) resets R and returns a bool set to false (exception is not thrown)

fmat A(5, 5, fill::randu);
fmat X = A.t() * A;

mat R1 = chol(X);
mat R2;
bool ok = chol(R2, X);

• lu()
• Cholesky decomposition in MathWorld
• Cholesky decomposition in Wikipedia
• Definite matrix in Wikipedia

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

• there is no explicit check whether X is symmetric/hermitian
• if eigenvectors are not necessary, it is more efficient to use a form that does not compute them (i.e. eig_sym(eigval, X))

// for matrices with real elements

fmat A(50, 50, fill::randu);
fmat B = A.t()*A;  // generate a symmetric matrix

fvec eigval;
fmat eigvec;

eig_sym(eigval, eigvec, B);

• svd()
• eigen decomposition in MathWorld
• eigenvalues & eigenvectors in Wikipedia
• divide & conquer eigenvalue algorithm in Wikipedia

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

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

fmat L, U, P;

lu(L, U, P, A);

fmat B = P.t() * L * U;

• chol()
• solve()
• LU decomposition in Wikipedia
• LU decomposition in MathWorld

• mar_rc = max(A.n_rows, A.n_cols)
• max_sv = maximum singular value of A
• epsilon = difference between 1 and the least value greater than 1 that is representable

• B = pinv(A) resets B and throws a std::runtime_error exception
• pinv(B,A) resets B and returns a bool set to false (exception is not thrown)

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

fmat B = pinv(A);        // use default tolerance

fmat C = pinv(A, 0.01);  // set tolerance to 0.01

• solve()
• datum::eps
• Pseudoinverse in MathWorld
• Moore-Penrose Matrix Inverse in MathWorld
• Moore-Penrose inverse in Wikipedia

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

fmat A(5, 5, fill::randu);
A.diag() += 3; // ensure positive definite

fvec b(5, fill::randu);
fvec x1 = solve(A, b);

fvec x2;
bool status = solve(x2, A, b);

fmat B(5, 5, fill::randu);
fmat X1 = solve(A, B);

• lu()
• pinv()
• linear system of equations in MathWorld
• system of linear equations in Wikipedia
• definiteness of a matrix in Wikipedia
• positive definite matrix in MathWorld
• ensmallen - library for solving arbitrary optimisation problems

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

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

fmat U;
fvec s;
fmat V;

svd(U, s, V, X);

• eig_sym()
• singular value decomposition in Wikipedia
• singular value decomposition in MathWorld

"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

fvec A(256, fill::randu);

fvec B(16, fill::randu);

fvec C = conv(A, B);

fvec D = conv(A, B, "same");

• conv2()
• cor()
• Convolution in MathWorld
• Convolution in Wikipedia
• FIR filter in Wikipedia

"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

fmat A(256, 256, fill::randu);

fmat B(16, 16, fill::randu);

fmat C = conv2(A, B);

fmat D = conv2(A, B, "same");

• conv()
• Convolution in MathWorld
• Convolution in Wikipedia
• Kernel (image processing) in Wikipedia

• the default norm_type = 0 performs normalisation using N-1 (where N is the number of samples), providing the best unbiased estimator
• using norm_type = 1 performs normalisation using N, which provides the second moment around the mean

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

fmat B  = mean(A);
fmat C  = var(A);
float m = mean(mean(A));

fvec v(5, fill::randu);
float x = var(v);

• cov()
• cor()
• min() & max()

• for norm_type = 0, normalisation is done using N-1, providing the best unbiased estimation of the covariance matrix (if the observations are from a normal distribution)
• for norm_type = 1, normalisation is done using N, which provides the second moment matrix of the observations about their mean

fmat X(4, 5, fill::randu);
fmat Y(4, 5, fill::randu);

fmat C = cov(X, Y);
fmat D = cov(X, Y, 1);

• cor()
• statistics functions
• Covariance in MathWorld

• for norm_type = 0, normalisation is done using N-1
• for norm_type = 1, normalisation is done using N

fmat X(4, 5, fill::randu);
fmat Y(4, 5, fill::randu);

fmat R = cor(X, Y);
fmat S = cor(X, Y, 1);

• cov()
• conv()
• statistics functions
• Correlation in MathWorld
• Autocorrelation in MathWorld

• coot_init() returns a boolean indicating whether or not initialisation was successful


• if print_info is set to true, information about the selected GPU device will be printed


• for the "opencl" initialisations, platform_id and dev_id specify the desired OpenCL platform and device IDs; available platforms and devices can be listed using the clinfo command-line utility, available in most package managers: clinfo -l


• for the "cuda" initialisations, dev_id specifies the desired CUDA device; available device IDs can be listed with the nvidia-smi command-line utility

• calling coot_init() manually must be done before any other Bandicoot operations
• coot_init() can only be called once
• if either caveat above is violated when calling coot_init(), a std::runtime_error exception will be thrown

• CUDA in Wikipedia
• OpenCL in Wikipedia

cout << "speed of light = " << datum::c_0 << endl;

cout << "log_max for floats = ";
cout << fdatum::log_max << endl;

cout << "log_max for doubles = ";
cout << datum::log_max << endl;

• .fill()
• NaN in Wikipedia
• physical constant in Wikipedia
• replacement of 2π with τ in Wikipedia
• The Tau Manifesto by Michael Hartl
• std::numeric_limits in cplusplus.com
• std::numeric_limits in cppreference.com

wall_clock timer;

timer.tic();

// ... do something ...

double n = timer.toc();

cout << "number of seconds: " << n << endl;

• elapsed real time in Wikipedia

#define COOT_WARN_LEVEL 1
#include <bandicoot>

• config.hpp
• .print()
• std::cout
• std::cerr
• std::ostream

• the default width is 32 bits on 32-bit platforms
• the default width is 64 bits on 64-bit platforms
• uword is a typedef for std::size_t

• C++ variable types
• explanation of typedef
• imat & umat matrix types
• ivec & uvec vector types

• GPUs are best suited for operations on large matrices, so small matrices (e.g. with size ≤ 100x100) may not obtain speedups
• Individual element access such as X(i,j) has an overhead of transferring between the GPU and CPU; when adapting Armadillo code to Bandicoot, direct element access should be avoided
• Where possible, use batch operations with Bandicoot; e.g., use A += 1 instead of for(uword i=0; i<A.n_elem; ++i) { A[i] += 1; }
• If direct element access cannot be avoided, consider temporarily transferring the entire Bandicoot matrix to CPU-accessible memory by creating an Armadillo matrix via conv_to<arma::fmat>(X)
• Due to the overhead of direct element access, Bandicoot does not provide iterators
• Consumer-level GPUs typically obtain better performance with 32-bit floating point elements rather than 64-bit (e.g. float instead of double), so using fmat instead of mat is preferable

g++ example.cpp -o example -std=c++11 -O2 -lbandicoot

• element access
• uword/sword
• output streams

• -lOpenCL (core OpenCL support)
• -lclBLAS (clBLAS for BLAS operations)

• -lcuda (core CUDA support)
• -lcudart (CUDA runtime library)
• -lnvrtc (runtime compilation of CUDA kernels)
• -lcublas (cuBLAS for BLAS operations)
• -lcusolver (cuSolverDn for decompositions and factorisations)
• -lcurand (cuRand for random number generation)

• on Linux, macOS, and UNIX-like systems: ~/.bandicoot/cache/ (e.g. /home/user/.bandicoot/cache/)
• on Windows: %APPDATA%\bandicoot\cache (e.g. C:\Users\Username\AppData\bandicoot\cache)

• Each release of Bandicoot has its public API (functions, classes, constants) described in the accompanying API documentation specific to that release.


• Each release of Bandicoot has its full version specified as A.B.C, where A is a major version number, B is a minor version number, and C is a patch level (indicating bug fixes). The version specification has explicit meaning, similar to Semantic Versioning, as follows:


• Within a major version (eg. 1), each minor version (eg. 1.1) has a public API that strongly strives to be backwards compatible (at the source level) with the public API of preceding minor versions. For example, user code written for version 1.0 should work with version 1.1, 1.2, etc. However, later minor versions may have more features (API additions and extensions) than preceding minor versions. As such, user code specifically written for version 1.2 may not work with 1.1.


• An increase in the patch level, while the major and minor versions are retained, indicates modifications to the code and/or documentation which aim to fix bugs without altering the public API.


• We don't like changes to existing public API and strongly prefer not to break any user software. However, to allow evolution, the public API may be altered in future major versions while remaining backwards compatible in as many cases as possible (eg. major version 2 may have slightly different public API than major version 1).


• Caveat: the above policy applies only to the public API described in the documentation. Any functionality within Bandicoot which is not explicitly described in the public API documentation is considered as internal implementation details, and may be changed or removed without notice.

• Version 1.13.0:
  • bugfixes for OpenCL backend on Mac OS


• Version 1.12.4:
  • add compatibility container functions: .front(), .back(), .size(), .clear(), .empty()
  • fix bug in two-dimensional CUDA grid size computation
  • add approx_equal()


• Version 1.11.1:
  • additional efficiency improvements for subview handling
  • handle Fortran "hidden arguments"; see COOT_USE_FORTRAN_HIDDEN_ARGS


• Version 1.11.0:
  • significant efficiency improvements for subview handling
  • removed redundant GPU kernels, improving compilation time
  • added element-wise min() and max()


• Version 1.10.0:
  • first stable release!