Reference for Armadillo 0.6.10

to Armadillo home page


(if something needs to be clarified or fixed in this documentation, the developers are very interested in hearing about it)


Matrix Classes and Member Functions
Vector Classes
Other Classes
Generated Vectors/Matrices
Functions Individually Applied to Each Element of a Matrix
Scalar Valued Functions of Vectors/Matrices
Scalar/Vector Valued Functions of Vectors/Matrices
Vector/Matrix Valued Functions of Vectors/Matrices
Decompositions, Inverse and Related Functions
Miscellaneous




Matrix Classes and Member Functions


Mat<type>, mat and cx_mat
  • The root template matrix class is Mat<type>, where type can be one of: char, int, float, double, std::complex<double>, etc.

  • For convenience the following typedefs have been defined:
      s32, u32 =
      		 signed int, unsigned int (32 bits wide)
      cx_float, cx_double =
      		 std::complex<float>, std::complex<double>
      imat =
      		 Mat<s32>
      umat =
      		 Mat<u32>
      fmat =
      		 Mat<float>
      mat =
      		 Mat<double>
      cx_fmat =
      		 Mat<cx_float>
      cx_mat =
      		 Mat<cx_double>

  • Data is stored with column-major ordering (i.e. column by column).

  • Functions which are wrappers for LAPACK or ATLAS functions (generally matrix decompositions) are only valid for the following types: fmat, mat, cx_fmat, cx_mat.

  • In this documentation the mat type is used for convenience. It is possible to use other types instead, e.g. fmat.

  • Constructors:
    • mat()
    • mat(n_rows, n_cols)
    • mat(mat)
    • mat(rowvec)
    • mat(colvec)
    • cx_mat(mat,mat)   (for constructing a complex matrix out of two real matrices)

  • Examples: 
      mat A = rand<mat>(5,5);
double x = A(1,2);
mat B = A + A;
mat C = A * B;
mat D = A % B;
B.zeros();
B.set_size(10,10);
B.zeros(10,10);

cx_mat X(A,B);

  • 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);
    Or: 
      mat A = 123.0 * ones<mat>(5,5);


.diag(k=0)
  • Access the k-th 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). An extracted a diagonal is interpreted as a column vector.

  • Examples: 
      mat    X = rand<mat>(5,5);
colvec a = X.diag();
colvec b = X.diag(1);
colvec c = X.diag(-2);
X.diag() = rand<colvec>(5);


element/object access via (), [] and .at()
  • Provide access to individual elements or objects stored in a container object (i.e., mat, colvec, rowvec, field).

      (n)
      		  
      		 For colvec and rowvec, access the n-th element. For mat and field, access the n-th element/object under the assumption of a flat layout, with column-major ordering of data (i.e. column by column). An exception is thrown if the requested element is out of bounds. The bounds check can be optionally disabled if the ARMA_NO_DEBUG or NDEBUG macro is defined.

      		 
      [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. An exception is thrown if the requested element is out of bounds. The bounds check can be optionally disabled if the ARMA_NO_DEBUG or NDEBUG macro is defined. 

      .at(i,j)
      		As for (i,j), but without a bounds check. Not recommended for use unless your code has been thoroughly debugged.

  • Examples: 
      mat A = rand<mat>(10,10);
A(9,9) = 123.0;
double x = A.at(9,9);
double y = A[99];

colvec p = rand<colvec>(10,1);
p(9) = 123.0;
double z = p[9];


.fill(value)
  • Sets the elements to a specified value. The type of value must match the type of elements used by the container object (e.g. for mat the type is double).

  • Member function of mat, colvec and rowvec classes.

  • Examples: 
      mat A(5,5);
A.fill(123.0);


.n_rows (number of rows)
.n_cols (number of columns)
.n_elem (number of elements)

  • Read-only member variables of mat, colvec, rowvec and field classes.

  • The variables are of type u32 (unsigned integer).

  • Examples: 
      colvec q(5);
cout << "q has " << q.n_cols << " columns" << endl;


operators + - * / % == != <= >= < >
  • Overloaded operators for mat, colvec and rowvec 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
      %
      		Element-wise multiplication of two objects (Schur product)
      ==
      		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".

  • An 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.

  • Caveat: operators involving an equality comparison (i.e., ==, !=, >=, <=) may not work as expected for floating point element types (i.e., float, double) due to the necessarily limited precision of these types. In other words, these operators are not recommended for matrices of type mat or fmat.


  • Examples: 
      mat A = rand<mat>(5,10);
mat B = rand<mat>(5,10);
mat C = rand<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);


