Mercurial > hg > segmenter-vamp-plugin
diff armadillo-3.900.4/docs.html @ 49:1ec0e2823891
Switch to using subrepo copies of qm-dsp, nnls-chroma, vamp-plugin-sdk; update Armadillo version; assume build without external BLAS/LAPACK
| author | Chris Cannam |
|---|---|
| date | Thu, 13 Jun 2013 10:25:24 +0100 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/armadillo-3.900.4/docs.html Thu Jun 13 10:25:24 2013 +0100 @@ -0,0 +1,11447 @@ +<!-- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> --> +<html> +<head> + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type"> + <title>Armadillo: API Reference</title> + <link rel="icon" href="armadillo_icon.png" type="image/png"> + <style type="text/css"> + <!-- +body + { + font-family: "Trebuchet MS", Arial, Helvetica, sans-serif; + color: #000000; + background-color: #FFFFFF; + /* font-size: 10pt; */ + /* line-height: 120%; */ + height: 110%; + } + +pre + { + font-family: "DejaVu Sans Mono", "Liberation Mono", "Andale Mono", "Bitstream Vera Sans Mono", "Luxi Mono", monospace; + font-size: smaller; + color: #666666; + } + +a + { + text-decoration: none; + color: #498c05; + } + +a:hover + { + text-decoration: underline; + color: #498c05; + } + +a.menu + { + text-decoration: none; + color: #CCCCCC; + } + +a.menu:hover + { + text-decoration: none; + color: #498c05; + } + +a.hidden, a.hidden:hover, a.hidden:active, a.hidden:link, a.hidden:visited + { + text-decoration: none; + border-bottom: 0px + } + +table + { + /* border: 1px solid #000; */ + /* display: block; */ + border-collapse: collapse; + } + +td.line + { + border-left: 2px solid rgb(204, 204, 204); + } + +.footertext + { + position: relative; + bottom: 0px; + } + +hr.greyline + { + color: rgb(204, 204, 204); + /* background-color: rgb(204, 204, 204); */ + } + + +#nobreak + { + white-space: nowrap; + } + +.noindent + { + text-indent: 0px; + margin-left: 1ex; + margin-right: 0ex; + margin-top: 0ex; + margin-bottom: 0ex; + padding-left: 1ex; + padding-right: 0ex; + padding-top: 0ex; + padding-bottom: 0ex; + list-style: disc; + } + --> + </style> +</head> +<body> +<center> +<table style="text-align: left; width: 80%; margin-left: auto; margin-right: auto;" border="0" cellpadding="0" cellspacing="0"> +<tbody> +<tr> +<td style="vertical-align: top;"> + +<table style="text-align: left; width: 100%;" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td style="text-align: left; vertical-align: top;"> + <font size=+2><b>Reference for Armadillo 3.900</b></font> + <br> + <b>(Bavarian Sunflower)</b> + </td> + <td style="text-align: right; vertical-align: top;"> + <b><a href="http://arma.sourceforge.net">to Armadillo home page</a></b> + <br> + <b><a href="http://nicta.com.au">to NICTA home page</a></b> + <br> + </td> + </tr> + </tbody> +</table> +<hr> +<br> +<br> +<a name="top"></a> +<a style="display:scroll; position:fixed; bottom:5px; right:5px;" href="#top"><font size=-1>[top]</font></a> + + +<!-- BEGIN CONTENT --> + + +<b>Preamble</b> +<br> +<br> +<table border="0" cellpadding="0" cellspacing="0"> +<tbody> +<tr> +<td style="text-align: left; vertical-align: top; width: 50%;"> +<ul> +<li> +To aid the conversion of Matlab/Octave programs, +there is a <a href="#syntax">syntax conversion table</a> +</li> +<br> +<li> +First time users may want to have a look at a short <a href="#example_prog">example program</a> +</li> +<br> +<li> +If you find any bugs or regressions, please <a href="http://arma.sourceforge.net/faq.html">report them</a> +</li> +<br> +<li> +Notes on <a href="#api_additions">API additions</a> +</li> +</ul> +</td> +<td> + +</td> +<td class="line" style="vertical-align: top;"> +<br> +</td> +<td style="text-align: left; vertical-align: top; width: 45%;"> +<ul> +<li> +Please cite the following tech report if you use Armadillo in your research and/or software. +Citations are useful for the continued development and maintenance of the library. +<br> +<br> +<font size=-1> +Conrad Sanderson. +<br> +<i><a href="armadillo_nicta_2010.pdf">Armadillo: An Open Source C++ Linear Algebra Library for Fast Prototyping and Computationally Intensive Experiments</a></i>. +<br> +Technical Report, NICTA, 2010. +</font> +</li> +</ul> +</td> +</tr> +</tbody> +</table> + +<br> +<br> + +<b>Matrix, Vector, Cube and Field Classes</b> +<ul> +<a href="#Mat">Mat<<i>type</i>>, mat and cx_mat</a> · +<a href="#Col">Col<<i>type</i>>, colvec and vec</a> · +<a href="#Row">Row<<i>type</i>>, rowvec</a> · +<a href="#Cube">Cube<<i>type</i>>, cube</a> · +<a href="#field">field<<i>object type</i>></a> · +<a href="#SpMat">SpMat<<i>type</i>>, sp_mat and sp_cx_mat</a> +</ul> +<br> + +<b>Member Functions & Variables</b> +<ul> +<a href="#attributes">attributes</a> · +<a href="#colptr">colptr</a> · +<a href="#copy_size">copy_size</a> · +<a href="#diag">diag</a> · +<a href="#each_colrow">each_col/each_row</a> · +<a href="#element_access">element access</a> · +<a href="#element_initialisation">element initialisation</a> · +<a href="#eval_member">eval</a> · +<a href="#eye_member">eye</a> · +<a href="#fill">fill</a> · +<a href="#i_member">i (inverse)</a> · +<a href="#imbue">imbue</a> · +<a href="#insert">insert rows/cols/slices</a> · +<a href="#in_range">in_range</a> · +<a href="#is_empty">is_empty</a> · +<a href="#is_finite">is_finite</a> · +<a href="#is_square">is_square</a> · +<a href="#is_vec">is_vec</a> · +<a href="#iterators_mat">iterators (matrices)</a> · +<a href="#iterators_cube">iterators (cubes)</a> · +<a href="#memptr">memptr</a> · +<a href="#min_and_max_member">min/max</a> · +<a href="#ones_member">ones</a> · +<a href="#operators">operators</a> · +<a href="#print">print</a> · +<a href="#raw_print">raw_print</a> · +<a href="#randu_randn_member">randu/randn</a> · +<a href="#reset">reset</a> · +<a href="#reshape_member">reshape</a> · +<a href="#resize_member">resize</a> · +<a href="#save_load_mat">save/load (matrices & cubes)</a> · +<a href="#save_load_field">save/load (fields)</a> · +<a href="#set_imag">set_imag/real</a> · +<a href="#set_size">set_size</a> · +<a href="#shed">shed rows/cols/slices</a> · +<a href="#stl_container_fns">STL container functions</a> · +<a href="#submat">submatrix views</a> · +<a href="#subcube">subcube views</a> · +<a href="#subfield">subfield views</a> · +<a href="#swap">swap</a> · +<a href="#swap_rows">swap_rows/cols</a> · +<a href="#t_st_members">t/st (transpose)</a> · +<a href="#transform">transform</a> · +<a href="#zeros_member">zeros</a> +</ul> +<br> + +<b>Other Classes</b> +<ul> +<a href="#running_stat">running_stat<<i>type</i>></a> · +<a href="#running_stat_vec">running_stat_vec<<i>type</i>></a> · +<a href="#wall_clock">wall_clock</a> +</ul> +<br> + +<b>Generated Vectors/Matrices/Cubes</b> +<ul> +<a href="#eye_standalone">eye</a> · +<a href="#linspace">linspace</a> · +<a href="#ones_standalone">ones</a> · +<a href="#randu_randn_standalone">randu/randn</a> · +<a href="#repmat">repmat</a> · +<a href="#speye">speye</a> · +<a href="#sprandu_sprandn">sprandu/sprandn</a> · +<a href="#toeplitz">toeplitz/circ_toeplitz</a> · +<a href="#zeros_standalone">zeros</a> +</ul> +<br> + +<b>Functions Individually Applied to Each Element of a Matrix/Cube</b> +<ul> +<a href="#abs">abs</a> · +<a href="#eps">eps</a> · +<a href="#misc_fns">misc functions (exp, log, pow, sqrt, ...)</a> · +<a href="#trig_fns">trigonometric functions (cos, sin, ...)</a> +</ul> +<br> + +<b>Scalar Valued Functions of Vectors/Matrices/Cubes</b> +<ul> +<a href="#accu">accu</a> · +<a href="#as_scalar">as_scalar</a> · +<a href="#det">det</a> · +<a href="#dot">dot/cdot/norm_dot</a> · +<a href="#log_det">log_det</a> · +<a href="#norm">norm</a> · +<a href="#rank">rank</a> · +<a href="#trace">trace</a> +</ul> +<br> + +<b>Scalar/Vector Valued Functions of Vectors/Matrices</b> +<ul> +<a href="#diagvec">diagvec</a> · +<a href="#min_and_max">min/max</a> · +<a href="#prod">prod</a> · +<a href="#sum">sum</a> · +<a href="#stats_fns">statistics (mean, stddev, ...)</a> +</ul> +<br> + +<b>Vector/Matrix/Cube Valued Functions of Vectors/Matrices/Cubes</b> +<ul> +<a href="#conv">conv</a> · +<a href="#conv_to">conv_to</a> · +<a href="#conj">conj</a> · +<a href="#cor">cor</a> · +<a href="#cov">cov</a> · +<a href="#cross">cross</a> · +<a href="#cumsum">cumsum</a> · +<a href="#diagmat">diagmat</a> · +<a href="#find">find</a> · +<a href="#flip">fliplr/flipud</a> · +<a href="#hist">hist</a> · +<a href="#histc">histc</a> · +<a href="#imag_real">imag/real</a> · +<a href="#join">join rows/cols/slices</a> · +<a href="#kron">kron</a> · +<a href="#reshape">reshape</a> · +<a href="#resize">resize</a> · +<a href="#shuffle">shuffle</a> · +<a href="#sort">sort</a> · +<a href="#sort_index">sort_index</a> · +<a href="#symmat">symmatu/symmatl</a> · +<a href="#strans">strans</a> · +<a href="#trans">trans</a> · +<a href="#trimat">trimatu/trimatl</a> · +<a href="#unique">unique</a> +</ul> +<br> + +<b>Decompositions, Factorisations, Inverses and Equation Solvers</b> +<ul> +<a href="#chol">chol</a> · +<a href="#eig_sym">eig_sym</a> · +<a href="#eig_gen">eig_gen</a> · +<a href="#fft">fft/ifft</a> · +<a href="#inv">inv</a> · +<a href="#lu">lu</a> · +<a href="#pinv">pinv</a> · +<a href="#princomp">princomp</a> · +<a href="#qr">qr</a> · +<a href="#qr_econ">qr_econ</a> · +<a href="#solve">solve</a> · +<a href="#svd">svd</a> · +<a href="#svd_econ">svd_econ</a> · +<a href="#syl">syl</a> +</ul> +<br> + +<b>Miscellaneous</b> +<ul> +<a href="#is_finite_standalone">is_finite()</a> · +<a href="#logging">logging of errors/warnings</a> · +<a href="#constants">various constants (pi, inf, speed of light, ...)</a> · +<!--<a href="#log_add">log_add</a> ·--> +<a href="#uword">uword/sword</a> · +<a href="#cx_float_double">cx_float/cx_double</a> · +<a href="#syntax">Matlab/Armadillo syntax differences</a> · +<a href="#example_prog">example program</a> · +<!--<a href="#catching_exceptions">catching exceptions</a> ·--> +<a href="#config_hpp">config.hpp</a> · +<a href="#api_additions">API additions</a> +</ul> +<br> + +<br> +<br> +<hr class="greyline"> +<hr class="greyline"> +<br> +<br> +<font size=+1><b>Matrix, Vector, Cube and Field Classes</b></font> +<br> +<br> +<hr class="greyline"> +<br> + +<a name="Mat"></a><b>Mat<</b><i>type</i><b>></b> +<br><b>mat</b> +<br><b>cx_mat</b> +<ul> +<li> +The root matrix class is <b>Mat<</b><i>type</i><b>></b>, where <i>type</i> can be one of: +<ul> +<li> +<i>float</i>, <i>double</i>, <i>std::complex<float></i>, <i>std::complex<double></i>, +<i>char</i>, <i>short</i>, <i>int</i>, and unsigned versions of <i>char</i>, <i>short</i>, <i>int</i>. +</li> +</ul> +</li> +<br> +<li> +For convenience the following typedefs have been defined: +<ul> +<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + mat + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Mat<double> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + fmat + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Mat<float> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + cx_mat + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Mat<<a href="#cx_float_double">cx_double</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + cx_fmat + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Mat<<a href="#cx_float_double">cx_float</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + umat + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Mat<<a href="#uword">uword</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + imat + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Mat<<a href="#uword">sword</a>> + </td> + </tr> + </tbody> +</table> +</ul> +</li> +<br> +<li> +In this documentation the <i>mat</i> type is used for convenience; +it is possible to use other types instead, eg. <i>fmat</i> +</li> +<br> +<li> +Functions which are wrappers for LAPACK or ATLAS functions (generally matrix decompositions) are only valid for the following types: +<i>fmat</i>, <i>mat</i>, <i>cx_fmat</i>, <i>cx_mat</i> +</li> +<br> +<li> +Elements are stored with column-major ordering (ie. column by column) +</li> +<br> +<a name="constructors_mat"></a> +<li> +Constructors: +<ul> +<li>mat()</li> +<li>mat(n_rows, n_cols)</li> +<li>mat(mat)</li> +<li>mat(vec)</li> +<li>mat(rowvec)</li> +<li>mat(string)</li> +<li>mat(std::vector) (treated as a column vector)</li> +<li>mat(initialiser_list) (C++11 only)</li> +<li>cx_mat(mat,mat) (for constructing a complex matrix out of two real matrices)</li> +</ul> +</li> +<br> +<li> +The string format for the constructor is elements separated by spaces, and rows denoted by semicolons. +For example, the 2x2 identity matrix can be created using the format string <code>"1 0; 0 1"</code>. +While string based initialisation is compact, +directly <a href="#element_access">setting the elements</a> +or using <a href="#element_initialisation">element initialisation</a> is considerably faster. +</li> +<br> +<a name="adv_constructors_mat"></a> +<li> +Advanced constructors: +<br> +<br> +<ul> +<li>mat(aux_mem*, n_rows, n_cols, copy_aux_mem = true, strict = true) +<br> +<br> +<ul> +Create a matrix using data from writeable auxiliary memory. +By default the matrix allocates its own memory and copies data from the auxiliary memory (for safety). +However, if <i>copy_aux_mem</i> is set to <i>false</i>, +the matrix will instead directly use the auxiliary memory (ie. no copying). +This is faster, but can be dangerous unless you know what you're doing! +<br> +<br> +The <i>strict</i> variable comes into effect only if <i>copy_aux_mem</i> is set to <i>false</i> +(ie. the matrix is directly using auxiliary memory). +If <i>strict</i> is set to <i>true</i>, +the matrix will be bound to the auxiliary memory for its lifetime; +the number of elements in the matrix can't be changed (directly or indirectly). +If <i>strict</i> is set to <i>false</i>, the matrix will not be bound to the auxiliary memory for its lifetime, +ie., the size of the matrix can be changed. +If the requested number of elements is different to the size of the auxiliary memory, +new memory will be allocated and the auxiliary memory will no longer be used. +</ul> +</li> +<br> +<li>mat(const aux_mem*, n_rows, n_cols) +<br> +<br> +<ul> +Create a matrix by copying data from read-only auxiliary memory. +</ul> +</li> +<a name="adv_constructors_mat_fixed"></a> +<br> +<li>mat::fixed<n_rows, n_cols> +<br> +<br> +<ul> +Create a fixed size matrix, with the size specified via template arguments. +Memory for the matrix is allocated at compile time. +This is generally faster than dynamic memory allocation, but the size of the matrix can't be changed afterwards (directly or indirectly). +<br> +<br> +For convenience, there are several pre-defined typedefs for each matrix type +(where the types are: <i>umat</i>, <i>imat</i>, <i>fmat</i>, <i>mat</i>, <i>cx_fmat</i>, <i>cx_mat</i>). +The typedefs specify a square matrix size, ranging from 2x2 to 9x9. +The typedefs were defined by simply appending a two digit form of the size to the matrix type +-- for example, <i>mat33</i> is equivalent to <i>mat::fixed<3,3></i>, +while <i>cx_mat44</i> is equivalent to <i>cx_mat::fixed<4,4></i>. +</ul> +</li> +<br> +<li>mat::fixed<n_rows, n_cols>(const aux_mem*) +<br> +<br> +<ul> +Create a fixed size matrix, with the size specified via template arguments, +and copying data from auxiliary memory. +</ul> +</li> +</ul> +</li> +<br> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +double x = A(1,2); + +mat B = A + A; +mat C = A * B; +mat D = A % B; + +cx_mat X(A,B); + +B.zeros(); +B.set_size(10,10); +B.zeros(5,6); + +// +// fixed size matrices: + +mat::fixed<5,6> F; +F.ones(); + +mat44 G; +G.randn(); + +cout << mat22().randu() << endl; + +// +// constructing matrices from +// auxiliary (external) memory: + +double aux_mem[24]; +mat H(aux_mem, 4, 6, false); +</pre> +</ul> +</li> +<br> +<li><b>Caveat:</b> +For mathematical correctness, scalars are treated as 1x1 matrices during initialisation. +As such, the code below <b>will not</b> generate a 5x5 matrix with every element equal to 123.0: +<ul> +<pre> +mat A(5,5); A = 123.0; +</pre> +</ul> +Use the following code instead: +<ul> +<pre> +mat A(5,5); A.fill(123.0); +</pre> +</ul> +<br> +<li> +See also: +<ul> +<li><a href="#attributes">matrix attributes</a></li> +<li><a href="#element_access">accessing elements</a></li> +<li><a href="#element_initialisation">initialising elements</a></li> +<li><a href="#operators">math & relational operators</a></li> +<li><a href="#submat">submatrix views</a></li> +<li><a href="#save_load_mat">saving & loading matrices</a></li> +<li><a href="#print">printing matrices</a></li> +<li><a href="#iterators_mat">STL-style element iterators</a></li> +<li><a href="#eval_member">.eval()</a></li> +<li><a href="#conv_to">conv_to()</a> (convert between matrix types)</li> +<li><a href="http://www.cplusplus.com/doc/tutorial/other_data_types/">explanation of <i>typedef</i></a> (cplusplus.com) +<li><a href="#Col">Col class</a></li> +<li><a href="#Row">Row class</a></li> +<li><a href="#Cube">Cube class</a></li> +<li><a href="#SpMat">SpMat class</a> (sparse matrix)</li> +<li><a href="#config_hpp">config.hpp</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"> +<br> + +<a name="Col"></a><b>Col<</b><i>type</i><b>></b> +<br><b>colvec</b> +<br><b>vec</b> +<ul> +<li> +Classes for column vectors (matrices with one column) +</li> +<br> +<li>The <b>Col<</b><i>type</i><b>></b> class is derived from the <b>Mat<</b><i>type</i><b>></b> class +and inherits most of the member functions +</li> +<br> +<li> +For convenience the following typedefs have been defined: +<ul> +<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + vec, colvec + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Col<double> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + fvec, fcolvec + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Col<float> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + cx_vec, cx_colvec + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Col<<a href="#cx_float_double">cx_double</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + cx_fvec, cx_fcolvec + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Col<<a href="#cx_float_double">cx_float</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + uvec, ucolvec + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Col<<a href="#uword">uword</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + ivec, icolvec + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Col<<a href="#uword">sword</a>> + </td> + </tr> + </tbody> +</table> +</ul> +</li> +<br> +<li> +In this documentation, the <b><i>vec</i></b> and <b><i>colvec</i></b> types have the <b>same meaning</b> and are used <b>interchangeably</b> +</li> +<br> +<li> +In this documentation, the types <i>vec</i> or <i>colvec</i> are used for convenience; it is possible to use other types instead, eg. <i>fvec</i>, <i>fcolvec</i> +</li> +<br> +<li> +Functions which take <i>Mat</i> as input can generally also take <i>Col</i> as input. +Main exceptions are functions which require square matrices +</li> +<br> +<li> +Constructors +<ul> +<li>vec(n_elem=0)</li> +<li>vec(vec)</li> +<li>vec(mat) (a <i>std::logic_error</i> exception is thrown if the given matrix has more than one column)</li> +<li>vec(string) (elements separated by spaces)</li> +<li>vec(std::vector)</li> +<li>vec(initialiser_list) (C++11 only)</li> +</ul> +</li> +<br> +<a name="adv_constructors_col"></a> +<li> +Advanced constructors: +<br> +<br> +<ul> +<li>vec(aux_mem*, number_of_elements, copy_aux_mem = true, strict = true) +<br> +<br> +<ul> +Create a column vector using data from writeable auxiliary memory. +By default the vector allocates its own memory and copies data from the auxiliary memory (for safety). +However, if <i>copy_aux_mem</i> is set to <i>false</i>, +the vector will instead directly use the auxiliary memory (ie. no copying). +This is faster, but can be dangerous unless you know what you're doing! +<br> +<br> +The <i>strict</i> variable comes into effect only if <i>copy_aux_mem</i> is set to <i>false</i> +(ie. the vector is directly using auxiliary memory). +If <i>strict</i> is set to <i>true</i>, +the vector will be bound to the auxiliary memory for its lifetime; +the number of elements in the vector can't be changed (directly or indirectly). +If <i>strict</i> is set to <i>false</i>, the vector will not be bound to the auxiliary memory for its lifetime, +ie., the vector's size can be changed. +If the requested number of elements is different to the size of the auxiliary memory, +new memory will be allocated and the auxiliary memory will no longer be used. +</ul> +</li> +<br> +<li>vec(const aux_mem*, number_of_elements) +<br> +<br> +<ul> +Create a column vector by copying data from read-only auxiliary memory. +</ul> +</li> +<a name="adv_constructors_col_fixed"></a> +<br> +<li>vec::fixed<number_of_elements> +<br> +<br> +<ul> +Create a fixed size column vector, with the size specified via the template argument. +Memory for the vector is allocated at compile time. +This is generally faster than dynamic memory allocation, but the size of the vector can't be changed afterwards (directly or indirectly). +<br> +<br> +For convenience, there are several pre-defined typedefs for each vector type +(where the types are: <i>uvec</i>, <i>ivec</i>, <i>fvec</i>, <i>vec</i>, <i>cx_fvec</i>, <i>cx_vec</i> as well as the corresponding <i>colvec</i> versions). +The pre-defined typedefs specify vector sizes ranging from 2 to 9. +The typedefs were defined by simply appending a single digit form of the size to the vector type +-- for example, <i>vec3</i> is equivalent to <i>vec::fixed<3></i>, +while <i>cx_vec4</i> is equivalent to <i>cx_vec::fixed<4></i>. +</ul> +</li> +<br> +<li>vec::fixed<number_of_elements>(const aux_mem*) +<br> +<br> +<ul> +Create a fixed size column vector, with the size specified via the template argument, +and copying data from auxiliary memory. +</ul> +</li> +</ul> +</li> +<br> +<br> +<li> +Examples: +<ul> +<pre> +vec x(10); +vec y = zeros<vec>(10,1); + +mat A = randu<mat>(10,10); +vec z = A.col(5); // extract a column vector +</pre> +</ul> +</li> +<br> +<li><b>Caveat:</b> +For mathematical correctness, scalars are treated as 1x1 matrices during initialisation. +As such, the code below <b>will not</b> generate a column vector with every element equal to 123.0: +<ul> +<pre> +vec a(5); a = 123.0; +</pre> +</ul> +Use the following code instead: +<ul> +<pre> +vec a(5); a.fill(123.0); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#Mat">Mat class</a></li> +<li><a href="#Row">Row class</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="Row"></a> +<b>Row<</b><i>type</i><b>></b> +<br><b>rowvec</b> +<ul> +<li> +Classes for row vectors (matrices with one row) +</li> +<br> +<li>The template <b>Row<</b><i>type</i><b>></b> class is derived from the <b>Mat<</b><i>type</i><b>></b> class +and inherits most of the member functions +</li> +<br> +<li> +For convenience the following typedefs have been defined: +<ul> +<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + rowvec + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Row<double> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + frowvec + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Row<float> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + cx_rowvec + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Row<<a href="#cx_float_double">cx_double</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + cx_frowvec + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Row<<a href="#cx_float_double">cx_float</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + urowvec + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Row<<a href="#uword">uword</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + irowvec + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Row<<a href="#uword">sword</a>> + </td> + </tr> + </tbody> +</table> +</ul> +</li> +<br> +<li> +In this documentation, the <i>rowvec</i> type is used for convenience; +it is possible to use other types instead, eg. <i>frowvec</i> +</li> +<br> +<li> +Functions which take <i>Mat</i> as input can generally also take <i>Row</i> as input. +Main exceptions are functions which require square matrices +</li> +<br> +<li> +Constructors +<ul> +<li>rowvec(n_elem=0)</li> +<li>rowvec(rowvec)</li> +<li>rowvec(mat) (a <i>std::logic_error</i> exception is thrown if the given matrix has more than one row)</li> +<li>rowvec(string) (elements separated by spaces)</li> +<li>rowvec(std::vector)</li> +<li>rowvec(initialiser_list) (C++11 only)</li> +</ul> +</li> +<br> +<a name="adv_constructors_row"></a> +<li> +Advanced constructors: +<br> +<br> +<ul> +<li>rowvec(aux_mem*, number_of_elements, copy_aux_mem = true, strict = true) +<br> +<br> +<ul> +Create a row vector using data from writeable auxiliary memory. +By default the vector allocates its own memory and copies data from the auxiliary memory (for safety). +However, if <i>copy_aux_mem</i> is set to <i>false</i>, +the vector will instead directly use the auxiliary memory (ie. no copying). +This is faster, but can be dangerous unless you know what you're doing! +<br> +<br> +The <i>strict</i> variable comes into effect only if <i>copy_aux_mem</i> is set to <i>false</i> +(ie. the vector is directly using auxiliary memory). +If <i>strict</i> is set to <i>true</i>, +the vector will be bound to the auxiliary memory for its lifetime; +the number of elements in the vector can't be changed (directly or indirectly). +If <i>strict</i> is set to <i>false</i>, the vector will not be bound to the auxiliary memory for its lifetime, +ie., the vector's size can be changed. +If the requested number of elements is different to the size of the auxiliary memory, +new memory will be allocated and the auxiliary memory will no longer be used. +</ul> +</li> +<br> +<li>rowvec(const aux_mem*, number_of_elements) +<br> +<br> +<ul> +Create a row vector by copying data from read-only auxiliary memory. +</ul> +</li> +<br> +<li>rowvec::fixed<number_of_elements> +<br> +<br> +<ul> +Create a fixed size row vector, with the size specified via the template argument. +Memory for the vector is allocated at compile time. +This is generally faster than dynamic memory allocation, but the size of the vector can't be changed afterwards (directly or indirectly). +<br> +<br> +For convenience, there are several pre-defined typedefs for each vector type +(where the types are: <i>urowvec</i>, <i>irowvec</i>, <i>frowvec</i>, <i>rowvec</i>, <i>cx_frowvec</i>, <i>cx_rowvec</i>). +The pre-defined typedefs specify vector sizes ranging from 2 to 9. +The typedefs were defined by simply appending a single digit form of the size to the vector type +-- for example, <i>rowvec3</i> is equivalent to <i>rowvec::fixed<3></i>, +while <i>cx_rowvec4</i> is equivalent to <i>cx_rowvec::fixed<4></i>. +</ul> +</li> +<br> +<li>rowvec::fixed<number_of_elements>(const aux_mem*) +<br> +<br> +<ul> +Create a fixed size row vector, with the size specified via the template argument, +and copying data from auxiliary memory. +</ul> +</li> +</ul> +</li> +<br> +<br> +<li> +Examples: +<ul> +<pre> +rowvec x(10); +rowvec y = zeros<mat>(1,10); + +mat A = randu<mat>(10,10); +rowvec z = A.row(5); // extract a row vector +</pre> +</ul> +</li> +<br> +<li> +<b>Caveat:</b> +For mathematical correctness, scalars are treated as 1x1 matrices during initialisation. +As such, the code below <b>will not</b> generate a row vector with every element equal to 123.0: +<ul> +<pre> +rowvec r(5); r = 123.0; +</pre> +</ul> +Use the following code instead: +<ul> +<pre> +rowvec r(5); r.fill(123.0); +</pre> +</ul> +<br> +<li>See also: +<ul> +<li><a href="#Mat">Mat class</a></li> +<li><a href="#Col">Col class</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"> +<br> + +<a name="Cube"></a> +<b>Cube<</b><i>type</i><b>></b> +<br><b>cube</b> +<br><b>cx_cube</b> +<ul> +<li> +Classes for cubes, also known as "3D matrices" or 3rd order tensors +</li> +<br> +<li> +The cube class is <b>Cube<</b><i>type</i><b>></b>, where <i>type</i> can be one of: +<i>char</i>, <i>int</i>, <i>float</i>, <i>double</i>, <i>std::complex<double></i>, etc +</li> +<br> +<li> +For convenience the following typedefs have been defined: +<ul> +<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + cube + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Cube<double> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + fcube + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Cube<float> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + cx_cube + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Cube<<a href="#cx_float_double">cx_double</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + cx_fcube + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Cube<<a href="#cx_float_double">cx_float</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + ucube + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Cube<<a href="#uword">uword</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + icube + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + Cube<<a href="#uword">sword</a>> + </td> + </tr> + </tbody> +</table> +</ul> +</li> +<br> +<li> +In this documentation the <i>cube</i> type is used for convenience; +it is possible to use other types instead, eg. <i>fcube</i> +</li> +<br> +<li> +Cube data is stored as a set of slices (matrices) stored contiguously within memory. +Within each slice, elements are stored with column-major ordering (ie. column by column) +</li> +<br> +<li> +Each slice can be interpreted as a matrix, hence functions which take <i>Mat</i> as input can generally also take cube slices as input +</li> +<br> +<a name="constructors_cube"></a> +<li> +Constructors: +<ul> +cube() +<br>cube(cube) +<br>cube(n_rows, n_cols, n_slices) +<br>cx_cube(cube, cube) (for constructing a complex cube out of two real cubes) +</ul> +</li> +<br> + +<a name="adv_constructors_cube"></a> +<li> +Advanced constructors: +<br> +<br> +<ul> +<li> +cube::fixed<n_rows, n_cols, n_slices> +<br> +<br> +<ul> +Create a fixed size cube, with the size specified via template arguments. +Memory for the cube is allocated at compile time. +This is generally faster than dynamic memory allocation, but the size of the cube can't be changed afterwards (directly or indirectly). +</ul> +</li> +<br> +<li>cube(aux_mem*, n_rows, n_cols, n_slices, copy_aux_mem = true, strict = true) +<br> +<br> +<ul> +Create a cube using data from writeable auxiliary memory. +By default the cube allocates its own memory and copies data from the auxiliary memory (for safety). +However, if <i>copy_aux_mem</i> is set to <i>false</i>, +the cube will instead directly use the auxiliary memory (ie. no copying). +This is faster, but can be dangerous unless you know what you're doing! +<br> +<br> +The <i>strict</i> variable comes into effect only if <i>copy_aux_mem</i> is set to <i>false</i> +(ie. the cube is directly using auxiliary memory). +If <i>strict</i> is set to <i>true</i>, +the cube will be bound to the auxiliary memory for its lifetime; +the number of elements in the cube can't be changed (directly or indirectly). +If <i>strict</i> is set to <i>false</i>, the cube will not be bound to the auxiliary memory for its lifetime, +ie., the size of the cube can be changed. +If the requested number of elements is different to the size of the auxiliary memory, +new memory will be allocated and the auxiliary memory will no longer be used. +</ul> +</li> +<br> +<li>cube(const aux_mem*, n_rows, n_cols, n_slices) +<br> +<br> +<ul> +Create a cube by copying data from read-only auxiliary memory. +</ul> +</li> +</ul> +</li> +<br> +<br> +<li> +Examples: +<ul> +<pre> +cube x(1,2,3); +cube y = randu<cube>(4,5,6); + +mat A = y.slice(1); // extract a slice from the cube + // (each slice is a matrix) + +mat B = randu<mat>(4,5); +y.slice(2) = B; // set a slice in the cube + +cube q = y + y; // cube addition +cube r = y % y; // element-wise cube multiplication + +cube::fixed<4,5,6> f; +f.ones(); +</pre> +</ul> +</li> +<br> +<li> +<b>Caveats</b> +<br> +<br> +<ul> +<li> +The size of individual slices can't be changed. +For example, the following <b>will not</b> work: +<ul> +<pre> +cube c(5,6,7); +c.slice(0) = randu<mat>(10,20); // wrong size +</pre> +</ul> +</li> +<li> +For mathematical correctness, scalars are treated as 1x1x1 cubes during initialisation. +As such, the code below <b>will not</b> generate a cube with every element equal to 123.0: +<ul> +<pre> +cube c(5,6,7); c = 123.0; +</pre> +</ul> +Use the following code instead: +<ul> +<pre> +cube c(5,6,7); c.fill(123.0); +</pre> +</ul> +<br> +</ul> +<li> +See also: +<ul> +<li><a href="#attributes">cube attributes</a></li> +<li><a href="#element_access">accessing elements</a></li> +<li><a href="#operators">math & relational operators</a></li> +<li><a href="#subcube">subcube views and slices</a></li> +<li><a href="#save_load_mat">saving & loading cubes</a></li> +<li><a href="#iterators_cube">STL-style element iterators</a></li> +<li><a href="#Mat">Mat class</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"> +<br> + +<a name="field"></a> +<b>field<</b><i>object type</i><b>></b> +<ul> +<li> +Class for one and two dimensional fields of arbitrary objects +</li> +<br> +<li> +Constructors (where <i>object type</i> is another class, eg. <i>std::string</i>, <i>mat</i>, <i>vec</i>, <i>rowvec</i>, etc): +<ul> +field<<i>object type</i>>(n_elem=0) +<br>field<<i>object type</i>>(n_rows, n_cols) +<br>field<<i>object type</i>>(field<<i>object type</i>>) +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre> +// create a field of strings +field<std::string> S(3,2); + +S(0,0) = "hello"; +S(1,0) = "there"; + +// string fields can be saved as plain text files +S.save("string_field"); + +// create a vec field with 3 rows and 2 columns +field<vec> F(3,2); + +// access components of the field +F(0,0) = vec(5); +F(1,1) = randu<vec>(6); +F(2,0).set_size(7); + +// access element 1 of the vec stored at 2,0 +double x = F(2,0)(1); + +// copy rows +F.row(0) = F.row(2); + +// extract a row of vecs from F +field<vec> G = F.row(1); + +// print the field to the standard output +G.print("G ="); + +// save the field to a binary file +G.save("vec_field"); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#attributes">field attributes</a></li> +<li><a href="#subfield">subfield views</a></li> +<li><a href="#save_load_field">saving/loading fields</a></li> +<li><a href="http://cplusplus.com/reference/string/string/">string class in the standard C++ library</a> (cplusplus.com)</li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"> +<br> + + +<a name="SpMat"></a><b>SpMat<</b><i>type</i><b>></b> +<br><b>sp_mat</b> +<br><b>sp_cx_mat</b> +<ul> +<li> +The root sparse matrix class is <b>SpMat<</b><i>type</i><b>></b>, where <i>type</i> can be one of: +<i>char</i>, <i>int</i>, <i>float</i>, <i>double</i>, <i>std::complex<double></i>, etc. +</li> +<br> +<li> +For convenience the following typedefs have been defined: +<ul> +<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + sp_mat + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + SpMat<double> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + sp_fmat + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + SpMat<float> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + sp_cx_mat + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + SpMat<<a href="#cx_float_double">cx_double</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + sp_cx_fmat + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + SpMat<<a href="#cx_float_double">cx_float</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + sp_umat + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + SpMat<<a href="#uword">uword</a>> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + sp_imat + </td> + <td style="vertical-align: top;"> + = + </td> + <td style="vertical-align: top;"> + SpMat<<a href="#uword">sword</a>> + </td> + </tr> + </tbody> +</table> +</ul> +</li> +<br> +<li> +In this documentation the <i>sp_mat</i> type is used for convenience; +it is possible to use other types instead, eg. <i>sp_fmat</i> +</li> +<br> +<a name="constructors_sp_mat"></a> +<li> +Constructors: +<ul> +<li>sp_mat()</li> +<li>sp_mat(n_rows, n_cols)</li> +<li>sp_mat(sp_mat)</li> +<li>sp_mat(string)</li> +<li>sp_cx_mat(sp_mat,sp_mat) (for constructing a complex matrix out of two real matrices)</li> +</ul> +<br> +<li> +<a name="batch_constructors_sp_mat"></a> +Batch insertion constructors: +<ul> +<li>sp_mat(locations, values, n_rows, n_cols, sort_locations = true)</li> +<li>sp_mat(locations, values, sort_locations = true)</li> +</ul> +<br> +<li> +Elements are stored in the <i>compressed sparse column</i> (CSC) format +</li> +<br> +<li> +All elements are treated as zero by default +</li> +<br> +<li> +This class behaves in a similar manner to the <a href="#Mat">Mat</a> class, +however, member functions which set all elements to non-zero values (and hence do not make sense for sparse matrices) have been deliberately omitted; +examples of omitted functions: <a href="#fill">.fill()</a>, <a href="#ones_member">.ones()</a>, += scalar, etc. +</li> +<br> + +<li>Batch insertion of values: +<ul> +<li> +Using batch insertion constructors is generally much faster than consecutively inserting values using <a href="#element_access">element access operators</a> +</li> +<br> +<li> +<i>locations</i> is a dense matrix of type <i>umat</i>, with a size of <i>2</i> x <i>N</i>, where <i>N</i> is the number of values to be inserted. +The row and column of the <i>i</i>-th element are specified as <i>locations(0,i)</i> and <i>locations(1,i)</i>, respectively. +</li> +<br> +<li> +<i>values</i> is a dense column vector containing the values to be inserted. +It must have the same element type as the sparse matrix. +The value in <i>values[i]</i> will be inserted at the location specified by the <i>i</i>-th column of the <i>locations</i> matrix. +</li> +<br> +<li> +The size of the constructed matrix is either manually specified via <i>n_rows</i> and <i>n_cols</i>, +or automatically determined from the maximal locations in the <i>locations</i> matrix. +</li> +<br> +<li> +If <i>sort_locations</i> is set to <i>false</i>, the <i>locations</i> matrix is assumed to contain locations that are already sorted according to column-major ordering. +</li> +</ul> +</li> +<br> + +<li> +<b>Caveat:</b> +support for sparse matrices in this version is <b>preliminary</b>; +it is not yet fully optimised, and sparse matrix decompositions/factorisations are not yet implemented. +The following subset of operations currently works with sparse matrices: +<ul> +<li>element access</li> +<li>fundamental arithmetic operations (such as addition and multiplication)</li> +<li>submatrix views</li> +<li>saving and loading (in <i>arma_binary</i> format)</li> +<li> +<a href="#abs">abs()</a>, +<a href="#accu">accu()</a>, +<a href="#as_scalar">as_scalar()</a>, +<a href="#dot">dot()</a>, +<a href="#stats_fns">mean()</a>, +<a href="#min_and_max">min()</a>, +<a href="#min_and_max">max()</a>, +<a href="#norm">norm()</a>, +<a href="#print">print()</a>, +<a href="#speye">speye()</a>, +<a href="#sprandu_sprandn">sprandu()/sprandn()</a>, +<a href="#misc_fns">square()</a>, +<a href="#misc_fns">sqrt()</a>, +<a href="#sum">sum()</a>, +<a href="#trace">trace()</a>, +<a href="#trans">trans()</a>, +<a href="#stats_fns">var()</a> +</li> +</ul> +</li> +<br> + +<li> +Examples: +<ul> +<pre> +sp_mat A(5,6); +sp_mat B(6,5); + +A(0,0) = 1; +A(1,0) = 2; + +B(0,0) = 3; +B(0,1) = 4; + +sp_mat C = 2*B; + +sp_mat D = A*C; + + +// batch insertion of two values at (5, 6) and (9, 9) +umat locations; +locations << 5 << 9 << endr + << 6 << 9 << endr; + +vec values; +values << 1.5 << 3.2 << endr; + +sp_mat X(locations, values); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#element_access">accessing elements</a></li> +<li><a href="#print">printing matrices</a></li> +<!-- +<li><a href="#SpCol">SpCol class</a> (TODO: add to documentation)</li> +<li><a href="#SpRow">SpRow class</a> (TODO: add to documentation)</li> +--> +<li><a href="http://en.wikipedia.org/wiki/Sparse_matrix">Sparse Matrix in Wikipedia</a></li> +<li><a href="#Mat">Mat class</a> (dense matrix)</li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"> +<hr class="greyline"> +<br> +<br> +<font size=+1><b>Member Functions & Variables</b></font> +<br> +<br> +<hr class="greyline"> +<br> + +<a name="attributes"></a> + +<b>attributes</b> +<ul> +<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0"> +<tbody> +<tr> +<td> +<b>.n_rows</b> +</td> +<td> </td> +<td> +(number of rows) +</td> +</tr> +<tr> +<td> +<b>.n_cols</b> +</td> +<td> </td> +<td> +(number of columns) +</td> +</tr> +<tr> +<td> +<b>.n_elem</b> +</td> +<td> </td> +<td> +(total number of elements) +</td> +</tr> +<tr> +<td> +<b>.n_slices</b> +</td> +<td> </td> +<td> +(number of slices) +</td> +</tr> +<tr> +<td> +<b>.n_nonzero</b> +</td> +<td> </td> +<td> +(number of nonzero elements) +</td> +</tr> +</tbody> +</table> +</ul> +<br> +<ul> +<li> +Member variables which are read-only; +to change the size, use +<a href="#set_size">.set_size()</a>, +<a href="#copy_size">.copy_size()</a>, +<a href="#zeros_member">.zeros()</a>, +<a href="#ones_member">.ones()</a>, +or +<a href="#reset">.reset()</a> +</li> +<br> +<li><i>n_rows</i>, <i>n_cols</i> and <i>n_elem</i> are applicable to <i>Mat</i>, <i>SpMat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i> classes</li> +<br> +<li><i>n_slices</i> is applicable only to the <i>Cube</i> class</li> +<br> +<li><i>n_nonzero</i> is applicable only to the <i>SpMat</i> class</li> +<br> +<li> +For the <i>Col</i> and <i>Row</i> classes, <i>n_elem</i> also indicates vector length</li> +<br> +<li>The variables are of type <a href="#uword">uword</a></li> +<br> +<li> +Examples: +<ul> +<pre> +mat X(4,5); +cout << "X has " << X.n_cols << " columns" << endl; +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#set_size">.set_size()</a></li> +<li><a href="#copy_size">.copy_size()</a></li> +<li><a href="#zeros_member">.zeros()</a></li> +<li><a href="#ones_member">.ones()</a></li> +<li><a href="#reset">.reset()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="colptr"></a> +<b>.colptr(col_number)</b> +<ul> +<li> +Member function of <i>Mat</i> +</li> +<br> +<li> +Obtain a raw pointer to the memory used by the specified column +</li> +<br> +<li> +As soon as the size of the matrix is changed, the pointer is no longer valid +</li> +<br> +<li>This function is not recommended for use unless you know what you're doing +-- you may wish to use <a href="#submat">submatrix views</a> instead +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); + +double* mem = A.colptr(2); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#memptr">.memptr()</a></li> +<li><a href="#submat">submatrix views</a></li> +<li><a href="#element_access">element access</a></li> +<li><a href="#iterators_mat">iterators (matrices)</a></li> +<li><a href="#adv_constructors_mat">advanced constructors (matrices)</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="copy_size"></a> +<b>.copy_size(A)</b> +<ul> +<li> +Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i> +</li> +<br> +<li> +Set the size to be the same as object <i>A</i> +</li> +<br> +<li> +Object <i>A</i> must be of the same root type as the object being modified +(eg. you can't set the size of a matrix by providing a cube) +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,6); +mat B; +B.copy_size(A); + +cout << B.n_rows << endl; +cout << B.n_cols << endl; +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#reset">.reset()</a></li> +<li><a href="#set_size">.set_size()</a></li> +<li><a href="#reshape_member">.reshape()</a></li> +<li><a href="#resize_member">.resize()</a></li> +<li><a href="#zeros_member">.zeros()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="diag"></a> +<b>.diag(</b><i>k=0</i><b>)</b> +<ul> +<li> +Member function of <i>Mat</i> +</li> +<br> +<li> +Read/write access to the <i>k</i>-th diagonal in a matrix +</li> +<br> +<li>The argument <i>k</i> is optional -- by default the main diagonal is accessed (<i>k=0</i>)</li> +<br> +<li>For <i>k > 0</i>, the <i>k</i>-th super-diagonal is accessed (top-right corner)</li> +<br> +<li>For <i>k < 0</i>, the <i>k</i>-th sub-diagonal is accessed (bottom-left corner)</li> +<br> +<li> +An extracted diagonal is interpreted as a column vector +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat X = randu<mat>(5,5); + +vec a = X.diag(); +vec b = X.diag(1); +vec c = X.diag(-2); + +X.diag() = randu<vec>(5); +X.diag() += 6; +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#eye_member">.eye()</a></li> +<li><a href="#diagvec">diagvec()</a></li> +<li><a href="#diagmat">diagmat()</a></li> +<li><a href="#submat">submatrix views</a></li> +<li><a href="#each_colrow">.each_col() & .each_row()</a></li> +<li><a href="#trace">trace()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="each_colrow"></a> +<b>.each_col()</b> +<br> +<b>.each_row()</b> +<br> +<br> +<b>.each_col(</b><i>vector_of_indices</i><b>)</b> +<br> +<b>.each_row(</b><i>vector_of_indices</i><b>)</b> +<ul> +<li> +Member functions of <i>Mat</i> +</li> +<br> +<li> +Write access to each column or row of a matrix/submatrix, +allowing a vector operation to be repeated on each column or row +</li> +<br> +<li> +The operation can be in-place vector addition, subtraction, element-wise multiplication, element-wise division, or simply vector copy +</li> +<br> +<li>The argument <i>vector_of_indices</i> is optional -- by default all columns or rows are accessed</li> +<br> +<li> +If the argument <i>vector_of_indices</i> is used, it must evaluate to be a vector of type <i><a href="#Col">uvec</a></i>; +the vector contains a list of indices of the columns or rows to be accessed +</li> +<br> +<li> +These functions were added in version 3.4 +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat X = ones<mat>(6,5); +vec v = linspace<vec>(10,15,6); + +// add v to each column in X +X.each_col() += v; + +// subtract v from columns 0 through to 3 in X +X.cols(0,3).each_col() -= v; + +uvec indices(2); +indices(0) = 2; +indices(1) = 4; + +// copy v to columns 2 and 4 in X +X.each_col(indices) = v; +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#diag">diagonal views</a></li> +<li><a href="#submat">submatrix views</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="element_access"></a> +<b>element/object access via (), [] and .at()</b> +<ul> +<li> +Provide access to individual elements or objects stored in a container object +(ie., <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>field</i>)<br> + <br> +<ul> + <table style="text-align: left; width: 100%;" + border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + <pre>(n)</pre> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> +For <i>vec</i> and <i>rowvec</i>, access the <i>n</i>-th element. +For <i>mat</i>, <i>cube</i> and <i>field</i>, access the <i>n</i>-th element/object under the assumption of a flat layout, +with column-major ordering of data (ie. column by column). +A <i>std::logic_error</i> exception is thrown if the requested element is out of bounds. +The bounds check can be <a href="#element_access_bounds_check_note">optionally disabled</a> at compile-time to get more speed. + </td> + </tr> +<tr> +<td> </td> +<td> </td> +<td> </td> +</tr> + <tr> + <td style="vertical-align: top;"> + <pre>.at(n) and [n]</pre> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +As for <i>(n)</i>, but without a bounds check. +Not recommended for use unless your code has been thoroughly debugged. + </td> + </tr> +<tr> +<td> </td> +<td> </td> +<td> </td> +</tr> + <tr> + <td style="vertical-align: top;"> + <pre>(i,j)</pre> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +For <i>mat</i> and <i>field</i> classes, access the element/object stored at the <i>i</i>-th row and <i>j</i>-th column. +A <i>std::logic_error</i> exception is thrown if the requested element is out of bounds. +The bounds check can be <a href="#element_access_bounds_check_note">optionally disabled</a> at compile-time to get more speed. + </td> + </tr> +<tr> +<td> </td> +<td> </td> +<td> </td> +</tr> + <tr> + <td style="vertical-align: top;"> + <pre>.at(i,j)</pre> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +As for <i>(i,j)</i>, but without a bounds check. +Not recommended for use unless your code has been thoroughly debugged. +</td> + <td style="vertical-align: top;"><br> + </td> + </tr> +<tr> +<td> </td> +<td> </td> +<td> </td> +</tr> + <tr> + <td style="vertical-align: top;"> + <pre>(i,j,k)</pre> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +Cube only: access the element stored at the <i>i</i>-th row, <i>j</i>-th column and <i>k</i>-th slice. +A <i>std::logic_error</i> exception is thrown if the requested element is out of bounds. +The bounds check can be <a href="#element_access_bounds_check_note">optionally disabled</a> at compile-time to get more speed. + </td> + </tr> +<tr> +<td> </td> +<td> </td> +<td> </td> +</tr> + <tr> + <td style="vertical-align: top;"> + <pre>.at(i,j,k)</pre> + </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +As for <i>(i,j,k)</i>, but without a bounds check. +Not recommended for use unless your code has been thoroughly debugged.</td> + </tr> + </tbody> + </table> +</ul> +</li> +<br> +<a name="element_access_bounds_check_note"></a> +<li> +The bounds checks used by the <i>(n)</i>, <i>(i,j)</i> and <i>(i,j,k)</i> access forms +can be disabled by defining <a href="#config_hpp_arma_no_debug"><i>ARMA_NO_DEBUG</i></a> or <i>NDEBUG</i> macros +before including the <i>armadillo</i> header file (eg. <i>#define ARMA_NO_DEBUG</i>). +Disabling the bounds checks is not recommended until your code has been thoroughly debugged +-- it's better to write correct code first, and then maximise its speed. +</li> +<br> +<li> +<b>Note</b>: for <a href="#SpMat">sparse matrices</a>, using element access operators to insert values via loops can be inefficient; +you may wish to use <a href="#batch_constructors_sp_mat">batch insertion constructors</a> instead +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(10,10); +A(9,9) = 123.0; +double x = A.at(9,9); +double y = A[99]; + +vec p = randu<vec>(10,1); +p(9) = 123.0; +double z = p[9]; +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#in_range">.in_range()</a></li> +<li><a href="#element_initialisation">element initialisation</a></li> +<li><a href="#submat">submatrix views</a></li> +<li><a href="#memptr">.memptr()</a></li> +<li><a href="#iterators_mat">iterators (matrices)</a></li> +<li><a href="#iterators_cube">iterators (cubes)</a></li> +<li><a href="#config_hpp">config.hpp</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="element_initialisation"></a> +<b>element initialisation</b> +<ul> +<li> +Instances of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>field</i> classes can be initialised via repeated use of the << operator +</li> +<br> +<li> +Special element <i>endr</i> indicates "end of row" (conceptually similar to <i>std::endl</i>) +</li> +<br> +<li> +Setting elements via << is a bit slower than directly <a href="#element_access">accessing</a> the elements, +but code using << is generally more readable as well as being easier to write +</li> +<br> +<li> +If you have a C++11 compiler, instances of <i>Mat</i>, <i>Col</i> and <i>Row</i> classes can be also initialised via initialiser lists; +this requires support for the C++11 standard to be <a href="#config_hpp_arma_use_cxx11">explicitly enabled</a> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A; + +A << 1 << 2 << 3 << endr + << 4 << 5 << 6 << endr; + +mat B = { 1, 2, 3, 4, 5, 6 }; // C++11 only +B.reshape(2,3); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#element_access">element access</a></li> +<li><a href="#print">.print()</a></li> +<li><a href="#save_load_mat">saving & loading matrices</a></li> +<li><a href="#adv_constructors_mat">advanced constructors (matrices)</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="eval_member"></a> +<b>.eval()</b> +<br> +<ul> +<li> +Member function of any matrix or vector expression +</li> +<br> +<li> +Explicitly forces the evaluation of a delayed expression and outputs a matrix +</li> +<br> +<li> +This function should be used sparingly and only in cases where it is absolutely necessary; indiscriminate use can cause slow downs +</li> +<br> +<li> +This function was added in version 3.2 +</li> +<br> +<li> +Examples: +<ul> +<pre> +cx_mat A( randu<mat>(4,4), randu<mat>(4,4) ); + +real(A).eval().save("A_real.dat", raw_ascii); +imag(A).eval().save("A_imag.dat", raw_ascii); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#Mat">Mat class</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="eye_member"></a> +<b>.eye()</b> +<br> +<b>.eye(n_rows, n_cols)</b> +<ul> +<li> +Set the elements along the main diagonal to one and off-diagonal elements set to zero, +optionally first resizing to specified dimensions +</li> +<br> +<li> +An identity matrix is generated when <i>n_rows</i> = <i>n_cols</i> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A(5,5); +A.eye(); + +mat B; +B.eye(5,5); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#ones_member">.ones()</a></li> +<li><a href="#diag">.diag()</a></li> +<li><a href="#diagmat">diagmat()</a></li> +<li><a href="#diagvec">diagvec()</a></li> +<li><a href="#eye_standalone">eye()</a> (standalone function)</li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="fill"></a> +<b>.fill(</b>value<b>)</b> +<ul> +<li> +Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i> classes. +</li> +<br> +<li>Sets the elements to a specified value</li> +<br> +<li>the type of value must match the type of elements used by the container object (eg. for <i>mat</i> the type is double) +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A(5,5); +A.fill(123.0); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#imbue">.imbue()</a></li> +<li><a href="#ones_member">.ones()</a></li> +<li><a href="#zeros_member">.zeros()</a></li> +<li><a href="#randu_randn_member">.randu() & .randn()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="i_member"></a> +<b>.i(</b> <i>slow=false</i> <b>)</b> +<ul> +<li> +Member function of any matrix expression +</li> +<br> +<li> +Provides an inverse of the matrix expression +</li> +<br> +<li>the <i>slow</i> argument is optional</li> +<br> +<li> +If the matrix expression is not square, a <i>std::logic_error</i> exception is thrown +</li> +<br> +<li> +If the matrix expression appears to be singular, the output matrix is reset and a <i>std::runtime_error</i> exception is thrown +</li> +<br> +<li> +For matrix sizes ≤ 4x4, a fast inverse algorithm is used by default. +In rare instances, the fast algorithm might be less precise than the standard algorithm. +To force the use of the standard algorithm, set the <i>slow</i> argument to <i>true</i> +</li> +<br> +<li> +<b>NOTE:</b> in many cases it is more efficient/faster to use the <a href="#solve">solve()</a> function instead of performing a matrix inverse +</li> +<br> +<li> +This function was added in version 3.0 +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(4,4); + +mat X = A.i(); +mat Y = (A+A).i(); + +mat B = randu<mat>(4,1); +mat Z = A.i() * B; // automatically converted to Z=solve(A,B) + +</pre> +</ul> +</li> +<li> +See also: +<ul> +<li><a href="#inv">inv()</a></li> +<li><a href="#pinv">pinv()</a></li> +<li><a href="#solve">solve()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="in_range"></a> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"><b>.in_range(</b> i <b>)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i>) + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.in_range( span(</b>start<b>,</b> end<b>) )</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i>) + </td> + </tr> + <tr> + <td> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.in_range(</b> row<b>,</b> col <b>)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>field</i>) + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.in_range( <font size=-1>span(</b>start_row<b>,</b> end_row<b>), span(</b>start_col<b>,</b> end_col<b>)</font> )</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>field</i>) + </td> + </tr> + <tr> + <td> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.in_range(</b> row<b>,</b> col<b>,</b> slice <b>)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member of <i>Cube</i>) + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.in_range( <font size=-1>span(</b>start_row<b>,</b> end_row<b>), span(</b>start_col<b>,</b> end_col<b>), span(</b>start_slice<b>,</b> end_slice<b>)</font> )</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member of <i>Cube</i>) + </td> + </tr> + </tbody> +</table> +<br> +<ul> +<li>Returns <i>true</i> if the given location or span is currently valid +</li> +<br> +<li>Returns <i>false</i> if the object is empty, the location is out of bounds, or the span is out of bounds +</li> +<br> +<li> +Instances of <i>span(a,b)</i> can be replaced by: +<ul> +<li><i>span()</i> or <i>span::all</i>, to indicate the entire range</li> +<li><i>span(a)</i>, to indicate a particular row, column or slice</li> +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(4,5); + +cout << A.in_range(0,0) << endl; // true +cout << A.in_range(3,4) << endl; // true +cout << A.in_range(4,5) << endl; // false +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#element_access">element access</a></li> +<li><a href="#submat">submatrix views</a></li> +<li><a href="#subcube">subcube views</a></li> +<li><a href="#subfield">subfield views</a></li> +<li><a href="#set_size">.set_size()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="is_empty"></a> +<b>.is_empty()</b> +<ul> +<li> +Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i> classes +</li> +<br> +<li>Returns true if the object has no elements +</li> +<br> +<li>Returns false if the object has one or more elements +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +cout << A.is_empty() << endl; + +A.reset(); +cout << A.is_empty() << endl; +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#is_square">.is_square()</a></li> +<li><a href="#is_vec">.is_vec()</a></li> +<li><a href="#is_finite">.is_finite()</a></li> +<li><a href="#reset">.reset()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="is_finite"></a> +<b>.is_finite()</b> +<ul> +<li> +Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i> classes +</li> +<br> +<li>Returns <i>true</i> if all elements of the object are finite +</li> +<br> +<li>Returns <i>false</i> if at least one of the elements of the object is non-finite (±infinity or NaN) +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +mat B = randu<mat>(5,5); + +B(1,1) = datum::nan; + +cout << A.is_finite() << endl; +cout << B.is_finite() << endl; +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#constants">datum::nan</a></li> +<li><a href="#constants">datum::inf</a></li> +<li><a href="#is_finite_standalone">is_finite()</a> (standalone function)</li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="is_square"></a> +<b>.is_square()</b> +<ul> +<li> +Member function of the <i>Mat</i> class +</li> +<br> +<li>Returns <i>true</i> if the matrix is square, ie., number of rows is equal to the number of columns +</li> +<br> +<li>Returns <i>false</i> if the matrix is not square +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +mat B = randu<mat>(6,7); + +cout << A.is_square() << endl; +cout << B.is_square() << endl; +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#is_empty">.is_empty()</a></li> +<li><a href="#is_vec">.is_vec()</a></li> +<li><a href="#is_finite">.is_finite()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="is_vec"></a> +<b>.is_vec()</b> +<br><b>.is_colvec()</b> +<br><b>.is_rowvec()</b> +<ul> +<li> +Member functions of the <i>Mat</i> class +</li> +<br> + +<li>.is_vec(): +<ul> +<li>Returns <i>true</i> if the matrix can be interpreted as a vector (either column or row vector) +</li> +<li>Returns <i>false</i> if the matrix does not have exactly one column or one row +</li> +</ul> +</li> +<br> + +<li>.is_colvec(): +<ul> +<li>Returns <i>true</i> if the matrix can be interpreted as a column vector +</li> +<li>Returns <i>false</i> if the matrix does not have exactly one column +</li> +</ul> +</li> +<br> + +<li>.is_rowvec(): +<ul> +<li>Returns <i>true</i> if the matrix can be interpreted as a row vector +</li> +<li>Returns <i>false</i> if the matrix does not have exactly one row +</li> +</ul> +</li> +<br> + +<li><b>Caveat:</b> do not assume that the vector has elements if these functions return <i>true</i> -- it is possible to have an empty vector (eg. 0x1) +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(1,5); +mat B = randu<mat>(5,1); +mat C = randu<mat>(5,5); + +cout << A.is_vec() << endl; +cout << B.is_vec() << endl; +cout << C.is_vec() << endl; +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#is_empty">.is_empty()</a></li> +<li><a href="#is_square">.is_square()</a></li> +<li><a href="#is_finite">.is_finite()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="imbue"></a> +<b>.imbue( </b>functor<b> )</b> +<br> +<b>.imbue( </b>lambda function<b> )</b> <i>(C++11 only)</i> +<br> +<ul> +<li> +Imbue (fill) with values provided by a functor or lambda function +</li> +<br> +<li> +For matrices, filling is done column-by-column (ie. column 0 is filled, then column 1, ...) +</li> +<br> +<li> +For cubes, filling is done slice-by-slice; each slice is filled column-by-column +</li> +<br> +<li> +This function was added in version 3.800 +</li> +<br> +<li> +Examples: +<ul> +<pre> +// C++11 only example +// need to include <random> + +std::mt19937 engine; // Mersenne twister random number engine + +std::uniform_real_distribution<double> distr(0.0, 1.0); + +mat A(4,5); + +A.imbue( [&]() { return distr(engine); } ); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#fill">.fill()</a></li> +<li><a href="#transform">.transform()</a></li> +<li><a href="http://en.wikipedia.org/wiki/Function_object">function object</a> at Wikipedia</li> +<li><a href="http://en.wikipedia.org/wiki/C%2B%2B11#Lambda_functions_and_expressions">C++11 lambda functions</a> at Wikipedia</li> +<li><a href="http://www.cprogramming.com/c++11/c++11-lambda-closures.html">lambda function</a> at cprogramming.com</li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="insert"></a> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + <b>.insert_rows( </b>row_number, X<b> )</b> + <br> + <b>.insert_rows( </b>row_number, number_of_rows, set_to_zero = true<b> )</b> + </td> + <td style="vertical-align: top;"><br></td> + <td style="vertical-align: top;">(member functions of <i>Mat</i> and <i>Col</i>) + </td> + </tr> + <tr> + <td> </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.insert_cols( </b>col_number, X<b> )</b> + <br> + <b>.insert_cols( </b>col_number, number_of_cols, set_to_zero = true<b> )</b> + </td> + <td style="vertical-align: top;"><br></td> + <td style="vertical-align: top;">(member functions of <i>Mat</i> and <i>Row</i>) + </td> + </tr> + <tr> + <td> </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.insert_slices( </b>slice_number, X<b> )</b> + <br> + <b>.insert_slices( </b>slice_number, number_of_slices, set_to_zero = true<b> )</b> + </td> + <td style="vertical-align: top;"><br></td> + <td style="vertical-align: top;">(member functions of <i>Cube</i>) + </td> + </tr> + </tbody> +</table> +<br> +<ul> +<li> +Functions with the <i>X</i> argument: insert a copy of X at the specified row/column/slice +<ul> +<li>if inserting rows, X must have the same number of columns as the recipient object</li> +<li>if inserting columns, X must have the same number of rows as the recipient object</li> +<li>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)</li> +</ul> +</li> +<br> +<li> +Functions with the <i>number_of_...</i> argument: expand the object by creating new rows/columns/slices. +By default, the new rows/columns/slices are set to zero. +If <i>set_to_zero</i> is <i>false</i>, the memory used by the new rows/columns/slices will not be initialised. +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,10); +mat B = ones<mat>(5,2); + +// at column 2, insert a copy of B; +// A will now have 12 columns +A.insert_cols(2, B); + +// at column 1, insert 5 zeroed columns; +// B will now have 7 columns +B.insert_cols(1, 5); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#shed">shed rows/columns/slices</a></li> +<li><a href="#join">join rows/columns/slices</a></li> +<li><a href="#resize_member">.resize()</a></li> +<li><a href="#submat">submatrix views</a></li> +<li><a href="#subcube">subcube views</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="iterators_mat"></a> +<b>iterators (matrices & vectors)</b> +<ul> +<li> +STL-style iterators and associated member functions of the <i>Mat</i>, <i>Col</i> and <i>Row</i> classes +</li> +<br> +<li> +iterator types: +<br> +<br> +<ul> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + <b>mat::iterator</b> + <br> + <b>vec::iterator</b> + <br> + <b>rowvec::iterator</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + random access iterators, for read/write access to elements + (which are stored column by column) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>mat::const_iterator</b> + <br> + <b>vec::const_iterator</b> + <br> + <b>rowvec::const_iterator</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + random access iterators, for read-only access to elements + (which are stored column by column) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>mat::col_iterator</b> + <br> + <b>vec::col_iterator</b> + <br> + <b>rowvec::col_iterator</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + random access iterators, for read/write access to the elements of a specific column + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>mat::const_col_iterator</b> + <br> + <b>vec::const_col_iterator</b> + <br> + <b>rowvec::const_col_iterator</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + random access iterators, for read-only access to the elements of a specific column + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>mat::row_iterator</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + rudimentary forward iterator, for read/write access to the elements of a specific row + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>mat::const_row_iterator</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + rudimentary forward iterator, for read-only access to the elements of a specific row + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>vec::row_iterator</b> + <br> + <b>rowvec::row_iterator</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + random access iterators, for read/write access to the elements of a specific row + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>vec::const_row_iterator</b> + <br> + <b>rowvec::const_row_iterator</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + random access iterators, for read-only access to the elements of a specific row + </td> + </tr> + </tbody> +</table> +</ul> +</li> +<br> +<br> +<li> +Member functions: +<br> +<br> +<ul> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + <b>.begin()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + iterator referring to the first element + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.end()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + iterator referring to the <i>past-the-end</i> element + </td> + </tr> + <tr> + <td> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.begin_row(</b><i>row_number</i><b>)</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + iterator referring to the first element of the specified row + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.end_row(</b><i>row_number</i><b>)</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + iterator referring to the <i>past-the-end</i> element of the specified row + </td> + </tr> + <tr> + <td> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.begin_col(</b><i>col_number</i><b>)</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + iterator referring to the first element of the specified column + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.end_col(</b><i>col_number</i><b>)</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + iterator referring to the <i>past-the-end</i> element of the specified column + </td> + </tr> + </tbody> +</table> +</ul> +</li> +<br> +<br> +<li> +Examples: +<ul> +<pre> +mat X = randu<mat>(5,5); + + +mat::iterator a = X.begin(); +mat::iterator b = X.end(); + +for(mat::iterator i=a; i!=b; ++i) + { + cout << *i << endl; + } + + +mat::col_iterator c = X.begin_col(1); // start of column 1 +mat::col_iterator d = X.end_col(3); // end of column 3 + +for(mat::col_iterator i=c; i!=d; ++i) + { + cout << *i << endl; + (*i) = 123.0; + } +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#stl_container_fns">STL container functions</a></li> +<li><a href="http://cplusplus.com/reference/std/iterator/">iterator at cplusplus.com</a></li> +<li><a href="#element_access">element access</a></li> +<li><a href="#memptr">.memptr()</a></li> +<li><a href="#colptr">.colptr()</a></li> +<li><a href="#submat">submatrix views</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="iterators_cube"></a> +<b>iterators (cubes)</b> +<ul> +<li> +STL-style iterators and associated member functions of the <i>Cube</i> class +</li> +<br> +<li> +iterator types: +<br> +<br> +<ul> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + <b>cube::iterator</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + random access iterator, for read/write access to elements; + the elements are ordered slice by slice; + the elements within each slice are ordered column by column + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>cube::const_iterator</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + random access iterators, for read-only access to elements + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>cube::slice_iterator</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + random access iterator, for read/write access to the elements of a particular slice; + the elements are ordered column by column + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>cube::const_slice_iterator</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + random access iterators, for read-only access to the elements of a particular slice + </td> + </tr> + </tbody> +</table> +</ul> +</li> +<br> +<br> +<li> +Member functions: +<br> +<br> +<ul> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + <b>.begin()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + iterator referring to the first element + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.end()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + iterator referring to the <i>past-the-end</i> element + </td> + </tr> + <tr> + <td> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.begin_slice(</b><i>slice_number</i><b>)</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + iterator referring to the first element of the specified slice + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.end_slice(</b><i>slice_number</i><b>)</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + iterator referring to the <i>past-the-end</i> element of the specified slice + </td> + </tr> + </tbody> +</table> +</ul> +</li> +<br> +<br> +<li> +Examples: +<ul> +<pre> +cube X = randu<cube>(2,3,4); + + +cube::iterator a = X.begin(); +cube::iterator b = X.end(); + +for(cube::iterator i=a; i!=b; ++i) + { + cout << *i << endl; + } + + +cube::slice_iterator c = X.begin_slice(1); // start of slice 1 +cube::slice_iterator d = X.end_slice(2); // end of slice 2 + +for(cube::slice_iterator i=c; i!=d; ++i) + { + cout << *i << endl; + (*i) = 123.0; + } +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="http://cplusplus.com/reference/std/iterator/">iterator at cplusplus.com</a></li> +<li><a href="#element_access">element access</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="memptr"></a> +<b>.memptr()</b> +<ul> +<li> +Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i> classes +</li> +<br> +<li> +Obtain a raw pointer to the memory used for storing elements. Not recommended for use unless you know what you're doing! +</li> +<br> +<li> +The function can be used for interfacing with libraries such as <a href="http://www.fftw.org/">FFTW</a> +</li> +<br> +<li> +As soon as the size of the matrix/vector/cube is changed, the pointer is no longer valid +</li> +<br> +<li> +Data for matrices is stored in a column-by-column order +</li> +<br> +<li> +Data for cubes is stored in a slice-by-slice (matrix-by-matrix) order +</li> +<br> +<li> +Examples: +<ul> +<pre> + mat A = randu<mat>(5,5); +const mat B = randu<mat>(5,5); + + double* A_mem = A.memptr(); +const double* B_mem = B.memptr(); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#colptr">.colptr()</a></li> +<li><a href="#element_access">element_access</a></li> +<li><a href="#iterators_mat">iterators (matrices)</a></li> +<li><a href="#iterators_cube">iterators (cubes)</a></li> +<li><a href="#adv_constructors_mat">advanced constructors (matrices)</a></li> +<li><a href="#adv_constructors_cube">advanced constructors (cubes)</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="min_and_max_member"></a> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"><b>.min()</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>) + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.max()</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.min(</b> index_of_min_val <b>)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>) + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.max(</b> index_of_max_val <b>)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.min(</b> row_of_min_val<b>,</b> col_of_min_val <b>)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member functions of <i>Mat</i>) + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.max(</b> row_of_max_val<b>,</b> col_of_max_val <b>)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> </td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.min(</b> row_of_min_val<b>,</b> col_of_min_val<b>,</b> slice_of_min_val <b>)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member functions of <i>Cube</i>) + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.max(</b> row_of_max_val<b>,</b> col_of_max_val<b>,</b> slice_of_max_val <b>)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> + </td> + </tr> + </tbody> +</table> +<ul> +<br> +<li> +Without arguments: return the extremum value of an object +</li> +<br> +<li> +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) +</li> +<br> +<li> +The provided variables must be of type <a href="#uword">uword</a>. +</li> +<br> +<li> +Examples: +<ul> +<pre> +vec v = randu<vec>(10); + +cout << "min value is " << v.min() << endl; + + +uword index; +double min_val = v.min(index); + +cout << "index of min value is " << index << endl; + + +mat A = randu<mat>(5,5); + +uword row; +uword col; +double min_val2 = A.max(row,col); + +cout << "max value is at " << row << ',' << col << endl; +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#min_and_max">min() & max()</a> (standalone functions)</li> +<li><a href="#running_stat">running_stat</a></li> +<li><a href="#running_stat_vec">running_stat_vec</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="ones_member"></a> +<b>.ones()</b> +<br><b>.ones(n_elem)</b> +<br><b>.ones(n_rows, n_cols)</b> +<br><b>.ones(n_rows, n_cols, n_slices)</b> +<ul> +<li> +Set the elements of an object to one, optionally first resizing to specified dimensions +</li> +<br> +<li> +<i>.ones()</i> and <i>.ones(n_elem)</i> are member functions of <i>Col</i> and <i>Row</i> +</li> +<br> +<li> +<i>.ones()</i> and <i>.ones(n_rows, n_cols)</i> are member functions of <i>Mat</i> +</li> +<br> +<li> +<i>.ones()</i> and <i>.ones(n_rows, n_cols, n_slices)</i> are member functions of <i>Cube</i> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,10); +A.ones(); // sets all elements to one +A.ones(10,20); // sets the size to 10 rows and 20 columns + // followed by setting all elements to one +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#ones_standalone">ones()</a> (standalone function)</li> +<li><a href="#eye_member">.eye()</a></li> +<li><a href="#zeros_member">.zeros()</a></li> +<li><a href="#fill">.fill()</a></li> +<li><a href="#imbue">.imbue()</a></li> +<li><a href="#randu_randn_member">.randu()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="operators"></a> +<b>operators: + - * / % == != <= >= < ></b> +<ul> +<li> +Overloaded operators for <i>mat</i>, <i>vec</i>, <i>rowvec</i> and <i>cube</i> classes +</li> +<br> +<li> +Meanings: +<br> +<br> +<ul> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"><b>+</b></td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;">Addition of two objects</td> + </tr> + <tr> + <td style="vertical-align: top;"><b>-</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">Subtraction of one object from another or negation of an object</td> + </tr> + <tr> + <td style="vertical-align: top;"><b>/</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">Element-wise division of an object by another object or a scalar</td> + </tr> + <tr> + <td style="vertical-align: top;"><b>*</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">Matrix multiplication of two objects; not applicable to the <i>cube</i> class unless multiplying a cube by a scalar</td> + </tr> + <tr> + <td style="vertical-align: top;"><b>%</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"><a name="schur_product"></a>Schur product: element-wise multiplication of two objects</td> + </tr> + <tr> + <td style="vertical-align: top;"><b>==</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">Element-wise equality evaluation of two objects; generates a matrix of type <i>umat</i> with entries that indicate whether at a given position the two elements from the two objects are equal (1) or not equal (0)</td> + </tr> + <tr> + <td style="vertical-align: top;"><b>!=</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">Element-wise non-equality evaluation of two objects</td> + </tr> + <tr> + <td style="vertical-align: top;"><b>>=</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">As for ==, but the check is for "greater than or equal to"</td> + </tr> + <tr> + <td style="vertical-align: top;"><b><=</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">As for ==, but the check is for "less than or equal to"</td> + </tr> + <tr> + <td style="vertical-align: top;"><b>></b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">As for ==, but the check is for "greater than"</td> + </tr> + <tr> + <td style="vertical-align: top;"><b><</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">As for ==, but the check is for "less than"</td> + </tr> + </tbody> +</table> +</ul> +</li> +<br> +<li> +A <i>std::logic_error</i> exception is thrown if incompatible object sizes are used +</li> +<br> +<li> +If the +, - and % operators are chained, Armadillo will try to avoid the generation of temporaries; +no temporaries are generated if all given objects are of the same type and size +</li> +<br> +<li> +If the * operator is chained, Armadillo will try to find an efficient ordering of the matrix multiplications +</li> +<br> +<li> +<b>Caveat:</b> operators involving an equality comparison (ie., ==, !=, >=, <=) +may not work as expected for floating point element types (ie., <i>float</i>, <i>double</i>) +due to the necessarily limited precision of these types; +in other words, these operators are (in general) not recommended for matrices of type <i>mat</i> or <i>fmat</i> +</li> +<br> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,10); +mat B = randu<mat>(5,10); +mat C = randu<mat>(10,5); + +mat P = A + B; +mat Q = A - B; +mat R = -B; +mat S = A / 123.0; +mat T = A % B; +mat U = A * C; + +// V is constructed without temporaries +mat V = A + B + A + B; + +imat AA = "1 2 3; 4 5 6; 7 8 9;"; +imat BB = "3 2 1; 6 5 4; 9 8 7;"; + +// compare elements +umat ZZ = (AA >= BB); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#accu">accu()</a></li> +<li><a href="#as_scalar">as_scalar()</a></li> +<li><a href="#find">find()</a></li> +<li><a href="#transform">.transform()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="print"></a> +<b>.print(header="")</b> +<br><b>.print(stream, header="")</b> +<ul> +<li> +Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i> +</li> +<br> +<li> +The first form prints the contents of an object to the <i>std::cout</i> stream, with an optional header line +</li> +<br> +<li> +The second form prints to a user specified stream +</li> +<br> +<li> +It's also possible to print objects using the << stream operator +</li> +<br> +<li> +Elements of a field can only be printed if there is an associated <i>operator<<</i> function defined +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +mat B = randu<mat>(6,6); + +A.print(); + +// print a transposed version of A +A.t().print(); + +// "B:" is the optional header line +B.print("B:"); + +cout << A << endl; +cout << "B:" << endl << B << endl; +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#raw_print">.raw_print()</a></li> +<li><a href="#save_load_mat">saving & loading matrices</a></li> +<li><a href="#element_initialisation">initialising elements</a></li> +<li><a href="#logging">logging of errors and warnings</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="raw_print"></a> +<b>.raw_print(header="")</b> +<br><b>.raw_print(stream, header="")</b> +<ul> +<li> +Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i> +</li> +<br> +<li> +Similar to the <a href="#print">.print()</a> member function, +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. +</li> +<br> +<li> +If the cell width is set to zero, a space is printed between the elements +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); + +cout.precision(11); +cout.setf(ios::fixed); + +A.raw_print(cout, "A ="); +</pre> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="randu_randn_member"></a> +<b>.randu()</b> +<br><b>.randu(n_elem)</b> +<br><b>.randu(n_rows, n_cols)</b> +<br><b>.randu(n_rows, n_cols, n_slices)</b> +<br> +<br> +<b>.randn()</b> +<br><b>.randn(n_elem)</b> +<br><b>.randn(n_rows, n_cols)</b> +<br><b>.randn(n_rows, n_cols, n_slices)</b> +<ul> +<li> +Fill an object with random values, optionally first resizing to specified dimensions +</li> +<br> +<li><i>.randu()</i> uses a uniform distribution in the [0,1] interval +</li> +<br> +<li><i>.randn()</i> uses a normal/Gaussian distribution with zero mean and unit variance +</li> +<br> +<li> +To change the seed, use the <a href="http://cplusplus.com/reference/clibrary/cstdlib/srand/">std::srand()</a> function +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A(4,5); +A.randu(); + +mat B; +B.randu(6,7); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#randu_randn_standalone">randu() & randn()</a> (standalone functions)</li> +<li><a href="#fill">.fill()</a></li> +<li><a href="#imbue">.imbue()</a></li> +<li><a href="#ones_member">.ones()</a></li> +<li><a href="#zeros_member">.zeros()</a></li> +<li><a href="http://cplusplus.com/reference/clibrary/cstdlib/srand/">std::srand()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="reset"></a> +<b> +.reset() +</b> +<ul> +<li> +Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i> +</li> +<br> +<li> +Causes an object to have no elements +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5, 5); +A.reset(); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#set_size">.set_size()</a></li> +<li><a href="#is_empty">.is_empty()</a></li> +<li><a href="#zeros_member">.zeros()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="reshape_member"></a> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"><b>.reshape(n_rows, n_cols, dim=0)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>) + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.reshape(n_rows, n_cols, n_slices, dim=0)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member function of <i>Cube</i>) + </td> + </tr> + </tbody> +</table> +<br> +<ul> +<li> +Recreate the object according to given size specifications, +with the elements taken from the previous version of the object, +either column-wise (dim=0) or row-wise (dim=1); +the elements in the generated object are placed column-wise (ie. the first column is filled up before filling the second column) +</li> +<br> +<li> +The layout of the elements in the recreated object will be different to the layout in the previous version of the object +</li> +<br> +<li> +This function can be used to vectorise a matrix (ie. concatenate all the columns or rows) +</li> +<br> +<li> +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 +</li> +<br> +<li> +If the total number of elements in the previous version of the object is less than the specified size, +the extra elements in the recreated object are set to zero +</li> +<br> +<li> +If the total number of elements in the previous version of the object is greater than the specified size, +only a subset of the elements is taken +</li> +<br> +<li> +<b>Caveat:</b> +.reshape() is slower than <a href="#set_size">.set_size()</a>, which doesn't preserve data +</li> +<br> +<li> +<b>Caveat:</b> +if you wish to grow/shrink the object while preserving the elements <b>as well as</b> the layout of the elements, +use <a href="#resize_member">.resize()</a> instead +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(4,5); +A.reshape(5,4); + +// vectorise A into a column vector: +A.reshape(A.n_elem, 1); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#resize_member">.resize()</a></li> +<li><a href="#set_size">.set_size()</a></li> +<li><a href="#copy_size">.copy_size()</a></li> +<li><a href="#zeros_member">.zeros()</a></li> +<li><a href="#reset">.reset()</a></li> +<li><a href="#reshape">reshape()</a> (standalone function)</li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="resize_member"></a> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"><b>.resize(n_elem)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member function of <i>Col</i>, <i>Row</i>) + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.resize(n_rows, n_cols)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member function of <i>Mat</i>) + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.resize(n_rows, n_cols, n_slices)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member function of <i>Cube</i>) + </td> + </tr> + </tbody> +</table> +<br> +<ul> +<li> +Recreate the object according to given size specifications, while preserving the elements as well as the layout of the elements +</li> +<br> +<li> +Can be used for growing or shrinking an object (ie. adding/removing rows, and/or columns, and/or slices) +</li> +<br> +<li> +<b>Caveat:</b> +.resize() is slower than <a href="#set_size">.set_size()</a>, which doesn't preserve data +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(4,5); +A.resize(7,6); +</pre> +</ul> +</li> +<br> +<li> +This function was added in version 2.4 +</li> +<br> +<li>See also: +<ul> +<li><a href="#reshape_member">.reshape()</a></li> +<li><a href="#set_size">.set_size()</a></li> +<li><a href="#copy_size">.copy_size()</a></li> +<li><a href="#zeros_member">.zeros()</a></li> +<li><a href="#reset">.reset()</a></li> +<li><a href="#insert">insert rows/cols/slices</a></li> +<li><a href="#shed">shed rows/cols/slices</a></li> +<li><a href="#resize">resize()</a> (standalone function)</li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="save_load_mat"></a> +<b> +.save(name, file_type = arma_binary) +<br> +.save(stream, file_type = arma_binary) +<br> +<br> +.load(name, file_type = auto_detect) +<br> +.load(stream, file_type = auto_detect) +<br> +<br> +.quiet_save(name, file_type = arma_binary) +<br> +.quiet_save(stream, file_type = arma_binary) +<br> +<br> +.quiet_load(name, file_type = auto_detect) +<br> +.quiet_load(stream, file_type = auto_detect) +</b> +<ul> +<li>Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i> classes</li> +<br> +<li>Store/retrieve data in files or streams</li> +<br> +<li>On success, <i>save()</i>, <i>load()</i>, <i>quiet_save()</i>, and <i>quite_load()</i> will return a <i>bool</i> set to <i>true</i></li> +<br> +<li><i>save()</i> and <i>quiet_save()</i> will return a <i>bool</i> set to <i>false</i> if the saving process fails</li> +<br> +<li> +<i>load()</i> and <i>quiet_load()</i> will return a <i>bool</i> set to <i>false</i> if the loading process fails; +additionally, the object will be reset so it has no elements +</li> +<br> +<li><i>load()</i> and <i>save()</i> will print warning messages if any problems are encountered</li> +<br> +<li><i>quiet_load()</i> and <i>quiet_save()</i> do not print any error messages</li> +<br> +<li> +The following file formats are supported: +<br> +<br> +<ul> + <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"><b>auto_detect</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +for <i>load()</i> and <i>quiet_load()</i>: +try to automatically detect the file type as one of the formats described below. +This is the default operation. +<br> +<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>raw_ascii</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +Numerical data stored in raw ASCII format, without a header. +The numbers are separated by whitespace. +The number of columns must be the same in each row. +Cubes are loaded as one slice. +Data which was saved in Matlab/Octave using the <i>-ascii</i> option can be read in Armadillo, except for complex numbers. +Complex numbers are stored in standard C++ notation, which is a tuple surrounded by brackets: eg. (1.23,4.56) indicates 1.24 + 4.56i. +<br> +<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>raw_binary</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +Numerical data stored in machine dependent raw binary format, without a header. +Matrices are loaded to have one column, +while cubes are loaded to have one slice with one column. +The <a href="#reshape_member">.reshape()</a> function can be used to alter the size of the loaded matrix/cube without losing data. +<br> +<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>arma_ascii</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +Numerical data stored in human readable text format, with a simple header to speed up loading. +The header indicates the type of matrix as well as the number of rows and columns. +For cubes, the header additionally specifies the number of slices. +<br> +<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>arma_binary</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +Numerical data stored in machine dependent binary format, with a simple header to speed up loading. +The header indicates the type of matrix as well as the number of rows and columns. +For cubes, the header additionally specifies the number of slices. +<br> +<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>csv_ascii</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +Numerical data stored in comma separated value (CSV) text format, without a header. +Applicable to <i>Mat</i> only. +<br> +<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>hdf5_binary</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +Numerical data stored in portable HDF5 binary format. +<br> +<b>Caveat</b>: +support for HDF5 must be enabled within Armadillo's <a href="#config_hpp">configuration</a>; +the <i>hdf5.h</i> header file must be available on your system and you will need to link with the hdf5 library (eg. -lhdf5). +Support for saving & loading of <i>Cube</i> objects was added in version 3.830. +<br> +<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>pgm_binary</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +Image data stored in Portable Gray Map (PGM) format. +Applicable to <i>Mat</i> only. +Saving <i>int</i>, <i>float</i> or <i>double</i> matrices is a lossy operation, as each element is copied and converted to an 8 bit representation. +As such the matrix should have values in the [0,255] interval, otherwise the resulting image may not display correctly. +<br> +<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>ppm_binary</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +Image data stored in Portable Pixel Map (PPM) format. +Applicable to <i>Cube</i> only. +Saving <i>int</i>, <i>float</i> or <i>double</i> matrices is a lossy operation, as each element is copied and converted to an 8 bit representation. +As such the cube/field should have values in the [0,255] interval, otherwise the resulting image may not display correctly. + </td> + </tr> + </tbody> + </table> +</ul> +</li> +<br> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); + +A.save("A1.mat"); // default save format is arma_binary +A.save("A2.mat", arma_ascii); + +mat B; +// automatically detect format type +B.load("A1.mat"); + +mat C; +// force loading in the arma_ascii format +C.load("A2.mat", arma_ascii); + + +// example of saving/loading using a stream +std::stringstream s; +A.save(s); + +mat D; +D.load(s); + + +// example of testing for success +mat E; +bool status = E.load("A2.mat"); + +if(status == true) + { + cout << "loaded okay" << endl; + } +else + { + cout << "problem with loading" << endl; + } +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#save_load_field">saving/loading fields</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="save_load_field"></a> +<b> +.save(name, file_type = arma_binary) +<br> +.save(stream, file_type = arma_binary) +<br> +<br> +.load(name, file_type = auto_detect) +<br> +.load(stream, file_type = auto_detect) +<br> +<br> +.quiet_save(name, file_type = arma_binary) +<br> +.quiet_save(stream, file_type = arma_binary) +<br> +<br> +.quiet_load(name, file_type = auto_detect) +<br> +.quiet_load(stream, file_type = auto_detect) +</b> +<ul> +<li>Member functions of the <i>field</i> class</li> +<br> +<li>Store/retrieve fields in files or stream</li> +<br> +<li>On success, save(), load(), quiet_save(), and quite_load() will return a <i>bool</i> set to <i>true</i></li> +<br> +<li>save() and quiet_save() will return a <i>bool</i> set to <i>false</i> if the saving process fails</li> +<br> +<li> +load() and quiet_load() will return a <i>bool</i> set to <i>false</i> if the loading process fails; +additionally, the field will be reset so it has no elements +</li> +<br> +<li>load() and save() will print warning messages if any problems are encountered</li> +<br> +<li>quiet_load() and quiet_save() do not print any error messages</li> +<br> +<li> +Fields with objects of type <i>std::string</i> are saved and loaded as raw text files. +The text files do not have a header. +Each string is separated by a whitespace. +load() and quiet_load() will only accept text files that have the same number of strings on each line. +The strings can have variable lengths. +</li> +<br> +<li> +Other than storing string fields as text files, the following file formats are supported: +<br> +<br> +<ul> + <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"><b>auto_detect</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +<br> +<li> +load(): try to automatically detect the field format type as one of the formats described below. +This is the default operation. +</li> +<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>arma_binary</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +<br> +<li> +Objects are stored in machine dependent binary format. +<li> +Default type for fields of type <i>Mat</i>, <i>Col</i> or <i>Row</i>. +</li> +<li> +Only applicable to fields of type <i>Mat</i>, <i>Col</i> or <i>Row</i>. +</li> +<br> + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>ppm_binary</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;"> +<br> +<li> +Image data stored in Portable Pixmap Map (PPM) format. +</li> +<li> +Only applicable to fields of type <i>Mat</i>, <i>Col</i> or <i>Row</i>. +</li> +<li> +.load(): Loads the specified image and stores the red, green and blue components as three separate matrices. +The resulting field is comprised of the three matrices, +with the red, green and blue components in the first, second and third matrix, respectively. +</li> +<li> +.save(): Saves a field with exactly three matrices of equal size as an image. +It is assumed that the red, green and blue components are stored in the first, second and third matrix, respectively. +Saving <i>int</i>, <i>float</i> or <i>double</i> matrices is a lossy operation, +as each matrix element is copied and converted to an 8 bit representation. +</li> + + </td> + </tr> + </tbody> + </table> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#save_load_mat">saving/loading matrices and cubes</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="set_imag"></a> +<b>.set_imag(X)</b> +<br> +<b>.set_real(X)</b> +<br> +<ul> +<li>Member functions of Mat, Col, Row and Cube</li> +<br> +<li> +Set the imaginary/real part of an object +</li> +<br> +<li> +<i>X</i> must have the same size as the recipient object +</li> +<br> +<li> +Examples: +<ul> +<pre> + mat A = randu<mat>(4,5); + mat B = randu<mat>(4,5); + +cx_mat C = zeros<cx_mat>(4,5); + +C.set_real(A); +C.set_imag(B); +</pre> +</ul> +</li> +<br> +<li> +<b>Caveat:</b> +if you want to directly construct a complex matrix out of two real matrices, +the following code is faster: +<ul> +<pre> + mat A = randu<mat>(4,5); + mat B = randu<mat>(4,5); + +cx_mat C = cx_mat(A,B); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#constructors_mat">matrix constructors</a></li> +<li><a href="#constructors_cube">cube constructors</a></li> +<li><a href="#imag_real">imag() / real()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="set_size"></a> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"><b>.set_size(n_elem)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member function of <i>Col</i>, <i>Row</i>, and <i>field</i>) + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.set_size(n_rows, n_cols)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member function of <i>Mat</i> and <i>field</i>) + </td> + </tr> + <tr> + <td style="vertical-align: top;"><b>.set_size(n_rows, n_cols, n_slices)</b></td> + <td style="vertical-align: top;"><br> + </td> + <td style="vertical-align: top;">(member function of <i>Cube</i>) + </td> + </tr> + </tbody> +</table> +<br> +<ul> +<li>Changes the size of an object</li> +<br> +<li> +If the requested number of elements is equal to the old number of elements, existing memory is reused +</li> +<br> +<li> +If the requested number of elements is not equal to the old number of elements, new memory is used; +the memory is uninitilised +</li> +<br> +<li> +If you need to initialise the memory, use <a href="#zeros_member">.zeros()</a> instead +</li> +<br> +<li> +If you need to explicitly preserve data, use <a href="#reshape_member">.reshape()</a> or <a href="#resize_member">.resize()</a> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A; +A.set_size(5,10); + +vec q; +q.set_size(100); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#reset">.reset()</a></li> +<li><a href="#copy_size">.copy_size()</a></li> +<li><a href="#reshape_member">.reshape()</a></li> +<li><a href="#resize_member">.resize()</a></li> +<li><a href="#zeros_member">.zeros()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="shed"></a> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + <b>.shed_row( </b>row_number<b> )</b> + <br> + <b>.shed_rows( </b>first_row, last_row<b> )</b> + </td> + <td style="vertical-align: top;"><br></td> + <td style="vertical-align: top;">(member functions of <i>Mat</i> and <i>Col</i>) + </td> + </tr> + <tr> + <td> </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.shed_col( </b>column_number<b> )</b> + <br> + <b>.shed_cols( </b>first_column, last_column<b> )</b> + </td> + <td style="vertical-align: top;"><br></td> + <td style="vertical-align: top;">(member functions of <i>Mat</i> and <i>Row</i>) + </td> + </tr> + <tr> + <td> </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.shed_slice( </b>slice_number<b> )</b> + <br> + <b>.shed_slices( </b>first_slice, last_slice<b> )</b> + </td> + <td style="vertical-align: top;"><br></td> + <td style="vertical-align: top;">(member functions of <i>Cube</i>) + </td> + </tr> + </tbody> +</table> +<br> +<ul> +<li> +Single argument functions: +remove the specified row/column/slice +</li> +<br> +<li> +Two argument functions: +remove the specified range of rows/columns/slices +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,10); + +A.shed_row(2); +A.shed_cols(2,4); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#insert">insert rows/columns/slices</a></li> +<li><a href="#join">join rows/columns/slices</a></li> +<li><a href="#resize_member">.resize()</a></li> +<li><a href="#submat">submatrix views</a></li> +<li><a href="#subcube">subcube views</a></li> +<li><a href="http://thesaurus.com/browse/shed"><i>shed</i> in thesaurus.com</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="stl_container_fns"></a> +<b>STL container functions</b> +<ul> +<li><i>Mat</i>, <i>Col</i> and <i>Row</i> classes provide the following member functions that mimic the containers in the C++ Standard Template Library:<br> +<br> + +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + <b>.clear()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + causes an object to have no elements + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.empty()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + returns true if the object has no elements; returns false if the object has one or more elements + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.size()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + returns the total number of elements + </td> + </tr> + </tbody> +</table> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +cout << A.size() << endl; + +A.clear(); +cout << A.empty() << endl; +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#iterators_mat">iterators (matrices)</a></li> +<li><a href="#attributes">matrix and vector attributes</a></li> +<li><a href="#is_empty">.is_empty()</a></li> +<li><a href="#reset">.reset()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="submat"></a> +<b>submatrix views</b> +<ul> +<li>A collection of member functions of <i>Mat</i>, <i>Col</i> and <i>Row</i> classes that provide read/write access to submatrix views<br> +<br> +<li>For a matrix or vector <i>X</i>, the subviews are accessed as:</li> +<br> +<ul> +<li>contiguous views: +<ul> +<br> +X.<b>col( </b>col_number<b> )</b><br> +X.<b>row( </b>row_number<b> )</b><br> +<br> +X.<b>cols( </b>first_col<b>,</b> last_col<b> )</b><br> +X.<b>rows( </b>first_row<b>,</b> last_row<b> )</b><br> +<br> +X<b>(</b> <b>span::all,</b> col_number <b>)</b><br> +X<b>(</b> <b>span(</b>first_row<b>,</b> last_row<b>),</b> col_number <b>)</b><br> +<br> +X<b>(</b> row_number<b>,</b> <b>span::all</b> <b>)</b><br> +X<b>(</b> row_number<b>,</b> <b>span(</b>first_col<b>,</b> last_col<b>) )</b><br> +<br> +X.<b>submat( </b>first_row<b>,</b> first_col<b>,</b> last_row<b>,</b> last_col<b> )</b><br> +X.<b>submat( span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b> last_col<b>) )</b><br> +<br> +X<b>( span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b> last_col<b>) )</b><br> +<br> +X.<b>unsafe_col( </b>col_number<b> )</b><br> +<br> +V.<b>subvec( </b>first_index<b>,</b> last_index<b> )</b> <i>(for vectors only)</i><br> +V<b>( span(</b>first_index<b>,</b> last_index<b>) )</b> <i>(for vectors only)</i><br> +</ul> +</li> +<br> +<li>non-contiguous views (added in version 3.0): +<ul> +<br> +X.<b>elem(</b> vector_of_indices <b>)</b><br> +X<b>(</b> vector_of_indices <b>)</b> <i>(added in version 3.810)</i><br> +<br> +X.<b>cols( </b>vector_of_column_indices<b> )</b><br> +X.<b>rows( </b>vector_of_row_indices<b> )</b><br> +<br> +X<b>(</b> vector_of_row_indices<b>,</b> vector_of_column_indices <b>)</b><br> +X.<b>submat(</b> vector_of_row_indices<b>,</b> vector_of_column_indices <b>)</b><br> +<!--X.<b>elem(</b> vector_of_row_indices<b>,</b> vector_of_column_indices <b>)</b><br>--> +</ul> +</li> +</ul> +<br> +<li> +Instances of <i>span::all</i>, to indicate an entire range, can be replaced by <i>span()</i>, where no number is specified +</li> +<br> +<li> +For functions requiring one or more vector of indices, +eg. <i>X.submat(vector_of_row_indices,vector_of_column_indices)</i>, +each vector of indices must be of type <i><a href="#Col">uvec</a></i>. +</li> +<br> +<li> +In the function <i>X.elem(vector_of_indices)</i>, +elements specified in <i>vector_of_indices</i> are accessed. +<i>X</i> is interpreted as one long vector, +with column-by-column ordering of the elements of <i>X</i>. +The <i>vector_of_indices</i> must evaluate to be a vector of type <i><a href="#Col">uvec</a></i> +(eg., generated by <i><a href="#find">find()</a></i>). +The aggregate set of the specified elements is treated as a column vector +(eg., the output of <i>X.elem()</i> is always a column vector). +</li> +<br> +<li> +The function <i>.unsafe_col()</i> is provided for speed reasons and should be used only if you know what you're doing. +The function creates a seemingly independent <i>Col</i> vector object (eg. <i>vec</i>), +but the vector actually uses memory from the existing matrix object. +As such, the created <i>Col</i> vector is currently not alias safe +and does not take into account that the parent matrix object could be deleted. +If deleted memory is accessed through the created <i>Col</i> vector, +it will cause memory corruption and/or a crash. +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = zeros<mat>(5,10); + +A.submat(0,1,2,3) = randu<mat>(3,3); + +// the following three statements +// access the same part of A +mat B = A.submat(0,1,2,3); +mat C = A.submat( span(0,2), span(1,3) ); +mat D = A( span(0,2), span(1,3) ); + +// the following two statements +// access the same part of A +A.col(1) = randu<mat>(5,1); +A(span::all, 1) = randu<mat>(5,1); + +mat X = randu<mat>(5,5); + +// get all elements of X that are greater than 0.5 +vec q = X.elem( find(X > 0.5) ); + +// set four specific elements of X to 1 +uvec indices; +indices << 2 << 3 << 6 << 8; + +X.elem(indices) = ones<vec>(4); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#diag">diagonal views</a> (read/write access to diagonals)</li> +<li><a href="#each_colrow">.each_col() & .each_row()</a> (vector operations repeated on each column or row)</li> +<li><a href="#colptr">.colptr()</a></li> +<li><a href="#in_range">.in_range()</a></li> +<li><a href="#find">find()</a></li> +<li><a href="#join">join rows/columns/slices</a></li> +<li><a href="#shed">shed rows/columns/slices</a></li> +<li><a href="#insert">insert rows/columns/slices</a></li> +<li><a href="#subcube">subcube views</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="subcube"></a> +<b>subcube views and slices</b> +<ul> +<li>A collection of member functions of the <i>Cube</i> class that provide subcube views<br> +<br> +<li>For a cube <i>Q</i>, the subviews are accessed as:</li> +<br> +<ul> +Q.<b>slice( </b>slice_number <b>)</b><br> +Q.<b>slices( </b>first_slice<b>,</b> last_slice <b>)</b><br> +<br> +Q.<b>subcube( </b>first_row<b>,</b> first_col<b>,</b> first_slice<b>, </b>last_row<b>,</b> last_col<b>, </b>last_slice <b>)</b><br> +Q.<b>subcube( span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b> last_col<b>), span(</b>first_slice<b>,</b> last_slice<b>) )</b><br> +<br> +Q<b>( span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b> last_col<b>), span(</b>first_slice<b>,</b> last_slice<b>) )</b><br> +</ul> +</li> +<br> +<li> +Instances of <i>span(a,b)</i> can be replaced by: +<ul> +<li><i>span()</i> or <i>span::all</i>, to indicate the entire range</li> +<li><i>span(a)</i>, to indicate a particular row, column or slice</li> +</ul> +</li> +<br> +<li> +An individual slice, accessed via <i>.slice()</i>, is an instance of the <i>Mat</i> class +(a reference to a matrix is provided) +</li> +<br> +<li> +Examples: +<ul> +<pre> +cube A = randu<cube>(2,3,4); +mat B = A.slice(1); + +A.slice(0) = randu<mat>(2,3); +A.slice(0)(1,2) = 99.0; + +A.subcube(0,0,1, 1,1,2) = randu<cube>(2,2,2); +A( span(0,1), span(0,1), span(1,2) ) = randu<cube>(2,2,2); + +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#in_range">.in_range()</a></li> +<li><a href="#join">join slices</a></li> +<li><a href="#shed">shed slices</a></li> +<li><a href="#insert">insert slices</a></li> +<li><a href="#submat">submatrix views</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="subfield"></a> +<b>subfield views</b> +<ul> +<li>A collection of member functions of the <i>field</i> class that provide subfield views<br> +<br> +<li>For a field <i>F</i>, the subfields are accessed as:</li> +<br> +<ul> +F.<b>row( </b>row_number <b>)</b><br> +F.<b>col( </b>col_number <b>)</b><br> +<br> +F.<b>rows( </b>first_row<b>,</b> last_row <b>)</b><br> +F.<b>cols( </b>first_col<b>,</b> last_col <b>)</b><br> +<br> +F.<b>subfield( </b>first_row<b>,</b> first_col<b>,</b> last_row<b>,</b> last_col <b>)</b><br> +F.<b>subfield( span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b> last_col<b>) )</b><br> +<br> +F<b>( span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b> last_col<b>) )</b><br> +</ul> +</li> +<br> +<li> +Instances of <i>span(a,b)</i> can be replaced by: +<ul> +<li><i>span()</i> or <i>span::all</i>, to indicate the entire range</li> +<li><i>span(a)</i>, to indicate a particular row or column</li> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#in_range">.in_range()</a></li> +<li><a href="#submat">submatrix views</a></li> +<li><a href="#subcube">subcube views</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="swap"></a> +<b>.swap(</b>X<b>)</b> +<ul> +<li> +Swap contents with matrix <i>X</i> +</li> +<br> +<li> +This function was added in version 3.800 +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = zeros<mat>(4,5); +mat B = ones<mat>(6,7); + +A.swap(B); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#swap_rows">.swap_rows() & .swap_cols()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="swap_rows"></a> +<b> +.swap_rows(row1, row2) +<br>.swap_cols(col1, col2) +</b> +<ul> +<li> +Member functions of <i>Mat</i>, <i>Col</i> and <i>Row</i> classes +</li> +<br> +<li> +Swap the contents of specified rows or columns +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat X = randu<mat>(5,5); +X.swap_rows(0,4); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#flip">fliplr() & flipud()</a></li> +<li><a href="#swap">.swap()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="t_st_members"></a> +<b> +.t() +<br>.st() +</b> +<ul> +<li> +Member functions of any matrix or vector expression +</li> +<br> +<li> +<i>.t()</i> 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) +</li> +<br> +<li> +<i>.st()</i> provides a transposed copy of the object, without taking the conjugate of the elements (complex matrices) +</li> +<br> +<li> +For non-complex objects, the <i>.t()</i> and <i>.st()</i> functions are equivalent +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(4,5); +mat B = A.t(); +</pre> +</ul> +</li> +<br> +<li> +The <i>.t()</i> and <i>.st()</i> functions were added in version 2.4 +</li> +<br> +<li> +See also: +<ul> +<li><a href="#trans">trans()</a></li> +<li><a href="#strans">strans()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="transform"></a> +<b>.transform( </b>functor<b> )</b> +<br> +<b>.transform( </b>lambda function<b> )</b> <i>(C++11 only)</i> +<br> +<ul> +<li> +Transform each element using a functor or lambda function +</li> +<br> +<li> +For matrices, transformation is done column-by-column (ie. column 0 is transformed, then column 1, ...) +</li> +<br> +<li> +For cubes, transformation is done slice-by-slice; each slice is transformed column-by-column +</li> +<br> +<li> +This function was added in version 3.800 +</li> +<br> +<li> +Examples: +<ul> +<pre> +// C++11 only example + +mat A = ones<mat>(4,5); + +// add 123 to every element +A.transform( [](double val) { return (val + 123.0); } ); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#operators">overloaded operators</a></li> +<li><a href="#imbue">.imbue()</a></li> +<li><a href="#fill">.fill()</a></li> +<li><a href="http://en.wikipedia.org/wiki/Function_object">function object</a> at Wikipedia</li> +<li><a href="http://en.wikipedia.org/wiki/C%2B%2B11#Lambda_functions_and_expressions">C++11 lambda functions</a> at Wikipedia</li> +<li><a href="http://www.cprogramming.com/c++11/c++11-lambda-closures.html">lambda function</a> at cprogramming.com</li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="zeros_member"></a> +<b>.zeros()</b> +<br><b>.zeros(n_elem)</b> +<br><b>.zeros(n_rows, n_cols)</b> +<br><b>.zeros(n_rows, n_cols, n_slices)</b> +<ul> +<li> +Set the elements of an object to zero, optionally first resizing to specified dimensions +</li> +<br> +<li> +<i>.zeros()</i> and <i>.zeros(n_elem)</i> are member function of <i>Col</i> and <i>Row</i> +</li> +<br> +<li> +<i>.zeros()</i> and <i>.zeros(n_rows, n_cols)</i> are member functions of <i>Mat</i> +</li> +<br> +<li> +<i>.zeros()</i> and <i>.zeros(n_rows, n_cols, n_slices)</i> are member functions of <i>Cube</i> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,10); +A.zeros(); // sets all elements to zero +A.zeros(10,20); // sets the size to 10 rows and 20 columns + // followed by setting all elements to zero +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#zeros_standalone">zeros()</a> (standalone function)</li> +<li><a href="#ones_member">.ones()</a></li> +<li><a href="#randu_randn_member">.randu()</a></li> +<li><a href="#fill">.fill()</a></li> +<li><a href="#imbue">.imbue()</a></li> +<li><a href="#reset">.reset()</a></li> +<li><a href="#set_size">.set_size()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"> + + +<hr class="greyline"> +<br> +<br> +<font size=+1><b>Other Classes</b></font> +<br> +<br> +<hr class="greyline"> +<br> + +<a name="running_stat"></a> +<b>running_stat<</b><i>type</i><b>></b> +<ul> +<li> +Class for keeping statistics of a continuously sampled one dimensional process/signal. +Useful if the storage of individual samples (scalars) is not necessary or desired. +Also useful if the number of samples is not known beforehand or exceeds available memory. +</li> +<br> +<li> +<i>type</i> should be one of: <i>float</i>, <i>double</i>, <i><a href="#cx_float_double">cx_float</a></i>, <i><a href="#cx_float_double">cx_double</a></i> +</li> +<br> +<li> +Member functions: +<ul> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + <b>.operator()(</b>scalar<b>)</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + update the statistics so far using the given scalar + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.mean()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + get the mean or average value so far + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.var(</b>norm_type=0<b>)</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + get the variance so far + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.stddev(</b>norm_type=0<b>)</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + get the standard deviation so far + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.min()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + get the minimum value so far + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.max()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + get the maximum value so far + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.reset()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + reset all statistics and set the number of samples to zero + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.count()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + get the number of samples so far + </td> + </tr> + </tbody> +</table> +</ul> +</li> +<br> +<li> +For the .var() and .stddev() functions, the default <i>norm_type=0</i> performs normalisation using <i>N-1</i> +(where <i>N</i> is the number of samples so far), +providing the best unbiased estimator. +Using <i>norm_type=1</i> causes normalisation to be done using <i>N</i>, which provides the second moment around the mean. +</li> +<br> +<li> +The return type of .count() depends on the underlying form of <i>type</i>: it is either <i>float</i> or <i>double</i>. +</li> +<br> +<li> +Examples: +<ul> +<pre> +running_stat<double> stats; + +for(uword i=0; i<10000; ++i) + { + double sample = double(rand())/RAND_MAX; + stats(sample); + } + +cout << "mean = " << stats.mean() << endl; +cout << "var = " << stats.var() << endl; +cout << "min = " << stats.min() << endl; +cout << "max = " << stats.max() << endl; +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#stats_fns">statistics functions</a></li> +<li><a href="#running_stat_vec">running_stat_vec</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="running_stat_vec"></a> +<b>running_stat_vec<</b><i>type</i><b>>(calc_cov = false)</b> +<ul> +<li> +Class for keeping statistics of a continuously sampled multi-dimensional process/signal. +Useful if the storage of individual samples is not necessary or desired. +Also useful if the number of samples is not known beforehand or exceeds available memory. +</li> +<br> +<li> +This class is similar to <i>running_stat</i>, with the difference being that vectors are processed instead of single values. +</li> +<br> +<li> +<i>type</i> must match the element type used by the sample vectors +(ie. it must be one of <i>float</i>, <i>double</i>, <i><a href="#cx_float_double">cx_float</a></i>, <i><a href="#cx_float_double">cx_double</a></i>) +</li> +<br> +<li> +<i>type</i> can be inferred via the use of the <i>elem_type</i> member typedef of a vector class. +For example, <i>fvec::elem_type</i> will be interpreted as <i>float</i>, +while <i>cx_vec::elem_type</i> will be interpreted as <i><a href="#cx_float_double">cx_double</a></i>. +</li> +<br> +<li> +Member functions: +<ul> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td style="vertical-align: top;"> + <b>.operator()(</b>vector<b>)</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + update the statistics so far using the given vector + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.mean()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + get the mean vector so far + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.var(</b>norm_type=0<b>)</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + get the vector of variances so far + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.stddev(</b>norm_type=0<b>)</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + get the vector of standard deviations so far + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.min()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + get the vector of minimum values so far + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.max()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + get the vector of maximum values so far + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.cov(</b>norm_type=0<b>)</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + get the covariance matrix so far + <br>NOTE: this only works if <i>calc_cov</i> is set to <i>true</i> during the construction of the class + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.reset()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + reset all statistics and set the number of samples to zero + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>.count()</b> + </td> + <td style="vertical-align: top;"> <br> + </td> + <td style="vertical-align: top;"> + get the number of samples so far + </td> + </tr> + </tbody> +</table> +</ul> +</li> +<br> +<li> +For the .var() and .stddev() functions, the default <i>norm_type=0</i> performs normalisation using <i>N-1</i> +(where <i>N</i> is the number of samples so far), +providing the best unbiased estimator. +Using <i>norm_type=1</i> causes normalisation to be done using <i>N</i>, which provides the second moment around the mean. +</li> +<br> +<li> +The return type of .count() depends on the underlying form of <i>type</i>: it is either <i>float</i> or <i>double</i>. +</li> +<br> +<li> +Examples: +<ul> +<pre> +running_stat_vec<rowvec::elem_type> stats; + +rowvec sample; + +for(uword i=0; i<10000; ++i) + { + sample = randu<rowvec>(5); + stats(sample); + } + +cout << "mean = " << stats.mean() << endl; +cout << "var = " << stats.var() << endl; +cout << "min = " << stats.min() << endl; +cout << "max = " << stats.max() << endl; + +// +// + +running_stat_vec<rowvec::elem_type> more_stats(true); + +for(uword i=0; i<20; ++i) + { + sample = randu<rowvec>(3); + + sample(1) -= sample(0); + sample(2) += sample(1); + + more_stats(sample); + } + +cout << "covariance matrix = " << endl; +cout << more_stats.cov() << endl; + +rowvec sd = more_stats.stddev(); + +cout << "correlations = " << endl; +cout << more_stats.cov() / (sd.t() * sd); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#cov">cov()</a></li> +<li><a href="#cor">cor()</a></li> +<li><a href="#running_stat">running_stat</a></li> +<li><a href="#stats_fns">statistics functions</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="wall_clock"></a> +<b>wall_clock</b> +<ul> +<li> +Simple wall clock timer class, for measuring the number of elapsed seconds between two intervals +</li> +<br> +<li> +Examples: +<ul> +<pre> +wall_clock timer; + +mat A = randu<mat>(4,4); +mat B = randu<mat>(4,4); +mat C; + +timer.tic(); +for(uword i=0; i<100000; ++i) + C = A + B + A + B; + +double n_secs = timer.toc(); +cout << "took " << n_secs << " seconds" << endl; +</pre> +</ul> +</li> +</ul> +<br> +<hr class="greyline"> + +<hr class="greyline"> +<br> +<br> +<font size=+1><b>Generated Vectors/Matrices</b></font> +<br> +<br> +<hr class="greyline"> +<br> + +<a name="eye_standalone"></a> +<b>eye(n_rows, n_cols)</b> +<ul> +<li> +Generate a matrix with the elements along the main diagonal set to one +and off-diagonal elements set to zero +</li> +<br> +<li> +An identity matrix is generated when <i>n_rows</i> = <i>n_cols</i> +</li> +<br> +<li> +Usage: +<ul> +<li> +<i>matrix_type</i> X = eye<<i>matrix_type</i>>(n_rows, n_cols) +</li> +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = eye<mat>(5,5); +mat B = 123.0 * eye<mat>(5,5); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#eye_member">.eye()</a> (member function of Mat)</li> +<li><a href="#diag">.diag()</a></li> +<li><a href="#ones_standalone">ones()</a></li> +<li><a href="#diagmat">diagmat()</a></li> +<li><a href="#diagvec">diagvec()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="linspace"></a> +<b>linspace(start, end, N=100)</b> +<ul> +<li> +Generate a vector with <i>N</i> elements; +the values of the elements linearly increase from <i>start</i> upto (and including) <i>end</i> +<br> +</li> +<br> +<li> +Usage: +<ul> +<li><i>vector_type</i> v = linspace<<i>vector_type</i>>(start, end, N)</li> +<li><i>matrix_type</i> X = linspace<<i>matrix_type</i>>(start, end, N)</li> +</ul> +</li> +<br> +<li> +If a <i>matrix_type</i> is specified, the resultant matrix will have one column +</li> +<br> +<li> +Examples: +<ul> +<pre> +vec v = linspace<vec>(10, 20, 5); +mat X = linspace<mat>(10, 20, 5); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#ones_standalone">ones()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + + + +<a name="ones_standalone"></a> +<b> +ones(n_elem) +<br>ones(n_rows, n_cols) +<br>ones(n_rows, n_cols, n_slices) +</b> +<ul> +<li> +Generate a vector, matrix or cube with all elements set to one +</li> +<br> +<li> +Usage: +<ul> +<li><i>vector_type</i> v = ones<<i>vector_type</i>>(n_elem)</li> +<li><i>matrix_type</i> X = ones<<i>matrix_type</i>>(n_rows, n_cols)</li> +<li><i>cube_type</i> Q = ones<<i>cube_type</i>>(n_rows, n_cols, n_slices)</li> +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre> +vec v = ones<vec>(10); +uvec u = ones<uvec>(11); +mat A = ones<mat>(5,6); +cube Q = ones<cube>(5,6,7); + +mat B = 123.0 * ones<mat>(5,6); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#ones_member">.ones()</a> (member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i>)</li> +<li><a href="#eye_standalone">eye()</a></li> +<li><a href="#linspace">linspace()</a></li> +<li><a href="#zeros_standalone">zeros()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="randu_randn_standalone"></a> +<b>randu(n_elem)</b> +<br><b>randu(n_rows, n_cols)</b> +<br><b>randu(n_rows, n_cols, n_slices)</b> +<br> +<br><b>randn(n_elem)</b> +<br><b>randn(n_rows, n_cols)</b> +<br><b>randn(n_rows, n_cols, n_slices)</b> +<ul> +<li> +Generate a vector, matrix or cube with the elements set to random values +</li> +<br> +<li><i>randu()</i> uses a uniform distribution in the [0,1] interval +</li> +<br> +<li><i>randn()</i> uses a normal/Gaussian distribution with zero mean and unit variance +</li> +<br> +<li> +Usage: +<ul> +<li><i>vector_type</i> v = randu<<i>vector_type</i>>(n_elem)</li> +<li><i>matrix_type</i> X = randu<<i>matrix_type</i>>(n_rows, n_cols)</li> +<li><i>cube_type</i> Q = randu<<i>cube_type</i>>(n_rows, n_cols, n_slices)</li> +</ul> +</li> +<br> +<li> +To change the seed, use the <a href="http://cplusplus.com/reference/clibrary/cstdlib/srand/">std::srand()</a> function. +</li> +<br> +<li> +Examples: +<ul> +<pre> +vec v = randu<vec>(5); +mat A = randu<mat>(5,6); +cube Q = randu<cube>(5,6,7); +</pre> +</ul> +</li> +<li>See also: +<ul> +<li><a href="#randu_randn_member">.randu() & .randn()</a> (member functions)</li> +<li><a href="#imbue">.imbue()</a></li> +<li><a href="#ones_standalone">ones()</a></li> +<li><a href="#zeros_standalone">zeros()</a></li> +<li><a href="#shuffle">shuffle()</a></li> +<li><a href="http://cplusplus.com/reference/clibrary/cstdlib/srand/">std::srand()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="repmat"></a> +<b>repmat(A, num_copies_per_row, num_copies_per_col)</b> +<ul> +<li>Generate a matrix by replicating matrix A in a block-like fashion</li> +<br> +<li>The generated matrix has the following size: +<ul> +rows = num_copies_per_row * A.n_rows +<br> +cols = num_copies_per_col * A.n_cols +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(2, 3); + +mat B = repmat(A, 4, 5); +</pre> +</ul> +</li> +<br> +</ul> +<hr class="greyline"> +<br> + +<a name="speye"></a> +<b>speye(n_rows, n_cols)</b> +<ul> +<li> +Generate a sparse matrix with the elements along the main diagonal set to one +and off-diagonal elements set to zero +</li> +<br> +<li> +An identity matrix is generated when <i>n_rows</i> = <i>n_cols</i> +</li> +<br> +<li> +Usage: +<ul> +<li> +<i>sparse_matrix_type</i> X = speye<<i>sparse_matrix_type</i>>(n_rows, n_cols) +</li> +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre> +sp_mat A = speye<sp_mat>(5,5); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#sprandu_sprandn">sprandu()/sprandn()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="sprandu_sprandn"></a> +<b>sprandu(n_rows, n_cols, density)</b> +<br><b>sprandn(n_rows, n_cols, density)</b> +<ul> +<li> +Generate a sparse matrix with the non-zero elements set to random values +</li> +<br> +<li> +The <i>density</i> argument specifies the percentage of non-zero elements; it must be in the [0,1] interval +</li> +<br> +<li><i>sprandu()</i> uses a uniform distribution in the [0,1] interval +</li> +<br> +<li><i>sprandn()</i> uses a normal/Gaussian distribution with zero mean and unit variance +</li> +<br> +<li> +Usage: +<ul> +<li><i>sparse_matrix_type</i> X = sprandu<<i>sparse_matrix_type</i>>(n_rows, n_cols, density)</li> +</ul> +</li> +<br> +<li> +To change the seed, use the <a href="http://cplusplus.com/reference/clibrary/cstdlib/srand/">std::srand()</a> function. +</li> +<br> +<li> +Examples: +<ul> +<pre> +sp_mat A = sprandu<sp_mat>(100, 200, 0.1); +</pre> +</ul> +</li> +<li>See also: +<ul> +<li><a href="#speye">speye()</a></li> +<li><a href="http://cplusplus.com/reference/clibrary/cstdlib/srand/">std::srand()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="toeplitz"></a> +<b>toeplitz(A)</b> +<br><b>toeplitz(A,B)</b> +<br><b>circ_toeplitz(A)</b> +<ul> +<li> +toeplitz(): generate a Toeplitz matrix, with the first column specified by <i>A</i>, and (optionally) the first row specified by <i>B</i> +</li> +<br> +<li> +circ_toeplitz(): generate a circulant Toeplitz matrix +</li> +<br> +<li> +A and B must be vectors +</li> +<br> +<li> +Examples: +<ul> +<pre> +vec A = randu<vec>(5); +mat X = toeplitz(A); +mat Y = circ_toeplitz(A); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="http://mathworld.wolfram.com/ToeplitzMatrix.html">Toeplitz matrix in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Toeplitz_matrix">Toeplitz matrix in Wikipedia</a></li> +<li><a href="http://en.wikipedia.org/wiki/Circulant_matrix">Circulant matrix in Wikipedia</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"> +<br> + +<a name="zeros_standalone"></a> +<b>zeros(n_elem)</b> +<br><b>zeros(n_rows, n_cols)</b> +<br><b>zeros(n_rows, n_cols, n_slices)</b> +<ul> +<li> +Generate a vector, matrix or cube with the elements set to zero +</li> +<br> +<li> +Usage: +<ul> +<li><i>vector_type</i> v = zeros<<i>vector_type</i>>(n_elem)</li> +<li><i>matrix_type</i> X = zeros<<i>matrix_type</i>>(n_rows, n_cols)</li> +<li><i>cube_type</i> X = zeros<<i>cube_type</i>>(n_rows, n_cols, n_slices)</li> +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre> +vec v = zeros<vec>(10); +uvec u = zeros<uvec>(11); +mat A = zeros<mat>(5,6); +cube Q = zeros<cube>(5,6,7); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#zeros_member">.zeros()</a> (member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i>)</li> +<li><a href="#ones_member">.ones()</a> (member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i>)</li> +<li><a href="#ones_standalone">ones()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"> + +<hr class="greyline"> +<br> +<br> +<font size=+1><b>Functions Individually Applied to Each Element of a Matrix/Cube</b></font> +<br> +<br> +<hr class="greyline"> +<br> + +<a name="abs"></a> +<b>abs(mat)</b> +<br><b>abs(cube)</b> +<br><b>abs(cx_mat)</b> +<br><b>abs(cx_cube)</b> +<ul> +<li> +Obtain the magnitude of each element +</li> +<br> +<li> +Usage for non-complex matrices: +<ul> +<li><i>matrix_type</i> Y = abs(X)</li> +<li>X and Y must have the same <i>matrix_type</i></li> +</ul> +</li> +<br> +<li> +Usage for non-complex cubes: +<ul> +<li><i>cube_type</i> Y = abs(X)</li> +<li>X and Y must have the same <i>cube_type</i></li> +</ul> +</li> +<br> +<li> +Usage for complex matrices: +<ul> +<li><i>non_complex_matrix_type</i> Y = abs(X)</li> +<li>X must be a have complex matrix type, eg., <i>cx_mat</i> or <i>cx_fmat</i></li> +<li>The type of Y must be related to the type of X, +eg., if X has the type <i>cx_mat</i>, then the type of Y must be <i>mat</i> +</ul> +</li> +<br> +<li> +Usage for complex cubes: +<ul> +<li><i>non_complex_cube_type</i> Y = abs(X)</li> +<li>X must be a have complex cube type, eg., <i>cx_cube</i> or <i>cx_fcube</i></li> +<li>The type of Y must be related to the type of X, +eg., if X has the type <i>cx_cube</i>, then the type of Y must be <i>cube</i> +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +mat B = abs(A); + +cx_mat X = randu<cx_mat>(5,5); +mat Y = abs(X); +</pre> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="eps"></a> +<b>eps(X)</b> +<ul> +<li> +Obtain the positive distance of the absolute value of each element of <i>X</i> to the next largest representable floating point number +</li> +<br> +<li> +<i>X</i> can be a scalar (eg. <i>double</i>), vector or matrix +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(4,5); +mat B = eps(A); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#constants">datum::eps</a></li> +<li><a href="http://mathworld.wolfram.com/Floating-PointArithmetic.html">Floating-Point Arithmetic in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/IEEE_754-2008">IEEE Standard for Floating-Point Arithmetic in Wikipedia</a></li> + +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="misc_fns"></a> +<b> +miscellaneous functions: +<br> exp, exp2, exp10, trunc_exp, +<br> log, log2, log10, trunc_log, +<br> pow, sqrt, square +<br> floor, ceil, round +</b> +<br> +<ul> +<li> +Apply a function to each element +</li> +<br> +<li> +Usage: +<ul> +<li> +<i>matrix_type</i> B = misc_fn(A) +</li> +<li> +<i>cube_type</i> B = misc_fn(A) +</li> +<li> +A and B must have the same <i>matrix_type/cube_type</i> +</li> +<li> +misc_fn(A) is one of: +<ul> + +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> +<tbody> + <tr> + <td style="vertical-align: top;"> + exp(A)<sup> </sup> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + base-e exponential, <i>e<sup>x</sup></i> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + exp2(A)<sup> </sup> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + base-2 exponential, <i>2<sup>x</sup></i> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + exp10(A)<sup> </sup> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + base-10 exponential, <i>10<sup>x</sup></i> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + trunc_exp(A) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + base-e exponential, + truncated to avoid infinity + <br> + <font size=-1>(only for elements with type <i>float</i> or <i>double</i>)</font> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + log(A)<sub> </sub> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + natural log, <i>log<sub>e</sub> x</i> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + log2(A)<sub> </sub> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + base-2 log, <i>log<sub>2</sub> x</i> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + log10(A)<sub> </sub> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + base-10 log, <i>log<sub>10</sub> x</i> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + trunc_log(A) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + natural log, + truncated to avoid ±infinity + <br> + <font size=-1>(only for elements with type <i>float</i> or <i>double</i>)</font> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + pow(A, p)<sup> </sup> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + raise to the power of p, <i>x<sup>p</sup></i> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + sqrt(A)<sup> </sup> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + square root, <i>x<sup>½</sup></i> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + square(A)<sup> </sup> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + square, <i>x<sup>2</sup></i> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + floor(A) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + largest integral value that is not greater than the input value + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + ceil(A) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + smallest integral value that is not less than the input value + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + round(A) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + round to nearest integer, away from zero + </td> + </tr> +</tbody> +</table> + + +</ul> +</li> + +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +mat B = exp(A); +</pre> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="trig_fns"></a> +<b>trigonometric functions (cos, sin, tan, ...)</b> +<ul> +<li> +Apply a trigonometric function to each element +</li> +<br> +<li> +Usage: +<ul> +<li> +<i>matrix_type</i> Y = trig_fn(X) +</li> +<li> +<i>cube_type</i> Y = trig_fn(X) +</li> +<li> +X and Y must have the same <i>matrix_type/cube_type</i> +</li> +<li> +trig_fn is one of: +<ul> +<li> +cos family: <i>cos</i>, <i>acos</i>, <i>cosh</i>, <i>acosh</i> +</li> +<li> +sin family: <i>sin</i>, <i>asin</i>, <i>sinh</i>, <i>asinh</i> +</li> +<li> +tan family: <i>tan</i>, <i>atan</i>, <i>tanh</i>, <i>atanh</i> +</li> +</ul> +</li> + +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat X = randu<mat>(5,5); +mat Y = cos(X); +</pre> +</ul> +</li> +</ul> +<br> +<hr class="greyline"> + +<hr class="greyline"> +<br> +<br> +<font size=+1><b>Scalar Valued Functions of Vectors/Matrices/Cubes</b></font> +<br> +<br> +<hr class="greyline"> +<br> + +<a name="accu"></a> +<b>accu(mat)</b> +<br><b>accu(cube)</b> +<ul> +<li> +Accumulate (sum) all elements +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +double x = accu(A); + +mat B = randu<mat>(5,5); +double y = accu(A % B); + +// operator % performs element-wise multiplication, +// hence accu(A % B) is a "multiply-and-accumulate" +// operation +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#sum">sum()</a></li> +<li><a href="#cumsum">cumsum()</a></li> +<li><a href="#as_scalar">as_scalar()</a></li> +<li><a href="#trace">trace()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="as_scalar"></a> +<b>as_scalar(expression)</b> +<ul> +<li> +Evaluate an expression that results in a 1x1 matrix, +followed by converting the 1x1 matrix to a pure scalar +</li> +<br> +<li> +If a binary or trinary expression is given (ie. 2 or 3 terms), +the function will try to exploit the fact that the result is a 1x1 matrix +by using optimised expression evaluations +</li> +<br> +<li> +Examples: +<ul> +<pre> +rowvec r = randu<rowvec>(5); +colvec q = randu<colvec>(5); +mat X = randu<mat>(5,5); + +// examples of some expressions +// for which optimised implementations exist + +double a = as_scalar(r*q); +double b = as_scalar(r*X*q); +double c = as_scalar(r*diagmat(X)*q); +double d = as_scalar(r*inv(diagmat(X))*q); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#accu">accu()</a></li> +<li><a href="#conv_to">conv_to()</a></li> +<li><a href="#dot">dot()</a></li> +<li><a href="#norm">norm()</a></li> +<li><a href="#reshape">reshape()</a></li> +<li><a href="#resize">resize()</a></li> +<li><a href="#trace">trace()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="det"></a> +<b>det(A, </b><i>slow=false</i><b>)</b> +<ul> +<li> +Determinant of square matrix <i>A</i> +</li> +<br> +<li> +If <i>A</i> is not square, a <i>std::logic_error</i> exception is thrown +</li> +<br> +<li> +<b>Caveat</b>: for large matrices you may want to use <a href="#log_det">log_det()</a> instead +</li> +<br> +<li> +For matrix sizes ≤ 4x4, a fast algorithm is used by default. +In rare instances, the fast algorithm might be less precise than the standard algorithm. +To force the use of the standard algorithm, set the <i>slow</i> argument to <i>true</i> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +double x = det(A); + +mat44 B = randu<mat>(4,4); + +double y = det(B); // use fast algorithm by default +double z = det(B, true); // use slow algorithm +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#log_det">log_det()</a></li> +<li><a href="http://mathworld.wolfram.com/Determinant.html">determinant in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Determinant">determinant in Wikipedia</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="dot"></a> +<b>dot(A, B)</b> +<br><b>cdot(A, B)</b> +<br><b>norm_dot(A, B)</b> +<ul> +<li> +<i>dot(A,B)</i>: dot product of <i>A</i> and <i>B</i>, under the assumption that <i>A</i> and <i>B</i> are vectors with the same number of elements +</li> +<br> +<li> +<i>cdot(A,B)</i>: as per <i>dot(A,B)</i>, but the complex conjugate of <i>A</i> is used +</li> +<br> +<li> +<i>norm_dot(A,B)</i>: normalised version of <i>dot(A,B)</i> +</li> +<br> +<li> +Examples: +<ul> +<pre> +vec a = randu<vec>(10); +vec b = randu<vec>(10); + +double x = dot(a,b); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#as_scalar">as_scalar()</a></li> +<li><a href="#cross">cross()</a></li> +<li><a href="#conj">conj()</a></li> +<li><a href="#norm">norm()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="log_det"></a> +<b>log_det(val, sign, A)</b> +<ul> +<li> +Log determinant of square matrix <i>A</i>, such that the determinant is equal to <i>exp(val)*sign</i> +</li> +<br> +<li> +If <i>A</i> is not square, a <i>std::logic_error</i> exception is thrown +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); + +double val; +double sign; + +log_det(val, sign, A); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#det">det()</a></li> +<li><a href="http://mathworld.wolfram.com/Determinant.html">determinant in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Determinant">determinant in Wikipedia</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="norm"></a> +<b> +norm(X, p) +</b> +<ul> +<li> +Compute the <i>p</i>-norm of <i>X</i>, where <i>X</i> can be a vector or a matrix +</li> +<br> +<li> +For vectors, <i>p</i> is an integer ≥1, or one of: "-inf", "inf", "fro" +</li> +<br> +<li> +For matrices, <i>p</i> is one of: 1, 2, "inf", "fro"; the calculated norm is the <i>induced norm</i> (not entrywise norm) +</li> +<br> +<li> +"-inf" is the minimum norm, "inf" is the maximum norm, while "fro" is the Frobenius norm +</li> +<br> +<li> +To obtain the zero norm or Hamming norm (ie. the number of non-zero elements), +you may want to use this expression: <a href="#accu">accu</a>(X != 0). +</li> +<br> +<li> +Examples: +<ul> +<pre> +vec q = randu<vec>(5); +double x = norm(q, 2); +double y = norm(q, "inf"); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#dot">dot()</a></li> +<li><a href="http://en.wikipedia.org/wiki/Norm_(mathematics)">Vector Norm in Wikipedia</a></li> +<li><a href="http://mathworld.wolfram.com/VectorNorm.html">Vector Norm in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Matrix_norm">Matrix Norm in Wikipedia</a></li> +<li><a href="http://mathworld.wolfram.com/MatrixNorm.html">Matrix Norm in MathWorld</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="rank"></a> +<b>rank(X, tolerance = default)</b> + +<ul> +<li>Returns the rank of matrix <i>X</i></li><br> +<li>Any singular values less than default tolerance are treated as zero</li><br> +<li>The default tolerance is <i>max(X.n_rows, X.n_cols)*eps(sigma)</i>, +where <i>sigma</i> is the largest singular value of <i>X</i> +</li><br> +<li>The computation is based on singular value decomposition; +if the decomposition fails, a <i>std::runtime_error</i> exception is thrown</li><br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(4,5); +uword r = rank(A); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#eps">eps()</a></li> +<li><a href="http://mathworld.wolfram.com/MatrixRank.html">Rank in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Rank_(linear_algebra)">Rank in Wikipedia</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="trace"></a> +<b>trace(X)</b> +<ul> +<li> +Sum of the diagonal elements of square matrix <i>X</i> +</li> +<br> +<li> +If <i>X</i> is an expression, +the function will try to use optimised expression evaluations to calculate only the diagonal elements +</li> +<br> +<li> +A <i>std::logic_error</i> exception is thrown if <i>X</i> does not evaluate to a square matrix +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +double x = trace(A); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#accu">accu()</a></li> +<li><a href="#as_scalar">as_scalar()</a></li> +<li><a href="#diag">.diag()</a></li> +<li><a href="#diagvec">diagvec()</a></li> +<li><a href="#sum">sum()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"> + +<hr class="greyline"> +<br> +<br> +<font size=+1><b>Scalar/Vector Valued Functions of Vectors/Matrices</b></font> +<br> +<br> +<hr class="greyline"> +<br> + +<a name="diagvec"></a> +<b>diagvec(A, k=0)</b> +<ul> +<li> +Extract the <i>k</i>-th diagonal from matrix <i>A</i> +</li> +<br> +<li> +The argument <i>k</i> is optional -- by default the main diagonal is extracted (<i>k=0</i>) +</li> +<br> +<li>For <i>k > 0</i>, the <i>k</i>-th super-diagonal is extracted (top-right corner)</li> +<br> +<li>For <i>k < 0</i>, the <i>k</i>-th sub-diagonal is extracted (bottom-left corner)</li> +<br> +<li> +An extracted a diagonal is interpreted as a column vector +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +vec d = diagvec(A); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#diag">.diag()</a></li> +<li><a href="#diagmat">diagmat()</a></li> +<li><a href="#trace">trace()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"> +<br> + +<a name="min_and_max"></a> +<b>min(mat, dim=0)</b> +<br><b>min(rowvec)</b> +<br><b>min(colvec)</b> +<br> +<br><b>max(mat, dim=0)</b> +<br><b>max(rowvec)</b> +<br><b>max(colvec)</b> +<ul> +<li> +For a matrix argument, return the extremum value for each column (dim=0), or each row (dim=1) +</li> +<br> +<li> +For a vector argument, return the extremum value +</li> +<br> +<li> +Examples: +<ul> +<pre> +colvec q = randu<colvec>(10,1); +double x = max(q); + +mat A = randu<mat>(10,10); +rowvec b = max(A); + +// same result as max(A) +// the 0 explicitly indicates +// "traverse across rows" +rowvec c = max(A,0); + +// the 1 explicitly indicates +// "traverse across columns" +colvec d = max(A,1); + +// find the overall maximum value +double y = max(max(A)); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#min_and_max_member">.min() & .max()</a> (member functions of Mat and Cube)</li> +<li><a href="#running_stat">running_stat</a></li> +<li><a href="#running_stat_vec">running_stat_vec</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="prod"></a> +<b>prod(mat, dim=0)</b> +<br><b>prod(rowvec)</b> +<br><b>prod(colvec)</b> +<ul> +<li> +For a matrix argument, return the product of elements in each column (dim=0), or each row (dim=1) +</li> +<br> +<li> +For a vector argument, return the product of all elements +</li> +<br> +<li> +Examples: +<ul> +<pre> +colvec q = randu<colvec>(10,1); +double x = prod(q); + +mat A = randu<mat>(10,10); +rowvec b = prod(A); + +// same result as prod(A) +// the 0 explicitly indicates +// "traverse across rows" +rowvec c = prod(A,0); + +// the 1 explicitly indicates +// "traverse across columns" +colvec d = prod(A,1); + +// find the overall product +double y = prod(prod(A)); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#schur_product">Schur product</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + + +<a name="sum"></a> +<b>sum(mat, dim=0)</b> +<br><b>sum(rowvec)</b> +<br><b>sum(colvec)</b> +<ul> +<li> +For a matrix argument, return the sum of elements in each column (dim=0), or each row (dim=1) +</li> +<br> +<li> +For a vector argument, return the sum of all elements +</li> +<br> +<li> +To get a sum of all the elements regardless of the argument type (ie. matrix or vector), +you may wish to use <a href="#accu">accu()</a> instead +</li> +<br> +<li> +Examples: +<ul> +<pre> +colvec q = randu<colvec>(10,1); +double x = sum(q); + +mat A = randu<mat>(10,10); +rowvec b = sum(A); + +// same result as sum(A) +// the 0 explicitly indicates +// "traverse across rows" +rowvec c = sum(A,0); + +// the 1 explicitly indicates +// "traverse across columns" +colvec d = sum(A,1); + +// find the overall sum +double y = sum(sum(A)); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#accu">accu()</a></li> +<li><a href="#cumsum">cumsum()</a></li> +<li><a href="#trace">trace()</a></li> +<li><a href="#as_scalar">as_scalar()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + + +<a name="stats_fns"></a> +<b>statistics: mean, median, stddev, var</b> + +<ul> +<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2"> +<tbody> + <tr> + <td style="vertical-align: top;"> + <b>mean(mat, dim=0)</b> + <br><b>mean(colvec)</b> + <br><b>mean(rowvec)</b> + <br> + <br> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + mean (average value) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>median(mat, dim=0)</b> + <br><b>median(colvec)</b> + <br><b>median(rowvec)</b> + <br> + <br> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + median + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>stddev(mat, norm_type=0, dim=0)</b> + <br><b>stddev(colvec, norm_type=0)</b> + <br><b>stddev(rowvec, norm_type=0)</b> + <br> + <br> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + standard deviation + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + <b>var(mat, norm_type=0, dim=0)</b> + <br><b>var(colvec, norm_type=0)</b> + <br><b>var(rowvec, norm_type=0)</b> + <br> + <br> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + variance + </td> + </tr> +</tbody> +</table> +<br> +<li> +For a matrix argument, find a particular statistic for each column (<i>dim=0</i>), or each row (<i>dim=1</i>) +</li> +<br> +<li> +For a vector argument, return a particular statistic calculated using all the elements of the vector +</li> +<br> +<li> +For the var() and stddev() functions, the default <i>norm_type=0</i> performs normalisation using <i>N-1</i> (where <i>N</i> is the number of samples), +providing the best unbiased estimator. +Using <i>norm_type=1</i> causes normalisation to be done using <i>N</i>, which provides the second moment around the mean +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +mat B = mean(A); +mat C = var(A); +double m = mean(mean(A)); + +vec q = randu<vec>(5); +double v = var(q); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#cov">cov()</a></li> +<li><a href="#cor">cor()</a></li> +<li><a href="#running_stat">running_stat</a></li> +<li><a href="#running_stat_vec">running_stat_vec</a></li> +<li><a href="#hist">hist()</a></li> +<li><a href="#histc">histc()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"> + +<hr class="greyline"> +<br> +<br> +<font size=+1><b>Vector/Matrix/Cube Valued Functions of Vectors/Matrices/Cubes</b></font> +<br> +<br> +<hr class="greyline"> +<br> + +<a name="conv"></a> +<b> +C = conv(A, B) +</b> +<ul> +<li> +Convolution of vectors <i>A</i> and <i>B</i> +</li> +<br> +<li> +If <i>A</i> and <i>B</i> are polynomial coefficient vectors, convolving them is equivalent to multiplying the two polynomials +</li> +<br> +<li> +The convolution operation is also equivalent to FIR filtering +</li> +<br> +<li> +The orientation of the result vector is the same as the orientation of <i>A</i> (ie. column or row vector) +</li> +<br> +<li> +Examples: +<ul> +<pre> +vec A = randu<vec>(128) - 0.5; +vec B = randu<vec>(128) - 0.5; + +vec C = conv(A,B); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#fft">fft()</a></li> +<li><a href="#cor">cor()</a></li> +<li><a href="http://mathworld.wolfram.com/Convolution.html">Convolution in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Convolution">Convolution in Wikipedia</a></li> +<li><a href="http://en.wikipedia.org/wiki/Finite_impulse_response">FIR filter in Wikipedia</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="conv_to"></a> +<b> +conv_to<<i>type</i>>::from(X) +</b> +<ul> +<li> +A form of casting +</li> +<br> +<li> +Convert between matrix/vector types (eg. <i>mat</i> to <i>fmat</i>), as well as cube types (eg. <i>cube</i> to <i>fcube</i>) +</li> +<br> +<li> +Conversion between <i>std::vector</i> and Armadillo matrices/vectors is also possible +</li> +<br> +<li> +Conversion of a <i>mat</i> object into <i>colvec</i>, <i>rowvec</i> or <i>std::vector</i> is possible if the object can be interpreted as a vector +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +fmat B = conv_to<fmat>::from(A); + +typedef std::vector<double> stdvec; + +stdvec x(3); +x[0] = 0.0; x[1] = 1.0; x[2] = 2.0; + +colvec y = conv_to< colvec >::from(x); +stdvec z = conv_to< stdvec >::from(y); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#as_scalar">as_scalar()</a></li> +<li><a href="#reshape">reshape()</a></li> +<li><a href="#resize">resize()</a></li> +<li><a href="#adv_constructors_mat">advanced constructors (matrices)</a></li> +<li><a href="#adv_constructors_cube">advanced constructors (cubes)</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="conj"></a> +<b>conj(cx_mat)</b> +<br><b>conj(cx_cube)</b> +<ul> +<li> +Obtain the complex conjugate of each element in a complex matrix/cube +</li> +<br> +<li> +Examples: +<ul> +<pre> +cx_mat X = randu<cx_mat>(5,5); +cx_mat Y = conj(X); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#trans">trans()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="cor"></a> +<b>cor(X, Y, norm_type=0)</b> +<br><b>cor(X, norm_type=0)</b> +<ul> +<li> +For two matrix arguments <i>X</i> and <i>Y</i>, +if each row of <i>X</i> and <i>Y</i> is an observation and each column is a variable, +the <i>(i,j)</i>-th entry of <i>cor(X,Y)</i> is the correlation coefficient between the <i>i</i>-th variable in <i>X</i> and the <i>j</i>-th variable in <i>Y</i> +</li> +<br> +<li> +For vector arguments, the type of vector is ignored and each element in the vector is treated as an observation +</li> +<br> +<li> +For matrices, <i>X</i> and <i>Y</i> must have the same dimensions +</li> +<br> +<li> +For vectors, <i>X</i> and <i>Y</i> must have the same number of elements +</li> +<br> +<li> +<i>cor(X)</i> is equivalent to <i>cor(X, X)</i>, also called autocorrelation +</li> +<br> +<li> +The default <i>norm_type=0</i> performs normalisation of the correlation matrix using <i>N-1</i> (where <i>N</i> is the number of observations). +Using <i>norm_type=1</i> causes normalisation to be done using <i>N</i> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat X = randu<mat>(4,5); +mat Y = randu<mat>(4,5); + +mat R = cor(X,Y); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="http://mathworld.wolfram.com/Correlation.html">Correlation in MathWorld</a></li> +<li><a href="http://mathworld.wolfram.com/Autocorrelation.html">Autocorrelation in MathWorld</a></li> +<li><a href="#cov">cov()</a></li> +<li><a href="#conv">conv()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="cov"></a> +<b>cov(X, Y, norm_type=0)</b> +<br><b>cov(X, norm_type=0)</b> +<ul> +<li> +For two matrix arguments <i>X</i> and <i>Y</i>, +if each row of <i>X</i> and <i>Y</i> is an observation and each column is a variable, +the <i>(i,j)</i>-th entry of <i>cov(X,Y)</i> is the covariance between the <i>i</i>-th variable in <i>X</i> and the <i>j</i>-th variable in <i>Y</i> +</li> +<br> +<li> +For vector arguments, the type of vector is ignored and each element in the vector is treated as an observation +</li> +<br> +<li> +For matrices, <i>X</i> and <i>Y</i> must have the same dimensions +</li> +<br> +<li> +For vectors, <i>X</i> and <i>Y</i> must have the same number of elements +</li> +<br> +<li> +<i>cov(X)</i> is equivalent to <i>cov(X, X)</i> +</li> +<br> +<li> +The default <i>norm_type=0</i> performs normalisation using <i>N-1</i> (where <i>N</i> is the number of observations), +providing the best unbiased estimation of the covariance matrix (if the observations are from a normal distribution). +Using <i>norm_type=1</i> causes normalisation to be done using <i>N</i>, which provides the second moment matrix of the observations about their mean +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat X = randu<mat>(4,5); +mat Y = randu<mat>(4,5); + +mat C = cov(X,Y); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#running_stat_vec">running_stat_vec</a></li> +<li><a href="#stats_fns">statistics functions</a></li> +<li><a href="http://mathworld.wolfram.com/Covariance.html">Covariance in MathWorld</a></li> +<li><a href="#cor">cor()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="cross"></a> +<b>cross(A, B)</b> +<ul> +<li> +Calculate the cross product between A and B, under the assumption that A and B are 3 dimensional vectors +</li> +<br> +<li> +Examples: +<ul> +<pre> +vec a = randu<vec>(3); +vec b = randu<vec>(3); + +vec c = cross(a,b); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#dot">dot()</a></li> +<li><a href="http://en.wikipedia.org/wiki/Cross_product">Cross product in Wikipedia</a></li> +<li><a href="http://mathworld.wolfram.com/CrossProduct.html">Cross product in MathWorld</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="cumsum"></a> +<b>cumsum(mat, dim=0)</b> +<br><b>cumsum(rowvec)</b> +<br><b>cumsum(colvec)</b> +<ul> +<li> +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) +</li> +<br> +<li> +For a vector argument, return a vector of the same orientation, containing the cumulative sum of elements +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +mat B = cumsum(A); + +vec x = randu<vec>(10); +vec y = cumsum(x); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#accu">accu()</a></li> +<li><a href="#sum">sum()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="diagmat"></a> +<b>diagmat(X)</b> +<ul> +<li> +Interpret a matrix or vector <i>X</i> as a diagonal matrix +</li> +<br> +<li> +If <i>X</i> 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 +</li> +<br> +<li> +If <i>X</i> 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 +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +mat B = diagmat(A); +mat C = A*diagmat(A); + +rowvec q = randu<rowvec>(5); +colvec r = randu<colvec>(5); +mat X = diagmat(q)*diagmat(r); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#diagvec">diagvec()</a></li> +<li><a href="#diag">.diag()</a></li> +<li><a href="#trimat">trimatu() / trimatl()</a></li> +<li><a href="#symmat">symmatu() / symmatl()</a></li> +<li><a href="#reshape">reshape()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"> +<br> + +<a name="find"></a> +<b>find(X, k=0, s="first")</b> +<ul> +<li>Return a column vector of the indices of non-zero elements of <i>X</i></li> +<br> +<li>The output vector must have the type <a href="#Col">uvec</a> or <a href="#Mat">umat</a> +(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>) +</li> +<br> +<li> +The input matrix <i>X</i> is interpreted as a vector, with column-by-column ordering of the elements of <i>X</i> +</li> +<br> +<li>Relational operators can be used instead of <i>X</i>, eg. <i>A > 0.5</i> +</li> +<br> +<li>If <i>k=0</i> (default), return the indices of all non-zero elements, otherwise return at most <i>k</i> of their indices</li> +<br> +<li>If <i>s="first"</i> (default), return at most the first <i>k</i> indices of the non-zero elements +</li> +<br> +<li>If <i>s="last"</i>, return at most the last <i>k</i> indices of the non-zero elements +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +mat B = randu<mat>(5,5); + +uvec q1 = find(A > B); +uvec q2 = find(A > 0.5); +uvec q3 = find(A > 0.5, 3, "last"); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#unique">unique()</a></li> +<li><a href="#conv_to">conv_to()</a> (convert between matrix/vector types)</li> +<li><a href="#submat">submatrix views</a></li> +<li><a href="#sort_index">sort_index()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"> +<br> + +<a name="flip"></a> +<b>fliplr(mat)</b> +<br><b>flipud(mat)</b> +<ul> +<li> +fliplr(): generate a copy of the input matrix, with the order of the columns reversed +</li> +<br> +<li> +flipud(): generate a copy of the input matrix, with the order of the rows reversed +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); + +mat B = fliplr(A); +mat C = flipud(A); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#swap_rows">.swap_rows() & .swap_cols()</a> (member functions of <i>Mat</i>, <i>Col</i> and <i>Row</i> classes)</li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="hist"></a> +<b>hist(V, n_bins=10)</b> +<br><b>hist(X, n_bins=10, dim=0)</b> +<br> +<br><b>hist(V, centers)</b> +<br><b>hist(X, centers, dim=0)</b> +<ul> +<li> +For vector <i>V</i>, +produce an unsigned vector of the same orientation as <i>V</i> (ie. either <a href="#Col">uvec</a> or <a href="#Row">urowvec</a>) +that represents a histogram of counts +</li> +<br> +<li> +For matrix <i>X</i>, +produce a <a href="#Mat">umat</a> matrix containing either +column histogram counts (for <i>dim=0</i>, default), +or +row histogram counts (for <i>dim=1</i>) +</li> +<br> +<li> +The bin centers can be automatically determined from the data, with the number of bins specified via <i>n_bins</i> (default is 10); +the range of the bins is determined by the range of the data +</li> +<br> +<li> +The bin centers can also be explicitly specified via the <i>centers</i> vector; +the vector must contain monotonically increasing values (eg. 0.1, 0.2, 0.3, ...) +</li> +<br> +<li> +This function was added in version 3.0 +</li> +<br> +<li> +Examples: +<ul> +<pre> +vec v = randn<vec>(1000); // Gaussian distribution + +uvec h1 = hist(v, 11); +uvec h2 = hist(v, linspace<vec>(-2,2,11)); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#histc">histc()</a></li> +<li><a href="#stats_fns">statistics functions</a></li> +<li><a href="#conv_to">conv_to()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="histc"></a> +<b>histc(V, edges)</b> +<br><b>histc(X, edges, dim=0)</b> +<ul> +<li> +For vector <i>V</i>, +produce an unsigned vector of the same orientation as <i>V</i> (ie. either <a href="#Col">uvec</a> or <a href="#Row">urowvec</a>) +that contains the counts of the number of values that fall between the elements in the <i>edges</i> vector +</li> +<br> +<li> +For matrix <i>X</i>, +produce a <i>umat</i> matrix containing either +column histogram counts (for <i>dim=0</i>, default), +or +row histogram counts (for <i>dim=1</i>) +</li> +<br> +<li> +The <i>edges</i> vector must contain monotonically increasing values (eg. 0.1, 0.2, 0.3, ...) +</li> +<br> +<li> +This function was added in version 3.0 +</li> +<br> +<li> +Examples: +<ul> +<pre> +vec v = randn<vec>(1000); // Gaussian distribution + +uvec h = histc(v, linspace<vec>(-2,2,11)); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#hist">hist()</a></li> +<li><a href="#stats_fns">statistics functions</a></li> +<li><a href="#conv_to">conv_to()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="imag_real"></a> +<b>imag(cx_mat)</b> +<br><b>imag(cx_cube)</b> +<br> +<br><b>real(cx_mat)</b> +<br><b>real(cx_cube)</b> +<ul> +<li> +Extract the imaginary/real part of a complex matrix/cube +</li> +<br> +<li> +Examples: +<ul> +<pre> +cx_mat C = randu<cx_mat>(5,5); + +mat A = imag(C); +mat B = real(C); +</pre> +</ul> +</li> +<br> +<li><b>Caveat:</b> versions 4.4, 4.5 and 4.6 of the GCC C++ compiler have a bug when using the <i>-std=c++0x</i> compiler option (ie. experimental support for C++11); +to work around this bug, preface Armadillo's imag() and real() with the <i>arma</i> namespace qualification, eg. arma::imag(C) +</li> +<br> +<li>See also: +<ul> +<li><a href="#set_imag">set_imag() / set_real()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="join"></a> +<b>join_rows(mat A, mat B)</b> +<br><b>join_cols(mat A, mat B)</b> +<br><b>join_slices(cube A, cube B)</b> +<ul> +<li> +join_rows(): +for two matrices A and B, append each row of B to its respective row of A; +matrices A and B must have the same number of rows +</li> +<br> +<li> +join_cols(): +for two matrices A and B, append each column of B to its respective column of A; +matrices A and B must have the same number of columns +</li> +<br> +<li> +join_slices(): +for two cubes A and B, append the slices of B to the slices of A; +cubes A and B have the same number of rows and columns (ie. all slices must have the same size) +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(4,5); +mat B = randu<mat>(4,6); +mat C = randu<mat>(6,5); + +mat X = join_rows(A,B); +mat Y = join_cols(A,C); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#shed">shed rows/columns/slices</a></li> +<li><a href="#insert">insert rows/columns/slices</a></li> +<li><a href="#submat">submatrix views</a></li> +<li><a href="#subcube">subcube views</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="kron"></a> +<b>kron(A,B)</b> + +<ul> +<li>Kronecker tensor product.</li> +<br> +<li>Using matrix <i>A</i> (with <i>n</i> rows and <i>p</i> columns) and matrix <i>B</i> (with <i>m</i> rows and <i>q</i> columns), +<i>kron(A,B)</i> returns a matrix (with <i>nm</i> rows and <i>pq</i> columns) which denotes the tensor product of <i>A</i> and <i>B</i> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(4,5); +mat B = randu<mat>(5,4); + +mat K = kron(A,B); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="http://mathworld.wolfram.com/KroneckerProduct.html">Kronecker Product in MathWorld</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="reshape"></a> +<b>reshape(mat, n_rows, n_cols, dim=0)</b> +<br><b>reshape(cube, n_rows, n_cols, n_slices, dim=0)</b> +<ul> +<li> +Generate a matrix/cube sized according to given size specifications, +whose elements are taken from the given matrix/cube, either column-wise (dim=0) or row-wise (dim=1); +the elements in the generated object are placed column-wise (ie. the first column is filled up before filling the second column) +</li> +<br> +<li> +The layout of the elements in the generated object will be different to the layout in the given object +</li> +<br> +<li> +This function can be used to create a vector representation of a matrix (ie. concatenate all the columns or rows) +</li> +<br> +<li> +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 +</li> +<br> +<li> +If the total number of elements in the given matrix/cube is less than the specified size, +the remaining elements in the generated matrix/cube are set to zero +</li> +<br> +<li> +If the total number of elements in the given matrix/cube is greater than the specified size, +only a subset of elements is taken from the given matrix/cube +</li> +<br> +<li> +<b>Caveat:</b> +reshape() is slower than <a href="#set_size">.set_size()</a>, which doesn't preserve data +</li> +<br> +<li> +<b>Caveat:</b> +if you wish to grow/shrink a matrix while preserving the elements <b>as well as</b> the layout of the elements, +use <a href="#resize">resize()</a> instead +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(10, 5); +mat B = reshape(A, 5, 10); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#reshape_member">.reshape()</a> (member function of Mat and Cube)</li> +<li><a href="#set_size">.set_size()</a> (member function of Mat and Cube)</li> +<li><a href="#resize">resize()</a></li> +<li><a href="#as_scalar">as_scalar()</a></li> +<li><a href="#conv_to">conv_to()</a></li> +<li><a href="#diagmat">diagmat()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="resize"></a> +<b>resize(mat, n_rows, n_cols)</b> +<br><b>resize(cube, n_rows, n_cols, n_slices)</b> +<ul> +<li> +Generate a matrix/cube sized according to given size specifications, +whose elements as well as the layout of the elements are taken from the given matrix/cube +</li> +<br> +<li> +<b>Caveat:</b> +resize() is slower than <a href="#set_size">.set_size()</a>, which doesn't preserve data +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(4, 5); +mat B = resize(A, 7, 6); +</pre> +</ul> +</li> +<br> +<li> +This function was added in version 2.4 +</li> +<br> +<li> +See also: +<ul> +<li><a href="#resize_member">.resize()</a> (member function of Mat and Cube)</li> +<li><a href="#set_size">.set_size()</a> (member function of Mat and Cube)</li> +<li><a href="#reshape">reshape()</a></li> +<li><a href="#as_scalar">as_scalar()</a></li> +<li><a href="#conv_to">conv_to()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="shuffle"></a> +<b>shuffle(mat, dim=0)</b> +<br><b>shuffle(rowvec, dim=0)</b> +<br><b>shuffle(colvec, dim=0)</b> +<ul> +<li> +Shuffle the rows (dim=0) or columns (dim=1) of a matrix or vector +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(4,5); +mat B = shuffle(A); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#randu_randn_standalone">randu() / randn()</a></li> +<li><a href="#sort">sort()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="sort"></a> +<b>sort(mat, sort_type=0, dim=0)</b> +<br><b>sort(rowvec, sort_type=0)</b> +<br><b>sort(colvec, sort_type=0)</b> +<ul> +<li>For a matrix argument, return a matrix with the elements of the input matrix sorted in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)</li> +<br> +<li><i>sort_type=0</i> (default) indicates an ascending sort</li> +<br> +<li><i>sort_type=1</i> indicates a descending sort</li> +<br> +<li>For a vector argument, return a vector which is a sorted version of the input vector</li> +<br> +<li>For matrices and vectors with complex numbers, sorting is via absolute values</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(10,10); +mat B = sort(A); +</pre> +</ul> +</li> +<li> +See also: +<ul> +<li><a href="#sort_index">sort_index()</a></li> +<li><a href="#shuffle">shuffle()</a></li> +<li><a href="#randu_randn_standalone">randu() / randn()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="sort_index"></a> +<b>sort_index(colvec, sort_type=0)</b> +<br><b>sort_index(rowvec, sort_type=0)</b> +<br> +<br><b>stable_sort_index(colvec, sort_type=0)</b> +<br><b>stable_sort_index(rowvec, sort_type=0)</b> +<ul> +<li>Return a vector which describes the sorted order of the given vector's elements +(ie. it contains the indices of the given vector's elements) +</li> +<br> +<li>The output vector must have the type <a href="#Col">uvec</a> or <a href="#Mat">umat</a> +(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>) +</li> +<br> +<li><i>sort_type=0</i> (default) indicates an ascending sort</li> +<br> +<li><i>sort_type=1</i> indicates a descending sort</li> +<br> +<li>The <i>stable_sort_index()</i> variant preserves the relative order of elements with equivalent values; the variant was added in version 3.6</li> +<br> +<li> +Examples: +<ul> +<pre> +vec q = randu<vec>(10); +uvec indices = sort_index(q); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#find">find()</a></li> +<li><a href="#sort">sort()</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="symmat"></a> +<b>symmatu(A)</b> +<br><b>symmatl(A)</b> +<ul> +<li> +<i>symmatu(A)</i>: interpret square matrix <i>A</i> as symmetric, reflecting the upper triangle to the lower triangle +</li> +<br> +<li> +<i>symmatl(A)</i>: interpret square matrix <i>A</i> as symmetric, reflecting the lower triangle to the upper triangle +</li> +<br> +<li> +If <i>A</i> is non-square, a <i>std::logic_error</i> exception is thrown +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); + +mat B = symmatu(A); +mat C = symmatl(A); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#diagmat">diagmat()</a></li> +<li><a href="#trimat">trimatu() / trimatl()</a></li> +<li><a href="http://en.wikipedia.org/wiki/Symmetric_matrix">Symmetric matrix in Wikipedia</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="strans"></a> +<b>strans(mat)</b> +<br><b>strans(colvec)</b> +<br><b>strans(rowvec)</b> +<ul> +<li> +Simple matrix transpose, without taking the conjugate of the elements (complex matrices) +</li> +<br> +<li> +Use <a href="#trans">trans()</a> instead, unless you explicitly need to take the transpose of a complex matrix without taking the conjugate of the elements +</li> +<br> +<li>See also: +<ul> +<li><a href="#t_st_members">.st()</a></li> +<li><a href="#trans">trans()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + + +<a name="trans"></a> +<b>trans(mat)</b> +<br><b>trans(colvec)</b> +<br><b>trans(rowvec)</b> +<ul> +<li> +Matrix transpose / Hermitian transpose +</li> +<br> +<li> +If a given object has real elements, a normal transpose is done +</li> +<br> +<li> +If a given object has complex elements, a Hermitian transpose is done (ie. the conjugate of the elements is taken during the transpose operation) +</li> +<br> +<li> +<b>Caveat:</b> for complex matrices, the functionality of trans() has changed in version 2.0: +<ul> +<li>in version 1.x, <i>trans()</i> does not take the conjugate of complex elements</li> +<li>in version 1.x, the <i>htrans()</i> function is used for the Hermitian transpose</li> +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre>mat A = randu<mat>(5,10); +mat B = trans(A); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#t_st_members">.t()</a></li> +<li><a href="#strans">strans()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + + +<a name="trimat"></a> +<b>trimatu(A)</b> +<br><b>trimatl(A)</b> +<ul> +<li> +<i>trimatu(A)</i>: interpret square matrix <i>A</i> as upper triangular +</li> +<br> +<li> +<i>trimatl(A)</i>: interpret square matrix <i>A</i> as lower triangular +</li> +<br> +<li> +A <i>std::logic_error</i> exception is thrown if <i>A</i> is non-square +</li> +<br> +<li> +Examples: +<ul> +<pre>mat A = randu<mat>(5,5); +mat U = trimatu(A); +mat L = trimatl(A); + +// tell the inv() function to look only +// at the upper triangular part +mat X = inv( trimatu(U) ); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#symmat">symmatu() / symmatl()</a></li> +<li><a href="#diagmat">diagmat()</a></li> +<li><a href="#inv">inv()</a></li> +<li><a href="#solve">solve()</a></li> +<li><a href="http://mathworld.wolfram.com/TriangularMatrix.html">Triangular matrix in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Triangular_matrix">Triangular matrix in Wikipedia</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"> +<br> + + +<a name="unique"></a> +<b>unique(A)</b> +<br> +<ul> +<li> +Return the unique elements of <i>A</i>, sorted in ascending order +</li> +<br> +<li> +If <i>A</i> is a vector, the output is also a vector with the same orientation (row or column) as <i>A</i>; +if <i>A</i> is a matrix, the output is always a column vector +</li> +<br> +<li> +This function was added in version 3.2 +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat X; +X << 1 << 2 << endr + << 2 << 3 << endr; + +mat Y = unique(X); +</pre> +</ul> +</li> +<br> +<li>See also: +<ul> +<li><a href="#find">find()</a></li> +<li><a href="#sort">sort()</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"> + + +<hr class="greyline"> +<br> +<br> +<font size=+1><b>Decompositions, Factorisations, Inverses and Equation Solvers</b></font> +<br> +<br> +<hr class="greyline"> +<br> + +<a name="chol"></a> +<b>R = chol(X)</b> +<br><b>chol(R, X)</b> +<ul> +<li> +Cholesky decomposition of <i>X</i>, such that <i>R.t()*R = X</i> +</li> +<br> +<li> +X must be a symmetric, positive-definite matrix +</li> +<br> +<li>If the decomposition fails, <i>R</i> is reset and: +<ul> +<li><i>chol(X)</i> throws a <i>std::runtime_error</i> exception</li> +<li><i>chol(R,X)</i> returns a bool set to <i>false</i></li> +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat X = randu<mat>(5,5); +mat Y = X.t()*X; + +mat R = chol(Y); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="http://mathworld.wolfram.com/CholeskyDecomposition.html">Cholesky decomposition in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Cholesky_decomposition">Cholesky decomposition in Wikipedia</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="eig_sym"></a> +<b>vec eigval = eig_sym(mat X)</b> +<br><b>vec eigval = eig_sym(cx_mat X)</b> +<br> +<br><b>eig_sym(vec eigval, mat X)</b> +<br><b>eig_sym(vec eigval, cx_mat X)</b> +<br> +<br><b>eig_sym(vec eigval, mat eigvec, mat X, method = "standard")</b> +<br><b>eig_sym(vec eigval, cx_mat eigvec, cx_mat X, method = "standard")</b> +<ul> +<li>Eigen decomposition of symmetric/hermitian matrix <i>X</i></li> +<br> +<li>The eigenvalues and corresponding eigenvectors are stored in <i>eigval</i> and <i>eigvec</i>, respectively</li> +<br> +<li>The eigenvalues are in ascending order</li> +<br> +<li>If <i>X</i> is not square, a <i>std::logic_error</i> exception is thrown</li> +<br> +<li>The <i>method</i> argument is optional</li> +<br> +<li> +By default, a standard eigen decomposition algorithm is used; +a divide-and-conquer algorithm can be used instead by explicitly setting <i>method</i> to <i>"dc"</i> +</li> +<br> +<li> +The divide-and-conquer algorithm provides slightly different results, but is notably faster for large matrices +</li> +<br> +<li>If the decomposition fails, the output objects are reset and: +<ul> +<li><i>eig_sym(X)</i> throws a <i>std::runtime_error</i> exception</li> +<li><i>eig_sym(eigval, X)</i> and <i>eig_sym(eigval, eigvec, X)</i> return a bool set to <i>false</i></li> +</ul> +</li> +<br> +<li>There is currently no check whether <i>X</i> is symmetric</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(50,50); +mat B = A.t()*A; // generate a symmetric matrix + +vec eigval; +mat eigvec; + +eig_sym(eigval, eigvec, B); // use standard algorithm by default + +eig_sym(eigval, eigvec, B, "dc"); // use "divide & conquer" algorithm +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#eig_gen">eig_gen()</a></li> +<li><a href="#svd">svd()</a></li> +<li><a href="#svd_econ">svd_econ()</a></li> +<li><a href="http://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors">eigenvalues & eigenvectors in Wikipedia</a></li> +<li><a href="http://en.wikipedia.org/wiki/Divide-and-conquer_eigenvalue_algorithm">divide & conquer eigenvalue algorithm in Wikipedia</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="eig_gen"></a> +<b>eig_gen(cx_vec eigval, cx_mat eigvec, mat X, side='r')</b> +<br> +<b>eig_gen(cx_vec eigval, cx_mat eigvec, cx_mat X, side='r')</b> +<br> +<br> +<b>eig_gen(cx_vec eigval, mat l_eigvec, mat r_eigvec, mat X)</b> +<br> +<b>eig_gen(cx_vec eigval, cx_mat l_eigvec, cx_mat r_eigvec, cx_mat X)</b> +<ul> +<li> +Eigen decomposition of general (non-symmetric/non-hermitian) square matrix <i>X</i></li> +<br> +<li>The eigenvalues and corresponding eigenvectors are stored in <i>eigval</i> and <i>eigvec</i>, respectively</li> +<br> +<li> +For the first two forms, <i>side='r'</i> (default) specifies that right eigenvectors are computed, +while <i>side='l'</i> specifies that left eigenvectors are computed +</li> +<br> +<li>For the last two forms, both left and right eigenvectors are computed</li> +<br> +<li> +The eigenvalues are not guaranteed to be ordered +</li> +<br> +<li>If <i>X</i> is not square, a <i>std::logic_error</i> exception is thrown</li> +<br> +<li>If the decomposition fails, the output objects are reset and <i>eig_gen()</i> returns a bool set to <i>false</i></li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(10,10); + +cx_vec eigval; +cx_mat eigvec; + +eig_gen(eigval, eigvec, A); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#eig_sym">eig_sym()</a></li> +<li><a href="#svd">svd()</a></li> +<li><a href="#svd_econ">svd_econ()</a></li> +<li><a href="http://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors">eigenvalues & eigenvectors in Wikipedia</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="fft"></a> +<b>cx_mat Y = fft(X)</b><br> +<b>cx_mat Y = fft(X, n)</b><br> +<br> +<b>cx_mat Z = ifft(cx_mat Y)</b><br> +<b>cx_mat Z = ifft(cx_mat Y, n)</b><br> +<ul> +<li>fft(): fast Fourier transform of a vector or matrix (real or complex)</li> +<br> +<li>ifft(): inverse fast Fourier transform of a vector or matrix (complex only)</li> +<br> +<li>If given a matrix, the transform is done on each column vector of the matrix</li> +<br> +<li> +The optional <i>n</i> argument specifies the transform length: +<ul> +<li>if <i>n</i> is larger than the length of the input vector, a zero-padded version of the vector is used</li> +<li>if <i>n</i> is smaller than the length of the input vector, only the first <i>n</i> elements of the vector are used</li> +</ul> +</li> +<br> +<li> +If <i>n</i> is not specified, the transform length is the same as the length of the input vector +</li> +<br> +<li><b>Caveat:</b> the transform is fastest when the transform length is a power of 2, eg. 64, 128, 256, 512, 1024, ...</li> +<br> +<li>The implementation of the transform in this version is preliminary; it is not yet fully optimised</li> +<br> +<li>This function was added in version 3.810</li> +<br> +<li> +Examples: +<ul> +<pre> + vec X = randu<vec>(100); +cx_vec Y = fft(X, 128); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#conv">conv()</a></li> +<li><a href="#imag_real">real()</a></li> +<li><a href="http://mathworld.wolfram.com/FastFourierTransform.html">fast Fourier transform in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Fast_Fourier_transform">fast Fourier transform in Wikipedia</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="inv"></a> +<b>B = inv(A, </b><i>slow=false</i><b>)</b> +<br> +<b>inv(B, A, </b><i>slow=false</i><b>)</b> +<ul> +<li> +Inverse of square matrix <i>A</i> +</li> +<br> +<li>the <i>slow</i> argument is optional</li> +<br> +<li> +If <i>A</i> is known to be a triangular matrix, +the inverse can be computed faster by explicitly marking the matrix as triangular +through <a href="#trimat">trimatu()</a> or <a href="#trimat">trimatl()</a> +</li> +<br> +<li> +If <i>A</i> is known to be a positive-definite symmetric matrix, +the inverse can be computed faster by explicitly marking the matrix using sympd() +</li> +<br> +<li> +If <i>A</i> is not square, a <i>std::logic_error</i> exception is thrown +</li> +<br> +<li>If <i>A</i> appears to be singular, <i>B</i> is reset and: +<ul> +<li><i>inv(A)</i> throws a <i>std::runtime_error</i> exception</li> +<li><i>inv(B,A)</i> returns a bool set to <i>false</i></li> +</ul> +</li> +<br> +<li> +<b>NOTE:</b> in many cases it is more efficient/faster to use the <a href="#solve">solve()</a> function instead of performing a matrix inverse; +for example, if you want to solve a system of linear equations, eg., <i>X = inv(A)*B</i>, +use <a href="#solve">solve()</a> instead +</li> +<br> +<li> +For matrix sizes ≤ 4x4, a fast inverse algorithm is used by default. +In rare instances, the fast algorithm might be less precise than the standard algorithm. +To force the use of the standard algorithm, set the <i>slow</i> argument to <i>true</i> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +mat B = inv(A); + + +// Diagonal elements in C are set to the +// reciprocal of the corresponding elements in A. +// Off-diagonal elements in C are set to zero. +mat C = inv( diagmat(A) ); + + +// tell inv() to look only at the upper triangular part of A +mat D = inv( trimatu(A) ); + + +// tell inv() that AA is a symmetric positive definite matrix +mat AA = A*A.t(); +mat E = inv( sympd(AA) ); + + +mat44 F = randu<mat>(4,4); + +mat G = inv(F); // use fast algorithm by default +mat H = inv(F, true); // use slow algorithm +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#i_member">.i()</a> +<li><a href="#pinv">pinv()</a> +<li><a href="#solve">solve()</a></li> +<li><a href="#trimat">trimatu() / trimatl()</a></li> +<li><a href="http://mathworld.wolfram.com/MatrixInverse.html">matrix inverse in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Invertible_matrix">invertible matrix in Wikipedia</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + + + +<a name="lu"></a> +<b>lu(mat L, mat U, mat P, mat X)</b> +<br> +<b>lu(mat L, mat U, mat X)</b> +<ul> +<li> +Lower-upper decomposition (with partial pivoting) of matrix <i>X</i> +</li> +<br> +<li> +The first form provides +a lower-triangular matrix <i>L</i>, +an upper-triangular matrix <i>U</i>, +and a permutation matrix <i>P</i>, +such that <i>P.t()*L*U = X</i> +</li> +<br> +<li> +The second form provides permuted <i>L</i> and <i>U</i>, such that <i>L*U = X</i>. +Note that in this case <i>L</i> is generally not lower-triangular +</li> +<br> +<li> +If the decomposition fails, the output objects are reset and <i>lu()</i> returns a bool set to <i>false</i> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); + +mat L, U, P; + +lu(L, U, P, A); + +mat B = P.t()*L*U; +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="http://en.wikipedia.org/wiki/LU_decomposition">LU decomposition in Wikipedia</a></li> +<li><a href="http://mathworld.wolfram.com/LUDecomposition.html">LU decomposition in MathWorld</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="pinv"></a> +<b>B = pinv(A, tolerance = default)</b> +<br><b>pinv(B, A, tolerance = default)</b> +<ul> +<li>Moore-Penrose pseudo-inverse of matrix <i>A</i></li> +<br> +<li>The <i>tolerance</i> argument is optional</li> +<br> +<li>The computation is based on singular value decomposition; +if the decomposition fails, <i>B</i> is reset and: +<ul> +<li><i>pinv(A)</i> throws a <i>std::runtime_error</i> exception</li> +<li><i>pinv(B,A)</i> returns a bool set to <i>false</i></li> +</ul> +<br> +<li>Any singular values less than <i>tolerance</i> are treated as zero</li> +<br> +<li>For matrix <i>A</i> with <i>m</i> rows and <i>n</i> columns, +the default tolerance is <i>max(m,n)*norm(A)*datum::eps</i>, +where <i>datum::eps</i> denotes the difference between 1 and the least value greater than 1 that is representable</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(4,5); +mat B = pinv(A); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#i_member">.i()</a></li> +<li><a href="#inv">inv()</a></li> +<li><a href="#solve">solve()</a></li> +<li><a href="#constants">datum::eps</a></li> +<li><a href="http://mathworld.wolfram.com/Pseudoinverse.html">Pseudoinverse in MathWorld</a></li> +<li><a href="http://mathworld.wolfram.com/Moore-PenroseMatrixInverse.html">Moore-Penrose Matrix Inverse in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Moore-Penrose_pseudoinverse">Moore-Penrose pseudoinverse in Wikipedia</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="princomp"></a> +<b>mat coeff = princomp(mat X)</b> +<br><b>cx_mat coeff = princomp(cx_mat X)</b><br> + +<br><b>princomp(mat coeff, mat X)</b> +<br><b>princomp(cx_mat coeff, cx_mat X)</b><br> + +<br><b>princomp(mat coeff, mat score, mat X)</b> +<br><b>princomp(cx_mat coeff, cx_mat score, cx_mat X)</b><br> + +<br><b>princomp(mat coeff, mat score, vec latent, mat X)</b> +<br><b>princomp(cx_mat coeff, cx_mat score, vec latent, cx_mat X)</b><br> + +<br><b>princomp(mat coeff, mat score, vec latent, vec tsquared, mat X)</b> +<br><b>princomp(cx_mat coeff, cx_mat score, vec latent, cx_vec tsquared, cx_mat X)</b><br> +<br> +<ul> +<li>Principal component analysis of matrix <i>X</i></li><br> +<li>Each row of <i>X</i> is an observation and each column is a variable</li><br> +<li>output objects: +<ul> +<li><i>coeff</i>: principal component coefficients</li> +<li><i>score</i>: projected data</li> +<li><i>latent</i>: eigenvalues of the covariance matrix of <i>X</i></li> +<li><i>tsquared</i>: Hotteling's statistic for each sample</li> +</ul> +</li> +<br> +<li>The computation is based on singular value decomposition; +if the decomposition fails, the output objects are reset and: +<ul> +<li><i>princomp(X)</i> throws a <i>std::runtime_error</i> exception</li> +<li>remaining forms of <i>princomp()</i> return a bool set to <i>false</i></li> +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,4); + +mat coeff; +mat score; +vec latent; +vec tsquared; + +princomp(coeff, score, latent, tsquared, A); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="http://en.wikipedia.org/wiki/Principal_component_analysis">principal components analysis in Wikipedia</a></li> +<li><a href="http://mathworld.wolfram.com/PrincipalComponentAnalysis.html">principal components analysis in MathWorld</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="qr"></a> +<b>qr(Q,R,X)</b> +<ul> +<li> +Decomposition of <i>X</i> into an orthogonal matrix <i>Q</i> and a right triangular matrix <i>R</i>, such that <i>Q*R = X</i> +</li> +<br> +<li> +If the decomposition fails, <i>Q</i> and <i>R</i> are reset and the function returns a bool set to <i>false</i> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat X = randu<mat>(5,5); +mat Q, R; + +qr(Q,R,X); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#qr_econ">qr_econ()</a></li> +<li><a href="http://en.wikipedia.org/wiki/Orthogonal_matrix">Orthogonal matrix in Wikipedia</a></li> +<li><a href="http://en.wikipedia.org/wiki/QR_decomposition">QR decomposition in Wikipedia</a></li> +<li><a href="http://mathworld.wolfram.com/QRDecomposition.html">QR decomposition in MathWorld</a></li> +<li><a href="http://octave.sourceforge.net/octave/function/qr.html">QR decomposition in Octave</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="qr_econ"></a> +<b>qr_econ(Q,R,X)</b> +<ul> +<li> +Economical decomposition of <i>X</i> (with size <i>m</i> x <i>n</i>) into an orthogonal matrix <i>Q</i> and a right triangular matrix <i>R</i>, such that <i>Q*R = X</i> +</li> +<br> +<li> +If <i>m</i> > <i>n</i>, only the first <i>n</i> rows of <i>R</i> and the first <i>n</i> columns of <i>Q</i> are calculated +(ie. the zero rows of <i>R</i> and the corresponding columns of <i>Q</i> are omitted) +</li> +<br> +<li> +If the decomposition fails, <i>Q</i> and <i>R</i> are reset and the function returns a bool set to <i>false</i> +</li> +<br> +<li> +This function was added in version 3.4 +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat X = randu<mat>(6,5); +mat Q, R; + +qr_econ(Q,R,X); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#qr">qr()</a></li> +<li><a href="http://en.wikipedia.org/wiki/Orthogonal_matrix">Orthogonal matrix in Wikipedia</a></li> +<li><a href="http://en.wikipedia.org/wiki/QR_decomposition">QR decomposition in Wikipedia</a></li> +<li><a href="http://octave.sourceforge.net/octave/function/qr.html">QR decomposition in Octave</a></li> +<li><a href="http://mathworld.wolfram.com/QRDecomposition.html">QR decomposition in MathWorld</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<a name="solve"></a> +<b>X = solve(A, B, </b><i>slow=false</i><b>)</b> +<br><b>solve(X, A, B, </b><i>slow=false</i><b>)</b> +<ul> +<li>Solve a system of linear equations, ie., <i>A*X = B</i>, where <i>X</i> is unknown</li> +<br> +<li>The <i>slow</i> argument is optional</li> +<br> +<li>For a square matrix <i>A</i>, this function is conceptually the same as <i>X = inv(A)*B</i>, but is more efficient</li> +<br> +<li>Similar functionality to the "\" (left division operator) operator in Matlab/Octave, ie. <i>X = A \ B</i></li> +<br> +<li>The number of rows in <i>A</i> and <i>B</i> must be the same</li> +<br> +<li> +If <i>A</i> is known to be a triangular matrix, +the solution can be computed faster by explicitly marking the matrix as triangular +through <a href="#trimat">trimatu()</a> or <a href="#trimat">trimatl()</a> +</li> +<br> +<li> +If <i>A</i> is non-square (and hence also non-triangular), +solve() will also try to provide approximate solutions to under-determined as well as over-determined systems</li> +<br> +<li> +If no solution is found, <i>X</i> is reset and: +<ul> +<li><i>solve(A,B)</i> throws a <i>std::runtime_error</i> exception</li> +<li><i>solve(X,A,B)</i> returns a bool set to <i>false</i></li> +</ul> +</li> +<br> +<li> +For matrix sizes ≤ 4x4, a fast algorithm is used by default. +In rare instances, the fast algorithm might be less precise than the standard algorithm. +To force the use of the standard algorithm, set the <i>slow</i> argument to <i>true</i> +</li> +<br> +<li> +<b>NOTE:</b> Old versions of the ATLAS library (eg. 3.6) can corrupt memory and crash your program; +the standard LAPACK library and later versions of ATLAS (eg. 3.8) work without problems +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +vec b = randu<vec>(5); +mat B = randu<mat>(5,5); + +vec x = solve(A, b); +mat X = solve(A, B); + +vec x2; +solve(x2, A, b); + +// tell solve() to look only at the upper triangular part of A +mat Y = solve( trimatu(A), B ); + + +mat44 C = randu<mat>(4,4); +mat44 D = randu<mat>(4,4); + +mat E = solve(C, D); // use fast algorithm by default +mat F = solve(C, D, true); // use slow algorithm + +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#i_member">.i()</a></li> +<li><a href="#inv">inv()</a></li> +<li><a href="#pinv">pinv()</a></li> +<li><a href="#syl">syl()</a></li> +<li><a href="#trimat">trimatu() / trimatl()</a></li> +<li><a href="http://mathworld.wolfram.com/LinearSystemofEquations.html">linear system of equations in MathWorld</a></li> +<li><a href="http://en.wikipedia.org/wiki/Linear_system_of_equations">system of linear equations in Wikipedia</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + + +<a name="svd"></a> +<b>vec s = svd(mat X)</b> +<br><b>vec s = svd(cx_mat X)</b> +<br> +<br><b>svd(vec s, mat X)</b>, +<br><b>svd(vec s, cx_mat X)</b> +<br> +<br><b>svd(mat U, vec s, mat V, mat X, method = "standard")</b> +<br><b>svd(cx_mat U, vec s, cx_mat V, cx_mat X, method = "standard")</b> +<ul> +<li> +The first four forms compute the singular values of <i>X</i> +</li> +<br> +<li> +The last two forms compute the full singular value decomposition of <i>X</i> +</li> +<br> +<li>The <i>method</i> argument is optional</li> +<br> +<li> +By default, a standard decomposition algorithm is used; +a divide-and-conquer algorithm can be used instead by explicitly setting <i>method</i> to <i>"dc"</i> +</li> +<br> +<li> +The divide-and-conquer algorithm provides slightly different results, but is notably faster for large matrices +</li> +<br> +<li>If <i>X</i> is square, it can be reconstructed using <i>X = U*diagmat(s)*V.t()</i> +</li> +<br> +<li> +The singular values are in descending order +</li> +<br> +<li> +If the decomposition fails, the output objects are reset and: +<ul> +<li><i>svd(X)</i> throws a <i>std::runtime_error</i> exception</li> +<li><i>svd(s,X)</i> and <i>svd(U,s,V,X)</i> return a bool set to <i>false</i></li> +</ul> +</li> +<br> +<li> +<b>NOTE:</b> Old versions of the ATLAS library (eg. 3.6) can corrupt memory and crash your program; +the standard LAPACK library and later versions of ATLAS (eg. 3.8) work without problems +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat X = randu<mat>(5,5); + +mat U; +vec s; +mat V; + +svd(U,s,V,X); // use standard algorithm by default + +svd(U,s,V,X, "dc"); // use "divide & conquer" algorithm +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#svd_econ">svd_econ()</a></li> +<li><a href="#eig_gen">eig_gen()</a></li> +<li><a href="#eig_sym">eig_sym()</a></li> +<li><a href="http://en.wikipedia.org/wiki/Singular_value_decomposition">singular value decomposition in Wikipedia</a></li> +<li><a href="http://mathworld.wolfram.com/SingularValueDecomposition.html">singular value decomposition in MathWorld</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"> +<br> + +<a name="svd_econ"></a> +<b>svd_econ(mat U, vec s, mat V, mat X, mode = 'b')</b> +<br><b>svd_econ(cx_mat U, vec s, cx_mat V, cx_mat X, mode = 'b')</b> +<ul> +<li> +Economical singular value decomposition of <i>X</i> +</li> +<br> +<li> +mode is one of: +<ul> +<li><i>'l'</i>: compute only left singular vectors</li> +<li><i>'r'</i>: compute only right singular vectors</li> +<li><i>'b'</i>: compute both left and right singular vectors (default)</li> +</ul> +</li> +<br> +<li> +The singular values are in descending order +</li> +<br> +<li> +If the decomposition fails, the output objects are reset and bool set to <i>false</i> is returned +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat X = randu<mat>(4,5); + +mat U; +vec s; +mat V; +svd_econ(U, s, V, X, 'l'); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#svd">svd()</a></li> +<li><a href="#eig_gen">eig_gen()</a></li> +<li><a href="#eig_sym">eig_sym()</a></li> +<li><a href="http://en.wikipedia.org/wiki/Singular_value_decomposition">singular value decomposition in Wikipedia</a></li> +<li><a href="http://mathworld.wolfram.com/SingularValueDecomposition.html">singular value decomposition in MathWorld</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"> +<br> + +<a name="syl"></a> +<b>X = syl(A, B, C)</b> +<br><b>syl(X, A, B, C)</b> +<ul> +<li>Solve the Sylvester equation, ie., <i>AX + XB + C = 0</i>, where <i>X</i> is unknown.</li> +<br> +<li>Matrices <i>A</i>, <i>B</i> and <i>C</i> must be square sized.</li> +<br> +<li> +If no solution is found, <i>X</i> is reset and: +<ul> +<li><i>syl(A,B,C)</i> throws a <i>std::runtime_error</i> exception</li> +<li><i>svd(X,A,B,C)</i> returns a bool set to <i>false</i></li> +</ul> +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +mat B = randu<mat>(5,5); +mat C = randu<mat>(5,5); + +mat X1 = syl(A, B, C); + +mat X2; +syl(X2, A, B, C); +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#solve">solve()</a></li> +<li><a href="http://en.wikipedia.org/wiki/Sylvester_equation">Sylvester equation in Wikipedia</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"> + + +<hr class="greyline"> +<br> +<br> +<font size=+1><b>Miscellaneous</b></font> +<br> +<br> +<hr class="greyline"> +<br> + +<a name="is_finite_standalone"></a> +<b>is_finite(X)</b> +<ul> +<li> +Returns <i>true</i> if all elements in <i>X</i> are finite +</li> +<br> +<li> +Returns <i>false</i> if at least one element in <i>X</i> is non-finite (±infinity or NaN) +</li> +<br> +<li> +<i>X</i> can be a scalar (eg. <i>double</i>), vector, matrix or cube +</li> +<br> +<li> +Examples: +<ul> +<pre> +mat A = randu<mat>(5,5); +mat B = randu<mat>(5,5); + +B(1,1) = datum::nan; + +cout << is_finite(A) << endl; +cout << is_finite(B) << endl; + +cout << is_finite( 0.123456789 ) << endl; +cout << is_finite( datum::nan ) << endl; +cout << is_finite( datum::inf ) << endl; +</pre> +</ul> +</li> +<br> +<li> +See also: +<ul> +<li><a href="#constants">datum::nan</a></li> +<li><a href="#constants">datum::inf</a></li> +<li><a href="#is_finite">.is_finite()</a> (member function of <i>Mat</i> and <i>Cube</i>)</li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="logging"></a> +<b>logging of warnings and errors</b> +<br> +<br> +<b>set_stream_err1(user_stream)</b><br> +<b>set_stream_err2(user_stream)</b><br> +<br> +<b>std::ostream& x = get_stream_err1()</b> +<br> +<b>std::ostream& x = get_stream_err2()</b> +<br> +<ul> +<li> +By default, Armadillo prints warnings and messages associated with <i>std::logic_error</i> and <i>std::runtime_error</i> exceptions to the <i>std::cout</i> stream +</li> +<br> +<li><b>set_stream_err1()</b>: change the stream for messages associated with <i>std::logic_error</i> exceptions (eg. out of bounds accesses)</li> +<br> +<li><b>set_stream_err2()</b>: change the stream for warnings and messages associated with <i>std::runtime_error</i> exceptions (eg. failed decompositions)</li> +<br> +<li><b>get_stream_err1()</b>: get a reference to the stream for messages associated with <i>std::logic_error</i> exceptions</li> +<br> +<li><b>get_stream_err2()</b>: get a reference to the stream for warnings and messages associated with <i>std::runtime_error</i> exceptions</li> +<br> +<li> +Examples: +<ul> +<pre> +// print "hello" to the current err1 stream +get_stream_err1() << "hello" << endl; + +// change the err2 stream to be a file +ofstream f("my_log.txt"); +set_stream_err2(f); + +// trying to invert a singular matrix +// will print a message to the err2 stream +// and throw an exception +mat X = zeros<mat>(5,5); +mat Y = inv(X); + +// disable messages being printed to the err2 stream +std::ostream nullstream(0); +set_stream_err2(nullstream); +</pre> +</ul> +</li> +<br> +<li> +<b>Caveat</b>: set_stream_err1() and set_stream_err2() will not change the stream used by .print() +</li> +<br> +<li> +See also: +<ul> +<li><a href="#print">.print()</a></li> +<li><a href="http://cplusplus.com/reference/iostream/cout/">std::cout</a></li> +<li><a href="http://cplusplus.com/reference/iostream/ostream/">std::ostream</a></li> +<li><a href="http://cplusplus.com/reference/std/stdexcept/logic_error/">std::logic_error</a></li> +<li><a href="http://cplusplus.com/reference/std/stdexcept/runtime_error/">std::runtime_error</a></li> +<li><a href="http://cplusplus.com/doc/tutorial/exceptions/">tutorial on exceptions</a></li> +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + + + +<a name="constants"></a> +<b>various constants (pi, inf, speed of light, ...)</b> +<br> +<ul> +<li> +Collection of math and fundamental physical constants +</li> +<br> +<li> +Physical constants were mainly taken from +<a href="http://physics.nist.gov/cuu/Constants">NIST</a> +and some from +<a href="http://www.wolframalpha.com">WolframAlpha</a> +on 2009-06-23; +constants from NIST are in turn sourced from the <a href="http://physics.nist.gov/cuu/Constants/papers.html">2006 CODATA values</a> +</li> +<br> +<li> +The constants are stored in the <i>Datum<type></i> class, +where <i>type</i> is either <i>float</i> or <i>double</i> +</li> +<br> +<li> +For convenience, +<i>Datum<double></i> has been typedefed as <i>datum</i> +while +<i>Datum<float></i> has been typedefed as <i>fdatum</i> +</li> +<br> +<li> +In previous versions of Armadillo (eg. 2.x), the constants are accessed via static functions in <i>math</i> and <i>phy</i> classes, eg. <i>math::pi()</i>; +for compatibility, these classes are still available in version 3.x, but are not explicitly documented +</li> +<br> +<li> +Meaning of the constants: +<br> +<br> +<ul> +<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2"> +<tbody> + <tr> + <td style="vertical-align: top;"> + datum::pi + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + π, the ratio of any circle's circumference to its diameter + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::inf + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + infinity + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::nan + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + “not a number” (NaN); <b>caveat:</b> NaN is not equal to anything, even itself + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::e + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + base of the natural logarithm + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::sqrt2 + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + square root of 2 + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::eps + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + the difference between 1 and the least value greater than 1 that is representable (type and machine dependant) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::log_min + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + log of minimum non-zero value (type and machine dependant) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::log_max + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + log of maximum value (type and machine dependant) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::euler + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Euler's constant, aka Euler-Mascheroni constant + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::gratio + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + golden ratio + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::m_u + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + atomic mass constant (in kg) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::N_A + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Avogadro constant + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::k + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Boltzmann constant (in joules per kelvin) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::k_evk + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Boltzmann constant (in eV/K) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::a_0 + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Bohr radius (in meters) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::mu_B + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Bohr magneton + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::Z_0 + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + characteristic impedance of vacuum (in ohms) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::G_0 + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + conductance quantum (in siemens) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::k_e + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Coulomb's constant (in meters per farad) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::eps_0 + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + electric constant (in farads per meter) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::m_e + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + electron mass (in kg) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::eV + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + electron volt (in joules) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::ec + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + elementary charge (in coulombs) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::F + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Faraday constant (in coulombs) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::alpha + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + fine-structure constant + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::alpha_inv + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + inverse fine-structure constant + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::K_J + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Josephson constant + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::mu_0 + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + magnetic constant (in henries per meter) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::phi_0 + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + magnetic flux quantum (in webers) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::R + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + molar gas constant (in joules per mole kelvin) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::G + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Newtonian constant of gravitation (in newton square meters per kilogram squared) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::h + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Planck constant (in joule seconds) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::h_bar + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Planck constant over 2 pi, aka reduced Planck constant (in joule seconds) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::m_p + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + proton mass (in kg) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::R_inf + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Rydberg constant (in reciprocal meters) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::c_0 + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + speed of light in vacuum (in meters per second) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::sigma + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Stefan-Boltzmann constant + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::R_k + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + von Klitzing constant (in ohms) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + datum::b + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Wien wavelength displacement law constant + </td> + </tr> +</tbody> +</table> +</ul> +</li> +<br> +<li> +<b>Caveat:</b> +datum::nan is not equal to anything, even itself; +if you wish to check whether a given number <i>x</i> is finite, +use <a href="#is_finite_standalone">is_finite</a>(<i>x</i>). +</li> +<br> +<li> +Examples: +<ul> +<pre> +cout << "2.0 * pi = " << 2.0 * datum::pi << endl; + +cout << "speed of light = " << datum::c_0 << endl; + +cout << "log_max for floats = "; +cout << fdatum::log_max << endl; + +cout << "log_max for doubles = "; +cout << datum::log_max << endl; +</pre> +</ul> +</li> +<li> +See also: +<ul> +<li><a href="#is_finite_standalone">is_finite()</a></li> +<li><a href="http://en.wikipedia.org/wiki/NaN">NaN</a> in Wikipedia</li> +<li><a href="http://en.wikipedia.org/wiki/Physical_constant">physical constant</a> in Wikipedia</li> +<li><a href="http://cplusplus.com/reference/std/limits/numeric_limits/">std::numeric_limits</a></li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> + +<!-- +<a name="log_add"></a> +<b>log_add(log_a, log_b)</b> +<ul> +<li> +Safe replacement for log(exp(log_a) + exp(log_b)) +</li> +<br> +<li> +Usage: +<ul> +<li> +<i>scalar_type</i> log_c = log_add(log_a, log_b) +</li> +<li> +<i>scalar_type</i> is either <i>float</i> or <i>double</i> +</li> +<li> +log_a, log_b and log_c must have the same type +</li> +</ul> +</li> +</ul> +<br> +<hr class="greyline"><br> +--> + +<a name="uword"></a> +<b>uword</b>, <b>sword</b> +<ul> +<li> +<i>uword</i> is a typedef for an unsigned integer with a minimum width of 32 bits; if <i>ARMA_64BIT_WORD</i> is enabled, the minimum width is 64 bits +</li> +<br> +<li> +<i>sword</i> is a typedef for a signed integer with a minimum width of 32 bits; if <i>ARMA_64BIT_WORD</i> is enabled, the minimum width is 64 bits +</li> +<br> +<li> +<a href="#config_hpp_arma_64bit_word"><i>ARMA_64BIT_WORD</i></a> can be enabled via editing <i>include/armadillo_bits/config.hpp</i> +</li> +<br> +<li>See also: +<ul> +<li><a href="http://cplusplus.com/doc/tutorial/variables/">C++ variable types</a></li> +<li><a href="http://www.cplusplus.com/doc/tutorial/other_data_types/">explanation of <i>typedef</i></a></li> +<li><a href="#Mat">imat & umat</a> matrix types +<li><a href="#Col">ivec & uvec</a> vector types +</ul> +</li> +<br> +</ul> +<hr class="greyline"><br> + +<a name="cx_float_double"></a> +<b>cx_float</b>, <b>cx_double</b> +<ul> +<li> +cx_float is a typedef for <i>std::complex<float></i> +</li> +<br> +<li> +cx_double is a typedef for <i>std::complex<double></i> +</li> +<br> +<li>See also: +<ul> +<li><a href="http://cplusplus.com/reference/std/complex/">complex numbers in the standard C++ library</a></li> +<li><a href="http://www.cplusplus.com/doc/tutorial/other_data_types/">explanation of <i>typedef</i></a></li> +<li><a href="#Mat">cx_mat</a> matrix type +<li><a href="#Col">cx_vec</a> vector type +</ul> +</li> +<br> +</ul> + +<a name="syntax"></a> +<hr class="greyline"> +<br> +<b> +Examples of Matlab/Octave syntax and conceptually corresponding Armadillo syntax +</b> +<br> +<br> +<ul> +<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2"> +<tbody> + <tr> + <td style="vertical-align: top;"> + <b>Matlab/Octave</b> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <b>Armadillo</b> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <b>Notes</b> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A(1, 1) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A(0, 0) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + indexing in Armadillo starts at 0 + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A(k, k) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A(k-1, k-1) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + size(A,1) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A<a href="#attributes">.n_rows</a> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + read only + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + size(A,2) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A<a href="#attributes">.n_cols</a> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + size(Q,3) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Q<a href="#attributes">.n_slices</a> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Q is a <a href="#Cube">cube</a> (3D array) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + numel(A) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A<a href="#attributes">.n_elem</a> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A(:, k) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A<a href="#submat">.col</a>(k) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +this is a conceptual example only; +exact conversion from Matlab/Octave to Armadillo syntax +will require taking into account that indexing starts at 0 + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A(k, :) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A<a href="#submat">.row</a>(k) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A(:, p:q) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A<a href="#submat">.cols</a>(p, q) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A(p:q, :) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A<a href="#submat">.rows</a>(p, q) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A(p:q, r:s) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <font size=-1> + A<a href="#submat">.submat</a>(p, r, q, s) + </font> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <font size=-1> + A.submat(first_row, first_col, last_row, last_col) + </font> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <font size=-1> + or + </font> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <font size=-1> + A( <a href="#submat">span</a>(p,q), <a href="#submat">span</a>(r,s) ) + </font> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <font size=-1> + A( span(first_row, last_row), span(first_col, last_col) ) + </font> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + Q(:, :, k) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Q<a href="#subcube">.slice</a>(k) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Q is a <a href="#Cube">cube</a> (3D array) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + Q(:, :, t:u) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Q<a href="#subcube">.slices</a>(t, u) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + Q(p:q, r:s, t:u) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <font size=-1> + Q<a href="#subcube">.subcube</a>(p, r, t, q, s, u) + </font> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <font size=-1> + .subcube(first_row, first_col, first_slice, last_row, last_col, last_slice) + </font> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <font size=-1> + or + </font> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <font size=-1> + Q( <a href="#subcube">span</a>(p,q), <a href="#subcube">span</a>(r,s), <a href="#subcube">span</a>(t,u) ) + </font> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A' + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A<a href="#t_st_members">.t()</a> or <a href="#trans">trans</a>(A) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + matrix transpose / Hermitian transpose + <br> + (for complex matrices, the conjugate of each element is taken) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A.' + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A<a href="#t_st_members">.st()</a> or <a href="#strans">strans</a>(A) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + simple matrix transpose + <br> + (for complex matrices, the conjugate of each element is not taken) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A = zeros(size(A)) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A<a href="#zeros_member">.zeros()</a> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A = ones(size(A)) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A.<a href="#ones_member">ones()</a> + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A = zeros(k) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A = <a href="#zeros_standalone">zeros</a><mat>(k,k) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A = ones(k) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A = <a href="#ones_standalone">ones</a><mat>(k,k) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + C = complex(A,B) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + cx_mat C = <a href="#Mat">cx_mat</a>(A,B) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A .* B + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A % B + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <a href="#operators">element-wise multiplication</a> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A ./ B + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A / B + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <a href="#operators">element-wise division</a> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A \ B + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <a href="#solve">solve</a>(A,B) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + conceptually similar to <a href="#inv">inv</a>(A)*B, but more efficient + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A = A + 1; + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A++ + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A = A - 1; + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A-- + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A = [ 1 2; 3 4; ] + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +A <font size=-1><<</font> 1 <font size=-1><<</font> 2 <font size=-1><<</font> endr<br> + <font size=-1><<</font> 3 <font size=-1><<</font> 4 <font size=-1><<</font> endr; + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <a href="#element_initialisation">element initialisation</a>, + with special element <i>endr</i> indicating <i>end of row</i> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + X = [ A B ] + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + X = <a href="#join">join_rows</a>(A,B) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + X = [ A; B ] + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + X = <a href="#join">join_cols</a>(A,B) + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + A + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + cout <font size=-1><<</font> A <font size=-1><<</font> endl; + <br>or + <br>A<a href="#print">.print</a>("A ="); + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + save -ascii 'A.dat' A + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A<a href="#save_load_mat">.save</a>("A.dat", raw_ascii); + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + Matlab/Octave matrices saved as ascii are readable by Armadillo (and vice-versa) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + load -ascii 'A.dat' + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + A<a href="#save_load_mat">.load</a>("A.dat", raw_ascii); + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + S = { 'abc'; 'def' } + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <a href="#field">field</a><std::string> S(2); + <br>S(0) = "abc"; + <br>S(1) = "def"; + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + <a href="#field">fields</a> can store arbitrary objects, in a 1D or 2D layout + </td> + </tr> +</tbody> +</table> +</ul> +<br> + +<a name="example_prog"></a> +<hr class="greyline"> +<br> +<b>example program</b> +<br> +<br> +<ul> +<li> +If you save the program below as <i>example.cpp</i>, +under Linux you can compile it using: +<br> +g++ example.cpp -o example -O1 -larmadillo +</li> +<ul> +<pre> +#include <iostream> +#include <armadillo> + +using namespace std; +using namespace arma; + +int main(int argc, char** argv) + { + mat A = randu<mat>(4,5); + mat B = randu<mat>(4,5); + + cout << A*B.t() << endl; + + return 0; + } +</pre> +</ul> +<li> +You may also want to have a look at the example programs that come with the Armadillo archive. +</li> +<br> +<li> +As Armadillo is a template library, we strongly recommended to have optimisation enabled when compiling programs +(eg. when compiling with GCC, use the -O1 or -O2 options). +</li> +</ul> +<br> + + + +<a name="config_hpp"></a> +<hr class="greyline"> +<br> +<b>config.hpp</b> +<br> +<br> +<ul> +<li> +Armadillo can be configured via editing the file <i>include/armadillo_bits/config.hpp</i>. +Specific functionality can be enabled or disabled by uncommenting or commenting out a particular <i>#define</i>, listed below. +<br> +<br> +<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2"> +<tbody> + <tr> + <td style="vertical-align: top;"> +ARMA_USE_LAPACK + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Enable the use of LAPACK, or a high-speed replacement for LAPACK (eg. Intel MKL, AMD ACML or the Accelerate framework). +Armadillo requires LAPACK for functions such as <a href="#svd">svd()</a>, <a href="#inv">inv()</a>, <a href="#eig_sym">eig_sym()</a>, <a href="#solve">solve()</a>, etc. + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +ARMA_USE_BLAS + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Enable the use of BLAS, or a high-speed replacement for BLAS (eg. OpenBLAS, Intel MKL, AMD ACML or the Accelerate framework). +BLAS is used for <a href="#operators">matrix multiplication</a>. +Without BLAS, Armadillo will use a built-in matrix multiplication routine, which might be slower for large matrices. +<!--However, if you're using 64 bit operating system with 32 bit BLAS, it's better to disable the use of BLAS.--> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +ARMA_BLAS_CAPITALS + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Use capitalised (uppercase) BLAS and LAPACK function names (eg. DGEMM vs dgemm) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +ARMA_BLAS_UNDERSCORE + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Append an underscore to BLAS and LAPACK function names (eg. dgemm_ vs dgemm). Enabled by default. + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +ARMA_BLAS_LONG + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Use "long" instead of "int" when calling BLAS and LAPACK functions + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +ARMA_BLAS_LONG_LONG + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Use "long long" instead of "int" when calling BLAS and LAPACK functions + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +ARMA_USE_TBB_ALLOC + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Use Intel TBB <i>scalable_malloc()</i> and <i>scalable_free()</i> instead of standard <i>new[]</i> and <i>delete[]</i> for managing matrix memory + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +ARMA_USE_MKL_ALLOC + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Use Intel MKL <i>mkl_malloc()</i> and <i>mkl_free()</i> instead of standard <i>new[]</i> and <i>delete[]</i> for managing matrix memory + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +<a name="config_hpp_arma_64bit_word"></a> +ARMA_64BIT_WORD + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Use 64 bit integers. Useful if you require matrices/vectors capable of holding more than 4 billion elements. +Your machine and compiler must have support for 64 bit integers (eg. via "long" or "long long"). +This can also be enabled by adding <i>#define ARMA_64BIT_WORD</i> before each instance of <i>#include <armadillo></i>. + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +<a name="config_hpp_arma_use_cxx11"></a> +ARMA_USE_CXX11 + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Use C++11 features, such as <a href="#element_initialisation">initialiser lists</a> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +ARMA_USE_HDF5 + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Enable the the ability to <a href="#save_load_mat">save and load</a> matrices stored in the HDF5 format; +the <i>hdf5.h</i> header file must be available on your system and you will need to link with the hdf5 library (eg. -lhdf5) + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +<a name="config_hpp_arma_no_debug"></a> +ARMA_NO_DEBUG + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Disable all run-time checks, such as <a href="#element_access">bounds checking</a>. +This will result in faster code, but you first need to make sure that your code runs correctly! +We strongly recommend to have the run-time checks enabled during development, +as this greatly aids in finding mistakes in your code, and hence speeds up development. +We recommend that run-time checks be disabled <b>only</b> for the shipped version of your program. + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +ARMA_EXTRA_DEBUG + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Print out the trace of internal functions used for evaluating expressions. +Not recommended for normal use. +This is mainly useful for debugging the library. + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +ARMA_MAT_PREALLOC + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +The number of preallocated elements used by matrices and vectors. +Must be always enabled and set to an integer that is at least 1. +By default set to 16. +If you mainly use lots of very small vectors (eg. ≤ 4 elements), change the number to the size of your vectors. + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +ARMA_DEFAULT_OSTREAM + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +The default stream used for printing <a href="#logging">error messages</a> and by <a href="#print">.print()</a>. +Must be always enabled. +By default this is set to <i>std::cout</i> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +ARMA_DONT_USE_LAPACK + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Disable use of LAPACK. Overrides <i>ARMA_USE_LAPACK</i> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> + <tr> + <td style="vertical-align: top;"> +ARMA_DONT_USE_BLAS + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> +Disable use of BLAS. Overrides <i>ARMA_USE_BLAS</i> + </td> + </tr> + <tr> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + <td style="vertical-align: top;"> + + </td> + </tr> +</tbody> +</table> +</li> + +<br> +<li> +See also: +<ul> +<li><a href="#logging">logging of warnings and errors</a></li> +<li><a href="#element_access">element access</a></li> +<li><a href="#element_initialisation">element initialisation</a></li> +<li><a href="#uword">uword/sword</a></li> +</ul> +</li> +<br> +</ul> +<br> + + + +<!-- +<a name="catching_exceptions"></a> +<hr class="greyline"> +<br> +<b>how to catch std::runtime_error exceptions</b> +<br> +<br> +<ul> +<li> +If a function such as <a href="#inv">inv()</a> fails to find a solution, +an error message is printed and a <i>std::runtime_error</i> exception is thrown. +If the exception is not caught, the program typically terminates. +Below is an example of how to catch exceptions: +<ul> +<pre> +#include <iostream> +#include <armadillo> + +using namespace std; +using namespace arma; + +int main(int argc, char** argv) + { + // create a non-invertible matrix + mat A = zeros<mat>(5,5); + + mat B; + + try + { + B = inv(A); + } + catch (std::runtime_error& x) + { + cout << "caught an exception" << endl; + } + + return 0; + } +</pre> +</ul> +<li> +See also: +<ul> +<li><a href="#logging">logging of warnings and errors</a></li> +<li><a href="http://cplusplus.com/doc/tutorial/exceptions/">tutorial on exceptions</a></li> +<li><a href="http://cplusplus.com/reference/std/stdexcept/runtime_error/">std::runtime_error</a></li> +</ul> +</li> +<br> +</ul> +<br> +--> + +<a name="api_additions"></a> +<a name="api_changes"></a> +<hr class="greyline"> +<br> +<b>API Additions, Changes and Deprecations</b> +<br> +<br> +<li>API and Version Policy +<ul> +<li> +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). +</li> +<br> +<li> +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). +For example, code written for version 3.0 will work with version 3.2. +However, as each minor version may have more features (ie. API extensions) than earlier versions, +code specifically written for version 3.2 doesn't necessarily work with 3.0. +</li> +<br> +<li> +An odd minor version number (eg. 3.3) indicates an experimental version. +Experimental versions are generally faster and have more functionality, +but their APIs have not been finalised yet. +</li> +<br> +<li> +In general, we don't like changes to existing APIs and prefer not to break any user software. +However, to allow evolution and help code maintenance, we reserve the right to change the APIs in future major versions of Armadillo, +while remaining backwards compatible wherever possible +(eg. 4.0 may have slightly different APIs than 3.x). +Also, in a rare instance the user API may need to be altered if a bug fix absolutely requires it. +</li> +</ul> +</li> + +<!-- +<br> +<li> +<a name="deprecated"></a> +List of deprecated functionality; this functionality will be <b>removed</b> in version 4.0: +<ul> +<li> +... +</li> +</ul> +</li> +--> + +<br> +<br> +<li> +List of additions and changes for each version: +<br> +<br> +<ul> +<a name="added_in_3900"></a> +<li>Added in 3.900: +<ul> +<li>automatic SSE2 vectorisation of elementary expressions (eg. matrix addition) when using GCC 4.7+ with -O3 optimisation</li> +<li>faster <a href="#stats_fns">median()</a></li> +<li>faster handling of compound expressions with transposes of <a href="#submat">submatrix</a> rows</li> +<li>faster handling of compound expressions with transposes of complex vectors</li> +<li>added support for <a href="#save_load_mat">saving & loading</a> of <a href="#Cube">cubes</a> in HDF5 format</li> +</ul> +</li> +<br> +<a name="added_in_3820"></a> +<li>Added in 3.820: +<ul> +<li>faster <a href="#as_scalar">as_scalar()</a> for compound expressions</li> +<li>faster transpose of small vectors</li> +<li>faster matrix-vector product for small vectors</li> +<li>faster multiplication of small <a href="#adv_constructors_mat_fixed">fixed size matrices</a></li> +</ul> +</li> +<br> +<a name="added_in_3810"></a> +<li>Added in 3.810: +<ul> +<li>fast Fourier transform: <a href="#fft">fft()</a></li> +<li>handling of <a href="#imbue">.imbue()</a> and <a href="#transform">.transform()</a> by submatrices and subcubes</li> +<li><a href="#batch_constructors_sp_mat">batch insertion constructors</a> for sparse matrices +</ul> +</li> +<br> +<a name="added_in_3800"></a> +<li>Added in 3.800: +<ul> +<li><a href="#imbue">.imbue()</a> for filling a matrix/cube with values provided by a functor or lambda expression</li> +<li><a href="#swap">.swap()</a> for swapping contents with another matrix</li> +<li><a href="#transform">.transform()</a> for transforming a matrix/cube using a functor or lambda expression</li> +<li><a href="#misc_fns">round()</a> for rounding matrix elements towards nearest integer</li> +<li>faster <a href="#find">find()</a></li> +</ul> +</li> +<br> +<li>Changed in 3.800: +<ul> +<li>Armadillo is now licensed using the <a href="http://www.mozilla.org/MPL/2.0/">Mozilla Public License 2.0</a>; +<br> +see also the associated <a href="http://www.mozilla.org/MPL/2.0/FAQ.html">frequently asked questions</a> about the license</li> +</ul> +<br> +</li> +<a name="added_in_36"></a> +<li>Added in 3.6: +<ul> +<li>faster handling of compound expressions with submatrices and subcubes</li> +<li>faster <a href="#trace">trace()</a></li> +<li>support for loading matrices as text files with <i>NaN</i> and <i>Inf</i> elements</li> +<li><a href="#sort_index">stable_sort_index()</a>, which preserves the relative order of elements with equivalent values</li> +<li>handling of <a href="#SpMat">sparse matrices</a> by <a href="#stats_fns">mean()</a>, <a href="#stats_fns">var()</a>, <a href="#norm">norm()</a>, <a href="#abs">abs()</a>, <a href="#misc_fns">square()</a>, <a href="#misc_fns">sqrt()</a></li> +<li>saving and loading of sparse matrices in <i>arma_binary</i> format</li> +</ul> +<br> +</li> +<a name="added_in_34"></a> +<li>Added in 3.4: +<ul> +<li>economical QR decomposition: <a href="#qr_econ">qr_econ()</a></li> +<li><a href="#each_colrow">.each_col() & .each_row()</a> for vector operations repeated on each column or row of a matrix</li> +<li>preliminary support for <a href="#SpMat">sparse matrices</a></li> +<li>ability to <a href="#save_load_mat">save and load</a> matrices in HDF5 format</li> +<li>faster <a href="#svd">singular value decomposition</a> via optional use of divide-and-conquer algorithm</li> +<li>faster <a href="#randu_randn_member">.randn()</a></li> +<li>faster <a href="#dot">dot() and cdot()</a> for complex numbers</li> +</ul> +<br> +</li> +<a name="added_in_32"></a> +<li>Added in 3.2: +<ul> +<li><a href="#unique">unique()</a>, for finding unique elements of a matrix</li> +<li><a href="#eval_member">.eval()</a>, for forcing the evaluation of delayed expressions</li> +<li>faster <a href="#eig_sym">eigen decomposition</a> via optional use of divide-and-conquer algorithm</li> +<li>faster <a href="#t_st_members">transpose</a> of vectors and compound expressions</li> +<li>faster handling of <a href="#diag">diagonal views</a></li> +<li>faster handling of tiny <a href="#adv_constructors_col_fixed">fixed size</a> vectors (≤ 4 elements)</li> +</ul> +<br> +</li> +<a name="added_in_30"></a> +<li>Added in 3.0: +<ul> +<li>shorthand for inverse: <a href="#i_member">.i()</a></li> +<li><a href="#constants">datum</a> class</li> +<li><a href="#hist">hist()</a> and <a href="#histc">histc()</a></li> +<li>non-contiguous <a href="#submat">submatrix views</a></li> +<li>faster handling of <a href="#submat">submatrix views</a> with a single row or column</li> +<li>faster element access in <a href="#adv_constructors_mat_fixed">fixed size matrices</a></li> +<li>faster <a href="#repmat">repmat()</a></li> +</ul> +<br> +</li> +<li>Changed in 3.0: +<ul> +<li>expressions <i>X=<a href="#inv">inv</a>(A)*B</i> and <i>X=A<a href="#i_member">.i()</a>*B</i> are automatically converted to <i>X=<a href="#solve">solve</a>(A,B)</i> +<li>better detection of vector expressions by <a href="#sum">sum()</a>, <a href="#cumsum">cumsum()</a>, <a href="#prod">prod()</a>, <a href="#min_and_max">min()</a>, <a href="#min_and_max">max()</a>, <a href="#stats_fns">mean()</a>, <a href="#stats_fns">median()</a>, <a href="#stats_fns">stddev()</a>, <a href="#stats_fns">var()</a> +<li>faster generation of random numbers +(eg. <a href="#randu_randn_standalone">randu()</a> and <a href="#randu_randn_standalone">randn()</a>), +via an algorithm that produces slightly different numbers than in 2.x +</li> +<li> +support for tying writeable auxiliary (external) memory to fixed size matrices has been removed; +instead, you can use standard matrices with <a href="#adv_constructors_mat">writeable auxiliary memory</a>, +or initialise fixed size matrices by <a href="#adv_constructors_mat">copying the memory</a>. +Using auxiliary memory with standard matrices is unaffected. +</li> +<li> +<i>.print_trans()</i> and <i>.raw_print_trans()</i> have been removed; +instead, you can chain <i><a href="#t_st_members">.t()</a></i> and <i><a href="#print">.print()</a></i> to achieve a similar result: <i>X.t().print()</i> +</li> +</ul> +<br> +</li> +<a name="added_in_24"></a> +<li>Added in 2.4: +<ul> +<li>shorter forms of transposes: <a href="#t_st_members">.t()</a> and <a href="#t_st_members">.st()</a></li> +<li><a href="#resize_member">.resize()</a> and <a href="#resize">resize()</a></li> +<li>optional use of 64 bit indices (allowing matrices to have more than 4 billion elements), +<br>enabled via ARMA_64BIT_WORD in <i>include/armadillo_bits/config.hpp</i></li> +<li>experimental support for C++11 initialiser lists, +<br>enabled via ARMA_USE_CXX11 in <i>include/armadillo_bits/config.hpp</i></li> +</ul> +<br> +<li>Changed in 2.4: +<ul> +<li>refactored code to eliminate warnings when using the Clang C++ compiler</li> +<li><a href="#Mat">umat</a>, <a href="#Col">uvec</a>, <a href="#min_and_max_member">.min()</a> and <a href="#min_and_max_member">.max()</a> +have been changed to use the <a href="#uword"><i>uword</i></a> type instead of the <i>u32</i> type; +by default the <i>uword</i> and <i>u32</i> types are equivalent (ie. unsigned integer type with a minimum width 32 bits); +however, when the use of 64 bit indices is enabled via ARMA_64BIT_WORD in <i>include/armadillo_bits/config.hpp</i>, +the <i>uword</i> type then has a minimum width of 64 bits +</ul> +</li> +<br> +<li>Added in 2.2: +<ul> +<li><a href="#svd_econ">svd_econ()</a></li> +<li><a href="#toeplitz">circ_toeplitz()</a></li> +<li><a href="#is_vec">.is_colvec()</a> and <a href="#is_vec">.is_rowvec()</a></li> +</ul> +<br> +<li>Added in 2.0: +<ul> +<li><a href="#det">det()</a>, <a href="#inv">inv()</a> and <a href="#solve">solve()</a> can be forced to use more precise algorithms for tiny matrices (≤ 4x4)</li> +<li><a href="#syl">syl()</a>, for solving Sylvester's equation</li> +<li><a href="#strans">strans()</a>, for transposing a complex matrix without taking the complex conjugate</li> +<li><a href="#symmat">symmatu()</a> and <a href="#symmat">symmatl()</a></li> +<li>submatrices of <a href="#submat">submatrices</a></li> +<li>faster <a href="#inv">inverse</a> of symmetric positive definite matrices</li> +<li>faster element access for <a href="#adv_constructors_mat_fixed">fixed size</a> matrices</li> +<li>faster multiplication of tiny matrices (eg. 4x4)</li> +<li>faster compound expressions containing <a href="#submat">submatrices</a></li> +<li>handling of arbitrarily sized empty matrices (eg. 5x0)</li> +<li>.count() member function in <a href="#running_stat">running_stat</a> and <a href="#running_stat_vec">running_stat_vec</a></li> +<li><a href="#save_load_mat">loading & saving</a> of matrices as CSV text files</li> +</ul> +<br> +<li>Changed in 2.0: +<ul> +<li><a href="#trans">trans()</a> now takes the complex conjugate when transposing a complex matrix</li> +<li>Forms of +<a href="#chol">chol()</a>, <a href="#eig_sym">eig_sym()</a>, <a href="#eig_gen">eig_gen()</a>, +<a href="#inv">inv()</a>, <a href="#lu">lu()</a>, <a href="#pinv">pinv()</a>, <a href="#princomp">princomp()</a>, +<a href="#qr">qr()</a>, <a href="#solve">solve()</a>, <a href="#svd">svd()</a>, <a href="#syl">syl()</a> +that do not return a bool indicating success now throw <i>std::runtime_error</i> exceptions when failures are detected</li> +<li>princomp_cov() has been removed; <a href="#eig_sym">eig_sym()</a> in conjunction with <a href="#cov">cov()</a> can be used instead</li> +<li><a href="#is_vec">.is_vec()</a> now outputs <i>true</i> for empty vectors (eg. 0x1)</li> +<li>set_log_stream() & get_log_stream() have been replaced by <a href="#logging">set_stream_err1()</a> & <a href="#logging">get_stream_err1()</a></li> +</ul> +<br> +<li>Added in 1.2: +<ul> +<li><a href="#min_and_max_member">.min() & .max()</a> member functions of Mat and Cube</li> +<li><a href="#misc_fns">floor()</a> and <a href="#misc_fns">ceil()</a></li> +<li>representation of “not a number”: math::nan()</li> +<li>representation of infinity: math::inf()</li> +<li>standalone <a href="#is_finite_standalone">is_finite()</a></li> +<li><a href="#in_range">.in_range()</a> can use <b>span()</b> arguments</li> +<li><a href="#adv_constructors_mat">fixed size</a> matrices and vectors can use auxiliary (external) memory</li> +<li><a href="#submat">submatrices</a> and <a href="#subfield">subfields</a> can be accessed via <i><b>X(</b> <b>span(</b>a,b<b>)</b>, <b>span(</b>c,d<b>)</b> <b>)</b></i></li> +<li><a href="#subcube">subcubes</a> can be accessed via <i><b>X(</b> <b>span(</b>a,b<b>)</b>, <b>span(</b>c,d<b>)</b>, <b>span(</b>e,f<b>)</b> <b>)</b></i></li> +<li>the two argument version of <i><b>span</b></i> can be replaced by +<i><b>span::all</b></i> or <i><b>span()</b></i>, to indicate an entire range +</li> +<li>for cubes, the two argument version of <i><b>span</b></i> can be replaced by +a single argument version, <i><b>span(</b>a<b>)</b></i>, to indicate a single column, row or slice +</li> +<li>arbitrary "flat" subcubes can be interpreted as matrices; for example: +<ul> +<pre> +cube Q = randu<cube>(5,3,4); +mat A = Q( span(1), span(1,2), span::all ); +// A has a size of 2x4 + +vec v = ones<vec>(4); +Q( span(1), span(1), span::all ) = v; +</pre> +</ul> +</li> +<li>interpretation of matrices as triangular through <a href="#trimat">trimatu() / trimatl()</a></li> +<li>explicit handling of triangular matrices by <a href="#solve">solve()</a> and <a href="#inv">inv()</a></li> +<li>extended syntax for <a href="#submat">submatrices</a>, including access to elements whose indices are specified in a vector</li> +<li>ability to change the stream used for <a href="#logging">logging</a> of errors and warnings</li> +<li>ability to <a href="#save_load_mat">save/load matrices</a> in raw binary format</li> +<li>cumulative sum function: <a href="#cumsum">cumsum()</a></li> +</ul> +</li> +<br> +<li> +Changed in 1.0 (compared to earlier 0.x development versions): +<ul> +<li> +the 3 argument version of <a href="#lu">lu()</a>, +eg. lu(L,U,X), +provides L and U which should be the same as produced by Octave 3.2 +(this was not the case in versions prior to 0.9.90) +</li> +<br> +<li> +rand() has been replaced by <a href="#randu_randn_standalone">randu()</a>; +this has been done to avoid confusion with <a href="http://cplusplus.com/reference/clibrary/cstdlib/rand/">std::rand()</a>, +which generates random numbers in a different interval +</li> +<br> +<li> +In versions earlier than 0.9.0, +some multiplication operations directly converted result matrices with a size of 1x1 into scalars. +This is no longer the case. +If you know the result of an expression will be a 1x1 matrix and wish to treat it as a pure scalar, +use the <a href="#as_scalar">as_scalar()</a> wrapping function +</li> +<br> +<li> +Almost all functions have been placed in the delayed operations framework (for speed purposes). +This may affect code which assumed that the output of some functions was a pure matrix. +The solution is easy, as explained below. +<br> +<br> +In general, Armadillo queues operations before executing them. +As such, the direct output of an operation or function cannot be assumed to be a directly accessible matrix. +The queued operations are executed when the output needs to be stored in a matrix, +eg. <i>mat B = trans(A)</i> or <i>mat B(trans(A))</i>. +If you need to force the execution of the delayed operations, +place the operation or function inside the corresponding Mat constructor. +For example, if your code assumed that the output of some functions was a pure matrix, +eg. <i>chol(m).diag()</i>, change the code to <i>mat(chol(m)).diag()</i>. +Similarly, if you need to pass the result of an operation such as <i>A+B</i> to one of your own functions, +use <i>my_function( mat(A+B) )</i>. +</li> +</ul> +</li> +</ul> +</li> +<br> +<br> +<br> + + +<!-- END CONTENT --> + + +<hr> +<br> +<br> + +</td> +</tr> +</tbody> +</table> +</center> +</body> +</html>