Add equivalent functions matfaust.Faust.numel() and pyfaust.Faust.size().

- Update density() to use the new function.
- Update the API doc (density() and matfaust.Faust.size()/pyfaust.Faust.shape()).

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

@@ -479,6 +479,7 @@ classdef Faust
 		%>	ncols = size(F, 2)
 		%> @endcode
 		%>
+		%> <p/>@b See @b also Faust.numel
 		%======================================================================
 		function varargout = size(F,varargin)
 			%% SIZE Size of a Faust (overloaded Matlab built-in function).
@@ -536,7 +537,30 @@ classdef Faust
 			end
 		end
 
-
+		%======================================================================
+		%> @brief Gives the number of elements in the Faust (equivalent to prod(size(F)).
+		%>
+		%> @b Usage
+		%>
+		%> &nbsp;&nbsp;&nbsp; @b n = numel(F)
+		%>
+		%> @param F the Faust object.
+		%>
+		%> @retval n the number of elements of the Faust.
+		%>
+		%> @b Example
+		%> @code
+		%>	import matfaust.Faust
+		%>	F = Faust.rand(5, [50, 100], .5, 'mixed', false)
+		%>	n = numel(F)
+		%> @endcode
+		%>
+		%> <p/>@b See @b also Faust.size
+		%>
+		%======================================================================
+		function n = numel(F)
+			n = prod(size(F));
+		end
 
 		%======================================================================
 		%> @brief Serves as the last index when slicing or indexing a Faust.
@@ -981,12 +1005,20 @@ classdef Faust
 		end
 
 		%======================================================================
-		%> @brief Calculates the density of F, that is, the number of non-zeros
-		%> in factors over the total number of elements in dense matrix of F
-		%> (which is equal to size(F, 1)*size(F, 2)).
+		%> @brief Calculates the density of F such that nnz_sum(F) == density(F)*numel(F).
+		%>
+		%> @b Usage
+		%>
+		%> &nbsp;&nbsp;&nbsp; @b dens = density(F)
 		%>
 		%> @b NOTE: this definition of density allows the value to be greater than 1.
 		%>
+		%> @b NOTE: a value of density below one indicates potential memory savings compared
+		%> to storing the corresponding dense matrix full(F), as well as potentially
+		%> faster matrix-vector multiplication when applying F*x instead of full(F)*x.
+		%>
+		%>
+		%>
 		%> @param F the Faust object.
 		%>
 		%> @retval dens density of F.
@@ -998,7 +1030,7 @@ classdef Faust
 		%>	dens = density(F)
 		%> @endcode
 		%>
-		%> <p/>@b See @b also Faust.nnz_sum, Faust.rcg
+		%> <p/>@b See @b also Faust.nnz_sum, Faust.rcg, Faust.size, Faust.numel
 		%======================================================================
 		function dens = density(F)
 			%% DENSITY Density of the Faust.
@@ -1011,7 +1043,7 @@ classdef Faust
 			%
 			% See also rcg, nnz_sum.
 
-			prod_dim=prod(size(F));
+			prod_dim=numel(F);
 			if (prod_dim ~= 0)
 				dens=nnz_sum(F)/prod_dim;
 			else

wrapper/python/pyfaust.py

@@ -270,10 +270,35 @@ class Faust:
             >>> nrows = F.shape[0]
             >>> ncols = F.shape[1]
 
-        <b/> See also Faust.display
+        <b/> See also Faust.size
         """
         return F.m_faust.shape()
 
+    @property
+    def size(F):
+        """
+        Gives the number of elements in the Faust F.
+
+        It's equivalent to np.prod(F.shape)).
+
+        This function is intended to be used as a property (see the examples).
+
+        Args:
+            F: the Faust object.
+
+        Returns:
+            The number of elements in the Faust F.
+
+        Examples:
+            >>> from pyfaust import Faust
+            >>> F = Faust.rand(2, 50, is_real=False)
+            >>> size = F.size
+
+        <b/> See also Faust.shape
+
+        """
+        return np.prod(F.shape)
+
     def transpose(F):
         """
         Returns the transpose of the Faust F.
@@ -333,8 +358,7 @@ class Faust:
             >>> F = Faust.rand(5, 50, is_real=False)
             >>> Fc = F.conj()
 
-        <b/> See also Faust.transpose, Faust.get_factor, Faust.get_num_factors,
-        Faust.getH, Faust.H
+        <b/> See also Faust.transpose, Faust.get_factor, Faust.get_num_factors, Faust.getH, Faust.H
         """
         F_conj = Faust(core_obj=F.m_faust.conj())
         return F_conj
@@ -644,13 +668,15 @@ class Faust:
         return F.m_faust.nnz()
 
     def density(F):
-        """ Calculates the density of F.
+        """ Calculates the density of F such that F.nnz_sum() == F.density()/F.size.
 
-        The density of F is equal to the number of non-zeros in factors over
-        the total number of elements in dense matrix of F (which is equal to
-        F.shape[0]*F.shape[1]).
+        NOTE: This definition of density allows the value to be greater than
+        one.
 
-        NOTE: this definition of density allows the value to be greater than 1.
+        NOTE: A value of density below one indicates potential memory savings
+        compared to storing the corresponding dense matrix F.todense(), as well
+        as potentially faster matrix-vector multiplication when applying F*x
+        instead of F.todense()*x.
 
         Args:
             F: the Faust object.
@@ -663,9 +689,9 @@ class Faust:
         >>> F = Faust.rand(5, 50, .5)
         >>> dens = F.density()
 
-        <b/> See also Faust.nnz_sum, Faust.rcg
+        <b/> See also Faust.nnz_sum, Faust.rcg, Faust.size
         """
-        return float(F.nnz_sum())/(F.shape[1]*F.shape[0])
+        return float(F.nnz_sum())/F.size
 
     def rcg(F):
         """