.print(header="")
  • Member function of mat, colvec and rowvec.

  • Prints the contents of an object to the cout stream, with an optional header line.

  • It's also possible print objects using the << stream operator.

  • Examples: 
      mat A = rand<mat>(5,5);
mat B = rand<mat>(6,6);

A.print();

// "B =" is the optional header line
B.print("B =");

cout << A << endl;
cout << "B =" << endl << B << endl;


.reset()
  • Member function of field, mat, colvec, rowvec.

  • Causes an object to have no elements.

  • Examples: 
      mat A = rand<mat>(5, 5);
A.reset();


.save(name, file_type = arma_binary)
.load(name, file_type = auto_detect)
  • Store/retrieve data in files

  • Member functions of mat, colvec, rowvec classes

  • load() will reset the object to have no elements if the loading process failed (e.g. wrong filename, unsupported format, etc).

  • The following file formats are supported:

      auto_detect
      		load(): try to automatically detect the matrix format type as one of the formats described below. This is the default operation.

      raw_ascii
      		Numerical data stored in raw ASCII format (no header), with the numbers separated by white space. The number of columns must be the same in each row. load() can read data which was saved in Matlab/Octave using the -ascii option, except for complex numbers. Complex numbers are stored in standard C++ notation (a tuple surrounded by brackets: e.g. (1.23,4.56) indicates 1.24 + 4.56i).

      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.

      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.

      pgm_binary
      		Image data stored in Portable Gray Map (PGM) format. Saving int, float or double matrices is a lossy operation, as each element of the matrix 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.


  • Examples: 
      mat A = rand<mat>(5,5);

// default save format is arma_binary
A.save("A1.mat");
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);


.set_size(n_elem)
(member function of colvec, rowvec, and field)
.set_size(n_rows,n_cols)
(member function of mat and field)

  • Changes the size of an object.

  • If the old number of elements is equal to the requested number of elements, old memory is reused.

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


sub-matrix views
  • A collection of member functions of mat, colvec and rowvec classes that provide sub-matrix views.

      .row( row_number )
      .col( column_number )
      .rows( first_row, last_row )
      .cols( first_column, last_column )
      .submat( first_row, first_column, last_row, last_column )

  • Examples: 
      mat A = zeros<mat>(5,10);
mat B = A.submat(0,1,2,3);
A.submat(0,1,2,3) = rand<mat>(3,3);
A.row(1) = rand<mat>(1,10);


.swap_rows(row1, row2)
.swap_cols(col1, col2)
  • Member function of mat, colvec and rowvec classes.

  • Swap the contents of specified rows or columns.

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


.zeros()
.zeros(n_rows,n_cols)
.zeros(n_elem)
  • Set the elements of an object to zero, optionally first resizing to specified dimensions

  • .zeros() and .zeros(n_rows,n_cols) are member functions of Mat

  • .zeros() and .zeros(n_elem) are member function of Col and Row

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

  • See also: zeros() (stand alone function)



Vector Classes


Col<type>, colvec and 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:
      ivec, icolvec =
      		 Col<s32>
      uvec, ucolvec =
      		 Col<u32>
      fvec, fcolvec =
      		 Col<float>
      vec, colvec =
      		 Col<double>
      cx_fvec, cx_fcolvec =
      		 Col<cx_float>
      cx_vec, cx_colvec =
      		 Col<cx_double>

  • In this documentation the colvec type is used for convenience and to accentuate that it is a column vector. It is possible to use the shorter version, i.e. vec, as well as other types, e.g. fvec, fcolvec.

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

  • Constructors
    • colvec(n_elem=0)
    • colvec(colvec)
    • colvec(mat)

  • An exception is thrown if the given matrix has more than one column.

  • Examples: 
      colvec x(10);
