Move functions dft, wht, eye and rand from FaustFactory to pyfaust package...

Move functions dft, wht, eye and rand from FaustFactory to pyfaust package root, update tests, documentation and notebooks to respect this change.

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 ParamsHierarchicalFactSquareMat.m ParamsHierarchicalFactRectMat.m license.m omp.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 license.m omp.m wht.m dft.m eye.m rand.m")
 		endif()
 		if(BUILD_WRAPPER_PYTHON)
 			string(CONCAT DOXYGEN_FILE_PATTERNS ${DOXYGEN_FILE_PATTERNS} " __init__.py factparams.py demo.py tools.py")

misc/test/src/Matlab/FaustFactoryTest.m

@@ -237,11 +237,11 @@ classdef FaustFactoryTest < matlab.unittest.TestCase
 		end
 
 		function testHadamard(this)
-			disp('Test FaustFactory.wht()')
+			disp('Test matfaust.wht()')
 			import matfaust.*
 			log2n = randi([1,6]);
 			n = 2^log2n;
-			H = FaustFactory.wht(n, false);
+			H = wht(n, false);
 			fH = full(H);
 			this.verifyEqual(nnz(fH), numel(fH));
 			i = 1;
@@ -253,20 +253,20 @@ classdef FaustFactoryTest < matlab.unittest.TestCase
 				end
 				i = i + 1;
 			end
-			this.assertEqual(full(FaustFactory.wht(n)), full(normalize(FaustFactory.wht(n, false))), 'AbsTol', 10^-12)
+			this.assertEqual(full(wht(n)), full(normalize(H)), 'AbsTol', 10^-7)
 		end
 
 		function testFourier(this)
-			disp('Test FaustFactory.dft()')
-			import matfaust.*
+			disp('Test matfaust.dft()')
+			import matfaust.dft
 			log2n = randi([1,10]);
 			n = 2^log2n;
-			F = FaustFactory.dft(n, false);
+			F = dft(n, false);
 			fF = full(F);
 			fftI = fft(eye(n));
 			% this.verifyEqual(nnz(fH), numel(fH));
 			this.verifyEqual(norm(fF-fftI), 0, 'AbsTol', 10^-12);
-			this.assertEqual(full(FaustFactory.dft(n)), full(normalize(FaustFactory.dft(n, false))), 'AbsTol', 10^-12)
+			this.assertEqual(full(dft(n)), full(normalize(F)), 'AbsTol', 10^-7)
 		end
 	end
 

misc/test/src/Matlab/FaustTest.m

