Change the boolean is_real argument of FaustFactory.rand() to str...

Change the boolean is_real argument of FaustFactory.rand() to str 'complex'/'real' (for both pyfaust and matfaust).

Part of issue #43.

gen_doc/bin_pkgs/README_template.html

@@ -53,7 +53,7 @@ Neverthless, it could be useful to check that it really worked and set the envir
 
 <p>To test whether the FAµST Matlab wrapper auto-setup succeeded at install stage, you can open a terminal and type:</p>
 
-<pre><code>matlab -nodisplay -nojvm -r "import matfaust.FaustFactory;F = FaustFactory.rand(1, 10, .5, 'dense', false);disp(F);exit"
+<pre><code>matlab -nodisplay -nojvm -r "import matfaust.FaustFactory;F = FaustFactory.rand(1, 10, .5, 'dense', 'complex');disp(F);exit"
 </code></pre>
 
 <p>Note: if Matlab is not set in your PATH environment variable you need to replace `matlab' with its full path
@@ -77,7 +77,7 @@ Neverthless, it could be useful to check that it really worked and set the envir
 
 <pre><code>&gt;&gt; setup_FAUST
 &gt;&gt; % then test again FAµST
-&gt;&gt; import matfaust.FaustFactory;F = FaustFactory.rand(1, 10, .5, 'dense', false);disp(F);exit
+&gt;&gt; import matfaust.FaustFactory;F = FaustFactory.rand(1, 10, .5, 'dense', 'complex');disp(F);exit
 </code></pre>
 
 <p>For that change to be applied permanently, you need to automatize the `addpath()&lsquo; call made by setup_FAUST.<br/>

gen_doc/bin_pkgs/README_template.md

@@ -45,7 +45,7 @@ Neverthless, it could be useful to check that it really worked and set the envir
 
 To test whether the FAµST Matlab wrapper auto-setup succeeded at install stage, you can open a terminal and type:
 
-	matlab -nodisplay -nojvm -r "import matfaust.FaustFactory;F = FaustFactory.rand(1, 10, .5, 'dense', false);disp(F);exit"
+	matlab -nodisplay -nojvm -r "import matfaust.FaustFactory;F = FaustFactory.rand(1, 10, .5, 'dense', 'complex');disp(F);exit"
 
 Note: if Matlab is not set in your PATH environment variable you need to replace `matlab' with its full path
 	(e.g. on macOS /Applications/Matlab/MATLAB_R2018b.app/bin/matlab)
@@ -66,7 +66,7 @@ Then launch the script that is responsible to add FAµST location in your Matlab
 
 	>> setup_FAUST
 	>> % then test again FAµST
-	>> import matfaust.FaustFactory;F = FaustFactory.rand(1, 10, .5, 'dense', false);disp(F);exit
+	>> import matfaust.FaustFactory;F = FaustFactory.rand(1, 10, .5, 'dense', 'complex');disp(F);exit
 
 For that change to be applied permanently, you need to automatize the `addpath()' call made by setup_FAUST.<br/>
 For that purpose:

misc/test/src/Python/test_FaustPy.py

@@ -284,10 +284,14 @@ class TestFaustPy(unittest.TestCase):
         FAUST,SPARSE,FULL=0,1,2
         for typeH in range(0,3):
             for cat_axis in [0,1]:
+                if(isinstance(self,TestFaustPyCplx)):
+                    field = 'complex'
+                else:
+                    field = 'real'
                 G = \
                 FaustFactory.rand(self.r.randint(1,TestFaustPy.MAX_NUM_FACTORS),
                                   F.shape[(cat_axis+1)%2],
-                                  is_real=not isinstance(self,TestFaustPyCplx))
+                                  field=field)
                 # add one random factor to get a random number of rows to test
                 # vertcat and a random number of cols to test horzcat
                 if cat_axis == 0:

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

@@ -545,7 +545,7 @@ classdef Faust
 		%> @b Example
 		%> @code
 		%>	import matfaust.FaustFactory
-		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', false)
+		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', 'complex')
 		%>	F_ctrans = F'
 		%>	F_ctrans2 = ctranspose(F)
 		%>	% F_ctrans == F_ctrans2
@@ -588,7 +588,7 @@ classdef Faust
 		%> @b Example
 		%> @code
 		%>	import matfaust.FaustFactory
-		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', false)
+		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', 'complex')
 		%>	F_conj = conj(F)
 		%> @endcode
 		%>
@@ -628,7 +628,7 @@ classdef Faust
 		%> @b Example
 		%> @code
 		%>	import matfaust.FaustFactory