colvec y = zeros<colvec>(10,1);

mat    A = rand<mat>(10,10);
colvec 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: 
      colvec q(5);
q = 123.0;
    Use the following code instead: 
      colvec q(5);
q.fill(123.0);
    Or: 
      colvec q = 123.0 * ones<colvec>(5,1);


Row<type> and 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:
      irowvec =
      		 Row<s32>
      urowvec =
      		 Row<u32>
      frowvec =
      		 Row<float>
      rowvec =
      		 Row<double>
      cx_frowvec =
      		 Row<cx_float>
      cx_rowvec =
      		 Row<cx_double>

  • In this documentation the rowvec type is used for convenience. It is possible to use other types instead, e.g. frowvec.

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

  • Constructors
      rowvec(n_elem=0)
      rowvec(rowvec)
      rowvec(mat)

  • An exception is thrown if the given matrix has more than one row.

  • Examples: 
      rowvec x(10);
rowvec y = zeros<mat>(1,10);

mat A = rand<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);
    Or: 
      rowvec r = 123.0 * ones<rowvec>(1,5);



Other Classes


field<object type>
  • Class for one and two dimensional fields of arbitrary objects

  • Constructors (where object type is another class, e.g. mat, colvec, rowvec, std::string, etc):
      field<object type>(n_elem=0)
      field<object type>(n_rows, n_cols)
      field<object type>(field<object type>)

  • Stored objects can be accessed via the () operator, or via the [] operator.

  • The () operator has a bounds check that can be optionally disabled if the ARMA_NO_DEBUG or NDEBUG macro is defined

  • The [] operator has no bounds check -- this not recommended for use unless your code has been thoroughly debugged

  • The field class has several member functions for accessing sub-fields:
      .row( row_number )
      .col( column_number )
      .rows( first_row, last_row )
      .cols( first_column, last_column )
      .subfield( first_row, first_column, last_row, last_column )

  • Fields with objects of type mat, colvec, rowvec and std::string can be saved or loaded via field's .save() and .load() member functions. The interface is similar to the .save()/.load() functions in the Mat class, with the main difference being that different 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, colvec or rowvec.
    • Only applicable to fields of type mat, colvec or rowvec.

      • ppm_binary

    • Image data stored in Portable Pixmap Map (PPM) format.
    • Only applicable to fields of type mat, colvec or rowvec.
    • .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.

  • 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. The .load() function will only accept text files that have the same number of strings on each line. The strings can have variable lengths.

  • Examples: 
      // create a colvec field with 3 rows and 2 columns
field<colvec> F(3,2);

// access components of the field
F(0,0) = colvec(5);
F(1,1) = rand<colvec>(6);
F(2,0).set_size(7);

// access element 1 of the colvec stored at 2,0
double x = F(2,0)(1);

// copy rows
F.row(0) = F.row(2);

// extract a row of colvecs from F
field<colvec> G = F.row(1);

// print the field to the standard output
G.print("G =");

// save the field to a binary file
G.save("colvec_field");


// create a field of strings
field<std::string> S(3,2);

S(0,0) = "hello";
S(1,0) = "there";

// string fields can be saved as plain text files
S.save("string_field");


running_stat<type>
  • Class for keeping statistics of a continuously sampled process/signal. Useful if the storage of individual samples is not necessary or desired. Also useful if the number of samples is not known beforehand or exceeds available memory.

  • type should be one of: float, double, std::complex<float>, std::complex<double>

  • Member functions:
      .operator()(sample)  
      		 update the statistics so far using the given sample
      .mean()  
      		 get the mean or average value so far
      .var(norm_type=0)  
      		 get the variance so far
      .stddev(norm_type=0)  
      		 get the standard deviation so far
      .min()  
      		 get the minimum value so far
      .max()  
      		 get the maximum value so far

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

  • Examples: 
      running_stat<double> stats;

