Enable projectors for palm4msa()/hiearchical() only supporting...

Enable projectors for palm4msa()/hiearchical() only supporting ConstraintGeneric/ConstraintList before. Update the doc (mostly for projectors).

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

@@ -19,12 +19,15 @@
 %>
 %> @b Example 1: Fully Defined Parameters for a Random Matrix Factorization
 %> @code
-%>  import matfaust.*
 %>  import matfaust.factparams.*
 %>  import matfaust.fact.hierarchical
 %>  M = rand(500, 32);
 %>  fact_cons = ConstraintList('splin', 5, 500, 32, 'sp', 96, 32, 32, 'sp', 96, 32, 32);
 %>  res_cons = ConstraintList('normcol', 1, 32, 32, 'sp', 666, 32, 32, 'sp', 333, 32, 32);
+%> % or alternatively you can use projectors-functors
+%> % import matfaust.proj.*
+%> % fact_cons = {splin([500,32], 5), sp([32,32], 96), sp([32,32], 96)}
+%> % res_cons = {normcol([32,32], 1), sp([32,32], 666), sp([32,32], 333)}
 %>  stop_crit = StoppingCriterion(200);
 %>  stop_crit2 = StoppingCriterion(200);
 %>  params = ParamsHierarchical(fact_cons, res_cons, stop_crit, stop_crit2, 'is_update_way_R2L', false, 'init_lambda', 1.0);

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

@@ -15,6 +15,9 @@
 %>  import matfaust.fact.palm4msa
 %>  M = rand(500, 32);
 %>  cons = ConstraintList('splin', 5, 500, 32, 'normcol', 1, 32, 32);
+%>  % or alternatively, using the projectors
+%>  % import matfaust.proj.*
+%>  % cons = {splin([500,32], 5), normcol([32,32], 1)};
 %>  stop_crit = StoppingCriterion(200);
 %>  params = ParamsPalm4MSA(cons, stop_crit, 'is_update_way_R2L', false, 'init_lambda', 1.0);
 %>  F = palm4msa(M, params)

wrapper/matlab/+matfaust/+factparams/@ConstraintList/ConstraintList.m

@@ -10,6 +10,7 @@ classdef ConstraintList
 	methods
 		function this = ConstraintList(varargin)
 			import matfaust.factparams.*
+			import matfaust.proj.*
 			tuple_len = 4; % name, value, nrows, ncols
 			i = 1;
 			j = 1; % the number of processed constraints

wrapper/matlab/+matfaust/+factparams/@ParamsFact/ParamsFact.m

@@ -38,6 +38,13 @@ classdef (Abstract) ParamsFact
 	methods
 		function p = ParamsFact(num_facts, constraints, varargin)
 			import matfaust.factparams.ParamsFact
+			if(iscell(constraints))
+				for i=1:length(constraints)
+					if(isa(constraints{i}, 'matfaust.proj.proj_gen'))
+						constraints{i} = constraints{i}.constraint
+					end
+				end
+			end
 			% set default values
 			is_update_way_R2L = ParamsFact.DEFAULT_IS_UPDATE_WAY_R2L;
 			init_lambda = ParamsFact.DEFAULT_INIT_LAMBDA;

wrapper/matlab/+matfaust/+factparams/@ParamsHierarchical/ParamsHierarchical.m

@@ -17,6 +17,20 @@ classdef ParamsHierarchical < matfaust.factparams.ParamsFact
 	methods
 		function p = ParamsHierarchical(fact_constraints, res_constraints, stop_crit1, stop_crit2, varargin)
 			import matfaust.factparams.*
+			if(iscell(fact_constraints))
+				for i=1:length(fact_constraints)
+					if(isa(fact_constraints{i}, 'matfaust.proj.proj_gen'))
+						fact_constraints{i} = fact_constraints{i}.constraint
+					end
+				end
+			end
+			if(iscell(res_constraints))
+				for i=1:length(res_constraints)
+					if(isa(res_constraints{i}, 'matfaust.proj.proj_gen'))
+						res_constraints{i} = res_constraints{i}.constraint
+					end
+				end
+			end
 			if(isa(fact_constraints, 'ConstraintList'))
 				fact_constraints = fact_constraints.clist;
 			end
@@ -24,10 +38,10 @@ classdef ParamsHierarchical < matfaust.factparams.ParamsFact
 				res_constraints = res_constraints.clist;
 			end
 			if(~ iscell(fact_constraints))
-				error('fact_constraints (argument 1) must be a cell array')
+				error('fact_constraints (argument 1) must be a cell array of matfaust.factparams.ConstraintGeneric or matfaust.proj.proj_gen.')
 			end
 			if(~ iscell(res_constraints))
-				error('res_constraints (argument 2) must be a cell array')
+				error('res_constraints (argument 2) must be a cell array of matfaust.factparams.ConstraintGeneric or matfaust.proj.proj_gen.')
 			end
 			if(length(fact_constraints) ~= length(res_constraints))
 				error('lengths of fact_constraints and res_constraints must be equal.')

wrapper/matlab/+matfaust/+proj/@const/const.m

 %==================================================
-%> Functor that implements the CONST projector.
+%> Functor for the CONST projector.
 %==================================================
-classdef const < matfaust.factparams.proj_gen
+classdef const < matfaust.proj.proj_gen
 	properties
 	end
 	methods

wrapper/matlab/+matfaust/+proj/@normcol/normcol.m

 %==================================================
-%> Functor that implements the NORMCOL projector. A, the image matrix, is defined by \f$ \forall j \in \{1,\ldots,shape(2)\} \| A_{*,j} \|_2 = s \| \f$.
+%> @brief Functor for the NORMCOL projector.
+%>
+%> A, the image matrix, is defined by \f$ \forall j \in \{1,\ldots,shape(2)\} \f$ the j-th column \f$  A_{*,j} \f$ is such that \f$ \| A_{*,j} \|_2 = s  \f$.
 %==================================================
-classdef normcol < matfaust.factparams.proj_gen
+classdef normcol < matfaust.proj.proj_gen
 	properties
 	end
 	methods

wrapper/matlab/+matfaust/+proj/@normlin/normlin.m

 %==================================================
-%> Functor that implements the NORMLIN projector. A, the image matrix, is defined by \f$ \forall i \in \{1,\ldots,shape(1)\} \| A_{i, *} \|_2 = s \| \f$.
+%> @brief Functor for the NORMLIN projector.
+%>
+%> A, the image matrix, is defined by \f$ \forall i \in \{1,\ldots,shape(1)\} \f$ the i-th row \f$  A_{i,*} \f$ is such that \f$ \| A_{i, *} \|_2 = s \f$.
 %==================================================
-classdef normlin < matfaust.factparams.proj_gen
+classdef normlin < matfaust.proj.proj_gen
 	properties
 	end
 	methods

wrapper/matlab/+matfaust/+proj/@proj_gen/proj_gen.m

 %> @package matfaust.proj @brief This module provides matrix projectors.
 
 %=========================================================
-%> @brief The parent abstract class to represent projectors.
+%> @brief The parent abstract class to represent projectors (as functors).
 %=========================================================
 classdef (Abstract) proj_gen
 	properties (SetAccess = protected)

wrapper/matlab/+matfaust/+proj/@sp/sp.m

 %==================================================
-%> @brief Functor that implements the SP projector. A, the projected matrix, is such that \f$ \| A \|_0 = k,  \| A\|_F = 1\f$.
+%> @brief Functor for the SP projector.
+%>
+%> A, the image matrix, is such that \f$ \| A \|_0 = k,  \| A\|_F = 1\f$.
 %==================================================
-classdef sp < matfaust.factparams.proj_gen
+classdef sp < matfaust.proj.proj_gen
 	properties
 	end
 	methods

wrapper/matlab/+matfaust/+proj/@spcol/spcol.m

 %==================================================
-%> @brief Functor that implements the SPCOL projector. A, the projected matrix, is defined by \f$ \forall j \in \{1,\ldots,shape(2)\} \| \f$ the j-th column \f$ \| A_{*,j}\| \f$ is such that \f$ A_{*,j}\|_0 = k,  \| A\|_F = 1\f$.
+%> @brief Functor for the SPCOL projector.
+%>
+%> A, the image matrix, is defined by \f$ \forall j \in \{1,\ldots,shape(2)\} \f$ the j-th column \f$  A_{*,j} \f$ is such that \f$ \|A_{*,j}\|_0 = k,  \| A\|_F = 1\f$.
 %==================================================
-classdef spcol < matfaust.factparams.proj_gen
+classdef spcol < matfaust.proj.proj_gen
 	properties
 	end
 	methods

wrapper/matlab/+matfaust/+proj/@splin/splin.m

 %==========================================
-%> Functor that implements the SPLIN projector. A, the projected matrix, is defined by \f$ \forall i \in \{1,\ldots,shape(1)\} \| \f$ the i-th row \f$ A_{i,*}\f$ is such that \f$ \| A_{i,*}\|_0 = k,  \| A\|_F = 1\f$. 
+%> @brief Functor for the SPLIN projector.
+%>
+%> A, the image matrix, is defined by \f$ \forall i \in \{1,\ldots,shape(1)\} \f$ the i-th row \f$  A_{i,*} \f$ is such that \f$ \|A_{i,*}\|_0 = k,  \| A\|_F = 1\f$.
 %==========================================
-classdef splin < matfaust.factparams.proj_gen
+classdef splin < matfaust.proj.proj_gen
 	properties
 	end
 	methods

wrapper/matlab/+matfaust/+proj/@splincol/splincol.m

 %==================================================
-%> @brief Functor that implements the SPLINCOL projector.
+%> @brief Functor for the SPLINCOL projector.
 %>
 %> It's the union of SPLIN and SPCOL projectors.
 %==================================================
-classdef splincol < matfaust.factparams.proj_gen
+classdef splincol < matfaust.proj.proj_gen
 	properties
 	end
 	methods

wrapper/matlab/+matfaust/+proj/@supp/supp.m

 %==================================================
-%> @brief Functor that implements the SUPP projector.
+%> @brief Functor for the the SUPP projector.
 %>
 %> A, the image matrix, is such that nonzeros(A) == nonzeros(S)
 %==================================================
-classdef supp < matfaust.factparams.proj_gen
+classdef supp < matfaust.proj.proj_gen
 	properties
 	end
 	methods

wrapper/python/pyfaust/fact.py

@@ -428,6 +428,9 @@ def palm4msa(M, p, ret_lambda=False):
     >>> import numpy as np
     >>> M = np.random.rand(500, 32)
     >>> cons = ConstraintList('splin', 5, 500, 32, 'normcol', 1.0, 32, 32)
+    >>> # or alternatively using pyfaust.proj
+    >>> # from pyfaust.proj import splin, normcol
+    >>> # cons = [ splin((500,32), 5), normcol((32,32), 1.0)]
     >>> stop_crit = StoppingCriterion(num_its=200)
     >>> param = ParamsPalm4MSA(cons, stop_crit)
     >>> F = palm4msa(M, param)
@@ -518,6 +521,9 @@ def hierarchical(M, p, ret_lambda=False, ret_params=False):
         >>> M = np.random.rand(500, 32)
         >>> fact_cons = ConstraintList('splin', 5, 500, 32, 'sp', 96, 32, 32, 'sp', 96, 32, 32)
         >>> res_cons = ConstraintList('normcol', 1, 32, 32, 'sp', 666, 32, 32, 'sp', 333, 32, 32)
+        >>> # or alternatively using pyfaust.proj
+        >>> # from pyfaust.proj import *
+        >>> # res_cons = [normcol((32,32), 1), sp((32,32), 666), sp((32,32), 333)]
         >>> stop_crit1 = StoppingCriterion(num_its=200)
         >>> stop_crit2 = StoppingCriterion(num_its=200)
         >>> param = ParamsHierarchical(fact_cons, res_cons, stop_crit1, stop_crit2)

wrapper/python/pyfaust/factparams.py

@@ -324,7 +324,7 @@ class ConstraintName:
     Example:
         >>> # SPLINCOL Comprehensive Example
         >>> # This constraint doesn't necessarily
-        >>> # lead to a  projected matrix with asked sparsity respected
+        >>> # lead to a  image matrix with asked sparsity respected
         >>> # both for columns and rows
         >>> from numpy.random import rand
         >>> from numpy.linalg import norm
@@ -540,6 +540,11 @@ class ParamsFact(ABC):
         self.is_update_way_R2L = is_update_way_R2L
         self.init_lambda = init_lambda
         self.step_size = step_size
+        if((isinstance(constraints, list) or isinstance(constraints, tuple))
+           and np.array([isinstance(constraints[i],pyfaust.proj.proj_gen) for i in
+                    range(0,len(constraints))]).all()):
+            # "convert" projs to constraints
+            constraints = [ p.constraint for p in constraints ]
         if(isinstance(constraints, ConstraintList)):
             self.constraints = constraints.clist
         else:

wrapper/python/pyfaust/proj.py

@@ -12,7 +12,7 @@ else:
 
 class proj_gen(ABC):
     """
-    Parent abstract class of all projector functors.
+    The parent abstract class to represent projectors (as functors).
     """
     @abstractmethod
     def __init__(self):
@@ -23,7 +23,7 @@ class proj_gen(ABC):
 
 class toeplitz(proj_gen):
     """
-    Functor that implements the TOEPLITZ projector.
+    Functor for the TOEPLITZ projector.
     """
     def __init__(self, shape, normalized=True, pos=False):
         self.constraint = ConstraintMat('toeplitz', np.empty(shape), normalized, pos)
@@ -42,7 +42,7 @@ class toeplitz(proj_gen):
 
 class circ(proj_gen):
     """
-    Functor that implements the CIRC(ulant) projector.
+    Functor for the CIRC(ulant) projector.
     """
     def __init__(self, shape, normalized=True, pos=False):
         self.constraint = ConstraintMat('circ', np.empty(shape), normalized, pos)
@@ -67,7 +67,7 @@ class circ(proj_gen):
 
 class hankel(proj_gen):
     """
-    Functor that implements the HANKEL projector.
+    Functor for the HANKEL projector.
     """
     def __init__(self, shape, normalized=True, pos=False):
         self.constraint = ConstraintMat('hankel', np.empty(shape), normalized, pos)
@@ -75,7 +75,7 @@ class hankel(proj_gen):
 
 class sp(proj_gen):
     """
-    Functor that implements the SP projector. A, the projected matrix, is such that \f$ \| A \|_0 = k,  \| A\|_F = 1\f$.
+    Functor for the SP projector. A, the image matrix, is such that \f$ \| A \|_0 = k,  \| A\|_F = 1\f$.
     """
 
     def __init__(self, shape, k, normalized=True, pos=False):
@@ -91,7 +91,7 @@ class sp(proj_gen):
 
 class splin(proj_gen):
     """
-    Functor that implements the SPLIN projector. A, the projected matrix, is defined by \f$ \forall i \in \{0,...,shape[0]-1\} \| \f$ the i-th row \f$ A_{i,*}\f$ is such that \f$ \| A_{i,*}\|_0 = k,  \| A\|_F = 1\f$.
+    Functor for the SPLIN projector. A, the image matrix, is defined by \f$ \forall i \in \{0,...,shape[0]-1\} \| \f$ the i-th row \f$ A_{i,*}\f$ is such that \f$ \| A_{i,*}\|_0 = k,  \| A\|_F = 1\f$.
     """
     def __init__(self, shape, k, normalized=True, pos=False):
         """
@@ -105,7 +105,7 @@ class splin(proj_gen):
 
 class spcol(proj_gen):
     """
-    Functor that implements the SPCOL projector. A, the projected matrix, is defined by \f$ \forall j \in \{0,...,shape[1]-1\} \| \f$ the j-th column \f$ \| A_{*,j}\f$ is such that \f$ A_{*,j}\|_0 = k,  \| A\|_F = 1\f$.
+    Functor for the SPCOL projector. A, the image matrix, is defined by \f$ \forall j \in \{0,...,shape[1]-1\} \f$ the j-th column \f$ A_{*,j}\f$ is such that \f$ \| A_{*,j}\|_0 = k,  \| A\|_F = 1\f$.
     """
     def __init__(self, shape, k, normalized=True, pos=False):
         """
@@ -120,7 +120,7 @@ class spcol(proj_gen):
 
 class splincol(proj_gen):
     """
-    Functor that implements the SPLINCOL projector.
+    Functor for the SPLINCOL projector.
 
     It's the union of SPLIN and SPCOL projectors.
     """
@@ -137,7 +137,7 @@ class splincol(proj_gen):
 
 class supp(proj_gen):
     """
-        Functor that implements the SUPP projector. A, the image matrix, is such that np.nonzero(A) == np.nonzero(S).
+        Functor for the SUPP projector. A, the image matrix, is such that np.nonzero(A) == np.nonzero(S).
     """
     def __init__(self, S, normalized=True, pos=False):
         """
@@ -151,7 +151,7 @@ class supp(proj_gen):
 
 class const(proj_gen):
     """
-        Functor that implements the CONST projector. A, the image matrix, is such that A == C.
+        Functor for the CONST projector. A, the image matrix, is such that A == C.
     """
     def __init__(self, C, normalized=False):
         """
@@ -166,7 +166,7 @@ class const(proj_gen):
 
 class normcol(proj_gen):
     """
-        Functor that implements the NORMCOL projector. A, the image matrix, is defined by \f$ \forall j \in \{0,...,shape[1]-1\} \| A_{*,j} \|_2 = s \| \f$.
+        Functor for the NORMCOL projector. A, the image matrix, is defined by \f$ \forall j \in \{0,...,shape[1]-1\} \f$ the j-th column \f$ A_{*,j} \f$ is such that \f$\| A_{*,j}\|_2 = s  \f$.
 
     """
     def __init__(self, shape, s, normalized=False, pos=False):
@@ -181,7 +181,7 @@ class normcol(proj_gen):
 
 class normlin(proj_gen):
     """
-        Functor that implements the NORMLIN projector. A, the image matrix, is defined by \f$ \forall j \in \{0,...,shape[0]-1\} \| A_{i,*} \|_2 = s \| \f$.
+        Functor for the NORMLIN projector. A, the image matrix, is defined by \f$ \forall i \in \{0,...,shape[0]-1\}\f$ the i-th row \f$ A_{i,*} \f$ is such that \f$ \| A_{i,*} \|_2 = s \f$.
 
     """