-		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', false)
+		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', 'complex')
 		%>	[nrows, ncols] = size(F)
 		%>	nrows = size(F, 1)
 		%>	ncols = size(F, 2)
@@ -708,7 +708,7 @@ classdef Faust
 		%> @b Example
 		%> @code
 		%>	import matfaust.FaustFactory
-		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', false)
+		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', 'complex')
 		%>	n = numel(F)
 		%> @endcode
 		%>
@@ -797,7 +797,7 @@ classdef Faust
 		%> @b Example
 		%> @code
 		%>	import matfaust.FaustFactory
-		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', false)
+		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', 'complex')
 		%>	f1 = get_factor(F, 1)
 		%> @endcode
 		%> <p>@b See @b also Faust.get_num_factors
@@ -844,7 +844,7 @@ classdef Faust
 		%> @b Example
 		%> @code
 		%>	import matfaust.FaustFactory
-		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', false)
+		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', 'complex')
 		%>	f1 = get_factor_nonopt(F, 1)
 		%> @endcode
 		%> <p>@b See @b also Faust.get_num_factors
@@ -890,7 +890,7 @@ classdef Faust
 		%> @b Example
 		%> @code
 		%>	import matfaust.FaustFactory
-		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', false)
+		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', 'complex')
 		%>	nf = get_num_factors(F)
 		%> @endcode
 		%>
@@ -927,7 +927,7 @@ classdef Faust
 		%> @b Example
 		%> @code
 		%>	import matfaust.*
-		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', false)
+		%>	F = FaustFactory.rand(5, [50, 100], .5, 'mixed', 'complex')
 		%>	save(F, 'F.mat')
 		%>	G = Faust('F.mat')
 		%> @endcode

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

@@ -299,26 +299,25 @@ classdef FaustFactory
 		%>
 		%>
 		%>
-		%> @param num_factors (varargin{1}) If it's an integer it will be the number of random factors to set in the Faust.
+		%> @param num_factors (arg. 1) If it's an integer it will be the number of random factors to set in the Faust.
 		%>                    If num_factors is a vector of 2 integers then the
 		%>                    number of factors will be set randomly between
 		%>                    num_factors(1) and num_factors(2) (inclusively).
-		%> @param dim_sizes (varargin{2}) if it's an integer it will be the order of the square
+		%> @param dim_sizes (arg. 2) if it's an integer it will be the order of the square
 		%> 					matrix factors (of size size_dims^2).
 		%> 					If it's a vector of 2 integers then the
 		%> 					number of rows and columns will
 		%> 					be a random number between size_dims(1) and
 		%> 					size_dims(2) (inclusively).
-		%> @param density	(varargin{3}, optional) the approximate density of factors generated. The default value is 0.1.
+		%> @param density	(arg. 3, optional) the approximate density of factors generated. The default value is 0.1.
 		%> 					It should be a floating point number between 0 and 1.
-		%> @param fac_type	(varargin{4}, optional) the type of factors. Must be
+		%> @param fac_type	(arg. 4, optional) the type of factors. Must be
 		%>                 	'sparse', 'dense' or 'mixed' if you want a mix of dense and
 		%>                  sparse matrices in the generated Faust (choice's done according
 		%>                  to an uniform distribution).
 		%>                  The default value is 'mixed'.
-		%> @param is_real	(varargin{5}, optional) a boolean set to true to generate a real Faust,
-		%>                  set to false to generate a complex Faust.
-		%>                  The default value is true.
+		%> @param field	(arg. 5, optional) 'real' or 'complex' to set the Faust field.
+		%>                  The default value is 'real'.
 		%>
 		%>
 		%>
@@ -328,7 +327,7 @@ classdef FaustFactory
 		%> @code
 		%> % in a matlab terminal
 		%> >> import matfaust.FaustFactory
-		%> >> F = FaustFactory.rand(2, 10, .5, 'mixed', false)
+		%> >> F = FaustFactory.rand(2, 10, .5, 'mixed', 'complex')
 		%>
 		%> F =
 		%>
@@ -413,17 +412,13 @@ classdef FaustFactory
 					end
 					%set the field of factors
 					if(nargin >= 5)
-						if(islogical(varargin{5}))
-							if(varargin{5})
-								field = REAL;
-							else
-								field = COMPLEX;
-							end
+						if(varargin{5} == 'real')
+							field = REAL;
+						elseif(varargin{5} == 'complex')
+							field = COMPLEX;
 						else
-							error('FaustFactory.rand(): the fifth argument (isreal) must be a boolean.')
+							error('FaustFactory.rand(): the fifth argument (isreal) must be ''complex'' or ''real''.')
 						end
-					else
-						field = REAL;
 					end
 				else
 					fac_type = MIXED;

wrapper/python/pyfaust.py

@@ -199,7 +199,7 @@ class Faust:
 
         Examples:
             >>> from pyfaust import FaustFactory
-            >>> F = FaustFactory.rand(2, 50, is_real=False)
+            >>> F = FaustFactory.rand(2, 50, field='complex')
             >>> nrows, ncols = F.shape
             >>> nrows = F.shape[0]
             >>> ncols = F.shape[1]
@@ -225,7 +225,7 @@ class Faust:
 
         Examples:
             >>> from pyfaust import FaustFactory
-            >>> F = FaustFactory.rand(2, 50, is_real=False)
+            >>> F = FaustFactory.rand(2, 50, field='complex')
             >>> size = F.size
 
         <b/> See also Faust.shape
@@ -288,7 +288,7 @@ class Faust:
 
         Examples:
             >>> from pyfaust import FaustFactory
-            >>> F = FaustFactory.rand(5, 50, is_real=False)
+            >>> F = FaustFactory.rand(5, 50, field='complex')
             >>> Fc = F.conj()
 
         <b/> See also Faust.transpose, Faust.getH, Faust.H
@@ -310,7 +310,7 @@ class Faust:
 
         Examples:
             >>> from pyfaust import FaustFactory
-            >>> F = FaustFactory.rand(5, 50, is_real=False)
+            >>> F = FaustFactory.rand(5, 50, field='complex')
             >>> H1 = F.getH()
             >>> H2 = F.transpose()
             >>> H2 = H2.conj()
@@ -336,7 +336,7 @@ class Faust:
 
         Examples:
             >>> from pyfaust import FaustFactory
-            >>> F = FaustFactory.rand(5, 50, is_real=False)
+            >>> F = FaustFactory.rand(5, 50, field='complex')
             >>> H1 = F.H
             >>> H2 = F.transpose()
             >>> H2 = H2.conj()
@@ -1032,7 +1032,7 @@ class Faust:
 
         Examples:
             >>> from pyfaust import FaustFactory, Faust
-            >>> F = FaustFactory.rand([2, 3], [10, 20],.5, is_real=False)
+            >>> F = FaustFactory.rand([2, 3], [10, 20],.5, field='complex')
             >>> F.save("F.mat")
             >>> G = Faust(filepath="F.mat")
 
@@ -1063,7 +1063,7 @@ class Faust:
 
         Examples:
             >>> from pyfaust import FaustFactory
-            >>> F = FaustFactory.rand([2, 3], [10, 20],.5, is_real=False)
+            >>> F = FaustFactory.rand([2, 3], [10, 20],.5, field='complex')
             dtype('complex128')
             >>> F = FaustFactory.rand([2, 3], [10, 20],.5)
             dtype('float64')
@@ -1278,7 +1278,7 @@ class FaustFactory:
 
     @staticmethod
     def rand(num_factors, dim_sizes, density=0.1, fac_type="mixed",
-                  is_real=True):
+                  field='real'):
         """
         Generates a random Faust.
 
@@ -1301,16 +1301,15 @@ class FaustFactory:
                 sparse matrices in the generated Faust (choice's done according
                 to an uniform distribution).
                             The default value is "mixed".
-                is_real: (optional) a boolean set to True to generate a real Faust,
-                        set to False to generate a complex Faust. The default value
-                        is True.
+                field: (optional) a str to set the Faust field: 'real' or
+                'complex'. By default, the value is 'real'.
 
         Returns:
             the random Faust.
 
         Examples:
             >>> from pyfaust import FaustFactory
-            >>> F = FaustFactory.rand(2, 10, .5, is_real=False)
+            >>> F = FaustFactory.rand(2, 10, .5, field='complex')
             >>> G = FaustFactory.rand([2, 5], [10, 20], .5, fac_type="dense")
             >>> F
             Faust size 10x10, density 0.99, nnz_sum 99, 2 factors:<br/>
@@ -1325,6 +1324,12 @@ class FaustFactory:
 
         <b/> See also Faust.__init__
         """
+        if(field == 'real'):
+            is_real = True
+        elif(field == 'complex'):
+            is_real = False
+        else:
+            raise ValueError('field argument must be either "real" or "complex".')
         DENSE=0
         SPARSE=1
         MIXED=2