for(u32 i=0; i<10000; ++i)
  {
  double sample = double(rand())/RAND_MAX;
  stats(sample);
  }

cout << "mean = " << stats.mean() << endl;
cout << "var  = " << stats.var()  << endl;
cout << "min  = " << stats.min()  << endl;
cout << "max  = " << stats.max()  << endl;


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

  • Examples: 
      wall_clock timer;

mat A = rand<mat>(4,4);
mat B = rand<mat>(4,4);
mat C;

timer.tic();
for(u32 i=0; i<100000; ++i)
  C = A + B + A + B;

double n_secs = timer.toc();
cout << "took " << n_secs << " seconds" << endl;



Generated Vectors/Matrices


eye(n_rows, n_cols)
  • Generate the identity matrix (diagonal elements set to one and off-diagonal elements set to zero).

  • Usage:
    • matrix_type X = eye<matrix_type>(n_rows, n_cols)
    • n_rows must be equal to n_cols
    • Two arguments are used to make it explicitly clear that a square matrix is generated

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


linspace(start, end, N, dim=0)
  • Generate a vector with N elements. The values of the elements linearly increase from start upto (and including) end.

  • dim=0 indicates a column vector, while dim=1 indicates a row vector.

  • Examples: 
      double start = 10.0;
double end   = 20.0;
u32    N     = 5;

mat    X     = linspace(start, end, N);
mat    Y     = linspace(start, end, N, 1);

colvec q     = linspace(start, end, N);
rowvec r     = linspace(start, end, N, 1);


ones(n_elem)
ones(n_rows, n_cols)
  • Generate a vector or a matrix 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)

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


rand(n_elem), randn(n_elem)
rand(n_rows,n_cols), randn(n_rows,n_cols)
  • Generate a vector or a matrix with the elements set to random values.

  • rand() 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 = rand<vector_type>(n_elem)
    • matrix_type X = rand<matrix_type>(n_rows,n_cols)

  • Examples: 
      mat A = rand<mat>(5,5);
colvec q = rand<colvec>(5);
rowvec r = rand<rowvec>(5);


zeros(n_elem)
zeros(n_rows,n_cols)
  • Generate a vector or a matrix 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)

  • Examples: 
      mat A = zeros<mat>(5,5);
colvec q = zeros<colvec>(5);
rowvec r = zeros<rowvec>(5);

  • See also: .zeros() (member function of Mat, Col and Row)



Functions Individually Applied to Each Element of a Matrix


abs(mat)
abs(cx_mat)
  • Obtain the magnitude of each element in a matrix

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

  • Usage for complex matrices:
    • non_complex_matrix_type Y = abs(X)
    • X must be a have complex matrix type, e.g., cx_mat or cx_fmat
    • The type of Y must be related to the type of X, e.g., if X has the type cx_mat, then the type of Y must be mat

  • Examples: 
      mat A = rand<mat>(5,5);
mat B = abs(A); 

cx_mat X = rand<cx_mat>(5,5);
mat    Y = abs(X);


misc functions (exp, log, log10, pow, sqrt, square)
  • Apply a function to each element of a matrix.

  • Usage:
    • matrix_type Y = misc_fn(X)
    • X and Y must have the same matrix_type
    • misc_fn(X) is one of:
        exp(X)   base-e exponential of each element
        log(X)   natural log of each element
        log10(X)   base-10 log of each element
        pow(X, p)   raise each element to the power of p
        sqrt(X)   square root of each element
        square(X)   square of each element

  • Examples: 
      mat X = rand<mat>(5,5);
mat Y = exp(X);


trigonometric functions
  • Apply a trigonometric function to each element of a matrix.

  • Usage:
    • matrix_type Y = trig_fn(X)
    • X and Y must have the same matrix_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 = rand<mat>(5,5);
mat Y = cos(X);



Scalar Valued Functions of Vectors/Matrices


accu(mat)
  • Accumulate (sum) all elements

  • Examples: 
      mat A = rand<mat>(5,5);
double x = accu(A);

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


det(mat)
  • Determinant of a square matrix.

  • An exception is thrown if the given matrix is not square.

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


dot(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

  • norm_dot(A,B): normalised version of dot(A,B)

  • Examples: 
      colvec a = rand<colvec>(10);
colvec b = rand<colvec>(10);

double x = dot(a,b);


norm(X, p)
  • Compute the p-norm of X, under the assumption that X is a vector.

  • Examples: 
      colvec q = rand<colvec>(5);
double x = norm(q,2);


trace(mat)
  • Sum of the diagonal elements of a square matrix.

  • An exception is thrown if the given matrix is not square.

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



Scalar/Vector Valued Functions of Vectors/Matrices


min(mat, dim=0), min(rowvec), min(colvec)
max(mat, dim=0), max(rowvec), max(colvec)
  • For a matrix argument, return the minimum/maximum value for each column (dim=0), or each row (dim=1).

  • For a vector argument, return the minimum/maximum value.

  • Examples: 
      colvec q = rand<colvec>(10,1);
double x = max(q);

mat A = rand<mat>(10,10);
rowvec b = max(A);

// same result as max(A)
// the 0 explicitly indicates "along columns"
rowvec c = max(A,0); 

// the 1 explicitly indicates "along rows"
colvec d = max(A,1);

// find the overall maximum value
double y = max(max(A));


sort(mat, sort_type=0, dim=0)
sort(rowvec, sort_type=0), sort(colvec, sort_type=0)
  • For a matrix argument, return a vector with the elements of the input matrix sorted in each column (dim=0), or each row (dim=1)

  • sort_type=0 (default) indicates an ascending sort

  • sort_type=1 indicates a descending sort

  • For a vector argument, return a vector which is a sorted version of the input vector

  • Examples: 
      mat A = rand<mat>(10,10);
mat B = sort(A);


sort_index(colvec, sort_type=0), sort_index(rowvec, sort_type=0)
  • Sort the given vector and return a vector (with elements of type u32) which describes the sorted order (i.e. it contains the indices of the given vector's elements).

  • sort_type=0 (default) indicates an ascending sort

  • sort_type=1 indicates a descending sort

  • Examples: 
      colvec  q       = rand<colvec>(10);
ucolvec indices = sort_index(q);


sum(mat, dim=0)
sum(rowvec), sum(colvec)
  • For a matrix argument, return the sum of elements in each column (dim=0), or each row (dim=1).

  • For a vector argument, return the sum of all elements.

  • Examples: 
      colvec q = rand<colvec>(10,1);
double x = sum(q);

mat A = rand<mat>(10,10);
rowvec b = sum(A);

// same result as sum(A)
// the 0 explicitly indicates "along columns"
rowvec c = sum(A,0);

// 1 explicitly indicates "along rows"
colvec d = sum(A,1);

// find the overall sum
double y = sum(sum(A));


statistics (mean, median, stddev, var)
    mean(mat, dim=0)
    mean(colvec), mean(rowvec)

    		  mean (average value)
    median(mat, dim=0)
    median(colvec), median(rowvec)

    		  median
    stddev(mat, norm_type=0, dim=0)
    stddev(colvec, norm_type=0), stddev(rowvec, norm_type=0)

    		  standard deviation
    var(mat, norm_type=0, dim=0)
    var(colvec, norm_type=0), var(rowvec, norm_type=0)

    		  variance

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

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

  • 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 causes normalisation to be done using N, which provides the second moment around the mean.

  • Examples: 
      mat A    = rand<mat>(5,5);
mat B    = mean(A);
mat C    = var(A);
double m = mean(mean(A));

colvec q = rand<colvec>(5);
double v = var(q);



Vector/Matrix Valued Functions of Vectors/Matrices


conv_to<matrix_type>::from(X)
  • Convert between matrix types (e.g. mat to fmat)

  • Conversion of mat into colvec or rowvec is only possible if the object has one column or one row, respectively.

  • Conversion of a matrix into a scalar is only possible for matrices with a size of 1x1.

  • Examples: 
      mat  A = rand<mat>(1,5);
mat  B = rand<mat>(5,1);

fmat C = conv_to<fmat>::from(A);

double x = conv_to<rowvec>::from(A) * conv_to<colvec>::from(B);
double y = conv_to<double>::from(A * B);


conj(cx_mat)
  • Obtain the complex conjugate of each element in a complex matrix

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


diagmat(mat)
diagmat(rowvec), diagmat(colvec)
  • Interpret a matrix or vector as a diagonal matrix.

  • For mat, given matrix must be square. The main diagonal is copied and all other elements in the generated matrix are set to zero.

  • For colvec and rowvec, 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 = rand<mat>(5,5);
mat B = diagmat(A);
mat C = A*diagmat(A);

rowvec q = rand<rowvec>(5);
colvec r = rand<colvec>(5);
mat X = diagmat(q)*diagmat(r);


htrans(cx_mat)
htrans(cx_colvec), htrans(cx_rowvec)
  • Hermitian transpose

  • This operation is equivalent to taking the transpose and then taking the complex conjugate of each element

  • Examples: 
      cx_mat A = rand<cx_mat>(5,10);
cx_mat B = htrans(A);


imag(cx_mat)
real(cx_mat)
  • Extract the imaginary/real part of a complex matrix.

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


reshape(mat, n_rows, n_cols, dim=0)
  • Return a matrix sized according to supplied n_rows and n_cols, whose elements are taken from the given matrix, either column-wise (dim=0) or row-wise (dim=1).

  • The number of elements in the given matrix must be equal to n_rows * n_cols.

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


trans(mat)
trans(colvec), trans(rowvec)
  • Matrix transpose

  • Examples: 
      mat A = rand<mat>(5,10);
mat B = trans(A);



Decompositions and Related Functions


chol(R, X)
R = chol(X)
  • Cholesky decomposition of X, such that trans(R)*R = X.

  • X must be a symmetric, positive-definite matrix.

  • Examples: 
      mat X = rand<mat>(5,5);
mat Y = trans(X)*X;

mat R = chol(Y);

  • See also: Cholesky decomposition in MathWorld


eig_sym(colvec eigval, mat X)
eig_sym(colvec eigval, cx_mat X)

colvec eigval = eig_sym(mat X)
colvec eigval = eig_sym(cx_mat X)

eig_sym(colvec eigval, mat eigvec, mat X)
eig_sym(colvec eigval, cx_mat eigvec, cx_mat X)
  • Eigen decomposition of symmetric/hermitian matrix X.

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

  • The eigenvalues are not guaranteed to be ordered.

  • An exception is thrown if X is not square.

  • There is currently no check for symmetry of X.

  • Examples: 
      mat A = rand<mat>(10,10);
mat B = trans(A)*A;  // generate a symmetric matrix

colvec eigval;
mat    eigvec;

eig_sym(eigval, eigvec, B);

  • See also: eigen decomposition in MathWorld


eig_gen(cx_colvec eigval, cx_mat eigvec, mat X, side='r')
eig_gen(cx_colvec eigval, cx_mat eigvec, cx_mat X, side='r')

eig_gen(cx_colvec eigval, mat l_eigvec, mat r_eigvec, mat X)
eig_gen(cx_colvec eigval, cx_mat l_eigvec, cx_mat r_eigvec, cx_mat X)
  • Eigen decomposition of general (non-symmetric/non-hermitian) square matrix X.

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

  • For the first two forms, side='r' (default) specifies that right eigenvectors are computed, while side='l' specifies that left eigenvectors are computed.

  • For the last two forms, both left and right eigenvectors are computed.

  • The eigenvalues are not guaranteed to be ordered.

  • An exception is thrown if X is not square.

  • Examples: 
      mat A = rand<mat>(10,10);

cx_colvec eigval;
cx_mat    eigvec;

eig_gen(eigval, eigvec, A);

  • See also: eigen decomposition in MathWorld


inv(mat)
  • Inverse of a square matrix.

  • An exception is thrown if the given matrix is not square or is rank deficient.

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

// Diagonal elements in C are set to the reciprocal
// of the corresponding elements in A. Off-diagonal
// elements of C are set to zero.
mat C = inv(diagmat(A));

  • See also:


lu(mat L, mat U, mat P, mat X)
  • Lower-upper decomposition (with partial pivoting) of matrix X, such that P*X = L*U and X = trans(P)*L*U.

  • P is a permutation matrix, L is a lower-triangular matrix, and U is an upper-triangular matrix.

  • Examples: 
      mat A = rand<mat>(10,10);

mat L;
mat U;
mat P;

lu(L, U, P, A);

mat B = trans(P)*L*U;

  • See also: LU decomposition in Wikipedia


qr(Q,R,X)
  • Decomposition of matrix X into an orthogonal (Q) and a right triangular matrix (R), such that Q*R = X.

  • Examples: 
      mat X = rand<mat>(5,5);
mat Q, R;

qr(Q,R,X);

  • See also: QR decomposition in MathWorld


solve(colvec x, mat A, colvec b)
solve(mat X, mat A, mat B),

colvec x = solve(mat A, colvec b)
mat X = solve(mat A, mat B)
  • Solve a system of linear equations, i.e., A*X = B, where X is unknown.

  • For a square matrix A, this function is conceptually the same as X = inv(A)*B, but is done more efficiently.

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

  • This function will also try to provide approximate solutions to under-determined as well as over-determined systems (non-square A matrices).

  • Similar functionality to the "\" (left division operator) operator in Matlab/Octave, i.e., X = A\B.

  • NOTE: ATLAS 3.6 provides an implementation of the LAPACK library that may crash when solving under/over determined systems. Later versions of ATLAS may work (not yet tested). Using the standard LAPACK library works without problems.

  • Examples: 
      mat A    = rand<mat>(5,5);
colvec b = rand<colvec>(5);
mat B    = rand<mat>(5,5);

colvec x = solve(A,b);
mat X    = solve(A,B);

  • See also: linear system of equations in MathWorld


svd(colvec s, mat X),
svd(colvec s, cx_mat X)

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

svd(mat U, colvec s, mat V, mat X)
svd(cx_mat U, colvec s, cx_mat V, cx_mat X)
  • The single- and two-argument versions compute the singular values of X

  • The three argument version computes the singular value decomposition of X, such that:
    • X = U*diagmat(s)*trans(V), if X has real numbers
    • X = U*diagmat(s)*htrans(V), if X has complex numbers

  • Examples: 
      mat X = rand<mat>(5,5);

mat U;
colvec s;
mat V;
svd(U,s,V,X);

  • See also: singular value decomposition in MathWorld



Miscellaneous


constants (pi, e, euler, gratio, sqrt2, eps, log_min, log_max)

  • Collection of constants, with their precision and/or value dependant on the numerical type and/or machine used.

  • The constants are stored as static functions in the Math<type> class, where type is either float or double.

  • For convenience, Math<float> has been typedefed as fmath, while Math<double> has been typedefed as math.

  • Meaning of the constants:
      math::pi()   ratio of any circle's circumference to its diameter
      math::e()   base of the natural logarithm
      math::euler()   Euler's constant, aka Euler-Mascheroni constant
      math::gratio()   golden ratio
      math::sqrt2()   square root of 2
      math::eps()   the difference between 1 and the least value greater than 1 that is representable
      math::log_min()   log of minimum non-zero value
      math::log_max()   log of maximum value

  • Examples: 
      cout << "2.0 * pi = " << 2.0 * math::pi() << endl;
cout << "log_max, when using floats  = " << fmath::log_max() << endl;
cout << "log_max, when using doubles = " <<  math::log_max() << endl;


log_add(log_a, log_b)
  • Safe replacement for log(exp(log_a) + exp(log_b))

  • Usage:
    • scalar_type log_c = log_add(log_a, log_b)
    • scalar_type is either float or double
    • log_a, log_b and log_c must have the same type


s32, u32
  • s32 is a typedef for a 32 bit wide signed int

  • u32 is a typedef for a 32 bit wide unsigned int



cx_float, cx_double
  • cx_float is a typedef for std::complex<float>

  • cx_double is a typedef for std::complex<double>