armadillo
 
Armadillo
C++ linear algebra library

 
 
      
About
License
Questions
API Docs
Speed
Authors
Download

[top]
API Reference for Armadillo 4.550

Preamble

 


Matrix, Vector, Cube and Field Classes
Member Functions & Variables
Generated Vectors/Matrices/Cubes
Functions Individually Applied to Each Element of a Matrix/Cube
Scalar Valued Functions of Vectors/Matrices/Cubes
Scalar/Vector Valued Functions of Vectors/Matrices
Vector/Matrix/Cube Valued Functions of Vectors/Matrices/Cubes
Decompositions, Factorisations, Inverses and Equation Solvers
Statistical Modelling
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:
      mat  =  Mat<double>
      fmat  =  Mat<float>
      cx_mat  =  Mat<cx_double>
      cx_fmat  =  Mat<cx_float>
      umat  =  Mat<uword>
      imat  =  Mat<sword>

  • 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(mat)
      mat(vec)
      mat(rowvec)
      mat(string)
      mat(std::vector)   (treated as a column vector)
      mat(initialiser_list)   (C++11 only)
      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 the format string "1 0; 0 1". While string based initialisation is compact, it is considerably faster to directly set the elements, use element initialisation, or use C++11 initialiser lists.

  • Advanced constructors:

      mat(aux_mem*, n_rows, n_cols, copy_aux_mem = true, strict = true)

        Create a matrix using data from writable auxiliary 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're doing!

        The strict variable comes into effect only if copy_aux_mem is set to false (ie. the matrix is directly using auxiliary memory). If 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 (directly or indirectly). If strict is set to false, the matrix will not be bound to the auxiliary memory for its lifetime, ie., the size of the matrix can be changed. If the requested number of elements is different to the size of the auxiliary memory, new memory will be allocated and the auxiliary memory will no longer be used.

      mat(const aux_mem*, n_rows, n_cols)

        Create a matrix by copying data from read-only auxiliary 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 aux_mem*)

        Create a fixed size matrix, with the size specified via template arguments, and copying data from auxiliary memory.


  • Examples:
      mat A = randu<mat>(5,5);
      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);
      
      mat E(4,5, fill::zeros);
      
      //
      // fixed size matrices:
      
      mat::fixed<5,6> F;
      F.ones();
      
      mat44 G;
      G.randn();
      
      cout << mat22().randu() << endl;
      
      //
      // constructing matrices from
      // auxiliary (external) memory:
      
      double aux_mem[24];
      mat H(aux_mem, 4, 6, false);
      

  • 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
  • Classes for column vectors (matrices with one column)

  • The Col<type> class is derived from the Mat<type> class and inherits most of the member functions

  • For convenience the following typedefs have been defined:
      vec  =  colvec  =  Col<double>
      fvec  =  fcolvec  =  Col<float>
      cx_vec  =  cx_colvec  =  Col<cx_double>
      cx_fvec  =  cx_fcolvec  =  Col<cx_float>
      uvec  =  ucolvec  =  Col<uword>
      ivec  =  icolvec  =  Col<sword>

  • In this documentation, the vec and colvec types have the same meaning and are used interchangeably

  • In this documentation, the types vec or colvec are used for convenience; it is possible to use other types instead, eg. fvec, fcolvec

  • Functions which take Mat as input can generally also take Col as input. Main exceptions are functions which require square matrices

  • Constructors
      vec()
      vec(n_elem)
      vec(n_elem, fill_type)
      vec(vec)
      vec(mat)   (a std::logic_error exception is thrown if the given matrix has more than one column)
      vec(string)   (elements separated by spaces)
      vec(std::vector)
      vec(initialiser_list)   (C++11 only)

  • When specifying the size with n_elem, by default the memory is uninitialised; memory can be initialised by specifying the fill_type, as per the Mat class

  • Advanced constructors:

      vec(aux_mem*, number_of_elements, copy_aux_mem = true, strict = true)

        Create a column vector using data from writable auxiliary 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're doing!

        The strict variable comes into effect only if copy_aux_mem is set to false (ie. the vector is directly using auxiliary memory). If 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 (directly or indirectly). If strict is set to false, the vector will not be bound to the auxiliary memory for its lifetime, ie., the vector's size can be changed. If the requested number of elements is different to the size of the auxiliary memory, new memory will be allocated and the auxiliary memory will no longer be used.

      vec(const aux_mem*, number_of_elements)

        Create a column vector by copying data from read-only auxiliary 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 allocated 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 simply appending a single digit form of the size to the vector type -- for example, vec3 is equivalent to vec::fixed<3>, while cx_vec4 is equivalent to cx_vec::fixed<4>.

      vec::fixed<number_of_elements>(const aux_mem*)

        Create a fixed size column vector, with the size specified via the template argument, and copying data from auxiliary memory.


  • Examples:
      vec x(10);
      vec y = zeros<vec>(10);
      
      mat A = randu<mat>(10,10);
      vec z = A.col(5); // extract a column vector
      

  • 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
  • Classes for row vectors (matrices with one row)

  • The template Row<type> class is derived from the Mat<type> class and inherits most of the member functions

  • For convenience the following typedefs have been defined:
      rowvec  =  Row<double>
      frowvec  =  Row<float>
      cx_rowvec  =  Row<cx_double>
      cx_frowvec  =  Row<cx_float>
      urowvec  =  Row<uword>
      irowvec  =  Row<sword>

  • In this documentation, the rowvec type is used for convenience; it is possible to use other types instead, eg. frowvec

  • Functions which take Mat as input can generally also take Row as input. Main exceptions are functions which require square matrices

  • Constructors
      rowvec()
      rowvec(n_elem)
      rowvec(n_elem, fill_type)
      rowvec(rowvec)
      rowvec(mat)   (a std::logic_error exception is thrown if the given matrix has more than one row)
      rowvec(string)   (elements separated by spaces)
      rowvec(std::vector)
      rowvec(initialiser_list)   (C++11 only)

  • When specifying the size with n_elem, by default the memory is uninitialised; memory can be initialised by specifying the fill_type, as per the Mat class

  • Advanced constructors:

      rowvec(aux_mem*, number_of_elements, copy_aux_mem = true, strict = true)

        Create a row vector using data from writable auxiliary 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're doing!

        The strict variable comes into effect only if copy_aux_mem is set to false (ie. the vector is directly using auxiliary memory). If 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 (directly or indirectly). If strict is set to false, the vector will not be bound to the auxiliary memory for its lifetime, ie., the vector's size can be changed. If the requested number of elements is different to the size of the auxiliary memory, new memory will be allocated and the auxiliary memory will no longer be used.

      rowvec(const aux_mem*, number_of_elements)

        Create a row vector by copying data from read-only auxiliary 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 allocated 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 simply appending a single digit form of the size to the vector type -- for example, rowvec3 is equivalent to rowvec::fixed<3>, while cx_rowvec4 is equivalent to cx_rowvec::fixed<4>.

      rowvec::fixed<number_of_elements>(const aux_mem*)

        Create a fixed size row vector, with the size specified via the template argument, and copying data from auxiliary memory.


  • Examples:
      rowvec x(10);
      rowvec y = zeros<rowvec>(10);
      
      mat    A = randu<mat>(10,10);
      rowvec z = A.row(5); // extract a row vector
      

  • 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:
      cube  =  Cube<double>
      fcube  =  Cube<float>
      cx_cube  =  Cube<cx_double>
      cx_fcube  =  Cube<cx_float>
      ucube  =  Cube<uword>
      icube  =  Cube<sword>

  • 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(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(aux_mem*, n_rows, n_cols, n_slices, copy_aux_mem = true, strict = true)

        Create a cube using data from writable auxiliary 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're doing!

        The strict variable comes into effect only if copy_aux_mem is set to false (ie. the cube is directly using auxiliary memory). If 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 (directly or indirectly). If strict is set to false, the cube will not be bound to the auxiliary memory for its lifetime, ie., the size of the cube can be changed. If the requested number of elements is different to the size of the auxiliary memory, new memory will be allocated and the auxiliary memory will no longer be used.

      cube(const aux_mem*, n_rows, n_cols, n_slices)

        Create a cube by copying data from read-only auxiliary 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

    • The size of individual slices can't be changed. For example, the following will not work:
        cube c(5,6,7);
        c.slice(0) = randu<mat>(10,20); // wrong size
        
    • 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 (resulting in a field of vectors), or matrix, or cube

  • Each element can have an arbitrary 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>(field<object_type>)

  • Caveat: if you want to store a set of matrices of the same size, the Cube class is more efficient

  • Examples:
      // create a field containing vectors
      field<vec> F(3,2);
      
      // each vector in the field can have an arbitrary size
      F(0,0) = vec(5);
      F(1,1) = randu<vec>(6);
      F(2,0).set_size(7);
      
      // access element 1 of vector stored at 2,0
      double x = F(2,0)(1);
      
      // copy a row of vectors
      F.row(0) = F.row(2);
      
      // extract a row of vectors from F
      field<vec> G = F.row(1);
      
      // print the field to the standard output
      G.print("G =");
      
      // save the field to a binary file
      G.save("vec_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(sp_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(rowind, colptr, values, n_rows, n_cols)
    • form 2: sp_mat(locations, values, sort_locations = true)
    • form 3: sp_mat(locations, values, n_rows, n_cols, sort_locations = true, check_for_zeros = true)
    • form 4: sp_mat(add_values, locations, values, n_rows, n_cols, sort_locations = true, check_for_zeros = true)

      • Using batch insertion constructors is generally much faster than consecutively inserting values using element access operators

      • For form 1, rowind is a dense column vector of type umat or uvec containing the row indices of the values to be inserted, and colptr is a dense column vector of type umat or uvec containing indices of values corresponding to the start of new columns; the vectors correspond to the arrays used by the compressed sparse column format

      • For forms 2, 3, 4, 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 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 2 and 3, the value in values[i] will be inserted at the location specified by the i-th column of the locations matrix.

      • For form 4, 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 manually specified via n_rows and n_cols (forms 1, 3, 4), or automatically determined from the maximal locations in the locations matrix (form 2)

      • 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

  • Caveat: support for sparse matrices in this version is preliminary; it is not yet fully optimised, and sparse matrix decompositions/factorisations are not yet fully implemented; the following subset of operations currently works with sparse matrices:

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





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


.colptr( col_number )

.copy_size( A )
  • Set the size to be the same as object A

  • Object A must be of the same root type as the object being modified (eg. you can't set the size of a matrix by providing a cube)

  • Examples:
      mat A = randu<mat>(5,6);
      mat B;
      B.copy_size(A);
      
      cout << B.n_rows << endl;
      cout << B.n_cols << endl;
      

  • See also:



.diag()
.diag( k )
  • Member function of Mat

  • Read/write access to a diagonal in a matrix

  • The argument k is optional; by default the main diagonal is accessed (k=0)

  • For k > 0, the k-th super-diagonal is accessed (top-right corner)

  • For k < 0, the k-th sub-diagonal is accessed (bottom-left corner)

  • The diagonal is interpreted as a column vector within expressions

  • Examples:
      mat X = randu<mat>(5,5);
      
      vec a = X.diag();
      vec b = X.diag(1);
      vec c = X.diag(-2);
      
      X.diag()  = randu<vec>(5);
      X.diag() += 6;
      

  • See also:



.each_col()
.each_row()

.each_col( vector_of_indices )
.each_row( vector_of_indices )
  • Member functions of Mat

  • Write access to each column or row of a matrix/submatrix, allowing a vector operation to be repeated on each column or row

  • The operation can be in-place vector addition, subtraction, element-wise multiplication, element-wise division, or simply vector copy

  • The argument vector_of_indices is optional -- by default all columns or rows are accessed

  • If the argument vector_of_indices is used, it must evaluate to be a vector of type uvec; the vector contains a list of indices of the columns or rows to be accessed

  • Examples:
      mat X = ones<mat>(6,5);
      vec v = linspace<vec>(10,15,6);
      
      // add v to each column in X
      X.each_col() += v;
      
      // 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;
      
      // copy v to columns 2 and 4 in X
      X.each_col(indices) = v;
      

  • 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 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)
      Cube only: access the element 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.

  • Note: 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
  • Instances of Mat, Col, Row and field classes can be initialised via the << operator

  • Special element endr indicates "end of row" (conceptually similar to std::endl)

  • Setting elements via << is a bit slower than directly accessing the elements, but code using << is generally more readable and easier to write

  • When using a C++11 compiler, matrices and vectors can use initialiser lists instead; for example: { 1, 2, 3, 4 }

  • Examples:
      mat A;
      
      A << 1 << 2 << 3 << endr
        << 4 << 5 << 6 << endr;
      
      mat B = { 1, 2, 3, 4, 5, 6 };  // C++11 only
      B.reshape(2,3);
      

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



.eye()
.eye( n_rows, n_cols )
  • Member functions of Mat and SpMat

  • Set the elements along the main diagonal to one and off-diagonal elements to zero, optionally first resizing to specified dimensions

  • An identity matrix is generated when n_rows = n_cols

  • Examples:
      mat A(5,5);
      A.eye();
      
      mat B;
      B.eye(5,5);
      

  • See also:



.fill( value )

.i()
.i( method )
  • Member functions of any matrix expression

  • Provides an inverse of the matrix expression

  • If the matrix expression is not square, a std::logic_error exception is thrown

  • If the matrix expression appears to be singular, the output matrix is reset and a std::runtime_error exception is thrown

  • The method argument is optional. For matrix sizes ≤ 4x4, a fast algorithm is used. In rare instances, the fast algorithm might be less precise than the standard algorithm. To force the use of the standard algorithm, set the method argument to "std". For matrix sizes greater than 4x4, the standard algorithm is always used

  • Caveat: if matrix A is know to be symmetric positive definite, it's faster to use inv_sympd() instead

  • Caveat: if you want to solve a system of linear equations, such as Z = inv(X)*Y, it is faster and more accurate to use solve() instead

  • Examples:
      mat A = randu<mat>(4,4);
      mat B = randu<mat>(4,1);
      
      mat X = A.i();
      
      mat Y = (A+A).i();
      
  • See also:



.in_range( i )
  (member of Mat, Col, Row, Cube and field)
.in_range( span(start, end) )
  (member of Mat, Col, Row, Cube and field)
 
.in_range( row, col )
  (member of Mat, Col, Row and field)
.in_range( span(start_row, end_row), span(start_col, end_col) )
  (member of Mat, Col, Row and 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 mat or field)
  (member of Mat, Col, Row and field)
.in_range( first_row, first_col, size(n_rows, n_cols) )
  (member of Mat, Col, Row and 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()
  • Returns true if the object has no elements

  • Returns false if the object has one or more elements

  • Examples:
      mat A = randu<mat>(5,5);
      cout << A.is_empty() << endl;
      
      A.reset();
      cout << A.is_empty() << 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:



.is_square()
  • Member function of Mat and SpMat

  • Returns true if the matrix is square, ie., number of rows is equal to the number of columns

  • Returns false if the matrix is not square

  • Examples:
      mat A = randu<mat>(5,5);
      mat B = randu<mat>(6,7);
      
      cout << A.is_square() << endl;
      cout << B.is_square() << endl;
      

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



.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; each slice is filled column-by-column

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



.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:



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:



.memptr()
  • Member function of Mat, Col, Row and Cube

  • Obtain a raw pointer to the memory used for storing elements. Not recommended for use unless you know what you're doing!

  • The function can be used for interfacing with libraries such as FFTW

  • As soon as the size of the matrix/vector/cube is changed, the pointer is no longer valid

  • Data for matrices is stored in a column-by-column order

  • Data for cubes is stored in a slice-by-slice (matrix-by-matrix) order

  • Examples:
            mat A = randu<mat>(5,5);
      const mat B = randu<mat>(5,5);
      
            double* A_mem = A.memptr();
      const double* B_mem = B.memptr();
      

  • See also:



.min()
  (member functions of Mat, Col, Row, SpMat, Cube)
.max()
   
 
   
.min( index_of_min_val )
  (member functions of Mat, Col, Row, SpMat, Cube)
.max( index_of_max_val )
   
 
   
.min( row_of_min_val, col_of_min_val )
  (member functions of Mat and SpMat)
.max( row_of_max_val, col_of_max_val )
   
 
   
.min( row_of_min_val, col_of_min_val, slice_of_min_val )
  (member functions of Cube)
.max( row_of_max_val, col_of_max_val, slice_of_max_val )
   

  • Without arguments: return the extremum value of an object

  • With one or more arguments: return the extremum value of an object and store the location of the extremum value in the provided variable(s)

  • The provided variables must be of type uword

  • Examples:
      vec v = randu<vec>(10);
      
      cout << "min value is " << v.min() << endl;
      
      
      uword  index;
      double min_val = v.min(index);
      
      cout << "index of min value is " << index << endl;
      
      
      mat A = randu<mat>(5,5);
      
      uword  row;
      uword  col;
      double min_val2 = A.max(row,col);
      
      cout << "max value is at " << row << ',' << col << endl;
      

  • 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)
  • Set all the elements of an object to one, optionally first resizing to specified dimensions

  • Examples:
      mat A = randu<mat>(5,10);
      A.ones();      // sets all elements to one
      A.ones(10,20); // sets the size to 10 rows and 20 columns
                     // followed by setting all elements to one
      

  • See also:



operators:  +  -  *  /  %  ==  !=  <=  >=  <  >
  • Overloaded operators for mat, vec, rowvec 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., ==, !=, >=, <=) may not work as expected for floating point element types (ie., float, double) due to the necessarily limited precision of these types; in other words, these operators are (in general) not recommended for matrices of type mat or fmat

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



.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 )
  • Member functions of Mat, Col, Row, SpMat and Cube

  • Similar to the .print() member function, with the difference that no formatting of the output is done -- ie. the user can set the stream's parameters such as precision, cell width, etc.

  • If the cell width is set to zero, a space is printed between the elements

  • Examples:
      mat A = randu<mat>(5,5);
      
      cout.precision(11);
      cout.setf(ios::fixed);
      
      A.raw_print(cout, "A =");
      



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

