Update matfaust API doc (fact_hierarchical()) and add...

Update matfaust API doc (fact_hierarchical()) and add ParamsHierarchicalFactSquareMat.m and ParamsHierarchicalFactRectMat.m to doxydoc parsing file list.

gen_doc/CMakeLists.txt

@@ -7,7 +7,7 @@ if(BUILD_DOCUMENTATION)
 			string(CONCAT DOXYGEN_FILE_PATTERNS "*.cpp *.hpp *.h *.cu *.hu")
 		endif()
 		if(BUILD_WRAPPER_MATLAB)
-			string(CONCAT DOXYGEN_FILE_PATTERNS ${DOXYGEN_FILE_PATTERNS} " Faust.m StoppingCriterion.m ConstraintGeneric.m ConstraintMat.m ConstraintReal.m ConstraintInt.m ConstraintName.m ParamsFact.m ParamsHierarchicalFact.m ParamsPalm4MSA.m FaustFactory.m hadamard.m quickstart.m fft.m bsl.m runtimecmp.m runall.m version.m faust_fact.m")
+			string(CONCAT DOXYGEN_FILE_PATTERNS ${DOXYGEN_FILE_PATTERNS} " Faust.m StoppingCriterion.m ConstraintGeneric.m ConstraintMat.m ConstraintReal.m ConstraintInt.m ConstraintName.m ParamsFact.m ParamsHierarchicalFact.m ParamsPalm4MSA.m FaustFactory.m hadamard.m quickstart.m fft.m bsl.m runtimecmp.m runall.m version.m faust_fact.m ParamsHierarchicalFactSquareMat.m ParamsHierarchicalFactRectMat.m")
 		endif()
 		if(BUILD_WRAPPER_PYTHON)
 			string(CONCAT DOXYGEN_FILE_PATTERNS ${DOXYGEN_FILE_PATTERNS} " __init__.py factparams.py demo.py")

wrapper/matlab/+matfaust/@FaustFactory/FaustFactory.m

@@ -113,16 +113,21 @@ classdef FaustFactory
 		%>
 		%>
 		%> @param M the dense matrix to factorize.
-		%> @param p is a set of factorization parameters. It might be a fully defined instance of parameters or a simplified shorthand:
+		%> @param p is a set of factorization parameters. It might be a fully defined instance of parameters (matfaust.factparams.ParamsHierarchicalFact) or a simplified expression which designates a pre-defined parametrization:
 		%> - 'squaremat' to use pre-defined parameters typically used to factorize a Hadamard square matrix of order a power of two (see matfaust.demo.hadamard).
-		%> - {'rectmat', j, k, s} to use pre-defined parameters used for instance in factorization of the MEG matrix which is a rectangular matrix of size m*n such that m < n (see matfaust.demo.bsl); j is the number of factors, k the sparsity of the first factor columns, and s the whole matrix sparsity for all residuum factors in the factorization. <br/>The sparsity is here the number of non-zero elements.
-		%> @note The fully defined parameters (ParamsHierarchicalFact instance) used/generated by the function are available in the return result (so one can consult what precisely mean the simplified parameterizations).
-		%>
+		%> - {'rectmat', j, k, s} to use pre-defined parameters used for instance in factorization of the MEG matrix which is a rectangular matrix of size m*n such that m < n (see matfaust.demo.bsl); j is the number of factors, k the sparsity of the main factor's columns, and s the sparsity of rows for all other factors except the residuum (that is the first factor here because the factorization is made toward the left -- is_side_fact_left == true, cf. matfaust.factparams.ParamsHierarchicalFact).
+		%> </br>The residuum has a sparsity of P*rho^(num_facts-1). <br/> By default, rho == .8 and P = 1.4. It's possible to set custom values with for example p == { 'rectmat', j, k, s, 'rho', .4, 'P', .7}. <br/>The sparsity is here the number of non-zero elements.
+		%> @note - The fully defined parameters (ParamsHierarchicalFact instance) used/generated by the function are available in the return result (so one can consult what precisely mean the simplified parameterizations and possibly adjust the attributes to factorize again).
+		%> @note - This function has its shorthand matfaust.faust_fact(). For convenience you might use it like this:
+		%> @code
+		%> import matfaust.*
+		%> F = faust_fact(M, p) % equiv. to FaustFactory.fact_hierarchical(M, p)
+		%> @endcode
 		%>
 		%> @retval F The Faust object result of the factorization.
 		%> @retval [F, lambda, p_obj] = fact_hierarchical(M, p) to optionally get lambda (scale) and the p_obj ParamsHierarchicalFact instance used to factorize.
 		%>
-		%> @b Example 1
+		%> @b Example 1: Fully Defined Parameters for a Random Matrix Factorization
 		%> @code
 		%>  import matfaust.*
 		%>  import matfaust.factparams.*
@@ -154,7 +159,7 @@ classdef FaustFactory
 		%> import matfaust.FaustFactory.*
 		%> % generate a Hadamard Faust of size 32x32
 		%> FH = wht(5);
-		%> H = full(wht(5)); % the full matrix version
+		%> H = full(FH); % the full matrix version
 		%> % factorize it
 		%> FH2 = FaustFactory.fact_hierarchical(H, 'squaremat');
 		%> % test the relative error
@@ -179,6 +184,49 @@ classdef FaustFactory
 		%>- FACTOR 4 (real) SPARSE, size 32x32, density 0.0625, nnz 64
 		%>
 		%>
+		%>@b Example 3: Simplified Parameters for a Rectangular Matrix Factorization (the BSL demo  MEG matrix)
+		%>
+		%> @code
+		%> >> % in a matlab terminal
+		%> >> import matfaust.*
+		%> >> load('matrix_MEG.mat')
+		%> >> MEG = matrix;
+		%> >> num_facts = 9;
+		%> >> k = 10;
+		%> >> s = 8;
+		%> >> MEG16 = FaustFactory.fact_hierarchical(MEG, {'rectmat', num_facts, k, s})
+		%> @endcode
+		%> MEG16 =
+		%>
+		%> Faust size 204x8193, density 0.0631655, nnz_sum 105573, 9 factor(s):
+		%> - FACTOR 0 (real) SPARSE, size 204x204, density 0.293613, nnz 12219
+		%> - FACTOR 1 (real) SPARSE, size 204x204, density 0.0392157, nnz 1632
+		%> - FACTOR 2 (real) SPARSE, size 204x204, density 0.0392157, nnz 1632
+		%> - FACTOR 3 (real) SPARSE, size 204x204, density 0.0392157, nnz 1632
+		%> - FACTOR 4 (real) SPARSE, size 204x204, density 0.0392157, nnz 1632
+		%> - FACTOR 5 (real) SPARSE, size 204x204, density 0.0392157, nnz 1632
+		%> - FACTOR 6 (real) SPARSE, size 204x204, density 0.0392157, nnz 1632
+		%> - FACTOR 7 (real) SPARSE, size 204x204, density 0.0392157, nnz 1632
+		%> - FACTOR 8 (real) SPARSE, size 204x8193, density 0.0490196, nnz 81930
+		%>
+		%> @code
+		%> >> % verify the constraint k == 10, on column 5
+		%> >> fac9 = get_factor(MEG16,9);
+		%> >> numel(nonzeros(fac9(:,5)))
+		%> @endcode
+		%> ans =
+		%>
+		%> 10
+		%>
+		%> @code
+		%> >> % now verify the s constraint is respected on MEG16 factor 2
+		%> >> numel(nonzeros(get_factor(MEG16, 2)))/size(MEG16,1)
+		%> @endcode
+		%>
+		%>ans =
+		%>
+		%> 8
+		%> <p> @b See @b also matfaust.faust_fact, factparams.ParamsHierarchicalFact, factparams.ParamsHierarchicalFactSquareMat, factparams.ParamsHierarchicalFactRectMat
 		%==========================================================================================
 		function varargout = fact_hierarchical(M, p)
 			import matfaust.Faust