Update wrapper eigtj doc and backend C++ code too.

src/algorithm/factorization/faust_GivensFGFTComplex.h

@@ -16,7 +16,7 @@ namespace Faust {
 			/**
 			 * \class Faust::GivensFGFTComplex
 			 *
-			 * \brief This class implements the Givens FGFT algorithm.
+			 * \brief This class implements the Givens FGFT algorithm (Truncated Jacobi algorithm) for the complex matrix case (ideal case being the Hermitian matrix case).
 			 * This algorithm is based on the classical Jacobi eigenvalues algorithm.
 			 *
 			 *  References:
@@ -27,6 +27,9 @@ namespace Faust {
 			 *    over Networks.
 			 *    <https://hal.inria.fr/hal-01416110>
 			 *
+			 *    For the complex version of the algorithm, see generalization here:
+			 *    https://en.wikipedia.org/wiki/Jacobi_method_for_complex_Hermitian_matrices
+			 *
 			 */
 			/** \brief Temporary storage matrix for maximization of L. */
 			Faust::MatDense<FPP,DEVICE> C;
@@ -36,7 +39,7 @@ namespace Faust {
 			int* q_candidates;  /* default IndexType for underlying eigen matrix is int. */
 			protected:
 				const static unsigned int ERROR_CALC_PERIOD = 100;
-				/** \brief Fourier matrix factorization matrices (Givens matrix). */
+				/** \brief Fourier matrix/eigenvectors factorization matrices (Givens matrix). */
 				vector<Faust::MatSparse<FPP,DEVICE>> facts;
 				/** \brief Diagonalization approximate of Laplacian. */
 				Faust::Vect<FPP,DEVICE> D;

src/algorithm/factorization/faust_GivensFGFTParallelComplex.h

@@ -14,7 +14,7 @@ namespace Faust {
 		/**
 		 * \class Faust::GivensFGFTParallelComplex
 		 *
-		 * \brief This class implements the parallel version of Givens FGFT algorithm.
+		 * \brief This class implements the parallel version of Givens FGFT algorithm (for the complex case).
 		 *
 		 * This variant of the parent class algorithm consists mainly to put t 2D rotation matrices in each iteration factor S (i.e. facts[ite]) when the basis version puts only a single rotation matrix into L.
 		 *
@@ -28,6 +28,8 @@ namespace Faust {
 		 *    over Networks.
 		 *    <https://hal.inria.fr/hal-01416110>
 		 *
+		 *  Complementary reference for the complex case: https://en.wikipedia.org/wiki/Jacobi_method_for_complex_Hermitian_matrices
+		 *
 		 */
 
 		/** Maximum number of rotations per factor

wrapper/matlab/+matfaust/+fact/eigtj.m

@@ -15,7 +15,7 @@
 %> &nbsp;&nbsp;&nbsp; @b eigtj(M, J, 'nGivens_per_fac', t, 'tol', 0.01, 'relerr', true) Uses a stopping criterion based on relative squared error norm(V*D*V'-M, 'fro')^2/norm(M, 'fro')^2. This criterion is concurrent to maxiter (here J).<br/>
 %> &nbsp;&nbsp;&nbsp; @b eigtj(M, J, 'nGivens_per_fac', t, 'tol', 0.01, 'relerr', true) Uses a stopping criterion based on absolute squared error norm(V*D*V'-M, 'fro')^2. This criterion is concurrent to maxiter (here J).<br/>
 %>
-%> @param M the matrix to diagonalize. Must be real and symmetric or hermitian.
+%> @param M the matrix to diagonalize. Must be real and symmetric or hermitian if complex. Be warn that the dense or sparse chosen format will be respected along the algorithm execution so that the performances and accuracy can be different moreover if there is many iterations.
 %> @param maxiter defines the number of Givens rotations that are computed in eigenvector transform V. The number of rotations per factor of V is defined by nGivens_per_fac.
 %> @param 'nGivens_per_fac', integer the number of Givens rotations per factor of V, must be an integer between 1 to floor(size(M, 1)/2) which is the default value.
 %> @param 'tol', number (optional) the tolerance error under what the algorithm stops. By default, it's zero for not stopping on error criterion.

wrapper/python/pyfaust/fact.py

@@ -93,7 +93,10 @@ def eigtj(M, maxiter, tol=0, relerr=True,  nGivens_per_fac=None, verbosity=0,
     parameters maxiter and nGivens_per_fac.
 
     Args:
-        M: (numpy.ndarray) the matrix to diagonalize. Must be real and symmetric.
+        M: (numpy.ndarray or csr_matrix) the matrix to diagonalize. Must be
+        real and symmetric or hermitian if complex. Be warn that the sparse or
+        dense chosen format for M is respected along the algorithm execution so
+        that the performances and accuracy can be different.
         maxiter: (int) defines the number of Givens rotations that are computed in
         eigenvector transform V. The number of rotations per factor of V is
         defined by nGivens_per_fac.
@@ -156,7 +159,8 @@ def fgft_givens(Lap, maxiter, tol=0.0, relerr=True, nGivens_per_fac=None,
     Computes the FGFT of the Laplacian matrix Lap (using fact.eigtj).
 
     Args:
-        Lap: the Laplacian matrix as a numpy array. Must be real and symmetric.
+        Lap: the Laplacian matrix as a numpy array or csr_matrix. Must be real
+        and symmetric or hermitian if complex.
         maxiter: see fact.eigtj
         tol: see fact.eigtj
         relerr: see fact.eigtj