Update pyfaust API doc (fact_hierarchical()).

wrapper/python/pyfaust.py

@@ -1388,12 +1388,34 @@ class FaustFactory:
 
         Args:
             M: the numpy matrix to factorize.
-            p: the ParamsHierarchicalFact instance to define the algorithm parameters.
+			p: is a set of factorization parameters. It might be a fully defined instance of parameters (pyfaust.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 pyfaust.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 pyfaust.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. pyfaust.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 pyfaust.faust_fact(). For convenience you might use it like this:
+				<code>
+				from pyfaust import *
+				F = faust_fact(M, p) % equiv. to FaustFactory.fact_hierarchical(M, p)
+				</code>
+
+            ret_lambda: set to True to ask the function to return the scale factor (False by default).
+            ret_params: set to True to ask the function to return the
+            ParamsHierarchicalFact instance used (False by default).
 
         Returns:
-            The Faust object result of the factorization.
+            F the Faust object result of the factorization.<br/>
+            if ret_lambda == True (and ret_params == False), then the function
+            returns the tuple (F,_lambda) (_lambda is the scale factor at the
+            end of factorization).<br/>
+            if ret_params == True (and ret_lambda == False), then the function
+            returns the tuple (F, p) (p being the ParamsHierarchicalFact
+            instance really used by the algorithm).<br/>
+            if ret_lambda == True and ret_params == True, then the function
+            returns the tuple (F, _lambda, p).
 
         Examples:
+            <b> 1. Fully Defined Parameters for a Random Matrix Factorization </b>
             >>> from pyfaust import FaustFactory
             >>> from pyfaust.factparams import ParamsHierarchicalFact, ConstraintReal,\
             >>> ConstraintInt, ConstraintName, StoppingCriterion
@@ -1413,12 +1435,78 @@ class FaustFactory:
             2/3<br/>
             Faust::HierarchicalFact<FPP,DEVICE>::compute_facts : factorisation
             3/3<br/>
-            >>> F.display()
+            >>> F
             Faust size 500x32, density 0.189063, nnz_sum 3025, 4 factor(s):
                 - FACTOR 0 (real) SPARSE, size 500x32, density 0.15625, nnz 2500
                 - FACTOR 1 (real) SPARSE, size 32x32, density 0.09375, nnz 96
                 - FACTOR 2 (real) SPARSE, size 32x32, density 0.09375, nnz 96
                 - FACTOR 3 (real) SPARSE, size 32x32, density 0.325195, nnz 333
+
+            <b>2. Simplified Parameters for Hadamard Factorization</b>
+
+            >>> from pyfaust import FaustFactory as Facto
+            >>> from numpy.linalg import norm
+            >>> # generate a Hadamard Faust of size 32x32
+            >>> FH = Facto.wht(5);
+            >>> H = FH.toarray(); # the full matrix version
+            >>> # factorize it
+            >>> FH2 = Facto.fact_hierarchical(H, 'squaremat');
+            >>> # test the relative error
+            >>> (FH-FH2).norm('fro')/FH.norm('fro') # the result is 1.1015e-16, the factorization is accurate
+            >>> FH
+            Faust size 32x32, density 0.3125, nnz_sum 320, 5 factor(s):
+            - FACTOR 0 (real) SPARSE, size 32x32, density 0.0625, nnz 64
+            - FACTOR 1 (real) SPARSE, size 32x32, density 0.0625, nnz 64
+            - FACTOR 2 (real) SPARSE, size 32x32, density 0.0625, nnz 64
+            - FACTOR 3 (real) SPARSE, size 32x32, density 0.0625, nnz 64
+            - FACTOR 4 (real) SPARSE, size 32x32, density 0.0625, nnz 64
+
+            >>> FH2
+            Faust size 32x32, density 0.3125, nnz_sum 320, 5 factor(s):
+                - FACTOR 0 (real) SPARSE, size 32x32, density 0.0625, nnz 64
+                - FACTOR 1 (real) SPARSE, size 32x32, density 0.0625, nnz 64
+                - FACTOR 2 (real) SPARSE, size 32x32, density 0.0625, nnz 64
+                - FACTOR 3 (real) SPARSE, size 32x32, density 0.0625, nnz 64
+                - FACTOR 4 (real) SPARSE, size 32x32, density 0.0625, nnz 64
+
+           <b> 3. Simplified Parameters for a Rectangular Matrix Factorization
+           (the BSL demo MEG matrix)</b>
+           >>> from pyfaust import *
+           >>> from scipy.io import loadmat
+           >>> d = loadmat('@FAUST_MATFAUST_DEMO_DATA_BIN_DIR@/matrix_MEG.mat')
+           >>> MEG = d['matrix']
+           >>> num_facts = 9
+           >>> k = 10
+           >>> s = 8
+           >>> MEG16 = FaustFactory.fact_hierarchical(MEG, ['rectmat', num_facts, k, s])
+           >>> 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
+
+           >>> # verify the constraint k == 10, on column 4
+           >>> count_nonzero(MEG16.get_factor(8)[:,4].toarray())
+           10
+           >>> # now verify the s constraint is respected on MEG16 factor 1
+           >>> count_nonzero(MEG16.get_factor(1).toarray())/MEG16.shape[0]
+           8.0
+
         """
         from pyfaust.factparams import (ParamsHierarchicalFact,
         ParamsFactFactory)