21281 lines
651 KiB
HTML
21281 lines
651 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
<!--
|
|
Copyright 2008-2016 Conrad Sanderson (http://conradsanderson.id.au)
|
|
Copyright 2008-2016 National ICT Australia (NICTA)
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<html>
|
|
<head>
|
|
<meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type">
|
|
<title>Armadillo: API Documentation</title>
|
|
<link rel="icon" href="armadillo_icon.png" type="image/png">
|
|
<style type="text/css">
|
|
<!--
|
|
body
|
|
{
|
|
/* font-family: "Trebuchet MS", "Droid Sans", sans-serif; */
|
|
font-family: "Trebuchet MS", 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.latent, a.latent:hover, a.latent:active, a.latent:link, a.latent:visited
|
|
{
|
|
text-decoration: none;
|
|
border-bottom: 0px;
|
|
color: #000000;
|
|
}
|
|
|
|
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;">
|
|
|
|
|
|
<!-- BEGIN CONTENT -->
|
|
|
|
|
|
<style type="text/css">
|
|
<!--
|
|
@media all
|
|
{
|
|
.pagebreak { }
|
|
.noprint { }
|
|
}
|
|
|
|
@media print
|
|
{
|
|
.pagebreak { page-break-before: always; }
|
|
.noprint { display: none !important; }
|
|
}
|
|
-->
|
|
</style>
|
|
|
|
<a class="noprint" style="display:scroll; position:fixed; bottom:5px; right:5px;" href="#top"><font size=-1>[top]</font></a>
|
|
|
|
<a name="top"></a>
|
|
<big><b>API Documentation for Armadillo 14.0 (under development)</b></big>
|
|
<br>
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<b>Preamble</b>
|
|
<br>
|
|
<br>
|
|
<table border="0" cellpadding="0" cellspacing="0">
|
|
<tbody>
|
|
<tr>
|
|
<td style="text-align: left; vertical-align: top; width: 45%;">
|
|
<ul>
|
|
<li>
|
|
For converting Matlab/Octave programs,
|
|
see the <a href="#syntax">syntax conversion table</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
First time users: please see the short <a href="#example_prog">example program</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If you discover any bugs or regressions, please <a href="https://arma.sourceforge.net/faq.html">report them</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
History of <a href="#changelog">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: 50%;">
|
|
<ul>
|
|
<li>
|
|
Please cite the following papers if you use Armadillo in your research and/or software.
|
|
<br>
|
|
Citations are useful for the continued development and maintenance of the library.
|
|
<br>
|
|
<br>
|
|
Conrad Sanderson and Ryan Curtin.
|
|
<br><i><a href="armadillo_joss_2016.pdf">Armadillo: a template-based C++ library for linear algebra</a></i>.
|
|
<br>Journal of Open Source Software, Vol. 1, No. 2, pp. 26, 2016.
|
|
<br>
|
|
<br>
|
|
<!--
|
|
Conrad Sanderson and Ryan Curtin.
|
|
<br><i><a href="armadillo_lncs_2018.pdf">A User-Friendly Hybrid Sparse Matrix Class in C++</a></i>.
|
|
<br>Lecture Notes in Computer Science (LNCS), Vol. 10931, pp. 422-430, 2018.
|
|
-->
|
|
Conrad Sanderson and Ryan Curtin.
|
|
<br><i><a href="armadillo_mca_2019.pdf">Practical Sparse Matrices in C++ with Hybrid Storage and Template-Based Expression Optimisation</a></i>.
|
|
<br>Mathematical and Computational Applications, Vol. 24, No. 3, 2019.
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
<b>Overview</b>
|
|
<ul>
|
|
<li><a href="#part_classes">matrix, vector, cube and field classes</a></li>
|
|
<li><a href="#part_membfns">member functions & variables</a></li>
|
|
<br>
|
|
<li><a href="#part_gen">generated vectors / matrices / cubes</a></li>
|
|
<li><a href="#part_fns">functions of vectors / matrices / cubes</a></li>
|
|
<br>
|
|
<li><a href="#part_decompdense">decompositions, factorisations, inverses and equation solvers (dense matrices)</a></li>
|
|
<li><a href="#part_decompsparse">decompositions, factorisations, and equation solvers (sparse matrices)</a></li>
|
|
<br>
|
|
<li><a href="#part_sigproc">signal & image processing</a></li>
|
|
<li><a href="#part_stats">statistics and clustering</a></li>
|
|
<li><a href="#part_misc">miscellaneous (constants, configuration options, ...)</a></li>
|
|
</ul>
|
|
<br>
|
|
|
|
<a name="part_classes"></a>
|
|
<b>Matrix, Vector, Cube and Field Classes</b>
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><a href="#Mat">Mat<<i>type</i>>, mat, cx_mat</a></td><td> </td><td>dense matrix class</td></tr>
|
|
<tr><td><a href="#Col">Col<<i>type</i>>, colvec, vec</a></td><td> </td><td>dense column vector class</td></tr>
|
|
<tr><td><a href="#Row">Row<<i>type</i>>, rowvec</a></td><td> </td><td>dense row vector class</td></tr>
|
|
<tr><td> </td><td> </td><td> </td></tr>
|
|
<tr><td><a href="#Cube">Cube<<i>type</i>>, cube, cx_cube</a></td><td> </td><td>dense cube class ("3D matrix")</td></tr>
|
|
<tr><td><a href="#field">field<<i>object type</i>></a></td><td> </td><td>class for storing arbitrary objects in matrix-like or cube-like layouts</td></tr>
|
|
<tr><td><a href="#SpMat">SpMat<<i>type</i>>, sp_mat, sp_cx_mat</a></td><td> </td><td>sparse matrix class</td></tr>
|
|
<tr><td> </td><td> </td><td> </td></tr>
|
|
<tr><td><a href="#operators">operators</a></td><td> </td><td><code><big>+</big> <big>−</big> <big>*</big> % / == != <= >= < > && ||</code></td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
<br>
|
|
|
|
<a name="part_membfns"></a>
|
|
<b>Member Functions & Variables</b>
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><a href="#attributes">attributes</a></td><td> </td><td>.n_rows, .n_cols, .n_elem, .n_slices, ...</td></tr>
|
|
<tr><td><a href="#element_access">element access</a></td><td> </td><td>element/object access via (), [] and .at()</td></tr>
|
|
<tr><td><a href="#element_initialisation">element initialisation</a></td><td> </td><td>set elements via initialiser lists</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#zeros_member">.zeros</a></td><td> </td><td>set all elements to zero</td></tr>
|
|
<tr><td><a href="#ones_member">.ones</a></td><td> </td><td>set all elements to one</td></tr>
|
|
<tr><td><a href="#eye_member">.eye</a></td><td> </td><td>set elements along main diagonal to one and off-diagonal elements to zero</td></tr>
|
|
<tr><td><a href="#randu_randn_member">.randu / .randn</a></td><td> </td><td>set all elements to random values</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#fill">.fill</a></td><td> </td><td>set all elements to specified value</td></tr>
|
|
<tr><td><a href="#imbue">.imbue</a></td><td> </td><td>imbue (fill) with values provided by functor or lambda function</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#clean">.clean</a></td><td> </td><td>replace elements below a threshold with zeros</td></tr>
|
|
<tr><td><a href="#replace">.replace</a></td><td> </td><td>replace specific elements with a new value</td></tr>
|
|
<tr><td><a href="#clamp_member">.clamp</a></td><td> </td><td>clamp values to lower and upper limits</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#transform">.transform</a></td><td> </td><td>transform each element via functor or lambda function</td></tr>
|
|
<tr><td><a href="#for_each">.for_each</a></td><td> </td><td>apply a functor or lambda function to each element</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#set_size">.set_size</a></td><td> </td><td>change size without keeping elements (fast)</td></tr>
|
|
<tr><td><a href="#reshape_member">.reshape</a></td><td> </td><td>change size while keeping elements</td></tr>
|
|
<tr><td><a href="#resize_member">.resize</a></td><td> </td><td>change size while keeping elements and preserving layout</td></tr>
|
|
<tr><td><a href="#copy_size">.copy_size</a></td><td> </td><td>change size to be same as given object</td></tr>
|
|
<tr><td><a href="#reset">.reset</a></td><td> </td><td>change size to empty</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#submat">submatrix views</a></td><td> </td><td>read/write access to contiguous and non-contiguous submatrices</td></tr>
|
|
<tr><td><a href="#subcube">subcube views</a></td><td> </td><td>read/write access to contiguous and non-contiguous subcubes</td></tr>
|
|
<tr><td><a href="#subfield">subfield views</a></td><td> </td><td>read/write access to contiguous subfields</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#diag">.diag</a></td><td> </td><td>read/write access to matrix diagonals</td></tr>
|
|
<tr><td><a href="#each_colrow">.each_col / .each_row</a></td><td> </td><td>vector operations applied to each column/row of matrix (aka "broadcasting")</td></tr>
|
|
<tr><td><a href="#each_slice">.each_slice</a></td><td> </td><td>matrix operations applied to each slice of cube (aka "broadcasting")</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#set_imag">.set_imag / .set_real</a></td><td> </td><td>set imaginary/real part</td></tr>
|
|
<tr><td><a href="#insert">.insert_rows / cols / slices</a></td><td> </td><td>insert vector/matrix/cube at specified row/column/slice</td></tr>
|
|
<tr><td><a href="#shed">.shed_rows / cols / slices</a></td><td> </td><td>remove specified rows/columns/slices</td></tr>
|
|
<tr><td><a href="#swap_rows">.swap_rows / cols</a></td><td> </td><td>swap specified rows or columns</td></tr>
|
|
<tr><td><a href="#swap">.swap</a></td><td> </td><td>swap contents with given object</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#memptr">.memptr</a></td><td> </td><td>raw pointer to memory</td></tr>
|
|
<tr><td><a href="#colptr">.colptr</a></td><td> </td><td>raw pointer to memory used by specified column</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#iterators_mat">iterators (matrices)</a></td><td> </td><td>iterators and associated member functions for dense matrices and vectors</td></tr>
|
|
<tr><td><a href="#iterators_cube">iterators (cubes)</a></td><td> </td><td>iterators and associated member functions for cubes</td></tr>
|
|
<tr><td><a href="#iterators_spmat">iterators (sparse matrices)</a></td><td> </td><td>iterators and associated member functions for sparse matrices</td></tr>
|
|
<tr><td><a href="#iterators_submat">iterators (submatrices)</a></td><td> </td><td>iterators and associated member functions for submatrices & subcubes</td></tr>
|
|
<tr><td><a href="#compat_container_fns">compat. container functions</a></td><td> </td><td>compatibility container functions</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#as_col_row">.as_col / .as_row</a></td><td> </td><td>return flattened matrix as column or row vector</td></tr>
|
|
<tr><td><a href="#col_row_as_mat">.col_as_mat / .row_as_mat</a></td><td> </td><td>return matrix representation of cube column or cube row</td></tr>
|
|
<tr><td><a href="#t_st_members">.t / .st </a></td><td> </td><td>return matrix transpose</td></tr>
|
|
<tr><td><a href="#i_member">.i </a></td><td> </td><td>return inverse of square matrix</td></tr>
|
|
<tr><td><a href="#min_and_max_member">.min / .max</a></td><td> </td><td>return extremum value</td></tr>
|
|
<tr><td><a href="#index_min_and_index_max_member">.index_min / .index_max</a></td><td> </td><td>return index of extremum value</td></tr>
|
|
<tr><td><a href="#eval_member">.eval</a></td><td> </td><td>force evaluation of delayed expression</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#in_range">.in_range</a></td><td> </td><td>check whether given location or span is valid</td></tr>
|
|
<tr><td><a href="#is_empty">.is_empty</a></td><td> </td><td>check whether object is empty</td></tr>
|
|
<tr><td><a href="#is_vec">.is_vec</a></td><td> </td><td>check whether matrix is a vector</td></tr>
|
|
<tr><td><a href="#is_sorted">.is_sorted</a></td><td> </td><td>check whether vector or matrix is sorted</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#is_trimat">.is_trimatu / .is_trimatl</a></td><td> </td><td>check whether matrix is upper/lower triangular</td></tr>
|
|
<tr><td><a href="#is_diagmat">.is_diagmat</a></td><td> </td><td>check whether matrix is diagonal</td></tr>
|
|
<tr><td><a href="#is_square">.is_square</a></td><td> </td><td>check whether matrix is square sized</td></tr>
|
|
<tr><td><a href="#is_symmetric">.is_symmetric</a></td><td> </td><td>check whether matrix is symmetric</td></tr>
|
|
<tr><td><a href="#is_hermitian">.is_hermitian</a></td><td> </td><td>check whether matrix is hermitian</td></tr>
|
|
<tr><td><a href="#is_sympd">.is_sympd</a></td><td> </td><td>check whether matrix is symmetric/hermitian positive definite</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#is_zero">.is_zero</a></td><td> </td><td>check whether all elements are zero</td></tr>
|
|
<tr><td><a href="#is_finite">.is_finite</a></td><td> </td><td>check whether all elements are finite</td></tr>
|
|
<tr><td><a href="#has_inf">.has_inf</a></td><td> </td><td>check whether any element is ±infinity</td></tr>
|
|
<tr><td><a href="#has_nan">.has_nan</a></td><td> </td><td>check whether any element is NaN</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#print">.print</a></td><td> </td><td>print object to <i>std::cout</i> or user specified stream</td></tr>
|
|
<tr><td><a href="#raw_print">.raw_print</a></td><td> </td><td>print object without formatting</td></tr>
|
|
<tr><td><a href="#brief_print">.brief_print</a></td><td> </td><td>print object in shortened/abridged form</td></tr>
|
|
<tr><td><small><small> </small></small></td><td><small><small> </small></small></td><td><small><small> </small></small></td></tr>
|
|
<tr><td><a href="#save_load_mat">.save/.load (matrices & cubes)</a></td><td> </td><td>save/load matrices and cubes in files or streams</td></tr>
|
|
<tr><td><a href="#save_load_field">.save/.load (fields)</a></td><td> </td><td>save/load fields in files or streams</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
<br>
|
|
|
|
<a name="part_gen"></a>
|
|
<b>Generated Vectors / Matrices / Cubes</b>
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#linspace">linspace</a></td><td> </td><td>generate vector with linearly spaced elements</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#logspace">logspace</a></td><td> </td><td>generate vector with logarithmically spaced elements</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#regspace">regspace</a></td><td> </td><td>generate vector with regularly spaced elements</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#randperm">randperm</a></td><td> </td><td>generate vector with random permutation of a sequence of integers</td></tr>
|
|
<tr><td><a href="#eye_standalone">eye</a></td><td> </td><td>generate identity matrix</td></tr>
|
|
<tr><td><a href="#ones_standalone">ones</a></td><td> </td><td>generate object filled with ones</td></tr>
|
|
<tr><td><a href="#zeros_standalone">zeros</a></td><td> </td><td>generate object filled with zeros</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#randu">randu</a></td><td> </td><td>generate object with random values (uniform distribution)</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#randn">randn</a></td><td> </td><td>generate object with random values (normal distribution)</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#randg">randg</a></td><td> </td><td>generate object with random values (gamma distribution)</td></tr>
|
|
<tr><td><a href="#randi">randi</a></td><td> </td><td>generate object with random integer values in specified interval</td></tr>
|
|
<tr><td><a href="#speye">speye</a></td><td> </td><td>generate sparse identity matrix</td></tr>
|
|
<tr><td><a href="#spones">spones</a></td><td> </td><td>generate sparse matrix with non-zero elements set to one</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#sprandu_sprandn">sprandu / sprandn</a></td><td> </td><td>generate sparse matrix with non-zero elements set to random values</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#toeplitz">toeplitz</a></td><td> </td><td>generate Toeplitz matrix</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
<br>
|
|
|
|
<a name="part_fns"></a>
|
|
<b>Functions of Vectors / Matrices / Cubes</b>
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#abs">abs</a></td><td> </td><td>obtain magnitude of each element</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#accu">accu</a></td><td> </td><td>accumulate (sum) all elements</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#affmul">affmul</a></td><td> </td><td>affine matrix multiplication</td></tr>
|
|
<tr><td><a href="#all">all</a></td><td> </td><td>check whether all elements are non-zero, or satisfy a relational condition</td></tr>
|
|
<tr><td><a href="#any">any</a></td><td> </td><td>check whether any element is non-zero, or satisfies a relational condition</td></tr>
|
|
<tr><td><a href="#approx_equal">approx_equal</a></td><td> </td><td>approximate equality</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#arg">arg</a></td><td> </td><td>phase angle of each element</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#as_scalar">as_scalar</a></td><td> </td><td>convert 1x1 matrix to pure scalar</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#clamp">clamp</a></td><td> </td><td>obtain clamped elements according to given limits</td></tr>
|
|
<tr><td><a href="#cond">cond</a></td><td> </td><td>condition number of matrix</td></tr>
|
|
<tr><td><a href="#conj">conj</a></td><td> </td><td>obtain complex conjugate of each element</td></tr>
|
|
<tr><td><a href="#conv_to">conv_to</a></td><td> </td><td>convert/cast between matrix types</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#cross">cross</a></td><td> </td><td>cross product</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#cumsum">cumsum</a></td><td> </td><td>cumulative sum</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#cumprod">cumprod</a></td><td> </td><td>cumulative product</td></tr>
|
|
<tr><td><a href="#det">det</a></td><td> </td><td>determinant</td></tr>
|
|
<tr><td><a href="#diagmat">diagmat</a></td><td> </td><td>generate diagonal matrix from given matrix or vector</td></tr>
|
|
<tr><td><a href="#diagvec">diagvec</a></td><td> </td><td>extract specified diagonal</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#diags_spdiags">diags / spdiags</a></td><td> </td><td>generate band matrix from given set of vectors</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#diff">diff</a></td><td> </td><td>differences between adjacent elements</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#dot">dot / cdot / norm_dot</a></td><td> </td><td>dot product</td></tr>
|
|
<tr><td><a href="#eps">eps</a></td><td> </td><td>obtain distance of each element to next largest floating point representation</td></tr>
|
|
<tr><td><a href="#expmat">expmat</a></td><td> </td><td>matrix exponential</td></tr>
|
|
<tr><td><a href="#expmat_sym">expmat_sym</a></td><td> </td><td>matrix exponential of symmetric matrix</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#find">find</a></td><td> </td><td>find indices of non-zero elements, or elements satisfying a relational condition</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#find_finite">find_finite</a></td><td> </td><td>find indices of finite elements</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#find_nonfinite">find_nonfinite</a></td><td> </td><td>find indices of non-finite elements</td></tr>
|
|
<tr><td><a href="#find_nan">find_nan</a></td><td> </td><td>find indices of NaN elements</td></tr>
|
|
<tr><td><a href="#find_unique">find_unique</a></td><td> </td><td>find indices of unique elements</td></tr>
|
|
<tr><td><a href="#flip">fliplr / flipud</a></td><td> </td><td>flip matrix left to right or upside down</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#imag_real">imag / real</a></td><td> </td><td>extract imaginary/real part</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#ind2sub">ind2sub</a></td><td> </td><td>convert linear index to subscripts</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#index_min_and_index_max_standalone">index_min / index_max</a></td><td> </td><td>indices of extremum values</td></tr>
|
|
<tr><td><a href="#inplace_trans">inplace_trans</a></td><td> </td><td>in-place transpose</td></tr>
|
|
<tr><td><a href="#intersect">intersect</a></td><td> </td><td>find common elements in two vectors/matrices</td></tr>
|
|
<tr><td><a href="#join">join_rows / join_cols</a></td><td> </td><td>concatenation of matrices</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#join_slices">join_slices</a></td><td> </td><td>concatenation of cubes</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#kron">kron</a></td><td> </td><td>Kronecker tensor product</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#log_det">log_det</a></td><td> </td><td>log determinant</td></tr>
|
|
<tr><td><a href="#log_det_sympd">log_det_sympd</a></td><td> </td><td>log determinant of symmetric positive definite matrix</td></tr>
|
|
<tr><td><a href="#logmat">logmat</a></td><td> </td><td>matrix logarithm</td></tr>
|
|
<tr><td><a href="#logmat_sympd">logmat_sympd</a></td><td> </td><td>matrix logarithm of symmetric matrix</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#min_and_max">min / max</a></td><td> </td><td>return extremum values</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#nonzeros">nonzeros</a></td><td> </td><td>return non-zero values</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#norm">norm</a></td><td> </td><td>various norms of vectors and matrices</td></tr>
|
|
<tr><td><a href="#norm2est">norm2est</a></td><td> </td><td>fast estimate of the matrix 2-norm</td></tr>
|
|
<tr><td><a href="#normalise">normalise</a></td><td> </td><td>normalise vectors to unit <i>p</i>-norm</td></tr>
|
|
<tr><td><a href="#pow">pow</a></td><td> </td><td>element-wise power</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#powmat">powmat</a></td><td> </td><td>matrix power</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#prod">prod</a></td><td> </td><td>product of elements</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#rank">rank</a></td><td> </td><td>rank of matrix</td></tr>
|
|
<tr><td><a href="#rcond">rcond</a></td><td> </td><td>reciprocal condition number</td></tr>
|
|
<tr><td><a href="#repelem">repelem</a></td><td> </td><td>replicate elements</td></tr>
|
|
<tr><td><a href="#repmat">repmat</a></td><td> </td><td>replicate matrix in block-like fashion</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#reshape">reshape</a></td><td> </td><td>change size while keeping elements</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#resize">resize</a></td><td> </td><td>change size while keeping elements and preserving layout</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#reverse">reverse</a></td><td> </td><td>reverse order of elements</td></tr>
|
|
<tr><td><a href="#roots">roots</a></td><td> </td><td>roots of polynomial</td></tr>
|
|
<tr><td><a href="#shift">shift</a></td><td> </td><td>shift elements</td></tr>
|
|
<tr><td><a href="#shuffle">shuffle</a></td><td> </td><td>randomly shuffle elements</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#size">size</a></td><td> </td><td>obtain dimensions of given object</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#sort">sort</a></td><td> </td><td>sort elements</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#sort_index">sort_index</a></td><td> </td><td>vector describing sorted order of elements</td></tr>
|
|
<tr><td><a href="#sqrtmat">sqrtmat</a></td><td> </td><td>square root of matrix</td></tr>
|
|
<tr><td><a href="#sqrtmat_sympd">sqrtmat_sympd</a></td><td> </td><td>square root of symmetric matrix</td></tr>
|
|
<tr><td><a href="#sum">sum</a></td><td> </td><td>sum of elements</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#sub2ind">sub2ind</a></td><td> </td><td>convert subscripts to linear index</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#symmat">symmatu / symmatl</a></td><td> </td><td>generate symmetric matrix from given matrix</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#trace">trace</a></td><td> </td><td>sum of diagonal elements</td></tr>
|
|
<tr><td><a href="#trans">trans</a></td><td> </td><td>transpose of matrix</td></tr>
|
|
<tr><td><a href="#trapz">trapz</a></td><td> </td><td>trapezoidal numerical integration</td></tr>
|
|
<tr><td><a href="#trimat">trimatu / trimatl</a></td><td> </td><td>copy upper/lower triangular part</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#trimat_ind">trimatu_ind / trimatl_ind</a></td><td> </td><td>obtain indices of upper/lower triangular part</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#unique">unique</a></td><td> </td><td>return unique elements</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#vecnorm">vecnorm</a></td><td> </td><td>obtain vector norm of each row or column of a matrix</td></tr>
|
|
<tr><td><a href="#vectorise">vectorise</a></td><td> </td><td>flatten matrix into vector</td></tr>
|
|
<tr><td><a href="#misc_fns">misc functions</a></td><td> </td><td>miscellaneous element-wise functions: exp, log, sqrt, round, sign, ...</td></tr>
|
|
<tr><td><a href="#trig_fns">trig functions</a></td><td> </td><td>trigonometric element-wise functions: cos, sin, tan, ...</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
<br>
|
|
|
|
<a name="part_decompdense"></a>
|
|
<b>Decompositions, Factorisations, Inverses and Equation Solvers (Dense Matrices)</b>
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#chol">chol</a></td><td> </td><td>Cholesky decomposition</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#eig_sym">eig_sym</a></td><td> </td><td>eigen decomposition of dense symmetric/hermitian matrix</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#eig_gen">eig_gen</a></td><td> </td><td>eigen decomposition of dense general square matrix</td></tr>
|
|
<tr><td><a href="#eig_pair">eig_pair</a></td><td> </td><td>eigen decomposition for pair of general dense square matrices</td></tr>
|
|
<tr><td><a href="#hess">hess</a></td><td> </td><td>upper Hessenberg decomposition</td></tr>
|
|
<tr><td><a href="#inv">inv</a></td><td> </td><td>inverse of general square matrix</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#inv_sympd">inv_sympd</a></td><td> </td><td>inverse of symmetric positive definite matrix</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#lu">lu </a></td><td> </td><td>lower-upper decomposition</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#null">null</a></td><td> </td><td>orthonormal basis of null space</td></tr>
|
|
<tr><td><a href="#orth">orth</a></td><td> </td><td>orthonormal basis of range space</td></tr>
|
|
<tr><td><a href="#pinv">pinv</a></td><td> </td><td>pseudo-inverse / generalised inverse</td></tr>
|
|
<tr><td><a href="#qr">qr </a></td><td> </td><td>QR decomposition</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#qr_econ">qr_econ</a></td><td> </td><td>economical QR decomposition</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#qz">qz </a></td><td> </td><td>generalised Schur decomposition</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#schur">schur</a></td><td> </td><td>Schur decomposition</td></tr>
|
|
<tr><td><a href="#solve">solve</a></td><td> </td><td>solve systems of linear equations</td></tr>
|
|
<tr><td><a href="#svd">svd</a></td><td> </td><td>singular value decomposition</td></tr>
|
|
<tr><td><a href="#svd_econ">svd_econ</a></td><td> </td><td>economical singular value decomposition</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#syl">syl</a></td><td> </td><td>Sylvester equation solver</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
<br>
|
|
|
|
<a name="part_decompsparse"></a>
|
|
<b>Decompositions, Factorisations and Equation Solvers (Sparse Matrices)</b>
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#eigs_sym">eigs_sym</a></td><td> </td><td>limited number of eigenvalues & eigenvectors of sparse symmetric real matrix</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#eigs_gen">eigs_gen</a></td><td> </td><td>limited number of eigenvalues & eigenvectors of sparse general square matrix</td></tr>
|
|
<tr><td><a href="#svds">svds</a></td><td> </td><td>truncated svd: limited number of singular values & singular vectors of sparse matrix</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#spsolve">spsolve</a></td><td> </td><td>solve sparse systems of linear equations</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#spsolve_factoriser">spsolve_factoriser</a></td><td> </td><td>factoriser for solving sparse systems of linear equations</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
<br>
|
|
|
|
<a name="part_sigproc"></a>
|
|
<b>Signal & Image Processing</b>
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#conv">conv</a></td><td> </td><td>1D convolution</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#conv2">conv2</a></td><td> </td><td>2D convolution</td></tr>
|
|
<tr><td><a href="#fft">fft / ifft</a></td><td> </td><td>1D fast Fourier transform and its inverse</td></tr>
|
|
<tr><td><a href="#fft2">fft2 / ifft2</a></td><td> </td><td>2D fast Fourier transform and its inverse</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#interp1">interp1</a></td><td> </td><td>1D interpolation</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#interp2">interp2</a></td><td> </td><td>2D interpolation</td></tr>
|
|
<tr><td><a href="#polyfit">polyfit</a></td><td> </td><td>find polynomial coefficients for data fitting</td></tr>
|
|
<tr><td><a href="#polyval">polyval</a></td><td> </td><td>evaluate polynomial</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
<br>
|
|
|
|
<a name="part_stats"></a>
|
|
<b>Statistics & Clustering</b>
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#stats_fns">stats functions</a></td><td> </td><td>mean, median, standard deviation, variance</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#cov">cov</a></td><td> </td><td>covariance</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#cor">cor</a></td><td> </td><td>correlation</td></tr>
|
|
<tr><td><a href="#hist">hist</a></td><td> </td><td>histogram of counts</td></tr>
|
|
<tr><td><a href="#histc">histc</a></td><td> </td><td>histogram of counts with user specified edges</td></tr>
|
|
<tr><td><a href="#quantile">quantile</a></td><td> </td><td>quantiles of a dataset</td></tr>
|
|
<tr><td><a href="#princomp">princomp</a></td><td> </td><td>principal component analysis (PCA)</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#normpdf">normpdf</a></td><td> </td><td>probability density function of normal distribution</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#log_normpdf">log_normpdf</a></td><td> </td><td>logarithm version of probability density function of normal distribution</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#normcdf">normcdf</a></td><td> </td><td>cumulative distribution function of normal distribution</td></tr>
|
|
<tr><td><a href="#mvnrnd">mvnrnd</a></td><td> </td><td>random vectors from multivariate normal distribution</td></tr>
|
|
<tr><td><a href="#chi2rnd">chi2rnd</a></td><td> </td><td>random numbers from chi-squared distribution</td></tr>
|
|
<tr><td><a href="#wishrnd">wishrnd</a></td><td> </td><td>random matrix from Wishart distribution</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#iwishrnd">iwishrnd</a></td><td> </td><td>random matrix from inverse Wishart distribution</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#running_stat">running_stat</a></td><td> </td><td>running statistics of scalars (one dimensional process/signal)</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#running_stat_vec">running_stat_vec</a></td><td> </td><td>running statistics of vectors (multi-dimensional process/signal)</td></tr>
|
|
<tr><td><a href="#kmeans">kmeans</a></td><td> </td><td>cluster data into disjoint sets</td></tr>
|
|
<tr><td><a href="#gmm_diag">gmm_diag/gmm_full</a></td><td> </td><td>probabilistic clustering and likelihood calculation via Gaussian mixture models</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
<br>
|
|
|
|
<a name="part_misc"></a>
|
|
<b>Miscellaneous</b>
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#constants">constants</a></td><td> </td><td>pi, inf, NaN, eps, speed of light, ...</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#wall_clock">wall_clock</a></td><td> </td><td>timer for measuring number of elapsed seconds</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#rng_seed">RNG seed setting</a></td><td> </td><td>functions for changing RNG seeds</td></tr>
|
|
<tr><td><a href="#output_streams">output streams</a></td><td> </td><td>streams for printing warnings and errors</td></tr>
|
|
<tr><td><a href="#uword">uword / sword</a></td><td> </td><td>shorthand for unsigned and signed integers</td></tr>
|
|
<tr><td><a href="#cx_double">cx_double / cx_float</a></td><td> </td><td>shorthand for std::complex<double> and std::complex<float></td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#syntax">Matlab/Armadillo syntax differences</a></td><td> </td><td>examples of Matlab syntax and conceptually corresponding Armadillo syntax</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#example_prog">example program</a></td><td> </td><td>short example program</td></tr>
|
|
<tr style="background-color: #F5F5F5;"><td><a href="#config_hpp">config.hpp</a></td><td> </td><td>configuration options</td></tr>
|
|
<tr><td><a href="#changelog">API additions</a></td><td> </td><td>API stability and list of API additions</td></tr>
|
|
<!--<tr><td><a href="#log_add">log_add</a></td><td> </td><td>TODO</td></tr>-->
|
|
<!--<tr><td><a href="#catching_exceptions">catching exceptions</a></td><td> </td><td>TODO</td></tr>-->
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
<br>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div>
|
|
<hr class="greyline">
|
|
<hr class="greyline">
|
|
<br>
|
|
<br>
|
|
<font size=+1><b>Matrix, Vector, Cube and Field Classes</b></font>
|
|
<br>
|
|
<br>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="Mat"></a><b>Mat<</b><i>type</i><b>></b>
|
|
<br><b>mat</b>
|
|
<br><b>cx_mat</b>
|
|
<ul>
|
|
<li>
|
|
Classes for dense matrices, with elements stored in <a href="https://en.wikipedia.org/wiki/Column_major">column-major ordering</a> (ie. column by column)
|
|
</li>
|
|
<br>
|
|
<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>short</i>, <i>int</i>, <i>long</i>, and unsigned versions of <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; text-align: right;">
|
|
<code>mat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Mat<double></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>dmat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Mat<double></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>fmat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Mat<float></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_mat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Mat<<a href="#cx_double">cx_double</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_dmat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Mat<<a href="#cx_double">cx_double</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_fmat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Mat<<a href="#cx_double">cx_float</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>umat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Mat<<a href="#uword">uword</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>imat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Mat<<a href="#uword">sword</a>></code>
|
|
</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 matrix types instead, eg. <i>fmat</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Matrix types with integer elements (such as <i>umat</i> and <i>imat</i>) cannot hold special values such as NaN and Inf
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Functions which use LAPACK (generally matrix decompositions) are only valid for the following matrix types:
|
|
<i>mat</i>, <i>dmat</i>, <i>fmat</i>, <i>cx_mat</i>, <i>cx_dmat</i>, <i>cx_fmat</i>
|
|
</li>
|
|
<br>
|
|
<a name="constructors_mat"></a>
|
|
<li>
|
|
Constructors:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>mat()</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>mat(<i>n_rows</i>, <i>n_cols</i>)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>mat(<i>n_rows</i>, <i>n_cols</i>, <i>fill_form</i>)</code></td><td> </td><td>(elements are initialised according to <i>fill_form</i>)</td></tr>
|
|
<tr><td><code>mat(size(<i>X</i>))</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>mat(size(<i>X</i>), <i>fill_form</i>)</code></td><td> </td><td>(elements are initialised according to <i>fill_form</i>)</td></tr>
|
|
<tr><td><code>mat(mat)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>mat(vec)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>mat(rowvec)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>mat(initializer_list)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>mat(string)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>mat(std::vector)</code></td><td> </td><td>(treated as a column vector)</td></tr>
|
|
<tr><td><code>mat(sp_mat)</code></td><td> </td><td>(for converting a sparse matrix to a dense matrix)</td></tr>
|
|
<tr><td><code>cx_mat(mat,mat)</code></td><td> </td><td>(for constructing a complex matrix out of two real matrices)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The elements can be explicitly initialised during construction by specifying <i>fill_form</i>,
|
|
which is one of:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>fill::zeros</code></td><td> ↦ </td><td>set all elements to 0</td></tr>
|
|
<tr><td><code>fill::ones</code></td><td> ↦ </td><td>set all elements to 1</td></tr>
|
|
<tr><td><code>fill::eye</code></td><td> ↦ </td><td>set the elements on the main diagonal to 1 and off-diagonal elements to 0</td></tr>
|
|
<tr><td><code>fill::randu</code></td><td> ↦ </td><td>set all elements to random values from a uniform distribution in the [0,1] interval</td></tr>
|
|
<tr><td><code>fill::randn</code></td><td> ↦ </td><td>set all elements to random values from a normal/Gaussian distribution with zero mean and unit variance</td></tr>
|
|
<tr><td><code>fill::value(scalar)</code></td><td> ↦ </td><td>set all elements to specified scalar</td></tr>
|
|
<tr><td><code>fill::none</code></td><td> ↦ </td><td>do not initialise the elements</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b>
|
|
<ul>
|
|
<li>since Armadillo 10.5, the elements are initialised to zero by default</li>
|
|
<li>
|
|
in Armadillo 10.4 and older versions, the elements are not initialised unless <i>fill_form</i> is specified;
|
|
ie. without specifying <i>fill_form</i>, the elements may contain garbage values, including NaN
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For the <i>mat(string)</i> constructor, the format is elements separated by spaces, and rows denoted by semicolons;
|
|
for example, the 2x2 identity matrix can be created using <code>"1 0; 0 1"</code>;
|
|
note that string based initialisation is slower than directly <a href="#element_access">setting the elements</a> or using <a href="#element_initialisation">element initialisation</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Each instance of <i>mat</i> automatically allocates and releases internal memory.
|
|
All internally allocated memory used by an instance of <i>mat</i> is automatically released as soon as the instance goes out of scope.
|
|
For example, if an instance of <i>mat</i> is declared inside a function, it will be automatically destroyed at the end of the function.
|
|
To forcefully release memory at any point, use <a href="#reset">.reset()</a>; note that in normal use this is not required.
|
|
</li>
|
|
<br>
|
|
<a name="adv_constructors_mat"></a>
|
|
<li>
|
|
Advanced constructors:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<code>mat(ptr_aux_mem, n_rows, n_cols, copy_aux_mem = true, strict = false)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a matrix using data from writable auxiliary (external) memory, where <i>ptr_aux_mem</i> is a pointer to the 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 are doing!
|
|
<br>
|
|
<br>
|
|
The <i>strict</i> parameter comes into effect only when <i>copy_aux_mem</i> is set to <i>false</i>
|
|
(ie. the matrix is directly using auxiliary memory)
|
|
<ul>
|
|
<li>
|
|
when <i>strict</i> is set to <i>false</i>, the matrix will use the auxiliary memory until a size change or an aliasing event
|
|
</li>
|
|
<li>
|
|
when <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
|
|
</li>
|
|
</ul>
|
|
</ul>
|
|
<br>
|
|
<code>mat(const ptr_aux_mem, n_rows, n_cols)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a matrix by copying data from read-only auxiliary memory,
|
|
where <i>ptr_aux_mem</i> is a pointer to the memory
|
|
</ul>
|
|
<a name="adv_constructors_mat_fixed"></a>
|
|
<br>
|
|
<code>mat::fixed<n_rows, n_cols></code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a fixed size matrix, with the size specified via template arguments.
|
|
Memory for the matrix is reserved 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 appending a two digit form of the size to the matrix type;
|
|
examples: <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>
|
|
<br>
|
|
<code>mat::fixed<n_rows, n_cols>(<i>fill_form</i>)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a fixed size matrix, with the elements explicitly initialised according to <i>fill_form</i>
|
|
</ul>
|
|
<br>
|
|
<code>mat::fixed<n_rows, n_cols>(const ptr_aux_mem)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a fixed size matrix, with the size specified via template arguments;
|
|
data is copied from auxiliary memory, where <i>ptr_aux_mem</i> is a pointer to the memory
|
|
</ul>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
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);
|
|
|
|
B.print("B:");
|
|
|
|
mat::fixed<5,6> F;
|
|
|
|
double aux_mem[24];
|
|
mat H(&aux_mem[0], 4, 6, false); // use auxiliary memory
|
|
</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,fill::value(123.0)); // Armadillo 10.6 and newer
|
|
</pre>
|
|
</ul>
|
|
or
|
|
<ul>
|
|
<pre>
|
|
mat A(5,5,fill::none); A.fill(123.0); // Armadillo 10.5 and older
|
|
</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">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="#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 with compressed sparse column format)</li>
|
|
<li><a href="#config_hpp">config.hpp</a></li>
|
|
<li><a href="https://cplusplus.com/doc/tutorial/other_data_types/">explanation of <i>typedef</i></a> (cplusplus.com)
|
|
<li><a href="https://en.wikipedia.org/wiki/C_data_types">C data types</a> (Wikipedia)
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="Col"></a><b>Col<</b><i>type</i><b>></b>
|
|
<br><b>vec</b>
|
|
<br><b>cx_vec</b>
|
|
<ul>
|
|
<li>
|
|
Classes for column vectors (dense 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; text-align: right;">
|
|
<code>vec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>colvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Col<double></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>dvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>dcolvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Col<double></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>fvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>fcolvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Col<float></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_vec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_colvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Col<<a href="#cx_double">cx_double</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_dvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_dcolvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Col<<a href="#cx_double">cx_double</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_fvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_fcolvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Col<<a href="#cx_double">cx_float</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>uvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>ucolvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Col<<a href="#uword">uword</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>ivec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>icolvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Col<<a href="#uword">sword</a>></code>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
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 column vector 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>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>vec()</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>vec(<i>n_elem</i>)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>vec(<i>n_elem</i>, <i>fill_form</i>)</code></td><td> </td><td>(elements are initialised according to <i>fill_form</i>)</td></tr>
|
|
<tr><td><code>vec(size(<i>X</i>))</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>vec(size(<i>X</i>), <i>fill_form</i>)</code></td><td> </td><td>(elements are initialised according to <i>fill_form</i>)</td></tr>
|
|
<tr><td><code>vec(vec)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>vec(mat)</code></td><td> </td><td>(<i>std::logic_error</i> exception is thrown if the given matrix has more than one column)</td></tr>
|
|
<tr><td><code>vec(initializer_list)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>vec(string)</code></td><td> </td><td>(elements separated by spaces)</td></tr>
|
|
<tr><td><code>vec(std::vector)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>cx_vec(vec,vec)</code></td><td> </td><td>(for constructing a complex vector out of two real vectors)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b>
|
|
<ul>
|
|
<li>since Armadillo 10.5, the elements are initialised to zero by default</li>
|
|
<li>
|
|
in Armadillo 10.4 and older versions, the elements are not initialised unless <i>fill_form</i> is specified;
|
|
ie. without specifying <i>fill_form</i>, the elements may contain garbage values, including NaN; see the <a href="#Mat">Mat class</a> for details on <i>fill_form</i>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="adv_constructors_col"></a>
|
|
<li>
|
|
Advanced constructors:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<code>vec(ptr_aux_mem, number_of_elements, copy_aux_mem = true, strict = false)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a column vector using data from writable auxiliary (external) memory, where <i>ptr_aux_mem</i> is a pointer to the 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 are doing!
|
|
<br>
|
|
<br>
|
|
The <i>strict</i> parameter comes into effect only when <i>copy_aux_mem</i> is set to <i>false</i>
|
|
(ie. the vector is directly using auxiliary memory)
|
|
<ul>
|
|
<li>
|
|
when <i>strict</i> is set to <i>false</i>, the vector will use the auxiliary memory until a size change or an aliasing event
|
|
</li>
|
|
<li>
|
|
when <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
|
|
</li>
|
|
</ul>
|
|
</ul>
|
|
<br>
|
|
<code>vec(const ptr_aux_mem, number_of_elements)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a column vector by copying data from read-only auxiliary memory,
|
|
where <i>ptr_aux_mem</i> is a pointer to the memory
|
|
</ul>
|
|
<a name="adv_constructors_col_fixed"></a>
|
|
<br>
|
|
<code>vec::fixed<number_of_elements></code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a fixed size column vector, with the size specified via the template argument.
|
|
Memory for the vector is reserved 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 appending a single digit form of the size to the vector type;
|
|
examples: <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>
|
|
<br>
|
|
<code>vec::fixed<number_of_elements>(<i>fill_form</i>)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a fixed size column vector, with the elements explicitly initialised according to <i>fill_form</i>
|
|
</ul>
|
|
<br>
|
|
<code>vec::fixed<number_of_elements>(const ptr_aux_mem)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a fixed size column vector, with the size specified via the template argument;
|
|
data is copied from auxiliary memory, where <i>ptr_aux_mem</i> is a pointer to the memory
|
|
</ul>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec x(10);
|
|
vec y(10, fill::ones);
|
|
|
|
mat A(10, 10, fill::randu);
|
|
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 v(5); v = 123.0;
|
|
</pre>
|
|
</ul>
|
|
Use the following code instead:
|
|
<ul>
|
|
<pre>
|
|
vec v(5, fill::value(123.0)); // Armadillo 10.6 and newer
|
|
</pre>
|
|
</ul>
|
|
or
|
|
<ul>
|
|
<pre>
|
|
vec v(5, fill::none); v.fill(123.0); // Armadillo 10.5 and older
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
-->
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#element_initialisation">element initialisation</a></li>
|
|
<li><a href="#Mat">Mat class</a></li>
|
|
<li><a href="#Row">Row class</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="Row"></a>
|
|
<b>Row<</b><i>type</i><b>></b>
|
|
<br><b>rowvec</b>
|
|
<br><b>cx_rowvec</b>
|
|
<ul>
|
|
<li>
|
|
Classes for row vectors (dense 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; text-align: right;">
|
|
<code>rowvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Row<double></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>drowvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Row<double></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>frowvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Row<float></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_rowvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Row<<a href="#cx_double">cx_double</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_drowvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Row<<a href="#cx_double">cx_double</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_frowvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Row<<a href="#cx_double">cx_float</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>urowvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Row<<a href="#uword">uword</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>irowvec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Row<<a href="#uword">sword</a>></code>
|
|
</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 row vector 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>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>rowvec()</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>rowvec(<i>n_elem</i>)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>rowvec(<i>n_elem</i>, <i>fill_form</i>)</code></td><td> </td><td>(elements are initialised according to <i>fill_form</i>)</td></tr>
|
|
<tr><td><code>rowvec(size(<i>X</i>))</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>rowvec(size(<i>X</i>), <i>fill_form</i>)</code></td><td> </td><td>(elements are initialised according to <i>fill_form</i>)</td></tr>
|
|
<tr><td><code>rowvec(rowvec)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>rowvec(mat)</code></td><td> </td><td>(<i>std::logic_error</i> exception is thrown if the given matrix has more than one row)</td></tr>
|
|
<tr><td><code>rowvec(initializer_list)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>rowvec(string)</code></td><td> </td><td>(elements separated by spaces)</td></tr>
|
|
<tr><td><code>rowvec(std::vector)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>cx_rowvec(rowvec,rowvec)</code></td><td> </td><td>(for constructing a complex row vector out of two real row vectors)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b>
|
|
<ul>
|
|
<li>since Armadillo 10.5, the elements are initialised to zero by default</li>
|
|
<li>
|
|
in Armadillo 10.4 and older versions, the elements are not initialised unless <i>fill_form</i> is specified;
|
|
ie. without specifying <i>fill_form</i>, the elements may contain garbage values, including NaN; see the <a href="#Mat">Mat class</a> for details on <i>fill_form</i>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="adv_constructors_row"></a>
|
|
<li>
|
|
Advanced constructors:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<code>rowvec(ptr_aux_mem, number_of_elements, copy_aux_mem = true, strict = false)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a row vector using data from writable auxiliary (external) memory, where <i>ptr_aux_mem</i> is a pointer to the 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 are doing!
|
|
<br>
|
|
<br>
|
|
The <i>strict</i> parameter comes into effect only when <i>copy_aux_mem</i> is set to <i>false</i>
|
|
(ie. the vector is directly using auxiliary memory)
|
|
<ul>
|
|
<li>
|
|
when <i>strict</i> is set to <i>false</i>, the vector will use the auxiliary memory until a size change or an aliasing event
|
|
</li>
|
|
<li>
|
|
when <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
|
|
</li>
|
|
</ul>
|
|
</ul>
|
|
<br>
|
|
<code>rowvec(const ptr_aux_mem, number_of_elements)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a row vector by copying data from read-only auxiliary memory,
|
|
where <i>ptr_aux_mem</i> is a pointer to the memory
|
|
</ul>
|
|
<br>
|
|
<code>rowvec::fixed<number_of_elements></code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a fixed size row vector, with the size specified via the template argument.
|
|
Memory for the vector is reserved 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 appending a single digit form of the size to the vector type;
|
|
examples: <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>
|
|
<br>
|
|
<code>rowvec::fixed<number_of_elements>(<i>fill_form</i>)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a fixed size row vector, with the elements explicitly initialised according to <i>fill_form</i>
|
|
</ul>
|
|
<br>
|
|
<code>rowvec::fixed<number_of_elements>(const ptr_aux_mem)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a fixed size row vector, with the size specified via the template argument;
|
|
data is copied from auxiliary memory, where <i>ptr_aux_mem</i> is a pointer to the memory
|
|
</ul>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
rowvec x(10);
|
|
rowvec y(10, fill::ones);
|
|
|
|
mat A(10, 10, fill::randu);
|
|
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, fill::value(123.0)); // Armadillo 10.6 and newer
|
|
</pre>
|
|
</ul>
|
|
or
|
|
<ul>
|
|
<pre>
|
|
rowvec r(5, fill::none); r.fill(123.0); // Armadillo 10.5 and older
|
|
</pre>
|
|
</ul>
|
|
<br>
|
|
-->
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#element_initialisation">element initialisation</a></li>
|
|
<li><a href="#Mat">Mat class</a></li>
|
|
<li><a href="#Col">Col class</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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 (quasi 3rd order tensors), also known as "3D matrices"
|
|
</li>
|
|
<br>
|
|
<li>
|
|
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>
|
|
The root 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>short</i>, <i>int</i>, <i>long</i> and unsigned versions of <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; text-align: right;">
|
|
<code>cube</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Cube<double></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>dcube</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Cube<double></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>fcube</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Cube<float></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_cube</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Cube<<a href="#cx_double">cx_double</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_dcube</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Cube<<a href="#cx_double">cx_double</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cx_fcube</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Cube<<a href="#cx_double">cx_float</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>ucube</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Cube<<a href="#uword">uword</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>icube</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Cube<<a href="#uword">sword</a>></code>
|
|
</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>
|
|
<a name="constructors_cube"></a>
|
|
<li>
|
|
Constructors:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<code>cube()</code>
|
|
<tr><td><code>cube(<i>n_rows</i>, <i>n_cols</i>, <i>n_slices</i>)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>cube(<i>n_rows</i>, <i>n_cols</i>, <i>n_slices</i>, <i>fill_form</i>)</code></td><td> </td><td>(elements are initialised according to <i>fill_form</i>)</td></tr>
|
|
<tr><td><code>cube(size(<i>X</i>))</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>cube(size(<i>X</i>), <i>fill_form</i>)</code></td><td> </td><td>(elements are initialised according to <i>fill_form</i>)</td></tr>
|
|
<tr><td><code>cube(cube)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>cx_cube(cube, cube)</code></td><td> </td><td>(for constructing a complex cube out of two real cubes)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The elements can be explicitly initialised during construction by specifying <i>fill_form</i>,
|
|
which is one of:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>fill::zeros</code></td><td> ↦ </td><td>set all elements to 0</td></tr>
|
|
<tr><td><code>fill::ones</code></td><td> ↦ </td><td>set all elements to 1</td></tr>
|
|
<tr><td><code>fill::randu</code></td><td> ↦ </td><td>set all elements to random values from a uniform distribution in the [0,1] interval</td></tr>
|
|
<tr><td><code>fill::randn</code></td><td> ↦ </td><td>set all elements to random values from a normal/Gaussian distribution with zero mean and unit variance</td></tr>
|
|
<tr><td><code>fill::value(scalar)</code></td><td> ↦ </td><td>set all elements to specified scalar</td></tr>
|
|
<tr><td><code>fill::none</code></td><td> ↦ </td><td>do not initialise the elements</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b>
|
|
<ul>
|
|
<li>since Armadillo 10.5, the elements are initialised to zero by default</li>
|
|
<li>
|
|
in Armadillo 10.4 and older versions, the elements are not initialised unless <i>fill_form</i> is specified;
|
|
ie. without specifying <i>fill_form</i>, the elements may contain garbage values, including NaN
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Each instance of <i>cube</i> automatically allocates and releases internal memory.
|
|
All internally allocated memory used by an instance of <i>cube</i> is automatically released as soon as the instance goes out of scope.
|
|
For example, if an instance of <i>cube</i> is declared inside a function, it will be automatically destroyed at the end of the function.
|
|
To forcefully release memory at any point, use <a href="#reset">.reset()</a>; note that in normal use this is not required.
|
|
</li>
|
|
<br>
|
|
<a name="adv_constructors_cube"></a>
|
|
<li>
|
|
Advanced constructors:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<code>cube::fixed<n_rows, n_cols, n_slices></code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a fixed size cube, with the size specified via template arguments.
|
|
Memory for the cube is reserved 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>
|
|
<br>
|
|
<code>cube(ptr_aux_mem, n_rows, n_cols, n_slices, copy_aux_mem = true, strict = false)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a cube using data from writable auxiliary (external) memory, where <i>ptr_aux_mem</i> is a pointer to the 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 are doing!
|
|
<br>
|
|
<br>
|
|
The <i>strict</i> parameter comes into effect only when <i>copy_aux_mem</i> is set to <i>false</i>
|
|
(ie. the cube is directly using auxiliary memory)
|
|
<ul>
|
|
<li>
|
|
when <i>strict</i> is set to <i>false</i>, the cube will use the auxiliary memory until a size change or an aliasing event
|
|
</li>
|
|
<li>
|
|
when <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
|
|
</li>
|
|
</ul>
|
|
</ul>
|
|
<br>
|
|
<code>cube(const ptr_aux_mem, n_rows, n_cols, n_slices)</code>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
Create a cube by copying data from read-only auxiliary memory,
|
|
where <i>ptr_aux_mem</i> is a pointer to the memory
|
|
</ul>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
cube x(1, 2, 3);
|
|
cube y(4, 5, 6, fill::randu);
|
|
|
|
mat A = y.slice(1); // extract a slice from the cube
|
|
// (each slice is a matrix)
|
|
|
|
mat B(4, 5, fill::randu);
|
|
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>Notes:</b>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
Each cube 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>
|
|
<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,fill::value(123.0)); // Armadillo 10.6 and newer
|
|
</pre>
|
|
</ul>
|
|
or
|
|
<ul>
|
|
<pre>
|
|
cube c(5,6,7,fill::none); c.fill(123.0); // Armadillo 10.5 and older
|
|
</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">element iterators</a></li>
|
|
<li><a href="#field">field class</a></li>
|
|
<li><a href="#Mat">Mat class</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="field"></a>
|
|
<b>field<</b><i>object_type</i><b>></b>
|
|
<ul>
|
|
<li>
|
|
Class for storing arbitrary objects in matrix-like or cube-like layouts
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Somewhat similar to a matrix or cube, but instead of each element being a scalar,
|
|
each element can be a vector, or matrix, or cube
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Each element can have an arbitrary size (eg. in a field of matrices, each matrix can have a unique size)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Constructors, where <i>object_type</i> is another class, eg. <i>vec</i>, <i>mat</i>, <i>std::string</i>, etc:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>field<<i>object_type</i>>()</code></td></tr>
|
|
<tr><td><code>field<<i>object_type</i>>(<i>n_elem</i>)</code></td></tr>
|
|
<tr><td><code>field<<i>object_type</i>>(<i>n_rows</i>, <i>n_cols</i>)</code></td></tr>
|
|
<tr><td><code>field<<i>object_type</i>>(<i>n_rows</i>, <i>n_cols</i>, <i>n_slices</i>)</code></td></tr>
|
|
<tr><td><code>field<<i>object_type</i>>(size(<i>X</i>))</code></td></tr>
|
|
<tr><td><code>field<<i>object_type</i>>(field<<i>object_type</i>>)</code></td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> to store a set of matrices of the same size, the <a href="#Cube">Cube</a> class is more efficient
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A = randn(2,3);
|
|
mat B = randn(4,5);
|
|
|
|
field<mat> F(2,1);
|
|
F(0,0) = A;
|
|
F(1,0) = B;
|
|
|
|
F.print("F:");
|
|
|
|
F.save("mat_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="#Cube">Cube class</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
Classes for sparse matrices; intended for storing large matrices, where most of the elements are zeros
|
|
</li>
|
|
<br>
|
|
<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>short</i>, <i>int</i>, <i>long</i> and unsigned versions of <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; text-align: right;">
|
|
<code>sp_mat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>SpMat<double></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>sp_dmat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>SpMat<double></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>sp_fmat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>SpMat<float></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>sp_cx_mat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>SpMat<<a href="#cx_double">cx_double</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>sp_cx_dmat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>SpMat<<a href="#cx_double">cx_double</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>sp_cx_fmat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>SpMat<<a href="#cx_double">cx_float</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>sp_umat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>SpMat<<a href="#uword">uword</a>></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>sp_imat</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
=
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>SpMat<<a href="#uword">sword</a>></code>
|
|
</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>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>sp_mat()</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>sp_mat(<i>n_rows</i>, <i>n_cols</i>)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>sp_mat(size(<i>X</i>))</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>sp_mat(sp_mat)</code></td><td> </td><td> </td></tr>
|
|
<tr><td><code>sp_mat(mat)</code></td><td> </td><td>(for converting a dense matrix to a sparse matrix)</td></tr>
|
|
<tr><td><code>sp_cx_mat(sp_mat,sp_mat)</code></td><td> </td><td>(for constructing a complex matrix out of two real matrices)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
<br>
|
|
<li>
|
|
All elements are treated as zero by default (ie. the matrix is initialised to contain zeros)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Non-zero elements are stored in <a href="https://en.wikipedia.org/wiki/Sparse_matrix">compressed sparse column (CSC) format</a> (ie. column-major ordering);
|
|
zero-valued elements are never stored
|
|
</li>
|
|
<br>
|
|
<li>
|
|
This class behaves in a similar manner to the dense matrix <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>
|
|
<b>Caveat:</b>
|
|
the sparse matrix class is not intended for small matrices (eg. with size ≤ 100x100), due to the overhead of the compressed storage format;
|
|
for small matrices use the <a href="#Mat">Mat</a> class, even if most of the elements are zeros
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<a name="batch_constructors_sp_mat"></a>
|
|
Batch insertion constructors:
|
|
<ul>
|
|
<li>form 1: <code>sp_mat(<i>locations</i>, <i>values</i>, <i>sort_locations = true</i>)</code></li>
|
|
<li>form 2: <code>sp_mat(<i>locations</i>, <i>values</i>, <i>n_rows</i>, <i>n_cols</i>, <i>sort_locations = true</i>, <i>check_for_zeros = true</i>)</code></li>
|
|
<li>form 3: <code>sp_mat(<i>add_values</i>, <i>locations</i>, <i>values</i>, <i>n_rows</i>, <i>n_cols</i>, <i>sort_locations = true</i>, <i>check_for_zeros = true</i>)</code></li>
|
|
<li>form 4: <code>sp_mat(<i>rowind</i>, <i>colptr</i>, <i>values</i>, <i>n_rows</i>, <i>n_cols</i>, <i>check_for_zeros = true</i>)</code></li>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
For forms 1, 2, 3,
|
|
<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 form 4,
|
|
<i>rowind</i> is a dense column vector of type <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>uvec</i> (with length <i>n_cols + 1</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="https://en.wikipedia.org/wiki/Sparse_matrix">compressed sparse column format</a>;
|
|
this form is useful for copying data from other CSC sparse matrix containers
|
|
</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>add_values</i> is either <i>true</i> or <i>false</i>; when set to <i>true</i>, identical locations are allowed, and the values at identical locations are added
|
|
</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, 3, 4)
|
|
</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; do not set this to <i>false</i> unless you know what you are doing!
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If <i>check_for_zeros</i> is set to <i>false</i>, the <i>values</i> vector is assumed to contain no zero values; do not set this to <i>false</i> unless you know what you are doing!
|
|
</li>
|
|
</ul>
|
|
</ul>
|
|
<br>
|
|
<li>
|
|
The following subset of operations & functions is available for sparse matrices:
|
|
<ul>
|
|
<li>fundamental arithmetic <a href="#operators">operations</a> (such as addition and multiplication)</li>
|
|
<li><a href="#submat">submatrix views</a>: most contiguous forms and the non-contiguous form of <i>X.cols(vector_of_column_indices)</i></li>
|
|
<li><a href="#diag">diagonal views</a></li>
|
|
<li><a href="#save_load_mat">saving and loading</a> (using <i>arma_binary</i>, <i>coord_ascii</i>, and <i>csv_ascii</i> formats)</li>
|
|
<li>element-wise functions: <a href="#abs">abs()</a>, <a href="#misc_fns">cbrt()</a>, <a href="#misc_fns">ceil()</a>, <a href="#conj">conj()</a>, <a href="#misc_fns">floor()</a>, <a href="#imag_real">imag()</a>, <a href="#imag_real">real()</a>, <a href="#misc_fns">round()</a>, <a href="#misc_fns">sign()</a>, <a href="#misc_fns">sqrt()</a>, <a href="#misc_fns">square()</a>, <a href="#misc_fns">trunc()</a></li>
|
|
<li>scalar functions of matrices: <a href="#accu">accu()</a>, <a href="#as_scalar">as_scalar()</a>, <a href="#dot">dot()</a>, <a href="#norm">norm()</a>, <a href="#norm2est">norm2est()</a>, <a href="#trace">trace()</a></li>
|
|
<li>vector valued functions of matrices: <a href="#diagvec">diagvec()</a>, <a href="#min_and_max">min()</a>, <a href="#min_and_max">max()</a>, <a href="#nonzeros">nonzeros()</a>, <a href="#sum">sum()</a>, <a href="#stats_fns">mean()</a>, <a href="#stats_fns">stddev()</a>, <a href="#stats_fns">var()</a>, <a href="#vecnorm">vecnorm()</a>, <a href="#vectorise">vectorise()</a></li>
|
|
<li>matrix valued functions of matrices: <a href="#clamp">clamp()</a>, <a href="#diagmat">diagmat()</a>, <a href="#diags_spdiags">spdiags()</a>, <a href="#flip">flipud()/fliplr()</a>, <a href="#join">join_rows()</a>, <a href="#join">join_cols()</a>, <a href="#kron">kron()</a>, <a href="#normalise">normalise()</a>, <a href="#repelem">repelem()</a>, <a href="#repmat">repmat()</a>, <a href="#reshape">reshape()</a>, <a href="#resize">resize()</a>, <a href="#reverse">reverse()</a>, <a href="#shift">shift()</a>, <a href="#symmat">symmatu()/symmatl()</a>, <a href="#trimat">trimatu()/trimatl()</a>, <a href="#t_st_members">.t()</a>, <a href="#trans">trans()</a></li>
|
|
<li>generated matrices: <a href="#speye">speye()</a>, <a href="#spones">spones()</a>, <a href="#sprandu_sprandn">sprandu()</a>, <a href="#sprandu_sprandn">sprandn()</a>, <a href="#zeros_standalone">zeros()</a></li>
|
|
<li>eigen decompositions and SVD: <a href="#eigs_sym">eigs_sym()</a>, <a href="#eigs_gen">eigs_gen()</a>, <a href="#svds">svds()</a></li>
|
|
<li>solution of sparse linear systems: <a href="#spsolve">spsolve()</a>
|
|
<li>miscellaneous: <a href="#approx_equal">approx_equal()</a>, <a href="#element_access">element access</a>, <a href="#iterators_spmat">element iterators</a>, <a href="#as_col_row">.as_col() / .as_row()</a>, <a href="#for_each">.for_each()</a>, <a href="#print">.print()</a>, <a href="#clean">.clean()</a>, <a href="#replace">.replace()</a>, <a href="#transform">.transform()</a>, <a href="#is_finite">.is_finite()</a>, <a href="#is_symmetric">.is_symmetric()</a>, <a href="#is_hermitian">.is_hermitian()</a>, <a href="#is_trimat">.is_trimatu()</a>, <a href="#is_trimat">.is_trimatl()</a>, <a href="#is_diagmat">.is_diagmat()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
sp_mat A = sprandu(1000, 2000, 0.01);
|
|
sp_mat B = sprandu(2000, 1000, 0.01);
|
|
|
|
sp_mat C = 2*B;
|
|
sp_mat D = A*C;
|
|
|
|
sp_mat E(1000,1000);
|
|
E(1,2) = 123;
|
|
|
|
|
|
// batch insertion of 3 values at
|
|
// locations (1, 2), (7, 8), (9, 9)
|
|
|
|
umat locations = { { 1, 7, 9 },
|
|
{ 2, 8, 9 } };
|
|
|
|
vec values = { 1.0, 2.0, 3.0 };
|
|
|
|
sp_mat X(locations, values);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#element_access">element access</a></li>
|
|
<li><a href="#iterators_spmat">element iterators (sparse matrices)</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="https://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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="operators"></a>
|
|
<b>operators: <code><big>+</big> <big>−</big> <big>*</big> % / == != <= >= < > && ||</code></b>
|
|
<ul>
|
|
<li>
|
|
Overloaded operators for <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i> classes
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Operations:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;"><code><b><big>+</big></b></code></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;"><code><b><big>−</big></b></code></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;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><code><b><big>*</big></b></code></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 by a scalar</td>
|
|
</tr>
|
|
<tr>
|
|
<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;"><code><b>%</b></code></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;"><a name="schur_product"></a>element-wise multiplication of two objects (Schur product)</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><code><b>/</b></code></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;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><code><b>==</b></code></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">element-wise equality evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><code><b>!=</b></code></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">element-wise non-equality evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
|
|
</tr>
|
|
<tr>
|
|
<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;"><code><b>>=</b></code></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">element-wise "greater than or equal to" evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><code><b><=</b></code></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">element-wise "less than or equal to" evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
|
|
</tr>
|
|
<tr>
|
|
<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;"><code><b>></b></code></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">element-wise "greater than" evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><code><b><</b></code></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">element-wise "less than" evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
|
|
</tr>
|
|
<tr>
|
|
<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;"><code><b>&&</b></code></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">element-wise logical AND evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><code><b>||</b></code></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">element-wise logical OR evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For element-wise relational and logical operations
|
|
(ie. <code><b>==</b></code>, <code><b>!=</b></code>, <code><b>>=</b></code>, <code><b><=</b></code>, <code><b>></b></code>, <code><b><</b></code>, <code><b>&&</b></code>, <code><b>||</b></code>)
|
|
each element in the generated object is either 0 or 1, depending on the result of the operation
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b>
|
|
operators involving equality comparison (ie. <code><b>==</b></code>, <code><b>!=</b></code>, <code><b>>=</b></code>, <code><b><=</b></code>)
|
|
are not recommended for matrices of type <i>mat</i> or <i>fmat</i>,
|
|
due to the necessarily <a href="https://en.wikipedia.org/wiki/Floating-point_arithmetic">limited precision of floating-point</a> element types;
|
|
consider using <a href="#approx_equal">approx_equal()</a> instead
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If the <code><b>+</b></code>, <code><b>−</b></code> and <code><b>%</b></code> operators are chained, Armadillo aims 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 <code><b>*</b></code> operator is chained, Armadillo aims to find an efficient ordering of the matrix multiplications
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Broadcasting operations are available via <a href="#each_colrow">.each_col()</a>, <a href="#each_colrow">.each_row()</a>, <a href="#each_slice">.each_slice()</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If incompatible object sizes are used, a <i>std::logic_error</i> exception is thrown
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 10, fill::randu);
|
|
mat B(5, 10, fill::randu);
|
|
mat C(10, 5, fill::randu);
|
|
|
|
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="#approx_equal">approx_equal()</a></li>
|
|
<li><a href="#pow">pow()</a></li>
|
|
<li><a href="#any">any()</a></li>
|
|
<li><a href="#all">all()</a></li>
|
|
<li><a href="#affmul">affmul()</a></li>
|
|
<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="#replace">.replace()</a></li>
|
|
<li><a href="#transform">.transform()</a></li>
|
|
<li><a href="#each_colrow">.each_col() & .each_row()</a> (vector operations applied to each column or row)</li>
|
|
<li><a href="#misc_fns">miscellaneous element-wise functions</a> (exp, log, sqrt, square, round, ...)</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Floating-point_arithmetic">floating point arithmetic in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Floating-PointRepresentation.html">floating point representation in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div>
|
|
<hr class="greyline">
|
|
<hr class="greyline">
|
|
<br>
|
|
<br>
|
|
<font size=+1><b>Member Functions & Variables</b></font>
|
|
<br>
|
|
<br>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="attributes"></a>
|
|
<b>attributes</b>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<code><b>.n_rows</b></code>
|
|
</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>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code><b>.n_cols</b></code>
|
|
</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>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code><b>.n_elem</b></code>
|
|
</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>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code><b>.n_slices</b></code>
|
|
</td>
|
|
<td> </td>
|
|
<td>
|
|
number of slices; present in <i>Cube</i> and <i>field</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code><b>.n_nonzero</b></code>
|
|
</td>
|
|
<td> </td>
|
|
<td>
|
|
number of non-zero elements; present in <i>SpMat</i>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
<ul>
|
|
<li>The variables are of type <a href="#uword">uword</a></li>
|
|
<br>
|
|
<li>
|
|
The variables 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>
|
|
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>
|
|
<li><a href="#size">size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>(i)</code>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
For <i>vec</i> and <i>rowvec</i>, access the element stored at index <i>i</i>.
|
|
For <i>mat</i>, <i>cube</i> and <i>field</i>, access the element/object stored at index <i>i</i> under the assumption of a flat layout,
|
|
with column-major ordering of data (ie. column by column).
|
|
An exception is thrown if the requested element is out of bounds.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>.at(i)</code> or <code>[i]</code>
|
|
</td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
As for <code>(i)</code>, but without a bounds check; not recommended; see the caveats below
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>(r,c)</code>
|
|
</td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
For <i>mat</i> and <i>2D field</i> classes, access the element/object stored at row <i>r</i> and column <i>c</i>.
|
|
An exception is thrown if the requested element is out of bounds.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>.at(r,c)</code>
|
|
</td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
As for <code>(r,c)</code>, but without a bounds check; not recommended; see the caveats below
|
|
</td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>(r,c,s)</code>
|
|
</td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
For <i>cube</i> and <i>3D field</i> classes, access the element/object stored at row <i>r</i>, column <i>c</i>, and slice <i>s</i>.
|
|
An exception is thrown if the requested element is out of bounds.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>.at(r,c,s)</code>
|
|
</td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
As for <code>(r,c,s)</code>, but without a bounds check; not recommended; see the caveats below
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The indices of elements are specified via the <a href="#uword">uword</a> type, which is a typedef for an <a href="#uword">unsigned integer type</a>.
|
|
When using loops to access elements, it is best to use <i>uword</i> instead of <i>int</i>.
|
|
For example: <code>for(uword i=0; i<X.n_elem; ++i) { X(i) = ... }</code>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>
|
|
accessing elements without bounds checks is slightly faster, but is not recommended until your code has been thoroughly debugged first
|
|
</li>
|
|
<li>
|
|
indexing in C++ starts at 0
|
|
</li>
|
|
<li>accessing elements via <code>[r,c]</code> and <code>[r,c,s]</code> does not work correctly in C++;
|
|
instead use <code>(r,c)</code> and <code>(r,c,s)</code>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat M(10, 10, fill::randu);
|
|
M(9,9) = 123.0;
|
|
double x = M(1,2);
|
|
|
|
vec v(10, fill::randu);
|
|
v(9) = 123.0;
|
|
double y = v(0);
|
|
</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="#ind2sub">ind2sub()</a></li>
|
|
<li><a href="#sub2ind">sub2ind()</a></li>
|
|
<li><a href="#index_min_and_index_max_member">.index_min() / .index_max()</a></li>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
<li><a href="#memptr">.memptr()</a></li>
|
|
<li><a href="#transform">.transform()</a></li>
|
|
<li><a href="#for_each">.for_each()</a></li>
|
|
<li><a href="#iterators_mat">iterators (dense matrices)</a></li>
|
|
<li><a href="#iterators_cube">iterators (cubes)</a></li>
|
|
<li><a href="#iterators_spmat">iterators (sparse matrices)</a></li>
|
|
<li><a href="#config_hpp">config.hpp</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="element_initialisation"></a>
|
|
<b>element initialisation</b>
|
|
<ul>
|
|
<li>
|
|
Set elements in <i>Mat</i>, <i>Col</i>, <i>Row</i> via braced initialiser lists
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec v = { 1, 2, 3 };
|
|
|
|
mat A = { {1, 3, 5},
|
|
{2, 4, 6} };
|
|
</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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="zeros_member"></a>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.zeros()</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i>, <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.zeros( n_elem )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Col</i> and <i>Row</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.zeros( n_rows, n_cols )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i> and <i>SpMat</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.zeros( n_rows, n_cols, n_slices )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.zeros( size(X) )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>)
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
Set the elements of an object to zero,
|
|
optionally first changing the size to specified dimensions
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A;
|
|
A.zeros(5, 10); // or: mat A(5, 10, fill::zeros);
|
|
|
|
mat B;
|
|
B.zeros( size(A) );
|
|
|
|
mat C(5, 10, fill::randu);
|
|
C.zeros();
|
|
</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="#clean">.clean()</a></li>
|
|
<li><a href="#is_zero">.is_zero()</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>
|
|
<li><a href="#size">size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="ones_member"></a>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.ones()</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.ones( n_elem )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Col</i> and <i>Row</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.ones( n_rows, n_cols )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.ones( n_rows, n_cols, n_slices )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.ones( size(X) )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
Set all the elements of an object to one,
|
|
optionally first changing the size to specified dimensions
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A;
|
|
A.ones(5, 10); // or: mat A(5, 10, fill::ones);
|
|
|
|
mat B;
|
|
B.ones( size(A) );
|
|
|
|
mat C(5, 10, fill::randu);
|
|
C.ones();
|
|
</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>
|
|
<li><a href="#size">size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="eye_member"></a>
|
|
<b>.eye()</b>
|
|
<br>
|
|
<b>.eye( n_rows, n_cols )</b>
|
|
<br>
|
|
<b>.eye( size(X) )</b>
|
|
<ul>
|
|
<li>
|
|
Member functions of <i>Mat</i> and <i>SpMat</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Set the elements along the main diagonal to one and off-diagonal elements to zero,
|
|
optionally first changing the size 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;
|
|
A.eye(5, 5); // or: mat A(5, 5, fill::eye);
|
|
|
|
mat B;
|
|
B.eye( size(A) );
|
|
|
|
mat C(5, 5, fill::randu);
|
|
C.eye();
|
|
</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>
|
|
<li><a href="#size">size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="randu_randn_member"></a>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.randu()</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.randu( n_elem )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Col</i> and <i>Row</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.randu( n_rows, n_cols )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.randu( n_rows, n_cols, n_slices )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.randu( size(X) )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<br>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.randn()</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.randn( n_elem )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Col</i> and <i>Row</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.randn( n_rows, n_cols )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.randn( n_rows, n_cols, n_slices )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.randn( size(X) )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
Set all the elements to random values,
|
|
optionally first changing the size 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>For complex elements, the real and imaginary parts are treated separately
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A;
|
|
A.randu(5, 10); // or: mat A(5, 10, fill::randu);
|
|
|
|
mat B;
|
|
B.randu( size(A) );
|
|
|
|
mat C(5, 10, fill::zeros);
|
|
C.randu();
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#randu">randu()</a> (standalone function with extended functionality)</li>
|
|
<li><a href="#randn">randn()</a> (standalone function with extended functionality)</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="#size">size()</a></li>
|
|
<li><a href="#rng_seed">RNG seed setting</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Uniform_distribution_(continuous)">uniform distribution in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="fill"></a>
|
|
<b>.fill( value )</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>field</i>
|
|
</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 <i>double</i>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 6);
|
|
|
|
A.fill(123.0); // or: mat A(5, 6, fill::value(123.0));
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Note:</b> to set all elements to zero during matrix construction, use the following more compact form:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 6, fill::zeros);
|
|
</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="#replace">.replace()</a></li>
|
|
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="imbue"></a>
|
|
<b>.imbue( </b>functor<b> )</b>
|
|
<br>
|
|
<b>.imbue( </b>lambda_function<b> )</b>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i>
|
|
</li>
|
|
<br>
|
|
<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, with each slice treated as a matrix
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
std::mt19937 engine; // Mersenne twister random number engine
|
|
|
|
std::uniform_real_distribution<double> distr(0.0, 1.0);
|
|
|
|
mat A(4, 5, fill::none);
|
|
|
|
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="#element_access">element access</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Function_object">function object</a> at Wikipedia</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/C%2B%2B11#Lambda_functions_and_expressions">C++11 lambda functions</a> at Wikipedia</li>
|
|
<li><a href="https://www.cprogramming.com/c++11/c++11-lambda-closures.html">lambda function</a> at cprogramming.com</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="clean"></a>
|
|
<b>.clean( </b>threshold<b> )</b>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>SpMat</i>
|
|
</li>
|
|
<br>
|
|
<li>For objects with non-complex elements: each element with an absolute value ≤ <i>threshold</i> is replaced by zero</li>
|
|
<br>
|
|
<li>For objects with complex elements: for each element, each component (real and imaginary) with an absolute value ≤ <i>threshold</i> is replaced by zero</li>
|
|
<br>
|
|
<li>Can be used to sparsify a matrix, in the sense of zeroing values with small magnitudes</li>
|
|
<br>
|
|
<li><b>Caveat:</b> to explicitly convert from dense storage to sparse storage, use the <a href="#SpMat">SpMat class</a></li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
sp_mat A;
|
|
|
|
A.sprandu(1000, 1000, 0.01);
|
|
|
|
A(12,34) = datum::eps;
|
|
A(56,78) = -datum::eps;
|
|
|
|
A.clean(datum::eps);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#replace">.replace()</a></li>
|
|
<li><a href="#clamp_member">.clamp()</a></li>
|
|
<li><a href="#transform">.transform()</a></li>
|
|
<li><a href="#is_zero">.is_zero()</a></li>
|
|
<li><a href="#zeros_member">.zeros()</a></li>
|
|
<li><a href="#nonzeros">nonzeros()</a></li>
|
|
<li><a href="#constants">datum::eps</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="replace"></a>
|
|
<b>.replace( old_value, new_value )</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>SpMat</i>
|
|
</li>
|
|
<br>
|
|
<li>For all elements equal to <i>old_value</i>, set them to <i>new_value</i></li>
|
|
<br>
|
|
<li>The type of <i>old_value</i> and <i>new_value</i> must match the type of elements used by the container object (eg. for <i>mat</i> the type is <i>double</i>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>floating point numbers (<i>float</i> and <i>double</i>) are approximations due to their <a href="https://en.wikipedia.org/wiki/Floating-point_arithmetic">necessarily limited precision</a></li>
|
|
<li>for sparse matrices (<i>SpMat</i>), replacement is not done when <i>old_value = 0</i></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 6, fill::randu);
|
|
|
|
A.diag().fill(datum::nan);
|
|
|
|
A.replace(datum::nan, 0); // replace each NaN with 0
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#transform">.transform()</a></li>
|
|
<li><a href="#for_each">.for_each()</a></li>
|
|
<li><a href="#clean">.clean()</a></li>
|
|
<li><a href="#clamp_member">.clamp()</a></li>
|
|
<li><a href="#fill">.fill()</a></li>
|
|
<li><a href="#has_nan">.has_nan()</a></li>
|
|
<li><a href="#has_inf">.has_inf()</a></li>
|
|
<li><a href="#find">find()</a></li>
|
|
<li><a href="#operators">relational operators</a></li>
|
|
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="clamp_member"></a>
|
|
<b>.clamp( min_value, max_value )</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>SpMat</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Clamp each element to the [<i>min_val</i>, <i>max_val</i>] interval;
|
|
<br>any value lower than <i>min_val</i> will be set to <i>min_val</i>, and any value higher than <i>max_val</i> will be set to <i>max_val</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For complex elements, the real and imaginary components are clamped separately
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For sparse matrices, clamping is applied only to the non-zero elements
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 6, fill::randu);
|
|
|
|
A.clamp(0.2, 0.8);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#replace">.replace()</a></li>
|
|
<li><a href="#clean">.clean()</a></li>
|
|
<li><a href="#transform">.transform()</a></li>
|
|
<li><a href="#for_each">.for_each()</a></li>
|
|
<li><a href="#clamp">clamp()</a> (standalone function)</li>
|
|
<li><a href="#operators">relational operators</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="transform"></a>
|
|
<b>.transform( </b>functor<b> )</b>
|
|
<br>
|
|
<b>.transform( </b>lambda_function<b> )</b>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>SpMat</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Transform each element using a functor or lambda function
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For dense matrices, transformation is done column-by-column for all elements
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For sparse matrices, transformation is done column-by-column for non-zero elements
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For cubes, transformation is done slice-by-slice, with each slice treated as a matrix
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(4, 5, fill::ones);
|
|
|
|
// add 123 to every element
|
|
A.transform( [](double val) { return (val + 123.0); } );
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#for_each">.for_each()</a></li>
|
|
<li><a href="#replace">.replace()</a></li>
|
|
<li><a href="#imbue">.imbue()</a></li>
|
|
<li><a href="#clean">.clean()</a></li>
|
|
<li><a href="#clamp_member">.clamp()</a></li>
|
|
<li><a href="#element_access">element access</a></li>
|
|
<li><a href="#operators">overloaded operators</a></li>
|
|
<li><a href="#misc_fns">miscellaneous element-wise functions</a> (exp, log, sqrt, square, round, ...)</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Function_object">function object</a> at Wikipedia</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/C%2B%2B11#Lambda_functions_and_expressions">C++11 lambda functions</a> at Wikipedia</li>
|
|
<li><a href="https://www.cprogramming.com/c++11/c++11-lambda-closures.html">lambda function</a> at cprogramming.com</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="for_each"></a>
|
|
<b>.for_each( </b>functor<b> )</b>
|
|
<br>
|
|
<b>.for_each( </b>lambda_function<b> )</b>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i> and <i>field</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For each element, pass its reference to a functor or lambda function
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For dense matrices and fields, the processing is done column-by-column for all elements
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For sparse matrices, the processing is done column-by-column for non-zero elements
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For cubes, processing is done slice-by-slice, with each slice treated as a matrix
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
// add 123 to each element in a dense matrix
|
|
|
|
mat A(4, 5, fill::ones);
|
|
|
|
A.for_each( [](mat::elem_type& val) { val += 123.0; } ); // NOTE: the '&' is crucial!
|
|
|
|
|
|
// add 123 to each non-zero element in a sparse matrix
|
|
|
|
sp_mat S; S.sprandu(1000, 2000, 0.1);
|
|
|
|
S.for_each( [](sp_mat::elem_type& val) { val += 123.0; } ); // NOTE: the '&' is crucial!
|
|
|
|
|
|
// set the size of all matrices in field F
|
|
|
|
field<mat> F(2,3);
|
|
|
|
F.for_each( [](mat& X) { X.zeros(4,5); } ); // NOTE: the '&' is crucial!
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#transform">.transform()</a></li>
|
|
<li><a href="#replace">.replace()</a></li>
|
|
<li><a href="#each_colrow">.each_col() & .each_row()</a></li>
|
|
<li><a href="#each_slice">.each_slice()</a></li>
|
|
<li><a href="#element_access">element access</a></li>
|
|
<li><a href="#misc_fns">miscellaneous element-wise functions</a> (exp, log, sqrt, square, round, ...)</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Function_object">function object</a> at Wikipedia</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/C%2B%2B11#Lambda_functions_and_expressions">C++11 lambda functions</a> at Wikipedia</li>
|
|
<li><a href="https://www.cprogramming.com/c++11/c++11-lambda-closures.html">lambda function</a> at cprogramming.com</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="set_size"></a>
|
|
<table style="text-align: left;" 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> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Col</i>, <i>Row</i>, <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> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>, <i>SpMat</i>, <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> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Cube</i> and <i>field</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.set_size( size(X) )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>, <i>field</i>)
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>Change the size of an object, without explicitly preserving data and without initialising the elements (ie. elements may contain garbage values, including NaN)</li>
|
|
<br>
|
|
<li>
|
|
To initialise the elements to zero while changing the size, use <a href="#zeros_member">.zeros()</a> instead
|
|
</li>
|
|
<br>
|
|
<li>
|
|
To explicitly preserve data while changing the size, use <a href="#reshape_member">.reshape()</a> or <a href="#resize_member">.resize()</a> instead;
|
|
<br><b>NOTE</b>: <i>.reshape()</i> and <i>.resize()</i> are considerably slower than <i>.set_size()</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A;
|
|
A.set_size(5, 10); // or: mat A(5, 10, fill::none);
|
|
|
|
mat B;
|
|
B.set_size( size(A) ); // or: mat B(size(A), fill::none);
|
|
|
|
vec v;
|
|
v.set_size(100); // or: vec v(100, fill::none);
|
|
</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>
|
|
<li><a href="#size">size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="reshape_member"></a>
|
|
<table style="text-align: left;" 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> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i> and <i>SpMat</i>)
|
|
</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> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.reshape( size(X) )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Cube</i>, <i>SpMat</i>)
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
Recreate the object according to given size specifications,
|
|
with the elements taken from the previous version of the object in a column-wise manner;
|
|
the elements in the generated object are placed column-wise (ie. the first column is filled up before filling the second column)
|
|
</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>
|
|
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>Caveats:</b>
|
|
<ul>
|
|
<li>
|
|
to change the size without preserving data, use <a href="#set_size">.set_size()</a> instead, which is much faster
|
|
</li>
|
|
<li>
|
|
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>
|
|
<li>
|
|
to flatten a matrix into a vector, use <a href="#vectorise">vectorise()</a> or <a href="#as_col_row">.as_col() / .as_row()</a> instead
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(4, 5, fill::randu);
|
|
|
|
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="#as_col_row">.as_col() / .as_row()</a></li>
|
|
<li><a href="#reshape">reshape()</a> (standalone function)</li>
|
|
<li><a href="#vectorise">vectorise()</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="resize_member"></a>
|
|
<table style="text-align: left;" 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> </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> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i> and <i>SpMat</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> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.resize( size(X) )</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>)
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<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>
|
|
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(4, 5, fill::randu);
|
|
|
|
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>
|
|
<li><a href="#size">size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="copy_size"></a>
|
|
<b>.copy_size( A )</b>
|
|
<ul>
|
|
<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. the size of a matrix can't be set by providing a cube)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 6, fill::randu);
|
|
|
|
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>
|
|
<li><a href="#size">size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="reset"></a>
|
|
<b>
|
|
.reset()
|
|
</b>
|
|
<ul>
|
|
<li>
|
|
Reset the size to zero (the object will have no elements)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
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>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
<table>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
|
|
<table>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
|
|
<li>contiguous views for matrix X:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
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>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>
|
|
<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 matrix ]</i><br>
|
|
<br>
|
|
X<b>(</b> <b>span(</b>first_row<b>,</b> last_row<b>),</b> col_number <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>head_cols( </b>number_of_cols<b> )</b><br>
|
|
X.<b>head_rows( </b>number_of_rows<b> )</b><br>
|
|
<br>
|
|
X.<b>tail_cols( </b>number_of_cols<b> )</b><br>
|
|
X.<b>tail_rows( </b>number_of_rows<b> )</b><br>
|
|
<br>
|
|
X.<b>unsafe_col( </b>col_number<b> )</b> <i>[ use with caution ]</i><br>
|
|
</ul>
|
|
</li>
|
|
|
|
<br>
|
|
|
|
<li>
|
|
contiguous views for vector V:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
V<b>( span(</b>first_index<b>,</b> last_index<b>) )</b><br>
|
|
V.<b>subvec( </b>first_index<b>,</b> last_index<b> )</b><br>
|
|
<br>
|
|
V.<b>subvec( </b>first_index<b>, size(</b>W<b>) )</b> <i>[ W is a vector ]</i><br>
|
|
<br>
|
|
V.<b>head( </b>number_of_elements<b> )</b><br>
|
|
V.<b>tail( </b>number_of_elements<b> )</b>
|
|
</ul>
|
|
</li>
|
|
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
</td>
|
|
|
|
<td> </td>
|
|
<td class="line" style="vertical-align: top;"> </td>
|
|
<td> </td>
|
|
|
|
<td style="vertical-align: top;">
|
|
|
|
<table>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
|
|
<li>non-contiguous views for matrix or vector X:
|
|
<ul>
|
|
<br>
|
|
X.<b>elem(</b> vector_of_indices <b>)</b><br>
|
|
X<b>(</b> vector_of_indices <b>)</b><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>submat(</b> vector_of_row_indices<b>,</b> vector_of_column_indices <b>)</b><br>
|
|
X<b>(</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>
|
|
<br>
|
|
<br>
|
|
|
|
<li>related matrix views (documented separately)
|
|
<ul>
|
|
<br>
|
|
X.<a href="#diag">diag()</a><br>
|
|
X.<a href="#each_colrow">each_row()</a><br>
|
|
X.<a href="#each_colrow">each_col()</a><br>
|
|
</ul>
|
|
</li>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
<br>
|
|
<li>
|
|
Instances of <i>span(start,end)</i> can be replaced by <i>span::all</i> to indicate the entire range
|
|
</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 a vector of type <a href="#Col">uvec</a>
|
|
(eg. generated by the <a href="#find">find()</a> function).
|
|
The aggregate set of the specified elements is treated as a column vector
|
|
(ie. 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 are doing.
|
|
It creates a seemingly independent <i>Col</i> vector object (eg. <i>vec</i>),
|
|
but uses memory from the existing matrix object.
|
|
As such, the created vector is not alias safe,
|
|
and does not take into account that the underlying matrix memory could be freed
|
|
(eg. due to any operation involving a size change of the matrix).
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 10, fill::zeros);
|
|
|
|
A.submat( 0,1, 2,3 ) = randu<mat>(3,3);
|
|
A( span(0,2), span(1,3) ) = randu<mat>(3,3);
|
|
A( 0,1, size(3,3) ) = randu<mat>(3,3);
|
|
|
|
mat B = A.submat( 0,1, 2,3 );
|
|
mat C = A( span(0,2), span(1,3) );
|
|
mat D = A( 0,1, size(3,3) );
|
|
|
|
A.col(1) = randu<mat>(5,1);
|
|
A(span::all, 1) = randu<mat>(5,1);
|
|
|
|
mat X(5, 5, fill::randu);
|
|
|
|
// get all elements of X that are greater than 0.5
|
|
vec q = X.elem( find(X > 0.5) );
|
|
|
|
// add 123 to all elements of X greater than 0.5
|
|
X.elem( find(X > 0.5) ) += 123.0;
|
|
|
|
// set four specific elements of X to 1
|
|
uvec indices = { 2, 3, 6, 8 };
|
|
|
|
X.elem(indices) = ones<vec>(4);
|
|
|
|
// add 123 to the last 5 elements of vector a
|
|
vec a(10, fill::randu);
|
|
a.tail(5) += 123.0;
|
|
|
|
// add 123 to the first 3 elements of column 2 of X
|
|
X.col(2).head(3) += 123;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#diag">diagonal views</a></li>
|
|
<li><a href="#each_colrow">.each_col() & .each_row()</a> (vector operations applied to 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 / cols / slices</a></li>
|
|
<li><a href="#shed">.shed_rows / cols / slices</a></li>
|
|
<li><a href="#insert">.insert_rows / cols / slices</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
<li><a href="#subcube">subcube views</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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</li>
|
|
<br>
|
|
<table>
|
|
<tr>
|
|
|
|
<td style="vertical-align: top;">
|
|
<li>contiguous views for cube Q:
|
|
<br>
|
|
<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>row( </b>row_number <b>)</b><br>
|
|
Q.<b>rows( </b>first_row<b>,</b> last_row <b>)</b><br>
|
|
<br>
|
|
Q.<b>col( </b>col_number <b>)</b><br>
|
|
Q.<b>cols( </b>first_col<b>,</b> last_col <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>
|
|
<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>
|
|
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>
|
|
<br>
|
|
Q.<b>head_slices( </b>number_of_slices<b> )</b><br>
|
|
Q.<b>tail_slices( </b>number_of_slices<b> )</b><br>
|
|
<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>
|
|
Q.<b>tube( </b>first_row<b>,</b> first_col<b>, size(</b>n_rows<b>,</b> n_cols<b>) )</b><br>
|
|
</ul>
|
|
</li>
|
|
</td>
|
|
|
|
<td> </td>
|
|
<td class="line" style="vertical-align: top;"> </td>
|
|
<td> </td>
|
|
|
|
<td style="vertical-align: top;">
|
|
<li>non-contiguous views for cube Q:
|
|
<ul>
|
|
<br>
|
|
Q.<b>elem(</b> vector_of_indices <b>)</b><br>
|
|
Q<b>(</b> vector_of_indices <b>)</b>
|
|
<br>
|
|
<br>
|
|
Q.<b>slices(</b> vector_of_slice_indices <b>)</b><br>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>related cube views (documented separately)
|
|
<ul>
|
|
<br>Q.<a href="#each_slice">each_slice()</a>
|
|
<br>Q.<a href="#col_row_as_mat">col_as_mat()</a>
|
|
<br>Q.<a href="#col_row_as_mat">row_as_mat()</a>
|
|
<br>
|
|
<br>
|
|
</ul>
|
|
</li>
|
|
</td>
|
|
|
|
</tr>
|
|
</table>
|
|
<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>
|
|
In the function <i>Q.elem(vector_of_indices)</i>,
|
|
elements specified in <i>vector_of_indices</i> are accessed.
|
|
<i>Q</i> is interpreted as one long vector,
|
|
with slice-by-slice and column-by-column ordering of the elements of <i>Q</i>.
|
|
The <i>vector_of_indices</i> must evaluate to a vector of type <a href="#Col">uvec</a>
|
|
(eg. generated by the <a href="#find">find()</a> function).
|
|
The aggregate set of the specified elements is treated as a column vector
|
|
(ie. the output of <i>Q.elem()</i> is always a column vector).
|
|
</li>
|
|
<br>
|
|
<li>
|
|
In the function <i>Q.slices(vector_of_slice_indices)</i>,
|
|
slices specified in <i>vector_of_slice_indices</i> are accessed.
|
|
The <i>vector_of_slice_indices</i> must evaluate to a vector of type <a href="#Col">uvec</a>.
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
cube A(2, 3, 4, fill::randu);
|
|
|
|
mat B = A.slice(1); // each slice is a matrix
|
|
|
|
A.slice(0) = randu<mat>(2,3);
|
|
A.slice(0)(1,2) = 99.0;
|
|
|
|
A.subcube(0,0,1, 1,1,2) = randu<cube>(2,2,2);
|
|
A( span(0,1), span(0,1), span(1,2) ) = randu<cube>(2,2,2);
|
|
A( 0,0,1, size(2,2,2) ) = randu<cube>(2,2,2);
|
|
|
|
// add 123 to all elements of A greater than 0.5
|
|
A.elem( find(A > 0.5) ) += 123.0;
|
|
|
|
cube C = A.head_slices(2); // get first two slices
|
|
|
|
A.head_slices(2) += 123.0;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#in_range">.in_range()</a></li>
|
|
<li><a href="#each_slice">.each_slice()</a></li>
|
|
<li><a href="#col_row_as_mat">.col_as_mat() / .row_as_mat()</a></li>
|
|
<li><a href="#join_slices">join_slices()</a></li>
|
|
<li><a href="#shed">shed_slices()</a></li>
|
|
<li><a href="#insert">insert_slices()</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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 2D 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>
|
|
<br>
|
|
F<b>( </b>first_row<b>,</b> first_col<b>, size(</b>G<b>) )</b> <i>[ G is a 2D 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>
|
|
<br>
|
|
<li>For a 3D field <i>F</i>, the subfields are accessed as:</li>
|
|
<br>
|
|
<ul>
|
|
F.<b>slice( </b>slice_number <b>)</b><br>
|
|
<br>
|
|
F.<b>slices( </b>first_slice<b>,</b> last_slice <b>)</b><br>
|
|
<br>
|
|
F.<b>subfield( </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>
|
|
<br>
|
|
F<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>
|
|
F<b>( </b>first_row<b>,</b> first_col<b>,</b> first_slice<b>, size(</b>G<b>) )</b> <i>[ G is a 3D field ]</i><br>
|
|
F<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>
|
|
</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="#size">size()</a></li>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
<li><a href="#subcube">subcube views</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="diag"></a>
|
|
<b>.diag()</b>
|
|
<br><b>.diag(</b> k <b>)</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i> and <i>SpMat</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 <i>k = 0</i></li>
|
|
<br>
|
|
<li>
|
|
The argument <i>k</i> specifies the diagonal to use:
|
|
<ul>
|
|
<li><i>k = 0</i> indicates the main diagonal (default setting)</li>
|
|
<li><i>k < 0</i> indicates the <i>k</i>-th sub-diagonal (below main diagonal, towards bottom-left corner)</li>
|
|
<li><i>k > 0</i> indicates the <i>k</i>-th super-diagonal (above main diagonal, towards top-right corner)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>The diagonal is interpreted as a column vector within expressions</li>
|
|
<br>
|
|
<li>
|
|
<b>Note</b>: to calculate only the diagonal elements of a compound expression, use <a href="#diagvec">diagvec()</a> or <a href="#diagmat">diagmat()</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(5, 5, fill::randu);
|
|
|
|
vec a = X.diag();
|
|
vec b = X.diag(1);
|
|
vec c = X.diag(-2);
|
|
|
|
X.diag() = randu<vec>(5);
|
|
X.diag() += 6;
|
|
X.diag().ones();
|
|
|
|
sp_mat S = sprandu<sp_mat>(10,10,0.1);
|
|
|
|
vec v(S.diag()); // copy sparse diagonal to dense vector
|
|
</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="#diags_spdiags">diags() / spdiags()</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>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="each_colrow"></a>
|
|
<table>
|
|
<tr><td><b>.each_col()</b></td> <td> </td><td><b>.each_row()</b></td> <td> </td><td>(form 1)</td></tr>
|
|
<tr><td><b>.each_col(</b> vector_of_indices <b>)</b></td><td> </td><td><b>.each_row(</b> vector_of_indices <b>)</b></td><td> </td><td>(form 2)</td></tr>
|
|
<tr><td><b>.each_col(</b> lambda_function <b>)</b></td> <td> </td><td><b>.each_row(</b> lambda_function <b>)</b></td> <td> </td><td>(form 3)</td></tr>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
Member functions of <i>Mat</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Apply a vector operation to each column or row of a matrix
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Similar to "broadcasting" in Matlab / Octave
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Supported operations for forms 1 and 2:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<table>
|
|
<tr><td><code><b>+</b></code></td><td> </td><td>addition</td><td> </td><td><code><b>+=</b></code></td><td> </td><td>in-place addition</td></tr>
|
|
<tr><td><code><b>−</b></code></td><td> </td><td>subtraction</td><td> </td><td><code><b>−=</b></code></td><td> </td><td>in-place subtraction</td></tr>
|
|
<tr><td><code><b>%</b></code></td><td> </td><td>element-wise multiplication</td><td> </td><td><code><b>%=</b></code></td><td> </td><td>in-place element-wise multiplication</td></tr>
|
|
<tr><td><code><b>/</b></code></td><td> </td><td>element-wise division</td><td> </td><td><code><b>/=</b></code></td><td> </td><td>in-place element-wise division</td></tr>
|
|
<tr><td><code><b>=</b></code></td><td> </td><td>assignment (copy)</td><td> </td><td> </td><td> </td><td> </td></tr>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For form 2:
|
|
<ul>
|
|
<li>the argument <i>vector_of_indices</i> contains a list of indices of the columns/rows to be used; it must evaluate to a vector of type <i><a href="#Col">uvec</a></i></li>
|
|
<li>arithmetic operations as per form 1 are supported</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For form 3:
|
|
<ul>
|
|
<li>apply the given <i>lambda_function</i> to each column vector or row vector</li>
|
|
<li>the function must accept a reference to a <a href="#Col">Col</a> or <a href="#Row">Row</a> object with the same element type as the underlying matrix</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(6, 5, fill::ones);
|
|
vec v = linspace<vec>(10,15,6);
|
|
|
|
X.each_col() += v; // in-place addition of v to each column vector of X
|
|
|
|
mat Y = X.each_col() + v; // generate Y by adding v to each column vector of X
|
|
|
|
// 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;
|
|
|
|
X.each_col(indices) = v; // copy v to columns 2 and 4 in X
|
|
|
|
|
|
X.each_col( [](vec& a){ a.print(); } ); // lambda function with non-const vector
|
|
|
|
const mat& XX = X;
|
|
XX.each_col( [](const vec& b){ b.print(); } ); // lambda function with const vector
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#operators">math & relational operators</a></li>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
<li><a href="#diag">diagonal views</a></li>
|
|
<li><a href="#repmat">repmat()</a></li>
|
|
<li><a href="#pow">pow()</a></li>
|
|
<li><a href="#for_each">.for_each()</a></li>
|
|
<li><a href="#each_slice">.each_slice()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="each_slice"></a>
|
|
<table>
|
|
<tr><td><b>.each_slice()</b></td><td> </td><td>(form 1)</td></tr>
|
|
<tr><td><b>.each_slice(</b> vector_of_indices <b>)</b></td><td> </td><td>(form 2)</td></tr>
|
|
<tr><td><b>.each_slice(</b> lambda_function <b>)</b></td><td> </td><td>(form 3)</td></tr>
|
|
<tr><td><b>.each_slice(</b> lambda_function, use_mp <b>)</b></td><td> </td><td>(form 4)</td></tr>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Cube</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Apply a matrix operation to each slice of a cube, with each slice treated as a matrix
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Similar to "broadcasting" in Matlab / Octave
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Supported operations for form 1:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<table>
|
|
<tr><td><code><b>+</b></code></td><td> </td><td>addition</td><td> </td><td><code><b>+=</b></code></td><td> </td><td>in-place addition</td></tr>
|
|
<tr><td><code><b>−</b></code></td><td> </td><td>subtraction</td><td> </td><td><code><b>−=</b></code></td><td> </td><td>in-place subtraction</td></tr>
|
|
<tr><td><code><b>%</b></code></td><td> </td><td>element-wise multiplication</td><td> </td><td><code><b>%=</b></code></td><td> </td><td>in-place element-wise multiplication</td></tr>
|
|
<tr><td><code><b>/</b></code></td><td> </td><td>element-wise division</td><td> </td><td><code><b>/=</b></code></td><td> </td><td>in-place element-wise division</td></tr>
|
|
<tr><td><code><b>*</b></code></td><td> </td><td>matrix multiplication</td><td> </td><td><code><b>*=</b></code></td><td> </td><td>in-place matrix multiplication</td></tr>
|
|
<tr><td><code><b>=</b></code></td><td> </td><td>assignment (copy)</td><td> </td><td> </td><td> </td><td> </td></tr>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For form 2:
|
|
<ul>
|
|
<li>the argument <i>vector_of_indices</i> contains a list of indices of the slices to be used; it must evaluate to a vector of type <i><a href="#Col">uvec</a></i></li>
|
|
<li>arithmetic operations as per form 1 are supported, except for <code><b>*</b></code> and <code><b>*=</b></code> (ie. matrix multiplication)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For form 3:
|
|
<ul>
|
|
<li>apply the given <i>lambda_function</i> to each slice</li>
|
|
<li>the function must accept a reference to a <a href="#Mat">Mat</a> object with the same element type as the underlying cube</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For form 4:
|
|
<ul>
|
|
<li>apply the given <i>lambda_function</i> to each slice, as per form 3</li>
|
|
<li>the argument <i>use_mp</i> is a bool to enable the use of OpenMP for multi-threaded execution of <i>lambda_function</i> on multiple slices at the same time</li>
|
|
<li>the order of processing the slices is not deterministic (eg. slice 2 can be processed before slice 1)</li>
|
|
<li><i>lambda_function</i> must be thread-safe, ie. it must not write to variables outside of its scope
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
cube C(4, 5, 6, fill::randu);
|
|
|
|
mat M = repmat(linspace<vec>(1,4,4), 1, 5);
|
|
|
|
C.each_slice() += M; // in-place addition of M to each slice of C
|
|
|
|
cube D = C.each_slice() + M; // generate D by adding M to each slice of C
|
|
|
|
|
|
uvec indices(2);
|
|
indices(0) = 2;
|
|
indices(1) = 4;
|
|
|
|
C.each_slice(indices) = M; // copy M to slices 2 and 4 in C
|
|
|
|
|
|
C.each_slice( [](mat& X){ X.print(); } ); // lambda function with non-const matrix
|
|
|
|
const cube& CC = C;
|
|
CC.each_slice( [](const mat& X){ X.print(); } ); // lambda function with const matrix
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#operators">math & relational operators</a></li>
|
|
<li><a href="#subcube">subcube views</a></li>
|
|
<li><a href="#pow">pow()</a></li>
|
|
<li><a href="#for_each">.for_each()</a></li>
|
|
<li><a href="#each_colrow">.each_col() & .each_row()</a> </li>
|
|
<li><a href="https://www.cprogramming.com/c++11/c++11-lambda-closures.html">lambda function</a> at cprogramming.com</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="set_imag"></a>
|
|
<b>.set_imag( X )</b>
|
|
<br>
|
|
<b>.set_real( X )</b>
|
|
<br>
|
|
<ul>
|
|
<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(4, 5, fill::randu);
|
|
mat B(4, 5, fill::randu);
|
|
|
|
cx_mat C(4, 5, fill::zeros);
|
|
|
|
C.set_real(A);
|
|
C.set_imag(B);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b>
|
|
to directly construct a complex matrix out of two real matrices,
|
|
the following code is faster:
|
|
<ul>
|
|
<pre>
|
|
mat A(4, 5, fill::randu);
|
|
mat B(4, 5, fill::randu);
|
|
|
|
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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="insert"></a>
|
|
<table style="text-align: left;" 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>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member functions of <i>Mat</i>, <i>Col</i> and <i>Cube</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>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member functions of <i>Mat</i>, <i>Row</i> and <i>Cube</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>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member functions of <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<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 (and slices) as the recipient object</li>
|
|
<li>if inserting columns, <i>X</i> must have the same number of rows (and slices) 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:
|
|
<ul>
|
|
<li>expand the object by creating new rows/columns/slices</li>
|
|
<li>the elements in the new rows/columns/slices are set to zero</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 10, fill::randu);
|
|
mat B(5, 2, fill::ones );
|
|
|
|
// 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 / cols / slices</a></li>
|
|
<li><a href="#join">join_rows / cols / 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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="shed"></a>
|
|
<table style="text-align: left;" 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>
|
|
<br>
|
|
<b>.shed_rows( </b>vector_of_indices<b> )</b>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">
|
|
(member function of <i>Mat</i>, <i>Col</i>, <i>SpMat</i>, <i>Cube</i>)
|
|
<br>
|
|
(member function of <i>Mat</i>, <i>Col</i>, <i>SpMat</i>, <i>Cube</i>)
|
|
<br>
|
|
(member function of <i>Mat</i>, <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>
|
|
<br>
|
|
<b>.shed_cols( </b>vector_of_indices<b> )</b>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">
|
|
(member function of <i>Mat</i>, <i>Row</i>, <i>SpMat</i>, <i>Cube</i>)
|
|
<br>
|
|
(member function of <i>Mat</i>, <i>Row</i>, <i>SpMat</i>, <i>Cube</i>)
|
|
<br>
|
|
(member function of <i>Mat</i>, <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>
|
|
<br>
|
|
<b>.shed_slices( </b>vector_of_indices<b> )</b>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member functions of <i>Cube</i>)
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
Functions with single scalar argument: remove the specified row/column/slice
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Functions with two scalar arguments: remove the specified range of rows/columns/slices
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>vector_of_indices</i> must evaluate to a vector of type <a href="#Col">uvec</a>; it contains the indices of rows/columns/slices to remove
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 10, fill::randu);
|
|
mat B(5, 10, fill::randu);
|
|
|
|
A.shed_row(2);
|
|
A.shed_cols(2,4);
|
|
|
|
uvec indices = {4, 6, 8};
|
|
B.shed_cols(indices);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#insert">.insert_rows / cols / slices</a></li>
|
|
<li><a href="#join">join_rows / cols / 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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>, <i>Row</i> and <i>SpMat</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Swap the contents of specified rows or columns
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(5, 5, fill::randu);
|
|
X.swap_rows(0,4);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#reverse">reverse()</a></li>
|
|
<li><a href="#flip">fliplr() & flipud()</a></li>
|
|
<li><a href="#swap">.swap()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="swap"></a>
|
|
<b>.swap( X )</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Swap contents with object <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(4, 5, fill::zeros);
|
|
mat B(6, 7, fill::ones );
|
|
|
|
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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Obtain a raw pointer to the memory used for storing elements
|
|
</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>
|
|
<b>Caveat:</b> the pointer becomes invalid after any operation involving a size change or aliasing
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> this function is not recommended for use unless you know what you are doing!
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
const mat B(5, 5, fill::randu);
|
|
|
|
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="#submat">submatrix views</a></li>
|
|
<li><a href="#element_access">element access</a></li>
|
|
<li><a href="#iterators_mat">iterators (dense 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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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 elements in the specified column
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> the pointer becomes invalid after any operation involving a size change or aliasing
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> this function is not recommended for use unless you know what you are doing
|
|
-- it is safer to use <a href="#submat">submatrix views</a> instead
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
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 (dense matrices)</a></li>
|
|
<li><a href="#adv_constructors_mat">advanced constructors (matrices)</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="iterators_mat"></a>
|
|
<b>iterators (dense matrices & vectors)</b>
|
|
<ul>
|
|
<li>
|
|
Iterators and associated member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Iterators for dense matrices and vectors traverse over all elements within the specified range
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Member functions:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<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; text-align: right;">
|
|
<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; text-align: right;">
|
|
<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; text-align: right;">
|
|
<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>
|
|
<tr>
|
|
<td>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<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; text-align: right;">
|
|
<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>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Iterator types:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<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; text-align: right;">
|
|
<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; text-align: right;">
|
|
<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 specified columns
|
|
</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; text-align: right;">
|
|
<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 specified columns
|
|
</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; text-align: right;">
|
|
<b>mat::row_iterator</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
bidirectional iterator, for read/write access to the elements of specified rows
|
|
</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; text-align: right;">
|
|
<b>mat::const_row_iterator</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
bidirectional iterator, for read-only access to the elements of specified rows
|
|
</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; text-align: right;">
|
|
<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 specified rows
|
|
</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; text-align: right;">
|
|
<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 specified rows
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(5, 6, fill::randu);
|
|
|
|
mat::iterator it = X.begin();
|
|
mat::iterator it_end = X.end();
|
|
|
|
for(; it != it_end; ++it)
|
|
{
|
|
cout << (*it) << endl;
|
|
}
|
|
|
|
mat::col_iterator col_it = X.begin_col(1); // start of column 1
|
|
mat::col_iterator col_it_end = X.end_col(3); // end of column 3
|
|
|
|
for(; col_it != col_it_end; ++col_it)
|
|
{
|
|
cout << (*col_it) << endl;
|
|
(*col_it) = 123.0;
|
|
}
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#Mat">Mat class</a></li>
|
|
<li><a href="#element_access">element access</a></li>
|
|
<li><a href="#for_each">.for_each()</a></li>
|
|
<li><a href="#memptr">.memptr()</a></li>
|
|
<li><a href="#colptr">.colptr()</a></li>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
<li><a href="#iterators_submat">iterators (submatrices)</a></li>
|
|
<li><a href="#iterators_cube">iterators (cubes)</a></li>
|
|
<li><a href="#iterators_spmat">iterators (sparse matrices)</a></li>
|
|
<li><a href="https://cplusplus.com/reference/iterator/">iterator at cplusplus.com</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="iterators_cube"></a>
|
|
<b>iterators (cubes)</b>
|
|
<ul>
|
|
<li>
|
|
Iterators and associated member functions of <i>Cube</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Iterators for cubes traverse over all elements within the specified range
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Member functions:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<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; text-align: right;">
|
|
<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; text-align: right;">
|
|
<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; text-align: right;">
|
|
<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>
|
|
<li>
|
|
Iterator types:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<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; text-align: right;">
|
|
<b>cube::const_iterator</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
random access iterator, 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; text-align: right;">
|
|
<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; text-align: right;">
|
|
<b>cube::const_slice_iterator</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
random access iterator, for read-only access to the elements of a particular slice
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
cube X(2, 3, 4, fill::randu);
|
|
|
|
cube::iterator it = X.begin();
|
|
cube::iterator it_end = X.end();
|
|
|
|
for(; it != it_end; ++it)
|
|
{
|
|
cout << (*it) << endl;
|
|
}
|
|
|
|
cube::slice_iterator s_it = X.begin_slice(1); // start of slice 1
|
|
cube::slice_iterator s_it_end = X.end_slice(2); // end of slice 2
|
|
|
|
for(; s_it != s_it_end; ++s_it)
|
|
{
|
|
cout << (*s_it) << endl;
|
|
(*s_it) = 123.0;
|
|
}
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#Cube">Cube class</a></li>
|
|
<li><a href="#element_access">element access</a></li>
|
|
<li><a href="#for_each">.for_each()</a></li>
|
|
<li><a href="#memptr">.memptr()</a></li>
|
|
<li><a href="#subcube">subcube views</a></li>
|
|
<li><a href="#iterators_submat">iterators (subcubes)</a></li>
|
|
<li><a href="#iterators_mat">iterators (dense matrices)</a></li>
|
|
<li><a href="https://cplusplus.com/reference/iterator/">iterator at cplusplus.com</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="iterators_spmat"></a>
|
|
<b>iterators (sparse matrices)</b>
|
|
<ul>
|
|
<li>
|
|
Iterators and associated member functions of <i>SpMat</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Iterators for sparse matrices traverse over non-zero elements within the specified range
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>writing a zero value into a sparse matrix through an iterator will invalidate all current iterators associated with the sparse matrix</li>
|
|
<li>to modify the non-zero elements in a safer manner, use <a href="#transform">.transform()</a> or <a href="#for_each">.for_each()</a> instead of iterators
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Member functions:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<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; text-align: right;">
|
|
<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; text-align: right;">
|
|
<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; text-align: right;">
|
|
<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>
|
|
<tr>
|
|
<td>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<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; text-align: right;">
|
|
<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>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Iterator types:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<b>sp_mat::iterator</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
bidirectional iterator, for read/write access to elements (which are stored column by column)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<b>sp_mat::const_iterator</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
bidirectional iterator, 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; text-align: right;">
|
|
<b>sp_mat::col_iterator</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
bidirectional iterator, for read/write access to the elements of a specific column
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<b>sp_mat::const_col_iterator</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
bidirectional iterator, 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; text-align: right;">
|
|
<b>sp_mat::row_iterator</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
bidirectional iterator, for read/write access to the elements of a specific row
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<b>sp_mat::const_row_iterator</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
bidirectional 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>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The iterators have <i>.row()</i> and <i>.col()</i> functions which return the row and column of the current element;
|
|
the returned values are of type <a href="#uword">uword</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
sp_mat X = sprandu<sp_mat>(1000, 2000, 0.1);
|
|
|
|
sp_mat::const_iterator it = X.begin();
|
|
sp_mat::const_iterator it_end = X.end();
|
|
|
|
for(; it != it_end; ++it)
|
|
{
|
|
cout << "val: " << (*it) << endl;
|
|
cout << "row: " << it.row() << endl;
|
|
cout << "col: " << it.col() << endl;
|
|
}
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#SpMat">SpMat class</a></li>
|
|
<li><a href="#element_access">element access</a></li>
|
|
<li><a href="#transform">.transform()</a></li>
|
|
<li><a href="#for_each">.for_each()</a></li>
|
|
<li><a href="#replace">.replace()</a></li>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
<li><a href="#iterators_mat">iterators (dense matrices)</a></li>
|
|
<li><a href="https://cplusplus.com/reference/iterator/">iterator at cplusplus.com</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="iterators_submat"></a>
|
|
<b>iterators (dense submatrices & subcubes)</b>
|
|
<ul>
|
|
<li>
|
|
iterators for dense <a href="#submat">submatrix</a> and <a href="#subcube">subcube</a> views,
|
|
allowing range-based for loops
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b>
|
|
These iterators are intended <b>only</b> to be used with range-based for loops. Any other use is not supported.
|
|
For example, the direct use of the <i>begin()</i> and <i>end()</i> functions, as well as the underlying iterators types is not supported.
|
|
The implementation of submatrices and subcubes uses short-lived temporary objects that are subject to automatic deletion, and as such are error-prone to handle manually.
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(100, 200, fill::randu);
|
|
|
|
for( double& val : X(span(40,60), span(50,100)) )
|
|
{
|
|
cout << val << endl;
|
|
val = 123.0;
|
|
}
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
<li><a href="#for_each">.for_each()</a></li>
|
|
<li><a href="#iterators_mat">iterators (dense matrices)</a></li>
|
|
<li><a href="#iterators_cube">iterators (cubes)</a></li>
|
|
<li><a href="https://en.cppreference.com/w/cpp/language/range-for">range-based for</a> (cppreference.com)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="compat_container_fns"></a>
|
|
<b>compatibility container functions</b>
|
|
<ul>
|
|
<li>Member functions to mimic the functionality of containers in the C++ standard library:<br>
|
|
<br>
|
|
|
|
<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>.front()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
access the first element in a vector
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>.back()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
access the last element in a vector
|
|
</td>
|
|
</tr>
|
|
<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(5, 5, fill::randu);
|
|
cout << A.size() << endl;
|
|
|
|
A.clear();
|
|
cout << A.empty() << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#iterators_mat">iterators (dense matrices)</a></li>
|
|
<li><a href="#iterators_cube">iterators (cubes)</a></li>
|
|
<li><a href="#iterators_spmat">iterators (sparse 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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="as_col_row"></a>
|
|
<b>
|
|
.as_col()
|
|
<br>.as_row()
|
|
</b>
|
|
<ul>
|
|
<li>
|
|
Member functions of any matrix expression
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>.as_col()</i>: return a flattened version of the matrix as a column vector; flattening is done by concatenating all columns
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>.as_row()</i>: return a flattened version of the matrix as a row vector; flattening is done by concatenating all rows
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> concatenating columns is faster than concatenating rows
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(4, 5, fill::randu);
|
|
vec v = X.as_col();
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#reshape_member">.reshape()</a></li>
|
|
<li><a href="#t_st_members">.t() / .st()</a></li>
|
|
<li><a href="#as_scalar">as_scalar()</a></li>
|
|
<li><a href="#vectorise">vectorise()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="col_row_as_mat"></a>
|
|
<b>.col_as_mat(</b> col_number <b>)</b>
|
|
<br>
|
|
<b>.row_as_mat(</b> row_number <b>)</b>
|
|
<ul>
|
|
<li>
|
|
Member functions of any cube expression
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>.col_as_mat( col_number )</i>:
|
|
<ul>
|
|
<li>return a matrix representation of the specified cube column</li>
|
|
<li>the number of rows is preserved</li>
|
|
<li>given a cube with size <i>R x C x S</i>, the resultant matrix size is <i>R x S</i>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>.row_as_mat( row_number )</i>:
|
|
<ul>
|
|
<li>return a matrix representation of the specified cube row</li>
|
|
<li>the number of columns is preserved</li>
|
|
<li>given a cube with size <i>R x C x S</i>, the resultant matrix size is <i>S x C</i>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
cube Q(5, 4, 3, fill::randu);
|
|
|
|
mat A = Q.col_as_mat(2); // size of A: 5x3
|
|
|
|
mat B = Q.row_as_mat(2); // size of B: 3x4
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#subcube">.slice()</a></li>
|
|
<li><a href="#vectorise">vectorise()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="t_st_members"></a>
|
|
<b>
|
|
.t()
|
|
<br>.st()
|
|
</b>
|
|
<ul>
|
|
<li>
|
|
Member functions of any matrix or vector expression
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For real (non-complex) matrix:
|
|
<ul>
|
|
<li><i>.t()</i> provides a transposed copy of the matrix</li>
|
|
<li><i>.st()</i> is not applicable</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For complex matrix:
|
|
<ul>
|
|
<li><i>.t()</i> provides a Hermitian (conjugate) transposed copy (ie. signs of imaginary components are flipped)</li>
|
|
<li><i>.st()</i> provides a simple transposed copy (ie. signs of imaginary components are not flipped)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(4, 5, fill::randu);
|
|
mat B = A.t();
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#trans">trans()</a></li>
|
|
<li><a href="#reverse">reverse()</a></li>
|
|
<li><a href="#as_col_row">.as_col() / .as_row()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Transpose">transpose in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Transpose.html">transpose in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Conjugate_transpose">conjugate transpose in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/ConjugateTranspose.html">conjugate transpose in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="i_member"></a>
|
|
<b>.i()</b>
|
|
<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 sized, 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>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>
|
|
if matrix <i>A</i> is know to be symmetric positive definite, <a href="#inv_sympd">inv_sympd()</a> is faster
|
|
</li>
|
|
<li>
|
|
to solve a system of linear equations, such as <i>Z = inv(X)*Y</i>,
|
|
<a href="#solve">solve()</a> can be faster and/or more accurate
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(4, 4, fill::randu);
|
|
|
|
mat X = A.i();
|
|
|
|
mat Y = (A+A).i();
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#inv">inv()</a></li>
|
|
<li><a href="#rcond">rcond()</a></li>
|
|
<li><a href="#pinv">pinv()</a></li>
|
|
<li><a href="#solve">solve()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="min_and_max_member"></a>
|
|
<b>.min()</b>
|
|
<br><b>.max()</b>
|
|
<ul>
|
|
<li>
|
|
Return the extremum value of any matrix or cube expression
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For objects with complex numbers, absolute values are used for comparison
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
double max_val = A.max();
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#index_min_and_index_max_member">.index_min() & .index_max()</a></li>
|
|
<li><a href="#min_and_max">min() & max()</a> (standalone functions with extended functionality)</li>
|
|
<li><a href="#clamp">clamp()</a>
|
|
<li><a href="#running_stat">running_stat</a></li>
|
|
<li><a href="#running_stat_vec">running_stat_vec</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="index_min_and_index_max_member"></a>
|
|
<b>.index_min()</b>
|
|
<br><b>.index_max()</b>
|
|
<ul>
|
|
<li>
|
|
Return the linear index of the extremum value of any matrix or cube expression
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For objects with complex numbers, absolute values are used for comparison
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The returned index is of type <a href="#uword">uword</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
uword i = A.index_max();
|
|
|
|
double max_val = A(i);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#min_and_max_member">.min() & .max()</a></li>
|
|
<li><a href="#index_min_and_index_max_standalone">index_min() & index_max()</a> (standalone functions with extended functionality)</li>
|
|
<li><a href="#ind2sub">ind2sub()</a></li>
|
|
<li><a href="#sort_index">sort_index()</a></li>
|
|
<li><a href="#find">find()</a></li>
|
|
<li><a href="#element_access">element access</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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 degrade performance
|
|
</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="#as_scalar">as_scalar()</a></li>
|
|
<li><a href="#Mat">Mat class</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="in_range"></a>
|
|
<table style="text-align: left;" 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> </td>
|
|
<td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>, <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> </td>
|
|
<td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>, <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> </td>
|
|
<td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i>, <i>field</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.in_range(</b> <font size=-1><b>span(</b>start_row<b>,</b> end_row<b>), span(</b>start_col<b>,</b> end_col<b>)</b></font> <b>)</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i>, <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> </td>
|
|
<td style="vertical-align: top;">(member of <i>Cube</i> and <i>field</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>.in_range(</b> <font size=-1><b>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>)</b></font> <b>)</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member of <i>Cube</i> and <i>field</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
|
|
</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 matrix or field)</i></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i>, <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> </td>
|
|
<td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i>, <i>field</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
|
|
</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 or field)</i></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td> </td>
|
|
<td style="vertical-align: top;">(member of <i>Cube</i> and <i>field</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> </td>
|
|
<td style="vertical-align: top;">(member of <i>Cube</i> and <i>field</i>)
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<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(4, 5, fill::randu);
|
|
|
|
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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="is_empty"></a>
|
|
<b>.is_empty()</b>
|
|
<ul>
|
|
<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(5, 5, fill::randu);
|
|
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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="is_vec"></a>
|
|
<b>.is_vec()</b>
|
|
<br><b>.is_colvec()</b>
|
|
<br><b>.is_rowvec()</b>
|
|
<ul>
|
|
<li>
|
|
Member functions of <i>Mat</i> and <i>SpMat</i>
|
|
</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(1, 5, fill::randu);
|
|
mat B(5, 1, fill::randu);
|
|
mat C(5, 5, fill::randu);
|
|
|
|
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>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="is_sorted"></a>
|
|
<b>.is_sorted()</b>
|
|
<br><b>.is_sorted( sort_direction )</b>
|
|
<br><b>.is_sorted( sort_direction, dim )</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i>, <i>Row</i> and <i>Col</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If the object is a vector, return a <i>bool</i> indicating whether the elements are sorted
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If the object is a matrix, return a <i>bool</i> indicating whether the elements are sorted in each column (<i>dim = 0</i>), or each row (<i>dim = 1</i>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>sort_direction</i> argument is optional; <i>sort_direction</i> is one of:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>"ascend"</code></td><td> ↦ </td><td>elements are ascending; consecutive elements can be equal; this is the <b>default operation</b></td></tr>
|
|
<tr><td><code>"descend"</code></td><td> ↦ </td><td>elements are descending; consecutive elements can be equal</td></tr>
|
|
<tr><td><code>"strictascend"</code></td><td> ↦ </td><td>elements are strictly ascending; consecutive elements cannot be equal</td></tr>
|
|
<tr><td><code>"strictdescend"</code></td><td> ↦ </td><td>elements are strictly descending; consecutive elements cannot be equal</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>dim</i> argument is optional; by default <i>dim = 0</i> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For matrices and vectors with complex numbers, order is checked via absolute values
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec a(10, fill::randu);
|
|
vec b = sort(a);
|
|
|
|
bool check1 = a.is_sorted();
|
|
bool check2 = b.is_sorted();
|
|
|
|
|
|
mat A(10, 10, fill::randu);
|
|
|
|
// check whether each column is sorted in descending manner
|
|
cout << A.is_sorted("descend") << endl;
|
|
|
|
// check whether each row is sorted in ascending manner
|
|
cout << A.is_sorted("ascend", 1) << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#sort">sort()</a></li>
|
|
<li><a href="#sort_index">sort_index()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="is_trimat"></a>
|
|
<b>.is_trimatu()</b>
|
|
<br>
|
|
<b>.is_trimatl()</b>
|
|
<ul>
|
|
<li>
|
|
Member functions of <i>Mat</i> and <i>SpMat</i>
|
|
</li>
|
|
<br>
|
|
<li><i>.is_trimatu()</i>:
|
|
<ul>
|
|
<li>return <i>true</i> if the matrix is upper triangular, ie. the matrix is square sized and all elements below the main diagonal are zero; return <i>false</i> otherwise</li>
|
|
<li><b>caveat:</b> if this function returns <i>true</i>, do not assume that the matrix contains non-zero elements on or above the main diagonal</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li><i>.is_trimatl()</i>:
|
|
<ul>
|
|
<li>return <i>true</i> if the matrix is lower triangular, ie. the matrix is square sized and all elements above the main diagonal are zero; return <i>false</i> otherwise</li>
|
|
<li><b>caveat:</b> if this function returns <i>true</i>, do not assume that the matrix contains non-zero elements on or below the main diagonal</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
mat B = trimatl(A);
|
|
|
|
cout << A.is_trimatu() << endl;
|
|
cout << B.is_trimatl() << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#trimat">trimatu() / trimatl()</a></li>
|
|
<li><a href="#is_symmetric">.is_symmetric()</a></li>
|
|
<li><a href="#is_diagmat">.is_diagmat()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/TriangularMatrix.html">Triangular matrix in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Triangular_matrix">Triangular matrix in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="is_diagmat"></a>
|
|
<b>.is_diagmat()</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i> and <i>SpMat</i>
|
|
</li>
|
|
<br>
|
|
<li>Return <i>true</i> if the matrix is diagonal, ie. all elements outside of the main diagonal are zero
|
|
</li>
|
|
<br>
|
|
<li>Return <i>false</i> otherwise
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> if this function returns <i>true</i>, do not assume that the matrix contains non-zero elements on the main diagonal
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
mat B = diagmat(A);
|
|
|
|
cout << A.is_diagmat() << endl;
|
|
cout << B.is_diagmat() << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#diagmat">diagmat()</a></li>
|
|
<li><a href="#is_trimat">.is_trimatu() / .is_trimatl()</a></li>
|
|
<li><a href="#is_symmetric">.is_symmetric()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/DiagonalMatrix.html">Diagonal matrix in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Diagonal_matrix">Diagonal matrix in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="is_square"></a>
|
|
<b>.is_square()</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i> and <i>SpMat</i>
|
|
</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(5, 5, fill::randu);
|
|
mat B(6, 7, fill::randu);
|
|
|
|
cout << A.is_square() << endl;
|
|
cout << B.is_square() << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#is_symmetric">.is_symmetric()</a></li>
|
|
<li><a href="#is_hermitian">.is_hermitian()</a></li>
|
|
<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>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="is_symmetric"></a>
|
|
<b>.is_symmetric()</b>
|
|
<br><b>.is_symmetric( tol )</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i> and <i>SpMat</i>
|
|
</li>
|
|
<br>
|
|
<li>Returns <i>true</i> if the matrix is symmetric</li>
|
|
<br>
|
|
<li>Returns <i>false</i> if the matrix is not symmetric</li>
|
|
<br>
|
|
<li>
|
|
The <i>tol</i> argument is optional; if <i>tol</i> is specified, the given matrix <i>X</i> is considered symmetric if <i>norm(X - X.st(), "inf") / norm (X, "inf") ≤ tol</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
mat B = A.t() * A;
|
|
|
|
cout << A.is_symmetric() << endl;
|
|
cout << B.is_symmetric() << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#is_hermitian">.is_hermitian()</a></li>
|
|
<li><a href="#is_sympd">.is_sympd()</a></li>
|
|
<li><a href="#is_square">.is_square()</a></li>
|
|
<li><a href="#is_trimat">.is_trimatu() / .is_trimatl()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Symmetric_matrix">Symmetric matrix in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/SymmetricMatrix.html">Symmetric matrix in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="is_hermitian"></a>
|
|
<b>.is_hermitian()</b>
|
|
<br><b>.is_hermitian( tol )</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i> and <i>SpMat</i>
|
|
</li>
|
|
<br>
|
|
<li>Returns <i>true</i> if the matrix is hermitian (self-adjoint)</li>
|
|
<br>
|
|
<li>Returns <i>false</i> if the matrix is not hermitian</li>
|
|
<br>
|
|
<li>
|
|
The <i>tol</i> argument is optional; if <i>tol</i> is specified, the given matrix <i>X</i> is considered hermitian if <i>norm(X - X.t(), "inf") / norm (X, "inf") ≤ tol</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
cx_mat A(5, 5, fill::randu);
|
|
cx_mat B = A.t() * A;
|
|
|
|
cout << A.is_hermitian() << endl;
|
|
cout << B.is_hermitian() << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#is_symmetric">.is_symmetric()</a></li>
|
|
<li><a href="#is_sympd">.is_sympd()</a></li>
|
|
<li><a href="#is_square">.is_square()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Hermitian_matrix">Hermitian matrix in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/HermitianMatrix.html">Hermitian matrix in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="is_sympd"></a>
|
|
<b>.is_sympd()</b>
|
|
<br><b>.is_sympd( tol )</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i> and any dense matrix expression
|
|
</li>
|
|
<br>
|
|
<li>Returns <i>true</i> if the matrix is symmetric/hermitian positive definite within the tolerance given by <i>tol</i>
|
|
</li>
|
|
<br>
|
|
<li>Returns <i>false</i> otherwise
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>tol</i> argument is optional; if <i>tol</i> is not specified, by default <i>tol = 100 * datum::eps * norm(X, "fro")</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
mat B = A.t() * A;
|
|
|
|
cout << A.is_sympd() << endl;
|
|
cout << B.is_sympd() << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#is_symmetric">.is_symmetric()</a></li>
|
|
<li><a href="#is_hermitian">.is_hermitian()</a></li>
|
|
<li><a href="#constants">datum::eps</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="is_zero"></a>
|
|
<b>.is_zero()</b>
|
|
<br>
|
|
<b>.is_zero(</b> tolerance <b>)</b>
|
|
<ul>
|
|
<li>For objects with non-complex elements: return <i>true</i> if each element has an absolute value ≤ <i>tolerance</i>; return <i>false</i> otherwise</li>
|
|
<br>
|
|
<li>For objects with complex elements: return <i>true</i> if for each element, each component (real and imaginary) has an absolute value ≤ <i>tolerance</i>; return <i>false</i> otherwise</li>
|
|
<br>
|
|
<li>The argument <i>tolerance</i> is optional; by default <i>tolerance = 0</i></li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::zeros);
|
|
|
|
A(0,0) = datum::eps;
|
|
|
|
cout << A.is_zero() << endl;
|
|
cout << A.is_zero(datum::eps) << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#clean">.clean()</a></li>
|
|
<li><a href="#all">all()</a></li>
|
|
<li><a href="#constants">datum::eps</a></li>
|
|
<li><a href="#approx_equal">approx_equal()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="is_finite"></a>
|
|
<a name="is_finite_member"></a>
|
|
<b>.is_finite()</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>
|
|
</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(5, 5, fill::randu);
|
|
mat B(5, 5, fill::randu);
|
|
|
|
B(1,1) = datum::inf;
|
|
|
|
cout << A.is_finite() << endl;
|
|
cout << B.is_finite() << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#has_inf">.has_inf()</a></li>
|
|
<li><a href="#has_nan">.has_nan()</a></li>
|
|
<li><a href="#find_finite">find_finite()</a></li>
|
|
<li><a href="#find_nonfinite">find_nonfinite()</a></li>
|
|
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="has_inf"></a>
|
|
<b>.has_inf()</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>
|
|
</li>
|
|
<br>
|
|
<li>Returns <i>true</i> if at least one of the elements of the object is ±infinity
|
|
</li>
|
|
<br>
|
|
<li>Returns <i>false</i> otherwise
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
mat B(5, 5, fill::randu);
|
|
|
|
B(1,1) = datum::inf;
|
|
|
|
cout << A.has_inf() << endl;
|
|
cout << B.has_inf() << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#has_nan">.has_nan()</a>
|
|
<li><a href="#replace">.replace()</a></li>
|
|
<li><a href="#is_finite">.is_finite()</a>
|
|
<li><a href="#find_nonfinite">find_nonfinite()</a></li>
|
|
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="has_nan"></a>
|
|
<b>.has_nan()</b>
|
|
<ul>
|
|
<li>
|
|
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>
|
|
</li>
|
|
<br>
|
|
<li>Returns <i>true</i> if at least one of the elements of the object is NaN (not-a-number)
|
|
</li>
|
|
<br>
|
|
<li>Returns <i>false</i> otherwise
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b>
|
|
<code>NaN</code> is not equal to anything, even itself
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
mat B(5, 5, fill::randu);
|
|
|
|
B(1,1) = datum::nan;
|
|
|
|
cout << A.has_nan() << endl;
|
|
cout << B.has_nan() << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#has_inf">.has_inf()</a>
|
|
<li><a href="#replace">.replace()</a></li>
|
|
<li><a href="#is_finite">.is_finite()</a>
|
|
<li><a href="#find_nonfinite">find_nonfinite()</a></li>
|
|
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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 functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</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(5, 5, fill::randu);
|
|
mat B(6, 6, fill::randu);
|
|
|
|
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="#brief_print">.brief_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="#output_streams">output streams</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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 functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i> and <i>Cube</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Similar to the <a href="#print">.print()</a> member function,
|
|
with the difference that no formatting of the output is done; the stream's parameters such as precision, cell width, etc. can be set manually
|
|
</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(5, 5, fill::randu);
|
|
|
|
cout.precision(11);
|
|
cout.setf(ios::fixed);
|
|
|
|
A.raw_print(cout, "A:");
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#print">.print()</a></li>
|
|
<li><a href="#brief_print">.brief_print()</a></li>
|
|
<li><a href="https://en.cppreference.com/w/cpp/io/ios_base/fmtflags">std::ios_base::fmtflags</a> (cppreference.com)</li>
|
|
<li><a href="https://cplusplus.com/reference/ios/ios_base/fmtflags/">std::ios_base::fmtflags</a> (cplusplus.com)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="brief_print"></a>
|
|
<b>.brief_print()</b>
|
|
<br><b>.brief_print( header )</b>
|
|
<br>
|
|
<br><b>.brief_print( stream )</b>
|
|
<br><b>.brief_print( stream, header )</b>
|
|
<ul>
|
|
<li>
|
|
Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i> and <i>Cube</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Print a shortened/abridged version of an object and its size to the <i>std::cout</i> stream (default),
|
|
or a user specified stream, with an optional header string
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Can be useful for gaining a glimpse of large matrices
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(123, 456, fill::randu);
|
|
|
|
A.brief_print("A:");
|
|
|
|
// possible output:
|
|
//
|
|
// A:
|
|
// [matrix size: 123x456]
|
|
// 0.8402 0.7605 0.6218 ... 0.9744
|
|
// 0.3944 0.9848 0.0409 ... 0.7799
|
|
// 0.7831 0.9350 0.4140 ... 0.8835
|
|
// : : : : :
|
|
// 0.4954 0.1826 0.9848 ... 0.1918
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#print">.print()</a></li>
|
|
<li><a href="#raw_print">.raw_print()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="save_load_mat"></a>
|
|
<b>saving / loading matrices & cubes</b>
|
|
<br>
|
|
<br>
|
|
<table>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<b>.save(</b> filename <b>)</b>
|
|
<br><b>.save(</b> filename<b>,</b> file_type <b>)</b>
|
|
<br>
|
|
<br><b>.save(</b> stream <b>)</b>
|
|
<br><b>.save(</b> stream<b>,</b> file_type <b>)</b>
|
|
<br>
|
|
<br><b>.save( hdf5_name(</b>filename<b>,</b> dataset<b>) )</b>
|
|
<br><b>.save( hdf5_name(</b>filename<b>,</b> dataset<b>,</b> settings<b>) )</b>
|
|
<br>
|
|
<br><b>.save( csv_name(</b>filename<b>,</b> header<b>) )</b>
|
|
<br><b>.save( csv_name(</b>filename<b>,</b> header<b>,</b> settings<b>) )</b>
|
|
</td>
|
|
<td> </td>
|
|
<td>
|
|
<b>.load(</b> filename <b>)</b>
|
|
<br><b>.load(</b> filename<b>,</b> file_type <b>)</b>
|
|
<br>
|
|
<br><b>.load(</b> stream <b>)</b>
|
|
<br><b>.load(</b> stream<b>,</b> file_type <b>)</b>
|
|
<br>
|
|
<br><b>.load( hdf5_name(</b>filename<b>,</b> dataset<b>) )</b>
|
|
<br><b>.load( hdf5_name(</b>filename<b>,</b> dataset<b>,</b> settings<b>) )</b>
|
|
<br>
|
|
<br><b>.load( csv_name(</b>filename<b>,</b> header<b>) )</b>
|
|
<br><b>.load( csv_name(</b>filename<b>,</b> header<b>,</b> settings<b>) )</b>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<br>
|
|
<ul>
|
|
<li>Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>SpMat</i></li>
|
|
<br>
|
|
<li>Store/retrieve data in a file or stream (<b>caveat:</b> the stream must be opened in binary mode)</li>
|
|
<br>
|
|
<li>On success, <i>.save()</i> and <i>.load()</i> return a <i>bool</i> set to <i>true</i></li>
|
|
<br>
|
|
<li>On failure, <i>.save()</i> and <i>.load()</i> return a <i>bool</i> set to <i>false</i>; additionally, <i>.load()</i> resets the object so that it has no elements</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 only by <i>.load()</i> only: attempt to automatically detect the file type as one of the formats described below;
|
|
<br>[ default operation for <i>.load()</i> ]<br><br>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>arma_binary</b><br></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 and size of matrix/cube.
|
|
<br>[ default operation for <i>.save()</i> ]
|
|
<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 and size of matrix/cube.
|
|
<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>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>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, <b>without</b> a header.
|
|
To save/load <b>with</b> a header, use the <b>csv_name(</b>filename,header<b>)</b> specification instead (more details below).
|
|
Handles complex numbers stored in the compound form of 1.24+4.56i.
|
|
Applicable to <i>Mat</i> and <i>SpMat</i>.
|
|
<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><b>coord_ascii</b></td>
|
|
<td style="vertical-align: top;"><br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Numerical data stored as a text file in coordinate list format, without a header.
|
|
Only non-zero values are stored.
|
|
<br>
|
|
For real matrices, each line contains information in the following format: <code>row column value</code>
|
|
<br>For complex matrices, each line contains information in the following format: <code>row column real_value imag_value</code>
|
|
<br>The rows and columns start at zero.
|
|
<br>Armadillo ≥ 10.3: applicable to <i>Mat</i> and <i>SpMat</i>; Armadillo ≤ 10.2: applicable to <i>SpMat</i> only.
|
|
<br><b>Caveat:</b> not supported by <i>auto_detect</i>.
|
|
<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.
|
|
<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 <a href="https://en.wikipedia.org/wiki/Hierarchical_Data_Format">HDF5</a> binary format.
|
|
<ul>
|
|
<li>
|
|
for saving, the default dataset name within the HDF5 file is "dataset"
|
|
</li>
|
|
<li>
|
|
for loading, the order of operations is:
|
|
(1) try loading a dataset named "dataset",
|
|
(2) try loading a dataset named "value",
|
|
(3) try loading the first available dataset
|
|
</li>
|
|
<li>
|
|
to explicitly control the dataset name, specify it via the <b>hdf5_name()</b> argument (more details below)
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b>
|
|
for saving / loading HDF5 files, 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. <code><i>-lhdf5</i></code>).
|
|
HDF5 support can be enabled by defining <a href="#config_hpp">ARMA_USE_HDF5</a> before including the armadillo header:
|
|
<br>
|
|
<code>
|
|
#define ARMA_USE_HDF5
|
|
<br>#include <armadillo>
|
|
</code>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
By providing either <b>hdf5_name(</b>filename<b>,</b> dataset<b>)</b> or <b>hdf5_name(</b>filename<b>,</b> dataset<b>,</b> settings<b>)</b>, the <i>file_type</i> type is assumed to be <i>hdf5_binary</i>
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
the <i>dataset</i> argument specifies an HDF5 dataset name (eg. "my_dataset") that can include a full path (eg. "/group_name/my_dataset");
|
|
if a blank dataset name is specified (ie. ""), it is assumed to be "dataset"
|
|
<br>
|
|
<br>
|
|
</li>
|
|
<li>the <i>settings</i> argument is optional; it is one of the following, or a combination thereof:
|
|
<br>
|
|
<br>
|
|
<table>
|
|
<tr style="vertical-align: top;"><td><code>hdf5_opts::trans </code></td><td> </td><td>save/load the data with columns transposed to rows (and vice versa)</td></tr>
|
|
<tr style="vertical-align: top;"><td><code>hdf5_opts::append </code></td><td> </td><td>instead of overwriting the file, append the specified dataset to the file;<br>the specified dataset must not already exist in the file</td></tr>
|
|
<tr style="vertical-align: top;"><td><code>hdf5_opts::replace</code></td><td> </td><td>instead of overwriting the file, replace the specified dataset in the file<br><b>caveat:</b> HDF5 may not automatically reclaim deleted space; use <a href="https://support.hdfgroup.org/HDF5/Tutor/cmdtooledit.html">h5repack</a> to clean HDF5 files</td></tr>
|
|
</table>
|
|
<br>
|
|
the above settings can be combined using the <code>+</code> operator; for example: <code>hdf5_opts::trans + hdf5_opts::append</code>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
By providing either <b>csv_name(</b>filename<b>,</b> header<b>)</b> or <b>csv_name(</b>filename<b>,</b> header<b>,</b> settings<b>)</b>,
|
|
the file is assumed to have data in comma separated value (CSV) text format
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
the <i>header</i> argument specifies the object which stores the separate elements of the header line; it must have the type <code><a href="#field">field<std::string></a></code>
|
|
<br>
|
|
<br>
|
|
</li>
|
|
<li>the optional <i>settings</i> argument is one of the following, or a combination thereof:
|
|
<br>
|
|
<br>
|
|
<table>
|
|
<tr style="vertical-align: top;"><td><code>csv_opts::trans </code></td><td> </td><td>save/load the data with columns transposed to rows (and vice versa)</td></tr>
|
|
<tr style="vertical-align: top;"><td><code>csv_opts::no_header</code></td><td> </td><td>assume there is no header line; the <i>header</i> argument is not referenced</td></tr>
|
|
<tr style="vertical-align: top;"><td><code>csv_opts::semicolon</code></td><td> </td><td>use semicolon (;) instead of comma (,) as the separator character</td></tr>
|
|
<tr style="vertical-align: top;"><td><code>csv_opts::strict </code></td><td> </td><td>interpret missing values as NaN (not applicable to sparse matrices)</td></tr>
|
|
</table>
|
|
<br>
|
|
the above settings can be combined using the <code>+</code> operator; for example: <code>csv_opts::trans + csv_opts::no_header</code>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 6, fill::randu);
|
|
|
|
// default save format is arma_binary
|
|
A.save("A.bin");
|
|
|
|
// save in raw_ascii format
|
|
A.save("A.txt", raw_ascii);
|
|
|
|
// save in CSV format without a header
|
|
A.save("A.csv", csv_ascii);
|
|
|
|
// save in CSV format with a header
|
|
field<std::string> header(A.n_cols);
|
|
header(0) = "foo";
|
|
header(1) = "bar"; // etc
|
|
A.save( csv_name("A.csv", header) );
|
|
|
|
// save in HDF5 format with internal dataset named as "my_data"
|
|
A.save(hdf5_name("A.h5", "my_data"));
|
|
|
|
// automatically detect format type while loading
|
|
mat B;
|
|
B.load("A.bin");
|
|
|
|
// force loading in arma_ascii format
|
|
mat C;
|
|
C.load("A.txt", arma_ascii);
|
|
|
|
|
|
// example of testing for success
|
|
mat D;
|
|
bool ok = D.load("A.bin");
|
|
|
|
if(ok == false)
|
|
{
|
|
cout << "problem with loading" << endl;
|
|
}
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="https://en.wikipedia.org/wiki/Hierarchical_Data_Format">HDF</a> in Wikipedia</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Comma-separated_values">CSV</a> in Wikipedia
|
|
<li><a href="#save_load_field">saving / loading fields</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="save_load_field"></a>
|
|
<b>saving / loading fields</b>
|
|
<br>
|
|
<br>
|
|
<table>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<b>.save( name )</b>
|
|
<br><b>.save( name, file_type )</b>
|
|
<br>
|
|
<br><b>.save( stream )</b>
|
|
<br><b>.save( stream, file_type )</b>
|
|
</td>
|
|
<td> </td>
|
|
<td>
|
|
<b>.load( name )</b>
|
|
<br><b>.load( name, file_type )</b>
|
|
<br>
|
|
<br><b>.load( stream )</b>
|
|
<br><b>.load( stream, file_type )</b>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<br>
|
|
<ul>
|
|
<li>Store/retrieve data in a file or stream (<b>caveat:</b> the stream must be opened in binary mode)</li>
|
|
<br>
|
|
<li>On success, <i>.save()</i> and <i>.load()</i> return a <i>bool</i> set to <i>true</i></li>
|
|
<br>
|
|
<li>On failure, <i>.save()</i> and <i>.load()</i> return a <i>bool</i> set to <i>false</i>; additionally, <i>.load()</i> resets the object so that it has no elements</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.
|
|
<i>load()</i> 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>
|
|
<i>.load()</i>: attempt 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>, <i>Row</i> or <i>Cube</i>
|
|
</li>
|
|
<li>
|
|
only applicable to fields of type <i>Mat</i>, <i>Col</i>, <i>Row</i> or <i>Cube</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>
|
|
<i>.load()</i>: 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>
|
|
<i>.save()</i>: 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>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div>
|
|
<hr class="greyline">
|
|
<hr class="greyline">
|
|
<br>
|
|
<br>
|
|
<font size=+1><b>Generated Vectors / Matrices / Cubes</b></font>
|
|
<br>
|
|
<br>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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 are linearly spaced from <i>start</i> to (and including) <i>end</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i>N</i> is optional; by default <i>N = 100</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Usage:
|
|
<ul>
|
|
<li>vec v = linspace(start, end, N)</li>
|
|
<li><i>vector_type</i> v = linspace<<i>vector_type</i>>(start, end, N)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> for <i>N = 1</i>, the generated vector will have a single element equal to <i>end</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec a = linspace(0, 5, 6);
|
|
|
|
rowvec b = linspace<rowvec>(5, 0, 6);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#regspace">regspace()</a></li>
|
|
<li><a href="#logspace">logspace()</a></li>
|
|
<li><a href="#randperm">randperm()</a></li>
|
|
<li><a href="#ones_standalone">ones()</a></li>
|
|
<li><a href="#interp1">interp1()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="logspace"></a>
|
|
<b>logspace( A, B )</b>
|
|
<br><b>logspace( A, B, N )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a vector with <i>N</i> elements;
|
|
the values of the elements are logarithmically spaced from <i>10<sup><font size=-1>A</font></sup></i> to (and including) <i>10<sup><font size=-1>B</font></sup></i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i>N</i> is optional; by default <i>N = 50</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Usage:
|
|
<ul>
|
|
<li>vec v = logspace(A, B, N)</li>
|
|
<li><i>vector_type</i> v = logspace<<i>vector_type</i>>(A, B, N)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec a = logspace(0, 5, 6);
|
|
|
|
rowvec b = logspace<rowvec>(5, 0, 6);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#linspace">linspace()</a></li>
|
|
<li><a href="#regspace">regspace()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="regspace"></a>
|
|
<b>regspace( start, end )</b>
|
|
<br><b>regspace( start, delta, end )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a vector with regularly spaced elements:
|
|
<br>[ <i>(start + 0*delta)</i>, <i>(start + 1*delta)</i>, <i>(start + 2*delta)</i>, <i>⋯</i>, <i>(start + M*delta)</i> ]
|
|
<br>where <i>M = floor((end-start) / delta)</i>, so that <i>(start + M*delta) ≤ end</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Similar in operation to the Matlab/Octave colon operator, ie. <i>start:end</i> and <i>start:delta:end</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If <i>delta</i> is not specified:
|
|
<ul>
|
|
<li><i>delta</i> = +1, if <i>start ≤ end</i></li>
|
|
<li><i>delta</i> = −1, if <i>start > end</i> (<b>caveat:</b> this is different to Matlab/Octave)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
An empty vector is generated when one of the following conditions is true:
|
|
<ul>
|
|
<li><i>start < end</i>, and <i>delta < 0</i></li>
|
|
<li><i>start > end</i>, and <i>delta > 0</i></li>
|
|
<li><i>delta = 0</i></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Usage:
|
|
<ul>
|
|
<li>vec v = regspace(start, end)</li>
|
|
<li>vec v = regspace(start, delta, end)</li>
|
|
<li><i>vector_type</i> v = regspace<<i>vector_type</i>>(start, end)</li>
|
|
<li><i>vector_type</i> v = regspace<<i>vector_type</i>>(start, delta, end)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec a = regspace(0, 9); // 0, 1, ..., 9
|
|
|
|
uvec b = regspace<uvec>(2, 2, 10); // 2, 4, ..., 10
|
|
|
|
ivec c = regspace<ivec>(0, -1, -10); // 0, -1, ..., -10
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> do not use <i>regspace()</i> to specify ranges for contiguous submatrix views; use <a href="#submat">span()</a> instead
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#linspace">linspace()</a></li>
|
|
<li><a href="#logspace">logspace()</a></li>
|
|
<li><a href="#randperm">randperm()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="randperm"></a>
|
|
<b>randperm( N )</b>
|
|
<br><b>randperm( N, M )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a vector with a random permutation of integers from <i>0</i> to <i>N-1</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The optional argument <i>M</i> indicates the number of elements to return,
|
|
sampled without replacement from <i>0</i> to <i>N-1</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
uvec X = randperm(10);
|
|
uvec Y = randperm(10,2);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#randi">randi()</a></li>
|
|
<li><a href="#shuffle">shuffle()</a></li>
|
|
<li><a href="#linspace">linspace()</a></li>
|
|
<li><a href="#regspace">regspace()</a></li>
|
|
<li><a href="#rng_seed">RNG seed setting</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="eye_standalone"></a>
|
|
<b>eye( n_rows, n_cols )</b>
|
|
<br>
|
|
<b>eye( size(X) )</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>mat X = eye( n_rows, n_cols )</li>
|
|
<li><i>matrix_type</i> X = eye<<i>matrix_type</i>>( n_rows, n_cols )</li>
|
|
<li><i>matrix_type</i> Y = eye<<i>matrix_type</i>>( size(X) )</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A = eye(5,5); // or: mat A(5,5,fill::eye);
|
|
|
|
fmat B = 123.0 * eye<fmat>(5,5);
|
|
|
|
cx_mat C = eye<cx_mat>( size(B) );
|
|
</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>
|
|
<li><a href="#speye">speye()</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="ones_standalone"></a>
|
|
<b>
|
|
ones( n_elem )
|
|
<br>ones( n_rows, n_cols )
|
|
<br>ones( n_rows, n_cols, n_slices )
|
|
<br>ones( size(X) )
|
|
</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>matrix_type</i> Y = ones<<i>matrix_type</i>>( size(X) )</li>
|
|
<li><i>cube_type</i> Q = ones<<i>cube_type</i>>( n_rows, n_cols, n_slices )</li>
|
|
<li><i>cube_type</i> R = ones<<i>cube_type</i>>( size(Q) )</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> specifying <i>fill::ones</i> during object construction is more compact, eg. <code>mat A(5, 6, fill::ones)</code>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec v = ones(10); // or: vec v(10, fill::ones);
|
|
uvec u = ones<uvec>(10);
|
|
rowvec r = ones<rowvec>(10);
|
|
|
|
mat A = ones(5,6); // or: mat A(5, 6, fill::ones);
|
|
fmat B = ones<fmat>(5,6);
|
|
umat C = ones<umat>(5,6);
|
|
|
|
cube Q = ones(5,6,7); // or: cube Q(5, 6, 7, fill::ones);
|
|
fcube R = ones<fcube>(5,6,7);
|
|
</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="#fill">.fill()</a></li>
|
|
<li><a href="#eye_standalone">eye()</a></li>
|
|
<li><a href="#linspace">linspace()</a></li>
|
|
<li><a href="#regspace">regspace()</a></li>
|
|
<li><a href="#zeros_standalone">zeros()</a></li>
|
|
<li><a href="#randu">randu()</a></li>
|
|
<li><a href="#spones">spones()</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
<br><b>zeros( size(X) )</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>matrix_type</i> Y = zeros<<i>matrix_type</i>>( size(X) )</li>
|
|
<li><i>cube_type</i> Q = zeros<<i>cube_type</i>>( n_rows, n_cols, n_slices )</li>
|
|
<li><i>cube_type</i> R = zeros<<i>cube_type</i>>( size(Q) )</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> specifying <i>fill::zeros</i> during object construction is more compact, eg. <code>mat A(5, 6, fill::zeros)</code>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec v = zeros(10); // or: vec v(10, fill::zeros);
|
|
uvec u = zeros<uvec>(10);
|
|
rowvec r = zeros<rowvec>(10);
|
|
|
|
mat A = zeros(5,6); // or: mat A(5, 6, fill::zeros);
|
|
fmat B = zeros<fmat>(5,6);
|
|
umat C = zeros<umat>(5,6);
|
|
|
|
cube Q = zeros(5,6,7); // or: cube Q(5, 6, 7, fill::zeros);
|
|
fcube R = zeros<fcube>(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>, <i>SpMat</i> and <i>Cube</i>)</li>
|
|
<li><a href="#fill">.fill()</a></li>
|
|
<li><a href="#ones_standalone">ones()</a></li>
|
|
<li><a href="#randu">randu()</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="randu"></a>
|
|
<b>randu( )</b>
|
|
<br><b>randu( distr_param(a,b) )</b>
|
|
<br>
|
|
<br><b>randu( n_elem )</b>
|
|
<br><b>randu( n_elem, distr_param(a,b) )</b>
|
|
<br>
|
|
<br><b>randu( n_rows, n_cols )</b>
|
|
<br><b>randu( n_rows, n_cols, distr_param(a,b) )</b>
|
|
<br>
|
|
<br><b>randu( n_rows, n_cols, n_slices )</b>
|
|
<br><b>randu( n_rows, n_cols, n_slices, distr_param(a,b) )</b>
|
|
<br>
|
|
<br><b>randu( size(X) )</b>
|
|
<br><b>randu( size(X), distr_param(a,b) )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a scalar, vector, matrix or cube with the elements set to random <b>floating point</b> values uniformly distributed in the [a,b] interval
|
|
</li>
|
|
<br>
|
|
<li>The default distribution parameters are <i>a = 0</i> and <i>b = 1</i>
|
|
</li>
|
|
<br>
|
|
<li>For complex elements, the real and imaginary parts are treated separately
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Usage:
|
|
<ul>
|
|
<li><i>scalar_type</i> s = randu<<i>scalar_type</i>>( ), where <i>scalar_type</i> ∈ { float, double, <a href="#cx_double">cx_float</a>, <a href="#cx_double">cx_double</a> }</li>
|
|
<li><i>scalar_type</i> s = randu<<i>scalar_type</i>>( distr_param(a,b) ), where <i>scalar_type</i> ∈ { float, double, <a href="#cx_double">cx_float</a>, <a href="#cx_double">cx_double</a> }</li>
|
|
<br>
|
|
<li><i>vector_type</i> v = randu<<i>vector_type</i>>( n_elem )</li>
|
|
<li><i>vector_type</i> v = randu<<i>vector_type</i>>( n_elem, distr_param(a,b) )</li>
|
|
<br>
|
|
<li><i>matrix_type</i> X = randu<<i>matrix_type</i>>( n_rows, n_cols )</li>
|
|
<li><i>matrix_type</i> X = randu<<i>matrix_type</i>>( n_rows, n_cols, distr_param(a,b) )</li>
|
|
<br>
|
|
<li><i>cube_type</i> Q = randu<<i>cube_type</i>>( n_rows, n_cols, n_slices )</li>
|
|
<li><i>cube_type</i> Q = randu<<i>cube_type</i>>( n_rows, n_cols, n_slices, distr_param(a,b) )</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> 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>
|
|
double a = randu();
|
|
double b = randu(distr_param(10,20));
|
|
|
|
vec v1 = randu(5); // or: vec v1(5, fill::randu);
|
|
vec v2 = randu(5, distr_param(10,20));
|
|
|
|
rowvec r1 = randu<rowvec>(5);
|
|
rowvec r2 = randu<rowvec>(5, distr_param(10,20));
|
|
|
|
mat A1 = randu(5, 6); // or: mat A1(5, 6, fill::randu);
|
|
mat A2 = randu(5, 6, distr_param(10,20));
|
|
|
|
fmat B1 = randu<fmat>(5, 6);
|
|
fmat B2 = randu<fmat>(5, 6, distr_param(10,20));
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#randu_randn_member">.randu()</a> (member function)</li>
|
|
<li><a href="#randn">randn()</a></li>
|
|
<li><a href="#randg">randg()</a></li>
|
|
<li><a href="#randi">randi()</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="#sprandu_sprandn">sprandu()</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
<li><a href="#rng_seed">RNG seed setting</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Uniform_distribution_(continuous)">uniform distribution in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="randn"></a>
|
|
<b>randn( )</b>
|
|
<br><b>randn( distr_param(mu,sd) )</b>
|
|
<br>
|
|
<br><b>randn( n_elem )</b>
|
|
<br><b>randn( n_elem, distr_param(mu,sd) )</b>
|
|
<br>
|
|
<br><b>randn( n_rows, n_cols )</b>
|
|
<br><b>randn( n_rows, n_cols, distr_param(mu,sd) )</b>
|
|
<br>
|
|
<br><b>randn( n_rows, n_cols, n_slices )</b>
|
|
<br><b>randn( n_rows, n_cols, n_slices, distr_param(mu,sd) )</b>
|
|
<br>
|
|
<br><b>randn( size(X) )</b>
|
|
<br><b>randn( size(X), distr_param(mu,sd) )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a scalar, vector, matrix or cube with the elements set to random values with normal / Gaussian distribution, parameterised by mean <i>mu</i> and standard deviation <i>sd</i>
|
|
</li>
|
|
<br>
|
|
<li>The default distribution parameters are <i>mu = 0</i> and <i>sd = 1</i>
|
|
</li>
|
|
<br>
|
|
<li>For complex elements, the real and imaginary parts are treated separately
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Usage:
|
|
<ul>
|
|
<li><i>scalar_type</i> s = randn<<i>scalar_type</i>>( ), where <i>scalar_type</i> ∈ { float, double, <a href="#cx_double">cx_float</a>, <a href="#cx_double">cx_double</a> }</li>
|
|
<li><i>scalar_type</i> s = randn<<i>scalar_type</i>>( distr_param(mu,sd) ), where <i>scalar_type</i> ∈ { float, double, <a href="#cx_double">cx_float</a>, <a href="#cx_double">cx_double</a> }</li>
|
|
<br>
|
|
<li><i>vector_type</i> v = randn<<i>vector_type</i>>( n_elem )</li>
|
|
<li><i>vector_type</i> v = randn<<i>vector_type</i>>( n_elem, distr_param(mu,sd) )</li>
|
|
<br>
|
|
<li><i>matrix_type</i> X = randn<<i>matrix_type</i>>( n_rows, n_cols )</li>
|
|
<li><i>matrix_type</i> X = randn<<i>matrix_type</i>>( n_rows, n_cols, distr_param(mu,sd) )</li>
|
|
<br>
|
|
<li><i>cube_type</i> Q = randn<<i>cube_type</i>>( n_rows, n_cols, n_slices )</li>
|
|
<li><i>cube_type</i> Q = randn<<i>cube_type</i>>( n_rows, n_cols, n_slices, distr_param(mu,sd) )</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
double a = randn();
|
|
double b = randn(distr_param(10,5));
|
|
|
|
vec v1 = randn(5); // or: vec v1(5, fill::randn);
|
|
vec v2 = randn(5, distr_param(10,5));
|
|
|
|
rowvec r1 = randn<rowvec>(5);
|
|
rowvec r2 = randn<rowvec>(5, distr_param(10,5));
|
|
|
|
mat A1 = randn(5, 6); // or: mat A1(5, 6, fill::randn);
|
|
mat A2 = randn(5, 6, distr_param(10,5));
|
|
|
|
fmat B1 = randn<fmat>(5, 6);
|
|
fmat B2 = randn<fmat>(5, 6, distr_param(10,5));
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#randu_randn_member">.randn()</a> (member function)</li>
|
|
<li><a href="#randu">randu()</a></li>
|
|
<li><a href="#randg">randg()</a></li>
|
|
<li><a href="#randi">randi()</a></li>
|
|
<li><a href="#mvnrnd">mvnrnd()</a></li>
|
|
<li><a href="#normpdf">normpdf()</a></li>
|
|
<li><a href="#imbue">.imbue()</a></li>
|
|
<li><a href="#sprandu_sprandn">sprandn()</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
<li><a href="#rng_seed">RNG seed setting</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="randg"></a>
|
|
<b>randg( )</b>
|
|
<br><b>randg( distr_param(a,b) )</b>
|
|
<br>
|
|
<br><b>randg( n_elem )</b>
|
|
<br><b>randg( n_elem, distr_param(a,b) )</b>
|
|
<br>
|
|
<br><b>randg( n_rows, n_cols )</b>
|
|
<br><b>randg( n_rows, n_cols, distr_param(a,b) )</b>
|
|
<br>
|
|
<br><b>randg( n_rows, n_cols, n_slices )</b>
|
|
<br><b>randg( n_rows, n_cols, n_slices, distr_param(a,b) )</b>
|
|
<br>
|
|
<br><b>randg( size(X) )</b>
|
|
<br><b>randg( size(X), distr_param(a,b) )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a scalar, vector, matrix or cube with the elements set to random values from a gamma distribution:
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;"> </td><td style="vertical-align: top;"> </td><td style="vertical-align: top;"><i>x<sup> a-1</sup> exp( -x / b )</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><i>p<font size=+1>(</font>x | a,b<font size=+1>)</font></i></td><td style="vertical-align: top;"> <font size=+1>=</font> </td><td style="vertical-align: top;"><font size=+1><b><hr></b></font></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> </td><td style="vertical-align: top;"> </td><td style="vertical-align: top; text-align: center;"><i>b<sup> a</sup> Γ(a)</i></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
where <i>a</i> is the shape parameter and <i>b</i> is the scale parameter, with constraints <i>a > 0</i> and <i>b > 0</i>
|
|
</li>
|
|
<br>
|
|
<li>The default distribution parameters are <i>a = 1</i> and <i>b = 1</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Usage:
|
|
<ul>
|
|
<li><i>scalar_type</i> s = randg<<i>scalar_type</i>>( ), where <i>scalar_type</i> is either <i>float</i> or <i>double</i></li>
|
|
<li><i>scalar_type</i> s = randg<<i>scalar_type</i>>( distr_param(a,b) ), where <i>scalar_type</i> is either <i>float</i> or <i>double</i></li>
|
|
<br>
|
|
<li><i>vector_type</i> v = randg<<i>vector_type</i>>( n_elem )</li>
|
|
<li><i>vector_type</i> v = randg<<i>vector_type</i>>( n_elem, distr_param(a,b) )</li>
|
|
<br>
|
|
<li><i>matrix_type</i> X = randg<<i>matrix_type</i>>( n_rows, n_cols )</li>
|
|
<li><i>matrix_type</i> X = randg<<i>matrix_type</i>>( n_rows, n_cols, distr_param(a,b) )</li>
|
|
<br>
|
|
<li><i>cube_type</i> Q = randg<<i>cube_type</i>>( n_rows, n_cols, n_slices )</li>
|
|
<li><i>cube_type</i> Q = randg<<i>cube_type</i>>( n_rows, n_cols, n_slices, distr_param(a,b) )</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec v1 = randg(100);
|
|
vec v2 = randg(100, distr_param(2,1));
|
|
|
|
rowvec r1 = randg<rowvec>(100);
|
|
rowvec r2 = randg<rowvec>(100, distr_param(2,1));
|
|
|
|
mat A1 = randg(10, 10);
|
|
mat A2 = randg(10, 10, distr_param(2,1));
|
|
|
|
fmat B1 = randg<fmat>(10, 10);
|
|
fmat B2 = randg<fmat>(10, 10, distr_param(2,1));
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#randu">randu()</a></li>
|
|
<li><a href="#randn">randn()</a></li>
|
|
<li><a href="#randi">randi()</a></li>
|
|
<li><a href="#chi2rnd">chi2rnd()</a></li>
|
|
<li><a href="#imbue">.imbue()</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
<li><a href="#rng_seed">RNG seed setting</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Gamma_distribution">gamma distribution in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="randi"></a>
|
|
<b>randi( )</b>
|
|
<br><b>randi( distr_param(a,b) )</b>
|
|
<br>
|
|
<br><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>
|
|
<br>
|
|
<br><b>randi( size(X) )</b>
|
|
<br><b>randi( size(X), distr_param(a,b) )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a scalar, vector, matrix or cube with the elements set to random <b>integer</b> values uniformly distributed 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>scalar_type</i> v = randi<<i>scalar_type</i>>( )</li>
|
|
<li><i>scalar_type</i> v = randi<<i>scalar_type</i>>( distr_param(a,b) )</li>
|
|
<br>
|
|
<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>
|
|
<b>Caveat:</b> to generate a matrix with random floating point values (ie. <i>float</i> or <i>double</i>) instead of integers, use <a href="#randu">randu()</a> instead
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
int a = randi();
|
|
int b = randi(distr_param(-10, +20));
|
|
|
|
imat A1 = randi(5, 6);
|
|
imat A2 = randi(5, 6, distr_param(-10, +20));
|
|
|
|
mat B1 = randi<mat>(5, 6);
|
|
mat B2 = randi<mat>(5, 6, distr_param(-10, +20));
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#randu">randu()</a></li>
|
|
<li><a href="#randperm">randperm()</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="#size">size()</a></li>
|
|
<li><a href="#rng_seed">RNG seed setting</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="speye"></a>
|
|
<b>speye( n_rows, n_cols )</b>
|
|
<br>
|
|
<b>speye( size(X) )</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>
|
|
<li><i>sparse_matrix_type</i> Y = speye<<i>sparse_matrix_type</i>>( size(X) )</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="#spones">spones()</a></li>
|
|
<li><a href="#sprandu_sprandn">sprandu() & sprandn()</a></li>
|
|
<li><a href="#eye_standalone">eye()</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="spones"></a>
|
|
<b>spones( A )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a sparse matrix with the same structure as sparse matrix <i>A</i>,
|
|
but with the non-zero elements set to one
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
sp_mat A = sprandu<sp_mat>(100, 200, 0.1);
|
|
|
|
sp_mat B = spones(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#speye">speye()</a></li>
|
|
<li><a href="#sprandu_sprandn">sprandu() & sprandn()</a></li>
|
|
<li><a href="#ones_standalone">ones()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="sprandu_sprandn"></a>
|
|
<b>sprandu( n_rows, n_cols, density )</b>
|
|
<br><b>sprandn( n_rows, n_cols, density )</b>
|
|
<br>
|
|
<br><b>sprandu( size(X), density )</b>
|
|
<br><b>sprandn( size(X), 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>
|
|
<li><i>sparse_matrix_type</i> Y = sprandu<<i>sparse_matrix_type</i>>( size(X), density )</li>
|
|
</ul>
|
|
</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="#spones">spones()</a></li>
|
|
<li><a href="#randu">randu()</a></li>
|
|
<li><a href="#randn">randn()</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
<li><a href="#rng_seed">RNG seed setting</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Uniform_distribution_(continuous)">uniform distribution in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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(5, fill::randu);
|
|
mat X = toeplitz(A);
|
|
mat Y = circ_toeplitz(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="https://mathworld.wolfram.com/ToeplitzMatrix.html">Toeplitz matrix in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Toeplitz_matrix">Toeplitz matrix in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Circulant_matrix">Circulant matrix in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div>
|
|
<hr class="greyline">
|
|
<hr class="greyline">
|
|
<br>
|
|
<br>
|
|
<font size=+1><b>Functions of Vectors / Matrices / Cubes</b></font>
|
|
<br>
|
|
<br>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="abs"></a>
|
|
<b>abs( X )</b>
|
|
<ul>
|
|
<li>
|
|
Obtain the magnitude of each element
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Usage for non-complex X:
|
|
<ul>
|
|
<li>Y = abs(X)</li>
|
|
<li>X and Y must have the same matrix type or cube type, such as <i>mat</i> or <i>cube</i></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Usage for complex X:
|
|
<ul>
|
|
<li><i>real_object_type</i> Y = abs(X)</li>
|
|
<li>The type of X must be a complex matrix or complex cube, such as <i>cx_mat</i> or <i>cx_cube</i></li>
|
|
<li>The type of Y must be the real counterpart to the type of X; if X has the type <i>cx_mat</i>, then the type of Y must be <i>mat</i>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
mat B = abs(A);
|
|
|
|
cx_mat X(5, 5, fill::randu);
|
|
mat Y = abs(X);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#arg">arg()</a></li>
|
|
<li><a href="#conj">conj()</a></li>
|
|
<li><a href="#imag_real">imag() / real()</a></li>
|
|
<li><a href="#pow">pow()</a></li>
|
|
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="accu"></a>
|
|
<b>accu( X )</b>
|
|
<ul>
|
|
<li>
|
|
Accumulate (sum) all elements of a vector, matrix or cube
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 6, fill::randu);
|
|
mat B(5, 6, fill::randu);
|
|
|
|
double x = accu(A);
|
|
|
|
double y = accu(A % B);
|
|
|
|
// accu(A % B) is a "multiply-and-accumulate" operation
|
|
// as operator % performs element-wise multiplication
|
|
</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="#trace">trace()</a></li>
|
|
<li><a href="#stats_fns">mean()</a></li>
|
|
<li><a href="#dot">dot()</a></li>
|
|
<li><a href="#as_scalar">as_scalar()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="affmul"></a>
|
|
<b>affmul( A, B )</b>
|
|
<ul>
|
|
<li>Multiply matrix <i>A</i> by an automatically extended form of <i>B</i></li>
|
|
<br>
|
|
<li><i>A</i> is typically an affine transformation matrix</li>
|
|
<br>
|
|
<li><i>B</i> can be a vector or matrix, and is treated as having an additional row of ones</li>
|
|
<br>
|
|
<li>The number of columns in <i>A</i> must be equal to number of rows in the extended form of <i>B</i> (ie. A.n_cols = B.n_rows+1)</li>
|
|
<br>
|
|
<li>If <i>A</i> is 3x3 and <i>B</i> is 2x1, the equivalent matrix multiplication is:</li>
|
|
<pre>
|
|
⎡ C<sub>0</sub> ⎤ ⎡ A<sub>00</sub> A<sub>01</sub> A<sub>02</sub> ⎤ ⎡ B<sub>0</sub> ⎤
|
|
⎢ C<sub>1</sub> ⎥ = ⎢ A<sub>10</sub> A<sub>11</sub> A<sub>12</sub> ⎥ x ⎢ B<sub>1</sub> ⎥
|
|
⎣ C<sub>2</sub> ⎦ ⎣ A<sub>20</sub> A<sub>21</sub> A<sub>22</sub> ⎦ ⎣ 1<sub> </sub> ⎦
|
|
</pre>
|
|
<li>If <i>A</i> is 2x3 and <i>B</i> is 2x1, the equivalent matrix multiplication is:</li>
|
|
<pre>
|
|
⎡ C<sub>0</sub> ⎤ ⎡ A<sub>00</sub> A<sub>01</sub> A<sub>02</sub> ⎤ ⎡ B<sub>0</sub> ⎤
|
|
⎣ C<sub>1</sub> ⎦ = ⎣ A<sub>10</sub> A<sub>11</sub> A<sub>12</sub> ⎦ x ⎢ B<sub>1</sub> ⎥
|
|
⎣ 1<sub> </sub> ⎦
|
|
</pre>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(2, 3, fill::randu);
|
|
vec B(2, fill::randu);
|
|
|
|
vec C = affmul(A,B);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#operators">math operators</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Affine_transformation">Affine transformation in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Transformation_matrix">Transformation matrix in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
<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>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec V(10, fill::randu);
|
|
mat X(5, 5, fill::randu);
|
|
|
|
|
|
// 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="#approx_equal">approx_equal()</a></li>
|
|
<li><a href="#find">find()</a></li>
|
|
<li><a href="#is_zero">.is_zero()</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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
<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>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec V(10, fill::randu);
|
|
mat X(5, 5, fill::randu);
|
|
|
|
|
|
// 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="#approx_equal">approx_equal()</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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="approx_equal"></a>
|
|
<b>approx_equal( A, B, method, tol )</b>
|
|
<br><b>approx_equal( A, B, method, abs_tol, rel_tol )</b>
|
|
<ul>
|
|
<li>
|
|
Return <i>true</i> if all corresponding elements in <i>A</i> and <i>B</i> are approximately equal
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Return <i>false</i> if any of the corresponding elements in <i>A</i> and <i>B</i> are not approximately equal, or if <i>A</i> and <i>B</i> have different dimensions
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i>method</i> controls how the approximate equality is determined; it is one of:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>"absdiff"</code></td><td> ↦ </td><td>scalars <i>x</i> and <i>y</i> are considered equal if <i>|x − y|  ≤  tol</i></td></tr>
|
|
<tr><td><code>"reldiff"</code></td><td> ↦ </td><td>scalars <i>x</i> and <i>y</i> are considered equal if <i>|x − y| / max( |x|, |y| )  ≤  tol</i></td></tr>
|
|
<tr><td><code>"both"</code></td><td> ↦ </td><td>scalars <i>x</i> and <i>y</i> are considered equal if <i>|x − y|  ≤  abs_tol</i> <b>or</b> <i>|x − y| / max( |x|, |y| )  ≤  rel_tol</i></td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
mat B = A + 0.001;
|
|
|
|
bool same1 = approx_equal(A, B, "absdiff", 0.002);
|
|
|
|
|
|
mat C = 1000 * randu<mat>(5,5);
|
|
mat D = C + 1;
|
|
|
|
bool same2 = approx_equal(C, D, "reldiff", 0.1);
|
|
|
|
bool same3 = approx_equal(C, D, "both", 2, 0.1);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#all">all()</a></li>
|
|
<li><a href="#any">any()</a></li>
|
|
<li><a href="#find">find()</a></li>
|
|
<li><a href="#is_zero">.is_zero()</a></li>
|
|
<li><a href="#operators">relational operators</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="arg"></a>
|
|
<b>arg( X )</b>
|
|
<ul>
|
|
<li>
|
|
Obtain the phase angle (in radians) of each element
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Usage for non-complex X:
|
|
<ul>
|
|
<li>Y = arg(X)</li>
|
|
<li>X and Y must have the same matrix type or cube type, such as <i>mat</i> or <i>cube</i></li>
|
|
<li>non-complex elements are treated as complex elements with zero imaginary component
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Usage for complex X:
|
|
<ul>
|
|
<li><i>real_object_type</i> Y = arg(X)</li>
|
|
<li>The type of X must be a complex matrix or complex cube, such as <i>cx_mat</i> or <i>cx_cube</i></li>
|
|
<li>The type of Y must be the real counterpart to the type of X; if X has the type <i>cx_mat</i>, then the type of Y must be <i>mat</i>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
cx_mat A(5, 5, fill::randu);
|
|
mat B = arg(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#abs">abs()</a></li>
|
|
<li><a href="#trig_fns">atan2()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Argument_(complex_analysis)">Argument (complex analysis) in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/ComplexArgument.html">Complex Argument in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
Optimised expression evaluations are automatically used when a binary or trinary expression is given (ie. 2 or 3 terms)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
rowvec r(5, fill::randu);
|
|
colvec q(5, fill::randu);
|
|
|
|
mat X(5, 5, fill::randu);
|
|
|
|
// examples of expressions which have optimised implementations
|
|
|
|
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="#as_col_row">.as_col() / .as_row()</a></li>
|
|
<li><a href="#vectorise">vectorise()</a></li>
|
|
<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>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="clamp"></a>
|
|
<b>clamp( X, min_val, max_val )</b>
|
|
<ul>
|
|
<li>
|
|
Create a copy of <i>X</i> with each element clamped to the [<i>min_val</i>, <i>max_val</i>] interval;
|
|
<br>any value lower than <i>min_val</i> will be set to <i>min_val</i>, and any value higher than <i>max_val</i> will be set to <i>max_val</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For objects with complex elements, the real and imaginary components are clamped separately
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If <i>X</i> is a sparse matrix, clamping is applied only to the non-zero elements
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
mat B = clamp(A, 0.2, 0.8);
|
|
|
|
mat C = clamp(A, A.min(), 0.8);
|
|
|
|
mat D = clamp(A, 0.2, A.max());
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#clamp_member">.clamp()</a> (member function)</li>
|
|
<li><a href="#min_and_max_member">.min() & .max()</a></li>
|
|
<li><a href="#clean">.clean()</a></li>
|
|
<li><a href="#replace">.replace()</a></li>
|
|
<li><a href="#find">find()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="cond"></a>
|
|
<b>cond( A )</b>
|
|
<ul>
|
|
<li>Return the condition number of matrix <i>A</i> (the ratio of the largest singular value to the smallest)</li>
|
|
<br>
|
|
<li>Matrix <i>A</i> is well-conditioned when the condition number is close to 1</li>
|
|
<br>
|
|
<li>Matrix <i>A</i> is ill-conditioned (poorly conditioned) when the condition number is large</li>
|
|
<br>
|
|
<li>The computation is based on singular value decomposition</li>
|
|
<br>
|
|
<li><b>Caveat:</b> calculating the approximate reciprocal condition number via <a href="#rcond">rcond()</a> is considerably more efficient</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
double c = cond(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#rcond">rcond()</a></li>
|
|
<li><a href="#rank">rank()</a></li>
|
|
<li><a href="#inv">inv()</a></li>
|
|
<li><a href="#svd">svd()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/ConditionNumber.html">condition number in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Condition_number">condition number in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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(5, 5, fill::randu);
|
|
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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="conv_to"></a>
|
|
<b>
|
|
conv_to< <i>type</i> >::from( X )
|
|
</b>
|
|
<ul>
|
|
<li>
|
|
Convert (cast) from one matrix type to another (eg. <i>mat</i> to <i>imat</i>), or one cube type to another (eg. <i>cube</i> to <i>icube</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(5, 5, fill::randu);
|
|
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="#abs">abs()</a></li>
|
|
<li><a href="#imag_real">imag() / real()</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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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(3, fill::randu);
|
|
vec b(3, fill::randu);
|
|
|
|
vec c = cross(a,b);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#dot">dot()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Cross_product">Cross product in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/CrossProduct.html">Cross product in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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(5, 5, fill::randu);
|
|
mat B = cumsum(A);
|
|
mat C = cumsum(A, 1);
|
|
|
|
vec x(10, fill::randu);
|
|
vec y = cumsum(x);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#cumprod">cumprod()</a></li>
|
|
<li><a href="#accu">accu()</a></li>
|
|
<li><a href="#sum">sum()</a></li>
|
|
<li><a href="#diff">diff()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="cumprod"></a>
|
|
<b>cumprod( V )</b>
|
|
<br><b>cumprod( X )</b>
|
|
<br><b>cumprod( X, dim )</b>
|
|
<ul>
|
|
<li>
|
|
For vector <i>V</i>, return a vector of the same orientation, containing the cumulative product of elements
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For matrix <i>X</i>, return a matrix containing the cumulative 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>
|
|
mat A(5, 5, fill::randu);
|
|
mat B = cumprod(A);
|
|
mat C = cumprod(A, 1);
|
|
|
|
vec x(10, fill::randu);
|
|
vec y = cumprod(x);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#cumsum">cumsum()</a></li>
|
|
<li><a href="#prod">prod()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="det"></a>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><b>val = det( A )</b></td><td> </td><td>(form 1)</td></tr>
|
|
<tr><td><b>det( val, A )</b></td><td> </td><td>(form 2)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>Calculate the determinant of square matrix <i>A</i>, based on LU decomposition</li>
|
|
<br>
|
|
<li>form 1: return the determinant</li>
|
|
<br>
|
|
<li>form 2: store the calculated determinant in <i>val</i> and return a bool indicating success</li>
|
|
<br>
|
|
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the calculation fails:
|
|
<ul>
|
|
<li><i>val = det(A)</i> throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>det(val,A)</i> returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li><b>Caveat:</b> <a href="#log_det">log_det()</a> is preferred, as it's less likely to suffer from numerical underflows/overflows</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
double val1 = det(A); // form 1
|
|
|
|
double val2;
|
|
bool success = det(val2, A); // form 2
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#log_det">log_det()</a></li>
|
|
<li><a href="#rcond">rcond()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Determinant.html">determinant in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Determinant">determinant in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="diagmat"></a>
|
|
<b>diagmat( V )</b>
|
|
<br><b>diagmat( V, k )</b>
|
|
<br>
|
|
<br><b>diagmat( X )</b>
|
|
<br><b>diagmat( X, k )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a diagonal matrix from vector <i>V</i> or matrix <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Given vector <i>V</i>:
|
|
<ul>
|
|
<li>generate a square matrix with the <i>k</i>-th diagonal containing a copy of the vector; all other elements are set to zero</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Given matrix <i>X</i>:
|
|
<ul>
|
|
<li>generate a matrix with the <i>k</i>-th diagonal containing a copy of the <i>k</i>-th diagonal of <i>X</i>; all other elements are set to zero</li>
|
|
<li>if <i>X</i> is an expression, the evaluation of the expression aims to calculate only the diagonal elements</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>The argument <i>k</i> is optional; by default <i>k = 0</i></li>
|
|
<br>
|
|
<li>
|
|
The argument <i>k</i> specifies the diagonal to use:
|
|
<ul>
|
|
<li><i>k = 0</i> indicates the main diagonal (default setting)</li>
|
|
<li><i>k < 0</i> indicates the <i>k</i>-th sub-diagonal (below main diagonal, towards bottom-left corner)</li>
|
|
<li><i>k > 0</i> indicates the <i>k</i>-th super-diagonal (above main diagonal, towards top-right corner)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
mat B = diagmat(A);
|
|
mat C = diagmat(A,1);
|
|
|
|
vec v(5, fill::randu);
|
|
mat D = diagmat(v);
|
|
mat E = diagmat(v,1);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#diag">.diag()</a></li>
|
|
<li><a href="#is_diagmat">.is_diagmat()</a></li>
|
|
<li><a href="#diagvec">diagvec()</a></li>
|
|
<li><a href="#diags_spdiags">diags() / spdiags()</a></li>
|
|
<li><a href="#trace">trace()</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>
|
|
<li><a href="https://en.wikipedia.org/wiki/Diagonal_matrix">diagonal matrix in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="diagvec"></a>
|
|
<b>diagvec( X )</b>
|
|
<br><b>diagvec( X, k )</b>
|
|
<ul>
|
|
<li>
|
|
Extract the <i>k</i>-th diagonal from matrix <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>The argument <i>k</i> is optional; by default <i>k = 0</i></li>
|
|
<br>
|
|
<li>
|
|
The argument <i>k</i> specifies the diagonal to extract:
|
|
<ul>
|
|
<li><i>k = 0</i> indicates the main diagonal (default setting)</li>
|
|
<li><i>k < 0</i> indicates the <i>k</i>-th sub-diagonal (below main diagonal, towards bottom-left corner)</li>
|
|
<li><i>k > 0</i> indicates the <i>k</i>-th super-diagonal (above main diagonal, towards top-right corner)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The extracted diagonal is interpreted as a column vector
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If <i>X</i> is an expression, the evaluation of the expression aims to calculate only the diagonal elements
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="diags_spdiags"></a>
|
|
<table>
|
|
<tbody>
|
|
<tr><td style="text-align: right;"><b>diags( V, D, n_rows, n_cols )</b></td></tr>
|
|
<tr><td style="text-align: right;"><b>spdiags( V, D, n_rows, n_cols )</b></td></tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
Generate a matrix with diagonals specified by vector <i>D</i> copied from corresponding column vectors in matrix <i>V</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Function <i>diags()</i> generates a dense matrix, while function <i>spdiags()</i> generates a sparse matrix; in both cases the generated matrix has the same element type as matrix <i>V</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Given vector <i>D</i> must be a vector of type <a href="#Col">ivec</a> or <a href="#Row">irowvec</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The number of columns in given matrix <i>V</i> must match the number of elements in vector <i>D</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Each element in vector <i>D</i> specifies diagonal <i>k</i>, where:
|
|
<ul>
|
|
<li><i>k = 0</i> indicates the main diagonal</li>
|
|
<li><i>k < 0</i> indicates the <i>k</i>-th sub-diagonal (below main diagonal, towards bottom-left corner)</li>
|
|
<li><i>k > 0</i> indicates the <i>k</i>-th super-diagonal (above main diagonal, towards top-right corner)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For <i>k < 0</i>, vectors from matrix <i>V</i> are truncated at the end
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For <i>k > 0</i>, vectors from matrix <i>V</i> are truncated from the start
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat V(10, 3, fill::randu);
|
|
|
|
ivec D = {-1, 0, +1};
|
|
|
|
mat X = diags(V, D, 10, 10);
|
|
|
|
sp_mat Y = spdiags(V, D, 10, 10);
|
|
</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="https://en.wikipedia.org/wiki/Band_matrix">band matrix in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="diff"></a>
|
|
<b>diff( V )</b>
|
|
<br><b>diff( V, k )</b>
|
|
<br>
|
|
<br><b>diff( X )</b>
|
|
<br><b>diff( X, k )</b>
|
|
<br><b>diff( X, k, dim )</b>
|
|
<ul>
|
|
<li>
|
|
For vector <i>V</i>, return a vector of the same orientation, containing the differences between consecutive elements
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For matrix <i>X</i>, return a matrix containing the differences between consecutive elements in each column (<i>dim = 0</i>), or each row (<i>dim = 1</i>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The optional argument <i>k</i> indicates that the differences are calculated recursively <i>k</i> times; by default <i>k = 1</i> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The resulting number of differences is <i>n − k</i>, where <i>n</i> is the number of elements; if <i>n ≤ k</i>, the number of differences is zero (ie. an empty vector/matrix is returned)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i>dim</i> is optional; by default <i>dim = 0</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec a = linspace<vec>(1,10,10);
|
|
|
|
vec b = diff(a);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#trapz">trapz()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Numerical_differentiation">numerical differentiation in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/NumericalDifferentiation.html">numerical differentiation in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>, treating <i>A</i> and <i>B</i> as vectors
|
|
</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 dot product; equivalent to <i>dot(A,B)  /  ( ∥A∥·∥B∥ )</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> <a href="#norm">norm()</a> is more robust for calculating the norm, as it handles underflows and overflows
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec a(10, fill::randu);
|
|
vec b(10, fill::randu);
|
|
|
|
double x = dot(a,b);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#norm">norm()</a></li>
|
|
<li><a href="#as_scalar">as_scalar()</a></li>
|
|
<li><a href="#cross">cross()</a></li>
|
|
<li><a href="#conj">conj()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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(4, 5, fill::randu);
|
|
mat B = eps(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#constants">datum::eps</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Floating-PointArithmetic.html">Floating-Point Arithmetic in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/IEEE_754-2008">IEEE Standard for Floating-Point Arithmetic in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="expmat"></a>
|
|
<b>B = expmat( A )</b>
|
|
<br><b>expmat( B, A )</b>
|
|
<ul>
|
|
<li>Matrix exponential of general square matrix <i>A</i></li>
|
|
<br>
|
|
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the matrix exponential cannot be found:
|
|
<ul>
|
|
<li><i>B = expmat(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>expmat(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>the matrix exponential operation is generally <b>not</b> the same as applying the <a href="#misc_fns">exp()</a> function to each element</li>
|
|
<li>if matrix <i>A</i> is symmetric, <a href="#expmat_sym">expmat_sym()</a> is faster</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
mat B = expmat(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#expmat_sym">expmat_sym()</a></li>
|
|
<li><a href="#logmat">logmat()</a></li>
|
|
<li><a href="#sqrtmat">sqrtmat()</a></li>
|
|
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Matrix_exponential">matrix exponential in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/MatrixExponential.html">matrix exponential in MathWorld</a></li>
|
|
<li><a href="http://doi.org/10.1137/S00361445024180">Nineteen Dubious Ways to Compute the Exponential of a Matrix, Twenty-Five Years Later</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="expmat_sym"></a>
|
|
<b>B = expmat_sym( A )</b>
|
|
<br><b>expmat_sym( B, A )</b>
|
|
<ul>
|
|
<li>Matrix exponential of symmetric/hermitian matrix <i>A</i></li>
|
|
<br>
|
|
<li>The computation is based on eigen decomposition</li>
|
|
<br>
|
|
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the matrix exponential cannot be found:
|
|
<ul>
|
|
<li><i>B = expmat_sym(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>expmat_sym(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<!--
|
|
<br>
|
|
<li><b>Caveat:</b> there is no explicit check whether <i>A</i> is symmetric/hermitian</li>
|
|
-->
|
|
<br>
|
|
<li><b>Caveat:</b> the matrix exponential operation is generally <b>not</b> the same as applying the <a href="#misc_fns">exp()</a> function to each element</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
mat B = A*A.t(); // make symmetric matrix
|
|
|
|
mat C = expmat_sym(B);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#expmat">expmat()</a></li>
|
|
<li><a href="#logmat_sympd">logmat_sympd()</a></li>
|
|
<li><a href="#sqrtmat_sympd">sqrtmat_sympd()</a></li>
|
|
<li><a href="#is_symmetric">.is_symmetric()</a></li>
|
|
<li><a href="#is_hermitian">.is_hermitian()</a></li>
|
|
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Matrix_exponential">matrix exponential in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/MatrixExponential.html">matrix exponential in MathWorld</a></li>
|
|
<li><a href="http://doi.org/10.1137/S00361445024180">Nineteen Dubious Ways to Compute the Exponential of a Matrix, Twenty-Five Years Later</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<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>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>to clamp values to an interval, <a href="#clamp">clamp()</a> is more efficient</li>
|
|
<li>to replace a specific value, <a href="#replace">.replace()</a> is more efficient</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
mat B(5, 5, fill::randu);
|
|
|
|
uvec q1 = find(A > B);
|
|
uvec q2 = find(A > 0.5);
|
|
uvec q3 = find(A > 0.5, 3, "last");
|
|
|
|
// change elements of A greater than 0.5 to 1
|
|
A.elem( find(A > 0.5) ).ones();
|
|
</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="#clamp">clamp()</a></li>
|
|
<li><a href="#transform">.transform()</a></li>
|
|
<li><a href="#find_finite">find_finite()</a></li>
|
|
<li><a href="#find_nonfinite">find_nonfinite()</a></li>
|
|
<li><a href="#find_nan">find_nan()</a></li>
|
|
<li><a href="#find_unique">find_unique()</a></li>
|
|
<li><a href="#nonzeros">nonzeros()</a></li>
|
|
<li><a href="#unique">unique()</a></li>
|
|
<li><a href="#sort_index">sort_index()</a></li>
|
|
<li><a href="#ind2sub">ind2sub()</a></li>
|
|
<li><a href="#index_min_and_index_max_member">.index_min() & .index_max()</a></li>
|
|
<li><a href="#trimat_ind">trimatu_ind() / trimatl_ind()</a></li>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
<li><a href="#subcube">subcube views</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="find_finite"></a>
|
|
<b>find_finite( X )</b>
|
|
<ul>
|
|
<li>Return a column vector containing the indices of elements of <i>X</i> that are finite (ie. not ±Inf and not NaN)</li>
|
|
<br>
|
|
<li>The output vector must have the type <a href="#Col">uvec</a>
|
|
(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>X</i> is interpreted as a vector, with column-by-column ordering of the elements of <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
A(1,1) = datum::inf;
|
|
|
|
// accumulate only finite elements
|
|
double val = accu( A.elem( find_finite(A) ) );
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#find">find()</a></li>
|
|
<li><a href="#find_nonfinite">find_nonfinite()</a></li>
|
|
<li><a href="#find_nan">find_nan()</a></li>
|
|
<li><a href="#is_finite">.is_finite()</a></li>
|
|
<li><a href="#replace">.replace()</a></li>
|
|
<li><a href="#has_inf">.has_inf()</a></li>
|
|
<li><a href="#has_nan">.has_nan()</a></li>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="find_nonfinite"></a>
|
|
<b>find_nonfinite( X )</b>
|
|
<ul>
|
|
<li>Return a column vector containing the indices of elements of <i>X</i> that are non-finite (ie. ±Inf or NaN)</li>
|
|
<br>
|
|
<li>The output vector must have the type <a href="#Col">uvec</a>
|
|
(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>X</i> is interpreted as a vector, with column-by-column ordering of the elements of <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
A(1,1) = datum::inf;
|
|
A(2,2) = datum::nan;
|
|
|
|
// change non-finite elements to zero
|
|
A.elem( find_nonfinite(A) ).zeros();
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> to replace instances of a specific non-finite value (eg. NaN or Inf),
|
|
it is more efficient to use <a href="#replace">.replace()</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#find">find()</a></li>
|
|
<li><a href="#find_finite">find_finite()</a></li>
|
|
<li><a href="#find_nan">find_nan()</a></li>
|
|
<li><a href="#is_finite">.is_finite()</a></li>
|
|
<li><a href="#replace">.replace()</a></li>
|
|
<li><a href="#has_inf">.has_inf()</a></li>
|
|
<li><a href="#has_nan">.has_nan()</a></li>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="find_nan"></a>
|
|
<b>find_nan( X )</b>
|
|
<ul>
|
|
<li>Return a column vector containing the indices of elements of <i>X</i> that are NaN (not-a-number)</li>
|
|
<br>
|
|
<li>The output vector must have the type <a href="#Col">uvec</a>
|
|
(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>X</i> is interpreted as a vector, with column-by-column ordering of the elements of <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
A(2,3) = datum::nan;
|
|
|
|
uvec indices = find_nan(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> to replace instances of NaN values,
|
|
it is more efficient to use <a href="#replace">.replace()</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#find">find()</a></li>
|
|
<li><a href="#find_finite">find_finite()</a></li>
|
|
<li><a href="#find_nonfinite">find_nonfinite()</a></li>
|
|
<li><a href="#replace">.replace()</a></li>
|
|
<li><a href="#has_nan">.has_nan()</a></li>
|
|
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/NaN">NaN</a> in Wikipedia</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="find_unique"></a>
|
|
<b>find_unique( X )</b>
|
|
<br><b>find_unique( X, ascending_indices )</b>
|
|
<ul>
|
|
<li>Return a column vector containing the indices of unique elements of <i>X</i></li>
|
|
<br>
|
|
<li>The output vector must have the type <a href="#Col">uvec</a>
|
|
(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>X</i> is interpreted as a vector, with column-by-column ordering of the elements of <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>The <i>ascending_indices</i> argument is optional; it is one of:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td style="text-align: right;"><code>true</code></td><td> = </td><td>the returned indices are sorted to be ascending (<b>default setting</b>)</td></tr>
|
|
<tr><td style="text-align: right;"><code>false</code></td><td> = </td><td>the returned indices are in arbitrary order (faster operation)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A = { { 2, 2, 4 },
|
|
{ 4, 6, 6 } };
|
|
|
|
uvec indices = find_unique(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#find">find()</a></li>
|
|
<li><a href="#unique">unique()</a></li>
|
|
<li><a href="#intersect">intersect()</a></li>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="flip"></a>
|
|
<b>fliplr( X )</b>
|
|
<br><b>flipud( X )</b>
|
|
<ul>
|
|
<li>
|
|
<i>fliplr():</i> generate a copy of matrix <i>X</i>, with the order of the columns reversed
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>flipud():</i> generate a copy of matrix <i>X</i>, with the order of the rows reversed
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
mat B = fliplr(A);
|
|
mat C = flipud(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#reverse">reverse()</a></li>
|
|
<li><a href="#shift">shift()</a></li>
|
|
<li><a href="#swap_rows">.swap_rows() & .swap_cols()</a></li>
|
|
<li><a href="#t_st_members">.t()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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(5, 5, fill::randu);
|
|
|
|
mat A = imag(C);
|
|
mat B = real(C);
|
|
</pre>
|
|
</ul>
|
|
</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>
|
|
<li><a href="#conv_to">conv_to()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="ind2sub"></a>
|
|
<table>
|
|
<tbody>
|
|
<tr><td>uvec</td><td> sub = <b>ind2sub( size(</b>X<b>),</b> index <b>)</b></td><td> </td><td>(form 1)</td></tr>
|
|
<tr><td>umat</td><td> sub = <b>ind2sub( size(</b>X<b>),</b> vector_of_indices <b>)</b></td><td> </td><td>(form 2)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
Convert a linear index, or a vector of indices, to subscript notation
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i><b>size(</b>X<b>)</b></i> can be replaced with <i><b>size(</b>n_rows<b>,</b> n_cols<b>)</b></i> or <i><b>size(</b>n_rows<b>,</b> n_cols<b>,</b> n_slices<b>)</b></i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If an index is out of range, a <i>std::logic_error</i> exception is thrown
|
|
</li>
|
|
<br>
|
|
<li>
|
|
When only one index is given (form 1), the subscripts are returned in a vector of type <a href="#Col">uvec</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
When a vector of indices (of type <a href="#Col">uvec</a>) is given (form 2), the corresponding subscripts are returned in each column of an <i>m x n</i> matrix of type <a href="#Mat">umat</a>;
|
|
<i>m=2</i> for matrix subscripts, while <i>m=3</i> for cube subscripts
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat M(4, 5, fill::randu);
|
|
|
|
uvec s = ind2sub( size(M), 6 );
|
|
|
|
cout << "row: " << s(0) << endl;
|
|
cout << "col: " << s(1) << endl;
|
|
|
|
|
|
uvec indices = find(M > 0.5);
|
|
umat t = ind2sub( size(M), indices );
|
|
|
|
|
|
cube Q(2,3,4);
|
|
|
|
uvec u = ind2sub( size(Q), 8 );
|
|
|
|
cout << "row: " << u(0) << endl;
|
|
cout << "col: " << u(1) << endl;
|
|
cout << "slice: " << u(2) << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#size">size()</a></li>
|
|
<li><a href="#sub2ind">sub2ind()</a></li>
|
|
<li><a href="#element_access">element access</a></li>
|
|
<li><a href="#find">find()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="index_min_and_index_max_standalone"></a>
|
|
<table>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<b>index_min( V )</b>
|
|
<br><b>index_min( M )</b>
|
|
<br><b>index_min( M, dim )</b>
|
|
<br><b>index_min( Q )</b>
|
|
<br><b>index_min( Q, dim )</b>
|
|
</td>
|
|
<td> </td>
|
|
<td>
|
|
<b>index_max( V )</b>
|
|
<br><b>index_max( M )</b>
|
|
<br><b>index_max( M, dim )</b>
|
|
<br><b>index_max( Q )</b>
|
|
<br><b>index_max( Q, dim )</b>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
For vector <i>V</i>, return the linear index of the extremum value; the returned index is of type <a href="#uword">uword</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For matrix <i>M</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 column containing the index of the extremum value in the corresponding column of <i>M</i>
|
|
</li>
|
|
<li>
|
|
<i>dim = 1</i>, return a column vector (of type <a href="#Col">uvec</a> or <a href="#Mat">umat</a>),
|
|
with each row containing the index of the extremum value in the corresponding row of <i>M</i>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For cube <i>Q</i>, return a cube (of type <a href="#Cube">ucube</a>) containing the indices of extremum values of elements along dimension <i>dim</i>, where <i>dim</i> ∈ { 0, 1, 2 }
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For each column, row, or slice, the index starts at zero
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>dim</i> argument is optional; by default <i>dim = 0</i> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For objects with complex numbers, absolute values are used for comparison
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec v(10, fill::randu);
|
|
|
|
uword i = index_max(v);
|
|
double max_val_in_v = v(i);
|
|
|
|
|
|
mat M(5, 6, fill::randu);
|
|
|
|
urowvec ii = index_max(M);
|
|
ucolvec jj = index_max(M,1);
|
|
|
|
double max_val_in_col_2 = M( ii(2), 2 );
|
|
|
|
double max_val_in_row_4 = M( 4, jj(4) );
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#min_and_max">min() & max()</a></li>
|
|
<li><a href="#index_min_and_index_max_member">.index_min() & .index_max()</a> (member functions)</li>
|
|
<li><a href="#sort_index">sort_index()</a></li>
|
|
<li><a href="#find">find()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="inplace_trans"></a>
|
|
<b>inplace_trans( X )
|
|
<br>inplace_trans( X, method )
|
|
<br>
|
|
<br>inplace_strans( X )
|
|
<br>inplace_strans( X, method )
|
|
</b>
|
|
<ul>
|
|
<li>
|
|
In-place / in-situ transpose of matrix <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For real (non-complex) matrix:
|
|
<ul>
|
|
<li><i>inplace_trans()</i> performs a normal transpose</li>
|
|
<li><i>inplace_strans()</i> not applicable</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For complex matrix:
|
|
<ul>
|
|
<li><i>inplace_trans()</i> performs a Hermitian transpose (ie. the conjugate of the elements is taken during the transpose)</li>
|
|
<li><i>inplace_strans()</i> provides a transposed copy without taking the conjugate of the elements</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i>method</i> is optional
|
|
</li>
|
|
<br>
|
|
<li>
|
|
By default, a greedy transposition algorithm is used; a low-memory algorithm can be used instead by explicitly setting <i>method</i> to <code>"lowmem"</code>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The low-memory algorithm is considerably slower than the greedy 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>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(4, 5, fill::randu);
|
|
mat Y(20000, 30000, fill::randu);
|
|
|
|
inplace_trans(X); // use greedy algorithm by default
|
|
|
|
inplace_trans(Y, "lowmem"); // use low-memory (and slow) algorithm
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="intersect"></a>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><b>C = intersect( A, B )</b></td><td> </td><td>(form 1)</td></tr>
|
|
<tr><td><b>intersect( C, iA, iB, A, B )</b></td><td> </td><td>(form 2)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
For form 1:
|
|
<ul>
|
|
<li>return the unique elements common to both <i>A</i> and <i>B</i>, sorted in ascending order</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For form 2:
|
|
<ul>
|
|
<li>store in <i>C</i> the unique elements common to both <i>A</i> and <i>B</i>, sorted in ascending order</li>
|
|
<li>store in <i>iA</i> and <i>iB</i> the indices of the unique elements, such that <i>C = A.elem(iA)</i> and <i>C = B.elem(iB)</i></li>
|
|
<li><i>iA</i> and <i>iB</i> must have the type <a href="#Col">uvec</a> (ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>C</i> is a column vector if either <i>A</i> or <i>B</i> is a matrix or column vector;
|
|
<i>C</i> is a row vector if both <i>A</i> and <i>B</i> are row vectors
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For matrices and vectors with complex numbers, ordering is via absolute values
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
ivec A = regspace<ivec>(4, 1); // 4, 3, 2, 1
|
|
ivec B = regspace<ivec>(3, 6); // 3, 4, 5, 6
|
|
|
|
ivec C = intersect(A,B); // 3, 4
|
|
|
|
ivec CC;
|
|
uvec iA;
|
|
uvec iB;
|
|
|
|
intersect(CC, iA, iB, A, B);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#unique">unique()</a></li>
|
|
<li><a href="#find_unique">find_unique()</a></li>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="join"></a>
|
|
<table>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<b>join_rows( A, B )</b>
|
|
<br><b>join_rows( A, B, C )</b>
|
|
<br><b>join_rows( A, B, C, D )</b>
|
|
<br>
|
|
<br><b>join_cols( A, B )</b>
|
|
<br><b>join_cols( A, B, C )</b>
|
|
<br><b>join_cols( A, B, C, D )</b>
|
|
</td>
|
|
<td> </td>
|
|
<td>
|
|
<b>join_horiz( A, B )</b>
|
|
<br><b>join_horiz( A, B, C )</b>
|
|
<br><b>join_horiz( A, B, C, D )</b>
|
|
<br>
|
|
<br><b>join_vert( A, B )</b>
|
|
<br><b>join_vert( A, B, C )</b>
|
|
<br><b>join_vert( A, B, C, D )</b>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
<i>join_rows()</i> and <i>join_horiz()</i>: horizontal concatenation;
|
|
join the corresponding rows of the given matrices;
|
|
the given matrices must have the same number of rows
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>join_cols()</i> and <i>join_vert()</i>: vertical concatenation;
|
|
join the corresponding columns of the given matrices;
|
|
the given matrices must have the same number of columns
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(4, 5, fill::randu);
|
|
mat B(4, 6, fill::randu);
|
|
mat C(6, 5, fill::randu);
|
|
|
|
mat AB = join_rows(A,B);
|
|
mat AC = join_cols(A,C);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#shed">.shed_rows / cols / slices</a></li>
|
|
<li><a href="#insert">.insert_rows / cols / slices</a></li>
|
|
<li><a href="#join_slices">join_slices()</a></li>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="join_slices"></a>
|
|
<b>join_slices( cube C, cube D )</b>
|
|
<br><b>join_slices( mat M, mat N )</b>
|
|
<br>
|
|
<br><b>join_slices( mat M, cube C )</b>
|
|
<br><b>join_slices( cube C, mat M )</b>
|
|
<ul>
|
|
<li>
|
|
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> must have the same number of rows and columns (ie. all slices must have the same size)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
for two matrices <i>M</i> and <i>N</i>: treat <i>M</i> and <i>N</i> as cube slices and join them to form a cube with 2 slices;
|
|
matrices <i>M</i> and <i>N</i> must have the same number of rows and columns
|
|
</li>
|
|
<br>
|
|
<li>
|
|
for matrix <i>M</i> and cube <i>C</i>: treat <i>M</i> as a cube slice and join it with the slices of <i>C</i>;
|
|
matrix <i>M</i> and cube <i>C</i> must have the same number of rows and columns
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
cube C(5, 10, 3, fill::randu);
|
|
cube D(5, 10, 4, fill::randu);
|
|
|
|
cube E = join_slices(C,D);
|
|
|
|
mat M(10, 20, fill::randu);
|
|
mat N(10, 20, fill::randu);
|
|
|
|
cube Q = join_slices(M,N);
|
|
|
|
cube R = join_slices(Q,M);
|
|
|
|
cube S = join_slices(M,Q);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#shed">.shed_rows / cols / slices</a></li>
|
|
<li><a href="#insert">.insert_rows / cols / slices</a></li>
|
|
<li><a href="#join">join_rows / cols</a></li>
|
|
<li><a href="#subcube">subcube views</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="kron"></a>
|
|
<b>kron( A, B )</b>
|
|
|
|
<ul>
|
|
<li>Kronecker tensor product</li>
|
|
<br>
|
|
<li>Given 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),
|
|
generate a matrix (with <i>nm</i> rows and <i>pq</i> columns) that denotes the tensor product of <i>A</i> and <i>B</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(4, 5, fill::randu);
|
|
mat B(5, 4, fill::randu);
|
|
|
|
mat K = kron(A,B);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#repmat">repmat()</a></li>
|
|
<li><a href="#repelem">repelem()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/KroneckerProduct.html">Kronecker product in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Kronecker_product">Kronecker product in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="log_det"></a>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><b>complex result = log_det( A )</b></td><td> </td><td>(form 1)</td></tr>
|
|
<tr><td><b>log_det( val, sign, A )</b></td><td> </td><td>(form 2)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>Log determinant of square matrix <i>A</i>, based on LU decomposition</li>
|
|
<br>
|
|
<li>form 1: return the complex log determinant
|
|
<ul>
|
|
<li>
|
|
if matrix <i>A</i> is real and the determinant is positive:
|
|
<ul>
|
|
<li>the real part is the log determinant</li>
|
|
<li>the imaginary part is zero</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
if matrix <i>A</i> is real and the determinant is negative:
|
|
<ul>
|
|
<li>the real part is log abs(determinant)</li>
|
|
<li>the imaginary part is equal to <i><a href="#constants">datum::pi</a></i></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<br>
|
|
<li>form 2: store the calculated log determinant in <i>val</i> and <i>sign</i>, and return a bool indicating success;
|
|
<br>the determinant is equal to <i>exp(val) · sign</i>
|
|
</li>
|
|
<br>
|
|
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the log determinant cannot be found:
|
|
<ul>
|
|
<li><i>result = log_det(A)</i> throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>log_det(val, sign, A)</i> returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
cx_double result = log_det(A); // form 1
|
|
|
|
double val;
|
|
double sign;
|
|
|
|
bool ok = log_det(val, sign, A); // form 2
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#log_det_sympd">log_det_sympd()</a></li>
|
|
<li><a href="#det">det()</a></li>
|
|
<li><a href="#rcond">rcond()</a></li>
|
|
<li><a href="#cx_double">cx_double</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Determinant.html">determinant in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Determinant">determinant in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="log_det_sympd"></a>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><b>result = log_det_sympd( A )</b></td><td> </td><td>(form 1)</td></tr>
|
|
<tr><td><b>log_det_sympd( result, A )</b></td><td> </td><td>(form 2)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>Log determinant of symmetric positive definite matrix <i>A</i></li>
|
|
<br>
|
|
<li>form 1: return the log determinant</li>
|
|
<br>
|
|
<li>form 2: store the calculated log determinant in <i>result</i> and return a bool indicating success</li>
|
|
<br>
|
|
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the log determinant cannot be found:
|
|
<ul>
|
|
<li><i>result = log_det_sympd(A)</i> throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>log_det_sympd(result, A)</i> returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
mat B = A.t() * A; // make symmetric matrix
|
|
|
|
double result1 = log_det_sympd(B); // form 1
|
|
|
|
double result2;
|
|
bool success = log_det_sympd(result2, B); // form 2
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#log_det">log_det()</a></li>
|
|
<li><a href="#rcond">rcond()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Determinant.html">determinant in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Determinant">determinant in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="logmat"></a>
|
|
<b>B = logmat( A )</b>
|
|
<br><b>logmat( B, A )</b>
|
|
<ul>
|
|
<li>Complex matrix logarithm of general square matrix <i>A</i></li>
|
|
<br>
|
|
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the matrix logarithm cannot be found:
|
|
<ul>
|
|
<li><i>B = logmat(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>logmat(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li><b>Caveats:</b>
|
|
<ul>
|
|
<li>the matrix logarithm operation is generally <b>not</b> the same as applying the <a href="#misc_fns">log()</a> function to each element</li>
|
|
<li>if matrix <i>A</i> is symmetric positive definite, <a href="#logmat_sympd">logmat_sympd()</a> is faster</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
cx_mat B = logmat(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#logmat_sympd">logmat_sympd()</a></li>
|
|
<li><a href="#expmat">expmat()</a></li>
|
|
<li><a href="#sqrtmat">sqrtmat()</a></li>
|
|
<li><a href="#imag_real">real()</a></li>
|
|
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Logarithm_of_a_matrix">matrix logarithm in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="logmat_sympd"></a>
|
|
<b>B = logmat_sympd( A )</b>
|
|
<br><b>logmat_sympd( B, A )</b>
|
|
<ul>
|
|
<li>Matrix logarithm of symmetric/hermitian positive definite matrix <i>A</i></li>
|
|
<br>
|
|
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the matrix logarithm cannot be found:
|
|
<ul>
|
|
<li><i>B = logmat_sympd(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>logmat_sympd(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<!--
|
|
<br>
|
|
<li><b>Caveat:</b> there is no explicit check whether <i>A</i> is symmetric/hermitian positive definite</li>
|
|
-->
|
|
<br>
|
|
<li><b>Caveat:</b> the matrix logarithm operation is generally <b>not</b> the same as applying the <a href="#misc_fns">log()</a> function to each element</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
mat B = A*A.t(); // make symmetric matrix
|
|
|
|
mat C = logmat_sympd(B);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#logmat">logmat()</a></li>
|
|
<li><a href="#expmat_sym">expmat_sym()</a></li>
|
|
<li><a href="#sqrtmat_sympd">sqrtmat_sympd()</a></li>
|
|
<li><a href="#is_sympd">.is_sympd()</a></li>
|
|
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Logarithm_of_a_matrix">matrix logarithm in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Positive-definite_matrix">positive definite matrix in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/PositiveDefiniteMatrix.html">positive definite matrix in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="min_and_max"></a>
|
|
<table>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<b>min( V )</b>
|
|
<br><b>min( M )</b>
|
|
<br><b>min( M, dim )</b>
|
|
<br><b>min( Q )</b>
|
|
<br><b>min( Q, dim )</b>
|
|
<br><b>min( A, B )</b>
|
|
</td>
|
|
<td> </td>
|
|
<td>
|
|
<b>max( V )</b>
|
|
<br><b>max( M )</b>
|
|
<br><b>max( M, dim )</b>
|
|
<br><b>max( Q )</b>
|
|
<br><b>max( Q, dim )</b>
|
|
<br><b>max( A, B )</b>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
For vector <i>V</i>, return the extremum value
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For matrix <i>M</i>, return the extremum value for each column (<i>dim = 0</i>), or each row (<i>dim = 1</i>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For cube <i>Q</i>, return the extremum values of elements along dimension <i>dim</i>, where <i>dim</i> ∈ { 0, 1, 2 }
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>dim</i> argument is optional; by default <i>dim = 0</i> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For two matrices/cubes <i>A</i> and <i>B</i>, return a matrix/cube containing element-wise extremum values
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For objects with complex numbers, absolute values are used for comparison
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
colvec v(10, fill::randu);
|
|
double x = max(v);
|
|
|
|
mat M(10, 10, fill::randu);
|
|
|
|
rowvec a = max(M);
|
|
rowvec b = max(M,0);
|
|
colvec c = max(M,1);
|
|
|
|
// element-wise maximum
|
|
mat X(5, 6, fill::randu);
|
|
mat Y(5, 6, fill::randu);
|
|
mat Z = arma::max(X,Y); // 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)</li>
|
|
<li><a href="#index_min_and_index_max_standalone">index_min() & index_max()</a>
|
|
<li><a href="#clamp">clamp()</a>
|
|
<li><a href="#stats_fns">statistics functions</a>
|
|
<li><a href="#running_stat">running_stat</a> - class for running statistics of scalars</li>
|
|
<li><a href="#running_stat_vec">running_stat_vec</a> - class for running statistics of vectors</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="nonzeros"></a>
|
|
<b>nonzeros( X )</b>
|
|
<ul>
|
|
<li>
|
|
Return a column vector containing the non-zero <b>values</b> of <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>X</i> can be a sparse or dense matrix
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>
|
|
for dense matrices/vectors,
|
|
to obtain the <b>number</b> of non-zero elements,
|
|
the expression <code><a href="#accu">accu</a>(X != 0)</code> is more efficient
|
|
</li>
|
|
<li>
|
|
for sparse matrices,
|
|
to obtain the <b>number</b> of non-zero elements,
|
|
the <code><a href="#attributes">.n_nonzero</a></code> attribute is more efficient, eg. <code>X.n_nonzero</code>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
sp_mat A = sprandu<sp_mat>(100, 100, 0.1);
|
|
vec a = nonzeros(A);
|
|
|
|
mat B(100, 100, fill::eye);
|
|
vec b = nonzeros(B);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#find">find()</a>
|
|
<li><a href="#unique">unique()</a></li>
|
|
<li><a href="#vectorise">vectorise()</a>
|
|
<li><a href="#clean">.clean()</a>
|
|
<li><a href="#for_each">.for_each()</a>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="norm"></a>
|
|
<b>norm( X )</b>
|
|
<br><b>norm( X, p )</b>
|
|
<ul>
|
|
<li>
|
|
Compute the <i>p</i>-norm of <i>X</i>, where <i>X</i> is a vector or matrix
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For vectors, <i>p</i> is an integer ≥ 1, or one of: <code>"-inf"</code>, <code>"inf"</code>, <code>"fro"</code>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For matrices, <i>p</i> is one of: 1, 2, <code>"inf"</code>, <code>"fro"</code>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<code>"-inf"</code> is the minimum quasi-norm, <code>"inf"</code> is the maximum norm, <code>"fro"</code> is the Frobenius norm
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i>p</i> is optional; by default <i>p = 2</i> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For vector norm with <i>p = 2</i> and matrix norm with <i>p = "fro"</i>, a robust algorithm is used to reduce the likelihood of underflows and overflows
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>matrix 2-norm (spectral norm) is based on SVD, which is computationally intensive; a faster alternative is <a href="#norm2est">norm2est()</a></li>
|
|
<li>to obtain the vector norm of each row or column of a matrix, use <a href="#vecnorm">vecnorm()</a></li>
|
|
<li>to obtain the zero/Hamming pseudo-norm (number of non-zero elements), use this expression: <code><a href="#accu">accu</a>(X != 0)</code></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec q(5, fill::randu);
|
|
|
|
double x = norm(q, 2);
|
|
double y = norm(q, "inf");
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#vecnorm">vecnorm()</a></li>
|
|
<li><a href="#norm2est">norm2est()</a></li>
|
|
<li><a href="#normalise">normalise()</a></li>
|
|
<li><a href="#dot">dot()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Norm_(mathematics)">vector norm in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/VectorNorm.html">vector norm in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Matrix_norm">matrix norm in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/MatrixNorm.html">matrix norm in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="norm2est"></a>
|
|
<b>norm2est( X )</b>
|
|
<br><b>norm2est( X, tol )</b>
|
|
<br><b>norm2est( X, tol, max_iter )</b>
|
|
<ul>
|
|
<li>
|
|
Fast estimate of the 2-norm (spectral norm) of <i>X</i>, where <i>X</i> is a dense or sparse matrix
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The estimate is found via an iterative algorithm which finishes when one of the following conditions is met:
|
|
<ul>
|
|
<li>
|
|
the relative difference between two consecutive estimates is less than the specified tolerance,
|
|
ie. |est<sub>1</sub> - est<sub>2</sub>| / max(est<sub>1</sub> , est<sub>2</sub>) < tol
|
|
</li>
|
|
<li>the number of iterations is equal to <i>max_iter</i></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The optional argument <i>tol</i> specifies the tolerance for the relative difference; by default <i>tol = 1e-6</i> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The optional argument <i>max_iter</i> specifies the maximum number of iterations; by default <i>max_iter = 100</i> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(2000, 3000, fill::randu);
|
|
|
|
double x = norm2est(X);
|
|
double y = norm2est(X, 1e-5);
|
|
double z = norm2est(X, 1e-4, 10);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#norm">norm()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Matrix_norm">matrix norm in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/MatrixNorm.html">matrix norm in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="normalise"></a>
|
|
<b>normalise( V )</b>
|
|
<br><b>normalise( V, p )</b>
|
|
<br>
|
|
<br><b>normalise( X )</b>
|
|
<br><b>normalise( X, p )</b>
|
|
<br><b>normalise( X, p, dim )</b>
|
|
<ul>
|
|
<li>For vector <i>V</i>, return its normalised version (ie. having unit <i>p</i>-norm)</li>
|
|
<br>
|
|
<li>
|
|
For matrix <i>X</i>, return its normalised version, where each column (<i>dim = 0</i>) or row (<i>dim = 1</i>) has been normalised to have unit <i>p</i>-norm</li>
|
|
<br>
|
|
<li>
|
|
The <i>p</i> argument is optional; by default <i>p = 2</i> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>dim</i> argument is optional; by default <i>dim = 0</i> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec A(10, fill::randu);
|
|
vec B = normalise(A);
|
|
vec C = normalise(A, 1);
|
|
|
|
mat X(5, 6, fill::randu);
|
|
mat Y = normalise(X);
|
|
mat Z = normalise(X, 2, 1);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#norm">norm()</a></li>
|
|
<li><a href="#vecnorm">vecnorm()</a></li>
|
|
<li><a href="#dot">norm_dot()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/NormalizedVector.html">Normalised vector in MathWorld</a>
|
|
<li><a href="https://en.wikipedia.org/wiki/Unit_vector">Unit vector in Wikipedia</a>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="pow"></a>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><b>pow( A, scalar )</b></td><td> </td><td>(form 1)</td></tr>
|
|
<tr><td><b>pow( A, B )</b></td><td> </td><td>(form 2)</td></tr>
|
|
<tr><td><b>pow( M.each_col(), C )</b></td><td> </td><td>(form 3)</td></tr>
|
|
<tr><td><b>pow( M.each_row(), R )</b></td><td> </td><td>(form 4)</td></tr>
|
|
<tr><td><b>pow( Q.each_slice(), M )</b></td><td> </td><td>(form 5)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>Element-wise power operations</li>
|
|
<br>
|
|
<li>form 1: raise all elements in <i>A</i> to the power denoted by the given scalar</li>
|
|
<br>
|
|
<li>form 2: raise each element in <i>A</i> to the power denoted by the corresponding element in <i>B</i>;
|
|
<br>the sizes of <i>A</i> and <i>B</i> must be the same</li>
|
|
<br>
|
|
<li>form 3: for each column vector of matrix <i>M</i>, raise each element to the power denoted by the corresponding element in column vector <i>C</i>;
|
|
<br>the number of rows in <i>M</i> and <i>C</i> must be the same</li>
|
|
<br>
|
|
<li>form 4: for each row vector of matrix <i>M</i>, raise each element to the power denoted by the corresponding element in row vector <i>R</i>;
|
|
<br>the number of columns in <i>M</i> and <i>R</i> must be the same</li>
|
|
<br>
|
|
<li>form 5: for each slice of cube <i>Q</i>, raise each element to the power denoted by the corresponding element in matrix <i>M</i>;
|
|
<br>the number of rows and columns in <i>Q</i> and <i>M</i> must be the same</li>
|
|
<br>
|
|
<li><b>Caveats</b>:
|
|
<ul>
|
|
<li>to raise all elements to the power 2, use <a href="#misc_fns">square()</a> instead</li>
|
|
<li>for the matrix power operation, which takes into account matrix structure, use <a href="#powmat">powmat()</a></li>
|
|
</ul>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 6, fill::randu);
|
|
mat B(5, 6, fill::randu);
|
|
|
|
mat X = pow(A, 3.45);
|
|
mat Y = pow(A, B);
|
|
|
|
vec C(5, fill::randu);
|
|
rowvec R(6, fill::randu);
|
|
|
|
mat Z1 = pow(A.each_col(), C);
|
|
mat Z2 = pow(A.each_row(), R);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#powmat">powmat()</a></li>
|
|
<li><a href="#abs">abs()</a></li>
|
|
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
|
|
<li><a href="#each_colrow">.each_col() & .each_row()</a></li>
|
|
<li><a href="#each_slice">.each_slice()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="powmat"></a>
|
|
<b>B = powmat( A, n )</b>
|
|
<br><b>powmat( B, A, n )</b>
|
|
<ul>
|
|
<li>Matrix power operation: raise square matrix <i>A</i> to the power of <i>n</i>, where <i>n</i> has the type <i>int</i> or <i>double</i></li>
|
|
<br>
|
|
<li>If <i>n</i> has the type <i>double</i>, the resultant matrix <i>B</i> always has complex elements</li>
|
|
<br>
|
|
<li>For <i>n = 0</i>, an identity matrix is generated</li>
|
|
<br>
|
|
<!--
|
|
<li>For <i>n ≤ -1</i>, inverse of <i>A</i> is raised to the power of <i>abs(n)</i></li>
|
|
<br>
|
|
-->
|
|
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the matrix power cannot be found:
|
|
<ul>
|
|
<li><i>B = powmat(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>powmat(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li><b>Caveats</b>:
|
|
<ul>
|
|
<li>the matrix power operation is generally <b>not</b> the same as applying the <a href="#pow">pow()</a> function to each element</li>
|
|
<li>to find the inverse of a matrix, use <a href="#inv">inv()</a> instead</li>
|
|
<li>to solve a system of linear equations, use <a href="#solve">solve()</a> instead</li>
|
|
<li>to find the matrix square root, use <a href="#sqrtmat">sqrtmat()</a> instead</li>
|
|
</ul>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
mat B = powmat(A, 4); // integer exponent
|
|
|
|
cx_mat C = powmat(A, 4.56); // non-integer exponent
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#pow">pow()</a></li>
|
|
<li><a href="#sqrtmat">sqrtmat()</a></li>
|
|
<li><a href="#inv">inv()</a></li>
|
|
<li><a href="#eye_standalone">eye()</a></li>
|
|
<li><a href="#operators">operators</a></li>
|
|
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="prod"></a>
|
|
<b>prod( V )</b>
|
|
<br><b>prod( M )</b>
|
|
<br><b>prod( M, dim )</b>
|
|
<ul>
|
|
<li>
|
|
For vector <i>V</i>, return the product of all elements
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For matrix <i>M</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 v(10, fill::randu);
|
|
double x = prod(v);
|
|
|
|
mat M(10, 10, fill::randu);
|
|
|
|
rowvec a = prod(M);
|
|
rowvec b = prod(M,0);
|
|
colvec c = prod(M,1);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#cumprod">cumprod()</a></li>
|
|
<li><a href="#operators">Schur product in operators</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="rank"></a>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><b>r = rank( X )</b></td><td> </td><td>(form 1)</td></tr>
|
|
<tr><td><b>r = rank( X, tolerance )</b></td><td> </td><td> </td></tr>
|
|
<tr><td> </td><td> </td></tr>
|
|
<tr><td><b>rank( r, X )</b></td><td> </td><td>(form 2)</td></tr>
|
|
<tr><td><b>rank( r, X, tolerance )</b></td><td> </td><td> </td></tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>Calculate the rank of matrix <i>X</i>, based on singular value decomposition</li>
|
|
<br>
|
|
<li>form 1: return the rank</li>
|
|
<br>
|
|
<li>form 2: store the calculated rank in <i>r</i> and return a bool indicating success</li>
|
|
<br>
|
|
<li>Any singular values less than <i>tolerance</i> are treated as zero</li>
|
|
<br>
|
|
<li>
|
|
The <i>tolerance</i> argument is optional; by default <i>tolerance = max_rc · max_sv · epsilon</i>, where:
|
|
<ul>
|
|
<li><i>max_rc</i> = max(X.n_rows, X.n_cols)</li>
|
|
<li><i>max_sv</i> = maximum singular value of <i>X</i> (ie. spectral norm)</li>
|
|
<li><i>epsilon</i> = difference between 1 and the least value greater than 1 that is representable</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>If the calculation fails:
|
|
<ul>
|
|
<li><i>r = rank(X)</i> throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>rank(r,X)</i> returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> to distinguish from <code>std::rank</code>, use the <code>arma::</code> prefix, ie. <code>arma::rank(X)</code>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(4, 5, fill::randu);
|
|
|
|
uword r1 = rank(A); // form 1
|
|
|
|
uword r2;
|
|
bool success = rank(r2, A); // form 2
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#rcond">rcond()</a></li>
|
|
<li><a href="#svd">svd()</a></li>
|
|
<li><a href="#orth">orth()</a></li>
|
|
<li><a href="#constants">datum::eps</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/MatrixRank.html">Rank in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Rank_(linear_algebra)">Rank in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="rcond"></a>
|
|
<b>rcond( A )</b>
|
|
<ul>
|
|
<li>
|
|
Return the 1-norm estimate of the reciprocal condition number of square matrix <i>A</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Values close to 1 suggest that <i>A</i> is well-conditioned
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Values close to 0 suggest that <i>A</i> is badly conditioned
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> to efficiently calculate rcond and matrix inverse at the same time, use <a href="#inv">inv()</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
double r = rcond(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#cond">cond()</a></li>
|
|
<li><a href="#rank">rank()</a></li>
|
|
<li><a href="#det">det()</a></li>
|
|
<li><a href="#inv">inv()</a></li>
|
|
<li><a href="#solve">solve()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="repelem"></a>
|
|
<b>repelem( A, num_copies_per_row, num_copies_per_col )</b>
|
|
<ul>
|
|
<li>Generate a matrix by replicating each element of matrix <i>A</i></li>
|
|
<br>
|
|
<li>The generated matrix has the following size:
|
|
<ul>
|
|
<table border="0">
|
|
<tbody>
|
|
<tr><td>n_rows</td><td> = </td><td>num_copies_per_row</td><td>*</td><td>A.n_rows</td></tr>
|
|
<tr><td>n_cols</td><td> = </td><td>num_copies_per_col</td><td>*</td><td>A.n_cols</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(2, 3, fill::randu);
|
|
|
|
mat B = repelem(A, 4, 5);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#repmat">repmat()</a></li>
|
|
<li><a href="#kron">kron()</a></li>
|
|
<li><a href="#reshape">reshape()</a></li>
|
|
<li><a href="#resize">resize()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
<table border="0">
|
|
<tbody>
|
|
<tr><td>n_rows</td><td> = </td><td>num_copies_per_row</td><td>×</td><td>A.n_rows</td></tr>
|
|
<tr><td>n_cols</td><td> = </td><td>num_copies_per_col</td><td>×</td><td>A.n_cols</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> to apply a vector operation on each row or column of a matrix,
|
|
it is generally more efficient to use <a href="#each_colrow">.each_row()</a> or <a href="#each_colrow">.each_col()</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(2, 3, fill::randu);
|
|
|
|
mat B = repmat(A, 4, 5);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#each_colrow">.each_col() & .each_row()</a> (vector operations applied to each column or row)</li>
|
|
<li><a href="#repelem">repelem()</a></li>
|
|
<li><a href="#kron">kron()</a></li>
|
|
<li><a href="#reshape">reshape()</a></li>
|
|
<li><a href="#resize">resize()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="reshape"></a>
|
|
<b>reshape( X, n_rows, n_cols )</b> (X is a vector or matrix)
|
|
<br><b>reshape( X, size(Y) )</b>
|
|
<br>
|
|
<br><b>reshape( Q, n_rows, n_cols, n_slices )</b> (Q is a cube)
|
|
<br><b>reshape( Q, size(R) )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a vector/matrix/cube with given size specifications,
|
|
whose elements are taken from the given object in a column-wise manner;
|
|
the elements in the generated object are placed column-wise (ie. the first column is filled up before filling the second column)
|
|
</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>
|
|
If the total number of elements in the given object is less than the specified size,
|
|
the remaining elements in the generated object are set to zero
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If the total number of elements in the given object is greater than the specified size,
|
|
only a subset of elements is taken from the given object
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>
|
|
to change the size without preserving data, use <a href="#set_size">.set_size()</a> instead, which is much faster
|
|
</li>
|
|
<li>
|
|
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>
|
|
<li>
|
|
to flatten a matrix into a vector, use <a href="#vectorise">vectorise()</a> or <a href="#as_col_row">.as_col() / .as_row()</a> instead
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(10, 5, fill::randu);
|
|
|
|
mat B = reshape(A, 5, 10);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#reshape_member">.reshape()</a> (member function)</li>
|
|
<li><a href="#set_size">.set_size()</a></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>
|
|
<li><a href="#repmat">repmat()</a></li>
|
|
<li><a href="#repelem">repelem()</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
<li><a href="#interp2">interp2()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="resize"></a>
|
|
<b>resize( X, n_rows, n_cols )</b> (X is a vector or matrix)
|
|
<br><b>resize( X, size(Y) )</b>
|
|
<br>
|
|
<br><b>resize( Q, n_rows, n_cols, n_slices )</b> (Q is a cube)
|
|
<br><b>resize( Q, size(R) )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a vector/matrix/cube with given size specifications,
|
|
whose elements as well as the layout of the elements are taken from the given object
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b>
|
|
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(4, 5, fill::randu);
|
|
|
|
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>
|
|
<li><a href="#repmat">repmat()</a></li>
|
|
<li><a href="#repelem">repelem()</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="reverse"></a>
|
|
<b>reverse( V )</b>
|
|
<br><b>reverse( X )</b>
|
|
<br><b>reverse( X, dim )</b>
|
|
<ul>
|
|
<li>
|
|
For vector <i>V</i>, generate a copy of the vector with the order of elements reversed
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For matrix <i>X</i>, generate a copy of the matrix with the order of elements reversed 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>
|
|
vec v(123, fill::randu);
|
|
vec y = reverse(v);
|
|
|
|
mat A(4, 5, fill::randu);
|
|
mat B = reverse(A);
|
|
mat C = reverse(A,1);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#flip">fliplr() & flipud()</a></li>
|
|
<li><a href="#shift">shift()</a></li>
|
|
<li><a href="#sort">sort()</a></li>
|
|
<li><a href="#trans">trans()</a></li>
|
|
<li><a href="#t_st_members">.t()</a></li>
|
|
<li><a href="#swap_rows">.swap_rows() & .swap_cols()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="roots"></a>
|
|
<b>R = roots( P )</b>
|
|
<br><b>roots( R, P )</b>
|
|
<ul>
|
|
<li>
|
|
Find the complex roots of a polynomial function represented via vector <i>P</i> and store them in column vector <i>R</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The polynomial function is modelled as:
|
|
<ul>
|
|
y = p<sub><sub>0</sub></sub>x<sup><sup>N</sup></sup>
|
|
+ p<sub><sub>1</sub></sub>x<sup><sup>N-1</sup></sup>
|
|
+ p<sub><sub>2</sub></sub>x<sup><sup>N-2</sup></sup>
|
|
+ ...
|
|
+ p<sub><sub>N-1</sub></sub>x<sup><sup>1</sup></sup>
|
|
+ p<sub><sub>N</sub></sub>
|
|
</ul>
|
|
where p<sub><sub>i</sub></sub> is the i-th polynomial coefficient in vector <i>P</i>
|
|
</li>
|
|
<br>
|
|
<li>The computation is based on eigen decomposition; if the decomposition fails:
|
|
<ul>
|
|
<li><i>R = roots(P)</i> resets <i>R</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>roots(R,P)</i> resets <i>R</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec P(5, fill::randu);
|
|
|
|
cx_vec R = roots(P);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#polyval">polyval()</a></li>
|
|
<li><a href="#polyfit">polyfit()</a></li>
|
|
<li><a href="#imag_real">real()</a></li>
|
|
<li><a href="#solve">solve()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Zero_of_a_function">zero of a function in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="shift"></a>
|
|
<b>shift( V, N )</b>
|
|
<br><b>shift( X, N )</b>
|
|
<br><b>shift( X, N, dim )</b>
|
|
<ul>
|
|
<li>
|
|
For vector <i>V</i>, generate a copy of the vector with the elements shifted by <i>N</i> positions in a circular manner
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For matrix <i>X</i>, generate a copy of the matrix with the elements shifted by <i>N</i> positions in each column (<i>dim = 0</i>), or each row (<i>dim = 1</i>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>N</i> can be positive or negative
|
|
</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(4, 5, fill::randu);
|
|
mat B = shift(A, -1);
|
|
mat C = shift(A, +1);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#shuffle">shuffle()</a></li>
|
|
<li><a href="#flip">fliplr() & flipud()</a></li>
|
|
<li><a href="#reverse">reverse()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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 elements shuffled 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(4, 5, fill::randu);
|
|
mat B = shuffle(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#shift">shift()</a></li>
|
|
<li><a href="#sort">sort()</a></li>
|
|
<li><a href="#unique">unique()</a></li>
|
|
<li><a href="#randi">randi()</a></li>
|
|
<li><a href="#randperm">randperm()</a></li>
|
|
<li><a href="#rng_seed">RNG seed setting</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="size"></a>
|
|
<b>size( X )</b>
|
|
<br>
|
|
<b>size( n_rows, n_cols )</b>
|
|
<br>
|
|
<b>size( n_rows, n_cols, n_slices )</b>
|
|
<ul>
|
|
<li>
|
|
Obtain the dimensions of object <i>X</i>, or explicitly specify the dimensions
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Dimensions provided via <i>size(...)</i> can be used in conjunction with
|
|
<a href="#Mat">matrix constructors</a>,
|
|
<a href="#submat">submatrix views</a>,
|
|
<a href="#randu">random matrix generation</a>,
|
|
<a href="#ind2sub">ind2sub()</a>,
|
|
<a href="#sub2ind">sub2ind()</a>,
|
|
etc.
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>size(…)</i> objects support simple arithmetic operations such as addition and multiplication
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Two <i>size(…)</i> objects can be compared for equality/inequality
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>size(…)</i> objects can be passed to an std::ostream (eg. cout) via <<
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> to prevent interference from <a href="https://en.cppreference.com/w/cpp/iterator/size"><i>std::size()</i></a> in C++17,
|
|
preface Armadillo's <i>size(…)</i> with the <i>arma</i> namespace qualification, eg. <i>arma::size(…)</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5,6);
|
|
|
|
mat B(size(A), fill::zeros);
|
|
|
|
mat C; C.randu(size(A));
|
|
|
|
mat D = ones<mat>(size(A));
|
|
|
|
mat E(10,20, fill::ones);
|
|
E(3,4,size(C)) = C; // access submatrix of E
|
|
|
|
mat F( size(A) + size(E) );
|
|
|
|
mat G( size(A) * 2 );
|
|
|
|
cout << "size of A: " << size(A) << endl;
|
|
|
|
bool is_same_size = (size(A) == size(E));
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#attributes">attributes</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="sort"></a>
|
|
<b>sort( V )</b>
|
|
<br><b>sort( V, sort_direction )</b>
|
|
<br>
|
|
<br><b>sort( X )</b>
|
|
<br><b>sort( X, sort_direction )</b>
|
|
<br><b>sort( X, sort_direction, dim )</b>
|
|
<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>The <i>sort_direction</i> argument is optional; <i>sort_direction</i> is either <code>"ascend"</code> or <code>"descend"</code>; by default <code>"ascend"</code> is used</li>
|
|
<br>
|
|
<li>For matrices and vectors with complex numbers, sorting is via absolute values</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(10, 10, fill::randu);
|
|
mat B = sort(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#sort_index">sort_index()</a></li>
|
|
<li><a href="#is_sorted">.is_sorted()</a></li>
|
|
<li><a href="#shuffle">shuffle()</a></li>
|
|
<li><a href="#unique">unique()</a></li>
|
|
<li><a href="#reverse">reverse()</a></li>
|
|
<li><a href="#randi">randi()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="sort_index"></a>
|
|
<b>sort_index( X )</b>
|
|
<br><b>sort_index( X, sort_direction )</b>
|
|
<br>
|
|
<br><b>stable_sort_index( X )</b>
|
|
<br><b>stable_sort_index( X, sort_direction )</b>
|
|
<ul>
|
|
<li>Return a vector which describes the sorted order of the elements of <i>X</i>
|
|
(ie. it contains the indices of the elements of <i>X</i>)
|
|
</li>
|
|
<br>
|
|
<li>The output vector must have the type <a href="#Col">uvec</a>
|
|
(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>X</i> is interpreted as a vector, with column-by-column ordering of the elements of <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>The <i>sort_direction</i> argument is optional; <i>sort_direction</i> is either <code>"ascend"</code> or <code>"descend"</code>; by default <code>"ascend"</code> is used</li>
|
|
<br>
|
|
<li>The <i>stable_sort_index()</i> variant preserves the relative order of elements with equivalent values</li>
|
|
<br>
|
|
<li>For matrices and vectors with complex numbers, sorting is via absolute values</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec q(10, fill::randu);
|
|
|
|
uvec indices = sort_index(q);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#sort">sort()</a></li>
|
|
<li><a href="#find">find()</a></li>
|
|
<li><a href="#is_sorted">.is_sorted()</a></li>
|
|
<li><a href="#index_min_and_index_max_member">.index_min() & .index_max()</a></li>
|
|
<li><a href="#ind2sub">ind2sub()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="sqrtmat"></a>
|
|
<b>B = sqrtmat( A )</b>
|
|
<br><b>sqrtmat( B, A )</b>
|
|
<ul>
|
|
<li>Complex square root of general square matrix <i>A</i></li>
|
|
<br>
|
|
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>
|
|
If matrix <i>A</i> appears to be singular, an approximate square root is attempted; additionally, <i>sqrtmat(B,A)</i> returns a bool set to false
|
|
</li>
|
|
<br>
|
|
<li><b>Caveats:</b>
|
|
<ul>
|
|
<li>the square root of a matrix is generally <b>not</b> the same as applying the <a href="#misc_fns">sqrt()</a> function to each element</li>
|
|
<li>if matrix <i>A</i> is symmetric positive definite, <a href="#sqrtmat_sympd">sqrtmat_sympd()</a> is faster</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
cx_mat B = sqrtmat(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#sqrtmat_sympd">sqrtmat_sympd()</a></li>
|
|
<li><a href="#powmat">powmat()</a></li>
|
|
<li><a href="#expmat">expmat()</a></li>
|
|
<li><a href="#logmat">logmat()</a></li>
|
|
<li><a href="#chol">chol()</a></li>
|
|
<li><a href="#imag_real">real()</a></li>
|
|
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Square_root_of_a_matrix">square root of a matrix in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="sqrtmat_sympd"></a>
|
|
<b>B = sqrtmat_sympd( A )</b>
|
|
<br><b>sqrtmat_sympd( B, A )</b>
|
|
<ul>
|
|
<li>Square root of symmetric/hermitian positive definite matrix <i>A</i></li>
|
|
<br>
|
|
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the square root cannot be found:
|
|
<ul>
|
|
<li><i>B = sqrtmat_sympd(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>sqrtmat_sympd(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<!--
|
|
<br>
|
|
<li><b>Caveat:</b> there is no explicit check whether <i>A</i> is symmetric/hermitian positive definite</li>
|
|
-->
|
|
<br>
|
|
<li><b>Caveat:</b> the matrix square root operation is generally <b>not</b> the same as applying the <a href="#misc_fns">sqrt()</a> function to each element</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
mat B = A*A.t(); // make symmetric matrix
|
|
|
|
mat C = sqrtmat_sympd(B);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#sqrtmat">sqrtmat()</a></li>
|
|
<li><a href="#expmat_sym">expmat_sym()</a></li>
|
|
<li><a href="#logmat_sympd">logmat_sympd()</a></li>
|
|
<li><a href="#chol">chol()</a></li>
|
|
<li><a href="#is_sympd">.is_sympd()</a></li>
|
|
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Square_root_of_a_matrix">square root of a matrix in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Positive-definite_matrix">positive definite matrix in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/PositiveDefiniteMatrix.html">positive definite matrix in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="sum"></a>
|
|
<b>sum( V )</b>
|
|
<br><b>sum( M )</b>
|
|
<br><b>sum( M, dim )</b>
|
|
<br><b>sum( Q )</b>
|
|
<br><b>sum( Q, dim )</b>
|
|
<ul>
|
|
<li>
|
|
For vector <i>V</i>, return the sum of all elements
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For matrix <i>M</i>, return the sum of elements in each column (<i>dim = 0</i>), or each row (<i>dim = 1</i>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For cube <i>Q</i>, return the sums of elements along dimension <i>dim</i>, where <i>dim</i> ∈ { 0, 1, 2 };
|
|
for example, <i>dim = 0</i> indicates the sum of elements in each column within each slice
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>dim</i> argument is optional; by default <i>dim = 0</i> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> to get a sum of all the elements regardless of the object type (ie. vector, or matrix, or cube), use <a href="#accu">accu()</a> instead
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
colvec v(10, fill::randu);
|
|
double x = sum(v);
|
|
|
|
mat M(10, 10, fill::randu);
|
|
|
|
rowvec a = sum(M);
|
|
rowvec b = sum(M,0);
|
|
colvec c = sum(M,1);
|
|
|
|
double y = accu(M); // find the overall sum regardless of object type
|
|
</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="#trapz">trapz()</a></li>
|
|
<li><a href="#stats_fns">mean()</a></li>
|
|
<li><a href="#as_scalar">as_scalar()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="sub2ind"></a>
|
|
<table>
|
|
<tbody>
|
|
<tr><td>uword </td><td>index</td><td> = <b>sub2ind( size(</b>M<b>),</b> row<b>,</b> col <b>)</b></td><td>(<i>M</i> is a matrix)</td></tr>
|
|
<tr><td>uvec </td><td>indices</td><td> = <b>sub2ind( size(</b>M<b>),</b> matrix_of_subscripts <b>)</b></td><td></td></tr>
|
|
<tr><td> </td><td> </td><td> </td><td> </td></tr>
|
|
<tr><td>uword </td><td>index</td><td> = <b>sub2ind( size(</b>Q<b>),</b> row<b>,</b> col<b>,</b> slice <b>)</b></td><td>(<i>Q</i> is a cube)</td></tr>
|
|
<tr><td>uvec </td><td>indices</td><td> = <b>sub2ind( size(</b>Q<b>),</b> matrix_of_subscripts <b>)</b></td><td></td></tr>
|
|
</tbody>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
Convert subscripts to a linear index
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i><b>size(</b>X<b>)</b></i> can be replaced with <i><b>size(</b>n_rows<b>,</b> n_cols<b>)</b></i> or <i><b>size(</b>n_rows<b>,</b> n_cols<b>,</b> n_slices<b>)</b></i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For the <i>matrix_of_subscripts</i> argument, the subscripts must be stored in each column of an <i>m x n</i> matrix of type <a href="#Mat">umat</a>;
|
|
<i>m = 2</i> for matrix subscripts, while <i>m = 3</i> for cube subscripts
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If a subscript is out of range, a <i>std::logic_error</i> exception is thrown
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat M(4,5);
|
|
cube Q(4,5,6);
|
|
|
|
uword i = sub2ind( size(M), 2, 3 );
|
|
uword j = sub2ind( size(Q), 2, 3, 4 );
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#size">size()</a></li>
|
|
<li><a href="#ind2sub">ind2sub()</a></li>
|
|
<li><a href="#element_access">element access</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="symmat"></a>
|
|
<b>symmatu( A )</b>
|
|
<br><b>symmatu( A, do_conj )</b>
|
|
<br>
|
|
<br><b>symmatl( A )</b>
|
|
<br><b>symmatl( A, do_conj )</b>
|
|
<ul>
|
|
<li>
|
|
<i>symmatu(A)</i>: generate symmetric matrix from square matrix <i>A</i>, by reflecting the upper triangle to the lower triangle
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>symmatl(A)</i>: generate symmetric matrix from square matrix <i>A</i>, by reflecting the lower triangle to the upper triangle
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If <i>A</i> is a complex matrix, the reflection uses the complex conjugate of the elements;
|
|
to disable the complex conjugate, set <i>do_conj</i> to <i>false</i>
|
|
</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(5, 5, fill::randu);
|
|
|
|
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="#is_symmetric">.is_symmetric()</a></li>
|
|
<li><a href="#is_hermitian">.is_hermitian()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Symmetric_matrix">Symmetric matrix in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="trace"></a>
|
|
<b>trace( X )</b>
|
|
<ul>
|
|
<li>
|
|
Sum of the elements on the main diagonal of matrix <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If <i>X</i> is an expression, the evaluation of the expression aims to calculate only the diagonal elements
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
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="#diagmat">diagmat()</a></li>
|
|
<li><a href="#sum">sum()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="trans"></a>
|
|
<b>trans( A )</b>
|
|
<br><b>strans( A )</b>
|
|
<ul>
|
|
<li>
|
|
For real (non-complex) matrix:
|
|
<ul>
|
|
<li><i>trans()</i> provides a transposed copy of the matrix</li>
|
|
<li><i>strans()</i> is not applicable</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For complex matrix:
|
|
<ul>
|
|
<li><i>trans()</i> provides a Hermitian (conjugate) transposed copy (ie. signs of imaginary components are flipped)</li>
|
|
<li><i>strans()</i> provides a simple transposed copy (ie. signs of imaginary components are not flipped)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 10, fill::randu);
|
|
|
|
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="#inplace_trans">inplace_trans()</a></li>
|
|
<li><a href="#reverse">reverse()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Transpose">transpose in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Transpose.html">transpose in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Conjugate_transpose">conjugate transpose in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/ConjugateTranspose.html">conjugate transpose in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="trapz"></a>
|
|
<b>trapz( X, Y )</b>
|
|
<br><b>trapz( X, Y, dim )</b>
|
|
<br>
|
|
<br><b>trapz( Y )</b>
|
|
<br><b>trapz( Y, dim )</b>
|
|
<ul>
|
|
<li>
|
|
Compute the trapezoidal integral of <i>Y</i> with respect to spacing in <i>X</i>, in each column (<i>dim = 0</i>) or each row (<i>dim = 1</i>) of <i>Y</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>X</i> must be a vector; its length must equal either the number of rows in <i>Y</i> (when <i>dim = 0</i>), or the number of columns in <i>Y</i> (when <i>dim = 1</i>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If <i>X</i> is not specified, unit spacing is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>dim</i> argument is optional; by default <i>dim = 0</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec X = linspace<vec>(0, datum::pi, 1000);
|
|
vec Y = sin(X);
|
|
|
|
mat Z = trapz(X,Y);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#diff">diff()</a></li>
|
|
<li><a href="#sum">sum()</a></li>
|
|
<li><a href="#linspace">linspace()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Numerical_integration">numerical integration in Wikipedia</a>
|
|
<li><a href="https://mathworld.wolfram.com/NumericalIntegration.html">numerical integration in MathWorld</a>
|
|
<li><a href="https://en.wikipedia.org/wiki/Trapezoidal_rule">trapezoidal rule in Wikipedia</a>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="trimat"></a>
|
|
<b>trimatu( A )</b>
|
|
<br><b>trimatu( A, k )</b>
|
|
<br>
|
|
<br><b>trimatl( A )</b>
|
|
<br><b>trimatl( A, k )</b>
|
|
<ul>
|
|
<li>
|
|
Create a new matrix by copying either the upper or lower triangular part from square matrix <i>A</i>, and setting the remaining elements to zero
|
|
<ul>
|
|
<li><i>trimatu()</i> copies the upper triangular part</li>
|
|
<li><i>trimatl()</i> copies the lower triangular part</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i>k</i> specifies the diagonal which inclusively delineates the boundary of the triangular part
|
|
<ul>
|
|
<li>
|
|
for <i>k > 0</i>, the <i>k</i>-th super-diagonal is used (above main diagonal, towards top-right corner)
|
|
</li>
|
|
<li>
|
|
for <i>k < 0</i>, the <i>k</i>-th sub-diagonal is used (below main diagonal, towards bottom-left corner)
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i>k</i> is optional; by default the main diagonal is used (<i>k = 0</i>)
|
|
</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(5, 5, fill::randu);
|
|
|
|
mat U = trimatu(A);
|
|
mat L = trimatl(A);
|
|
|
|
mat UU = trimatu(A, 1); // omit the main diagonal
|
|
mat LL = trimatl(A, -1); // omit the main diagonal
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#is_trimat">.is_trimatu() / .is_trimatl()</a></li>
|
|
<li><a href="#trimat_ind">trimatu_ind() / trimatl_ind()</a></li>
|
|
<li><a href="#symmat">symmatu() / symmatl()</a></li>
|
|
<li><a href="#diagmat">diagmat()</a></li>
|
|
<li><a href="#nonzeros">nonzeros()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/TriangularMatrix.html">Triangular matrix in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Triangular_matrix">Triangular matrix in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="trimat_ind"></a>
|
|
<b>trimatu_ind( size(A) )</b>
|
|
<br><b>trimatu_ind( size(A), k )</b>
|
|
<br>
|
|
<br><b>trimatl_ind( size(A) )</b>
|
|
<br><b>trimatl_ind( size(A), k )</b>
|
|
<ul>
|
|
<li>
|
|
Return a column vector containing the indices of elements that form the upper or lower triangle part of matrix <i>A</i>
|
|
<ul>
|
|
<li><i>trimatu_ind()</i> refers to the upper triangular part</li>
|
|
<li><i>trimatl_ind()</i> refers to the lower triangular part</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>The output vector must have the type <a href="#Col">uvec</a>
|
|
(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i>k</i> specifies the diagonal which inclusively delineates the boundary of the triangular part
|
|
<ul>
|
|
<li>
|
|
for <i>k > 0</i>, the <i>k</i>-th super-diagonal is used (above main diagonal, towards top-right corner)
|
|
</li>
|
|
<li>
|
|
for <i>k < 0</i>, the <i>k</i>-th sub-diagonal is used (below main diagonal, towards bottom-left corner)
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i>k</i> is optional; by default the main diagonal is used (<i>k = 0</i>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i><b>size(</b>A<b>)</b></i> can be replaced with <i><b>size(</b>n_rows<b>,</b> n_cols<b>)</b></i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
uvec upper_indices = trimatu_ind( size(A) );
|
|
uvec lower_indices = trimatl_ind( size(A) );
|
|
|
|
// extract upper/lower triangle into vector
|
|
vec upper_part = A(upper_indices);
|
|
vec lower_part = A(lower_indices);
|
|
|
|
// obtain indices without the main diagonal
|
|
uvec alt_upper_indices = trimatu_ind( size(A), 1);
|
|
uvec alt_lower_indices = trimatl_ind( size(A), -1);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#trimat">trimatu() / trimatl()</a></li>
|
|
<li><a href="#find">find()</a></li>
|
|
<li><a href="#submat">submatrix views</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X = { { 1, 2 }
|
|
{ 2, 3 } };
|
|
|
|
mat Y = unique(X);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#find">find()</a></li>
|
|
<li><a href="#find_unique">find_unique()</a></li>
|
|
<li><a href="#sort">sort()</a></li>
|
|
<li><a href="#shuffle">shuffle()</a></li>
|
|
<li><a href="#nonzeros">nonzeros()</a></li>
|
|
<li><a href="#intersect">intersect()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="vecnorm"></a>
|
|
<b>vecnorm( X )</b>
|
|
<br><b>vecnorm( X, p )</b>
|
|
<br><b>vecnorm( X, p, dim )</b>
|
|
<ul>
|
|
<li>
|
|
Compute the <i>p</i>-norm of each column vector <i>(dim = 0)</i> or row vector <i>(dim = 1)</i> of matrix <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>p</i> is an integer ≥ 1, or <code>"-inf"</code> (minimum quasi-norm), or <code>"inf"</code> (maximum norm)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The arguments <i>p</i> and <i>dim</i> are optional; by default <i>p = 2</i> and <i>dim = 0</i> are used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> to compute the matrix norm, use <a href="#norm">norm()</a> instead
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(4, 5, fill::randu);
|
|
|
|
rowvec r = vecnorm(X, 2);
|
|
|
|
colvec c = vecnorm(X, "inf", 1);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#norm">norm()</a></li>
|
|
<li><a href="#normalise">normalise()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Norm_(mathematics)">vector norm in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/VectorNorm.html">vector norm in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="vectorise"></a>
|
|
<b>vectorise( X )</b>
|
|
<br><b>vectorise( X, dim )</b>
|
|
<br><b>vectorise( Q )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a flattened version of matrix <i>X</i> or cube <i>Q</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, resulting in a column vector; 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, resulting in a row vector; equivalent to concatenating all the rows of <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>column-wise vectorisation is faster than row-wise vectorisation</li>
|
|
<li>for sparse matrices, row-wise vectorisation is not recommended</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(4, 5, fill::randu);
|
|
|
|
vec v = vectorise(X);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#as_col_row">.as_col() / .as_row()</a></li>
|
|
<li><a href="#col_row_as_mat">.col_as_mat() / .row_as_mat()</a></li>
|
|
<li><a href="#nonzeros">nonzeros()</a></li>
|
|
<li><a href="#reshape">reshape()</a></li>
|
|
<li><a href="#resize">resize()</a></li>
|
|
<li><a href="#diagvec">diagvec()</a></li>
|
|
<li><a href="#as_scalar">as_scalar()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="misc_fns"></a>
|
|
<b>miscellaneous element-wise functions:</b>
|
|
<ul>
|
|
<table border="0" cellpadding="0" cellspacing="0">
|
|
<tr><td><b>exp </b></td><td> </td><td><b>log </b></td><td> </td><td><b>square</b></td><td> </td><td><b>floor </b></td><td> </td><td><b>erf </b></td><td> </td><td><b>tgamma</b></td><td> </td><td><b>sign </b></td></tr>
|
|
<tr><td><b>exp2 </b></td><td> </td><td><b>log2 </b></td><td> </td><td><b>sqrt </b></td><td> </td><td><b>ceil </b></td><td> </td><td><b>erfc </b></td><td> </td><td><b>lgamma</b></td><td> </td><td><b> </b></td></tr>
|
|
<tr><td><b>exp10 </b></td><td> </td><td><b>log10 </b></td><td> </td><td><b>cbrt </b></td><td> </td><td><b>round </b></td><td> </td><td><b> </b></td><td> </td><td><b> </b></td><td> </td><td><b> </b></td></tr>
|
|
<tr><td><b>expm1 </b></td><td> </td><td><b>log1p </b></td><td> </td><td><b> </b></td><td> </td><td><b>trunc </b></td><td> </td><td><b> </b></td><td> </td><td><b> </b></td><td> </td><td><b> </b></td></tr>
|
|
<tr><td><b>trunc_exp</b></td><td> </td><td><b>trunc_log</b></td><td> </td><td><b> </b></td><td> </td><td><b> </b></td><td> </td><td><b> </b></td><td> </td><td><b> </b></td><td> </td><td><b> </b></td></tr>
|
|
</table>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
Apply a function to each element
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Usage:
|
|
<ul>
|
|
<li><i>B = fn(A)</i>, where <i>fn(A)</i> is one of the functions below</li>
|
|
<li><i>A</i> and <i>B</i> must have the same matrix type or cube type, such as <i>mat</i> or <i>cube</i></li>
|
|
</ul>
|
|
<br>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr style="background-color: #F5F5F5;">
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>exp(A)</code><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 style="background-color: #F5F5F5;">
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>exp2(A)</code><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 style="background-color: #F5F5F5;">
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>exp10(A)</code><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; text-align: right;">
|
|
<code>expm1(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
compute <code>exp(A)-1</code> accurately for values of A close to zero <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>trunc_exp(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
base-e exponential,
|
|
truncated to avoid infinity <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
|
|
</td>
|
|
</tr>
|
|
<tr style="background-color: #F5F5F5;">
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>log(A)</code><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 style="background-color: #F5F5F5;">
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>log2(A)</code><sub> </sub>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
base-2 log: <i>log<sub><small>2</small></sub> x</i>
|
|
</td>
|
|
</tr>
|
|
<tr style="background-color: #F5F5F5;">
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>log10(A)</code><sub> </sub>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
base-10 log: <i>log<sub><small>10</small></sub> x</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>log1p(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
compute <code>log(1+A)</code> accurately for values of A close to zero <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>trunc_log(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
natural log,
|
|
truncated to avoid ±infinity <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
|
|
</td>
|
|
</tr>
|
|
<tr style="background-color: #F5F5F5;">
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>square(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
square: <i>x<sup><small> 2</small></sup></i>
|
|
</td>
|
|
</tr>
|
|
<tr style="background-color: #F5F5F5;">
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>sqrt(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
square root: <i>√x</i>
|
|
</td>
|
|
</tr>
|
|
<tr style="background-color: #F5F5F5;">
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>cbrt(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
cube root: <i>∛x</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>floor(A)</code>
|
|
</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; text-align: right;">
|
|
<code>ceil(A)</code>
|
|
</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; text-align: right;">
|
|
<code>round(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
round to nearest integer, with halfway cases rounded away from zero
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>trunc(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
round to nearest integer, towards zero
|
|
</td>
|
|
</tr>
|
|
<tr style="background-color: #F5F5F5;">
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>erf(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
error function <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
|
|
</td>
|
|
</tr>
|
|
<tr style="background-color: #F5F5F5;">
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>erfc(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
complementary error function <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>tgamma(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
gamma function <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>lgamma(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
natural log of the absolute value of gamma function <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
|
|
</td>
|
|
</tr>
|
|
<tr style="background-color: #F5F5F5;">
|
|
<td style="vertical-align: top; text-align: right;">
|
|
<code>sign(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
signum function;
|
|
for each element <i>a</i> in <i>A</i>, the corresponding element <i>b</i> in <i>B</i> is:
|
|
<ul>
|
|
<table border="0" cellpadding="0" cellspacing="0">
|
|
<tbody>
|
|
<tr><td> </td><td>⎧ </td><td style="text-align: right;">−1</td><td> if <i>a</i> < 0</td></tr>
|
|
<tr><td>b = </td><td>⎨ </td><td style="text-align: right;"> 0</td><td> if <i>a</i> = 0</td></tr>
|
|
<tr><td> </td><td>⎩ </td><td style="text-align: right;"> +1</td><td> if <i>a</i> > 0</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
if <i>a</i> is complex and non-zero, then <i>b</i> = <i>a</i> / abs(<i>a</i>)
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>all of the above functions are applied element-wise, where each element is treated independently</li>
|
|
<li>
|
|
the element-wise functions <i>exp()</i>, <i>log()</i> and <i>sqrt()</i>
|
|
have the corresponding functions <a href="#expmat">expmat()</a>, <a href="#logmat">logmat()</a> and <a href="#sqrtmat">sqrtmat()</a> which take into account matrix structure
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
mat B = exp(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#abs">abs()</a></li>
|
|
<li><a href="#pow">pow()</a></li>
|
|
<li><a href="#clamp">clamp()</a></li>
|
|
<li><a href="#conj">conj()</a></li>
|
|
<li><a href="#imag_real">imag() / real()</a></li>
|
|
<li><a href="#transform">.transform()</a> (apply user-defined function to each element)</li>
|
|
<li><a href="#expmat">expmat()</a></li>
|
|
<li><a href="#logmat">logmat()</a></li>
|
|
<li><a href="#sqrtmat">sqrtmat()</a></li>
|
|
<li><a href="#trig_fns">trigonometric functions</a></li>
|
|
<li><a href="#stats_fns">statistics functions</a></li>
|
|
<li><a href="#constants">miscellaneous constants</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="trig_fns"></a>
|
|
<b>trigonometric element-wise functions (cos, sin, tan, ...)</b>
|
|
<ul>
|
|
<li>
|
|
For single argument functions, <i>B = trig_fn(A)</i>, where <i>trig_fn</i> is applied to each element in <i>A</i>, with <i>trig_fn</i> as one of:
|
|
<ul>
|
|
<li>
|
|
<i>cos</i>, <i>acos</i>, <i>cosh</i>, <i>acosh</i>
|
|
</li>
|
|
<li>
|
|
<i>sin</i>, <i>asin</i>, <i>sinh</i>, <i>asinh</i>
|
|
</li>
|
|
<li>
|
|
<i>tan</i>, <i>atan</i>, <i>tanh</i>, <i>atanh</i>
|
|
</li>
|
|
<li>
|
|
<i>sinc</i>, defined as sinc(x) = sin(πx) / (πx) for x ≠ 0, and sinc(x) = 1 for x = 0
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For dual argument functions, apply the function to each tuple of two corresponding elements in <i>X</i> and <i>Y</i>:
|
|
<ul>
|
|
<li><i>Z = atan2(Y, X)</i></li>
|
|
<li><i>Z = hypot(X, Y)</i></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(5, 5, fill::randu);
|
|
mat Y = cos(X);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Trigonometric_functions">trigonometric functions in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Atan2">atan2 function in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Hypot">hypot function in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Sinc_function">sinc function in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div>
|
|
<hr class="greyline">
|
|
<hr class="greyline">
|
|
<br>
|
|
<br>
|
|
<font size=+1><b>Decompositions, Factorisations, Inverses and Equation Solvers (Dense Matrices)</b></font>
|
|
<br>
|
|
<br>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="chol"></a>
|
|
<table>
|
|
<tr><td><b>R = chol( X )</b></td><td> </td><td>(form 1)</td></tr>
|
|
<tr><td><b>R = chol( X, layout )</b></td><td> </td><td>(form 2)</td></tr>
|
|
<tr><td> </td><td> </td><td> </td></tr>
|
|
<tr><td><b> chol( R, X )</b></td><td> </td><td>(form 3)</td></tr>
|
|
<tr><td><b> chol( R, X, layout )</b></td><td> </td><td>(form 4)</td></tr>
|
|
<tr><td> </td><td> </td><td> </td></tr>
|
|
<tr><td><b> chol( R, P, X, layout, "vector" )</b></td><td> </td><td>(form 5)</td></tr>
|
|
<tr><td><b> chol( R, P, X, layout, "matrix" )</b></td><td> </td><td>(form 6)</td></tr>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
Cholesky decomposition of symmetric/hermitian matrix <i>X</i> into triangular matrix <i>R</i>, with an optional permutation vector/matrix <i>P</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
By default, <i>R</i> is upper triangular
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The optional argument <i>layout</i> is either <code>"upper"</code> or <code>"lower"</code>, which specifies whether <i>R</i> is upper or lower triangular
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Forms 1 to 4 require <i>X</i> to be positive definite
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Forms 5 to 6 require <i>X</i> to be positive semi-definite; pivoted decomposition provides a permutation vector/matrix <i>P</i> with type <a href="#Col">uvec</a> or <a href="#Mat">umat</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The decomposition has the following form:
|
|
<ul>
|
|
<li>forms 1 and 3: <i>X = R.t() * R</i></li>
|
|
<li>forms 2 and 4 with <i>layout = "upper"</i>: <i>X = R.t() * R</i></li>
|
|
<li>forms 2 and 4 with <i>layout = "lower"</i>: <i>X = R * R.t()</i></li>
|
|
<li>form 5 with <i>layout = "upper"</i>: <i>X(P,P) = R.t() * R</i>, where <i>X(P,P)</i> is a <a href="#submat">non-contiguous view</a> of <i>X</i></li>
|
|
<li>form 5 with <i>layout = "lower"</i>: <i>X(P,P) = R * R.t()</i>, where <i>X(P,P)</i> is a <a href="#submat">non-contiguous view</a> of <i>X</i></li>
|
|
<li>form 6 with <i>layout = "upper"</i>: <i>X = P * R.t() * R * P.t()</i></li>
|
|
<li>form 6 with <i>layout = "lower"</i>: <i>X = P * R * R.t() * P.t()</i></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>If the decomposition fails:
|
|
<ul>
|
|
<li>the forms <i>R = chol(X)</i> and <i>R = chol(X,layout)</i> reset <i>R</i> and throw a <i>std::runtime_error</i> exception</li>
|
|
<li>the other forms reset <i>R</i> and <i>P</i>, and return a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> to find the inverse of a positive definite matrix, use <a href="#inv_sympd">inv_sympd()</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
mat X = A.t()*A;
|
|
|
|
mat R1 = chol(X);
|
|
mat R2 = chol(X, "lower");
|
|
|
|
mat R3;
|
|
bool ok = chol(R3, X);
|
|
|
|
mat R;
|
|
uvec P_vec;
|
|
umat P_mat;
|
|
|
|
chol(R, P_vec, X, "upper", "vector");
|
|
chol(R, P_mat, X, "lower", "matrix");
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#sqrtmat">sqrtmat()</a></li>
|
|
<li><a href="#lu">lu()</a></li>
|
|
<li><a href="#qr">qr()</a></li>
|
|
<li><a href="#inv_sympd">inv_sympd()</a></li>
|
|
<li><a href="#is_sympd">.is_sympd()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/CholeskyDecomposition.html">Cholesky decomposition in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Cholesky_decomposition">Cholesky decomposition in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Definite_matrix">Definite matrix in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="eig_sym"></a>
|
|
<b>vec eigval = eig_sym( X )</b>
|
|
<br>
|
|
<br><b>eig_sym( eigval, X )</b>
|
|
<br>
|
|
<br><b>eig_sym( eigval, eigvec, X )</b>
|
|
<br><b>eig_sym( eigval, eigvec, X, method )</b>
|
|
<ul>
|
|
<li>Eigen decomposition of <b>dense</b> 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>The eigenvectors are stored as column vectors</li>
|
|
<br>
|
|
<li>If <i>X</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>
|
|
The <i>method</i> argument is optional; <i>method</i> is either <code>"dc"</code> or <code>"std"</code>
|
|
<ul>
|
|
<li>
|
|
<code>"dc"</code> indicates divide-and-conquer method (default setting)
|
|
</li>
|
|
<li>
|
|
<code>"std"</code> indicates standard method
|
|
</li>
|
|
<li>
|
|
the divide-and-conquer method provides slightly different results than the standard method, but is considerably faster for large matrices
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>If the decomposition fails:
|
|
<ul>
|
|
<li><i>eigval = eig_sym(X)</i> resets <i>eigval</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>eig_sym(eigval,X)</i> resets <i>eigval</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>eig_sym(eigval,eigvec,X)</i> resets <i>eigval</i> & <i>eigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<!--
|
|
<br>
|
|
<li><b>Caveat:</b> there is no explicit check whether <i>X</i> is symmetric/hermitian</li>
|
|
-->
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
// for matrices with real elements
|
|
|
|
mat A(50, 50, fill::randu);
|
|
mat B = A.t()*A; // generate a symmetric matrix
|
|
|
|
vec eigval;
|
|
mat eigvec;
|
|
|
|
eig_sym(eigval, eigvec, B);
|
|
|
|
|
|
// for matrices with complex elements
|
|
|
|
cx_mat C(50, 50, fill::randu);
|
|
cx_mat D = C.t()*C;
|
|
|
|
vec eigval2;
|
|
cx_mat eigvec2;
|
|
|
|
eig_sym(eigval2, eigvec2, D);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#eig_gen">eig_gen()</a></li>
|
|
<li><a href="#eig_pair">eig_pair()</a></li>
|
|
<li><a href="#svd">svd()</a></li>
|
|
<li><a href="#svd_econ">svd_econ()</a></li>
|
|
<li><a href="#princomp">princomp()</a></li>
|
|
<li><a href="#eigs_sym">eigs_sym()</a></li>
|
|
<li><a href="#is_symmetric">.is_symmetric()</a></li>
|
|
<li><a href="#is_hermitian">.is_hermitian()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors">eigenvalues & eigenvectors in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Divide-and-conquer_eigenvalue_algorithm">divide & conquer eigenvalue algorithm in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="eig_gen"></a>
|
|
<b>cx_vec eigval = eig_gen( X )</b>
|
|
<br><b>cx_vec eigval = eig_gen( X, bal )</b>
|
|
<br>
|
|
<br><b>eig_gen( eigval, X )</b>
|
|
<br><b>eig_gen( eigval, X, bal )</b>
|
|
<br>
|
|
<br><b>eig_gen( eigval, eigvec, X )</b>
|
|
<br><b>eig_gen( eigval, eigvec, X, bal )</b>
|
|
<br>
|
|
<br><b>eig_gen( eigval, leigvec, reigvec, X )</b>
|
|
<br><b>eig_gen( eigval, leigvec, reigvec, X, bal )</b>
|
|
<ul>
|
|
<li>Eigen decomposition of <b>dense</b> general (non-symmetric/non-hermitian) square matrix <i>X</i></li>
|
|
<br>
|
|
<li>The eigenvalues and corresponding right eigenvectors are stored in <i>eigval</i> and <i>eigvec</i>, respectively</li>
|
|
<br>
|
|
<li>If both left and right eigenvectors are requested they are stored in <i>leigvec</i> and <i>reigvec</i>, respectively</li>
|
|
<br>
|
|
<li>The eigenvectors are stored as column vectors</li>
|
|
<br>
|
|
<li>
|
|
The <i>bal</i> argument is optional; <i>bal</i> is one of:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>"balance"</code></td><td> ↦ </td><td>diagonally scale and permute <i>X</i> to improve conditioning of the eigenvalues</td></tr>
|
|
<tr><td><code>"nobalance"</code></td><td> ↦ </td><td>do not balance <i>X</i>; this is the <b>default operation</b></td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>If <i>X</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the decomposition fails:
|
|
<ul>
|
|
<li><i>eigval = eig_gen(X)</i> resets <i>eigval</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>eig_gen(eigval,X)</i> resets <i>eigval</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>eig_gen(eigval,eigvec,X)</i> resets <i>eigval</i> & <i>eigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>eig_gen(eigval,leigvec,reigvec,X)</i> resets <i>eigval</i>, <i>leigvec</i> & <i>reigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(10, 10, fill::randu);
|
|
|
|
cx_vec eigval;
|
|
cx_mat eigvec;
|
|
|
|
eig_gen(eigval, eigvec, A);
|
|
eig_gen(eigval, eigvec, A, "balance");
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#eig_pair">eig_pair()</a></li>
|
|
<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="#schur">schur()</a></li>
|
|
<li><a href="#eigs_gen">eigs_gen()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors">eigenvalues & eigenvectors in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="eig_pair"></a>
|
|
<b>cx_vec eigval = eig_pair( A, B )</b>
|
|
<br>
|
|
<br><b>eig_pair( eigval, A, B )</b>
|
|
<br>
|
|
<br><b>eig_pair( eigval, eigvec, A, B )</b>
|
|
<br>
|
|
<br><b>eig_pair( eigval, leigvec, reigvec, A, B )</b>
|
|
<ul>
|
|
<li>
|
|
Eigen decomposition for pair of general <b>dense</b> square matrices <i>A</i> and <i>B</i> of the same size,
|
|
such that <i>A*eigvec = B*eigvec*diagmat(eigval)</i>
|
|
</li>
|
|
<br>
|
|
<li>The eigenvalues and corresponding right eigenvectors are stored in <i>eigval</i> and <i>eigvec</i>, respectively</li>
|
|
<br>
|
|
<li>If both left and right eigenvectors are requested they are stored in <i>leigvec</i> and <i>reigvec</i>, respectively</li>
|
|
<br>
|
|
<li>The eigenvectors are stored as column vectors</li>
|
|
<br>
|
|
<li>If <i>A</i> or <i>B</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the decomposition fails:
|
|
<ul>
|
|
<li><i>eigval = eig_pair(A,B)</i> resets <i>eigval</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>eig_pair(eigval,A,B)</i> resets <i>eigval</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>eig_pair(eigval,eigvec,A,B)</i> resets <i>eigval</i> & <i>eigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>eig_pair(eigval,leigvec,reigvec,A,B)</i> resets <i>eigval</i>, <i>leigvec</i> & <i>reigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(10, 10, fill::randu);
|
|
mat B(10, 10, fill::randu);
|
|
|
|
cx_vec eigval;
|
|
cx_mat eigvec;
|
|
|
|
eig_pair(eigval, eigvec, A, B);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#eig_gen">eig_gen()</a></li>
|
|
<li><a href="#eig_sym">eig_sym()</a></li>
|
|
<li><a href="#qz">qz()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors">eigenvalues & eigenvectors in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="hess"></a>
|
|
<b>H = hess( X )</b>
|
|
<br>
|
|
<br><b>hess( H, X )</b>
|
|
<br>
|
|
<br><b>hess( U, H, X )</b>
|
|
<ul>
|
|
<li>Upper Hessenberg decomposition of square matrix <i>X</i>, such that <i>X = U*H*U.t()</i></li>
|
|
<br>
|
|
<li><i>U</i> is a unitary matrix containing the Hessenberg vectors</li>
|
|
<br>
|
|
<li><i>H</i> is a square matrix known as the upper Hessenberg matrix, with elements below the first subdiagonal set to zero</li>
|
|
<br>
|
|
<li>If <i>X</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the decomposition fails:
|
|
<ul>
|
|
<li><i>H = hess(X)</i> resets <i>H</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>hess(H,X)</i> resets <i>H</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>hess(U,H,X)</i> resets <i>U</i> & <i>H</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> in general, upper Hessenberg decomposition is not unique
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(20,20, fill::randu);
|
|
|
|
mat U;
|
|
mat H;
|
|
|
|
hess(U, H, X);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#qz">qz()</a></li>
|
|
<li><a href="#schur">schur()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/HessenbergDecomposition.html">Hessenberg decomposition in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Hessenberg_matrix">Hessenberg matrix in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="inv"></a>
|
|
<b>B = inv( A )</b>
|
|
<br><b>B = inv( A, settings )</b>
|
|
<br>
|
|
<br><b>inv( B, A )</b>
|
|
<br><b>inv( B, A, settings )</b>
|
|
<br>
|
|
<br><b>inv( B, rcond, A )</b>
|
|
<ul>
|
|
<li>
|
|
Inverse of general square matrix <i>A</i>
|
|
</li>
|
|
<br>
|
|
<li>The <i>settings</i> argument is optional; it is one of the following:
|
|
<br>
|
|
<br>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>inv_opts::no_ugly</code></td><td> </td><td>do not provide inverses for poorly conditioned matrices (where <i>rcond < A.n_rows · <a href="#constants">datum::eps</a></i>)</td></tr>
|
|
<tr><td><code>inv_opts::allow_approx</code></td><td> </td><td>allow approximate inverses for rank deficient or poorly conditioned matrices</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The reciprocal condition number is optionally calculated and stored in <i>rcond</i>
|
|
<ul>
|
|
<li><i>rcond</i> close to 1 suggests that <i>A</i> is well-conditioned</li>
|
|
<li><i>rcond</i> close to 0 suggests that <i>A</i> is badly conditioned</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown
|
|
</li>
|
|
<br>
|
|
<li>If <i>A</i> appears to be singular:
|
|
<ul>
|
|
<li><i>B = inv(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>inv(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>inv(B,rcond,A)</i> resets <i>B</i>, sets <i>rcond</i> to zero, and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>if matrix <i>A</i> is know to be symmetric positive definite, <a href="#inv_sympd">inv_sympd()</a> is faster</li>
|
|
<li>if matrix <i>A</i> is know to be diagonal, use <i>inv( diagmat(A) )</i></li>
|
|
<li>if matrix <i>A</i> is know to be triangular, use <i>inv( trimatu(A) )</i> or <i>inv( trimatl(A) )</i></li>
|
|
<li>to solve a system of linear equations, such as <i>Z = inv(X)*Y</i>, <a href="#solve">solve()</a> can be faster and/or more accurate</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
mat B = inv(A);
|
|
|
|
mat C;
|
|
bool success = inv(C, A);
|
|
|
|
mat D;
|
|
double rcond_val;
|
|
inv(D, rcond_val, A);
|
|
|
|
A.col(1).zeros();
|
|
mat E;
|
|
inv(E, A, inv_opts::allow_approx);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#i_member">.i()</a>
|
|
<li><a href="#inv_sympd">inv_sympd()</a>
|
|
<li><a href="#rcond">rcond()</a>
|
|
<li><a href="#pinv">pinv()</a>
|
|
<li><a href="#solve">solve()</a></li>
|
|
<li><a href="#diagmat">diagmat()</a></li>
|
|
<li><a href="#trimat">trimatu() / trimatl()</a></li>
|
|
<li><a href="#powmat">powmat()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/MatrixInverse.html">matrix inverse in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Invertible_matrix">invertible matrix in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="inv_sympd"></a>
|
|
<b>B = inv_sympd( A )</b>
|
|
<br><b>B = inv_sympd( A, settings )</b>
|
|
<br>
|
|
<br><b>inv_sympd( B, A )</b>
|
|
<br><b>inv_sympd( B, A, settings )</b>
|
|
<br>
|
|
<br><b>inv_sympd( B, rcond, A )</b>
|
|
<ul>
|
|
<li>
|
|
Inverse of symmetric/hermitian positive definite matrix <i>A</i>
|
|
</li>
|
|
<br>
|
|
<li>The <i>settings</i> argument is optional; it is one of the following:
|
|
<br>
|
|
<br>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>inv_opts::no_ugly</code></td><td> </td><td>do not provide inverses for poorly conditioned matrices (where <i>rcond < A.n_rows · <a href="#constants">datum::eps</a></i>)</td></tr>
|
|
<tr><td><code>inv_opts::allow_approx</code></td><td> </td><td>allow approximate inverses for rank deficient or poorly conditioned symmetric matrices</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The reciprocal condition number is optionally calculated and stored in <i>rcond</i>
|
|
<ul>
|
|
<li><i>rcond</i> close to 1 suggests that <i>A</i> is well-conditioned</li>
|
|
<li><i>rcond</i> close to 0 suggests that <i>A</i> is badly conditioned</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown
|
|
</li>
|
|
<br>
|
|
<li>If <i>A</i> appears to be singular or not positive definite:
|
|
<ul>
|
|
<li><i>B = inv_sympd(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>inv_sympd(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>inv_sympd(B,rcond,A)</i> resets <i>B</i>, sets rcond to zero, and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<!--
|
|
<br>
|
|
<li><b>Caveat:</b> there is no explicit check whether <i>A</i> is symmetric/hermitian positive definite</li>
|
|
-->
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b>
|
|
to solve a system of linear equations, such as <i>Z = inv(X)*Y</i>,
|
|
using <a href="#solve">solve()</a> can be faster and/or more accurate
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
mat B = A.t() * A;
|
|
|
|
mat C = inv_sympd(B);
|
|
|
|
mat D;
|
|
bool success = inv_sympd(D, B);
|
|
|
|
mat E;
|
|
double rcond_val;
|
|
inv_sympd(E, rcond_val, B);
|
|
|
|
B.col(1).zeros();
|
|
B.row(1).zeros();
|
|
mat F;
|
|
inv_sympd(F, B, inv_opts::allow_approx);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#inv">inv()</a>
|
|
<li><a href="#rcond">rcond()</a>
|
|
<li><a href="#pinv">pinv()</a>
|
|
<li><a href="#solve">solve()</a></li>
|
|
<li><a href="#eig_sym">eig_sym()</a></li>
|
|
<li><a href="#is_sympd">.is_sympd()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/MatrixInverse.html">matrix inverse in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Invertible_matrix">invertible matrix in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/PositiveDefiniteMatrix.html">positive definite matrix in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Positive-definite_matrix">positive definite matrix in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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:
|
|
<ul>
|
|
<li><i>lu(L,U,P,X)</i> resets <i>L</i>, <i>U</i>, <i>P</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>lu(L,U,X)</i> resets <i>L</i>, <i>U</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
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="#chol">chol()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/LU_decomposition">LU decomposition in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/LUDecomposition.html">LU decomposition in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="null"></a>
|
|
<b>B = null( A )</b>
|
|
<br><b>B = null( A, tolerance )</b>
|
|
<br>
|
|
<br><b>null( B, A )</b>
|
|
<br><b>null( B, A, tolerance )</b>
|
|
<ul>
|
|
<li>
|
|
Find the orthonormal basis of the null space of matrix <i>A</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The dimension of the range space is the number of singular values of <i>A</i> not greater than <i>tolerance</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>tolerance</i> argument is optional; by default <i>tolerance = max_rc · max_sv · epsilon</i>, where:
|
|
<ul>
|
|
<li><i>max_rc</i> = max(A.n_rows, A.n_cols)</li>
|
|
<li><i>max_sv</i> = maximum singular value of <i>A</i> (ie. spectral norm)</li>
|
|
<li><i>epsilon</i> = difference between 1 and the least value greater than 1 that is representable</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The computation is based on singular value decomposition; if the decomposition fails:
|
|
<ul>
|
|
<li><i>B = null(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>null(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 6, fill::randu);
|
|
|
|
A.row(0).zeros();
|
|
A.col(0).zeros();
|
|
|
|
mat B = null(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#orth">orth()</a></li>
|
|
<li><a href="#qr">qr()</a></li>
|
|
<li><a href="#svd">svd()</a></li>
|
|
<li><a href="#rank">rank()</a></li>
|
|
<li><a href="#constants">datum::eps</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Orthonormal_basis">Orthonormal basis in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="orth"></a>
|
|
<b>B = orth( A )</b>
|
|
<br><b>B = orth( A, tolerance )</b>
|
|
<br>
|
|
<br><b>orth( B, A )</b>
|
|
<br><b>orth( B, A, tolerance )</b>
|
|
<ul>
|
|
<li>
|
|
Find the orthonormal basis of the range space of matrix <i>A</i>,
|
|
so that <i>B.t()*B ≈ eye(r,r)</i>, where <i>r = rank(A)</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The dimension of the range space is the number of singular values of <i>A</i> greater than <i>tolerance</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>tolerance</i> argument is optional; by default <i>tolerance = max_rc · max_sv · epsilon</i>, where:
|
|
<ul>
|
|
<li><i>max_rc</i> = max(A.n_rows, A.n_cols)</li>
|
|
<li><i>max_sv</i> = maximum singular value of <i>A</i> (ie. spectral norm)</li>
|
|
<li><i>epsilon</i> = difference between 1 and the least value greater than 1 that is representable</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The computation is based on singular value decomposition; if the decomposition fails:
|
|
<ul>
|
|
<li><i>B = orth(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>orth(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 6, fill::randu);
|
|
|
|
mat B = orth(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#null">null()</a></li>
|
|
<li><a href="#qr">qr()</a></li>
|
|
<li><a href="#svd">svd()</a></li>
|
|
<li><a href="#rank">rank()</a></li>
|
|
<li><a href="#constants">datum::eps</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Orthonormal_basis">Orthonormal basis in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="pinv"></a>
|
|
<b>B = pinv( A )</b>
|
|
<br><b>B = pinv( A, tolerance )</b>
|
|
<br><b>B = pinv( A, tolerance, method )</b>
|
|
<br>
|
|
<br><b>pinv( B, A )</b>
|
|
<br><b>pinv( B, A, tolerance )</b>
|
|
<br><b>pinv( B, A, tolerance, method )</b>
|
|
<ul>
|
|
<li>Moore-Penrose pseudo-inverse (generalised inverse) of matrix <i>A</i></li>
|
|
<br>
|
|
<li>
|
|
The computation is based on singular value decomposition
|
|
</li>
|
|
<br>
|
|
<li>The <i>tolerance</i> argument is optional;
|
|
by default <i>tolerance = max_rc · max_sv · epsilon</i>, where:
|
|
<ul>
|
|
<li><i>max_rc</i> = max(A.n_rows, A.n_cols)</li>
|
|
<li><i>max_sv</i> = maximum singular value of <i>A</i> (ie. spectral norm)</li>
|
|
<li><i>epsilon</i> = difference between 1 and the least value greater than 1 that is representable</li>
|
|
</ul>
|
|
</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; <i>method</i> is either <code>"dc"</code> or <code>"std"</code>
|
|
<ul>
|
|
<li>
|
|
<code>"dc"</code> indicates divide-and-conquer method (default setting)
|
|
</li>
|
|
<li>
|
|
<code>"std"</code> indicates standard method
|
|
</li>
|
|
<li>
|
|
the divide-and-conquer method provides slightly different results than the standard method, but is considerably faster for large matrices
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>If the decomposition fails:
|
|
<ul>
|
|
<li><i>B = pinv(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>pinv(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>
|
|
to find approximate solutions to under-/over-determined or rank deficient systems of linear equations,
|
|
<a href="#solve">solve()</a> can be considerably faster and/or more accurate
|
|
</li>
|
|
<li>
|
|
if the given matrix <i>A</i> is square-sized and only occasionally rank deficient,
|
|
using <a href="#inv">inv()</a> or <a href="#inv_sympd">inv_sympd()</a> with the <code>inv_opts::allow_approx</code> option is faster
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(4, 5, fill::randu);
|
|
|
|
mat B = pinv(A); // use default tolerance
|
|
|
|
mat C = pinv(A, 0.01); // set tolerance to 0.01
|
|
</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="#svd">svd()</a></li>
|
|
<li><a href="#constants">datum::eps</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Pseudoinverse.html">Pseudoinverse in MathWorld</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Moore-PenroseMatrixInverse.html">Moore-Penrose Matrix Inverse in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Moore-Penrose_inverse">Moore-Penrose inverse in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="qr"></a>
|
|
<table>
|
|
<tr><td><b>qr( Q, R, X )</b></td><td> </td><td>(form 1)</td></tr>
|
|
<tr><td><b>qr( Q, R, P, X, "vector" )</b></td><td> </td><td>(form 2)</td></tr>
|
|
<tr><td><b>qr( Q, R, P, X, "matrix" )</b></td><td> </td><td>(form 3)</td></tr>
|
|
</table>
|
|
<ul>
|
|
<li>
|
|
Decomposition of <i>X</i> into an orthogonal matrix <i>Q</i> and a right triangular matrix <i>R</i>,
|
|
with an optional permutation matrix/vector <i>P</i>
|
|
<ul>
|
|
<li>form 1: decomposition has the form <i>Q*R = X</i></li>
|
|
<li>form 2: <i>P</i> is permutation vector with type <a href="#Col">uvec</a>; decomposition has the form <i>Q*R = X.cols(P)</i></li>
|
|
<li>form 3: <i>P</i> is permutation matrix with type <a href="#Mat">umat</a>; decomposition has the form <i>Q*R = X*P</i></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If <i>P</i> is specified, a column pivoting decomposition is used;
|
|
the diagonal entries of <i>R</i> are ordered from largest to smallest magnitude
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If the decomposition fails, <i>Q</i>, <i>R</i> and <i>P</i> are reset and the function returns a bool set to <i>false</i> (exception is not thrown)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(5, 5, fill::randu);
|
|
|
|
mat Q;
|
|
mat R;
|
|
|
|
qr(Q, R, X);
|
|
|
|
uvec P_vec;
|
|
umat P_mat;
|
|
|
|
qr(Q, R, P_vec, X, "vector");
|
|
qr(Q, R, P_mat, X, "matrix");
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#qr_econ">qr_econ()</a></li>
|
|
<li><a href="#chol">chol()</a></li>
|
|
<li><a href="#orth">orth()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Orthogonal_matrix">orthogonal matrix in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/QR_decomposition">QR decomposition in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/QRDecomposition.html">QR decomposition in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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> (exception is not thrown)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(6, 5, fill::randu);
|
|
|
|
mat Q;
|
|
mat R;
|
|
|
|
qr_econ(Q, R, X);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#qr">qr()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Orthogonal_matrix">orthogonal matrix in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/QR_decomposition">QR decomposition in Wikipedia</a></li>
|
|
<li><a href="https://octave.sourceforge.net/octave/function/qr.html">QR decomposition in Octave</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/QRDecomposition.html">QR decomposition in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="qz"></a>
|
|
<b>qz( AA, BB, Q, Z, A, B )</b>
|
|
<br><b>qz( AA, BB, Q, Z, A, B, select )</b>
|
|
<ul>
|
|
<li>
|
|
Generalised Schur decomposition for pair of general square matrices <i>A</i> and <i>B</i> of the same size,
|
|
<br>such that <i>A = Q.t()*AA*Z.t()</i> and <i>B = Q.t()*BB*Z.t()</i>
|
|
</li>
|
|
<br>
|
|
<li>The <i>select</i> argument is optional and specifies the ordering of the top left of the Schur form; it is one of the following:
|
|
<br>
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>"none"</code></td><td> </td><td>no ordering (default operation)</td></tr>
|
|
<tr><td><code>"lhp"</code></td><td> </td><td>left-half-plane: eigenvalues with real part < 0</td></tr>
|
|
<tr><td><code>"rhp"</code></td><td> </td><td>right-half-plane: eigenvalues with real part > 0</td></tr>
|
|
<tr><td><code>"iuc"</code></td><td> </td><td>inside-unit-circle: eigenvalues with absolute value < 1</td></tr>
|
|
<tr><td><code>"ouc"</code></td><td> </td><td>outside-unit-circle: eigenvalues with absolute value > 1</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>The left and right Schur vectors are stored in <i>Q</i> and <i>Z</i>, respectively</li>
|
|
<br>
|
|
<li>In the complex-valued problem, the generalised eigenvalues are found in <i>diagvec(AA) / diagvec(BB)</i></li>
|
|
<br>
|
|
<li>If <i>A</i> or <i>B</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the decomposition fails, <i>AA</i>, <i>BB</i>, <i>Q</i> and <i>Z</i> are reset, and the function returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(10, 10, fill::randu);
|
|
mat B(10, 10, fill::randu);
|
|
|
|
mat AA;
|
|
mat BB;
|
|
mat Q;
|
|
mat Z;
|
|
|
|
qz(AA, BB, Q, Z, A, B);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#hess">hess()</a></li>
|
|
<li><a href="#schur">schur()</a></li>
|
|
<li><a href="#eig_pair">eig_pair()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Schur_decomposition#Generalized_Schur_decomposition">generalised Schur decomposition in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="schur"></a>
|
|
<b>S = schur( X )</b>
|
|
<br>
|
|
<br><b>schur( S, X )</b>
|
|
<br>
|
|
<br><b>schur( U, S, X )</b>
|
|
<ul>
|
|
<li>Schur decomposition of square matrix <i>X</i>, such that <i>X = U*S*U.t()</i></li>
|
|
<br>
|
|
<li><i>U</i> is a unitary matrix containing the Schur vectors</li>
|
|
<br>
|
|
<li><i>S</i> is an upper triangular matrix, called the Schur form of <i>X</i></li>
|
|
<br>
|
|
<li>If <i>X</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the decomposition fails:
|
|
<ul>
|
|
<li><i>S = schur(X)</i> resets <i>S</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>schur(S,X)</i> resets <i>S</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>schur(U,S,X)</i> resets <i>U</i> & <i>S</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> in general, Schur decomposition is not unique
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(20,20, fill::randu);
|
|
|
|
mat U;
|
|
mat S;
|
|
|
|
schur(U, S, X);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#hess">hess()</a></li>
|
|
<li><a href="#qz">qz()</a></li>
|
|
<li><a href="#eig_gen">eig_gen()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/SchurDecomposition.html">Schur decomposition in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Schur_decomposition">Schur decomposition in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="solve"></a>
|
|
<b>X = solve( A, B )</b>
|
|
<br><b>X = solve( A, B, settings )</b>
|
|
<br>
|
|
<br><b>solve( X, A, B )</b>
|
|
<br><b>solve( X, A, B, settings )</b>
|
|
<ul>
|
|
<li>Solve a <b>dense</b> system of linear equations, <i>A*X = B</i>, where <i>X</i> is unknown;
|
|
similar functionality to the \ operator in Matlab/Octave, ie. <i>X = A \ B</i>
|
|
</li>
|
|
<br>
|
|
<li><i>A</i> can be square sized (critically determined system), or non-square (under/over-determined system); <i>A</i> can be rank deficient
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>B</i> can be a vector or matrix
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The number of rows in <i>A</i> and <i>B</i> must be the same
|
|
</li>
|
|
<br>
|
|
<li>
|
|
By default, matrix <i>A</i> is analysed to automatically determine whether it is a general matrix, band matrix, diagonal matrix, or symmetric/hermitian positive definite (SPD) matrix;
|
|
based on the detected matrix structure, a specialised solver is used for faster execution;
|
|
if no solution is found, an approximate solver is automatically used as a fallback;
|
|
see the <a href="armadillo_solver_2020.pdf">associated paper</a> for more details
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If <i>A</i> is known to be a triangular matrix,
|
|
the solution can be computed faster by explicitly indicating that <i>A</i> is triangular through <a href="#trimat">trimatu()</a> or <a href="#trimat">trimatl()</a>; see examples below
|
|
</li>
|
|
<br>
|
|
<li>The <i>settings</i> argument is optional; it is one of the following, or a combination thereof:
|
|
<br>
|
|
<br>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>solve_opts::fast</code></td><td> </td><td>fast mode: disable determining solution quality via rcond, disable iterative refinement, disable equilibration</td></tr>
|
|
<tr><td><code>solve_opts::refine</code></td><td> </td><td>apply iterative refinement to improve solution quality (matrix <i>A</i> must be square)</td></tr>
|
|
<tr><td><code>solve_opts::equilibrate</code></td><td> </td><td>equilibrate the system before solving (matrix <i>A</i> must be square)</td></tr>
|
|
<tr><td><code>solve_opts::likely_sympd</code></td><td> </td><td>indicate that matrix <i>A</i> is likely symmetric/hermitian positive definite</td></tr>
|
|
<tr><td><code>solve_opts::allow_ugly</code></td><td> </td><td>keep solutions of systems that are singular to working precision</td></tr>
|
|
<tr><td><code>solve_opts::no_approx</code></td><td> </td><td>do not find approximate solutions for rank deficient systems</td></tr>
|
|
<tr><td><code>solve_opts::no_band</code></td><td> </td><td>do not use specialised solver for band matrices or diagonal matrices</td></tr>
|
|
<tr><td><code>solve_opts::no_trimat</code></td><td> </td><td>do not use specialised solver for triangular matrices</td></tr>
|
|
<tr><td><code>solve_opts::no_sympd</code></td><td> </td><td>do not use specialised solver for symmetric/hermitian positive definite matrices</td></tr>
|
|
<tr><td><code>solve_opts::force_approx</code></td><td> </td><td>skip the standard solver and directly use of the approximate solver</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<br>
|
|
the above settings can be combined using the <code>+</code> operator; for example: <code>solve_opts::fast + solve_opts::no_approx</code>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If a rank deficient system is detected and the <i><code>solve_opts::no_approx</code></i> option is <b>not</b> enabled, a warning is emitted and an approximate solution is attempted;
|
|
<br>since Armadillo 10.4, this warning can be disabled by setting <a href="#config_hpp">ARMA_WARN_LEVEL</a> to 1 before including the armadillo header:
|
|
<br><code>#define ARMA_WARN_LEVEL 1</code>
|
|
<br><code>#include <armadillo></code>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>using <i><code>solve_opts::fast</code></i> will speed up finding the solution, but for poorly conditioned systems the solution may have lower quality</li>
|
|
<li>not all SPD matrices are automatically detected; to skip the analysis step and directly indicate that matrix <i>A</i> is likely SPD, use <code>solve_opts::likely_sympd</code></li>
|
|
<li>using <i><code>solve_opts::force_approx</code></i> is only advised if the system is known to be rank deficient; the approximate solver is considerably slower</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If no solution is found:
|
|
<ul>
|
|
<li><i>X = solve(A,B)</i> resets <i>X</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>solve(X,A,B)</i> resets <i>X</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Implementation details are available in the following paper:
|
|
<br>
|
|
<ul>
|
|
Conrad Sanderson and Ryan Curtin.<br>
|
|
<a href="armadillo_solver_2020.pdf">An Adaptive Solver for Systems of Linear Equations</a>.<br>
|
|
International Conference on Signal Processing and Communication Systems, 2020.
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
vec b(5, fill::randu);
|
|
mat B(5, 5, fill::randu);
|
|
|
|
vec x1 = solve(A, b);
|
|
|
|
vec x2;
|
|
bool status = solve(x2, A, b);
|
|
|
|
mat X1 = solve(A, B);
|
|
|
|
mat X2 = solve(A, B, solve_opts::fast); // enable fast mode
|
|
|
|
mat X3 = solve(trimatu(A), B); // indicate that A is triangular
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#inv">inv()</a></li>
|
|
<li><a href="#pinv">pinv()</a></li>
|
|
<li><a href="#rcond">rcond()</a></li>
|
|
<li><a href="#roots">roots()</a></li>
|
|
<li><a href="#syl">syl()</a></li>
|
|
<li><a href="#spsolve">spsolve()</a> - solve sparse system of linear equations</li>
|
|
<li><a href="https://mathworld.wolfram.com/LinearSystemofEquations.html">linear system of equations in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Linear_system_of_equations">system of linear equations in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Band_matrix">band matrix in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Definiteness_of_a_matrix">definiteness of a matrix in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/PositiveDefiniteMatrix.html">positive definite matrix in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Iterative_refinement">iterative refinement</a></li>
|
|
<li><a href="https://ensmallen.org">ensmallen</a> - C++ library for solving numerical optimisation problems</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="svd"></a>
|
|
<b>vec s = svd( X )</b>
|
|
<br>
|
|
<br><b>svd( vec s, 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 <b>dense</b> matrix <i>X</i>
|
|
</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>
|
|
The <i>method</i> argument is optional; <i>method</i> is either <code>"dc"</code> or <code>"std"</code>
|
|
<ul>
|
|
<li>
|
|
<code>"dc"</code> indicates divide-and-conquer method (default setting)
|
|
</li>
|
|
<li>
|
|
<code>"std"</code> indicates standard method
|
|
</li>
|
|
<li>
|
|
the divide-and-conquer method provides slightly different results than the standard method, but is considerably faster for large matrices
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If the decomposition fails, the output objects are reset and:
|
|
<ul>
|
|
<li><i>s = svd(X)</i> resets <i>s</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>svd(s,X)</i> resets <i>s</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>svd(U,s,V,X)</i> resets <i>U</i>, <i>s</i>, <i>V</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(5, 5, fill::randu);
|
|
|
|
mat U;
|
|
vec s;
|
|
mat V;
|
|
|
|
svd(U,s,V,X);
|
|
</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="#princomp">princomp()</a></li>
|
|
<li><a href="#pinv">pinv()</a></li>
|
|
<li><a href="#svds">svds()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Singular_value_decomposition">singular value decomposition in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/SingularValueDecomposition.html">singular value decomposition in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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, mode, method )</b>
|
|
<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, mode, method )</b>
|
|
<ul>
|
|
<li>
|
|
Economical singular value decomposition of <b>dense</b> matrix <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The singular values are in descending order
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>mode</i> argument is optional; <i>mode</i> is one of:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td></td><td style="text-align: left;"><code>"both"</code></td><td> = </td><td>compute both left and right singular vectors (default operation)</td></tr>
|
|
<tr><td></td><td style="text-align: left;"><code>"left"</code></td><td> = </td><td>compute only left singular vectors</td></tr>
|
|
<tr><td></td><td style="text-align: left;"><code>"right"</code></td><td> = </td><td>compute only right singular vectors</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>method</i> argument is optional; <i>method</i> is either <code>"dc"</code> or <code>"std"</code>
|
|
<ul>
|
|
<li>
|
|
<code>"dc"</code> indicates divide-and-conquer method (default setting)
|
|
</li>
|
|
<li>
|
|
<code>"std"</code> indicates standard method
|
|
</li>
|
|
<li>
|
|
the divide-and-conquer method provides slightly different results than the standard method, but is considerably faster for large matrices
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If the decomposition fails, <i>U</i>, <i>s</i>, <i>V</i> are reset and a bool set to <i>false</i> is returned (exception is not thrown)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(4, 5, fill::randu);
|
|
|
|
mat U;
|
|
vec s;
|
|
mat V;
|
|
|
|
svd_econ(U, s, V, X);
|
|
</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="#princomp">princomp()</a></li>
|
|
<li><a href="#svds">svds()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Singular_value_decomposition">singular value decomposition in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/SingularValueDecomposition.html">singular value decomposition in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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:
|
|
<ul>
|
|
<li><i>syl(A,B,C)</i> resets <i>X</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>syl(X,A,B,C)</i> resets <i>X</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
mat B(5, 5, fill::randu);
|
|
mat C(5, 5, fill::randu);
|
|
|
|
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="https://en.wikipedia.org/wiki/Sylvester_equation">Sylvester equation in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div>
|
|
<hr class="greyline">
|
|
<hr class="greyline">
|
|
<br>
|
|
<br>
|
|
<font size=+1><b>Decompositions, Factorisations and Equation Solvers (Sparse Matrices)</b></font>
|
|
<br>
|
|
<br>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="eigs_sym"></a>
|
|
<b>vec eigval = eigs_sym( X, k )</b>
|
|
<br><b>vec eigval = eigs_sym( X, k, form )</b>
|
|
<br><b>vec eigval = eigs_sym( X, k, form, opts )</b>
|
|
<br><b>vec eigval = eigs_sym( X, k, sigma )</b>
|
|
<br><b>vec eigval = eigs_sym( X, k, sigma, opts )</b>
|
|
<br>
|
|
<br><b>eigs_sym( eigval, X, k )</b>
|
|
<br><b>eigs_sym( eigval, X, k, form )</b>
|
|
<br><b>eigs_sym( eigval, X, k, form, opts )</b>
|
|
<br><b>eigs_sym( eigval, X, k, sigma )</b>
|
|
<br><b>eigs_sym( eigval, X, k, sigma, opts )</b>
|
|
<br>
|
|
<br><b>eigs_sym( eigval, eigvec, X, k )</b>
|
|
<br><b>eigs_sym( eigval, eigvec, X, k, form )</b>
|
|
<br><b>eigs_sym( eigval, eigvec, X, k, form, opts )</b>
|
|
<br><b>eigs_sym( eigval, eigvec, X, k, sigma )</b>
|
|
<br><b>eigs_sym( eigval, eigvec, X, k, sigma, opts )</b>
|
|
<ul>
|
|
<li>Obtain a limited number of eigenvalues and eigenvectors of <b>sparse</b> symmetric real matrix <i>X</i></li>
|
|
<br>
|
|
<li>
|
|
<i>k</i> specifies the number of eigenvalues and eigenvectors
|
|
</li>
|
|
<br>
|
|
<li>The argument <i>form</i> is optional; <i>form</i> is one of:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>"lm"</code></td><td> = </td><td>obtain eigenvalues with largest magnitude (default operation)</td></tr>
|
|
<tr><td><code>"sm"</code></td><td> = </td><td>obtain eigenvalues with smallest magnitude (see the caveats below)</td></tr>
|
|
<tr><td><code>"la"</code></td><td> = </td><td>obtain eigenvalues with largest algebraic value</td></tr>
|
|
<tr><td><code>"sa"</code></td><td> = </td><td>obtain eigenvalues with smallest algebraic value</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>The argument <i>sigma</i> is optional; if <i>sigma</i> is given, eigenvalues closest to <i>sigma</i> are found via shift-invert mode
|
|
<br><b>NOTE:</b> to use <i>sigma</i>, both <i>ARMA_USE_ARPACK</i> and <i>ARMA_USE_SUPERLU</i> must be enabled in <a href="#config_hpp">config.hpp</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>opts</i> argument is optional; <i>opts</i> is an instance of the <i>eigs_opts</i> structure:
|
|
<ul>
|
|
<pre>
|
|
struct eigs_opts
|
|
{
|
|
double tol; // default: 0
|
|
unsigned int maxiter; // default: 1000
|
|
unsigned int subdim; // default: max(2*k+1, 20)
|
|
};
|
|
</pre>
|
|
</ul>
|
|
<ul>
|
|
<li><i>tol</i> specifies the tolerance for convergence</li>
|
|
<li><i>maxiter</i> specifies the maximum number of Arnoldi iterations</li>
|
|
<li><i>subdim</i> specifies the dimension of the Krylov subspace, with the constraint <code>k < subdim ≤ X.n_rows</code>; recommended value is <code>subdim ≥ 2*k</code></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>The eigenvalues and corresponding eigenvectors are stored in <i>eigval</i> and <i>eigvec</i>, respectively</li>
|
|
<br>
|
|
<li>If <i>X</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
|
|
<br>
|
|
<li>If the decomposition fails:
|
|
<ul>
|
|
<li><i>eigval = eigs_sym(X,k)</i> resets <i>eigval</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>eigs_sym(eigval,X,k)</i> resets <i>eigval</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>eigs_sym(eigval,eigvec,X,k)</i> resets <i>eigval</i> & <i>eigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li><b>Caveats:</b>
|
|
<ul>
|
|
<li>the number of obtained eigenvalues/eigenvectors may be lower than requested, depending on the given data</li>
|
|
<li>
|
|
if the decomposition fails, try first increasing <i>opts.subdim</i> (Krylov subspace dimension),
|
|
and, as secondary options, try increasing <i>opts.maxiter</i> (maximum number of iterations),
|
|
and/or <i>opts.tol</i> (tolerance for convergence), and/or <i>k</i> (number of eigenvalues)
|
|
</li>
|
|
<li>for an alternative to the <code>"sm"</code> form, use the shift-invert mode with <i>sigma</i> set to 0.0</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>NOTE:</b> the implementation in Armadillo 12.6 is considerably faster than earlier versions;
|
|
further speedups can be obtained by enabling OpenMP in your compiler (eg. <i>-fopenmp</i> in GCC and clang)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
// generate sparse matrix
|
|
sp_mat A = sprandu<sp_mat>(1000, 1000, 0.1);
|
|
sp_mat B = A.t()*A;
|
|
|
|
vec eigval;
|
|
mat eigvec;
|
|
|
|
eigs_sym(eigval, eigvec, B, 5); // find 5 eigenvalues/eigenvectors
|
|
|
|
eigs_opts opts;
|
|
opts.maxiter = 10000; // increase max iterations to 10000
|
|
|
|
eigs_sym(eigval, eigvec, B, 5, "lm", opts);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#eigs_gen">eigs_gen()</a></li>
|
|
<li><a href="#eig_sym">eig_sym()</a></li>
|
|
<li><a href="#svds">svds()</a></li>
|
|
<li><a href="#is_symmetric">.is_symmetric()</a></li>
|
|
<!-- <li><a href="https://www.caam.rice.edu/software/ARPACK/UG/node33.html">shift-invert mode in ARPACK</a></li> -->
|
|
<li><a href="http://li.mit.edu/Archive/Activities/Archive/CourseWork/Ju_Li/MITCourses/18.335/Doc/ARPACK/Lehoucq97.pdf">shift-invert mode in ARPACK</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors">eigenvalues & eigenvectors in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="eigs_gen"></a>
|
|
<b>cx_vec eigval = eigs_gen( X, k )</b>
|
|
<br><b>cx_vec eigval = eigs_gen( X, k, form )</b>
|
|
<br><b>cx_vec eigval = eigs_gen( X, k, sigma )</b>
|
|
<br><b>cx_vec eigval = eigs_gen( X, k, form, opts )</b>
|
|
<br><b>cx_vec eigval = eigs_gen( X, k, sigma, opts )</b>
|
|
<br>
|
|
<br><b>eigs_gen( eigval, X, k )</b>
|
|
<br><b>eigs_gen( eigval, X, k, form )</b>
|
|
<br><b>eigs_gen( eigval, X, k, sigma )</b>
|
|
<br><b>eigs_gen( eigval, X, k, form, opts )</b>
|
|
<br><b>eigs_gen( eigval, X, k, sigma, opts )</b>
|
|
<br>
|
|
<br><b>eigs_gen( eigval, eigvec, X, k )</b>
|
|
<br><b>eigs_gen( eigval, eigvec, X, k, form )</b>
|
|
<br><b>eigs_gen( eigval, eigvec, X, k, sigma )</b>
|
|
<br><b>eigs_gen( eigval, eigvec, X, k, form, opts )</b>
|
|
<br><b>eigs_gen( eigval, eigvec, X, k, sigma, opts )</b>
|
|
<ul>
|
|
<li>
|
|
Obtain a limited number of eigenvalues and eigenvectors of <b>sparse</b> general (non-symmetric/non-hermitian) square matrix <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>k</i> specifies the number of eigenvalues and eigenvectors
|
|
</li>
|
|
<br>
|
|
<li>The argument <i>form</i> is optional; <i>form</i> is one of:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td><code>"lm"</code></td><td> = </td><td>obtain eigenvalues with largest magnitude (default operation)</td></tr>
|
|
<tr><td><code>"sm"</code></td><td> = </td><td>obtain eigenvalues with smallest magnitude (see the caveats below)</td></tr>
|
|
<tr><td><code>"lr"</code></td><td> = </td><td>obtain eigenvalues with largest real part</td></tr>
|
|
<tr><td><code>"sr"</code></td><td> = </td><td>obtain eigenvalues with smallest real part</td></tr>
|
|
<tr><td><code>"li"</code></td><td> = </td><td>obtain eigenvalues with largest imaginary part</td></tr>
|
|
<tr><td><code>"si"</code></td><td> = </td><td>obtain eigenvalues with smallest imaginary part</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>The argument <i>sigma</i> is optional; if <i>sigma</i> is given, eigenvalues closest to <i>sigma</i> are found via shift-invert mode
|
|
<br><b>NOTE:</b> to use <i>sigma</i>, both <i>ARMA_USE_ARPACK</i> and <i>ARMA_USE_SUPERLU</i> must be enabled in <a href="#config_hpp">config.hpp</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>opts</i> argument is optional; <i>opts</i> is an instance of the <i>eigs_opts</i> structure:
|
|
<ul>
|
|
<pre>
|
|
struct eigs_opts
|
|
{
|
|
double tol; // default: 0
|
|
unsigned int maxiter; // default: 1000
|
|
unsigned int subdim; // default: max(2*k+1, 20)
|
|
};
|
|
</pre>
|
|
</ul>
|
|
<ul>
|
|
<li><i>tol</i> specifies the tolerance for convergence</li>
|
|
<li><i>maxiter</i> specifies the maximum number of Arnoldi iterations</li>
|
|
<li><i>subdim</i> specifies the dimension of the Krylov subspace, with the constraint <code>k + 2 < subdim ≤ X.n_rows</code>; recommended value is <code>subdim ≥ 2*k + 1</code></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The eigenvalues and corresponding eigenvectors are stored in <i>eigval</i> and <i>eigvec</i>, respectively
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If <i>X</i> is not square sized, a <i>std::logic_error</i> exception is thrown
|
|
</li>
|
|
<br>
|
|
<li>If the decomposition fails:
|
|
<ul>
|
|
<li><i>eigval = eigs_gen(X,k)</i> resets <i>eigval</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>eigs_gen(eigval,X,k)</i> resets <i>eigval</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>eigs_gen(eigval,eigvec,X,k)</i> resets <i>eigval</i> & <i>eigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li><b>Caveats:</b>
|
|
<ul>
|
|
<li>the number of obtained eigenvalues/eigenvectors may be lower than requested, depending on the given data</li>
|
|
<li>
|
|
if the decomposition fails, try first increasing <i>opts.subdim</i> (Krylov subspace dimension)
|
|
and, as secondary options, try increasing <i>opts.maxiter</i> (maximum number of iterations),
|
|
and/or <i>opts.tol</i> (tolerance for convergence), and/or <i>k</i> (number of eigenvalues)
|
|
</li>
|
|
<li>for an alternative to the <code>"sm"</code> form, use the shift-invert mode with <i>sigma</i> set to 0.0</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>NOTE:</b> the implementation in Armadillo 12.6 is considerably faster than earlier versions;
|
|
further speedups can be obtained by enabling OpenMP in your compiler (eg. <i>-fopenmp</i> in GCC and clang)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
// generate sparse matrix
|
|
sp_mat A = sprandu<sp_mat>(1000, 1000, 0.1);
|
|
|
|
cx_vec eigval;
|
|
cx_mat eigvec;
|
|
|
|
eigs_gen(eigval, eigvec, A, 5); // find 5 eigenvalues/eigenvectors
|
|
|
|
eigs_opts opts;
|
|
opts.maxiter = 10000; // increase max iterations to 10000
|
|
|
|
eigs_gen(eigval, eigvec, A, 5, "lm", opts);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#eigs_sym">eigs_sym()</a></li>
|
|
<li><a href="#eig_gen">eig_gen()</a></li>
|
|
<li><a href="#svds">svds()</a></li>
|
|
<!-- <li><a href="https://www.caam.rice.edu/software/ARPACK/UG/node33.html">shift-invert mode in ARPACK</a></li> -->
|
|
<li><a href="http://li.mit.edu/Archive/Activities/Archive/CourseWork/Ju_Li/MITCourses/18.335/Doc/ARPACK/Lehoucq97.pdf">shift-invert mode in ARPACK</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors">eigenvalues & eigenvectors in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="svds"></a>
|
|
<b>vec s = svds( X, k )</b>
|
|
<br><b>vec s = svds( X, k, tol )</b>
|
|
<br>
|
|
<br><b>svds( vec s, X, k )</b>
|
|
<br><b>svds( vec s, X, k, tol )</b>
|
|
<br>
|
|
<br><b>svds( mat U, vec s, mat V, sp_mat X, k )</b>
|
|
<br><b>svds( mat U, vec s, mat V, sp_mat X, k, tol )</b>
|
|
<br>
|
|
<br><b>svds( cx_mat U, vec s, cx_mat V, sp_cx_mat X, k )</b>
|
|
<br><b>svds( cx_mat U, vec s, cx_mat V, sp_cx_mat X, k, tol )</b>
|
|
<ul>
|
|
<li>
|
|
Obtain a limited number of singular values and singular vectors (truncated SVD) of <b>sparse</b> matrix <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The singular values and vectors are calculated via sparse eigen decomposition of:
|
|
<code>
|
|
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
|
|
<tbody>
|
|
<tr><td>⎡ </td><td>zeros(X.n_rows, X.n_rows)</td><td> </td><td> X</td><td> ⎤</td></tr>
|
|
<tr><td>⎣ </td><td style="text-align: right;">X.t()</td><td> </td><td>zeros(X.n_cols, X.n_cols)</td><td> ⎦</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</code>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>k</i> specifies the number of singular values and singular vectors
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The singular values are in descending order
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The argument <i>tol</i> is optional; it specifies the tolerance for convergence;
|
|
it is passed as <i>(tol ÷ √2)</i> to <a href="#eigs_sym">eigs_sym()</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If the decomposition fails, the output objects are reset and:
|
|
<ul>
|
|
<li><i>s = svds(X,k)</i> resets <i>s</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>svds(s,X,k)</i> resets <i>s</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
<li><i>svds(U,s,V,X,k)</i> resets <i>U</i>, <i>s</i>, <i>V</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveats:</b>
|
|
<ul>
|
|
<li>
|
|
<i>svds()</i> is intended only for finding a few singular values from a large sparse matrix;
|
|
to find all singular values, use <a href="#svd">svd()</a> instead
|
|
</li>
|
|
<li>
|
|
depending on the given matrix, <i>svds()</i> may find fewer singular values than specified
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>NOTE:</b> the implementation in Armadillo 12.6 is considerably faster than earlier versions;
|
|
further speedups can be obtained by enabling OpenMP in your compiler (eg. <i>-fopenmp</i> in GCC and clang)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
sp_mat X = sprandu<sp_mat>(100, 200, 0.1);
|
|
|
|
mat U;
|
|
vec s;
|
|
mat V;
|
|
|
|
svds(U, s, V, X, 10);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#eigs_gen">eigs_gen()</a></li>
|
|
<li><a href="#eigs_sym">eigs_sym()</a></li>
|
|
<li><a href="#svd">svd()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Singular_value_decomposition">singular value decomposition in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/SingularValueDecomposition.html">singular value decomposition in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="spsolve"></a>
|
|
<b>X = spsolve( A, B )</b>
|
|
<br><b>X = spsolve( A, B, solver )</b>
|
|
<br><b>X = spsolve( A, B, solver, opts )</b>
|
|
<br>
|
|
<br><b>spsolve( X, A, B )</b>
|
|
<br><b>spsolve( X, A, B, solver )</b>
|
|
<br><b>spsolve( X, A, B, solver, opts )</b>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
Solve a <b>sparse</b> system of linear equations, <i>A*X = B</i>, where <i>A</i> is a sparse matrix, <i>B</i> is a dense matrix or vector, and <i>X</i> is unknown
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The number of rows in <i>A</i> and <i>B</i> must be the same
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If no solution is found:
|
|
<ul>
|
|
<li><i>X = spsolve(A, B)</i> resets <i>X</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>spsolve(X, A, B)</i> resets <i>X</i> and returns a bool set to <i>false</i> (no exception is thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>solver</i> argument is optional; <i>solver</i> is either <code>"superlu"</code> or <code>"lapack"</code>; by default <code>"superlu"</code> is used
|
|
<ul>
|
|
<li>
|
|
for <code>"superlu"</code>, <i>ARMA_USE_SUPERLU</i> must be enabled in <a href="#config_hpp">config.hpp</a>
|
|
</li>
|
|
<li>
|
|
for <code>"lapack"</code>, sparse matrix <i>A</i> is converted to a dense matrix before using the LAPACK solver; this considerably increases memory usage
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Notes</b>:
|
|
<ul>
|
|
<li>the SuperLU solver is mainly useful for very large and/or very sparse matrices</li>
|
|
<li>to reuse the SuperLU factorisation of <i>A</i> for finding solutions where <i>B</i> is iteratively changed, see the <a href="#spsolve_factoriser">spsolve_factoriser</a> class</li>
|
|
<li>if there is sufficient amount of memory to store a dense version of matrix <i>A</i>, the LAPACK solver can be faster</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>opts</i> argument is optional and applicable to the SuperLU solver;
|
|
<br><i>opts</i> is an instance of the <i>superlu_opts</i> structure:
|
|
<ul>
|
|
<pre>
|
|
struct superlu_opts
|
|
{
|
|
bool allow_ugly; // default: false
|
|
bool equilibrate; // default: false
|
|
bool symmetric; // default: false
|
|
double pivot_thresh; // default: 1.0
|
|
permutation_type permutation; // default: superlu_opts::COLAMD
|
|
refine_type refine; // default: superlu_opts::REF_NONE
|
|
};
|
|
</pre>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<i>allow_ugly</i> is either <i>true</i> or <i>false</i>; indicates whether to keep solutions of systems singular to working precision
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>equilibrate</i> is either <i>true</i> or <i>false</i>; indicates whether to equilibrate the system (scale the rows and columns of <i>A</i> to have unit norm)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>symmetric</i> is either <i>true</i> or <i>false</i>; indicates whether to use SuperLU symmetric mode, which gives preference to diagonal pivots
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>pivot_threshold</i> is in the range [0.0, 1.0], used for determining whether a diagonal entry is an acceptable pivot (details in SuperLU documentation)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>permutation</i> specifies the type of column permutation; it is one of:
|
|
<br>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
|
|
<tr><td><code>superlu_opts::NATURAL</code></td><td> </td><td>natural ordering</td></tr>
|
|
<tr><td><code>superlu_opts::MMD_ATA</code></td><td> </td><td>minimum degree ordering on structure of <code>A.t() * A</code></td></tr>
|
|
<tr><td><code>superlu_opts::MMD_AT_PLUS_A</code></td><td> </td><td>minimum degree ordering on structure of <code>A.t() + A</code></td></tr>
|
|
<tr><td><code>superlu_opts::COLAMD</code></td><td> </td><td>approximate minimum degree column ordering</td></tr>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>refine</i> specifies the type of iterative refinement; it is one of:
|
|
<br>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
|
|
<tr><td><code>superlu_opts::REF_NONE</code></td><td> </td><td>no refinement</td></tr>
|
|
<tr><td><code>superlu_opts::REF_SINGLE</code></td><td> </td><td>iterative refinement in single precision</td></tr>
|
|
<tr><td><code>superlu_opts::REF_DOUBLE</code></td><td> </td><td>iterative refinement in double precision</td></tr>
|
|
<tr><td><code>superlu_opts::REF_EXTRA</code></td><td> </td><td>iterative refinement in extra precision</td></tr>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
sp_mat A = sprandu<sp_mat>(1000, 1000, 0.1);
|
|
|
|
vec b(1000, fill::randu);
|
|
mat B(1000, 5, fill::randu);
|
|
|
|
vec x = spsolve(A, b); // solve one system
|
|
mat X = spsolve(A, B); // solve several systems
|
|
|
|
bool status = spsolve(x, A, b); // use default solver
|
|
if(status == false) { cout << "no solution" << endl; }
|
|
|
|
spsolve(x, A, b, "lapack" ); // use LAPACK solver
|
|
spsolve(x, A, b, "superlu"); // use SuperLU solver
|
|
|
|
superlu_opts opts;
|
|
|
|
opts.allow_ugly = true;
|
|
opts.equilibrate = true;
|
|
|
|
spsolve(x, A, b, "superlu", opts);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#spsolve_factoriser">spsolve_factoriser</a></li>
|
|
<li><a href="#solve">solve()</a> - solve dense system of linear equations</li>
|
|
<!-- <li><a href="http://crd-legacy.lbl.gov/~xiaoye/SuperLU/">SuperLU home page</a> -->
|
|
<li><a href="https://portal.nersc.gov/project/sparse/superlu/">SuperLU home page</a>
|
|
<li><a href="https://mathworld.wolfram.com/LinearSystemofEquations.html">linear system of equations in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Linear_system_of_equations">system of linear equations in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="spsolve_factoriser"></a>
|
|
<b>spsolve_factoriser</b>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
Class for factorisation of <b>sparse</b> matrix <i>A</i> for solving systems of linear equations in the form <i>A*X = B</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Allows the SuperLU factorisation of <i>A</i> to be reused for finding solutions in cases where <i>B</i> is iteratively changed
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For an instance of <i>spsolve_factoriser</i> named as <i>SF</i>, the member functions are:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<b>SF.factorise(</b>A<b>)</b>
|
|
<br>
|
|
<b>SF.factorise(</b>A<b>, </b>opts<b>)</b>
|
|
<ul>
|
|
<li>
|
|
factorise square-sized sparse matrix <i>A</i>
|
|
</li>
|
|
<li>
|
|
optional settings are given in the <i>opts</i> argument as per the <a href="#spsolve">spsolve()</a> function
|
|
</li>
|
|
<li>if the factorisation fails, a bool set to <i>false</i> is returned</li>
|
|
</ul>
|
|
<br>
|
|
<b>SF.solve(</b>X<b>, </b>B<b>)</b>
|
|
<ul>
|
|
<li>
|
|
using the given dense matrix <i>B</i> and the computed factorisation,
|
|
store in <i>X</i> the solution to <i>A*X = B</i>
|
|
</li>
|
|
<li>if computing the solution fails, <i>X</i> is reset and a bool set to <i>false</i> is returned</li>
|
|
</ul>
|
|
<br>
|
|
<b>SF.rcond()</b>
|
|
<ul>
|
|
<li>
|
|
return the 1-norm estimate of the reciprocal condition number computed during the factorisation
|
|
<ul>
|
|
<li>
|
|
values close to 1 suggest that the factorised matrix is well-conditioned
|
|
</li>
|
|
<li>
|
|
values close to 0 suggest that the factorised matrix is badly conditioned
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<br>
|
|
<b>SF.reset()</b>
|
|
<ul>
|
|
<li>
|
|
reset the instance and release all memory related to the stored factorisation;
|
|
this is automatically done when the instance goes out of scope
|
|
</li>
|
|
</ul>
|
|
</ul>
|
|
<br>
|
|
<li><b>Notes:</b>
|
|
<ul>
|
|
<li>if the factorisation of <i>A</i> does not need to be reused, use <a href="#spsolve">spsolve()</a> instead</li>
|
|
<li>this class internally uses the SuperLU solver; <i>ARMA_USE_SUPERLU</i> must be enabled in <a href="#config_hpp">config.hpp</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
sp_mat A = sprandu<sp_mat>(1000, 1000, 0.1);
|
|
|
|
spsolve_factoriser SF;
|
|
|
|
bool status = SF.factorise(A);
|
|
|
|
if(status == false) { cout << "factorisation failed" << endl; }
|
|
|
|
double rcond_value = SF.rcond();
|
|
|
|
vec B1(1000, fill::randu);
|
|
vec B2(1000, fill::randu);
|
|
|
|
vec X1;
|
|
vec X2;
|
|
|
|
bool solution1_ok = SF.solve(X1,B1);
|
|
bool solution2_ok = SF.solve(X2,B2);
|
|
|
|
if(solution1_ok == false) { cout << "couldn't find X1" << endl; }
|
|
if(solution2_ok == false) { cout << "couldn't find X2" << endl; }
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#spsolve">spsolve()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/LinearSystemofEquations.html">linear system of equations in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Linear_system_of_equations">system of linear equations in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div>
|
|
<hr class="greyline">
|
|
<hr class="greyline">
|
|
<br>
|
|
<br>
|
|
<font size=+1><b>Signal & Image Processing</b></font>
|
|
<br>
|
|
<br>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="conv"></a>
|
|
<b>conv( A, B )</b>
|
|
<br><b>conv( A, B, shape )</b>
|
|
<ul>
|
|
<li>
|
|
1D convolution of vectors <i>A</i> and <i>B</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The orientation of the result vector is the same as the orientation of <i>A</i> (ie. either column or row vector)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>shape</i> argument is optional; it is one of:
|
|
<ul>
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td style="text-align: right;"><code>"full"</code></td><td> = </td><td>return the full convolution (<b>default setting</b>), with the size equal to <i>A.n_elem + B.n_elem - 1</i></td></tr>
|
|
<tr><td style="text-align: right;"><code>"same"</code></td><td> = </td><td>return the central part of the convolution, with the same size as vector <i>A</i></td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The convolution operation is also equivalent to FIR filtering
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec A(256, fill::randu);
|
|
|
|
vec B(16, fill::randu);
|
|
|
|
vec C = conv(A, B);
|
|
|
|
vec D = conv(A, B, "same");
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#conv2">conv2()</a></li>
|
|
<li><a href="#fft">fft()</a></li>
|
|
<li><a href="#cor">cor()</a></li>
|
|
<li><a href="#interp1">interp1()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Convolution.html">Convolution in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Convolution">Convolution in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Finite_impulse_response">FIR filter in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="conv2"></a>
|
|
<b>conv2( A, B )</b>
|
|
<br><b>conv2( A, B, shape )</b>
|
|
<ul>
|
|
<li>
|
|
2D convolution of matrices <i>A</i> and <i>B</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>shape</i> argument is optional; it is one of:
|
|
<ul>
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td style="text-align: right;"><code>"full"</code></td><td> = </td><td>return the full convolution (<b>default setting</b>), with the size equal to <i>size(A) + size(B) - 1</i></td></tr>
|
|
<tr><td style="text-align: right;"><code>"same"</code></td><td> = </td><td>return the central part of the convolution, with the same size as matrix <i>A</i></td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>The implementation of 2D convolution in this version is preliminary</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(256, 256, fill::randu);
|
|
|
|
mat B(16, 16, fill::randu);
|
|
|
|
mat C = conv2(A, B);
|
|
|
|
mat D = conv2(A, B, "same");
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#conv">conv()</a></li>
|
|
<li><a href="#fft2">fft2()</a></li>
|
|
<li><a href="#interp2">interp2()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Convolution.html">Convolution in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Convolution">Convolution in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Kernel_%28image_processing%29">Kernel (image processing) in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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><i>fft():</i> fast Fourier transform of a vector or matrix (real or complex)</li>
|
|
<br>
|
|
<li><i>ifft():</i> 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>
|
|
By default, an internal FFT algorithm based on <a href="https://github.com/mborgerding/kissfft">KISS FFT</a> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Since Armadillo 12.0, the <a href="https://www.fftw.org/">FFTW3 library</a> can be optionally used for faster execution, as follows:
|
|
<ul>
|
|
<li><a href="#config_hpp">ARMA_USE_FFTW3</a> must be defined before including the armadillo header:
|
|
<br>
|
|
<code>
|
|
#define ARMA_USE_FFTW3
|
|
<br>#include <armadillo>
|
|
</code>
|
|
</li>
|
|
<li>you will also need to link with the FFTW3 runtime library (eg. <code><i>-lfftw3</i></code>)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec X(100, fill::randu);
|
|
|
|
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="https://mathworld.wolfram.com/FastFourierTransform.html">fast Fourier transform in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Fast_Fourier_transform">fast Fourier transform in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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><i>fft2():</i> 2D fast Fourier transform of a matrix (real or complex)</li>
|
|
<br>
|
|
<li><i>ifft2():</i> 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 2D transform in this version is preliminary</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(100, 100, fill::randu);
|
|
|
|
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="#conv2">conv2()</a></li>
|
|
<li><a href="#imag_real">real()</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/FastFourierTransform.html">fast Fourier transform in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Fast_Fourier_transform">fast Fourier transform in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="interp1"></a>
|
|
<b>interp1( X, Y, XI, YI )</b>
|
|
<br><b>interp1( X, Y, XI, YI, method )</b>
|
|
<br><b>interp1( X, Y, XI, YI, method, extrapolation_value )</b>
|
|
<ul>
|
|
<li>
|
|
1D data interpolation
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Given a 1D function specified in vectors <i>X</i> and <i>Y</i>
|
|
(where <i>X</i> specifies locations and <i>Y</i> specifies the corresponding values),
|
|
<br>
|
|
generate vector <i>YI</i> which contains interpolated values at locations <i>XI</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>method</i> argument is optional; it is one of:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td style="text-align: right;"><code>"nearest"</code></td><td> = </td><td>interpolate using single nearest neighbour</td></tr>
|
|
<tr><td style="text-align: right;"><code>"linear"</code></td><td> = </td><td>linear interpolation between two nearest neighbours (<b>default setting</b>)</td></tr>
|
|
<tr><td style="text-align: right;"><code>"*nearest"</code></td><td> = </td><td>as per <code>"nearest"</code>, but faster by assuming that <i>X</i> and <i>XI</i> are monotonically increasing</td></tr>
|
|
<tr><td style="text-align: right;"><code>"*linear"</code></td><td> = </td><td>as per <code>"linear"</code>, but faster by assuming that <i>X</i> and <i>XI</i> are monotonically increasing</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If a location in <i>XI</i> is outside the domain of <i>X</i>, the corresponding value in <i>YI</i> is set to <i>extrapolation_value</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>extrapolation_value</i> argument is optional; by default it is <a href="#constants">datum::nan</a> (not-a-number)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec x = linspace<vec>(0, 3, 20);
|
|
vec y = square(x);
|
|
|
|
vec xx = linspace<vec>(0, 3, 100);
|
|
|
|
vec yy;
|
|
|
|
interp1(x, y, xx, yy); // use linear interpolation by default
|
|
|
|
interp1(x, y, xx, yy, "*linear"); // faster than "linear"
|
|
|
|
interp1(x, y, xx, yy, "nearest");
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#interp2">interp2()</a></li>
|
|
<li><a href="#polyval">polyval()</a></li>
|
|
<li><a href="#linspace">linspace()</a></li>
|
|
<li><a href="#regspace">regspace()</a></li>
|
|
<li><a href="#conv">conv()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Interpolation">interpolation in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="interp2"></a>
|
|
<b>interp2( X, Y, Z, XI, YI, ZI )</b>
|
|
<br><b>interp2( X, Y, Z, XI, YI, ZI, method )</b>
|
|
<br><b>interp2( X, Y, Z, XI, YI, ZI, method, extrapolation_value )</b>
|
|
<ul>
|
|
<li>
|
|
2D data interpolation
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Given a 2D function specified by matrix <i>Z</i> with coordinates given by vectors <i>X</i> and <i>Y</i>,
|
|
<br>generate matrix <i>ZI</i> which contains interpolated values at the coordinates given by vectors <i>XI</i> and <i>YI</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The vector pairs <i>(X, Y)</i> and <i>(XI, YI)</i> define 2D coordinates in a grid;
|
|
<br>for example, <i>X</i> defines the horizontal coordinates and <i>Y</i> defines the corresponding vertical coordinates,
|
|
<br>so that ( <i>X(m)</i>, <i>Y(n) )</i> is the 2D coordinate of element <i>Z(n,m)</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The length of vector <i>X</i> must be equal to the number of columns in matrix <i>Z</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The length of vector <i>Y</i> must be equal to the number of rows in matrix <i>Z</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Vectors <i>X</i>, <i>Y</i>, <i>XI</i>, <i>YI</i> must contain monotonically increasing values (eg. 0.1, 0.2, 0.3, ...)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>method</i> argument is optional; it is one of:
|
|
<ul>
|
|
<table>
|
|
<tbody>
|
|
<tr><td style="text-align: right;"><code>"nearest"</code></td><td> = </td><td>interpolate using nearest neighbours</td></tr>
|
|
<tr><td style="text-align: right;"><code>"linear"</code></td><td> = </td><td>linear interpolation between nearest neighbours (<b>default setting</b>)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If a coordinate in the 2D grid specified by <i>(XI, YI)</i> is outside the domain of the 2D grid specified by <i>(X, Y)</i>,
|
|
<br>the corresponding value in <i>ZI</i> is set to <i>extrapolation_value</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>extrapolation_value</i> argument is optional; by default it is <a href="#constants">datum::nan</a> (not-a-number)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
|
|
mat Z;
|
|
|
|
Z.load("input_image.pgm", pgm_binary); // load an image in pgm format
|
|
|
|
vec X = regspace(1, Z.n_cols); // X = horizontal spacing
|
|
vec Y = regspace(1, Z.n_rows); // Y = vertical spacing
|
|
|
|
vec XI = regspace(X.min(), 1.0/2.0, X.max()); // magnify by approx 2
|
|
vec YI = regspace(Y.min(), 1.0/3.0, Y.max()); // magnify by approx 3
|
|
|
|
mat ZI;
|
|
|
|
interp2(X, Y, Z, XI, YI, ZI); // use linear interpolation by default
|
|
|
|
ZI.save("output_image.pgm", pgm_binary);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#interp1">interp1()</a></li>
|
|
<li><a href="#regspace">regspace()</a></li>
|
|
<li><a href="#conv2">conv2()</a></li>
|
|
<li><a href="#reshape">reshape()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Bilinear_interpolation">bilinear interpolation in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="polyfit"></a>
|
|
<b>P = polyfit( X, Y, N )</b>
|
|
<br><b>polyfit( P, X, Y, N )</b>
|
|
<ul>
|
|
<li>
|
|
Given a 1D function specified in vectors <i>X</i> and <i>Y</i>
|
|
(where <i>X</i> holds independent values and <i>Y</i> holds the corresponding dependent values),
|
|
<br>model the function as a polynomial of order <i>N</i> and store the polynomial coefficients in column vector <i>P</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The given function is modelled as:
|
|
<ul>
|
|
y = p<sub><sub>0</sub></sub>x<sup><sup>N</sup></sup>
|
|
+ p<sub><sub>1</sub></sub>x<sup><sup>N-1</sup></sup>
|
|
+ p<sub><sub>2</sub></sub>x<sup><sup>N-2</sup></sup>
|
|
+ ...
|
|
+ p<sub><sub>N-1</sub></sub>x<sup><sup>1</sup></sup>
|
|
+ p<sub><sub>N</sub></sub>
|
|
</ul>
|
|
where p<sub><sub>i</sub></sub> is the i-th polynomial coefficient; the coefficients are selected to minimise the overall error of the fit (least squares)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The column vector <i>P</i> has <i>N+1</i> coefficients
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>N</i> must be smaller than the number of elements in <i>X</i>
|
|
</li>
|
|
<br>
|
|
<li>If the polynomial coefficients cannot be found:
|
|
<ul>
|
|
<li><i>P = polyfit( X, Y, N )</i> resets <i>P</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li><i>polyfit( P, X, Y, N )</i> resets <i>P</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec x = linspace<vec>(0,4*datum::pi,100);
|
|
vec y = cos(x);
|
|
|
|
vec p = polyfit(x,y,10);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#polyval">polyval()</a></li>
|
|
<li><a href="#roots">roots()</a></li>
|
|
<li><a href="#interp1">interp1()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Polynomial">polynomial in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Least_squares">least squares in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Curve_fitting">curve fitting in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/LeastSquaresFitting.html">least squares fitting in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="polyval"></a>
|
|
<b>Y = polyval( P, X )</b>
|
|
<ul>
|
|
<li>
|
|
Given vector <i>P</i> of polynomial coefficients and vector <i>X</i> containing the independent values of a 1D function,
|
|
<br>generate vector <i>Y</i> which contains the corresponding dependent values
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For each <i>x</i> value in vector <i>X</i>, the corresponding <i>y</i> value in vector <i>Y</i> is generated using:
|
|
<ul>
|
|
y = p<sub><sub>0</sub></sub>x<sup><sup>N</sup></sup>
|
|
+ p<sub><sub>1</sub></sub>x<sup><sup>N-1</sup></sup>
|
|
+ p<sub><sub>2</sub></sub>x<sup><sup>N-2</sup></sup>
|
|
+ ...
|
|
+ p<sub><sub>N-1</sub></sub>x<sup><sup>1</sup></sup>
|
|
+ p<sub><sub>N</sub></sub>
|
|
</ul>
|
|
where p<sub><sub>i</sub></sub> is the i-th polynomial coefficient in vector <i>P</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>P</i> must contain polynomial coefficients in descending powers (eg. generated by the <a href="#polyfit">polyfit()</a> function)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec x1 = linspace<vec>(0,4*datum::pi,100);
|
|
vec y1 = cos(x1);
|
|
vec p1 = polyfit(x1,y1,10);
|
|
|
|
vec y2 = polyval(p1,x1);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#polyfit">polyfit()</a></li>
|
|
<li><a href="#roots">roots()</a></li>
|
|
<li><a href="#interp1">interp1()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Polynomial">polynomial in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div>
|
|
<hr class="greyline">
|
|
<hr class="greyline">
|
|
<br>
|
|
<br>
|
|
<font size=+1><b>Statistics & Clustering</b></font>
|
|
<br>
|
|
<br>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="stats_fns"></a>
|
|
<b>mean, median, stddev, var, range</b>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>mean( V )</b>
|
|
<br><b>mean( M )</b>
|
|
<br><b>mean( M, dim )</b>
|
|
<br><b>mean( Q )</b>
|
|
<br><b>mean( Q, dim )</b>
|
|
<br>
|
|
<br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
⎫ <br>
|
|
⎪ <br>
|
|
⎬ mean (average value)<br>
|
|
⎪ <br>
|
|
⎭
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>median( V )</b>
|
|
<br><b>median( M )</b>
|
|
<br><b>median( M, dim )</b>
|
|
<br>
|
|
<br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
⎫ <br>
|
|
⎬ median<br>
|
|
⎭
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>stddev( V )</b>
|
|
<br><b>stddev( V, norm_type )</b>
|
|
<br><b>stddev( M )</b>
|
|
<br><b>stddev( M, norm_type )</b>
|
|
<br><b>stddev( M, norm_type, dim )</b>
|
|
<br>
|
|
<br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
⎫ <br>
|
|
⎪ <br>
|
|
⎬ standard deviation<br>
|
|
⎪ <br>
|
|
⎭
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>var( V )</b>
|
|
<br><b>var( V, norm_type )</b>
|
|
<br><b>var( M )</b>
|
|
<br><b>var( M, norm_type )</b>
|
|
<br><b>var( M, norm_type, dim )</b>
|
|
<br>
|
|
<br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
⎫ <br>
|
|
⎪ <br>
|
|
⎬ variance<br>
|
|
⎪ <br>
|
|
⎭
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>range( V )</b>
|
|
<br><b>range( M )</b>
|
|
<br><b>range( M, dim )</b>
|
|
<br>
|
|
<br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
⎫ <br>
|
|
⎬ range (difference between max and min)<br>
|
|
⎭
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<li>
|
|
For vector <i>V</i>, return the statistic calculated using all the elements of the vector
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For matrix <i>M</i>, find the statistic for each column (<i>dim = 0</i>), or each row (<i>dim = 1</i>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For cube <i>Q</i>, find the statistics of elements along dimension <i>dim</i>, where <i>dim</i> ∈ { 0, 1, 2 }
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>dim</i> argument is optional; by default <i>dim = 0</i> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>norm_type</i> argument is optional; by default <i>norm_type = 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>
|
|
<b>Caveat:</b>
|
|
to obtain statistics for integer matrices/vectors (eg. <a href="#Mat">umat</a>, <a href="#Mat">imat</a>, <a href="#Col">uvec</a>, <a href="#Col">ivec</a>),
|
|
convert to a matrix/vector with floating point values (eg. <a href="#Mat">mat</a>, <a href="#Col">vec</a>) using the <a href="#conv_to">conv_to()</a> function
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 5, fill::randu);
|
|
|
|
mat B = mean(A);
|
|
mat C = var(A);
|
|
double m = mean(mean(A));
|
|
|
|
vec v(5, fill::randu);
|
|
double x = var(v);
|
|
</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="#hist">hist()</a></li>
|
|
<li><a href="#histc">histc()</a></li>
|
|
<li><a href="#quantile">quantile()</a></li>
|
|
<li><a href="#normpdf">normpdf()</a></li>
|
|
<li><a href="#min_and_max">min() & max()</a></li>
|
|
<li><a href="#running_stat">running_stat</a> - class for running statistics of scalars</li>
|
|
<li><a href="#running_stat_vec">running_stat_vec</a> - class for running statistics of vectors</li>
|
|
<li><a href="#gmm_diag">gmm_diag / gmm_full</a> - probabilistic clustering and likelihood calculation via Gaussian mixture models</li>
|
|
<li><a href="#kmeans">kmeans()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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 <i>norm_type</i> argument is optional; by default <i>norm_type = 0</i> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
the <i>norm_type</i> argument controls the type of normalisation used, with <i>N</i> denoting the number of observations:
|
|
<ul>
|
|
<li>
|
|
for <i>norm_type = 0</i>, normalisation is done using <i>N-1</i>,
|
|
providing the best unbiased estimation of the covariance matrix (if the observations are from a normal distribution)
|
|
</li>
|
|
<li>
|
|
for <i>norm_type = 1</i>, normalisation is done using <i>N</i>,
|
|
which provides the second moment matrix of the observations about their mean
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(4, 5, fill::randu);
|
|
mat Y(4, 5, fill::randu);
|
|
|
|
mat C = cov(X,Y);
|
|
mat D = cov(X,Y, 1);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#cor">cor()</a></li>
|
|
<li><a href="#stats_fns">statistics functions</a></li>
|
|
<li><a href="#running_stat_vec">running_stat_vec</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Covariance.html">Covariance in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>norm_type</i> argument is optional; by default <i>norm_type = 0</i> is used
|
|
</li>
|
|
<br>
|
|
<li>
|
|
the <i>norm_type</i> argument controls the type of normalisation used, with <i>N</i> denoting the number of observations:
|
|
<ul>
|
|
<li>for <i>norm_type = 0</i>, normalisation is done using <i>N-1</i></li>
|
|
<li>for <i>norm_type = 1</i>, normalisation is done using <i>N</i></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(4, 5, fill::randu);
|
|
mat Y(4, 5, fill::randu);
|
|
|
|
mat R = cor(X,Y);
|
|
mat S = cor(X,Y, 1);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#cov">cov()</a></li>
|
|
<li><a href="#conv">conv()</a></li>
|
|
<li><a href="#stats_fns">statistics functions</a></li>
|
|
<li><a href="#running_stat_vec">running_stat_vec</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Correlation.html">Correlation in MathWorld</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/Autocorrelation.html">Autocorrelation in MathWorld</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="hist"></a>
|
|
<b>hist( V )</b>
|
|
<br><b>hist( V, n_bins )</b>
|
|
<br><b>hist( V, centers )</b>
|
|
<br>
|
|
<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>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec v(1000, fill::randn); // 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="#quantile">quantile()</a></li>
|
|
<li><a href="#stats_fns">statistics functions</a></li>
|
|
<li><a href="#conv_to">conv_to()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec v(1000, fill::randn); // 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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="quantile"></a>
|
|
<b>quantile( V, P )</b>
|
|
<br><b>quantile( X, P )</b>
|
|
<br><b>quantile( X, P, dim )</b>
|
|
<ul>
|
|
<li>
|
|
For a dataset stored in vector <i>V</i> or matrix <i>X</i>,
|
|
calculate the quantiles corresponding to the cumulative probability values in the given <i>P</i> vector
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For vector <i>V</i>, produce a vector with the same orientation as <i>V</i> and the same length as <i>P</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For matrix <i>X</i>, produce a matrix with the quantiles for each column vector (<i>dim = 0</i>) or each row vector (<i>dim = 1</i>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>dim</i> argument is optional; by default <i>dim = 0</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>P</i> vector must contain values in the [0,1] interval (eg. 0.00, 0.25, 0.50, 0.75, 1.00)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The algorithm for calculating the quantiles is based on <i>Definition 5</i> in:
|
|
<br>
|
|
Rob J. Hyndman and Yanan Fan.
|
|
Sample Quantiles in Statistical Packages.
|
|
The American Statistician, 50(4), 361-365, 1996.
|
|
DOI: <a href="https://doi.org/10.2307/2684934">10.2307/2684934</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec V(1000, fill::randn); // Gaussian distribution
|
|
|
|
vec P = { 0.25, 0.50, 0.75 };
|
|
|
|
vec Q = quantile(V, P);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#hist">hist()</a></li>
|
|
<li><a href="#stats_fns">median()</a></li>
|
|
<li><a href="#normcdf">normcdf()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Quantile">quantile in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
<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
|
|
</li>
|
|
<br>
|
|
<li>If the decomposition fails:
|
|
<ul>
|
|
<li><i>coeff = princomp(X)</i> resets <i>coeff</i> and throws a <i>std::runtime_error</i> exception</li>
|
|
<li>remaining forms of <i>princomp()</i> reset all output matrices and return a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat A(5, 4, fill::randu);
|
|
|
|
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="#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="https://en.wikipedia.org/wiki/Principal_component_analysis">principal components analysis in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="normpdf"></a>
|
|
<b>normpdf( X )</b>
|
|
<br><b>normpdf( X, M, S )</b>
|
|
<ul>
|
|
<li>
|
|
For each scalar <i>x</i> in <i>X</i>, compute its probability density function according to a Gaussian (normal) distribution using the corresponding mean value <i>m</i> in <i>M</i> and the corresponding standard deviation value <i>s</i> in <i>S</i>:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<code>
|
|
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
|
|
<tbody>
|
|
<tr>
|
|
<td> </td><td> 1 </td><td> </td><td>⎧</td><td> </td><td>(x-m)<sup>2</sup></td><td>⎫</td>
|
|
</tr>
|
|
<tr>
|
|
<td>y = </td><td>‒‒‒‒</td><td> exp</td><td>⎪</td><td>−0.5 </td><td>‒‒‒‒‒‒ </td><td>⎪</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td><td>s·√τ</td><td> </td><td>⎩</td><td> </td><td> s<sup>2</sup></td><td>⎭</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</code>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li><i>X</i> can be a scalar, vector, or matrix</li>
|
|
<br>
|
|
<li><i>M</i> and <i>S</i> can jointly be either scalars, vectors, or matrices</li>
|
|
<br>
|
|
<li>If <i>M</i> and <i>S</i> are omitted, their values are assumed to be 0 and 1, respectively</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> to reduce the incidence of numerical underflows, consider using <a href="#log_normpdf">log_normpdf()</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec X(10, fill::randu);
|
|
vec M(10, fill::randu);
|
|
vec S(10, fill::randu);
|
|
|
|
vec P1 = normpdf(X);
|
|
vec P2 = normpdf(X, M, S );
|
|
vec P3 = normpdf(1.23, M, S );
|
|
vec P4 = normpdf(X, 4.56, 7.89);
|
|
double P5 = normpdf(1.23, 4.56, 7.89);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#log_normpdf">log_normpdf()</a></li>
|
|
<li><a href="#normcdf">normcdf()</a></li>
|
|
<li><a href="#randn">randn()</a></li>
|
|
<li><a href="#gmm_diag">gmm_diag / gmm_full</a> - probabilistic clustering and likelihood calculation via Gaussian mixture models</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="log_normpdf"></a>
|
|
<b>log_normpdf( X )</b>
|
|
<br><b>log_normpdf( X, M, S )</b>
|
|
<ul>
|
|
<li>
|
|
For each scalar <i>x</i> in <i>X</i>, compute the logarithm version of probability density function according to a Gaussian (normal) distribution using the corresponding mean value <i>m</i> in <i>M</i> and the corresponding standard deviation value <i>s</i> in <i>S</i>:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<code>
|
|
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
|
|
<tbody>
|
|
<tr>
|
|
<td> </td><td> </td><td>⎧</td><td> 1 </td><td> </td><td>⎧</td><td> </td><td>(x-m)<sup>2</sup></td><td>⎫</td><td>⎫</td>
|
|
</tr>
|
|
<tr>
|
|
<td>y = </td><td>log</td><td>⎪</td><td>‒‒‒‒</td><td> exp</td><td>⎪</td><td>−0.5 </td><td>‒‒‒‒‒‒ </td><td>⎪</td><td>⎪</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td><td> </td><td>⎩</td><td>s·√τ</td><td> </td><td>⎩</td><td> </td><td> s<sup>2</sup></td><td>⎭</td><td>⎭</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<br>
|
|
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
|
|
<tbody>
|
|
<tr>
|
|
<td> </td><td> </td><td> </td><td>⎧</td><td> </td><td>(x-m)<sup>2</sup></td><td>⎫</td>
|
|
</tr>
|
|
<tr>
|
|
<td> = </td><td>−log(s·√τ)</td><td> + </td><td>⎪</td><td>−0.5 </td><td>‒‒‒‒‒‒ </td><td>⎪</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td><td> </td><td> </td><td>⎩</td><td> </td><td> s<sup>2</sup></td><td>⎭</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</code>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li><i>X</i> can be a scalar, vector, or matrix</li>
|
|
<br>
|
|
<li><i>M</i> and <i>S</i> can jointly be either scalars, vectors, or matrices</li>
|
|
<br>
|
|
<li>If <i>M</i> and <i>S</i> are omitted, their values are assumed to be 0 and 1, respectively</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec X(10, fill::randu);
|
|
vec M(10, fill::randu);
|
|
vec S(10, fill::randu);
|
|
|
|
vec P1 = log_normpdf(X);
|
|
vec P2 = log_normpdf(X, M, S );
|
|
vec P3 = log_normpdf(1.23, M, S );
|
|
vec P4 = log_normpdf(X, 4.56, 7.89);
|
|
double P5 = log_normpdf(1.23, 4.56, 7.89);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#normpdf">normpdf()</a></li>
|
|
<li><a href="#gmm_diag">gmm_diag / gmm_full</a> - probabilistic clustering and likelihood calculation via Gaussian mixture models</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="normcdf"></a>
|
|
<b>normcdf( X )</b>
|
|
<br><b>normcdf( X, M, S )</b>
|
|
<ul>
|
|
<li>
|
|
For each scalar <i>x</i> in <i>X</i>, compute its cumulative distribution function according to a Gaussian (normal) distribution using the corresponding mean value <i>m</i> in <i>M</i> and the corresponding standard deviation value <i>s</i> in <i>S</i>
|
|
</li>
|
|
<br>
|
|
<li><i>X</i> can be a scalar, vector, or matrix</li>
|
|
<br>
|
|
<li><i>M</i> and <i>S</i> can jointly be either scalars, vectors, or matrices</li>
|
|
<br>
|
|
<li>If <i>M</i> and <i>S</i> are omitted, their values are assumed to be 0 and 1, respectively</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec X(10, fill::randu);
|
|
vec M(10, fill::randu);
|
|
vec S(10, fill::randu);
|
|
|
|
vec P1 = normcdf(X);
|
|
vec P2 = normcdf(X, M, S );
|
|
vec P3 = normcdf(1.23, M, S );
|
|
vec P4 = normcdf(X, 4.56, 7.89);
|
|
double P5 = normcdf(1.23, 4.56, 7.89);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#normpdf">normpdf()</a></li>
|
|
<li><a href="#quantile">quantile()</a></li>
|
|
<li><a href="#randn">randn()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Cumulative_distribution_function">cumulative distribution function in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="mvnrnd"></a>
|
|
<b>X = mvnrnd( M, C )</b>
|
|
<br><b>X = mvnrnd( M, C, N )</b>
|
|
<br>
|
|
<br>
|
|
<b>mvnrnd( X, M, C )</b>
|
|
<br><b>mvnrnd( X, M, C, N )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a matrix with random column vectors from a multivariate Gaussian (normal) distribution with parameters <i>M</i> and <i>C</i>:
|
|
<ul>
|
|
<li><i>M</i> is the mean; must be a column vector</li>
|
|
<li><i>C</i> is the covariance matrix; must be symmetric positive semi-definite (preferably positive definite)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li><i>N</i> is the number of column vectors to generate; if <i>N</i> is omitted, it is assumed to be 1</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> repeated generation of one vector (or a small number of vectors) using the same <i>M</i> and <i>C</i> parameters can be inefficient;
|
|
<br>for repeated generation consider using the <i>generate()</i> function in the <a href="#gmm_diag">gmm_diag</a> and <a href="#gmm_full">gmm_full</a> classes
|
|
</li>
|
|
<br>
|
|
<li>If generating the random vectors fails:
|
|
<ul>
|
|
<li><i>X = mvnrnd(M, C)</i> and <i>X = mvnrnd(M, C, N)</i> reset <i>X</i> and throw a <i>std::runtime_error</i> exception</li>
|
|
<li><i>mvnrnd(X, M, C)</i> and <i>mvnrnd(X, M, C, N)</i> reset <i>X</i> and return a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
vec M(5, fill::randu);
|
|
|
|
mat B(5, 5, fill::randu);
|
|
mat C = B.t() * B;
|
|
|
|
mat X = mvnrnd(M, C, 100);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#randn">randn()</a></li>
|
|
<li><a href="#chi2rnd">chi2rnd()</a></li>
|
|
<li><a href="#wishrnd">wishrnd()</a></li>
|
|
<li><a href="#cov">cov()</a></li>
|
|
<li><a href="#is_sympd">.is_sympd()</a></li>
|
|
<li><a href="#gmm_diag">gmm_diag / gmm_full</a> - probabilistic clustering and likelihood calculation via Gaussian mixture models</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Multivariate_normal_distribution">multivariate normal distribution in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="chi2rnd"></a>
|
|
<b>chi2rnd( DF )</b>
|
|
<br>
|
|
<b>chi2rnd( DF_scalar )</b>
|
|
<br>
|
|
<b>chi2rnd( DF_scalar, n_elem )</b>
|
|
<br>
|
|
<b>chi2rnd( DF_scalar, n_rows, n_cols )</b>
|
|
<br>
|
|
<b>chi2rnd( DF_scalar, size(X) )</b>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
Generate a random scalar, vector or matrix with elements sampled from a chi-squared distribution with the degrees of freedom specified by parameter <i>DF</i> or <i>DF_scalar</i>
|
|
</li>
|
|
<br>
|
|
<li><i>DF</i> is a vector or matrix, while <i>DF_scalar</i> is a scalar</li>
|
|
<br>
|
|
<li>Each value in <i>DF</i> and <i>DF_scalar</i> must be greater than zero</li>
|
|
<br>
|
|
<li>
|
|
For the <i>chi2rnd(DF)</i> form, the output vector/matrix has the same size and type as <i>DF</i>; each element in <i>DF</i> specifies a separate degree of freedom
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Usage:
|
|
<ul>
|
|
<li><i>vector_type</i> v = chi2rnd( DF ), where the type of DF is a real <i>vector_type</i></li>
|
|
<li><i>matrix_type</i> X = chi2rnd( DF ), where the type of DF is a real <i>matrix_type</i></li>
|
|
<br>
|
|
<li><i>scalar_type</i> s = chi2rnd<<i>scalar_type</i>>( DF_scalar ), where <i>scalar_type</i> is either <i>float</i> or <i>double</i></li>
|
|
<li><i>vector_type</i> v = chi2rnd<<i>vector_type</i>>( DF_scalar, n_elem )</li>
|
|
<li><i>matrix_type</i> X = chi2rnd<<i>matrix_type</i>>( DF_scalar, n_rows, n_cols )</li>
|
|
<li><i>matrix_type</i> Y = chi2rnd<<i>matrix_type</i>>( DF_scalar, size(X) )</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X = chi2rnd(2, 5, 6);
|
|
|
|
mat A = randi<mat>(5, 6, distr_param(1, 10));
|
|
mat B = chi2rnd(A);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#randg">randg()</a></li>
|
|
<li><a href="#randn">randn()</a></li>
|
|
<li><a href="#mvnrnd">mvnrnd()</a></li>
|
|
<li><a href="#wishrnd">wishrnd()</a></li>
|
|
<li><a href="#size">size()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Chi-squared_distribution">chi-squared distribution in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="wishrnd"></a>
|
|
<b>W = wishrnd( S, df )</b>
|
|
<br>
|
|
<b>W = wishrnd( S, df, D )</b>
|
|
<br>
|
|
<br>
|
|
<b>wishrnd( W, S, df )</b>
|
|
<br>
|
|
<b>wishrnd( W, S, df, D )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a random matrix sampled from the Wishart distribution with parameters <i>S</i> and <i>df</i>:
|
|
<ul>
|
|
<li><i>S</i> is a symmetric positive definite matrix (eg. a covariance matrix)</li>
|
|
<li><i>df</i> is a scalar specifying the degrees of freedom; it can be a non-integer value</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>D</i> is an optional argument; it specifies the Cholesky decomposition of <i>S</i>; if <i>D</i> is provided, <i>S</i> is ignored;
|
|
<br>using <i>D</i> is more efficient if <i>wishrnd()</i> needs to be used many times for the same <i>S</i> matrix
|
|
</li>
|
|
<br>
|
|
<li>If generating the random matrix fails:
|
|
<ul>
|
|
<li><i>W = wishrnd(S, df)</i> and <i>W = wishrnd(S, df, D)</i> reset <i>W</i> and throw a <i>std::runtime_error</i> exception</li>
|
|
<li><i>wishrnd(W, S, df)</i> and <i>wishrnd(W, S, df, D)</i> reset <i>W</i> and return a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> for the inverse (inverted) Wishart distribution, use <a href="#iwishrnd">iwishrnd()</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(5, 5, fill::randu);
|
|
|
|
mat S = X.t() * X;
|
|
|
|
mat W = wishrnd(S, 6.7);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#iwishrnd">iwishrnd()</a></li>
|
|
<li><a href="#chi2rnd">chi2rnd()</a></li>
|
|
<li><a href="#mvnrnd">mvnrnd()</a></li>
|
|
<li><a href="#chol">chol()</a></li>
|
|
<li><a href="#cov">cov()</a></li>
|
|
<li><a href="#randn">randn()</a></li>
|
|
<li><a href="#is_sympd">.is_sympd()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Wishart_distribution">Wishart distribution in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="iwishrnd"></a>
|
|
<b>W = iwishrnd( T, df )</b>
|
|
<br>
|
|
<b>W = iwishrnd( T, df, Dinv )</b>
|
|
<br>
|
|
<br>
|
|
<b>iwishrnd( W, T, df )</b>
|
|
<br>
|
|
<b>iwishrnd( W, T, df, Dinv )</b>
|
|
<ul>
|
|
<li>
|
|
Generate a random matrix sampled from the <b>inverse</b> Wishart distribution with parameters <i>T</i> and <i>df</i>:
|
|
<ul>
|
|
<li><i>T</i> is a symmetric positive definite matrix</li>
|
|
<li><i>df</i> is a scalar specifying the degrees of freedom; it can be a non-integer value</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>Dinv</i> is an optional argument; it specifies the Cholesky decomposition of the inverse of <i>T</i>; if <i>Dinv</i> is provided, <i>T</i> is ignored
|
|
<br>using <i>Dinv</i> is more efficient if <i>iwishrnd()</i> needs to be used many times for the same <i>T</i> matrix
|
|
</li>
|
|
<br>
|
|
<li>If generating the random matrix fails:
|
|
<ul>
|
|
<li><i>W = iwishrnd(T, df)</i> and <i>W = iwishrnd(T, df, Dinv)</i> reset <i>W</i> and throw a <i>std::runtime_error</i> exception</li>
|
|
<li><i>iwishrnd(W, T, df)</i> and <i>iwishrnd(W, T, df, Dinv)</i> reset <i>W</i> and return a bool set to <i>false</i> (exception is not thrown)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> for the plain (non-inverse) Wishart distribution, use <a href="#wishrnd">wishrnd()</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
mat X(5, 5, fill::randu);
|
|
|
|
mat T = X.t() * X;
|
|
|
|
mat W = iwishrnd(T, 6.7);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#wishrnd">wishrnd()</a></li>
|
|
<li><a href="#chol">chol()</a></li>
|
|
<li><a href="#inv_sympd">inv_sympd()</a></li>
|
|
<li><a href="#is_sympd">.is_sympd()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Inverse-Wishart_distribution">inverse Wishart distribution in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="running_stat"></a>
|
|
<b>running_stat<</b><i>type</i><b>></b>
|
|
<ul>
|
|
<li>
|
|
Class for running statistics (online statistics) of scalars (one dimensional process/signal)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Useful if the storage of all samples (scalars) is impractical, or if the number of samples is not known in advance
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>type</i> is 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>
|
|
For an instance of <i>running_stat</i> named as <i>X</i>, the member functions are:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X(</b>scalar<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
update the statistics using the given scalar
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.min()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
current minimum value
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.max()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
current maximum value
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.range()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
current range
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.mean()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
current mean or average value
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.var()</b> and <b>X.var(</b>norm_type<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
current variance
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.stddev()</b> and <b>X.stddev(</b>norm_type<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
current standard deviation
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.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>X.count()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
current number of samples
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>norm_type</i> argument is optional; by default <i>norm_type = 0</i> is used
|
|
</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="#running_stat_vec">running_stat_vec</a> (running statistics of vectors)</li>
|
|
<li><a href="#stats_fns">statistics functions</a></li>
|
|
<li><a href="#gmm_diag">gmm_diag / gmm_full</a> - probabilistic clustering via Gaussian mixture models</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="running_stat_vec"></a>
|
|
<b>running_stat_vec<</b><i>vec_type</i><b>></b>
|
|
<br><b>running_stat_vec<</b><i>vec_type</i><b>>(calc_cov)</b>
|
|
<ul>
|
|
<li>
|
|
Class for running statistics (online statistics) of vectors (multi-dimensional process/signal)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Useful if the storage of all samples (vectors) is impractical, or if the number of samples is not known in advance
|
|
</li>
|
|
<br>
|
|
<li>
|
|
This class is similar to <i>running_stat</i>, with the difference that vectors are processed instead of scalars
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>vec_type</i> is the vector type of the samples; for example: <i><a href="#Col">vec</a></i>, <i><a href="#Col">cx_vec</a></i>, <i><a href="#Row">rowvec</a></i>, ...
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For an instance of <i>running_stat_vec</i> named as <i>X</i>, the member functions are:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X(</b>vector<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
update the statistics using the given vector
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.min()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
vector of current minimum values
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.max()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
vector of current maximum values
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.range()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
vector of current ranges
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.mean()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
vector of current means
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.var()</b> and <b>X.var(</b>norm_type<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
vector of current variances
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.stddev()</b> and <b>X.stddev(</b>norm_type<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
vector of current standard deviations
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.cov()</b> and <b>X.cov(</b>norm_type<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
matrix of current covariances;
|
|
valid if <i>calc_cov=true</i> during construction of <i>running_stat_vec</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>X.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>X.count()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
current number of samples
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>calc_cov</i> argument is optional; by default <i>calc_cov=false</i>, indicating that the covariance matrix will not be calculated;
|
|
to enable the covariance matrix, use <i>calc_cov=true</i> during construction; for example: <i>running_stat_vec<vec> X(true);</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>norm_type</i> argument is optional; by default <i>norm_type = 0</i> is used
|
|
</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>vec_type</i>: it is either <i>float</i> or <i>double</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
running_stat_vec<vec> stats;
|
|
|
|
vec sample;
|
|
|
|
for(uword i=0; i<10000; ++i)
|
|
{
|
|
sample = randu<vec>(5);
|
|
stats(sample);
|
|
}
|
|
|
|
cout << "mean = " << endl << stats.mean() << endl;
|
|
cout << "var = " << endl << stats.var() << endl;
|
|
cout << "max = " << endl << stats.max() << endl;
|
|
|
|
//
|
|
//
|
|
|
|
running_stat_vec<rowvec> more_stats(true);
|
|
|
|
for(uword i=0; i<20; ++i)
|
|
{
|
|
sample = randu<rowvec>(3);
|
|
|
|
sample(1) -= sample(0);
|
|
sample(2) += sample(1);
|
|
|
|
more_stats(sample);
|
|
}
|
|
|
|
cout << "covariance matrix = " << endl;
|
|
cout << more_stats.cov() << endl;
|
|
|
|
rowvec sd = more_stats.stddev();
|
|
|
|
cout << "correlations = " << endl;
|
|
cout << more_stats.cov() / (sd.t() * sd);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#running_stat">running_stat</a> (running statistics of scalars)</li>
|
|
<li><a href="#stats_fns">statistics functions</a></li>
|
|
<li><a href="#cov">cov()</a></li>
|
|
<li><a href="#cor">cor()</a></li>
|
|
<li><a href="#gmm_diag">gmm_diag / gmm_full</a> - probabilistic clustering via Gaussian mixture models</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="kmeans"></a>
|
|
<b>kmeans(</b> means<b>,</b> data<b>,</b> k<b>,</b> seed_mode<b>,</b> n_iter<b>,</b> print_mode <b>)</b>
|
|
<ul>
|
|
<li>
|
|
Cluster given data into <i>k</i> disjoint sets
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>means</i> parameter is the output matrix for storing the resulting centroids of the sets, with each centroid stored as a column vector
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>data</i> parameter is the input data matrix, with each sample stored as a column vector
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>k</i> parameter indicates the number of centroids;
|
|
the number of samples in the <i>data</i> matrix should be much larger than <i>k</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>seed_mode</i> parameter specifies how the initial centroids are seeded; it is one of:
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr><td><code>keep_existing</code></td><td> </td><td>use the centroids specified in the <i>means</i> matrix as the starting point</td></tr>
|
|
<tr><td><code>static_subset</code></td><td> </td><td>use a subset of the data vectors (repeatable)</td></tr>
|
|
<tr><td><code>random_subset</code></td><td> </td><td>use a subset of the data vectors (random)</td></tr>
|
|
<tr><td><code>static_spread</code></td><td> </td><td>use a maximally spread subset of data vectors (repeatable)</td></tr>
|
|
<tr><td><code>random_spread</code></td><td> </td><td>use a maximally spread subset of data vectors (random start)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<br>
|
|
<b>Caveat:</b> seeding the initial centroids with <code>static_spread</code> and <code>random_spread</code>
|
|
can be much more time consuming than with <code>static_subset</code> and <code>random_subset</code>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>n_iter</i> parameter specifies the number of clustering iterations; this is data dependent, but about 10 is typically sufficient
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The <i>print_mode</i> parameter is either <i>true</i> or <i>false</i>, indicating whether progress is printed during clustering
|
|
</li>
|
|
<br>
|
|
<li>
|
|
If the clustering fails, the <i>means</i> matrix is reset and a bool set to <i>false</i> is returned
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For faster execution on multi-core machines, enable OpenMP in your compiler (eg. <i>-fopenmp</i> in GCC and clang)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> for probabilistic clustering, use the <a href="#gmm_diag">gmm_diag</a> or <a href="#gmm_full">gmm_full</a> classes instead
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
uword d = 5; // dimensionality
|
|
uword N = 10000; // number of vectors
|
|
|
|
mat data(d, N, fill::randu);
|
|
|
|
mat means;
|
|
|
|
bool status = kmeans(means, data, 2, random_subset, 10, true);
|
|
|
|
if(status == false)
|
|
{
|
|
cout << "clustering failed" << endl;
|
|
}
|
|
|
|
means.print("means:");
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#gmm_diag">gmm_diag / gmm_full</a></li>
|
|
<li><a href="#stats_fns">statistics functions</a></li>
|
|
<li><a href="#running_stat_vec">running_stat_vec</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/K-means_clustering">k-means clustering in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/K-MeansClusteringAlgorithm.html">k-means clustering in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/OpenMP">OpenMP in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="gmm_diag"></a>
|
|
<a name="gmm_full"></a>
|
|
<b>gmm_diag</b>
|
|
<br><b>gmm_full</b>
|
|
|
|
<ul>
|
|
<li>
|
|
Classes for multi-variate probabilistic clustering and likelihood calculation via <b>Gaussian Mixture Models</b> (GMMs)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Distribution of data is modelled as:
|
|
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;"> </td><td style="vertical-align: top;"> </td><td style="vertical-align: top;"><i><sub>n_gaus-1</sub></i></td><td style="vertical-align: top;"> </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"><i>p<font size=+1>(</font>x<font size=+1>)</font></i></td><td style="vertical-align: top;"> <font size=+1>=</font> </td><td style="vertical-align: top;"><i><font size=+1><b>∑</b></font></i></td>
|
|
<td style="vertical-align: top;"><i>h<sub>g</sub></i> <font size=+1>N(</font><small> </small><i>x</i><small> </small>|<small> </small><i>m<sub>g</sub></i><small> </small>, <i>C<sub>g</sub></i><small> </small><font size=+1>)</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> </td><td style="vertical-align: top;"> </td><td style="vertical-align: top;"><i><sup>g=0</sup></i></td><td style="vertical-align: top;"> </td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
where:
|
|
<ul>
|
|
<li><i>x</i> is a column vector</li>
|
|
<li><i>n_gaus</i> is the number of Gaussians; <i>n_gaus</i> ≥ 1</li>
|
|
<li>N(<small> </small><i>x</i><small> </small>|<small> </small><i>m<sub>g</sub></i><small> </small>, <i>C<sub>g</sub></i><small> </small>) represents a Gaussian (normal) distribution</li>
|
|
<li>each Gaussian <i>g</i> has the following parameters:
|
|
<ul>
|
|
<li><i>h<sub>g</sub></i> is the heft (weight), with constraints <i>h<sub>g</sub></i> ≥ 0 and ∑<i>h<sub>g</sub></i> = 1</li>
|
|
<li><i>m<sub>g</sub></i> is the mean vector (centroid) with dimensionality <i>n_dims</i></li>
|
|
<li><i>C<sub>g</sub></i> is the covariance matrix (either diagonal or full)</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>gmm_diag</i> is tailored for <b>diagonal covariance matrices</b>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>gmm_full</i> is tailored for <b>full covariance matrices</b>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<i>gmm_diag</i> is considerably faster than <i>gmm_full</i>, at the cost of some reduction in modelling accuracy
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Both <i>gmm_diag</i> and <i>gmm_full</i> include tailored k-means and Expectation Maximisation algorithms for learning model parameters from training data
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For faster execution on multi-core machines, enable OpenMP in your compiler (eg. <i>-fopenmp</i> in GCC and clang)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Implementation details are available in the following paper:
|
|
<ul>
|
|
Conrad Sanderson and Ryan Curtin.
|
|
<br><i><a href="armadillo_spcs_2017.pdf">An Open Source C++ Implementation of Multi-Threaded Gaussian Mixture Models, k-Means and Expectation Maximisation</a></i>.
|
|
<br><a class="latent" href="https://doi.org/10.1109/ICSPCS.2017.8270510">International Conference on Signal Processing and Communication Systems, 2017.</a>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
For an instance of <i>gmm_diag</i> or <i>gmm_full</i> named as <i>M</i>, the member functions and variables are:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.log_p(</b>V<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return a scalar representing the log-likelihood of vector <i>V</i> (of type <i>vec</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.log_p(</b>V, g<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return a scalar representing the log-likelihood of vector <i>V</i> (of type <i>vec</i>), according to Gaussian with index <i>g</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.log_p(</b>X<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return a row vector (of type <code>rowvec</code>) containing log-likelihoods of each column vector in matrix <i>X</i> (of type <i>mat</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.log_p(</b>X, g<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return a row vector (of type <code>rowvec</code>) containing log-likelihoods of each column vector in matrix <i>X</i> (of type <i>mat</i>), according to Gaussian with index <i>g</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.sum_log_p(</b>X<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return a scalar representing the sum of log-likelihoods for all column vectors in matrix <i>X</i> (of type <i>mat</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.sum_log_p(</b>X, g<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return a scalar representing the sum of log-likelihoods for all column vectors in matrix <i>X</i> (of type <i>mat</i>), according to Gaussian with index <i>g</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.avg_log_p(</b>X<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return a scalar representing the average log-likelihood of all column vectors in matrix <i>X</i> (of type <i>mat</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.avg_log_p(</b>X, g<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return a scalar representing the average log-likelihood of all column vectors in matrix <i>X</i> (of type <i>mat</i>), according to Gaussian with index <i>g</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.assign(</b>V, dist_mode<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return the index of the closest mean (or Gaussian) to vector <i>V</i> (of type <i>vec</i>);<br>
|
|
parameter <i>dist_mode</i> is one of:
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr><td style="vertical-align: top;"><code>eucl_dist</code></td><td> </td><td style="vertical-align: top;">Euclidean distance (takes only means into account)</td></tr>
|
|
<tr><td style="vertical-align: top;"><code>prob_dist</code></td><td> </td><td style="vertical-align: top;">probabilistic "distance", defined as the inverse likelihood (takes into account means, covariances and hefts)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.assign(</b>X, dist_mode<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return a row vector (of type <i>urowvec</i>) containing the indices of the closest means (or Gaussians) to each column vector in matrix <i>X</i> (of type <i>mat</i>);<br>
|
|
parameter <i>dist_mode</i> is either <code>eucl_dist</code> or <code>prob_dist</code> (as per the <b>.assign()</b> function above)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.raw_hist(</b>X, dist_mode<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return a row vector (of type <code>urowvec</code>) representing the raw histogram of counts;
|
|
each entry is the number of counts corresponding to a Gaussian;
|
|
each count is the number times the corresponding Gaussian was the closest to each column vector in matrix <i>X</i>;<br>
|
|
parameter <i>dist_mode</i> is either <code>eucl_dist</code> or <code>prob_dist</code> (as per the <b>.assign()</b> function above)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.norm_hist(</b>X, dist_mode<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
similar to the <b>.raw_hist()</b> function above;
|
|
return a row vector (of type <code>rowvec</code>) containing normalised counts;
|
|
the vector sums to one;<br>
|
|
parameter <i>dist_mode</i> is either <code>eucl_dist</code> or <code>prob_dist</code> (as per the <b>.assign()</b> function above)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.generate()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return a column vector (of type <i>vec</i>) representing a random sample generated according to the model's parameters
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.generate(</b>N<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return a matrix (of type <i>mat</i>) containing <i>N</i> column vectors, with each vector representing a random sample generated according to the model's parameters
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.save(</b>filename<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
save the model to a file and return a <i>bool</i> indicating either success (<i>true</i>) or failure (<i>false</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.load(</b>filename<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
load the model from a file and return a <i>bool</i> indicating either success (<i>true</i>) or failure (<i>false</i>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.n_gaus()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return the number of means/Gaussians in the model
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.n_dims()</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return the dimensionality of the means/Gaussians in the model
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.reset(</b>n_dims, n_gaus<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
set the model to have dimensionality <i>n_dims</i>, with <i>n_gaus</i> number of Gaussians;<br>
|
|
all the means are set to zero, all covariance matrix representations are equivalent to the identity matrix, and all the hefts (weights) are set to be uniform
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.hefts</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
read-only row vector (of type <i>rowvec</i>) containing the hefts (weights)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.means</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
read-only matrix (of type <i>mat</i>) containing the means (centroids), stored as column vectors
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.dcovs</b>
|
|
<br><i>[only in gmm_diag]</i>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
read-only matrix (of type <i>mat</i>) containing the representation of diagonal covariance matrices,
|
|
with the set of diagonal covariances for each Gaussian stored as a column vector;
|
|
applicable only to the <i>gmm_diag</i> class
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.fcovs</b>
|
|
<br><i>[only in gmm_full]</i>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
read-only <a href="#Cube">cube</a> containing the full covariance matrices,
|
|
with each covariance matrix stored as a slice within the cube;
|
|
applicable only to the <i>gmm_full</i> class
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.set_hefts(</b>V<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
set the hefts (weights) of the model to be as specified in row vector <i>V</i> (of type <i>rowvec</i>);
|
|
the number of hefts must match the existing model
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.set_means(</b>X<b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
set the means to be as specified in matrix <i>X</i> (of type <i>mat</i>);
|
|
the number of means and their dimensionality must match the existing model
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.set_dcovs(</b>X<b>)</b>
|
|
<br><i>[only in gmm_diag]</i>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
set the diagonal covariances matrices to be as specified in matrix <i>X</i> (of type <i>mat</i>),
|
|
with the set of diagonal covariances for each Gaussian stored as a column vector;
|
|
the number of covariance matrices and their dimensionality must match the existing model;
|
|
applicable only to the <i>gmm_diag</i> class
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.set_fcovs(</b>X<b>)</b>
|
|
<br><i>[only in gmm_full]</i>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
set the full covariances matrices to be as specified in cube <i>X</i>,
|
|
with each covariance matrix stored as a slice within the cube;
|
|
the number of covariance matrices and their dimensionality must match the existing model;
|
|
applicable only to the <i>gmm_full</i> class
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b>M.set_params(</b><small>means</small>, <small>covs</small>, <small>hefts</small><b>)</b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
set all the parameters at the same time;
|
|
the type and layout of the parameters is as per the <b>.set_hefts()</b>, <b>.set_means()</b>, <b>.set_dcovs()</b> and <b>.set_fcovs()</b> functions above;
|
|
the number of Gaussians and dimensionality can be different from the existing model
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
<td style="vertical-align: top;"> <br></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;" colspan=3>
|
|
<b>M.learn(</b>data, n_gaus, dist_mode, seed_mode, km_iter, em_iter, var_floor, print_mode<b>)</b><br>
|
|
learn the model parameters via multi-threaded k-means and/or EM algorithms;
|
|
return a <code>bool</code> value, with <i>true</i> indicating success, and <i>false</i> indicating failure;
|
|
the parameters have the following meanings:
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;"><i>data</i></td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;">
|
|
matrix (of type <i>mat</i>) containing training samples; each sample is stored as a column vector
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;"><i>n_gaus</i></td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;">
|
|
set the number of Gaussians to <i>n_gaus</i>;
|
|
to help convergence, it is recommended that the given <i>data</i> matrix (above) contains at least 10 samples for each Gaussian
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;"><i>dist_mode</i></td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;">
|
|
specifies the distance used during the seeding of initial means and k-means clustering:
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr><td><code>eucl_dist</code></td><td> </td><td>Euclidean distance</td></tr>
|
|
<tr><td><code>maha_dist</code></td><td> </td><td>Mahalanobis distance, which uses a global diagonal covariance matrix estimated from the training samples; this is recommended for probabilistic applications</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;"><i>seed_mode</i></td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;">
|
|
specifies how the initial means are seeded prior to running k-means and/or EM algorithms:
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr><td><code>keep_existing</code></td><td> </td><td>keep the existing model (do not modify the means, covariances and hefts)</td></tr>
|
|
<tr><td><code>static_subset</code></td><td> </td><td>a subset of the training samples (repeatable)</td></tr>
|
|
<tr><td><code>random_subset</code></td><td> </td><td>a subset of the training samples (random)</td></tr>
|
|
<tr><td><code>static_spread</code></td><td> </td><td>a maximally spread subset of training samples (repeatable)</td></tr>
|
|
<tr><td><code>random_spread</code></td><td> </td><td>a maximally spread subset of training samples (random start)</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<br>
|
|
<b>caveat:</b> seeding the initial means with <code>static_spread</code> and <code>random_spread</code>
|
|
can be much more time consuming than with <code>static_subset</code> and <code>random_subset</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;"><i>km_iter</i></td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;">
|
|
the number of iterations of the k-means algorithm;
|
|
this is data dependent, but typically 10 iterations are sufficient
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;"><i>em_iter</i></td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;">
|
|
the number of iterations of the EM algorithm;
|
|
this is data dependent, but typically 5 to 10 iterations are sufficient
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;"><i>var_floor</i></td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;">
|
|
the variance floor (smallest allowed value) for the diagonal covariances;
|
|
setting this to a small non-zero value can help with convergence and/or better quality parameter estimates
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;"><i>print_mode</i></td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;">
|
|
either <code>true</code> or <code>false</code>;
|
|
enable or disable printing of progress during the k-means and EM algorithms
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
// create synthetic data with 2 Gaussians
|
|
|
|
uword d = 5; // dimensionality
|
|
uword N = 10000; // number of vectors
|
|
|
|
mat data(d, N, fill::zeros);
|
|
|
|
vec mean0 = linspace<vec>(1,d,d);
|
|
vec mean1 = mean0 + 2;
|
|
|
|
uword i = 0;
|
|
|
|
while(i < N)
|
|
{
|
|
if(i < N) { data.col(i) = mean0 + randn<vec>(d); ++i; }
|
|
if(i < N) { data.col(i) = mean0 + randn<vec>(d); ++i; }
|
|
if(i < N) { data.col(i) = mean1 + randn<vec>(d); ++i; }
|
|
}
|
|
|
|
|
|
// model the data as a diagonal GMM with 2 Gaussians
|
|
|
|
gmm_diag model;
|
|
|
|
bool status = model.learn(data, 2, maha_dist, random_subset, 10, 5, 1e-10, true);
|
|
|
|
if(status == false)
|
|
{
|
|
cout << "learning failed" << endl;
|
|
}
|
|
|
|
model.means.print("means:");
|
|
|
|
double scalar_likelihood = model.log_p( data.col(0) );
|
|
rowvec set_likelihood = model.log_p( data.cols(0,9) );
|
|
|
|
double overall_likelihood = model.avg_log_p(data);
|
|
|
|
uword gaus_id = model.assign( data.col(0), eucl_dist );
|
|
urowvec gaus_ids = model.assign( data.cols(0,9), prob_dist );
|
|
|
|
urowvec hist1 = model.raw_hist (data, prob_dist);
|
|
rowvec hist2 = model.norm_hist(data, eucl_dist);
|
|
|
|
model.save("my_model.gmm");
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="#normpdf">normpdf()</a></li>
|
|
<li><a href="#mvnrnd">mvnrnd()</a></li>
|
|
<li><a href="#stats_fns">statistics functions</a></li>
|
|
<li><a href="#running_stat_vec">running_stat_vec</a></li>
|
|
<li><a href="#kmeans">kmeans()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Covariance_matrix">covariance matrix in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/CovarianceMatrix.html">covariance matrix in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Mahalanobis_distance">Mahalanobis distance in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Multivariate_normal_distribution">multivariate normal distribution in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Mixture_model">mixture model in Wikipedia</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/K-means_clustering">k-means clustering in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/K-MeansClusteringAlgorithm.html">k-means clustering in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Expectation-maximization_algorithm">Expectation-Maximisation algorithm in Wikipedia</a></li>
|
|
<li><a href="https://mathworld.wolfram.com/MaximumLikelihood.html">maximum likelihood in MathWorld</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/OpenMP">OpenMP in Wikipedia</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div>
|
|
<hr class="greyline">
|
|
<hr class="greyline">
|
|
<br>
|
|
<br>
|
|
<font size=+1><b>Miscellaneous</b></font>
|
|
<br>
|
|
<br>
|
|
|
|
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="constants"></a>
|
|
<b>constants (pi, inf, eps, ...)</b>
|
|
<br>
|
|
<ul>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::tau</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
τ, the ratio of any circle's circumference to its radius; equivalent to 2π
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::pi</code>
|
|
</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;">
|
|
<code>datum::inf</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
∞, infinity
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::nan</code>
|
|
</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;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::eps</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
machine epsilon; approximately 2.2204e-16; difference between 1 and the next representable value
|
|
<!-- machine epsilon: the difference between 1 and the value least greater than 1 that is representable (type and machine dependent) -->
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::e</code>
|
|
</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;">
|
|
<code>datum::sqrt2</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
square root of 2
|
|
</td>
|
|
</tr>
|
|
<!--
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::sqrt2pi</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
square root of 2π
|
|
</td>
|
|
</tr>
|
|
-->
|
|
<tr>
|
|
<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;">
|
|
<code>datum::log_min</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
log of minimum non-zero value (type and machine dependent)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::log_max</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
log of maximum value (type and machine dependent)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::euler</code>
|
|
</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;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::gratio</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
golden ratio
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::m_u</code>
|
|
</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;">
|
|
<code>datum::N_A</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Avogadro constant
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>datum::k</code>
|
|
</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;">
|
|
<code>datum::k_evk</code>
|
|
</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;">
|
|
<code>datum::a_0</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Bohr radius (in meters)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>datum::mu_B</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Bohr magneton
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::Z_0</code>
|
|
</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;">
|
|
<code>datum::G_0</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
conductance quantum (in siemens)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>datum::k_e</code>
|
|
</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;">
|
|
<code>datum::eps_0</code>
|
|
</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;">
|
|
<code>datum::m_e</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
electron mass (in kg)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>datum::eV</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
electron volt (in joules)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::ec</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
elementary charge (in coulombs)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::F</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Faraday constant (in coulombs)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>datum::alpha</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
fine-structure constant
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::alpha_inv</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
inverse fine-structure constant
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::K_J</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Josephson constant
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>datum::mu_0</code>
|
|
</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;">
|
|
<code>datum::phi_0</code>
|
|
</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;">
|
|
<code>datum::R</code>
|
|
</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;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::G</code>
|
|
</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;">
|
|
<code>datum::h</code>
|
|
</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;">
|
|
<code>datum::h_bar</code>
|
|
</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;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::m_p</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
proton mass (in kg)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::R_inf</code>
|
|
</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;">
|
|
<code>datum::c_0</code>
|
|
</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;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
<td style="vertical-align: top;"> </td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::sigma</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Stefan-Boltzmann constant
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>datum::R_k</code>
|
|
</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;">
|
|
<code>datum::b</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Wien wavelength displacement law constant
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<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>;
|
|
<br>
|
|
for convenience,
|
|
<i>Datum<double></i> is typedefed as <i>datum</i>,
|
|
and
|
|
<i>Datum<float></i> is typedefed as <i>fdatum</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b>
|
|
<code>datum::nan</code> is not equal to anything, even itself;
|
|
to check whether a scalar <i>x</i> is finite,
|
|
use <a href="https://en.cppreference.com/w/cpp/numeric/math/isfinite">std::isfinite</a>(<i>x</i>)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The physical constants were mainly taken from
|
|
<a href="https://physics.nist.gov/cuu/Constants">NIST 2018 CODATA values</a>,
|
|
and some from
|
|
<a href="https://www.wolframalpha.com">WolframAlpha</a> (as of 2009-06-23)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
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">.is_finite()</a></li>
|
|
<li><a href="#fill">.fill()</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/NaN">NaN</a> in Wikipedia</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Physical_constant">physical constant</a> in Wikipedia</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Turn_(angle)">replacement of 2π with τ</a> in Wikipedia</li>
|
|
<li><a href="https://tauday.com/tau-manifesto">The Tau Manifesto</a> by Michael Hartl</li>
|
|
<li><a href="https://cplusplus.com/reference/limits/numeric_limits/">std::numeric_limits</a> in cplusplus.com</li>
|
|
<li><a href="https://en.cppreference.com/w/cpp/types/numeric_limits">std::numeric_limits</a> in cppreference.com</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="wall_clock"></a>
|
|
<b>wall_clock</b>
|
|
<ul>
|
|
<li>
|
|
Simple timer class for measuring the number of elapsed seconds
|
|
</li>
|
|
<br>
|
|
<li>
|
|
An instance of the class has two member functions:
|
|
<br>
|
|
<br>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b><code>.tic()</code></b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
start the timer
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b><code>.toc()</code></b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
return the number of seconds since the last call to <code>.tic()</code>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Examples:
|
|
<ul>
|
|
<pre>
|
|
wall_clock timer;
|
|
|
|
timer.tic();
|
|
|
|
// ... do something ...
|
|
|
|
double n = timer.toc();
|
|
|
|
cout << "number of seconds: " << n << endl;
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="https://en.wikipedia.org/wiki/Elapsed_real_time">elapsed real time</a> in Wikipedia</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<br>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="rng_seed"></a>
|
|
<b>RNG seed setting</b>
|
|
<ul>
|
|
<li>
|
|
There are two functions to change the seed used by the random number generator (RNG):
|
|
<br>
|
|
<br>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b><code>arma_rng::set_seed( value )</code></b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
set the RNG seed to the specified <i>value</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<b><code>arma_rng::set_seed_random()</code></b>
|
|
</td>
|
|
<td style="vertical-align: top;"> <br>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
set the RNG seed to a value drawn from
|
|
<a href="https://en.cppreference.com/w/cpp/numeric/random/random_device">std::random_device</a> (if the reported entropy is not zero),
|
|
or <a href="https://en.wikipedia.org/wiki//dev/random">/dev/urandom</a> (on Linux and macOS),
|
|
or based on the current time (on systems without <i>/dev/urandom</i>)
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Since Armadillo 12.6.2, the default RNG on all systems is the 64-bit version of the <a href="https://en.wikipedia.org/wiki/Mersenne_Twister">Mersenne Twister</a> (aka MT19937-64)
|
|
</li>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b> when using a multi-threading framework (such as OpenMP) and the underlying system supports the <a href="https://en.cppreference.com/w/cpp/language/storage_duration">thread_local</a> storage specifier,
|
|
the above functions change the seed only within the thread they are running on
|
|
</li>
|
|
<br>
|
|
<li>
|
|
To change the seeds on all OpenMP threads to the same value, adapt the following code:
|
|
<pre>
|
|
#pragma omp parallel
|
|
{
|
|
arma_rng::set_seed(123);
|
|
}
|
|
</pre>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
To change the seeds on all OpenMP threads to unique values, adapt the following code:
|
|
<pre>
|
|
std::atomic<std::size_t> counter(0);
|
|
|
|
#pragma omp parallel
|
|
{
|
|
arma_rng::set_seed(123 + counter++);
|
|
}
|
|
</pre>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li>
|
|
<a href="#randu">randu()</a>,
|
|
<a href="#randn">randn()</a>,
|
|
<a href="#randg">randg()</a>,
|
|
<a href="#randi">randi()</a>,
|
|
<a href="#sprandu_sprandn">sprandu()</a>,
|
|
<a href="#sprandu_sprandn">sprandn()</a>,
|
|
<a href="#shuffle">shuffle()</a>,
|
|
<a href="#randperm">randperm()</a>
|
|
</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Pseudorandom_number_generator">Pseudo-random number generator</a> in Wikipedia</li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Mersenne_Twister">Mersenne Twister</a> in Wikipedia</li>
|
|
<li><a href="https://en.wikipedia.org/wiki//dev/random">/dev/random</a> in Wikipedia</li>
|
|
<li><a href="https://en.cppreference.com/w/cpp/numeric/random/mersenne_twister_engine">std::mersenne_twister_engine</a> in cppreference.com</li>
|
|
<li><a href="https://en.cppreference.com/w/cpp/numeric/random/random_device">std::random_device</a> in cppreference.com</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<br>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="output_streams"></a>
|
|
<a name="logging"></a>
|
|
<b>output streams</b>
|
|
<ul>
|
|
<li>
|
|
The default stream for printing matrices and cubes is <code>std::cout</code>
|
|
<br>the stream can be changed via the <code>ARMA_COUT_STREAM</code> define; see <a href="#config_hpp">config.hpp</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The default stream for printing warnings and errors is <code>std::cerr</code>
|
|
<br>the stream can be changed via the <code>ARMA_CERR_STREAM</code> define; see <a href="#config_hpp">config.hpp</a>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
The degree of printed warnings is controlled by the <code>ARMA_WARN_LEVEL</code> define; see <a href="#config_hpp">config.hpp</a>
|
|
</li>
|
|
<br>
|
|
<li>Example of changing the warning level:
|
|
<pre>
|
|
#define ARMA_WARN_LEVEL 1
|
|
#include <armadillo>
|
|
</pre>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<li><a href="#config_hpp">config.hpp</a></li>
|
|
<li><a href="#print">.print()</a></li>
|
|
<li><a href="https://cplusplus.com/reference/iostream/cout/">std::cout</a></li>
|
|
<li><a href="https://cplusplus.com/reference/iostream/cerr/">std::cerr</a></li>
|
|
<li><a href="https://cplusplus.com/reference/ostream/ostream/">std::ostream</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<!--
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<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>
|
|
-->
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="uword"></a>
|
|
<b>uword</b>, <b>sword</b>
|
|
<ul>
|
|
<li><i>uword</i> is a typedef for an unsigned integer type; it is used for matrix <a href="#element_access">indices</a> as well as all internal counters and loops</li>
|
|
<br>
|
|
<li><i>sword</i> is a typedef for a signed integer type</li>
|
|
<br>
|
|
<li>The minimum width of both <i>uword</i> and <i>sword</i> is either 32 or 64 bits:
|
|
<ul>
|
|
<li>the default width is 32 bits on 32-bit platforms</li>
|
|
<li>the default width is 64 bits on 64-bit platforms</li>
|
|
<li>the default width is 32 bits when using Armadillo in the R environment (via RcppArmadillo) on either 32-bit or 64-bit platforms</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<li>The width can also be forcefully set to 64 bits by enabling <a href="#config_hpp_arma_64bit_word"><i>ARMA_64BIT_WORD</i></a> via editing <i>include/armadillo_bits/config.hpp</i></li>
|
|
<br>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="https://cplusplus.com/doc/tutorial/variables/">C++ variable types</a></li>
|
|
<li><a href="https://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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="cx_double"></a>
|
|
<b>cx_double</b>, <b>cx_float</b>
|
|
<ul>
|
|
<li>
|
|
Convenience short forms (typedefs) for complex element types:
|
|
<br>
|
|
<br>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<b><code>cx_double</code></b>
|
|
</td>
|
|
<td> <br>
|
|
</td>
|
|
<td>
|
|
equivalent to <code>std::complex<double></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>cx_float</code></b>
|
|
</td>
|
|
<td> <br>
|
|
</td>
|
|
<td>
|
|
equivalent to <code>std::complex<float></code>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Example:
|
|
<ul>
|
|
<pre>
|
|
cx_mat X(5, 5, fill::randu);
|
|
|
|
X(1,2) = cx_double(3.4, 5.6);
|
|
|
|
cx_double val = X(2,3);
|
|
</pre>
|
|
</ul>
|
|
</li>
|
|
<li>See also:
|
|
<ul>
|
|
<li><a href="https://cplusplus.com/reference/complex/">complex numbers in the standard C++ library</a></li>
|
|
<li><a href="https://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>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="syntax"></a>
|
|
<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;">
|
|
<code>A(1, 1)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A(0, 0)</code>
|
|
</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;">
|
|
<code>A(k, k)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A(k-1, k-1)</code>
|
|
</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;">
|
|
<code>size(A,1)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A<a href="#attributes">.n_rows</a></code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
read only
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>size(A,2)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A<a href="#attributes">.n_cols</a></code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>size(Q,3)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Q<a href="#attributes">.n_slices</a></code>
|
|
</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;">
|
|
<code>numel(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A<a href="#attributes">.n_elem</a></code>
|
|
</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;">
|
|
<code>A(:, k)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A<a href="#submat">.col</a>(k)</code>
|
|
</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;">
|
|
<code>A(k, :)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A<a href="#submat">.row</a>(k)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>A(:, p:q)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A<a href="#submat">.cols</a>(p, q)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>A(p:q, :)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A<a href="#submat">.rows</a>(p, q)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>A(p:q, r:s)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A( <a href="#submat">span</a>(p,q), <a href="#submat">span</a>(r,s) )</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
A( span(first_row, last_row), span(first_col, last_col) )
|
|
</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;">
|
|
<code>Q(:, :, k)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Q<a href="#subcube">.slice</a>(k)</code>
|
|
</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;">
|
|
<code>Q(:, :, t:u)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>Q<a href="#subcube">.slices</a>(t, u)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>Q(p:q, r:s, t:u)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<font size=-1>
|
|
<code>Q( <a href="#subcube">span</a>(p,q), <a href="#subcube">span</a>(r,s), <a href="#subcube">span</a>(t,u) )</code>
|
|
</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;">
|
|
<code>A'</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A<a href="#t_st_members">.t()</a> or <a href="#trans">trans</a>(A)</code>
|
|
</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;">
|
|
|
|
</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;">
|
|
<code>A = zeros(size(A))</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A<a href="#zeros_member">.zeros()</a></code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>A = ones(size(A))</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A.<a href="#ones_member">ones()</a></code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>A = zeros(k)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A = <a href="#zeros_standalone">zeros</a><mat>(k,k)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>A = ones(k)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A = <a href="#ones_standalone">ones</a><mat>(k,k)</code>
|
|
</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;">
|
|
<code>C = complex(A,B)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>cx_mat C = <a href="#Mat">cx_mat</a>(A,B)</code>
|
|
</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;">
|
|
<code>A .* B</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A % B</code>
|
|
</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;">
|
|
<code>A ./ B</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A / B</code>
|
|
</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;">
|
|
<code>A \ B</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code><a href="#solve">solve</a>(A,B)</code>
|
|
</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;">
|
|
<code>A = A + 1;</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A++</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>A = A - 1;</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A--</code>
|
|
</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;">
|
|
<code>A = [ 1 2; 3 4; ]</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>
|
|
A = { { 1, 2 },<br>
|
|
{ 3, 4 } };
|
|
</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<a href="#element_initialisation">element initialisation</a>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>X = A(:)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>X = <a href="#vectorise">vectorise</a>(A)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>X = [ A B ]</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>X = <a href="#join">join_horiz</a>(A,B)</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>X = [ A; B ]</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>X = <a href="#join">join_vert</a>(A,B)</code>
|
|
</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;">
|
|
<code>A</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>cout <font size=-1><<</font> A <font size=-1><<</font> endl;</code>
|
|
<br><font size=-1>or</font>
|
|
<br><code>A<a href="#print">.print</a>("A =");</code>
|
|
</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;">
|
|
<code>save ‑ascii 'A.txt' A</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A<a href="#save_load_mat">.save</a>("A.txt", raw_ascii);</code>
|
|
</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;">
|
|
<code>load ‑ascii 'A.txt'</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>A<a href="#save_load_mat">.load</a>("A.txt", raw_ascii);</code>
|
|
</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;">
|
|
<code>A = randn(2,3);
|
|
<br>B = randn(4,5);
|
|
<br>F = { A; B }</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
<code>mat A = randn(2,3);
|
|
<br>mat B = randn(4,5);
|
|
<br><a href="#field">field</a><mat> F(2,1);
|
|
<br>F(0,0) = A;
|
|
<br>F(1,0) = B;</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: center;">
|
|
<a href="#field">fields</a> store arbitrary objects, such as matrices
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</ul>
|
|
<br>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="example_prog"></a>
|
|
<b>example program</b>
|
|
<br>
|
|
<ul>
|
|
<pre>
|
|
#include <iostream>
|
|
#include <armadillo>
|
|
|
|
using namespace std;
|
|
using namespace arma;
|
|
|
|
int main()
|
|
{
|
|
mat A(4, 5, fill::randu);
|
|
mat B(4, 5, fill::randu);
|
|
|
|
cout << A*B.t() << endl;
|
|
|
|
return 0;
|
|
}
|
|
</pre>
|
|
<li>
|
|
If the above program is stored as <i>example.cpp</i>,
|
|
under Linux and macOS it can be compiled using:
|
|
<br>
|
|
<ul><code>g++ example.cpp -o example -std=c++11 -O2 -larmadillo</code></ul>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Armadillo extensively uses template meta-programming,
|
|
so it's recommended to enable optimisation when compiling programs (eg. use the -O2 or -O3 options for GCC or clang)
|
|
</li>
|
|
<br>
|
|
<li>See the <a href="http://arma.sourceforge.net/faq.html">Questions</a> page for more info on compiling and linking</li>
|
|
<br>
|
|
<li>See also the example program that comes with the Armadillo archive</li>
|
|
</ul>
|
|
<br>
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="config_hpp"></a>
|
|
<b>config.hpp</b>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
Armadillo can be configured via editing the file <i>include/armadillo_bits/config.hpp</i>
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Specific functionality can be enabled or disabled by uncommenting or commenting out a particular <i>#define</i>, listed below.
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Some options can also be specified by explicitly defining them <b>before</b> including the armadillo header.
|
|
</li>
|
|
<br>
|
|
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
|
|
<tbody>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>ARMA_DONT_USE_WRAPPER</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Disable going through the run-time Armadillo wrapper library (<i>libarmadillo.so</i>) when calling LAPACK, BLAS, ARPACK, SuperLU and HDF5 functions.
|
|
You will need to directly link with BLAS, LAPACK, etc (eg. <code><i>-lblas -llapack</i></code>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_USE_LAPACK</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Enable use of LAPACK, or a high-speed replacement for LAPACK (eg. OpenBLAS, Intel MKL, 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>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>ARMA_DONT_USE_LAPACK</code>
|
|
</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>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>ARMA_USE_BLAS</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Enable use of BLAS, or a high-speed replacement for BLAS (eg. OpenBLAS, Intel MKL, 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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_DONT_USE_BLAS</code>
|
|
</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>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>ARMA_USE_NEWARP</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Enable use of NEWARP (built-in alternative to ARPACK).
|
|
This is used for the eigen decomposition of real (non-complex) sparse matrices, ie. <a href="#eigs_gen">eigs_gen()</a>, <a href="#eigs_sym">eigs_sym()</a> and <a href="#svds">svds().</a>
|
|
Requires ARMA_USE_LAPACK to be enabled.
|
|
If use of both NEWARP and ARPACK is enabled, NEWARP will be preferred.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_DONT_USE_NEWARP</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Disable use of NEWARP (built-in alternative to ARPACK); overrides <i>ARMA_USE_NEWARP</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_USE_ARPACK</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Enable use of ARPACK, or a high-speed replacement for ARPACK.
|
|
Armadillo requires ARPACK for the eigen decomposition of complex sparse matrices, ie. <a href="#eigs_gen">eigs_gen()</a>, <a href="#eigs_sym">eigs_sym()</a> and <a href="#svds">svds()</a>.
|
|
If use of NEWARP is disabled, ARPACK will also be used for the eigen decomposition of real sparse matrices.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_DONT_USE_ARPACK</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Disable use of ARPACK; overrides <i>ARMA_USE_ARPACK</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_USE_SUPERLU</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Enable use of SuperLU, which is used by <a href="#spsolve">spsolve()</a> for finding the solutions of sparse systems,
|
|
as well as <a href="#eigs_sym">eigs_sym()</a> and <a href="#eigs_gen">eigs_gen()</a> in shift-invert mode.
|
|
You will need to link with the superlu library, for example <code><i>-lsuperlu</i></code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_DONT_USE_SUPERLU</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Disable use of SuperLU; overrides <i>ARMA_USE_SUPERLU</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_USE_HDF5</code>
|
|
</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. <code><i>-lhdf5</i></code>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_DONT_USE_HDF5</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Disable the use of the HDF5 library; overrides <i>ARMA_USE_HDF5</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_USE_FFTW3</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Enable use of the FFTW3 library by <a href="#fft">fft()</a> and <a href="#fft">ifft()</a>;
|
|
you will need to link with the FFTW3 library (eg. <code><i>-lfftw3</i></code>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_DONT_USE_FFTW3</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Disable the use of the FFTW3 library; overrides <i>ARMA_USE_FFTW3</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_DONT_USE_STD_MUTEX</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Disable use of <i>std::mutex</i>; applicable if your compiler and/or environment doesn't support <i>std::mutex</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_DONT_OPTIMISE_BAND</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Disable automatically optimised handling of band matrices by <a href="#solve">solve()</a> and <a href="#chol">chol()</a>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_DONT_OPTIMISE_SYMPD</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Disable automatically optimised handling of symmetric/hermitian positive definite matrices by
|
|
<a href="#solve">solve()</a>,
|
|
<a href="#inv">inv()</a>,
|
|
<a href="#pinv">pinv()</a>,
|
|
<a href="#expmat">expmat()</a>,
|
|
<a href="#logmat">logmat()</a>,
|
|
<a href="#sqrtmat">sqrtmat()</a>,
|
|
<a href="#powmat">powmat()</a>,
|
|
<a href="#rcond">rcond()</a>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_USE_OPENMP</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Use OpenMP for parallelisation of computationally expensive element-wise operations
|
|
(such as <a href="#misc_fns">exp()</a>, <a href="#misc_fns">log()</a>, <a href="#trig_fns">cos()</a>, etc).
|
|
Automatically enabled when using a compiler which has OpenMP 3.1+ active (eg. the <code>-fopenmp</code> option for gcc and clang).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_DONT_USE_OPENMP</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Disable use of OpenMP for parallelisation of element-wise operations; overrides <i>ARMA_USE_OPENMP</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_OPENMP_THRESHOLD</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
The minimum number of elements in a matrix to enable OpenMP based parallelisation of computationally expensive element-wise functions; default value is 320
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_OPENMP_THREADS</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
The maximum number of threads for OpenMP based parallelisation of computationally expensive element-wise functions; default value is 8
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_BLAS_CAPITALS</code>
|
|
</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>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>ARMA_BLAS_UNDERSCORE</code>
|
|
</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>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>ARMA_BLAS_LONG</code>
|
|
</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>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>ARMA_BLAS_LONG_LONG</code>
|
|
</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>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>ARMA_USE_FORTRAN_HIDDEN_ARGS</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Use so-called "hidden arguments" when calling BLAS and LAPACK functions. Enabled by default.
|
|
See Fortran <a href="https://gcc.gnu.org/onlinedocs/gfortran/Argument-passing-conventions.html">argument passing conventions</a> for more details.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_DONT_USE_FORTRAN_HIDDEN_ARGS</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Disable use of so-called "hidden arguments" when calling BLAS and LAPACK functions.
|
|
May be necessary when using Armadillo in conjunction with broken MKL headers (eg. if you have <code>#include "mkl_lapack.h"</code> in your code).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_USE_TBB_ALLOC</code>
|
|
</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>malloc()</i> and <i>free()</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>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>ARMA_USE_MKL_ALLOC</code>
|
|
</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>malloc()</i> and <i>free()</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>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>ARMA_USE_MKL_TYPES</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Use Intel MKL types for complex numbers.
|
|
You will need to include appropriate MKL headers before the Armadillo header.
|
|
You may also need to enable one or more of the following options:
|
|
<code>ARMA_BLAS_LONG</code>, <code>ARMA_BLAS_LONG_LONG</code>, <code>ARMA_DONT_USE_FORTRAN_HIDDEN_ARGS</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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>
|
|
<code>ARMA_64BIT_WORD</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Use 64 bit integers. Automatically enabled when using a 64-bit platform, except when using Armadillo in the R environment (via RcppArmadillo).
|
|
Useful if matrices/vectors capable of holding more than 4 billion elements are required.
|
|
<!-- 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>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>ARMA_DONT_CHECK_CONFORMANCE</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
Disable all run-time checks, including size conformance and <a href="#element_access">bounds checks</a>.
|
|
NOT RECOMMENDED.
|
|
DO NOT USE UNLESS YOU KNOW WHAT YOU ARE DOING AND ARE WILLING TO RISK THE DOWNSIDES.
|
|
Keeping the checks enabled during development and deployment greatly aids in finding mistakes in your code.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_MAT_PREALLOC</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
The number of pre-allocated 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>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>ARMA_COUT_STREAM</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
The default stream used for printing matrices and cubes by <a href="#print">.print()</a>.
|
|
Must be always enabled.
|
|
By default defined 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>
|
|
</tr>
|
|
<tr>
|
|
<td style="vertical-align: top;">
|
|
<code>ARMA_CERR_STREAM</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
The default stream used for printing warnings and errors.
|
|
Must be always enabled.
|
|
By default defined to <i>std::cerr</i>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<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;">
|
|
<code>ARMA_WARN_LEVEL</code>
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
|
|
</td>
|
|
<td style="vertical-align: top;">
|
|
The level of warning messages printed to <i>ARMA_CERR_STREAM</i>.
|
|
<br>Must be an integer ≥ 0. By default defined to 2.
|
|
<table>
|
|
<tr><td>0</td><td> = </td><td>no warnings; generally not recommended</td></tr>
|
|
<tr><td>1</td><td> = </td><td>only critical warnings about arguments and/or data which are likely to lead to incorrect results</td></tr>
|
|
<tr><td>2</td><td> = </td><td>as per level 1, and warnings about poorly conditioned systems (low rcond) detected by <a href="#solve">solve()</a>, <a href="#spsolve">spsolve()</a>, etc</td></tr>
|
|
<tr><td>3</td><td> = </td><td>as per level 2, and warnings about failed decompositions, failed saving / loading, etc</td></tr>
|
|
</table>
|
|
<br>
|
|
Example usage:
|
|
<pre>
|
|
#define ARMA_WARN_LEVEL 1
|
|
#include <armadillo>
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<br>
|
|
<li>
|
|
See also:
|
|
<ul>
|
|
<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>
|
|
<li><a href="#output_streams">output streams</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
|
|
<!--
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="catching_exceptions"></a>
|
|
<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(5, 5, fill::zeros);
|
|
|
|
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="https://cplusplus.com/doc/tutorial/exceptions/">tutorial on exceptions</a></li>
|
|
<li><a href="https://cplusplus.com/reference/stdexcept/runtime_error/">std::runtime_error</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
</ul>
|
|
<br>
|
|
-->
|
|
|
|
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
|
|
<a name="api_additions"></a>
|
|
<a name="changelog"></a>
|
|
<b>History of API Additions and Changes</b>
|
|
<br>
|
|
<ul>
|
|
<li>API Stability and Version Policy:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
Each release of Armadillo has its public API (functions, classes, constants) described in the accompanying API documentation specific to that release.
|
|
</li>
|
|
<br>
|
|
<li>
|
|
Each release of Armadillo has its full version specified as <i>A.B.C</i>, where <i>A</i> is a major version number, <i>B</i> is a minor version number, and <i>C</i> is a patch level.
|
|
The version specification has explicit meaning (similar to <a href="https://semver.org/">Semantic Versioning</a>) as follows:
|
|
</li>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
Within a major version (eg. 10), each minor version (eg. 10.2) has a public API that strongly strives to be <b>backwards compatible</b> (at the source level) with the public API of preceding minor versions.
|
|
For example, user code written for version 10.0 should work with version 10.1, 10.2, etc.
|
|
However, subsequent minor versions may have more features (API additions and extensions) than preceding minor versions.
|
|
As such, user code <i>specifically</i> written for version 10.2 may not work with 10.1.
|
|
</li>
|
|
<br>
|
|
<li>
|
|
An increase in the patch level, while the major and minor versions are retained, indicates modifications to the code and/or documentation which aim to fix bugs without altering the public API.
|
|
</li>
|
|
<br>
|
|
<li>
|
|
We don't like changes to existing public API and strongly prefer not to break any user software.
|
|
However, to allow evolution, the public API may be altered in future major versions while remaining backwards compatible in as many cases as possible
|
|
(eg. major version 11 may have slightly different public API than major version 10).
|
|
</li>
|
|
</ul>
|
|
<br>
|
|
<li>
|
|
<b>Caveat:</b>
|
|
the above policy applies only to the public API described in the documentation.
|
|
Any functionality within Armadillo which is <u>not explicitly</u> described in the public API documentation is considered as internal implementation detail,
|
|
and may be changed or removed without notice.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<!--
|
|
<br>
|
|
<li>
|
|
<a name="deprecated"></a>
|
|
List of deprecated functionality; this functionality will be <b>removed</b> in version A.B:
|
|
<ul>
|
|
<li>
|
|
...
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
-->
|
|
|
|
<br>
|
|
<br>
|
|
<li>
|
|
List of additions and changes for each version:
|
|
<br>
|
|
<br>
|
|
<ul>
|
|
|
|
|
|
|
|
<a name="version_140"></a>
|
|
<li>Version 14.0 (under development)
|
|
<ul>
|
|
<li>C++14 is now the minimum required C++ standard</li>
|
|
<li>faster handling of compound expressions by <a href="#as_scalar">as_scalar()</a>, <a href="#accu">accu()</a>, <a href="#dot">dot()</a></li>
|
|
<li>faster interactions between sparse submatrix views and dense matrices</li>
|
|
<li>expanded <a href="#stats_fns">stddev()</a> to handle sparse matrices</li>
|
|
<li>
|
|
sparse matrix versions of
|
|
<a href="#min_and_max">min()</a>,
|
|
<a href="#min_and_max">max()</a>,
|
|
<a href="#sum">sum()</a>,
|
|
<a href="#stats_fns">mean()</a>,
|
|
<a href="#stats_fns">var()</a>,
|
|
<a href="#diagvec">diagvec()</a>,
|
|
<a href="#vecnorm">vecnorm()</a>
|
|
now return dense vectors
|
|
</li>
|
|
<li>TODO: ...</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_128"></a>
|
|
<li>Version 12.8:
|
|
<ul>
|
|
<li>faster detection of symmetric expressions by <a href="#pinv">pinv()</a> and <a href="#rank">rank()</a></li>
|
|
<li>faster handling of sparse submatrix views</li>
|
|
<li>expanded <a href="#shift">shift()</a> to handle sparse matrices</li>
|
|
<li>expanded <a href="#conv_to">conv_to</a> for more flexible conversions between sparse and dense matrices</li>
|
|
<li>added <a href="#misc_fns">cbrt()</a></li>
|
|
<li>more compact representation of integers when <a href="#save_load_mat">saving</a> matrices in CSV format</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_126"></a>
|
|
<li>Version 12.6:
|
|
<ul>
|
|
<li>faster multiplication of dense vectors by <a href="#SpMat">sparse matrices</a> (and vice versa)</li>
|
|
<li>faster <a href="#eigs_sym">eigs_sym()</a>, <a href="#eigs_gen">eigs_gen()</a>, <a href="#svds">svds()</a></li>
|
|
<li>faster <a href="#conv">conv()</a> and <a href="#conv2">conv2()</a> when using OpenMP</li>
|
|
<!-- <li>more efficient move constructors in dense vector classes</li> -->
|
|
<li>added <a href="#diags_spdiags">diags()</a> and <a href="#diags_spdiags">spdiags()</a> for generating band matrices from set of vectors</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_124"></a>
|
|
<li>Version 12.4:
|
|
<ul>
|
|
<li>added <a href="#norm2est">norm2est()</a> for finding fast estimates of matrix 2-norm (spectral norm)</li>
|
|
<li>added <a href="#vecnorm">vecnorm()</a> for obtaining the vector norm of each row or column of a matrix</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_122"></a>
|
|
<li>Version 12.2:
|
|
<ul>
|
|
<li>more efficient use of FFTW3 by <a href="#fft">fft()</a> and <a href="#fft">ifft()</a></li>
|
|
<li>faster in-place element-wise multiplication of <a href="#SpMat">sparse matrices</a> by dense matrices</li>
|
|
<li>added <a href="#spsolve_factoriser">spsolve_factoriser</a> class to allow reuse of sparse matrix factorisation for solving systems of linear equations</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_120"></a>
|
|
<li>Version 12.0:
|
|
<ul>
|
|
<li>faster <a href="#fft">fft()</a> and <a href="#fft">ifft()</a> via optional use of FFTW3</li>
|
|
<li>faster <a href="#min_and_max">min()</a> and <a href="#min_and_max">max()</a></li>
|
|
<li>faster <a href="#index_min_and_index_max_standalone">index_min()</a> and <a href="#index_min_and_index_max_standalone">index_max()</a></li>
|
|
<li>added <a href="#col_row_as_mat">.col_as_mat()</a> and <a href="#col_row_as_mat">.row_as_mat()</a> which return matrix representation of cube column and cube row</li>
|
|
<li>added <code>csv_opts::strict</code> option to <a href="#save_load_mat">loading CSV files</a> to interpret missing values as NaN</li>
|
|
<li>added <code>check_for_zeros</code> option to form 4 of <a href="#batch_constructors_sp_mat">sparse matrix batch constructors</a></li>
|
|
<li><a href="#inv">inv()</a> and <a href="#inv_sympd">inv_sympd()</a> with options <code>inv_opts::no_ugly</code> or <code>inv_opts::allow_approx</code> now use a scaled threshold similar to <a href="#pinv">pinv()</a></li>
|
|
<li><code>set_cout_stream()</code> and <code>set_cerr_stream()</code> are now no-ops; instead use the options <a href="#config_hpp">ARMA_WARN_LEVEL</a>, or <a href="#config_hpp">ARMA_COUT_STREAM</a>, or <a href="#config_hpp">ARMA_CERR_STREAM</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_114"></a>
|
|
<li>Version 11.4:
|
|
<ul>
|
|
<li>extended <a href="#pow">pow()</a> with various forms of element-wise power operations</li>
|
|
<li>added <a href="#find_nan">find_nan()</a> to find indices of NaN elements</li>
|
|
<li>faster handling of compound expressions by <a href="#sum">sum()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_112"></a>
|
|
<li>Version 11.2:
|
|
<ul>
|
|
<li>extended <a href="#randu">randu()</a> and <a href="#randn">randn()</a> to allow specification of distribution parameters</li>
|
|
<li>added <code>inv_opts::no_ugly</code> option to <a href="#inv">inv()</a> and <a href="#inv_sympd">inv_sympd()</a> to disallow inverses of poorly conditioned matrices</li>
|
|
<li>more efficient handling of rank-deficient matrices via <code>inv_opts::allow_approx</code> option in <a href="#inv">inv()</a> and <a href="#inv_sympd">inv_sympd()</a></li>
|
|
<li>faster handling of sparse submatrix column views by <a href="#norm">norm()</a>, <a href="#accu">accu()</a>, <a href="#nonzeros">nonzeros()</a></li>
|
|
<li>faster handling of symmetric and diagonal matrices by <a href="#cond">cond()</a></li>
|
|
<li>better detection of rank deficient matrices by <a href="#solve">solve()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_110"></a>
|
|
<li>Version 11.0:
|
|
<ul>
|
|
<li>added variants of <a href="#inv">inv()</a> and <a href="#inv_sympd">inv_sympd()</a> that provide <i>rcond</i> (reciprocal condition number)</li>
|
|
<li>added <code>inv_opts::allow_approx</code> option to <a href="#inv">inv()</a> and <a href="#inv_sympd">inv_sympd()</a> to allow approximate inverses of poorly conditioned matrices</li>
|
|
<li>stricter handling of singular matrices by <a href="#inv">inv()</a> and <a href="#inv_sympd">inv_sympd()</a></li>
|
|
<li>stricter handling of non-sympd matrices by <a href="#inv_sympd">inv_sympd()</a></li>
|
|
<li>stricter handling of non-finite matrices by <a href="#pinv">pinv()</a></li>
|
|
<li>more robust handling of rank deficient matrices by <a href="#solve">solve()</a></li>
|
|
<li>faster handling of diagonal matrices by <a href="#rcond">rcond()</a></li>
|
|
<li>changed <a href="#eigs_sym">eigs_sym()</a> and <a href="#eigs_gen">eigs_gen()</a> to use higher quality RNG</li>
|
|
<li><a href="#quantile">quantile()</a> and <a href="#stats_fns">median()</a> will now throw an exception if given matrices/vectors have NaN elements</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_108"></a>
|
|
<li>Version 10.8:
|
|
<ul>
|
|
<li>faster handling of symmetric matrices by <a href="#pinv">pinv()</a> and <a href="#rank">rank()</a></li>
|
|
<li>faster handling of diagonal matrices by <a href="#inv_sympd">inv_sympd()</a>, <a href="#pinv">pinv()</a>, <a href="#rank">rank()</a></li>
|
|
<li>expanded <a href="#norm">norm()</a> to handle integer vectors and matrices</li>
|
|
<li>added <a href="#constants">datum::tau</a> to replace 2π</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_107"></a>
|
|
<li>Version 10.7:
|
|
<ul>
|
|
<li>faster handling of <a href="#submat">submatrix views</a> accessed by <code>X.cols(first_col,last_col)</code></li>
|
|
<li>faster handling of element-wise <a href="#min_and_max">min()</a> and <a href="#min_and_max">max()</a> in compound expressions</li>
|
|
<li>expanded <a href="#solve">solve()</a> with <code>solve_opts::force_approx</code> option to force use of the approximate solver</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_106"></a>
|
|
<li>Version 10.6:
|
|
<ul>
|
|
<li>expanded <a href="#chol">chol()</a> to optionally use pivoted decomposition</li>
|
|
<li>expanded vector, matrix and cube constructors to allow element initialisation via <code>fill::value(scalar)</code>, eg. <code>mat X(4,5,fill::value(123))</code></li>
|
|
<li>faster <a href="#save_load_mat">loading</a> of CSV files when using OpenMP
|
|
<li>added <i>csv_opts::semicolon</i> option to allow <a href="#save_load_mat">saving / loading</a> of CSV files with semicolon (;) instead of comma (,) as the separator</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_105"></a>
|
|
<li>Version 10.5:
|
|
<ul>
|
|
<li>added <a href="#clamp_member">.clamp()</a> member function</li>
|
|
<li>expanded the standalone <a href="#clamp">clamp()</a> function to handle complex values</li>
|
|
<li>more efficient use of OpenMP</li>
|
|
<li>vector, matrix and cube constructors now initialise elements to zero by default;
|
|
<br>element initialisation can be disabled via the <code>fill::none</code> specifier, eg. <code>mat X(4,5,fill::none)</code>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_104"></a>
|
|
<li>Version 10.4:
|
|
<ul>
|
|
<li>faster handling of triangular matrices by <a href="#log_det">log_det()</a></li>
|
|
<li>added <a href="#log_det_sympd">log_det_sympd()</a> for log determinant of symmetric positive matrices</li>
|
|
<li>added <code>ARMA_WARN_LEVEL</code> <a href="#config_hpp">configuration option</a>, to control the degree of emitted warning messages</li>
|
|
<li>reduced the default degree of warning messages, so that failed decompositions, failed saving / loading, etc, no longer emit warnings</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_103"></a>
|
|
<li>Version 10.3:
|
|
<ul>
|
|
<li>faster handling of symmetric positive definite matrices by <a href="#pinv">pinv()</a></li>
|
|
<li>expanded <a href="#save_load_mat">.save() / .load()</a> for dense matrices to handle <i>coord_ascii</i> format</li>
|
|
<li>for out of bounds access, <a href="#element_access">element accessors</a> now throw the more nuanced <i>std::out_of_range</i> exception, instead of only <i>std::logic_error</i>
|
|
<li>improved quality of random numbers</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_102"></a>
|
|
<li>Version 10.2:
|
|
<ul>
|
|
<li>faster handling of <a href="#subcube">subcubes</a></li>
|
|
<li>added <a href="#misc_fns">tgamma()</a></li>
|
|
<li>added <a href="#brief_print">.brief_print()</a> for abridged printing of matrices & cubes</li>
|
|
<li>expanded sparse matrix forms of <a href="#trimat">trimatu()</a> and <a href="#trimat">trimatl()</a> to allow specifying the diagonal delimiter</li>
|
|
<li>expanded <a href="#eigs_sym">eigs_sym()</a> and <a href="#eigs_gen">eigs_gen()</a> with optional shift-invert mode</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_101"></a>
|
|
<li>Version 10.1:
|
|
<ul>
|
|
<li>C++11 is now the minimum required C++ standard</li>
|
|
<li>faster handling of compound expressions by <a href="#trimat">trimatu()</a> and <a href="#trimat">trimatl()</a></li>
|
|
<li>faster sparse matrix addition, subtraction and element-wise multiplication</li>
|
|
<li>expanded sparse <a href="#submat">submatrix views</a> to handle the non-contiguous form of <i>X.cols(vector_of_column_indices)</i></li>
|
|
<li>expanded <a href="#eigs_sym">eigs_sym()</a> and <a href="#eigs_gen">eigs_gen()</a> with optional fine-grained parameters</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_9900"></a>
|
|
<li>Version 9.900:
|
|
<ul>
|
|
<li>faster <a href="#solve">solve()</a> for under/over-determined systems</li>
|
|
<li>faster <a href="#eig_gen">eig_gen()</a> and <a href="#eig_pair">eig_pair()</a> for large matrices</li>
|
|
<li>faster handling of matrix multiplication expressions by <a href="#diagvec">diagvec()</a> and <a href="#diagmat">diagmat()</a></li>
|
|
<li>faster handling of relational expressions by <a href="#accu">accu()</a></li>
|
|
<li>faster handling of sympd matrices by <a href="#expmat">expmat()</a>, <a href="#logmat">logmat()</a>, <a href="#sqrtmat">sqrtmat()</a></li>
|
|
<li>faster access to columns in sparse submatrix views</li>
|
|
<li>added <a href="#quantile">quantile()</a></li>
|
|
<li>added <a href="#powmat">powmat()</a></li>
|
|
<li>added <a href="#trimat_ind">trimatu_ind()</a> and <a href="#trimat_ind">trimatl_ind()</a></li>
|
|
<li>added <a href="#log_normpdf">log_normpdf()</a></li>
|
|
<li>added <a href="#is_zero">.is_zero()</a></li>
|
|
<li>added <code>ARMA_DONT_USE_CXX11_MUTEX</code> <a href="#config_hpp">configuration option</a> to disable use of <i>std::mutex</i></li>
|
|
<li>expanded <a href="#eig_gen">eig_gen()</a> and <a href="#eig_pair">eig_pair()</a> to optionally provide left and right eigenvectors</li>
|
|
<li>expanded <a href="#qr">qr()</a> to optionally use pivoted decomposition</li>
|
|
<li>expanded <a href="#save_load_mat">.save()</a> and <a href="#save_load_mat">.load()</a> to handle CSV files with headers via <i>csv_name(filename,header)</i> specification</li>
|
|
<li>more consistent detection of sparse vector expressions</li>
|
|
<li>updated <a href="#constants">physical constants</a> to NIST 2018 CODATA values</li>
|
|
<li>workaround for <a href="#save_load_mat">save/load</a> issues with HDF5 v1.12</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_9800"></a>
|
|
<li>Version 9.800:
|
|
<ul>
|
|
<li>faster <a href="#solve">solve()</a> in default operation; iterative refinement is no longer applied by default; use <code>solve_opts::refine</code> to explicitly enable refinement</li>
|
|
<li>faster <a href="#expmat">expmat()</a></li>
|
|
<li>faster handling of triangular matrices by <a href="#rcond">rcond()</a></li>
|
|
<li>added <a href="#compat_container_fns">.front()</a> and <a href="#compat_container_fns">.back()</a>
|
|
<li>added <a href="#is_trimat">.is_trimatu()</a> and <a href="#is_trimat">.is_trimatl()</a></li>
|
|
<li>added <a href="#is_diagmat">.is_diagmat()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_9700"></a>
|
|
<li>Version 9.700:
|
|
<ul>
|
|
<li>faster handling of cubes by <a href="#vectorise">vectorise()</a></li>
|
|
<li>faster handling of sparse matrices by <a href="#nonzeros">nonzeros()</a></li>
|
|
<li>faster row-wise <a href="#index_min_and_index_max_standalone">index_min()</a> and <a href="#index_min_and_index_max_standalone">index_max()</a></li>
|
|
<li>expanded <a href="#join">join_rows()</a> and <a href="#join">join_cols()</a> to handle joining up to 4 matrices</li>
|
|
<li>expanded <a href="#save_load_mat">.save()</a> and <a href="#save_load_mat">.load()</a> to allow storing sparse matrices in CSV format</li>
|
|
<li>added <a href="#randperm">randperm()</a> to generate a vector with random permutation of a sequence of integers</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_9600"></a>
|
|
<li>Version 9.600:
|
|
<ul>
|
|
<li>faster handling of sparse <a href="#submat">submatrices</a></li>
|
|
<li>faster handling of sparse <a href="#diag">diagonal views</a></li>
|
|
<li>faster handling of sparse matrices by <a href="#symmat">symmatu()</a> and <a href="#symmat">symmatl()</a></li>
|
|
<li>faster handling of sparse matrices by <a href="#join">join_cols()</a></li>
|
|
<li>expanded <a href="#clamp">clamp()</a> to handle sparse matrices</li>
|
|
<li>added <a href="#clean">.clean()</a> to replace elements below a threshold with zeros</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_9500"></a>
|
|
<li>Version 9.500:
|
|
<ul>
|
|
<li>expanded <a href="#solve">solve()</a> with <code>solve_opts::likely_sympd</code> to indicate that the given matrix is likely positive definite</li>
|
|
<li>more robust automatic detection of positive definite matrices by <a href="#solve">solve()</a> and <a href="#inv">inv()</a></li>
|
|
<li>faster handling of sparse submatrices</li>
|
|
<li>expanded <a href="#eigs_sym">eigs_sym()</a> to print a warning if the given matrix is not symmetric</li>
|
|
<li>
|
|
extended LAPACK function prototypes to follow Fortran <a href="https://gcc.gnu.org/onlinedocs/gfortran/Argument-passing-conventions.html">passing conventions</a> for so-called "hidden arguments",
|
|
in order to address <a href="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=90329">GCC Bug 90329</a>;
|
|
<br>
|
|
to use previous LAPACK function prototypes without the "hidden arguments",
|
|
<code>#define ARMA_DONT_USE_FORTRAN_HIDDEN_ARGS</code> before <code>#include <armadillo></code>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_9400"></a>
|
|
<li>Version 9.400:
|
|
<ul>
|
|
<li>faster <a href="#cov">cov()</a> and <a href="#cor">cor()</a></li>
|
|
<li>added <a href="#as_col_row">.as_col()</a> and <a href="#as_col_row">.as_row()</a></li>
|
|
<li>expanded <a href="#shed">.shed_rows()</a> / <a href="#shed">.shed_cols()</a> / <a href="#shed">.shed_slices()</a> to remove rows/columns/slices specified in a vector</li>
|
|
<li>expanded <a href="#vectorise">vectorise()</a> to handle sparse matrices</li>
|
|
<li>expanded element-wise versions of <a href="#min_and_max">max()</a> and <a href="#min_and_max">min()</a> to handle sparse matrices</li>
|
|
<li>optimised handling of sparse matrix expressions: sparse % (sparse +- scalar) and sparse / (sparse +- scalar)</li>
|
|
<li>
|
|
expanded
|
|
<a href="#eig_sym">eig_sym()</a>,
|
|
<a href="#chol">chol()</a>,
|
|
<a href="#expmat_sym">expmat_sym()</a>,
|
|
<a href="#logmat_sympd">logmat_sympd()</a>,
|
|
<a href="#sqrtmat_sympd">sqrtmat_sympd()</a>,
|
|
<a href="#inv_sympd">inv_sympd()</a>
|
|
to print a warning if the given matrix is not symmetric
|
|
</li>
|
|
<li>more consistent detection of vector expressions</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_9300"></a>
|
|
<li>Version 9.300:
|
|
<ul>
|
|
<li>faster handling of compound complex matrix expressions by <a href="#trace">trace()</a></li>
|
|
<li>more efficient handling of element access for inplace modifications in <a href="#SpMat">sparse matrices</a></li>
|
|
<li>added <a href="#is_sympd">.is_sympd()</a> to check whether a matrix is symmetric/hermitian positive definite</li>
|
|
<li>added <a href="#interp2">interp2()</a> for 2D data interpolation</li>
|
|
<li>added <a href="#misc_fns">expm1()</a> and <a href="#misc_fns">log1p()</a></li>
|
|
<li>expanded <a href="#is_sorted">.is_sorted()</a> with options <code>"strictascend"</code> and <code>"strictdescend"</code></li>
|
|
<li>expanded <a href="#eig_gen">eig_gen()</a> to optionally perform balancing prior to decomposition</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_9200"></a>
|
|
<li>Version 9.200:
|
|
<ul>
|
|
<li>faster handling of symmetric positive definite matrices by <a href="#rcond">rcond()</a></li>
|
|
<li>faster transpose of matrices with size ≥ 512x512</li>
|
|
<li>faster handling of compound sparse matrix expressions by <a href="#accu">accu()</a>, <a href="#diagmat">diagmat()</a>, <a href="#trace">trace()</a></li>
|
|
<li>faster handling of sparse matrices by <a href="#join">join_rows()</a></li>
|
|
<li>added <a href="#trig_fns">sinc()</a></li>
|
|
<li>expanded <a href="#misc_fns">sign()</a> to handle scalar arguments</li>
|
|
<li>expanded <a href="#operators">operators</a> (*, %, +, −) to handle sparse matrices with differing element types (eg. multiplication of complex matrix by real matrix)</li>
|
|
<li>expanded <a href="#conv_to">conv_to()</a> to allow conversion between sparse matrices with differing element types</li>
|
|
<li>expanded <a href="#solve">solve()</a> to optionally allow keeping solutions of systems singular to working precision</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_9100"></a>
|
|
<li>Version 9.100:
|
|
<ul>
|
|
<li>faster handling of symmetric/hermitian positive definite matrices by <a href="#solve">solve()</a></li>
|
|
<li>faster handling of <a href="#inv_sympd">inv_sympd()</a> in compound expressions</li>
|
|
<li>added <a href="#is_symmetric">.is_symmetric()</a></li>
|
|
<li>added <a href="#is_hermitian">.is_hermitian()</a></li>
|
|
<li>expanded <a href="#spsolve">spsolve()</a> to optionally allow keeping solutions of systems singular to working precision</li>
|
|
<li>new <a href="#config_hpp">configuration</a> options <small>ARMA_OPTIMISE_SOLVE_BAND</small> and <small>ARMA_OPTIMISE_SOLVE_SYMPD</small></li>
|
|
<li>smarter use of the element cache in sparse matrices</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_8600"></a>
|
|
<li>Version 8.600:
|
|
<ul>
|
|
<li>added <a href="#hess">hess()</a> for Hessenberg decomposition</li>
|
|
<li>added .row(), .rows(), .col(), .cols() to <a href="#subcube">subcube views</a></li>
|
|
<li>expanded <a href="#shed">.shed_rows()</a> and <a href="#shed">.shed_cols()</a> to handle cubes</li>
|
|
<li>expanded <a href="#insert">.insert_rows()</a> and <a href="#insert">.insert_cols()</a> to handle cubes</li>
|
|
<li>expanded <a href="#subcube">subcube views</a> to allow non-contiguous access to slices</li>
|
|
<li>improved tuning of <a href="#SpMat">sparse matrix</a> element access operators</li>
|
|
<li>faster handling of tridiagonal matrices by <a href="#solve">solve()</a></li>
|
|
<li>faster multiplication of matrices with differing element types when using OpenMP</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_8500"></a>
|
|
<li>Version 8.500:
|
|
<ul>
|
|
<li>faster handling of sparse matrices by <a href="#kron">kron()</a> and <a href="#repmat">repmat()</a></li>
|
|
<li>faster <a href="#trans">transpose</a> of sparse matrices</li>
|
|
<li>faster <a href="#element_access">element access</a> in sparse matrices</li>
|
|
<li>faster <a href="#iterators_spmat">row iterators</a> for sparse matrices</li>
|
|
<li>faster handling of compound expressions by <a href="#trace">trace()</a></li>
|
|
<li>more efficient handling of aliasing in <a href="#submat">submatrix views</a></li>
|
|
<li>expanded <a href="#normalise">normalise()</a> to handle sparse matrices</li>
|
|
<li>expanded <a href="#transform">.transform()</a> and <a href="#for_each">.for_each()</a> to handle sparse matrices</li>
|
|
<li>added <a href="#reverse">reverse()</a> for reversing order of elements</li>
|
|
<li>added <a href="#repelem">repelem()</a> for replicating elements</li>
|
|
<li>added <a href="#roots">roots()</a> for finding the roots of a polynomial</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_8400"></a>
|
|
<li>Version 8.400:
|
|
<ul>
|
|
<li>faster handling of sparse matrices by <a href="#repmat">repmat()</a></li>
|
|
<li>faster <a href="#save_load_mat">loading</a> of CSV files</li>
|
|
<li>expanded <a href="#kron">kron()</a> to handle sparse matrices</li>
|
|
<li>expanded <a href="#index_min_and_index_max_standalone">index_min()</a> and <a href="#index_min_and_index_max_standalone">index_max()</a> to handle cubes</li>
|
|
<li>expanded <a href="#randi">randi()</a>, <a href="#randu">randu()</a>, <a href="#randn">randn()</a>, <a href="#randg">randg()</a> to output single scalars</li>
|
|
<li>added <a href="#iterators_submat">submatrix & subcube iterators</a></li>
|
|
<li>added <a href="#normcdf">normcdf()</a></li>
|
|
<li>added <a href="#mvnrnd">mvnrnd()</a></li>
|
|
<li>added <a href="#chi2rnd">chi2rnd()</a></li>
|
|
<li>added <a href="#wishrnd">wishrnd()</a> and <a href="#iwishrnd">iwishrnd()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_8300"></a>
|
|
<li>Version 8.300:
|
|
<ul>
|
|
<li>faster handling of band matrices by <a href="#solve">solve()</a></li>
|
|
<li>faster handling of band matrices by <a href="#chol">chol()</a></li>
|
|
<li>faster <a href="#randg">randg()</a> when using OpenMP</li>
|
|
<li>added <a href="#normpdf">normpdf()</a></li>
|
|
<li>expanded <a href="#save_load_mat">.save()</a> to allow appending new datasets to existing HDF5 files
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_8200"></a>
|
|
<li>Version 8.200:
|
|
<ul>
|
|
<li>added <a href="#intersect">intersect()</a> for finding common elements in two vectors/matrices</li>
|
|
<li>expanded <a href="#affmul">affmul()</a> to handle non-square matrices</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_8100"></a>
|
|
<li>Version 8.100:
|
|
<ul>
|
|
<li>faster incremental construction of <a href="#SpMat">sparse matrices</a> via element access operators</li>
|
|
<li>faster <a href="#diag">diagonal views</a> in <a href="#SpMat">sparse matrices</a></li>
|
|
<li>expanded <a href="#SpMat">SpMat</a> to save/load sparse matrices in <a href="#save_load_mat">coord format</a></li>
|
|
<li>expanded <a href="#save_load_mat">.save()/.load()</a> to allow specification of datasets within HDF5 files</li>
|
|
<li>added <a href="#affmul">affmul()</a> to simplify application of affine transformations</li>
|
|
<li>warnings and errors are now printed by default to the <i>std::cerr</i> stream</li>
|
|
<li>added <a href="#logging">set_cerr_stream()</a> and <a href="#logging">get_cerr_stream()</a> to replace <i>set_stream_err1()</i>, <i>set_stream_err2()</i>, <i>get_stream_err1()</i>, <i>get_stream_err2()</i></li>
|
|
<li>new <a href="#config_hpp">configuration</a> options ARMA_COUT_STREAM and ARMA_CERR_STREAM</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_7960"></a>
|
|
<li>Version 7.960:
|
|
<ul>
|
|
<li>faster <a href="#randn">randn()</a> when using OpenMP</li>
|
|
<li>faster <a href="#gmm_diag">gmm_diag</a> class, for Gaussian mixture models with diagonal covariance matrices</li>
|
|
<li>added <i>.sum_log_p()</i> to the <a href="#gmm_diag">gmm_diag</a> class</li>
|
|
<li>added <a href="#gmm_full">gmm_full</a> class, for Gaussian mixture models with full covariance matrices</li>
|
|
<li>expanded <a href="#each_slice">.each_slice()</a> to optionally use OpenMP for multi-threaded execution</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_7950"></a>
|
|
<li>Version 7.950:
|
|
<ul>
|
|
<li>expanded <a href="#accu">accu()</a> and <a href="#sum">sum()</a> to use OpenMP for processing expressions with computationally expensive element-wise functions</li>
|
|
<li>expanded <a href="#trimat">trimatu()</a> and <a href="#trimat">trimatl()</a> to allow specification of the diagonal which delineates the boundary of the triangular part</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_7900"></a>
|
|
<li>Version 7.900:
|
|
<ul>
|
|
<li>expanded <a href="#clamp">clamp()</a> to handle cubes</li>
|
|
<li>
|
|
computationally expensive element-wise functions (such as <a href="#misc_fns">exp()</a>, <a href="#misc_fns">log()</a>, <a href="#trig_fns">cos()</a>, etc)
|
|
can now be automatically sped up via <a href="https://en.wikipedia.org/wiki/OpenMP">OpenMP</a>;
|
|
this requires a C++11/C++14 compiler with OpenMP 3.1+ support
|
|
<ul>
|
|
<li>for GCC and clang compilers use the following options to enable both C++11 and OpenMP: <code>-std=c++11 -fopenmp</code></li>
|
|
<li><b>Caveat:</b> when using GCC, use of <code>-march=native</code> in conjunction with <code>-fopenmp</code> may lead to speed regressions on recent processors</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_7800"></a>
|
|
<li>Version 7.800:
|
|
<ul>
|
|
<li>
|
|
changed license to the permissive <a href="https://opensource.org/licenses/Apache-2.0">Apache License 2.0</a>;
|
|
see the <a href="http://arma.sourceforge.net/faq.html#license">Questions page</a> for more info
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_7700"></a>
|
|
<li>Version 7.700:
|
|
<ul>
|
|
<li>added <a href="#polyfit">polyfit()</a> and <a href="#polyval">polyval()</a></li>
|
|
<li>added second form of <a href="#log_det">log_det()</a> to directly return the result as a complex number</li>
|
|
<li>added <a href="#stats_fns">range()</a> to statistics functions</li>
|
|
<li>expanded <a href="#trimat">trimatu()/trimatl()</a> and <a href="#symmat">symmatu()/symmatl()</a> to handle sparse matrices</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_7600"></a>
|
|
<li>Version 7.600:
|
|
<ul>
|
|
<li>more accurate <a href="#eigs_sym">eigs_sym()</a> and <a href="#eigs_gen">eigs_gen()</a></li>
|
|
<li>expanded <a href="#misc_fns">floor()</a>, <a href="#misc_fns">ceil()</a>, <a href="#misc_fns">round()</a>, <a href="#misc_fns">trunc()</a>, <a href="#misc_fns">sign()</a> to handle sparse matrices</li>
|
|
<li>added <a href="#arg">arg()</a>, <a href="#trig_fns">atan2()</a>, <a href="#trig_fns">hypot()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_7500"></a>
|
|
<li>Version 7.500:
|
|
<ul>
|
|
<li>expanded <a href="#qz">qz()</a> to optionally specify ordering of the Schur form</li>
|
|
<li>expanded <a href="#each_slice">.each_slice()</a> to support matrix multiplication</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_7400"></a>
|
|
<li>Version 7.400:
|
|
<ul>
|
|
<li>added <a href="#expmat_sym">expmat_sym()</a>, <a href="#logmat_sympd">logmat_sympd()</a>, <a href="#sqrtmat_sympd">sqrtmat_sympd()</a></li>
|
|
<li>added <a href="#replace">.replace()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_7300"></a>
|
|
<li>Version 7.300:
|
|
<ul>
|
|
<li>added <a href="#index_min_and_index_max_standalone">index_min()</a> and <a href="#index_min_and_index_max_standalone">index_max()</a> standalone functions</li>
|
|
<li>expanded <a href="#submat">.subvec()</a> to accept <a href="#size">size()</a> arguments</li>
|
|
<li>more robust handling of non-square matrices by <a href="#lu">lu()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_7200"></a>
|
|
<li>Version 7.200:
|
|
<ul>
|
|
<li>added <a href="#index_min_and_index_max_member">.index_min()</a> and <a href="#index_min_and_index_max_member">.index_max()</a> member functions</li>
|
|
<li>expanded <a href="#ind2sub">ind2sub()</a> to handle vectors of indices</li>
|
|
<li>expanded <a href="#sub2ind">sub2ind()</a> to handle matrix of subscripts</li>
|
|
<li>expanded <a href="#expmat">expmat()</a>, <a href="#logmat">logmat()</a> and <a href="#sqrtmat">sqrtmat()</a> to optionally return a bool indicating success</li>
|
|
<li>faster handling of compound expressions by <a href="#vectorise">vectorise()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_7100"></a>
|
|
<li>Version 7.100:
|
|
<ul>
|
|
<li>added <a href="#misc_fns">erf()</a>, <a href="#misc_fns">erfc()</a>, <a href="#misc_fns">lgamma()</a></li>
|
|
<li>added <a href="#subcube">.head_slices()</a> and <a href="#subcube">.tail_slices()</a> to subcube views</li>
|
|
<li><a href="#spsolve">spsolve()</a> now requires SuperLU 5.2</li>
|
|
<li><a href="#eigs_sym">eigs_sym()</a>, <a href="#eigs_gen">eigs_gen()</a> and <a href="#svds">svds()</a> now use a built-in reimplementation of ARPACK for real (non-complex) matrices; contributed by Yixuan Qiu</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_6700"></a>
|
|
<li>Version 6.700:
|
|
<ul>
|
|
<li>added <a href="#trapz">trapz()</a> for numerical integration</li>
|
|
<li>added <a href="#logmat">logmat()</a> for calculating the matrix logarithm</li>
|
|
<li>added <a href="#regspace">regspace()</a> for generating vectors with regularly spaced elements</li>
|
|
<li>added <a href="#logspace">logspace()</a> for generating vectors with logarithmically spaced elements</li>
|
|
<li>added <a href="#approx_equal">approx_equal()</a> for determining approximate equality</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_6600"></a>
|
|
<li>Version 6.600:
|
|
<ul>
|
|
<li>expanded <a href="#sum">sum()</a>, <a href="#stats_fns">mean()</a>, <a href="#min_and_max">min()</a>, <a href="#min_and_max">max()</a> to handle cubes</li>
|
|
<li>expanded <a href="#Cube">Cube</a> class to handle arbitrarily sized empty cubes (eg. 0x5x2)</li>
|
|
<li>added <a href="#shift">shift()</a> for circular shifts of elements</li>
|
|
<li>added <a href="#sqrtmat">sqrtmat()</a> for finding the square root of a matrix</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_6500"></a>
|
|
<li>Version 6.500:
|
|
<ul>
|
|
<li>added <a href="#conv2">conv2()</a> for 2D convolution</li>
|
|
<li>added stand-alone <a href="#kmeans">kmeans()</a> function for clustering data</li>
|
|
<li>added <a href="#misc_fns">trunc()</a></li>
|
|
<li>extended <a href="#conv">conv()</a> to optionally provide central convolution</li>
|
|
<li>faster handling of multiply-and-accumulate by <a href="#accu">accu()</a> when using Intel MKL, ATLAS or OpenBLAS</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_6400"></a>
|
|
<li>Version 6.400:
|
|
<ul>
|
|
<li>expanded <a href="#each_colrow">each_col()</a>, <a href="#each_colrow">each_row()</a> and <a href="#each_slice">each_slice()</a> to handle C++11 lambda functions</li>
|
|
<li>added <a href="#ind2sub">ind2sub()</a> and <a href="#sub2ind">sub2ind()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_6300"></a>
|
|
<li>Version 6.300:
|
|
<ul>
|
|
<li>expanded <a href="#solve">solve()</a> to find approximate solutions for rank-deficient systems</li>
|
|
<li>faster handling of <a href="#submat">non-contiguous submatrix views</a> in compound expressions</li>
|
|
<li>added <a href="#for_each">.for_each()</a> to <i>Mat</i>, <i>Row</i>, <i>Col</i>, <i>Cube</i> and <i>field</i> classes</li>
|
|
<li>added <a href="#rcond">rcond()</a> for estimating the reciprocal condition number</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_6200"></a>
|
|
<li>Version 6.200:
|
|
<ul>
|
|
<li>expanded <a href="#diagmat">diagmat()</a> to handle non-square matrices and arbitrary diagonals</li>
|
|
<li>expanded <a href="#trace">trace()</a> to handle non-square matrices</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_6100"></a>
|
|
<li>Version 6.100:
|
|
<ul>
|
|
<li>faster <a href="#norm">norm()</a> and <a href="#normalise">normalise()</a> when using Intel MKL, ATLAS or OpenBLAS</li>
|
|
<li>added Schur decomposition: <a href="#schur">schur()</a></li>
|
|
<li>stricter handling of matrix objects by <a href="#hist">hist()</a> and <a href="#histc">histc()</a></li>
|
|
<li><a href="#adv_constructors_mat">advanced constructors</a> for using auxiliary memory by Mat, Col, Row and Cube now have the default of <i>strict = false</i></li>
|
|
<li><a href="#Cube">Cube</a> class now delays allocation of <a href="#subcube">.slice()</a> related structures until needed</li>
|
|
<li>expanded <a href="#join_slices">join_slices()</a> to handle joining cubes with matrices</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_5600"></a>
|
|
<li>Version 5.600:
|
|
<ul>
|
|
<li>added <a href="#each_slice">.each_slice()</a> for matrix operations applied to each slice of a cube</li>
|
|
<li>expanded <a href="#each_colrow">.each_col()</a> and <a href="#each_colrow">.each_row()</a> to handle out-of-place operations</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_5500"></a>
|
|
<li>Version 5.500:
|
|
<ul>
|
|
<li>expanded object constructors and generators to handle <a href="#size">size()</a> based specification of dimensions</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_5400"></a>
|
|
<li>Version 5.400:
|
|
<ul>
|
|
<li>added <a href="#find_unique">find_unique()</a> for finding indices of unique values</li>
|
|
<li>added <a href="#diff">diff()</a> for calculating differences between consecutive elements</li>
|
|
<li>added <a href="#cumprod">cumprod()</a> for calculating cumulative product</li>
|
|
<li>added <a href="#null">null()</a> for finding the orthonormal basis of null space</li>
|
|
<li>expanded <a href="#interp1">interp1()</a> to handle repeated locations</li>
|
|
<li>expanded <a href="#unique">unique()</a> to handle complex numbers</li>
|
|
<li>faster <a href="#flip">flipud()</a></li>
|
|
<li>faster row-wise <a href="#cumsum">cumsum()</a></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_5300"></a>
|
|
<li>Version 5.300:
|
|
<ul>
|
|
<li>added generalised Schur decomposition: <a href="#qz">qz()</a></li>
|
|
<li>added <a href="#has_inf">.has_inf()</a> and <a href="#has_nan">.has_nan()</a></li>
|
|
<li>expanded <a href="#interp1">interp1()</a> to handle out-of-domain locations</li>
|
|
<li>expanded <a href="#SpMat">sparse matrix</a> class with <a href="#set_imag">.set_imag()</a> and <a href="#set_imag">.set_real()</a></li>
|
|
<li>expanded <a href="#imag_real">imag()</a>, <a href="#imag_real">real()</a> and <a href="#conj">conj()</a> to handle sparse matrices</li>
|
|
<li>expanded <a href="#diagmat">diagmat()</a>, <a href="#reshape">reshape()</a> and <a href="#resize">resize()</a> to handle sparse matrices</li>
|
|
<li>faster sparse <a href="#sum">sum()</a></li>
|
|
<li>faster row-wise <a href="#sum">sum()</a>, <a href="#stats_fns">mean()</a>, <a href="#min_and_max">min()</a>, <a href="#min_and_max">max()</a></li>
|
|
<li>updated <a href="#constants">physical constants</a> to NIST 2014 CODATA values</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_5200"></a>
|
|
<li>Version 5.200:
|
|
<ul>
|
|
<li>added <a href="#orth">orth()</a> for finding the orthonormal basis of the range space of a matrix</li>
|
|
<li>expanded <a href="#element_initialisation">element initialisation</a> to handle nested initialiser lists (C++11)</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_5100"></a>
|
|
<li>Version 5.100:
|
|
<ul>
|
|
<li>added <a href="#interp1">interp1()</a> for 1D interpolation</li>
|
|
<li>added <a href="#is_sorted">.is_sorted()</a> for checking whether a vector or matrix has sorted elements</li>
|
|
<li>updated <a href="#constants">physical constants</a> to NIST 2010 CODATA values</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_5000"></a>
|
|
<li>Version 5.000:
|
|
<ul>
|
|
<li>added <a href="#spsolve">spsolve()</a> for solving sparse systems of linear equations</li>
|
|
<li>added <a href="#svds">svds()</a> for singular value decomposition of sparse matrices</li>
|
|
<li>added <a href="#nonzeros">nonzeros()</a> for extracting non-zero values from matrices</li>
|
|
<li>added handling of <a href="#diag">diagonal views</a> by sparse matrices
|
|
<li>expanded <a href="#repmat">repmat()</a> to handle sparse matrices
|
|
<li>expanded <a href="#join">join_rows()</a> and <a href="#join">join_cols()</a> to handle sparse matrices
|
|
<li><a href="#sort_index">sort_index()</a> and <a href="#sort_index">stable_sort_index()</a> have been placed in the delayed operations framework for increased efficiency
|
|
<li>use of <a href="#uword">64 bit integers</a> is automatically enabled when using a C++11 compiler</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_4650"></a>
|
|
<li>Version 4.650:
|
|
<ul>
|
|
<li>added <a href="#randg">randg()</a> for generating random values from gamma distributions (C++11 only)</li>
|
|
<li>added <i>.head_rows()</i> and <i>.tail_rows()</i> to <a href="#submat">submatrix views</a></li>
|
|
<li>added <i>.head_cols()</i> and <i>.tail_cols()</i> to <a href="#submat">submatrix views</a></li>
|
|
<li>expanded <a href="#eigs_sym">eigs_sym()</a> to optionally calculate eigenvalues with smallest/largest algebraic values</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_4600"></a>
|
|
<li>Version 4.600:
|
|
<ul>
|
|
<li>added <i>.head()</i> and <i>.tail()</i> to <a href="#submat">submatrix views</a></li>
|
|
<li>faster matrix transposes within compound expressions</li>
|
|
<li>faster in-place matrix multiplication</li>
|
|
<li>faster <a href="#accu">accu()</a> and <a href="#norm">norm()</a> when compiling with <i>-O3 -ffast-math -march=native</i> (gcc and clang)
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_4550"></a>
|
|
<li>Version 4.550:
|
|
<ul>
|
|
<li>added matrix exponential function: <a href="#expmat">expmat()</a></li>
|
|
<li>faster <i>.log_p()</i> and <i>.avg_log_p()</i> functions in the <a href="#gmm_diag">gmm_diag</a> class when compiling with OpenMP enabled</li>
|
|
<li>faster handling of in-place addition/subtraction of expressions with an outer product
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_4500"></a>
|
|
<li>Version 4.500:
|
|
<ul>
|
|
<li>faster handling of complex vectors by <a href="#norm">norm()</a></li>
|
|
<li>expanded <a href="#chol">chol()</a> to optionally specify output matrix as upper or lower triangular</li>
|
|
<li>better handling of non-finite values when <a href="#save_load_mat">saving</a> matrices as text files</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_4450"></a>
|
|
<li>Version 4.450:
|
|
<ul>
|
|
<li>faster handling of matrix transposes within compound expressions</li>
|
|
<li>expanded <a href="#symmat">symmatu()/symmatl()</a> to optionally disable taking the complex conjugate of elements</li>
|
|
<li>expanded <a href="#sort_index">sort_index()</a> to handle complex vectors</li>
|
|
<li>expanded the <a href="#gmm_diag">gmm_diag</a> class with functions to generate random samples</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_4400"></a>
|
|
<li>Version 4.400:
|
|
<ul>
|
|
<li>faster handling of subvectors by <a href="#dot">dot()</a></li>
|
|
<li>faster handling of aliasing by <a href="#submat">submatrix</a> views</li>
|
|
<li>added <a href="#clamp">clamp()</a> for clamping values to be between lower and upper limits</li>
|
|
<li>added <a href="#gmm_diag">gmm_diag</a> class for statistical modelling of data using Gaussian Mixture Models</li>
|
|
<li>expanded <a href="#batch_constructors_sp_mat">batch insertion constructors</a> for sparse matrices to add values at repeated locations</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_4320"></a>
|
|
<li>Version 4.320:
|
|
<ul>
|
|
<li>expanded <a href="#eigs_sym">eigs_sym()</a> and <a href="#eigs_gen">eigs_gen()</a> to use an optional tolerance parameter</li>
|
|
<li>expanded <a href="#eig_sym">eig_sym()</a> to automatically fall back to standard decomposition method if divide-and-conquer fails</li>
|
|
<li>cmake-based installer enables use of C++11 random number generator when using gcc 4.8.3+ in C++11 mode</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_4300"></a>
|
|
<li>Version 4.300:
|
|
<ul>
|
|
<li>added <a href="#find_finite">find_finite()</a> and <a href="#find_nonfinite">find_nonfinite()</a></li>
|
|
<li>expressions <i>X=<a href="#inv">inv</a>(A)*B*C</i> and <i>X=A<a href="#i_member">.i()</a>*B*C</i> are automatically converted to <i>X=<a href="#solve">solve</a>(A,B*C)</i></li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_4200"></a>
|
|
<li>Version 4.200:
|
|
<ul>
|
|
<li>faster transpose of sparse matrices</li>
|
|
<li>more efficient handling of aliasing during matrix multiplication</li>
|
|
<li>faster <a href="#inv">inverse</a> of matrices marked as diagonal</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_4100"></a>
|
|
<li>Version 4.100:
|
|
<ul>
|
|
<li>added <a href="#normalise">normalise()</a> for normalising vectors to unit <i>p</i>-norm</li>
|
|
<li>extended the <a href="#field">field class</a> to handle 3D layout</li>
|
|
<li>extended <a href="#eigs_sym">eigs_sym()</a> and <a href="#eigs_gen">eigs_gen()</a> to obtain eigenvalues of various forms (eg. largest or smallest magnitude)</li>
|
|
<li>automatic SIMD vectorisation of elementary expressions (eg. matrix addition) when using Clang 3.4+ with -O3 optimisation</li>
|
|
<li>faster handling of sparse submatrix views</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_4000"></a>
|
|
<li>Version 4.000:
|
|
<ul>
|
|
<li>added eigen decompositions of sparse matrices: <a href="#eigs_sym">eigs_sym()</a> and <a href="#eigs_gen">eigs_gen()</a></li>
|
|
<li>added eigen decomposition for pair of matrices: <a href="#eig_pair">eig_pair()</a></li>
|
|
<li>added simpler forms of <a href="#eig_gen">eig_gen()</a></li>
|
|
<li>added condition number of matrices: <a href="#cond">cond()</a></li>
|
|
<li>expanded <a href="#find">find()</a> to handle cubes</li>
|
|
<li>expanded <a href="#subcube">subcube views</a> to access elements specified in a vector</li>
|
|
<li>template argument for <a href="#running_stat_vec">running_stat_vec</a> expanded to accept vector types</li>
|
|
<li>more robust fast <a href="#inv">inverse</a> of 4x4 matrices</li>
|
|
<li>faster divide-and-conquer decompositions are now used by default for
|
|
<a href="#eig_sym">eig_sym()</a>,
|
|
<a href="#pinv">pinv()</a>,
|
|
<a href="#princomp">princomp()</a>,
|
|
<a href="#rank">rank()</a>,
|
|
<a href="#svd">svd()</a>,
|
|
<a href="#svd_econ">svd_econ()</a>
|
|
</li>
|
|
<li>
|
|
the form <i>inv(sympd(X))</i> no longer assumes that <i>X</i> is positive definite; use <a href="#inv_sympd">inv_sympd()</a> instead
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_3930"></a>
|
|
<li>Version 3.930:
|
|
<ul>
|
|
<li>added <a href="#size">size()</a> based specifications of <a href="#submat">submatrix view</a> sizes</li>
|
|
<li>added element-wise variants of <a href="#min_and_max">min()</a> and <a href="#min_and_max">max()</a></li>
|
|
<li>added divide-and-conquer variant of <a href="#svd_econ">svd_econ()</a></li>
|
|
<li>added divide-and-conquer variant of <a href="#pinv">pinv()</a></li>
|
|
<li>added <a href="#randi">randi()</a> for generating matrices with random integer values</li>
|
|
<li>added <a href="#inplace_trans">inplace_trans()</a> for memory efficient in-place transposes</li>
|
|
<li>added more intuitive specification of sort direction in <a href="#sort">sort()</a> and <a href="#sort_index">sort_index()</a></li>
|
|
<li>added 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="version_3920"></a>
|
|
<li>Version 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>added signum function: <a href="#misc_fns">sign()</a></li>
|
|
<li>added move constructors when using C++11</li>
|
|
<li>added 2D fast Fourier transform: <a href="#fft2">fft2()</a></li>
|
|
<li>added <a href="#subcube">.tube()</a> for easier extraction of vectors and subcubes from cubes</li>
|
|
<li>added 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="version_3910"></a>
|
|
<li>Version 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>added <a href="#vectorise">vectorise()</a> for reshaping matrices into vectors</li>
|
|
<li>added <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="version_3900"></a>
|
|
<li>Version 3.900:
|
|
<ul>
|
|
<li>added automatic SSE2 vectorisation of elementary expressions (eg. matrix addition) when using GCC 4.7+ with -O3 optimisation</li>
|
|
<li>faster <a href="#stats_fns">median()</a></li>
|
|
<li>faster handling of compound expressions with transposes of <a href="#submat">submatrix</a> rows</li>
|
|
<li>faster handling of compound expressions with transposes of complex vectors</li>
|
|
<li>added support for <a href="#save_load_mat">saving & loading</a> of <a href="#Cube">cubes</a> in HDF5 format</li>
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_3820"></a>
|
|
<li>Version 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="version_3810"></a>
|
|
<li>Version 3.810:
|
|
<ul>
|
|
<li>added fast Fourier transform: <a href="#fft">fft()</a></li>
|
|
<li>added handling of <a href="#imbue">.imbue()</a> and <a href="#transform">.transform()</a> by submatrices and subcubes</li>
|
|
<li>added <a href="#batch_constructors_sp_mat">batch insertion constructors</a> for sparse matrices
|
|
</ul>
|
|
</li>
|
|
<br>
|
|
<a name="version_3800"></a>
|
|
<li>Version 3.800:
|
|
<ul>
|
|
<li>added <a href="#imbue">.imbue()</a> for filling a matrix/cube with values provided by a functor or lambda expression</li>
|
|
<li>added <a href="#swap">.swap()</a> for swapping contents with another matrix</li>
|
|
<li>added <a href="#transform">.transform()</a> for transforming a matrix/cube using a functor or lambda expression</li>
|
|
<li>added <a href="#misc_fns">round()</a> for rounding matrix elements towards nearest integer</li>
|
|
<li>faster <a href="#find">find()</a></li>
|
|
<li>changed license to the <a href="https://www.mozilla.org/MPL/2.0/">Mozilla Public License 2.0</a></li>
|
|
</ul>
|
|
<br>
|
|
</li>
|
|
<a name="version_36"></a>
|
|
<li>Version 3.6:
|
|
<ul>
|
|
<li>faster handling of compound expressions with submatrices and subcubes</li>
|
|
<li>faster <a href="#trace">trace()</a></li>
|
|
<li>added support for loading matrices as text files with <i>NaN</i> and <i>Inf</i> elements</li>
|
|
<li>added <a href="#sort_index">stable_sort_index()</a>, which preserves the relative order of elements with equivalent values</li>
|
|
<li>added 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>added saving and loading of sparse matrices in <i>arma_binary</i> format</li>
|
|
</ul>
|
|
<br>
|
|
</li>
|
|
<a name="version_34"></a>
|
|
<li>Version 3.4:
|
|
<ul>
|
|
<li>added economical QR decomposition: <a href="#qr_econ">qr_econ()</a></li>
|
|
<li>added <a href="#each_colrow">.each_col() & .each_row()</a> for vector operations applied to each column or row of a matrix</li>
|
|
<li>added preliminary support for <a href="#SpMat">sparse matrices</a></li>
|
|
<li>added 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="version_32"></a>
|
|
<li>Version 3.2:
|
|
<ul>
|
|
<li>added <a href="#unique">unique()</a>, for finding unique elements of a matrix</li>
|
|
<li>added <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="version_30"></a>
|
|
<li>Version 3.0:
|
|
<ul>
|
|
<li>added shorthand for inverse: <a href="#i_member">.i()</a></li>
|
|
<li>added <a href="#constants">datum</a> class</li>
|
|
<li>added <a href="#hist">hist()</a> and <a href="#histc">histc()</a></li>
|
|
<li>added 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>
|
|
<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">randu()</a> and <a href="#randn">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="version_24"></a>
|
|
<li>Version 2.4:
|
|
<ul>
|
|
<li>added shorter forms of transposes: <a href="#t_st_members">.t()</a> and <a href="#t_st_members">.st()</a></li>
|
|
<li>added <a href="#resize_member">.resize()</a> and <a href="#resize">resize()</a></li>
|
|
<li>added optional use of 64 bit indices (allowing matrices to have more than 4 billion elements), enabled via ARMA_64BIT_WORD in <i>include/armadillo_bits/config.hpp</i></li>
|
|
<li>added experimental support for C++11 initialiser lists, enabled via ARMA_USE_CXX11 in <i>include/armadillo_bits/config.hpp</i></li>
|
|
<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>Version 2.2:
|
|
<ul>
|
|
<li>added <a href="#svd_econ">svd_econ()</a></li>
|
|
<li>added <a href="#toeplitz">circ_toeplitz()</a></li>
|
|
<li>added <a href="#is_vec">.is_colvec()</a> and <a href="#is_vec">.is_rowvec()</a></li>
|
|
</ul>
|
|
<br>
|
|
<li>Version 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>added <a href="#syl">syl()</a>, for solving Sylvester's equation</li>
|
|
<li>added <a href="#trans">strans()</a>, for transposing a complex matrix without taking the complex conjugate</li>
|
|
<li>added <a href="#symmat">symmatu()</a> and <a href="#symmat">symmatl()</a></li>
|
|
<li>added 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>added handling of arbitrarily sized empty matrices (eg. 5x0)</li>
|
|
<li>added .count() member function in <a href="#running_stat">running_stat</a> and <a href="#running_stat_vec">running_stat_vec</a></li>
|
|
<li>added <a href="#save_load_mat">loading & saving</a> of matrices as CSV text files</li>
|
|
<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>Version 1.2:
|
|
<ul>
|
|
<li>added <a href="#min_and_max_member">.min() & .max()</a> member functions of Mat and Cube</li>
|
|
<li>added <a href="#misc_fns">floor()</a> and <a href="#misc_fns">ceil()</a></li>
|
|
<li>added representation of “not a number”: math::nan()</li>
|
|
<li>added representation of infinity: math::inf()</li>
|
|
<li><a href="#in_range">.in_range()</a> expanded to 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>added interpretation of matrices as triangular through <a href="#trimat">trimatu() / trimatl()</a></li>
|
|
<li>added 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>added ability to change the stream used for <a href="#logging">logging</a> of errors and warnings</li>
|
|
<li>added ability to <a href="#save_load_mat">save/load matrices</a> in raw binary format</li>
|
|
<li>added 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">randu()</a>;
|
|
this has been done to avoid confusion with <a href="https://cplusplus.com/reference/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>
|
|
</ul>
|
|
|
|
<!-- END CONTENT -->
|
|
|
|
|
|
<hr>
|
|
<br>
|
|
<br>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|