@@ -408,8 +408,8 @@ classdef FaustTest < matlab.unittest.TestCase
 			this.assertLessThan(norm(full(F'*r)-full(F)'*r)/norm(full(F)'*r), eps(1.))
 			this.assertLessThan(norm(full(F.'*r)-full(F).'*r)/norm(full(F).'*r), eps(1.))
 			disp('test mul of two Fausts')
-			r_fausts = {matfaust.FaustFactory.rand(randi(100), size(F,2)),
-			matfaust.FaustFactory.rand(randi(100), size(F,2), .5, 'complex')};
+			r_fausts = {matfaust.rand(randi(100), size(F,2)),
+			matfaust.rand(randi(100), size(F,2), .5, 'complex')};
 			for ii=1:length(r_fausts)
 				rF = r_fausts{ii};
 				test_rF = full(F*rF);
@@ -448,7 +448,7 @@ classdef FaustTest < matlab.unittest.TestCase
 			disp('test plus(Faust1,Faust2)')
 			import matfaust.FaustFactory
 			import matfaust.Faust
-			fausts = {FaustFactory.rand(5,size(F,1))*Faust(rand(size(F,1),size(F,2))), FaustFactory.rand(5,size(F,1), .5, 'complex')*Faust(rand(size(F,1),size(F,2)))}
+			fausts = {matfaust.rand(5,size(F,1))*Faust(rand(size(F,1),size(F,2))), matfaust.rand(5,size(F,1), .5, 'complex')*Faust(rand(size(F,1),size(F,2)))}
 			for i=1:length(fausts)
 				F2 = fausts{i}
 				this.verifyEqual(full(F+F2),full(F)+full(F2),'RelTol', 10^-2)
@@ -469,7 +469,7 @@ classdef FaustTest < matlab.unittest.TestCase
 			disp('test minus(Faust1,Faust2)')
 			import matfaust.FaustFactory
 			import matfaust.Faust
-			fausts = {FaustFactory.rand(5,size(F,1))*Faust(rand(size(F,1),size(F,2)))} %, FaustFactory.rand(5,size(F,1), .5, 'complex')*rand(size(F,2),size(F,2))} %TODO: re-enable complex Faust when #72 is solved
+			fausts = {matfaust.rand(5,size(F,1))*Faust(rand(size(F,1),size(F,2)))} %, matfaust.rand(5,size(F,1), .5, 'complex')*rand(size(F,2),size(F,2))} %TODO: re-enable complex Faust when #72 is solved
 			for i=1:length(fausts)
 				F2 = fausts{i}
 				this.verifyEqual(full(F-F2),full(F)-full(F2),'RelTol', 10^-2)
@@ -477,17 +477,18 @@ classdef FaustTest < matlab.unittest.TestCase
 		end
 
 		function testcat(this)
-			import matfaust.*
+			import matfaust.rand
+			import matfaust.Faust
 			disp('Test cat')
-			FAUST=0
-			SPARSE=1
-			FULL=2
+			FAUST=0;
+			SPARSE=1;
+			FULL=2;
 			for typeG=0:2
 				for dimcat=1:2
 					other_dim = mod(dimcat,2)+1;
 					F = this.test_faust;
 					%=============== test vert (or horz) cat
-					G = FaustFactory.rand(randi(FaustTest.MAX_NUM_FACTORS), size(F,other_dim));
+					G = matfaust.rand(randi(FaustTest.MAX_NUM_FACTORS), size(F,other_dim));
 					G_num_factors = numfactors(G);
 					% set a Faust with a random number of rows (or cols) from G
 					H_facs = cell(1,G_num_factors+1);

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

@@ -23,33 +23,12 @@
 %>
 %>    - The third group of algorithms is for FGFT computing: FaustFactory.fgft_palm FaustFactory.fgft_givens FaustFactory.eigtj
 %>
-%>    A more secondary functionality of this class is the Faust generation.
-%>    Several methods are available:
-%>
-%>    - The pseudo-random generation of a Faust with FaustFactory.rand(),
-%>    - the discrete Fourier transform with FaustFactory.dft(),
-%>    - the Hadamard transform with FaustFactory.wht(),
-%>    - and the identity Faust with FaustFactory.eye().
 %>
 % ======================================================================
 
 classdef FaustFactory
 	properties (SetAccess = public)
 
-	end
-	properties(SetAccess = private, Hidden = true, Constant)
-			%> Identifies a complex Faust.
-			COMPLEX=3;
-			%> Identifies a real Faust.
-			REAL=4;
-			% Constants to identify kind of factors to generate
-			%> Designates a dense factor matrix
-			DENSE=0;
-			%> Designates a dense factor matrix
-			SPARSE=1;
-			%> Means DENSE or SPARSE
-			MIXED=2;
-
 	end
 	methods(Static)
 
@@ -321,9 +300,9 @@ classdef FaustFactory
 			[F, lambda ] = FaustFactory.fact_palm4msa(M, p);
 			f1 = factors(F, 1);
 			f1 = f1 / lambda;
-			nF = cell(1, get_num_factors(F));
+			nF = cell(1, numfactors(F));
 			nF{1} = f1;
-			for i=2:get_num_factors(F)
+			for i=2:numfactors(F)
 				nF{i} = factors(F, i);
 			end
 			nF{2} = nF{2}*lambda;
@@ -390,9 +369,9 @@ classdef FaustFactory
 			[F, lambda, p] = FaustFactory.fact_hierarchical(M, p);
 			f1 = factors(F, 1);
 			f1 = f1 / lambda;
-			nF = cell(1, get_num_factors(F));
+			nF = cell(1, numfactors(F));
 			nF{1} = f1;
-			for i=2:get_num_factors(F)
+			for i=2:numfactors(F)
 				nF{i} = factors(F, i);
 			end
 			nF{2} = nF{2}*lambda;
@@ -665,7 +644,7 @@ classdef FaustFactory
 		%==========================================================================================
 		function [V,D] = eigtj(M, J, varargin)
 			[V, D] = matfaust.FaustFactory.fgft_givens(M, J, varargin{:});
-			V = factors(V,1:get_num_factors(V))
+			V = factors(V,1:numfactors(V))
 			% copy seems unecessary but it's to workaround a bug (temporarily)
 		end
 
@@ -707,440 +686,6 @@ classdef FaustFactory
 			V = W2(:,1:size(Id,1))*matfaust.Faust(Id(:,I));
 		end
 
-		%==========================================================================================
-		%> @brief Constructs a Faust implementing the Walsh-Hadamard Transform of order n.
-		%>
-		%> The resulting Faust has log2(n) sparse factors of order n, each one having 2 non-zero elements
-		%> per row and per column.
-		%>
-		%> @b Usage
-		%>
-		%> &nbsp;&nbsp;&nbsp; @b H = wht(n) <br/>
-		%> &nbsp;&nbsp;&nbsp; @b H = wht(n, norma)
-		%>
-		%> @param n the power of two exponent for a Hadamard matrix of order n and a factorization into log2(n) factors.
-		%> @param norma: (optional) true (by default) to normalize the returned Faust as if Faust.normalize() was called, false otherwise.
-		%>
-		%> @retval H the Faust implementing the Hadamard transform of dimension n.
-		%>
-		%> @b Example
-		%> @code
-		%> % in a matlab terminal
-		%> >> import matfaust.FaustFactory.*
-		%> >> H = wht(1024) % is equal to
-		%> >> H = normalize(wht(1024, false))
-		%> @endcode
-		%>
-		%>
-		%>H =
-		%>
-		%>Faust size 1024x1024, density 0.0195312, nnz_sum 20480, 10 factor(s):
-		%>- FACTOR 0 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%>- FACTOR 1 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%>- FACTOR 2 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%>- FACTOR 3 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%>- FACTOR 4 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%>- FACTOR 5 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%>- FACTOR 6 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%>- FACTOR 7 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%>- FACTOR 8 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%>- FACTOR 9 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%>
-		%==========================================================================================
-		function H = wht(n, varargin)
-			% check n (must be integer > 0)
-			if(~ isreal(n) || n < 0 || abs(n-floor(n)) > 0)
-				error('n must be an integer greater than zero')
-			end
-			log2n = floor(log2(n));
-			if(2^log2n < n)
-				error('n must be a power of 2')
-			end
-			if(log2n > 31)
-				error('Can''t handle a Hadamard Faust of order larger than 2^31')
-			end
-			if(length(varargin) > 0)
-				if(~ islogical(varargin{1}))
-					error('wht optional second argument must be a boolean');
-				end
-				norma = varargin{1};
-			else
-				norma = true; % normalization by default
-			end
-			core_obj = mexFaustReal('hadamard', log2n, norma);
-			is_real = true;
-			e = MException('FAUST:OOM', 'Out of Memory');
-			if(core_obj == 0)
-				throw(e)
-			end
-			H = matfaust.Faust(core_obj, is_real);
-		end
-
-		%==========================================================================================
-		%> @brief Constructs a Faust whose the full matrix is the Discrete Fourier Transform square matrix of order n.
-		%>
-		%> The factorization algorithm used is Cooley-Tukey (FFT).
-		%>
-		%> The resulting Faust is complex and has log2(n)+1 sparse factors whose the log2(n) first
-		%> have 2 nonzero elements per row and per column. The last factor is a permutation matrix.
-		%>
-		%>
-		%> @b Usage
-		%>
-		%> &nbsp;&nbsp;&nbsp; @b F = dft(n) <br/>
-		%> &nbsp;&nbsp;&nbsp; @b F = dft(n, norma)
-		%>
-		%> @param n: the power of two for a FFT of order n and a factorization in log2(n)+1 factors.
-		%> @param norma: (optional) true (by default) to normalize the returned Faust as if Faust.normalize() was called, false otherwise.
-		%>
-		%>
-		%> @retval F the Faust implementing the FFT transform of dimension n.
-		%>
-		%> @b Example
-		%> @code
-		%> % in a matlab terminal
-		%> >> import matfaust.FaustFactory.*
-		%> >> F = dft(1024) % is equal to
-		%> >> F = normalize(dft(1024))
-		%> @endcode
-		%>
-		%>
-		%> F =
-		%>
-		%> Faust size 1024x1024, density 0.0205078, nnz_sum 21504, 11 factor(s):
-		%> - FACTOR 0 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%> - FACTOR 1 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%> - FACTOR 2 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%> - FACTOR 3 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%> - FACTOR 4 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%> - FACTOR 5 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%> - FACTOR 6 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%> - FACTOR 7 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%> - FACTOR 8 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%> - FACTOR 9 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
-		%> - FACTOR 10 (complex) SPARSE, size 1024x1024, density 0.000976562, nnz 1024
-		%==========================================================================================
-		function F = dft(n, varargin)
-			% check n (must be integer > 0)
-			if(~ isreal(n) || n < 0 || abs(n-floor(n)) > 0)
-				error('n must be an integer greater than zero')
-			end
-			log2n = floor(log2(n));
-			if(2^log2n < n)
-				error('n must be a power of 2')
-			end
-			if(log2n>31)
-				error('Can''t handle a FFT Faust of order larger than 2^31')
-			end
-			if(length(varargin) > 0)
-				if(~ islogical(varargin{1}))
-					error('wht optional second argument must be a boolean');
-				end
-				norma = varargin{1};
-			else
-				norma = true; % normalization by default
-			end
-			core_obj = mexFaustCplx('fourier', log2n, norma);
-			is_real = false;
-			e = MException('FAUST:OOM', 'Out of Memory');
-			if(core_obj == 0)
-				throw(e)
-			end
-			F = matfaust.Faust(core_obj, is_real);
-		end
-
-		%==========================================================================================
-		%> @brief Faust identity.
-		%>
-		%> @b Usage
-		%>
-		%> &nbsp;&nbsp;&nbsp; @b FaustFactory.eye(m,n) or FaustFactory.eye([m,n]) forms a M-by-N Faust F = Faust(speye(M,N)).<br/>
-		%> &nbsp;&nbsp;&nbsp; @b FaustFactory.eye(m) is a short for FaustFactory.eye(m,n).<br/>
-		%> &nbsp;&nbsp;&nbsp; @b FaustFactory.eye(S, 'complex') or FaustFactory.eye(S, 'complex') or FaustFactory.eye(S, 'complex') with S the size, does the same as above but returns a complex Faust.</br>
-		%>
-		%> @b Example
-		%> @code
-		%> % in a matlab terminal
-		%>>> import matfaust.FaustFactory
-		%>>> FaustFactory.eye(4)
-		%>
-		%>ans =
-		%>
-		%>Faust size 4x4, density 0.25, nnz_sum 4, 1 factor(s):
-		%>- FACTOR 0 (real) SPARSE, size 4x4, density 0.25, nnz 4
-		%>
-		%>>> full(FaustFactory.eye(4))
-		%>
-		%>ans =
-		%>
-		%>     1     0     0     0
-		%>     0     1     0     0
-		%>     0     0     1     0
-		%>     0     0     0     1
-		%>
-		%>>> full(FaustFactory.eye(4,5))
-		%>
-		%>ans =
-		%>
-		%>     1     0     0     0     0
-		%>     0     1     0     0     0
-		%>     0     0     1     0     0
-		%>     0     0     0     1     0
-		%>
-		%>>> full(FaustFactory.eye([5,4]))
-		%>
-		%>ans =
-		%>
-		%>     1     0     0     0
-		%>     0     1     0     0
-		%>     0     0     1     0
-		%>     0     0     0     1
-		%>     0     0     0     0
-		%>
-		%>>> full(FaustFactory.eye([5,4],'complex'))
-		%>
-		%>ans =
-		%>
-		%>   1.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i
-		%>   0.0000 + 0.0000i   1.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i
-		%>   0.0000 + 0.0000i   0.0000 + 0.0000i   1.0000 + 0.0000i   0.0000 + 0.0000i
-		%>   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   1.0000 + 0.0000i
-		%>   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i
-		%>
-		%>>> full(FaustFactory.eye([4],'complex'))
-		%>
-		%>ans =
-		%>
-		%>   1.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i
-		%>   0.0000 + 0.0000i   1.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i
-		%>   0.0000 + 0.0000i   0.0000 + 0.0000i   1.0000 + 0.0000i   0.0000 + 0.0000i
-		%>   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   1.0000 + 0.0000i
-		%> @endcode
-		%>
-		%==========================================================================================
-		function F = eye(varargin)
-			if(nargin < 1)
-				error('First argument is mandatory')
-			end
-			import matfaust.Faust
-			if(ismatrix(varargin{1}))
-				shape = varargin{1};
-				ndim = size(shape,2);
-				nrows = size(shape,1);
-				if(ndim > 2)
-					error('N-dimensional arrays are not supported.')
-				elseif(nrows > 1)
-					error('Size vector should be a row vector with real elements.')
-				elseif(ndim == 2)
-					m = shape(1);
-					n = shape(2);
-				elseif(ndim == 1)
-					m = varargin{1};
-					if(nargin > 1 && isnumeric(varargin{2}))
-						n = varargin{2};
-					else
-						n = m;
-					end
-				else
-					error('Size vector should be a row vector with real elements.')
-				end
-			else
-				error('Size inputs must be numeric.')
-			end
-			la = varargin{nargin};
-			if(nargin ~= 1 && ~ isnumeric(la) && (ischar(la) || ischar(cell2mat(la))))
-				% F = Faust(sparse(1:m, 1:n, 1+eps(1)*j)); % hack to avoid passing through a full matrix
-				if(strcmp(la,'complex'))
-					F = Faust(eye(m,n,'like', sparse(1,1,1+i)));
-				elseif(strcmp(la, 'real'))
-					F = Faust(speye(m,n));
-				else
-					if(iscell(la))
-						la = cell2mat(la)
-					end
-					error(['Unknown option: ' la])
-				end
-			else
-				F = Faust(speye(m,n));
-			end
-		end
-
-
-		%==========================================================================================
-		%> @brief Generates a random Faust.
-		%>
-		%> @b Usage
-		%>
-		%> &nbsp;&nbsp;&nbsp; @b FaustFactory.rand(N,S) with N and S two integers, generates a Faust of N factors. All factors are square matrices of order S. The type of factors (dense or sparse) is a random choice.
-		%>
-		%> &nbsp;&nbsp;&nbsp; @b FaustFactory.rand([N1,N2],S) same as above except that here the number of factors is randomly chosen between N1 and N2 inclusively.
-		%>
-		%> &nbsp;&nbsp;&nbsp; @b FaustFactory.rand([N1,N2],[S1, S2]) or @b FaustFactory.rand(N, [S1, S2]) same as above except that here the factor matrices have random sizes; the number of rows and columns are both randomly chosen between S1 and S2 inclusively.
-		%>
-		%> &nbsp;&nbsp;&nbsp; @b FaustFactory.rand(N, S, D) or @b FaustFactory.rand([N1, N2], [S1, S2], D) same as above but specifying D the approximate density of each factor.
-		%>
-		%> &nbsp;&nbsp;&nbsp; @b FaustFactory.rand(@b N, @b S, @b {D, @b 'per_row'}) or @b FaustFactory.rand([@b N1, @b N2], [@b S1, @b S2], {@b D, @b 'per_row'}) same as above but specifying D, the density of each factor per row ('per_row') or per column ('per_col').
-		%>
-		%> &nbsp;&nbsp;&nbsp; @b @b FaustFactory\.rand(N, @b S, @b D, @b 'dense') or @b FaustFactory\.rand(@b [@b  N1, @b N2], [@b S1, @b S2], @b D, @b 'dense') same as above but generating only dense matrices as factors.
-		%>
-		%> &nbsp;&nbsp;&nbsp; @b FaustFactory\.rand(@b N, @b S, @b D, @b 'sparse') or @b FaustFactory\.rand([@b N1, @b N2], [@b S1, @b S2], @b D, @b 'sparse') same as above but generating only sparse matrices as factors.
-		%>
-		%> &nbsp;&nbsp;&nbsp; @b FaustFactory\.rand(@b N, @b S, @b D, @b 'sparse', @b 'complex'), @b FaustFactory\.rand([@b N1, @b N2], [@b S1, @b S2], @b D, @b 'sparse', @b false), FaustFactory\.rand(@b N, @b S, @b D, @b 'dense', @b 'complex') or @b FaustFactory\.rand([@b N1, @b N2], [@b S1, @b S2], @b D, @b 'dense', @b 'complex') same as above but generating a complex Faust, that is, matrices defined over the complex field.
-		%>
-		%>
-		%>
-		%>
-		%>
-		%>
-		%>
-		%> @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 (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	(arg. 3, optional) the approximate density of factors generated.
-		%> 					It should be a floating point number between 0 and 1.
-		%>					This argument can also be a cell array {D, 'per_row'} or {D, 'per_col'} to specify the density per row or per column.
-		%>					By default the density is set per row and is such that the Faust's factors will have 5 non-zero elements per row.
-		%> @param fac_type	(arg. 4 or 5, 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 field	(arg. 4 or 5, optional) 'real' or 'complex' to set the Faust field.
-		%>                  The default value is 'real'.
-		%>
-		%>
-		%>
-		%> @retval F the random Faust.
-		%>
-		%> @b Example @b 1
-		%> @code
-		%> % in a matlab terminal
-		%> >> import matfaust.FaustFactory
-		%> >> F = FaustFactory.rand(2, 10, .5, 'mixed', 'complex')
-		%>
-		%> F =
-		%>
-		%> Faust size 10x10, density 1, nnz_sum 100, 2 factor(s):
-		%> - FACTOR 0 (complex) SPARSE, size 10x10, density 0.5, nnz 50
-		%> - FACTOR 1 (complex) DENSE, size 10x10, density 0.5, nnz 50
-		%> @endcode
-		%> @b Example @b 2
-		%> @code
-		%> >> import matfaust.FaustFactory
-		%> >> G = FaustFactory.rand([2, 5], [10, 20], .5, 'dense')
-		%>
-		%> G =
-		%>
-		%> Faust size 19x18, density 0.973684, nnz_sum 333, 3 factor(s):
-		%> - FACTOR 0 (real) DENSE, size 19x12, density 0.5, nnz 114
-		%> - FACTOR 1 (real) DENSE, size 12x15, density 0.466667, nnz 84
-		%> - FACTOR 2 (real) DENSE, size 15x18, density 0.5, nnz 135
-		%>
-		%> @endcode
-		%>
-		%> <p>@b See @b also Faust.Faust.
-		%==========================================================================================
-		function F = rand(varargin)
-			import matfaust.FaustFactory
-			if(nargin < 2)
-				error('FaustFactory.rand(): the number of arguments must be at least 2.')
-			end
-			% set num of factors
-			num_factors = varargin{1};
-			dim_sizes = varargin{2};
-			if(isscalar(num_factors) && mod(num_factors,1) == 0)
-				min_num_factors = num_factors;
-				max_num_factors = num_factors;
-			elseif(ismatrix(num_factors) && size(num_factors, 1) == 1 && size(num_factors, 2) == 2)
-				min_num_factors = num_factors(1);
-				max_num_factors = num_factors(2);
-			else
-				error('FaustFactory.rand(): the argument 1 (num_factors) must be an integer or a vector of two integers.')
-			end
-			% set sizes of factors
-			if(isscalar(dim_sizes) && mod(dim_sizes, 1) == 0)
-				min_dim_size = dim_sizes;
-				max_dim_size = dim_sizes;
-			elseif(ismatrix(dim_sizes) && size(dim_sizes,1) == 1 && size(dim_sizes,2) == 2)
-				min_dim_size = dim_sizes(1);
-				max_dim_size = dim_sizes(2);
-			else
-				error('FaustFactory.rand(): the argument 2 (dim_sizes) must be an integer or a vector of two integers.')
-			end
-			field = FaustFactory.REAL;
-			fac_type = FaustFactory.MIXED;
-			per_row = true;
-			density = -1; % default density: 5 elements per row or per column for each factor
-			err_dens_not_num = 'FaustFactory.rand(): the argument 3 (density) must be a real number in [0;1] or a cell array of length 2 with density at first and ''per_row'' or ''per_col'' char array in second cell.';
-			if(nargin >= 3)
-				if(isscalar(varargin{3}) && isreal(varargin{3}))
-					density = varargin{3};
-				elseif(iscell(varargin{3}))
-					density_cell = varargin{3};
-					if(isreal(density_cell{1}))
-						density = density_cell{1};
-						if(length(density_cell) >= 2)
-							if(strcmp(density_cell{2}, 'per_row'))
-								per_row = true;
-							elseif(strcmp(density_cell{2}, 'per_col'))
-								per_row = false;
-							else
-								error('FaustFactory.rand(): when argument 3 (density) is a cell the first cell element must be a real number into [0;1] and the second a char array ''per_row'' or ''per_row''.')
-							end
-						end
-					else
-						error(err_dens_not_num)
-					end
-				else
-					error(err_dens_not_num)
-				end
-				if(nargin >= 4)
-					for i=4:nargin
-						% set repr. type of factors ('sparse', 'dense', 'mixed') and field ('real' or 'complex')
-						if(nargin >= i)
-							err_unknown_arg4or5 = ['FaustFactory.rand(): the argument ' int2str(i) ' (fac_type) must be among a character array among ''sparse'', ''dense'', ''mixed'', ''real'', or ''complex''.'];
-							if(ischar(varargin{i}))
-								if(strcmp(varargin{i}, 'sparse'))
-									fac_type = FaustFactory.SPARSE;
-								elseif(strcmp(varargin{i},'dense'))
-									fac_type = FaustFactory.DENSE;
-								elseif(strcmp(varargin{i},'mixed'))
-									fac_type = FaustFactory.MIXED;
-								elseif(strcmp(varargin{i}, 'real'))
-									field = FaustFactory.REAL;
-								elseif(strcmp(varargin{i},'complex'))
-									field = FaustFactory.COMPLEX;
-								else
-									error(err_unknown_arg4or5)
-								end
-							else
-								error(err_unknown_arg4or5)
-							end
-						end
-					end
-				end
-			end
-			e = MException('FAUST:OOM', 'Out of Memory');
-			if(field == FaustFactory.COMPLEX)
-				core_obj = mexFaustCplx('rand', fac_type, min_num_factors, max_num_factors, min_dim_size, max_dim_size, density, per_row);
-				is_real = false;
-			else %if(field == FaustFactory.REAL)
-				core_obj = mexFaustReal('rand', fac_type, min_num_factors, max_num_factors, min_dim_size, max_dim_size, density, per_row);
-				is_real = true;
-			end
-			if(core_obj == 0)
-				throw(e)
-			end
-			F = matfaust.Faust(core_obj, is_real);
-		end
-
 	end
 	methods(Access = private, Static)
 		function check_fact_mat(funcname, M)

wrapper/matlab/+matfaust/dft.m

+%==========================================================================================
+%> @brief Constructs a Faust whose the full matrix is the Discrete Fourier Transform square matrix of order n.
+%>
+%> The factorization algorithm used is Cooley-Tukey (FFT).
+%>
+%> The resulting Faust is complex and has log2(n)+1 sparse factors whose the log2(n) first
+%> have 2 nonzero elements per row and per column. The last factor is a permutation matrix.
+%>
+%>
+%> @b Usage
+%>
+%> &nbsp;&nbsp;&nbsp; @b F = dft(n) <br/>
+%> &nbsp;&nbsp;&nbsp; @b F = dft(n, norma)
+%>
+%> @param n: the power of two for a FFT of order n and a factorization in log2(n)+1 factors.
+%> @param norma: (optional) true (by default) to normalize the returned Faust as if Faust.normalize() was called, false otherwise.
+%>
+%>
+%> @retval F the Faust implementing the FFT transform of dimension n.
+%>
+%> @b Example
+%> @code
+%> % in a matlab terminal
+%> >> import matfaust.*
+%> >> F = dft(1024) % is equal to
+%> >> F = normalize(dft(1024))
+%> @endcode
+%>
+%>
+%> F =
+%>
+%> Faust size 1024x1024, density 0.0205078, nnz_sum 21504, 11 factor(s):
+%> - FACTOR 0 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%> - FACTOR 1 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%> - FACTOR 2 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%> - FACTOR 3 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%> - FACTOR 4 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%> - FACTOR 5 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%> - FACTOR 6 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%> - FACTOR 7 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%> - FACTOR 8 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%> - FACTOR 9 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%> - FACTOR 10 (complex) SPARSE, size 1024x1024, density 0.000976562, nnz 1024
+%==========================================================================================
+function F = dft(n, varargin)
+	% check n (must be integer > 0)
+	if(~ isreal(n) || n < 0 || abs(n-floor(n)) > 0)
+		error('n must be an integer greater than zero')
+	end
+	log2n = floor(log2(n));
+	if(2^log2n < n)
+		error('n must be a power of 2')
+	end
+	if(log2n>31)
+		error('Can''t handle a FFT Faust of order larger than 2^31')
+	end
+	if(length(varargin) > 0)
+		if(~ islogical(varargin{1}))
+			error('wht optional second argument must be a boolean');
+		end
+		norma = varargin{1};
+	else
+		norma = true; % normalization by default
+	end
+	core_obj = mexFaustCplx('fourier', log2n, norma);
+	is_real = false;
+	e = MException('FAUST:OOM', 'Out of Memory');
+	if(core_obj == 0)
+		throw(e)
+	end
+	F = matfaust.Faust(core_obj, is_real);
+end

wrapper/matlab/+matfaust/eye.m

+%==========================================================================================
+%> @brief Faust identity.
+%>
+%> @b Usage
+%>
+%> &nbsp;&nbsp;&nbsp; @b eye(m,n) or eye([m,n]) forms a M-by-N Faust F = Faust(speye(M,N)).<br/>
+%> &nbsp;&nbsp;&nbsp; @b eye(m) is a short for eye(m,n).<br/>
+%> &nbsp;&nbsp;&nbsp; @b eye(S, 'complex') or eye(S, 'complex') or eye(S, 'complex') with S the size, does the same as above but returns a complex Faust.</br>
+%>
+%> @b Example
+%> @code
+%> % in a matlab terminal
+%>>> matfaust.eye(4)
+%>
+%>ans =
+%>
+%>Faust size 4x4, density 0.25, nnz_sum 4, 1 factor(s):
+%>- FACTOR 0 (real) SPARSE, size 4x4, density 0.25, nnz 4
+%>
+%>>> full(matfaust.eye(4))
+%>
+%>ans =
+%>
+%>     1     0     0     0
+%>     0     1     0     0
+%>     0     0     1     0
+%>     0     0     0     1
+%>
+%>>> full(matfaust.eye(4,5))
+%>
+%>ans =
+%>
+%>     1     0     0     0     0
+%>     0     1     0     0     0
+%>     0     0     1     0     0
+%>     0     0     0     1     0
+%>
+%>>> full(matfaust.eye([5,4]))
+%>
+%>ans =
+%>
+%>     1     0     0     0
+%>     0     1     0     0
+%>     0     0     1     0
+%>     0     0     0     1
+%>     0     0     0     0
+%>
+%>>> full(matfaust.eye([5,4],'complex'))
+%>
+%>ans =
+%>
+%>   1.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i
+%>   0.0000 + 0.0000i   1.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i
+%>   0.0000 + 0.0000i   0.0000 + 0.0000i   1.0000 + 0.0000i   0.0000 + 0.0000i
+%>   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   1.0000 + 0.0000i
+%>   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i
+%>
+%>>> full(matfaust.eye([4],'complex'))
+%>
+%>ans =
+%>
+%>   1.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i
+%>   0.0000 + 0.0000i   1.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i
+%>   0.0000 + 0.0000i   0.0000 + 0.0000i   1.0000 + 0.0000i   0.0000 + 0.0000i
+%>   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   1.0000 + 0.0000i
+%> @endcode
+%>
+%==========================================================================================
+function F = eye(varargin)
+	if(nargin < 1)
+		error('First argument is mandatory')
+	end
+	import matfaust.Faust
+	if(ismatrix(varargin{1}))
+		shape = varargin{1};
+		ndim = size(shape,2);
+		nrows = size(shape,1);
+		if(ndim > 2)
+			error('N-dimensional arrays are not supported.')
+		elseif(nrows > 1)
+			error('Size vector should be a row vector with real elements.')
+		elseif(ndim == 2)
+			m = shape(1);
+			n = shape(2);
+		elseif(ndim == 1)
+			m = varargin{1};
+			if(nargin > 1 && isnumeric(varargin{2}))
+				n = varargin{2};
+			else
+				n = m;
+			end
+		else
+			error('Size vector should be a row vector with real elements.')
+		end
+	else
+		error('Size inputs must be numeric.')
+	end
+	la = varargin{nargin};
+	if(nargin ~= 1 && ~ isnumeric(la) && (ischar(la) || ischar(cell2mat(la))))
+		% F = Faust(sparse(1:m, 1:n, 1+eps(1)*j)); % hack to avoid passing through a full matrix
+		if(strcmp(la,'complex'))
+			F = Faust(eye(m,n,'like', sparse(1,1,1+i)));
+		elseif(strcmp(la, 'real'))
+			F = Faust(speye(m,n));
+		else
+			if(iscell(la))
+				la = cell2mat(la)
+			end
+			error(['Unknown option: ' la])
+		end
+	else
+		F = Faust(speye(m,n));
+	end
+end

wrapper/matlab/+matfaust/rand.m

+%==========================================================================================
+%> @brief Generates a random Faust.
+%>
+%> @b Usage
+%>
+%>     @b rand(N,S) with N and S two integers, generates a Faust of N factors. All factors are square matrices of order S. The type of factors (dense or sparse) is a random choice.
+%>
+%>     @b rand([N1,N2],S) same as above except that here the number of factors is randomly chosen between N1 and N2 inclusively.
+%>
+%>     @b rand([N1,N2],[S1, S2]) or @b rand(N, [S1, S2]) same as above except that here the factor matrices have random sizes; the number of rows and columns are both randomly chosen between S1 and S2 inclusively.
+%>
+%>     @b rand(N, S, D) or @b rand([N1, N2], [S1, S2], D) same as above but specifying D the approximate density of each factor.
+%>
+%>     @b rand(@b N, @b S, @b {D, @b 'per_row'}) or @b rand([@b N1, @b N2], [@b S1, @b S2], {@b D, @b 'per_row'}) same as above but specifying D, the density of each factor per row ('per_row') or per column ('per_col').
+%>
+%>     @b @b rand(N, @b S, @b D, @b 'dense') or @b rand(@b [@b  N1, @b N2], [@b S1, @b S2], @b D, @b 'dense') same as above but generating only dense matrices as factors.
+%>
+%>     @b rand(@b N, @b S, @b D, @b 'sparse') or @b rand([@b N1, @b N2], [@b S1, @b S2], @b D, @b 'sparse') same as above but generating only sparse matrices as factors.
+%>
+%>     @b rand(@b N, @b S, @b D, @b 'sparse', @b 'complex'), @b rand([@b N1, @b N2], [@b S1, @b S2], @b D, @b 'sparse', @b false), rand(@b N, @b S, @b D, @b 'dense', @b 'complex') or @b rand([@b N1, @b N2], [@b S1, @b S2], @b D, @b 'dense', @b 'complex') same as above but generating a complex Faust, that is, matrices defined over the complex field.
+%>
+%>
+%>
+%>
+%>
+%>
+%>
+%> @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 (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	(arg. 3, optional) the approximate density of factors generated.
+%> 					It should be a floating point number between 0 and 1.
+%>					This argument can also be a cell array {D, 'per_row'} or {D, 'per_col'} to specify the density per row or per column.
+%>					By default the density is set per row and is such that the Faust's factors will have 5 non-zero elements per row.
+%> @param fac_type	(arg. 4 or 5, 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 field	(arg. 4 or 5, optional) 'real' or 'complex' to set the Faust field.
+%>                  The default value is 'real'.
+%>
+%>
+%>
+%> @retval F the random Faust.
+%>
+%> @b Example @b 1
+%> @code
+%> % in a matlab terminal
+%> >> F = matfaust.rand(2, 10, .5, 'mixed', 'complex')
+%>
+%> F =
+%>
+%> Faust size 10x10, density 1, nnz_sum 100, 2 factor(s):
+%> - FACTOR 0 (complex) SPARSE, size 10x10, density 0.5, nnz 50
+%> - FACTOR 1 (complex) DENSE, size 10x10, density 0.5, nnz 50
+%> @endcode
+%> @b Example @b 2
+%> @code
+%> >> G = matfaust.rand([2, 5], [10, 20], .5, 'dense')
+%>
+%> G =
+%>
+%> Faust size 19x18, density 0.973684, nnz_sum 333, 3 factor(s):
+%> - FACTOR 0 (real) DENSE, size 19x12, density 0.5, nnz 114
+%> - FACTOR 1 (real) DENSE, size 12x15, density 0.466667, nnz 84
+%> - FACTOR 2 (real) DENSE, size 15x18, density 0.5, nnz 135
+%>
+%> @endcode
+%>
+%> <p>@b See @b also Faust.Faust.
+%==========================================================================================
+function F = rand(varargin)
+	import matfaust.*
+	%> Identifies a complex Faust.
+	COMPLEX=3;
+	%> Identifies a real Faust.
+	REAL=4;
+	% Constants to identify kind of factors to generate
+	%> Designates a dense factor matrix
+	DENSE=0;
+	%> Designates a dense factor matrix
+	SPARSE=1;
+	%> Means DENSE or SPARSE
+	MIXED=2;
+
+	if(nargin < 2)
+		error('matfaust.rand(): the number of arguments must be at least 2.')
+	end
+	% set num of factors
+	num_factors = varargin{1};
+	dim_sizes = varargin{2};
+	if(isscalar(num_factors) && mod(num_factors,1) == 0)
+		min_num_factors = num_factors;
+		max_num_factors = num_factors;
+	elseif(ismatrix(num_factors) && size(num_factors, 1) == 1 && size(num_factors, 2) == 2)
+		min_num_factors = num_factors(1);
+		max_num_factors = num_factors(2);
+	else
+		error('matfaust.rand(): the argument 1 (num_factors) must be an integer or a vector of two integers.')
+	end
+	% set sizes of factors
+	if(isscalar(dim_sizes) && mod(dim_sizes, 1) == 0)
+		min_dim_size = dim_sizes;
+		max_dim_size = dim_sizes;
+	elseif(ismatrix(dim_sizes) && size(dim_sizes,1) == 1 && size(dim_sizes,2) == 2)
+		min_dim_size = dim_sizes(1);
+		max_dim_size = dim_sizes(2);
+	else
+		error('matfaust.rand(): the argument 2 (dim_sizes) must be an integer or a vector of two integers.')
+	end
+	field = REAL;
+	fac_type = MIXED;
+	per_row = true;
+	density = -1; % default density: 5 elements per row or per column for each factor
+	err_dens_not_num = 'matfaust.rand(): the argument 3 (density) must be a real number in [0;1] or a cell array of length 2 with density at first and ''per_row'' or ''per_col'' char array in second cell.';
+	if(nargin >= 3)
+		if(isscalar(varargin{3}) && isreal(varargin{3}))
+			density = varargin{3};
+		elseif(iscell(varargin{3}))
+			density_cell = varargin{3};
+			if(isreal(density_cell{1}))
+				density = density_cell{1};
+				if(length(density_cell) >= 2)
+					if(strcmp(density_cell{2}, 'per_row'))
+						per_row = true;
+					elseif(strcmp(density_cell{2}, 'per_col'))
+						per_row = false;
+					else
+						error('matfaust.rand(): when argument 3 (density) is a cell the first cell element must be a real number into [0;1] and the second a char array ''per_row'' or ''per_row''.')
+					end
+				end
+			else
+				error(err_dens_not_num)
+			end
+		else
+			error(err_dens_not_num)
+		end
+		if(nargin >= 4)
+			for i=4:nargin
+				% set repr. type of factors ('sparse', 'dense', 'mixed') and field ('real' or 'complex')
+				if(nargin >= i)
+					err_unknown_arg4or5 = ['matfaust.rand(): the argument ' int2str(i) ' (fac_type) must be among a character array among ''sparse'', ''dense'', ''mixed'', ''real'', or ''complex''.'];
+					if(ischar(varargin{i}))
+						if(strcmp(varargin{i}, 'sparse'))
+							fac_type = SPARSE;
+						elseif(strcmp(varargin{i},'dense'))
+							fac_type = DENSE;
+						elseif(strcmp(varargin{i},'mixed'))
+							fac_type = MIXED;
+						elseif(strcmp(varargin{i}, 'real'))
+							field = REAL;
+						elseif(strcmp(varargin{i},'complex'))
+							field = COMPLEX;
+						else
+							error(err_unknown_arg4or5)
+						end
+					else
+						error(err_unknown_arg4or5)
+					end
+				end
+			end
+		end
+	end
+	e = MException('FAUST:OOM', 'Out of Memory');
+	if(field == COMPLEX)
+		core_obj = mexFaustCplx('rand', fac_type, min_num_factors, max_num_factors, min_dim_size, max_dim_size, density, per_row);
+		is_real = false;
+	else %if(field == REAL)
+		core_obj = mexFaustReal('rand', fac_type, min_num_factors, max_num_factors, min_dim_size, max_dim_size, density, per_row);
+		is_real = true;
+	end
+	if(core_obj == 0)
+		throw(e)
+	end
+	F = matfaust.Faust(core_obj, is_real);
+end

wrapper/matlab/+matfaust/wht.m

+%==========================================================================================
+%> @brief Constructs a Faust implementing the Walsh-Hadamard Transform of order n.
+%>
+%> The resulting Faust has log2(n) sparse factors of order n, each one having 2 non-zero elements
+%> per row and per column.
+%>
+%> @b Usage
+%>
+%> &nbsp;&nbsp;&nbsp; @b H = wht(n) <br/>
+%> &nbsp;&nbsp;&nbsp; @b H = wht(n, norma)
+%>
+%> @param n the power of two exponent for a Hadamard matrix of order n and a factorization into log2(n) factors.
+%> @param norma: (optional) true (by default) to normalize the returned Faust as if Faust.normalize() was called, false otherwise.
+%>
+%> @retval H the Faust implementing the Hadamard transform of dimension n.
+%>
+%> @b Example
+%> @code
+%> % in a matlab terminal
+%> >> import matfaust.*
+%> >> H = wht(1024) % is equal to
+%> >> H = normalize(wht(1024, false))
+%> @endcode
+%>
+%>
+%>H =
+%>
+%>Faust size 1024x1024, density 0.0195312, nnz_sum 20480, 10 factor(s):
+%>- FACTOR 0 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%>- FACTOR 1 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%>- FACTOR 2 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%>- FACTOR 3 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%>- FACTOR 4 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%>- FACTOR 5 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%>- FACTOR 6 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%>- FACTOR 7 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%>- FACTOR 8 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%>- FACTOR 9 (real) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
+%>
+%==========================================================================================
+function H = wht(n, varargin)
+	% check n (must be integer > 0)
+	if(~ isreal(n) || n < 0 || abs(n-floor(n)) > 0)
+		error('n must be an integer greater than zero')
+	end
+	log2n = floor(log2(n));
+	if(2^log2n < n)
+		error('n must be a power of 2')
+	end
+	if(log2n > 31)
+		error('Can''t handle a Hadamard Faust of order larger than 2^31')
+	end
+	if(length(varargin) > 0)
+		if(~ islogical(varargin{1}))
+			error('wht optional second argument must be a boolean');
+		end
+		norma = varargin{1};
+	else
+		norma = true; % normalization by default
+	end
+	core_obj = mexFaustReal('hadamard', log2n, norma);
+	is_real = true;
+	e = MException('FAUST:OOM', 'Out of Memory');
+	if(core_obj == 0)
+		throw(e)
+	end
+	H = matfaust.Faust(core_obj, is_real);
+end