.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)
  • Set all the elements to random values, optionally first resizing 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(4,5);
      A.randu();
      
      mat B;
      B.randu(6,7);
      
      arma_rng::set_seed_random();  // set the seed to a random value
      

  • See also:



.reset()


.reshape( n_rows, n_cols )
  (member function of Mat)
.reshape( n_rows, n_cols, n_slices )
  (member function of Cube)
  • Recreate the object according to given size specifications, with the elements taken from the previous version of the object in a column-wise manner; the elements in the generated object are placed column-wise (ie. the first column is filled up before filling the second column)

  • The layout of the elements in the recreated object will be different to the layout in the previous version of the object

  • The new total number of elements (according to the specified size) doesn't have to be the same as the previous total number of elements in the object

  • If the total number of elements in the previous version of the object is less than the specified size, the extra elements in the recreated object are set to zero

  • If the total number of elements in the previous version of the object is greater than the specified size, only a subset of the elements is taken

  • Caveat: do not use .reshape() if you simply want to change the size without preserving data; use .set_size() instead, which is much faster

  • Caveat: if you wish to grow/shrink the object while preserving the elements as well as the layout of the elements, use .resize() instead

  • Caveat: if you want to create a vector representation of a matrix (ie. concatenate all the columns or rows), use vectorise() instead

  • Examples:
      mat A = randu<mat>(4,5);
      
      A.reshape(5,4);
      

  • See also:



.resize( n_elem )
  (member function of Col, Row)
.resize( n_rows, n_cols )
  (member function of Mat)
.resize( n_rows, n_cols, n_slices )
  (member function of Cube)



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 )

.quiet_save( name )
.quiet_save( name, file_type )

.quiet_save( stream )
.quiet_save( stream, file_type )

.quiet_load( name )
.quiet_load( name, file_type )

.quiet_load( stream )
.quiet_load( stream, file_type )
  • Member functions of Mat, Col, Row and Cube

  • Store/retrieve data in files or streams

  • The default file_type for .save() and .quiet_save() is arma_binary (see below)

  • The default file_type for .load() and .quiet_load() is auto_detect (see below)

  • On success, save(), load(), quiet_save(), and quite_load() will return a bool set to true

  • save() and quiet_save() will return a bool set to false if the saving process fails

  • load() and quiet_load() will return a bool set to false if the loading process fails; additionally, the object will be reset so it has no elements

  • load() and save() will print warning messages if any problems are encountered

  • quiet_load() and quiet_save() do not print any error messages

  • file_type can be one of the following:

      auto_detect
      Used by load() and quiet_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() and .quiet_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)

      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);
      
      mat B;
      // automatically detect format type
      B.load("A1.mat");
      
      mat C;
      // force loading in the arma_ascii format
      C.load("A2.mat", arma_ascii);
      
      
      // example of saving/loading using a stream
      std::stringstream s;
      A.save(s);
      
      mat D;
      D.load(s);
      
      
      // example of testing for success
      mat E;
      bool status = E.load("A2.mat");
      
      if(status == true)
        {
        cout << "loaded okay" << endl;
        }
      else
        {
        cout << "problem with loading" << endl;
        }
      

  • See also:



saving/loading fields

.save( name,
file_type = arma_binary )
.save( stream,
file_type = arma_binary )

.load( name,
file_type = auto_detect )
.load( stream,
file_type = auto_detect )

.quiet_save( name,
file_type = arma_binary )
.quiet_save( stream,
file_type = arma_binary )

.quiet_load( name,
file_type = auto_detect )
.quiet_load( stream,
file_type = auto_detect )
  • Member functions of field

  • Store/retrieve fields in files or stream

  • On success, save(), load(), quiet_save(), and quite_load() will return a bool set to true

  • save() and quiet_save() will return a bool set to false if the saving process fails

  • load() and quiet_load() will return a bool set to false if the loading process fails; additionally, the field will be reset so it has no elements

  • load() and save() will print warning messages if any problems are encountered

  • quiet_load() and quiet_save() do not print any error messages

  • 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() and quiet_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:



.set_imag( X )
.set_real( X )
  • Member functions of Mat, Col, Row and Cube

  • 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: if you want 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:



.set_size( n_elem )
  (member function of Col, Row, and field)
.set_size( n_rows, n_cols )
  (member function of Mat, SpMat and field)
.set_size( n_rows, n_cols, n_slices )
  (member function of Cube)

  • Changes the size of an object

  • If the requested number of elements is equal to the old number of elements, existing memory is reused (not applicable to SpMat)

  • If the requested number of elements is not equal to the old number of elements, old memory is freed and new memory is allocated; the memory is uninitialised; if you need to initialise the memory, use .zeros() instead

  • If you need to explicitly preserve data while changing the size, use .reshape() or .resize() instead; caveat: .reshape() and .resize() are considerably slower than .set_size()

  • Examples:
      mat A;
      A.set_size(5,10);
      
      vec q;
      q.set_size(100);
      

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



STL-style container functions
  • Member functions that mimic the containers in the C++ Standard Template Library:

    .clear()  
    causes an object to have no elements
    .empty()  
    returns true if the object has no elements; returns false if the object has one or more elements
    .size()  
    returns the total number of elements

  • Examples:
      mat A = randu<mat>(5,5);
      cout << A.size() << endl;
      
      A.clear();
      cout << A.empty() << endl;
      

  • See also:



submatrix views
  • A collection of member functions of Mat, Col and Row classes that provide read/write access to submatrix views

  • For a matrix or vector X, the subviews are accessed as:

    • contiguous views:

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

        Xfirst_row, first_col, size(n_rows, n_cols) )
        Xfirst_row, first_col, size(Y) )    (Y is a mat)

        X( span::all, col_number )
        X( span(first_row, last_row), col_number )

        X( row_number, span::all )
        X( row_number, span(first_col, last_col) )

        X.unsafe_col( col_number )

        V( span(first_index, last_index) )       (for vectors only)
        V.subvec( first_index, last_index )     (for vectors only)

    • non-contiguous views:

        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::all, to indicate an entire range, can be replaced by span(), where no number is specified

  • 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 be a vector of type uvec (eg., generated by find()). 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're doing. The function creates a seemingly independent Col vector object (eg. vec), but the vector actually uses memory from the existing matrix object. As such, the created Col vector is currently not alias safe and does not take into account that the parent matrix object could be deleted. If deleted memory is accessed through the created Col vector, it will cause memory corruption and/or a crash.

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

  • See also:



subcube views and slices
  • A collection of member functions of the Cube class that provide subcube views

  • For a cube Q, the subviews are accessed as:

    • contiguous views:

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

        Qfirst_row, first_col, first_slice, size(n_rows, n_cols, n_slices) )
        Qfirst_row, first_col, first_slice, size(R) )      (R is a cube)

        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:

        Q.elem( vector_of_indices )
        Q( vector_of_indices )

  • 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 be a vector of type uvec (eg., generated by find()). 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);
      
      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;
      

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

      Ffirst_row, first_col, size(G) )    (G is a 2D field)
      Ffirst_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) )

      Ffirst_row, first_col, first_slice, size(G) )    (G is a 3D field)
      Ffirst_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:



.swap( X )
  • Member function of Mat, Col, Row and Cube

  • Swap contents with object X

  • Examples:
      mat A = zeros<mat>(4,5);
      mat B =  ones<mat>(6,7);
      
      A.swap(B);
      

  • See also:



.swap_rows( row1, row2 )
.swap_cols( col1, col2 )
  • Member functions of Mat, Col, Row and SpMat

  • Swap the contents of specified rows or columns

  • Examples:
      mat X = randu<mat>(5,5);
      X.swap_rows(0,4);
      

  • See also:



.t()
.st()
  • Member functions of any matrix or vector expression

  • .t() provides a transposed copy of the object; if a given object has complex elements, a Hermitian transpose is done (ie. the conjugate of the elements is taken during the transpose operation)

  • .st() provides a transposed copy of the object, without taking the conjugate of the elements (complex matrices)

  • For non-complex objects, the .t() and .st() functions are equivalent

  • Examples:
      mat A = randu<mat>(4,5);
      mat B = A.t();
      

  • See also:



.transform( functor )
.transform( lambda_function )   (C++11 only)
  • Member functions of Mat, Col, Row and Cube

  • Transform each element using a functor or lambda function

  • For matrices, transformation is done column-by-column (ie. column 0 is transformed, then column 1, ...)

  • For cubes, transformation is done slice-by-slice; each slice is transformed column-by-column

  • Examples:
      // C++11 only example
      
      mat A = ones<mat>(4,5);
      
      // add 123 to every element
      A.transform( [](double val) { return (val + 123.0); } );
      

  • 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)
  • Set the elements of an object to zero, optionally first resizing to specified dimensions

  • Examples:
      mat A = randu<mat>(5,10);
      A.zeros();      // sets all elements to zero
      A.zeros(10,20); // sets the size to 10 rows and 20 columns
                      // followed by setting all elements to zero
      

  • See also:





Generated Vectors/Matrices



eye( n_rows, n_cols )
  • 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)

  • Examples:
      mat A = eye<mat>(5,5);
      mat B = 123.0 * eye<mat>(5,5);
      

  • See also:



linspace( start, end )
linspace( start, end, N )
  • Generate a vector with N elements; the values of the elements linearly increase from start to (and including) end

  • By default N = 100

  • Usage:
    • vector_type v = linspace<vector_type>(start, end, N)
    • matrix_type X = linspace<matrix_type>(start, end, N)

  • If a matrix_type is specified, the resultant matrix will have one column

  • Examples:
      vec v = linspace<vec>(10, 20, 5);
      mat X = linspace<mat>(10, 20, 5);
      

  • See also:



ones( n_elem )
ones( n_rows, n_cols )
ones( n_rows, n_cols, n_slices )
  • 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)
    • cube_type Q = ones<cube_type>(n_rows, n_cols, n_slices)

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

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

  • To change the RNG seed, use arma_rng::set_seed(value) or arma_rng::set_seed_random() functions

  • Caveat: if you want 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 )

randn( n_elem )
randn( n_rows, n_cols )
randn( n_rows, n_cols, n_slices )
  • 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)
    • cube_type Q = randu<cube_type>(n_rows, n_cols, n_slices)

  • To change the RNG seed, use arma_rng::set_seed(value) or arma_rng::set_seed_random() functions

  • Caveat: if you want 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:



repmat( A, num_copies_per_row, num_copies_per_col )
  • Generate a matrix by replicating matrix A in a block-like fashion

  • The generated matrix has the following size:
      rows = num_copies_per_row * A.n_rows
      cols = num_copies_per_col * A.n_cols

  • Examples:
      mat A = randu<mat>(2, 3);
      
      mat B = repmat(A, 4, 5);
      
  • See also:



speye( n_rows, n_cols )
  • Generate a sparse 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:
    • sparse_matrix_type X = speye<sparse_matrix_type>(n_rows, n_cols)

  • Examples:
      sp_mat A = speye<sp_mat>(5,5);
      

  • See also:



spones( A )
  • Generate a sparse matrix with the same structure as sparse matrix A, but with the non-zero elements set to one

  • Examples:
      sp_mat A = sprandu<sp_mat>(100, 200, 0.1);
      
      sp_mat B = spones(A);
      
  • See also:



sprandu( n_rows, n_cols, density )
sprandn( n_rows, n_cols, density )
  • Generate a sparse matrix with the non-zero elements set to random values

  • The density argument specifies the percentage of non-zero elements; it must be in the [0,1] interval

  • sprandu() uses a uniform distribution in the [0,1] interval

  • sprandn() uses a normal/Gaussian distribution with zero mean and unit variance

  • Usage:
    • sparse_matrix_type X = sprandu<sparse_matrix_type>(n_rows, n_cols, density)

  • To change the RNG seed, use arma_rng::set_seed(value) or arma_rng::set_seed_random() functions

  • Examples:
      sp_mat A = sprandu<sp_mat>(100, 200, 0.1);
      
  • See also:



toeplitz( A )
toeplitz( A, B )
circ_toeplitz( A )

zeros( n_elem )
zeros( n_rows, n_cols )
zeros( n_rows, n_cols, n_slices )
  • 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)
    • cube_type X = zeros<cube_type>(n_rows, n_cols, n_slices)

  • 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 Individually Applied to Each Element of a Matrix/Cube



abs( X )
  • Obtain the magnitude of each element

  • Usage for non-complex matrices and cubes:
    • matrix_type Y = abs(X)
    • cube_type Y = abs(X)
    • X and Y must have the same matrix_type / cube_type

  • Usage for complex matrices and cubes:
    • non_complex_matrix_type Y = abs(X)
    • non_complex_cube_type Y = abs(X)
    • X must be a have complex matrix / cube type, eg., cx_mat or cx_cube
    • The type of Y must be related to the type of X, eg., if X has the type cx_mat, then the type of Y must be mat

  • Examples:
      mat A = randu<mat>(5,5);
      mat B = abs(A); 
      
      cx_mat X = randu<cx_mat>(5,5);
      mat    Y = abs(X);
      
  • 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:



conj( X )
  • Obtain the complex conjugate of each element in a complex matrix or cube

  • Examples:
      cx_mat X = randu<cx_mat>(5,5);
      cx_mat Y = conj(X);
      

  • See also:



conv_to< type >::from( X )
  • Convert from one matrix type to another (eg. mat to imat), or one cube type to another (eg. cube to icube)

  • Conversion between std::vector and Armadillo matrices/vectors is also possible

  • Conversion of a mat object into colvec, rowvec or std::vector is possible if the object can be interpreted as a vector

  • Examples:
      mat  A = randu<mat>(5,5);
      fmat B = conv_to<fmat>::from(A);
      
      typedef std::vector<double> stdvec;
      
      stdvec x(3);
      x[0] = 0.0; x[1] = 1.0;  x[2] = 2.0;
      
      colvec y = conv_to< colvec >::from(x);
      stdvec z = conv_to< stdvec >::from(y); 
      

  • See also:



eps( X )


imag( X )
real( X )
  • Extract the imaginary/real part of a complex matrix or cube

  • Examples:
      cx_mat C = randu<cx_mat>(5,5);
      
      mat    A = imag(C);
      mat    B = real(C);
      

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



miscellaneous element-wise functions:
    exp, exp2, exp10, trunc_exp
    log, log2, log10, trunc_log
    pow, sqrt, square
    floor, ceil, round
    sign
  • Apply a function to each element

  • Usage:
    • matrix_type B = fn(A)
    • cube_type B = fn(A)
    • A and B must have the same matrix_type/cube_type
    • fn(A) is one of:
        exp(A)    base-e exponential: ex
        exp2(A)    base-2 exponential: 2x
        exp10(A)    base-10 exponential: 10x
        trunc_exp(A)   base-e exponential, truncated to avoid infinity
        (only for elements with type float or double)
        log(A)    natural log: loge x
        log2(A)    base-2 log: log2 x
        log10(A)    base-10 log: log10 x
        trunc_log(A)   natural log, truncated to avoid ±infinity
        (only for elements with type float or double)
        pow(A, p)    raise to the power of p: xp
        sqrt(A)    square root: x½
        square(A)    square: x2
        floor(A)   largest integral value that is not greater than the input value
        ceil(A)   smallest integral value that is not less than the input value
        round(A)   round to nearest integer, away from zero
        sign(A)   signum function; for each element a in A, the corresponding element b in B is:
        −1 if a < 0
        0 if a = 0
        +1 if a > 0
        if a is complex and non-zero, then b = a / abs(a)

  • Examples:
      mat A = randu<mat>(5,5);
      mat B = exp(A);
      

  • See also:



trigonometric element-wise functions (cos, sin, tan, ...)
  • Apply a trigonometric function to each element

  • Usage:
    • matrix_type Y = trig_fn(X)
    • cube_type Y = trig_fn(X)
    • X and Y must have the same matrix_type/cube_type
    • trig_fn is one of:
      • cos family: cos, acos, cosh, acosh
      • sin family: sin, asin, sinh, asinh
      • tan family: tan, atan, tanh, atanh

  • Examples:
      mat X = randu<mat>(5,5);
      mat Y = cos(X);
      





Scalar Valued Functions of Vectors/Matrices/Cubes



accu( X )
  • Accumulate (sum) all elements of a matrix or cube

  • Examples:
      mat A = randu<mat>(5,5);
      double x = accu(A);
      
      mat B = randu<mat>(5,5);
      double y = accu(A % B);
      
      // operator % performs element-wise multiplication,
      // hence accu(A % B) is a "multiply-and-accumulate" operation
      

  • See also:



as_scalar( expression )
  • Evaluate an expression that results in a 1x1 matrix, followed by converting the 1x1 matrix to a pure scalar

  • If a binary or trinary expression is given (ie. 2 or 3 terms), the function will try to exploit the fact that the result is a 1x1 matrix by using optimised expression evaluations

  • Examples:
      rowvec r = randu<rowvec>(5);
      colvec q = randu<colvec>(5);
      mat    X = randu<mat>(5,5);
      
      // examples of some expressions
      // for which optimised implementations exist
      
      double a = as_scalar(r*q);
      double b = as_scalar(r*X*q);
      double c = as_scalar(r*diagmat(X)*q);
      double d = as_scalar(r*inv(diagmat(X))*q);
      

  • See also:



cond( A )

det( A )
det( A, method )
  • Determinant of square matrix A

  • If A is not square, a std::logic_error exception is thrown

  • The method argument is optional. For matrix sizes ≤ 4x4, a fast algorithm is used. In rare instances, the fast algorithm might be less precise than the standard algorithm. To force the use of the standard algorithm, set the method argument to "std". For matrix sizes greater than 4x4, the standard algorithm is always used

  • Caveat: for large matrices you may want to use log_det() instead

  • Examples:
      mat    A = randu<mat>(5,5);
      double x = det(A);
      

  • See also:



dot( A, B )
cdot( A, B )
norm_dot( A, B )
  • dot(A,B): dot product of A and B, under the assumption that A and B are vectors with the same number of elements

  • cdot(A,B): as per dot(A,B), but the complex conjugate of A is used

  • norm_dot(A,B): equivalent to dot(A,B) / (∥A∥•∥B∥)

  • Examples:
      vec a = randu<vec>(10);
      vec b = randu<vec>(10);
      
      double x = dot(a,b);
      

  • 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

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



log_det( val, sign, A )
  • Log determinant of square matrix A, such that the determinant is equal to exp(val)*sign

  • If A is not square, a std::logic_error exception is thrown

  • Examples:
      mat A = randu<mat>(5,5);
      
      double val;
      double sign;
      
      log_det(val, sign, A);
      

  • See also:



norm( X )
norm( X, p )
  • Compute the p-norm of X, where X can be a vector or a matrix

  • For vectors, p is an integer ≥1, or one of: "-inf", "inf", "fro"

  • For matrices, p is one of: 1, 2, "inf", "fro"; the calculated norm is the induced norm (not entrywise norm)

  • "-inf" is the minimum norm, "inf" is the maximum norm, while "fro" is the Frobenius norm

  • To obtain the zero norm or Hamming norm (ie. the number of non-zero elements), use this expression: accu(X != 0)

  • In version 4.100+, the argument p is optional; by default p=2 is used

  • Examples:
      vec    q = randu<vec>(5);
      
      double x = norm(q, 2);
      double y = norm(q, "inf");
      

  • See also:



rank( X )
rank( X, tolerance )
  • Returns the rank of matrix X

  • Any singular values less than default tolerance are treated as zero

  • The tolerance argument is optional; by default the tolerance is max(X.n_rows, X.n_cols)*eps(sigma), where sigma is the largest singular value of X

  • The computation is based on singular value decomposition; if the decomposition fails, a std::runtime_error exception is thrown

  • Examples:
      mat   A = randu<mat>(4,5);
      
      uword r = rank(A);
      

  • See also:



trace( X )
  • Sum of the diagonal elements of square matrix X

  • If X is an expression, the function will try to use optimised expression evaluations to calculate only the diagonal elements

  • A std::logic_error exception is thrown if X does not evaluate to a square matrix

  • Examples:
      mat    A = randu<mat>(5,5);
      
      double x = trace(A);
      

  • See also:





Scalar/Vector Valued Functions of Vectors/Matrices



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:



diagvec( A )
diagvec( A, k )
  • Extract the k-th diagonal from matrix A

  • The argument k is optional; by default the main diagonal is extracted (k=0)

  • For k > 0, the k-th super-diagonal is extracted (top-right corner)

  • For k < 0, the k-th sub-diagonal is extracted (bottom-left corner)

  • The extracted diagonal is interpreted as a column vector

  • Examples:
      mat A = randu<mat>(5,5);
      
      vec d = diagvec(A);
      

  • See also:



min( V )
min( X )
min( X, dim )
min( A, B )

max( V )
max( X )
max( X, dim )
max( A, B )
  • For vector V, return the extremum value

  • For matrix X, return the extremum value for each column (dim=0), or each row (dim=1)

  • The dim argument is optional; by default dim=0 is used

  • For two matrices A and B, return a matrix containing element-wise extremum values

  • Examples:
      colvec v   = randu<colvec>(10,1);
      double val = max(v);
      
      mat    X = randu<mat>(10,10);
      rowvec r = max(X);
      
      // same result as max(X)
      // the 0 explicitly indicates "traverse across rows"
      rowvec s = max(X,0); 
      
      // the 1 explicitly indicates "traverse across columns"
      colvec t = max(X,1);
      
      // find the overall maximum value
      double y = max(max(X));
      
      // element-wise maximum
      mat A = randu<mat>(5,6);
      mat B = randu<mat>(5,6);
      mat C = arma::max(A,B);  // use arma:: prefix to distinguish from std::max()
      

  • See also:



prod( V )
prod( X )
prod( X, dim )
  • For vector V, return the product of all elements

  • For matrix X, 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 q = randu<colvec>(10,1);
      double x = prod(q);
      
      mat    A = randu<mat>(10,10);
      rowvec b = prod(A);
      
      // same result as prod(A)
      // the 0 explicitly indicates
      // "traverse across rows"
      rowvec c = prod(A,0);
      
      // the 1 explicitly indicates
      // "traverse across columns"
      colvec d = prod(A,1);
      
      // find the overall product
      double y = prod(prod(A));
      

  • See also:




sum( V )
sum( X )
sum( X, dim )
  • For vector V, return the sum of all elements

  • For matrix X, return the sum of elements in each column (dim=0), or each row (dim=1)

  • The dim argument is optional; by default dim=0 is used

  • To get a sum of all the elements regardless of the argument type (ie. matrix or vector), use accu() instead

  • Examples:
      colvec q = randu<colvec>(10,1);
      double x = sum(q);
      
      mat    A = randu<mat>(10,10);
      rowvec b = sum(A);
      
      // same result as sum(A)
      // the 0 explicitly indicates "traverse across rows"
      rowvec c = sum(A,0);
      
      // the 1 explicitly indicates "traverse across columns"
      colvec d = sum(A,1);
      
      // find the overall sum
      double y = sum(sum(A));
      
      double z = accu(A);
      

  • See also:



statistics: mean, median, stddev, var
    mean( V )
    mean( X )
    mean( X, dim )

        mean (average value)
    median( V )
    median( X )
    median( X, dim )

        median
    stddev( V )
    stddev( V, norm_type )
    stddev( X )
    stddev( X, norm_type )
    stddev( X, norm_type, dim )

        standard deviation
    var( V )
    var( V, norm_type )
    var( X )
    var( X, norm_type )
    var( X, norm_type, dim )

        variance

  • For vector V, return a particular statistic calculated using all the elements of the vector

  • For matrix X, find a particular statistic for each column (dim=0), or each row (dim=1)

  • The dim argument is optional; by default dim=0 is used

  • The norm_type argument is optional; by default norm_type=0 is used

  • For the var() and stddev() functions:
    • 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

  • Examples:
      mat A    = randu<mat>(5,5);
      mat B    = mean(A);
      mat C    = var(A);
      double m = mean(mean(A));
      
      vec    q = randu<vec>(5);
      double v = var(q);
      

  • See also:





Vector/Matrix/Cube Valued Functions of Vectors/Matrices/Cubes



conv( A, B )
  • Convolution of vectors A and B

  • If A and B are polynomial coefficient vectors, convolving them is equivalent to multiplying the two polynomials

  • The convolution operation is also equivalent to FIR filtering

  • The orientation of the result vector is the same as the orientation of A (ie. column or row vector)

  • Examples:
      vec A = randu<vec>(128) - 0.5;
      vec B = randu<vec>(128) - 0.5;
      
      vec C = conv(A,B);
      

  • 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), also called autocorrelation

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



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:



cross( A, B )


cumsum( V )
cumsum( X )
cumsum( X, dim )
  • For vector V, return a vector of the same orientation, containing the cumulative sum of elements

  • For matrix X, return a matrix containing the cumulative sum of elements in each column (dim=0), or each row (dim=1)

  • The dim argument is optional; by default dim=0 is used

  • Examples:
      mat A = randu<mat>(5,5);
      mat B = cumsum(A);
      mat C = cumsum(A, 1);
      
      vec x = randu<vec>(10);
      vec y = cumsum(x);
      

  • See also:



diagmat( X )
  • Interpret a matrix or vector X as a diagonal matrix

  • If X is a matrix, the matrix must be square; the main diagonal is copied and all other elements in the generated matrix are set to zero

  • If X is a vector, elements of the vector are placed on the main diagonal in the generated matrix and all other elements are set to zero

  • Examples:
      mat A = randu<mat>(5,5);
      mat B = diagmat(A);
      mat C = A*diagmat(A);
      
      rowvec q = randu<rowvec>(5);
      colvec r = randu<colvec>(5);
      mat    X = diagmat(q)*diagmat(r);
      

  • See also:



expmat( X )

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 or umat (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 )
  • Return a column vector containing the indices of elements of X that are finite (ie. not ±Inf and not NaN)

  • The output vector must have the type uvec or umat (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

  • Examples:
      mat A = randu<mat>(5,5);
      
      A(1,1) = datum::inf;
      
      // accumulate only finite elements
      double val = accu( A.elem( find_finite(A) ) );
      

  • See also:



find_nonfinite( X )
  • Return a column vector containing the indices of elements of X that are non-finite (ie. ±Inf or NaN)

  • The output vector must have the type uvec or umat (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

  • Examples:
      mat A = randu<mat>(5,5);
      
      A(1,1) = datum::inf;
      
      // change non-finite elements to zero
      A.elem( find_nonfinite(A) ).zeros();
      

  • See also:



fliplr( X )
flipud( X )
  • fliplr(): generate a copy of matrix X, with the order of the columns reversed

  • flipud(): generate a copy of matrix X, with the order of the rows reversed

  • Examples:
      mat A = randu<mat>(5,5);
      
      mat B = fliplr(A);
      mat C = flipud(A);
      

  • See also:



hist( V )
hist( V, n_bins )
hist( X )
hist( X, n_bins )
hist( X, n_bins, dim )

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 )
  • For vector V, produce an unsigned vector of the same orientation as V (ie. either uvec or urowvec) that contains the counts of the number of values that fall between the elements in the edges vector

  • For matrix X, produce a umat matrix containing either column histogram counts (for dim=0, default), or row histogram counts (for dim=1)

  • The edges vector must contain monotonically increasing values (eg. 0.1, 0.2, 0.3, ...)

  • Examples:
      vec  v = randn<vec>(1000);  // Gaussian distribution
      
      uvec h = histc(v, linspace<vec>(-2,2,11));
      

  • See also:



inplace_strans( X )
inplace_strans( X, method )
  • Simple in-place / in-situ transpose of matrix X, without taking the conjugate of the elements (complex matrices)

  • Use inplace_trans() instead, unless you explicitly need to take the transpose of a complex matrix without taking the conjugate of the elements

  • See the documentation for inplace_trans() for more details



inplace_trans( X )
inplace_trans( X, method )
  • In-place / in-situ transpose of matrix X

  • If X has real elements, a normal transpose is done

  • If X has complex elements, a Hermitian transpose is done (ie. the conjugate of the elements is taken during the transpose operation)

  • The argument method is optional

  • By default, a standard 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 standard 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 standard algorithm by default
      
      inplace_trans(Y, "lowmem");  // use low-memory (and slow) algorithm
      

  • See also:



join_rows( A, B )
join_horiz( A, B )

join_cols( A, B )
join_vert( A, B )

join_slices( C, D )
  • 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

  • join_slices(): for two cubes C and D, join the slices of C with the slices of D; cubes C and D have the same number of rows and columns (ie. all slices must have the same size)

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



kron( A, B )
  • Kronecker tensor product

  • Given matrix A (with n rows and p columns) and matrix B (with m rows and q columns), generate a matrix (with nm rows and pq columns) that denotes the tensor product of A and B

  • Examples:
      mat A = randu<mat>(4,5);
      mat B = randu<mat>(5,4);
      
      mat K = kron(A,B);
      

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



reshape( mat, n_rows, n_cols )
reshape( cube, n_rows, n_cols, n_slices )
  • Generate a matrix or cube sized according to given size specifications, whose elements are taken from the given matrix/cube in a column-wise manner; the elements in the generated object are placed column-wise (ie. the first column is filled up before filling the second column)

  • The layout of the elements in the generated object will be different to the layout in the given object

  • The total number of elements in the generated matrix/cube doesn't have to be the same as the total number of elements in the given matrix/cube

  • If the total number of elements in the given matrix/cube is less than the specified size, the remaining elements in the generated matrix/cube are set to zero

  • If the total number of elements in the given matrix/cube is greater than the specified size, only a subset of elements is taken from the given matrix/cube

  • Caveat: do not use reshape() if you simply want to change the size without preserving data; use .set_size() instead, which is much faster

  • Caveat: if you wish to grow/shrink a matrix while preserving the elements as well as the layout of the elements, use resize() instead

  • Caveat: if you want to create a vector representation of a matrix (ie. concatenate all the columns or rows), use vectorise() instead

  • Examples:
      mat A = randu<mat>(10, 5);
      mat B = reshape(A, 5, 10);
      

  • See also:



resize( mat, n_rows, n_cols )
resize( cube, n_rows, n_cols, n_slices )
  • Generate a matrix or cube sized according to given size specifications, whose elements as well as the layout of the elements are taken from the given matrix/cube

  • Caveat: do not use resize() if you simply want to change the size without preserving data; use .set_size() instead, which is much faster

  • Examples:
      mat A = randu<mat>(4, 5);
      mat B = resize(A, 7, 6);
      

  • See also:



shuffle( V )
shuffle( X )
shuffle( X, dim )
  • For vector V, generate a copy of the vector with the elements shuffled

  • For matrix X, generate a copy of the matrix with the rows (dim=0) or columns (dim=1) shuffled

  • The dim argument is optional; by default dim=0 is used

  • Examples:
      mat A = randu<mat>(4,5);
      mat B = shuffle(A);
      

  • See also:



sort( V )
sort( V, sort_direction )

sort( X )
sort( X, sort_direction )
sort( X, sort_direction, dim )
  • For vector V, return a vector which is a sorted version of the input vector

  • For matrix X, return a matrix with the elements of the input matrix sorted in each column (dim=0), or each row (dim=1)

  • The dim argument is optional; by default dim=0 is used

  • The sort_direction argument is optional; sort_direction is either "ascend" or "descend"; by default "ascend" is used

  • For matrices and vectors with complex numbers, sorting is via absolute values

  • Examples:
      mat A = randu<mat>(10,10);
      mat B = sort(A);
      
  • See also:



sort_index( V )
sort_index( V, sort_direction )

stable_sort_index( V )
stable_sort_index( V, sort_direction )
  • Return a vector which describes the sorted order of the elements of input vector V (ie. it contains the indices of the elements of V)

  • The output vector must have the type uvec or umat (ie. the indices are stored as unsigned integers of type uword)

  • The sort_direction argument is optional; sort_direction is either "ascend" or "descend"; by default "ascend" is used

  • The stable_sort_index() variant preserves the relative order of elements with equivalent values

  • Examples:
      vec  q       = randu<vec>(10);
      uvec indices = sort_index(q);
      

  • See also:



symmatu( A )
symmatu( A, do_conj )

symmatl( A )
symmatl( A, do_conj )
  • symmatu(A): interpret square matrix A as symmetric, reflecting the upper triangle to the lower triangle

  • symmatl(A): interpret square matrix A as symmetric, reflecting the lower triangle to the upper triangle

  • If A is a complex matrix, the reflection uses the complex conjugate of the elements; to disable the complex conjugate, set do_conj to false

  • If A is non-square, a std::logic_error exception is thrown

  • Examples:
      mat A = randu<mat>(5,5);
      
      mat B = symmatu(A);
      mat C = symmatl(A);
      

  • See also:



strans( A )
  • Simple matrix transpose of A, without taking the conjugate of the elements (complex matrices)

  • Use trans() instead, unless you explicitly need to take the transpose of a complex matrix without taking the conjugate of the elements

  • See also:



trans( A )
  • Matrix transpose / Hermitian transpose of A

  • If A has real elements, a normal transpose is done

  • If A has complex elements, a Hermitian transpose is done (ie. the conjugate of the elements is taken during the transpose operation)

  • Examples:
      mat A = randu<mat>(5,10);
      
      mat B = trans(A);
      mat C = A.t();    // equivalent to trans(A), but more compact
      

  • See also:



trimatu( A )
trimatl( A )


unique( A )
  • Return the unique elements of A, sorted in ascending order

  • If A is a vector, the output is also a vector with the same orientation (row or column) as A; if A is a matrix, the output is always a column vector

  • Examples:
      mat X;
      X << 1 << 2 << endr
        << 2 << 3 << endr;
      
      mat Y = unique(X);
      

  • See also:


vectorise( A )
vectorise( A, dim )
  • Generate a column vector (dim=0) or row vector (dim=1) from matrix A

  • The argument dim is optional; by default dim=0 is used

  • For dim=0, the elements are copied from X column-wise; equivalent to concatenating all the columns of A

  • For dim=1, the elements are copied from X row-wise; equivalent to concatenating all the rows of A

  • Concatenating columns is faster than concatenating rows

  • Examples:
      mat A = randu<mat>(4, 5);
      
      vec v = vectorise(A);
      

  • See also:





Decompositions, Factorisations, Inverses and Equation Solvers



R = chol( X )
chol( R, X )

R = chol( X, layout )
chol( R, X, layout )
  • Cholesky decomposition of matrix X

  • Matrix X must be symmetric and positive-definite

  • By default, R is upper triangular, such that R.t()*R = X

  • The argument layout is optional; layout is either "upper" or "lower", which specifies whether R is upper or lower triangular

  • If the decomposition fails, R is reset and:
    • chol(X) throws a std::runtime_error exception
    • chol(R,X) returns a bool set to false

  • Examples:
      mat X = randu<mat>(5,5);
      mat Y = X.t()*X;
      
      mat R1 = chol(Y);
      mat R2 = chol(Y, "lower");
      

  • 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, a std::logic_error exception is thrown

  • The method argument is optional; method is either "dc" or "std", with "dc" indicating divide-and-conquer and "std" indicating standard
    • In version 4.000 and later, the default method is "dc"
    • In version 3.930, the default method is "std"

  • 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:
    • eig_sym(X) throws a std::runtime_error exception
    • eig_sym(eigval, X) and eig_sym(eigval, eigvec, X) return a bool set to false

  • 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 )
  • Eigen decomposition of dense general (non-symmetric/non-hermitian) square matrix X

  • The eigenvalues and corresponding eigenvectors are stored in eigval and eigvec, respectively

  • If X is not square, a std::logic_error exception is thrown

  • If the decomposition fails, the output objects are reset and:
    • eig_gen(X) throws a std::runtime_error exception
    • eig_gen(eigval, X) and eig_gen(eigval, eigvec, X) return a bool set to false

  • Examples:
      mat A = randu<mat>(10,10);
      
      cx_vec eigval;
      cx_mat eigvec;
      
      eig_gen(eigval, eigvec, A);
      

  • 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, a std::logic_error exception is thrown

  • If the decomposition fails, the output objects are reset and:
    • eig_pair(A,B) throws a std::runtime_error exception
    • eig_pair(eigval, A, B) and eig_pair(eigval, eigvec, A, B) return a bool set to false

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



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 either "lm" or "sm":
    • "lm":
    •  obtain eigenvalues with largest magnitude (default operation)
    • "sm":
    •  obtain eigenvalues with smallest magnitude

  • 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, a std::logic_error exception is thrown

  • If the decomposition fails, the output objects are reset and:
    • eigs_sym(X,k) throws a std::runtime_error exception
    • eigs_sym(eigval,X,k) and eigs_sym(eigval,eigvec,X,k) return a bool set to false

  • There is currently no check whether X is symmetric

  • Examples:
      // generate sparse matrix
      sp_mat A = sprandu<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, a std::logic_error exception is thrown

  • If the decomposition fails, the output objects are reset and:
    • eigs_gen(X,k) throws a std::runtime_error exception
    • eigs_gen(eigval,X,k) and eigs_gen(eigval,eigvec,X,k) return a bool set to false

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



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 )
  • fft(): fast Fourier transform of a vector or matrix (real or complex)

  • ifft(): inverse fast Fourier transform of a vector or matrix (complex only)

  • If given a matrix, the transform is done on each column vector of the matrix

  • The optional n argument specifies the transform length:
    • if n is larger than the length of the input vector, a zero-padded version of the vector is used
    • if n is smaller than the length of the input vector, only the first n elements of the vector are used

  • If n is not specified, the transform length is the same as the length of the input vector

  • Caveat: the transform is fastest when the transform length is a power of 2, eg. 64, 128, 256, 512, 1024, ...

  • The implementation of the transform in this version is preliminary; it is not yet fully optimised

  • Examples:
         vec X = randu<vec>(100);
      cx_vec Y = fft(X, 128);
      

  • 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 )
  • fft2(): 2D fast Fourier transform of a matrix (real or complex)

  • ifft2(): 2D inverse fast Fourier transform of a matrix (complex only)

  • The optional arguments n_rows and n_cols specify the size of the transform; a truncated and/or zero-padded version of the input matrix is used

  • Caveat: the transform is fastest when both n_rows and n_cols are a power of 2, eg. 64, 128, 256, 512, 1024, ...

  • The implementation of the transform in this version is preliminary; it is not yet fully optimised

  • Examples:
         mat A = randu<mat>(100,100);
      cx_mat B = fft2(A);
      cx_mat C = fft2(A, 128, 128);
      

  • See also:



B = inv( A )
B = inv( A, method )

inv( B, A )
inv( B, A, method )
  • Inverse of square matrix A

  • The method argument is optional. For matrix sizes ≤ 4x4, a fast algorithm is used. In rare instances, the fast algorithm might be less precise than the standard algorithm. To force the use of the standard algorithm, set the method argument to "std". For matrix sizes greater than 4x4, the standard algorithm is always used

  • If A is not square, a std::logic_error exception is thrown

  • If A appears to be singular, B is reset and:
    • inv(A) throws a std::runtime_error exception
    • inv(B,A) returns a bool set to false

  • Caveat: if matrix A is know to be symmetric positive definite, it's faster to use inv_sympd() instead

  • Caveat: if matrix A is know to be diagonal, use inv( diagmat(A) )

  • Caveat: if you want to solve a system of linear equations, such as Z = inv(X)*Y, it is faster and more accurate to use solve() instead

  • Examples:
      mat A = randu<mat>(5,5);
      
      mat B = inv(A);
      

  • See also:



B = inv_sympd( A )
inv_sympd( B, A )


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, the output objects are reset and lu() returns a bool set to false

  • 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 = pinv( A)
B = pinv( A, tolerance )
B = pinv( A, tolerance, method )

pinv( B, A )
pinv( B, A, tolerance )
pinv( B, A, tolerance, method )
  • Moore-Penrose pseudo-inverse of matrix A

  • The computation is based on singular value decomposition; if the decomposition fails, B is reset and:
    • pinv(A) throws a std::runtime_error exception
    • pinv(B,A) returns a bool set to false

  • The tolerance argument is optional

  • For matrix A with m rows and n columns, the default tolerance is max(m,n)*norm(A)*datum::eps, where datum::eps denotes the difference between 1 and the least value greater than 1 that is representable

  • Any singular values less than tolerance are treated as zero

  • The method argument is optional; method is either "dc" or "std", with "dc" indicating divide-and-conquer and "std" indicating standard
    • In version 4.000 and later, the default method is "dc"
    • In version 3.930, the default method is "std"

  • The divide-and-conquer method provides slightly different results than the standard method, but is considerably faster for large matrices

  • Examples:
      mat A = randu<mat>(4,5);
      
      mat B = pinv(A);        // use default tolerance
      
      mat C = pinv(A, 0.01);  // set tolerance to 0.01
      

  • 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, the output objects are reset and:
    • princomp(X) throws a std::runtime_error exception
    • remaining forms of princomp() return a bool set to false

  • Examples:
      mat A = randu<mat>(5,4);
      
      mat coeff;
      mat score;
      vec latent;
      vec tsquared;
      
      princomp(coeff, score, latent, tsquared, A);
      

  • See also:



qr( Q, R, X )


qr_econ( Q, R, X )


X = solve( A, B )
X = solve( A, B, method )

solve( X, A, B )
solve( X, A, B, method )
  • Solve a system of linear equations, A*X = B, where X is unknown; similar functionality to the \ operator in Matlab/Octave, ie. X = A \ B

  • If A is square, solve() is faster and more accurate than using X = inv(A)*B

  • If A is non-square, solve() will try to provide approximate solutions to under-determined as well as over-determined systems

  • B can be a vector or a matrix

  • The number of rows in A and B must be the same

  • The method argument is optional. For matrix sizes ≤ 4x4, a fast algorithm is used. In rare instances, the fast algorithm might be less precise than the standard algorithm. To force the use of the standard algorithm, set the method argument to "std". For matrix sizes greater than 4x4, the standard algorithm is always used

  • If A is known to be a triangular matrix, the solution can be computed faster by explicitly marking A as triangular through trimatu() or trimatl()

  • If no solution is found, X is reset and:
    • solve(A,B) throws a std::runtime_error exception
    • solve(X,A,B) returns a bool set to false

  • Examples:
      mat A = randu<mat>(5,5);
      vec b = randu<vec>(5);
      mat B = randu<mat>(5,5);
      
      vec x = solve(A, b);
      mat X = solve(A, B);
      
      vec x2;
      solve(x2, A, b);
      

  • See also:



vec s = svd( mat X )
vec s = svd( cx_mat X )

svd( vec s, mat X )
svd( vec s, cx_mat 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 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", with "dc" indicating divide-and-conquer and "std" indicating standard
    • In version 4.000 and later, the default method is "dc"
    • In version 3.930, the default method is "std"

  • 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:
    • svd(X) throws a std::runtime_error exception
    • svd(s,X) and svd(U,s,V,X) return a bool set to false

  • 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, side )
svd_econ( mat U, vec s, mat V, mat X, side, 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, side )
svd_econ( cx_mat U, vec s, cx_mat V, cx_mat X, side, method )
  • Economical singular value decomposition of X

  • The singular values are in descending order

  • The side argument is optional; side 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", with "dc" indicating divide-and-conquer and "std" indicating standard
    • In version 4.000 and later, the default method is "dc"
    • In version 3.930, the default method is "std"

  • 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 a bool set to false is returned

  • 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, X is reset and:
    • syl(A,B,C) throws a std::runtime_error exception
    • syl(X,A,B,C) returns a bool set to false

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





Statistical Modelling



gmm_diag
  • Class for modelling data as a Gaussian Mixture Model (GMM), under the assumption of diagonal covariance matrices

  • Can also be used for 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 and N(x|mg, Cg) represents a Gaussian (normal) distribution; for each Gaussian g, the parameter hg is the heft (weight), with hg ≥ 0 and ∑hg = 1, the parameter mg is the mean (centroid) vector with dimensionality n_dims, and the parameter 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(meansdcovshefts)  
      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

    • to run the k-means and EM algorithms in multi-threaded mode, enable OpenMP in your compiler (eg. -fopenmp in GCC)

  • Examples:
      // create synthetic data with 2 Gaussians
      
      uword N = 10000;
      uword d = 5;
      
      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; }
        }
      
      
      gmm_diag model;
      
      model.learn(data, 2, maha_dist, random_subset, 10, 5, 1e-10, true);
      
      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:



running_stat<type>
  • Class for keeping the running statistics of a continuously sampled one dimensional process/signal

  • Useful if the storage of individual samples (scalars) is not required, or the number of samples is not known beforehand

  • type is one of: float, double, cx_float, cx_double

  • For an instance of running_stat named as X, the member functions are:

      X(scalar)  
      update the statistics so far using the given scalar
      X.min()  
      get the minimum value so far
      X.max()  
      get the maximum value so far
      X.mean()  
      get the mean or average value so far
      X.var()  and  X.var(norm_type)  
      get the variance so far
      X.stddev()  and  X.stddev(norm_type)  
      get the standard deviation so far
      X.reset()  
      reset all statistics and set the number of samples to zero
      X.count()  
      get the number of samples so far

  • The norm_type argument is optional; by default norm_type=0 is used

  • For the .var() and .stddev() functions, the default norm_type=0 performs normalisation using N-1 (where N is the number of samples so far), providing the best unbiased estimator; using norm_type=1 causes normalisation to be done using N, which provides the second moment around the mean

  • The return type of .count() depends on the underlying form of type: it is either float or double

  • Examples:
      running_stat<double> stats;
      
      for(uword i=0; i<10000; ++i)
        {
        double sample = randn();
        stats(sample);
        }
      
      cout << "mean = " << stats.mean() << endl;
      cout << "var  = " << stats.var()  << endl;
      cout << "min  = " << stats.min()  << endl;
      cout << "max  = " << stats.max()  << endl;
      

  • See also:



running_stat_vec<vec_type>
running_stat_vec<vec_type>(calc_cov)
  • Class for keeping the running statistics of a continuously sampled multi-dimensional process/signal

  • Useful if the storage of individual samples (vectors) is not required, or if the number of samples is not known beforehand

  • This class is similar to running_stat, with the difference that vectors are processed instead of scalars

  • vec_type is the vector type of the samples; for example: vec, cx_vec, rowvec, ...

  • For an instance of running_stat_vec named as X, the member functions are:

      X(vector)  
      update the statistics so far using the given vector
      X.min()  
      get the vector of minimum values so far
      X.max()  
      get the vector of maximum values so far
      X.mean()  
      get the mean vector so far
      X.var()  and  X.var(norm_type)  
      get the vector of variances so far
      X.stddev()  and  X.stddev(norm_type)  
      get the vector of standard deviations so far
      X.cov()  and  X.cov(norm_type)  
      get the covariance matrix so far; valid if calc_cov=true during construction of running_stat_vec
      X.reset()  
      reset all statistics and set the number of samples to zero
      X.count()  
      get the number of samples so far

  • The calc_cov argument is optional; by default calc_cov=false, indicating that the covariance matrix will not be calculated; to enable the covariance matrix, use calc_cov=true during construction; for example: running_stat_vec<vec> X(true);

  • The norm_type argument is optional; by default norm_type=0 is used

  • For the .var() and .stddev() functions, the default norm_type=0 performs normalisation using N-1 (where N is the number of samples so far), providing the best unbiased estimator; using norm_type=1 causes normalisation to be done using N, which provides the second moment around the mean

  • The return type of .count() depends on the underlying form of vec_type: it is either float or double

  • Examples:
      running_stat_vec<vec> stats;
      
      vec sample;
      
      for(uword i=0; i<10000; ++i)
        {
        sample = randu<vec>(5);
        stats(sample);
        }
      
      cout << "mean = " << endl << stats.mean() << endl;
      cout << "var  = " << endl << stats.var()  << endl;
      cout << "max  = " << endl << stats.max()  << endl;
      
      //
      //
      
      running_stat_vec<rowvec> more_stats(true);
      
      for(uword i=0; i<20; ++i)
        {
        sample = randu<rowvec>(3);
        
        sample(1) -= sample(0);
        sample(2) += sample(1);
        
        more_stats(sample);
        }
      
      cout << "covariance matrix = " << endl;
      cout << more_stats.cov() << endl;
      
      rowvec sd = more_stats.stddev();
      
      cout << "correlations = " << endl;
      cout << more_stats.cov() / (sd.t() * sd);
      

  • See also:





Miscellaneous



wall_clock
  • Simple wall clock timer class, for measuring the number of elapsed seconds between two intervals

  • Examples:
      wall_clock timer;
      
      mat A = randu<mat>(4,4);
      mat B = randu<mat>(4,4);
      mat C;
      
      timer.tic();
      
      for(uword i=0; i<100000; ++i)
        {
        C = A + B + A + B;
        }
      
      double n_secs = timer.toc();
      cout << "took " << n_secs << " seconds" << 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, Armadillo prints warnings and messages associated with std::logic_error, std::runtime_error and std::bad_alloc exceptions to the std::cout stream

  • 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

  • The printing of all errors and warnings can be disabled by defining ARMA_DONT_PRINT_ERRORS before including the armadillo header

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



pre-defined constants (pi, inf, speed of light, ...)
    datum::pi   π, the ratio of any circle's circumference to its diameter
    datum::inf   ∞, infinity
    datum::nan   “not a number” (NaN); caveat: NaN is not equal to anything, even itself
         
    datum::e   base of the natural logarithm
    datum::sqrt2   square root of 2
    datum::eps   the difference between 1 and the least value greater than 1 that is representable (type and machine dependent)
         
    datum::log_min   log of minimum non-zero value (type and machine dependent)
    datum::log_max   log of maximum value (type and machine dependent)
    datum::euler   Euler's constant, aka Euler-Mascheroni constant
         
    datum::gratio   golden ratio
    datum::m_u   atomic mass constant (in kg)
    datum::N_A   Avogadro constant
         
    datum::k   Boltzmann constant (in joules per kelvin)
    datum::k_evk   Boltzmann constant (in eV/K)
    datum::a_0   Bohr radius (in meters)
         
    datum::mu_B   Bohr magneton
    datum::Z_0   characteristic impedance of vacuum (in ohms)
    datum::G_0   conductance quantum (in siemens)
         
    datum::k_e   Coulomb's constant (in meters per farad)
    datum::eps_0   electric constant (in farads per meter)
    datum::m_e   electron mass (in kg)
         
    datum::eV   electron volt (in joules)
    datum::ec   elementary charge (in coulombs)
    datum::F   Faraday constant (in coulombs)
         
    datum::alpha   fine-structure constant
    datum::alpha_inv   inverse fine-structure constant
    datum::K_J   Josephson constant
         
    datum::mu_0   magnetic constant (in henries per meter)
    datum::phi_0   magnetic flux quantum (in webers)
    datum::R   molar gas constant (in joules per mole kelvin)
         
    datum::G   Newtonian constant of gravitation (in newton square meters per kilogram squared)
    datum::h   Planck constant (in joule seconds)
    datum::h_bar   Planck constant over 2 pi, aka reduced Planck constant (in joule seconds)
         
    datum::m_p   proton mass (in kg)
    datum::R_inf   Rydberg constant (in reciprocal meters)
    datum::c_0   speed of light in vacuum (in meters per second)
         
    datum::sigma   Stefan-Boltzmann constant
    datum::R_k   von Klitzing constant (in ohms)
    datum::b   Wien wavelength displacement law constant

  • Caveat: datum::nan is not equal to anything, even itself; if you wish to check whether a given number x is finite, use is_finite(x)

  • The constants are stored in the Datum<type> class, where type is either float or double

  • For convenience, Datum<double> has been typedefed as datum while Datum<float> has been typedefed as fdatum

  • The physical constants were mainly taken from NIST and some from WolframAlpha on 2009-06-23; constants from NIST are in turn sourced from the 2006 CODATA values

  • Examples:
      cout << "2.0 * pi = " << 2.0 * datum::pi << endl;
      
      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;
      
  • See also:



uword, sword
  • uword is a typedef for an unsigned integer with a minimum width of 32 bits; if ARMA_64BIT_WORD is enabled, the minimum width is 64 bits

  • sword is a typedef for a signed integer with a minimum width of 32 bits; if ARMA_64BIT_WORD is enabled, the minimum width is 64 bits

  • ARMA_64BIT_WORD can be enabled via editing include/armadillo_bits/config.hpp

  • See also:



cx_double, cx_float

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.submat(p, r, q, s)   A.submat(first_row, first_col, last_row, last_col)
        or    
        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.subcube(p, r, t, q, s, u)   .subcube(first_row, first_col, first_slice, last_row, last_col, last_slice)
        or    
        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.'   A.st() or strans(A)   simple matrix transpose
    (for complex matrices, the conjugate of each element is not 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; ]   << 1 << 2 << endr
       << 3 << 4 << endr;
      element initialisation, with special element endr indicating end of row
             
    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);    
             
    S = { 'abc'; 'def' }   field<std::string> S(2);
    S(0) = "abc";
    S(1) = "def";
      fields can store arbitrary objects, in a 1D or 2D layout



example program

  • If you save the program below as example.cpp, under Linux you can compile it using:
    g++ example.cpp -o example -O1 -larmadillo
    • #include <iostream>
      #include <armadillo>
      
      using namespace std;
      using namespace arma;
      
      int main(int argc, char** argv)
        {
        mat A = randu<mat>(4,5);
        mat B = randu<mat>(4,5);
        
        cout << A*B.t() << endl;
        
        return 0;
        }
      
  • You may also want to have a look at the example programs that come with the Armadillo archive

  • As Armadillo is a template library, we strongly recommended to have optimisation enabled when compiling programs (eg. when compiling with GCC, use the -O1 or -O2 options)



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_USE_LAPACK   Enable the 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 the 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_ARPACK   Enable the use of ARPACK, or a high-speed replacement for ARPACK. Armadillo requires ARPACK for the eigen decomposition of sparse matrices, ie. eigs_gen() and eigs_sym()
         
    ARMA_DONT_USE_ARPACK   Disable use of ARPACK. Overrides ARMA_USE_ARPACK
         
    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_DONT_USE_WRAPPER   Disable going through the run-time Armadillo wrapper library (libarmadillo.so) when calling LAPACK, BLAS, ARPACK and HDF5 functions. You will need to directly link with LAPACK, BLAS, etc (eg. -llapack -lblas)
         
    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. 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 preallocated 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 and 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 with an even number (ie. evenly divisible by two) are backwards compatible with earlier even 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

    • Experimental versions are denoted by an odd minor version number (ie. not evenly divisible by two), such as 4.199. Experimental versions are generally faster and/or have more functionality, but their APIs have not been finalised yet (though the likelihood of APIs changes is quite low)

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

    • Added in 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

    • Added in 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

    • Added in 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

    • Added in 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

    • Added in 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

    • Added in 4.300:

    • Added in 4.200:
      • faster transpose of sparse matrices
      • more efficient handling of aliasing during matrix multiplication
      • faster inverse of matrices marked as diagonal

    • Added in 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

    • Added in 4.000:

    • Changed in 4.000:

    • Added in 3.930:

    • Added in 3.920:
      • faster .zeros()
      • faster round(), exp2() and log2() when using C++11
      • signum function: sign()
      • move constructors when using C++11
      • 2D fast Fourier transform: fft2()
      • .tube() for easier extraction of vectors and subcubes from cubes
      • specification of a fill type during construction of Mat, Col, Row and Cube classes, eg. mat X(4, 5, fill::zeros)

    • Added in 3.910:
      • faster multiplication of a matrix with a transpose of itself, ie. X*X.t() and X.t()*X
      • vectorise() for reshaping matrices into vectors
      • all() and any() for indicating presence of elements satisfying a relational condition

    • Added in 3.900:
      • 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
      • support for saving & loading of cubes in HDF5 format

    • Added in 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

    • Added in 3.810:

    • Added in 3.800:
      • .imbue() for filling a matrix/cube with values provided by a functor or lambda expression
      • .swap() for swapping contents with another matrix
      • .transform() for transforming a matrix/cube using a functor or lambda expression
      • round() for rounding matrix elements towards nearest integer
      • faster find()

    • Changed in 3.800:
    • Added in 3.6:
    • Added in 3.4:
    • Added in 3.2:
    • Added in 3.0:
    • Changed in 3.0:
      • 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()

    • Added in 2.4:
      • shorter forms of transposes: .t() and .st()
      • .resize() and resize()
      • 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
      • experimental support for C++11 initialiser lists,
        enabled via ARMA_USE_CXX11 in include/armadillo_bits/config.hpp

    • Changed in 2.4:
      • 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

    • Added in 2.2:
    • Added in 2.0:
    • Changed in 2.0:
    • Added in 1.2:
      • .min() & .max() member functions of Mat and Cube
      • floor() and ceil()
      • representation of “not a number”: math::nan()
      • representation of infinity: math::inf()
      • standalone is_finite()
      • .in_range() can 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;
          
      • interpretation of matrices as triangular through trimatu() / trimatl()
      • explicit handling of triangular matrices by solve() and inv()
      • extended syntax for submatrices, including access to elements whose indices are specified in a vector
      • ability to change the stream used for logging of errors and warnings
      • ability to save/load matrices in raw binary format
      • 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) ).



  • Get Armadillo C++ matrix library at SourceForge.net. Fast, secure and Free Open Source software downloads