<!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.930</b></font>
<br>
<b>(Dragon's Back)</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,
see the <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 discover 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="#randi">randi</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="#conj">conj</a> ·
<a href="#conv_to">conv_to</a> ·
<a href="#eps">eps</a> ·
<a href="#imag_real">imag/real</a> ·
<a href="#misc_fns">misc functions (exp, log, pow, sqrt, round, sign, ...)</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="#all">all</a> ·
<a href="#any">any</a> ·
<a href="#conv">conv</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="#inplace_strans">inplace_strans</a> ·
<a href="#inplace_trans">inplace_trans</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> ·
<a href="#vectorise">vectorise</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="#fft2">fft2/ifft2</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">pre-defined constants (pi, inf, speed of light, ...)</a> ·
<!--<a href="#log_add">log_add</a> ·-->
<a href="#uword">uword/sword</a> ·
<a href="#cx_double">cx_double/cx_float</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> is 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>, <i>long</i> and unsigned versions of <i>char</i>, <i>short</i>, <i>int</i>, <i>long</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_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_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 <a href="https://en.wikipedia.org/wiki/Column_major">column-major ordering</a> (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(n_rows, n_cols, fill_type) (version 3.920+)</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>
When specifying the size with <i>n_rows</i> and <i>n_cols</i>, by default the memory is uninitialised;
since version 3.920, memory can be initialised by specifying the <i>fill_type</i>,
which is one of:
<i>fill::zeros</i>,
<i>fill::ones</i>,
<i>fill::eye</i>,
<i>fill::randu</i>,
<i>fill::randn</i>,
<i>fill::none</i>,
with the following meanings:
<ul>
<table>
<tbody>
<tr><td>fill::zeros</td><td> = </td><td>set all elements to 0</td></tr>
<tr><td>fill::ones</td><td> = </td><td>set all elements to 1</td></tr>
<tr><td>fill::eye</td><td> = </td><td>set the elements along the main diagonal to 1 and off-diagonal elements to 0</td></tr>
<tr><td>fill::randu</td><td> = </td><td>set each element to a random value from a uniform distribution in the [0,1] interval</td></tr>
<tr><td>fill::randn</td><td> = </td><td>set each element to a random value from a normal/Gaussian distribution with zero mean and unit variance</td></tr>
<tr><td>fill::none</td><td> = </td><td>do not modify the elements</td></tr>
</tbody>
</table>
</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,
it is considerably faster to directly <a href="#element_access">set the elements</a>,
use <a href="#element_initialisation">element initialisation</a>,
or use C++11 initialiser lists.
</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 writable 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.ones(5,6);
mat E(4,5, fill::zeros); // in version 3.920+
//
// 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_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_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()</li>
<li>vec(n_elem)</li>
<li>vec(n_elem, fill_type) (version 3.920+)</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>
<li>
When specifying the size with <i>n_elem</i>, by default the memory is uninitialised;
since version 3.920, memory can be initialised by specifying the <i>fill_type</i>,
as per the <a href="#Mat">Mat class</a>
</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 writable 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);
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_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_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()</li>
<li>rowvec(n_elem)</li>
<li>rowvec(n_elem, fill_type) (version 3.920+)</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>
<li>
When specifying the size with <i>n_elem</i>, by default the memory is uninitialised;
since version 3.920, memory can be initialised by specifying the <i>fill_type</i>,
as per the <a href="#Mat">Mat class</a>
</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 writable 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<rowvec>(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> is 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>, <i>long</i> and unsigned versions of <i>char</i>, <i>short</i>, <i>int</i>, <i>long</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;">
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_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_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>
<li>cube()</li>
<li>cube(n_rows, n_cols, n_slices)</li>
<li>cube(n_rows, n_cols, n_slices, fill_type) (version 3.920+)</li>
<li>cube(cube)</li>
<li>cx_cube(cube, cube) (for constructing a complex cube out of two real cubes)</li>
</ul>
</li>
<br>
<li>
When specifying the cube size with <i>n_rows</i>, <i>n_cols</i> and <i>n_slices</i>, by default the memory is uninitialised;
since version 3.920, memory can be initialised by specifying the <i>fill_type</i>,
as per the <a href="#Mat">Mat class</a> (except for <i>fill::eye</i>)
</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 writable 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> is 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>, <i>long</i> and unsigned versions of <i>char</i>, <i>short</i>, <i>int</i>, <i>long</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;">
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_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_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(<i>n_rows</i>, <i>n_cols</i>)</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>
Elements are stored in the <a href="http://en.wikipedia.org/wiki/Sparse_matrix">compressed sparse column (CSC) format</a>
</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>
<a name="batch_constructors_sp_mat"></a>
Batch insertion constructors:
<ul>
<li>form 1: sp_mat(<i>locations</i>, <i>values</i>, <i>sort_locations = true</i>)</li>
<li>form 2: sp_mat(<i>locations</i>, <i>values</i>, <i>n_rows</i>, <i>n_cols</i>, <i>sort_locations = true</i>)</li>
<li>form 3: sp_mat(<i>rowind</i>, <i>colptr</i>, <i>values</i>, <i>n_rows</i>, <i>n_cols</i>) (added in version 3.920)</li>
<br>
<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>
For forms 1 and 2, <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 location of the <i>i</i>-th element is specified by the contents of the <i>i</i>-th column of the <i>locations</i> matrix,
where the row is in <i>locations(0,i)</i>, and the column is in <i>locations(1,i)</i>
</li>
<br>
<li>
For all forms, <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.
For forms 1 and 2, 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>
For form 3,
<i>rowind</i> is a dense column vector of type <i>umat</i> or <i>uvec</i> containing the row indices of the values to be inserted,
and
<i>colptr</i> is a dense column vector of type <i>umat</i> or <i>uvec</i> containing indices of <i>values</i> corresponding to the start of new columns;
the vectors correspond to the arrays used by the <a href="http://en.wikipedia.org/wiki/Sparse_matrix">compressed sparse column format</a>
</li>
<br>
<li>
The size of the constructed matrix is either automatically determined from the maximal locations in the <i>locations</i> matrix (form 1),
or manually specified via <i>n_rows</i> and <i>n_cols</i> (forms 2 and 3)
</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>
</ul>
<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; present in <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>field</i> and <i>SpMat</i> classes
</td>
</tr>
<tr>
<td>
<b>.n_cols</b>
</td>
<td> </td>
<td>
number of columns; present in <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>field</i> and <i>SpMat</i> classes
</td>
</tr>
<tr>
<td>
<b>.n_elem</b>
</td>
<td> </td>
<td>
total number of elements; present in <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>field</i> and <i>SpMat</i> classes
</td>
</tr>
<tr>
<td>
<b>.n_slices</b>
</td>
<td> </td>
<td>
number of slices; present in the <i>Cube</i> class
</td>
</tr>
<tr>
<td>
<b>.n_nonzero</b>
</td>
<td> </td>
<td>
number of non-zero elements; present in the <i>SpMat</i> class
</td>
</tr>
</tbody>
</table>
</ul>
<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>
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>
<br><b>.diag( k )</b>
<ul>
<li>
Member function of <i>Mat</i>
</li>
<br>
<li>
Read/write access to a 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>
The diagonal is interpreted as a column vector within expressions
</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( vector_of_indices )</b>
<br>
<b>.each_row( vector_of_indices )</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;">
<code>(n)</code>
</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;">
<code>.at(n)</code> or <code>[n]</code>
</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;">
<code>(i,j)</code>
</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;">
<code>.at(i,j)</code>
</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;">
<code>(i,j,k)</code>
</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;">
<code>.at(i,j,k)</code>
</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 the <a href="#config_hpp_arma_no_debug">ARMA_NO_DEBUG</a> macro
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>
When using a C++11 compiler, instances of <i>Mat</i>, <i>Col</i> and <i>Row</i> classes can be also initialised via initialiser lists
</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="#reshape_member">.reshape()</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 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( value )</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>
<li><a href="#constants">pre-defined constants (pi, nan, inf, ...)</a></li>
</ul>
</li>
<br>
</ul>
<hr class="greyline"><br>
<a name="i_member"></a>
<b>.i()</b>
<br><b>.i( slow )</b>
<br><b>.i( method )</b> <i>(added in version 3.930)</i>
<ul>
<li>
Member function of any matrix expression
</li>
<br>
<li>
Provides an inverse of the matrix expression
</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>The <i>slow</i> argument is optional</li>
<br>
<li>The <i>method</i> argument is optional</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,
either set the <i>slow</i> argument to <i>true</i>,
or set the <i>method</i> argument to "standard"
</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(); // use fast algorithm by default
X = A.i("standard"); // use standard algorithm
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>
<tr>
<td>
</td>
</tr>
<tr>
<td>
<i>Added in version 3.930:</i>
</td>
</tr>
<tr>
<td style="vertical-align: top;"><b>.in_range(</b> first_row<b>,</b> first_col<b>, size(</b>X<b>) )</b> <i>(X is a mat or field)</i></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(</b> first_row<b>,</b> first_col<b>, size(</b>n_rows<b>,</b> n_cols<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>
</td>
</tr>
<tr>
<td>
<i>Added in version 3.930:</i>
</td>
</tr>
<tr>
<td style="vertical-align: top;"><b>.in_range(</b> first_row<b>,</b> first_col<b>, </b> first_slice<b>, size(</b>Q<b>) )</b> <i>(Q is a cube)</i></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(</b> first_row<b>,</b> first_col<b>, </b> first_slice<b>, size(</b>n_rows<b>,</b> n_cols<b></b> n_slices<b>) )</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 <i>true</i> if the object has no elements
</li>
<br>
<li>Returns <i>false</i> 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">pre-defined constants (pi, nan, 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 <b>)</b>
<br>
<b>.insert_rows( </b>row_number, number_of_rows, set_to_zero <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<b>,</b> X<b> )</b>
<br>
<b>.insert_cols( </b>col_number<b>,</b> number_of_cols <b>)</b>
<br>
<b>.insert_cols( </b>col_number<b>,</b> number_of_cols<b>,</b> set_to_zero <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<b>,</b> X<b> )</b>
<br>
<b>.insert_slices( </b>slice_number<b>,</b> number_of_slices <b>)</b>
<br>
<b>.insert_slices( </b>slice_number<b>,</b> number_of_slices<b>,</b> set_to_zero <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 <i>X</i> at the specified row/column/slice
<ul>
<li>if inserting rows, <i>X</i> must have the same number of columns as the recipient object</li>
<li>if inserting columns, <i>X</i> must have the same number of rows as the recipient object</li>
<li>if inserting slices, <i>X</i> 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( row_number )</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( row_number )</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( col_number )</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( col_number )</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( slice_number )</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( slice_number )</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()</b>
<br><b>.print( header )</b>
<br>
<br><b>.print( stream )</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>
Print the contents of an object to the <i>std::cout</i> stream (default),
or a user specified stream, with an optional header string
</li>
<br>
<li>
Objects can also be printed 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;
cout << 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()</b>
<br><b>.raw_print( header )</b>
<br>
<br><b>.raw_print( stream )</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 )</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, dim )</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> </td>
</tr>
<tr>
<td style="vertical-align: top;"><b>.reshape( 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>
<tr>
<td style="vertical-align: top;"><b>.reshape( n_rows, n_cols, n_slices, dim )</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 (<i>dim=0</i>) or row-wise (<i>dim=1</i>);
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>
do not use .reshape() if you simply want to change the size without preserving data;
use <a href="#set_size">.set_size()</a> instead, which is much faster
</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);
</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>
<li><a href="#vectorise">vectorise()</a></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>
do not use .resize() if you simply want to change the size without preserving data;
use <a href="#set_size">.set_size()</a> instead, which is much faster
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A = randu<mat>(4,5);
A.resize(7,6);
</pre>
</ul>
</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>
<li><a href="#vectorise">vectorise()</a></li>
</ul>
</li>
</ul>
<br>
<hr class="greyline"><br>
<a name="save_load_mat"></a>
<b>
.save( name )
<br>.save( name, file_type )
<br>
<br>.save( stream )
<br>.save( stream, file_type )
<br>
<br>.load( name )
<br>.load( name, file_type )
<br>
<br>.load( stream )
<br>.load( stream, file_type )
<br>
<br>.quiet_save( name )
<br>.quiet_save( name, file_type )
<br>
<br>.quiet_save( stream )
<br>.quiet_save( stream, file_type )
<br>
<br>.quiet_load( name )
<br>.quiet_load( name, file_type )
<br>
<br>.quiet_load( stream )
<br>.quiet_load( stream, file_type )
</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>
The default <i>file_type</i> for <i>.save()</i> and <i>.quiet_save()</i> is <i>arma_binary</i> (see below)
</li>
<br>
<li>
The default <i>file_type</i> for <i>.load()</i> and <i>.quiet_load()</i> is <i>auto_detect</i> (see below)
</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>
<i>file_type</i> can be one of the following:
<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;">
Used by <i>load()</i> and <i>quiet_load()</i> only:
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.
<i>arma_binary</i> is the default <i>file_type</i> for <i>.save()</i> and <i>.quiet_save()</i>
<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.900.
<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,</b> file_type = arma_binary <b>)
<br>
.save( stream,</b> file_type = arma_binary <b>)
<br>
<br>
.load( name,</b> file_type = auto_detect <b>)
<br>
.load( stream,</b> file_type = auto_detect <b>)
<br>
<br>
.quiet_save( name,</b> file_type = arma_binary <b>)
<br>
.quiet_save( stream,</b> file_type = arma_binary <b>)
<br>
<br>
.quiet_load( name,</b> file_type = auto_detect <b>)
<br>
.quiet_load( stream,</b> file_type = auto_detect <b>)
</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 uninitialised
</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;">
<b>.empty()</b>
</td>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;">
returns <i>true</i> if the object has no elements; returns <i>false</i> if the object has one or more elements
</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>
<br>
X<b>( span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<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>unsafe_col( </b>col_number<b> )</b><br>
<br>
V<b>( span(</b>first_index<b>,</b> last_index<b>) )</b> <i>(for vectors only)</i><br>
V.<b>subvec( </b>first_index<b>,</b> last_index<b> )</b> <i>(for vectors only)</i><br>
<br>
<i>Added in version 3.930:</i>
<br>
X<b>( </b>first_row<b>,</b> first_col<b>, size(</b>n_rows<b>, </b>n_cols<b>) )</b><br>
X<b>( </b>first_row<b>,</b> first_col<b>, size(</b>Y<b>) )</b> <i>(Y is a mat)</i><br>
<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 four 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) );
mat E = A( 0, 1, size(3,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>
<br>
<i>Added in version 3.920:</i>
<br>
Q.<b>tube( </b>row<b>,</b> col <b>)</b><br>
Q.<b>tube( </b>first_row<b>,</b> first_col<b>,</b> last_row<b>,</b> last_col <b>)</b><br>
Q.<b>tube( span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b> last_col<b>) )</b><br>
<br>
<i>Added in version 3.930:</i>
<br>
Q<b>( </b>first_row<b>,</b> first_col<b>,</b> first_slice<b>, size(</b>n_rows<b>,</b> n_cols<b>, </b>n_slices<b>) )</b><br>
Q<b>( </b>first_row<b>,</b> first_col<b>,</b> first_slice<b>, size(</b>R<b>) )</b> <i>(R is a cube)</i><br>
Q.<b>tube( </b>first_row<b>,</b> first_col<b>, size(</b>n_rows<b>,</b> n_cols<b>) )</b><br>
</ul>
</li>
<br>
<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>
All <i>.tube()</i> forms are variants of <i>.subcube()</i>, using <i>first_slice = 0</i> and <i>last_slice = Q.n_slices-1</i>
</li>
<br>
<li>
The <i>.tube(row,col)</i> form uses <i>row = first_row = last_row</i>, and <i>col = first_col = last_col</i>
</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);
A( 0,0,1, size(2,2,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>
<br>
F<b>( span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<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>
<i>Added in version 3.930:</i>
<br>
F<b>( </b>first_row<b>,</b> first_col<b>, size(</b>G<b>) )</b> <i>(G is a field)</i><br>
F<b>( </b>first_row<b>,</b> first_col<b>, size(</b>n_rows<b>, </b>n_cols<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( X )</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>
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_double">cx_float</a></i>, <i><a href="#cx_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>.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>.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>
</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>.var(</b> norm_type <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>
</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>.stddev(</b> norm_type <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>.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 <i>.var()</i> and <i>.stddev()</i> 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 <i>.count()</i> 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 = randn();
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>></b>
<br><b>running_stat_vec<</b><i>type</i><b>>(calc_cov)</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_double">cx_float</a></i>, <i><a href="#cx_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_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>.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>.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>
</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>.var(</b> norm_type <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>
</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>.stddev(</b> norm_type <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>.cov()</b>
</td>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;">
get the covariance matrix so far
</td>
</tr>
<tr>
<td style="vertical-align: top;">
<b>.cov(</b> norm_type <b>)</b>
</td>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;">
get the covariance matrix 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>
By default the covariance matrix is not calculated;
to enable the covariance matrix, set <i>calc_cov</i> to <i>true</i> during the construction of the class
</li>
<br>
<li>
For the <i>.var()</i> and <i>.stddev()</i> 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 <i>.count()</i> 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 )</b>
<br><b>linspace( start, end, N )</b>
<ul>
<li>
Generate a vector with <i>N</i> elements;
the values of the elements linearly increase from <i>start</i> to (and including) <i>end</i>
</li>
<br>
<li>
By default <i>N = 100</i>
</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>
<li><a href="#randu_randn_standalone">randu() & randn()</a></li>
</ul>
</li>
</ul>
<br>
<hr class="greyline"><br>
<a name="randi"></a>
<b>randi( n_elem )</b>
<br><b>randi( n_elem, distr_param(a,b) )</b>
<br>
<br><b>randi( n_rows, n_cols )</b>
<br><b>randi( n_rows, n_cols, distr_param(a,b) )</b>
<br>
<br><b>randi( n_rows, n_cols, n_slices )</b>
<br><b>randi( n_rows, n_cols, n_slices, distr_param(a,b) )</b>
<ul>
<li>
Generate a vector, matrix or cube with the elements set to random <b>integer</b> values in the [a,b] interval
</li>
<br>
<li>The default distribution parameters are <i>a=0</i> and <i>b=maximum_int</i>
</li>
<br>
<li>
Usage:
<ul>
<li><i>vector_type</i> v = randi<<i>vector_type</i>>(n_elem)</li>
<li><i>vector_type</i> v = randi<<i>vector_type</i>>(n_elem, distr_param(a,b))</li>
<br>
<li><i>matrix_type</i> X = randi<<i>matrix_type</i>>(n_rows, n_cols)</li>
<li><i>matrix_type</i> X = randi<<i>matrix_type</i>>(n_rows, n_cols, distr_param(a,b))</li>
<br>
<li><i>cube_type</i> Q = randi<<i>cube_type</i>>(n_rows, n_cols, n_slices)</li>
<li><i>cube_type</i> Q = randi<<i>cube_type</i>>(n_rows, n_cols, n_slices, distr_param(a,b))</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>
<b>Caveat:</b> if you want to generate a continuous distribution with floating point values (ie. <i>float</i> or <i>double</i>),
use <a href="#randu_randn_standalone">randu()</a> or <a href="#randu_randn_standalone">randn()</a> instead
</li>
<br>
<li>
This function was added in version 3.930
</li>
<br>
<li>
Examples:
<ul>
<pre>
imat A = randu<imat>(5, 6);
imat A = randu<imat>(6, 7, distr_param(-10, +20));
</pre>
</ul>
</li>
<li>See also:
<ul>
<li><a href="#randu_randn_standalone">randu() & randn()</a></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="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 <b>floating point</b> 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>
<b>Caveat:</b> if you want to generate a matrix with random integer values instead of floating point values,
use <a href="#randi">randi()</a> instead
</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="#randi">randi()</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 <i>A</i> 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>
<li><a href="#randu_randn_standalone">randu() & randn()</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>
<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>
<li>
See also:
<ul>
<li><a href="#conj">conj()</a></li>
<li><a href="#imag_real">imag() / real()</a></li>
</ul>
</li>
</ul>
<br>
<hr class="greyline"><br>
<a name="conj"></a>
<b>conj( X )</b>
<ul>
<li>
Obtain the complex conjugate of each element in a complex matrix or 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="#abs">abs()</a></li>
<li><a href="#imag_real">imag() / real()</a></li>
<li><a href="#trans">trans()</a></li>
</ul>
</li>
<br>
</ul>
<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="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="imag_real"></a>
<b>imag( X )</b>
<br><b>real( X )</b>
<ul>
<li>
Extract the imaginary/real part of a complex matrix or 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 <i>imag()</i> and <i>real()</i> with the <i>arma</i> namespace qualification, eg. <i>arma::imag(C)</i>
</li>
<br>
<li>See also:
<ul>
<li><a href="#set_imag">set_imag() / set_real()</a></li>
<li><a href="#abs">abs()</a></li>
<li><a href="#conj">conj()</a></li>
</ul>
</li>
<br>
</ul>
<hr class="greyline"><br>
<a name="misc_fns"></a>
<b>
miscellaneous element-wise functions:
<ul>
exp, exp2, exp10, trunc_exp
<br>log, log2, log10, trunc_log
<br>pow, sqrt, square
<br>floor, ceil, round
<br>sign
</ul>
</b>
<ul>
<li>
Apply a function to each element
</li>
<br>
<li>
Usage:
<ul>
<li>
<i>matrix_type</i> B = fn(A)
</li>
<li>
<i>cube_type</i> B = fn(A)
</li>
<li>
A and B must have the same <i>matrix_type/cube_type</i>
</li>
<li>
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>
<tr>
<td style="vertical-align: top;">
sign(A)
</td>
<td style="vertical-align: top;">
</td>
<td style="vertical-align: top;">
signum function (added in version 3.920);
<br>for each element <i>a</i> in <i>A</i>, the corresponding element <i>b</i> in <i>B</i> is:
<table>
<tbody>
<tr><td style="text-align: right;">−1</td><td> if <i>a</i> < 0</td></tr>
<tr><td style="text-align: right;">0</td><td> if <i>a</i> = 0</td></tr>
<tr><td style="text-align: right;">+1</td><td> if <i>a</i> > 0</td></tr>
</tbody>
</table>
if <i>a</i> is complex and non-zero, then <i>b</i> = <i>a</i> / abs(<i>a</i>)
</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>
<br>
<li>
See also:
<ul>
<li><a href="#abs">abs()</a></li>
<li><a href="#conj">conj()</a></li>
<li><a href="#imag_real">imag() / real()</a></li>
<li><a href="#constants">pre-defined constants</a></li>
</ul>
</li>
</ul>
<br>
<hr class="greyline"><br>
<a name="trig_fns"></a>
<b>trigonometric element-wise 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( X )</b>
<ul>
<li>
Accumulate (sum) all elements of a matrix or cube
</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="#trace">trace()</a></li>
<li><a href="#dot">dot()</a></li>
<li><a href="#norm">norm()</a></li>
<li><a href="#conv_to">conv_to()</a></li>
<li><a href="#reshape">reshape()</a></li>
<li><a href="#resize">resize()</a></li>
<li><a href="#vectorise">vectorise()</a></li>
</ul>
</li>
<br>
</ul>
<hr class="greyline"><br>
<a name="det"></a>
<b>det( A )</b>
<br><b>det( A, slow )</b>
<br><b>det( A, method )</b> <i>(added in version 3.930)</i>
<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,
either set the <i>slow</i> argument to <i>true</i>,
or set the <i>method</i> argument to "standard"
</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),
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 )</b>
<br>
<b>rank( X, tolerance )</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 <i>tolerance</i> argument is optional;
by default the 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 )</b>
<br><b>diagvec( A, k )</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>
The extracted 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>
<li><a href="#vectorise">vectorise()</a></li>
</ul>
</li>
<br>
</ul>
<hr class="greyline">
<br>
<a name="min_and_max"></a>
<b>min( V )</b>
<br><b>min( X )</b>
<br><b>min( X, dim )</b>
<br><b>min( A, B )</b> <i>(added in version 3.930)</i>
<br>
<br><b>max( V )</b>
<br><b>max( X )</b>
<br><b>max( X, dim )</b>
<br><b>max( A, B )</b> <i>(added in version 3.930)</i>
<ul>
<li>
For vector <i>V</i>, return the extremum value
</li>
<br>
<li>
For matrix <i>X</i>, return the extremum value for each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
For two matrices <i>A</i> and <i>B</i>, return a matrix containing element-wise extremum values
</li>
<br>
<li>
Examples:
<ul>
<pre>
colvec v = randu<colvec>(10,1);
double val = max(v);
mat X = randu<mat>(10,10);
rowvec r = max(X);
// same result as max(X)
// the 0 explicitly indicates "traverse across rows"
rowvec s = max(X,0);
// the 1 explicitly indicates "traverse across columns"
colvec t = max(X,1);
// find the overall maximum value
double y = max(max(X));
// element-wise maximum
mat A = randu<mat>(5,6);
mat B = randu<mat>(5,6);
mat C = arma::max(A,B); // use arma:: prefix to distinguish from std::max()
</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( V )</b>
<br><b>prod( X )</b>
<br><b>prod( X, dim )</b>
<ul>
<li>
For vector <i>V</i>, return the product of all elements
</li>
<br>
<li>
For matrix <i>X</i>, return the product of elements in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</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>
<br><b>sum( V )</b>
<br><b>sum( X )</b>
<br><b>sum( X, dim )</b>
<ul>
<li>
For vector <i>V</i>, return the sum of all elements
</li>
<br>
<li>
For matrix <i>X</i>, return the sum of elements in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
To get a sum of all the elements regardless of the argument type (ie. matrix or vector),
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));
double z = accu(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( V )</b>
<br><b>mean( X )</b>
<br><b>mean( X, dim )</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( V )</b>
<br><b>median( X )</b>
<br><b>median( X, dim )</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( V )</b>
<br><b>stddev( V, norm_type )</b>
<br><b>stddev( X )</b>
<br><b>stddev( X, norm_type )</b>
<br><b>stddev( X, norm_type, dim )</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( V )</b>
<br><b>var( V, norm_type )</b>
<br><b>var( X )</b>
<br><b>var( X, norm_type )</b>
<br><b>var( X, norm_type, dim )</b>
<br>
<br>
</td>
<td style="vertical-align: top;">
</td>
<td style="vertical-align: top;">
variance
</td>
</tr>
</tbody>
</table>
<br>
<li>
For vector <i>V</i>, return a particular statistic calculated using all the elements of the vector
</li>
<br>
<li>
For matrix <i>X</i>, find a particular statistic for each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
For the <i>var()</i> and <i>stddev()</i> functions:
<ul>
<li>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</li>
<li>using <i>norm_type=1</i> performs normalisation using <i>N</i>, which provides the second moment around the mean</li>
</ul>
</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="all"></a>
<b>all( V )</b>
<br><b>all( X )</b>
<br><b>all( X, dim )</b>
<ul>
<li>For vector <i>V</i>, return <i>true</i> if all elements of the vector are non-zero or satisfy a relational condition</li>
<br>
<li>
For matrix <i>X</i> and
<ul>
<li>
<i>dim=0</i>, return a row vector (of type <a href="#Row">urowvec</a> or <a href="#Mat">umat</a>),
with each element (0 or 1) indicating whether the corresponding column of <i>X</i> has all non-zero elements</li>
<br>
<li>
<i>dim=1</i>, return a column vector (of type <a href="#Col">ucolvec</a> or <a href="#Mat">umat</a>),
with each element (0 or 1) indicating whether the corresponding row of <i>X</i> has all non-zero elements</li>
</ul>
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
Relational operators can be used instead of <i>V</i> or <i>X</i>, eg. <i>A > 0.5</i>
</li>
<br>
<li>
This function was added in version 3.910
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec V = randu<vec>(10);
mat X = randu<mat>(5,5);
// status1 will be set to true if vector V has all non-zero elements
bool status1 = all(V);
// status2 will be set to true if vector V has all elements greater than 0.5
bool status2 = all(V > 0.5);
// status3 will be set to true if matrix X has all elements greater than 0.6;
// note the use of vectorise()
bool status3 = all(vectorise(X) > 0.6);
// generate a row vector indicating which columns of X have all elements greater than 0.7
umat A = all(X > 0.7);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#any">any()</a></li>
<li><a href="#find">find()</a></li>
<li><a href="#conv_to">conv_to()</a> (convert between matrix/vector types)</li>
<li><a href="#vectorise">vectorise()</a></li>
</ul>
</li>
<br>
</ul>
<hr class="greyline">
<br>
<a name="any"></a>
<b>any( V )</b>
<br><b>any( X )</b>
<br><b>any( X, dim )</b>
<ul>
<li>For vector <i>V</i>, return <i>true</i> if any element of the vector is non-zero or satisfies a relational condition</li>
<br>
<li>
For matrix <i>X</i> and
<ul>
<li>
<i>dim=0</i>, return a row vector (of type <a href="#Row">urowvec</a> or <a href="#Mat">umat</a>),
with each element (0 or 1) indicating whether the corresponding column of <i>X</i> has any non-zero elements</li>
<br>
<li>
<i>dim=1</i>, return a column vector (of type <a href="#Col">ucolvec</a> or <a href="#Mat">umat</a>),
with each element (0 or 1) indicating whether the corresponding row of <i>X</i> has any non-zero elements</li>
</ul>
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
Relational operators can be used instead of <i>V</i> or <i>X</i>, eg. <i>A > 0.9</i>
</li>
<br>
<li>
This function was added in version 3.910
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec V = randu<vec>(10);
mat X = randu<mat>(5,5);
// status1 will be set to true if vector V has any non-zero elements
bool status1 = any(V);
// status2 will be set to true if vector V has any elements greater than 0.5
bool status2 = any(V > 0.5);
// status3 will be set to true if matrix X has any elements greater than 0.6;
// note the use of vectorise()
bool status3 = any(vectorise(X) > 0.6);
// generate a row vector indicating which columns of X have elements greater than 0.7
umat A = any(X > 0.7);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#all">all()</a></li>
<li><a href="#find">find()</a></li>
<li><a href="#conv_to">conv_to()</a> (convert between matrix/vector types)</li>
<li><a href="#vectorise">vectorise()</a></li>
</ul>
</li>
<br>
</ul>
<hr class="greyline">
<br>
<a name="conv"></a>
<b>
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="cor"></a>
<b>cor( X, Y )</b>
<br><b>cor( X, Y, norm_type )</b>
<br>
<br><b>cor( X )</b>
<br><b>cor( X, norm_type )</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);
mat S = cor(X,Y, 1);
</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 )</b>
<br><b>cov( X, Y, norm_type )</b>
<br>
<br><b>cov( X )</b>
<br><b>cov( X, norm_type )</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);
mat D = cov(X,Y, 1);
</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( V )</b>
<br><b>cumsum( X )</b>
<br><b>cumsum( X, dim )</b>
<ul>
<li>
For vector <i>V</i>, return a vector of the same orientation, containing the cumulative sum of elements
</li>
<br>
<li>
For matrix <i>X</i>, return a matrix containing the cumulative sum of elements in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A = randu<mat>(5,5);
mat B = cumsum(A);
mat C = cumsum(A, 1);
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>
<li><a href="#vectorise">vectorise()</a></li>
</ul>
</li>
<br>
</ul>
<hr class="greyline">
<br>
<a name="find"></a>
<b>find( X )</b>
<br><b>find( X, k )</b>
<br><b>find( X, k, s )</b>
<ul>
<li>Return a column vector containing the indices of elements of <i>X</i> that are non-zero or satisfy a relational condition</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="#all">all()</a></li>
<li><a href="#any">any()</a></li>
<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( X )</b>
<br><b>flipud( X )</b>
<ul>
<li>
fliplr(): generate a copy of input matrix <i>X</i>, with the order of the columns reversed
</li>
<br>
<li>
flipud(): generate a copy of input matrix <i>X</i>, 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 )</b>
<br><b>hist( V, n_bins )</b>
<br><b>hist( X )</b>
<br><b>hist( X, n_bins )</b>
<br><b>hist( X, n_bins, dim )</b>
<br>
<br><b>hist( V, centers )</b>
<br><b>hist( X, centers )</b>
<br><b>hist( X, centers, dim )</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 )</b>
<br><b>histc( X, edges, dim )</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="inplace_strans"></a>
<b>inplace_strans( X )</b>
<br><b>inplace_strans( X, method )</b>
<ul>
<li>
Simple in-place / in-situ transpose of matrix <i>X</i>, without taking the conjugate of the elements (complex matrices)
</li>
<br>
<li>
Use <a href="#inplace_trans">inplace_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 the documentation for <a href="#inplace_trans">inplace_trans()</a> for more details
</li>
<br>
</ul>
<hr class="greyline"><br>
<a name="inplace_trans"></a>
<b>inplace_trans( X )</b>
<br><b>inplace_trans( X, method )</b>
<ul>
<li>
In-place / in-situ transpose of matrix <i>X</i>
</li>
<br>
<li>
If <i>X</i> has real elements, a normal transpose is done
</li>
<br>
<li>
If <i>X</i> has complex elements, a Hermitian transpose is done (ie. the conjugate of the elements is taken during the transpose operation)
</li>
<br>
<li>
The argument <i>method</i> is optional
</li>
<br>
<li>
By default, a standard transposition algorithm is used; a low-memory algorithm can be used instead by explicitly setting <i>method</i> to "lowmem"
</li>
<br>
<li>
The low-memory algorithm is considerably slower than the standard algorithm;
using the low-memory algorithm is only recommended for cases where <i>X</i> takes up more than half of available memory (ie. very large <i>X</i>)
</li>
<br>
<li>
This function was added in version 3.930
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X = randu<mat>(4,5);
mat Y = randu<mat>(20000,30000);
inplace_trans(X); // use standard algorithm by default
inplace_trans(Y, "lowmem"); // use low-memory (and slow) algorithm
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#inplace_strans">inplace_strans()</a></li>
<li><a href="#t_st_members">.t()</a></li>
<li><a href="#trans">trans()</a></li>
<li><a href="https://en.wikipedia.org/wiki/In-place_matrix_transposition">inplace matrix transpose in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>
<hr class="greyline"><br>
<a name="join"></a>
<b>join_rows( A, B )</b>
<br><b>join_cols( A, B )</b>
<br>
<br><b>join_horiz( A, B )</b>
<br><b>join_vert( A, B )</b>
<br>
<br><b>join_slices( C, D )</b>
<ul>
<li>
<i>join_rows()</i> and <i>join_horiz()</i>: horizontal concatenation;
for two matrices <i>A</i> and <i>B</i>, join each row of <i>A</i> with the corresponding row of <i>B</i>;
matrices <i>A</i> and <i>B</i> must have the same number of rows
</li>
<br>
<li>
<i>join_cols()</i> and <i>join_vert()</i>: vertical concatenation;
for two matrices <i>A</i> and <i>B</i>, join each column of <i>A</i> with the corresponding column of <i>B</i>;
matrices <i>A</i> and <i>B</i> must have the same number of columns
</li>
<br>
<li>
<i>join_slices()</i>:
for two cubes <i>C</i> and <i>D</i>, join the slices of <i>C</i> with the slices of <i>D</i>;
cubes <i>C</i> and <i>D</i> have the same number of rows and columns (ie. all slices must have the same size)
</li>
<br>
<li>
The <i>join_horiz()</i> and <i>join_vert()</i> forms were added in version 3.920
</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 )</b>
<br><b>reshape( mat, n_rows, n_cols, dim )</b>
<br>
<br><b>reshape( cube, n_rows, n_cols, n_slices )</b>
<br><b>reshape( cube, n_rows, n_cols, n_slices, dim )</b>
<ul>
<li>
Generate a matrix or 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 <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</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>
do not use reshape() if you simply want to change the size without preserving data;
use <a href="#set_size">.set_size()</a> instead, which is much faster
</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="#vectorise">vectorise()</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 or cube sized according to given size specifications,
whose elements as well as the layout of the elements are taken from the given matrix/cube
</li>
<br>
<li>
<b>Caveat:</b>
do not use resize() if you simply want to change the size without preserving data;
use <a href="#set_size">.set_size()</a> instead, which is much faster
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A = randu<mat>(4, 5);
mat B = resize(A, 7, 6);
</pre>
</ul>
</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="#vectorise">vectorise()</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( V )</b>
<br><b>shuffle( X )</b>
<br><b>shuffle( X, dim )</b>
<ul>
<li>
For vector <i>V</i>, generate a copy of the vector with the elements shuffled
</li>
<br>
<li>
For matrix <i>X</i>, generate a copy of the matrix with the rows (<i>dim=0</i>) or columns (<i>dim=1</i>) shuffled
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</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( V )</b>
<br><b>sort( V, sort_type )</b>
<br><b>sort( V, sort_direction )</b> <i>(added in version 3.930)</i>
<br>
<br><b>sort( X )</b>
<br><b>sort( X, sort_type )</b>
<br><b>sort( X, sort_type, dim )</b>
<br><b>sort( X, sort_direction )</b> <i>(added in version 3.930)</i>
<br><b>sort( X, sort_direction, dim )</b> <i>(added in version 3.930)</i>
<br>
<ul>
<li>For vector <i>V</i>, return a vector which is a sorted version of the input vector</li>
<br>
<li>For matrix <i>X</i>, 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>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li><i>sort_type=0</i> (default) indicates ascending sort, while <i>sort_type=1</i> indicates descending sort</li>
<br>
<li><i>sort_direction</i> can be either "ascend" or "descend"</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( V )</b>
<br><b>sort_index( V, sort_type )</b>
<br><b>sort_index( V, sort_direction )</b> (added in version 3.930)
<br>
<br><b>stable_sort_index( V )</b>
<br><b>stable_sort_index( V, sort_type )</b>
<br><b>stable_sort_index( V, sort_direction )</b> (added in version 3.930)
<ul>
<li>Return a vector which describes the sorted order of the elements of input vector <i>V</i>
(ie. it contains the indices of the elements of <i>V</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><i>sort_type=0</i> (default) indicates ascending sort, while <i>sort_type=1</i> indicates descending sort</li>
<br>
<li><i>sort_direction</i> can be either "ascend" or "descend"</li>
<br>
<li>The <i>stable_sort_index()</i> variant preserves the relative order of elements with equivalent values (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( A )</b>
<ul>
<li>
Simple matrix transpose of <i>A</i>, 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( A )</b>
<ul>
<li>
Matrix transpose / Hermitian transpose of <i>A</i>
</li>
<br>
<li>
If <i>A</i> has real elements, a normal transpose is done
</li>
<br>
<li>
If <i>A</i> has complex elements, a Hermitian transpose is done (ie. the conjugate of the elements is taken during the transpose operation)
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A = randu<mat>(5,10);
mat B = trans(A);
mat C = A.t(); // equivalent to trans(A), but more compact
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#t_st_members">.t()</a></li>
<li><a href="#strans">strans()</a></li>
<li><a href="#inplace_trans">inplace_trans</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">
<a name="vectorise"></a>
<b>vectorise( X )</b>
<br><b>vectorise( X, dim )</b>
<ul>
<li>
Generate a column vector (<i>dim=0</i>) or row vector (<i>dim=1</i>) from matrix <i>X</i>
</li>
<br>
<li>
The argument <i>dim</i> is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
For <i>dim=0</i>, the elements are copied from <i>X</i> column-wise; equivalent to concatenating all the columns of <i>X</i>
</li>
<br>
<li>
For <i>dim=1</i>, the elements are copied from <i>X</i> row-wise; equivalent to concatenating all the rows of <i>X</i>
</li>
<br>
<li>
Concatenating columns is faster than concatenating rows
</li>
<br>
<li>This function was added in version 3.910</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A = randu<mat>(4, 5);
vec v = vectorise(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#reshape">reshape()</a></li>
<li><a href="#resize">resize()</a></li>
<li><a href="#as_scalar">as_scalar()</a></li>
<li><a href="#diagvec">diagvec()</a></li>
</ul>
</li>
<br>
</ul>
<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 )</b>
<br><b>eig_sym(vec eigval, cx_mat eigvec, cx_mat X, method )</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 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 )</b>
<br>
<b>eig_gen( cx_vec eigval, cx_mat eigvec, cx_mat X, side )</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>
<!-- TODO: for version 4.0, change side='r' to side="right", side='l' to side="left" -->
<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>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="#fft2">fft2()</a></li>
<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="fft2"></a>
<b>cx_mat Y = fft2( X )</b><br>
<b>cx_mat Y = fft2( X, n_rows, n_cols )</b><br>
<br>
<b>cx_mat Z = ifft2( cx_mat Y )</b><br>
<b>cx_mat Z = ifft2( cx_mat Y, n_rows, n_cols )</b><br>
<ul>
<li>fft2(): 2D fast Fourier transform of a matrix (real or complex)</li>
<br>
<li>ifft2(): 2D inverse fast Fourier transform of a matrix (complex only)</li>
<br>
<li>
The optional arguments <i>n_rows</i> and <i>n_cols</i> specify the size of the transform;
a truncated and/or zero-padded version of the input matrix is used
</li>
<br>
<li><b>Caveat:</b> the transform is fastest when both <i>n_rows</i> and <i>n_cols</i> are 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.920</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A = randu<mat>(100,100);
cx_mat B = fft2(A);
cx_mat C = fft2(A, 128, 128);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#fft">fft()</a></li>
<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>
<br><b>B = inv( A, slow )</b>
<br><b>B = inv( A, method )</b> (added in version 3.930)
<br>
<br><b>inv( B, A )</b>
<br><b>inv( B, A, slow )</b>
<br><b>inv( B, A, method )</b> (added in version 3.930)
<ul>
<li>
Inverse of square matrix <i>A</i>
</li>
<br>
<li>the <i>slow</i> argument is optional</li>
<br>
<li>the <i>method</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,
either set the <i>slow</i> argument to <i>true</i>,
or set the <i>method</i> argument to "standard"
</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( L, U, P, X )</b>
<br><b>lu( L, U, 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)</b>
<br><b>B = pinv( A, tolerance )</b>
<br><b>B = pinv( A, tolerance, method )</b> <i>(added in version 3.930)</i>
<br>
<br><b>pinv( B, A )</b>
<br><b>pinv( B, A, tolerance )</b>
<br><b>pinv( B, A, tolerance, method )</b> <i>(added in version 3.930)</i>
<ul>
<li>Moore-Penrose pseudo-inverse of matrix <i>A</i></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>The <i>tolerance</i> argument is optional</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>Any singular values less than <i>tolerance</i> are treated as zero</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>
Examples:
<ul>
<pre>
mat A = randu<mat>(4,5);
mat B = pinv(A); // use default tolerance with standard algorithm
mat C = pinv(A, 0.0, "dc"); // use default tolerance with divide-and-conquer 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="#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>
<br><b>X = solve( A, B, slow )</b>
<br><b>X = solve( A, B, method )</b> <i>(added in version 3.930)</i>
<br>
<br><b>solve( X, A, B )</b>
<br><b>solve( X, A, B, slow )</b>
<br><b>solve( X, A, B, method )</b> <i>(added in version 3.930)</i>
<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>The <i>method</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),
<i>solve()</i> 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,
either set the <i>slow</i> argument to <i>true</i>,
or set the <i>method</i> argument to <i>"standard"</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 )</b>
<br><b>svd( mat U, vec s, mat V, mat X, method )</b>
<br>
<br><b>svd( cx_mat U, vec s, cx_mat V, cx_mat X )</b>
<br><b>svd( cx_mat U, vec s, cx_mat V, cx_mat X, method )</b>
<ul>
<li>
Singular value decomposition of matrix <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 )</b>
<br><b>svd_econ( mat U, vec s, mat V, mat X, mode )</b>
<br><b>svd_econ( mat U, vec s, mat V, mat X, side, method )</b> <i>(added in version 3.930)</i>
<br>
<br><b>svd_econ( cx_mat U, vec s, cx_mat V, cx_mat X )</b>
<br><b>svd_econ( cx_mat U, vec s, cx_mat V, cx_mat X, mode )</b>
<br><b>svd_econ( cx_mat U, vec s, cx_mat V, cx_mat X, side, method )</b> <i>(added in version 3.930)</i>
<ul>
<li>
Economical singular value decomposition of <i>X</i>
</li>
<br>
<li>
<i>mode</i> is one of:
<ul>
<li><i>'b'</i>: compute both left and right singular vectors (default operation)</li>
<li><i>'l'</i>: compute only left singular vectors</li>
<li><i>'r'</i>: compute only right singular vectors</li>
</ul>
</li>
<br>
<li>
<i>side</i> is one of:
<ul>
<li><i>"both"</i>: compute both left and right singular vectors</li>
<li><i>"left"</i>: compute only left singular vectors</li>
<li><i>"right"</i>: compute only right singular vectors</li>
</ul>
</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>
The singular values are in descending order
</li>
<br>
<li>
If the decomposition fails, the output objects are reset and a 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, 'b'); // use standard algorithm by default
svd_econ(U, s, V, X, "both", "dc"); // use divide-and-conquer algorithm
</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>syl(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">pre-defined constants (pi, nan, 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>pre-defined constants (pi, inf, speed of light, ...)</b>
<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>
<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>
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>
The 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>
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="#fill">.fill()</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_double"></a>
<b>cx_double</b>, <b>cx_float</b>
<ul>
<li>
<i>cx_double</i> is a shorthand / typedef for <i>std::complex<double></i>
</li>
<br>
<li>
<i>cx_float</i> is a shorthand / typedef for <i>std::complex<float></i>
</li>
<br>
<li>
Example:
<ul>
<pre>
cx_mat X = randu<cx_mat>(5,5);
X(1,2) = cx_double(2.0, 3.0);
</pre>
</ul>
</li>
<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>.
Since version 3.6, this is automatically enabled when using a compiler in C++11 mode, eg. g++ -std=c++11
</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 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
(ie. final release build).
</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 <i>A.B.C</i>, where <i>A</i> is a major version, <i>B</i> is a minor version, and <i>C</i> 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 (ie. when <i>B</i> is not evenly divisible by 2) indicates an experimental version.
Experimental versions are generally faster and have more functionality,
but their APIs have not been finalised yet (though the likelihood of APIs changes is quite low).
</li>
<br>
<li>
In general, we don't like changes to existing APIs and strongly prefer not to break any user software.
However, to allow evolution, we reserve the right to alter the APIs in future major versions of Armadillo,
while remaining backwards compatible wherever possible
(eg. 4.x may have slightly different APIs than 3.x).
Also, in a rare instance the user API may need to be tweaked 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_3930"></a>
<li>Added in 3.930:
<ul>
<li><i>size()</i> based specifications of <a href="#submat">submatrix view</a> sizes</li>
<li>element-wise variants of <a href="#min_and_max">min()</a> and <a href="#min_and_max">max()</a></li>
<li>divide-and-conquer variant of <a href="#svd_econ">svd_econ()</a></li>
<li>divide-and-conquer variant of <a href="#pinv">pinv()</a></li>
<li><a href="#randi">randi()</a> for generating matrices with random integer values</li>
<li><a href="#inplace_trans">inplace_trans()</a> for memory efficient in-place transposes</li>
<li>more intuitive specification of sort direction in <a href="#sort">sort()</a> and <a href="#sort_index">sort_index()</a></li>
<li>more intuitive specification of method in <a href="#det">det()</a>, <a href="#i_member">.i()</a>, <a href="#inv">inv()</a> and <a href="#solve">solve()</a></li>
<li>more precise timer for the <a href="#wall_clock">wall_clock</a> class when using C++11</li>
</ul>
</li>
<br>
<a name="added_in_3920"></a>
<li>Added in 3.920:
<ul>
<li>faster <a href="#zeros_member">.zeros()</a></li>
<li>faster <a href="#misc_fns">round()</a>, <a href="#misc_fns">exp2()</a> and <a href="#misc_fns">log2()</a> when using C++11</li>
<li>signum function: <a href="#misc_fns">sign()</a></li>
<li>move constructors when using C++11</li>
<li>2D fast Fourier transform: <a href="#fft2">fft2()</a></li>
<li><a href="#subcube">.tube()</a> for easier extraction of vectors and subcubes from cubes</li>
<li>specification of a fill type during construction of <a href="#Mat">Mat</a>, <a href="#Col">Col</a>, <a href="#Row">Row</a> and <a href="#Cube">Cube</a> classes,
eg. <i>mat X(4, 5, fill::zeros)</i></li>
</ul>
</li>
<br>
<a name="added_in_3910"></a>
<li>Added in 3.910:
<ul>
<li>faster multiplication of a matrix with a transpose of itself, ie. <i>X*X.t()</i> and <i>X.t()*X</i></li>
<li><a href="#vectorise">vectorise()</a> for reshaping matrices into vectors</li>
<li><a href="#all">all()</a> and <a href="#any">any()</a> for indicating presence of elements satisfying a relational condition</li>
</ul>
</li>
<br>
<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>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 writable auxiliary (external) memory to fixed size matrices has been removed;
instead, you can use standard matrices with <a href="#adv_constructors_mat">writable 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>
distrib
>
Fedora
>
18
>
x86_64
>
media
>
updates
>
by-pkgid
>
594ee2b02597c37fee56ae0616026e2f
>
files
>
393
