Mercurial > hg > segmenter-vamp-plugin

comparison armadillo-2.4.4/docs/index.html @ 0:8b6102e2a9b0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Armadillo Library
author maxzanoni76 <max.zanoni@eecs.qmul.ac.uk>
date Wed, 11 Apr 2012 09:27:06 +0100
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:8b6102e2a9b0
1 <!-- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -->
2 <html>
3 <head>
4 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type">
5 <title>Armadillo: C++ linear algebra library</title>
6 <link type="text/css" rel="stylesheet" href="style.css">
7 <link rel="icon" href="armadillo_icon.png" type="image/png">
8 </head>
9 <body>
10 <center>
11 <table style="text-align: left; width: 80%; margin-left: auto; margin-right: auto;" border="0" cellpadding="0" cellspacing="0">
12 <tbody>
13 <tr>
14 <td style="vertical-align: top;">
15
16 <table style="text-align: left; width: 100%;" border="0" cellpadding="0" cellspacing="0">
17 <tbody>
18 <tr>
19 <td style="text-align: left; vertical-align: top;">
20 <font size=+2><b>Reference for Armadillo 2.4.4</b></font>
21 <br>
22 <font size=-1><b>(Loco Lounge Lizard)</b></font>
23 </td>
24 <td style="text-align: right; vertical-align: top;">
25 <b><a href="http://arma.sourceforge.net">to Armadillo home page</a></b>
26 <br>
27 <b><a href="http://nicta.com.au">to NICTA home page</a></b>
28 </td>
29 </tr>
30 </tbody>
31 </table>
32 <hr>
33 <br>
34 <br>
35 <a name="top"></a>
36 <a style="display:scroll; position:fixed; bottom:5px; right:5px;" href="#top"><font size=-1>[top]</font></a>
37
38
39 <!-- BEGIN CONTENT -->
40
41
42 <b>Preamble</b>
43 <br>
44 <br>
45 <table border="0" cellpadding="0" cellspacing="0">
46 <tbody>
47 <tr>
48 <td style="text-align: left; vertical-align: top; width: 50%;">
49 <ul>
50 <li>
51 To aid the conversion of Matlab/Octave programs,
52 there is a <a href="#syntax">syntax conversion table</a>
53 </li>
54 <br>
55 <li>
56 First time users may want to have a look at a short <a href="#example_prog">example program</a>
57 </li>
58 <br>
59 <li>
60 If you find any bugs or regressions, please <a href="http://arma.sourceforge.net/faq.html">report them</a>
61 </li>
62 <br>
63 <li>
64 <b>Caveat:</b> the API for version 2.x has <a href="#api_changes">changes &amp; additions</a> compared to version 1.2;
65 see also the list of <a href="#deprecated">deprecated</a> functionality
66 </li>
67 </ul>
68 </td>
69 <td>
70 &nbsp;
71 </td>
72 <td class="line" style="vertical-align: top;">
73 <br>
74 </td>
75 <td style="text-align: left; vertical-align: top; width: 45%;">
76 <ul>
77 <li>
78 If you use Armadillo in your research and/or software,
79 we would appreciate a citation to the following tech report:
80 <br>
81 <br>
82 <font size=-1>
83 Conrad Sanderson.
84 <br>
85 <i><a href="armadillo_nicta_2010.pdf">Armadillo: An Open Source C++ Linear Algebra Library for Fast Prototyping and Computationally Intensive Experiments</a></i>.
86 <br>
87 Technical Report, NICTA, 2010.
88 </font>
89 </li>
90 </ul>
91 </td>
92 </tr>
93 </tbody>
94 </table>
95
96 <br>
97 <br>
98
99 <b>Matrix, Vector, Cube and Field Classes</b>
100 <ul>
101 <a href="#Mat">Mat&lt;<i>type</i>&gt;, mat and cx_mat</a>&nbsp;&middot;
102 <a href="#Col">Col&lt;<i>type</i>&gt;, colvec and vec</a>&nbsp;&middot;
103 <a href="#Row">Row&lt;<i>type</i>&gt;, rowvec</a>&nbsp;&middot;
104 <a href="#Cube">Cube&lt;<i>type</i>&gt;, cube</a>&nbsp;&middot;
105 <a href="#field">field&lt;<i>object&nbsp;type</i>&gt;</a>
106 </ul>
107 <br>
108
109 <b>Member Functions &amp; Variables</b>
110 <ul>
111 <a href="#attributes">attributes</a>&nbsp;&middot;
112 <a href="#colptr">colptr</a>&nbsp;&middot;
113 <a href="#copy_size">copy_size</a>&nbsp;&middot;
114 <a href="#diag">diag</a>&nbsp;&middot;
115 <a href="#element_access">element&nbsp;access</a>&nbsp;&middot;
116 <a href="#element_initialisation">element&nbsp;initialisation</a>&nbsp;&middot;
117 <a href="#eye_member">eye</a>&nbsp;&middot;
118 <a href="#fill">fill</a>&nbsp;&middot;
119 <a href="#insert">insert rows/cols/slices</a>&nbsp;&middot;
120 <a href="#in_range">in_range</a>&nbsp;&middot;
121 <a href="#is_empty">is_empty</a>&nbsp;&middot;
122 <a href="#is_finite">is_finite</a>&nbsp;&middot;
123 <a href="#is_square">is_square</a>&nbsp;&middot;
124 <a href="#is_vec">is_vec</a>&nbsp;&middot;
125 <a href="#iterators_mat">iterators (matrices)</a>&nbsp;&middot;
126 <a href="#iterators_cube">iterators (cubes)</a>&nbsp;&middot;
127 <a href="#memptr">memptr</a>&nbsp;&middot;
128 <a href="#min_and_max_member">min/max</a>&nbsp;&middot;
129 <a href="#ones_member">ones</a>&nbsp;&middot;
130 <a href="#operators">operators</a>&nbsp;&middot;
131 <a href="#print">print</a>&nbsp;&middot;
132 <a href="#raw_print">raw_print</a>&nbsp;&middot;
133 <a href="#randu_randn_member">randu/randn</a>&nbsp;&middot;
134 <a href="#reset">reset</a>&nbsp;&middot;
135 <a href="#reshape_member">reshape</a>&nbsp;&middot;
136 <a href="#resize_member">resize</a>&nbsp;&middot;
137 <a href="#save_load_mat">save/load (matrices &amp; cubes)</a>&nbsp;&middot;
138 <a href="#save_load_field">save/load (fields)</a>&nbsp;&middot;
139 <a href="#set_imag">set_imag/real</a>&nbsp;&middot;
140 <a href="#set_size">set_size</a>&nbsp;&middot;
141 <a href="#shed">shed rows/cols/slices</a>&nbsp;&middot;
142 <a href="#stl_container_fns">STL container functions</a>&nbsp;&middot;
143 <a href="#submat">submatrix&nbsp;views</a>&nbsp;&middot;
144 <a href="#subcube">subcube&nbsp;views</a>&nbsp;&middot;
145 <a href="#subfield">subfield&nbsp;views</a>&nbsp;&middot;
146 <a href="#swap_rows">swap_rows/cols</a>&nbsp;&middot;
147 <a href="#t_st_members">t/st (transpose)</a>&nbsp;&middot;
148 <a href="#zeros_member">zeros</a>
149 </ul>
150 <br>
151
152 <b>Other Classes</b>
153 <ul>
154 <a href="#running_stat">running_stat&lt;<i>type</i>&gt;</a>&nbsp;&middot;
155 <a href="#running_stat_vec">running_stat_vec&lt;<i>type</i>&gt;</a>&nbsp;&middot;
156 <a href="#wall_clock">wall_clock</a>
157 </ul>
158 <br>
159
160 <b>Generated Vectors/Matrices/Cubes</b>
161 <ul>
162 <a href="#eye_standalone">eye</a>&nbsp;&middot;
163 <a href="#linspace">linspace</a>&nbsp;&middot;
164 <a href="#ones_standalone">ones</a>&nbsp;&middot;
165 <a href="#randu_randn_standalone">randu/randn</a>&nbsp;&middot;
166 <a href="#repmat">repmat</a>&nbsp;&middot;
167 <a href="#toeplitz">toeplitz/toeplitz_circ</a>&nbsp;&middot;
168 <a href="#zeros_standalone">zeros</a>
169 </ul>
170 <br>
171
172 <b>Functions Individually Applied to Each Element of a Matrix/Cube</b>
173 <ul>
174 <a href="#abs">abs</a>&nbsp;&middot;
175 <a href="#eps">eps</a>&nbsp;&middot;
176 <a href="#misc_fns">misc functions (exp, log, pow, sqrt, ...)</a>&nbsp;&middot;
177 <a href="#trig_fns">trigonometric functions (cos, sin, ...)</a>
178 </ul>
179 <br>
180
181 <b>Scalar Valued Functions of Vectors/Matrices/Cubes</b>
182 <ul>
183 <a href="#accu">accu</a>&nbsp;&middot;
184 <a href="#as_scalar">as_scalar</a>&nbsp;&middot;
185 <a href="#det">det</a>&nbsp;&middot;
186 <a href="#dot">dot/cdot/norm_dot</a>&nbsp;&middot;
187 <a href="#log_det">log_det</a>&nbsp;&middot;
188 <a href="#norm">norm</a>&nbsp;&middot;
189 <a href="#rank">rank</a>&nbsp;&middot;
190 <a href="#trace">trace</a>
191 </ul>
192 <br>
193
194 <b>Scalar/Vector Valued Functions of Vectors/Matrices</b>
195 <ul>
196 <a href="#diagvec">diagvec</a>&nbsp;&middot;
197 <a href="#min_and_max">min/max</a>&nbsp;&middot;
198 <a href="#prod">prod</a>&nbsp;&middot;
199 <a href="#sum">sum</a>&nbsp;&middot;
200 <a href="#stats_fns">statistics (mean, stddev, ...)</a>
201 </ul>
202 <br>
203
204 <b>Vector/Matrix/Cube Valued Functions of Vectors/Matrices/Cubes</b>
205 <ul>
206 <a href="#conv">conv</a>&nbsp;&middot;
207 <a href="#conv_to">conv_to</a>&nbsp;&middot;
208 <a href="#conj">conj</a>&nbsp;&middot;
209 <a href="#cor">cor</a>&nbsp;&middot;
210 <a href="#cov">cov</a>&nbsp;&middot;
211 <a href="#cross">cross</a>&nbsp;&middot;
212 <a href="#cumsum">cumsum</a>&nbsp;&middot;
213 <a href="#diagmat">diagmat</a>&nbsp;&middot;
214 <a href="#find">find</a>&nbsp;&middot;
215 <a href="#flip">fliplr/flipud</a>&nbsp;&middot;
216 <a href="#imag_real">imag/real</a>&nbsp;&middot;
217 <a href="#join">join&nbsp;rows/cols/slices</a>&nbsp;&middot;
218 <a href="#kron">kron</a>&nbsp;&middot;
219 <a href="#reshape">reshape</a>&nbsp;&middot;
220 <a href="#resize">resize</a>&nbsp;&middot;
221 <a href="#shuffle">shuffle</a>&nbsp;&middot;
222 <a href="#sort">sort</a>&nbsp;&middot;
223 <a href="#sort_index">sort_index</a>&nbsp;&middot;
224 <a href="#symmat">symmatu/symmatl</a>&nbsp;&middot;
225 <a href="#strans">strans</a>&nbsp;&middot;
226 <a href="#trans">trans</a>&nbsp;&middot;
227 <a href="#trimat">trimatu/trimatl</a>
228 </ul>
229 <br>
230
231 <b>Decompositions, Inverses and Equation Solvers</b>
232 <ul>
233 <a href="#chol">chol</a>&nbsp;&middot;
234 <a href="#eig_sym">eig_sym</a>&nbsp;&middot;
235 <a href="#eig_gen">eig_gen</a>&nbsp;&middot;
236 <a href="#inv">inv</a>&nbsp;&middot;
237 <a href="#lu">lu</a>&nbsp;&middot;
238 <a href="#pinv">pinv</a>&nbsp;&middot;
239 <a href="#princomp">princomp</a>&nbsp;&middot;
240 <a href="#qr">qr</a>&nbsp;&middot;
241 <a href="#solve">solve</a>&nbsp;&middot;
242 <a href="#svd">svd</a>&nbsp;&middot;
243 <a href="#svd_econ">svd_econ</a>&nbsp;&middot;
244 <a href="#syl">syl</a>
245 </ul>
246 <br>
247
248 <b>Miscellaneous</b>
249 <ul>
250 <a href="#is_finite_standalone">is_finite()</a>&nbsp;&middot;
251 <a href="#logging">logging of errors/warnings</a>&nbsp;&middot;
252 <a href="#math_constants">math constants (pi, ...)</a>&nbsp;&middot;
253 <a href="#phys_constants">physical constants (speed of light, ...)</a>&nbsp;&middot;
254 <a href="#log_add">log_add</a>&nbsp;&middot;
255 <a href="#uword">uword/sword</a>&nbsp;&middot;
256 <a href="#cx_float_double">cx_float/cx_double</a>&nbsp;&middot;
257 <a href="#syntax">Matlab/Armadillo syntax differences</a>&nbsp;&middot;
258 <a href="#example_prog">example program</a>&nbsp;&middot;
259 <!--<a href="#catching_exceptions">catching exceptions</a>&nbsp;&middot;-->
260 <a href="#api_changes">API changes</a>
261 </ul>
262 <br>
263
264 <br>
265 <br>
266 <hr class="greyline">
267 <hr class="greyline">
268 <br>
269 <br>
270 <font size=+1><b>Matrix, Vector, Cube and Field Classes</b></font>
271 <br>
272 <br>
273 <hr class="greyline">
274 <br>
275
276 <a name="Mat"></a><b>Mat&lt;</b><i>type</i><b>&gt;</b>
277 <br><b>mat</b>
278 <br><b>cx_mat</b>
279 <ul>
280 <li>
281 The root template matrix class is <b>Mat&lt;</b><i>type</i><b>&gt;</b>, where <i>type</i> can be one of:
282 <i>char</i>, <i>int</i>, <i>float</i>, <i>double</i>, <i>std::complex&lt;double&gt;</i>, etc.
283 </li>
284 <br>
285 <li>
286 For convenience the following typedefs have been defined:
287 <ul>
288 <table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
289 <tbody>
290 <tr>
291 <td style="vertical-align: top;">
292 umat
293 </td>
294 <td style="vertical-align: top;">
295 &nbsp;=&nbsp;
296 </td>
297 <td style="vertical-align: top;">
298 Mat&lt;<a href="#uword">uword</a>&gt;
299 </td>
300 </tr>
301 <tr>
302 <td style="vertical-align: top;">
303 imat
304 </td>
305 <td style="vertical-align: top;">
306 &nbsp;=&nbsp;
307 </td>
308 <td style="vertical-align: top;">
309 Mat&lt;<a href="#uword">sword</a>&gt;
310 </td>
311 </tr>
312 <tr>
313 <td style="vertical-align: top;">
314 fmat
315 </td>
316 <td style="vertical-align: top;">
317 &nbsp;=&nbsp;
318 </td>
319 <td style="vertical-align: top;">
320 Mat&lt;float&gt;
321 </td>
322 </tr>
323 <tr>
324 <td style="vertical-align: top;">
325 mat
326 </td>
327 <td style="vertical-align: top;">
328 &nbsp;=&nbsp;
329 </td>
330 <td style="vertical-align: top;">
331 Mat&lt;double&gt;
332 </td>
333 </tr>
334 <tr>
335 <td style="vertical-align: top;">
336 cx_fmat
337 </td>
338 <td style="vertical-align: top;">
339 &nbsp;=&nbsp;
340 </td>
341 <td style="vertical-align: top;">
342 Mat&lt;<a href="#cx_float_double">cx_float</a>&gt;
343 </td>
344 </tr>
345 <tr>
346 <td style="vertical-align: top;">
347 cx_mat
348 </td>
349 <td style="vertical-align: top;">
350 &nbsp;=&nbsp;
351 </td>
352 <td style="vertical-align: top;">
353 Mat&lt;<a href="#cx_float_double">cx_double</a>&gt;
354 </td>
355 </tr>
356 </tbody>
357 </table>
358 </ul>
359 </li>
360 <br>
361 <li>
362 In this documentation the <i>mat</i> type is used for convenience;
363 it is possible to use other types instead, eg. <i>fmat</i>
364 </li>
365 <br>
366 <li>
367 Functions which are wrappers for LAPACK or ATLAS functions (generally matrix decompositions) are only valid for the following types:
368 <i>fmat</i>, <i>mat</i>, <i>cx_fmat</i>, <i>cx_mat</i>
369 </li>
370 <br>
371 <li>
372 Elements are stored with column-major ordering (ie. column by column)
373 </li>
374 <br>
375 <a name="constructors_mat"></a>
376 <li>
377 Constructors:
378 <ul>
379 <li>mat()</li>
380 <li>mat(n_rows, n_cols)</li>
381 <li>mat(mat)</li>
382 <li>mat(vec)</li>
383 <li>mat(rowvec)</li>
384 <li>mat(string)</li>
385 <li>mat(initialiser_list) &nbsp; (C++11 only)</li>
386 <li>cx_mat(mat,mat) &nbsp; (for constructing a complex matrix out of two real matrices)</li>
387 </ul>
388 </li>
389 <br>
390 <li>
391 The string format for the constructor is elements separated by spaces, and rows denoted by semicolons.
392 For example, the 2x2 identity matrix can be created using the format string <code>"1 0; 0 1"</code>.
393 While string based initialisation is compact, directly setting the elements or using <a href="#element_initialisation">element initialisation</a> is considerably faster.
394 </li>
395 <br>
396 <a name="adv_constructors_mat"></a>
397 <li>
398 Advanced constructors:
399 <br>
400 <br>
401 <ul>
402 <li>mat(aux_mem*, n_rows, n_cols, copy_aux_mem = true, strict = true)
403 <br>
404 <br>
405 <ul>
406 Create a matrix using data from writeable auxiliary memory.
407 By default the matrix allocates its own memory and copies data from the auxiliary memory (for safety).
408 However, if <i>copy_aux_mem</i> is set to <i>false</i>,
409 the matrix will instead directly use the auxiliary memory (ie. no copying).
410 This is faster, but can be dangerous unless you know what you're doing!
411 <br>
412 <br>
413 The <i>strict</i> variable comes into effect only if <i>copy_aux_mem</i> is set to <i>false</i>
414 (ie. the matrix is directly using auxiliary memory).
415 If <i>strict</i> is set to <i>true</i>,
416 the matrix will be bound to the auxiliary memory for its lifetime;
417 the number of elements in the matrix can't be changed (directly or indirectly).
418 If <i>strict</i> is set to <i>false</i>, the matrix will not be bound to the auxiliary memory for its lifetime,
419 ie., the size of the matrix can be changed.
420 If the requested number of elements is different to the size of the auxiliary memory,
421 new memory will be allocated and the auxiliary memory will no longer be used.
422 </ul>
423 </li>
424 <br>
425 <li>mat(const aux_mem*, n_rows, n_cols)
426 <br>
427 <br>
428 <ul>
429 Create a matrix by copying data from read-only auxiliary memory.
430 </ul>
431 </li>
432 <a name="adv_constructors_mat_fixed"></a>
433 <br>
434 <li>mat::fixed&lt;n_rows, n_cols&gt;
435 <br>
436 <br>
437 <ul>
438 Create a fixed size matrix, with the size specified via template arguments.
439 Memory for the matrix is allocated at compile time.
440 This is generally faster than dynamic memory allocation, but the size of the matrix can't be changed afterwards (directly or indirectly).
441 <br>
442 <br>
443 For convenience, there are several pre-defined typedefs for each matrix type
444 (where the types are: <i>umat</i>, <i>imat</i>, <i>fmat</i>, <i>mat</i>, <i>cx_fmat</i>, <i>cx_mat</i>).
445 The typedefs specify a square matrix size, ranging from 2x2 to 9x9.
446 The typedefs were defined by simply appending a two digit form of the size to the matrix type
447 -- for example, <i>mat33</i> is equivalent to <i>mat::fixed&lt;3,3&gt;</i>,
448 while <i>cx_mat44</i> is equivalent to <i>cx_mat::fixed&lt;4,4&gt;</i>.
449 </ul>
450 </li>
451 <br>
452 <li>mat::fixed&lt;n_rows, n_cols&gt;(const aux_mem*)
453 <br>
454 <br>
455 <ul>
456 Create a fixed size matrix, with the size specified via template arguments,
457 and copying data from auxiliary memory.
458 </ul>
459 </li>
460 </ul>
461 </li>
462 <br>
463 <br>
464 <li>
465 Examples:
466 <ul>
467 <pre>
468 mat A = randu&lt;mat&gt;(5,5);
469 double x = A(1,2);
470
471 mat B = A + A;
472 mat C = A * B;
473 mat D = A % B;
474
475 cx_mat X(A,B);
476
477 B.zeros();
478 B.set_size(10,10);
479 B.zeros(5,6);
480
481 //
482 // fixed size matrices:
483
484 mat::fixed&lt;5,6&gt; F;
485 F.ones();
486
487 mat44 G;
488 G.randn();
489
490 cout &lt;&lt; mat22().randu() &lt;&lt; endl;
491
492 //
493 // constructing matrices from
494 // auxiliary (external) memory:
495
496 double aux_mem[24];
497 mat H(aux_mem, 4, 6, false);
498 </pre>
499 </ul>
500 </li>
501 <br>
502 <li><b>Caveat:</b>
503 For mathematical correctness, scalars are treated as 1x1 matrices during initialisation.
504 As such, the code below <b>will not</b> generate a 5x5 matrix with every element equal to 123.0:
505 <ul>
506 <pre>
507 mat A(5,5);
508 A = 123.0;
509 </pre>
510 </ul>
511 Use the following code instead:
512 <ul>
513 <pre>
514 mat A(5,5);
515 A.fill(123.0);
516 </pre>
517 </ul>
518 Or:
519 <ul>
520 <pre>
521 mat A = 123.0 * ones&lt;mat&gt;(5,5);
522 </pre>
523 </ul>
524 <br>
525 <li>
526 See also:
527 <ul>
528 <li><a href="#attributes">matrix attributes</a></li>
529 <li><a href="#element_access">accessing elements</a></li>
530 <li><a href="#element_initialisation">initialising elements</a></li>
531 <li><a href="#operators">math &amp; relational operators</a></li>
532 <li><a href="#submat">submatrix views</a></li>
533 <li><a href="#save_load_mat">saving &amp; loading matrices</a></li>
534 <li><a href="#print">printing matrices</a></li>
535 <li><a href="#iterators_mat">STL-style element iterators</a></li>
536 <li><a href="http://www.cplusplus.com/doc/tutorial/other_data_types/">explanation of <i>typedef</i></a> (cplusplus.com)
537 <li><a href="#Col">Col class</a></li>
538 <li><a href="#Row">Row class</a></li>
539 <li><a href="#Cube">Cube class</a></li>
540 </ul>
541 </li>
542 <br>
543 </ul>
544 <hr class="greyline">
545 <br>
546
547 <a name="Col"></a><b>Col&lt;</b><i>type</i><b>&gt;</b>
548 <br><b>colvec</b>
549 <br><b>vec</b>
550 <ul>
551 <li>
552 Classes for column vectors (matrices with one column)
553 </li>
554 <br>
555 <li>The <b>Col&lt;</b><i>type</i><b>&gt;</b> class is derived from the <b>Mat&lt;</b><i>type</i><b>&gt;</b> class
556 and inherits most of the member functions
557 </li>
558 <br>
559 <li>
560 For convenience the following typedefs have been defined:
561 <ul>
562 <table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
563 <tbody>
564 <tr>
565 <td style="vertical-align: top;">
566 uvec, ucolvec
567 </td>
568 <td style="vertical-align: top;">
569 &nbsp;=&nbsp;
570 </td>
571 <td style="vertical-align: top;">
572 Col&lt;<a href="#uword">uword</a>&gt;
573 </td>
574 </tr>
575 <tr>
576 <td style="vertical-align: top;">
577 ivec, icolvec
578 </td>
579 <td style="vertical-align: top;">
580 &nbsp;=&nbsp;
581 </td>
582 <td style="vertical-align: top;">
583 Col&lt;<a href="#uword">sword</a>&gt;
584 </td>
585 </tr>
586 <tr>
587 <td style="vertical-align: top;">
588 fvec, fcolvec
589 </td>
590 <td style="vertical-align: top;">
591 &nbsp;=&nbsp;
592 </td>
593 <td style="vertical-align: top;">
594 Col&lt;float&gt;
595 </td>
596 </tr>
597 <tr>
598 <td style="vertical-align: top;">
599 vec, colvec
600 </td>
601 <td style="vertical-align: top;">
602 &nbsp;=&nbsp;
603 </td>
604 <td style="vertical-align: top;">
605 Col&lt;double&gt;
606 </td>
607 </tr>
608 <tr>
609 <td style="vertical-align: top;">
610 cx_fvec, cx_fcolvec
611 </td>
612 <td style="vertical-align: top;">
613 &nbsp;=&nbsp;
614 </td>
615 <td style="vertical-align: top;">
616 Col&lt;<a href="#cx_float_double">cx_float</a>&gt;
617 </td>
618 </tr>
619 <tr>
620 <td style="vertical-align: top;">
621 cx_vec, cx_colvec
622 </td>
623 <td style="vertical-align: top;">
624 &nbsp;=&nbsp;
625 </td>
626 <td style="vertical-align: top;">
627 Col&lt;<a href="#cx_float_double">cx_double</a>&gt;
628 </td>
629 </tr>
630 </tbody>
631 </table>
632 </ul>
633 </li>
634 <br>
635 <li>
636 In this documentation, the <b><i>vec</i></b> and <b><i>colvec</i></b> types have the <b>same meaning</b> and are used <b>interchangeably</b>
637 </li>
638 <br>
639 <li>
640 In this documentation, the types <i>vec</i> or <i>colvec</i> are used for convenience; it is possible to use other types instead, eg.&nbsp;<i>fvec</i>, <i>fcolvec</i>
641 </li>
642 <br>
643 <li>
644 Functions which take <i>Mat</i> as input can generally also take <i>Col</i> as input.
645 Main exceptions are functions which require square matrices
646 </li>
647 <br>
648 <li>
649 Constructors
650 <ul>
651 <li>vec(n_elem=0)</li>
652 <li>vec(vec)</li>
653 <li>vec(mat) &nbsp; (a <i>std::logic_error</i> exception is thrown if the given matrix has more than one column)</li>
654 <li>vec(string) &nbsp; (elements separated by spaces)</li>
655 <li>vec(initialiser_list) &nbsp; (C++11 only)</li>
656 </ul>
657 </li>
658 <br>
659 <a name="adv_constructors_col"></a>
660 <li>
661 Advanced constructors:
662 <br>
663 <br>
664 <ul>
665 <li>vec(aux_mem*, number_of_elements, copy_aux_mem = true, strict = true)
666 <br>
667 <br>
668 <ul>
669 Create a column vector using data from writeable auxiliary memory.
670 By default the vector allocates its own memory and copies data from the auxiliary memory (for safety).
671 However, if <i>copy_aux_mem</i> is set to <i>false</i>,
672 the vector will instead directly use the auxiliary memory (ie. no copying).
673 This is faster, but can be dangerous unless you know what you're doing!
674 <br>
675 <br>
676 The <i>strict</i> variable comes into effect only if <i>copy_aux_mem</i> is set to <i>false</i>
677 (ie. the vector is directly using auxiliary memory).
678 If <i>strict</i> is set to <i>true</i>,
679 the vector will be bound to the auxiliary memory for its lifetime;
680 the number of elements in the vector can't be changed (directly or indirectly).
681 If <i>strict</i> is set to <i>false</i>, the vector will not be bound to the auxiliary memory for its lifetime,
682 ie., the vector's size can be changed.
683 If the requested number of elements is different to the size of the auxiliary memory,
684 new memory will be allocated and the auxiliary memory will no longer be used.
685 </ul>
686 </li>
687 <br>
688 <li>vec(const aux_mem*, number_of_elements)
689 <br>
690 <br>
691 <ul>
692 Create a column vector by copying data from read-only auxiliary memory.
693 </ul>
694 </li>
695 <br>
696 <li>vec::fixed&lt;number_of_elements&gt;
697 <br>
698 <br>
699 <ul>
700 Create a fixed size column vector, with the size specified via the template argument.
701 Memory for the vector is allocated at compile time.
702 This is generally faster than dynamic memory allocation, but the size of the vector can't be changed afterwards (directly or indirectly).
703 <br>
704 <br>
705 For convenience, there are several pre-defined typedefs for each vector type
706 (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).
707 The pre-defined typedefs specify vector sizes ranging from 2 to 9.
708 The typedefs were defined by simply appending a single digit form of the size to the vector type
709 -- for example, <i>vec3</i> is equivalent to <i>vec::fixed&lt;3&gt;</i>,
710 while <i>cx_vec4</i> is equivalent to <i>cx_vec::fixed&lt;4&gt;</i>.
711 </ul>
712 </li>
713 <br>
714 <li>vec::fixed&lt;number_of_elements&gt;(const aux_mem*)
715 <br>
716 <br>
717 <ul>
718 Create a fixed size column vector, with the size specified via the template argument,
719 and copying data from auxiliary memory.
720 </ul>
721 </li>
722 </ul>
723 </li>
724 <br>
725 <br>
726 <li>
727 Examples:
728 <ul>
729 <pre>
730 vec x(10);
731 vec y = zeros&lt;vec&gt;(10,1);
732
733 mat A = randu&lt;mat&gt;(10,10);
734 vec z = A.col(5); // extract a column vector
735 </pre>
736 </ul>
737 </li>
738 <br>
739 <li><b>Caveat:</b>
740 For mathematical correctness, scalars are treated as 1x1 matrices during initialisation.
741 As such, the code below <b>will not</b> generate a column vector with every element equal to 123.0:
742 <ul>
743 <pre>
744 vec q(5);
745 q = 123.0;
746 </pre>
747 </ul>
748 Use the following code instead:
749 <ul>
750 <pre>
751 vec q(5);
752 q.fill(123.0);
753 </pre>
754 </ul>
755 Or:
756 <ul>
757 <pre>
758 vec q = 123.0 * ones&lt;vec&gt;(5,1);
759 </pre>
760 </ul>
761 </li>
762 <br>
763 <li>See also:
764 <ul>
765 <li><a href="#Mat">Mat class</a></li>
766 <li><a href="#Row">Row class</a></li>
767 </ul>
768 </li>
769 <br>
770 </ul>
771 <hr class="greyline"><br>
772
773 <a name="Row"></a>
774 <b>Row&lt;</b><i>type</i><b>&gt;</b>
775 <br><b>rowvec</b>
776 <ul>
777 <li>
778 Classes for row vectors (matrices with one row)
779 </li>
780 <br>
781 <li>The template <b>Row&lt;</b><i>type</i><b>&gt;</b> class is derived from the <b>Mat&lt;</b><i>type</i><b>&gt;</b> class
782 and inherits most of the member functions
783 </li>
784 <br>
785 <li>
786 For convenience the following typedefs have been defined:
787 <ul>
788 <table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
789 <tbody>
790 <tr>
791 <td style="vertical-align: top;">
792 urowvec
793 </td>
794 <td style="vertical-align: top;">
795 &nbsp;=&nbsp;
796 </td>
797 <td style="vertical-align: top;">
798 Row&lt;<a href="#uword">uword</a>&gt;
799 </td>
800 </tr>
801 <tr>
802 <td style="vertical-align: top;">
803 irowvec
804 </td>
805 <td style="vertical-align: top;">
806 &nbsp;=&nbsp;
807 </td>
808 <td style="vertical-align: top;">
809 Row&lt;<a href="#uword">sword</a>&gt;
810 </td>
811 </tr>
812 <tr>
813 <td style="vertical-align: top;">
814 frowvec
815 </td>
816 <td style="vertical-align: top;">
817 &nbsp;=&nbsp;
818 </td>
819 <td style="vertical-align: top;">
820 Row&lt;float&gt;
821 </td>
822 </tr>
823 <tr>
824 <td style="vertical-align: top;">
825 rowvec
826 </td>
827 <td style="vertical-align: top;">
828 &nbsp;=&nbsp;
829 </td>
830 <td style="vertical-align: top;">
831 Row&lt;double&gt;
832 </td>
833 </tr>
834 <tr>
835 <td style="vertical-align: top;">
836 cx_frowvec
837 </td>
838 <td style="vertical-align: top;">
839 &nbsp;=&nbsp;
840 </td>
841 <td style="vertical-align: top;">
842 Row&lt;<a href="#cx_float_double">cx_float</a>&gt;
843 </td>
844 </tr>
845 <tr>
846 <td style="vertical-align: top;">
847 cx_rowvec
848 </td>
849 <td style="vertical-align: top;">
850 &nbsp;=&nbsp;
851 </td>
852 <td style="vertical-align: top;">
853 Row&lt;<a href="#cx_float_double">cx_double</a>&gt;
854 </td>
855 </tr>
856 </tbody>
857 </table>
858 </ul>
859 </li>
860 <br>
861 <li>
862 In this documentation, the <i>rowvec</i> type is used for convenience;
863 it is possible to use other types instead, eg. <i>frowvec</i>
864 </li>
865 <br>
866 <li>
867 Functions which take <i>Mat</i> as input can generally also take <i>Row</i> as input.
868 Main exceptions are functions which require square matrices
869 </li>
870 <br>
871 <li>
872 Constructors
873 <ul>
874 <li>rowvec(n_elem=0)</li>
875 <li>rowvec(rowvec)</li>
876 <li>rowvec(mat) &nbsp; (a <i>std::logic_error</i> exception is thrown if the given matrix has more than one row)</li>
877 <li>rowvec(string) &nbsp; (elements separated by spaces)</li>
878 <li>rowvec(initialiser_list) &nbsp; (C++11 only)</li>
879 </ul>
880 </li>
881 <br>
882 <a name="adv_constructors_row"></a>
883 <li>
884 Advanced constructors:
885 <br>
886 <br>
887 <ul>
888 <li>rowvec(aux_mem*, number_of_elements, copy_aux_mem = true, strict = true)
889 <br>
890 <br>
891 <ul>
892 Create a row vector using data from writeable auxiliary memory.
893 By default the vector allocates its own memory and copies data from the auxiliary memory (for safety).
894 However, if <i>copy_aux_mem</i> is set to <i>false</i>,
895 the vector will instead directly use the auxiliary memory (ie. no copying).
896 This is faster, but can be dangerous unless you know what you're doing!
897 <br>
898 <br>
899 The <i>strict</i> variable comes into effect only if <i>copy_aux_mem</i> is set to <i>false</i>
900 (ie. the vector is directly using auxiliary memory).
901 If <i>strict</i> is set to <i>true</i>,
902 the vector will be bound to the auxiliary memory for its lifetime;
903 the number of elements in the vector can't be changed (directly or indirectly).
904 If <i>strict</i> is set to <i>false</i>, the vector will not be bound to the auxiliary memory for its lifetime,
905 ie., the vector's size can be changed.
906 If the requested number of elements is different to the size of the auxiliary memory,
907 new memory will be allocated and the auxiliary memory will no longer be used.
908 </ul>
909 </li>
910 <br>
911 <li>rowvec(const aux_mem*, number_of_elements)
912 <br>
913 <br>
914 <ul>
915 Create a row vector by copying data from read-only auxiliary memory.
916 </ul>
917 </li>
918 <br>
919 <li>rowvec::fixed&lt;number_of_elements&gt;
920 <br>
921 <br>
922 <ul>
923 Create a fixed size row vector, with the size specified via the template argument.
924 Memory for the vector is allocated at compile time.
925 This is generally faster than dynamic memory allocation, but the size of the vector can't be changed afterwards (directly or indirectly).
926 <br>
927 <br>
928 For convenience, there are several pre-defined typedefs for each vector type
929 (where the types are: <i>urowvec</i>, <i>irowvec</i>, <i>frowvec</i>, <i>rowvec</i>, <i>cx_frowvec</i>, <i>cx_rowvec</i>).
930 The pre-defined typedefs specify vector sizes ranging from 2 to 9.
931 The typedefs were defined by simply appending a single digit form of the size to the vector type
932 -- for example, <i>rowvec3</i> is equivalent to <i>rowvec::fixed&lt;3&gt;</i>,
933 while <i>cx_rowvec4</i> is equivalent to <i>cx_rowvec::fixed&lt;4&gt;</i>.
934 </ul>
935 </li>
936 <br>
937 <li>rowvec::fixed&lt;number_of_elements&gt;(const aux_mem*)
938 <br>
939 <br>
940 <ul>
941 Create a fixed size row vector, with the size specified via the template argument,
942 and copying data from auxiliary memory.
943 </ul>
944 </li>
945 </ul>
946 </li>
947 <br>
948 <br>
949 <li>
950 Examples:
951 <ul>
952 <pre>
953 rowvec x(10);
954 rowvec y = zeros&lt;mat&gt;(1,10);
955
956 mat A = randu&lt;mat&gt;(10,10);
957 rowvec z = A.row(5); // extract a row vector
958 </pre>
959 </ul>
960 </li>
961 <br>
962 <li>
963 <b>Caveat:</b>
964 For mathematical correctness, scalars are treated as 1x1 matrices during initialisation.
965 As such, the code below <b>will not</b> generate a row vector with every element equal to 123.0:
966 <ul>
967 <pre>
968 rowvec r(5);
969 r = 123.0;
970 </pre>
971 </ul>
972 Use the following code instead:
973 <ul>
974 <pre>
975 rowvec r(5);
976 r.fill(123.0);
977 </pre>
978 </ul>
979 Or:
980 <ul>
981 <pre>
982 rowvec r = 123.0 * ones&lt;rowvec&gt;(1,5);
983 </pre>
984 </ul>
985 <br>
986 <li>See also:
987 <ul>
988 <li><a href="#Mat">Mat class</a></li>
989 <li><a href="#Col">Col class</a></li>
990 </ul>
991 </li>
992 <br>
993 </ul>
994 <hr class="greyline">
995 <br>
996
997 <a name="Cube"></a>
998 <b>Cube&lt;</b><i>type</i><b>&gt;</b>
999 <br><b>cube</b>
1000 <br><b>cx_cube</b>
1001 <ul>
1002 <li>
1003 Classes for cubes, also known as "3D matrices"
1004 </li>
1005 <br>
1006 <li>
1007 The root template cube class is <b>Cube&lt;</b><i>type</i><b>&gt;</b>, where <i>type</i> can be one of:
1008 <i>char</i>, <i>int</i>, <i>float</i>, <i>double</i>, <i>std::complex&lt;double&gt;</i>, etc
1009 </li>
1010 <br>
1011 <li>
1012 For convenience the following typedefs have been defined:
1013 <ul>
1014 <table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
1015 <tbody>
1016 <tr>
1017 <td style="vertical-align: top;">
1018 ucube
1019 </td>
1020 <td style="vertical-align: top;">
1021 &nbsp;=&nbsp;
1022 </td>
1023 <td style="vertical-align: top;">
1024 Cube&lt;<a href="#uword">uword</a>&gt;
1025 </td>
1026 </tr>
1027 <tr>
1028 <td style="vertical-align: top;">
1029 icube
1030 </td>
1031 <td style="vertical-align: top;">
1032 &nbsp;=&nbsp;
1033 </td>
1034 <td style="vertical-align: top;">
1035 Cube&lt;<a href="#uword">sword</a>&gt;
1036 </td>
1037 </tr>
1038 <tr>
1039 <td style="vertical-align: top;">
1040 fcube
1041 </td>
1042 <td style="vertical-align: top;">
1043 &nbsp;=&nbsp;
1044 </td>
1045 <td style="vertical-align: top;">
1046 Cube&lt;float&gt;
1047 </td>
1048 </tr>
1049 <tr>
1050 <td style="vertical-align: top;">
1051 cube
1052 </td>
1053 <td style="vertical-align: top;">
1054 &nbsp;=&nbsp;
1055 </td>
1056 <td style="vertical-align: top;">
1057 Cube&lt;double&gt;
1058 </td>
1059 </tr>
1060 <tr>
1061 <td style="vertical-align: top;">
1062 cx_fcube
1063 </td>
1064 <td style="vertical-align: top;">
1065 &nbsp;=&nbsp;
1066 </td>
1067 <td style="vertical-align: top;">
1068 Cube&lt;<a href="#cx_float_double">cx_float</a>&gt;
1069 </td>
1070 </tr>
1071 <tr>
1072 <td style="vertical-align: top;">
1073 cx_cube
1074 </td>
1075 <td style="vertical-align: top;">
1076 &nbsp;=&nbsp;
1077 </td>
1078 <td style="vertical-align: top;">
1079 Cube&lt;<a href="#cx_float_double">cx_double</a>&gt;
1080 </td>
1081 </tr>
1082 </tbody>
1083 </table>
1084 </ul>
1085 </li>
1086 <br>
1087 <li>
1088 In this documentation the <i>cube</i> type is used for convenience;
1089 it is possible to use other types instead, eg. <i>fcube</i>
1090 </li>
1091 <br>
1092 <li>
1093 Cube data is stored as a set of slices (matrices) stored contiguously within memory.
1094 Within each slice, elements are stored with column-major ordering (ie. column by column)
1095 </li>
1096 <br>
1097 <li>
1098 Each slice can be interpreted as a matrix, hence functions which take <i>Mat</i> as input can generally also take cube slices as input
1099 </li>
1100 <br>
1101 <a name="constructors_cube"></a>
1102 <li>
1103 Constructors:
1104 <ul>
1105 cube()
1106 <br>cube(cube)
1107 <br>cube(n_rows, n_cols, n_slices)
1108 <br>cx_cube(cube, cube) (for constructing a complex cube out of two real cubes)
1109 </ul>
1110 </li>
1111 <br>
1112
1113 <a name="adv_constructors_cube"></a>
1114 <li>
1115 Advanced constructors:
1116 <br>
1117 <br>
1118 <ul>
1119 <li>
1120 cube::fixed&lt;n_rows, n_cols, n_slices&gt;
1121 <br>
1122 <br>
1123 <ul>
1124 Create a fixed size cube, with the size specified via template arguments.
1125 Memory for the cube is allocated at compile time.
1126 This is generally faster than dynamic memory allocation, but the size of the cube can't be changed afterwards (directly or indirectly).
1127 </ul>
1128 </li>
1129 <br>
1130 <li>cube(aux_mem*, n_rows, n_cols, n_slices, copy_aux_mem = true, strict = true)
1131 <br>
1132 <br>
1133 <ul>
1134 Create a cube using data from writeable auxiliary memory.
1135 By default the cube allocates its own memory and copies data from the auxiliary memory (for safety).
1136 However, if <i>copy_aux_mem</i> is set to <i>false</i>,
1137 the cube will instead directly use the auxiliary memory (ie. no copying).
1138 This is faster, but can be dangerous unless you know what you're doing!
1139 <br>
1140 <br>
1141 The <i>strict</i> variable comes into effect only if <i>copy_aux_mem</i> is set to <i>false</i>
1142 (ie. the cube is directly using auxiliary memory).
1143 If <i>strict</i> is set to <i>true</i>,
1144 the cube will be bound to the auxiliary memory for its lifetime;
1145 the number of elements in the cube can't be changed (directly or indirectly).
1146 If <i>strict</i> is set to <i>false</i>, the cube will not be bound to the auxiliary memory for its lifetime,
1147 ie., the size of the cube can be changed.
1148 If the requested number of elements is different to the size of the auxiliary memory,
1149 new memory will be allocated and the auxiliary memory will no longer be used.
1150 </ul>
1151 </li>
1152 <br>
1153 <li>cube(const aux_mem*, n_rows, n_cols, n_slices)
1154 <br>
1155 <br>
1156 <ul>
1157 Create a cube by copying data from read-only auxiliary memory.
1158 </ul>
1159 </li>
1160 </ul>
1161 </li>
1162 <br>
1163 <br>
1164 <li>
1165 Examples:
1166 <ul>
1167 <pre>
1168 cube x(1,2,3);
1169 cube y = randu&lt;cube&gt;(4,5,6);
1170
1171 mat A = y.slice(1); // extract a slice from the cube
1172 // (each slice is a matrix)
1173
1174 mat B = randu&lt;mat&gt;(4,5);
1175 y.slice(2) = B; // set a slice in the cube
1176
1177 cube q = y + y; // cube addition
1178 cube r = y % y; // element-wise cube multiplication
1179
1180 cube::fixed&lt;4,5,6&gt; f;
1181 f.ones();
1182 </pre>
1183 </ul>
1184 </li>
1185 <br>
1186 <li>
1187 <b>Caveats</b>
1188 <br>
1189 <br>
1190 <ul>
1191 <li>
1192 The size of individual slices can't be changed.
1193 For example, the following <b>will not</b> work:
1194 <ul>
1195 <pre>
1196 cube c(5,6,7);
1197 c.slice(0) = randu&lt;mat&gt;(10,20); // wrong size
1198 </pre>
1199 </ul>
1200 </li>
1201 <li>
1202 For mathematical correctness, scalars are treated as 1x1x1 cubes during initialisation.
1203 As such, the code below <b>will not</b> generate a cube with every element equal to 123.0:
1204 <ul>
1205 <pre>
1206 cube c(5,6,7);
1207 c = 123.0;
1208 </pre>
1209 </ul>
1210 Use the following code instead:
1211 <ul>
1212 <pre>
1213 cube c(5,6,7);
1214 c.fill(123.0);
1215 </pre>
1216 </ul>
1217 Or:
1218 <ul>
1219 <pre>
1220 cube c = 123.0 * ones&lt;cube&gt;(5,6,7);
1221 </pre>
1222 </ul>
1223 </li>
1224 </ul>
1225 <br>
1226 <li>
1227 See also:
1228 <ul>
1229 <li><a href="#attributes">cube attributes</a></li>
1230 <li><a href="#element_access">accessing elements</a></li>
1231 <li><a href="#operators">math &amp; relational operators</a></li>
1232 <li><a href="#subcube">subcube views and slices</a></li>
1233 <li><a href="#save_load_mat">saving &amp; loading cubes</a></li>
1234 <li><a href="#iterators_cube">STL-style element iterators</a></li>
1235 <li><a href="#Mat">Mat class</a></li>
1236 </ul>
1237 </li>
1238 <br>
1239 </ul>
1240 <hr class="greyline">
1241 <br>
1242
1243 <a name="field"></a>
1244 <b>field&lt;</b><i>object type</i><b>&gt;</b>
1245 <ul>
1246 <li>
1247 Class for one and two dimensional fields of arbitrary objects
1248 </li>
1249 <br>
1250 <li>
1251 Constructors (where <i>object type</i> is another class, eg. <i>std::string</i>, <i>mat</i>, <i>vec</i>, <i>rowvec</i>, etc):
1252 <ul>
1253 field&lt;<i>object type</i>&gt;(n_elem=0)
1254 <br>field&lt;<i>object type</i>&gt;(n_rows, n_cols)
1255 <br>field&lt;<i>object type</i>&gt;(field&lt;<i>object type</i>&gt;)
1256 </ul>
1257 </li>
1258 <br>
1259 <li>
1260 Examples:
1261 <ul>
1262 <pre>
1263 // create a field of strings
1264 field&lt;std::string&gt; S(3,2);
1265
1266 S(0,0) = "hello";
1267 S(1,0) = "there";
1268
1269 // string fields can be saved as plain text files
1270 S.save("string_field");
1271
1272 // create a vec field with 3 rows and 2 columns
1273 field&lt;vec&gt; F(3,2);
1274
1275 // access components of the field
1276 F(0,0) = vec(5);
1277 F(1,1) = randu&lt;vec&gt;(6);
1278 F(2,0).set_size(7);
1279
1280 // access element 1 of the vec stored at 2,0
1281 double x = F(2,0)(1);
1282
1283 // copy rows
1284 F.row(0) = F.row(2);
1285
1286 // extract a row of vecs from F
1287 field&lt;vec&gt; G = F.row(1);
1288
1289 // print the field to the standard output
1290 G.print("G =");
1291
1292 // save the field to a binary file
1293 G.save("vec_field");
1294 </pre>
1295 </ul>
1296 </li>
1297 <br>
1298 <li>See also:
1299 <ul>
1300 <li><a href="#attributes">field attributes</a></li>
1301 <li><a href="#subfield">subfield views</a></li>
1302 <li><a href="#save_load_field">saving/loading fields</a></li>
1303 <li><a href="http://cplusplus.com/reference/string/string/">string class in the standard C++ library</a> (cplusplus.com)</li>
1304 </ul>
1305 </li>
1306 <br>
1307 </ul>
1308 <hr class="greyline">
1309 <hr class="greyline">
1310 <br>
1311 <br>
1312 <font size=+1><b>Member Functions &amp; Variables</b></font>
1313 <br>
1314 <br>
1315 <hr class="greyline">
1316 <br>
1317
1318 <a name="attributes"></a>
1319
1320 <b>attributes</b>
1321 <ul>
1322 <table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
1323 <tbody>
1324 <tr>
1325 <td>
1326 <b>.n_rows</b>
1327 </td>
1328 <td>&nbsp;&nbsp;</td>
1329 <td>
1330 (number of rows)
1331 </td>
1332 </tr>
1333 <tr>
1334 <td>
1335 <b>.n_cols</b>
1336 </td>
1337 <td>&nbsp;&nbsp;</td>
1338 <td>
1339 (number of columns)
1340 </td>
1341 </tr>
1342 <tr>
1343 <td>
1344 <b>.n_elem</b>
1345 </td>
1346 <td>&nbsp;&nbsp;</td>
1347 <td>
1348 (total number of elements)
1349 </td>
1350 </tr>
1351 <tr>
1352 <td>
1353 <b>.n_slices</b>
1354 </td>
1355 <td>&nbsp;&nbsp;</td>
1356 <td>
1357 (number of slices)
1358 </td>
1359 </tr>
1360 </tbody>
1361 </table>
1362 </ul>
1363 <br>
1364 <ul>
1365 <li>
1366 Member variables which are read-only;
1367 to change the size, use
1368 <a href="#set_size">.set_size()</a>,
1369 <a href="#copy_size">.copy_size()</a>,
1370 <a href="#zeros_member">.zeros()</a>,
1371 <a href="#ones_member">.ones()</a>,
1372 or
1373 <a href="#reset">.reset()</a>
1374 </li>
1375 <br>
1376 <li><i>n_rows</i>, <i>n_cols</i> and <i>n_elem</i> are applicable to <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i> classes</li>
1377 <br>
1378 <li><i>n_slices</i> is applicable only to the <i>Cube</i> class</li>
1379 <br>
1380 <li>
1381 For the <i>Col</i> and <i>Row</i> classes, <i>n_elem</i> also indicates vector length</li>
1382 <br>
1383 <li>The variables are of type <a href="#uword">uword</a></li>
1384 <br>
1385 <li>
1386 Examples:
1387 <ul>
1388 <pre>
1389 mat X(4,5);
1390 cout &lt;&lt; "X has " &lt;&lt; X.n_cols &lt;&lt; " columns" &lt;&lt; endl;
1391 </pre>
1392 </ul>
1393 </li>
1394 <br>
1395 <li>
1396 See also:
1397 <ul>
1398 <li><a href="#set_size">.set_size()</a></li>
1399 <li><a href="#copy_size">.copy_size()</a></li>
1400 <li><a href="#zeros_member">.zeros()</a></li>
1401 <li><a href="#ones_member">.ones()</a></li>
1402 <li><a href="#reset">.reset()</a></li>
1403 </ul>
1404 </li>
1405 <br>
1406 </ul>
1407 <hr class="greyline"><br>
1408
1409 <a name="colptr"></a>
1410 <b>.colptr(col_number)</b>
1411 <ul>
1412 <li>
1413 Member function of <i>Mat</i>
1414 </li>
1415 <br>
1416 <li>
1417 Obtain a raw pointer to the memory used by the specified column
1418 </li>
1419 <br>
1420 <li>
1421 As soon as the size of the matrix is changed, the pointer is no longer valid
1422 </li>
1423 <br>
1424 <li>This function is not recommended for use unless you know what you're doing
1425 -- you may wish to use <a href="#submat">submatrix views</a> instead
1426 </li>
1427 <br>
1428 <li>
1429 Examples:
1430 <ul>
1431 <pre>
1432 mat A = randu&lt;mat&gt;(5,5);
1433
1434 double* mem = A.colptr(2);
1435 </pre>
1436 </ul>
1437 </li>
1438 <br>
1439 <li>
1440 See also:
1441 <ul>
1442 <li><a href="#memptr">.memptr()</a></li>
1443 <li><a href="#submat">submatrix access</a></li>
1444 <li><a href="#iterators_mat">iterators (matrices)</a></li>
1445 <li><a href="#adv_constructors_mat">advanced constructors (matrices)</a></li>
1446 </ul>
1447 </li>
1448 <br>
1449 </ul>
1450 <hr class="greyline"><br>
1451
1452 <a name="copy_size"></a>
1453 <b>.copy_size(A)</b>
1454 <ul>
1455 <li>
1456 Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i>
1457 </li>
1458 <br>
1459 <li>
1460 Set the size to be the same as object <i>A</i>
1461 </li>
1462 <br>
1463 <li>
1464 Object <i>A</i> must be of the same root type as the object being modified
1465 (eg. you can't set the size of a matrix by providing a cube)
1466 </li>
1467 <br>
1468 <li>
1469 Examples:
1470 <ul>
1471 <pre>
1472 mat A = randu&lt;mat&gt;(5,6);
1473 mat B;
1474 B.copy_size(A);
1475
1476 cout &lt;&lt; B.n_rows &lt;&lt; endl;
1477 cout &lt;&lt; B.n_cols &lt;&lt; endl;
1478 </pre>
1479 </ul>
1480 </li>
1481 </ul>
1482 <br>
1483 <hr class="greyline"><br>
1484
1485 <a name="diag"></a>
1486 <b>.diag(k=0)</b>
1487 <ul>
1488 <li>
1489 Member function of <i>Mat</i>.
1490 </li>
1491 <br>
1492 <li>
1493 Read/write access to the <i>k</i>-th diagonal in a matrix
1494 </li>
1495 <br>
1496 <li>The argument <i>k</i> is optional -- by default the main diagonal is accessed (<i>k=0</i>)</li>
1497 <br>
1498 <li>For <i>k &gt; 0</i>, the <i>k</i>-th super-diagonal is accessed (top-right corner)</li>
1499 <br>
1500 <li>For <i>k &lt; 0</i>, the <i>k</i>-th sub-diagonal is accessed (bottom-left corner)</li>
1501 <br>
1502 <li>
1503 An extracted diagonal is interpreted as a column vector
1504 </li>
1505 <br>
1506 <li>
1507 Examples:
1508 <ul>
1509 <pre>
1510 mat X = randu&lt;mat&gt;(5,5);
1511
1512 vec a = X.diag();
1513 vec b = X.diag(1);
1514 vec c = X.diag(-2);
1515
1516 X.diag() = randu&lt;vec&gt;(5);
1517 X.diag() += 6;
1518 </pre>
1519 </ul>
1520 </li>
1521 <br>
1522 <li>
1523 See also:
1524 <ul>
1525 <li><a href="#diagvec">diagvec()</a></li>
1526 <li><a href="#submat">submatrix views</a></li>
1527 </ul>
1528 </li>
1529 </ul>
1530 <br>
1531 <hr class="greyline"><br>
1532
1533 <a name="element_access"></a>
1534 <b>element/object access via (), [] and .at()</b>
1535 <ul>
1536 <li>
1537 Provide access to individual elements or objects stored in a container object
1538 (ie., <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>field</i>)<br>
1539 <br>
1540 <ul>
1541 <table style="text-align: left; width: 100%;"
1542 border="0" cellpadding="2" cellspacing="2">
1543 <tbody>
1544 <tr>
1545 <td style="vertical-align: top;">
1546 <pre>(n)</pre>
1547 </td>
1548 <td style="vertical-align: top;">&nbsp;<br>
1549 </td>
1550 <td style="vertical-align: top;">
1551 For <i>vec</i> and <i>rowvec</i>, access the <i>n</i>-th element.
1552 For <i>mat</i>, <i>cube</i> and <i>field</i>, access the <i>n</i>-th element/object under the assumption of a flat layout,
1553 with column-major ordering of data (ie. column by column).
1554 A <i>std::logic_error</i> exception is thrown if the requested element is out of bounds.
1555 The bounds check can be optionally disabled at compile-time (see below).
1556 </td>
1557 </tr>
1558 <tr>
1559 <td>&nbsp;</td>
1560 <td>&nbsp;</td>
1561 <td>&nbsp;</td>
1562 </tr>
1563 <tr>
1564 <td style="vertical-align: top;">
1565 <pre>.at(n) and [n]</pre>
1566 </td>
1567 <td style="vertical-align: top;"><br>
1568 </td>
1569 <td style="vertical-align: top;">
1570 As for <i>(n)</i>, but without a bounds check.
1571 Not recommended for use unless your code has been thoroughly debugged.
1572 </td>
1573 </tr>
1574 <tr>
1575 <td>&nbsp;</td>
1576 <td>&nbsp;</td>
1577 <td>&nbsp;</td>
1578 </tr>
1579 <tr>
1580 <td style="vertical-align: top;">
1581 <pre>(i,j)</pre>
1582 </td>
1583 <td style="vertical-align: top;"><br>
1584 </td>
1585 <td style="vertical-align: top;">
1586 For <i>mat</i> and <i>field</i> classes, access the element/object stored at the <i>i</i>-th row and <i>j</i>-th column.
1587 A <i>std::logic_error</i> exception is thrown if the requested element is out of bounds.
1588 The bounds check can be optionally disabled at compile-time (see below).
1589 </td>
1590 </tr>
1591 <tr>
1592 <td>&nbsp;</td>
1593 <td>&nbsp;</td>
1594 <td>&nbsp;</td>
1595 </tr>
1596 <tr>
1597 <td style="vertical-align: top;">
1598 <pre>.at(i,j)</pre>
1599 </td>
1600 <td style="vertical-align: top;"><br>
1601 </td>
1602 <td style="vertical-align: top;">
1603 As for <i>(i,j)</i>, but without a bounds check.
1604 Not recommended for use unless your code has been thoroughly debugged.
1605 </td>
1606 <td style="vertical-align: top;"><br>
1607 </td>
1608 </tr>
1609 <tr>
1610 <td>&nbsp;</td>
1611 <td>&nbsp;</td>
1612 <td>&nbsp;</td>
1613 </tr>
1614 <tr>
1615 <td style="vertical-align: top;">
1616 <pre>(i,j,k)</pre>
1617 </td>
1618 <td style="vertical-align: top;"><br>
1619 </td>
1620 <td style="vertical-align: top;">
1621 Cube only: access the element stored at the <i>i</i>-th row, <i>j</i>-th column and <i>k</i>-th slice.
1622 A <i>std::logic_error</i> exception is thrown if the requested element is out of bounds.
1623 The bounds check can be optionally disabled at compile-time (see below).
1624 </td>
1625 </tr>
1626 <tr>
1627 <td>&nbsp;</td>
1628 <td>&nbsp;</td>
1629 <td>&nbsp;</td>
1630 </tr>
1631 <tr>
1632 <td style="vertical-align: top;">
1633 <pre>.at(i,j,k)</pre>
1634 </td>
1635 <td style="vertical-align: top;"><br>
1636 </td>
1637 <td style="vertical-align: top;">
1638 As for <i>(i,j,k)</i>, but without a bounds check.
1639 Not recommended for use unless your code has been thoroughly debugged.</td>
1640 </tr>
1641 </tbody>
1642 </table>
1643 </ul>
1644 </li>
1645 <br>
1646 <li>
1647 The bounds checks used by the <i>(n)</i>, <i>(i,j)</i> and <i>(i,j,k)</i> access forms
1648 can be disabled by defining <i>ARMA_NO_DEBUG</i> or <i>NDEBUG</i> macros
1649 before including the <i>armadillo</i> header file (eg. <i>#define ARMA_NO_DEBUG</i>).
1650 Disabling the bounds checks is not recommended until your code has been thoroughly debugged
1651 -- it's better to write correct code first, and then maximise its speed.
1652 </li>
1653 <br>
1654 <li>
1655 Examples:
1656 <ul>
1657 <pre>
1658 mat A = randu&lt;mat&gt;(10,10);
1659 A(9,9) = 123.0;
1660 double x = A.at(9,9);
1661 double y = A[99];
1662
1663 vec p = randu&lt;vec&gt;(10,1);
1664 p(9) = 123.0;
1665 double z = p[9];
1666 </pre>
1667 </ul>
1668 </li>
1669 <br>
1670 <li>See also:
1671 <ul>
1672 <li><a href="#in_range">.in_range()</a></li>
1673 <li><a href="#iterators_mat">iterators (matrices)</a></li>
1674 <li><a href="#iterators_cube">iterators (cubes)</a></li>
1675 </ul>
1676 </li>
1677 <br>
1678 </ul>
1679 <hr class="greyline"><br>
1680
1681 <a name="element_initialisation"></a>
1682 <b>element initialisation</b>
1683 <ul>
1684 <li>
1685 Instances of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>field</i> classes can be initialised via repeated use of the &lt;&lt; operator
1686 </li>
1687 <br>
1688 <li>
1689 Special element <i>endr</i> indicates "end of row" (conceptually similar to <i>std::endl</i>)
1690 </li>
1691 <br>
1692 <li>
1693 Setting elements via &lt;&lt; is a bit slower than directly <a href="#element_access">accessing</a> the elements,
1694 but code using &lt;&lt; is generally more readable as well as being easier to write
1695 </li>
1696 <br>
1697 <li>
1698 If you have a C++11 compiler, instances of <i>Mat</i>, <i>Col</i> and <i>Row</i> classes can be also initialised via initialiser lists;
1699 this requires support for the C++11 standard to be <a href="#added_in_24">explicitly enabled</a>
1700 </li>
1701 <br>
1702 <li>
1703 Examples:
1704 <ul>
1705 <pre>
1706 mat A;
1707
1708 A &lt;&lt; 1 &lt;&lt; 2 &lt;&lt; 3 &lt;&lt; endr
1709 &lt;&lt; 4 &lt;&lt; 5 &lt;&lt; 6 &lt;&lt; endr;
1710
1711 mat B = { 1, 2, 3, 4, 5, 6 }; // C++11 only
1712 B.reshape(2,3);
1713 </pre>
1714 </ul>
1715 </li>
1716 <br>
1717 <li>
1718 See also:
1719 <ul>
1720 <li><a href="#element_access">element access</a></li>
1721 <li><a href="#print">.print()</a></li>
1722 <li><a href="#save_load_mat">saving &amp; loading matrices</a></li>
1723 <li><a href="#adv_constructors_mat">advanced constructors (matrices)</a></li>
1724 </ul>
1725 </li>
1726 <br>
1727 </ul>
1728 <hr class="greyline"><br>
1729
1730 <a name="eye_member"></a>
1731 <b>.eye()</b>
1732 <br>
1733 <b>.eye(n_rows, n_cols)</b>
1734 <ul>
1735 <li>
1736 Set the elements along the main diagonal to one and off-diagonal elements set to zero,
1737 optionally first resizing to specified dimensions
1738 </li>
1739 <br>
1740 <li>
1741 An identity matrix is generated when <i>n_rows</i> = <i>n_cols</i>
1742 </li>
1743 <br>
1744 <li>
1745 Examples:
1746 <ul>
1747 <pre>
1748 mat A(5,5);
1749 A.eye();
1750
1751 mat B;
1752 B.eye(5,5);
1753 </pre>
1754 </ul>
1755 </li>
1756 <br>
1757 <li>See also:
1758 <ul>
1759 <li><a href="#eye_standalone">eye()</a> (standalone function)</li>
1760 <li><a href="#diagmat">diagmat()</a></li>
1761 <li><a href="#diagvec">diagvec()</a></li>
1762 <li><a href="#ones_member">.ones()</a></li>
1763 </ul>
1764 </li>
1765 <br>
1766 </ul>
1767 <hr class="greyline"><br>
1768
1769 <a name="fill"></a>
1770 <b>.fill(value)</b>
1771 <ul>
1772 <li>
1773 Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i> classes.
1774 </li>
1775 <br>
1776 <li>Sets the elements to a specified value.
1777 The type of value must match the type of elements used by the container object
1778 (eg. for <i>mat</i> the type is double)
1779 </li>
1780 <br>
1781 <li>
1782 Examples:
1783 <ul>
1784 <pre>
1785 mat A(5,5);
1786 A.fill(123.0);
1787 </pre>
1788 </ul>
1789 </li>
1790 <br>
1791 <li>
1792 See also:
1793 <ul>
1794 <li><a href="#ones_member">.ones()</a></li>
1795 <li><a href="#zeros_member">.zeros()</a></li>
1796 <li><a href="#randu_randn_member">.randu() &amp; .randn()</a></li>
1797 </ul>
1798 </li>
1799 <br>
1800 </ul>
1801 <hr class="greyline"><br>
1802
1803 <a name="in_range"></a>
1804 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
1805 <tbody>
1806 <tr>
1807 <td style="vertical-align: top;"><b>.in_range(</b> i <b>)</b></td>
1808 <td style="vertical-align: top;"><br>
1809 </td>
1810 <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i>)
1811 </td>
1812 </tr>
1813 <tr>
1814 <td style="vertical-align: top;"><b>.in_range( span(</b>start<b>,</b> end<b>) )</b></td>
1815 <td style="vertical-align: top;"><br>
1816 </td>
1817 <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i>)
1818 </td>
1819 </tr>
1820 <tr>
1821 <td>
1822 &nbsp;
1823 </td>
1824 </tr>
1825 <tr>
1826 <td style="vertical-align: top;"><b>.in_range(</b> row<b>,</b> col <b>)</b></td>
1827 <td style="vertical-align: top;"><br>
1828 </td>
1829 <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>field</i>)
1830 </td>
1831 </tr>
1832 <tr>
1833 <td style="vertical-align: top;"><b>.in_range( <font size=-1>span(</b>start_row<b>,</b> end_row<b>), span(</b>start_col<b>,</b> end_col<b>)</font> )</b></td>
1834 <td style="vertical-align: top;"><br>
1835 </td>
1836 <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>field</i>)
1837 </td>
1838 </tr>
1839 <tr>
1840 <td>
1841 &nbsp;
1842 </td>
1843 </tr>
1844 <tr>
1845 <td style="vertical-align: top;"><b>.in_range(</b> row<b>,</b> col<b>,</b> slice <b>)</b></td>
1846 <td style="vertical-align: top;"><br>
1847 </td>
1848 <td style="vertical-align: top;">(member of <i>Cube</i>)
1849 </td>
1850 </tr>
1851 <tr>
1852 <td style="vertical-align: top;"><b>.in_range( <font size=-1>span(</b>start_row<b>,</b> end_row<b>), span(</b>start_col<b>,</b> end_col<b>), span(</b>start_slice<b>,</b> end_slice<b>)</font> )</b></td>
1853 <td style="vertical-align: top;"><br>
1854 </td>
1855 <td style="vertical-align: top;">(member of <i>Cube</i>)
1856 </td>
1857 </tr>
1858 </tbody>
1859 </table>
1860 <br>
1861 <ul>
1862 <li>Returns <i>true</i> if the given location or span is currently valid
1863 </li>
1864 <br>
1865 <li>Returns <i>false</i> if the object is empty, the location is out of bounds, or the span is out of bounds
1866 </li>
1867 <br>
1868 <li>
1869 Instances of <i>span(a,b)</i> can be replaced by:
1870 <ul>
1871 <li><i>span()</i> or <i>span::all</i>, to indicate the entire range</li>
1872 <li><i>span(a)</i>, to indicate a particular row, column or slice</li>
1873 </ul>
1874 </li>
1875 <br>
1876 <li>
1877 Examples:
1878 <ul>
1879 <pre>
1880 mat A = randu&lt;mat&gt;(4,5);
1881
1882 cout &lt;&lt; A.in_range(0,0) &lt;&lt; endl; // true
1883 cout &lt;&lt; A.in_range(3,4) &lt;&lt; endl; // true
1884 cout &lt;&lt; A.in_range(4,5) &lt;&lt; endl; // false
1885 </pre>
1886 </ul>
1887 </li>
1888 <br>
1889 <li>
1890 See also:
1891 <ul>
1892 <li><a href="#element_access">element access</a></li>
1893 <li><a href="#submat">submatrix views</a></li>
1894 <li><a href="#subcube">subcube views</a></li>
1895 <li><a href="#subfield">subfield views</a></li>
1896 <li><a href="#set_size">.set_size()</a></li>
1897 </ul>
1898 </li>
1899 <br>
1900 </ul>
1901 <hr class="greyline"><br>
1902
1903 <a name="is_empty"></a>
1904 <b>.is_empty()</b>
1905 <ul>
1906 <li>
1907 Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i> classes
1908 </li>
1909 <br>
1910 <li>Returns true if the object has no elements
1911 </li>
1912 <br>
1913 <li>Returns false if the object has one or more elements
1914 </li>
1915 <br>
1916 <li>
1917 Examples:
1918 <ul>
1919 <pre>
1920 mat A = randu&lt;mat&gt;(5,5);
1921 cout &lt;&lt; A.is_empty() &lt;&lt; endl;
1922
1923 A.reset();
1924 cout &lt;&lt; A.is_empty() &lt;&lt; endl;
1925 </pre>
1926 </ul>
1927 </li>
1928 <br>
1929 <li>
1930 See also:
1931 <ul>
1932 <li><a href="#is_square">.is_square()</a></li>
1933 <li><a href="#is_vec">.is_vec()</a></li>
1934 <li><a href="#reset">.reset()</a></li>
1935 </ul>
1936 </li>
1937 <br>
1938 </ul>
1939 <hr class="greyline"><br>
1940
1941 <a name="is_finite"></a>
1942 <b>.is_finite()</b>
1943 <ul>
1944 <li>
1945 Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i> classes
1946 </li>
1947 <br>
1948 <li>Returns <i>true</i> if all elements of the object are finite
1949 </li>
1950 <br>
1951 <li>Returns <i>false</i> if at least one of the elements of the object is non-finite (&plusmn;infinity or NaN)
1952 </li>
1953 <br>
1954 <li>
1955 Examples:
1956 <ul>
1957 <pre>
1958 mat A = randu&lt;mat&gt;(5,5);
1959 mat B = randu&lt;mat&gt;(5,5);
1960
1961 B(1,1) = math::nan()
1962
1963 cout &lt;&lt; A.is_finite() &lt;&lt; endl;
1964 cout &lt;&lt; B.is_finite() &lt;&lt; endl;
1965 </pre>
1966 </ul>
1967 </li>
1968 <br>
1969 <li>
1970 See also:
1971 <ul>
1972 <li><a href="#math_constants">math::nan()</a></li>
1973 <li><a href="#math_constants">math::inf()</a></li>
1974 <li><a href="#is_finite_standalone">is_finite()</a> (standalone function)</li>
1975 </ul>
1976 </li>
1977 <br>
1978 </ul>
1979 <hr class="greyline"><br>
1980
1981 <a name="is_square"></a>
1982 <b>.is_square()</b>
1983 <ul>
1984 <li>
1985 Member function of the <i>Mat</i> class
1986 </li>
1987 <br>
1988 <li>Returns <i>true</i> if the matrix is square, ie., number of rows is equal to the number of columns
1989 </li>
1990 <br>
1991 <li>Returns <i>false</i> if the matrix is not square
1992 </li>
1993 <br>
1994 <li>
1995 Examples:
1996 <ul>
1997 <pre>
1998 mat A = randu&lt;mat&gt;(5,5);
1999 mat B = randu&lt;mat&gt;(6,7);
2000
2001 cout &lt;&lt; A.is_square() &lt;&lt; endl;
2002 cout &lt;&lt; B.is_square() &lt;&lt; endl;
2003 </pre>
2004 </ul>
2005 </li>
2006 <br>
2007 <li>
2008 See also:
2009 <ul>
2010 <li><a href="#is_empty">.is_empty()</a></li>
2011 <li><a href="#is_vec">.is_vec()</a></li>
2012 </ul>
2013 </li>
2014 </ul>
2015 <br>
2016 <hr class="greyline"><br>
2017
2018 <a name="is_vec"></a>
2019 <b>.is_vec()</b>
2020 <br><b>.is_colvec()</b>
2021 <br><b>.is_rowvec()</b>
2022 <ul>
2023 <li>
2024 Member functions of the <i>Mat</i> class
2025 </li>
2026 <br>
2027
2028 <li>.is_vec():
2029 <ul>
2030 <li>Returns <i>true</i> if the matrix can be interpreted as a vector (either column or row vector)
2031 </li>
2032 <li>Returns <i>false</i> if the matrix does not have exactly one column or one row
2033 </li>
2034 </ul>
2035 </li>
2036 <br>
2037
2038 <li>.is_colvec():
2039 <ul>
2040 <li>Returns <i>true</i> if the matrix can be interpreted as a column vector
2041 </li>
2042 <li>Returns <i>false</i> if the matrix does not have exactly one column
2043 </li>
2044 </ul>
2045 </li>
2046 <br>
2047
2048 <li>.is_rowvec():
2049 <ul>
2050 <li>Returns <i>true</i> if the matrix can be interpreted as a row vector
2051 </li>
2052 <li>Returns <i>false</i> if the matrix does not have exactly one row
2053 </li>
2054 </ul>
2055 </li>
2056 <br>
2057
2058 <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)
2059 </li>
2060 <br>
2061 <li>
2062 Examples:
2063 <ul>
2064 <pre>
2065 mat A = randu&lt;mat&gt;(1,5);
2066 mat B = randu&lt;mat&gt;(5,1);
2067 mat C = randu&lt;mat&gt;(5,5);
2068
2069 cout &lt;&lt; A.is_vec() &lt;&lt; endl;
2070 cout &lt;&lt; B.is_vec() &lt;&lt; endl;
2071 cout &lt;&lt; C.is_vec() &lt;&lt; endl;
2072 </pre>
2073 </ul>
2074 </li>
2075 <br>
2076 <li>
2077 See also:
2078 <ul>
2079 <li><a href="#is_empty">.is_empty()</a></li>
2080 <li><a href="#is_square">.is_square()</a></li>
2081 </ul>
2082 </li>
2083 </ul>
2084 <br>
2085 <hr class="greyline"><br>
2086
2087 <a name="insert"></a>
2088 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
2089 <tbody>
2090 <tr>
2091 <td style="vertical-align: top;">
2092 <b>.insert_rows(&nbsp;</b>row_number, X<b>&nbsp;)</b>
2093 <br>
2094 <b>.insert_rows(&nbsp;</b>row_number, number_of_rows, set_to_zero&nbsp;=&nbsp;true<b>&nbsp;)</b>
2095 </td>
2096 <td style="vertical-align: top;"><br></td>
2097 <td style="vertical-align: top;">(member functions of <i>Mat</i> and <i>Col</i>)
2098 </td>
2099 </tr>
2100 <tr>
2101 <td>&nbsp;</td>
2102 </tr>
2103 <tr>
2104 <td style="vertical-align: top;">
2105 <b>.insert_cols(&nbsp;</b>col_number, X<b>&nbsp;)</b>
2106 <br>
2107 <b>.insert_cols(&nbsp;</b>col_number, number_of_cols, set_to_zero&nbsp;=&nbsp;true<b>&nbsp;)</b>
2108 </td>
2109 <td style="vertical-align: top;"><br></td>
2110 <td style="vertical-align: top;">(member functions of <i>Mat</i> and <i>Row</i>)
2111 </td>
2112 </tr>
2113 <tr>
2114 <td>&nbsp;</td>
2115 </tr>
2116 <tr>
2117 <td style="vertical-align: top;">
2118 <b>.insert_slices(&nbsp;</b>slice_number, X<b>&nbsp;)</b>
2119 <br>
2120 <b>.insert_slices(&nbsp;</b>slice_number, number_of_slices, set_to_zero&nbsp;=&nbsp;true<b>&nbsp;)</b>
2121 </td>
2122 <td style="vertical-align: top;"><br></td>
2123 <td style="vertical-align: top;">(member functions of <i>Cube</i>)
2124 </td>
2125 </tr>
2126 </tbody>
2127 </table>
2128 <br>
2129 <ul>
2130 <li>
2131 Functions with the <i>X</i> argument: insert a copy of X at the specified row/column/slice
2132 <ul>
2133 <li>if inserting rows, X must have the same number of columns as the recipient object</li>
2134 <li>if inserting columns, X must have the same number of rows as the recipient object</li>
2135 <li>if inserting slices, X must have the same number of rows and columns as the recipient object (ie. all slices must have the same size)</li>
2136 </ul>
2137 </li>
2138 <br>
2139 <li>
2140 Functions with the <i>number_of_...</i> argument: expand the object by creating new rows/columns/slices.
2141 By default, the new rows/columns/slices are set to zero.
2142 If <i>set_to_zero</i> is <i>false</i>, the memory used by the new rows/columns/slices will not be initialised.
2143 </li>
2144 <br>
2145 <li>
2146 Examples:
2147 <ul>
2148 <pre>
2149 mat A = randu&lt;mat&gt;(5,10);
2150 mat B = ones&lt;mat&gt;(5,2);
2151
2152 // at column 2, insert a copy of B;
2153 // A will now have 12 columns
2154 A.insert_cols(2, B);
2155
2156 // at column 1, insert 5 zeroed columns;
2157 // B will now have 7 columns
2158 B.insert_cols(1, 5);
2159 </pre>
2160 </ul>
2161 </li>
2162 <br>
2163 <li>
2164 See also:
2165 <ul>
2166 <li><a href="#shed">shed rows/columns/slices</a></li>
2167 <li><a href="#join">join rows/columns/slices</a></li>
2168 <li><a href="#resize_member">.resize()</a></li>
2169 <li><a href="#submat">submatrix views</a></li>
2170 <li><a href="#subcube">subcube views</a></li>
2171 </ul>
2172 </li>
2173 <br>
2174 </ul>
2175 <hr class="greyline"><br>
2176
2177 <a name="iterators_mat"></a>
2178 <b>iterators (matrices &amp; vectors)</b>
2179 <ul>
2180 <li>
2181 STL-style iterators and associated member functions of the <i>Mat</i>, <i>Col</i> and <i>Row</i> classes
2182 </li>
2183 <br>
2184 <li>
2185 iterator types:
2186 <br>
2187 <br>
2188 <ul>
2189 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
2190 <tbody>
2191 <tr>
2192 <td style="vertical-align: top;">
2193 <b>mat::iterator</b>
2194 <br>
2195 <b>vec::iterator</b>
2196 <br>
2197 <b>rowvec::iterator</b>
2198 </td>
2199 <td style="vertical-align: top;">&nbsp;<br>
2200 </td>
2201 <td style="vertical-align: top;">
2202 random access iterators, for read/write access to elements
2203 (which are stored column by column)
2204 </td>
2205 </tr>
2206 <tr>
2207 <td style="vertical-align: top;">
2208 &nbsp;
2209 </td>
2210 <td style="vertical-align: top;">&nbsp;<br>
2211 </td>
2212 <td style="vertical-align: top;">
2213 &nbsp;
2214 </td>
2215 </tr>
2216 <tr>
2217 <td style="vertical-align: top;">
2218 <b>mat::const_iterator</b>
2219 <br>
2220 <b>vec::const_iterator</b>
2221 <br>
2222 <b>rowvec::const_iterator</b>
2223 </td>
2224 <td style="vertical-align: top;">&nbsp;<br>
2225 </td>
2226 <td style="vertical-align: top;">
2227 random access iterators, for read-only access to elements
2228 (which are stored column by column)
2229 </td>
2230 </tr>
2231 <tr>
2232 <td style="vertical-align: top;">
2233 &nbsp;
2234 </td>
2235 <td style="vertical-align: top;">&nbsp;<br>
2236 </td>
2237 <td style="vertical-align: top;">
2238 &nbsp;
2239 </td>
2240 </tr>
2241 <tr>
2242 <td style="vertical-align: top;">
2243 <b>mat::col_iterator</b>
2244 <br>
2245 <b>vec::col_iterator</b>
2246 <br>
2247 <b>rowvec::col_iterator</b>
2248 </td>
2249 <td style="vertical-align: top;">&nbsp;<br>
2250 </td>
2251 <td style="vertical-align: top;">
2252 random access iterators, for read/write access to the elements of a specific column
2253 </td>
2254 </tr>
2255 <tr>
2256 <td style="vertical-align: top;">
2257 &nbsp;
2258 </td>
2259 <td style="vertical-align: top;">&nbsp;<br>
2260 </td>
2261 <td style="vertical-align: top;">
2262 &nbsp;
2263 </td>
2264 </tr>
2265 <tr>
2266 <td style="vertical-align: top;">
2267 <b>mat::const_col_iterator</b>
2268 <br>
2269 <b>vec::const_col_iterator</b>
2270 <br>
2271 <b>rowvec::const_col_iterator</b>
2272 </td>
2273 <td style="vertical-align: top;">&nbsp;<br>
2274 </td>
2275 <td style="vertical-align: top;">
2276 random access iterators, for read-only access to the elements of a specific column
2277 </td>
2278 </tr>
2279 <tr>
2280 <td style="vertical-align: top;">
2281 &nbsp;
2282 </td>
2283 <td style="vertical-align: top;">&nbsp;<br>
2284 </td>
2285 <td style="vertical-align: top;">
2286 &nbsp;
2287 </td>
2288 </tr>
2289 <tr>
2290 <td style="vertical-align: top;">
2291 <b>mat::row_iterator</b>
2292 </td>
2293 <td style="vertical-align: top;">&nbsp;<br>
2294 </td>
2295 <td style="vertical-align: top;">
2296 rudimentary forward iterator, for read/write access to the elements of a specific row
2297 </td>
2298 </tr>
2299 <tr>
2300 <td style="vertical-align: top;">
2301 &nbsp;
2302 </td>
2303 <td style="vertical-align: top;">&nbsp;<br>
2304 </td>
2305 <td style="vertical-align: top;">
2306 &nbsp;
2307 </td>
2308 </tr>
2309 <tr>
2310 <td style="vertical-align: top;">
2311 <b>mat::const_row_iterator</b>
2312 </td>
2313 <td style="vertical-align: top;">&nbsp;<br>
2314 </td>
2315 <td style="vertical-align: top;">
2316 rudimentary forward iterator, for read-only access to the elements of a specific row
2317 </td>
2318 </tr>
2319 <tr>
2320 <td style="vertical-align: top;">
2321 &nbsp;
2322 </td>
2323 <td style="vertical-align: top;">&nbsp;<br>
2324 </td>
2325 <td style="vertical-align: top;">
2326 &nbsp;
2327 </td>
2328 </tr>
2329 <tr>
2330 <td style="vertical-align: top;">
2331 <b>vec::row_iterator</b>
2332 <br>
2333 <b>rowvec::row_iterator</b>
2334 </td>
2335 <td style="vertical-align: top;">&nbsp;<br>
2336 </td>
2337 <td style="vertical-align: top;">
2338 random access iterators, for read/write access to the elements of a specific row
2339 </td>
2340 </tr>
2341 <tr>
2342 <td style="vertical-align: top;">
2343 &nbsp;
2344 </td>
2345 <td style="vertical-align: top;">&nbsp;<br>
2346 </td>
2347 <td style="vertical-align: top;">
2348 &nbsp;
2349 </td>
2350 </tr>
2351 <tr>
2352 <td style="vertical-align: top;">
2353 <b>vec::const_row_iterator</b>
2354 <br>
2355 <b>rowvec::const_row_iterator</b>
2356 </td>
2357 <td style="vertical-align: top;">&nbsp;<br>
2358 </td>
2359 <td style="vertical-align: top;">
2360 random access iterators, for read-only access to the elements of a specific row
2361 </td>
2362 </tr>
2363 </tbody>
2364 </table>
2365 </ul>
2366 </li>
2367 <br>
2368 <br>
2369 <li>
2370 Member functions:
2371 <br>
2372 <br>
2373 <ul>
2374 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
2375 <tbody>
2376 <tr>
2377 <td style="vertical-align: top;">
2378 <b>.begin()</b>
2379 </td>
2380 <td style="vertical-align: top;">&nbsp;<br>
2381 </td>
2382 <td style="vertical-align: top;">
2383 iterator referring to the first element
2384 </td>
2385 </tr>
2386 <tr>
2387 <td style="vertical-align: top;">
2388 <b>.end()</b>
2389 </td>
2390 <td style="vertical-align: top;">&nbsp;<br>
2391 </td>
2392 <td style="vertical-align: top;">
2393 iterator referring to the <i>past-the-end</i> element
2394 </td>
2395 </tr>
2396 <tr>
2397 <td>
2398 &nbsp;
2399 </td>
2400 </tr>
2401 <tr>
2402 <td style="vertical-align: top;">
2403 <b>.begin_row(</b><i>row_number</i><b>)</b>
2404 </td>
2405 <td style="vertical-align: top;">&nbsp;<br>
2406 </td>
2407 <td style="vertical-align: top;">
2408 iterator referring to the first element of the specified row
2409 </td>
2410 </tr>
2411 <tr>
2412 <td style="vertical-align: top;">
2413 <b>.end_row(</b><i>row_number</i><b>)</b>
2414 </td>
2415 <td style="vertical-align: top;">&nbsp;<br>
2416 </td>
2417 <td style="vertical-align: top;">
2418 iterator referring to the <i>past-the-end</i> element of the specified row
2419 </td>
2420 </tr>
2421 <tr>
2422 <td>
2423 &nbsp;
2424 </td>
2425 </tr>
2426 <tr>
2427 <td style="vertical-align: top;">
2428 <b>.begin_col(</b><i>col_number</i><b>)</b>
2429 </td>
2430 <td style="vertical-align: top;">&nbsp;<br>
2431 </td>
2432 <td style="vertical-align: top;">
2433 iterator referring to the first element of the specified column
2434 </td>
2435 </tr>
2436 <tr>
2437 <td style="vertical-align: top;">
2438 <b>.end_col(</b><i>col_number</i><b>)</b>
2439 </td>
2440 <td style="vertical-align: top;">&nbsp;<br>
2441 </td>
2442 <td style="vertical-align: top;">
2443 iterator referring to the <i>past-the-end</i> element of the specified column
2444 </td>
2445 </tr>
2446 </tbody>
2447 </table>
2448 </ul>
2449 </li>
2450 <br>
2451 <br>
2452 <li>
2453 Examples:
2454 <ul>
2455 <pre>
2456 mat X = randu&lt;mat&gt;(5,5);
2457
2458
2459 mat::iterator a = X.begin();
2460 mat::iterator b = X.end();
2461
2462 for(mat::iterator i=a; i!=b; ++i)
2463 {
2464 cout &lt;&lt; *i &lt;&lt; endl;
2465 }
2466
2467
2468 mat::col_iterator c = X.begin_col(1); // start of column 1
2469 mat::col_iterator d = X.end_col(3); // end of column 3
2470
2471 for(mat::col_iterator i=c; i!=d; ++i)
2472 {
2473 cout &lt;&lt; *i &lt;&lt; endl;
2474 (*i) = 123.0;
2475 }
2476 </pre>
2477 </ul>
2478 </li>
2479 <br>
2480 <li>
2481 See also:
2482 <ul>
2483 <li><a href="#stl_container_fns">STL container functions</a></li>
2484 <li><a href="http://cplusplus.com/reference/std/iterator/">iterator at cplusplus.com</a></li>
2485 <li><a href="#element_access">element access</a></li>
2486 </ul>
2487 </li>
2488 <br>
2489 </ul>
2490 <hr class="greyline"><br>
2491
2492 <a name="iterators_cube"></a>
2493 <b>iterators (cubes)</b>
2494 <ul>
2495 <li>
2496 STL-style iterators and associated member functions of the <i>Cube</i> class
2497 </li>
2498 <br>
2499 <li>
2500 iterator types:
2501 <br>
2502 <br>
2503 <ul>
2504 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
2505 <tbody>
2506 <tr>
2507 <td style="vertical-align: top;">
2508 <b>cube::iterator</b>
2509 </td>
2510 <td style="vertical-align: top;">&nbsp;<br>
2511 </td>
2512 <td style="vertical-align: top;">
2513 random access iterator, for read/write access to elements;
2514 the elements are ordered slice by slice;
2515 the elements within each slice are ordered column by column
2516 </td>
2517 </tr>
2518 <tr>
2519 <td style="vertical-align: top;">
2520 &nbsp;
2521 </td>
2522 <td style="vertical-align: top;">&nbsp;<br>
2523 </td>
2524 <td style="vertical-align: top;">
2525 &nbsp;
2526 </td>
2527 </tr>
2528 <tr>
2529 <td style="vertical-align: top;">
2530 <b>cube::const_iterator</b>
2531 </td>
2532 <td style="vertical-align: top;">&nbsp;<br>
2533 </td>
2534 <td style="vertical-align: top;">
2535 random access iterators, for read-only access to elements
2536 </td>
2537 </tr>
2538 <tr>
2539 <td style="vertical-align: top;">
2540 &nbsp;
2541 </td>
2542 <td style="vertical-align: top;">&nbsp;<br>
2543 </td>
2544 <td style="vertical-align: top;">
2545 &nbsp;
2546 </td>
2547 </tr>
2548 <tr>
2549 <td style="vertical-align: top;">
2550 <b>cube::slice_iterator</b>
2551 </td>
2552 <td style="vertical-align: top;">&nbsp;<br>
2553 </td>
2554 <td style="vertical-align: top;">
2555 random access iterator, for read/write access to the elements of a particular slice;
2556 the elements are ordered column by column
2557 </td>
2558 </tr>
2559 <tr>
2560 <td style="vertical-align: top;">
2561 &nbsp;
2562 </td>
2563 <td style="vertical-align: top;">&nbsp;<br>
2564 </td>
2565 <td style="vertical-align: top;">
2566 &nbsp;
2567 </td>
2568 </tr>
2569 <tr>
2570 <td style="vertical-align: top;">
2571 <b>cube::const_slice_iterator</b>
2572 </td>
2573 <td style="vertical-align: top;">&nbsp;<br>
2574 </td>
2575 <td style="vertical-align: top;">
2576 random access iterators, for read-only access to the elements of a particular slice
2577 </td>
2578 </tr>
2579 </tbody>
2580 </table>
2581 </ul>
2582 </li>
2583 <br>
2584 <br>
2585 <li>
2586 Member functions:
2587 <br>
2588 <br>
2589 <ul>
2590 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
2591 <tbody>
2592 <tr>
2593 <td style="vertical-align: top;">
2594 <b>.begin()</b>
2595 </td>
2596 <td style="vertical-align: top;">&nbsp;<br>
2597 </td>
2598 <td style="vertical-align: top;">
2599 iterator referring to the first element
2600 </td>
2601 </tr>
2602 <tr>
2603 <td style="vertical-align: top;">
2604 <b>.end()</b>
2605 </td>
2606 <td style="vertical-align: top;">&nbsp;<br>
2607 </td>
2608 <td style="vertical-align: top;">
2609 iterator referring to the <i>past-the-end</i> element
2610 </td>
2611 </tr>
2612 <tr>
2613 <td>
2614 &nbsp;
2615 </td>
2616 </tr>
2617 <tr>
2618 <td style="vertical-align: top;">
2619 <b>.begin_slice(</b><i>slice_number</i><b>)</b>
2620 </td>
2621 <td style="vertical-align: top;">&nbsp;<br>
2622 </td>
2623 <td style="vertical-align: top;">
2624 iterator referring to the first element of the specified slice
2625 </td>
2626 </tr>
2627 <tr>
2628 <td style="vertical-align: top;">
2629 <b>.end_slice(</b><i>slice_number</i><b>)</b>
2630 </td>
2631 <td style="vertical-align: top;">&nbsp;<br>
2632 </td>
2633 <td style="vertical-align: top;">
2634 iterator referring to the <i>past-the-end</i> element of the specified slice
2635 </td>
2636 </tr>
2637 </tbody>
2638 </table>
2639 </ul>
2640 </li>
2641 <br>
2642 <br>
2643 <li>
2644 Examples:
2645 <ul>
2646 <pre>
2647 cube X = randu&lt;cube&gt;(2,3,4);
2648
2649
2650 cube::iterator a = X.begin();
2651 cube::iterator b = X.end();
2652
2653 for(cube::iterator i=a; i!=b; ++i)
2654 {
2655 cout &lt;&lt; *i &lt;&lt; endl;
2656 }
2657
2658
2659 cube::slice_iterator c = X.begin_slice(1); // start of slice 1
2660 cube::slice_iterator d = X.end_slice(2); // end of slice 2
2661
2662 for(cube::slice_iterator i=c; i!=d; ++i)
2663 {
2664 cout &lt;&lt; *i &lt;&lt; endl;
2665 (*i) = 123.0;
2666 }
2667 </pre>
2668 </ul>
2669 </li>
2670 <br>
2671 <li>
2672 See also:
2673 <ul>
2674 <li><a href="http://cplusplus.com/reference/std/iterator/">iterator at cplusplus.com</a></li>
2675 <li><a href="#element_access">element access</a></li>
2676 </ul>
2677 </li>
2678 <br>
2679 </ul>
2680 <hr class="greyline"><br>
2681
2682 <a name="memptr"></a>
2683 <b>.memptr()</b>
2684 <ul>
2685 <li>
2686 Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i> classes
2687 </li>
2688 <br>
2689 <li>
2690 Obtain a raw pointer to the memory used for storing elements. Not recommended for use unless you know what you're doing!
2691 </li>
2692 <br>
2693 <li>
2694 The function can be used for interfacing with libraries such as <a href="http://www.fftw.org/">FFTW</a>
2695 </li>
2696 <br>
2697 <li>
2698 As soon as the size of the matrix/vector/cube is changed, the pointer is no longer valid
2699 </li>
2700 <br>
2701 <li>
2702 Data for matrices is stored in a column-by-column order
2703 </li>
2704 <br>
2705 <li>
2706 Data for cubes is stored in a slice-by-slice (matrix-by-matrix) order
2707 </li>
2708 <br>
2709 <li>
2710 Examples:
2711 <ul>
2712 <pre>
2713 mat A = randu&lt;mat&gt;(5,5);
2714 const mat B = randu&lt;mat&gt;(5,5);
2715
2716 double* A_mem = A.memptr();
2717 const double* B_mem = B.memptr();
2718 </pre>
2719 </ul>
2720 </li>
2721 <br>
2722 <li>
2723 See also:
2724 <ul>
2725 <li><a href="#colptr">.colptr()</a></li>
2726 <li><a href="#iterators_mat">iterators (matrices)</a></li>
2727 <li><a href="#iterators_cube">iterators (cubes)</a></li>
2728 <li><a href="#adv_constructors_mat">advanced constructors (matrices)</a></li>
2729 <li><a href="#adv_constructors_cube">advanced constructors (cubes)</a></li>
2730 </ul>
2731 </li>
2732 <br>
2733 </ul>
2734 <hr class="greyline"><br>
2735
2736 <a name="min_and_max_member"></a>
2737 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
2738 <tbody>
2739 <tr>
2740 <td style="vertical-align: top;"><b>.min()</b></td>
2741 <td style="vertical-align: top;"><br>
2742 </td>
2743 <td style="vertical-align: top;">(member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
2744 </td>
2745 </tr>
2746 <tr>
2747 <td style="vertical-align: top;"><b>.max()</b></td>
2748 <td style="vertical-align: top;"><br>
2749 </td>
2750 <td style="vertical-align: top;">&nbsp;
2751 </td>
2752 </tr>
2753 <tr>
2754 <td style="vertical-align: top;">&nbsp;</td>
2755 <td style="vertical-align: top;"><br>
2756 </td>
2757 <td style="vertical-align: top;">&nbsp;
2758 </td>
2759 </tr>
2760 <tr>
2761 <td style="vertical-align: top;"><b>.min(</b>&nbsp;index_of_min_val&nbsp;<b>)</b></td>
2762 <td style="vertical-align: top;"><br>
2763 </td>
2764 <td style="vertical-align: top;">(member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
2765 </td>
2766 </tr>
2767 <tr>
2768 <td style="vertical-align: top;"><b>.max(</b>&nbsp;index_of_max_val&nbsp;<b>)</b></td>
2769 <td style="vertical-align: top;"><br>
2770 </td>
2771 <td style="vertical-align: top;">&nbsp;
2772 </td>
2773 </tr>
2774 <tr>
2775 <td style="vertical-align: top;">&nbsp;</td>
2776 <td style="vertical-align: top;"><br>
2777 </td>
2778 <td style="vertical-align: top;">&nbsp;
2779 </td>
2780 </tr>
2781 <tr>
2782 <td style="vertical-align: top;"><b>.min(</b>&nbsp;row_of_min_val<b>,</b> col_of_min_val&nbsp;<b>)</b></td>
2783 <td style="vertical-align: top;"><br>
2784 </td>
2785 <td style="vertical-align: top;">(member functions of <i>Mat</i>)
2786 </td>
2787 </tr>
2788 <tr>
2789 <td style="vertical-align: top;"><b>.max(</b>&nbsp;row_of_max_val<b>,</b> col_of_max_val&nbsp;<b>)</b></td>
2790 <td style="vertical-align: top;"><br>
2791 </td>
2792 <td style="vertical-align: top;">&nbsp;
2793 </td>
2794 </tr>
2795 <tr>
2796 <td style="vertical-align: top;">&nbsp;</td>
2797 <td style="vertical-align: top;"><br>
2798 </td>
2799 <td style="vertical-align: top;">&nbsp;
2800 </td>
2801 </tr>
2802 <tr>
2803 <td style="vertical-align: top;"><b>.min(</b>&nbsp;row_of_min_val<b>,</b> col_of_min_val<b>,</b> slice_of_min_val&nbsp;<b>)</b></td>
2804 <td style="vertical-align: top;"><br>
2805 </td>
2806 <td style="vertical-align: top;">(member functions of <i>Cube</i>)
2807 </td>
2808 </tr>
2809 <tr>
2810 <td style="vertical-align: top;"><b>.max(</b>&nbsp;row_of_max_val<b>,</b> col_of_max_val<b>,</b> slice_of_max_val&nbsp;<b>)</b></td>
2811 <td style="vertical-align: top;"><br>
2812 </td>
2813 <td style="vertical-align: top;">&nbsp;
2814 </td>
2815 </tr>
2816 </tbody>
2817 </table>
2818 <ul>
2819 <br>
2820 <li>
2821 Without arguments: return the extremum value of an object
2822 </li>
2823 <br>
2824 <li>
2825 With one or more arguments: return the extremum value of an object and store the location of the extremum value in the provided variable(s)
2826 </li>
2827 <br>
2828 <li>
2829 The provided variables must be of type <a href="#uword">uword</a>.
2830 </li>
2831 <br>
2832 <li>
2833 Examples:
2834 <ul>
2835 <pre>
2836 vec v = randu&lt;vec&gt;(10);
2837
2838 cout &lt;&lt; "min value is " &lt;&lt; v.min() &lt;&lt; endl;
2839
2840
2841 uword index;
2842 double min_val = v.min(index);
2843
2844 cout &lt;&lt; "index of min value is " &lt;&lt; index &lt;&lt; endl;
2845
2846
2847 mat A = randu&lt;mat&gt;(5,5);
2848
2849 uword row;
2850 uword col;
2851 double min_val2 = A.max(row,col);
2852
2853 cout &lt;&lt; "max value is at " &lt;&lt; row &lt;&lt; ',' &lt;&lt; col &lt;&lt; endl;
2854 </pre>
2855 </ul>
2856 </li>
2857 <br>
2858 <li>
2859 See also:
2860 <ul>
2861 <li><a href="#min_and_max">min() &amp; max()</a> (standalone functions)</li>
2862 <li><a href="#running_stat">running_stat</a></li>
2863 <li><a href="#running_stat_vec">running_stat_vec</a></li>
2864 </ul>
2865 </li>
2866 <br>
2867 </ul>
2868 <hr class="greyline"><br>
2869
2870 <a name="ones_member"></a>
2871 <b>.ones()</b>
2872 <br><b>.ones(n_elem)</b>
2873 <br><b>.ones(n_rows, n_cols)</b>
2874 <br><b>.ones(n_rows, n_cols, n_slices)</b>
2875 <ul>
2876 <li>
2877 Set the elements of an object to one, optionally first resizing to specified dimensions
2878 </li>
2879 <br>
2880 <li>
2881 <i>.ones()</i> and <i>.ones(n_elem)</i> are member functions of <i>Col</i> and <i>Row</i>
2882 </li>
2883 <br>
2884 <li>
2885 <i>.ones()</i> and <i>.ones(n_rows, n_cols)</i> are member functions of <i>Mat</i>
2886 </li>
2887 <br>
2888 <li>
2889 <i>.ones()</i> and <i>.ones(n_rows, n_cols, n_slices)</i> are member functions of <i>Cube</i>
2890 </li>
2891 <br>
2892 <li>
2893 Examples:
2894 <ul>
2895 <pre>
2896 mat A = randu&lt;mat&gt;(5,10);
2897 A.ones(); // sets all elements to one
2898 A.ones(10,20); // sets the size to 10 rows and 20 columns
2899 // followed by setting all elements to one
2900 </pre>
2901 </ul>
2902 </li>
2903 <br>
2904 <li>
2905 See also:
2906 <ul>
2907 <li><a href="#ones_standalone">ones()</a> (standalone function)</li>
2908 <li><a href="#zeros_member">.zeros()</a></li>
2909 <li><a href="#fill">.fill()</a></li>
2910 </ul>
2911 </li>
2912 <br>
2913 </ul>
2914 <hr class="greyline"><br>
2915
2916 <a name="operators"></a>
2917 <b>operators: &nbsp; + &nbsp; - &nbsp; * &nbsp; / &nbsp; % &nbsp; == &nbsp; != &nbsp; &lt;= &nbsp; &gt;= &nbsp; &lt; &nbsp; &gt;</b>
2918 <ul>
2919 <li>
2920 Overloaded operators for <i>mat</i>, <i>vec</i>, <i>rowvec</i> and <i>cube</i> classes
2921 </li>
2922 <br>
2923 <li>
2924 Meanings:
2925 <br>
2926 <br>
2927 <ul>
2928 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
2929 <tbody>
2930 <tr>
2931 <td style="vertical-align: top;"><b>+</b></td>
2932 <td style="vertical-align: top;">&nbsp;&nbsp;&nbsp;<br>
2933 </td>
2934 <td style="vertical-align: top;">Addition of two objects</td>
2935 </tr>
2936 <tr>
2937 <td style="vertical-align: top;"><b>-</b></td>
2938 <td style="vertical-align: top;"><br>
2939 </td>
2940 <td style="vertical-align: top;">Subtraction of one object from another or negation of an object</td>
2941 </tr>
2942 <tr>
2943 <td style="vertical-align: top;"><b>/</b></td>
2944 <td style="vertical-align: top;"><br>
2945 </td>
2946 <td style="vertical-align: top;">Element-wise division of an object by another object or a scalar</td>
2947 </tr>
2948 <tr>
2949 <td style="vertical-align: top;"><b>*</b></td>
2950 <td style="vertical-align: top;"><br>
2951 </td>
2952 <td style="vertical-align: top;">Matrix multiplication of two objects; not applicable to the <i>cube</i> class unless multiplying a cube by a scalar</td>
2953 </tr>
2954 <tr>
2955 <td style="vertical-align: top;"><b>%</b></td>
2956 <td style="vertical-align: top;"><br>
2957 </td>
2958 <td style="vertical-align: top;"><a name="schur_product"></a>Schur product: element-wise multiplication of two objects</td>
2959 </tr>
2960 <tr>
2961 <td style="vertical-align: top;"><b>==</b></td>
2962 <td style="vertical-align: top;"><br>
2963 </td>
2964 <td style="vertical-align: top;">Element-wise equality evaluation of two objects; generates a matrix of type <i>umat</i> with entries that indicate whether at a given position the two elements from the two objects are equal (1) or not equal (0)</td>
2965 </tr>
2966 <tr>
2967 <td style="vertical-align: top;"><b>!=</b></td>
2968 <td style="vertical-align: top;"><br>
2969 </td>
2970 <td style="vertical-align: top;">Element-wise non-equality evaluation of two objects</td>
2971 </tr>
2972 <tr>
2973 <td style="vertical-align: top;"><b>&gt;=</b></td>
2974 <td style="vertical-align: top;"><br>
2975 </td>
2976 <td style="vertical-align: top;">As for ==, but the check is for "greater than or equal to"</td>
2977 </tr>
2978 <tr>
2979 <td style="vertical-align: top;"><b>&lt;=</b></td>
2980 <td style="vertical-align: top;"><br>
2981 </td>
2982 <td style="vertical-align: top;">As for ==, but the check is for "less than or equal to"</td>
2983 </tr>
2984 <tr>
2985 <td style="vertical-align: top;"><b>&gt;</b></td>
2986 <td style="vertical-align: top;"><br>
2987 </td>
2988 <td style="vertical-align: top;">As for ==, but the check is for "greater than"</td>
2989 </tr>
2990 <tr>
2991 <td style="vertical-align: top;"><b>&lt;</b></td>
2992 <td style="vertical-align: top;"><br>
2993 </td>
2994 <td style="vertical-align: top;">As for ==, but the check is for "less than"</td>
2995 </tr>
2996 </tbody>
2997 </table>
2998 </ul>
2999 </li>
3000 <br>
3001 <li>
3002 A <i>std::logic_error</i> exception is thrown if incompatible object sizes are used
3003 </li>
3004 <br>
3005 <li>
3006 If the +, - and % operators are chained, Armadillo will try to avoid the generation of temporaries;
3007 no temporaries are generated if all given objects are of the same type and size
3008 </li>
3009 <br>
3010 <li>
3011 If the * operator is chained, Armadillo will try to find an efficient ordering of the matrix multiplications
3012 </li>
3013 <br>
3014 <li>
3015 <b>Caveat:</b> operators involving an equality comparison (ie., ==, !=, &gt;=, &lt;=)
3016 may not work as expected for floating point element types (ie., <i>float</i>, <i>double</i>)
3017 due to the necessarily limited precision of these types;
3018 in other words, these operators are (in general) not recommended for matrices of type <i>mat</i> or <i>fmat</i>
3019 </li>
3020 <br>
3021 <br>
3022 <li>
3023 Examples:
3024 <ul>
3025 <pre>
3026 mat A = randu&lt;mat&gt;(5,10);
3027 mat B = randu&lt;mat&gt;(5,10);
3028 mat C = randu&lt;mat&gt;(10,5);
3029
3030 mat P = A + B;
3031 mat Q = A - B;
3032 mat R = -B;
3033 mat S = A / 123.0;
3034 mat T = A % B;
3035 mat U = A * C;
3036
3037 // V is constructed without temporaries
3038 mat V = A + B + A + B;
3039
3040 imat AA = "1 2 3; 4 5 6; 7 8 9;";
3041 imat BB = "3 2 1; 6 5 4; 9 8 7;";
3042
3043 // compare elements
3044 umat ZZ = (AA >= BB);
3045 </pre>
3046 </ul>
3047 </li>
3048 <br>
3049 <li>
3050 See also:
3051 <ul>
3052 <li><a href="#accu">accu()</a></li>
3053 <li><a href="#as_scalar">as_scalar()</a></li>
3054 <li><a href="#find">find()</a></li>
3055 </ul>
3056 </li>
3057 <br>
3058 </ul>
3059 <hr class="greyline"><br>
3060
3061 <a name="print"></a>
3062 <b>.print(header="")</b>
3063 <br><b>.print(stream, header="")</b>
3064 <ul>
3065 <li>
3066 Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i>
3067 </li>
3068 <br>
3069 <li>
3070 The first form prints the contents of an object to the <i>std::cout</i> stream, with an optional header line
3071 </li>
3072 <br>
3073 <li>
3074 The second form prints to a user specified stream
3075 </li>
3076 <br>
3077 <li>
3078 It's also possible to print objects using the &lt;&lt; stream operator
3079 </li>
3080 <br>
3081 <li>
3082 Elements of a field can only be printed if there is an associated <i>operator&lt;&lt;</i> function defined
3083 </li>
3084 <br>
3085 <li>
3086 Examples:
3087 <ul>
3088 <pre>
3089 mat A = randu&lt;mat&gt;(5,5);
3090 mat B = randu&lt;mat&gt;(6,6);
3091
3092 A.print();
3093
3094 // print a transposed version of A
3095 A.t().print();
3096
3097 // "B:" is the optional header line
3098 B.print("B:");
3099
3100 cout &lt;&lt; A &lt;&lt; endl;
3101 cout &lt;&lt; "B:" &lt;&lt; endl &lt;&lt; B &lt;&lt; endl;
3102 </pre>
3103 </ul>
3104 </li>
3105 <br>
3106 <li>
3107 See also:
3108 <ul>
3109 <li><a href="#raw_print">.raw_print()</a></li>
3110 <li><a href="#save_load_mat">saving &amp; loading matrices</a></li>
3111 <li><a href="#element_initialisation">initialising elements</a></li>
3112 <li><a href="#logging">logging of errors and warnings</a></li>
3113 </ul>
3114 </li>
3115 <br>
3116 </ul>
3117 <hr class="greyline"><br>
3118
3119 <a name="raw_print"></a>
3120 <b>.raw_print(header="")</b>
3121 <br><b>.raw_print(stream, header="")</b>
3122 <ul>
3123 <li>
3124 Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i>
3125 </li>
3126 <br>
3127 <li>
3128 Similar to the <a href="#print">.print()</a> member function,
3129 with the difference being that no formatting of the output is done -- ie. the user can set the stream's parameters such as precision, cell width, etc.
3130 </li>
3131 <br>
3132 <li>
3133 If the cell width is set to zero, a space is printed between the elements
3134 </li>
3135 <br>
3136 <li>
3137 Examples:
3138 <ul>
3139 <pre>
3140 mat A = randu&lt;mat&gt;(5,5);
3141
3142 cout.precision(11);
3143 cout.setf(ios::fixed);
3144
3145 A.raw_print(cout, "A =");
3146 </pre>
3147 </ul>
3148 </li>
3149 </ul>
3150 <br>
3151 <hr class="greyline"><br>
3152
3153 <a name="randu_randn_member"></a>
3154 <b>.randu()</b>
3155 <br><b>.randu(n_elem)</b>
3156 <br><b>.randu(n_rows, n_cols)</b>
3157 <br><b>.randu(n_rows, n_cols, n_slices)</b>
3158 <br>
3159 <br>
3160 <b>.randn()</b>
3161 <br><b>.randn(n_elem)</b>
3162 <br><b>.randn(n_rows, n_cols)</b>
3163 <br><b>.randn(n_rows, n_cols, n_slices)</b>
3164 <ul>
3165 <li>
3166 Fill an object with random values, optionally first resizing to specified dimensions
3167 </li>
3168 <br>
3169 <li><i>.randu()</i> uses a uniform distribution in the [0,1] interval
3170 </li>
3171 <br>
3172 <li><i>.randn()</i> uses a normal/Gaussian distribution with zero mean and unit variance
3173 </li>
3174 <br>
3175 <li>
3176 To change the seed, use the <a href="http://cplusplus.com/reference/clibrary/cstdlib/srand/">std::srand()</a> function
3177 </li>
3178 <br>
3179 <li>
3180 Examples:
3181 <ul>
3182 <pre>
3183 mat A(4,5);
3184 A.randu();
3185
3186 mat B;
3187 B.randu(6,7);
3188 </pre>
3189 </ul>
3190 </li>
3191 <br>
3192 <li>
3193 See also:
3194 <ul>
3195 <li><a href="#randu_randn_standalone">randu() &amp; randn()</a> (standalone functions)</li>
3196 <li><a href="#fill">.fill()</a></li>
3197 <li><a href="#ones_member">.ones()</a></li>
3198 <li><a href="#zeros_member">.zeros()</a></li>
3199 <li><a href="http://cplusplus.com/reference/clibrary/cstdlib/srand/">std::srand()</a></li>
3200 </ul>
3201 </li>
3202 <br>
3203 </ul>
3204 <hr class="greyline"><br>
3205
3206 <a name="reset"></a>
3207 <b>
3208 .reset()
3209 </b>
3210 <ul>
3211 <li>
3212 Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>field</i>
3213 </li>
3214 <br>
3215 <li>
3216 Causes an object to have no elements
3217 </li>
3218 <br>
3219 <li>
3220 Examples:
3221 <ul>
3222 <pre>
3223 mat A = randu&lt;mat&gt;(5, 5);
3224 A.reset();
3225 </pre>
3226 </ul>
3227 </li>
3228 <br>
3229 <li>See also:
3230 <ul>
3231 <li><a href="#set_size">.set_size()</a></li>
3232 <li><a href="#is_empty">.is_empty()</a></li>
3233 <li><a href="#zeros_member">.zeros()</a></li>
3234 </ul>
3235 </li>
3236 </ul>
3237 <br>
3238 <hr class="greyline"><br>
3239
3240 <a name="reshape_member"></a>
3241 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
3242 <tbody>
3243 <tr>
3244 <td style="vertical-align: top;"><b>.reshape(n_rows, n_cols, dim=0)</b></td>
3245 <td style="vertical-align: top;"><br>
3246 </td>
3247 <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>)
3248 </td>
3249 </tr>
3250 <tr>
3251 <td style="vertical-align: top;"><b>.reshape(n_rows, n_cols, n_slices, dim=0)</b></td>
3252 <td style="vertical-align: top;"><br>
3253 </td>
3254 <td style="vertical-align: top;">(member function of <i>Cube</i>)
3255 </td>
3256 </tr>
3257 </tbody>
3258 </table>
3259 <br>
3260 <ul>
3261 <li>
3262 Recreate the object according to given size specifications,
3263 with the elements taken from the previous version of the object,
3264 either column-wise (dim=0) or row-wise (dim=1);
3265 the elements in the generated object are placed column-wise (ie. the first column is filled up before filling the second column)
3266 </li>
3267 <br>
3268 <li>
3269 The layout of the elements in the recreated object will be different to the layout in the previous version of the object
3270 </li>
3271 <br>
3272 <li>
3273 This function can be used to vectorise a matrix (ie. concatenate all the columns or rows)
3274 </li>
3275 <br>
3276 <li>
3277 The new total number of elements (according to the specified size) doesn't have to be the same as the previous total number of elements in the object
3278 </li>
3279 <br>
3280 <li>
3281 If the total number of elements in the previous version of the object is less than the specified size,
3282 the extra elements in the recreated object are set to zero
3283 </li>
3284 <br>
3285 <li>
3286 If the total number of elements in the previous version of the object is greater than the specified size,
3287 only a subset of the elements is taken
3288 </li>
3289 <br>
3290 <li>
3291 <b>Caveat:</b>
3292 .reshape() is slower than <a href="#set_size">.set_size()</a>, which doesn't preserve data
3293 </li>
3294 <br>
3295 <li>
3296 <b>Caveat:</b>
3297 if you wish to grow/shrink the object while preserving the elements <b>as well as</b> the layout of the elements,
3298 use <a href="#resize_member">.resize()</a> instead
3299 </li>
3300 <br>
3301 <li>
3302 Examples:
3303 <ul>
3304 <pre>
3305 mat A = randu&lt;mat&gt;(4,5);
3306 A.reshape(5,4);
3307
3308 // vectorise A into a column vector:
3309 A.reshape(A.n_elem, 1);
3310 </pre>
3311 </ul>
3312 </li>
3313 <br>
3314 <li>See also:
3315 <ul>
3316 <li><a href="#resize_member">.resize()</a></li>
3317 <li><a href="#set_size">.set_size()</a></li>
3318 <li><a href="#reset">.reset()</a></li>
3319 <li><a href="#reshape">reshape()</a> (standalone function)</li>
3320 </ul>
3321 </li>
3322 </ul>
3323 <br>
3324 <hr class="greyline"><br>
3325
3326 <a name="resize_member"></a>
3327 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
3328 <tbody>
3329 <tr>
3330 <td style="vertical-align: top;"><b>.resize(n_elem)</b></td>
3331 <td style="vertical-align: top;"><br>
3332 </td>
3333 <td style="vertical-align: top;">(member function of <i>Col</i>, <i>Row</i>)
3334 </td>
3335 </tr>
3336 <tr>
3337 <td style="vertical-align: top;"><b>.resize(n_rows, n_cols)</b></td>
3338 <td style="vertical-align: top;"><br>
3339 </td>
3340 <td style="vertical-align: top;">(member function of <i>Mat</i>)
3341 </td>
3342 </tr>
3343 <tr>
3344 <td style="vertical-align: top;"><b>.resize(n_rows, n_cols, n_slices)</b></td>
3345 <td style="vertical-align: top;"><br>
3346 </td>
3347 <td style="vertical-align: top;">(member function of <i>Cube</i>)
3348 </td>
3349 </tr>
3350 </tbody>
3351 </table>
3352 <br>
3353 <ul>
3354 <li>
3355 Recreate the object according to given size specifications, while preserving the elements as well as the layout of the elements
3356 </li>
3357 <br>
3358 <li>
3359 Can be used for growing or shrinking an object (ie. adding/removing rows, and/or columns, and/or slices)
3360 </li>
3361 <br>
3362 <li>
3363 <b>Caveat:</b>
3364 .resize() is slower than <a href="#set_size">.set_size()</a>, which doesn't preserve data
3365 </li>
3366 <br>
3367 <li>
3368 Examples:
3369 <ul>
3370 <pre>
3371 mat A = randu&lt;mat&gt;(4,5);
3372 A.resize(7,6);
3373 </pre>
3374 </ul>
3375 </li>
3376 <br>
3377 <li>
3378 This function was added in version 2.4.1
3379 </li>
3380 <br>
3381 <li>See also:
3382 <ul>
3383 <li><a href="#reshape_member">.reshape()</a></li>
3384 <li><a href="#set_size">.set_size()</a></li>
3385 <li><a href="#reset">.reset()</a></li>
3386 <li><a href="#insert">insert rows/cols/slices</a></li>
3387 <li><a href="#shed">shed rows/cols/slices</a></li>
3388 <li><a href="#resize">resize()</a> (standalone function)</li>
3389 </ul>
3390 </li>
3391 </ul>
3392 <br>
3393 <hr class="greyline"><br>
3394
3395 <a name="save_load_mat"></a>
3396 <b>
3397 .save(name, file_type = arma_binary)
3398 <br>
3399 .save(stream, file_type = arma_binary)
3400 <br>
3401 <br>
3402 .load(name, file_type = auto_detect)
3403 <br>
3404 .load(stream, file_type = auto_detect)
3405 <br>
3406 <br>
3407 .quiet_save(name, file_type = arma_binary)
3408 <br>
3409 .quiet_save(stream, file_type = arma_binary)
3410 <br>
3411 <br>
3412 .quiet_load(name, file_type = auto_detect)
3413 <br>
3414 .quiet_load(stream, file_type = auto_detect)
3415 </b>
3416 <ul>
3417 <li>Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i> classes</li>
3418 <br>
3419 <li>Store/retrieve data in files or streams</li>
3420 <br>
3421 <li>On success, <i>save()</i>, <i>load()</i>, <i>quiet_save()</i>, and <i>quite_load()</i> will return a <i>bool</i> set to <i>true</i></li>
3422 <br>
3423 <li><i>save()</i> and <i>quiet_save()</i> will return a <i>bool</i> set to <i>false</i> if the saving process fails</li>
3424 <br>
3425 <li>
3426 <i>load()</i> and <i>quiet_load()</i> will return a <i>bool</i> set to <i>false</i> if the loading process fails;
3427 additionally, the object will be reset so it has no elements
3428 </li>
3429 <br>
3430 <li><i>load()</i> and <i>save()</i> will print warning messages if any problems are encountered</li>
3431 <br>
3432 <li><i>quiet_load()</i> and <i>quiet_save()</i> do not print any error messages</li>
3433 <br>
3434 <li>
3435 The following file formats are supported:
3436 <br>
3437 <br>
3438 <ul>
3439 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
3440 <tbody>
3441 <tr>
3442 <td style="vertical-align: top;"><b>auto_detect</b></td>
3443 <td style="vertical-align: top;"><br>
3444 </td>
3445 <td style="vertical-align: top;">
3446 for <i>load()</i> and <i>quiet_load()</i>:
3447 try to automatically detect the file type as one of the formats described below.
3448 This is the default operation.
3449 <br>
3450 <br>
3451 </td>
3452 </tr>
3453 <tr>
3454 <td style="vertical-align: top;"><b>raw_ascii</b></td>
3455 <td style="vertical-align: top;"><br>
3456 </td>
3457 <td style="vertical-align: top;">
3458 Numerical data stored in raw ASCII format, without a header.
3459 The numbers are separated by whitespace.
3460 The number of columns must be the same in each row.
3461 Data which was saved in Matlab/Octave using the <i>-ascii</i> option can be read in Armadillo, except for complex numbers.
3462 Complex numbers are stored in standard C++ notation (a tuple surrounded by brackets: eg. (1.23,4.56) indicates 1.24&nbsp;+&nbsp;4.56i).
3463 Cubes are loaded as one slice.
3464 <br>
3465 <br>
3466 </td>
3467 </tr>
3468 <tr>
3469 <td style="vertical-align: top;"><b>raw_binary</b></td>
3470 <td style="vertical-align: top;"><br>
3471 </td>
3472 <td style="vertical-align: top;">
3473 Numerical data stored in machine dependent raw binary format, without a header.
3474 Matrices are loaded to have one column,
3475 while cubes are loaded to have one slice with one column.
3476 The <a href="#reshape_member">.reshape()</a> function can be used to alter the size of the loaded matrix/cube without losing data.
3477 <br>
3478 <br>
3479 </td>
3480 </tr>
3481 <tr>
3482 <td style="vertical-align: top;"><b>arma_ascii</b></td>
3483 <td style="vertical-align: top;"><br>
3484 </td>
3485 <td style="vertical-align: top;">
3486 Numerical data stored in human readable text format, with a simple header to speed up loading.
3487 The header indicates the type of matrix as well as the number of rows and columns.
3488 For cubes, the header additionally specifies the number of slices.
3489 <br>
3490 <br>
3491 </td>
3492 </tr>
3493 <tr>
3494 <td style="vertical-align: top;"><b>arma_binary</b></td>
3495 <td style="vertical-align: top;"><br>
3496 </td>
3497 <td style="vertical-align: top;">
3498 Numerical data stored in machine dependent binary format, with a simple header to speed up loading.
3499 The header indicates the type of matrix as well as the number of rows and columns.
3500 For cubes, the header additionally specifies the number of slices.
3501 <br>
3502 <br>
3503 </td>
3504 </tr>
3505 <tr>
3506 <td style="vertical-align: top;"><b>csv_ascii</b></td>
3507 <td style="vertical-align: top;"><br>
3508 </td>
3509 <td style="vertical-align: top;">
3510 Numerical data stored in comma separated value (CSV) text format, without a header.
3511 Applicable to <i>Mat</i> only.
3512 <br>
3513 <br>
3514 </td>
3515 </tr>
3516 <tr>
3517 <td style="vertical-align: top;"><b>pgm_binary</b></td>
3518 <td style="vertical-align: top;"><br>
3519 </td>
3520 <td style="vertical-align: top;">
3521 Image data stored in Portable Gray Map (PGM) format.
3522 Applicable to <i>Mat</i> only.
3523 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.
3524 As such the matrix should have values in the [0,255] interval, otherwise the resulting image may not display correctly.
3525 <br>
3526 <br>
3527 </td>
3528 </tr>
3529 <tr>
3530 <td style="vertical-align: top;"><b>ppm_binary</b></td>
3531 <td style="vertical-align: top;"><br>
3532 </td>
3533 <td style="vertical-align: top;">
3534 Image data stored in Portable Pixel Map (PPM) format.
3535 Applicable to <i>Cube</i> only.
3536 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.
3537 As such the cube/field should have values in the [0,255] interval, otherwise the resulting image may not display correctly.
3538 </td>
3539 </tr>
3540 </tbody>
3541 </table>
3542 </ul>
3543 </li>
3544 <br>
3545 <br>
3546 <li>
3547 Examples:
3548 <ul>
3549 <pre>
3550 mat A = randu&lt;mat&gt;(5,5);
3551
3552 A.save("A1.mat"); // default save format is arma_binary
3553 A.save("A2.mat", arma_ascii);
3554
3555 mat B;
3556 // automatically detect format type
3557 B.load("A1.mat");
3558
3559 mat C;
3560 // force loading in the arma_ascii format
3561 C.load("A2.mat", arma_ascii);
3562
3563
3564 // example of saving/loading using a stream
3565 std::stringstream s;
3566 A.save(s);
3567
3568 mat D;
3569 D.load(s);
3570
3571
3572 // example of testing for success
3573 mat E;
3574 bool status = E.load("A2.mat");
3575
3576 if(status == true)
3577 {
3578 cout &lt;&lt; "loaded okay" &lt;&lt; endl;
3579 }
3580 else
3581 {
3582 cout &lt;&lt; "problem with loading" &lt;&lt; endl;
3583 }
3584 </pre>
3585 </ul>
3586 </li>
3587 <br>
3588 <li>See also:
3589 <ul>
3590 <li><a href="#save_load_field">saving/loading fields</a></li>
3591 </ul>
3592 </li>
3593 <br>
3594 </ul>
3595 <hr class="greyline"><br>
3596
3597 <a name="save_load_field"></a>
3598 <b>
3599 .save(name, file_type = arma_binary)
3600 <br>
3601 .save(stream, file_type = arma_binary)
3602 <br>
3603 <br>
3604 .load(name, file_type = auto_detect)
3605 <br>
3606 .load(stream, file_type = auto_detect)
3607 <br>
3608 <br>
3609 .quiet_save(name, file_type = arma_binary)
3610 <br>
3611 .quiet_save(stream, file_type = arma_binary)
3612 <br>
3613 <br>
3614 .quiet_load(name, file_type = auto_detect)
3615 <br>
3616 .quiet_load(stream, file_type = auto_detect)
3617 </b>
3618 <ul>
3619 <li>Member functions of the <i>field</i> class</li>
3620 <br>
3621 <li>Store/retrieve fields in files or stream</li>
3622 <br>
3623 <li>On success, save(), load(), quiet_save(), and quite_load() will return a <i>bool</i> set to <i>true</i></li>
3624 <br>
3625 <li>save() and quiet_save() will return a <i>bool</i> set to <i>false</i> if the saving process fails</li>
3626 <br>
3627 <li>
3628 load() and quiet_load() will return a <i>bool</i> set to <i>false</i> if the loading process fails;
3629 additionally, the field will be reset so it has no elements
3630 </li>
3631 <br>
3632 <li>load() and save() will print warning messages if any problems are encountered</li>
3633 <br>
3634 <li>quiet_load() and quiet_save() do not print any error messages</li>
3635 <br>
3636 <li>
3637 Fields with objects of type <i>std::string</i> are saved and loaded as raw text files.
3638 The text files do not have a header.
3639 Each string is separated by a whitespace.
3640 load() and quiet_load() will only accept text files that have the same number of strings on each line.
3641 The strings can have variable lengths.
3642 </li>
3643 <br>
3644 <li>
3645 Other than storing string fields as text files, the following file formats are supported:
3646 <br>
3647 <br>
3648 <ul>
3649 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
3650 <tbody>
3651 <tr>
3652 <td style="vertical-align: top;"><b>auto_detect</b></td>
3653 <td style="vertical-align: top;"><br>
3654 </td>
3655 <td style="vertical-align: top;">
3656 <br>
3657 <li>
3658 load(): try to automatically detect the field format type as one of the formats described below.
3659 This is the default operation.
3660 </li>
3661 <br>
3662 </td>
3663 </tr>
3664 <tr>
3665 <td style="vertical-align: top;"><b>arma_binary</b></td>
3666 <td style="vertical-align: top;"><br>
3667 </td>
3668 <td style="vertical-align: top;">
3669 <br>
3670 <li>
3671 Objects are stored in machine dependent binary format.
3672 <li>
3673 Default type for fields of type <i>Mat</i>, <i>Col</i> or <i>Row</i>.
3674 </li>
3675 <li>
3676 Only applicable to fields of type <i>Mat</i>, <i>Col</i> or <i>Row</i>.
3677 </li>
3678 <br>
3679 </td>
3680 </tr>
3681 <tr>
3682 <td style="vertical-align: top;"><b>ppm_binary</b></td>
3683 <td style="vertical-align: top;"><br>
3684 </td>
3685 <td style="vertical-align: top;">
3686 <br>
3687 <li>
3688 Image data stored in Portable Pixmap Map (PPM) format.
3689 </li>
3690 <li>
3691 Only applicable to fields of type <i>Mat</i>, <i>Col</i> or <i>Row</i>.
3692 </li>
3693 <li>
3694 .load(): Loads the specified image and stores the red, green and blue components as three separate matrices.
3695 The resulting field is comprised of the three matrices,
3696 with the red, green and blue components in the first, second and third matrix, respectively.
3697 </li>
3698 <li>
3699 .save(): Saves a field with exactly three matrices of equal size as an image.
3700 It is assumed that the red, green and blue components are stored in the first, second and third matrix, respectively.
3701 Saving <i>int</i>, <i>float</i> or <i>double</i> matrices is a lossy operation,
3702 as each matrix element is copied and converted to an 8 bit representation.
3703 </li>
3704
3705 </td>
3706 </tr>
3707 </tbody>
3708 </table>
3709 </ul>
3710 </li>
3711 <br>
3712 <li>See also:
3713 <ul>
3714 <li><a href="#save_load_mat">saving/loading matrices and cubes</a></li>
3715 </ul>
3716 </li>
3717 <br>
3718 </ul>
3719 <hr class="greyline"><br>
3720
3721 <a name="set_imag"></a>
3722 <b>.set_imag(X)</b>
3723 <br>
3724 <b>.set_real(X)</b>
3725 <br>
3726 <ul>
3727 <li>Member functions of Mat, Col, Row and Cube</li>
3728 <br>
3729 <li>
3730 Set the imaginary/real part of an object
3731 </li>
3732 <br>
3733 <li>
3734 <i>X</i> must have the same size as the recipient object
3735 </li>
3736 <br>
3737 <li>
3738 Examples:
3739 <ul>
3740 <pre>
3741 mat A = randu&lt;mat&gt;(4,5);
3742 mat B = randu&lt;mat&gt;(4,5);
3743
3744 cx_mat C = zeros&lt;mat&gt;(4,5);
3745
3746 C.set_real(A);
3747 C.set_imag(B);
3748 </pre>
3749 </ul>
3750 </li>
3751 <br>
3752 <li>
3753 <b>Caveat:</b>
3754 if you want to directly construct a complex matrix out of two real matrices,
3755 the following code is faster:
3756 <ul>
3757 <pre>
3758 mat A = randu&lt;mat&gt;(4,5);
3759 mat B = randu&lt;mat&gt;(4,5);
3760
3761 cx_mat C = cx_mat(A,B);
3762 </pre>
3763 </ul>
3764 </li>
3765 <br>
3766 <li>See also:
3767 <ul>
3768 <li><a href="#constructors_mat">matrix constructors</a></li>
3769 <li><a href="#constructors_cube">cube constructors</a></li>
3770 <li><a href="#imag_real">imag()&nbsp;/&nbsp;real()</a></li>
3771 </ul>
3772 </li>
3773 <br>
3774 </ul>
3775 <hr class="greyline"><br>
3776
3777 <a name="set_size"></a>
3778 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
3779 <tbody>
3780 <tr>
3781 <td style="vertical-align: top;"><b>.set_size(n_elem)</b></td>
3782 <td style="vertical-align: top;"><br>
3783 </td>
3784 <td style="vertical-align: top;">(member function of <i>Col</i>, <i>Row</i>, and <i>field</i>)
3785 </td>
3786 </tr>
3787 <tr>
3788 <td style="vertical-align: top;"><b>.set_size(n_rows, n_cols)</b></td>
3789 <td style="vertical-align: top;"><br>
3790 </td>
3791 <td style="vertical-align: top;">(member function of <i>Mat</i> and <i>field</i>)
3792 </td>
3793 </tr>
3794 <tr>
3795 <td style="vertical-align: top;"><b>.set_size(n_rows, n_cols, n_slices)</b></td>
3796 <td style="vertical-align: top;"><br>
3797 </td>
3798 <td style="vertical-align: top;">(member function of <i>Cube</i>)
3799 </td>
3800 </tr>
3801 </tbody>
3802 </table>
3803 <br>
3804 <ul>
3805 <li>Changes the size of an object</li>
3806 <br>
3807 <li>
3808 If the requested number of elements is equal to the old number of elements, existing memory is reused
3809 </li>
3810 <br>
3811 <li>
3812 If the requested number of elements is not equal to the old number of elements, new memory is used
3813 </li>
3814 <br>
3815 <li>
3816 If you need to explicitly preserve data, use <a href="#reshape_member">.reshape()</a> or <a href="#resize_member">.resize()</a>
3817 </li>
3818 <br>
3819 <li>
3820 Examples:
3821 <ul>
3822 <pre>
3823 mat A;
3824 A.set_size(5,10);
3825
3826 vec q;
3827 q.set_size(100);
3828 </pre>
3829 </ul>
3830 </li>
3831 <br>
3832 <li>See also:
3833 <ul>
3834 <li><a href="#reset">.reset()</a></li>
3835 <li><a href="#reshape_member">.reshape()</a></li>
3836 <li><a href="#resize_member">.resize()</a></li>
3837 </ul>
3838 </li>
3839 </ul>
3840 <br>
3841 <hr class="greyline"><br>
3842
3843 <a name="shed"></a>
3844 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
3845 <tbody>
3846 <tr>
3847 <td style="vertical-align: top;">
3848 <b>.shed_row(&nbsp;</b>row_number<b>&nbsp;)</b>
3849 <br>
3850 <b>.shed_rows(&nbsp;</b>first_row, last_row<b>&nbsp;)</b>
3851 </td>
3852 <td style="vertical-align: top;"><br></td>
3853 <td style="vertical-align: top;">(member functions of <i>Mat</i> and <i>Col</i>)
3854 </td>
3855 </tr>
3856 <tr>
3857 <td>&nbsp;</td>
3858 </tr>
3859 <tr>
3860 <td style="vertical-align: top;">
3861 <b>.shed_col(&nbsp;</b>column_number<b>&nbsp;)</b>
3862 <br>
3863 <b>.shed_cols(&nbsp;</b>first_column, last_column<b>&nbsp;)</b>
3864 </td>
3865 <td style="vertical-align: top;"><br></td>
3866 <td style="vertical-align: top;">(member functions of <i>Mat</i> and <i>Row</i>)
3867 </td>
3868 </tr>
3869 <tr>
3870 <td>&nbsp;</td>
3871 </tr>
3872 <tr>
3873 <td style="vertical-align: top;">
3874 <b>.shed_slice(&nbsp;</b>slice_number<b>&nbsp;)</b>
3875 <br>
3876 <b>.shed_slices(&nbsp;</b>first_slice, last_slice<b>&nbsp;)</b>
3877 </td>
3878 <td style="vertical-align: top;"><br></td>
3879 <td style="vertical-align: top;">(member functions of <i>Cube</i>)
3880 </td>
3881 </tr>
3882 </tbody>
3883 </table>
3884 <br>
3885 <ul>
3886 <li>
3887 Single argument functions:
3888 remove the specified row/column/slice
3889 </li>
3890 <br>
3891 <li>
3892 Two argument functions:
3893 remove the specified range of rows/columns/slices
3894 </li>
3895 <br>
3896 <li>
3897 Examples:
3898 <ul>
3899 <pre>
3900 mat A = randu&lt;mat&gt;(5,10);
3901
3902 A.shed_row(2);
3903 A.shed_cols(2,4);
3904 </pre>
3905 </ul>
3906 </li>
3907 <br>
3908 <li>
3909 See also:
3910 <ul>
3911 <li><a href="#insert">insert rows/columns/slices</a></li>
3912 <li><a href="#join">join rows/columns/slices</a></li>
3913 <li><a href="#resize_member">.resize()</a></li>
3914 <li><a href="#submat">submatrix views</a></li>
3915 <li><a href="#subcube">subcube views</a></li>
3916 <li><a href="http://thesaurus.com/browse/shed"><i>shed</i> in thesaurus.com</a></li>
3917 </ul>
3918 </li>
3919 <br>
3920 </ul>
3921 <hr class="greyline"><br>
3922
3923 <a name="stl_container_fns"></a>
3924 <b>STL container functions</b>
3925 <ul>
3926 <li><i>Mat</i>, <i>Col</i> and <i>Row</i> classes provide the following member functions that mimic the containers in the C++ Standard Template Library:<br>
3927 <br>
3928
3929 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
3930 <tbody>
3931 <tr>
3932 <td style="vertical-align: top;">
3933 <b>.clear()</b>
3934 </td>
3935 <td style="vertical-align: top;">&nbsp;<br>
3936 </td>
3937 <td style="vertical-align: top;">
3938 causes an object to have no elements
3939 </td>
3940 </tr>
3941 <tr>
3942 <td style="vertical-align: top;">
3943 &nbsp;
3944 </td>
3945 <td style="vertical-align: top;">&nbsp;<br>
3946 </td>
3947 <td style="vertical-align: top;">
3948 &nbsp;
3949 </td>
3950 </tr>
3951 <tr>
3952 <td style="vertical-align: top;">
3953 <b>.empty()</b>
3954 </td>
3955 <td style="vertical-align: top;">&nbsp;<br>
3956 </td>
3957 <td style="vertical-align: top;">
3958 returns true if the object has no elements; returns false if the object has one or more elements
3959 </td>
3960 </tr>
3961 <tr>
3962 <td style="vertical-align: top;">
3963 &nbsp;
3964 </td>
3965 <td style="vertical-align: top;">&nbsp;<br>
3966 </td>
3967 <td style="vertical-align: top;">
3968 &nbsp;
3969 </td>
3970 </tr>
3971 <tr>
3972 <td style="vertical-align: top;">
3973 <b>.size()</b>
3974 </td>
3975 <td style="vertical-align: top;">&nbsp;<br>
3976 </td>
3977 <td style="vertical-align: top;">
3978 returns the total number of elements
3979 </td>
3980 </tr>
3981 </tbody>
3982 </table>
3983 </li>
3984 <br>
3985 <li>
3986 Examples:
3987 <ul>
3988 <pre>
3989 mat A = randu&lt;mat&gt;(5,5);
3990 cout &lt;&lt; A.size() &lt;&lt; endl;
3991
3992 A.clear();
3993 cout &lt;&lt; A.empty() &lt;&lt; endl;
3994 </pre>
3995 </ul>
3996 </li>
3997 <br>
3998 <li>
3999 See also:
4000 <ul>
4001 <li><a href="#iterators_mat">iterators (matrices)</a></li>
4002 <li><a href="#attributes">matrix and vector attributes</a></li>
4003 <li><a href="#is_empty">.is_empty()</a></li>
4004 <li><a href="#reset">.reset()</a></li>
4005 </ul>
4006 </li>
4007 <br>
4008 </ul>
4009 <hr class="greyline"><br>
4010
4011 <a name="submat"></a>
4012 <b>submatrix views</b>
4013 <ul>
4014 <li>A collection of member functions of <i>Mat</i>, <i>Col</i> and <i>Row</i> classes that provide submatrix views<br>
4015 <br>
4016 <li>For a matrix or vector <i>X</i>, the subviews are accessed as:</li>
4017 <br>
4018 <ul>
4019 X.<b>col(&nbsp;</b>col_number<b>&nbsp;)</b><br>
4020 X<b>(</b>&nbsp;<b>span::all,</b> col_number&nbsp;<b>)</b><br>
4021 X<b>(</b>&nbsp;<b>span(</b>first_row<b>,</b> last_row<b>),</b> col_number&nbsp;<b>)</b><br>
4022 <br>
4023 X.<b>unsafe_col(&nbsp;</b>col_number<b>&nbsp;)</b><br>
4024 <br>
4025 X.<b>row(&nbsp;</b>row_number<b>&nbsp;)</b><br>
4026 X<b>(</b>&nbsp;row_number<b>,</b> <b>span::all</b>&nbsp;<b>)</b><br>
4027 X<b>(</b>&nbsp;row_number<b>,</b> <b>span(</b>first_col<b>,</b> last_col<b>)&nbsp;)</b><br>
4028 <br>
4029 X.<b>cols(&nbsp;</b>first_col<b>,</b> last_col<b>&nbsp;)</b><br>
4030 X.<b>rows(&nbsp;</b>first_row<b>,</b> last_row<b>&nbsp;)</b><br>
4031 <br>
4032 X.<b>submat(&nbsp;</b>first_row<b>,</b> first_col<b>,</b> last_row<b>,</b> last_col<b>&nbsp;)</b><br>
4033 X.<b>submat(&nbsp;span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b> last_col<b>)&nbsp;)</b><br>
4034 <br>
4035 X<b>(&nbsp;span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b> last_col<b>)&nbsp;)</b><br>
4036 <br>
4037 X.<b>elem(</b>&nbsp;vector_of_indices&nbsp;<b>)</b>
4038 </ul>
4039 </li>
4040 <br>
4041 <li>For a vector <i>V</i> (column or row vector), there is an additional method:</li>
4042 <!-- <li>For a vector <i>V</i> (column or row vector), there are three additional methods:</li> -->
4043 <br>
4044 <ul>
4045 V.<b>subvec(&nbsp;</b>first_index<b>,</b> last_index<b>&nbsp;)</b><br>
4046 <!--
4047 V.<b>subvec(&nbsp;span(</b>first_index<b>,</b> last_index<b>)&nbsp;)</b><br>
4048 <br>
4049 V<b>(&nbsp;span(</b>first_index<b>,</b> last_index<b>)&nbsp;)</b><br>
4050 -->
4051 </ul>
4052 <br>
4053 <li>
4054 Instances of <i>span::all</i>, to indicate an entire range, can be replaced by <i>span()</i>, where no number is specified
4055 </li>
4056 <br>
4057 <li>
4058 In the function <i>X.elem(vector_of_indices)</i>,
4059 elements specified in <i>vector_of_indices</i> are accessed.
4060 <i>X</i> is interpreted as one long vector,
4061 with column-by-column ordering of the elements of <i>X</i>.
4062 The <i>vector_of_indices</i> must evaluate to be a vector of type <i><a href="#Col">uvec</a></i>
4063 (eg., generated by <i><a href="#find">find()</a></i>).
4064 The aggregate set of the specified elements is treated as a column vector
4065 (eg., the output of <i>X.elem()</i> is always a column vector).
4066 </li>
4067 <br>
4068 <li>
4069 The function <i>.unsafe_col()</i> is provided for speed reasons and should be used only if you know what you're doing.
4070 The function creates a seemingly independent <i>Col</i> vector object (eg. <i>vec</i>),
4071 but the vector actually uses memory from the existing matrix object.
4072 As such, the created <i>Col</i> vector is currently not alias safe
4073 and does not take into account that the parent matrix object could be deleted.
4074 If deleted memory is accessed through the created <i>Col</i> vector,
4075 it will cause memory corruption and/or a crash.
4076 </li>
4077 <br>
4078 <li>
4079 Examples:
4080 <ul>
4081 <pre>
4082 mat A = zeros&lt;mat&gt;(5,10);
4083
4084 A.submat(0,1,2,3) = randu&lt;mat&gt;(3,3);
4085
4086 // the following three statements
4087 // access the same part of A
4088 mat B = A.submat(0,1,2,3);
4089 mat C = A.submat( span(0,2), span(1,3) );
4090 mat D = A( span(0,2), span(1,3) );
4091
4092 // the following two statements
4093 // access the same part of A
4094 A.col(1) = randu&lt;mat&gt;(5,1);
4095 A(span::all, 1) = randu&lt;mat&gt;(5,1);
4096
4097 mat X = randu&lt;mat&gt;(5,5);
4098
4099 // get all elements of X that are greater than 0.5
4100 vec q = X.elem( find(X > 0.5) );
4101
4102 // set four specific elements of X to 1
4103 uvec indices;
4104 indices &lt;&lt; 2 &lt;&lt; 3 &lt;&lt; 6 &lt;&lt; 8;
4105
4106 X.elem(indices) = ones&lt;vec&gt;(4);
4107 </pre>
4108 </ul>
4109 </li>
4110 <br>
4111 <li>
4112 See also:
4113 <ul>
4114 <li><a href="#diag">.diag()</a></li>
4115 <li><a href="#colptr">.colptr()</a></li>
4116 <li><a href="#in_range">.in_range()</a></li>
4117 <li><a href="#find">find()</a></li>
4118 <li><a href="#join">join rows/columns/slices</a></li>
4119 <li><a href="#shed">shed rows/columns/slices</a></li>
4120 <li><a href="#insert">insert rows/columns/slices</a></li>
4121 <li><a href="#subcube">subcube views</a></li>
4122 </ul>
4123 </li>
4124 <br>
4125 </ul>
4126 <hr class="greyline"><br>
4127
4128 <a name="subcube"></a>
4129 <b>subcube views and slices</b>
4130 <ul>
4131 <li>A collection of member functions of the <i>Cube</i> class that provide subcube views<br>
4132 <br>
4133 <li>For a cube <i>Q</i>, the subviews are accessed as:</li>
4134 <br>
4135 <ul>
4136 Q.<b>slice(&nbsp;</b>slice_number&nbsp;<b>)</b><br>
4137 Q.<b>slices(&nbsp;</b>first_slice<b>,</b> last_slice&nbsp;<b>)</b><br>
4138 <br>
4139 Q.<b>subcube(&nbsp;</b>first_row<b>,</b> first_col<b>,</b> first_slice<b>, </b>last_row<b>,</b> last_col<b>, </b>last_slice&nbsp;<b>)</b><br>
4140 Q.<b>subcube(&nbsp;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>)&nbsp;)</b><br>
4141 <br>
4142 Q<b>(&nbsp;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>)&nbsp;)</b><br>
4143 </ul>
4144 </li>
4145 <br>
4146 <li>
4147 Instances of <i>span(a,b)</i> can be replaced by:
4148 <ul>
4149 <li><i>span()</i> or <i>span::all</i>, to indicate the entire range</li>
4150 <li><i>span(a)</i>, to indicate a particular row, column or slice</li>
4151 </ul>
4152 </li>
4153 <br>
4154 <li>
4155 An individual slice, accessed via <i>.slice()</i>, is an instance of the <i>Mat</i> class
4156 (a reference to a matrix is provided)
4157 </li>
4158 <br>
4159 <li>
4160 Examples:
4161 <ul>
4162 <pre>
4163 cube A = randu&lt;cube&gt;(2,3,4);
4164 mat B = A.slice(1);
4165
4166 A.slice(0) = randu&lt;mat&gt;(2,3);
4167 A.slice(0)(1,2) = 99.0;
4168
4169 A.subcube(0,0,1, 1,1,2) = randu&lt;cube&gt;(2,2,2);
4170 A( span(0,1), span(0,1), span(1,2) ) = randu&lt;cube&gt;(2,2,2);
4171
4172 </pre>
4173 </ul>
4174 </li>
4175 <br>
4176 <li>
4177 See also:
4178 <ul>
4179 <li><a href="#in_range">.in_range()</a></li>
4180 <li><a href="#join">join slices</a></li>
4181 <li><a href="#shed">shed slices</a></li>
4182 <li><a href="#insert">insert slices</a></li>
4183 <li><a href="#submat">submatrix views</a></li>
4184 </ul>
4185 </li>
4186 <br>
4187 </ul>
4188 <hr class="greyline"><br>
4189
4190 <a name="subfield"></a>
4191 <b>subfield views</b>
4192 <ul>
4193 <li>A collection of member functions of the <i>field</i> class that provide subfield views<br>
4194 <br>
4195 <li>For a field <i>F</i>, the subfields are accessed as:</li>
4196 <br>
4197 <ul>
4198 F.<b>row(&nbsp;</b>row_number&nbsp;<b>)</b><br>
4199 F.<b>col(&nbsp;</b>col_number&nbsp;<b>)</b><br>
4200 <br>
4201 F.<b>rows(&nbsp;</b>first_row<b>,</b> last_row&nbsp;<b>)</b><br>
4202 F.<b>cols(&nbsp;</b>first_col<b>,</b> last_col&nbsp;<b>)</b><br>
4203 <br>
4204 F.<b>subfield(&nbsp;</b>first_row<b>,</b>&nbsp;first_col<b>,</b> last_row<b>,</b>&nbsp;last_col <b>)</b><br>
4205 F.<b>subfield(&nbsp;span(</b>first_row<b>,</b>&nbsp;last_row<b>), span(</b>first_col<b>,</b>&nbsp;last_col<b>) )</b><br>
4206 <br>
4207 F<b>(&nbsp;span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b>&nbsp;last_col<b>) )</b><br>
4208 </ul>
4209 </li>
4210 <br>
4211 <li>
4212 Instances of <i>span(a,b)</i> can be replaced by:
4213 <ul>
4214 <li><i>span()</i> or <i>span::all</i>, to indicate the entire range</li>
4215 <li><i>span(a)</i>, to indicate a particular row or column</li>
4216 </ul>
4217 </li>
4218 <br>
4219 <li>
4220 See also:
4221 <ul>
4222 <li><a href="#in_range">.in_range()</a></li>
4223 <li><a href="#submat">submatrix views</a></li>
4224 <li><a href="#subcube">subcube views</a></li>
4225 </ul>
4226 </li>
4227 <br>
4228 </ul>
4229 <hr class="greyline"><br>
4230
4231 <a name="swap_rows"></a>
4232 <b>
4233 .swap_rows(row1, row2)
4234 <br>.swap_cols(col1, col2)
4235 </b>
4236 <ul>
4237 <li>
4238 Member functions of <i>Mat</i>, <i>Col</i> and <i>Row</i> classes
4239 </li>
4240 <br>
4241 <li>
4242 Swap the contents of specified rows or columns
4243 </li>
4244 <br>
4245 <li>
4246 Examples:
4247 <ul>
4248 <pre>
4249 mat X = randu&lt;mat&gt;(5,5);
4250 X.swap_rows(0,4);
4251 </pre>
4252 </ul>
4253 </li>
4254 <br>
4255 <li>
4256 See also:
4257 <ul>
4258 <li><a href="#flip">fliplr() &amp; flipud()</a></li>
4259 </ul>
4260 </li>
4261 <br>
4262 </ul>
4263 <hr class="greyline"><br>
4264
4265 <a name="t_st_members"></a>
4266 <b>
4267 .t()
4268 <br>.st()
4269 </b>
4270 <ul>
4271 <li>
4272 Member functions of any expression involving matrices or vectors
4273 </li>
4274 <br>
4275 <li>
4276 <i>.t()</i> provides a transposed copy of the object; if a given object has complex elements, a Hermitian transpose is done (ie. the conjugate of the elements is taken during the transpose operation)
4277 </li>
4278 <br>
4279 <li>
4280 <i>.st()</i> provides a transposed copy of the object, without taking the conjugate of the elements (complex matrices)
4281 </li>
4282 <br>
4283 <li>
4284 For non-complex objects, the <i>.t()</i> and <i>.st()</i> functions are equivalent
4285 </li>
4286 <br>
4287 <li>
4288 Examples:
4289 <ul>
4290 <pre>
4291 mat A = randu&lt;mat&gt;(4,5);
4292 mat B = A.t();
4293 </pre>
4294 </ul>
4295 </li>
4296 <br>
4297 <li>
4298 The <i>.t()</i> and <i>.st()</i> functions were added in version 2.4
4299 </li>
4300 <br>
4301 <li>
4302 See also:
4303 <ul>
4304 <li><a href="#trans">trans()</a></li>
4305 <li><a href="#strans">strans()</a></li>
4306 </ul>
4307 </li>
4308 <br>
4309 </ul>
4310 <hr class="greyline"><br>
4311
4312 <a name="zeros_member"></a>
4313 <b>.zeros()</b>
4314 <br><b>.zeros(n_elem)</b>
4315 <br><b>.zeros(n_rows, n_cols)</b>
4316 <br><b>.zeros(n_rows, n_cols, n_slices)</b>
4317 <ul>
4318 <li>
4319 Set the elements of an object to zero, optionally first resizing to specified dimensions
4320 </li>
4321 <br>
4322 <li>
4323 <i>.zeros()</i> and <i>.zeros(n_elem)</i> are member function of <i>Col</i> and <i>Row</i>
4324 </li>
4325 <br>
4326 <li>
4327 <i>.zeros()</i> and <i>.zeros(n_rows, n_cols)</i> are member functions of <i>Mat</i>
4328 </li>
4329 <br>
4330 <li>
4331 <i>.zeros()</i> and <i>.zeros(n_rows, n_cols, n_slices)</i> are member functions of <i>Cube</i>
4332 </li>
4333 <br>
4334 <li>
4335 Examples:
4336 <ul>
4337 <pre>
4338 mat A = randu&lt;mat&gt;(5,10);
4339 A.zeros(); // sets all elements to zero
4340 A.zeros(10,20); // sets the size to 10 rows and 20 columns
4341 // followed by setting all elements to zero
4342 </pre>
4343 </ul>
4344 </li>
4345 <br>
4346 <li>
4347 See also:
4348 <ul>
4349 <li><a href="#zeros_standalone">zeros()</a> (standalone function)</li>
4350 <li><a href="#ones_member">.ones()</a></li>
4351 <li><a href="#fill">.fill()</a></li>
4352 <li><a href="#reset">.reset()</a></li>
4353 </ul>
4354 </li>
4355 <br>
4356 </ul>
4357 <hr class="greyline">
4358
4359
4360 <hr class="greyline">
4361 <br>
4362 <br>
4363 <font size=+1><b>Other Classes</b></font>
4364 <br>
4365 <br>
4366 <hr class="greyline">
4367 <br>
4368
4369 <a name="running_stat"></a>
4370 <b>running_stat&lt;</b><i>type</i><b>&gt;</b>
4371 <ul>
4372 <li>
4373 Class for keeping statistics of a continuously sampled one dimensional process/signal.
4374 Useful if the storage of individual samples (scalars) is not necessary or desired.
4375 Also useful if the number of samples is not known beforehand or exceeds available memory.
4376 </li>
4377 <br>
4378 <li>
4379 <i>type</i> should be one of: <i>float</i>, <i>double</i>, <i><a href="#cx_float_double">cx_float</a></i>, <i><a href="#cx_float_double">cx_double</a></i>
4380 </li>
4381 <br>
4382 <li>
4383 Member functions:
4384 <ul>
4385 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
4386 <tbody>
4387 <tr>
4388 <td style="vertical-align: top;">
4389 <b>.operator()(</b>scalar<b>)</b>
4390 </td>
4391 <td style="vertical-align: top;">&nbsp;<br>
4392 </td>
4393 <td style="vertical-align: top;">
4394 update the statistics so far using the given scalar
4395 </td>
4396 </tr>
4397 <tr>
4398 <td style="vertical-align: top;">
4399 <b>.mean()</b>
4400 </td>
4401 <td style="vertical-align: top;">&nbsp;<br>
4402 </td>
4403 <td style="vertical-align: top;">
4404 get the mean or average value so far
4405 </td>
4406 </tr>
4407 <tr>
4408 <td style="vertical-align: top;">
4409 <b>.var(</b>norm_type=0<b>)</b>
4410 </td>
4411 <td style="vertical-align: top;">&nbsp;<br>
4412 </td>
4413 <td style="vertical-align: top;">
4414 get the variance so far
4415 </td>
4416 </tr>
4417 <tr>
4418 <td style="vertical-align: top;">
4419 <b>.stddev(</b>norm_type=0<b>)</b>
4420 </td>
4421 <td style="vertical-align: top;">&nbsp;<br>
4422 </td>
4423 <td style="vertical-align: top;">
4424 get the standard deviation so far
4425 </td>
4426 </tr>
4427 <tr>
4428 <td style="vertical-align: top;">
4429 <b>.min()</b>
4430 </td>
4431 <td style="vertical-align: top;">&nbsp;<br>
4432 </td>
4433 <td style="vertical-align: top;">
4434 get the minimum value so far
4435 </td>
4436 </tr>
4437 <tr>
4438 <td style="vertical-align: top;">
4439 <b>.max()</b>
4440 </td>
4441 <td style="vertical-align: top;">&nbsp;<br>
4442 </td>
4443 <td style="vertical-align: top;">
4444 get the maximum value so far
4445 </td>
4446 </tr>
4447 <tr>
4448 <td style="vertical-align: top;">
4449 <b>.reset()</b>
4450 </td>
4451 <td style="vertical-align: top;">&nbsp;<br>
4452 </td>
4453 <td style="vertical-align: top;">
4454 reset all statistics and set the number of samples to zero
4455 </td>
4456 </tr>
4457 <tr>
4458 <td style="vertical-align: top;">
4459 <b>.count()</b>
4460 </td>
4461 <td style="vertical-align: top;">&nbsp;<br>
4462 </td>
4463 <td style="vertical-align: top;">
4464 get the number of samples so far
4465 </td>
4466 </tr>
4467 </tbody>
4468 </table>
4469 </ul>
4470 </li>
4471 <br>
4472 <li>
4473 For the .var() and .stddev() functions, the default <i>norm_type=0</i> performs normalisation using <i>N-1</i>
4474 (where <i>N</i> is the number of samples so far),
4475 providing the best unbiased estimator.
4476 Using <i>norm_type=1</i> causes normalisation to be done using <i>N</i>, which provides the second moment around the mean.
4477 </li>
4478 <br>
4479 <li>
4480 The return type of .count() depends on the underlying form of <i>type</i>: it is either <i>float</i> or <i>double</i>.
4481 </li>
4482 <br>
4483 <li>
4484 Examples:
4485 <ul>
4486 <pre>
4487 running_stat&lt;double&gt; stats;
4488
4489 for(uword i=0; i&lt;10000; ++i)
4490 {
4491 double sample = double(rand())/RAND_MAX;
4492 stats(sample);
4493 }
4494
4495 cout &lt;&lt; "mean = " &lt;&lt; stats.mean() &lt;&lt; endl;
4496 cout &lt;&lt; "var = " &lt;&lt; stats.var() &lt;&lt; endl;
4497 cout &lt;&lt; "min = " &lt;&lt; stats.min() &lt;&lt; endl;
4498 cout &lt;&lt; "max = " &lt;&lt; stats.max() &lt;&lt; endl;
4499 </pre>
4500 </ul>
4501 </li>
4502 <br>
4503 <li>See also:
4504 <ul>
4505 <li><a href="#stats_fns">statistics functions</a></li>
4506 <li><a href="#running_stat_vec">running_stat_vec</a></li>
4507 </ul>
4508 </li>
4509 </ul>
4510 <br>
4511 <hr class="greyline"><br>
4512
4513 <a name="running_stat_vec"></a>
4514 <b>running_stat_vec&lt;</b><i>type</i><b>&gt;(calc_cov = false)</b>
4515 <ul>
4516 <li>
4517 Class for keeping statistics of a continuously sampled multi-dimensional process/signal.
4518 Useful if the storage of individual samples is not necessary or desired.
4519 Also useful if the number of samples is not known beforehand or exceeds available memory.
4520 </li>
4521 <br>
4522 <li>
4523 This class is similar to <i>running_stat</i>, with the difference being that vectors are processed instead of single values.
4524 </li>
4525 <br>
4526 <li>
4527 <i>type</i> must match the element type used by the sample vectors
4528 (ie. it must be one of <i>float</i>, <i>double</i>, <i><a href="#cx_float_double">cx_float</a></i>, <i><a href="#cx_float_double">cx_double</a></i>)
4529 </li>
4530 <br>
4531 <li>
4532 <i>type</i> can be inferred via the use of the <i>elem_type</i> member typedef of a vector class.
4533 For example, <i>fvec::elem_type</i> will be interpreted as <i>float</i>,
4534 while <i>cx_vec::elem_type</i> will be interpreted as <i><a href="#cx_float_double">cx_double</a></i>.
4535 </li>
4536 <br>
4537 <li>
4538 Member functions:
4539 <ul>
4540 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
4541 <tbody>
4542 <tr>
4543 <td style="vertical-align: top;">
4544 <b>.operator()(</b>vector<b>)</b>
4545 </td>
4546 <td style="vertical-align: top;">&nbsp;<br>
4547 </td>
4548 <td style="vertical-align: top;">
4549 update the statistics so far using the given vector
4550 </td>
4551 </tr>
4552 <tr>
4553 <td style="vertical-align: top;">
4554 <b>.mean()</b>
4555 </td>
4556 <td style="vertical-align: top;">&nbsp;<br>
4557 </td>
4558 <td style="vertical-align: top;">
4559 get the mean vector so far
4560 </td>
4561 </tr>
4562 <tr>
4563 <td style="vertical-align: top;">
4564 <b>.var(</b>norm_type=0<b>)</b>
4565 </td>
4566 <td style="vertical-align: top;">&nbsp;<br>
4567 </td>
4568 <td style="vertical-align: top;">
4569 get the vector of variances so far
4570 </td>
4571 </tr>
4572 <tr>
4573 <td style="vertical-align: top;">
4574 <b>.stddev(</b>norm_type=0<b>)</b>
4575 </td>
4576 <td style="vertical-align: top;">&nbsp;<br>
4577 </td>
4578 <td style="vertical-align: top;">
4579 get the vector of standard deviations so far
4580 </td>
4581 </tr>
4582 <tr>
4583 <td style="vertical-align: top;">
4584 <b>.min()</b>
4585 </td>
4586 <td style="vertical-align: top;">&nbsp;<br>
4587 </td>
4588 <td style="vertical-align: top;">
4589 get the vector of minimum values so far
4590 </td>
4591 </tr>
4592 <tr>
4593 <td style="vertical-align: top;">
4594 <b>.max()</b>
4595 </td>
4596 <td style="vertical-align: top;">&nbsp;<br>
4597 </td>
4598 <td style="vertical-align: top;">
4599 get the vector of maximum values so far
4600 </td>
4601 </tr>
4602 <tr>
4603 <td style="vertical-align: top;">
4604 <b>.cov(</b>norm_type=0<b>)</b>
4605 </td>
4606 <td style="vertical-align: top;">&nbsp;<br>
4607 </td>
4608 <td style="vertical-align: top;">
4609 get the covariance matrix so far
4610 <br>NOTE: this only works if <i>calc_cov</i> is set to <i>true</i> during the construction of the class
4611 </td>
4612 </tr>
4613 <tr>
4614 <td style="vertical-align: top;">
4615 <b>.reset()</b>
4616 </td>
4617 <td style="vertical-align: top;">&nbsp;<br>
4618 </td>
4619 <td style="vertical-align: top;">
4620 reset all statistics and set the number of samples to zero
4621 </td>
4622 </tr>
4623 <tr>
4624 <td style="vertical-align: top;">
4625 <b>.count()</b>
4626 </td>
4627 <td style="vertical-align: top;">&nbsp;<br>
4628 </td>
4629 <td style="vertical-align: top;">
4630 get the number of samples so far
4631 </td>
4632 </tr>
4633 </tbody>
4634 </table>
4635 </ul>
4636 </li>
4637 <br>
4638 <li>
4639 For the .var() and .stddev() functions, the default <i>norm_type=0</i> performs normalisation using <i>N-1</i>
4640 (where <i>N</i> is the number of samples so far),
4641 providing the best unbiased estimator.
4642 Using <i>norm_type=1</i> causes normalisation to be done using <i>N</i>, which provides the second moment around the mean.
4643 </li>
4644 <br>
4645 <li>
4646 The return type of .count() depends on the underlying form of <i>type</i>: it is either <i>float</i> or <i>double</i>.
4647 </li>
4648 <br>
4649 <li>
4650 Examples:
4651 <ul>
4652 <pre>
4653 running_stat_vec&lt;rowvec::elem_type&gt; stats;
4654
4655 rowvec sample;
4656
4657 for(uword i=0; i&lt;10000; ++i)
4658 {
4659 sample = randu&lt;rowvec&gt;(5);
4660 stats(sample);
4661 }
4662
4663 cout &lt;&lt; "mean = " &lt;&lt; stats.mean() &lt;&lt; endl;
4664 cout &lt;&lt; "var = " &lt;&lt; stats.var() &lt;&lt; endl;
4665 cout &lt;&lt; "min = " &lt;&lt; stats.min() &lt;&lt; endl;
4666 cout &lt;&lt; "max = " &lt;&lt; stats.max() &lt;&lt; endl;
4667
4668 //
4669 //
4670
4671 running_stat_vec&lt;rowvec::elem_type&gt; more_stats(true);
4672
4673 for(uword i=0; i&lt;20; ++i)
4674 {
4675 sample = randu&lt;rowvec&gt;(3);
4676
4677 sample(1) -= sample(0);
4678 sample(2) += sample(1);
4679
4680 more_stats(sample);
4681 }
4682
4683 cout &lt;&lt; "covariance matrix = " &lt;&lt; endl;
4684 cout &lt;&lt; more_stats.cov() &lt;&lt; endl;
4685
4686 rowvec sd = more_stats.stddev();
4687
4688 cout &lt;&lt; "correlations = " &lt;&lt; endl;
4689 cout &lt;&lt; more_stats.cov() / (trans(sd) * sd);
4690 </pre>
4691 </ul>
4692 </li>
4693 <br>
4694 <li>See also:
4695 <ul>
4696 <li><a href="#cov">cov()</a></li>
4697 <li><a href="#cor">cor()</a></li>
4698 <li><a href="#running_stat">running_stat</a></li>
4699 <li><a href="#stats_fns">statistics functions</a></li>
4700 </ul>
4701 </li>
4702 </ul>
4703 <br>
4704 <hr class="greyline"><br>
4705
4706 <a name="wall_clock"></a>
4707 <b>wall_clock</b>
4708 <ul>
4709 <li>
4710 Simple wall clock timer class, for measuring the number of elapsed seconds between two intervals
4711 </li>
4712 <br>
4713 <li>
4714 Examples:
4715 <ul>
4716 <pre>
4717 wall_clock timer;
4718
4719 mat A = randu&lt;mat&gt;(4,4);
4720 mat B = randu&lt;mat&gt;(4,4);
4721 mat C;
4722
4723 timer.tic();
4724 for(uword i=0; i&lt;100000; ++i)
4725 C = A + B + A + B;
4726
4727 double n_secs = timer.toc();
4728 cout &lt;&lt; "took " &lt;&lt; n_secs &lt;&lt; " seconds" &lt;&lt; endl;
4729 </pre>
4730 </ul>
4731 </li>
4732 </ul>
4733 <br>
4734 <hr class="greyline">
4735
4736 <hr class="greyline">
4737 <br>
4738 <br>
4739 <font size=+1><b>Generated Vectors/Matrices</b></font>
4740 <br>
4741 <br>
4742 <hr class="greyline">
4743 <br>
4744
4745 <a name="eye_standalone"></a>
4746 <b>eye(n_rows, n_cols)</b>
4747 <ul>
4748 <li>
4749 Generate a matrix with the elements along the main diagonal set to one
4750 and off-diagonal elements set to zero
4751 </li>
4752 <br>
4753 <li>
4754 An identity matrix is generated when <i>n_rows</i> = <i>n_cols</i>
4755 </li>
4756 <br>
4757 <li>
4758 Usage:
4759 <ul>
4760 <li>
4761 <i>matrix_type</i> X = eye&lt;<i>matrix_type</i>&gt;(n_rows, n_cols)
4762 </li>
4763 </ul>
4764 </li>
4765 <br>
4766 <li>
4767 Examples:
4768 <ul>
4769 <pre>
4770 mat A = eye&lt;mat&gt;(5,5);
4771 mat B = 123.0 * eye&lt;mat&gt;(5,5);
4772 </pre>
4773 </ul>
4774 </li>
4775 <br>
4776 <li>See also:
4777 <ul>
4778 <li><a href="#eye_member">.eye()</a> (member function of Mat)</li>
4779 <li><a href="#ones_standalone">ones()</a></li>
4780 <li><a href="#diagmat">diagmat()</a></li>
4781 <li><a href="#diagvec">diagvec()</a></li>
4782 </ul>
4783 </li>
4784 <br>
4785 </ul>
4786 <hr class="greyline"><br>
4787
4788 <a name="linspace"></a>
4789 <b>linspace(start, end, N=100)</b>
4790 <ul>
4791 <li>
4792 Generate a vector with <i>N</i> elements;
4793 the values of the elements linearly increase from <i>start</i> upto (and including) <i>end</i>
4794 <br>
4795 </li>
4796 <br>
4797 <li>
4798 Usage:
4799 <ul>
4800 <li><i>vector_type</i> v = linspace&lt;<i>vector_type</i>&gt;(start, end, N)</li>
4801 <li><i>matrix_type</i> X = linspace&lt;<i>matrix_type</i>&gt;(start, end, N)</li>
4802 </ul>
4803 </li>
4804 <br>
4805 <li>
4806 If a <i>matrix_type</i> is specified, the resultant matrix will have one column
4807 </li>
4808 <br>
4809 <li>
4810 Examples:
4811 <ul>
4812 <pre>
4813 vec v = linspace&lt;vec&gt;(10, 20, 5);
4814 mat X = linspace&lt;mat&gt;(10, 20, 5);
4815 </pre>
4816 </ul>
4817 </li>
4818 </ul>
4819 <br>
4820 <hr class="greyline"><br>
4821
4822 <a name="ones_standalone"></a>
4823 <b>
4824 ones(n_elem)
4825 <br>ones(n_rows, n_cols)
4826 <br>ones(n_rows, n_cols, n_slices)
4827 </b>
4828 <ul>
4829 <li>
4830 Generate a vector, matrix or cube with all elements set to one
4831 </li>
4832 <br>
4833 <li>
4834 Usage:
4835 <ul>
4836 <li><i>vector_type</i> v = ones&lt;<i>vector_type</i>&gt;(n_elem)</li>
4837 <li><i>matrix_type</i> X = ones&lt;<i>matrix_type</i>&gt;(n_rows, n_cols)</li>
4838 <li><i>cube_type</i> Q = ones&lt;<i>cube_type</i>&gt;(n_rows, n_cols, n_slices)</li>
4839 </ul>
4840 </li>
4841 <br>
4842 <li>
4843 Examples:
4844 <ul>
4845 <pre>
4846 vec v = ones&lt;vec&gt;(10);
4847 mat A = ones&lt;mat&gt;(5,6);
4848 cube Q = ones&lt;cube&gt;(5,6,7);
4849
4850 mat B = 123.0 * ones&lt;mat&gt;(5,6);
4851 </pre>
4852 </ul>
4853 </li>
4854 <br>
4855 <li>
4856 See also:
4857 <ul>
4858 <li><a href="#ones_member">.ones()</a> (member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i>)</li>
4859 <li><a href="#eye_standalone">eye()</a></li>
4860 </ul>
4861 </li>
4862 </ul>
4863 <br>
4864 <hr class="greyline"><br>
4865
4866 <a name="randu_randn_standalone"></a>
4867 <b>randu(n_elem)</b>
4868 <br><b>randu(n_rows, n_cols)</b>
4869 <br><b>randu(n_rows, n_cols, n_slices)</b>
4870 <br>
4871 <br><b>randn(n_elem)</b>
4872 <br><b>randn(n_rows, n_cols)</b>
4873 <br><b>randn(n_rows, n_cols, n_slices)</b>
4874 <ul>
4875 <li>
4876 Generate a vector, matrix or cube with the elements set to random values
4877 </li>
4878 <br>
4879 <li><i>randu()</i> uses a uniform distribution in the [0,1] interval
4880 </li>
4881 <br>
4882 <li><i>randn()</i> uses a normal/Gaussian distribution with zero mean and unit variance
4883 </li>
4884 <br>
4885 <li>
4886 Usage:
4887 <ul>
4888 <li><i>vector_type</i> v = randu&lt;<i>vector_type</i>&gt;(n_elem)</li>
4889 <li><i>matrix_type</i> X = randu&lt;<i>matrix_type</i>&gt;(n_rows, n_cols)</li>
4890 <li><i>cube_type</i> Q = randu&lt;<i>cube_type</i>&gt;(n_rows, n_cols, n_slices)</li>
4891 </ul>
4892 </li>
4893 <br>
4894 <li>
4895 To change the seed, use the <a href="http://cplusplus.com/reference/clibrary/cstdlib/srand/">std::srand()</a> function.
4896 </li>
4897 <br>
4898 <li>
4899 Examples:
4900 <ul>
4901 <pre>
4902 vec v = randu&lt;vec&gt;(5);
4903 mat A = randu&lt;mat&gt;(5,6);
4904 cube Q = randu&lt;cube&gt;(5,6,7);
4905 </pre>
4906 </ul>
4907 </li>
4908 <li>See also:
4909 <ul>
4910 <li><a href="#randu_randn_member">.randu() &amp; .randn()</a> (member functions)</li>
4911 <li><a href="#ones_standalone">ones()</a></li>
4912 <li><a href="#zeros_standalone">zeros()</a></li>
4913 <li><a href="#shuffle">shuffle()</a></li>
4914 <li><a href="http://cplusplus.com/reference/clibrary/cstdlib/srand/">std::srand()</a></li>
4915 <li><a href="#api_changes">API changes</a></li>
4916 </ul>
4917 </li>
4918 <br>
4919 </ul>
4920 <hr class="greyline"><br>
4921
4922 <a name="repmat"></a>
4923 <b>repmat(A, num_copies_per_row, num_copies_per_col)</b>
4924 <ul>
4925 <li>Generate a matrix by replicating matrix A in a block-like fashion</li>
4926 <br>
4927 <li>The generated matrix has the following size:
4928 <ul>
4929 rows = num_copies_per_row * A.n_rows
4930 <br>
4931 cols = num_copies_per_col * A.n_cols
4932 </ul>
4933 </li>
4934 <br>
4935 <li>
4936 Examples:
4937 <ul>
4938 <pre>
4939 mat A = randu&lt;mat&gt;(2, 3);
4940
4941 mat B = repmat(A, 4, 5);
4942 </pre>
4943 </ul>
4944 </li>
4945 <br>
4946 </ul>
4947 <hr class="greyline">
4948 <br>
4949
4950 <a name="toeplitz"></a>
4951 <b>toeplitz(A)</b>
4952 <br><b>toeplitz(A,B)</b>
4953 <br><b>circ_toeplitz(A)</b>
4954 <ul>
4955 <li>
4956 toeplitz(): generate a Toeplitz matrix, with the first column specified by <i>A</i>, and (optionally) the first row specified by <i>B</i>
4957 </li>
4958 <br>
4959 <li>
4960 circ_toeplitz(): generate a circulant Toeplitz matrix
4961 </li>
4962 <br>
4963 <li>
4964 A and B must be vectors
4965 </li>
4966 <br>
4967 <li>
4968 Examples:
4969 <ul>
4970 <pre>
4971 vec A = randu&lt;vec&gt;(5);
4972 mat X = toeplitz(A);
4973 mat Y = circ_toeplitz(A);
4974 </pre>
4975 </ul>
4976 </li>
4977 <br>
4978 <li>See also:
4979 <ul>
4980 <li><a href="http://mathworld.wolfram.com/ToeplitzMatrix.html">Toeplitz matrix in MathWorld</a></li>
4981 <li><a href="http://en.wikipedia.org/wiki/Toeplitz_matrix">Toeplitz matrix in Wikipedia</a></li>
4982 <li><a href="http://en.wikipedia.org/wiki/Circulant_matrix">Circulant matrix in Wikipedia</a></li>
4983 </ul>
4984 </li>
4985 <br>
4986 </ul>
4987 <hr class="greyline">
4988 <br>
4989
4990 <a name="zeros_standalone"></a>
4991 <b>zeros(n_elem)</b>
4992 <br><b>zeros(n_rows, n_cols)</b>
4993 <br><b>zeros(n_rows, n_cols, n_slices)</b>
4994 <ul>
4995 <li>
4996 Generate a vector, matrix or cube with the elements set to zero
4997 </li>
4998 <br>
4999 <li>
5000 Usage:
5001 <ul>
5002 <li><i>vector_type</i> v = zeros&lt;<i>vector_type</i>&gt;(n_elem)</li>
5003 <li><i>matrix_type</i> X = zeros&lt;<i>matrix_type</i>&gt;(n_rows, n_cols)</li>
5004 <li><i>cube_type</i> X = zeros&lt;<i>cube_type</i>&gt;(n_rows, n_cols, n_slices)</li>
5005 </ul>
5006 </li>
5007 <br>
5008 <li>
5009 Examples:
5010 <ul>
5011 <pre>
5012 vec v = zeros&lt;vec&gt;(5);
5013 mat A = zeros&lt;mat&gt;(5,6);
5014 cube Q = zeros&lt;cube&gt;(5,6,7);
5015 </pre>
5016 </ul>
5017 </li>
5018 <br>
5019 <li>
5020 See also:
5021 <ul>
5022 <li><a href="#zeros_member">.zeros()</a> (member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i>)</li>
5023 <li><a href="#ones_member">.ones()</a> (member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i>)</li>
5024 <li><a href="#ones_standalone">ones()</a></li>
5025 </ul>
5026 </li>
5027 </ul>
5028 <br>
5029 <hr class="greyline">
5030
5031 <hr class="greyline">
5032 <br>
5033 <br>
5034 <font size=+1><b>Functions Individually Applied to Each Element of a Matrix/Cube</b></font>
5035 <br>
5036 <br>
5037 <hr class="greyline">
5038 <br>
5039
5040 <a name="abs"></a>
5041 <b>abs(mat)</b>
5042 <br><b>abs(cube)</b>
5043 <br><b>abs(cx_mat)</b>
5044 <br><b>abs(cx_cube)</b>
5045 <ul>
5046 <li>
5047 Obtain the magnitude of each element
5048 </li>
5049 <br>
5050 <li>
5051 Usage for non-complex matrices:
5052 <ul>
5053 <li><i>matrix_type</i> Y = abs(X)</li>
5054 <li>X and Y must have the same <i>matrix_type</i></li>
5055 </ul>
5056 </li>
5057 <br>
5058 <li>
5059 Usage for non-complex cubes:
5060 <ul>
5061 <li><i>cube_type</i> Y = abs(X)</li>
5062 <li>X and Y must have the same <i>cube_type</i></li>
5063 </ul>
5064 </li>
5065 <br>
5066 <li>
5067 Usage for complex matrices:
5068 <ul>
5069 <li><i>non_complex_matrix_type</i> Y = abs(X)</li>
5070 <li>X must be a have complex matrix type, eg., <i>cx_mat</i> or <i>cx_fmat</i></li>
5071 <li>The type of Y must be related to the type of X,
5072 eg., if X has the type <i>cx_mat</i>, then the type of Y must be <i>mat</i>
5073 </ul>
5074 </li>
5075 <br>
5076 <li>
5077 Usage for complex cubes:
5078 <ul>
5079 <li><i>non_complex_cube_type</i> Y = abs(X)</li>
5080 <li>X must be a have complex cube type, eg., <i>cx_cube</i> or <i>cx_fcube</i></li>
5081 <li>The type of Y must be related to the type of X,
5082 eg., if X has the type <i>cx_cube</i>, then the type of Y must be <i>cube</i>
5083 </ul>
5084 </li>
5085 <br>
5086 <li>
5087 Examples:
5088 <ul>
5089 <pre>
5090 mat A = randu&lt;mat&gt;(5,5);
5091 mat B = abs(A);
5092
5093 cx_mat X = randu&lt;cx_mat&gt;(5,5);
5094 mat Y = abs(X);
5095 </pre>
5096 </ul>
5097 </li>
5098 </ul>
5099 <br>
5100 <hr class="greyline"><br>
5101
5102 <a name="eps"></a>
5103 <b>eps(X)</b>
5104 <ul>
5105 <li>
5106 Obtain the positive distance of the absolute value of each element of <i>X</i> to the next largest representable floating point number
5107 </li>
5108 <br>
5109 <li>
5110 <i>X</i> can be a scalar (eg. <i>double</i>), vector or matrix
5111 </li>
5112 <br>
5113 <li>
5114 Examples:
5115 <ul>
5116 <pre>
5117 mat A = randu&lt;mat&gt;(4,5);
5118 mat B = eps(A);
5119 </pre>
5120 </ul>
5121 </li>
5122 <br>
5123 <li>
5124 See also:
5125 <ul>
5126 <li><a href="#math_constants">math::eps()</a></li>
5127 <li><a href="http://mathworld.wolfram.com/Floating-PointArithmetic.html">Floating-Point Arithmetic in MathWorld</a></li>
5128 <li><a href="http://en.wikipedia.org/wiki/IEEE_754-2008">IEEE Standard for Floating-Point Arithmetic in Wikipedia</a></li>
5129
5130 </ul>
5131 </li>
5132 </ul>
5133 <br>
5134 <hr class="greyline"><br>
5135
5136 <a name="misc_fns"></a>
5137 <b>
5138 miscellaneous functions:
5139 <br>&nbsp; exp, exp2, exp10, trunc_exp,
5140 <br>&nbsp; log, log2, log10, trunc_log,
5141 <br>&nbsp; pow, sqrt, square
5142 <br>&nbsp; floor, ceil
5143 </b>
5144 <br>
5145 <ul>
5146 <li>
5147 Apply a function to each element
5148 </li>
5149 <br>
5150 <li>
5151 Usage:
5152 <ul>
5153 <li>
5154 <i>matrix_type</i> B = misc_fn(A)
5155 </li>
5156 <li>
5157 <i>cube_type</i> B = misc_fn(A)
5158 </li>
5159 <li>
5160 A and B must have the same <i>matrix_type/cube_type</i>
5161 </li>
5162 <li>
5163 misc_fn(A) is one of:
5164 <ul>
5165
5166 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
5167 <tbody>
5168 <tr>
5169 <td style="vertical-align: top;">
5170 exp(A)<sup>&nbsp;</sup>
5171 </td>
5172 <td style="vertical-align: top;">
5173 &nbsp;
5174 </td>
5175 <td style="vertical-align: top;">
5176 base-e exponential, <i>e<sup>x</sup></i>
5177 </td>
5178 </tr>
5179 <tr>
5180 <td style="vertical-align: top;">
5181 exp2(A)<sup>&nbsp;</sup>
5182 </td>
5183 <td style="vertical-align: top;">
5184 &nbsp;
5185 </td>
5186 <td style="vertical-align: top;">
5187 base-2 exponential, <i>2<sup>x</sup></i>
5188 </td>
5189 </tr>
5190 <tr>
5191 <td style="vertical-align: top;">
5192 exp10(A)<sup>&nbsp;</sup>
5193 </td>
5194 <td style="vertical-align: top;">
5195 &nbsp;
5196 </td>
5197 <td style="vertical-align: top;">
5198 base-10 exponential, <i>10<sup>x</sup></i>
5199 </td>
5200 </tr>
5201 <tr>
5202 <td style="vertical-align: top;">
5203 trunc_exp(A)
5204 </td>
5205 <td style="vertical-align: top;">
5206 &nbsp;
5207 </td>
5208 <td style="vertical-align: top;">
5209 base-e exponential,
5210 truncated to avoid infinity
5211 <br>
5212 <font size=-1>(only for elements with type <i>float</i> or <i>double</i>)</font>
5213 </td>
5214 </tr>
5215 <tr>
5216 <td style="vertical-align: top;">
5217 log(A)<sub>&nbsp;</sub>
5218 </td>
5219 <td style="vertical-align: top;">
5220 &nbsp;
5221 </td>
5222 <td style="vertical-align: top;">
5223 natural log, <i>log<sub>e</sub>&nbsp;x</i>
5224 </td>
5225 </tr>
5226 <tr>
5227 <td style="vertical-align: top;">
5228 log2(A)<sub>&nbsp;</sub>
5229 </td>
5230 <td style="vertical-align: top;">
5231 &nbsp;
5232 </td>
5233 <td style="vertical-align: top;">
5234 base-2 log, <i>log<sub>2</sub>&nbsp;x</i>
5235 </td>
5236 </tr>
5237 <tr>
5238 <td style="vertical-align: top;">
5239 log10(A)<sub>&nbsp;</sub>
5240 </td>
5241 <td style="vertical-align: top;">
5242 &nbsp;
5243 </td>
5244 <td style="vertical-align: top;">
5245 base-10 log, <i>log<sub>10</sub>&nbsp;x</i>
5246 </td>
5247 </tr>
5248 <tr>
5249 <td style="vertical-align: top;">
5250 trunc_log(A)
5251 </td>
5252 <td style="vertical-align: top;">
5253 &nbsp;
5254 </td>
5255 <td style="vertical-align: top;">
5256 natural log,
5257 truncated to avoid &plusmn;infinity
5258 <br>
5259 <font size=-1>(only for elements with type <i>float</i> or <i>double</i>)</font>
5260 </td>
5261 </tr>
5262 <tr>
5263 <td style="vertical-align: top;">
5264 pow(A, p)<sup>&nbsp;</sup>
5265 </td>
5266 <td style="vertical-align: top;">
5267 &nbsp;
5268 </td>
5269 <td style="vertical-align: top;">
5270 raise to the power of p, <i>x<sup>p</sup></i>
5271 </td>
5272 </tr>
5273 <tr>
5274 <td style="vertical-align: top;">
5275 sqrt(A)<sup>&nbsp;</sup>
5276 </td>
5277 <td style="vertical-align: top;">
5278 &nbsp;
5279 </td>
5280 <td style="vertical-align: top;">
5281 square root, <i>x<sup>&frac12;</sup></i>
5282 </td>
5283 </tr>
5284 <tr>
5285 <td style="vertical-align: top;">
5286 square(A)<sup>&nbsp;</sup>
5287 </td>
5288 <td style="vertical-align: top;">
5289 &nbsp;
5290 </td>
5291 <td style="vertical-align: top;">
5292 square, <i>x<sup>2</sup></i>
5293 </td>
5294 </tr>
5295 <tr>
5296 <td style="vertical-align: top;">
5297 floor(A)
5298 </td>
5299 <td style="vertical-align: top;">
5300 &nbsp;
5301 </td>
5302 <td style="vertical-align: top;">
5303 largest integral value that is not greater than the input value
5304 </td>
5305 </tr>
5306 <tr>
5307 <td style="vertical-align: top;">
5308 ceil(A)
5309 </td>
5310 <td style="vertical-align: top;">
5311 &nbsp;
5312 </td>
5313 <td style="vertical-align: top;">
5314 smallest integral value that is not less than the input value
5315 </td>
5316 </tr>
5317 </tbody>
5318 </table>
5319
5320
5321 </ul>
5322 </li>
5323
5324 </ul>
5325 </li>
5326 <br>
5327 <li>
5328 Examples:
5329 <ul>
5330 <pre>
5331 mat A = randu&lt;mat&gt;(5,5);
5332 mat B = exp(A);
5333 </pre>
5334 </ul>
5335 </li>
5336 </ul>
5337 <br>
5338 <hr class="greyline"><br>
5339
5340 <a name="trig_fns"></a>
5341 <b>trigonometric functions (cos, sin, tan, ...)</b>
5342 <ul>
5343 <li>
5344 Apply a trigonometric function to each element
5345 </li>
5346 <br>
5347 <li>
5348 Usage:
5349 <ul>
5350 <li>
5351 <i>matrix_type</i> Y = trig_fn(X)
5352 </li>
5353 <li>
5354 <i>cube_type</i> Y = trig_fn(X)
5355 </li>
5356 <li>
5357 X and Y must have the same <i>matrix_type/cube_type</i>
5358 </li>
5359 <li>
5360 trig_fn is one of:
5361 <ul>
5362 <li>
5363 cos family: <i>cos</i>, <i>acos</i>, <i>cosh</i>, <i>acosh</i>
5364 </li>
5365 <li>
5366 sin family: <i>sin</i>, <i>asin</i>, <i>sinh</i>, <i>asinh</i>
5367 </li>
5368 <li>
5369 tan family: <i>tan</i>, <i>atan</i>, <i>tanh</i>, <i>atanh</i>
5370 </li>
5371 </ul>
5372 </li>
5373
5374 </ul>
5375 </li>
5376 <br>
5377 <li>
5378 Examples:
5379 <ul>
5380 <pre>
5381 mat X = randu&lt;mat&gt;(5,5);
5382 mat Y = cos(X);
5383 </pre>
5384 </ul>
5385 </li>
5386 </ul>
5387 <br>
5388 <hr class="greyline">
5389
5390 <hr class="greyline">
5391 <br>
5392 <br>
5393 <font size=+1><b>Scalar Valued Functions of Vectors/Matrices/Cubes</b></font>
5394 <br>
5395 <br>
5396 <hr class="greyline">
5397 <br>
5398
5399 <a name="accu"></a>
5400 <b>accu(mat)</b>
5401 <br><b>accu(cube)</b>
5402 <ul>
5403 <li>
5404 Accumulate (sum) all elements
5405 </li>
5406 <br>
5407 <li>
5408 Examples:
5409 <ul>
5410 <pre>
5411 mat A = randu&lt;mat&gt;(5,5);
5412 double x = accu(A);
5413
5414 mat B = randu&lt;mat&gt;(5,5);
5415 double y = accu(A % B);
5416
5417 // operator % performs element-wise multiplication,
5418 // hence accu(A % B) is a "multiply-and-accumulate"
5419 // operation
5420 </pre>
5421 </ul>
5422 </li>
5423 <br>
5424 <li>
5425 See also:
5426 <ul>
5427 <li><a href="#sum">sum()</a></li>
5428 <li><a href="#cumsum">cumsum()</a></li>
5429 <li><a href="#as_scalar">as_scalar()</a></li>
5430 </ul>
5431 </li>
5432 <br>
5433 </ul>
5434 <hr class="greyline"><br>
5435
5436 <a name="as_scalar"></a>
5437 <b>as_scalar(expression)</b>
5438 <ul>
5439 <li>
5440 Evaluate an expression that results in a 1x1 matrix,
5441 followed by converting the 1x1 matrix to a pure scalar
5442 </li>
5443 <br>
5444 <li>
5445 If a binary or trinary expression is given (ie. 2 or 3 terms),
5446 the function will try to exploit the fact that the result is a 1x1 matrix
5447 by using optimised expression evaluations
5448 </li>
5449 <br>
5450 <li>
5451 Examples:
5452 <ul>
5453 <pre>
5454 rowvec r = randu&lt;rowvec&gt;(5);
5455 colvec q = randu&lt;colvec&gt;(5);
5456 mat X = randu&lt;mat&gt;(5,5);
5457
5458 // examples of some expressions
5459 // for which optimised implementations exist
5460
5461 double a = as_scalar(r*q);
5462 double b = as_scalar(r*X*q);
5463 double c = as_scalar(r*diagmat(X)*q);
5464 double d = as_scalar(r*inv(diagmat(X))*q);
5465 </pre>
5466 </ul>
5467 </li>
5468 <br>
5469 <li>
5470 See also:
5471 <ul>
5472 <li><a href="#accu">accu()</a></li>
5473 <li><a href="#conv_to">conv_to()</a></li>
5474 <li><a href="#dot">dot()</a></li>
5475 <li><a href="#norm">norm()</a></li>
5476 <li><a href="#reshape">reshape()</a></li>
5477 <li><a href="#resize">resize()</a></li>
5478 </ul>
5479 </li>
5480 <br>
5481 </ul>
5482 <hr class="greyline"><br>
5483
5484 <a name="det"></a>
5485 <b>det(A, slow = <i>false</i>)</b>
5486 <ul>
5487 <li>
5488 Determinant of square matrix <i>A</i>
5489 </li>
5490 <br>
5491 <li>
5492 If <i>A</i> is not square, a <i>std::logic_error</i> exception is thrown
5493 </li>
5494 <br>
5495 <li>
5496 <b>Caveat</b>: for large matrices you may want to use <a href="#log_det">log_det()</a> instead
5497 </li>
5498 <br>
5499 <li>
5500 For matrix sizes &le; 4x4, a fast algorithm is used by default.
5501 In rare instances, the fast algorithm might be less precise than the standard algorithm.
5502 To force the use of the standard algorithm, set the <i>slow</i> argument to <i>true</i>
5503 </li>
5504 <br>
5505 <li>
5506 Examples:
5507 <ul>
5508 <pre>
5509 mat A = randu&lt;mat&gt;(5,5);
5510 double x = det(A);
5511
5512 mat44 B = randu&lt;mat&gt;(4,4);
5513
5514 double y = det(B); // use fast algorithm by default
5515 double z = det(B, true); // use slow algorithm
5516 </pre>
5517 </ul>
5518 </li>
5519 <br>
5520 <li>
5521 See also:
5522 <ul>
5523 <li><a href="#log_det">log_det()</a></li>
5524 <li><a href="http://mathworld.wolfram.com/Determinant.html">determinant in MathWorld</a></li>
5525 <li><a href="http://en.wikipedia.org/wiki/Determinant">determinant in Wikipedia</a></li>
5526 </ul>
5527 </li>
5528 <br>
5529 </ul>
5530 <hr class="greyline"><br>
5531
5532 <a name="dot"></a>
5533 <b>dot(A, B)</b>
5534 <br><b>cdot(A, B)</b>
5535 <br><b>norm_dot(A, B)</b>
5536 <ul>
5537 <li>
5538 <i>dot(A,B)</i>: dot product of A and B, under the assumption that A and B are vectors with the same number of elements
5539 </li>
5540 <br>
5541 <li>
5542 <i>cdot(A,B)</i>: as per <i>dot(A,B)</i>, but the complex conjugate of A is used
5543 </li>
5544 <br>
5545 <li>
5546 <i>norm_dot(A,B)</i>: normalised version of <i>dot(A,B)</i>
5547 </li>
5548 <br>
5549 <li>
5550 Examples:
5551 <ul>
5552 <pre>
5553 vec a = randu&lt;vec&gt;(10);
5554 vec b = randu&lt;vec&gt;(10);
5555
5556 double x = dot(a,b);
5557 </pre>
5558 </ul>
5559 </li>
5560 <br>
5561 <li>See also:
5562 <ul>
5563 <li><a href="#as_scalar">as_scalar()</a></li>
5564 <li><a href="#cross">cross()</a></li>
5565 <li><a href="#conj">conj()</a></li>
5566 <li><a href="#norm">norm()</a></li>
5567 </ul>
5568 </li>
5569 <br>
5570 </ul>
5571 <hr class="greyline"><br>
5572
5573 <a name="log_det"></a>
5574 <b>log_det(val, sign, A)</b>
5575 <ul>
5576 <li>
5577 Log determinant of square matrix <i>A</i>, such that the determinant is equal to <i>exp(val)*sign</i>
5578 </li>
5579 <br>
5580 <li>
5581 If <i>A</i> is not square, a <i>std::logic_error</i> exception is thrown
5582 </li>
5583 <br>
5584 <li>
5585 Examples:
5586 <ul>
5587 <pre>
5588 mat A = randu&lt;mat&gt;(5,5);
5589
5590 double val;
5591 double sign;
5592
5593 log_det(val, sign, A);
5594 </pre>
5595 </ul>
5596 </li>
5597 <br>
5598 <li>
5599 See also:
5600 <ul>
5601 <li><a href="#det">det()</a></li>
5602 <li><a href="http://mathworld.wolfram.com/Determinant.html">determinant in MathWorld</a></li>
5603 <li><a href="http://en.wikipedia.org/wiki/Determinant">determinant in Wikipedia</a></li>
5604 </ul>
5605 </li>
5606 <br>
5607 </ul>
5608 <hr class="greyline"><br>
5609
5610 <a name="norm"></a>
5611 <b>
5612 norm(X, p)
5613 </b>
5614 <ul>
5615 <li>
5616 Compute the <i>p</i>-norm of <i>X</i>, where <i>X</i> can be a vector or a matrix
5617 </li>
5618 <br>
5619 <li>
5620 For vectors, <i>p</i> is an integer &ge;1, or one of: "-inf", "inf", "fro"
5621 </li>
5622 <br>
5623 <li>
5624 For matrices, <i>p</i> is one of: 1, 2, "inf", "fro"
5625 </li>
5626 <br>
5627 <li>
5628 "-inf" is the minimum norm, "inf" is the maximum norm, while "fro" is the Frobenius norm
5629 </li>
5630 <br>
5631 <li>
5632 To obtain the zero norm or Hamming norm (ie. the number of non-zero elements),
5633 you may want to use this expression: <a href="#accu">accu</a>(X&nbsp;!=&nbsp;0).
5634 </li>
5635 <br>
5636 <li>
5637 Examples:
5638 <ul>
5639 <pre>
5640 vec q = randu&lt;vec&gt;(5);
5641 double x = norm(q, 2);
5642 double y = norm(q, "inf");
5643 </pre>
5644 </ul>
5645 </li>
5646 <br>
5647 <li>
5648 See also:
5649 <ul>
5650 <li><a href="#dot">dot()</a></li>
5651 <li><a href="http://en.wikipedia.org/wiki/Norm_(mathematics)">Vector Norm in Wikipedia</a></li>
5652 <li><a href="http://mathworld.wolfram.com/VectorNorm.html">Vector Norm in MathWorld</a></li>
5653 <li><a href="http://en.wikipedia.org/wiki/Matrix_norm">Matrix Norm in Wikipedia</a></li>
5654 <li><a href="http://mathworld.wolfram.com/MatrixNorm.html">Matrix Norm in MathWorld</a></li>
5655 </ul>
5656 </li>
5657 <br>
5658 </ul>
5659 <hr class="greyline"><br>
5660
5661 <a name="rank"></a>
5662 <b>rank(X, tolerance = default)</b>
5663
5664 <ul>
5665 <li>Returns the rank of matrix <i>X</i></li><br>
5666 <li>Any singular values less than default tolerance are treated as zero</li><br>
5667 <li>The default tolerance is <i>max(X.n_rows, X.n_cols)*eps(sigma)</i>,
5668 where <i>sigma</i> is the largest singular value of <i>X</i>
5669 </li><br>
5670 <li>The computation is based on singular value decomposition;
5671 if the decomposition fails, a <i>std::runtime_error</i> exception is thrown</li><br>
5672 <li>
5673 Examples:
5674 <ul>
5675 <pre>
5676 mat A = randu&lt;mat&gt;(4,5);
5677 uword r = rank(A);
5678 </pre>
5679 </ul>
5680 </li>
5681 <br>
5682 <li>
5683 See also:
5684 <ul>
5685 <li><a href="#eps">eps()</a></li>
5686 <li><a href="http://mathworld.wolfram.com/MatrixRank.html">Rank in MathWorld</a></li>
5687 <li><a href="http://en.wikipedia.org/wiki/Rank_(linear_algebra)">Rank in Wikipedia</a></li>
5688 </ul>
5689 </li>
5690 </ul>
5691 <br>
5692 <hr class="greyline"><br>
5693
5694 <a name="trace"></a>
5695 <b>trace(mat)</b>
5696 <ul>
5697 <li>
5698 Sum of the diagonal elements of a square matrix
5699 </li>
5700 <br>
5701 <li>
5702 A <i>std::logic_error</i> exception is thrown if the given matrix is not square
5703 </li>
5704 <br>
5705 <li>
5706 Examples:
5707 <ul>
5708 <pre>
5709 mat A = randu&lt;mat&gt;(5,5);
5710 double x = trace(A);
5711 </pre>
5712 </ul>
5713 </li>
5714 <br>
5715 <li>
5716 See also:
5717 <ul>
5718 <li><a href="#diag">.diag()</a></li>
5719 <li><a href="#diagvec">diagvec()</a></li>
5720 <li><a href="#sum">sum()</a></li>
5721 </ul>
5722 </li>
5723 <br>
5724 </ul>
5725 <hr class="greyline">
5726
5727 <hr class="greyline">
5728 <br>
5729 <br>
5730 <font size=+1><b>Scalar/Vector Valued Functions of Vectors/Matrices</b></font>
5731 <br>
5732 <br>
5733 <hr class="greyline">
5734 <br>
5735
5736 <a name="diagvec"></a>
5737 <b>diagvec(A, k=0)</b>
5738 <ul>
5739 <li>
5740 Extract the <i>k</i>-th diagonal from matrix <i>A</i>
5741 </li>
5742 <br>
5743 <li>
5744 The argument <i>k</i> is optional -- by default the main diagonal is extracted (<i>k=0</i>)
5745 </li>
5746 <br>
5747 <li>For <i>k &gt; 0</i>, the <i>k</i>-th super-diagonal is extracted (top-right corner)</li>
5748 <br>
5749 <li>For <i>k &lt; 0</i>, the <i>k</i>-th sub-diagonal is extracted (bottom-left corner)</li>
5750 <br>
5751 <li>
5752 An extracted a diagonal is interpreted as a column vector
5753 </li>
5754 <br>
5755 <li>
5756 Examples:
5757 <ul>
5758 <pre>
5759 mat A = randu&lt;mat&gt;(5,5);
5760 vec d = diagvec(A);
5761 </pre>
5762 </ul>
5763 </li>
5764 <br>
5765 <li>See also:
5766 <ul>
5767 <li><a href="#diag">.diag()</a></li>
5768 <li><a href="#diagmat">diagmat()</a></li>
5769 </ul>
5770 </li>
5771 <br>
5772 </ul>
5773 <hr class="greyline">
5774 <br>
5775
5776 <a name="min_and_max"></a>
5777 <b>min(mat, dim=0)</b>
5778 <br><b>min(rowvec)</b>
5779 <br><b>min(colvec)</b>
5780 <br>
5781 <br><b>max(mat, dim=0)</b>
5782 <br><b>max(rowvec)</b>
5783 <br><b>max(colvec)</b>
5784 <ul>
5785 <li>
5786 For a matrix argument, return the extremum value for each column (dim=0), or each row (dim=1)
5787 </li>
5788 <br>
5789 <li>
5790 For a vector argument, return the extremum value
5791 </li>
5792 <br>
5793 <li>
5794 Examples:
5795 <ul>
5796 <pre>
5797 colvec q = randu&lt;colvec&gt;(10,1);
5798 double x = max(q);
5799
5800 mat A = randu&lt;mat&gt;(10,10);
5801 rowvec b = max(A);
5802
5803 // same result as max(A)
5804 // the 0 explicitly indicates
5805 // "traverse across rows"
5806 rowvec c = max(A,0);
5807
5808 // the 1 explicitly indicates
5809 // "traverse across columns"
5810 colvec d = max(A,1);
5811
5812 // find the overall maximum value
5813 double y = max(max(A));
5814 </pre>
5815 </ul>
5816 </li>
5817 <br>
5818 <li>
5819 See also:
5820 <ul>
5821 <li><a href="#min_and_max_member">.min() &amp; .max()</a> (member functions of Mat and Cube)</li>
5822 <li><a href="#running_stat">running_stat</a></li>
5823 <li><a href="#running_stat_vec">running_stat_vec</a></li>
5824 </ul>
5825 </li>
5826 <br>
5827 </ul>
5828 <hr class="greyline"><br>
5829
5830 <a name="prod"></a>
5831 <b>prod(mat, dim=0)</b>
5832 <br><b>prod(rowvec)</b>
5833 <br><b>prod(colvec)</b>
5834 <ul>
5835 <li>
5836 For a matrix argument, return the product of elements in each column (dim=0), or each row (dim=1)
5837 </li>
5838 <br>
5839 <li>
5840 For a vector argument, return the product of all elements
5841 </li>
5842 <br>
5843 <li>
5844 Examples:
5845 <ul>
5846 <pre>
5847 colvec q = randu&lt;colvec&gt;(10,1);
5848 double x = prod(q);
5849
5850 mat A = randu&lt;mat&gt;(10,10);
5851 rowvec b = prod(A);
5852
5853 // same result as prod(A)
5854 // the 0 explicitly indicates
5855 // "traverse across rows"
5856 rowvec c = prod(A,0);
5857
5858 // the 1 explicitly indicates
5859 // "traverse across columns"
5860 colvec d = prod(A,1);
5861
5862 // find the overall product
5863 double y = prod(prod(A));
5864 </pre>
5865 </ul>
5866 </li>
5867 <br>
5868 <li>
5869 See also:
5870 <ul>
5871 <li><a href="#schur_product">Schur product</a></li>
5872 </ul>
5873 </li>
5874 </ul>
5875 <br>
5876 <hr class="greyline"><br>
5877
5878
5879 <a name="sum"></a>
5880 <b>sum(mat, dim=0)</b>
5881 <br><b>sum(rowvec)</b>
5882 <br><b>sum(colvec)</b>
5883 <ul>
5884 <li>
5885 For a matrix argument, return the sum of elements in each column (dim=0), or each row (dim=1)
5886 </li>
5887 <br>
5888 <li>
5889 For a vector argument, return the sum of all elements
5890 </li>
5891 <br>
5892 <li>
5893 To get a sum of all the elements regardless of the argument type (ie. matrix or vector),
5894 you may wish to use <a href="#accu">accu()</a> instead
5895 </li>
5896 <br>
5897 <li>
5898 Examples:
5899 <ul>
5900 <pre>
5901 colvec q = randu&lt;colvec&gt;(10,1);
5902 double x = sum(q);
5903
5904 mat A = randu&lt;mat&gt;(10,10);
5905 rowvec b = sum(A);
5906
5907 // same result as sum(A)
5908 // the 0 explicitly indicates
5909 // "traverse across rows"
5910 rowvec c = sum(A,0);
5911
5912 // the 1 explicitly indicates
5913 // "traverse across columns"
5914 colvec d = sum(A,1);
5915
5916 // find the overall sum
5917 double y = sum(sum(A));
5918 </pre>
5919 </ul>
5920 </li>
5921 <br>
5922 <li>
5923 See also:
5924 <ul>
5925 <li><a href="#accu">accu()</a></li>
5926 <li><a href="#cumsum">cumsum()</a></li>
5927 <li><a href="#trace">trace()</a></li>
5928 <li><a href="#as_scalar">as_scalar()</a></li>
5929 </ul>
5930 </li>
5931 <br>
5932 </ul>
5933 <hr class="greyline"><br>
5934
5935
5936 <a name="stats_fns"></a>
5937 <b>statistics: mean, median, stddev, var</b>
5938
5939 <ul>
5940 <table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
5941 <tbody>
5942 <tr>
5943 <td style="vertical-align: top;">
5944 <b>mean(mat, dim=0)</b>
5945 <br><b>mean(colvec)</b>
5946 <br><b>mean(rowvec)</b>
5947 <br>
5948 <br>
5949 </td>
5950 <td style="vertical-align: top;">
5951 &nbsp;
5952 </td>
5953 <td style="vertical-align: top;">
5954 mean (average value)
5955 </td>
5956 </tr>
5957 <tr>
5958 <td style="vertical-align: top;">
5959 <b>median(mat, dim=0)</b>
5960 <br><b>median(colvec)</b>
5961 <br><b>median(rowvec)</b>
5962 <br>
5963 <br>
5964 </td>
5965 <td style="vertical-align: top;">
5966 &nbsp;
5967 </td>
5968 <td style="vertical-align: top;">
5969 median
5970 </td>
5971 </tr>
5972 <tr>
5973 <td style="vertical-align: top;">
5974 <b>stddev(mat, norm_type=0, dim=0)</b>
5975 <br><b>stddev(colvec, norm_type=0)</b>
5976 <br><b>stddev(rowvec, norm_type=0)</b>
5977 <br>
5978 <br>
5979 </td>
5980 <td style="vertical-align: top;">
5981 &nbsp;
5982 </td>
5983 <td style="vertical-align: top;">
5984 standard deviation
5985 </td>
5986 </tr>
5987 <tr>
5988 <td style="vertical-align: top;">
5989 <b>var(mat, norm_type=0, dim=0)</b>
5990 <br><b>var(colvec, norm_type=0)</b>
5991 <br><b>var(rowvec, norm_type=0)</b>
5992 <br>
5993 <br>
5994 </td>
5995 <td style="vertical-align: top;">
5996 &nbsp;
5997 </td>
5998 <td style="vertical-align: top;">
5999 variance
6000 </td>
6001 </tr>
6002 </tbody>
6003 </table>
6004 <br>
6005 <li>
6006 For a matrix argument, find a particular statistic for each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
6007 </li>
6008 <br>
6009 <li>
6010 For a vector argument, return a particular statistic calculated using all the elements of the vector
6011 </li>
6012 <br>
6013 <li>
6014 For the var() and stddev() functions, the default <i>norm_type=0</i> performs normalisation using <i>N-1</i> (where <i>N</i> is the number of samples),
6015 providing the best unbiased estimator.
6016 Using <i>norm_type=1</i> causes normalisation to be done using <i>N</i>, which provides the second moment around the mean
6017 </li>
6018 <br>
6019 <li>
6020 Examples:
6021 <ul>
6022 <pre>
6023 mat A = randu&lt;mat&gt;(5,5);
6024 mat B = mean(A);
6025 mat C = var(A);
6026 double m = mean(mean(A));
6027
6028 vec q = randu&lt;vec&gt;(5);
6029 double v = var(q);
6030 </pre>
6031 </ul>
6032 </li>
6033 <br>
6034 <li>
6035 See also:
6036 <ul>
6037 <li><a href="#cov">cov()</a></li>
6038 <li><a href="#cor">cor()</a></li>
6039 <li><a href="#running_stat">running_stat</a></li>
6040 <li><a href="#running_stat_vec">running_stat_vec</a></li>
6041 </ul>
6042 </li>
6043 </ul>
6044 <br>
6045 <hr class="greyline">
6046
6047 <hr class="greyline">
6048 <br>
6049 <br>
6050 <font size=+1><b>Vector/Matrix/Cube Valued Functions of Vectors/Matrices/Cubes</b></font>
6051 <br>
6052 <br>
6053 <hr class="greyline">
6054 <br>
6055
6056 <a name="conv"></a>
6057 <b>
6058 C = conv(A, B)
6059 </b>
6060 <ul>
6061 <li>
6062 Convolution of vectors A and B.
6063 </li>
6064 <br>
6065 <li>
6066 If A and B are polynomial coefficient vectors, convolving them is equivalent to multiplying the two polynomials
6067 </li>
6068 <br>
6069 <li>
6070 The convolution operation is also equivalent to FIR filtering
6071 </li>
6072 <br>
6073 <li>
6074 The orientation of the result vector is the same as the orientation of A (ie. column or row vector)
6075 </li>
6076 <br>
6077 <li>
6078 Examples:
6079 <ul>
6080 <pre>
6081 vec A = randu&lt;vec&gt;(128) - 0.5;
6082 vec B = randu&lt;vec&gt;(128) - 0.5;
6083
6084 vec C = conv(A,B);
6085 </pre>
6086 </ul>
6087 </li>
6088 <br>
6089 <li>
6090 See also:
6091 <ul>
6092 <li><a href="http://mathworld.wolfram.com/Convolution.html">Convolution in MathWorld</a></li>
6093 <li><a href="http://en.wikipedia.org/wiki/Convolution">Convolution in Wikipedia</a></li>
6094 <li><a href="http://en.wikipedia.org/wiki/Finite_impulse_response">FIR filter in Wikipedia</a></li>
6095 <li><a href="#cor">cor()</a></li>
6096 </ul>
6097 </li>
6098 </ul>
6099 <br>
6100 <hr class="greyline"><br>
6101
6102 <a name="conv_to"></a>
6103 <b>
6104 conv_to&lt;<i>type</i>&gt;::from(X)
6105 </b>
6106 <ul>
6107 <li>
6108 A form of casting
6109 </li>
6110 <br>
6111 <li>
6112 Convert between matrix/vector types (eg. <i>mat</i> to <i>fmat</i>), as well as cube types (eg. <i>cube</i> to <i>fcube</i>)
6113 </li>
6114 <br>
6115 <li>
6116 Conversion between <i>std::vector</i> and Armadillo matrices/vectors is also possible
6117 </li>
6118 <br>
6119 <li>
6120 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
6121 </li>
6122 <br>
6123 <li>
6124 Examples:
6125 <ul>
6126 <pre>
6127 mat A = randu&lt;mat&gt;(5,5);
6128 fmat B = conv_to&lt;fmat&gt;::from(A);
6129
6130 typedef std::vector&lt;double&gt; stdvec;
6131
6132 stdvec x(3);
6133 x[0] = 0.0; x[1] = 1.0; x[2] = 2.0;
6134
6135 colvec y = conv_to&lt; colvec &gt;::from(x);
6136 stdvec z = conv_to&lt; stdvec &gt;::from(y);
6137 </pre>
6138 </ul>
6139 </li>
6140 <br>
6141 <li>
6142 See also:
6143 <ul>
6144 <li><a href="#as_scalar">as_scalar()</a></li>
6145 <li><a href="#reshape">reshape()</a></li>
6146 <li><a href="#resize">resize()</a></li>
6147 <li><a href="#adv_constructors_mat">advanced constructors (matrices)</a></li>
6148 <li><a href="#adv_constructors_cube">advanced constructors (cubes)</a></li>
6149 </ul>
6150 </li>
6151 <br>
6152 </ul>
6153 <hr class="greyline"><br>
6154
6155 <a name="conj"></a>
6156 <b>conj(cx_mat)</b>
6157 <br><b>conj(cx_cube)</b>
6158 <ul>
6159 <li>
6160 Obtain the complex conjugate of each element in a complex matrix/cube
6161 </li>
6162 <br>
6163 <li>
6164 Examples:
6165 <ul>
6166 <pre>
6167 cx_mat X = randu&lt;cx_mat&gt;(5,5);
6168 cx_mat Y = conj(X);
6169 </pre>
6170 </ul>
6171 </li>
6172 <br>
6173 <li>See also:
6174 <ul>
6175 <li><a href="#trans">trans()</a></li>
6176 </ul>
6177 </li>
6178 <br>
6179 </ul>
6180 <hr class="greyline"><br>
6181
6182 <a name="cor"></a>
6183 <b>cor(X, Y, norm_type=0)</b>
6184 <br><b>cor(X, norm_type=0)</b>
6185 <ul>
6186 <li>
6187 For two matrix arguments <i>X</i> and <i>Y</i>,
6188 if each row of <i>X</i> and <i>Y</i> is an observation and each column is a variable,
6189 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>
6190 </li>
6191 <br>
6192 <li>
6193 For vector arguments, the type of vector is ignored and each element in the vector is treated as an observation
6194 </li>
6195 <br>
6196 <li>
6197 For matrices, <i>X</i> and <i>Y</i> must have the same dimensions
6198 </li>
6199 <br>
6200 <li>
6201 For vectors, <i>X</i> and <i>Y</i> must have the same number of elements
6202 </li>
6203 <br>
6204 <li>
6205 <i>cor(X)</i> is equivalent to <i>cor(X, X)</i>, also called autocorrelation
6206 </li>
6207 <br>
6208 <li>
6209 The default <i>norm_type=0</i> performs normalisation of the correlation matrix using <i>N-1</i> (where <i>N</i> is the number of observations).
6210 Using <i>norm_type=1</i> causes normalisation to be done using <i>N</i>
6211 </li>
6212 <br>
6213 <li>
6214 Examples:
6215 <ul>
6216 <pre>
6217 mat X = randu&lt;mat&gt;(4,5);
6218 mat Y = randu&lt;mat&gt;(4,5);
6219
6220 mat R = cor(X,Y);
6221 </pre>
6222 </ul>
6223 </li>
6224 <br>
6225 <li>
6226 See also:
6227 <ul>
6228 <li><a href="http://mathworld.wolfram.com/Correlation.html">Correlation in MathWorld</a></li>
6229 <li><a href="http://mathworld.wolfram.com/Autocorrelation.html">Autocorrelation in MathWorld</a></li>
6230 <li><a href="#cov">cov()</a></li>
6231 <li><a href="#conv">conv()</a></li>
6232 </ul>
6233 </li>
6234 </ul>
6235 <br>
6236 <hr class="greyline"><br>
6237
6238 <a name="cov"></a>
6239 <b>cov(X, Y, norm_type=0)</b>
6240 <br><b>cov(X, norm_type=0)</b>
6241 <ul>
6242 <li>
6243 For two matrix arguments <i>X</i> and <i>Y</i>,
6244 if each row of <i>X</i> and <i>Y</i> is an observation and each column is a variable,
6245 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>
6246 </li>
6247 <br>
6248 <li>
6249 For vector arguments, the type of vector is ignored and each element in the vector is treated as an observation
6250 </li>
6251 <br>
6252 <li>
6253 For matrices, <i>X</i> and <i>Y</i> must have the same dimensions
6254 </li>
6255 <br>
6256 <li>
6257 For vectors, <i>X</i> and <i>Y</i> must have the same number of elements
6258 </li>
6259 <br>
6260 <li>
6261 <i>cov(X)</i> is equivalent to <i>cov(X, X)</i>
6262 </li>
6263 <br>
6264 <li>
6265 The default <i>norm_type=0</i> performs normalisation using <i>N-1</i> (where <i>N</i> is the number of observations),
6266 providing the best unbiased estimation of the covariance matrix (if the observations are from a normal distribution).
6267 Using <i>norm_type=1</i> causes normalisation to be done using <i>N</i>, which provides the second moment matrix of the observations about their mean
6268 </li>
6269 <br>
6270 <li>
6271 Examples:
6272 <ul>
6273 <pre>
6274 mat X = randu&lt;mat&gt;(4,5);
6275 mat Y = randu&lt;mat&gt;(4,5);
6276
6277 mat C = cov(X,Y);
6278 </pre>
6279 </ul>
6280 </li>
6281 <br>
6282 <li>
6283 See also:
6284 <ul>
6285 <li><a href="#running_stat_vec">running_stat_vec</a></li>
6286 <li><a href="#stats_fns">statistics functions</a></li>
6287 <li><a href="http://mathworld.wolfram.com/Covariance.html">Covariance in MathWorld</a></li>
6288 <li><a href="#cor">cor()</a></li>
6289 </ul>
6290 </li>
6291 </ul>
6292 <br>
6293 <hr class="greyline"><br>
6294
6295 <a name="cross"></a>
6296 <b>cross(A, B)</b>
6297 <ul>
6298 <li>
6299 Calculate the cross product between A and B, under the assumption that A and B are 3 dimensional vectors
6300 </li>
6301 <br>
6302 <li>
6303 Examples:
6304 <ul>
6305 <pre>
6306 vec a = randu&lt;vec&gt;(3);
6307 vec b = randu&lt;vec&gt;(3);
6308
6309 vec c = cross(a,b);
6310 </pre>
6311 </ul>
6312 </li>
6313 <br>
6314 <li>
6315 See also:
6316 <ul>
6317 <li><a href="#dot">dot()</a></li>
6318 <li><a href="http://en.wikipedia.org/wiki/Cross_product">Cross product in Wikipedia</a></li>
6319 <li><a href="http://mathworld.wolfram.com/CrossProduct.html">Cross product in MathWorld</a></li>
6320 </ul>
6321 </li>
6322 </ul>
6323 <br>
6324 <hr class="greyline"><br>
6325
6326 <a name="cumsum"></a>
6327 <b>cumsum(mat, dim=0)</b>
6328 <br><b>cumsum(rowvec)</b>
6329 <br><b>cumsum(colvec)</b>
6330 <ul>
6331 <li>
6332 For a matrix argument, return a matrix containing the cumulative sum of elements in each column (dim=0, the default), or each row (dim=1)
6333 </li>
6334 <br>
6335 <li>
6336 For a vector argument, return a vector of the same orientation, containing the cumulative sum of elements
6337 </li>
6338 <br>
6339 <li>
6340 Examples:
6341 <ul>
6342 <pre>
6343 mat A = randu&lt;mat&gt;(5,5);
6344 mat B = cumsum(A);
6345
6346 vec x = randu&lt;vec&gt;(10);
6347 vec y = cumsum(x);
6348 </pre>
6349 </ul>
6350 </li>
6351 <br>
6352 <li>
6353 See also:
6354 <ul>
6355 <li><a href="#accu">accu()</a></li>
6356 <li><a href="#sum">sum()</a></li>
6357 </ul>
6358 </li>
6359 <br>
6360 </ul>
6361 <hr class="greyline"><br>
6362
6363 <a name="diagmat"></a>
6364 <b>diagmat(mat)</b>
6365 <br><b>diagmat(rowvec)</b>
6366 <br><b>diagmat(colvec)</b>
6367 <ul>
6368 <li>
6369 Interpret a matrix or vector as a diagonal matrix
6370 </li>
6371 <br>
6372 <li>
6373 For <i>mat</i>, given matrix must be square; the main diagonal is copied and all other elements in the generated matrix are set to zero
6374 </li>
6375 <br>
6376 <li>
6377 For <i>colvec</i> and <i>rowvec</i>, elements of the vector are placed on the main diagonal in the generated matrix and all other elements are set to zero
6378 </li>
6379 <br>
6380 <li>
6381 Examples:
6382 <ul>
6383 <pre>
6384 mat A = randu&lt;mat&gt;(5,5);
6385 mat B = diagmat(A);
6386 mat C = A*diagmat(A);
6387
6388 rowvec q = randu&lt;rowvec&gt;(5);
6389 colvec r = randu&lt;colvec&gt;(5);
6390 mat X = diagmat(q)*diagmat(r);
6391 </pre>
6392 </ul>
6393 </li>
6394 <br>
6395 <li>
6396 See also:
6397 <ul>
6398 <li><a href="#diagvec">diagvec()</a></li>
6399 <li><a href="#trimat">trimatu() / trimatl()</a></li>
6400 <li><a href="#symmat">symmatu() / symmatl()</a></li>
6401 <li><a href="#reshape">reshape()</a></li>
6402 </ul>
6403 </li>
6404 <br>
6405 </ul>
6406 <hr class="greyline">
6407 <br>
6408
6409 <a name="find"></a>
6410 <b>find(X, k=0, s="first")</b>
6411 <ul>
6412 <li>Return a column vector of the indices of non-zero elements of <i>X</i></li>
6413 <br>
6414 <li>The output vector must have the type <a href="#Col">uvec</a> or <a href="#Mat">umat</a>
6415 (ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
6416 </li>
6417 <br>
6418 <li>
6419 The input matrix <i>X</i> is interpreted as a vector, with column-by-column ordering of the elements of <i>X</i>
6420 </li>
6421 <br>
6422 <li>Relational operators can be used instead of <i>X</i>, eg.&nbsp;<i>A&nbsp;&gt;&nbsp;0.5</i>
6423 </li>
6424 <br>
6425 <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>
6426 <br>
6427 <li>If <i>s="first"</i> (default), return at most the first <i>k</i> indices of the non-zero elements
6428 </li>
6429 <br>
6430 <li>If <i>s="last"</i>, return at most the last <i>k</i> indices of the non-zero elements
6431 </li>
6432 <br>
6433 <li>
6434 Examples:
6435 <ul>
6436 <pre>
6437 mat A = randu&lt;mat&gt;(5,5);
6438 mat B = randu&lt;mat&gt;(5,5);
6439
6440 uvec q1 = find(A &gt; B);
6441 uvec q2 = find(A &gt; 0.5);
6442 uvec q3 = find(A &gt; 0.5, 3, "last");
6443 </pre>
6444 </ul>
6445 </li>
6446 <br>
6447 <li>
6448 See also:
6449 <ul>
6450 <li><a href="#conv_to">conv_to()</a> (convert between matrix/vector types)</li>
6451 <li><a href="#submat">submatrix views</a></li>
6452 <li><a href="#sort_index">sort_index()</a></li>
6453 </ul>
6454 </li>
6455 <br>
6456 </ul>
6457 <hr class="greyline">
6458 <br>
6459
6460 <a name="flip"></a>
6461 <b>fliplr(mat)</b>
6462 <br><b>flipud(mat)</b>
6463 <ul>
6464 <li>
6465 fliplr(): generate a copy of the input matrix, with the order of the columns reversed
6466 </li>
6467 <br>
6468 <li>
6469 flipud(): generate a copy of the input matrix, with the order of the rows reversed
6470 </li>
6471 <br>
6472 <li>
6473 Examples:
6474 <ul>
6475 <pre>
6476 mat A = randu&lt;mat&gt;(5,5);
6477
6478 mat B = fliplr(A);
6479 mat C = flipud(A);
6480 </pre>
6481 </ul>
6482 </li>
6483 <br>
6484 <li>
6485 See also:
6486 <ul>
6487 <li><a href="#swap_rows">.swap_rows() &amp; .swap_cols()</a> (member functions of <i>Mat</i>, <i>Col</i> and <i>Row</i> classes)</li>
6488 </ul>
6489 </li>
6490 <br>
6491 </ul>
6492 <hr class="greyline"><br>
6493
6494 <a name="imag_real"></a>
6495 <b>imag(cx_mat)</b>
6496 <br><b>imag(cx_cube)</b>
6497 <br>
6498 <br><b>real(cx_mat)</b>
6499 <br><b>real(cx_cube)</b>
6500 <ul>
6501 <li>
6502 Extract the imaginary/real part of a complex matrix/cube
6503 </li>
6504 <br>
6505 <li>
6506 Examples:
6507 <ul>
6508 <pre>
6509 cx_mat C = randu&lt;cx_mat&gt;(5,5);
6510
6511 mat A = imag(C);
6512 mat B = real(C);
6513 </pre>
6514 </ul>
6515 </li>
6516 <br>
6517 <li><b>Caveat:</b> versions 4.4, 4.5 and 4.6 of the GCC C++ compiler have a bug when using the <i>-std=c++0x</i> compiler option (ie. experimental support for C++11);
6518 to work around this bug, preface Armadillo's imag() and real() with the <i>arma</i> namespace qualification, eg. arma::imag(C)
6519 </li>
6520 <br>
6521 <li>See also:
6522 <ul>
6523 <li><a href="#set_imag">set_imag()&nbsp;/&nbsp;set_real()</a></li>
6524 </ul>
6525 </li>
6526 <br>
6527 </ul>
6528 <hr class="greyline"><br>
6529
6530 <a name="join"></a>
6531 <b>join_rows(mat A, mat B)</b>
6532 <br><b>join_cols(mat A, mat B)</b>
6533 <br><b>join_slices(cube A, cube B)</b>
6534 <ul>
6535 <li>
6536 join_rows():
6537 for two matrices A and B, append each row of B to its respective row of A;
6538 matrices A and B must have the same number of rows
6539 </li>
6540 <br>
6541 <li>
6542 join_cols():
6543 for two matrices A and B, append each column of B to its respective column of A;
6544 matrices A and B must have the same number of columns
6545 </li>
6546 <br>
6547 <li>
6548 join_slices():
6549 for two cubes A and B, append the slices of B to the slices of A;
6550 cubes A and B have the same number of rows and columns (ie. all slices must have the same size)
6551 </li>
6552 <br>
6553 <li>
6554 Examples:
6555 <ul>
6556 <pre>
6557 mat A = randu&lt;mat&gt;(4,5);
6558 mat B = randu&lt;mat&gt;(4,6);
6559 mat C = randu&lt;mat&gt;(6,5);
6560
6561 mat X = join_rows(A,B);
6562 mat Y = join_cols(A,C);
6563 </pre>
6564 </ul>
6565 </li>
6566 <br>
6567 <li>
6568 See also:
6569 <ul>
6570 <li><a href="#shed">shed rows/columns/slices</a></li>
6571 <li><a href="#insert">insert rows/columns/slices</a></li>
6572 <li><a href="#submat">submatrix views</a></li>
6573 <li><a href="#subcube">subcube views</a></li>
6574 </ul>
6575 </li>
6576 <br>
6577 </ul>
6578 <hr class="greyline"><br>
6579
6580 <a name="kron"></a>
6581 <b>kron(A,B)</b>
6582
6583 <ul>
6584 <li>Kronecker tensor product.</li>
6585 <br>
6586 <li>Using matrix <i>A</i> (with <i>n</i> rows and <i>p</i> columns) and matrix <i>B</i> (with <i>m</i> rows and <i>q</i> columns),
6587 <i>kron(A,B)</i> returns a matrix (with <i>nm</i> rows and <i>pq</i> columns) which denotes the tensor product of <i>A</i> and <i>B</i>
6588 </li>
6589 <br>
6590 <li>
6591 Examples:
6592 <ul>
6593 <pre>
6594 mat A = randu&lt;mat&gt;(4,5);
6595 mat B = randu&lt;mat&gt;(5,4);
6596
6597 mat K = kron(A,B);
6598 </pre>
6599 </ul>
6600 </li>
6601 <br>
6602 <li>
6603 See also:
6604 <ul>
6605 <li><a href="http://mathworld.wolfram.com/KroneckerProduct.html">Kronecker Product in MathWorld</a></li>
6606 </ul>
6607 </li>
6608 </ul>
6609 <br>
6610 <hr class="greyline"><br>
6611
6612 <a name="reshape"></a>
6613 <b>reshape(mat, n_rows, n_cols, dim=0)</b>
6614 <br><b>reshape(cube, n_rows, n_cols, n_slices, dim=0)</b>
6615 <ul>
6616 <li>
6617 Generate a matrix/cube sized according to given size specifications,
6618 whose elements are taken from the given matrix/cube, either column-wise (dim=0) or row-wise (dim=1);
6619 the elements in the generated object are placed column-wise (ie. the first column is filled up before filling the second column)
6620 </li>
6621 <br>
6622 <li>
6623 The layout of the elements in the generated object will be different to the layout in the given object
6624 </li>
6625 <br>
6626 <li>
6627 This function can be used to create a vector representation of a matrix (ie. concatenate all the columns or rows)
6628 </li>
6629 <br>
6630 <li>
6631 The total number of elements in the generated matrix/cube doesn't have to be the same as the total number of elements in the given matrix/cube
6632 </li>
6633 <br>
6634 <li>
6635 If the total number of elements in the given matrix/cube is less than the specified size,
6636 the remaining elements in the generated matrix/cube are set to zero
6637 </li>
6638 <br>
6639 <li>
6640 If the total number of elements in the given matrix/cube is greater than the specified size,
6641 only a subset of elements is taken from the given matrix/cube
6642 </li>
6643 <br>
6644 <li>
6645 <b>Caveat:</b>
6646 reshape() is slower than <a href="#set_size">.set_size()</a>, which doesn't preserve data
6647 </li>
6648 <br>
6649 <li>
6650 <b>Caveat:</b>
6651 if you wish to grow/shrink a matrix while preserving the elements <b>as well as</b> the layout of the elements,
6652 use <a href="#resize">resize()</a> instead
6653 </li>
6654 <br>
6655 <li>
6656 Examples:
6657 <ul>
6658 <pre>
6659 mat A = randu&lt;mat&gt;(10, 5);
6660 mat B = reshape(A, 5, 10);
6661 </pre>
6662 </ul>
6663 </li>
6664 <br>
6665 <li>
6666 See also:
6667 <ul>
6668 <li><a href="#reshape_member">.reshape()</a> (member function of Mat and Cube)</li>
6669 <li><a href="#set_size">.set_size()</a> (member function of Mat and Cube)</li>
6670 <li><a href="#resize">resize()</a></li>
6671 <li><a href="#as_scalar">as_scalar()</a></li>
6672 <li><a href="#conv_to">conv_to()</a></li>
6673 <li><a href="#diagmat">diagmat()</a></li>
6674 </ul>
6675 </li>
6676 <br>
6677 </ul>
6678 <hr class="greyline"><br>
6679
6680 <a name="resize"></a>
6681 <b>resize(mat, n_rows, n_cols)</b>
6682 <br><b>resize(cube, n_rows, n_cols, n_slices)</b>
6683 <ul>
6684 <li>
6685 Generate a matrix/cube sized according to given size specifications,
6686 whose elements as well as the layout of the elements are taken from the given matrix/cube
6687 </li>
6688 <br>
6689 <li>
6690 <b>Caveat:</b>
6691 resize() is slower than <a href="#set_size">.set_size()</a>, which doesn't preserve data
6692 </li>
6693 <br>
6694 <li>
6695 Examples:
6696 <ul>
6697 <pre>
6698 mat A = randu&lt;mat&gt;(4, 5);
6699 mat B = resize(A, 7, 6);
6700 </pre>
6701 </ul>
6702 </li>
6703 <br>
6704 <li>
6705 This function was added in version 2.4.1
6706 </li>
6707 <br>
6708 <li>
6709 See also:
6710 <ul>
6711 <li><a href="#resize_member">.resize()</a> (member function of Mat and Cube)</li>
6712 <li><a href="#set_size">.set_size()</a> (member function of Mat and Cube)</li>
6713 <li><a href="#reshape">reshape()</a></li>
6714 <li><a href="#as_scalar">as_scalar()</a></li>
6715 <li><a href="#conv_to">conv_to()</a></li>
6716 </ul>
6717 </li>
6718 <br>
6719 </ul>
6720 <hr class="greyline"><br>
6721
6722 <a name="shuffle"></a>
6723 <b>shuffle(mat, dim=0)</b>
6724 <br><b>shuffle(rowvec, dim=0)</b>
6725 <br><b>shuffle(colvec, dim=0)</b>
6726 <ul>
6727 <li>
6728 Shuffle the rows (dim=0) or columns (dim=1) of a matrix or vector
6729 </li>
6730 <br>
6731 <li>
6732 Examples:
6733 <ul>
6734 <pre>
6735 mat A = randu&lt;mat&gt;(4,5);
6736 mat B = shuffle(A);
6737 </pre>
6738 </ul>
6739 </li>
6740 <br>
6741 <li>
6742 See also:
6743 <ul>
6744 <li><a href="#randu_randn_standalone">randu() / randn()</a></li>
6745 <li><a href="#sort">sort()</a></li>
6746 </ul>
6747 </li>
6748 <br>
6749 </ul>
6750 <hr class="greyline"><br>
6751
6752 <a name="sort"></a>
6753 <b>sort(mat, sort_type=0, dim=0)</b>
6754 <br><b>sort(rowvec, sort_type=0)</b>
6755 <br><b>sort(colvec, sort_type=0)</b>
6756 <ul>
6757 <li>For a matrix argument, return a matrix with the elements of the input matrix sorted in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)</li>
6758 <br>
6759 <li><i>sort_type=0</i> (default) indicates an ascending sort</li>
6760 <br>
6761 <li><i>sort_type=1</i> indicates a descending sort</li>
6762 <br>
6763 <li>For a vector argument, return a vector which is a sorted version of the input vector</li>
6764 <br>
6765 <li>
6766 Examples:
6767 <ul>
6768 <pre>
6769 mat A = randu&lt;mat&gt;(10,10);
6770 mat B = sort(A);
6771 </pre>
6772 </ul>
6773 </li>
6774 <li>
6775 See also:
6776 <ul>
6777 <li><a href="#sort_index">sort_index()</a></li>
6778 <li><a href="#shuffle">shuffle()</a></li>
6779 <li><a href="#randu_randn_standalone">randu() / randn()</a></li>
6780 </ul>
6781 </li>
6782 <br>
6783 </ul>
6784 <hr class="greyline"><br>
6785
6786 <a name="sort_index"></a>
6787 <b>sort_index(colvec, sort_type=0)</b>
6788 <br><b>sort_index(rowvec, sort_type=0)</b>
6789 <ul>
6790 <li>Return a vector which describes the sorted order of the given vector's elements
6791 (ie. it contains the indices of the given vector's elements)
6792 </li>
6793 <br>
6794 <li>The output vector must have the type <a href="#Col">uvec</a> or <a href="#Mat">umat</a>
6795 (ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
6796 </li>
6797 <br>
6798 <li><i>sort_type=0</i> (default) indicates an ascending sort</li>
6799 <br>
6800 <li><i>sort_type=1</i> indicates a descending sort</li>
6801 <br>
6802 <li>
6803 Examples:
6804 <ul>
6805 <pre>
6806 vec q = randu&lt;vec&gt;(10);
6807 uvec indices = sort_index(q);
6808 </pre>
6809 </ul>
6810 </li>
6811 <br>
6812 <li>
6813 See also:
6814 <ul>
6815 <li><a href="#find">find()</a></li>
6816 <li><a href="#sort">sort()</a></li>
6817 </ul>
6818 </li>
6819 <br>
6820 </ul>
6821 <hr class="greyline"><br>
6822
6823 <a name="symmat"></a>
6824 <b>symmatu(A)</b>
6825 <br><b>symmatl(A)</b>
6826 <ul>
6827 <li>
6828 <i>symmatu(A)</i>: interpret square matrix <i>A</i> as symmetric, reflecting the upper triangle to the lower triangle
6829 </li>
6830 <br>
6831 <li>
6832 <i>symmatl(A)</i>: interpret square matrix <i>A</i> as symmetric, reflecting the lower triangle to the upper triangle
6833 </li>
6834 <br>
6835 <li>
6836 If <i>A</i> is non-square, a <i>std::logic_error</i> exception is thrown
6837 </li>
6838 <br>
6839 <li>
6840 Examples:
6841 <ul>
6842 <pre>
6843 mat A = randu&lt;mat&gt;(5,5);
6844
6845 mat B = symmatu(A);
6846 mat C = symmatl(A);
6847 </pre>
6848 </ul>
6849 </li>
6850 <br>
6851 <li>See also:
6852 <ul>
6853 <li><a href="#diagmat">diagmat()</a></li>
6854 <li><a href="#trimat">trimatu() / trimatl()</a></li>
6855 <li><a href="http://en.wikipedia.org/wiki/Symmetric_matrix">Symmetric matrix in Wikipedia</a></li>
6856 </ul>
6857 </li>
6858 </ul>
6859 <br>
6860 <hr class="greyline"><br>
6861
6862 <a name="strans"></a>
6863 <b>strans(mat)</b>
6864 <br><b>strans(colvec)</b>
6865 <br><b>strans(rowvec)</b>
6866 <ul>
6867 <li>
6868 Simple matrix transpose, without taking the conjugate of the elements (complex matrices)
6869 </li>
6870 <br>
6871 <li>
6872 Use <a href="#trans">trans()</a> instead, unless you explicitly need to take the transpose of a complex matrix without taking the conjugate of the elements
6873 </li>
6874 <br>
6875 <li>See also:
6876 <ul>
6877 <li><a href="#t_st_members">.st()</a></li>
6878 <li><a href="#trans">trans()</a></li>
6879 </ul>
6880 </li>
6881 </ul>
6882 <br>
6883 <hr class="greyline"><br>
6884
6885
6886 <a name="trans"></a>
6887 <b>trans(mat)</b>
6888 <br><b>trans(colvec)</b>
6889 <br><b>trans(rowvec)</b>
6890 <ul>
6891 <li>
6892 Matrix transpose / Hermitian transpose
6893 </li>
6894 <br>
6895 <li>
6896 If a given object has real elements, a normal transpose is done
6897 </li>
6898 <br>
6899 <li>
6900 If a given object has complex elements, a Hermitian transpose is done (ie. the conjugate of the elements is taken during the transpose operation)
6901 </li>
6902 <br>
6903 <li>
6904 <b>Caveat:</b> for complex matrices, the functionality of trans() has changed in version 2.0:
6905 <ul>
6906 <li>in version 1.2.x and earlier, trans() does not take the conjugate of complex elements</li>
6907 <li>in version 1.2.x and earlier, the deprecated htrans() function is used for the Hermitian transpose</li>
6908 </ul>
6909 </li>
6910 <br>
6911 <li>
6912 Examples:
6913 <ul>
6914 <pre>mat A = randu&lt;mat&gt;(5,10);
6915 mat B = trans(A);
6916 </pre>
6917 </ul>
6918 </li>
6919 <br>
6920 <li>See also:
6921 <ul>
6922 <li><a href="#t_st_members">.t()</a></li>
6923 <li><a href="#strans">strans()</a></li>
6924 </ul>
6925 </li>
6926 </ul>
6927 <br>
6928 <hr class="greyline"><br>
6929
6930
6931 <a name="trimat"></a>
6932 <b>trimatu(A)</b>
6933 <br><b>trimatl(A)</b>
6934 <ul>
6935 <li>
6936 trimatu(A): interpret square matrix A as upper triangular
6937 </li>
6938 <br>
6939 <li>
6940 trimatl(A): interpret square matrix A as lower triangular
6941 </li>
6942 <br>
6943 <li>
6944 A <i>std::logic_error</i> exception is thrown if A is non-square
6945 </li>
6946 <br>
6947 <li>
6948 Examples:
6949 <ul>
6950 <pre>mat A = randu&lt;mat&gt;(5,5);
6951 mat U = trimatu(A);
6952 mat L = trimatl(A);
6953
6954 // tell the inv() function to look only
6955 // at the upper triangular part
6956 mat X = inv( trimatu(U) );
6957 </pre>
6958 </ul>
6959 </li>
6960 <br>
6961 <li>See also:
6962 <ul>
6963 <li><a href="#symmat">symmatu() / symmatl()</a></li>
6964 <li><a href="#diagmat">diagmat()</a></li>
6965 <li><a href="#inv">inv()</a></li>
6966 <li><a href="#solve">solve()</a></li>
6967 <li><a href="http://mathworld.wolfram.com/TriangularMatrix.html">Triangular matrix in MathWorld</a></li>
6968 <li><a href="http://en.wikipedia.org/wiki/Triangular_matrix">Triangular matrix in Wikipedia</a></li>
6969 </ul>
6970 </li>
6971 </ul>
6972 <br>
6973 <hr class="greyline">
6974
6975
6976 <hr class="greyline">
6977 <br>
6978 <br>
6979 <font size=+1><b>Decompositions, Inverses and Equation Solvers</b></font>
6980 <br>
6981 <br>
6982 <hr class="greyline">
6983 <br>
6984
6985 <a name="chol"></a>
6986 <b>R = chol(X)</b>
6987 <br><b>chol(R, X)</b>
6988 <ul>
6989 <li>
6990 Cholesky decomposition of <i>X</i>, such that <i>trans(R)*R = X</i>
6991 </li>
6992 <br>
6993 <li>
6994 X must be a symmetric, positive-definite matrix
6995 </li>
6996 <br>
6997 <li>If the decomposition fails, <i>R</i> is reset and:
6998 <ul>
6999 <li><i>chol(X)</i> throws a <i>std::runtime_error</i> exception</li>
7000 <li><i>chol(R,X)</i> returns a bool set to <i>false</i></li>
7001 </ul>
7002 </li>
7003 <br>
7004 <li>
7005 Examples:
7006 <ul>
7007 <pre>
7008 mat X = randu&lt;mat&gt;(5,5);
7009 mat Y = trans(X)*X;
7010
7011 mat R = chol(Y);
7012 </pre>
7013 </ul>
7014 </li>
7015 <br>
7016 <li>
7017 See also:
7018 <ul>
7019 <li><a href="http://mathworld.wolfram.com/CholeskyDecomposition.html">Cholesky decomposition in MathWorld</a></li>
7020 </ul>
7021 </li>
7022 </ul>
7023 <br>
7024 <hr class="greyline"><br>
7025
7026 <a name="eig_sym"></a>
7027 <b>vec eigval = eig_sym(mat X)</b>
7028 <br><b>vec eigval = eig_sym(cx_mat X)</b>
7029 <br>
7030 <br><b>eig_sym(vec eigval, mat X)</b>
7031 <br><b>eig_sym(vec eigval, cx_mat X)</b>
7032 <br>
7033 <br><b>eig_sym(vec eigval, mat eigvec, mat X)</b>
7034 <br><b>eig_sym(vec eigval, cx_mat eigvec, cx_mat X)</b>
7035 <ul>
7036 <li>
7037 Eigen decomposition of symmetric/hermitian matrix <i>X</i></li>
7038 <br>
7039 <li>The eigenvalues and corresponding eigenvectors are stored in <i>eigval</i> and <i>eigvec</i>, respectively</li>
7040 <br>
7041 <li>
7042 The eigenvalues are in ascending order
7043 </li>
7044 <br>
7045 <li>If <i>X</i> is not square, a <i>std::logic_error</i> exception is thrown</li>
7046 <br>
7047 <li>If the decomposition fails, the output objects are reset and:
7048 <ul>
7049 <li><i>eig_sym(X)</i> throws a <i>std::runtime_error</i> exception</li>
7050 <li><i>eig_sym(eigval, X)</i> and <i>eig_sym(eigval, eigvec, X)</i> return a bool set to <i>false</i></li>
7051 </ul>
7052 </li>
7053 <br>
7054 <li>There is currently no check whether <i>X</i> is symmetric</li>
7055 <br>
7056 <li>
7057 Examples:
7058 <ul>
7059 <pre>
7060 mat A = randu&lt;mat&gt;(10,10);
7061 mat B = trans(A)*A; // generate a symmetric matrix
7062
7063 vec eigval;
7064 mat eigvec;
7065
7066 eig_sym(eigval, eigvec, B);
7067 </pre>
7068 </ul>
7069 </li>
7070 <br>
7071 <li>
7072 See also:
7073 <ul>
7074 <li><a href="#eig_gen">eig_gen()</a></li>
7075 <li><a href="#svd">svd()</a></li>
7076 <li><a href="#svd_econ">svd_econ()</a></li>
7077 <li><a href="http://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li>
7078 </ul>
7079 </li>
7080 <br>
7081 </ul>
7082 <hr class="greyline"><br>
7083
7084 <a name="eig_gen"></a>
7085 <b>eig_gen(cx_vec eigval, cx_mat eigvec, mat X, side='r')</b>
7086 <br>
7087 <b>eig_gen(cx_vec eigval, cx_mat eigvec, cx_mat X, side='r')</b>
7088 <br>
7089 <br>
7090 <b>eig_gen(cx_vec eigval, mat l_eigvec, mat r_eigvec, mat X)</b>
7091 <br>
7092 <b>eig_gen(cx_vec eigval, cx_mat l_eigvec, cx_mat r_eigvec, cx_mat X)</b>
7093 <ul>
7094 <li>
7095 Eigen decomposition of general (non-symmetric/non-hermitian) square matrix <i>X</i></li>
7096 <br>
7097 <li>The eigenvalues and corresponding eigenvectors are stored in <i>eigval</i> and <i>eigvec</i>, respectively</li>
7098 <br>
7099 <li>
7100 For the first two forms, <i>side='r'</i> (default) specifies that right eigenvectors are computed,
7101 while <i>side='l'</i> specifies that left eigenvectors are computed
7102 </li>
7103 <br>
7104 <li>For the last two forms, both left and right eigenvectors are computed</li>
7105 <br>
7106 <li>
7107 The eigenvalues are not guaranteed to be ordered
7108 </li>
7109 <br>
7110 <li>If <i>X</i> is not square, a <i>std::logic_error</i> exception is thrown</li>
7111 <br>
7112 <li>If the decomposition fails, the output objects are reset and <i>eig_gen()</i> returns a bool set to <i>false</i></li>
7113 <br>
7114 <li>
7115 Examples:
7116 <ul>
7117 <pre>
7118 mat A = randu&lt;mat&gt;(10,10);
7119
7120 cx_vec eigval;
7121 cx_mat eigvec;
7122
7123 eig_gen(eigval, eigvec, A);
7124 </pre>
7125 </ul>
7126 </li>
7127 <br>
7128 <li>
7129 See also:
7130 <ul>
7131 <li><a href="#eig_sym">eig_sym()</a></li>
7132 <li><a href="#svd">svd()</a></li>
7133 <li><a href="#svd_econ">svd_econ()</a></li>
7134 <li><a href="http://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li>
7135 </ul>
7136 </li>
7137 </ul>
7138 <br>
7139 <hr class="greyline"><br>
7140
7141 <a name="inv"></a>
7142 <b>B = inv(A, slow = <i>false</i>)</b>
7143 <br>
7144 <b>inv(B, A, slow = <i>false</i>)</b>
7145 <ul>
7146 <li>
7147 Inverse of square matrix <i>A</i>
7148 </li>
7149 <br>
7150 <li>
7151 If <i>A</i> is known to be a triangular matrix,
7152 the inverse can be computed faster by explicitly marking the matrix as triangular
7153 through <a href="#trimat">trimatu()</a> or <a href="#trimat">trimatl()</a>
7154 </li>
7155 <br>
7156 <li>
7157 If <i>A</i> is known to be a positive-definite symmetric matrix,
7158 the inverse can be computed faster by explicitly marking the matrix using sympd()
7159 </li>
7160 <br>
7161 <li>
7162 If <i>A</i> is not square, a <i>std::logic_error</i> exception is thrown
7163 </li>
7164 <br>
7165 <li>If <i>A</i> appears to be singular, <i>B</i> is reset and:
7166 <ul>
7167 <li><i>inv(A)</i> throws a <i>std::runtime_error</i> exception</li>
7168 <li><i>inv(B,A)</i> returns a bool set to <i>false</i></li>
7169 </ul>
7170 </li>
7171 <br>
7172 <li>
7173 If you want to solve a system of linear equations, eg., <i>X = inv(A)*B</i>,
7174 the <a href="#solve">solve()</a> function is generally more efficient
7175 </li>
7176 <br>
7177 <li>
7178 For matrix sizes &le; 4x4, a fast inverse algorithm is used by default.
7179 In rare instances, the fast algorithm might be less precise than the standard algorithm.
7180 To force the use of the standard algorithm, set the <i>slow</i> argument to <i>true</i>
7181 </li>
7182 <br>
7183 <li>
7184 Examples:
7185 <ul>
7186 <pre>
7187 mat A = randu&lt;mat&gt;(5,5);
7188 mat B = inv(A);
7189
7190
7191 // Diagonal elements in C are set to the
7192 // reciprocal of the corresponding elements in A.
7193 // Off-diagonal elements in C are set to zero.
7194 mat C = inv( diagmat(A) );
7195
7196
7197 // tell inv() to look only at the upper triangular part of A
7198 mat D = inv( trimatu(A) );
7199
7200
7201 // tell inv() that AA is a symmetric positive definite matrix
7202 mat AA = A*trans(A);
7203 mat E = inv( sympd(AA) );
7204
7205
7206 mat44 F = randu&lt;mat&gt;(4,4);
7207
7208 mat G = inv(F); // use fast algorithm by default
7209 mat H = inv(F, true); // use slow algorithm
7210 </pre>
7211 </ul>
7212 </li>
7213 <br>
7214 <li>
7215 See also:
7216 <ul>
7217 <li><a href="#pinv">pinv()</a>
7218 <li><a href="#solve">solve()</a></li>
7219 <li><a href="#trimat">trimatu() / trimatl()</a></li>
7220 <li><a href="http://mathworld.wolfram.com/MatrixInverse.html">matrix inverse in MathWorld</a></li>
7221 <li><a href="http://en.wikipedia.org/wiki/Invertible_matrix">invertible matrix in Wikipedia</a></li>
7222 </ul>
7223 </li>
7224 </ul>
7225 <br>
7226 <hr class="greyline"><br>
7227
7228
7229
7230 <a name="lu"></a>
7231 <b>lu(mat L, mat U, mat P, mat X)</b>
7232 <br>
7233 <b>lu(mat L, mat U, mat X)</b>
7234 <ul>
7235 <li>
7236 Lower-upper decomposition (with partial pivoting) of matrix <i>X</i>
7237 </li>
7238 <br>
7239 <li>
7240 The first form provides
7241 a lower-triangular matrix <i>L</i>,
7242 an upper-triangular matrix <i>U</i>,
7243 and a permutation matrix <i>P</i>,
7244 such that <i>trans(P)*L*U&nbsp;=&nbsp;X</i>
7245 </li>
7246 <br>
7247 <li>
7248 The second form provides permuted <i>L</i> and <i>U</i>, such that <i>L*U = X</i>.
7249 Note that in this case <i>L</i> is generally not lower-triangular
7250 </li>
7251 <br>
7252 <li>
7253 If the decomposition fails, the output objects are reset and <i>lu()</i> returns a bool set to <i>false</i>
7254 </li>
7255 <br>
7256 <li>
7257 Examples:
7258 <ul>
7259 <pre>
7260 mat A = randu&lt;mat&gt;(5,5);
7261
7262 mat L, U, P;
7263
7264 lu(L, U, P, A);
7265
7266 mat B = trans(P)*L*U;
7267 </pre>
7268 </ul>
7269 </li>
7270 <br>
7271 <li>
7272 See also:
7273 <ul>
7274 <li><a href="http://en.wikipedia.org/wiki/LU_decomposition">LU decomposition in Wikipedia</a></li>
7275 <li><a href="http://mathworld.wolfram.com/LUDecomposition.html">LU decomposition in MathWorld</a></li>
7276 </ul>
7277 </li>
7278 </ul>
7279 <br>
7280 <hr class="greyline"><br>
7281
7282 <a name="pinv"></a>
7283 <b>B = pinv(A, tolerance = default)</b>
7284 <br><b>pinv(B, A, tolerance = default)</b>
7285 <ul>
7286 <li>Moore-Penrose pseudo-inverse of matrix <i>A</i></li>
7287 <br>
7288 <li>The computation is based on singular value decomposition;
7289 if the decomposition fails, <i>B</i> is reset and:
7290 <ul>
7291 <li><i>pinv(A)</i> throws a <i>std::runtime_error</i> exception</li>
7292 <li><i>pinv(B,A)</i> returns a bool set to <i>false</i></li>
7293 </ul>
7294 <br>
7295 <li>Any singular values less than <i>tol</i> are treated as zero</li>
7296 <br>
7297 <li>For matrix <i>A</i> with <i>m</i> rows and <i>n</i> columns,
7298 the default tolerance is <i>max(m,n)*norm(A)*math::eps()</i>,
7299 where <i>math::eps()</i> denotes the difference between 1 and the least value greater than 1 that is representable</li>
7300 <br>
7301 <li>
7302 Examples:
7303 <ul>
7304 <pre>
7305 mat A = randu&lt;mat&gt;(4,5);
7306 mat B = pinv(A);
7307 </pre>
7308 </ul>
7309 </li>
7310 <br>
7311 <li>
7312 See also:
7313 <ul>
7314 <li><a href="#inv">inv()</a></li>
7315 <li><a href="#math_constants">math::eps()</a></li>
7316 <li><a href="http://mathworld.wolfram.com/Pseudoinverse.html">Pseudoinverse in MathWorld</a></li>
7317 <li><a href="http://mathworld.wolfram.com/Moore-PenroseMatrixInverse.html">Moore-Penrose Matrix Inverse in MathWorld</a></li>
7318 <li><a href="http://en.wikipedia.org/wiki/Moore-Penrose_pseudoinverse">Moore-Penrose pseudoinverse in Wikipedia</a></li>
7319 </ul>
7320 </li>
7321 </ul>
7322 <br>
7323 <hr class="greyline"><br>
7324
7325 <a name="princomp"></a>
7326 <b>mat coeff = princomp(mat X)</b>
7327 <br><b>cx_mat coeff = princomp(cx_mat X)</b><br>
7328
7329 <br><b>princomp(mat coeff, mat X)</b>
7330 <br><b>princomp(cx_mat coeff, cx_mat X)</b><br>
7331
7332 <br><b>princomp(mat coeff, mat score, mat X)</b>
7333 <br><b>princomp(cx_mat coeff, cx_mat score, cx_mat X)</b><br>
7334
7335 <br><b>princomp(mat coeff, mat score, vec latent, mat X)</b>
7336 <br><b>princomp(cx_mat coeff, cx_mat score, vec latent, cx_mat X)</b><br>
7337
7338 <br><b>princomp(mat coeff, mat score, vec latent, vec tsquared, mat X)</b>
7339 <br><b>princomp(cx_mat coeff, cx_mat score, vec latent, cx_vec tsquared, cx_mat X)</b><br>
7340 <br>
7341 <ul>
7342 <li>Principal component analysis of matrix <i>X</i></li><br>
7343 <li>Each row of <i>X</i> is an observation and each column is a variable</li><br>
7344 <li>output objects:
7345 <ul>
7346 <li><i>coeff</i>: principal component coefficients</li>
7347 <li><i>score</i>: projected data</li>
7348 <li><i>latent</i>: eigenvalues of the covariance matrix of <i>X</i></li>
7349 <li><i>tsquared</i>: Hotteling's statistic for each sample</li>
7350 </ul>
7351 </li>
7352 <br>
7353 <li>The computation is based on singular value decomposition;
7354 if the decomposition fails, the output objects are reset and:
7355 <ul>
7356 <li><i>princomp(X)</i> throws a <i>std::runtime_error</i> exception</li>
7357 <li>remaining forms of <i>princomp()</i> return a bool set to <i>false</i></li>
7358 </ul>
7359 </li>
7360 <br>
7361 <li>
7362 Examples:
7363 <ul>
7364 <pre>
7365 mat A = randu&lt;mat&gt;(5,4);
7366
7367 mat coeff;
7368 mat score;
7369 vec latent;
7370 vec tsquared;
7371
7372 princomp(coeff, score, latent, tsquared, A);
7373 </pre>
7374 </ul>
7375 </li>
7376 <br>
7377 <li>
7378 See also:
7379 <ul>
7380 <li><a href="http://en.wikipedia.org/wiki/Principal_component_analysis">principal components analysis in Wikipedia</a></li>
7381 <li><a href="http://mathworld.wolfram.com/PrincipalComponentAnalysis.html">principal components analysis in MathWorld</a></li>
7382 </ul>
7383 </li>
7384 <br>
7385 </ul>
7386 <hr class="greyline"><br>
7387
7388 <a name="qr"></a>
7389 <b>qr(Q,R,X)</b>
7390 <ul>
7391 <li>
7392 Decomposition of matrix <i>X</i> into an orthogonal (<i>Q</i>) and a right triangular matrix (<i>R</i>), such that <i>Q*R = X</i>
7393 </li>
7394 <br>
7395 <li>
7396 If the decomposition fails, <i>Q</i> and <i>R</i> are reset and the function returns a bool set to <i>false</i>
7397 </li>
7398 <br>
7399 <li>
7400 Examples:
7401 <ul>
7402 <pre>
7403 mat X = randu&lt;mat&gt;(5,5);
7404 mat Q, R;
7405
7406 qr(Q,R,X);
7407 </pre>
7408 </ul>
7409 </li>
7410 <br>
7411 <li>
7412 See also:
7413 <ul>
7414 <li><a href="http://mathworld.wolfram.com/QRDecomposition.html">QR decomposition in MathWorld</a></li>
7415 <li><a href="http://octave.sourceforge.net/octave/function/qr.html">QR decomposition in Octave</a></li>
7416 </ul>
7417 </li>
7418 </ul>
7419 <br>
7420 <hr class="greyline"><br>
7421
7422 <a name="solve"></a>
7423 <b>X = solve(A, B, slow = false)</b>
7424 <br><b>solve(X, A, B, slow = false)</b>
7425 <ul>
7426 <li>Solve a system of linear equations, ie., <i>A*X = B</i>, where <i>X</i> is unknown</li>
7427 <br>
7428 <li>For a square matrix <i>A</i>, this function is conceptually the same as <i>X = inv(A)*B</i>, but is more efficient</li>
7429 <br>
7430 <li>Similar functionality to the "\" (left division operator) operator in Matlab/Octave, ie. <i>X&nbsp;=&nbsp;A&nbsp;\&nbsp;B</i></li>
7431 <br>
7432 <li>The number of rows in <i>A</i> and <i>B</i> must be the same</li>
7433 <br>
7434 <li>
7435 If <i>A</i> is known to be a triangular matrix,
7436 the solution can be computed faster by explicitly marking the matrix as triangular
7437 through <a href="#trimat">trimatu()</a> or <a href="#trimat">trimatl()</a>
7438 </li>
7439 <br>
7440 <li>
7441 If <i>A</i> is non-square (and hence also non-triangular),
7442 solve() will also try to provide approximate solutions to under-determined as well as over-determined systems</li>
7443 <br>
7444 <li>
7445 If no solution is found, <i>X</i> is reset and:
7446 <ul>
7447 <li><i>solve(A,B)</i> throws a <i>std::runtime_error</i> exception</li>
7448 <li><i>solve(X,A,B)</i> returns a bool set to <i>false</i></li>
7449 </ul>
7450 </li>
7451 <br>
7452 <li>
7453 For matrix sizes &le; 4x4, a fast algorithm is used by default.
7454 In rare instances, the fast algorithm might be less precise than the standard algorithm.
7455 To force the use of the standard algorithm, set the <i>slow</i> argument to <i>true</i>
7456 </li>
7457 <br>
7458 <li>
7459 <b>NOTE:</b> Old versions of the ATLAS library (eg.&nbsp;3.6) can corrupt memory and crash your program;
7460 the standard LAPACK library and later versions of ATLAS (eg.&nbsp;3.8) work without problems
7461 </li>
7462 <br>
7463 <li>
7464 Examples:
7465 <ul>
7466 <pre>
7467 mat A = randu&lt;mat&gt;(5,5);
7468 vec b = randu&lt;vec&gt;(5);
7469 mat B = randu&lt;mat&gt;(5,5);
7470
7471 vec x = solve(A, b);
7472 mat X = solve(A, B);
7473
7474 vec x2;
7475 solve(x2, A, b);
7476
7477 // tell solve() to look only at the upper triangular part of A
7478 mat Y = solve( trimatu(A), B );
7479
7480
7481 mat44 C = randu&lt;mat&gt;(4,4);
7482 mat44 D = randu&lt;mat&gt;(4,4);
7483
7484 mat E = solve(C, D); // use fast algorithm by default
7485 mat F = solve(C, D, true); // use slow algorithm
7486
7487 </pre>
7488 </ul>
7489 </li>
7490 <br>
7491 <li>
7492 See also:
7493 <ul>
7494 <li><a href="#inv">inv()</a></li>
7495 <li><a href="#syl">syl()</a></li>
7496 <li><a href="#trimat">trimatu() / trimatl()</a></li>
7497 <li><a href="http://mathworld.wolfram.com/LinearSystemofEquations.html">linear system of equations in MathWorld</a></li>
7498 <li><a href="http://en.wikipedia.org/wiki/Linear_system_of_equations">system of linear equations in Wikipedia</a></li>
7499 </ul>
7500 </li>
7501 <br>
7502 </ul>
7503 <hr class="greyline"><br>
7504
7505
7506 <a name="svd"></a>
7507 <b>vec s = svd(mat X)</b>
7508 <br><b>vec s = svd(cx_mat X)</b>
7509 <br>
7510 <br><b>svd(vec s, mat X)</b>,
7511 <br><b>svd(vec s, cx_mat X)</b>
7512 <br>
7513 <br><b>svd(mat U, vec s, mat V, mat X)</b>
7514 <br><b>svd(cx_mat U, vec s, cx_mat V, cx_mat X)</b>
7515 <ul>
7516 <li>
7517 The single and two argument versions compute the singular values of <i>X</i>
7518 </li>
7519 <br>
7520 <li>
7521 The four argument version computes the full singular value decomposition of <i>X</i>
7522 </li>
7523 <br>
7524 <li>If <i>X</i> is square, it can be reconstructed using <i>X = U*diagmat(s)*trans(V)</i>
7525 </li>
7526 <br>
7527 <li>
7528 The singular values are in descending order
7529 </li>
7530 <br>
7531 <li>
7532 If the decomposition fails, the output objects are reset and:
7533 <ul>
7534 <li><i>svd(X)</i> throws a <i>std::runtime_error</i> exception</li>
7535 <li><i>svd(s,X)</i> and <i>svd(U,s,V,X)</i> return a bool set to <i>false</i></li>
7536 </ul>
7537 </li>
7538 <br>
7539 <li>
7540 <b>NOTE:</b> Old versions of the ATLAS library (eg.&nbsp;3.6) can corrupt memory and crash your program;
7541 the standard LAPACK library and later versions of ATLAS (eg.&nbsp;3.8) work without problems
7542 </li>
7543 <br>
7544 <li>
7545 Examples:
7546 <ul>
7547 <pre>
7548 mat X = randu&lt;mat&gt;(5,5);
7549
7550 mat U;
7551 vec s;
7552 mat V;
7553 svd(U,s,V,X);
7554 </pre>
7555 </ul>
7556 </li>
7557 <br>
7558 <li>
7559 See also:
7560 <ul>
7561 <li><a href="#svd_econ">svd_econ()</a></li>
7562 <li><a href="#eig_gen">eig_gen()</a></li>
7563 <li><a href="#eig_sym">eig_sym()</a></li>
7564 <li><a href="http://en.wikipedia.org/wiki/Singular_value_decomposition">singular value decomposition in Wikipedia</a></li>
7565 <li><a href="http://mathworld.wolfram.com/SingularValueDecomposition.html">singular value decomposition in MathWorld</a></li>
7566 </ul>
7567 </li>
7568 </ul>
7569 <br>
7570 <hr class="greyline">
7571 <br>
7572
7573 <a name="svd_econ"></a>
7574 <b>svd_econ(mat U, vec s, mat V, mat X, mode = 'b')</b>
7575 <br><b>svd_econ(cx_mat U, vec s, cx_mat V, cx_mat X, mode = 'b')</b>
7576 <ul>
7577 <li>
7578 Economical singular value decomposition of <i>X</i>
7579 </li>
7580 <br>
7581 <li>
7582 mode is one of:
7583 <ul>
7584 <li><i>'l'</i>: compute only left singular vectors</li>
7585 <li><i>'r'</i>: compute only right singular vectors</li>
7586 <li><i>'b'</i>: compute both left and right singular vectors (default)</li>
7587 </ul>
7588 </li>
7589 <br>
7590 <li>
7591 The singular values are in descending order
7592 </li>
7593 <br>
7594 <li>
7595 If the decomposition fails, the output objects are reset and bool set to <i>false</i> is returned
7596 </li>
7597 <br>
7598 <li>
7599 Examples:
7600 <ul>
7601 <pre>
7602 mat X = randu&lt;mat&gt;(4,5);
7603
7604 mat U;
7605 vec s;
7606 mat V;
7607 svd_econ(U, s, V, X, 'l');
7608 </pre>
7609 </ul>
7610 </li>
7611 <br>
7612 <li>
7613 See also:
7614 <ul>
7615 <li><a href="#svd">svd()</a></li>
7616 <li><a href="#eig_gen">eig_gen()</a></li>
7617 <li><a href="#eig_sym">eig_sym()</a></li>
7618 <li><a href="http://en.wikipedia.org/wiki/Singular_value_decomposition">singular value decomposition in Wikipedia</a></li>
7619 <li><a href="http://mathworld.wolfram.com/SingularValueDecomposition.html">singular value decomposition in MathWorld</a></li>
7620 </ul>
7621 </li>
7622 </ul>
7623 <br>
7624 <hr class="greyline">
7625 <br>
7626
7627 <a name="syl"></a>
7628 <b>X = syl(A, B, C)</b>
7629 <br><b>syl(X, A, B, C)</b>
7630 <ul>
7631 <li>Solve the Sylvester equation, ie., <i>AX + XB + C = 0</i>, where <i>X</i> is unknown.</li>
7632 <br>
7633 <li>Matrices <i>A</i>, <i>B</i> and <i>C</i> must be square sized.</li>
7634 <br>
7635 <li>
7636 If no solution is found, <i>X</i> is reset and:
7637 <ul>
7638 <li><i>syl(A,B,C)</i> throws a <i>std::runtime_error</i> exception</li>
7639 <li><i>svd(X,A,B,C)</i> returns a bool set to <i>false</i></li>
7640 </ul>
7641 </li>
7642 <br>
7643 <li>
7644 Examples:
7645 <ul>
7646 <pre>
7647 mat A = randu&lt;mat&gt;(5,5);
7648 mat B = randu&lt;mat&gt;(5,5);
7649 mat C = randu&lt;mat&gt;(5,5);
7650
7651 mat X1 = syl(A, B, C);
7652
7653 mat X2;
7654 syl(X2, A, B, C);
7655 </pre>
7656 </ul>
7657 </li>
7658 <br>
7659 <li>
7660 See also:
7661 <ul>
7662 <li><a href="#solve">solve()</a></li>
7663 <li><a href="http://en.wikipedia.org/wiki/Sylvester_equation">Sylvester equation in Wikipedia</a></li>
7664 </ul>
7665 </li>
7666 <br>
7667 </ul>
7668 <hr class="greyline">
7669
7670
7671 <hr class="greyline">
7672 <br>
7673 <br>
7674 <font size=+1><b>Miscellaneous</b></font>
7675 <br>
7676 <br>
7677 <hr class="greyline">
7678 <br>
7679
7680 <a name="is_finite_standalone"></a>
7681 <b>is_finite(X)</b>
7682 <ul>
7683 <li>
7684 Returns <i>true</i> if all elements in <i>X</i> are finite
7685 </li>
7686 <br>
7687 <li>
7688 Returns <i>false</i> if at least one element in <i>X</i> is non-finite (&plusmn;infinity or NaN)
7689 </li>
7690 <br>
7691 <li>
7692 <i>X</i> can be a scalar (eg. <i>double</i>), vector, matrix or cube
7693 </li>
7694 <br>
7695 <li>
7696 Examples:
7697 <ul>
7698 <pre>
7699 mat A = randu&lt;mat&gt;(5,5);
7700 mat B = randu&lt;mat&gt;(5,5);
7701
7702 B(1,1) = math::nan();
7703
7704 cout &lt;&lt; is_finite(A) &lt;&lt; endl;
7705 cout &lt;&lt; is_finite(B) &lt;&lt; endl;
7706
7707 cout &lt;&lt; is_finite( 0.123456789 ) &lt;&lt; endl;
7708 cout &lt;&lt; is_finite( math::nan() ) &lt;&lt; endl;
7709 cout &lt;&lt; is_finite( math::inf() ) &lt;&lt; endl;
7710 </pre>
7711 </ul>
7712 </li>
7713 <br>
7714 <li>
7715 See also:
7716 <ul>
7717 <li><a href="#math_constants">math::nan()</a></li>
7718 <li><a href="#math_constants">math::inf()</a></li>
7719 <li><a href="#is_finite">.is_finite()</a> (member function of <i>Mat</i> and <i>Cube</i>)</li>
7720 </ul>
7721 </li>
7722 <br>
7723 </ul>
7724 <hr class="greyline"><br>
7725
7726 <a name="logging"></a>
7727 <b>logging of warnings and errors</b>
7728 <br>
7729 <br>
7730 <b>set_stream_err1(user_stream)</b><br>
7731 <b>set_stream_err2(user_stream)</b><br>
7732 <br>
7733 <b>std::ostream&amp; x = get_stream_err1()</b>
7734 <br>
7735 <b>std::ostream&amp; x = get_stream_err2()</b>
7736 <br>
7737 <ul>
7738 <li>
7739 By default, Armadillo prints warnings and messages associated with <i>std::logic_error</i> and <i>std::runtime_error</i> exceptions to the <i>std::cout</i> stream
7740 </li>
7741 <br>
7742 <li><b>set_stream_err1()</b>: change the stream for messages associated with <i>std::logic_error</i> exceptions (eg. out of bounds accesses)</li>
7743 <br>
7744 <li><b>set_stream_err2()</b>: change the stream for warnings and messages associated with <i>std::runtime_error</i> exceptions (eg. failed decompositions)</li>
7745 <br>
7746 <li><b>get_stream_err1()</b>: get a reference to the stream for messages associated with <i>std::logic_error</i> exceptions</li>
7747 <br>
7748 <li><b>get_stream_err2()</b>: get a reference to the stream for warnings and messages associated with <i>std::runtime_error</i> exceptions</li>
7749 <br>
7750 <li>
7751 Examples:
7752 <ul>
7753 <pre>
7754 // print "hello" to the current err1 stream
7755 get_stream_err1() &lt;&lt; "hello" &lt;&lt; endl;
7756
7757 // change the err2 stream to be a file
7758 ofstream f("my_log.txt");
7759 set_stream_err2(f);
7760
7761 // trying to invert a singular matrix
7762 // will print a message to the err2 stream
7763 // and throw an exception
7764 mat X = zeros&lt;mat&gt;(5,5);
7765 mat Y = inv(X);
7766
7767 // disable messages being printed to the err2 stream
7768 std::ostream nullstream(0);
7769 set_stream_err2(nullstream);
7770 </pre>
7771 </ul>
7772 </li>
7773 <br>
7774 <li>
7775 <b>Caveat</b>: set_stream_err1() and set_stream_err2() will not change the stream used by .print()
7776 </li>
7777 <br>
7778 <li>
7779 See also:
7780 <ul>
7781 <li><a href="#print">.print()</a></li>
7782 <li><a href="http://cplusplus.com/reference/iostream/cout/">std::cout</a></li>
7783 <li><a href="http://cplusplus.com/reference/iostream/ostream/">std::ostream</a></li>
7784 <li><a href="http://cplusplus.com/reference/std/stdexcept/logic_error/">std::logic_error</a></li>
7785 <li><a href="http://cplusplus.com/reference/std/stdexcept/runtime_error/">std::runtime_error</a></li>
7786 <li><a href="http://cplusplus.com/doc/tutorial/exceptions/">tutorial on exceptions</a></li>
7787 </ul>
7788 </li>
7789 <br>
7790 </ul>
7791 <hr class="greyline">
7792
7793
7794
7795 <a name="math_constants"></a>
7796 <b>math constants (pi, e, euler, gratio, sqrt2, eps, log_min, log_max, nan, inf)</b>
7797 <br>
7798 <ul>
7799 <li>
7800 Collection of constants, with their precision and/or value dependant on the numerical type and/or machine used.
7801 </li>
7802 <br>
7803 <li>
7804 The constants are stored as static functions in the <i>Math&lt;type&gt;</i> class,
7805 where <i>type</i> is either <i>float</i> or <i>double</i>.
7806 </li>
7807 <br>
7808 <li>
7809 For convenience, <i>Math&lt;float&gt;</i> has been typedefed as <i>fmath</i>,
7810 while <i>Math&lt;double&gt;</i> has been typedefed as <i>math</i>.
7811 </li>
7812 <br>
7813 <li>
7814 Meaning of the constants:
7815 <ul>
7816 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
7817 <tbody>
7818 <tr>
7819 <td style="vertical-align: top;">
7820 math::pi()
7821 </td>
7822 <td style="vertical-align: top;">
7823 &nbsp;
7824 </td>
7825 <td style="vertical-align: top;">
7826 &pi;, the ratio of any circle's circumference to its diameter
7827 </td>
7828 </tr>
7829 <tr>
7830 <td style="vertical-align: top;">
7831 math::e()
7832 </td>
7833 <td style="vertical-align: top;">
7834 &nbsp;
7835 </td>
7836 <td style="vertical-align: top;">
7837 base of the natural logarithm
7838 </td>
7839 </tr>
7840 <tr>
7841 <td style="vertical-align: top;">
7842 math::euler()
7843 </td>
7844 <td style="vertical-align: top;">
7845 &nbsp;
7846 </td>
7847 <td style="vertical-align: top;">
7848 Euler's constant, aka Euler-Mascheroni constant
7849 </td>
7850 </tr>
7851 <tr>
7852 <td style="vertical-align: top;">
7853 math::gratio()
7854 </td>
7855 <td style="vertical-align: top;">
7856 &nbsp;
7857 </td>
7858 <td style="vertical-align: top;">
7859 golden ratio
7860 </td>
7861 </tr>
7862 <tr>
7863 <td style="vertical-align: top;">
7864 math::sqrt2()
7865 </td>
7866 <td style="vertical-align: top;">
7867 &nbsp;
7868 </td>
7869 <td style="vertical-align: top;">
7870 square root of 2
7871 </td>
7872 </tr>
7873 <tr>
7874 <td style="vertical-align: top;">
7875 math::eps()
7876 </td>
7877 <td style="vertical-align: top;">
7878 &nbsp;
7879 </td>
7880 <td style="vertical-align: top;">
7881 the difference between 1 and the least value greater than 1 that is representable
7882 </td>
7883 </tr>
7884 <tr>
7885 <td style="vertical-align: top;">
7886 math::log_min()
7887 </td>
7888 <td style="vertical-align: top;">
7889 &nbsp;
7890 </td>
7891 <td style="vertical-align: top;">
7892 log of minimum non-zero value
7893 </td>
7894 </tr>
7895 <tr>
7896 <td style="vertical-align: top;">
7897 math::log_max()
7898 </td>
7899 <td style="vertical-align: top;">
7900 &nbsp;
7901 </td>
7902 <td style="vertical-align: top;">
7903 log of maximum value
7904 </td>
7905 </tr>
7906 <tr>
7907 <td style="vertical-align: top;">
7908 math::nan()
7909 </td>
7910 <td style="vertical-align: top;">
7911 &nbsp;
7912 </td>
7913 <td style="vertical-align: top;">
7914 &ldquo;not a number&rdquo; (NaN)
7915 </td>
7916 </tr>
7917 <tr>
7918 <td style="vertical-align: top;">
7919 math::inf()
7920 </td>
7921 <td style="vertical-align: top;">
7922 &nbsp;
7923 </td>
7924 <td style="vertical-align: top;">
7925 infinity
7926 </td>
7927 </tr>
7928 </tbody>
7929 </table>
7930 </ul>
7931 </li>
7932 <br>
7933 <li>
7934 <b>Caveat:</b>
7935 nan() is not equal to anything, even itself;
7936 if you wish to check whether a given number <i>x</i> is finite,
7937 use <a href="#is_finite_standalone">is_finite</a>(<i>x</i>).
7938 </li>
7939 <br>
7940 <li>
7941 Examples:
7942 <ul>
7943 <pre>
7944 cout &lt;&lt; "2.0 * pi = " &lt;&lt; 2.0 * math::pi() &lt;&lt; endl;
7945
7946 cout &lt;&lt; "log_max for floats = ";
7947 cout &lt;&lt; fmath::log_max() &lt;&lt; endl;
7948
7949 cout &lt;&lt; "log_max for doubles = ";
7950 cout &lt;&lt; math::log_max() &lt;&lt; endl;
7951 </pre>
7952 </ul>
7953 </li>
7954 <li>
7955 See also:
7956 <ul>
7957 <li><a href="#phys_constants">physical constants</a></li>
7958 <li><a href="#is_finite_standalone">is_finite()</a></li>
7959 <li><a href="http://en.wikipedia.org/wiki/NaN">Wikipedia entry for NaN</a></li>
7960 <li><a href="http://cplusplus.com/reference/std/limits/numeric_limits/">std::numeric_limits</a></li>
7961 </ul>
7962 </li>
7963 </ul>
7964 <br>
7965 <hr class="greyline"><br>
7966
7967 <a name="phys_constants"></a>
7968 <b>physical constants (speed of light, etc)</b>
7969 <br>
7970 <ul>
7971 <li>
7972 Collection of fundamental physical constants,
7973 mainly taken from
7974 <a href="http://physics.nist.gov/cuu/Constants">NIST</a>
7975 and some from
7976 <a href="http://www.wolframalpha.com">WolframAlpha</a>
7977 on 2009-06-23.
7978 </li>
7979 <br>
7980 <li>
7981 Constants from NIST are in turn sourced from the <a href="http://physics.nist.gov/cuu/Constants/papers.html">2006 CODATA values</a>.
7982 </li>
7983 <br>
7984 <li>
7985 The constants are stored as static functions in the <i>Phy&lt;type&gt;</i> class,
7986 where <i>type</i> is either <i>float</i> or <i>double</i>.
7987 </li>
7988 <br>
7989 <li>
7990 For convenience, <i>Phy&lt;float&gt;</i> has been typedefed as <i>fphy</i>,
7991 while <i>Phy&lt;double&gt;</i> has been typedefed as <i>phy</i>.
7992 </li>
7993 <br>
7994 <li>
7995 Meaning of the constants:
7996 <ul>
7997 <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
7998 <tbody>
7999 <tr>
8000 <td style="vertical-align: top;">
8001 phy::m_u()
8002 </td>
8003 <td style="vertical-align: top;">
8004 &nbsp;
8005 </td>
8006 <td style="vertical-align: top;">
8007 atomic mass constant (in kg)
8008 </td>
8009 </tr>
8010 <tr>
8011 <td style="vertical-align: top;">
8012 phy::N_A()
8013 </td>
8014 <td style="vertical-align: top;">
8015 &nbsp;
8016 </td>
8017 <td style="vertical-align: top;">
8018 Avogadro constant
8019 </td>
8020 </tr>
8021 <tr>
8022 <td style="vertical-align: top;">
8023 phy::k()
8024 </td>
8025 <td style="vertical-align: top;">
8026 &nbsp;
8027 </td>
8028 <td style="vertical-align: top;">
8029 Boltzmann constant (in joules per kelvin)
8030 </td>
8031 </tr>
8032 <tr>
8033 <td style="vertical-align: top;">
8034 phy::k_evk()
8035 </td>
8036 <td style="vertical-align: top;">
8037 &nbsp;
8038 </td>
8039 <td style="vertical-align: top;">
8040 Boltzmann constant (in eV/K)
8041 </td>
8042 </tr>
8043 <tr>
8044 <td style="vertical-align: top;">
8045 phy::a_0()
8046 </td>
8047 <td style="vertical-align: top;">
8048 &nbsp;
8049 </td>
8050 <td style="vertical-align: top;">
8051 Bohr radius (in meters)
8052 </td>
8053 </tr>
8054 <tr>
8055 <td style="vertical-align: top;">
8056 phy::mu_B()
8057 </td>
8058 <td style="vertical-align: top;">
8059 &nbsp;
8060 </td>
8061 <td style="vertical-align: top;">
8062 Bohr magneton
8063 </td>
8064 </tr>
8065 <tr>
8066 <td style="vertical-align: top;">
8067 phy::Z_0()
8068 </td>
8069 <td style="vertical-align: top;">
8070 &nbsp;
8071 </td>
8072 <td style="vertical-align: top;">
8073 characteristic impedance of vacuum (in ohms)
8074 </td>
8075 </tr>
8076 <tr>
8077 <td style="vertical-align: top;">
8078 phy::G_0()
8079 </td>
8080 <td style="vertical-align: top;">
8081 &nbsp;
8082 </td>
8083 <td style="vertical-align: top;">
8084 conductance quantum (in siemens)
8085 </td>
8086 </tr>
8087 <tr>
8088 <td style="vertical-align: top;">
8089 phy::k_e()
8090 </td>
8091 <td style="vertical-align: top;">
8092 &nbsp;
8093 </td>
8094 <td style="vertical-align: top;">
8095 Coulomb's constant (in meters per farad)
8096 </td>
8097 </tr>
8098 <tr>
8099 <td style="vertical-align: top;">
8100 phy::eps_0()
8101 </td>
8102 <td style="vertical-align: top;">
8103 &nbsp;
8104 </td>
8105 <td style="vertical-align: top;">
8106 electric constant (in farads per meter)
8107 </td>
8108 </tr>
8109 <tr>
8110 <td style="vertical-align: top;">
8111 phy::m_e()
8112 </td>
8113 <td style="vertical-align: top;">
8114 &nbsp;
8115 </td>
8116 <td style="vertical-align: top;">
8117 electron mass (in kg)
8118 </td>
8119 </tr>
8120 <tr>
8121 <td style="vertical-align: top;">
8122 phy::eV()
8123 </td>
8124 <td style="vertical-align: top;">
8125 &nbsp;
8126 </td>
8127 <td style="vertical-align: top;">
8128 electron volt (in joules)
8129 </td>
8130 </tr>
8131 <tr>
8132 <td style="vertical-align: top;">
8133 phy::e()
8134 </td>
8135 <td style="vertical-align: top;">
8136 &nbsp;
8137 </td>
8138 <td style="vertical-align: top;">
8139 elementary charge (in coulombs)
8140 </td>
8141 </tr>
8142 <tr>
8143 <td style="vertical-align: top;">
8144 phy::F()
8145 </td>
8146 <td style="vertical-align: top;">
8147 &nbsp;
8148 </td>
8149 <td style="vertical-align: top;">
8150 Faraday constant (in coulombs)
8151 </td>
8152 </tr>
8153 <tr>
8154 <td style="vertical-align: top;">
8155 phy::alpha()
8156 </td>
8157 <td style="vertical-align: top;">
8158 &nbsp;
8159 </td>
8160 <td style="vertical-align: top;">
8161 fine-structure constant
8162 </td>
8163 </tr>
8164 <tr>
8165 <td style="vertical-align: top;">
8166 phy::alpha_inv()
8167 </td>
8168 <td style="vertical-align: top;">
8169 &nbsp;
8170 </td>
8171 <td style="vertical-align: top;">
8172 inverse fine-structure constant
8173 </td>
8174 </tr>
8175 <tr>
8176 <td style="vertical-align: top;">
8177 phy::K_J()
8178 </td>
8179 <td style="vertical-align: top;">
8180 &nbsp;
8181 </td>
8182 <td style="vertical-align: top;">
8183 Josephson constant
8184 </td>
8185 </tr>
8186 <tr>
8187 <td style="vertical-align: top;">
8188 phy::mu_0()
8189 </td>
8190 <td style="vertical-align: top;">
8191 &nbsp;
8192 </td>
8193 <td style="vertical-align: top;">
8194 magnetic constant (in henries per meter)
8195 </td>
8196 </tr>
8197 <tr>
8198 <td style="vertical-align: top;">
8199 phy::phi_0()
8200 </td>
8201 <td style="vertical-align: top;">
8202 &nbsp;
8203 </td>
8204 <td style="vertical-align: top;">
8205 magnetic flux quantum (in webers)
8206 </td>
8207 </tr>
8208 <tr>
8209 <td style="vertical-align: top;">
8210 phy::R()
8211 </td>
8212 <td style="vertical-align: top;">
8213 &nbsp;
8214 </td>
8215 <td style="vertical-align: top;">
8216 molar gas constant (in joules per mole kelvin)
8217 </td>
8218 </tr>
8219 <tr>
8220 <td style="vertical-align: top;">
8221 phy::G()
8222 </td>
8223 <td style="vertical-align: top;">
8224 &nbsp;
8225 </td>
8226 <td style="vertical-align: top;">
8227 Newtonian constant of gravitation (in newton square meters per kilogram squared)
8228 </td>
8229 </tr>
8230 <tr>
8231 <td style="vertical-align: top;">
8232 phy::h()
8233 </td>
8234 <td style="vertical-align: top;">
8235 &nbsp;
8236 </td>
8237 <td style="vertical-align: top;">
8238 Planck constant (in joule seconds)
8239 </td>
8240 </tr>
8241 <tr>
8242 <td style="vertical-align: top;">
8243 phy::h_bar()
8244 </td>
8245 <td style="vertical-align: top;">
8246 &nbsp;
8247 </td>
8248 <td style="vertical-align: top;">
8249 Planck constant over 2 pi, aka reduced Planck constant (in joule seconds)
8250 </td>
8251 </tr>
8252 <tr>
8253 <td style="vertical-align: top;">
8254 phy::m_p()
8255 </td>
8256 <td style="vertical-align: top;">
8257 &nbsp;
8258 </td>
8259 <td style="vertical-align: top;">
8260 proton mass (in kg)
8261 </td>
8262 </tr>
8263 <tr>
8264 <td style="vertical-align: top;">
8265 phy::R_inf()
8266 </td>
8267 <td style="vertical-align: top;">
8268 &nbsp;
8269 </td>
8270 <td style="vertical-align: top;">
8271 Rydberg constant (in reciprocal meters)
8272 </td>
8273 </tr>
8274 <tr>
8275 <td style="vertical-align: top;">
8276 phy::c_0()
8277 </td>
8278 <td style="vertical-align: top;">
8279 &nbsp;
8280 </td>
8281 <td style="vertical-align: top;">
8282 speed of light in vacuum (in meters per second)
8283 </td>
8284 </tr>
8285 <tr>
8286 <td style="vertical-align: top;">
8287 phy::sigma()
8288 </td>
8289 <td style="vertical-align: top;">
8290 &nbsp;
8291 </td>
8292 <td style="vertical-align: top;">
8293 Stefan-Boltzmann constant
8294 </td>
8295 </tr>
8296 <tr>
8297 <td style="vertical-align: top;">
8298 phy::R_k()
8299 </td>
8300 <td style="vertical-align: top;">
8301 &nbsp;
8302 </td>
8303 <td style="vertical-align: top;">
8304 von Klitzing constant (in ohms)
8305 </td>
8306 </tr>
8307 <tr>
8308 <td style="vertical-align: top;">
8309 phy::b()
8310 </td>
8311 <td style="vertical-align: top;">
8312 &nbsp;
8313 </td>
8314 <td style="vertical-align: top;">
8315 Wien wavelength displacement law constant
8316 </td>
8317 </tr>
8318 </tbody>
8319 </table>
8320 </ul>
8321 </li>
8322 <br>
8323 <li>
8324 Examples:
8325 <ul>
8326 <pre>
8327 cout &lt;&lt; "speed of light = " &lt;&lt; phy::c_0() &lt;&lt; endl;
8328 </pre>
8329 </ul>
8330 </li>
8331 <br>
8332 <li>
8333 See also:
8334 <ul>
8335 <li><a href="http://en.wikipedia.org/wiki/Physical_constant">physical constant</a> entry in Wikipedia</li>
8336 <li><a href="#math_constants">math constants</a></li>
8337 </ul>
8338 </li>
8339 </ul>
8340 <br>
8341 <hr class="greyline"><br>
8342
8343 <a name="log_add"></a>
8344 <b>log_add(log_a, log_b)</b>
8345 <ul>
8346 <li>
8347 Safe replacement for log(exp(log_a) + exp(log_b))
8348 </li>
8349 <br>
8350 <li>
8351 Usage:
8352 <ul>
8353 <li>
8354 <i>scalar_type</i> log_c = log_add(log_a, log_b)
8355 </li>
8356 <li>
8357 <i>scalar_type</i> is either <i>float</i> or <i>double</i>
8358 </li>
8359 <li>
8360 log_a, log_b and log_c must have the same type
8361 </li>
8362 </ul>
8363 </li>
8364 </ul>
8365 <br>
8366 <hr class="greyline"><br>
8367
8368 <a name="uword"></a>
8369 <b>uword</b>, <b>sword</b>
8370 <ul>
8371 <li>
8372 <i>uword</i> is a typedef for an unsigned integer with a minimum width of 32 bits; if <i>ARMA_64BIT_WORD</i> is enabled, the minimum width is 64 bits
8373 </li>
8374 <br>
8375 <li>
8376 <i>sword</i> is a typedef for a signed integer with a minimum width of 32 bits; if <i>ARMA_64BIT_WORD</i> is enabled, the minimum width is 64 bits
8377 </li>
8378 <br>
8379 <li>
8380 <i>ARMA_64BIT_WORD</i> can be enabled via editing <i>include/armadillo_bits/config.hpp</i>
8381 </li>
8382 <br>
8383 <li>See also:
8384 <ul>
8385 <li><a href="http://cplusplus.com/doc/tutorial/variables/">C++ variable types</a></li>
8386 <li><a href="http://www.cplusplus.com/doc/tutorial/other_data_types/">explanation of <i>typedef</i></a></li>
8387 <li><a href="#Mat">imat &amp; umat</a> matrix types
8388 <li><a href="#Col">ivec &amp; uvec</a> vector types
8389 </ul>
8390 </li>
8391 <br>
8392 </ul>
8393 <hr class="greyline"><br>
8394
8395 <a name="cx_float_double"></a>
8396 <b>cx_float</b>, <b>cx_double</b>
8397 <ul>
8398 <li>
8399 cx_float is a typedef for <i>std::complex&lt;float&gt;</i>
8400 </li>
8401 <br>
8402 <li>
8403 cx_double is a typedef for <i>std::complex&lt;double&gt;</i>
8404 </li>
8405 <br>
8406 <li>See also:
8407 <ul>
8408 <li><a href="http://cplusplus.com/reference/std/complex/">complex numbers in the standard C++ library</a></li>
8409 <li><a href="http://www.cplusplus.com/doc/tutorial/other_data_types/">explanation of <i>typedef</i></a></li>
8410 <li><a href="#Mat">cx_mat</a> matrix type
8411 <li><a href="#Col">cx_vec</a> vector type
8412 </ul>
8413 </li>
8414 <br>
8415 </ul>
8416
8417 <a name="syntax"></a>
8418 <hr class="greyline">
8419 <br>
8420 <b>
8421 Examples of Matlab/Octave syntax and conceptually corresponding Armadillo syntax
8422 </b>
8423 <br>
8424 <br>
8425 <ul>
8426 <table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
8427 <tbody>
8428 <tr>
8429 <td style="vertical-align: top;">
8430 <b>Matlab/Octave</b>
8431 </td>
8432 <td style="vertical-align: top;">
8433 &nbsp;
8434 </td>
8435 <td style="vertical-align: top;">
8436 <b>Armadillo</b>
8437 </td>
8438 <td style="vertical-align: top;">
8439 &nbsp;
8440 </td>
8441 <td style="vertical-align: top;">
8442 <b>Notes</b>
8443 </td>
8444 </tr>
8445 <tr>
8446 <td style="vertical-align: top;">
8447 &nbsp;
8448 </td>
8449 <td style="vertical-align: top;">
8450 &nbsp;
8451 </td>
8452 <td style="vertical-align: top;">
8453 &nbsp;
8454 </td>
8455 <td style="vertical-align: top;">
8456 &nbsp;
8457 </td>
8458 <td style="vertical-align: top;">
8459 &nbsp;
8460 </td>
8461 </tr>
8462 <tr>
8463 <td style="vertical-align: top;">
8464 A(1, 1)
8465 </td>
8466 <td style="vertical-align: top;">
8467 &nbsp;
8468 </td>
8469 <td style="vertical-align: top;">
8470 A(0, 0)
8471 </td>
8472 <td style="vertical-align: top;">
8473 &nbsp;
8474 </td>
8475 <td style="vertical-align: top;">
8476 indexing in Armadillo starts at 0
8477 </td>
8478 </tr>
8479 <tr>
8480 <td style="vertical-align: top;">
8481 A(k, k)
8482 </td>
8483 <td style="vertical-align: top;">
8484 &nbsp;
8485 </td>
8486 <td style="vertical-align: top;">
8487 A(k-1, k-1)
8488 </td>
8489 <td style="vertical-align: top;">
8490 &nbsp;
8491 </td>
8492 <td style="vertical-align: top;">
8493 &nbsp;
8494 </td>
8495 </tr>
8496 <tr>
8497 <td style="vertical-align: top;">
8498 &nbsp;
8499 </td>
8500 <td style="vertical-align: top;">
8501 &nbsp;
8502 </td>
8503 <td style="vertical-align: top;">
8504 &nbsp;
8505 </td>
8506 <td style="vertical-align: top;">
8507 &nbsp;
8508 </td>
8509 <td style="vertical-align: top;">
8510 &nbsp;
8511 </td>
8512 </tr>
8513 <tr>
8514 <td style="vertical-align: top;">
8515 size(A,1)
8516 </td>
8517 <td style="vertical-align: top;">
8518 &nbsp;
8519 </td>
8520 <td style="vertical-align: top;">
8521 A<a href="#attributes">.n_rows</a>
8522 </td>
8523 <td style="vertical-align: top;">
8524 &nbsp;
8525 </td>
8526 <td style="vertical-align: top;">
8527 read only
8528 </td>
8529 </tr>
8530 <tr>
8531 <td style="vertical-align: top;">
8532 size(A,2)
8533 </td>
8534 <td style="vertical-align: top;">
8535 &nbsp;
8536 </td>
8537 <td style="vertical-align: top;">
8538 A<a href="#attributes">.n_cols</a>
8539 </td>
8540 <td style="vertical-align: top;">
8541 &nbsp;
8542 </td>
8543 <td style="vertical-align: top;">
8544 &nbsp;
8545 </td>
8546 </tr>
8547 <tr>
8548 <td style="vertical-align: top;">
8549 size(Q,3)
8550 </td>
8551 <td style="vertical-align: top;">
8552 &nbsp;
8553 </td>
8554 <td style="vertical-align: top;">
8555 Q<a href="#attributes">.n_slices</a>
8556 </td>
8557 <td style="vertical-align: top;">
8558 &nbsp;
8559 </td>
8560 <td style="vertical-align: top;">
8561 Q is a <a href="#Cube">cube</a> (3D array)
8562 </td>
8563 </tr>
8564 <tr>
8565 <td style="vertical-align: top;">
8566 numel(A)
8567 </td>
8568 <td style="vertical-align: top;">
8569 &nbsp;
8570 </td>
8571 <td style="vertical-align: top;">
8572 A<a href="#attributes">.n_elem</a>
8573 </td>
8574 <td style="vertical-align: top;">
8575 &nbsp;
8576 </td>
8577 <td style="vertical-align: top;">
8578 &nbsp;
8579 </td>
8580 </tr>
8581 <tr>
8582 <td style="vertical-align: top;">
8583 &nbsp;
8584 </td>
8585 <td style="vertical-align: top;">
8586 &nbsp;
8587 </td>
8588 <td style="vertical-align: top;">
8589 &nbsp;
8590 </td>
8591 <td style="vertical-align: top;">
8592 &nbsp;
8593 </td>
8594 <td style="vertical-align: top;">
8595 &nbsp;
8596 </td>
8597 </tr>
8598 <tr>
8599 <td style="vertical-align: top;">
8600 A(:, k)
8601 </td>
8602 <td style="vertical-align: top;">
8603 &nbsp;
8604 </td>
8605 <td style="vertical-align: top;">
8606 A<a href="#submat">.col</a>(k)
8607 </td>
8608 <td style="vertical-align: top;">
8609 &nbsp;
8610 </td>
8611 <td style="vertical-align: top;">
8612 this is a conceptual example only;
8613 exact conversion from Matlab/Octave to Armadillo syntax
8614 will require taking into account that indexing starts at 0
8615 </td>
8616 </tr>
8617 <tr>
8618 <td style="vertical-align: top;">
8619 A(k, :)
8620 </td>
8621 <td style="vertical-align: top;">
8622 &nbsp;
8623 </td>
8624 <td style="vertical-align: top;">
8625 A<a href="#submat">.row</a>(k)
8626 </td>
8627 <td style="vertical-align: top;">
8628 &nbsp;
8629 </td>
8630 <td style="vertical-align: top;">
8631 &nbsp;
8632 </td>
8633 </tr>
8634 <tr>
8635 <td style="vertical-align: top;">
8636 A(:, p:q)
8637 </td>
8638 <td style="vertical-align: top;">
8639 &nbsp;
8640 </td>
8641 <td style="vertical-align: top;">
8642 A<a href="#submat">.cols</a>(p, q)
8643 </td>
8644 <td style="vertical-align: top;">
8645 &nbsp;
8646 </td>
8647 <td style="vertical-align: top;">
8648 &nbsp;
8649 </td>
8650 </tr>
8651 <tr>
8652 <td style="vertical-align: top;">
8653 A(p:q, :)
8654 </td>
8655 <td style="vertical-align: top;">
8656 &nbsp;
8657 </td>
8658 <td style="vertical-align: top;">
8659 A<a href="#submat">.rows</a>(p, q)
8660 </td>
8661 <td style="vertical-align: top;">
8662 &nbsp;
8663 </td>
8664 <td style="vertical-align: top;">
8665 &nbsp;
8666 </td>
8667 </tr>
8668 <tr>
8669 <td style="vertical-align: top;">
8670 &nbsp;
8671 </td>
8672 <td style="vertical-align: top;">
8673 &nbsp;
8674 </td>
8675 <td style="vertical-align: top;">
8676 &nbsp;
8677 </td>
8678 <td style="vertical-align: top;">
8679 &nbsp;
8680 </td>
8681 <td style="vertical-align: top;">
8682 &nbsp;
8683 </td>
8684 </tr>
8685 <tr>
8686 <td style="vertical-align: top;">
8687 A(p:q, r:s)
8688 </td>
8689 <td style="vertical-align: top;">
8690 &nbsp;
8691 </td>
8692 <td style="vertical-align: top;">
8693 <font size=-1>
8694 A<a href="#submat">.submat</a>(p, r, q, s)
8695 </font>
8696 </td>
8697 <td style="vertical-align: top;">
8698 &nbsp;
8699 </td>
8700 <td style="vertical-align: top;">
8701 <font size=-1>
8702 A.submat(first_row, first_col, last_row, last_col)
8703 </font>
8704 </td>
8705 </tr>
8706 <tr>
8707 <td style="vertical-align: top;">
8708 &nbsp;
8709 </td>
8710 <td style="vertical-align: top;">
8711 &nbsp;
8712 </td>
8713 <td style="vertical-align: top;">
8714 <font size=-1>
8715 or
8716 </font>
8717 </td>
8718 <td style="vertical-align: top;">
8719 &nbsp;
8720 </td>
8721 <td style="vertical-align: top;">
8722 &nbsp;
8723 </td>
8724 </tr>
8725 <tr>
8726 <td style="vertical-align: top;">
8727 &nbsp;
8728 </td>
8729 <td style="vertical-align: top;">
8730 &nbsp;
8731 </td>
8732 <td style="vertical-align: top;">
8733 <font size=-1>
8734 A(&nbsp;<a href="#submat">span</a>(p,q),&nbsp;<a href="#submat">span</a>(r,s)&nbsp;)
8735 </font>
8736 </td>
8737 <td style="vertical-align: top;">
8738 &nbsp;
8739 </td>
8740 <td style="vertical-align: top;">
8741 <font size=-1>
8742 A(&nbsp;span(first_row,&nbsp;last_row), span(first_col,&nbsp;last_col)&nbsp;)
8743 </font>
8744 </td>
8745 </tr>
8746 <tr>
8747 <td style="vertical-align: top;">
8748 &nbsp;
8749 </td>
8750 <td style="vertical-align: top;">
8751 &nbsp;
8752 </td>
8753 <td style="vertical-align: top;">
8754 &nbsp;
8755 </td>
8756 <td style="vertical-align: top;">
8757 &nbsp;
8758 </td>
8759 <td style="vertical-align: top;">
8760 &nbsp;
8761 </td>
8762 </tr>
8763 <tr>
8764 <td style="vertical-align: top;">
8765 Q(:, :, k)
8766 </td>
8767 <td style="vertical-align: top;">
8768 &nbsp;
8769 </td>
8770 <td style="vertical-align: top;">
8771 Q<a href="#subcube">.slice</a>(k)
8772 </td>
8773 <td style="vertical-align: top;">
8774 &nbsp;
8775 </td>
8776 <td style="vertical-align: top;">
8777 Q is a <a href="#Cube">cube</a> (3D array)
8778 </td>
8779 </tr>
8780 <tr>
8781 <td style="vertical-align: top;">
8782 Q(:, :, t:u)
8783 </td>
8784 <td style="vertical-align: top;">
8785 &nbsp;
8786 </td>
8787 <td style="vertical-align: top;">
8788 Q<a href="#subcube">.slices</a>(t, u)
8789 </td>
8790 <td style="vertical-align: top;">
8791 &nbsp;
8792 </td>
8793 <td style="vertical-align: top;">
8794 &nbsp;
8795 </td>
8796 </tr>
8797 <tr>
8798 <td style="vertical-align: top;">
8799 &nbsp;
8800 </td>
8801 <td style="vertical-align: top;">
8802 &nbsp;
8803 </td>
8804 <td style="vertical-align: top;">
8805 &nbsp;
8806 </td>
8807 <td style="vertical-align: top;">
8808 &nbsp;
8809 </td>
8810 <td style="vertical-align: top;">
8811 &nbsp;
8812 </td>
8813 </tr>
8814 <tr>
8815 <td style="vertical-align: top;">
8816 Q(p:q, r:s, t:u)
8817 </td>
8818 <td style="vertical-align: top;">
8819 &nbsp;
8820 </td>
8821 <td style="vertical-align: top;">
8822 <font size=-1>
8823 Q<a href="#subcube">.subcube</a>(p,&nbsp;r,&nbsp;t,&nbsp;q,&nbsp;s,&nbsp;u)
8824 </font>
8825 </td>
8826 <td style="vertical-align: top;">
8827 &nbsp;
8828 </td>
8829 <td style="vertical-align: top;">
8830 <font size=-1>
8831 .subcube(first_row, first_col, first_slice, last_row, last_col, last_slice)
8832 </font>
8833 </td>
8834 </tr>
8835 <tr>
8836 <td style="vertical-align: top;">
8837 &nbsp;
8838 </td>
8839 <td style="vertical-align: top;">
8840 &nbsp;
8841 </td>
8842 <td style="vertical-align: top;">
8843 <font size=-1>
8844 or
8845 </font>
8846 </td>
8847 <td style="vertical-align: top;">
8848 &nbsp;
8849 </td>
8850 <td style="vertical-align: top;">
8851 &nbsp;
8852 </td>
8853 </tr>
8854 <tr>
8855 <td style="vertical-align: top;">
8856 &nbsp;
8857 </td>
8858 <td style="vertical-align: top;">
8859 &nbsp;
8860 </td>
8861 <td style="vertical-align: top;">
8862 <font size=-1>
8863 Q(&nbsp;<a href="#subcube">span</a>(p,q),&nbsp;<a href="#subcube">span</a>(r,s),&nbsp;<a href="#subcube">span</a>(t,u)&nbsp;)
8864 </font>
8865 </td>
8866 <td style="vertical-align: top;">
8867 &nbsp;
8868 </td>
8869 <td style="vertical-align: top;">
8870 &nbsp;
8871 </td>
8872 </tr>
8873 <tr>
8874 <td style="vertical-align: top;">
8875 &nbsp;
8876 </td>
8877 <td style="vertical-align: top;">
8878 &nbsp;
8879 </td>
8880 <td style="vertical-align: top;">
8881 &nbsp;
8882 </td>
8883 <td style="vertical-align: top;">
8884 &nbsp;
8885 </td>
8886 <td style="vertical-align: top;">
8887 &nbsp;
8888 </td>
8889 </tr>
8890 <tr>
8891 <td style="vertical-align: top;">
8892 A'
8893 </td>
8894 <td style="vertical-align: top;">
8895 &nbsp;
8896 </td>
8897 <td style="vertical-align: top;">
8898 A<a href="#t_st_members">.t()</a> or <a href="#trans">trans</a>(A)
8899 </td>
8900 <td style="vertical-align: top;">
8901 &nbsp;
8902 </td>
8903 <td style="vertical-align: top;">
8904 matrix transpose / Hermitian transpose
8905 <br>
8906 (for complex matrices, the conjugate of each element is taken)
8907 </td>
8908 </tr>
8909 <tr>
8910 <td style="vertical-align: top;">
8911 A.'
8912 </td>
8913 <td style="vertical-align: top;">
8914 &nbsp;
8915 </td>
8916 <td style="vertical-align: top;">
8917 A<a href="#t_st_members">.st()</a> or <a href="#strans">strans</a>(A)
8918 </td>
8919 <td style="vertical-align: top;">
8920 &nbsp;
8921 </td>
8922 <td style="vertical-align: top;">
8923 simple matrix transpose
8924 <br>
8925 (for complex matrices, the conjugate of each element is not taken)
8926 </td>
8927 </tr>
8928 <tr>
8929 <td style="vertical-align: top;">
8930 &nbsp;
8931 </td>
8932 <td style="vertical-align: top;">
8933 &nbsp;
8934 </td>
8935 <td style="vertical-align: top;">
8936 &nbsp;
8937 </td>
8938 <td style="vertical-align: top;">
8939 &nbsp;
8940 </td>
8941 <td style="vertical-align: top;">
8942 &nbsp;
8943 </td>
8944 </tr>
8945 <tr>
8946 <td style="vertical-align: top;">
8947 A = zeros(size(A))
8948 </td>
8949 <td style="vertical-align: top;">
8950 &nbsp;
8951 </td>
8952 <td style="vertical-align: top;">
8953 A<a href="#zeros_member">.zeros()</a>
8954 </td>
8955 <td style="vertical-align: top;">
8956 &nbsp;
8957 </td>
8958 <td style="vertical-align: top;">
8959 &nbsp;
8960 </td>
8961 </tr>
8962 <tr>
8963 <td style="vertical-align: top;">
8964 A = ones(size(A))
8965 </td>
8966 <td style="vertical-align: top;">
8967 &nbsp;
8968 </td>
8969 <td style="vertical-align: top;">
8970 A.<a href="#ones_member">ones()</a>
8971 </td>
8972 <td style="vertical-align: top;">
8973 &nbsp;
8974 </td>
8975 <td style="vertical-align: top;">
8976 &nbsp;
8977 </td>
8978 </tr>
8979 <tr>
8980 <td style="vertical-align: top;">
8981 A = zeros(k)
8982 </td>
8983 <td style="vertical-align: top;">
8984 &nbsp;
8985 </td>
8986 <td style="vertical-align: top;">
8987 A = <a href="#zeros_standalone">zeros</a>&lt;mat&gt;(k,k)
8988 </td>
8989 <td style="vertical-align: top;">
8990 &nbsp;
8991 </td>
8992 <td style="vertical-align: top;">
8993 &nbsp;
8994 </td>
8995 </tr>
8996 <tr>
8997 <td style="vertical-align: top;">
8998 A = ones(k)
8999 </td>
9000 <td style="vertical-align: top;">
9001 &nbsp;
9002 </td>
9003 <td style="vertical-align: top;">
9004 A = <a href="#ones_standalone">ones</a>&lt;mat&gt;(k,k)
9005 </td>
9006 <td style="vertical-align: top;">
9007 &nbsp;
9008 </td>
9009 <td style="vertical-align: top;">
9010 &nbsp;
9011 </td>
9012 </tr>
9013 <tr>
9014 <td style="vertical-align: top;">
9015 &nbsp;
9016 </td>
9017 <td style="vertical-align: top;">
9018 &nbsp;
9019 </td>
9020 <td style="vertical-align: top;">
9021 &nbsp;
9022 </td>
9023 <td style="vertical-align: top;">
9024 &nbsp;
9025 </td>
9026 <td style="vertical-align: top;">
9027 &nbsp;
9028 </td>
9029 </tr>
9030 <tr>
9031 <td style="vertical-align: top;">
9032 C = complex(A,B)
9033 </td>
9034 <td style="vertical-align: top;">
9035 &nbsp;
9036 </td>
9037 <td style="vertical-align: top;">
9038 cx_mat C = <a href="#Mat">cx_mat</a>(A,B)
9039 </td>
9040 <td style="vertical-align: top;">
9041 &nbsp;
9042 </td>
9043 <td style="vertical-align: top;">
9044 &nbsp;
9045 </td>
9046 </tr>
9047 <tr>
9048 <td style="vertical-align: top;">
9049 &nbsp;
9050 </td>
9051 <td style="vertical-align: top;">
9052 &nbsp;
9053 </td>
9054 <td style="vertical-align: top;">
9055 &nbsp;
9056 </td>
9057 <td style="vertical-align: top;">
9058 &nbsp;
9059 </td>
9060 <td style="vertical-align: top;">
9061 &nbsp;
9062 </td>
9063 </tr>
9064 <tr>
9065 <td style="vertical-align: top;">
9066 A .* B
9067 </td>
9068 <td style="vertical-align: top;">
9069 &nbsp;
9070 </td>
9071 <td style="vertical-align: top;">
9072 A % B
9073 </td>
9074 <td style="vertical-align: top;">
9075 &nbsp;
9076 </td>
9077 <td style="vertical-align: top;">
9078 <a href="#operators">element-wise multiplication</a>
9079 </td>
9080 </tr>
9081 <tr>
9082 <td style="vertical-align: top;">
9083 A ./ B
9084 </td>
9085 <td style="vertical-align: top;">
9086 &nbsp;
9087 </td>
9088 <td style="vertical-align: top;">
9089 A / B
9090 </td>
9091 <td style="vertical-align: top;">
9092 &nbsp;
9093 </td>
9094 <td style="vertical-align: top;">
9095 <a href="#operators">element-wise division</a>
9096 </td>
9097 </tr>
9098 <tr>
9099 <td style="vertical-align: top;">
9100 A \ B
9101 </td>
9102 <td style="vertical-align: top;">
9103 &nbsp;
9104 </td>
9105 <td style="vertical-align: top;">
9106 <a href="#solve">solve</a>(A,B)
9107 </td>
9108 <td style="vertical-align: top;">
9109 &nbsp;
9110 </td>
9111 <td style="vertical-align: top;">
9112 conceptually similar to <a href="#inv">inv</a>(A)*B, but more efficient
9113 </td>
9114 </tr>
9115 <tr>
9116 <td style="vertical-align: top;">
9117 A = A + 1;
9118 </td>
9119 <td style="vertical-align: top;">
9120 &nbsp;
9121 </td>
9122 <td style="vertical-align: top;">
9123 A++
9124 </td>
9125 <td style="vertical-align: top;">
9126 &nbsp;
9127 </td>
9128 <td style="vertical-align: top;">
9129 &nbsp;
9130 </td>
9131 </tr>
9132 <tr>
9133 <td style="vertical-align: top;">
9134 A = A - 1;
9135 </td>
9136 <td style="vertical-align: top;">
9137 &nbsp;
9138 </td>
9139 <td style="vertical-align: top;">
9140 A--
9141 </td>
9142 <td style="vertical-align: top;">
9143 &nbsp;
9144 </td>
9145 <td style="vertical-align: top;">
9146 &nbsp;
9147 </td>
9148 </tr>
9149 <tr>
9150 <td style="vertical-align: top;">
9151 &nbsp;
9152 </td>
9153 <td style="vertical-align: top;">
9154 &nbsp;
9155 </td>
9156 <td style="vertical-align: top;">
9157 &nbsp;
9158 </td>
9159 <td style="vertical-align: top;">
9160 &nbsp;
9161 </td>
9162 <td style="vertical-align: top;">
9163 &nbsp;
9164 </td>
9165 </tr>
9166 <tr>
9167 <td style="vertical-align: top;">
9168 A = [ 1 2; 3 4; ]
9169 </td>
9170 <td style="vertical-align: top;">
9171 &nbsp;
9172 </td>
9173 <td style="vertical-align: top;">
9174 A&nbsp;<font size=-1>&lt;&lt;</font> 1 <font size=-1>&lt;&lt;</font> 2 <font size=-1>&lt;&lt;</font> endr<br>
9175 &nbsp;&nbsp;&nbsp;<font size=-1>&lt;&lt;</font> 3 <font size=-1>&lt;&lt;</font> 4 <font size=-1>&lt;&lt;</font> endr;
9176 </td>
9177 <td style="vertical-align: top;">
9178 &nbsp;
9179 </td>
9180 <td style="vertical-align: top;">
9181 <a href="#element_initialisation">element initialisation</a>,
9182 with special element <i>endr</i> indicating <i>end of row</i>
9183 </td>
9184 </tr>
9185 <tr>
9186 <td style="vertical-align: top;">
9187 &nbsp;
9188 </td>
9189 <td style="vertical-align: top;">
9190 &nbsp;
9191 </td>
9192 <td style="vertical-align: top;">
9193 &nbsp;
9194 </td>
9195 <td style="vertical-align: top;">
9196 &nbsp;
9197 </td>
9198 <td style="vertical-align: top;">
9199 &nbsp;
9200 </td>
9201 </tr>
9202 <tr>
9203 <td style="vertical-align: top;">
9204 X = [&nbsp;A&nbsp;&nbsp;B&nbsp;]
9205 </td>
9206 <td style="vertical-align: top;">
9207 &nbsp;
9208 </td>
9209 <td style="vertical-align: top;">
9210 X = <a href="#join">join_rows</a>(A,B)
9211 </td>
9212 <td style="vertical-align: top;">
9213 &nbsp;
9214 </td>
9215 <td style="vertical-align: top;">
9216 &nbsp;
9217 </td>
9218 </tr>
9219 <tr>
9220 <td style="vertical-align: top;">
9221 X = [&nbsp;A;&nbsp;B&nbsp;]
9222 </td>
9223 <td style="vertical-align: top;">
9224 &nbsp;
9225 </td>
9226 <td style="vertical-align: top;">
9227 X = <a href="#join">join_cols</a>(A,B)
9228 </td>
9229 <td style="vertical-align: top;">
9230 &nbsp;
9231 </td>
9232 <td style="vertical-align: top;">
9233 &nbsp;
9234 </td>
9235 </tr>
9236 <tr>
9237 <td style="vertical-align: top;">
9238 &nbsp;
9239 </td>
9240 <td style="vertical-align: top;">
9241 &nbsp;
9242 </td>
9243 <td style="vertical-align: top;">
9244 &nbsp;
9245 </td>
9246 <td style="vertical-align: top;">
9247 &nbsp;
9248 </td>
9249 <td style="vertical-align: top;">
9250 &nbsp;
9251 </td>
9252 </tr>
9253 <tr>
9254 <td style="vertical-align: top;">
9255 A
9256 </td>
9257 <td style="vertical-align: top;">
9258 &nbsp;
9259 </td>
9260 <td style="vertical-align: top;">
9261 cout <font size=-1>&lt;&lt;</font> A <font size=-1>&lt;&lt;</font> endl;
9262 <br>or
9263 <br>A<a href="#print">.print</a>("A =");
9264 </td>
9265 <td style="vertical-align: top;">
9266 &nbsp;
9267 </td>
9268 <td style="vertical-align: top;">
9269 &nbsp;
9270 </td>
9271 </tr>
9272 <tr>
9273 <td style="vertical-align: top;">
9274 &nbsp;
9275 </td>
9276 <td style="vertical-align: top;">
9277 &nbsp;
9278 </td>
9279 <td style="vertical-align: top;">
9280 &nbsp;
9281 </td>
9282 <td style="vertical-align: top;">
9283 &nbsp;
9284 </td>
9285 <td style="vertical-align: top;">
9286 &nbsp;
9287 </td>
9288 </tr>
9289 <tr>
9290 <td style="vertical-align: top;">
9291 save&nbsp;-ascii&nbsp;'A.dat'&nbsp;A
9292 </td>
9293 <td style="vertical-align: top;">
9294 &nbsp;
9295 </td>
9296 <td style="vertical-align: top;">
9297 A<a href="#save_load_mat">.save</a>("A.dat",&nbsp;raw_ascii);
9298 </td>
9299 <td style="vertical-align: top;">
9300 &nbsp;
9301 </td>
9302 <td style="vertical-align: top;">
9303 Matlab/Octave matrices saved as ascii are readable by Armadillo (and vice-versa)
9304 </td>
9305 </tr>
9306 <tr>
9307 <td style="vertical-align: top;">
9308 load&nbsp;-ascii&nbsp;'A.dat'
9309 </td>
9310 <td style="vertical-align: top;">
9311 &nbsp;
9312 </td>
9313 <td style="vertical-align: top;">
9314 A<a href="#save_load_mat">.load</a>("A.dat",&nbsp;raw_ascii);
9315 </td>
9316 <td style="vertical-align: top;">
9317 &nbsp;
9318 </td>
9319 <td style="vertical-align: top;">
9320 &nbsp;
9321 </td>
9322 </tr>
9323 <tr>
9324 <td style="vertical-align: top;">
9325 &nbsp;
9326 </td>
9327 <td style="vertical-align: top;">
9328 &nbsp;
9329 </td>
9330 <td style="vertical-align: top;">
9331 &nbsp;
9332 </td>
9333 <td style="vertical-align: top;">
9334 &nbsp;
9335 </td>
9336 <td style="vertical-align: top;">
9337 &nbsp;
9338 </td>
9339 </tr>
9340 <tr>
9341 <td style="vertical-align: top;">
9342 S&nbsp;=&nbsp;{&nbsp;'abc';&nbsp;'def'&nbsp;}
9343 </td>
9344 <td style="vertical-align: top;">
9345 &nbsp;
9346 </td>
9347 <td style="vertical-align: top;">
9348 <a href="#field">field</a>&lt;std::string&gt; S(2);
9349 <br>S(0) = "abc";
9350 <br>S(1) = "def";
9351 </td>
9352 <td style="vertical-align: top;">
9353 &nbsp;
9354 </td>
9355 <td style="vertical-align: top;">
9356 <a href="#field">fields</a> can store arbitrary objects, in a 1D or 2D layout
9357 </td>
9358 </tr>
9359 </tbody>
9360 </table>
9361 </ul>
9362 <br>
9363
9364 <a name="example_prog"></a>
9365 <hr class="greyline">
9366 <br>
9367 <b>example program</b>
9368 <br>
9369 <br>
9370 <ul>
9371 <li>
9372 If you save the program below as <i>example.cpp</i>,
9373 under Linux you can compile it using:
9374 <br>
9375 g++ example.cpp -o example -O1 -larmadillo
9376 </li>
9377 <ul>
9378 <pre>
9379 #include &lt;iostream&gt;
9380 #include &lt;armadillo&gt;
9381
9382 using namespace std;
9383 using namespace arma;
9384
9385 int main(int argc, char** argv)
9386 {
9387 mat A = randu&lt;mat&gt;(4,5);
9388 mat B = randu&lt;mat&gt;(4,5);
9389
9390 cout &lt;&lt; A*trans(B) &lt;&lt; endl;
9391
9392 return 0;
9393 }
9394 </pre>
9395 </ul>
9396 <li>
9397 You may also want to have a look at the example programs that come with the Armadillo archive.
9398 </li>
9399 <br>
9400 <li>
9401 As Armadillo is a template library, we strongly recommended to have optimisation enabled when compiling programs
9402 (eg. when compiling with GCC, use the -O1 or -O2 options).
9403 </li>
9404 </ul>
9405 <br>
9406
9407
9408 <!--
9409 <a name="catching_exceptions"></a>
9410 <hr class="greyline">
9411 <br>
9412 <b>how to catch std::runtime_error exceptions</b>
9413 <br>
9414 <br>
9415 <ul>
9416 <li>
9417 If a function such as <a href="#inv">inv()</a> fails to find a solution,
9418 an error message is printed and a <i>std::runtime_error</i> exception is thrown.
9419 If the exception is not caught, the program typically terminates.
9420 Below is an example of how to catch exceptions:
9421 <ul>
9422 <pre>
9423 #include &lt;iostream&gt;
9424 #include &lt;armadillo&gt;
9425
9426 using namespace std;
9427 using namespace arma;
9428
9429 int main(int argc, char** argv)
9430 {
9431 // create a non-invertible matrix
9432 mat A = zeros&lt;mat&gt;(5,5);
9433
9434 mat B;
9435
9436 try
9437 {
9438 B = inv(A);
9439 }
9440 catch (std::runtime_error&amp; x)
9441 {
9442 cout &lt;&lt; "caught an exception" &lt;&lt; endl;
9443 }
9444
9445 return 0;
9446 }
9447 </pre>
9448 </ul>
9449 <li>
9450 See also:
9451 <ul>
9452 <li><a href="#logging">logging of warnings and errors</a></li>
9453 <li><a href="http://cplusplus.com/doc/tutorial/exceptions/">tutorial on exceptions</a></li>
9454 <li><a href="http://cplusplus.com/reference/std/stdexcept/runtime_error/">std::runtime_error</a></li>
9455 </ul>
9456 </li>
9457 <br>
9458 </ul>
9459 <br>
9460 -->
9461
9462 <a name="api_changes"></a>
9463 <hr class="greyline">
9464 <br>
9465 <b>API Changes, Additions and Deprecations</b>
9466 <br>
9467 <br>
9468 Armadillo's version number is X.Y.Z, where X is a major version, Y is a minor version, and Z is the patch level (indicating bug fixes).
9469 <br>
9470 <br>
9471 Within each major version (eg. 2.x), minor versions with an even number (eg. 2.2) are backwards compatible with earlier even minor versions (eg. 2.0).
9472 For example, code written for version 2.0 will work with version 2.2.
9473 However, as each minor version may have more features (ie. API extensions) than earlier versions,
9474 code written for version 2.2 doesn't necessarily work with 2.0.
9475 <br>
9476 <br>
9477 An odd minor version number (eg. 2.3) indicates an experimental version.
9478 Experimental versions are generally faster and have more functionality,
9479 but their APIs have not been finalised yet.
9480 <br>
9481 <br>
9482 In general, we don't like changes to existing APIs and prefer not to break any user software.
9483 However, to allow evolution and help code maintenance, we reserve the right to change the APIs in future major versions of Armadillo,
9484 while remaining backwards compatible wherever possible
9485 (eg. 3.0 may have slightly different APIs than 2.x).
9486 Also, in a rare instance the user API may need to be altered if a bug fix absolutely requires it.
9487 <br>
9488 <br>
9489 <br>
9490 <a name="deprecated"></a>
9491 Below is a list of deprecated functionality; this functionality will be <b>removed</b> in version 3.0:
9492 <ul>
9493 <li>
9494 <i>.print_trans()</i> and <i>.raw_print_trans()</i> are deprecated;
9495 <br>instead, you can chain <i>.t()</i> and <i>.print()</i> to achieve a similar result: <i>.t().print()</i>
9496 <br>&nbsp;
9497 </li>
9498 <li>
9499 support for tying writeable auxiliary (external) memory to fixed size matrices is deprecated;
9500 <br>instead, you can use standard matrices with <a href="#adv_constructors_mat">writeable auxiliary memory</a>,
9501 or initialise fixed size matrices by <a href="#adv_constructors_mat">copying the memory</a>.
9502 Using auxiliary memory with standard matrices is unaffected.
9503 <br>&nbsp;
9504 </li>
9505 </ul>
9506 <br>
9507 <br>
9508 Below is a list of additions and changes since prior versions of Armadillo:
9509 <ul>
9510 <a name="added_in_24"></a>
9511 <li>Added in 2.4:
9512 <ul>
9513 <li>shorter forms of transposes: <a href="#t_st_members">.t()</a> and <a href="#t_st_members">.st()</a></li>
9514 <li><a href="#resize_member">.resize()</a> and <a href="#resize">resize()</a> (added in 2.4.1)</li>
9515 <li>optional use of 64 bit indices (allowing matrices to have more than 4 billion elements),
9516 <br>enabled via ARMA_64BIT_WORD in <i>include/armadillo_bits/config.hpp</i></li>
9517 <li>experimental support for C++11 initialiser lists, enabled via ARMA_USE_CXX11 in <i>include/armadillo_bits/config.hpp</i></li>
9518 </ul>
9519 <br>
9520 <li>Changed in 2.4:
9521 <ul>
9522 <li>refactored code to eliminate warnings when using the Clang C++ compiler</li>
9523 <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>
9524 have been changed to use the <a href="#uword"><i>uword</i></a> type instead of the <i>u32</i> type;
9525 by default the <i>uword</i> and <i>u32</i> types are equivalent (ie. unsigned integer type with a minimum width 32 bits);
9526 however, when the use of 64 bit indices is enabled via ARMA_64BIT_WORD in <i>include/armadillo_bits/config.hpp</i>,
9527 the <i>uword</i> type then has a minimum width of 64 bits
9528 </ul>
9529 </li>
9530 <br>
9531 <li>Added in 2.2:
9532 <ul>
9533 <li><a href="#svd_econ">svd_econ()</a></li>
9534 <li><a href="#toeplitz">circ_toeplitz()</a></li>
9535 <li><a href="#is_vec">.is_colvec()</a> and <a href="#is_vec">.is_rowvec()</a></li>
9536 </ul>
9537 <br>
9538 <li>Changed in 2.0:
9539 <ul>
9540 <li><a href="#trans">trans()</a> now takes the complex conjugate when transposing a complex matrix</li>
9541 <li>Forms of
9542 <a href="#chol">chol()</a>, <a href="#eig_sym">eig_sym()</a>, <a href="#eig_gen">eig_gen()</a>,
9543 <a href="#inv">inv()</a>, <a href="#lu">lu()</a>, <a href="#pinv">pinv()</a>, <a href="#princomp">princomp()</a>,
9544 <a href="#qr">qr()</a>, <a href="#solve">solve()</a>, <a href="#svd">svd()</a>, <a href="#syl">syl()</a>
9545 that do not return a bool indicating success now throw <i>std::runtime_error</i> exceptions when failures are detected</li>
9546 <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>
9547 <li><a href="#is_vec">.is_vec()</a> now outputs <i>true</i> for empty vectors (eg. 0x1)</li>
9548 <li>set_log_stream() &amp; get_log_stream() have been replaced by <a href="#logging">set_stream_err1()</a> &amp; <a href="#logging">get_stream_err1()</a></li>
9549 </ul>
9550 <br>
9551 <li>Added in 2.0:
9552 <ul>
9553 <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 (&le;&nbsp;4x4)</li>
9554 <li><a href="#syl">syl()</a>, for solving Sylvester's equation</li>
9555 <li><a href="#strans">strans()</a>, for transposing a complex matrix without taking the complex conjugate</li>
9556 <li><a href="#symmat">symmatu()</a> and <a href="#symmat">symmatl()</a></li>
9557 <li>submatrices of <a href="#submat">submatrices</a></li>
9558 <li>faster <a href="#inv">inverse</a> of symmetric positive definite matrices</li>
9559 <li>faster element access for <a href="#adv_constructors_mat_fixed">fixed size</a> matrices</li>
9560 <li>faster multiplication of tiny matrices (eg. 4x4)</li>
9561 <li>faster compound expressions containing <a href="#submat">submatrices</a></li>
9562 <li>handling of arbitrarily sized empty matrices (eg. 5x0)</li>
9563 <li>.count() member function in <a href="#running_stat">running_stat</a> and <a href="#running_stat_vec">running_stat_vec</a></li>
9564 <li><a href="#save_load_mat">loading &amp; saving</a> of matrices as CSV text files</li>
9565 </ul>
9566 <br>
9567 <li>Added in 1.2:
9568 <ul>
9569 <li><a href="#min_and_max_member">.min() &amp; .max()</a> member functions of Mat and Cube</li>
9570 <li><a href="#misc_fns">floor()</a> and <a href="#misc_fns">ceil()</a></li>
9571 <li>representation of &ldquo;not a number&rdquo;: <a href="#math_constants">math::nan()</a></li>
9572 <li>representation of infinity: <a href="#math_constants">math::inf()</a></li>
9573 <li>standalone <a href="#is_finite_standalone">is_finite()</a></li>
9574 <li><a href="#in_range">.in_range()</a> can use <b>span()</b> arguments</li>
9575 <li><a href="#adv_constructors_mat">fixed size</a> matrices and vectors can use auxiliary (external) memory</li>
9576 <li><a href="#submat">submatrices</a> and <a href="#subfield">subfields</a> can be accessed via <i><b>X(</b>&nbsp;<b>span(</b>a,b<b>)</b>,&nbsp;<b>span(</b>c,d<b>)</b>&nbsp;<b>)</b></i></li>
9577 <li><a href="#subcube">subcubes</a> can be accessed via <i><b>X(</b>&nbsp;<b>span(</b>a,b<b>)</b>,&nbsp;<b>span(</b>c,d<b>)</b>,&nbsp;<b>span(</b>e,f<b>)</b>&nbsp;<b>)</b></i></li>
9578 <li>the two argument version of <i><b>span</b></i> can be replaced by
9579 <i><b>span::all</b></i> or <i><b>span()</b></i>, to indicate an entire range
9580 </li>
9581 <li>for cubes, the two argument version of <i><b>span</b></i> can be replaced by
9582 a single argument version, <i><b>span(</b>a<b>)</b></i>, to indicate a single column, row or slice
9583 </li>
9584 <li>arbitrary "flat" subcubes can be interpreted as matrices; for example:
9585 <ul>
9586 <pre>
9587 cube Q = randu&lt;cube&gt;(5,3,4);
9588 mat A = Q(&nbsp;span(1),&nbsp;span(1,2),&nbsp;span::all&nbsp;);
9589 // A has a size of 2x4
9590
9591 vec v = ones&lt;vec&gt;(4);
9592 Q(&nbsp;span(1),&nbsp;span(1),&nbsp;span::all&nbsp;)&nbsp;=&nbsp;v;
9593 </pre>
9594 </ul>
9595 </li>
9596 <li>interpretation of matrices as triangular through <a href="#trimat">trimatu() / trimatl()</a></li>
9597 <li>explicit handling of triangular matrices by <a href="#solve">solve()</a> and <a href="#inv">inv()</a></li>
9598 <li>extended syntax for <a href="#submat">submatrices</a>, including access to elements whose indices are specified in a vector</li>
9599 <li>ability to change the stream used for <a href="#logging">logging</a> of errors and warnings</li>
9600 <li>ability to <a href="#save_load_mat">save/load matrices</a> in raw binary format</li>
9601 <li>cumulative sum function: <a href="#cumsum">cumsum()</a></li>
9602 </ul>
9603 </li>
9604 <br>
9605 <li>
9606 Changed in 1.0 (compared to earlier 0.x development versions):
9607 <ul>
9608 <li>
9609 the 3 argument version of <a href="#lu">lu()</a>,
9610 eg. lu(L,U,X),
9611 provides L and U which should be the same as produced by Octave 3.2
9612 (this was not the case in versions prior to 0.9.90)
9613 </li>
9614 <br>
9615 <li>
9616 rand() has been replaced by <a href="#randu_randn_standalone">randu()</a>;
9617 this has been done to avoid confusion with <a href="http://cplusplus.com/reference/clibrary/cstdlib/rand/">std::rand()</a>,
9618 which generates random numbers in a different interval
9619 </li>
9620 <br>
9621 <li>
9622 In versions earlier than 0.9.0,
9623 some multiplication operations directly converted result matrices with a size of 1x1 into scalars.
9624 This is no longer the case.
9625 If you know the result of an expression will be a 1x1 matrix and wish to treat it as a pure scalar,
9626 use the <a href="#as_scalar">as_scalar()</a> wrapping function
9627 </li>
9628 <br>
9629 <li>
9630 Almost all functions have been placed in the delayed operations framework (for speed purposes).
9631 This may affect code which assumed that the output of some functions was a pure matrix.
9632 The solution is easy, as explained below.
9633 <br>
9634 <br>
9635 In general, Armadillo queues operations before executing them.
9636 As such, the direct output of an operation or function cannot be assumed to be a directly accessible matrix.
9637 The queued operations are executed when the output needs to be stored in a matrix,
9638 eg. <i>mat&nbsp;B&nbsp;=&nbsp;trans(A)</i> or <i>mat&nbsp;B(trans(A))</i>.
9639 If you need to force the execution of the delayed operations,
9640 place the operation or function inside the corresponding Mat constructor.
9641 For example, if your code assumed that the output of some functions was a pure matrix,
9642 eg. <i>chol(m).diag()</i>, change the code to <i>mat(chol(m)).diag()</i>.
9643 Similarly, if you need to pass the result of an operation such as <i>A+B</i> to one of your own functions,
9644 use <i>my_function(&nbsp;mat(A+B)&nbsp;)</i>.
9645 </li>
9646 </ul>
9647 </li>
9648 <br>
9649 </ul>
9650 <br>
9651 <br>
9652
9653
9654 <!-- END CONTENT -->
9655
9656
9657 <hr>
9658 <br>
9659 <br>
9660
9661 </td>
9662 </tr>
9663 </tbody>
9664 </table>
9665 </center>
9666 </body>
9667 </html>