Armadillo: API Reference

Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Armadillo: API Reference Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49:

Chris@49: Reference for Armadillo 3.900 Chris@49:
Chris@49: (Bavarian Sunflower) Chris@49:

Chris@49: to Armadillo home page Chris@49:
Chris@49: to NICTA home page Chris@49:
Chris@49:

Chris@49:

Chris@49:
Chris@49:
Chris@49: Chris@49: [top] Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Preamble Chris@49:
Chris@49:
Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49:

Chris@49:

Chris@49: To aid the conversion of Matlab/Octave programs, Chris@49: there is a syntax conversion table Chris@49:

Chris@49: First time users may want to have a look at a short example program Chris@49:

Chris@49: If you find any bugs or regressions, please report them Chris@49:

Chris@49: Notes on API additions Chris@49:

Chris@49:

Chris@49: Chris@49:

Chris@49:
Chris@49:

Chris@49:

Chris@49: Please cite the following tech report if you use Armadillo in your research and/or software. Chris@49: Citations are useful for the continued development and maintenance of the library. Chris@49:
Chris@49:
Chris@49: Chris@49: Conrad Sanderson. Chris@49:
Chris@49: Armadillo: An Open Source C++ Linear Algebra Library for Fast Prototyping and Computationally Intensive Experiments. Chris@49:
Chris@49: Technical Report, NICTA, 2010. Chris@49: Chris@49:

Chris@49:

Chris@49: Chris@49:
Chris@49:
Chris@49: Chris@49: Matrix, Vector, Cube and Field Classes Chris@49:

Mat<type>, mat and cx_mat

Col<type>, colvec and vec

Row<type>, rowvec

Cube<type>, cube

field<object type>

SpMat<type>, sp_mat and sp_cx_mat

Chris@49:
Chris@49: Chris@49: Member Functions & Variables Chris@49:

element initialisation

insert rows/cols/slices

save/load (matrices & cubes)

save/load (fields)

set_imag/real

set_size

shed rows/cols/slices

STL container functions

Chris@49:
Chris@49: Chris@49: Other Classes Chris@49:

running_stat<type>

running_stat_vec<type>

wall_clock

Chris@49:
Chris@49: Chris@49: Generated Vectors/Matrices/Cubes Chris@49:

toeplitz/circ_toeplitz

zeros

Chris@49:
Chris@49: Chris@49: Functions Individually Applied to Each Element of a Matrix/Cube Chris@49:

abs

eps

misc functions (exp, log, pow, sqrt, ...)

trigonometric functions (cos, sin, ...)

Chris@49:
Chris@49: Chris@49: Scalar Valued Functions of Vectors/Matrices/Cubes Chris@49:

Chris@49:
Chris@49: Chris@49: Scalar/Vector Valued Functions of Vectors/Matrices Chris@49:

statistics (mean, stddev, ...)

Chris@49:
Chris@49: Chris@49: Vector/Matrix/Cube Valued Functions of Vectors/Matrices/Cubes Chris@49:

join rows/cols/slices

Chris@49:
Chris@49: Chris@49: Decompositions, Factorisations, Inverses and Equation Solvers Chris@49:

Chris@49:
Chris@49: Chris@49: Miscellaneous Chris@49:

is_finite()

logging of errors/warnings

various constants (pi, inf, speed of light, ...)

uword/sword

cx_float/cx_double

Matlab/Armadillo syntax differences

example program

config.hpp

API additions

Chris@49:
Chris@49: Chris@49:
Chris@49:
Chris@49:

Chris@49:

Chris@49:
Chris@49:
Chris@49: Matrix, Vector, Cube and Field Classes Chris@49:
Chris@49:
Chris@49:

Chris@49:
Chris@49: Chris@49: Mat<type> Chris@49:
mat Chris@49:
cx_mat Chris@49:

Chris@49: The root matrix class is Mat<type>, where type can be one of: Chris@49:
- Chris@49: float, double, std::complex<float>, std::complex<double>, Chris@49: char, short, int, and unsigned versions of char, short, int. Chris@49:
Chris@49:

Chris@49: For convenience the following typedefs have been defined: Chris@49:

Chris@49: mat Chris@49:	Chris@49: = Chris@49:	Chris@49: Mat<double> Chris@49:
Chris@49: fmat Chris@49:	Chris@49: = Chris@49:	Chris@49: Mat<float> Chris@49:
Chris@49: cx_mat Chris@49:	Chris@49: = Chris@49:	Chris@49: Mat<cx_double> Chris@49:
Chris@49: cx_fmat Chris@49:	Chris@49: = Chris@49:	Chris@49: Mat<cx_float> Chris@49:
Chris@49: umat Chris@49:	Chris@49: = Chris@49:	Chris@49: Mat<uword> Chris@49:
Chris@49: imat Chris@49:	Chris@49: = Chris@49:	Chris@49: Mat<sword> Chris@49:

Chris@49:

Chris@49: In this documentation the mat type is used for convenience; Chris@49: it is possible to use other types instead, eg. fmat Chris@49:

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

Chris@49: Elements are stored with column-major ordering (ie. column by column) Chris@49:

Chris@49: Constructors: Chris@49:
- mat()
- mat(n_rows, n_cols)
- 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)
Chris@49:

Chris@49: The string format for the constructor is elements separated by spaces, and rows denoted by semicolons. Chris@49: For example, the 2x2 identity matrix can be created using the format string "1 0; 0 1". Chris@49: While string based initialisation is compact, Chris@49: directly setting the elements Chris@49: or using element initialisation is considerably faster. Chris@49:

Chris@49: Advanced constructors: Chris@49:
Chris@49:
Chris@49:
- mat(aux_mem*, n_rows, n_cols, copy_aux_mem = true, strict = true) Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
- mat(const aux_mem*, n_rows, n_cols) Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
- mat::fixed<n_rows, n_cols> Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
- mat::fixed<n_rows, n_cols>(const aux_mem*) Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: double x = A(1,2);
Chris@49: 
Chris@49: mat B = A + A;
Chris@49: mat C = A * B;
Chris@49: mat D = A % B;
Chris@49: 
Chris@49: cx_mat X(A,B);
Chris@49: 
Chris@49: B.zeros();
Chris@49: B.set_size(10,10);
Chris@49: B.zeros(5,6);
Chris@49: 
Chris@49: //
Chris@49: // fixed size matrices:
Chris@49: 
Chris@49: mat::fixed<5,6> F;
Chris@49: F.ones();
Chris@49: 
Chris@49: mat44 G;
Chris@49: G.randn();
Chris@49: 
Chris@49: cout << mat22().randu() << endl;
Chris@49: 
Chris@49: //
Chris@49: // constructing matrices from
Chris@49: // auxiliary (external) memory:
Chris@49: 
Chris@49: double aux_mem[24];
Chris@49: mat H(aux_mem, 4, 6, false);
Chris@49:

Chris@49:

Caveat: Chris@49: For mathematical correctness, scalars are treated as 1x1 matrices during initialisation. Chris@49: As such, the code below will not generate a 5x5 matrix with every element equal to 123.0: Chris@49:
Chris@49: Use the following code instead: Chris@49:
Chris@49:
Chris@49:
Chris@49: See also: Chris@49:
- matrix attributes
- accessing elements
- initialising elements
- math & relational operators
- submatrix views
- saving & loading matrices
- printing matrices
- STL-style element iterators
- .eval()
- conv_to() (convert between matrix types)
- explanation of typedef (cplusplus.com) Chris@49:
- Col class
- Row class
- Cube class
- SpMat class (sparse matrix)
- config.hpp
Chris@49:

Chris@49:

Chris@49:
Chris@49: Chris@49: Col<type> Chris@49:
colvec Chris@49:
vec Chris@49:

Chris@49: Classes for column vectors (matrices with one column) Chris@49:

The Col<type> class is derived from the Mat<type> class Chris@49: and inherits most of the member functions Chris@49:

Chris@49: For convenience the following typedefs have been defined: Chris@49:

Chris@49: vec, colvec Chris@49:	Chris@49: = Chris@49:	Chris@49: Col<double> Chris@49:
Chris@49: fvec, fcolvec Chris@49:	Chris@49: = Chris@49:	Chris@49: Col<float> Chris@49:
Chris@49: cx_vec, cx_colvec Chris@49:	Chris@49: = Chris@49:	Chris@49: Col<cx_double> Chris@49:
Chris@49: cx_fvec, cx_fcolvec Chris@49:	Chris@49: = Chris@49:	Chris@49: Col<cx_float> Chris@49:
Chris@49: uvec, ucolvec Chris@49:	Chris@49: = Chris@49:	Chris@49: Col<uword> Chris@49:
Chris@49: ivec, icolvec Chris@49:	Chris@49: = Chris@49:	Chris@49: Col<sword> Chris@49:

Chris@49:

Chris@49: In this documentation, the vec and colvec types have the same meaning and are used interchangeably Chris@49:

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

Chris@49: Functions which take Mat as input can generally also take Col as input. Chris@49: Main exceptions are functions which require square matrices Chris@49:

Chris@49: Constructors Chris@49:
- vec(n_elem=0)
- 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)
Chris@49:

Chris@49: Advanced constructors: Chris@49:
Chris@49:
Chris@49:
- vec(aux_mem*, number_of_elements, copy_aux_mem = true, strict = true) Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
- vec(const aux_mem*, number_of_elements) Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
- vec::fixed<number_of_elements> Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
- vec::fixed<number_of_elements>(const aux_mem*) Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

Caveat: Chris@49: For mathematical correctness, scalars are treated as 1x1 matrices during initialisation. Chris@49: As such, the code below will not generate a column vector with every element equal to 123.0: Chris@49:
Chris@49: Use the following code instead: Chris@49:
Chris@49:

See also: Chris@49:
- Mat class
- Row class
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: Row<type> Chris@49:
rowvec Chris@49:

Chris@49: Classes for row vectors (matrices with one row) Chris@49:

The template Row<type> class is derived from the Mat<type> class Chris@49: and inherits most of the member functions Chris@49:

Chris@49: For convenience the following typedefs have been defined: Chris@49:

Chris@49: rowvec Chris@49:	Chris@49: = Chris@49:	Chris@49: Row<double> Chris@49:
Chris@49: frowvec Chris@49:	Chris@49: = Chris@49:	Chris@49: Row<float> Chris@49:
Chris@49: cx_rowvec Chris@49:	Chris@49: = Chris@49:	Chris@49: Row<cx_double> Chris@49:
Chris@49: cx_frowvec Chris@49:	Chris@49: = Chris@49:	Chris@49: Row<cx_float> Chris@49:
Chris@49: urowvec Chris@49:	Chris@49: = Chris@49:	Chris@49: Row<uword> Chris@49:
Chris@49: irowvec Chris@49:	Chris@49: = Chris@49:	Chris@49: Row<sword> Chris@49:

Chris@49:

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

Chris@49: Functions which take Mat as input can generally also take Row as input. Chris@49: Main exceptions are functions which require square matrices Chris@49:

Chris@49: Constructors Chris@49:
- rowvec(n_elem=0)
- 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)
Chris@49:

Chris@49: Advanced constructors: Chris@49:
Chris@49:
Chris@49:
- rowvec(aux_mem*, number_of_elements, copy_aux_mem = true, strict = true) Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
- rowvec(const aux_mem*, number_of_elements) Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
- rowvec::fixed<number_of_elements> Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
- rowvec::fixed<number_of_elements>(const aux_mem*) Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: Caveat: Chris@49: For mathematical correctness, scalars are treated as 1x1 matrices during initialisation. Chris@49: As such, the code below will not generate a row vector with every element equal to 123.0: Chris@49:
Chris@49: Use the following code instead: Chris@49:
Chris@49:
Chris@49:
See also: Chris@49:
- Mat class
- Col class
Chris@49:

Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: Cube<type> Chris@49:
cube Chris@49:
cx_cube Chris@49:

Chris@49: Classes for cubes, also known as "3D matrices" or 3rd order tensors Chris@49:

Chris@49: The cube class is Cube<type>, where type can be one of: Chris@49: char, int, float, double, std::complex<double>, etc Chris@49:

Chris@49: For convenience the following typedefs have been defined: Chris@49:

Chris@49: cube Chris@49:	Chris@49: = Chris@49:	Chris@49: Cube<double> Chris@49:
Chris@49: fcube Chris@49:	Chris@49: = Chris@49:	Chris@49: Cube<float> Chris@49:
Chris@49: cx_cube Chris@49:	Chris@49: = Chris@49:	Chris@49: Cube<cx_double> Chris@49:
Chris@49: cx_fcube Chris@49:	Chris@49: = Chris@49:	Chris@49: Cube<cx_float> Chris@49:
Chris@49: ucube Chris@49:	Chris@49: = Chris@49:	Chris@49: Cube<uword> Chris@49:
Chris@49: icube Chris@49:	Chris@49: = Chris@49:	Chris@49: Cube<sword> Chris@49:

Chris@49:

Chris@49: In this documentation the cube type is used for convenience; Chris@49: it is possible to use other types instead, eg. fcube Chris@49:

Chris@49: Cube data is stored as a set of slices (matrices) stored contiguously within memory. Chris@49: Within each slice, elements are stored with column-major ordering (ie. column by column) Chris@49:

Chris@49: Each slice can be interpreted as a matrix, hence functions which take Mat as input can generally also take cube slices as input Chris@49:

Chris@49: Constructors: Chris@49:
Chris@49:

Chris@49: Advanced constructors: Chris@49:
Chris@49:
Chris@49:
- Chris@49: cube::fixed<n_rows, n_cols, n_slices> Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
- cube(aux_mem*, n_rows, n_cols, n_slices, copy_aux_mem = true, strict = true) Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
- cube(const aux_mem*, n_rows, n_cols, n_slices) Chris@49:
  Chris@49:
  Chris@49:
  Chris@49:
Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: cube x(1,2,3);
Chris@49: cube y = randu<cube>(4,5,6);
Chris@49: 
Chris@49: mat A = y.slice(1);  // extract a slice from the cube
Chris@49:                      // (each slice is a matrix)
Chris@49: 
Chris@49: mat B = randu<mat>(4,5);
Chris@49: y.slice(2) = B;     // set a slice in the cube
Chris@49: 
Chris@49: cube q = y + y;     // cube addition
Chris@49: cube r = y % y;     // element-wise cube multiplication
Chris@49: 
Chris@49: cube::fixed<4,5,6> f;
Chris@49: f.ones();
Chris@49:

Chris@49:

Chris@49: Caveats Chris@49:
Chris@49:
Chris@49:
- Chris@49: The size of individual slices can't be changed. Chris@49: For example, the following will not work: Chris@49:
  Chris@49:
- Chris@49: For mathematical correctness, scalars are treated as 1x1x1 cubes during initialisation. Chris@49: As such, the code below will not generate a cube with every element equal to 123.0: Chris@49:
  Chris@49: Use the following code instead: Chris@49:
  Chris@49:
  Chris@49:
Chris@49:
Chris@49: See also: Chris@49:
- cube attributes
- accessing elements
- math & relational operators
- subcube views and slices
- saving & loading cubes
- STL-style element iterators
- Mat class
Chris@49:

Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: field<object type> Chris@49:

Chris@49: Class for one and two dimensional fields of arbitrary objects Chris@49:

Chris@49: Constructors (where object type is another class, eg. std::string, mat, vec, rowvec, etc): Chris@49:
Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: // create a field of strings
Chris@49: field<std::string> S(3,2);
Chris@49: 
Chris@49: S(0,0) = "hello";
Chris@49: S(1,0) = "there";
Chris@49: 
Chris@49: // string fields can be saved as plain text files
Chris@49: S.save("string_field");
Chris@49: 
Chris@49: // create a vec field with 3 rows and 2 columns
Chris@49: field<vec> F(3,2);
Chris@49: 
Chris@49: // access components of the field
Chris@49: F(0,0) = vec(5);
Chris@49: F(1,1) = randu<vec>(6);
Chris@49: F(2,0).set_size(7);
Chris@49: 
Chris@49: // access element 1 of the vec stored at 2,0
Chris@49: double x = F(2,0)(1);
Chris@49: 
Chris@49: // copy rows
Chris@49: F.row(0) = F.row(2);
Chris@49: 
Chris@49: // extract a row of vecs from F
Chris@49: field<vec> G = F.row(1);
Chris@49: 
Chris@49: // print the field to the standard output
Chris@49: G.print("G =");
Chris@49: 
Chris@49: // save the field to a binary file
Chris@49: G.save("vec_field");
Chris@49:

Chris@49:

See also: Chris@49:
- field attributes
- subfield views
- saving/loading fields
- string class in the standard C++ library (cplusplus.com)
Chris@49:

Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: SpMat<type> Chris@49:
sp_mat Chris@49:
sp_cx_mat Chris@49:

Chris@49: The root sparse matrix class is SpMat<type>, where type can be one of: Chris@49: char, int, float, double, std::complex<double>, etc. Chris@49:

Chris@49: For convenience the following typedefs have been defined: Chris@49:

Chris@49: sp_mat Chris@49:	Chris@49: = Chris@49:	Chris@49: SpMat<double> Chris@49:
Chris@49: sp_fmat Chris@49:	Chris@49: = Chris@49:	Chris@49: SpMat<float> Chris@49:
Chris@49: sp_cx_mat Chris@49:	Chris@49: = Chris@49:	Chris@49: SpMat<cx_double> Chris@49:
Chris@49: sp_cx_fmat Chris@49:	Chris@49: = Chris@49:	Chris@49: SpMat<cx_float> Chris@49:
Chris@49: sp_umat Chris@49:	Chris@49: = Chris@49:	Chris@49: SpMat<uword> Chris@49:
Chris@49: sp_imat Chris@49:	Chris@49: = Chris@49:	Chris@49: SpMat<sword> Chris@49:

Chris@49:

Chris@49: In this documentation the sp_mat type is used for convenience; Chris@49: it is possible to use other types instead, eg. sp_fmat Chris@49:

Chris@49: Constructors: Chris@49:
- 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)
Chris@49:
Chris@49:
Chris@49: Chris@49: Batch insertion constructors: Chris@49:
- sp_mat(locations, values, n_rows, n_cols, sort_locations = true)
- sp_mat(locations, values, sort_locations = true)
Chris@49:
Chris@49:
Chris@49: Elements are stored in the compressed sparse column (CSC) format Chris@49:

Chris@49: All elements are treated as zero by default Chris@49:

Chris@49: This class behaves in a similar manner to the Mat class, Chris@49: however, member functions which set all elements to non-zero values (and hence do not make sense for sparse matrices) have been deliberately omitted; Chris@49: examples of omitted functions: .fill(), .ones(), += scalar, etc. Chris@49:

Batch insertion of values: Chris@49:
- Chris@49: Using batch insertion constructors is generally much faster than consecutively inserting values using element access operators Chris@49:
- Chris@49: 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. Chris@49: The row and column of the i-th element are specified as locations(0,i) and locations(1,i), respectively. Chris@49:
- Chris@49: values is a dense column vector containing the values to be inserted. Chris@49: It must have the same element type as the sparse matrix. Chris@49: The value in values[i] will be inserted at the location specified by the i-th column of the locations matrix. Chris@49:
- Chris@49: The size of the constructed matrix is either manually specified via n_rows and n_cols, Chris@49: or automatically determined from the maximal locations in the locations matrix. Chris@49:
- Chris@49: If sort_locations is set to false, the locations matrix is assumed to contain locations that are already sorted according to column-major ordering. Chris@49:
Chris@49:

Chris@49: Caveat: Chris@49: support for sparse matrices in this version is preliminary; Chris@49: it is not yet fully optimised, and sparse matrix decompositions/factorisations are not yet implemented. Chris@49: The following subset of operations currently works with sparse matrices: Chris@49:
- element access
- fundamental arithmetic operations (such as addition and multiplication)
- submatrix views
- saving and loading (in arma_binary format)
- Chris@49: abs(), Chris@49: accu(), Chris@49: as_scalar(), Chris@49: dot(), Chris@49: mean(), Chris@49: min(), Chris@49: max(), Chris@49: norm(), Chris@49: print(), Chris@49: speye(), Chris@49: sprandu()/sprandn(), Chris@49: square(), Chris@49: sqrt(), Chris@49: sum(), Chris@49: trace(), Chris@49: trans(), Chris@49: var() Chris@49:
Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: sp_mat A(5,6);
Chris@49: sp_mat B(6,5);
Chris@49: 
Chris@49: A(0,0) = 1;
Chris@49: A(1,0) = 2;
Chris@49: 
Chris@49: B(0,0) = 3;
Chris@49: B(0,1) = 4;
Chris@49: 
Chris@49: sp_mat C = 2*B;
Chris@49: 
Chris@49: sp_mat D = A*C;
Chris@49: 
Chris@49: 
Chris@49: // batch insertion of two values at (5, 6) and (9, 9)
Chris@49: umat locations;
Chris@49: locations << 5 << 9 << endr
Chris@49:           << 6 << 9 << endr;
Chris@49: 
Chris@49: vec values;
Chris@49: values << 1.5 << 3.2 << endr;
Chris@49: 
Chris@49: sp_mat X(locations, values);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- accessing elements
- printing matrices
- Sparse Matrix in Wikipedia
- Mat class (dense matrix)
Chris@49:

Chris@49:

Chris@49:
Chris@49:
Chris@49: Member Functions & Variables Chris@49:
Chris@49:
Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: Chris@49: attributes Chris@49:

Chris@49: .n_rows Chris@49:		Chris@49: (number of rows) Chris@49:
Chris@49: .n_cols Chris@49:		Chris@49: (number of columns) Chris@49:
Chris@49: .n_elem Chris@49:		Chris@49: (total number of elements) Chris@49:
Chris@49: .n_slices Chris@49:		Chris@49: (number of slices) Chris@49:
Chris@49: .n_nonzero Chris@49:		Chris@49: (number of nonzero elements) Chris@49:

Chris@49:
Chris@49:

Chris@49: Member variables which are read-only; Chris@49: to change the size, use Chris@49: .set_size(), Chris@49: .copy_size(), Chris@49: .zeros(), Chris@49: .ones(), Chris@49: or Chris@49: .reset() Chris@49:

n_rows, n_cols and n_elem are applicable to Mat, SpMat, Col, Row, Cube and field classes

n_slices is applicable only to the Cube class

n_nonzero is applicable only to the SpMat class

Chris@49: For the Col and Row classes, n_elem also indicates vector length

The variables are of type uword

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- .set_size()
- .copy_size()
- .zeros()
- .ones()
- .reset()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .colptr(col_number) Chris@49:

Chris@49: Member function of Mat Chris@49:

Chris@49: Obtain a raw pointer to the memory used by the specified column Chris@49:

Chris@49: As soon as the size of the matrix is changed, the pointer is no longer valid Chris@49:

This function is not recommended for use unless you know what you're doing Chris@49: -- you may wish to use submatrix views instead Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: 
Chris@49: double* mem = A.colptr(2);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .memptr()
- submatrix views
- element access
- iterators (matrices)
- advanced constructors (matrices)
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .copy_size(A) Chris@49:

Chris@49: Member function of Mat, Col, Row, Cube and field Chris@49:

Chris@49: Set the size to be the same as object A Chris@49:

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

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- .reset()
- .set_size()
- .reshape()
- .resize()
- .zeros()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: .diag(k=0) Chris@49:

Chris@49: Member function of Mat Chris@49:

Chris@49: Read/write access to the k-th diagonal in a matrix Chris@49:

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)

Chris@49: An extracted diagonal is interpreted as a column vector Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- .eye()
- diagvec()
- diagmat()
- submatrix views
- .each_col() & .each_row()
- trace()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: .each_col() Chris@49:
Chris@49: .each_row() Chris@49:
Chris@49:
Chris@49: .each_col(vector_of_indices) Chris@49:
Chris@49: .each_row(vector_of_indices) Chris@49:

Chris@49: Member functions of Mat Chris@49:

Chris@49: Write access to each column or row of a matrix/submatrix, Chris@49: allowing a vector operation to be repeated on each column or row Chris@49:

Chris@49: The operation can be in-place vector addition, subtraction, element-wise multiplication, element-wise division, or simply vector copy Chris@49:

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

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

Chris@49: These functions were added in version 3.4 Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat X = ones<mat>(6,5);
Chris@49: vec v = linspace<vec>(10,15,6);
Chris@49: 
Chris@49: // add v to each column in X
Chris@49: X.each_col() += v;
Chris@49: 
Chris@49: // subtract v from columns 0 through to 3 in X
Chris@49: X.cols(0,3).each_col() -= v;
Chris@49: 
Chris@49: uvec indices(2);
Chris@49: indices(0) = 2;
Chris@49: indices(1) = 4;
Chris@49: 
Chris@49: // copy v to columns 2 and 4 in X
Chris@49: X.each_col(indices) = v;
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- diagonal views
- submatrix views
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: element/object access via (), [] and .at() Chris@49:

Chris@49: Provide access to individual elements or objects stored in a container object Chris@49: (ie., Mat, Col, Row, Cube, field)
Chris@49:
Chris@49:

Chris@49: (n) Chris@49:	Chris@49:	Chris@49: For vec and rowvec, access the n-th element. Chris@49: For mat, cube and field, access the n-th element/object under the assumption of a flat layout, Chris@49: with column-major ordering of data (ie. column by column). Chris@49: A std::logic_error exception is thrown if the requested element is out of bounds. Chris@49: The bounds check can be optionally disabled at compile-time to get more speed. Chris@49:

Chris@49: .at(n) and [n] Chris@49:	Chris@49:	Chris@49: As for (n), but without a bounds check. Chris@49: Not recommended for use unless your code has been thoroughly debugged. Chris@49:

Chris@49: (i,j) Chris@49:	Chris@49:	Chris@49: For mat and field classes, access the element/object stored at the i-th row and j-th column. Chris@49: A std::logic_error exception is thrown if the requested element is out of bounds. Chris@49: The bounds check can be optionally disabled at compile-time to get more speed. Chris@49:

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

Chris@49: (i,j,k) Chris@49:	Chris@49:	Chris@49: Cube only: access the element stored at the i-th row, j-th column and k-th slice. Chris@49: A std::logic_error exception is thrown if the requested element is out of bounds. Chris@49: The bounds check can be optionally disabled at compile-time to get more speed. Chris@49:

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

Chris@49:

Chris@49: The bounds checks used by the (n), (i,j) and (i,j,k) access forms Chris@49: can be disabled by defining ARMA_NO_DEBUG or NDEBUG macros Chris@49: before including the armadillo header file (eg. #define ARMA_NO_DEBUG). Chris@49: Disabling the bounds checks is not recommended until your code has been thoroughly debugged Chris@49: -- it's better to write correct code first, and then maximise its speed. Chris@49:

Chris@49: Note: for sparse matrices, using element access operators to insert values via loops can be inefficient; Chris@49: you may wish to use batch insertion constructors instead Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(10,10);
Chris@49: A(9,9) = 123.0;
Chris@49: double x = A.at(9,9);
Chris@49: double y = A[99];
Chris@49: 
Chris@49: vec p = randu<vec>(10,1);
Chris@49: p(9) = 123.0;
Chris@49: double z = p[9];
Chris@49:

Chris@49:

See also: Chris@49:
- .in_range()
- element initialisation
- submatrix views
- .memptr()
- iterators (matrices)
- iterators (cubes)
- config.hpp
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: element initialisation Chris@49:

Chris@49: Instances of Mat, Col, Row and field classes can be initialised via repeated use of the << operator Chris@49:

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

Chris@49: Setting elements via << is a bit slower than directly accessing the elements, Chris@49: but code using << is generally more readable as well as being easier to write Chris@49:

Chris@49: If you have a C++11 compiler, instances of Mat, Col and Row classes can be also initialised via initialiser lists; Chris@49: this requires support for the C++11 standard to be explicitly enabled Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- element access
- .print()
- saving & loading matrices
- advanced constructors (matrices)
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .eval() Chris@49:
Chris@49:

Chris@49: Member function of any matrix or vector expression Chris@49:

Chris@49: Explicitly forces the evaluation of a delayed expression and outputs a matrix Chris@49:

Chris@49: This function should be used sparingly and only in cases where it is absolutely necessary; indiscriminate use can cause slow downs Chris@49:

Chris@49: This function was added in version 3.2 Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: cx_mat A( randu<mat>(4,4), randu<mat>(4,4) );
Chris@49: 
Chris@49: real(A).eval().save("A_real.dat", raw_ascii);
Chris@49: imag(A).eval().save("A_imag.dat", raw_ascii);
Chris@49:

Chris@49:

See also: Chris@49:
- Mat class
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .eye() Chris@49:
Chris@49: .eye(n_rows, n_cols) Chris@49:

Chris@49: Set the elements along the main diagonal to one and off-diagonal elements set to zero, Chris@49: optionally first resizing to specified dimensions Chris@49:

Chris@49: An identity matrix is generated when n_rows = n_cols Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A(5,5);
Chris@49: A.eye();
Chris@49: 
Chris@49: mat B;
Chris@49: B.eye(5,5);
Chris@49:

Chris@49:

See also: Chris@49:
- .ones()
- .diag()
- diagmat()
- diagvec()
- eye() (standalone function)
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .fill(value) Chris@49:

Chris@49: Member function of Mat, Col, Row and Cube classes. Chris@49:

Sets the elements to a specified value

the type of value must match the type of elements used by the container object (eg. for mat the type is double) Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A(5,5);
Chris@49: A.fill(123.0);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .imbue()
- .ones()
- .zeros()
- .randu() & .randn()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .i( slow=false ) Chris@49:

Chris@49: Member function of any matrix expression Chris@49:

Chris@49: Provides an inverse of the matrix expression Chris@49:

the slow argument is optional

Chris@49: If the matrix expression is not square, a std::logic_error exception is thrown Chris@49:

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

Chris@49: For matrix sizes ≤ 4x4, a fast inverse algorithm is used by default. Chris@49: In rare instances, the fast algorithm might be less precise than the standard algorithm. Chris@49: To force the use of the standard algorithm, set the slow argument to true Chris@49:

Chris@49: NOTE: in many cases it is more efficient/faster to use the solve() function instead of performing a matrix inverse Chris@49:

Chris@49: This function was added in version 3.0 Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(4,4);
Chris@49: 
Chris@49: mat X = A.i();
Chris@49: mat Y = (A+A).i();
Chris@49: 
Chris@49: mat B = randu<mat>(4,1);
Chris@49: mat Z = A.i() * B; // automatically converted to Z=solve(A,B)
Chris@49: 
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- inv()
- pinv()
- solve()
Chris@49:

Chris@49:

.in_range( i )	Chris@49:	(member of Mat, Col, Row, Cube and field) Chris@49:
.in_range( span(start, end) )	Chris@49:	(member of Mat, Col, Row, Cube and field) Chris@49:
Chris@49: Chris@49:
.in_range( row, col )	Chris@49:	(member of Mat, Col, Row and field) Chris@49:
.in_range( span(start_row, end_row), span(start_col, end_col) )	Chris@49:	(member of Mat, Col, Row and field) Chris@49:
Chris@49: Chris@49:
.in_range( row, col, slice )	Chris@49:	(member of Cube) Chris@49:
.in_range( span(start_row, end_row), span(start_col, end_col), span(start_slice, end_slice) )	Chris@49:	(member of Cube) Chris@49:

Chris@49:
Chris@49:

Returns true if the given location or span is currently valid Chris@49:

Returns false if the object is empty, the location is out of bounds, or the span is out of bounds Chris@49:

Chris@49: Instances of span(a,b) can be replaced by: Chris@49:
- span() or span::all, to indicate the entire range
- span(a), to indicate a particular row, column or slice
Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(4,5);
Chris@49: 
Chris@49: cout << A.in_range(0,0) << endl;  // true
Chris@49: cout << A.in_range(3,4) << endl;  // true
Chris@49: cout << A.in_range(4,5) << endl;  // false
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- element access
- submatrix views
- subcube views
- subfield views
- .set_size()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .is_empty() Chris@49:

Chris@49: Member function of Mat, Col, Row, Cube and field classes Chris@49:

Returns true if the object has no elements Chris@49:

Returns false if the object has one or more elements Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: cout << A.is_empty() << endl;
Chris@49: 
Chris@49: A.reset();
Chris@49: cout << A.is_empty() << endl;
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .is_square()
- .is_vec()
- .is_finite()
- .reset()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .is_finite() Chris@49:

Chris@49: Member function of Mat, Col, Row and Cube classes Chris@49:

Returns true if all elements of the object are finite Chris@49:

Returns false if at least one of the elements of the object is non-finite (±infinity or NaN) Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: mat B = randu<mat>(5,5);
Chris@49: 
Chris@49: B(1,1) = datum::nan;
Chris@49: 
Chris@49: cout << A.is_finite() << endl;
Chris@49: cout << B.is_finite() << endl;
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- datum::nan
- datum::inf
- is_finite() (standalone function)
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .is_square() Chris@49:

Chris@49: Member function of the Mat class Chris@49:

Returns true if the matrix is square, ie., number of rows is equal to the number of columns Chris@49:

Returns false if the matrix is not square Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: mat B = randu<mat>(6,7);
Chris@49: 
Chris@49: cout << A.is_square() << endl;
Chris@49: cout << B.is_square() << endl;
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .is_empty()
- .is_vec()
- .is_finite()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: .is_vec() Chris@49:
.is_colvec() Chris@49:
.is_rowvec() Chris@49:

Chris@49: Member functions of the Mat class Chris@49:

.is_vec(): Chris@49:
- Returns true if the matrix can be interpreted as a vector (either column or row vector) Chris@49:
- Returns false if the matrix does not have exactly one column or one row Chris@49:
Chris@49:

.is_colvec(): Chris@49:
- Returns true if the matrix can be interpreted as a column vector Chris@49:
- Returns false if the matrix does not have exactly one column Chris@49:
Chris@49:

.is_rowvec(): Chris@49:
- Returns true if the matrix can be interpreted as a row vector Chris@49:
- Returns false if the matrix does not have exactly one row Chris@49:
Chris@49:

Caveat: do not assume that the vector has elements if these functions return true -- it is possible to have an empty vector (eg. 0x1) Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(1,5);
Chris@49: mat B = randu<mat>(5,1);
Chris@49: mat C = randu<mat>(5,5);
Chris@49: 
Chris@49: cout << A.is_vec() << endl;
Chris@49: cout << B.is_vec() << endl;
Chris@49: cout << C.is_vec() << endl;
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .is_empty()
- .is_square()
- .is_finite()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: .imbue( functor ) Chris@49:
Chris@49: .imbue( lambda function ) (C++11 only) Chris@49:
Chris@49:

Chris@49: Imbue (fill) with values provided by a functor or lambda function Chris@49:

Chris@49: For matrices, filling is done column-by-column (ie. column 0 is filled, then column 1, ...) Chris@49:

Chris@49: For cubes, filling is done slice-by-slice; each slice is filled column-by-column Chris@49:

Chris@49: This function was added in version 3.800 Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: // C++11 only example
Chris@49: // need to include <random>
Chris@49: 
Chris@49: std::mt19937 engine;  // Mersenne twister random number engine
Chris@49: 
Chris@49: std::uniform_real_distribution<double> distr(0.0, 1.0);
Chris@49:   
Chris@49: mat A(4,5);
Chris@49:   
Chris@49: A.imbue( [&]() { return distr(engine); } );
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .fill()
- .transform()
- function object at Wikipedia
- C++11 lambda functions at Wikipedia
- lambda function at cprogramming.com
Chris@49:

Chris@49:

Chris@49: .insert_rows( row_number, X ) Chris@49: Chris@49: .insert_rows( row_number, number_of_rows, set_to_zero = true ) Chris@49:		(member functions of Mat and Col) Chris@49:

Chris@49: .insert_cols( col_number, X ) Chris@49: Chris@49: .insert_cols( col_number, number_of_cols, set_to_zero = true ) Chris@49:		(member functions of Mat and Row) Chris@49:

Chris@49: .insert_slices( slice_number, X ) Chris@49: Chris@49: .insert_slices( slice_number, number_of_slices, set_to_zero = true ) Chris@49:		(member functions of Cube) Chris@49:

Chris@49:
Chris@49:

Chris@49: Functions with the X argument: insert a copy of X at the specified row/column/slice Chris@49:
- 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)
Chris@49:

Chris@49: Functions with the number_of_... argument: expand the object by creating new rows/columns/slices. Chris@49: By default, the new rows/columns/slices are set to zero. Chris@49: If set_to_zero is false, the memory used by the new rows/columns/slices will not be initialised. Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,10);
Chris@49: mat B = ones<mat>(5,2);
Chris@49: 
Chris@49: // at column 2, insert a copy of B;
Chris@49: // A will now have 12 columns
Chris@49: A.insert_cols(2, B);
Chris@49: 
Chris@49: // at column 1, insert 5 zeroed columns;
Chris@49: // B will now have 7 columns
Chris@49: B.insert_cols(1, 5);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- shed rows/columns/slices
- join rows/columns/slices
- .resize()
- submatrix views
- subcube views
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: iterators (matrices & vectors) Chris@49:

Chris@49: STL-style iterators and associated member functions of the Mat, Col and Row classes Chris@49:

Chris@49: iterator types: Chris@49:
Chris@49:
Chris@49:

Chris@49: mat::iterator Chris@49: Chris@49: vec::iterator Chris@49: Chris@49: rowvec::iterator Chris@49:	Chris@49:	Chris@49: random access iterators, for read/write access to elements Chris@49: (which are stored column by column) Chris@49:
Chris@49: Chris@49:	Chris@49:	Chris@49: Chris@49:
Chris@49: mat::const_iterator Chris@49: Chris@49: vec::const_iterator Chris@49: Chris@49: rowvec::const_iterator Chris@49:	Chris@49:	Chris@49: random access iterators, for read-only access to elements Chris@49: (which are stored column by column) Chris@49:
Chris@49: Chris@49:	Chris@49:	Chris@49: Chris@49:
Chris@49: mat::col_iterator Chris@49: Chris@49: vec::col_iterator Chris@49: Chris@49: rowvec::col_iterator Chris@49:	Chris@49:	Chris@49: random access iterators, for read/write access to the elements of a specific column Chris@49:
Chris@49: Chris@49:	Chris@49:	Chris@49: Chris@49:
Chris@49: mat::const_col_iterator Chris@49: Chris@49: vec::const_col_iterator Chris@49: Chris@49: rowvec::const_col_iterator Chris@49:	Chris@49:	Chris@49: random access iterators, for read-only access to the elements of a specific column Chris@49:
Chris@49: Chris@49:	Chris@49:	Chris@49: Chris@49:
Chris@49: mat::row_iterator Chris@49:	Chris@49:	Chris@49: rudimentary forward iterator, for read/write access to the elements of a specific row Chris@49:
Chris@49: Chris@49:	Chris@49:	Chris@49: Chris@49:
Chris@49: mat::const_row_iterator Chris@49:	Chris@49:	Chris@49: rudimentary forward iterator, for read-only access to the elements of a specific row Chris@49:
Chris@49: Chris@49:	Chris@49:	Chris@49: Chris@49:
Chris@49: vec::row_iterator Chris@49: Chris@49: rowvec::row_iterator Chris@49:	Chris@49:	Chris@49: random access iterators, for read/write access to the elements of a specific row Chris@49:
Chris@49: Chris@49:	Chris@49:	Chris@49: Chris@49:
Chris@49: vec::const_row_iterator Chris@49: Chris@49: rowvec::const_row_iterator Chris@49:	Chris@49:	Chris@49: random access iterators, for read-only access to the elements of a specific row Chris@49:

Chris@49:

Chris@49: Member functions: Chris@49:
Chris@49:
Chris@49:

Chris@49: .begin() Chris@49:	Chris@49:	Chris@49: iterator referring to the first element Chris@49:
Chris@49: .end() Chris@49:	Chris@49:	Chris@49: iterator referring to the past-the-end element Chris@49:
Chris@49: Chris@49:
Chris@49: .begin_row(row_number) Chris@49:	Chris@49:	Chris@49: iterator referring to the first element of the specified row Chris@49:
Chris@49: .end_row(row_number) Chris@49:	Chris@49:	Chris@49: iterator referring to the past-the-end element of the specified row Chris@49:
Chris@49: Chris@49:
Chris@49: .begin_col(col_number) Chris@49:	Chris@49:	Chris@49: iterator referring to the first element of the specified column Chris@49:
Chris@49: .end_col(col_number) Chris@49:	Chris@49:	Chris@49: iterator referring to the past-the-end element of the specified column Chris@49:

Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat X = randu<mat>(5,5);
Chris@49: 
Chris@49: 
Chris@49: mat::iterator a = X.begin();
Chris@49: mat::iterator b = X.end();
Chris@49: 
Chris@49: for(mat::iterator i=a; i!=b; ++i)
Chris@49:   {
Chris@49:   cout << *i << endl;
Chris@49:   }
Chris@49: 
Chris@49: 
Chris@49: mat::col_iterator c = X.begin_col(1);  // start of column 1
Chris@49: mat::col_iterator d = X.end_col(3);    // end of column 3
Chris@49: 
Chris@49: for(mat::col_iterator i=c; i!=d; ++i)
Chris@49:   {
Chris@49:   cout << *i << endl;
Chris@49:   (*i) = 123.0;
Chris@49:   }
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- STL container functions
- iterator at cplusplus.com
- element access
- .memptr()
- .colptr()
- submatrix views
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: iterators (cubes) Chris@49:

Chris@49: STL-style iterators and associated member functions of the Cube class Chris@49:

Chris@49: iterator types: Chris@49:
Chris@49:
Chris@49:

Chris@49: cube::iterator Chris@49:	Chris@49:	Chris@49: random access iterator, for read/write access to elements; Chris@49: the elements are ordered slice by slice; Chris@49: the elements within each slice are ordered column by column Chris@49:
Chris@49: Chris@49:	Chris@49:	Chris@49: Chris@49:
Chris@49: cube::const_iterator Chris@49:	Chris@49:	Chris@49: random access iterators, for read-only access to elements Chris@49:
Chris@49: Chris@49:	Chris@49:	Chris@49: Chris@49:
Chris@49: cube::slice_iterator Chris@49:	Chris@49:	Chris@49: random access iterator, for read/write access to the elements of a particular slice; Chris@49: the elements are ordered column by column Chris@49:
Chris@49: Chris@49:	Chris@49:	Chris@49: Chris@49:
Chris@49: cube::const_slice_iterator Chris@49:	Chris@49:	Chris@49: random access iterators, for read-only access to the elements of a particular slice Chris@49:

Chris@49:

Chris@49: Member functions: Chris@49:
Chris@49:
Chris@49:

Chris@49: .begin() Chris@49:	Chris@49:	Chris@49: iterator referring to the first element Chris@49:
Chris@49: .end() Chris@49:	Chris@49:	Chris@49: iterator referring to the past-the-end element Chris@49:
Chris@49: Chris@49:
Chris@49: .begin_slice(slice_number) Chris@49:	Chris@49:	Chris@49: iterator referring to the first element of the specified slice Chris@49:
Chris@49: .end_slice(slice_number) Chris@49:	Chris@49:	Chris@49: iterator referring to the past-the-end element of the specified slice Chris@49:

Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: cube X = randu<cube>(2,3,4);
Chris@49: 
Chris@49: 
Chris@49: cube::iterator a = X.begin();
Chris@49: cube::iterator b = X.end();
Chris@49: 
Chris@49: for(cube::iterator i=a; i!=b; ++i)
Chris@49:   {
Chris@49:   cout << *i << endl;
Chris@49:   }
Chris@49: 
Chris@49: 
Chris@49: cube::slice_iterator c = X.begin_slice(1);  // start of slice 1
Chris@49: cube::slice_iterator d = X.end_slice(2);    // end of slice 2
Chris@49: 
Chris@49: for(cube::slice_iterator i=c; i!=d; ++i)
Chris@49:   {
Chris@49:   cout << *i << endl;
Chris@49:   (*i) = 123.0;
Chris@49:   }
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- iterator at cplusplus.com
- element access
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .memptr() Chris@49:

Chris@49: Member function of Mat, Col, Row and Cube classes Chris@49:

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

Chris@49: The function can be used for interfacing with libraries such as FFTW Chris@49:

Chris@49: As soon as the size of the matrix/vector/cube is changed, the pointer is no longer valid Chris@49:

Chris@49: Data for matrices is stored in a column-by-column order Chris@49:

Chris@49: Data for cubes is stored in a slice-by-slice (matrix-by-matrix) order Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- .colptr()
- element_access
- iterators (matrices)
- iterators (cubes)
- advanced constructors (matrices)
- advanced constructors (cubes)
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49:

.min()	Chris@49:	(member functions of Mat, Col, Row, Cube) Chris@49:
.max()	Chris@49:	Chris@49:
	Chris@49:	Chris@49:
.min( index_of_min_val )	Chris@49:	(member functions of Mat, Col, Row, Cube) Chris@49:
.max( index_of_max_val )	Chris@49:	Chris@49:
	Chris@49:	Chris@49:
.min( row_of_min_val, col_of_min_val )	Chris@49:	(member functions of Mat) Chris@49:
.max( row_of_max_val, col_of_max_val )	Chris@49:	Chris@49:
	Chris@49:	Chris@49:
.min( row_of_min_val, col_of_min_val, slice_of_min_val )	Chris@49:	(member functions of Cube) Chris@49:
.max( row_of_max_val, col_of_max_val, slice_of_max_val )	Chris@49:	Chris@49:

Chris@49:

Chris@49: Without arguments: return the extremum value of an object Chris@49:

Chris@49: 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) Chris@49:

Chris@49: The provided variables must be of type uword. Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- min() & max() (standalone functions)
- running_stat
- running_stat_vec
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .ones() Chris@49:
.ones(n_elem) Chris@49:
.ones(n_rows, n_cols) Chris@49:
.ones(n_rows, n_cols, n_slices) Chris@49:

Chris@49: Set the elements of an object to one, optionally first resizing to specified dimensions Chris@49:

Chris@49: .ones() and .ones(n_elem) are member functions of Col and Row Chris@49:

Chris@49: .ones() and .ones(n_rows, n_cols) are member functions of Mat Chris@49:

Chris@49: .ones() and .ones(n_rows, n_cols, n_slices) are member functions of Cube Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- ones() (standalone function)
- .eye()
- .zeros()
- .fill()
- .imbue()
- .randu()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: operators: + - * / % == != <= >= < > Chris@49:

Chris@49: Overloaded operators for mat, vec, rowvec and cube classes Chris@49:

Chris@49: Meanings: Chris@49:
Chris@49:
Chris@49:

+	Chris@49:	Addition of two objects
-	Chris@49:	Subtraction of one object from another or negation of an object
/	Chris@49:	Element-wise division of an object by another object or a scalar
*	Chris@49:	Matrix multiplication of two objects; not applicable to the cube class unless multiplying a cube by a scalar
%	Chris@49:	Schur product: element-wise multiplication of two objects
==	Chris@49:	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)
!=	Chris@49:	Element-wise non-equality evaluation of two objects
>=	Chris@49:	As for ==, but the check is for "greater than or equal to"
<=	Chris@49:	As for ==, but the check is for "less than or equal to"
>	Chris@49:	As for ==, but the check is for "greater than"
<	Chris@49:	As for ==, but the check is for "less than"

Chris@49:

Chris@49: A std::logic_error exception is thrown if incompatible object sizes are used Chris@49:

Chris@49: If the +, - and % operators are chained, Armadillo will try to avoid the generation of temporaries; Chris@49: no temporaries are generated if all given objects are of the same type and size Chris@49:

Chris@49: If the * operator is chained, Armadillo will try to find an efficient ordering of the matrix multiplications Chris@49:

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

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,10);
Chris@49: mat B = randu<mat>(5,10);
Chris@49: mat C = randu<mat>(10,5);
Chris@49: 
Chris@49: mat P = A + B;
Chris@49: mat Q = A - B;
Chris@49: mat R = -B;
Chris@49: mat S = A / 123.0;
Chris@49: mat T = A % B;
Chris@49: mat U = A * C;
Chris@49: 
Chris@49: // V is constructed without temporaries
Chris@49: mat V = A + B + A + B;
Chris@49: 
Chris@49: imat AA = "1 2 3; 4 5 6; 7 8 9;";
Chris@49: imat BB = "3 2 1; 6 5 4; 9 8 7;";
Chris@49: 
Chris@49: // compare elements
Chris@49: umat ZZ = (AA >= BB);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- accu()
- as_scalar()
- find()
- .transform()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .print(header="") Chris@49:
.print(stream, header="") Chris@49:

Chris@49: Member function of Mat, Col, Row, Cube and field Chris@49:

Chris@49: The first form prints the contents of an object to the std::cout stream, with an optional header line Chris@49:

Chris@49: The second form prints to a user specified stream Chris@49:

Chris@49: It's also possible to print objects using the << stream operator Chris@49:

Chris@49: Elements of a field can only be printed if there is an associated operator<< function defined Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: mat B = randu<mat>(6,6);
Chris@49: 
Chris@49: A.print();
Chris@49: 
Chris@49: // print a transposed version of A
Chris@49: A.t().print();
Chris@49: 
Chris@49: // "B:" is the optional header line
Chris@49: B.print("B:");
Chris@49: 
Chris@49: cout << A << endl;
Chris@49: cout << "B:" << endl << B << endl;
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .raw_print()
- saving & loading matrices
- initialising elements
- logging of errors and warnings
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .raw_print(header="") Chris@49:
.raw_print(stream, header="") Chris@49:

Chris@49: Member function of Mat, Col, Row and Cube Chris@49:

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

Chris@49: If the cell width is set to zero, a space is printed between the elements Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: .randu() Chris@49:
.randu(n_elem) Chris@49:
.randu(n_rows, n_cols) Chris@49:
.randu(n_rows, n_cols, n_slices) Chris@49:
Chris@49:
Chris@49: .randn() Chris@49:
.randn(n_elem) Chris@49:
.randn(n_rows, n_cols) Chris@49:
.randn(n_rows, n_cols, n_slices) Chris@49:

Chris@49: Fill an object with random values, optionally first resizing to specified dimensions Chris@49:

.randu() uses a uniform distribution in the [0,1] interval Chris@49:

.randn() uses a normal/Gaussian distribution with zero mean and unit variance Chris@49:

Chris@49: To change the seed, use the std::srand() function Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A(4,5);
Chris@49: A.randu();
Chris@49: 
Chris@49: mat B;
Chris@49: B.randu(6,7);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- randu() & randn() (standalone functions)
- .fill()
- .imbue()
- .ones()
- .zeros()
- std::srand()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: .reset() Chris@49: Chris@49:

Chris@49: Member function of Mat, Col, Row, Cube and field Chris@49:

Chris@49: Causes an object to have no elements Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5, 5);
Chris@49: A.reset();
Chris@49:

Chris@49:

See also: Chris@49:
- .set_size()
- .is_empty()
- .zeros()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49:

.reshape(n_rows, n_cols, dim=0)	Chris@49:	(member function of Mat, Col, Row) Chris@49:
.reshape(n_rows, n_cols, n_slices, dim=0)	Chris@49:	(member function of Cube) Chris@49:

Chris@49:
Chris@49:

Chris@49: Recreate the object according to given size specifications, Chris@49: with the elements taken from the previous version of the object, Chris@49: either column-wise (dim=0) or row-wise (dim=1); Chris@49: the elements in the generated object are placed column-wise (ie. the first column is filled up before filling the second column) Chris@49:

Chris@49: The layout of the elements in the recreated object will be different to the layout in the previous version of the object Chris@49:

Chris@49: This function can be used to vectorise a matrix (ie. concatenate all the columns or rows) Chris@49:

Chris@49: 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 Chris@49:

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

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

Chris@49: Caveat: Chris@49: .reshape() is slower than .set_size(), which doesn't preserve data Chris@49:

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

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(4,5);
Chris@49: A.reshape(5,4);
Chris@49: 
Chris@49: // vectorise A into a column vector:
Chris@49: A.reshape(A.n_elem, 1);
Chris@49:

Chris@49:

See also: Chris@49:
- .resize()
- .set_size()
- .copy_size()
- .zeros()
- .reset()
- reshape() (standalone function)
Chris@49:

Chris@49:
Chris@49:

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

Chris@49:
Chris@49:

Chris@49: Recreate the object according to given size specifications, while preserving the elements as well as the layout of the elements Chris@49:

Chris@49: Can be used for growing or shrinking an object (ie. adding/removing rows, and/or columns, and/or slices) Chris@49:

Chris@49: Caveat: Chris@49: .resize() is slower than .set_size(), which doesn't preserve data Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(4,5);
Chris@49: A.resize(7,6);
Chris@49:

Chris@49:

Chris@49: This function was added in version 2.4 Chris@49:

See also: Chris@49:
- .reshape()
- .set_size()
- .copy_size()
- .zeros()
- .reset()
- insert rows/cols/slices
- shed rows/cols/slices
- resize() (standalone function)
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: .save(name, file_type = arma_binary) Chris@49:
Chris@49: .save(stream, file_type = arma_binary) Chris@49:
Chris@49:
Chris@49: .load(name, file_type = auto_detect) Chris@49:
Chris@49: .load(stream, file_type = auto_detect) Chris@49:
Chris@49:
Chris@49: .quiet_save(name, file_type = arma_binary) Chris@49:
Chris@49: .quiet_save(stream, file_type = arma_binary) Chris@49:
Chris@49:
Chris@49: .quiet_load(name, file_type = auto_detect) Chris@49:
Chris@49: .quiet_load(stream, file_type = auto_detect) Chris@49: Chris@49:

Member functions of Mat, Col, Row and Cube classes

Store/retrieve data in files or streams

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

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

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

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

Chris@49: The following file formats are supported: Chris@49:
Chris@49:
Chris@49:

auto_detect	Chris@49:	Chris@49: for load() and quiet_load(): Chris@49: try to automatically detect the file type as one of the formats described below. Chris@49: This is the default operation. Chris@49: Chris@49: Chris@49:
raw_ascii	Chris@49:	Chris@49: Numerical data stored in raw ASCII format, without a header. Chris@49: The numbers are separated by whitespace. Chris@49: The number of columns must be the same in each row. Chris@49: Cubes are loaded as one slice. Chris@49: Data which was saved in Matlab/Octave using the -ascii option can be read in Armadillo, except for complex numbers. Chris@49: 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. Chris@49: Chris@49: Chris@49:
raw_binary	Chris@49:	Chris@49: Numerical data stored in machine dependent raw binary format, without a header. Chris@49: Matrices are loaded to have one column, Chris@49: while cubes are loaded to have one slice with one column. Chris@49: The .reshape() function can be used to alter the size of the loaded matrix/cube without losing data. Chris@49: Chris@49: Chris@49:
arma_ascii	Chris@49:	Chris@49: Numerical data stored in human readable text format, with a simple header to speed up loading. Chris@49: The header indicates the type of matrix as well as the number of rows and columns. Chris@49: For cubes, the header additionally specifies the number of slices. Chris@49: Chris@49: Chris@49:
arma_binary	Chris@49:	Chris@49: Numerical data stored in machine dependent binary format, with a simple header to speed up loading. Chris@49: The header indicates the type of matrix as well as the number of rows and columns. Chris@49: For cubes, the header additionally specifies the number of slices. Chris@49: Chris@49: Chris@49:
csv_ascii	Chris@49:	Chris@49: Numerical data stored in comma separated value (CSV) text format, without a header. Chris@49: Applicable to Mat only. Chris@49: Chris@49: Chris@49:
hdf5_binary	Chris@49:	Chris@49: Numerical data stored in portable HDF5 binary format. Chris@49: Chris@49: Caveat: Chris@49: support for HDF5 must be enabled within Armadillo's configuration; Chris@49: the hdf5.h header file must be available on your system and you will need to link with the hdf5 library (eg. -lhdf5). Chris@49: Support for saving & loading of Cube objects was added in version 3.830. Chris@49: Chris@49: Chris@49:
pgm_binary	Chris@49:	Chris@49: Image data stored in Portable Gray Map (PGM) format. Chris@49: Applicable to Mat only. Chris@49: Saving int, float or double matrices is a lossy operation, as each element is copied and converted to an 8 bit representation. Chris@49: As such the matrix should have values in the [0,255] interval, otherwise the resulting image may not display correctly. Chris@49: Chris@49: Chris@49:
ppm_binary	Chris@49:	Chris@49: Image data stored in Portable Pixel Map (PPM) format. Chris@49: Applicable to Cube only. Chris@49: Saving int, float or double matrices is a lossy operation, as each element is copied and converted to an 8 bit representation. Chris@49: As such the cube/field should have values in the [0,255] interval, otherwise the resulting image may not display correctly. Chris@49:

Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: 
Chris@49: A.save("A1.mat");  // default save format is arma_binary
Chris@49: A.save("A2.mat", arma_ascii);
Chris@49: 
Chris@49: mat B;
Chris@49: // automatically detect format type
Chris@49: B.load("A1.mat");
Chris@49: 
Chris@49: mat C;
Chris@49: // force loading in the arma_ascii format
Chris@49: C.load("A2.mat", arma_ascii);
Chris@49: 
Chris@49: 
Chris@49: // example of saving/loading using a stream
Chris@49: std::stringstream s;
Chris@49: A.save(s);
Chris@49: 
Chris@49: mat D;
Chris@49: D.load(s);
Chris@49: 
Chris@49: 
Chris@49: // example of testing for success
Chris@49: mat E;
Chris@49: bool status = E.load("A2.mat");
Chris@49: 
Chris@49: if(status == true)
Chris@49:   {
Chris@49:   cout << "loaded okay" << endl;
Chris@49:   }
Chris@49: else
Chris@49:   {
Chris@49:   cout << "problem with loading" << endl;
Chris@49:   }
Chris@49:

Chris@49:

See also: Chris@49:
- saving/loading fields
Chris@49:

Chris@49:

Member functions of the field class

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

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

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

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

Chris@49: Fields with objects of type std::string are saved and loaded as raw text files. Chris@49: The text files do not have a header. Chris@49: Each string is separated by a whitespace. Chris@49: load() and quiet_load() will only accept text files that have the same number of strings on each line. Chris@49: The strings can have variable lengths. Chris@49:

Chris@49: Other than storing string fields as text files, the following file formats are supported: Chris@49:
Chris@49:
Chris@49:

auto_detect	Chris@49:	Chris@49: Chris@49: Chris@49: load(): try to automatically detect the field format type as one of the formats described below. Chris@49: This is the default operation. Chris@49: Chris@49: Chris@49:
arma_binary	Chris@49:	Chris@49: Chris@49: Chris@49: Objects are stored in machine dependent binary format. Chris@49: Chris@49: Default type for fields of type Mat, Col or Row. Chris@49: Chris@49: Chris@49: Only applicable to fields of type Mat, Col or Row. Chris@49: Chris@49: Chris@49:
ppm_binary	Chris@49:	Chris@49: Chris@49: Chris@49: Image data stored in Portable Pixmap Map (PPM) format. Chris@49: Chris@49: Chris@49: Only applicable to fields of type Mat, Col or Row. Chris@49: Chris@49: Chris@49: .load(): Loads the specified image and stores the red, green and blue components as three separate matrices. Chris@49: The resulting field is comprised of the three matrices, Chris@49: with the red, green and blue components in the first, second and third matrix, respectively. Chris@49: Chris@49: Chris@49: .save(): Saves a field with exactly three matrices of equal size as an image. Chris@49: It is assumed that the red, green and blue components are stored in the first, second and third matrix, respectively. Chris@49: Saving int, float or double matrices is a lossy operation, Chris@49: as each matrix element is copied and converted to an 8 bit representation. Chris@49: Chris@49: Chris@49:

Chris@49:

See also: Chris@49:
- saving/loading matrices and cubes
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .set_imag(X) Chris@49:
Chris@49: .set_real(X) Chris@49:
Chris@49:

Member functions of Mat, Col, Row and Cube

Chris@49: Set the imaginary/real part of an object Chris@49:

Chris@49: X must have the same size as the recipient object Chris@49:

Chris@49: Examples: Chris@49:

Chris@49:    mat A = randu<mat>(4,5);
Chris@49:    mat B = randu<mat>(4,5);
Chris@49: 
Chris@49: cx_mat C = zeros<cx_mat>(4,5);
Chris@49: 
Chris@49: C.set_real(A);
Chris@49: C.set_imag(B);
Chris@49:

Chris@49:

Chris@49: Caveat: Chris@49: if you want to directly construct a complex matrix out of two real matrices, Chris@49: the following code is faster: Chris@49:
Chris@49:

See also: Chris@49:
- matrix constructors
- cube constructors
- imag() / real()
Chris@49:

Chris@49:

.set_size(n_elem)	Chris@49:	(member function of Col, Row, and field) Chris@49:
.set_size(n_rows, n_cols)	Chris@49:	(member function of Mat and field) Chris@49:
.set_size(n_rows, n_cols, n_slices)	Chris@49:	(member function of Cube) Chris@49:

Chris@49:
Chris@49:

Changes the size of an object

Chris@49: If the requested number of elements is equal to the old number of elements, existing memory is reused Chris@49:

Chris@49: If the requested number of elements is not equal to the old number of elements, new memory is used; Chris@49: the memory is uninitilised Chris@49:

Chris@49: If you need to initialise the memory, use .zeros() instead Chris@49:

Chris@49: If you need to explicitly preserve data, use .reshape() or .resize() Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A;
Chris@49: A.set_size(5,10);
Chris@49: 
Chris@49: vec q;
Chris@49: q.set_size(100);
Chris@49:

Chris@49:

See also: Chris@49:
- .reset()
- .copy_size()
- .reshape()
- .resize()
- .zeros()
Chris@49:

Chris@49:
Chris@49:

Chris@49: .shed_row( row_number ) Chris@49: Chris@49: .shed_rows( first_row, last_row ) Chris@49:		(member functions of Mat and Col) Chris@49:

Chris@49: .shed_col( column_number ) Chris@49: Chris@49: .shed_cols( first_column, last_column ) Chris@49:		(member functions of Mat and Row) Chris@49:

Chris@49: .shed_slice( slice_number ) Chris@49: Chris@49: .shed_slices( first_slice, last_slice ) Chris@49:		(member functions of Cube) Chris@49:

Chris@49:
Chris@49:

Chris@49: Single argument functions: Chris@49: remove the specified row/column/slice Chris@49:

Chris@49: Two argument functions: Chris@49: remove the specified range of rows/columns/slices Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,10);
Chris@49: 
Chris@49: A.shed_row(2);
Chris@49: A.shed_cols(2,4);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- insert rows/columns/slices
- join rows/columns/slices
- .resize()
- submatrix views
- subcube views
- shed in thesaurus.com
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: STL container functions Chris@49:

Mat, Col and Row classes provide the following member functions that mimic the containers in the C++ Standard Template Library:
Chris@49:
Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49:

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

Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: cout << A.size() << endl;
Chris@49: 
Chris@49: A.clear();
Chris@49: cout << A.empty() << endl;
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- iterators (matrices)
- matrix and vector attributes
- .is_empty()
- .reset()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: submatrix views Chris@49:

A collection of member functions of Mat, Col and Row classes that provide read/write access to submatrix views
Chris@49:
Chris@49:
For a matrix or vector X, the subviews are accessed as:

contiguous views: Chris@49:
Chris@49:

non-contiguous views (added in version 3.0): Chris@49:
Chris@49:

Chris@49: Instances of span::all, to indicate an entire range, can be replaced by span(), where no number is specified Chris@49:

Chris@49: For functions requiring one or more vector of indices, Chris@49: eg. X.submat(vector_of_row_indices,vector_of_column_indices), Chris@49: each vector of indices must be of type uvec. Chris@49:

Chris@49: In the function X.elem(vector_of_indices), Chris@49: elements specified in vector_of_indices are accessed. Chris@49: X is interpreted as one long vector, Chris@49: with column-by-column ordering of the elements of X. Chris@49: The vector_of_indices must evaluate to be a vector of type uvec Chris@49: (eg., generated by find()). Chris@49: The aggregate set of the specified elements is treated as a column vector Chris@49: (eg., the output of X.elem() is always a column vector). Chris@49:

Chris@49: The function .unsafe_col() is provided for speed reasons and should be used only if you know what you're doing. Chris@49: The function creates a seemingly independent Col vector object (eg. vec), Chris@49: but the vector actually uses memory from the existing matrix object. Chris@49: As such, the created Col vector is currently not alias safe Chris@49: and does not take into account that the parent matrix object could be deleted. Chris@49: If deleted memory is accessed through the created Col vector, Chris@49: it will cause memory corruption and/or a crash. Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = zeros<mat>(5,10);
Chris@49: 
Chris@49: A.submat(0,1,2,3) = randu<mat>(3,3);
Chris@49: 
Chris@49: // the following three statements
Chris@49: // access the same part of A
Chris@49: mat B = A.submat(0,1,2,3);
Chris@49: mat C = A.submat( span(0,2), span(1,3) );
Chris@49: mat D = A( span(0,2), span(1,3) );
Chris@49: 
Chris@49: // the following two statements
Chris@49: // access the same part of A
Chris@49: A.col(1)        = randu<mat>(5,1);
Chris@49: A(span::all, 1) = randu<mat>(5,1);
Chris@49: 
Chris@49: mat X = randu<mat>(5,5);
Chris@49: 
Chris@49: // get all elements of X that are greater than 0.5
Chris@49: vec q = X.elem( find(X > 0.5) );
Chris@49: 
Chris@49: // set four specific elements of X to 1
Chris@49: uvec indices;
Chris@49: indices << 2 << 3 << 6 << 8;
Chris@49: 
Chris@49: X.elem(indices) = ones<vec>(4);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- diagonal views (read/write access to diagonals)
- .each_col() & .each_row() (vector operations repeated on each column or row)
- .colptr()
- .in_range()
- find()
- join rows/columns/slices
- shed rows/columns/slices
- insert rows/columns/slices
- subcube views
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: subcube views and slices Chris@49:

A collection of member functions of the Cube class that provide subcube views
Chris@49:
Chris@49:
For a cube Q, the subviews are accessed as:

slice(

)

slices(

)

subcube(

)

subcube( span(

), span(

) )

( span(

), span(

) )

Chris@49: Instances of span(a,b) can be replaced by: Chris@49:
- span() or span::all, to indicate the entire range
- span(a), to indicate a particular row, column or slice
Chris@49:

Chris@49: An individual slice, accessed via .slice(), is an instance of the Mat class Chris@49: (a reference to a matrix is provided) Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: cube A = randu<cube>(2,3,4);
Chris@49: mat B = A.slice(1);
Chris@49: 
Chris@49: A.slice(0) = randu<mat>(2,3);
Chris@49: A.slice(0)(1,2) = 99.0;
Chris@49: 
Chris@49: A.subcube(0,0,1,  1,1,2) = randu<cube>(2,2,2);
Chris@49: A( span(0,1), span(0,1), span(1,2) ) = randu<cube>(2,2,2);
Chris@49: 
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .in_range()
- join slices
- shed slices
- insert slices
- submatrix views
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: subfield views Chris@49:

A collection of member functions of the field class that provide subfield views
Chris@49:
Chris@49:
For a field F, the subfields are accessed as:

row(

)

col(

)

rows(

)

cols(

)

subfield(

)

subfield( span(

), span(

) )

( span(

), span(

) )

Chris@49: Instances of span(a,b) can be replaced by: Chris@49:
- span() or span::all, to indicate the entire range
- span(a), to indicate a particular row or column
Chris@49:

Chris@49: See also: Chris@49:
- .in_range()
- submatrix views
- subcube views
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .swap(X) Chris@49:

Chris@49: Swap contents with matrix X Chris@49:

Chris@49: This function was added in version 3.800 Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = zeros<mat>(4,5);
Chris@49: mat B =  ones<mat>(6,7);
Chris@49: 
Chris@49: A.swap(B);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .swap_rows() & .swap_cols()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: .swap_rows(row1, row2) Chris@49:
.swap_cols(col1, col2) Chris@49: Chris@49:

Chris@49: Member functions of Mat, Col and Row classes Chris@49:

Chris@49: Swap the contents of specified rows or columns Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat X = randu<mat>(5,5);
Chris@49: X.swap_rows(0,4);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- fliplr() & flipud()
- .swap()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: .t() Chris@49:
.st() Chris@49: Chris@49:

Chris@49: Member functions of any matrix or vector expression Chris@49:

Chris@49: .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) Chris@49:

Chris@49: .st() provides a transposed copy of the object, without taking the conjugate of the elements (complex matrices) Chris@49:

Chris@49: For non-complex objects, the .t() and .st() functions are equivalent Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(4,5);
Chris@49: mat B = A.t();
Chris@49:

Chris@49:

Chris@49: The .t() and .st() functions were added in version 2.4 Chris@49:

Chris@49: See also: Chris@49:
- trans()
- strans()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .transform( functor ) Chris@49:
Chris@49: .transform( lambda function ) (C++11 only) Chris@49:
Chris@49:

Chris@49: Transform each element using a functor or lambda function Chris@49:

Chris@49: For matrices, transformation is done column-by-column (ie. column 0 is transformed, then column 1, ...) Chris@49:

Chris@49: For cubes, transformation is done slice-by-slice; each slice is transformed column-by-column Chris@49:

Chris@49: This function was added in version 3.800 Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- overloaded operators
- .imbue()
- .fill()
- function object at Wikipedia
- C++11 lambda functions at Wikipedia
- lambda function at cprogramming.com
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: .zeros() Chris@49:
.zeros(n_elem) Chris@49:
.zeros(n_rows, n_cols) Chris@49:
.zeros(n_rows, n_cols, n_slices) Chris@49:

Chris@49: Set the elements of an object to zero, optionally first resizing to specified dimensions Chris@49:

Chris@49: .zeros() and .zeros(n_elem) are member function of Col and Row Chris@49:

Chris@49: .zeros() and .zeros(n_rows, n_cols) are member functions of Mat Chris@49:

Chris@49: .zeros() and .zeros(n_rows, n_cols, n_slices) are member functions of Cube Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- zeros() (standalone function)
- .ones()
- .randu()
- .fill()
- .imbue()
- .reset()
- .set_size()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49:

Chris@49:
Chris@49:
Chris@49: Other Classes Chris@49:
Chris@49:
Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: running_stat<type> Chris@49:

Chris@49: Class for keeping statistics of a continuously sampled one dimensional process/signal. Chris@49: Useful if the storage of individual samples (scalars) is not necessary or desired. Chris@49: Also useful if the number of samples is not known beforehand or exceeds available memory. Chris@49:

Chris@49: type should be one of: float, double, cx_float, cx_double Chris@49:

Chris@49: Member functions: Chris@49:

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

Chris@49:

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

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

Chris@49: Examples: Chris@49:

Chris@49: running_stat<double> stats;
Chris@49: 
Chris@49: for(uword i=0; i<10000; ++i)
Chris@49:   {
Chris@49:   double sample = double(rand())/RAND_MAX;
Chris@49:   stats(sample);
Chris@49:   }
Chris@49: 
Chris@49: cout << "mean = " << stats.mean() << endl;
Chris@49: cout << "var  = " << stats.var()  << endl;
Chris@49: cout << "min  = " << stats.min()  << endl;
Chris@49: cout << "max  = " << stats.max()  << endl;
Chris@49:

Chris@49:

See also: Chris@49:
- statistics functions
- running_stat_vec
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: running_stat_vec<type>(calc_cov = false) Chris@49:

Chris@49: Class for keeping statistics of a continuously sampled multi-dimensional process/signal. Chris@49: Useful if the storage of individual samples is not necessary or desired. Chris@49: Also useful if the number of samples is not known beforehand or exceeds available memory. Chris@49:

Chris@49: This class is similar to running_stat, with the difference being that vectors are processed instead of single values. Chris@49:

Chris@49: type must match the element type used by the sample vectors Chris@49: (ie. it must be one of float, double, cx_float, cx_double) Chris@49:

Chris@49: type can be inferred via the use of the elem_type member typedef of a vector class. Chris@49: For example, fvec::elem_type will be interpreted as float, Chris@49: while cx_vec::elem_type will be interpreted as cx_double. Chris@49:

Chris@49: Member functions: Chris@49:

Chris@49: .operator()(vector) Chris@49:	Chris@49:	Chris@49: update the statistics so far using the given vector Chris@49:
Chris@49: .mean() Chris@49:	Chris@49:	Chris@49: get the mean vector so far Chris@49:
Chris@49: .var(norm_type=0) Chris@49:	Chris@49:	Chris@49: get the vector of variances so far Chris@49:
Chris@49: .stddev(norm_type=0) Chris@49:	Chris@49:	Chris@49: get the vector of standard deviations so far Chris@49:
Chris@49: .min() Chris@49:	Chris@49:	Chris@49: get the vector of minimum values so far Chris@49:
Chris@49: .max() Chris@49:	Chris@49:	Chris@49: get the vector of maximum values so far Chris@49:
Chris@49: .cov(norm_type=0) Chris@49:	Chris@49:	Chris@49: get the covariance matrix so far Chris@49: NOTE: this only works if calc_cov is set to true during the construction of the class Chris@49:
Chris@49: .reset() Chris@49:	Chris@49:	Chris@49: reset all statistics and set the number of samples to zero Chris@49:
Chris@49: .count() Chris@49:	Chris@49:	Chris@49: get the number of samples so far Chris@49:

Chris@49:

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

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

Chris@49: Examples: Chris@49:

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

Chris@49:

See also: Chris@49:
- cov()
- cor()
- running_stat
- statistics functions
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: wall_clock Chris@49:

Chris@49: Simple wall clock timer class, for measuring the number of elapsed seconds between two intervals Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: wall_clock timer;
Chris@49: 
Chris@49: mat A = randu<mat>(4,4);
Chris@49: mat B = randu<mat>(4,4);
Chris@49: mat C;
Chris@49: 
Chris@49: timer.tic();
Chris@49: for(uword i=0; i<100000; ++i)
Chris@49:   C = A + B + A + B;
Chris@49: 
Chris@49: double n_secs = timer.toc();
Chris@49: cout << "took " << n_secs << " seconds" << endl;
Chris@49:

Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49:

Chris@49:
Chris@49:
Chris@49: Generated Vectors/Matrices Chris@49:
Chris@49:
Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: eye(n_rows, n_cols) Chris@49:

Chris@49: Generate a matrix with the elements along the main diagonal set to one Chris@49: and off-diagonal elements set to zero Chris@49:

Chris@49: An identity matrix is generated when n_rows = n_cols Chris@49:

Chris@49: Usage: Chris@49:
- Chris@49: matrix_type X = eye<matrix_type>(n_rows, n_cols) Chris@49:
Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = eye<mat>(5,5);
Chris@49: mat B = 123.0 * eye<mat>(5,5);
Chris@49:

Chris@49:

See also: Chris@49:
- .eye() (member function of Mat)
- .diag()
- ones()
- diagmat()
- diagvec()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: linspace(start, end, N=100) Chris@49:

Chris@49: Generate a vector with N elements; Chris@49: the values of the elements linearly increase from start upto (and including) end Chris@49:
Chris@49:

Chris@49: Usage: Chris@49:
- vector_type v = linspace<vector_type>(start, end, N)
- matrix_type X = linspace<matrix_type>(start, end, N)
Chris@49:

Chris@49: If a matrix_type is specified, the resultant matrix will have one column Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: vec v = linspace<vec>(10, 20, 5);
Chris@49: mat X = linspace<mat>(10, 20, 5);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- ones()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: ones(n_elem) Chris@49:
ones(n_rows, n_cols) Chris@49:
ones(n_rows, n_cols, n_slices) Chris@49: Chris@49:

Chris@49: Generate a vector, matrix or cube with all elements set to one Chris@49:

Chris@49: Usage: Chris@49:
- 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)
Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: vec  v = ones<vec>(10);
Chris@49: uvec u = ones<uvec>(11);
Chris@49: mat  A = ones<mat>(5,6);
Chris@49: cube Q = ones<cube>(5,6,7);
Chris@49: 
Chris@49: mat  B = 123.0 * ones<mat>(5,6);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .ones() (member function of Mat, Col, Row and Cube)
- eye()
- linspace()
- zeros()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: randu(n_elem) Chris@49:
randu(n_rows, n_cols) Chris@49:
randu(n_rows, n_cols, n_slices) Chris@49:
Chris@49:
randn(n_elem) Chris@49:
randn(n_rows, n_cols) Chris@49:
randn(n_rows, n_cols, n_slices) Chris@49:

Chris@49: Generate a vector, matrix or cube with the elements set to random values Chris@49:

randu() uses a uniform distribution in the [0,1] interval Chris@49:

randn() uses a normal/Gaussian distribution with zero mean and unit variance Chris@49:

Chris@49: Usage: Chris@49:
- 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)
Chris@49:

Chris@49: To change the seed, use the std::srand() function. Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: vec  v = randu<vec>(5);
Chris@49: mat  A = randu<mat>(5,6);
Chris@49: cube Q = randu<cube>(5,6,7);
Chris@49:

Chris@49:

See also: Chris@49:
- .randu() & .randn() (member functions)
- .imbue()
- ones()
- zeros()
- shuffle()
- std::srand()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: repmat(A, num_copies_per_row, num_copies_per_col) Chris@49:

Generate a matrix by replicating matrix A in a block-like fashion

The generated matrix has the following size: Chris@49:
Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(2, 3);
Chris@49: 
Chris@49: mat B = repmat(A, 4, 5);
Chris@49:

Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: speye(n_rows, n_cols) Chris@49:

Chris@49: Generate a sparse matrix with the elements along the main diagonal set to one Chris@49: and off-diagonal elements set to zero Chris@49:

Chris@49: An identity matrix is generated when n_rows = n_cols Chris@49:

Chris@49: Usage: Chris@49:
- Chris@49: sparse_matrix_type X = speye<sparse_matrix_type>(n_rows, n_cols) Chris@49:
Chris@49:

Chris@49: Examples: Chris@49:
Chris@49:

See also: Chris@49:
- sprandu()/sprandn()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: sprandu(n_rows, n_cols, density) Chris@49:
sprandn(n_rows, n_cols, density) Chris@49:

Chris@49: Generate a sparse matrix with the non-zero elements set to random values Chris@49:

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

sprandu() uses a uniform distribution in the [0,1] interval Chris@49:

sprandn() uses a normal/Gaussian distribution with zero mean and unit variance Chris@49:

Chris@49: Usage: Chris@49:
- sparse_matrix_type X = sprandu<sparse_matrix_type>(n_rows, n_cols, density)
Chris@49:

Chris@49: To change the seed, use the std::srand() function. Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: sp_mat A = sprandu<sp_mat>(100, 200, 0.1);
Chris@49:

Chris@49:

See also: Chris@49:
- speye()
- std::srand()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: toeplitz(A) Chris@49:
toeplitz(A,B) Chris@49:
circ_toeplitz(A) Chris@49:

Chris@49: toeplitz(): generate a Toeplitz matrix, with the first column specified by A, and (optionally) the first row specified by B Chris@49:

Chris@49: circ_toeplitz(): generate a circulant Toeplitz matrix Chris@49:

Chris@49: A and B must be vectors Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: vec A = randu<vec>(5);
Chris@49: mat X = toeplitz(A);
Chris@49: mat Y = circ_toeplitz(A);
Chris@49:

Chris@49:

See also: Chris@49:
- Toeplitz matrix in MathWorld
- Toeplitz matrix in Wikipedia
- Circulant matrix in Wikipedia
Chris@49:

Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: zeros(n_elem) Chris@49:
zeros(n_rows, n_cols) Chris@49:
zeros(n_rows, n_cols, n_slices) Chris@49:

Chris@49: Generate a vector, matrix or cube with the elements set to zero Chris@49:

Chris@49: Usage: Chris@49:
- 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)
Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: vec  v = zeros<vec>(10);
Chris@49: uvec u = zeros<uvec>(11);
Chris@49: mat  A = zeros<mat>(5,6);
Chris@49: cube Q = zeros<cube>(5,6,7);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .zeros() (member function of Mat, Col, Row and Cube)
- .ones() (member function of Mat, Col, Row and Cube)
- ones()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49:

Chris@49:
Chris@49:
Chris@49: Functions Individually Applied to Each Element of a Matrix/Cube Chris@49:
Chris@49:
Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: abs(mat) Chris@49:
abs(cube) Chris@49:
abs(cx_mat) Chris@49:
abs(cx_cube) Chris@49:

Chris@49: Obtain the magnitude of each element Chris@49:

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

Chris@49: Usage for non-complex cubes: Chris@49:
- cube_type Y = abs(X)
- X and Y must have the same cube_type
Chris@49:

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

Chris@49: Usage for complex cubes: Chris@49:
- non_complex_cube_type Y = abs(X)
- X must be a have complex cube type, eg., cx_cube or cx_fcube
- The type of Y must be related to the type of X, Chris@49: eg., if X has the type cx_cube, then the type of Y must be cube Chris@49:
Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: mat B = abs(A); 
Chris@49: 
Chris@49: cx_mat X = randu<cx_mat>(5,5);
Chris@49: mat    Y = abs(X);
Chris@49:

Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: eps(X) Chris@49:

Chris@49: Obtain the positive distance of the absolute value of each element of X to the next largest representable floating point number Chris@49:

Chris@49: X can be a scalar (eg. double), vector or matrix Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(4,5);
Chris@49: mat B = eps(A);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- datum::eps
- Floating-Point Arithmetic in MathWorld
- IEEE Standard for Floating-Point Arithmetic in Wikipedia
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: miscellaneous functions: Chris@49:
exp, exp2, exp10, trunc_exp, Chris@49:
log, log2, log10, trunc_log, Chris@49:
pow, sqrt, square Chris@49:
floor, ceil, round Chris@49: Chris@49:
Chris@49:

Chris@49: Apply a function to each element Chris@49:

Chris@49: Usage: Chris@49:

Chris@49: matrix_type B = misc_fn(A) Chris@49:
Chris@49: cube_type B = misc_fn(A) Chris@49:
Chris@49: A and B must have the same matrix_type/cube_type Chris@49:

Chris@49: misc_fn(A) is one of: Chris@49:

Chris@49: exp(A) Chris@49:	Chris@49: Chris@49:	Chris@49: base-e exponential, e^x Chris@49:
Chris@49: exp2(A) Chris@49:	Chris@49: Chris@49:	Chris@49: base-2 exponential, 2^x Chris@49:
Chris@49: exp10(A) Chris@49:	Chris@49: Chris@49:	Chris@49: base-10 exponential, 10^x Chris@49:
Chris@49: trunc_exp(A) Chris@49:	Chris@49: Chris@49:	Chris@49: base-e exponential, Chris@49: truncated to avoid infinity Chris@49: Chris@49: (only for elements with type float or double) Chris@49:
Chris@49: log(A) Chris@49:	Chris@49: Chris@49:	Chris@49: natural log, log_e x Chris@49:
Chris@49: log2(A) Chris@49:	Chris@49: Chris@49:	Chris@49: base-2 log, log₂ x Chris@49:
Chris@49: log10(A) Chris@49:	Chris@49: Chris@49:	Chris@49: base-10 log, log₁₀ x Chris@49:
Chris@49: trunc_log(A) Chris@49:	Chris@49: Chris@49:	Chris@49: natural log, Chris@49: truncated to avoid ±infinity Chris@49: Chris@49: (only for elements with type float or double) Chris@49:
Chris@49: pow(A, p) Chris@49:	Chris@49: Chris@49:	Chris@49: raise to the power of p, x^p Chris@49:
Chris@49: sqrt(A) Chris@49:	Chris@49: Chris@49:	Chris@49: square root, x^½ Chris@49:
Chris@49: square(A) Chris@49:	Chris@49: Chris@49:	Chris@49: square, x² Chris@49:
Chris@49: floor(A) Chris@49:	Chris@49: Chris@49:	Chris@49: largest integral value that is not greater than the input value Chris@49:
Chris@49: ceil(A) Chris@49:	Chris@49: Chris@49:	Chris@49: smallest integral value that is not less than the input value Chris@49:
Chris@49: round(A) Chris@49:	Chris@49: Chris@49:	Chris@49: round to nearest integer, away from zero Chris@49:

Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: mat B = exp(A);
Chris@49:

Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: trigonometric functions (cos, sin, tan, ...) Chris@49:

Chris@49: Apply a trigonometric function to each element Chris@49:

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

Chris@49: Examples: Chris@49:

Chris@49: mat X = randu<mat>(5,5);
Chris@49: mat Y = cos(X);
Chris@49:

Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49:

Chris@49:
Chris@49:
Chris@49: Scalar Valued Functions of Vectors/Matrices/Cubes Chris@49:
Chris@49:
Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: accu(mat) Chris@49:
accu(cube) Chris@49:

Chris@49: Accumulate (sum) all elements Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- sum()
- cumsum()
- as_scalar()
- trace()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: as_scalar(expression) Chris@49:

Chris@49: Evaluate an expression that results in a 1x1 matrix, Chris@49: followed by converting the 1x1 matrix to a pure scalar Chris@49:

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

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- accu()
- conv_to()
- dot()
- norm()
- reshape()
- resize()
- trace()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: det(A, slow=false) Chris@49:

Chris@49: Determinant of square matrix A Chris@49:

Chris@49: If A is not square, a std::logic_error exception is thrown Chris@49:

Chris@49: Caveat: for large matrices you may want to use log_det() instead Chris@49:

Chris@49: For matrix sizes ≤ 4x4, a fast algorithm is used by default. Chris@49: In rare instances, the fast algorithm might be less precise than the standard algorithm. Chris@49: To force the use of the standard algorithm, set the slow argument to true Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat    A = randu<mat>(5,5);
Chris@49: double x = det(A);
Chris@49: 
Chris@49: mat44  B = randu<mat>(4,4);
Chris@49: 
Chris@49: double y = det(B);       // use fast algorithm by default
Chris@49: double z = det(B, true); // use slow algorithm
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- log_det()
- determinant in MathWorld
- determinant in Wikipedia
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: dot(A, B) Chris@49:
cdot(A, B) Chris@49:
norm_dot(A, B) Chris@49:

Chris@49: dot(A,B): dot product of A and B, under the assumption that A and B are vectors with the same number of elements Chris@49:

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

Chris@49: norm_dot(A,B): normalised version of dot(A,B) Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: vec a = randu<vec>(10);
Chris@49: vec b = randu<vec>(10);
Chris@49: 
Chris@49: double x = dot(a,b);
Chris@49:

Chris@49:

See also: Chris@49:
- as_scalar()
- cross()
- conj()
- norm()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: log_det(val, sign, A) Chris@49:

Chris@49: Log determinant of square matrix A, such that the determinant is equal to exp(val)*sign Chris@49:

Chris@49: If A is not square, a std::logic_error exception is thrown Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: 
Chris@49: double val;
Chris@49: double sign;
Chris@49: 
Chris@49: log_det(val, sign, A);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- det()
- determinant in MathWorld
- determinant in Wikipedia
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: norm(X, p) Chris@49: Chris@49:

Chris@49: Compute the p-norm of X, where X can be a vector or a matrix Chris@49:

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

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

Chris@49: "-inf" is the minimum norm, "inf" is the maximum norm, while "fro" is the Frobenius norm Chris@49:

Chris@49: To obtain the zero norm or Hamming norm (ie. the number of non-zero elements), Chris@49: you may want to use this expression: accu(X != 0). Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: vec    q = randu<vec>(5);
Chris@49: double x = norm(q, 2);
Chris@49: double y = norm(q, "inf");
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- dot()
- Vector Norm in Wikipedia
- Vector Norm in MathWorld
- Matrix Norm in Wikipedia
- Matrix Norm in MathWorld
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: rank(X, tolerance = default) Chris@49: Chris@49:

Returns the rank of matrix X

Any singular values less than default tolerance are treated as zero

The default tolerance is max(X.n_rows, X.n_cols)*eps(sigma), Chris@49: where sigma is the largest singular value of X Chris@49:

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

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(4,5);
Chris@49: uword r = rank(A);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- eps()
- Rank in MathWorld
- Rank in Wikipedia
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: trace(X) Chris@49:

Chris@49: Sum of the diagonal elements of square matrix X Chris@49:

Chris@49: If X is an expression, Chris@49: the function will try to use optimised expression evaluations to calculate only the diagonal elements Chris@49:

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

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: double x = trace(A);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- accu()
- as_scalar()
- .diag()
- diagvec()
- sum()
Chris@49:

Chris@49:

Chris@49: Chris@49:

Chris@49:
Chris@49:
Chris@49: Scalar/Vector Valued Functions of Vectors/Matrices Chris@49:
Chris@49:
Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: diagvec(A, k=0) Chris@49:

Chris@49: Extract the k-th diagonal from matrix A Chris@49:

Chris@49: The argument k is optional -- by default the main diagonal is extracted (k=0) Chris@49:

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)

Chris@49: An extracted a diagonal is interpreted as a column vector Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: vec d = diagvec(A);
Chris@49:

Chris@49:

See also: Chris@49:
- .diag()
- diagmat()
- trace()
Chris@49:

Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: min(mat, dim=0) Chris@49:
min(rowvec) Chris@49:
min(colvec) Chris@49:
Chris@49:
max(mat, dim=0) Chris@49:
max(rowvec) Chris@49:
max(colvec) Chris@49:

Chris@49: For a matrix argument, return the extremum value for each column (dim=0), or each row (dim=1) Chris@49:

Chris@49: For a vector argument, return the extremum value Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: colvec q = randu<colvec>(10,1);
Chris@49: double x = max(q);
Chris@49: 
Chris@49: mat    A = randu<mat>(10,10);
Chris@49: rowvec b = max(A);
Chris@49: 
Chris@49: // same result as max(A)
Chris@49: // the 0 explicitly indicates
Chris@49: // "traverse across rows"
Chris@49: rowvec c = max(A,0); 
Chris@49: 
Chris@49: // the 1 explicitly indicates
Chris@49: // "traverse across columns"
Chris@49: colvec d = max(A,1);
Chris@49: 
Chris@49: // find the overall maximum value
Chris@49: double y = max(max(A));
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .min() & .max() (member functions of Mat and Cube)
- running_stat
- running_stat_vec
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: prod(mat, dim=0) Chris@49:
prod(rowvec) Chris@49:
prod(colvec) Chris@49:

Chris@49: For a matrix argument, return the product of elements in each column (dim=0), or each row (dim=1) Chris@49:

Chris@49: For a vector argument, return the product of all elements Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: colvec q = randu<colvec>(10,1);
Chris@49: double x = prod(q);
Chris@49: 
Chris@49: mat    A = randu<mat>(10,10);
Chris@49: rowvec b = prod(A);
Chris@49: 
Chris@49: // same result as prod(A)
Chris@49: // the 0 explicitly indicates
Chris@49: // "traverse across rows"
Chris@49: rowvec c = prod(A,0);
Chris@49: 
Chris@49: // the 1 explicitly indicates
Chris@49: // "traverse across columns"
Chris@49: colvec d = prod(A,1);
Chris@49: 
Chris@49: // find the overall product
Chris@49: double y = prod(prod(A));
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- Schur product
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: sum(mat, dim=0) Chris@49:
sum(rowvec) Chris@49:
sum(colvec) Chris@49:

Chris@49: For a matrix argument, return the sum of elements in each column (dim=0), or each row (dim=1) Chris@49:

Chris@49: For a vector argument, return the sum of all elements Chris@49:

Chris@49: To get a sum of all the elements regardless of the argument type (ie. matrix or vector), Chris@49: you may wish to use accu() instead Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- accu()
- cumsum()
- trace()
- as_scalar()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: statistics: mean, median, stddev, var Chris@49: Chris@49:

Chris@49: mean(mat, dim=0) Chris@49: mean(colvec) Chris@49: mean(rowvec) Chris@49: Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: mean (average value) Chris@49:
Chris@49: median(mat, dim=0) Chris@49: median(colvec) Chris@49: median(rowvec) Chris@49: Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: median Chris@49:
Chris@49: stddev(mat, norm_type=0, dim=0) Chris@49: stddev(colvec, norm_type=0) Chris@49: stddev(rowvec, norm_type=0) Chris@49: Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: standard deviation Chris@49:
Chris@49: var(mat, norm_type=0, dim=0) Chris@49: var(colvec, norm_type=0) Chris@49: var(rowvec, norm_type=0) Chris@49: Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: variance Chris@49:

Chris@49: For a matrix argument, find a particular statistic for each column (dim=0), or each row (dim=1) Chris@49:

Chris@49: For a vector argument, return a particular statistic calculated using all the elements of the vector Chris@49:

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

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- cov()
- cor()
- running_stat
- running_stat_vec
- hist()
- histc()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49:

Chris@49:
Chris@49:
Chris@49: Vector/Matrix/Cube Valued Functions of Vectors/Matrices/Cubes Chris@49:
Chris@49:
Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: Chris@49: C = conv(A, B) Chris@49: Chris@49:

Chris@49: Convolution of vectors A and B Chris@49:

Chris@49: If A and B are polynomial coefficient vectors, convolving them is equivalent to multiplying the two polynomials Chris@49:

Chris@49: The convolution operation is also equivalent to FIR filtering Chris@49:

Chris@49: The orientation of the result vector is the same as the orientation of A (ie. column or row vector) Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: vec A = randu<vec>(128) - 0.5;
Chris@49: vec B = randu<vec>(128) - 0.5;
Chris@49: 
Chris@49: vec C = conv(A,B);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- fft()
- cor()
- Convolution in MathWorld
- Convolution in Wikipedia
- FIR filter in Wikipedia
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: conv_to<type>::from(X) Chris@49: Chris@49:

Chris@49: A form of casting Chris@49:

Chris@49: Convert between matrix/vector types (eg. mat to fmat), as well as cube types (eg. cube to fcube) Chris@49:

Chris@49: Conversion between std::vector and Armadillo matrices/vectors is also possible Chris@49:

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

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- as_scalar()
- reshape()
- resize()
- advanced constructors (matrices)
- advanced constructors (cubes)
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: conj(cx_mat) Chris@49:
conj(cx_cube) Chris@49:

Chris@49: Obtain the complex conjugate of each element in a complex matrix/cube Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: cx_mat X = randu<cx_mat>(5,5);
Chris@49: cx_mat Y = conj(X);
Chris@49:

Chris@49:

See also: Chris@49:
- trans()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: cor(X, Y, norm_type=0) Chris@49:
cor(X, norm_type=0) Chris@49:

Chris@49: For two matrix arguments X and Y, Chris@49: if each row of X and Y is an observation and each column is a variable, Chris@49: 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 Chris@49:

Chris@49: For vector arguments, the type of vector is ignored and each element in the vector is treated as an observation Chris@49:

Chris@49: For matrices, X and Y must have the same dimensions Chris@49:

Chris@49: For vectors, X and Y must have the same number of elements Chris@49:

Chris@49: cor(X) is equivalent to cor(X, X), also called autocorrelation Chris@49:

Chris@49: The default norm_type=0 performs normalisation of the correlation matrix using N-1 (where N is the number of observations). Chris@49: Using norm_type=1 causes normalisation to be done using N Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat X = randu<mat>(4,5);
Chris@49: mat Y = randu<mat>(4,5);
Chris@49: 
Chris@49: mat R = cor(X,Y);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- Correlation in MathWorld
- Autocorrelation in MathWorld
- cov()
- conv()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: cov(X, Y, norm_type=0) Chris@49:
cov(X, norm_type=0) Chris@49:

Chris@49: For two matrix arguments X and Y, Chris@49: if each row of X and Y is an observation and each column is a variable, Chris@49: 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 Chris@49:

Chris@49: For vector arguments, the type of vector is ignored and each element in the vector is treated as an observation Chris@49:

Chris@49: For matrices, X and Y must have the same dimensions Chris@49:

Chris@49: For vectors, X and Y must have the same number of elements Chris@49:

Chris@49: cov(X) is equivalent to cov(X, X) Chris@49:

Chris@49: The default norm_type=0 performs normalisation using N-1 (where N is the number of observations), Chris@49: providing the best unbiased estimation of the covariance matrix (if the observations are from a normal distribution). Chris@49: Using norm_type=1 causes normalisation to be done using N, which provides the second moment matrix of the observations about their mean Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat X = randu<mat>(4,5);
Chris@49: mat Y = randu<mat>(4,5);
Chris@49: 
Chris@49: mat C = cov(X,Y);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- running_stat_vec
- statistics functions
- Covariance in MathWorld
- cor()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: cross(A, B) Chris@49:

Chris@49: Calculate the cross product between A and B, under the assumption that A and B are 3 dimensional vectors Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: vec a = randu<vec>(3);
Chris@49: vec b = randu<vec>(3);
Chris@49: 
Chris@49: vec c = cross(a,b);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- dot()
- Cross product in Wikipedia
- Cross product in MathWorld
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: cumsum(mat, dim=0) Chris@49:
cumsum(rowvec) Chris@49:
cumsum(colvec) Chris@49:

Chris@49: For a matrix argument, return a matrix containing the cumulative sum of elements in each column (dim=0, the default), or each row (dim=1) Chris@49:

Chris@49: For a vector argument, return a vector of the same orientation, containing the cumulative sum of elements Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: mat B = cumsum(A);
Chris@49: 
Chris@49: vec x = randu<vec>(10);
Chris@49: vec y = cumsum(x);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- accu()
- sum()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: diagmat(X) Chris@49:

Chris@49: Interpret a matrix or vector X as a diagonal matrix Chris@49:

Chris@49: 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 Chris@49:

Chris@49: 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 Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

Chris@49: See also: Chris@49:
- diagvec()
- .diag()
- trimatu() / trimatl()
- symmatu() / symmatl()
- reshape()
Chris@49:

Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: find(X, k=0, s="first") Chris@49:

Return a column vector of the indices of non-zero elements of X

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

Chris@49: The input matrix X is interpreted as a vector, with column-by-column ordering of the elements of X Chris@49:

Relational operators can be used instead of X, eg. A > 0.5 Chris@49:

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 Chris@49:

If s="last", return at most the last k indices of the non-zero elements Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat  A  = randu<mat>(5,5);
Chris@49: mat  B  = randu<mat>(5,5);
Chris@49: 
Chris@49: uvec q1 = find(A > B);
Chris@49: uvec q2 = find(A > 0.5);
Chris@49: uvec q3 = find(A > 0.5, 3, "last");
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- unique()
- conv_to() (convert between matrix/vector types)
- submatrix views
- sort_index()
Chris@49:

Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: fliplr(mat) Chris@49:
flipud(mat) Chris@49:

Chris@49: fliplr(): generate a copy of the input matrix, with the order of the columns reversed Chris@49:

Chris@49: flipud(): generate a copy of the input matrix, with the order of the rows reversed Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: 
Chris@49: mat B = fliplr(A);
Chris@49: mat C = flipud(A);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .swap_rows() & .swap_cols() (member functions of Mat, Col and Row classes)
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: hist(V, n_bins=10) Chris@49:
hist(X, n_bins=10, dim=0) Chris@49:
Chris@49:
hist(V, centers) Chris@49:
hist(X, centers, dim=0) Chris@49:

Chris@49: For vector V, Chris@49: produce an unsigned vector of the same orientation as V (ie. either uvec or urowvec) Chris@49: that represents a histogram of counts Chris@49:

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

Chris@49: The bin centers can be automatically determined from the data, with the number of bins specified via n_bins (default is 10); Chris@49: the range of the bins is determined by the range of the data Chris@49:

Chris@49: The bin centers can also be explicitly specified via the centers vector; Chris@49: the vector must contain monotonically increasing values (eg. 0.1, 0.2, 0.3, ...) Chris@49:

Chris@49: This function was added in version 3.0 Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: vec  v  = randn<vec>(1000); // Gaussian distribution
Chris@49: 
Chris@49: uvec h1 = hist(v, 11);
Chris@49: uvec h2 = hist(v, linspace<vec>(-2,2,11));
Chris@49:

Chris@49:

See also: Chris@49:
- histc()
- statistics functions
- conv_to()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: histc(V, edges) Chris@49:
histc(X, edges, dim=0) Chris@49:

Chris@49: For vector V, Chris@49: produce an unsigned vector of the same orientation as V (ie. either uvec or urowvec) Chris@49: that contains the counts of the number of values that fall between the elements in the edges vector Chris@49:

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

Chris@49: The edges vector must contain monotonically increasing values (eg. 0.1, 0.2, 0.3, ...) Chris@49:

Chris@49: This function was added in version 3.0 Chris@49:

Chris@49: Examples: Chris@49:

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

Chris@49:

See also: Chris@49:
- hist()
- statistics functions
- conv_to()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: imag(cx_mat) Chris@49:
imag(cx_cube) Chris@49:
Chris@49:
real(cx_mat) Chris@49:
real(cx_cube) Chris@49:

Chris@49: Extract the imaginary/real part of a complex matrix/cube Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: cx_mat C = randu<cx_mat>(5,5);
Chris@49: 
Chris@49: mat    A = imag(C);
Chris@49: mat    B = real(C);
Chris@49:

Chris@49:

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); Chris@49: to work around this bug, preface Armadillo's imag() and real() with the arma namespace qualification, eg. arma::imag(C) Chris@49:

See also: Chris@49:
- set_imag() / set_real()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: join_rows(mat A, mat B) Chris@49:
join_cols(mat A, mat B) Chris@49:
join_slices(cube A, cube B) Chris@49:

Chris@49: join_rows(): Chris@49: for two matrices A and B, append each row of B to its respective row of A; Chris@49: matrices A and B must have the same number of rows Chris@49:

Chris@49: join_cols(): Chris@49: for two matrices A and B, append each column of B to its respective column of A; Chris@49: matrices A and B must have the same number of columns Chris@49:

Chris@49: join_slices(): Chris@49: for two cubes A and B, append the slices of B to the slices of A; Chris@49: cubes A and B have the same number of rows and columns (ie. all slices must have the same size) Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(4,5);
Chris@49: mat B = randu<mat>(4,6);
Chris@49: mat C = randu<mat>(6,5);
Chris@49: 
Chris@49: mat X = join_rows(A,B);
Chris@49: mat Y = join_cols(A,C);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- shed rows/columns/slices
- insert rows/columns/slices
- submatrix views
- subcube views
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: kron(A,B) Chris@49: Chris@49:

Kronecker tensor product.

Using matrix A (with n rows and p columns) and matrix B (with m rows and q columns), Chris@49: kron(A,B) returns a matrix (with nm rows and pq columns) which denotes the tensor product of A and B Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(4,5);
Chris@49: mat B = randu<mat>(5,4);
Chris@49: 
Chris@49: mat K = kron(A,B);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- Kronecker Product in MathWorld
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: reshape(mat, n_rows, n_cols, dim=0) Chris@49:
reshape(cube, n_rows, n_cols, n_slices, dim=0) Chris@49:

Chris@49: Generate a matrix/cube sized according to given size specifications, Chris@49: whose elements are taken from the given matrix/cube, either column-wise (dim=0) or row-wise (dim=1); Chris@49: the elements in the generated object are placed column-wise (ie. the first column is filled up before filling the second column) Chris@49:

Chris@49: The layout of the elements in the generated object will be different to the layout in the given object Chris@49:

Chris@49: This function can be used to create a vector representation of a matrix (ie. concatenate all the columns or rows) Chris@49:

Chris@49: 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 Chris@49:

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

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

Chris@49: Caveat: Chris@49: reshape() is slower than .set_size(), which doesn't preserve data Chris@49:

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

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(10, 5);
Chris@49: mat B = reshape(A, 5, 10);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .reshape() (member function of Mat and Cube)
- .set_size() (member function of Mat and Cube)
- resize()
- as_scalar()
- conv_to()
- diagmat()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: resize(mat, n_rows, n_cols) Chris@49:
resize(cube, n_rows, n_cols, n_slices) Chris@49:

Chris@49: Generate a matrix/cube sized according to given size specifications, Chris@49: whose elements as well as the layout of the elements are taken from the given matrix/cube Chris@49:

Chris@49: Caveat: Chris@49: resize() is slower than .set_size(), which doesn't preserve data Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(4, 5);
Chris@49: mat B = resize(A, 7, 6);
Chris@49:

Chris@49:

Chris@49: This function was added in version 2.4 Chris@49:

Chris@49: See also: Chris@49:
- .resize() (member function of Mat and Cube)
- .set_size() (member function of Mat and Cube)
- reshape()
- as_scalar()
- conv_to()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: shuffle(mat, dim=0) Chris@49:
shuffle(rowvec, dim=0) Chris@49:
shuffle(colvec, dim=0) Chris@49:

Chris@49: Shuffle the rows (dim=0) or columns (dim=1) of a matrix or vector Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(4,5);
Chris@49: mat B = shuffle(A);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- randu() / randn()
- sort()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: sort(mat, sort_type=0, dim=0) Chris@49:
sort(rowvec, sort_type=0) Chris@49:
sort(colvec, sort_type=0) Chris@49:

For a matrix argument, return a matrix 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

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

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(10,10);
Chris@49: mat B = sort(A);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- sort_index()
- shuffle()
- randu() / randn()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: sort_index(colvec, sort_type=0) Chris@49:
sort_index(rowvec, sort_type=0) Chris@49:
Chris@49:
stable_sort_index(colvec, sort_type=0) Chris@49:
stable_sort_index(rowvec, sort_type=0) Chris@49:

Return a vector which describes the sorted order of the given vector's elements Chris@49: (ie. it contains the indices of the given vector's elements) Chris@49:

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

sort_type=0 (default) indicates an ascending sort

sort_type=1 indicates a descending sort

The stable_sort_index() variant preserves the relative order of elements with equivalent values; the variant was added in version 3.6

Chris@49: Examples: Chris@49:

Chris@49: vec  q       = randu<vec>(10);
Chris@49: uvec indices = sort_index(q);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- find()
- sort()
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: symmatu(A) Chris@49:
symmatl(A) Chris@49:

Chris@49: symmatu(A): interpret square matrix A as symmetric, reflecting the upper triangle to the lower triangle Chris@49:

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

Chris@49: If A is non-square, a std::logic_error exception is thrown Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: 
Chris@49: mat B = symmatu(A);
Chris@49: mat C = symmatl(A);
Chris@49:

Chris@49:

See also: Chris@49:
- diagmat()
- trimatu() / trimatl()
- Symmetric matrix in Wikipedia
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: strans(mat) Chris@49:
strans(colvec) Chris@49:
strans(rowvec) Chris@49:

Chris@49: Simple matrix transpose, without taking the conjugate of the elements (complex matrices) Chris@49:

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

See also: Chris@49:
- .st()
- trans()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: trans(mat) Chris@49:
trans(colvec) Chris@49:
trans(rowvec) Chris@49:

Chris@49: Matrix transpose / Hermitian transpose Chris@49:

Chris@49: If a given object has real elements, a normal transpose is done Chris@49:

Chris@49: If a given object has complex elements, a Hermitian transpose is done (ie. the conjugate of the elements is taken during the transpose operation) Chris@49:

Chris@49: Caveat: for complex matrices, the functionality of trans() has changed in version 2.0: Chris@49:
- in version 1.x, trans() does not take the conjugate of complex elements
- in version 1.x, the htrans() function is used for the Hermitian transpose
Chris@49:

Chris@49: Examples: Chris@49:

mat A = randu<mat>(5,10);
Chris@49: mat B = trans(A);
Chris@49:

Chris@49:

See also: Chris@49:
- .t()
- strans()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: trimatu(A) Chris@49:
trimatl(A) Chris@49:

Chris@49: trimatu(A): interpret square matrix A as upper triangular Chris@49:

Chris@49: trimatl(A): interpret square matrix A as lower triangular Chris@49:

Chris@49: A std::logic_error exception is thrown if A is non-square Chris@49:

Chris@49: Examples: Chris@49:

mat A = randu<mat>(5,5);
Chris@49: mat U = trimatu(A);
Chris@49: mat L = trimatl(A);
Chris@49: 
Chris@49: // tell the inv() function to look only
Chris@49: // at the upper triangular part
Chris@49: mat X = inv( trimatu(U) );
Chris@49:

Chris@49:

See also: Chris@49:
- symmatu() / symmatl()
- diagmat()
- inv()
- solve()
- Triangular matrix in MathWorld
- Triangular matrix in Wikipedia
Chris@49:

Chris@49:
Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: Chris@49: unique(A) Chris@49:
Chris@49:

Chris@49: Return the unique elements of A, sorted in ascending order Chris@49:

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

Chris@49: This function was added in version 3.2 Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat X;
Chris@49: X << 1 << 2 << endr
Chris@49:   << 2 << 3 << endr;
Chris@49: 
Chris@49: mat Y = unique(X);
Chris@49:

Chris@49:

See also: Chris@49:
- find()
- sort()
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49:

Chris@49:
Chris@49:
Chris@49: Decompositions, Factorisations, Inverses and Equation Solvers Chris@49:
Chris@49:
Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: R = chol(X) Chris@49:
chol(R, X) Chris@49:

Chris@49: Cholesky decomposition of X, such that R.t()*R = X Chris@49:

Chris@49: X must be a symmetric, positive-definite matrix Chris@49:

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

Chris@49: Examples: Chris@49:

Chris@49: mat X = randu<mat>(5,5);
Chris@49: mat Y = X.t()*X;
Chris@49: 
Chris@49: mat R = chol(Y);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- Cholesky decomposition in MathWorld
- Cholesky decomposition in Wikipedia
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: vec eigval = eig_sym(mat X) Chris@49:
vec eigval = eig_sym(cx_mat X) Chris@49:
Chris@49:
eig_sym(vec eigval, mat X) Chris@49:
eig_sym(vec eigval, cx_mat X) Chris@49:
Chris@49:
eig_sym(vec eigval, mat eigvec, mat X, method = "standard") Chris@49:
eig_sym(vec eigval, cx_mat eigvec, cx_mat X, method = "standard") Chris@49:

Eigen decomposition of 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

Chris@49: By default, a standard eigen decomposition algorithm is used; Chris@49: a divide-and-conquer algorithm can be used instead by explicitly setting method to "dc" Chris@49:

Chris@49: The divide-and-conquer algorithm provides slightly different results, but is notably faster for large matrices Chris@49:

If the decomposition fails, the output objects are reset and: Chris@49:
- 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
Chris@49:

There is currently no check whether X is symmetric

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(50,50);
Chris@49: mat B = A.t()*A;  // generate a symmetric matrix
Chris@49: 
Chris@49: vec eigval;
Chris@49: mat eigvec;
Chris@49: 
Chris@49: eig_sym(eigval, eigvec, B);        // use standard algorithm by default
Chris@49: 
Chris@49: eig_sym(eigval, eigvec, B, "dc");  // use "divide & conquer" algorithm
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- eig_gen()
- svd()
- svd_econ()
- eigen decomposition in MathWorld
- eigenvalues & eigenvectors in Wikipedia
- divide & conquer eigenvalue algorithm in Wikipedia
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: eig_gen(cx_vec eigval, cx_mat eigvec, mat X, side='r') Chris@49:
Chris@49: eig_gen(cx_vec eigval, cx_mat eigvec, cx_mat X, side='r') Chris@49:
Chris@49:
Chris@49: eig_gen(cx_vec eigval, mat l_eigvec, mat r_eigvec, mat X) Chris@49:
Chris@49: eig_gen(cx_vec eigval, cx_mat l_eigvec, cx_mat r_eigvec, cx_mat X) Chris@49:

Chris@49: Eigen decomposition of general (non-symmetric/non-hermitian) square matrix X

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

Chris@49: For the first two forms, side='r' (default) specifies that right eigenvectors are computed, Chris@49: while side='l' specifies that left eigenvectors are computed Chris@49:

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

Chris@49: The eigenvalues are not guaranteed to be ordered Chris@49:

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

If the decomposition fails, the output objects are reset and eig_gen() returns a bool set to false

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(10,10);
Chris@49: 
Chris@49: cx_vec eigval;
Chris@49: cx_mat eigvec;
Chris@49: 
Chris@49: eig_gen(eigval, eigvec, A);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- eig_sym()
- svd()
- svd_econ()
- eigen decomposition in MathWorld
- eigenvalues & eigenvectors in Wikipedia
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: cx_mat Y = fft(X)
Chris@49: cx_mat Y = fft(X, n)
Chris@49:
Chris@49: cx_mat Z = ifft(cx_mat Y)
Chris@49: cx_mat Z = ifft(cx_mat Y, n)
Chris@49:

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

Chris@49: The optional n argument specifies the transform length: Chris@49:
- 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
Chris@49:

Chris@49: If n is not specified, the transform length is the same as the length of the input vector Chris@49:

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

This function was added in version 3.810

Chris@49: Examples: Chris@49:

Chris@49:    vec X = randu<vec>(100);
Chris@49: cx_vec Y = fft(X, 128);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- conv()
- real()
- fast Fourier transform in MathWorld
- fast Fourier transform in Wikipedia
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: B = inv(A, slow=false) Chris@49:
Chris@49: inv(B, A, slow=false) Chris@49:

Chris@49: Inverse of square matrix A Chris@49:

the slow argument is optional

Chris@49: If A is known to be a triangular matrix, Chris@49: the inverse can be computed faster by explicitly marking the matrix as triangular Chris@49: through trimatu() or trimatl() Chris@49:

Chris@49: If A is known to be a positive-definite symmetric matrix, Chris@49: the inverse can be computed faster by explicitly marking the matrix using sympd() Chris@49:

Chris@49: If A is not square, a std::logic_error exception is thrown Chris@49:

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

Chris@49: NOTE: in many cases it is more efficient/faster to use the solve() function instead of performing a matrix inverse; Chris@49: for example, if you want to solve a system of linear equations, eg., X = inv(A)*B, Chris@49: use solve() instead Chris@49:

Chris@49: For matrix sizes ≤ 4x4, a fast inverse algorithm is used by default. Chris@49: In rare instances, the fast algorithm might be less precise than the standard algorithm. Chris@49: To force the use of the standard algorithm, set the slow argument to true Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: mat B = inv(A);
Chris@49: 
Chris@49: 
Chris@49: // Diagonal elements in C are set to the
Chris@49: // reciprocal of the corresponding elements in A.
Chris@49: // Off-diagonal elements in C are set to zero.
Chris@49: mat C = inv( diagmat(A) );
Chris@49: 
Chris@49: 
Chris@49: // tell inv() to look only at the upper triangular part of A
Chris@49: mat D = inv( trimatu(A) );
Chris@49: 
Chris@49: 
Chris@49: // tell inv() that AA is a symmetric positive definite matrix
Chris@49: mat AA = A*A.t();
Chris@49: mat E  = inv( sympd(AA) );
Chris@49: 
Chris@49: 
Chris@49: mat44 F = randu<mat>(4,4);
Chris@49: 
Chris@49: mat G = inv(F);       // use fast algorithm by default
Chris@49: mat H = inv(F, true); // use slow algorithm
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .i() Chris@49:
- pinv() Chris@49:
- solve()
- trimatu() / trimatl()
- matrix inverse in MathWorld
- invertible matrix in Wikipedia
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: lu(mat L, mat U, mat P, mat X) Chris@49:
Chris@49: lu(mat L, mat U, mat X) Chris@49:

Chris@49: Lower-upper decomposition (with partial pivoting) of matrix X Chris@49:

Chris@49: The first form provides Chris@49: a lower-triangular matrix L, Chris@49: an upper-triangular matrix U, Chris@49: and a permutation matrix P, Chris@49: such that P.t()*L*U = X Chris@49:

Chris@49: The second form provides permuted L and U, such that L*U = X. Chris@49: Note that in this case L is generally not lower-triangular Chris@49:

Chris@49: If the decomposition fails, the output objects are reset and lu() returns a bool set to false Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: 
Chris@49: mat L, U, P;
Chris@49: 
Chris@49: lu(L, U, P, A);
Chris@49: 
Chris@49: mat B = P.t()*L*U;
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- LU decomposition in Wikipedia
- LU decomposition in MathWorld
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: B = pinv(A, tolerance = default) Chris@49:
pinv(B, A, tolerance = default) Chris@49:

Moore-Penrose pseudo-inverse of matrix A

The tolerance argument is optional

The computation is based on singular value decomposition; Chris@49: if the decomposition fails, B is reset and: Chris@49:
- pinv(A) throws a std::runtime_error exception
- pinv(B,A) returns a bool set to false
Chris@49:
Chris@49:
Any singular values less than tolerance are treated as zero

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

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(4,5);
Chris@49: mat B = pinv(A);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .i()
- inv()
- solve()
- datum::eps
- Pseudoinverse in MathWorld
- Moore-Penrose Matrix Inverse in MathWorld
- Moore-Penrose pseudoinverse in Wikipedia
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: mat coeff = princomp(mat X) Chris@49:
cx_mat coeff = princomp(cx_mat X)
Chris@49: Chris@49:
princomp(mat coeff, mat X) Chris@49:
princomp(cx_mat coeff, cx_mat X)
Chris@49: Chris@49:
princomp(mat coeff, mat score, mat X) Chris@49:
princomp(cx_mat coeff, cx_mat score, cx_mat X)
Chris@49: Chris@49:
princomp(mat coeff, mat score, vec latent, mat X) Chris@49:
princomp(cx_mat coeff, cx_mat score, vec latent, cx_mat X)
Chris@49: Chris@49:
princomp(mat coeff, mat score, vec latent, vec tsquared, mat X) Chris@49:
princomp(cx_mat coeff, cx_mat score, vec latent, cx_vec tsquared, cx_mat X)
Chris@49:
Chris@49:

Principal component analysis of matrix X

Each row of X is an observation and each column is a variable

output objects: Chris@49:
- coeff: principal component coefficients
- score: projected data
- latent: eigenvalues of the covariance matrix of X
- tsquared: Hotteling's statistic for each sample
Chris@49:

The computation is based on singular value decomposition; Chris@49: if the decomposition fails, the output objects are reset and: Chris@49:
- princomp(X) throws a std::runtime_error exception
- remaining forms of princomp() return a bool set to false
Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,4);
Chris@49: 
Chris@49: mat coeff;
Chris@49: mat score;
Chris@49: vec latent;
Chris@49: vec tsquared;
Chris@49: 
Chris@49: princomp(coeff, score, latent, tsquared, A);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- principal components analysis in Wikipedia
- principal components analysis in MathWorld
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: qr(Q,R,X) Chris@49:

Chris@49: Decomposition of X into an orthogonal matrix Q and a right triangular matrix R, such that Q*R = X Chris@49:

Chris@49: If the decomposition fails, Q and R are reset and the function returns a bool set to false Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat X = randu<mat>(5,5);
Chris@49: mat Q, R;
Chris@49: 
Chris@49: qr(Q,R,X);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- qr_econ()
- Orthogonal matrix in Wikipedia
- QR decomposition in Wikipedia
- QR decomposition in MathWorld
- QR decomposition in Octave
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: qr_econ(Q,R,X) Chris@49:

Chris@49: Economical decomposition of X (with size m x n) into an orthogonal matrix Q and a right triangular matrix R, such that Q*R = X Chris@49:

Chris@49: If m > n, only the first n rows of R and the first n columns of Q are calculated Chris@49: (ie. the zero rows of R and the corresponding columns of Q are omitted) Chris@49:

Chris@49: If the decomposition fails, Q and R are reset and the function returns a bool set to false Chris@49:

Chris@49: This function was added in version 3.4 Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat X = randu<mat>(6,5);
Chris@49: mat Q, R;
Chris@49: 
Chris@49: qr_econ(Q,R,X);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- qr()
- Orthogonal matrix in Wikipedia
- QR decomposition in Wikipedia
- QR decomposition in Octave
- QR decomposition in MathWorld
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: X = solve(A, B, slow=false) Chris@49:
solve(X, A, B, slow=false) Chris@49:

Solve a system of linear equations, ie., A*X = B, where X is unknown

The slow argument is optional

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

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

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

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

Chris@49: If A is non-square (and hence also non-triangular), Chris@49: solve() will also try to provide approximate solutions to under-determined as well as over-determined systems

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

Chris@49: For matrix sizes ≤ 4x4, a fast algorithm is used by default. Chris@49: In rare instances, the fast algorithm might be less precise than the standard algorithm. Chris@49: To force the use of the standard algorithm, set the slow argument to true Chris@49:

Chris@49: NOTE: Old versions of the ATLAS library (eg. 3.6) can corrupt memory and crash your program; Chris@49: the standard LAPACK library and later versions of ATLAS (eg. 3.8) work without problems Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: vec b = randu<vec>(5);
Chris@49: mat B = randu<mat>(5,5);
Chris@49: 
Chris@49: vec x = solve(A, b);
Chris@49: mat X = solve(A, B);
Chris@49: 
Chris@49: vec x2;
Chris@49: solve(x2, A, b);
Chris@49: 
Chris@49: // tell solve() to look only at the upper triangular part of A
Chris@49: mat Y = solve( trimatu(A), B );
Chris@49: 
Chris@49: 
Chris@49: mat44 C = randu<mat>(4,4);
Chris@49: mat44 D = randu<mat>(4,4);
Chris@49: 
Chris@49: mat E = solve(C, D);       // use fast algorithm by default
Chris@49: mat F = solve(C, D, true); // use slow algorithm
Chris@49: 
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- .i()
- inv()
- pinv()
- syl()
- trimatu() / trimatl()
- linear system of equations in MathWorld
- system of linear equations in Wikipedia
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: vec s = svd(mat X) Chris@49:
vec s = svd(cx_mat X) Chris@49:
Chris@49:
svd(vec s, mat X), Chris@49:
svd(vec s, cx_mat X) Chris@49:
Chris@49:
svd(mat U, vec s, mat V, mat X, method = "standard") Chris@49:
svd(cx_mat U, vec s, cx_mat V, cx_mat X, method = "standard") Chris@49:

Chris@49: The first four forms compute the singular values of X Chris@49:

Chris@49: The last two forms compute the full singular value decomposition of X Chris@49:

The method argument is optional

Chris@49: By default, a standard decomposition algorithm is used; Chris@49: a divide-and-conquer algorithm can be used instead by explicitly setting method to "dc" Chris@49:

Chris@49: The divide-and-conquer algorithm provides slightly different results, but is notably faster for large matrices Chris@49:

If X is square, it can be reconstructed using X = U*diagmat(s)*V.t() Chris@49:

Chris@49: The singular values are in descending order Chris@49:

Chris@49: If the decomposition fails, the output objects are reset and: Chris@49:
- svd(X) throws a std::runtime_error exception
- svd(s,X) and svd(U,s,V,X) return a bool set to false
Chris@49:

Chris@49: NOTE: Old versions of the ATLAS library (eg. 3.6) can corrupt memory and crash your program; Chris@49: the standard LAPACK library and later versions of ATLAS (eg. 3.8) work without problems Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat X = randu<mat>(5,5);
Chris@49: 
Chris@49: mat U;
Chris@49: vec s;
Chris@49: mat V;
Chris@49: 
Chris@49: svd(U,s,V,X);        // use standard algorithm by default
Chris@49: 
Chris@49: svd(U,s,V,X, "dc");  // use "divide & conquer" algorithm
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- svd_econ()
- eig_gen()
- eig_sym()
- singular value decomposition in Wikipedia
- singular value decomposition in MathWorld
Chris@49:

Chris@49:
Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: svd_econ(mat U, vec s, mat V, mat X, mode = 'b') Chris@49:
svd_econ(cx_mat U, vec s, cx_mat V, cx_mat X, mode = 'b') Chris@49:

Chris@49: Economical singular value decomposition of X Chris@49:

Chris@49: mode is one of: Chris@49:
- 'l': compute only left singular vectors
- 'r': compute only right singular vectors
- 'b': compute both left and right singular vectors (default)
Chris@49:

Chris@49: The singular values are in descending order Chris@49:

Chris@49: If the decomposition fails, the output objects are reset and bool set to false is returned Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat X = randu<mat>(4,5);
Chris@49: 
Chris@49: mat U;
Chris@49: vec s;
Chris@49: mat V;
Chris@49: svd_econ(U, s, V, X, 'l');
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- svd()
- eig_gen()
- eig_sym()
- singular value decomposition in Wikipedia
- singular value decomposition in MathWorld
Chris@49:

Chris@49:
Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: X = syl(A, B, C) Chris@49:
syl(X, A, B, C) Chris@49:

Solve the Sylvester equation, ie., AX + XB + C = 0, where X is unknown.

Matrices A, B and C must be square sized.

Chris@49: If no solution is found, X is reset and: Chris@49:
- syl(A,B,C) throws a std::runtime_error exception
- svd(X,A,B,C) returns a bool set to false
Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: mat B = randu<mat>(5,5);
Chris@49: mat C = randu<mat>(5,5);
Chris@49: 
Chris@49: mat X1 = syl(A, B, C);
Chris@49: 
Chris@49: mat X2;
Chris@49: syl(X2, A, B, C);
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- solve()
- Sylvester equation in Wikipedia
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49:

Chris@49:
Chris@49:
Chris@49: Miscellaneous Chris@49:
Chris@49:
Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: is_finite(X) Chris@49:

Chris@49: Returns true if all elements in X are finite Chris@49:

Chris@49: Returns false if at least one element in X is non-finite (±infinity or NaN) Chris@49:

Chris@49: X can be a scalar (eg. double), vector, matrix or cube Chris@49:

Chris@49: Examples: Chris@49:

Chris@49: mat A = randu<mat>(5,5);
Chris@49: mat B = randu<mat>(5,5);
Chris@49: 
Chris@49: B(1,1) = datum::nan;
Chris@49: 
Chris@49: cout << is_finite(A) << endl;
Chris@49: cout << is_finite(B) << endl;
Chris@49: 
Chris@49: cout << is_finite( 0.123456789 ) << endl;
Chris@49: cout << is_finite( datum::nan  ) << endl;
Chris@49: cout << is_finite( datum::inf  ) << endl;
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- datum::nan
- datum::inf
- .is_finite() (member function of Mat and Cube)
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: logging of warnings and errors Chris@49:
Chris@49:
Chris@49: set_stream_err1(user_stream)
Chris@49: set_stream_err2(user_stream)
Chris@49:
Chris@49: std::ostream& x = get_stream_err1() Chris@49:
Chris@49: std::ostream& x = get_stream_err2() Chris@49:
Chris@49:

Chris@49: By default, Armadillo prints warnings and messages associated with std::logic_error and std::runtime_error exceptions to the std::cout stream Chris@49:

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 exceptions (eg. failed decompositions)

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

Chris@49: Examples: Chris@49:

Chris@49: // print "hello" to the current err1 stream
Chris@49: get_stream_err1() << "hello" << endl;
Chris@49: 
Chris@49: // change the err2 stream to be a file
Chris@49: ofstream f("my_log.txt");
Chris@49: set_stream_err2(f);
Chris@49: 
Chris@49: // trying to invert a singular matrix
Chris@49: // will print a message to the err2 stream
Chris@49: // and throw an exception
Chris@49: mat X = zeros<mat>(5,5);
Chris@49: mat Y = inv(X);
Chris@49: 
Chris@49: // disable messages being printed to the err2 stream
Chris@49: std::ostream nullstream(0);
Chris@49: set_stream_err2(nullstream);
Chris@49:

Chris@49:

Chris@49: Caveat: set_stream_err1() and set_stream_err2() will not change the stream used by .print() Chris@49:

Chris@49: See also: Chris@49:
- .print()
- std::cout
- std::ostream
- std::logic_error
- std::runtime_error
- tutorial on exceptions
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: various constants (pi, inf, speed of light, ...) Chris@49:
Chris@49:

Chris@49: Collection of math and fundamental physical constants Chris@49:

Chris@49: Physical constants were mainly taken from Chris@49: NIST Chris@49: and some from Chris@49: WolframAlpha Chris@49: on 2009-06-23; Chris@49: constants from NIST are in turn sourced from the 2006 CODATA values Chris@49:

Chris@49: The constants are stored in the Datum<type> class, Chris@49: where type is either float or double Chris@49:

Chris@49: For convenience, Chris@49: Datum<double> has been typedefed as datum Chris@49: while Chris@49: Datum<float> has been typedefed as fdatum Chris@49:

Chris@49: In previous versions of Armadillo (eg. 2.x), the constants are accessed via static functions in math and phy classes, eg. math::pi(); Chris@49: for compatibility, these classes are still available in version 3.x, but are not explicitly documented Chris@49:

Chris@49: Meaning of the constants: Chris@49:
Chris@49:
Chris@49:

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

Chris@49:

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

Chris@49: Examples: Chris@49:

Chris@49: cout << "2.0 * pi = " << 2.0 * datum::pi << endl;
Chris@49: 
Chris@49: cout << "speed of light = " << datum::c_0 << endl;
Chris@49: 
Chris@49: cout << "log_max for floats = ";
Chris@49: cout << fdatum::log_max << endl;
Chris@49: 
Chris@49: cout << "log_max for doubles = ";
Chris@49: cout << datum::log_max << endl;
Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- is_finite()
- NaN in Wikipedia
- physical constant in Wikipedia
- std::numeric_limits
Chris@49:

Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: uword, sword Chris@49:

Chris@49: 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 Chris@49:

Chris@49: 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 Chris@49:

Chris@49: ARMA_64BIT_WORD can be enabled via editing include/armadillo_bits/config.hpp Chris@49:

See also: Chris@49:
- C++ variable types
- explanation of typedef
- imat & umat matrix types Chris@49:
- ivec & uvec vector types Chris@49:
Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: cx_float, cx_double Chris@49:

Chris@49: cx_float is a typedef for std::complex<float> Chris@49:

Chris@49: cx_double is a typedef for std::complex<double> Chris@49:

See also: Chris@49:
- complex numbers in the standard C++ library
- explanation of typedef
- cx_mat matrix type Chris@49:
- cx_vec vector type Chris@49:
Chris@49:

Chris@49: Chris@49: Chris@49:

Chris@49:
Chris@49: Chris@49: Examples of Matlab/Octave syntax and conceptually corresponding Armadillo syntax Chris@49: Chris@49:
Chris@49:
Chris@49:

Chris@49: Matlab/Octave Chris@49:	Chris@49: Chris@49:	Chris@49: Armadillo Chris@49:	Chris@49: Chris@49:	Chris@49: Notes Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A(1, 1) Chris@49:	Chris@49: Chris@49:	Chris@49: A(0, 0) Chris@49:	Chris@49: Chris@49:	Chris@49: indexing in Armadillo starts at 0 Chris@49:
Chris@49: A(k, k) Chris@49:	Chris@49: Chris@49:	Chris@49: A(k-1, k-1) Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: size(A,1) Chris@49:	Chris@49: Chris@49:	Chris@49: A.n_rows Chris@49:	Chris@49: Chris@49:	Chris@49: read only Chris@49:
Chris@49: size(A,2) Chris@49:	Chris@49: Chris@49:	Chris@49: A.n_cols Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: size(Q,3) Chris@49:	Chris@49: Chris@49:	Chris@49: Q.n_slices Chris@49:	Chris@49: Chris@49:	Chris@49: Q is a cube (3D array) Chris@49:
Chris@49: numel(A) Chris@49:	Chris@49: Chris@49:	Chris@49: A.n_elem Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A(:, k) Chris@49:	Chris@49: Chris@49:	Chris@49: A.col(k) Chris@49:	Chris@49: Chris@49:	Chris@49: this is a conceptual example only; Chris@49: exact conversion from Matlab/Octave to Armadillo syntax Chris@49: will require taking into account that indexing starts at 0 Chris@49:
Chris@49: A(k, :) Chris@49:	Chris@49: Chris@49:	Chris@49: A.row(k) Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A(:, p:q) Chris@49:	Chris@49: Chris@49:	Chris@49: A.cols(p, q) Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A(p:q, :) Chris@49:	Chris@49: Chris@49:	Chris@49: A.rows(p, q) Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A(p:q, r:s) Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49: A.submat(p, r, q, s) Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49: A.submat(first_row, first_col, last_row, last_col) Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49: or Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49: A( span(p,q), span(r,s) ) Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49: A( span(first_row, last_row), span(first_col, last_col) ) Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Q(:, :, k) Chris@49:	Chris@49: Chris@49:	Chris@49: Q.slice(k) Chris@49:	Chris@49: Chris@49:	Chris@49: Q is a cube (3D array) Chris@49:
Chris@49: Q(:, :, t:u) Chris@49:	Chris@49: Chris@49:	Chris@49: Q.slices(t, u) Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Q(p:q, r:s, t:u) Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49: Q.subcube(p, r, t, q, s, u) Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49: .subcube(first_row, first_col, first_slice, last_row, last_col, last_slice) Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49: or Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49: Q( span(p,q), span(r,s), span(t,u) ) Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A' Chris@49:	Chris@49: Chris@49:	Chris@49: A.t() or trans(A) Chris@49:	Chris@49: Chris@49:	Chris@49: matrix transpose / Hermitian transpose Chris@49: Chris@49: (for complex matrices, the conjugate of each element is taken) Chris@49:
Chris@49: A.' Chris@49:	Chris@49: Chris@49:	Chris@49: A.st() or strans(A) Chris@49:	Chris@49: Chris@49:	Chris@49: simple matrix transpose Chris@49: Chris@49: (for complex matrices, the conjugate of each element is not taken) Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A = zeros(size(A)) Chris@49:	Chris@49: Chris@49:	Chris@49: A.zeros() Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A = ones(size(A)) Chris@49:	Chris@49: Chris@49:	Chris@49: A.ones() Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A = zeros(k) Chris@49:	Chris@49: Chris@49:	Chris@49: A = zeros<mat>(k,k) Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A = ones(k) Chris@49:	Chris@49: Chris@49:	Chris@49: A = ones<mat>(k,k) Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: C = complex(A,B) Chris@49:	Chris@49: Chris@49:	Chris@49: cx_mat C = cx_mat(A,B) Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A .* B Chris@49:	Chris@49: Chris@49:	Chris@49: A % B Chris@49:	Chris@49: Chris@49:	Chris@49: element-wise multiplication Chris@49:
Chris@49: A ./ B Chris@49:	Chris@49: Chris@49:	Chris@49: A / B Chris@49:	Chris@49: Chris@49:	Chris@49: element-wise division Chris@49:
Chris@49: A \ B Chris@49:	Chris@49: Chris@49:	Chris@49: solve(A,B) Chris@49:	Chris@49: Chris@49:	Chris@49: conceptually similar to inv(A)*B, but more efficient Chris@49:
Chris@49: A = A + 1; Chris@49:	Chris@49: Chris@49:	Chris@49: A++ Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A = A - 1; Chris@49:	Chris@49: Chris@49:	Chris@49: A-- Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A = [ 1 2; 3 4; ] Chris@49:	Chris@49: Chris@49:	Chris@49: A << 1 << 2 << endr Chris@49: << 3 << 4 << endr; Chris@49:	Chris@49: Chris@49:	Chris@49: element initialisation, Chris@49: with special element endr indicating end of row Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: X = [ A B ] Chris@49:	Chris@49: Chris@49:	Chris@49: X = join_rows(A,B) Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: X = [ A; B ] Chris@49:	Chris@49: Chris@49:	Chris@49: X = join_cols(A,B) Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: A Chris@49:	Chris@49: Chris@49:	Chris@49: cout << A << endl; Chris@49: or Chris@49: A.print("A ="); Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: save -ascii 'A.dat' A Chris@49:	Chris@49: Chris@49:	Chris@49: A.save("A.dat", raw_ascii); Chris@49:	Chris@49: Chris@49:	Chris@49: Matlab/Octave matrices saved as ascii are readable by Armadillo (and vice-versa) Chris@49:
Chris@49: load -ascii 'A.dat' Chris@49:	Chris@49: Chris@49:	Chris@49: A.load("A.dat", raw_ascii); Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: S = { 'abc'; 'def' } Chris@49:	Chris@49: Chris@49:	Chris@49: field<std::string> S(2); Chris@49: S(0) = "abc"; Chris@49: S(1) = "def"; Chris@49:	Chris@49: Chris@49:	Chris@49: fields can store arbitrary objects, in a 1D or 2D layout Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49:

Chris@49:
Chris@49: example program Chris@49:
Chris@49:
Chris@49:

Chris@49: If you save the program below as example.cpp, Chris@49: under Linux you can compile it using: Chris@49:
Chris@49: g++ example.cpp -o example -O1 -larmadillo Chris@49:

Chris@49: #include <iostream>
Chris@49: #include <armadillo>
Chris@49: 
Chris@49: using namespace std;
Chris@49: using namespace arma;
Chris@49: 
Chris@49: int main(int argc, char** argv)
Chris@49:   {
Chris@49:   mat A = randu<mat>(4,5);
Chris@49:   mat B = randu<mat>(4,5);
Chris@49:   
Chris@49:   cout << A*B.t() << endl;
Chris@49:   
Chris@49:   return 0;
Chris@49:   }
Chris@49:

Chris@49: You may also want to have a look at the example programs that come with the Armadillo archive. Chris@49:

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

Chris@49:
Chris@49: Chris@49: Chris@49: Chris@49: Chris@49:

Chris@49:
Chris@49: config.hpp Chris@49:
Chris@49:
Chris@49:

Chris@49: Armadillo can be configured via editing the file include/armadillo_bits/config.hpp. Chris@49: Specific functionality can be enabled or disabled by uncommenting or commenting out a particular #define, listed below. Chris@49:
Chris@49:
Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49:

Chris@49: ARMA_USE_LAPACK Chris@49:	Chris@49: Chris@49:	Chris@49: Enable the use of LAPACK, or a high-speed replacement for LAPACK (eg. Intel MKL, AMD ACML or the Accelerate framework). Chris@49: Armadillo requires LAPACK for functions such as svd(), inv(), eig_sym(), solve(), etc. Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: ARMA_USE_BLAS Chris@49:	Chris@49: Chris@49:	Chris@49: Enable the use of BLAS, or a high-speed replacement for BLAS (eg. OpenBLAS, Intel MKL, AMD ACML or the Accelerate framework). Chris@49: BLAS is used for matrix multiplication. Chris@49: Without BLAS, Armadillo will use a built-in matrix multiplication routine, which might be slower for large matrices. Chris@49: Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: ARMA_BLAS_CAPITALS Chris@49:	Chris@49: Chris@49:	Chris@49: Use capitalised (uppercase) BLAS and LAPACK function names (eg. DGEMM vs dgemm) Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: ARMA_BLAS_UNDERSCORE Chris@49:	Chris@49: Chris@49:	Chris@49: Append an underscore to BLAS and LAPACK function names (eg. dgemm_ vs dgemm). Enabled by default. Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: ARMA_BLAS_LONG Chris@49:	Chris@49: Chris@49:	Chris@49: Use "long" instead of "int" when calling BLAS and LAPACK functions Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: ARMA_BLAS_LONG_LONG Chris@49:	Chris@49: Chris@49:	Chris@49: Use "long long" instead of "int" when calling BLAS and LAPACK functions Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: ARMA_USE_TBB_ALLOC Chris@49:	Chris@49: Chris@49:	Chris@49: Use Intel TBB scalable_malloc() and scalable_free() instead of standard new[] and delete[] for managing matrix memory Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: ARMA_USE_MKL_ALLOC Chris@49:	Chris@49: Chris@49:	Chris@49: Use Intel MKL mkl_malloc() and mkl_free() instead of standard new[] and delete[] for managing matrix memory Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49: ARMA_64BIT_WORD Chris@49:	Chris@49: Chris@49:	Chris@49: Use 64 bit integers. Useful if you require matrices/vectors capable of holding more than 4 billion elements. Chris@49: Your machine and compiler must have support for 64 bit integers (eg. via "long" or "long long"). Chris@49: This can also be enabled by adding #define ARMA_64BIT_WORD before each instance of #include <armadillo>. Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49: ARMA_USE_CXX11 Chris@49:	Chris@49: Chris@49:	Chris@49: Use C++11 features, such as initialiser lists Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: ARMA_USE_HDF5 Chris@49:	Chris@49: Chris@49:	Chris@49: Enable the the ability to save and load matrices stored in the HDF5 format; Chris@49: the hdf5.h header file must be available on your system and you will need to link with the hdf5 library (eg. -lhdf5) Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: Chris@49: ARMA_NO_DEBUG Chris@49:	Chris@49: Chris@49:	Chris@49: Disable all run-time checks, such as bounds checking. Chris@49: This will result in faster code, but you first need to make sure that your code runs correctly! Chris@49: We strongly recommend to have the run-time checks enabled during development, Chris@49: as this greatly aids in finding mistakes in your code, and hence speeds up development. Chris@49: We recommend that run-time checks be disabled only for the shipped version of your program. Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: ARMA_EXTRA_DEBUG Chris@49:	Chris@49: Chris@49:	Chris@49: Print out the trace of internal functions used for evaluating expressions. Chris@49: Not recommended for normal use. Chris@49: This is mainly useful for debugging the library. Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: ARMA_MAT_PREALLOC Chris@49:	Chris@49: Chris@49:	Chris@49: The number of preallocated elements used by matrices and vectors. Chris@49: Must be always enabled and set to an integer that is at least 1. Chris@49: By default set to 16. Chris@49: If you mainly use lots of very small vectors (eg. ≤ 4 elements), change the number to the size of your vectors. Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: ARMA_DEFAULT_OSTREAM Chris@49:	Chris@49: Chris@49:	Chris@49: The default stream used for printing error messages and by .print(). Chris@49: Must be always enabled. Chris@49: By default this is set to std::cout Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: ARMA_DONT_USE_LAPACK Chris@49:	Chris@49: Chris@49:	Chris@49: Disable use of LAPACK. Overrides ARMA_USE_LAPACK Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:
Chris@49: ARMA_DONT_USE_BLAS Chris@49:	Chris@49: Chris@49:	Chris@49: Disable use of BLAS. Overrides ARMA_USE_BLAS Chris@49:
Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:	Chris@49: Chris@49:

Chris@49:

Chris@49: See also: Chris@49:
- logging of warnings and errors
- element access
- element initialisation
- uword/sword
Chris@49:

Chris@49:
Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49:

Chris@49:
Chris@49: API Additions, Changes and Deprecations Chris@49:
Chris@49:
Chris@49:

API and Version Policy Chris@49:

Chris@49: Armadillo's version number is X.Y.Z, where X is a major version, Y is a minor version, and Z is the patch level (indicating bug fixes). Chris@49:

Chris@49: Within each major version (eg. 3.x), minor versions with an even number (eg. 3.2) are backwards compatible with earlier even minor versions (eg. 3.0). Chris@49: For example, code written for version 3.0 will work with version 3.2. Chris@49: However, as each minor version may have more features (ie. API extensions) than earlier versions, Chris@49: code specifically written for version 3.2 doesn't necessarily work with 3.0. Chris@49:

Chris@49: An odd minor version number (eg. 3.3) indicates an experimental version. Chris@49: Experimental versions are generally faster and have more functionality, Chris@49: but their APIs have not been finalised yet. Chris@49:

Chris@49: In general, we don't like changes to existing APIs and prefer not to break any user software. Chris@49: However, to allow evolution and help code maintenance, we reserve the right to change the APIs in future major versions of Armadillo, Chris@49: while remaining backwards compatible wherever possible Chris@49: (eg. 4.0 may have slightly different APIs than 3.x). Chris@49: Also, in a rare instance the user API may need to be altered if a bug fix absolutely requires it. Chris@49:

Chris@49:

Chris@49: Chris@49: Chris@49: Chris@49:
Chris@49:
Chris@49:

Chris@49: List of additions and changes for each version: Chris@49:
Chris@49:
Chris@49:

Added in 3.900: Chris@49:
- automatic SSE2 vectorisation of elementary expressions (eg. matrix addition) when using GCC 4.7+ with -O3 optimisation
- faster median()
- faster handling of compound expressions with transposes of submatrix rows
- faster handling of compound expressions with transposes of complex vectors
- added support for saving & loading of cubes in HDF5 format
Chris@49:

Added in 3.820: Chris@49:
- 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
Chris@49:

Added in 3.810: Chris@49:
- fast Fourier transform: fft()
- handling of .imbue() and .transform() by submatrices and subcubes
- batch insertion constructors for sparse matrices Chris@49:
Chris@49:

Added in 3.800: Chris@49:
- .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()
Chris@49:

Changed in 3.800: Chris@49:
- Armadillo is now licensed using the Mozilla Public License 2.0; Chris@49:
  Chris@49: see also the associated frequently asked questions about the license
Chris@49:
Chris@49:

Added in 3.6: Chris@49:
- faster handling of compound expressions with submatrices and subcubes
- faster trace()
- support for loading matrices as text files with NaN and Inf elements
- stable_sort_index(), which preserves the relative order of elements with equivalent values
- handling of sparse matrices by mean(), var(), norm(), abs(), square(), sqrt()
- saving and loading of sparse matrices in arma_binary format
Chris@49:
Chris@49:

Added in 3.4: Chris@49:
- economical QR decomposition: qr_econ()
- .each_col() & .each_row() for vector operations repeated on each column or row of a matrix
- preliminary support for sparse matrices
- ability to save and load matrices in HDF5 format
- faster singular value decomposition via optional use of divide-and-conquer algorithm
- faster .randn()
- faster dot() and cdot() for complex numbers
Chris@49:
Chris@49:

Added in 3.2: Chris@49:
- unique(), for finding unique elements of a matrix
- .eval(), for forcing the evaluation of delayed expressions
- faster eigen decomposition via optional use of divide-and-conquer algorithm
- faster transpose of vectors and compound expressions
- faster handling of diagonal views
- faster handling of tiny fixed size vectors (≤ 4 elements)
Chris@49:
Chris@49:

Added in 3.0: Chris@49:
- shorthand for inverse: .i()
- datum class
- hist() and histc()
- non-contiguous submatrix views
- faster handling of submatrix views with a single row or column
- faster element access in fixed size matrices
- faster repmat()
Chris@49:
Chris@49:
Changed in 3.0: Chris@49:
- expressions X=inv(A)*B and X=A.i()*B are automatically converted to X=solve(A,B) Chris@49:
- better detection of vector expressions by sum(), cumsum(), prod(), min(), max(), mean(), median(), stddev(), var() Chris@49:
- faster generation of random numbers Chris@49: (eg. randu() and randn()), Chris@49: via an algorithm that produces slightly different numbers than in 2.x Chris@49:
- Chris@49: support for tying writeable auxiliary (external) memory to fixed size matrices has been removed; Chris@49: instead, you can use standard matrices with writeable auxiliary memory, Chris@49: or initialise fixed size matrices by copying the memory. Chris@49: Using auxiliary memory with standard matrices is unaffected. Chris@49:
- Chris@49: .print_trans() and .raw_print_trans() have been removed; Chris@49: instead, you can chain .t() and .print() to achieve a similar result: X.t().print() Chris@49:
Chris@49:
Chris@49:

Added in 2.4: Chris@49:
- 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), Chris@49:
  enabled via ARMA_64BIT_WORD in include/armadillo_bits/config.hpp
- experimental support for C++11 initialiser lists, Chris@49:
  enabled via ARMA_USE_CXX11 in include/armadillo_bits/config.hpp
Chris@49:
Chris@49:
Changed in 2.4: Chris@49:
- refactored code to eliminate warnings when using the Clang C++ compiler
- umat, uvec, .min() and .max() Chris@49: have been changed to use the uword type instead of the u32 type; Chris@49: by default the uword and u32 types are equivalent (ie. unsigned integer type with a minimum width 32 bits); Chris@49: however, when the use of 64 bit indices is enabled via ARMA_64BIT_WORD in include/armadillo_bits/config.hpp, Chris@49: the uword type then has a minimum width of 64 bits Chris@49:
Chris@49:

Added in 2.2: Chris@49:
- svd_econ()
- circ_toeplitz()
- .is_colvec() and .is_rowvec()
Chris@49:
Chris@49:
Added in 2.0: Chris@49:
- det(), inv() and solve() can be forced to use more precise algorithms for tiny matrices (≤ 4x4)
- syl(), for solving Sylvester's equation
- strans(), for transposing a complex matrix without taking the complex conjugate
- symmatu() and symmatl()
- submatrices of submatrices
- faster inverse of symmetric positive definite matrices
- faster element access for fixed size matrices
- faster multiplication of tiny matrices (eg. 4x4)
- faster compound expressions containing submatrices
- handling of arbitrarily sized empty matrices (eg. 5x0)
- .count() member function in running_stat and running_stat_vec
- loading & saving of matrices as CSV text files
Chris@49:
Chris@49:
Changed in 2.0: Chris@49:
- trans() now takes the complex conjugate when transposing a complex matrix
- Forms of Chris@49: chol(), eig_sym(), eig_gen(), Chris@49: inv(), lu(), pinv(), princomp(), Chris@49: qr(), solve(), svd(), syl() Chris@49: that do not return a bool indicating success now throw std::runtime_error exceptions when failures are detected
- princomp_cov() has been removed; eig_sym() in conjunction with cov() can be used instead
- .is_vec() now outputs true for empty vectors (eg. 0x1)
- set_log_stream() & get_log_stream() have been replaced by set_stream_err1() & get_stream_err1()
Chris@49:
Chris@49:
Added in 1.2: Chris@49:
- .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 Chris@49: span::all or span(), to indicate an entire range Chris@49:
- for cubes, the two argument version of span can be replaced by Chris@49: a single argument version, span(a), to indicate a single column, row or slice Chris@49:
- arbitrary "flat" subcubes can be interpreted as matrices; for example: Chris@49:
  Chris@49:
- 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()
Chris@49:

Chris@49: Changed in 1.0 (compared to earlier 0.x development versions): Chris@49:
- Chris@49: the 3 argument version of lu(), Chris@49: eg. lu(L,U,X), Chris@49: provides L and U which should be the same as produced by Octave 3.2 Chris@49: (this was not the case in versions prior to 0.9.90) Chris@49:
- Chris@49: rand() has been replaced by randu(); Chris@49: this has been done to avoid confusion with std::rand(), Chris@49: which generates random numbers in a different interval Chris@49:
- Chris@49: In versions earlier than 0.9.0, Chris@49: some multiplication operations directly converted result matrices with a size of 1x1 into scalars. Chris@49: This is no longer the case. Chris@49: If you know the result of an expression will be a 1x1 matrix and wish to treat it as a pure scalar, Chris@49: use the as_scalar() wrapping function Chris@49:
- Chris@49: Almost all functions have been placed in the delayed operations framework (for speed purposes). Chris@49: This may affect code which assumed that the output of some functions was a pure matrix. Chris@49: The solution is easy, as explained below. Chris@49:
  Chris@49:
  Chris@49: In general, Armadillo queues operations before executing them. Chris@49: As such, the direct output of an operation or function cannot be assumed to be a directly accessible matrix. Chris@49: The queued operations are executed when the output needs to be stored in a matrix, Chris@49: eg. mat B = trans(A) or mat B(trans(A)). Chris@49: If you need to force the execution of the delayed operations, Chris@49: place the operation or function inside the corresponding Mat constructor. Chris@49: For example, if your code assumed that the output of some functions was a pure matrix, Chris@49: eg. chol(m).diag(), change the code to mat(chol(m)).diag(). Chris@49: Similarly, if you need to pass the result of an operation such as A+B to one of your own functions, Chris@49: use my_function( mat(A+B) ). Chris@49:
Chris@49:

Chris@49:

Chris@49:
Chris@49:
Chris@49:
Chris@49: Chris@49: Chris@49: Chris@49: Chris@49: Chris@49:

Chris@49:
Chris@49:
Chris@49: Chris@49:

Chris@49: Chris@49: Chris@49: