-
@@ -4378,9 +4418,10 @@
@@ -4449,8 +4490,6 @@
.insert_rows( row_number, X )
.insert_rows( row_number, number_of_rows )
-
- .insert_rows( row_number, number_of_rows, set_to_zero )
|
(member functions of Mat, Col and Cube)
@@ -4464,8 +4503,6 @@
.insert_cols( col_number, X )
.insert_cols( col_number, number_of_cols )
-
- .insert_cols( col_number, number_of_cols, set_to_zero )
|
|
(member functions of Mat, Row and Cube)
@@ -4479,8 +4516,6 @@
.insert_slices( slice_number, X )
.insert_slices( slice_number, number_of_slices )
-
- .insert_slices( slice_number, number_of_slices, set_to_zero )
|
|
(member functions of Cube)
@@ -4502,8 +4537,7 @@
Functions with the number_of_... argument:
- expand the object by creating new rows/columns/slices
-- by default, the new rows/columns/slices are set to zero
-- if set_to_zero is false, the memory used by the new rows/columns/slices will not be initialised
+- the elements in the new rows/columns/slices are set to zero
@@ -4528,8 +4562,8 @@
-
See also:
-
-The function can be used for interfacing with libraries such as FFTW
-
-
--
Data for matrices is stored in a column-by-column order
@@ -4757,6 +4786,7 @@
See also:
@@ -5322,7 +5352,7 @@
- subcube views
- iterators (subcubes)
- iterators (dense matrices)
-- iterator at cplusplus.com
+- iterator at cplusplus.com
@@ -5343,11 +5373,9 @@
-
Caveats:
--
-to modify the non-zero elements in a safer manner,
-use .transform() or .for_each() instead of iterators;
-
-writing a zero value into a sparse matrix through an iterator will invalidate all current iterators associated with the sparse matrix
+- writing a zero value into a sparse matrix through an iterator will invalidate all current iterators associated with the sparse matrix
+- to modify the non-zero elements in a safer manner, use .transform() or .for_each() instead of iterators
+
@@ -5569,7 +5597,7 @@
- .replace()
- submatrix views
- iterators (dense matrices)
-- iterator at cplusplus.com
+- iterator at cplusplus.com
@@ -5613,7 +5641,7 @@
- .for_each()
- iterators (dense matrices)
- iterators (cubes)
-- range-based for (cppreference.com)
+- range-based for (cppreference.com)
@@ -5755,6 +5783,58 @@
+
+.col_as_mat( col_number )
+
+.row_as_mat( row_number )
+
+-
+Member functions of any cube expression
+
+
+-
+.col_as_mat( col_number ):
+
+- return a matrix representation of the specified cube column
+- the number of rows is preserved
+- given a cube with size R x C x S, the resultant matrix size is R x S
+
+
+
+-
+.row_as_mat( row_number ):
+
+- return a matrix representation of the specified cube row
+- the number of columns is preserved
+- given a cube with size R x C x S, the resultant matrix size is S x C
+
+
+
+
+-
+Examples:
+
+cube Q(5, 4, 3, fill::randu);
+
+mat A = Q.col_as_mat(2); // size of A: 5x3
+
+mat B = Q.row_as_mat(2); // size of B: 3x4
+
+
+
+
+-
+See also:
+
+
+
+
+
+
.t()
@@ -6351,8 +6431,8 @@
- trimatu() / trimatl()
- .is_symmetric()
- .is_diagmat()
-- Triangular matrix in MathWorld
-- Triangular matrix in Wikipedia
+- Triangular matrix in MathWorld
+- Triangular matrix in Wikipedia
@@ -6395,7 +6475,7 @@
- diagmat()
- .is_trimatu() / .is_trimatl()
- .is_symmetric()
-- Diagonal matrix in MathWorld
+- Diagonal matrix in MathWorld
- Diagonal matrix in Wikipedia
@@ -6480,7 +6560,7 @@
- .is_square()
- .is_trimatu() / .is_trimatl()
- Symmetric matrix in Wikipedia
-- Symmetric matrix in MathWorld
+- Symmetric matrix in MathWorld
@@ -6523,7 +6603,7 @@
- .is_sympd()
- .is_square()
- Hermitian matrix in Wikipedia
-- Hermitian matrix in MathWorld
+- Hermitian matrix in MathWorld
@@ -6583,7 +6663,7 @@
- For objects with complex elements: return true if for each element, each component (real and imaginary) has an absolute value ≤ tolerance; return false otherwise
-- The argument tolerance is optional; by default tolerance = 0
+- The argument tolerance is optional; by default tolerance = 0
-
Examples:
@@ -6843,8 +6923,8 @@
@@ -6900,7 +6980,7 @@
-saving/loading matrices & cubes
+saving / loading matrices & cubes
@@ -7097,6 +7177,18 @@
-
+Caveat:
+for saving / loading HDF5 files, support for HDF5 must be enabled within Armadillo's configuration;
+the hdf5.h header file must be available on your system and you will need to link with the HDF5 library (eg.
-lhdf5).
+HDF5 support can be enabled by defining ARMA_USE_HDF5 before including the armadillo header:
+
+
+#define ARMA_USE_HDF5
+
#include <armadillo>
+
+
+
+-
By providing either hdf5_name(filename, dataset) or hdf5_name(filename, dataset, settings), the file_type type is assumed to be hdf5_binary
@@ -7113,7 +7205,7 @@
hdf5_opts::trans | | save/load the data with columns transposed to rows (and vice versa) |
hdf5_opts::append | | instead of overwriting the file, append the specified dataset to the file;
the specified dataset must not already exist in the file |
-hdf5_opts::replace | | instead of overwriting the file, replace the specified dataset in the file
caveat: HDF5 v1.8 may not automatically reclaim deleted space; use h5repack to clean HDF5 files |
+hdf5_opts::replace | | instead of overwriting the file, replace the specified dataset in the file
caveat: HDF5 may not automatically reclaim deleted space; use h5repack to clean HDF5 files |
the above settings can be combined using the + operator; for example: hdf5_opts::trans + hdf5_opts::append
@@ -7122,12 +7214,6 @@
-
-Caveat:
-for saving/loading HDF5 files, support for HDF5 must be enabled within Armadillo's configuration;
-the hdf5.h header file must be available on your system and you will need to link with the HDF5 library (eg.
-lhdf5)
-
-
--
By providing either csv_name(filename, header) or csv_name(filename, header, settings),
the file is assumed to have data in comma separated value (CSV) text format
@@ -7144,7 +7230,8 @@
csv_opts::trans | | save/load the data with columns transposed to rows (and vice versa) |
csv_opts::no_header | | assume there is no header line; the header argument is not referenced |
-csv_opts::semicolon | | use semicolon (;) instead of comma (,) as the separator character (Armadillo 10.6 and later) |
+csv_opts::semicolon | | use semicolon (;) instead of comma (,) as the separator character |
+csv_opts::strict | | interpret missing values as NaN (not applicable to sparse matrices) |
the above settings can be combined using the + operator; for example: csv_opts::trans + csv_opts::no_header
@@ -7201,7 +7288,7 @@
@@ -7209,7 +7296,7 @@
-saving/loading fields
+saving / loading fields
@@ -7319,7 +7406,7 @@
- See also:
@@ -7332,7 +7419,7 @@
-Generated Vectors/Matrices/Cubes
+Generated Vectors / Matrices / Cubes
@@ -7495,6 +7582,7 @@
@@ -7528,6 +7616,7 @@
See also:
@@ -7611,15 +7700,23 @@
-
+Caveat: specifying fill::ones during object construction is more compact, eg.
mat A(5, 6, fill::ones)
+
+
+-
Examples:
-vec v = ones<vec>(10);
-uvec u = ones<uvec>(11);
-mat A = ones<mat>(5,6);
-cube Q = ones<cube>(5,6,7);
+ vec v = ones(10); // or: vec v(10, fill::ones);
+ uvec u = ones<uvec>(10);
+rowvec r = ones<rowvec>(10);
-mat B = 123.0 * ones<mat>(5,6);
+ mat A = ones(5,6); // or: mat A(5, 6, fill::ones);
+fmat B = ones<fmat>(5,6);
+umat C = ones<umat>(5,6);
+
+ cube Q = ones(5,6,7); // or: cube Q(5, 6, 7, fill::ones);
+fcube R = ones<fcube>(5,6,7);
@@ -7628,12 +7725,12 @@
See also:
@@ -7664,13 +7761,23 @@
-
+Caveat: specifying fill::zeros during object construction is more compact, eg.
mat A(5, 6, fill::zeros)
+
+
+-
Examples:
-vec v = zeros<vec>(10);
-uvec u = zeros<uvec>(11);
-mat A = zeros<mat>(5,6);
-cube Q = zeros<cube>(5,6,7);
+ vec v = zeros(10); // or: vec v(10, fill::zeros);
+ uvec u = zeros<uvec>(10);
+rowvec r = zeros<rowvec>(10);
+
+ mat A = zeros(5,6); // or: mat A(5, 6, fill::zeros);
+fmat B = zeros<fmat>(5,6);
+umat C = zeros<umat>(5,6);
+
+ cube Q = zeros(5,6,7); // or: cube Q(5, 6, 7, fill::zeros);
+fcube R = zeros<fcube>(5,6,7);
@@ -7679,9 +7786,9 @@
See also:
@@ -7689,38 +7796,43 @@
-
-randu( )
+
+randu( )
+
randu( distr_param(a,b) )
+
randu( n_elem )
+
randu( n_elem, distr_param(a,b) )
+
randu( n_rows, n_cols )
+
randu( n_rows, n_cols, distr_param(a,b) )
+
randu( n_rows, n_cols, n_slices )
-
randu( size(X) )
+
randu( n_rows, n_cols, n_slices, distr_param(a,b) )
-
randn( )
-
randn( n_elem )
-
randn( n_rows, n_cols )
-
randn( n_rows, n_cols, n_slices )
-
randn( size(X) )
+
randu( size(X) )
+
randu( size(X), distr_param(a,b) )
-
-Generate a scalar, vector, matrix or cube with the elements set to random floating point values
-
-
-- randu() uses a uniform distribution in the [0,1] interval
+Generate a scalar, vector, matrix or cube with the elements set to random floating point values uniformly distributed in the [a,b] interval
-- randn() uses a normal/Gaussian distribution with zero mean and unit variance
+
- The default distribution parameters are a = 0 and b = 1
-
Usage:
- scalar_type s = randu<scalar_type>( ), where scalar_type ∈ { float, double, cx_float, cx_double }
+- scalar_type s = randu<scalar_type>( distr_param(a,b) ), where scalar_type ∈ { float, double, cx_float, cx_double }
+
- vector_type v = randu<vector_type>( n_elem )
+- vector_type v = randu<vector_type>( n_elem, distr_param(a,b) )
+
- matrix_type X = randu<matrix_type>( n_rows, n_cols )
-- matrix_type Y = randu<matrix_type>( size(X) )
+- matrix_type X = randu<matrix_type>( n_rows, n_cols, distr_param(a,b) )
+
- cube_type Q = randu<cube_type>( n_rows, n_cols, n_slices )
-- cube_type R = randu<cube_type>( size(Q) )
+- cube_type Q = randu<cube_type>( n_rows, n_cols, n_slices, distr_param(a,b) )
@@ -7729,17 +7841,27 @@
-
-Caveat: to generate a matrix with random integer values instead of floating point values,
-use randi() instead
+Caveat: to generate a matrix with random integer values instead of floating point values, use randi() instead
-
Examples:
-vec v = randu<vec>(5);
-mat A = randu<mat>(5,6);
-cube Q = randu<cube>(5,6,7);
+double a = randu();
+double b = randu(distr_param(10,20));
+
+vec v1 = randu(5); // or: vec v1(5, fill::randu);
+vec v2 = randu(5, distr_param(10,20));
+
+rowvec r1 = randu<rowvec>(5);
+rowvec r2 = randu<rowvec>(5, distr_param(10,20));
+
+mat A1 = randu(5, 6); // or: mat A1(5, 6, fill::randu);
+mat A2 = randu(5, 6, distr_param(10,20));
+
+fmat B1 = randu<fmat>(5, 6);
+fmat B2 = randu<fmat>(5, 6, distr_param(10,20));
arma_rng::set_seed_random(); // set the seed to a random value
@@ -7747,48 +7869,131 @@
- See also:
-
-randg( )
-
randg( distr_param(a,b) )
+
+randn( )
+
randn( distr_param(mu,sd) )
-
randg( n_elem )
-
randg( n_elem, distr_param(a,b) )
+
randn( n_elem )
+
randn( n_elem, distr_param(mu,sd) )
-
randg( n_rows, n_cols )
-
randg( n_rows, n_cols, distr_param(a,b) )
+
randn( n_rows, n_cols )
+
randn( n_rows, n_cols, distr_param(mu,sd) )
-
randg( n_rows, n_cols, n_slices )
-
randg( n_rows, n_cols, n_slices, distr_param(a,b) )
+
randn( n_rows, n_cols, n_slices )
+
randn( n_rows, n_cols, n_slices, distr_param(mu,sd) )
-
randg( size(X) )
-
randg( size(X), distr_param(a,b) )
+
randn( size(X) )
+
randn( size(X), distr_param(mu,sd) )
-
-Generate a scalar, vector, matrix or cube with the elements set to random values from a gamma distribution:
+Generate a scalar, vector, matrix or cube with the elements set to random values with normal / Gaussian distribution, parameterised by mean mu and standard deviation sd
+
+
+- The default distribution parameters are mu = 0 and sd = 1
+
+
+-
+Usage:
-
-
-
- | | | x a-1 exp( -x / b ) |
+- scalar_type s = randn<scalar_type>( ), where scalar_type ∈ { float, double, cx_float, cx_double }
+- scalar_type s = randn<scalar_type>( distr_param(mu,sd) ), where scalar_type ∈ { float, double, cx_float, cx_double }
+
+- vector_type v = randn<vector_type>( n_elem )
+- vector_type v = randn<vector_type>( n_elem, distr_param(mu,sd) )
+
+- matrix_type X = randn<matrix_type>( n_rows, n_cols )
+- matrix_type X = randn<matrix_type>( n_rows, n_cols, distr_param(mu,sd) )
+
+- cube_type Q = randn<cube_type>( n_rows, n_cols, n_slices )
+- cube_type Q = randn<cube_type>( n_rows, n_cols, n_slices, distr_param(mu,sd) )
+
+
+
+-
+To change the RNG seed, use arma_rng::set_seed(value) or arma_rng::set_seed_random() functions
+
+
+-
+Examples:
+
+double a = randn();
+double b = randn(distr_param(10,5));
+
+vec v1 = randn(5); // or: vec v1(5, fill::randn);
+vec v2 = randn(5, distr_param(10,5));
+
+rowvec r1 = randn<rowvec>(5);
+rowvec r2 = randn<rowvec>(5, distr_param(10,5));
+
+mat A1 = randn(5, 6); // or: mat A1(5, 6, fill::randn);
+mat A2 = randn(5, 6, distr_param(10,5));
+
+fmat B1 = randn<fmat>(5, 6);
+fmat B2 = randn<fmat>(5, 6, distr_param(10,5));
+
+arma_rng::set_seed_random(); // set the seed to a random value
+
+
+
+- See also:
+
+
+
+
+
+
+
+randg( )
+
randg( distr_param(a,b) )
+
+
randg( n_elem )
+
randg( n_elem, distr_param(a,b) )
+
+
randg( n_rows, n_cols )
+
randg( n_rows, n_cols, distr_param(a,b) )
+
+
randg( n_rows, n_cols, n_slices )
+
randg( n_rows, n_cols, n_slices, distr_param(a,b) )
+
+
randg( size(X) )
+
randg( size(X), distr_param(a,b) )
+
+-
+Generate a scalar, vector, matrix or cube with the elements set to random values from a gamma distribution:
+
+
+
+
+ | | | x a-1 exp( -x / b ) |
| p(x | a,b) | = |
|
@@ -7816,13 +8021,9 @@
- matrix_type X = randg<matrix_type>( n_rows, n_cols )
- matrix_type X = randg<matrix_type>( n_rows, n_cols, distr_param(a,b) )
-- matrix_type Y = randg<matrix_type>( size(X) )
-- matrix_type Y = randg<matrix_type>( size(X), distr_param(a,b) )
- cube_type Q = randg<cube_type>( n_rows, n_cols, n_slices )
- cube_type Q = randg<cube_type>( n_rows, n_cols, n_slices, distr_param(a,b) )
-- cube_type R = randg<cube_type>( size(Q) )
-- cube_type R = randg<cube_type>( size(Q), distr_param(a,b) )
@@ -7834,20 +8035,29 @@
Examples:
-vec v = randg<vec>(100, distr_param(2,1));
+vec v1 = randg(100);
+vec v2 = randg(100, distr_param(2,1));
-mat X = randg<mat>(10, 10, distr_param(2,1));
+rowvec r1 = randg<rowvec>(100);
+rowvec r2 = randg<rowvec>(100, distr_param(2,1));
+
+mat A1 = randg(10, 10);
+mat A2 = randg(10, 10, distr_param(2,1));
+
+fmat B1 = randg<fmat>(10, 10);
+fmat B2 = randg<fmat>(10, 10, distr_param(2,1));
- See also:
@@ -7871,7 +8081,7 @@
randi( size(X), distr_param(a,b) )
-
-Generate a scalar, vector, matrix or cube with the elements set to random integer values in the [a,b] interval
+Generate a scalar, vector, matrix or cube with the elements set to random integer values uniformly distributed in the [a,b] interval
- The default distribution parameters are a = 0 and b = maximum_int
@@ -7888,13 +8098,9 @@
- matrix_type X = randi<matrix_type>( n_rows, n_cols )
- matrix_type X = randi<matrix_type>( n_rows, n_cols, distr_param(a,b) )
-- matrix_type Y = randi<matrix_type>( size(X) )
-- matrix_type Y = randi<matrix_type>( size(X), distr_param(a,b) )
- cube_type Q = randi<cube_type>( n_rows, n_cols, n_slices )
- cube_type Q = randi<cube_type>( n_rows, n_cols, n_slices, distr_param(a,b) )
-- cube_type R = randi<cube_type>( size(Q) )
-- cube_type R = randi<cube_type>( size(Q), distr_param(a,b) )
@@ -7903,16 +8109,21 @@
-
-Caveat: to generate a continuous distribution with floating point values (ie. float or double), use randu() instead
+Caveat: to generate a matrix with random floating point values (ie. float or double) instead of integers, use randu() instead
-
Examples:
-imat A = randi<imat>(5, 6);
+int a = randi();
+int b = randi(distr_param(-10, +20));
+
+imat A1 = randi(5, 6);
+imat A2 = randi(5, 6, distr_param(-10, +20));
-imat A = randi<imat>(6, 7, distr_param(-10, +20));
+mat B1 = randi<mat>(5, 6);
+mat B2 = randi<mat>(5, 6, distr_param(-10, +20));
arma_rng::set_seed_random(); // set the seed to a random value
@@ -7920,8 +8131,7 @@
- See also:
@@ -8091,9 +8302,9 @@
- See also:
@@ -8106,7 +8317,7 @@
-Functions of Vectors/Matrices/Cubes
+Functions of Vectors / Matrices / Cubes
@@ -8155,7 +8366,8 @@
- arg()
- conj()
- imag() / real()
-- conv_to()
+- pow()
+- miscellaneous element-wise functions
@@ -8204,26 +8416,34 @@
affmul( A, B )
-- Multiply matrix A by an augmented form of B, where a row with ones is appended to B;
for example:
-
-⎡ A00 A01 A02 ⎤ ⎡ B0 ⎤
-⎢ A10 A11 A12 ⎥ x ⎢ B1 ⎥
-⎣ A20 A21 A22 ⎦ ⎣ 1 ⎦
-
+- Multiply matrix A by an automatically extended form of B
+
- A is typically an affine transformation matrix
-- The number of columns in A must be equal to number of rows in the augmented form of B (ie. A.n_cols = B.n_rows+1)
+- B can be a vector or matrix, and is treated as having an additional row of ones
-- B can be a vector or matrix
+- The number of columns in A must be equal to number of rows in the extended form of B (ie. A.n_cols = B.n_rows+1)
+- If A is 3x3 and B is 2x1, the equivalent matrix multiplication is:
+
+⎡ C0 ⎤ ⎡ A00 A01 A02 ⎤ ⎡ B0 ⎤
+⎢ C1 ⎥ = ⎢ A10 A11 A12 ⎥ x ⎢ B1 ⎥
+⎣ C2 ⎦ ⎣ A20 A21 A22 ⎦ ⎣ 1 ⎦
+
+- If A is 2x3 and B is 2x1, the equivalent matrix multiplication is:
+
+⎡ C0 ⎤ ⎡ A00 A01 A02 ⎤ ⎡ B0 ⎤
+⎣ C1 ⎦ = ⎣ A10 A11 A12 ⎦ x ⎢ B1 ⎥
+ ⎣ 1 ⎦
+
-
Examples:
-mat44 A; A.randu();
-vec3 B; B.randu();
+mat A(2, 3, fill::randu);
+vec B(2, fill::randu);
-vec4 C = affmul(A,B);
+vec C = affmul(A,B);
@@ -8472,7 +8692,7 @@
- abs()
- atan2()
- Argument (complex analysis) in Wikipedia
-- Complex Argument in MathWorld
+- Complex Argument in MathWorld
@@ -8573,27 +8793,20 @@
cond( A )
--
-Return the condition number of matrix A (the ratio of the largest singular value to the smallest)
-
+- Return the condition number of matrix A (the ratio of the largest singular value to the smallest)
--
-Large condition numbers suggest that matrix A is nearly singular
-
+- The ideal condition number is close to 1; large condition numbers suggest that matrix A is nearly singular
--
-The computation is based on singular value decomposition; if the decomposition fails, a std::runtime_error exception is thrown
-
+- The computation is based on singular value decomposition
--
-Caveat: the rcond() function is faster for providing an estimate of the reciprocal of the condition number
-
+- Caveat: rcond() is considerably faster
-
Examples:
-mat A(5, 5, fill::randu);
+mat A(5, 5, fill::randu);
+
double c = cond(A);
@@ -8606,8 +8819,8 @@
- rank()
- inv()
- solve()
-- condition number in MathWorld
-- condition number in Wikipedia
+- condition number in MathWorld
+- condition number in Wikipedia
@@ -8714,8 +8927,8 @@
See also:
@@ -8809,27 +9022,40 @@
-det( A )
+
+
+| val = det( A ) | | (form 1) |
+| det( val, A ) | | (form 2) |
+
+
--
-Determinant of square matrix A
-
+- Calculate the determinant of square matrix A, based on LU decomposition
--
-If A is not square sized, a std::logic_error exception is thrown
-
+- form 1: return the determinant
--
-Caveat: for large matrices log_det() and log_det_sympd() are more precise than det()
+
- form 2: store the calculated determinant in val and return a bool indicating success
+
+- If A is not square sized, a std::logic_error exception is thrown
+
+- If the calculation fails:
+
+- val = det(A) throws a std::runtime_error exception
+- det(val,A) returns a bool set to false (exception is not thrown)
+
+- Caveat: log_det() is preferred, as it's less likely to suffer from numerical underflows/overflows
+
-
Examples:
mat A(5, 5, fill::randu);
-double x = det(A);
+double val1 = det(A); // form 1
+
+double val2;
+bool success = det(val2, A); // form 2
@@ -8838,10 +9064,9 @@
See also:
@@ -8880,6 +9105,10 @@
-
+If X is an expression, the evaluation of the expression aims to calculate only the diagonal elements
+
+
+-
Examples:
@@ -8900,6 +9129,8 @@
- .diag()
- .is_diagmat()
- diagvec()
+- diags() / spdiags()
+- trace()
- trimatu() / trimatl()
- symmatu() / symmatl()
- reshape()
@@ -8912,11 +9143,11 @@
-diagvec( A )
-
diagvec( A, k )
+diagvec( X )
+
diagvec( X, k )
-
-Extract the k-th diagonal from matrix A
+Extract the k-th diagonal from matrix X
-
@@ -8932,6 +9163,10 @@
-
+If X is an expression, the evaluation of the expression aims to calculate only the diagonal elements
+
+
+-
Examples:
@@ -8954,6 +9189,74 @@
+
+
+
+| diags( V, D, n_rows, n_cols ) |
+| spdiags( V, D, n_rows, n_cols ) |
+
+
+
+-
+Generate a matrix with diagonals specified by vector D copied from corresponding column vectors in matrix V
+
+
+-
+Function diags() generates a dense matrix, while function spdiags() generates a sparse matrix; in both cases the generated matrix has the same element type as matrix V
+
+
+-
+Given vector D must be a vector of type ivec or irowvec
+
+
+-
+The number of columns in given matrix V must match the number of elements in vector D
+
+
+-
+Each element in vector D specifies diagonal k, where:
+
+- k = 0 indicates the main diagonal
+
- k < 0 indicates the k-th sub-diagonal (below main diagonal, towards bottom-left corner)
+
- k > 0 indicates the k-th super-diagonal (above main diagonal, towards top-right corner)
+
+
+
+-
+For k < 0, vectors from matrix V are truncated at the end
+
+
+-
+For k > 0, vectors from matrix V are truncated from the start
+
+
+-
+Examples:
+
+mat V(10, 3, fill::randu);
+
+ivec D = {-1, 0, +1};
+
+mat X = diags(V, D, 10, 10);
+
+sp_mat Y = spdiags(V, D, 10, 10);
+
+
+
+
+-
+See also:
+
+
+
+
+
+
diff( V )
diff( V, k )
@@ -8996,8 +9299,8 @@
- See also:
@@ -9074,8 +9377,8 @@
See also:
@@ -9097,9 +9400,13 @@
-- Caveat: if matrix A is symmetric, using expmat_sym() is faster
-
-- Caveat: the matrix exponential operation is generally not the same as applying the exp() function to each element
+-
+Caveats:
+
+- the matrix exponential operation is generally not the same as applying the exp() function to each element
+- if matrix A is symmetric, using expmat_sym() is faster
+
+
-
Examples:
@@ -9119,8 +9426,8 @@
- logmat()
- sqrtmat()
- miscellaneous element-wise functions
-- matrix exponential in Wikipedia
-- matrix exponential in MathWorld
+- matrix exponential in Wikipedia
+- matrix exponential in MathWorld
- Nineteen Dubious Ways to Compute the Exponential of a Matrix, Twenty-Five Years Later
@@ -9146,10 +9453,10 @@
-- Caveat: the matrix exponential operation is generally not the same as applying the exp() function to each element
+- Caveat: the matrix exponential operation is generally not the same as applying the exp() function to each element
-
Examples:
@@ -9173,8 +9480,8 @@
- .is_symmetric()
- .is_hermitian()
- miscellaneous element-wise functions
-- matrix exponential in Wikipedia
-- matrix exponential in MathWorld
+- matrix exponential in Wikipedia
+- matrix exponential in MathWorld
- Nineteen Dubious Ways to Compute the Exponential of a Matrix, Twenty-Five Years Later
@@ -9240,9 +9547,9 @@
- any()
- clamp()
- .transform()
-- approx_equal()
- find_finite()
- find_nonfinite()
+- find_nan()
- find_unique()
- nonzeros()
- unique()
@@ -9290,6 +9597,7 @@
- find()
- find_nonfinite()
+- find_nan()
- .is_finite()
- .replace()
- .has_inf()
@@ -9331,7 +9639,7 @@
-
-Caveat: to replace instances of a specific non-finite value (eg. nan or inf),
+Caveat: to replace instances of a specific non-finite value (eg. NaN or Inf),
it is more efficient to use .replace()
@@ -9340,6 +9648,7 @@
+
+find_nan( X )
+
+
+
+-
+Caveat: to replace instances of NaN values,
+it is more efficient to use .replace()
+
+
+-
+See also:
+
+
+
+
+
+
find_unique( X )
find_unique( X, ascending_indices )
@@ -9474,8 +9830,8 @@
-| uvec | sub = ind2sub( size(X), index ) | | (form 1) |
-| umat | sub = ind2sub( size(X), vector_of_indices ) | | (form 2) |
+| uvec | sub = ind2sub( size(X), index ) | | (form 1) |
+| umat | sub = ind2sub( size(X), vector_of_indices ) | | (form 2) |
@@ -9492,11 +9848,11 @@
-
-When only one index is given (form 1), the subscripts are returned in a vector of type uvec
+When only one index is given (form 1), the subscripts are returned in a vector of type uvec
-
-When a vector of indices (of type uvec) is given (form 2), the corresponding subscripts are returned in each column of an m x n matrix of type umat;
+When a vector of indices (of type uvec) is given (form 2), the corresponding subscripts are returned in each column of an m x n matrix of type umat;
m=2 for matrix subscripts, while m=3 for cube subscripts
@@ -9700,8 +10056,8 @@
-| C = intersect( A, B ) | | (form 1) |
-| intersect( C, iA, iB, A, B ) | | (form 2) |
+| C = intersect( A, B ) | | (form 1) |
+| intersect( C, iA, iB, A, B ) | | (form 2) |
@@ -9815,8 +10171,9 @@
-
See also:
@@ -9870,8 +10227,9 @@
-
See also:
@@ -9906,8 +10264,8 @@
@@ -9917,45 +10275,41 @@
-| log_det( val, sign, A ) | | (form 1) |
-| complex result = log_det( A ) | | (form 2) |
+| complex result = log_det( A ) | | (form 1) |
+| log_det( val, sign, A ) | | (form 2) |
--
-Log determinant of square matrix A
-
-
--
-If A is not square sized, a std::logic_error exception is thrown
-
+- Log determinant of square matrix A, based on LU decomposition
-- form 1: store the calculated log determinant in val and sign
-
the determinant is equal to exp(val)*sign
-
-
-- form 2: return the complex log determinant
+
- form 1: return the complex log determinant
-
if matrix A is real and the determinant is positive:
-- the real part of the result is the log determinant
+- the real part is the log determinant
- the imaginary part is zero
-
if matrix A is real and the determinant is negative:
-- the real part of the result is the log of the absolute value of the determinant
+- the real part is log abs(determinant)
- the imaginary part is equal to datum::pi
+ - form 2: store the calculated log determinant in val and sign, and return a bool indicating success;
+
the determinant is equal to exp(val) · sign
+
+
+- If A is not square sized, a std::logic_error exception is thrown
+
- If the log determinant cannot be found:
-- log_det(val, sign, A) returns a bool set to false (exception is not thrown)
- result = log_det(A) throws a std::runtime_error exception
+- log_det(val, sign, A) returns a bool set to false (exception is not thrown)
@@ -9965,12 +10319,12 @@
mat A(5, 5, fill::randu);
+cx_double result = log_det(A); // form 1
+
double val;
double sign;
-log_det(val, sign, A); // form 1
-
-cx_double result = log_det(A); // form 2
+bool ok = log_det(val, sign, A); // form 2
@@ -9982,8 +10336,8 @@
- det()
- rcond()
- cx_double
-- determinant in MathWorld
-- determinant in Wikipedia
+- determinant in MathWorld
+- determinant in Wikipedia
@@ -9993,27 +10347,23 @@
-| log_det_sympd( result, A ) | | (form 1) |
-| result = log_det_sympd( A ) | | (form 2) |
+| result = log_det_sympd( A ) | | (form 1) |
+| log_det_sympd( result, A ) | | (form 2) |
--
-Log determinant of symmetric positive definite matrix A
-
+- Log determinant of symmetric positive definite matrix A
--
-If A is not square sized, a std::logic_error exception is thrown
-
+- form 1: return the log determinant
-- form 1: store the calculated log determinant in result and return a bool indicating success
+- form 2: store the calculated log determinant in result and return a bool indicating success
-- form 2: return the log determinant
+- If A is not square sized, a std::logic_error exception is thrown
- If the log determinant cannot be found:
-- log_det_sympd(result, A) returns a bool set to false (exception is not thrown)
- result = log_det_sympd(A) throws a std::runtime_error exception
+- log_det_sympd(result, A) returns a bool set to false (exception is not thrown)
@@ -10025,10 +10375,10 @@
mat B = A.t() * A; // make symmetric matrix
-double result1;
-bool success = log_det_sympd(result1, B); // form 1
+double result1 = log_det_sympd(B); // form 1
-double result2 = log_det_sympd(B); // form 2
+double result2;
+bool success = log_det_sympd(result2, B); // form 2
@@ -10037,10 +10387,9 @@
See also:
@@ -10062,9 +10411,12 @@
-- Caveat: if matrix A is symmetric positive definite, using logmat_sympd() is faster
-
-- Caveat: the matrix logarithm operation is generally not the same as applying the log() function to each element
+- Caveats:
+
+- the matrix logarithm operation is generally not the same as applying the log() function to each element
+- if matrix A is symmetric positive definite, using logmat_sympd() is faster
+
+
-
Examples:
@@ -10108,10 +10460,10 @@
-- Caveat: the matrix logarithm operation is generally not the same as applying the log() function to each element
+- Caveat: the matrix logarithm operation is generally not the same as applying the log() function to each element
-
Examples:
@@ -10136,7 +10488,7 @@
- miscellaneous element-wise functions
- matrix logarithm in Wikipedia
- positive definite matrix in Wikipedia
-- positive definite matrix in MathWorld
+- positive definite matrix in MathWorld
@@ -10222,7 +10574,6 @@
- statistics functions
- running_stat - class for running statistics of scalars
- running_stat_vec - class for running statistics of vectors
-- ensmallen - library for finding minimum of arbitrary function
@@ -10275,6 +10626,7 @@
- find()
- unique()
- vectorise()
+
- .clean()
- .for_each()
@@ -10287,7 +10639,7 @@
norm( X, p )
-
-Compute the p-norm of X, where X can be a vector or matrix
+Compute the p-norm of X, where X is a vector or matrix
-
@@ -10295,11 +10647,11 @@
-
-For matrices, p is one of: 1, 2,
"inf", "fro"; the calculated norm is the induced norm (not entrywise norm)
+For matrices, p is one of: 1, 2, "inf", "fro"
-
-
"-inf" is the minimum norm, "inf" is the maximum norm, "fro" is the Frobenius norm
+"-inf" is the minimum quasi-norm, "inf" is the maximum norm, "fro" is the Frobenius norm
-
@@ -10311,8 +10663,12 @@
-
-To obtain the zero/Hamming pseudo-norm (the number of non-zero elements),
-use this expression:
accu(X != 0)
+Caveats:
+
+- to obtain the zero/Hamming pseudo-norm (the number of non-zero elements), use this expression:
accu(X != 0)
+- to obtain the vector norm of each row or column of a matrix, use vecnorm()
+- matrix 2-norm (spectral norm) is based on SVD, which is computationally intensive for large matrices; a possible alternative is norm2est()
+
-
@@ -10330,13 +10686,67 @@
-
See also:
+
+
+
+
+
+
+norm2est( X )
+
norm2est( X, tol )
+
norm2est( X, tol, max_iter )
+
+-
+Fast estimate of the 2-norm (spectral norm) of X, where X is a dense or sparse matrix
+
+
+-
+The estimate is found via an iterative algorithm which finishes when one of the following conditions is met:
+
+-
+the relative difference between two consecutive estimates is less than the specified tolerance,
+ie. |est1 - est2| / max(est1 , est2) < tol
+
+- the number of iterations is equal to max_iter
+
+
+
+-
+The optional argument tol specifies the tolerance for the relative difference; by default tol = 1e-6 is used
+
+
+-
+The optional argument max_iter specifies the maximum number of iterations; by default max_iter = 100 is used
+
+
+-
+Examples:
+
+mat X(2000, 3000, fill::randu);
+
+double x = norm2est(X);
+double y = norm2est(X, 1e-5);
+double z = norm2est(X, 1e-4, 10);
+
+
+
+
+-
+See also:
+
@@ -10383,44 +10793,64 @@
See also:
-
-prod( V )
-
prod( M )
-
prod( M, dim )
+
+
+
+| pow( A, scalar ) | | (form 1) |
+| pow( A, B ) | | (form 2) |
+| pow( M.each_col(), C ) | | (form 3) |
+| pow( M.each_row(), R ) | | (form 4) |
+| pow( Q.each_slice(), M ) | | (form 5) |
+
+
--
-For vector V, return the product of all elements
-
+- Element-wise power operations
--
-For matrix M, return the product of elements in each column (dim = 0), or each row (dim = 1)
-
+- form 1: raise all elements in A to the power denoted by the given scalar
--
-The dim argument is optional; by default dim = 0 is used
-
+- form 2: raise each element in A to the power denoted by the corresponding element in B;
+
the sizes of A and B must be the same
+
+- form 3: for each column vector of matrix M, raise each element to the power denoted by the corresponding element in column vector C;
+
the number of rows in M and C must be the same
+
+- form 4: for each row vector of matrix M, raise each element to the power denoted by the corresponding element in row vector R;
+
the number of columns in M and R must be the same
+
+- form 5: for each slice of cube Q, raise each element to the power denoted by the corresponding element in matrix M;
+
the number of rows and columns in Q and M must be the same
+
+- Caveats:
+
+- to raise all elements to the power 2, use square() instead
+- for the matrix power operation, which takes into account matrix structure, use powmat()
+
-
Examples:
-colvec v(10, fill::randu);
-double x = prod(v);
+mat A(5, 6, fill::randu);
+mat B(5, 6, fill::randu);
-mat M(10, 10, fill::randu);
+mat X = pow(A, 3.45);
+mat Y = pow(A, B);
-rowvec a = prod(M);
-rowvec b = prod(M,0);
-colvec c = prod(M,1);
+ vec C(5, fill::randu);
+rowvec R(6, fill::randu);
+
+mat Z1 = pow(A.each_col(), C);
+mat Z2 = pow(A.each_row(), R);
@@ -10428,8 +10858,11 @@
-
See also:
@@ -10461,10 +10894,10 @@
- Caveats:
+- the matrix power operation is generally not the same as applying the pow() function to each element
- to find the inverse of a matrix, use inv() instead
- to solve a system of linear equations, use solve() instead
- to find the matrix square root, use sqrtmat() instead
-- the matrix power operation is generally not the same as applying the pow() function to each element
-
@@ -10483,6 +10916,7 @@
-
See also:
-
-rank( X )
+
+prod( V )
+
prod( M )
+
prod( M, dim )
+
+-
+For vector V, return the product of all elements
+
+
+-
+For matrix M, return the product of elements in each column (dim = 0), or each row (dim = 1)
+
-rank( X, tolerance )
+-
+The dim argument is optional; by default dim = 0 is used
+
+
+-
+Examples:
-- Return the rank of matrix X, based on on singular value decomposition
+
+colvec v(10, fill::randu);
+double x = prod(v);
+
+mat M(10, 10, fill::randu);
+
+rowvec a = prod(M);
+rowvec b = prod(M,0);
+colvec c = prod(M,1);
+
+
+
+
+-
+See also:
+
+
+
+
+
+
+
+
+
+| r = rank( X ) | | (form 1) |
+| r = rank( X, tolerance ) | | |
+| | |
+| rank( r, X ) | | (form 2) |
+| rank( r, X, tolerance ) | | |
+
+
+
+- Calculate the rank of matrix X, based on singular value decomposition
+
+- form 1: return the rank
+
+- form 2: store the calculated rank in r and return a bool indicating success
- Any singular values less than tolerance are treated as zero
-
-The tolerance argument is optional; by default tolerance is max(m,n) · max_sv · datum::eps, where:
+The tolerance argument is optional; by default tolerance is set to max_rc · max_sv · epsilon, where:
-- m = number of rows and n = number of columns in X
+- max_rc = max(X.n_rows, X.n_cols)
- max_sv = maximum singular value of X
-- datum::eps = difference between 1 and the least value greater than 1 that is representable
+- epsilon = difference between 1 and the least value greater than 1 that is representable
-- If the decomposition fails, a std::runtime_error exception is thrown
-
--
-Caveat: to confirm whether a matrix is singular, use rcond() or cond()
+
- If the calculation fails:
+
+- r = rank(X) throws a std::runtime_error exception
+- rank(r,X) returns a bool set to false (exception is not thrown)
+
-
@@ -10528,7 +11017,10 @@
mat A(4, 5, fill::randu);
-uword r = rank(A);
+uword r1 = rank(A); // form 1
+
+uword r2;
+bool success = rank(r2, A); // form 2
@@ -10536,13 +11028,12 @@
-
See also:
@@ -10553,7 +11044,7 @@
rcond( A )
-
-Return the 1-norm estimate of the reciprocal of the condition number of square matrix A
+Return the 1-norm estimate of the reciprocal condition number of square matrix A
-
@@ -10706,15 +11197,14 @@
Caveats:
-
-do not use reshape() to change the size without preserving data;
-use .set_size() instead, which is much faster
+to change the size without preserving data, use .set_size() instead, which is much faster
-
to grow/shrink a matrix while preserving the elements as well as the layout of the elements,
use resize() instead
-
-to flatten a matrix into a vector, use vectorise() or .as_col() / .as_row() instead
+to flatten a matrix into a vector, use vectorise() or .as_col() / .as_row() instead
@@ -10764,8 +11254,7 @@
-
Caveat:
-do not use resize() to change the size without preserving data;
-use .set_size() instead, which is much faster
+to change the size without preserving data, use .set_size() instead, which is much faster
-
@@ -10973,7 +11462,8 @@
- shift()
- sort()
- unique()
-- randu() / randn()
+- randi()
+- randperm()
@@ -10985,32 +11475,37 @@
size( n_rows, n_cols )
-size( n_rows, n_cols, n_slices )
-
+size( n_rows, n_cols, n_slices )
+
+-
+Obtain the dimensions of object X, or explicitly specify the dimensions
+
+
+-
+Dimensions provided via size(...) can be used in conjunction with
+matrix constructors,
+submatrix views,
+random matrix generation,
+ind2sub(),
+sub2ind(),
+etc.
+
+
-
-Obtain the dimensions of object X, or explicitly specify the dimensions
+size(…) objects support simple arithmetic operations such as addition and multiplication
-
-The dimensions can be used in conjunction with:
-
+Two size(…) objects can be compared for equality/inequality
-
-The dimensions support simple arithmetic operations; they can also be printed and compared for equality/inequality
+size(…) objects can be passed to an std::ostream (eg. cout) via <<
-
Caveat: to prevent interference from std::size() in C++17,
-preface Armadillo's size() with the arma namespace qualification, eg. arma::size(X)
+preface Armadillo's size(…) with the arma namespace qualification, eg. arma::size(…)
-
@@ -11087,7 +11582,7 @@
- shuffle()
- unique()
- reverse()
-- randu() / randn()
+- randi()
@@ -11156,9 +11651,12 @@
If matrix A appears to be singular, an approximate square root is attempted; additionally, sqrtmat(B,A) returns a bool set to false
-- Caveat: if matrix A is symmetric positive definite, using sqrtmat_sympd() is faster
-
-- Caveat: the square root of a matrix is generally not the same as applying the sqrt() function to each element
+- Caveats:
+
+- the square root of a matrix is generally not the same as applying the sqrt() function to each element
+- if matrix A is symmetric positive definite, using sqrtmat_sympd() is faster
+
+
-
Examples:
@@ -11204,10 +11702,10 @@
-- Caveat: the matrix square root operation is generally not the same as applying the sqrt() function to each element
+- Caveat: the matrix square root operation is generally not the same as applying the sqrt() function to each element
-
Examples:
@@ -11233,7 +11731,7 @@
- miscellaneous element-wise functions
- square root of a matrix in Wikipedia
- positive definite matrix in Wikipedia
-- positive definite matrix in MathWorld
+- positive definite matrix in MathWorld
@@ -11317,7 +11815,7 @@
-
-The argument size(X) can be replaced with size(n_rows, n_cols) or size(n_rows, n_cols, n_slices)
+The argument size(X) can be replaced with size(n_rows, n_cols) or size(n_rows, n_cols, n_slices)
-
@@ -11395,7 +11893,7 @@
- trimatu() / trimatl()
- .is_symmetric()
- .is_hermitian()
-- Symmetric matrix in Wikipedia
+- Symmetric matrix in Wikipedia
@@ -11410,8 +11908,7 @@
-
-If X is an expression,
-the function aims to use optimised expression evaluations to calculate only the diagonal elements
+If X is an expression, the evaluation of the expression aims to calculate only the diagonal elements
-
@@ -11432,6 +11929,7 @@
- as_scalar()
- .diag()
- diagvec()
+- diagmat()
- sum()
@@ -11523,11 +12021,11 @@
- See also:
@@ -11592,8 +12090,8 @@
- symmatu() / symmatl()
- diagmat()
- nonzeros()
-- Triangular matrix in MathWorld
-- Triangular matrix in Wikipedia
+- Triangular matrix in MathWorld
+- Triangular matrix in Wikipedia
@@ -11710,6 +12208,53 @@
+
+vecnorm( X )
+
vecnorm( X, p )
+
vecnorm( X, p, dim )
+
+-
+Compute the p-norm of each column vector (dim = 0) or row vector (dim = 1) of matrix X
+
+
+-
+p is an integer ≥ 1, or
"-inf" (minimum quasi-norm), or "inf" (maximum norm)
+
+
+-
+The arguments p and dim are optional; by default p = 2 and dim = 0 are used
+
+
+-
+Caveat: to compute the matrix norm, use norm() instead
+
+
+-
+Examples:
+
+mat X(4, 5, fill::randu);
+
+rowvec r = vecnorm(X, 2);
+
+colvec c = vecnorm(X, "inf", 1);
+
+
+
+
+-
+See also:
+
+
+
+
+
+
vectorise( X )
vectorise( X, dim )
@@ -11754,6 +12299,7 @@
See also:
- .as_col() / .as_row()
+- .col_as_mat() / .row_as_mat()
- nonzeros()
- reshape()
- resize()
@@ -11769,9 +12315,9 @@
miscellaneous element-wise functions:
-| exp | | log | | pow | | floor | | erf | | tgamma | | sign |
-| exp2 | | log2 | | square | | ceil | | erfc | | lgamma | | |
-| exp10 | | log10 | | sqrt | | round | | | | | | |
+| exp | | log | | square | | floor | | erf | | tgamma | | sign |
+| exp2 | | log2 | | sqrt | | ceil | | erfc | | lgamma | | |
+| exp10 | | log10 | | | | round | | | | | | |
| expm1 | | log1p | | | | trunc | | | | | | |
| trunc_exp | | trunc_log | | | | | | | | | | |
@@ -11823,7 +12369,7 @@
base-10 exponential: 10 x
-
+
expm1(A)
|
@@ -11834,7 +12380,7 @@
compute exp(A)-1 accurately for values of A close to zero (only for float and double elements)
-
+
trunc_exp(A)
|
@@ -11846,7 +12392,7 @@
truncated to avoid infinity (only for float and double elements)
-
+
log(A)
|
@@ -11857,7 +12403,7 @@
natural log: loge x
-
+
log2(A)
|
@@ -11868,7 +12414,7 @@
base-2 log: log2 x
-
+
log10(A)
|
@@ -11904,17 +12450,6 @@
- pow(A, p)
- |
-
-
- |
-
- raise to the power of p: x p
- |
-
-
-
square(A)
|
@@ -12001,7 +12536,7 @@
complementary error function (only for float and double elements)
|
-
+
tgamma(A)
|
@@ -12012,7 +12547,7 @@
gamma function (only for float and double elements)
-
+
lgamma(A)
|
@@ -12023,7 +12558,7 @@
natural log of the absolute value of gamma function (only for float and double elements)
-
+
sign(A)
|
@@ -12054,8 +12589,8 @@
- all of the above functions are applied element-wise, where each element is treated independently
-
-the element-wise functions exp(), log(), sqrt() and pow()
-have the corresponding functions expmat(), logmat(), sqrtmat() and powmat() which take into account matrix structure
+the element-wise functions exp(), log() and sqrt()
+have the corresponding functions expmat(), logmat() and sqrtmat() which take into account matrix structure
@@ -12074,6 +12609,7 @@
See also:
- abs()
+- pow()
- clamp()
- conj()
- imag() / real()
@@ -12081,7 +12617,6 @@
- expmat()
- logmat()
- sqrtmat()
-- powmat()
- trigonometric functions
- statistics functions
- miscellaneous constants
@@ -12158,14 +12693,14 @@
-| R = chol( X ) | | (form 1) |
-| R = chol( X, layout ) | | (form 2) |
+| R = chol( X ) | | (form 1) |
+| R = chol( X, layout ) | | (form 2) |
| | | |
-| chol( R, X ) | | (form 3) |
-| chol( R, X, layout ) | | (form 4) |
+| chol( R, X ) | | (form 3) |
+| chol( R, X, layout ) | | (form 4) |
| | | |
-| chol( R, P, X, layout, "vector" ) | | (form 5) |
-| chol( R, P, X, layout, "matrix" ) | | (form 6) |
+| chol( R, P, X, layout, "vector" ) | | (form 5) |
+| chol( R, P, X, layout, "matrix" ) | | (form 6) |
@@ -12406,8 +12943,8 @@
- svd_econ()
- schur()
- eigs_gen()
-- eigen decomposition in MathWorld
-- eigenvalues & eigenvectors in Wikipedia
+- eigen decomposition in MathWorld
+- eigenvalues & eigenvectors in Wikipedia
@@ -12466,8 +13003,8 @@
- eig_gen()
- eig_sym()
- qz()
-- eigen decomposition in MathWorld
-- eigenvalues & eigenvectors in Wikipedia
+- eigen decomposition in MathWorld
+- eigenvalues & eigenvectors in Wikipedia
@@ -12520,7 +13057,7 @@
@@ -12530,12 +13067,37 @@
B = inv( A )
+
B = inv( A, settings )
+
inv( B, A )
+
inv( B, A, settings )
+
+
inv( B, rcond, A )
-
Inverse of general square matrix A
+- The settings argument is optional; it is one of the following:
+
+
+
+
+inv_opts::no_ugly | | do not provide inverses for poorly conditioned matrices (where rcond < A.n_rows · datum::eps) |
+inv_opts::allow_approx | | allow approximate inverses for rank deficient or poorly conditioned matrices |
+inv_opts::tiny | | use fast inverse algorithm for tiny matrices (with size ≤ 4x4); may produce lower quality inverses |
+
+
+
+
+-
+The reciprocal condition number is optionally calculated and stored in rcond
+
+- rcond close to 1 suggests that A is well-conditioned
+- rcond close to 0 suggests that A is badly conditioned
+
+
+
-
If A is not square sized, a std::logic_error exception is thrown
@@ -12544,6 +13106,7 @@
- B = inv(A) resets B and throws a std::runtime_error exception
- inv(B,A) resets B and returns a bool set to false (exception is not thrown)
+- inv(B,rcond,A) resets B, sets rcond to zero, and returns a bool set to false (exception is not thrown)
@@ -12564,6 +13127,17 @@
mat A(5, 5, fill::randu);
mat B = inv(A);
+
+mat C;
+bool success = inv(C, A);
+
+mat D;
+double rcond_val;
+inv(D, rcond_val, A);
+
+A.col(1).zeros();
+mat E;
+inv(E, A, inv_opts::allow_approx);
@@ -12580,8 +13154,8 @@
- diagmat()
- trimatu() / trimatl()
- powmat()
-- matrix inverse in MathWorld
-- invertible matrix in Wikipedia
+- matrix inverse in MathWorld
+- invertible matrix in Wikipedia
@@ -12590,12 +13164,37 @@
B = inv_sympd( A )
+
B = inv_sympd( A, settings )
+
inv_sympd( B, A )
+
inv_sympd( B, A, settings )
+
+
inv_sympd( B, rcond, A )
-
Inverse of symmetric/hermitian positive definite matrix A
+- The settings argument is optional; it is one of the following:
+
+
+
+
+inv_opts::no_ugly | | do not provide inverses for poorly conditioned matrices (where rcond < A.n_rows · datum::eps) |
+inv_opts::allow_approx | | allow approximate inverses for rank deficient or poorly conditioned symmetric matrices |
+inv_opts::tiny | | use fast inverse algorithm for tiny matrices (with size ≤ 4x4); may produce lower quality inverses |
+
+
+
+
+-
+The reciprocal condition number is optionally calculated and stored in rcond
+
+- rcond close to 1 suggests that A is well-conditioned
+- rcond close to 0 suggests that A is badly conditioned
+
+
+
-
If A is not square sized, a std::logic_error exception is thrown
@@ -12604,6 +13203,7 @@
- B = inv_sympd(A) resets B and throws a std::runtime_error exception
- inv_sympd(B,A) resets B and returns a bool set to false (exception is not thrown)
+- inv_sympd(B,rcond,A) resets B, sets rcond to zero, and returns a bool set to false (exception is not thrown)
+shift-invert mode in ARPACK
+- eigen decomposition in MathWorld
+- eigenvalues & eigenvectors in Wikipedia
@@ -13690,6 +14319,11 @@
-
+NOTE: the implementation in Armadillo 12.6 is considerably faster than earlier versions;
+further speedups can be obtained by enabling OpenMP in your compiler (eg. -fopenmp in GCC and clang)
+
+
+-
Examples:
@@ -13716,8 +14350,101 @@
- eig_gen()
- svds()
- shift-invert mode in ARPACK
-- eigen decomposition in MathWorld
-- eigenvalues & eigenvectors in Wikipedia
+- eigen decomposition in MathWorld
+- eigenvalues & eigenvectors in Wikipedia
+
+
+
+
+
+
+
+vec s = svds( X, k )
+
vec s = svds( X, k, tol )
+
+
svds( vec s, X, k )
+
svds( vec s, X, k, tol )
+
+
svds( mat U, vec s, mat V, sp_mat X, k )
+
svds( mat U, vec s, mat V, sp_mat X, k, tol )
+
+
svds( cx_mat U, vec s, cx_mat V, sp_cx_mat X, k )
+
svds( cx_mat U, vec s, cx_mat V, sp_cx_mat X, k, tol )
+
+-
+Obtain a limited number of singular values and singular vectors (truncated SVD) of sparse matrix X
+
+
+-
+The singular values and vectors are calculated via sparse eigen decomposition of:
+
+
+
+| ⎡ | zeros(X.n_rows, X.n_rows) | | X | ⎤ |
+| ⎣ | X.t() | | zeros(X.n_cols, X.n_cols) | ⎦ |
+
+
+
+
+
+-
+k specifies the number of singular values and singular vectors
+
+
+-
+The singular values are in descending order
+
+
+-
+The argument tol is optional; it specifies the tolerance for convergence;
+it is passed as (tol ÷ √2) to eigs_sym()
+
+
+-
+If the decomposition fails, the output objects are reset and:
+
+- s = svds(X,k) resets s and throws a std::runtime_error exception
+- svds(s,X,k) resets s and returns a bool set to false (exception is not thrown)
+- svds(U,s,V,X,k) resets U, s, V and returns a bool set to false (exception is not thrown)
+
+
+
+-
+Caveats:
+
+-
+svds() is intended only for finding a few singular values from a large sparse matrix;
+to find all singular values, use svd() instead
+
+-
+depending on the given matrix, svds() may find fewer singular values than specified
+
+
+
+
+-
+Examples:
+
+sp_mat X = sprandu<sp_mat>(100, 200, 0.1);
+
+mat U;
+vec s;
+mat V;
+
+svds(U, s, V, X, 10);
+
+
+
+
+-
+See also:
+
@@ -13754,10 +14481,10 @@
The solver argument is optional; solver is either "superlu" or "lapack"; by default "superlu" is used
-
-For
"superlu", ARMA_USE_SUPERLU must be enabled in config.hpp
+for "superlu", ARMA_USE_SUPERLU must be enabled in config.hpp
-
-For
"lapack", sparse matrix A is converted to a dense matrix before using the LAPACK solver; this considerably increases memory usage
+for "lapack", sparse matrix A is converted to a dense matrix before using the LAPACK solver; this considerably increases memory usage
@@ -13765,8 +14492,9 @@
-
Notes:
-- The SuperLU solver is mainly useful for very large and/or very sparse matrices
-- If there is sufficient amount of memory to store a dense version of matrix A, the LAPACK solver can be faster
+- the SuperLU solver is mainly useful for very large and/or very sparse matrices
+- to reuse the SuperLU factorisation of A for finding solutions where B is iteratively changed, see the spsolve_factoriser class
+- if there is sufficient amount of memory to store a dense version of matrix A, the LAPACK solver can be faster
@@ -13862,92 +14590,113 @@
-
See also:
-
-
-vec s = svds( X, k )
-
vec s = svds( X, k, tol )
-
-
svds( vec s, X, k )
-
svds( vec s, X, k, tol )
-
-
svds( mat U, vec s, mat V, sp_mat X, k )
-
svds( mat U, vec s, mat V, sp_mat X, k, tol )
-
-
svds( cx_mat U, vec s, cx_mat V, sp_cx_mat X, k )
-
svds( cx_mat U, vec s, cx_mat V, sp_cx_mat X, k, tol )
-
--
-Obtain a limited number of singular values and singular vectors (truncated SVD) of sparse matrix X
-
-
--
-The singular values and vectors are calculated via sparse eigen decomposition of:
-
-
-
-| ⎡ | zeros(X.n_rows, X.n_rows) | | X | ⎤ |
-| ⎣ | X.t() | | zeros(X.n_cols, X.n_cols) | ⎦ |
-
-
-
-
+
+
+spsolve_factoriser
+
-
-k specifies the number of singular values and singular vectors
+Class for factorisation of sparse matrix A for solving systems of linear equations in the form A*X = B
-
-The singular values are in descending order
+Allows the SuperLU factorisation of A to be reused for finding solutions in cases where B is iteratively changed
-
-The argument tol is optional; it specifies the tolerance for convergence;
-it is passed as (tol ÷ √2) to eigs_sym()
-
+For an instance of spsolve_factoriser named as SF, the member functions are:
+
--
-If the decomposition fails, the output objects are reset and:
-- s = svds(X,k) resets s and throws a std::runtime_error exception
-- svds(s,X,k) resets s and returns a bool set to false (exception is not thrown)
-- svds(U,s,V,X,k) resets U, s, V and returns a bool set to false (exception is not thrown)
-
+SF.factorise(A)
+
+SF.factorise(A, opts)
+
+-
+factorise square-sized sparse matrix A
+
+-
+optional settings are given in the opts argument as per the spsolve() function
+- if the factorisation fails, a bool set to false is returned
+
+SF.solve(X, B)
+
-
-Caveats:
+using the given dense matrix B and the computed factorisation,
+store in X the solution to A*X = B
+
+- if computing the solution fails, X is reset and a bool set to false is returned
+
+
+SF.rcond()
-
-svds() is intended only for finding a few singular values from a large sparse matrix;
-to find all singular values, use svd() instead
+return the 1-norm estimate of the reciprocal condition number computed during the factorisation
+
+ -
+ values close to 1 suggest that the factorised matrix is well-conditioned
+
+ -
+ values close to 0 suggest that the factorised matrix is badly conditioned
+
+
+
+
+SF.reset()
+
-
-depending on the given matrix, svds() may find fewer singular values than specified
+reset the instance and release all memory related to the stored factorisation;
+this is automatically done when the instance goes out of scope
+
+
+- Notes:
+
+- if the factorisation of A does not need to be reused, use spsolve() instead
+- this class internally uses the SuperLU solver; ARMA_USE_SUPERLU must be enabled in config.hpp
+
-
Examples:
-sp_mat X = sprandu<sp_mat>(100, 200, 0.1);
+sp_mat A = sprandu<sp_mat>(1000, 1000, 0.1);
-mat U;
-vec s;
-mat V;
+spsolve_factoriser SF;
-svds(U, s, V, X, 10);
+bool status = SF.factorise(A);
+
+if(status == false) { cout << "factorisation failed" << endl; }
+
+double rcond_value = SF.rcond();
+
+vec B1(1000, fill::randu);
+vec B2(1000, fill::randu);
+
+vec X1;
+vec X2;
+
+bool solution1_ok = SF.solve(X1,B1);
+bool solution2_ok = SF.solve(X2,B2);
+
+if(solution1_ok == false) { cout << "couldn't find X1" << endl; }
+if(solution2_ok == false) { cout << "couldn't find X2" << endl; }
@@ -13955,11 +14704,9 @@
-
See also:
@@ -14031,9 +14778,9 @@
- fft()
- cor()
- interp1()
-- Convolution in MathWorld
-- Convolution in Wikipedia
-- FIR filter in Wikipedia
+- Convolution in MathWorld
+- Convolution in Wikipedia
+- FIR filter in Wikipedia
@@ -14062,7 +14809,7 @@
-- The implementation of 2D convolution in this version is preliminary; it is not yet fully optimised
+- The implementation of 2D convolution in this version is preliminary
-
Examples:
@@ -14085,9 +14832,9 @@
- conv()
- fft2()
- interp2()
-- Convolution in MathWorld
-- Convolution in Wikipedia
-- Kernel (image processing) in Wikipedia
+- Convolution in MathWorld
+- Convolution in Wikipedia
+- Kernel (image processing) in Wikipedia
@@ -14121,7 +14868,23 @@
- Caveat: the transform is fastest when the transform length is a power of 2, eg. 64, 128, 256, 512, 1024, ...
-- The implementation of the transform in this version is preliminary; it is not yet fully optimised
+-
+By default, an internal FFT algorithm based on KISS FFT is used
+
+
+-
+Since Armadillo 12.0, the FFTW3 library can be optionally used for faster execution, as follows:
+
+- ARMA_USE_FFTW3 must be defined before including the armadillo header:
+
+
+#define ARMA_USE_FFTW3
+
#include <armadillo>
+
+
+- you will also need to link with the FFTW3 runtime library (eg.
-lfftw3)
+
+
-
Examples:
@@ -14140,8 +14903,8 @@
- fft2()
- conv()
- real()
-- fast Fourier transform in MathWorld
-- fast Fourier transform in Wikipedia
+- fast Fourier transform in MathWorld
+- fast Fourier transform in Wikipedia
@@ -14166,7 +14929,7 @@
- Caveat: the transform is fastest when both n_rows and n_cols are a power of 2, eg. 64, 128, 256, 512, 1024, ...
-- The implementation of the transform in this version is preliminary; it is not yet fully optimised
+- The implementation of the 2D transform in this version is preliminary
-
Examples:
@@ -14186,8 +14949,8 @@
- fft()
- conv2()
- real()
-- fast Fourier transform in MathWorld
-- fast Fourier transform in Wikipedia
+- fast Fourier transform in MathWorld
+- fast Fourier transform in Wikipedia
@@ -14417,7 +15180,7 @@
- polynomial in Wikipedia
- least squares in Wikipedia
- curve fitting in Wikipedia
-- least squares fitting in MathWorld
+- least squares fitting in MathWorld
@@ -14692,9 +15455,21 @@
-
-The default norm_type = 0 performs normalisation using N-1 (where N is the number of observations),
-providing the best unbiased estimation of the covariance matrix (if the observations are from a normal distribution).
-Using norm_type = 1 causes normalisation to be done using N, which provides the second moment matrix of the observations about their mean
+The norm_type argument is optional; by default norm_type = 0 is used
+
+
+-
+the norm_type argument controls the type of normalisation used, with N denoting the number of observations:
+
+-
+for norm_type = 0, normalisation is done using N-1,
+providing the best unbiased estimation of the covariance matrix (if the observations are from a normal distribution)
+
+-
+for norm_type = 1, normalisation is done using N,
+which provides the second moment matrix of the observations about their mean
+
+
-
@@ -14716,7 +15491,7 @@
- cor()
- statistics functions
- running_stat_vec
-- Covariance in MathWorld
+- Covariance in MathWorld
@@ -14753,8 +15528,15 @@
-
-The default norm_type = 0 performs normalisation of the correlation matrix using N-1 (where N is the number of observations).
-Using norm_type = 1 causes normalisation to be done using N
+The norm_type argument is optional; by default norm_type = 0 is used
+
+
+-
+the norm_type argument controls the type of normalisation used, with N denoting the number of observations:
+
+- for norm_type = 0, normalisation is done using N-1
+- for norm_type = 1, normalisation is done using N
+
-
@@ -14777,8 +15559,8 @@
- conv()
- statistics functions
- running_stat_vec
-- Correlation in MathWorld
-- Autocorrelation in MathWorld
+- Correlation in MathWorld
+- Autocorrelation in MathWorld
@@ -14917,8 +15699,8 @@
Rob J. Hyndman and Yanan Fan.
Sample Quantiles in Statistical Packages.
-The American Statistician, Vol. 50, No. 4, pp. 361-365, 1996.
-http://doi.org/10.2307/2684934
+The American Statistician, 50(4), 361-365, 1996.
+DOI: 10.2307/2684934
-
@@ -15006,7 +15788,7 @@
- eig_sym()
- svd()
- svd_econ()
-- principal components analysis in Wikipedia
+- principal components analysis in Wikipedia
@@ -15072,9 +15854,9 @@
@@ -15150,7 +15932,7 @@
@@ -15193,8 +15975,8 @@
@@ -15249,7 +16031,7 @@
-
See also:
@@ -15975,7 +16757,7 @@
-
-Internal implementation details are available in the following paper:
+Mathematical implementation details are available in the following paper:
@@ -16612,7 +17394,7 @@
-constants (pi, inf, speed of light, ...)
+constants (pi, inf, eps, ...)
|