Mentions légales du service

Skip to content
Snippets Groups Projects
Commit 8ac1653d authored by hhakim's avatar hhakim
Browse files

Update matfaust.fact.eigtj/svdtj doc (Rémi's review).

parent 8ce1ba87
No related branches found
No related tags found
No related merge requests found
Pipeline #833896 skipped
......@@ -82,7 +82,7 @@ void Faust::svdtj_core(MatGeneric<FPP,DEVICE>* M, MatDense<FPP,DEVICE> &dM, MatD
S.getData()[i] = W1_MW2(i,i);
}
// order D descendantly according to the abs value
// sort D in descending order according to the abs value
// and change the sign when the value is negative
// it gives a signed permutation matrix P to append to W1, abs(P2) is append to W2
vector<int> ord_indices;
......
%==========================================================================================
%> @brief Performs an approximate eigendecomposition of M and returns the eigenvalues in D along with the corresponding left eigenvectors (as the columns of the Faust object V).
%> @brief Performs an approximate eigendecomposition of M and returns the eigenvalues in D along with the corresponding normalized right eigenvectors (as the columns of the Faust object V).
%>
%> The output is such that <code>V*D*V'</code> approximates M. V is a product of Givens rotations obtained by truncating the Jacobi algorithm.
%>
%> The trade-off between accuracy and sparsity of V can be set through the parameters nGivens and nGivens_per_fac or concurrently with the arguments tol and relerr that define the targeted error.
%> The trade-off between accuracy and complexity of V can be set through the parameters nGivens and tol that define the targeted number of Givens rotations and targeted error.
%>
%>
%> @b Usage
%>
%> &nbsp;&nbsp;&nbsp; <b>[V,D] = eigtj(M, 'nGivens', n)</b> computes V with n Givens rotations grouped into factors containing ideally <code>m = floor(size(M,1)/2)</code> Givens rotation each (if m doesn't divide n, the first factor at least contains less than m rotations).<br/>
%> &nbsp;&nbsp;&nbsp; @b eigtj(M, 'nGivens', n, 'nGivens_per_fac', 1) does the same as in previous line but limiting to 1 the number of Givens rotation per factor. Setting nGivens_per_fac to 0 produces the same results. <br/>
%> &nbsp;&nbsp;&nbsp; @b eigtj(M, 'nGivens', n, 'nGivens_per_fac', t) as above but with t Givens rotatons per factor.<br/>
%> &nbsp;&nbsp;&nbsp; @b eigtj(M, 'nGivens', n, 'nGivens_per_fac', t, 'verbosity', 2) same as above with a level of output verbosity of 2. <br/>
%> &nbsp;&nbsp;&nbsp; @b eigtj(M, 'nGivens', n, 'nGivens_per_fac', t, 'tol', 0.01, 'relerr', true) Uses a stopping criterion based on relative error <code>norm(V*D*V'-M, 'fro')/norm(M, 'fro')</code>. This criterion is concurrent to nGivens (here n).<br/>
%> &nbsp;&nbsp;&nbsp; @b eigtj(M, 'nGivens', n, 'nGivens_per_fac', t, 'tol', 0.01, 'relerr', true) Uses a stopping criterion based on absolute error <code>norm(V*D*V'-M, 'fro')</code>. This criterion is concurrent to nGivens (here n).<br/>
%> &nbsp;&nbsp;&nbsp; Primary examples of calls include:<br/>
%> &nbsp;&nbsp;&nbsp; <b>[V,D] = eigtj(M, 'nGivens', n)</b> outputs V as a Faust object made of n elementary Givens rotations grouped into factors containing ideally <code>m = floor(size(M,1)/2)</code> such Givens rotations, and the diagonal entries of D are the approximate eigenvalues in ascending order.<br/>
%>&nbsp;&nbsp;&nbsp; <b>[V,D] = eigtj(M,’tol’,0.01)</b> same as above with n determined adaptively by a relative approximation error 0.01.<br/>
%>&nbsp;&nbsp;&nbsp; <b>[V,D] = eigtj(M,’tol’,0.01)</b> same as above with n determined adaptively by a relative approximation error 0.01.<br/>
%>&nbsp;&nbsp;&nbsp; <b>[V,D] = eigtj(M,’tol’,0.01,’relerr’,False)</b> same as above with an absolute approximation error.<br/>
%>&nbsp;&nbsp;&nbsp; <b>[V,D] = eigtj(M,’nGivens’,n,’tol’,0.01)</b> same as above with a number of elementary Givens bounded by n even if the targeted approximation error is not achieved.<br/>
%>&nbsp;&nbsp;&nbsp; <b>[V,D]= eigtj(M,’nGivens’,n,’tol’,0.01,’nGivens_per_fac’,t)</b> same as above with (up to) t Givens rotations per factor.<br/>
%>&nbsp;&nbsp;&nbsp; <b>[V,D]= eigtj(M,’nGivens’,n,’order’,’descend’) </b> same as above where the diagonal entries of D are the approximate eigenvalues in descending order (and with columns of V permuted accordingly).<br/>
%>&nbsp;&nbsp;&nbsp; <b>eigtj(M, 'nGivens', n, 'nGivens_per_fac', t, 'tol', 0.01, 'relerr', true)</b> uses a stopping criterion based on absolute error norm(V*D*V'-M, 'fro'). This criterion is concurrent to nGivens (here n).<br/>
%>
%> @param M the matrix to diagonalize. Must be real and symmetric, or complex hermitian. Can be in dense or sparse format.
%> @param nGivens, integer (optional if tol is set) the maximum number of iterations which is defined by the
%> number of Givens rotations that can be computed in eigenvector transform V.
%> @param nGivens, integer [optional if tol is set] targeted number of Givens rotations.
%> The number of rotations per factor of V is defined by nGivens_per_fac.
%> @param 'tol', number (optional if nGivens is set) the tolerance error at which the algorithm stops. By default, it's zero for not stopping on an error criterion. Note that the error reaching is not guaranteed (in particular, if the error starts to increase from one iteration to another then the algorithm is stopped).
%> @param 'order', char (optional) 'descend' for a descending order of eigenvalues, 'ascend' for an ascending order (default value) or 'undef' for no sort.
%> @param 'nGivens_per_fac', integer (optional) the number of Givens rotations per factor of V, must be an integer between 1 to <code>floor(size(M, 1)/2)</code> which is the default value.
%> @param 'relerr', true (optional) For a stopping criterion based on the relative error (this is the default error).
%> @param 'relerr', false (optional) For a stopping criterion based on the absolute error.
%> @param 'verbosity', integer (optional) the level of verbosity, the greater the value the more info is displayed. It can be helpful to understand for example why the algorithm stopped before reaching the tol error or the number of Givens (nGivens).
%> @param 'tol', number [optional if nGivens is set] the tolerance error at which the algorithm stops. The default value is zero so that stopping is based on reaching the targeted nGivens.
%> @param 'order', char [optional, default is ‘ascend’] order of eigenvalues, possible choices are ‘ascend, 'descend' or 'undef' (to avoid a sorting operation and save some time).
%> @param 'nGivens_per_fac', integer [optional, default is <code>floor(size(M, 1)/2)</code>] targeted number of Givens rotations per factor of V. Must be an integer between 1 to <code>floor(size(M, 1)/2)</code>.
%> @param 'relerr', bool [optional, default is True] the type of error used as stopping criterion. (true) for the relative error norm(V*D*V'-M, 'fro')/norm(M, 'fro'), (false) for the absolute error norm(V*D*V'-M, 'fro').
%> @param 'verbosity', integer [optional] verbosity level. The greater the value the more info is displayed. It can be helpful to understand for example why the algorithm stopped before reaching the tol error or the number of Givens (nGivens).
%>
%>
%> @retval [V,D]
%> - V the Faust object representing the approximate eigenvector transform. The column <code>V(:, i)</code> is the eigenvector corresponding to the eigenvalue <code>D(i,i)</code>.
%> - D the sparse diagonal matrix of the approximate eigenvalues (by default in ascendant order along the rows/columns).
%> - D the sparse (real) diagonal matrix of the approximate eigenvalues (by default in ascending order along the diagonal).
%>
%> @note
%> - When ‘nGivens’ and ‘tol’ are used simultaneously, the number of Givens rotations in V may be smaller than specified by ‘nGivens’ if the error criterion is met first, and the achieved error may be larger than specified if ‘nGivens’ is reached first during the iterations of the truncated Jacobi algorithm.
%> @note
%> - When nGivens_per_fac > 1, all factors have exactly nGivens_per_fac except the leftmost one which may have fewer if the total number of Givens rotations is not a multiple of nGivens_per_fact
%>
%>
%> @b Example
%> @code
......
......@@ -2,24 +2,27 @@
%> @brief Performs an approximate singular value decomposition and returns the left and
%> right singular vectors as Faust transforms.
%>
%> @note this function is based on fact.eigtj which relies on the truncated Jacobi algorithm, hence the 'tj' in the name.
%> @note this function is based on fact.eigtj which relies on the truncated Jacobi algorithm, hence the 'tj' in the name. See below the example for further details on how svdtj is defined using eigtj.
%>
%> @b Usage
%>
%> &nbsp;&nbsp;&nbsp; @b [U,S,V] = svdtj(M, varargin). See below for further details on how svdtj is defined using eigtj.<br/>
%%>
%> &nbsp;&nbsp;&nbsp; @b Primary examples of calls include:<br/>
%> &nbsp;&nbsp;&nbsp; @b <b>[U,S,V] = svdtj(M, ‘nGivens’,n) </b> outputs U,V as Faust objects made of n elementary Givens rotations grouped into factors. By default each factor gathers (up to) m = floor(size(M,1)/2) such rotations. By default vector S contains the approximate singular values in descending order.<br/>
%> &nbsp;&nbsp;&nbsp; @b <b>[U,S,V] = svdtj(M,’tol’,0.01)</b> same as above with n determined adaptively by a relative approximation error 0.01<br/>
%> &nbsp;&nbsp;&nbsp; @b <b>[U,S,V] = svdtj(M,’tol’,0.01,’relerr’,false)</b> same as above with an absolute approximation error<br/>
%> &nbsp;&nbsp;&nbsp; @b <b>[U,S,V] = svdtj(M,’nGivens’,n,’tol’,0.01)</b> same as above with a number of elementary Givens bounded by n even if the targeted approximation error is not achieved<br/>
%> &nbsp;&nbsp;&nbsp; @b <b>[U,S,V] = svdtj(M,’nGivens’,n,’tol’,0.01,’nGivens_per_fac’,t) </b>same as above with (up to) t Givens rotations per factor<br/>
%>
%>
%> @param M: a real or complex, dense or sparse matrix.
%> @param nGivens, integer: see fact.eigtj
%> @param 'nGivens_per_fac',integer see fact.eigtj
%> @param 'tol', number see fact.eigtj (the error tolerance is not exactly for the svdtj but for the subsequent eigtj calls).
%> @param 'tol', number see fact.eigtj (NB: as described below, the error tolerance is not exactly for the approximate SVD but for the subsequent eigtj calls).
%> @param 'relerr', bool see fact.eigtj
%> @param 'verbosity', integer see fact.eigtj
%> @param 'nGivens_per_fac',integer see fact.eigtj
%>
%> @retval [U,S,V]: U*S*V' being the approximation of M.
%> - S: (sparse diagonal matrix) the singular values in
%> descendant order.
%> - U: (Faust object) the left-singular transform.
%> - V: (Faust object) the right-singular transform.
%> @retval [U,S,V]: such that U*S*V' is the approximate of M with:
%> - S: (sparse real diagonal matrix) the singular values in descendant order.
%> - U, V: (Faust objects) unitary transforms.
%>
%> @Example
%> @code
......@@ -50,7 +53,7 @@
%> To compute a consistent approximation of S we observe that U and V are orthogonal/unitary hence \f$ S = U^* M V \f$ so we ignore the off-diagonal coefficients of the approximation and take \f$ S = diag(U^* M V) \approx diag(W_1^* M W_2)\f$
%>
%> The last step performed by svdtj() is to sort the singular values of S in descending order and build a signed permutation matrix to order the left singular vectors of W1 accordingly. The -1 elements of the signed permutation matrix allow to change the sign of each negative values of S by reporting it on the corresponding left singular vector (\f$ \sigma v_i = (-\sigma_i) (-v_i )\f$).<br/>
%> To sum up W1 is replaced by W1 P and W2 by W2 abs(P) (because W2 also needs to be ordered), with P the signed permutation resulting of the descending sort of S. That new transforms/Fausts W1 and W2 are returned by svdtj along with the ordered S. Note that the permutation factor is not append to the transform W1 (or W2) but multiplied directly to the last factor of W1 (or W2).
%> To sum up W1 is replaced by W1 P and W2 by W2 abs(P) (because W2 also needs to be ordered), with P the signed permutation resulting of the descending sort of S. The resulting transforms/Fausts W1 and W2 are returned by svdtj along with the ordered S. Note that the permutation factor P (resp. abs(P)) is fused with the rightmost factor of the Faust object W1 (resp. W2).
%>
%> <p> @b See @b also fact.eigtj
%>
......@@ -83,7 +86,7 @@ function [U,S,V] = svdtj(M, varargin)
relerr = true;
verbosity = 0;
argc = length(varargin);
order = 1; % ascending order
order = -1; % descending order
if(argc > 0)
for i=1:argc
switch(varargin{i})
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment