Document StoppingCriterion class in pyfaust and matfaust.

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

@@ -9,19 +9,77 @@
 % =========================================================
 classdef StoppingCriterion
 	properties (SetAccess = public)
-		is_criterion_error
+		%> see matfaust.factparams.StoppingCriterion
 		num_its
+		%> see matfaust.factparams.StoppingCriterion
 		tol
+		%> see matfaust.factparams.StoppingCriterion
 		maxiter
+		%> see matfaust.factparams.StoppingCriterion
 		relerr
 	end
+	properties(SetAccess = private)
+		is_criterion_error
+	end
+	properties(Constant)
+		DEFAULT_MAXITER = 10000
+		DEFAULT_NUMITS = 500
+		DEFAULT_TOL = .3
+	end
 	methods
+		% =========================================================
+		%>	@brief Displays a StoppingCriterion instance.
+		%>
+		% =========================================================
+		function display(self)
+			if(self.is_criterion_error)
+				printf('tol: %f ', self.tol)
+				printf('relerr: %d', self.relerr)
+				printf('maxiter: %d',self.maxiter)
+			else
+				printf('num_its: %d', self.num_its)
+				printf('maxiter: %d', self.maxiter)
+			end
+		end
+		% =========================================================
+		%>	@brief Constructor.
+		%>
+		%>	@param 'numits', int the fixed number of iterations of the algorithm. By default the value is DEFAULT_NUMITS. If arguments num_its and tol are used together only the last one in the argument list is taken into account.
+		%>	@param 'tol', real error target according to the algorithm is stopped. If arguments num_its and tol are used together only the last one in the argument list is taken into account.
+		%> @param 'maxiter', int the maximum number of iterations to run the algorithm, whatever is the criterion used (tol or num_its).
+		%> @param 'relerr', bool false to define a absolute error with tol, true for a relative error
+		%> (in this case the 'relmat' matrix will be used to convert internally the given 'tol' to the corresponding absolute error).
+		%> @param 'relmat', matrix the matrix against which is defined the relative error. if relerr is True, this argument is mandatory.
+		%>
+		%> @b Example:
+		%> @code
+		%>>> import matfaust.factparams.StoppingCriterion
+		%>>> s = StoppingCriterion(5)
+		%>num_its 5:
+		%>maxiter 10000:
+		%>>> s = StoppingCriterion(.5)
+		%>tol: 0.500000
+		%>relerr: 0
+		%>maxiter: 10000
+		%>>> s = StoppingCriterion('tol', .5)
+		%>tol: 0.500000
+		%>relerr: 0
+		%>maxiter: 10000
+		%>>> s = StoppingCriterion('numits', 5)
+		%>num_its 500:
+		%>maxiter 10000:
+		%>>> s = StoppingCriterion('tol', .2, 'relerr', true, 'relmat', rand(10,10))
+		%>tol: 1.210149
+		%>relerr: 1
+		%>maxiter: 10000
+		%> @endcode
+		% =========================================================
 		function stop_crit = StoppingCriterion(varargin)
 			%set default values
 			is_criterion_error = false;
-			tol = 0.3;
-			num_its = 500;
-			maxiter = 10000;
+			tol = matfaust.factparams.StoppingCriterion.DEFAULT_TOL;
+			num_its = matfaust.factparams.StoppingCriterion.DEFAULT_NUMITS;
+			maxiter = matfaust.factparams.StoppingCriterion.DEFAULT_MAXITER;
 			relerr = false;
 			matrix = [];
 			if(nargin < 1)

wrapper/python/pyfaust/factparams.py

@@ -969,11 +969,18 @@ def _init_init_D(init_D, dim_sz):
 
 class StoppingCriterion(object):
     """
-        This class defines a StoppingCriterion for the FAuST's algorithms.
+        This class defines a StoppingCriterion for PALM4MSA algorithms.
 
         A stopping criterion can be of two kinds:
             - number of iterations,
-            - error threshold for the approximation of the matrix.
+            - error threshold.
+
+        Attributes:
+            num_its: see pyfaust.factparams.StoppingCriterion.__init__.
+            maxiter: see pyfaust.factparams.StoppingCriterion.__init__.
+            relerr: see pyfaust.factparams.StoppingCriterion.__init__.
+            relmat: see pyfaust.factparams.StoppingCriterion.__init__.
+            tol: see pyfaust.factparams.StoppingCriterion.__init__.
     """
     DEFAULT_MAXITER=10000
     DEFAULT_TOL=0.3
@@ -982,6 +989,42 @@ class StoppingCriterion(object):
                  tol = None,
                  maxiter = DEFAULT_MAXITER,
                 relerr = False, relmat=None):
+        """
+        Class constructor.
+
+        Args:
+            num_its: (optional) the fixed number of iterations of the
+            algorithm. By default the value is DEFAULT_NUMITS. The constructor
+            will fail if arguments num_its and tol are used together.
+            tol: (optional) error target according to the algorithm is stopped.
+            The constructor  will fail if arguments num_its and tol are used together.
+            maxiter: (optional) The maximum number of iterations to run the algorithm,
+            whatever is the criterion used (tol or num_its).
+            relerr: (optional) if False the tol error defines an absolute
+            error, otherwise it defines a relative error (in this case the
+            'relmat' matrix will be used to convert internally the given 'tol'
+            value to the corresponding absolute error).
+            relmat: (optional) The matrix against which is defined the relative error.
+            if relerr is True, this argument is mandatory.
+
+
+        Example:
+            >>> from pyfaust.factparams import StoppingCriterion
+            >>> from numpy.random import rand
+            >>> s = StoppingCriterion()
+            >>> print(s)
+            num_its: 500, maxiter: 10000
+            >>> s = StoppingCriterion(5)
+            >>> print(s)
+            num_its: 5, maxiter: 10000
+            >>> s = StoppingCriterion(tol=.5)
+            >>> print(s)
+            tol: 0.5 relerr: False, maxiter: 10000
+            >>> s = StoppingCriterion(tol=.2, relerr=True, relmat=rand(10,10))
+            >>> print(s)
+            tol: 1.1123924064125228, relerr: True, maxiter: 10000
+
+        """
         self.tol = tol
         if(tol != None):
             self._is_criterion_error = True
@@ -994,7 +1037,7 @@ class StoppingCriterion(object):
                                           StoppingCriterion.DEFAULT_MAXITER or
                                           tol != None)):
             raise ValueError("The choice between tol and num_its arguments is exclusive.")
-        if(relerr and not (isinstance(relmat, np.ndarray) or relmat == None)):
+        if(relerr and (not isinstance(relmat, np.ndarray))):
             raise ValueError("when error is relative (relerr == true) the "
                              "reference matrix 'relmat' must be specified")
         self.relerr = relerr
@@ -1004,6 +1047,17 @@ class StoppingCriterion(object):
             if(relerr):
                 self.tol *= np.linalg.norm(relmat)
 
+    def __str__(self):
+        """
+            Converts StoppingCriterion to a str.
+        """
+        if(self._is_criterion_error):
+            return "tol: "+str(self.tol)+", relerr: "+str(self.relerr)+ \
+                    ", maxiter: " + str(self.maxiter)
+        else:
+            return "num_its: "+str(self.num_its)+ \
+                    ", maxiter: " + str(self.maxiter)
+
 class ParamsFactFactory:
     """
         The factory for creating simplified FAuST hierarchical algorithm parameters (ParamsHierarchical).