Exceptional GitLab maintenance is scheduled for June 19, 2025. The service will be unavailable between 12am and 2pm. Please do not work on the platform until an announcement indicates that maintenance is complete.
%>A FAµST data structure is designed to allow fast matrix-vector multiplications together with reduced memory storage compared to what would be obtained by manipulating directly the corresponding (dense) Matlab array.
%>A FAµST data structure is designed to allow fast matrix-vector multiplications together with reduced memory storage compared to what would be obtained by manipulating directly the corresponding (dense) Matlab array.
%>
%>
%>A particular example is the matrix associated to the discrete Fourier transform, which can be represented exactly as a FAµST, leading to a fast and compact implementation.
%>A particular example is the matrix associated to the discrete Fourier transform, which can be represented exactly as a FAµST, leading to a fast and compact implementation (see FaustFactory.fourier()).
%>
%>
%> Although the sparse matrices are more interesting for optimization it's not forbidden to define a Faust as a product of dense matrices or a mix of dense and sparse matrices.
%> Although sparse matrices are more interesting for optimization it's not forbidden to define a Faust as a product of dense matrices or a mix of dense and sparse matrices.
%>
%>
%> The matrices composing the Faust product, also called the factors, are defined on complex or real fields. Hence a Faust can be a complex Faust or a real Faust.
%> The matrices composing the Faust product, also called the factors, are defined on complex or real fields. Hence a Faust can be a complex Faust or a real Faust.
%>
%>
%> A Faust has ideally to be seen and used as a Matlab native dense matrix, but this matrix exists only virtually and is actually represented by its factors.
%> Several Matlab builtins have been overloaded to ensure that a Faust is
%> In order to use a Faust like a Matlab matrix, a certain number of Matlab built-ins available for Matlab matrices are implemented in this class but take note that not all are (e.g. IMAG() and REAL() are not defined for a Faust)
%> almost handled as a native Matlab matrix.
%>
%>
%> It's possible to retrieve the Matlab native dense matrix with the method Faust.full but it will cost the multiplication of the Faust's factors.
%> The main exception is that contrary to a Matlab native array a Faust is immutable.
%> It's noteworthy that in this documentation the expression 'dense matrix' designates the Matlab native dense matrix corresponding to a Faust, that is the matrix obtained by the multiplication of the previously mentioned Faust's factors.
%> It means that you cannot affect elements of a Faust using
%> the affectation operator `=' like you do with a Matlab matrix (e.g. `M(i,j) =
%> 2').
%> That limitation is the reason why the Matlab built-in `SUBSASGN()' is not
%> implemented in this class.
%>
%>
%> Likewise, other Faust's methods need to calculate the factor product, and they will be indicated with a warning in this documentation. You should avoid to use them if it's not really necessary (for example you might limit their use to test purposes).
%> Other notable limitations are that one cannot:
%> - compute the real and imaginary parts of a Faust,
%> - perform elmentwise operations between two Fausts (e.g. elementwise
%> multiplication).
%> In particular, the addition F+G is undefined for Faust objects (so
%> far).
%> - concatenate,
%> - reshape,
%> - invert.
%>
%>
%> Other important limitation is that contrary to a Matlab native dense matrix a Faust is immutable. It means that you cannot affect elements of a Faust using the affectation operator `=' like you do with a Matlab matrix (e.g. `M(i,j) = 2').
%> Primarily for convenience and test purposes, a Faust can be converted into
%> That limitation is the reason why the Matlab built-in `SUBSASGN()' is not implemented in this class.
%> the corresponding full matrix using the function Faust.full.
%>
%> Warning: using Faust.full is discouraged except for test purposes, as it
%> loses the main potential interests of the FAuST structure: compressed
%> memory storage and faster matrix-vector multiplication compared to its
%> equivalent full matrix representation.
%>
%> In this documentation, the expression 'full matrix' designates the Matlab array
%> Faust.full() obtained by the multiplication of the Faust factors.
%>
%> Likewise, some other Faust methods need to calculate the factor product, and they will be indicated with a warning in this documentation. You should avoid to use them if it's not really necessary (for example you might limit their use to test purposes).
%>
%> TODO: list of these functions here.
%>
%>
%> For more information about FAµST take a look at http://faust.inria.fr.
%> For more information about FAµST take a look at http://faust.inria.fr.
%> @brief Creates a Faust from a list of factors or alternatively from a file.
%> @brief Creates a Faust from a list of factors or alternatively from a file.
%>
%>
%> Another easy way to create a Faust is to call the static method FaustFactory.rand().
%> Other easy ways to create a Faust is to call one of the FaustFactory static methods: FaustFactory.rand(), FaustFactory.fourier() or FaustFactory.hadamard().
%> @b N = @b size(F,DIM) with N being the size of the DIM-th dimension of F.<br/>
%> @b n = @b size(f,dim) with n being the size of the dim-th dimension of F.<br/>
%> In other words N= NROWS if DIM == 1, N = NCOLS if DIM == 2.
%> In other words n == nrows if dim == 1, N = ncols if dim == 2.
%>
%>
%> @param F the Faust object.
%> @param F the Faust object.
%> @param varargin can be missing or specifying the index of the dimension to get the size of.
%> @param dim (optional) the index of the dimension to get the size of.
%> @brief Returns a Faust representing a submatrix of the dense matrix full(F) or a
%> @brief Subscripted reference of a Faust.
%> scalar element if that Faust can be reduced to a single element.
%>
%> The function returns a Faust representing a submatrix of full(F) or a
%> scalar element if that Faust can be reduced to a single element.
%>
%>
%>
%>
%> This function is a Matlab built-in overload.
%> This function overloads a Matlab built-in.
%>
%>
%> @b WARNING:
%> @b WARNING:
%> - This function doesn't handle a slice step different to 1 (e.g. F(i:2:j,:) where slice step is 2.)
%> - This function doesn't handle a slice step different from 1 (e.g. F(i:2:j,:) where slice step is 2.)
%> - It is not advised to use this function as an element accessor
%> - It is not advised to use this function as an element accessor
%> (e.g. F(0,0)) because such an use induces to convert the Faust to its
%> (e.g. F(1,1)) because such a use induces to convert the Faust to its
%> dense matrix representation and that is a very expensive computation if used
%> dense matrix representation and that is a very expensive computation if used
%> repetitively.
%> repetitively.
%>
%>
%> @b Usage
%> @b Usage
%>
%>
%> @b F(I,J) extracts the Faust representing the sub-matrix of full(F) defined by the subscript vectors I and J (take a look to examples below).
%> @b G = F(I,J) the Faust representing the sub-matrix of full(F) defined by the subscript vectors I and J (see examples below).
%>
%>
%> @param F the Faust object.
%> @param F the Faust object.
%> @param S the structure defining the Faust to extract like a submatrix (it's not supposed to be used directly ; usage and examples show how subscript should be used).
%> @param S the structure defining the Faust to extract like a submatrix (it's not supposed to be used directly ; usage and examples show how subscript should be used).
%> This function overloads a Matlab built-in function.
%>
%>
%> Several types of norm are available: 1-norm, 2-norm and Frobenius norm.
%> Several types of norm are available: 1-norm, 2-norm and Frobenius norm.
%>
%>
%> The norm of F is equal to the norm of its dense matrix full(F).
%> The norm of F is equal to the norm of full(F).
%>
%>
%> @b WARNING: this function costs at least as much as Faust.mtimes.
%> @b WARNING: if [n,m] == size(F), the computation time can be expected to be of the order of min(n,m) times that of multipliying F by a vector.
%>
%>
%> @b Usage
%> @b Usage
%>
%>
%> @b n = @b norm(F, 2) returns the 2-norm of F: approximately max(svd(full(F))).<br/><br>
%> @b n = @b norm(F, 2) the 2-norm or maximum singular value of F: approximately norm(full(F),2) == max(svd(full(F))).<br/><br>
%> @b n = @b norm(F) is the same as norm(F, 2).<br/><br>
%> @b n = @b norm(F) the same as norm(F, 2).<br/><br>
%> @b n = @b norm(F, 1) returns the 1-norm of F: the maximum absolute column sum of the matrix full(F).<br/><br>
%> @b n = @b norm(F, 1) the 1-norm of F: norm(full(F), 1) == max(sum(abs(full(F)))) <br/><br>
%> @b n = @b @b norm(F, @b 'fro') returns the Frobenius norm of F.<br/><br>
%> @b n = @b @b norm(F, @b 'fro') the Frobenius norm of F: norm(full(F), 'fro').<br/><br>
%>
%>
%> @param F the Faust object.
%> @param F the Faust object.
%> @param p (optional) the norm order or type. Respectively 1 or 2 for the 1-norm and 2-norm or 'fro' for the Frobenius norm (by default the 2-norm is computed).
%> @param p (optional) the norm order or type. Respectively 1 or 2 for the 1-norm and 2-norm or 'fro' for the Frobenius norm (by default the 2-norm is computed).
