diff --git a/docs.html b/docs.html
index c82bd900..b5a60296 100644
--- a/docs.html
+++ b/docs.html
@@ -150,7 +150,7 @@ hr.greyline
[top]
-API Documentation for Armadillo 12.2
+API Documentation for Armadillo 12.4
@@ -413,37 +413,39 @@ Conrad Sanderson and Ryan Curtin.
| min / max | | return extremum values |
| nonzeros | | return non-zero values |
| norm | | various norms of vectors and matrices |
-| normalise | | normalise vectors to unit p-norm |
+| norm2est | | fast estimate of the matrix 2-norm |
+| normalise | | normalise vectors to unit p-norm |
| pow | | element-wise power |
| powmat | | matrix power |
-| prod | | product of elements |
+| prod | | product of elements |
| rank | | rank of matrix |
| rcond | | reciprocal condition number |
-| repelem | | replicate elements |
+| repelem | | replicate elements |
| repmat | | replicate matrix in block-like fashion |
| reshape | | change size while keeping elements |
-| resize | | change size while keeping elements and preserving layout |
+| resize | | change size while keeping elements and preserving layout |
| reverse | | reverse order of elements |
| roots | | roots of polynomial |
-| shift | | shift elements |
+| shift | | shift elements |
| shuffle | | randomly shuffle elements |
| size | | obtain dimensions of given object |
-| sort | | sort elements |
+| sort | | sort elements |
| sort_index | | vector describing sorted order of elements |
| sqrtmat | | square root of matrix |
-| sqrtmat_sympd | | square root of symmetric matrix |
+| sqrtmat_sympd | | square root of symmetric matrix |
| sum | | sum of elements |
| sub2ind | | convert subscripts to linear index |
-| symmatu / symmatl | | generate symmetric matrix from given matrix |
+| symmatu / symmatl | | generate symmetric matrix from given matrix |
| trace | | sum of diagonal elements |
| trans | | transpose of matrix |
-| trapz | | trapezoidal numerical integration |
+| trapz | | trapezoidal numerical integration |
| trimatu / trimatl | | copy upper/lower triangular part |
| trimatu_ind / trimatl_ind | | obtain indices of upper/lower triangular part |
-| unique | | return unique elements |
+| unique | | return unique elements |
+| vecnorm | | obtain vector norm of each row or column of a matrix |
| vectorise | | flatten matrix into vector |
-| misc functions | | miscellaneous element-wise functions: exp, log, sqrt, round, sign, ... |
-| trig functions | | trigonometric element-wise functions: cos, sin, tan, ... |
+| misc functions | | miscellaneous element-wise functions: exp, log, sqrt, round, sign, ... |
+| trig functions | | trigonometric element-wise functions: cos, sin, tan, ... |
@@ -2106,8 +2108,8 @@ The following subset of operations & functions is available for sparse matri
diagonal views
saving and loading (using arma_binary, coord_ascii, and csv_ascii formats)
element-wise functions: abs(), ceil(), conj(), floor(), imag(), real(), round(), sign(), sqrt(), square(), trunc()
-scalar functions of matrices: accu(), as_scalar(), dot(), norm(), trace()
-vector valued functions of matrices: diagvec(), min(), max(), nonzeros(), sum(), mean(), var(), vectorise()
+scalar functions of matrices: accu(), as_scalar(), dot(), norm(), norm2est(), trace()
+vector valued functions of matrices: diagvec(), min(), max(), nonzeros(), sum(), mean(), var(), vecnorm(), vectorise()
matrix valued functions of matrices: clamp(), diagmat(), flipud()/fliplr(), join_rows(), join_cols(), kron(), normalise(), repelem(), repmat(), reshape(), resize(), reverse(), symmatu()/symmatl(), trimatu()/trimatl(), .t(), trans()
generated matrices: speye(), spones(), sprandu(), sprandn(), zeros()
eigen and svd decomposition: eigs_sym(), eigs_gen(), svds()
@@ -10565,7 +10567,7 @@ See also:
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
-
@@ -10577,7 +10579,7 @@ 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
-
@@ -10589,8 +10591,12 @@ For vector norm with p = 2 and matrix norm with p&thinsp
-
-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()
+
-
@@ -10608,8 +10614,9 @@ double y = norm(q, "inf");
-
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:
+
+
+
+
+
normalise( V )
@@ -10661,6 +10721,7 @@ mat Z = normalise(X, 2, 1);
See also:
+
+
+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 )
@@ -19872,6 +19980,14 @@ List of additions and changes for each version:
+
+Version 12.4:
+
+- added norm2est() for finding fast estimates of matrix 2-norm (spectral norm)
+- added vecnorm()for obtaing the norm of each row or column vector in a matrix
+
+
+
Version 12.2: