matfaust::Faust Class Reference

FAuST Matlab wrapper main class for using multi-layer sparse transforms. More...

Public Member Functions
function	Faust (varargin)
	Creates a Faust from a list of factors or alternatively from a file. More...
function	delete (F)
	Deletes the Faust object F (destructor). More...
function	uplus (F)
	Returns + F. More...
function	uminus (F)
	Returns - F. More...
function	plus (varargin)
	Plus. More...
function	minus (varargin)
	Minus. More...
function	mrdivide (F, s)
	/ Slash or right Faust divide. More...
function	mtimes (F, A)
	Multiplies the Faust F by A which is a full matrix, a Faust object or a scalar. More...
function	full (F)
	The full matrix implemented by F. More...
function	isreal (F)
	Indicates if F is a real Faust or a complex Faust. More...
function	real (F)
	Returns the real part of the Faust F. More...
function	imag (F)
	Returns the imaginary part of the Faust F. More...
function	single (F)
	Returns a new Faust whose class is single. It allows to convert all the factors to single precision. More...
function	double (F)
	Returns a new Faust whose class is double. It allows to convert all the factors to double precision. More...
function	transpose (F)
	The transpose of F. More...
function	ctranspose (F)
	The conjugate transpose of F. More...
function	conj (F)
	The complex conjugate of F. More...
function	pruneout (F, varargin)
	Returns a Faust optimized by removing useless zero rows and columns as many times as needed. More...
function	optimize_memory (F)
	Optimizes a Faust by changing the storage format of each factor in order to optimize the memory size. More...
function	optimize (F, varargin)
	Returns a Faust optimized with Faust.pruneout, Faust.optimize_memory and Faust.optimize_time. More...
function	optimize_time (F, varargin)
	Returns a Faust configured with the quickest Faust-matrix multiplication mode (benchmark ran on the fly). More...
function	size (F, varargin)
	The size of F. More...
function	numel (F)
	The number of elements in F. More...
function	nbytes (F)
	Gives the memory size of the Faust in bytes. More...
function	end (F, k, n)
	The last index when slicing or indexing a Faust. More...
function	factors (F, ids, varargin)
	Returns the i-th factor or a new Faust composed of F factors whose indices are listed in indices. More...
function	left (F, i, varargin)
	Returns the left hand side factors of F from index 1 to i included (in 1-base index). More...
function	right (F, i, varargin)
	Returns the right hand side factors of F from index i to end (in 1-base index). More...
function	numfactors (F)
	The number of factors of F. More...
function	length (F)
	The number of factors of F. More...
function	replace (F, i, new_factor)
	Replaces the factor of index i by new_factor in a new Faust copy of F. More...
function	insert (F, i, new_factor)
	Inserts new_factor at index i in a new Faust copy of F. More...
function	issparse (F, varargin)
	Returns true if F factors are all sparse matrices false otherwise. More...
function	isdense (F)
	Returns true if F factors are all dense matrices/arrays false otherwise. More...
function	save (F, filepath)
	Saves the Faust F into a file. More...
function	subsref (F, S)
	Subscripted reference of a Faust. More...
function	disp (F)
	Displays information about F. More...
function	norm (F, varargin)
	The matrix norm of F. More...
function	power_iteration (F, varargin)
	Performs the power iteration algorithm to compute the greatest eigenvalue of the Faust. More...
function	normalize (F, varargin)
	Returns the normalized F. More...
function	nnz_sum (F)
	The total number of nonzeros in the factors of F. More...
function	density (F)
	The density of F such that nnz_sum(F) == density(F) * numel(F). More...
function	rcg (F)
	The Relative Complexity Gain of F. More...
function	cat (varargin)
	Concatenates F with n Faust objects or full/sparse matrices. More...
function	horzcat (varargin)
	Horizontal concatenation [F,A, B, … ] where F is a Faust and A, B, … are Faust objects or sparse/full matrix. More...
function	vertcat (varargin)
	Vertical concatenation [F;A;B;…] where F is a Faust and A, B, … are Faust objects or sparse/full matrices. More...
function	imagesc (F, varargin)
	Displays image of F full matrix and its factors. More...
function	mldivide (F, B)
	\ Backslash or left full(F) divide. More...
function	pinv (F)
	Pseudoinverse matrix of full(F). More...
function	complex (F)
	Converts F to a new complex Faust. More...
function	clone (F, varargin)
	Clones the Faust (in a new memory space). More...
function	device (F)
	Returns the Faust device ('cpu' or 'gpu'). More...
function	class (F)
	Returns the Faust class ('single' or 'double'). More...
function	get_handle (F)
	Returns the Faust F C++ native object pointer as an integer. More...

Static Public Member Functions
static function	opt_butterfly (F)
	Optimizes any Faust composed of butterfly factors. More...
static function	isFaust (obj)
	Returns true if obj is a Faust object, false otherwise. More...
static function	load (filepath, varargin)
	Loads a Faust from a .mat file. More...
static function	load_native (filepath)
	Loads a Faust from a .mat file (native C++ version). More...

Protected Attributes
Property	matrix
	Underlying Faust native object handle. More...
Property	is_real
	See Faust.isreal. More...
Property	dev
	See Faust.device. More...
Property	dtype
	See Faust.class. More...

Detailed Description

FAuST Matlab wrapper main class for using multi-layer sparse transforms.

This class provides a Matlab array-like interface for operations with FAuST data structures, which correspond ideally to matrices that can be written exactly as the product of sparse matrices.

The Faust class 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 Faust, leading to a fast and compact implementation (see matfaust.dft()).

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.

Several Matlab builtins have been overloaded to ensure that a Faust is almost handled as a native Matlab matrix.

The main exception is that contrary to a Matlab native array a Faust is immutable. It means that you cannot modify elements of a Faust using the assignment operator ‘=’ as made 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. Note however that you can optionally contravene the immuability in certain functions (e.g. with the inplace argument of the Faust.optimize_time).

Other noticeable limitations are that one cannot:

• compute the real and imaginary parts of a Faust,
• perform elementwise operations between two Fausts (e.g. elementwise multiplication), the addition and subtraction are available though,
• reshape a Faust.

Mainly for convenience and test purposes, a Faust can be converted into 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.

List of functions that are memory costly:

• Faust.full(),
• Faust.pinv(),
• Faust.mldivide().
• element indexing (F(i,j), but note that slicing is memory efficient through memory views).

Note

it could be wiser to encapsulate a Faust in a lazylinop.LazyLinearOp for a totally lazy paradigm on all available operations.

For more information about FAuST take a look at https://faust.inria.fr.

Constructor & Destructor Documentation

Faust()

function matfaust::Faust::Faust

(

varargin

)

Creates a Faust from a list of factors or alternatively from a file.

Other easy ways to create a Faust is to call one of the following functions: matfaust.rand(), matfaust.dft() or matfaust.wht().

Usage

    Faust(factors) creates a Faust from a list of factors (1D cell array).

    Faust(filepath) creates a Faust from a previously saved Faust file (filepath is a character array).

Parameters

factors	(varargin{1}, first argument) the 1D cell array of factors to initialize the Faust with. The factors must respect the dimensions needed for the product to be defined (for i=1 to size(factors,2), size(factors{i},2) == size(factors{i+1},1)). The factors can be sparse, dense or BSR matrices. It might be real matrices in single or double precision but also complex matrices. The created Faust will be consequently a single, double or complex Faust. To create a BSR matrix you must use the matfaust.create_bsr function. Passing a single matrix to the constructor instead of a cell array is equivalent to passing a singleton cell array.
filepath	(varargin{1}, first argument) the file from which a Faust is created. It must be a character array. The format is Matlab version 5 (.mat extension). The file must have been saved before with Faust.save().
'dev',str	'gpu or 'cpu' to create the Faust on CPU or GPU (by default on CPU). Examples

>> import matfaust.Faust
>> factors = cell(1,5);
>> is_sparse = false;
>> % alternate sparse and dense factors
>> for i=1:5; if(is_sparse);factors{i} = sprand(100, 100, 0.1); else factors{i} = rand(100, 100); end; is_sparse = ~ is_sparse; end
>> % define a Faust with those factors
>> F = Faust(factors)
 
F =
 
Faust size 100x100, density 3.1897, nnz_sum 31897, 5 factor(s):
- FACTOR 0 (double) DENSE, size 100x100, density 1, nnz 10000
- FACTOR 1 (double) SPARSE, size 100x100, density 0.0943, nnz 943
- FACTOR 2 (double) DENSE, size 100x100, density 1, nnz 10000
- FACTOR 3 (double) SPARSE, size 100x100, density 0.0954, nnz 954
- FACTOR 4 (double) DENSE, size 100x100, density 1, nnz 10000
 
>> save(F, 'F.mat')
>> % define a Faust from file
>> G = Faust('F.mat')
 
G =
 
Faust size 100x100, density 3.1897, nnz_sum 31897, 5 factor(s):
- FACTOR 0 (double) DENSE, size 100x100, density 1, nnz 10000
- FACTOR 1 (double) SPARSE, size 100x100, density 0.0943, nnz 943
- FACTOR 2 (double) DENSE, size 100x100, density 1, nnz 10000
- FACTOR 3 (double) SPARSE, size 100x100, density 0.0954, nnz 954
- FACTOR 4 (double) DENSE, size 100x100, density 1, nnz 10000
 
>> H = Faust(rand(10,10)) % creating a Faust with only one factor
 
H =
 
Faust size 10x10, density 1, nnz_sum 100, 1 factor(s):
- FACTOR 0 (double) DENSE, size 10x10, density 1, nnz 100

See also Faust.delete, Faust.save, matfaust.rand, matfaust.dft, matfaust.wht

Member Function Documentation

cat()

function matfaust::Faust::cat

(

varargin

)

Concatenates F with n Faust objects or full/sparse matrices.

This function overloads a Matlab built-in function.

The resulting Faust C = cat(DIM,F,G,…) verifies that:

full(C) == full(cat(DIM, full(F), full(G), …))

Note

you could have an elementwise non-significant absolute difference between the two members (not more than eps(1.0)).

Usage

    C=CAT(DIM,F,G) concatenates the Faust F and G, which is a Faust or a matrix, along the dimension DIM. The result is the Faust C.
    CAT(2,F,G) is the same as [F,G].
    CAT(1,F,G) is the same as [F;G].
    CAT(DIM, F, G,…) concatenates an arbitrary number of Fausts and matrices along the DIM-th dimension.

Parameters

DIM	(1st arg.) the dimension along which to concatenate. DIM==1 means vertical concatenation, DIM==2 means horizontal concatenation.
F	(2nd arg.) the first Faust object.
G,…	(3rd to n+3 args) the Faust objects or matrices to concatenate to F. The matrices can be sparse or full.

Return values

C	the concatenation result as a new Faust.

Note

it could be wiser to encapsulate a Faust in a lazylinop.LazyLinearOp for a lazy concatenation.

Example

>>% in a matlab terminal
>> rng(42); % for reproducibility
>> F = matfaust.rand(50, 50);
>> G = matfaust.rand(50, 50);
>> [F;G] % equiv. to cat(1,F,G)
 
ans =
 
Faust size 100x50, density 0.52, nnz_sum 2600, 6 factor(s):
- FACTOR 0 (double) SPARSE, size 100x100, density 0.05, nnz 500
- FACTOR 1 (double) SPARSE, size 100x100, density 0.05, nnz 500
- FACTOR 2 (double) SPARSE, size 100x100, density 0.05, nnz 500
- FACTOR 3 (double) SPARSE, size 100x100, density 0.05, nnz 500
- FACTOR 4 (double) SPARSE, size 100x100, density 0.05, nnz 500
- FACTOR 5 (double) SPARSE, size 100x50, density 0.02, nnz 100
 
>> [F,G] % equiv. to cat(2,F,G)
 
ans =
 
Faust size 50x100, density 0.52, nnz_sum 2600, 6 factor(s):
- FACTOR 0 (double) SPARSE, size 50x100, density 0.02, nnz 100
- FACTOR 1 (double) SPARSE, size 100x100, density 0.05, nnz 500
- FACTOR 2 (double) SPARSE, size 100x100, density 0.05, nnz 500
- FACTOR 3 (double) SPARSE, size 100x100, density 0.05, nnz 500
- FACTOR 4 (double) SPARSE, size 100x100, density 0.05, nnz 500
- FACTOR 5 (double) SPARSE, size 100x100, density 0.05, nnz 500
 
>> [F;rand(100,50)] % vertical concatenation with auto-conversion of the random matrix to a Faust
 
ans =
 
Faust size 150x50, density 0.873333, nnz_sum 6550, 6 factor(s):
- FACTOR 0 (double) SPARSE, size 150x100, density 0.35, nnz 5250
- FACTOR 1 (double) SPARSE, size 100x100, density 0.03, nnz 300
- FACTOR 2 (double) SPARSE, size 100x100, density 0.03, nnz 300
- FACTOR 3 (double) SPARSE, size 100x100, density 0.03, nnz 300
- FACTOR 4 (double) SPARSE, size 100x100, density 0.03, nnz 300
- FACTOR 5 (double) SPARSE, size 100x50, density 0.02, nnz 100
 
>> [F;sprand(100,50,.2)] % vertical concatenation with auto-conversion of the random sparse matrix to a Faust
 
ans =
 
Faust size 150x50, density 0.329733, nnz_sum 2473, 6 factor(s):
- FACTOR 0 (double) SPARSE, size 150x100, density 0.0782, nnz 1173
- FACTOR 1 (double) SPARSE, size 100x100, density 0.03, nnz 300
- FACTOR 2 (double) SPARSE, size 100x100, density 0.03, nnz 300
- FACTOR 3 (double) SPARSE, size 100x100, density 0.03, nnz 300
- FACTOR 4 (double) SPARSE, size 100x100, density 0.03, nnz 300
- FACTOR 5 (double) SPARSE, size 100x50, density 0.02, nnz 100
 
>> [F;G;F;G]; % it's allowed to concatenate an arbitrary number of Fausts
>> [F,G,F,G]; % as long as the dimensions agree
>> [F,G;F,G];

Errors

• The dimensions of F and G don't agree:

 >> F = matfaust.rand(2,51);
 >> G = matfaust.rand(2,25);
 >> [F;G]
 ??? Error using mexFaustReal
The dimensions of the two Fausts must agree.

• The DIM argument is different from 1 and 2:

 >> F = matfaust.rand(2,4);
 >> G = matfaust.rand(2,4);
 >> cat(3,F,G)
 ??? Error using matfaust.Faust/cat
Wrong first argument: must be an integer between 1 and 2.

See also Faust.vertcat, Faust.horzcat.

class()

function matfaust::Faust::class

(

F

)

Returns the Faust class ('single' or 'double').

Return values

c	the Faust class.

Example:

>> class(matfaust.Faust(rand(10, 10)))
 
ans =
 
    'double'
 
>> class(matfaust.Faust(single(rand(10, 10))))
 
ans =
 
    'single'
 
>> class(matfaust.Faust(complex(rand(10, 10))))
 
ans =
 
    'double'

clone()

function matfaust::Faust::clone	(	F	,
		varargin
	)

Clones the Faust (in a new memory space).

Parameters

'dev',str

'gpu or 'cpu' to clone the Faust on CPU or GPU (by default on CPU).

Example

>> F = matfaust.rand(10, 10)
 
F =
 
Faust size 10x10, density 2.5, nnz_sum 250, 5 factor(s):
- FACTOR 0 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 1 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 2 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 3 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 4 (double) SPARSE, size 10x10, density 0.5, nnz 50
 
>> Fc = clone(F)
 
Fc =
 
Faust size 10x10, density 2.5, nnz_sum 250, 5 factor(s):
- FACTOR 0 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 1 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 2 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 3 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 4 (double) SPARSE, size 10x10, density 0.5, nnz 50
 
>> % and only if your device supports a compatible NVIDIA device
>> Fc_gpu = clone(F, 'dev', 'gpu');  % doctest: +SKIP_IF(~ matfaust.is_gpu_mod_enabled() || ~ matfaust.is_gpu_mod_working())
>> device(gpuF) % doctest: +SKIP_IF(~ matfaust.is_gpu_mod_enabled() || ~ matfaust.is_gpu_mod_working())
 
ans =
 
    'gpu'

Return values

Fc	the Faust clone.

complex()

function matfaust::Faust::complex

(

F

)

Converts F to a new complex Faust.

This function overloads a Matlab built-in function.

Usage

    cF = COMPLEX(F) for real Faust F returns the complex result cF with real part F and zero matrix as imaginary part of all cF's factors.

Example:

>> dF = matfaust.rand(5, 5, 'field', 'real', 'class', 'double')
 
dF =
 
Faust size 5x5, density 5, nnz_sum 125, 5 factor(s):
- FACTOR 0 (double) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 1 (double) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 2 (double) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 3 (double) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 4 (double) SPARSE, size 5x5, density 1, nnz 25
 
>> cF = complex(dF)
 
cF =
 
Faust size 5x5, density 5, nnz_sum 125, 5 factor(s):
- FACTOR 0 (complex) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 1 (complex) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 2 (complex) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 3 (complex) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 4 (complex) SPARSE, size 5x5, density 1, nnz 25

See also Faust.isreal, Faust.conj

conj()

function matfaust::Faust::conj

(

F

)

The complex conjugate of F.

This function overloads a Matlab built-in function.

Usage

    F_conj = conj(F)

Parameters

F	the Faust object.

Return values

F_conj

a Faust object implementing the conjugate of full(F), such that: full(F_conj) == conj(full(F))

Example

>> F = matfaust.rand(5, 5, 'field', 'complex');
>> F_conj = conj(F);
>> all(all(full(F_conj) == conj(full(F))))
 
ans =
 
  logical
 
     1

See also Faust.transpose, Faust.ctranspose, Faust.complex

ctranspose()

function matfaust::Faust::ctranspose

(

F

)

The conjugate transpose of F.

This function overloads a Matlab built-in function/operator.

Usage

    F_ctrans = ctranspose(F)
    F_ctrans = F'

Parameters

F	the Faust object.

Return values

F_ctrans

a Faust object implementing the conjugate transpose of full(F), such that: full(F_ctrans) == full(F)' == ctranspose(full(F))

Example

 >> F = matfaust.rand(5, 10, 'field', 'complex');
 >> F_ctrans = F'; % ' == ctranspose
 >> size(F_ctrans)
 
ans =
 
     10    5
 
 >> F_c = transpose(ctranspose(F));
 >> all(all(full(F_c) == full(conj(F))))
 
 ans =
 
   logical
 
      1

See also Faust.transpose, Faust.conj, Faust.complex

delete()

function matfaust::Faust::delete

(

F

)

Deletes the Faust object F (destructor).

Usage

    delete(F)

Parameters

F	the Faust to delete.

Example

>> F = matfaust.rand(5, 10);
>> delete(F) % underlying C++ object wiped out of memory but variable F still exists
>> exist('F')
 
ans =
 
     1
 
>> F
??? Invalid or deleted object.
>>
>> F = matfaust.rand(5, 10);
>> clear F % underlying C++ object is removed and variable too
>> exist('F')
 
ans =
 
     0
>> F
??? Unrecognized function or variable 'F'.

See also Faust.Faust, clear (built-in)

density()

function matfaust::Faust::density

(

F

)

The density of F such that nnz_sum(F) == density(F) * numel(F).

Usage

    dens = density(F)

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.

A density above one is possible but prevents any saving.

Parameters

F	the Faust object.

Return values

dens	density of F.

Example

>> F = matfaust.rand(10, 10);
>> density(F)
 
ans =
 
    2.5000

See also Faust.nnz_sum, Faust.rcg, Faust.size, Faust.numel

device()

function matfaust::Faust::device

(

F

)

Returns the Faust device ('cpu' or 'gpu').

Return values

dev	the Faust device.

Example:

>> cpuF = matfaust.rand(5, 5, 'dev', 'cpu');
>> device(cpuF)
 
ans =
 
    'cpu'
 
>> gpuF = matfaust.rand(5,5, 'dev', 'gpu'); % doctest: +SKIP_IF(~ matfaust.is_gpu_mod_enabled() || ~ matfaust.is_gpu_mod_working())
>> device(gpuF) % doctest: +SKIP_IF(~ matfaust.is_gpu_mod_enabled() || ~ matfaust.is_gpu_mod_working())
 
ans =
 
    'gpu'

disp()

function matfaust::Faust::disp

(

F

)

Displays information about F.

This function overloads a Matlab built-in function.

Usage

    disp(F)

    F

Parameters

F	the Faust object.

Example

>> F = matfaust.rand(98, 82, 'num_factors', 2);
>> disp(F) % doctest: +ELLIPSIS
Faust size 98x82, %> %> %>
>> F % doctest: +ELLIPSIS
 
F =
 
Faust size 98x82, %> %> %>

See also Faust.nnz_sum, Faust.density, Faust.size, Faust.factors, Faust.numfactors

double()

function matfaust::Faust::double

(

F

)

Returns a new Faust whose class is double. It allows to convert all the factors to double precision.

Usage

    dF = double(F)

Return values

sF	the double class/precision Faust.

Example:

 >> sF = matfaust.rand(5, 5, 'field', 'real', 'class', 'single')
 sF =
 
 Faust size 5x5, density 5, nnz_sum 125, 5 factor(s):
 - FACTOR 0 (float) SPARSE, size 5x5, density 1, nnz 25
 - FACTOR 1 (float) SPARSE, size 5x5, density 1, nnz 25
 - FACTOR 2 (float) SPARSE, size 5x5, density 1, nnz 25
 - FACTOR 3 (float) SPARSE, size 5x5, density 1, nnz 25
 - FACTOR 4 (float) SPARSE, size 5x5, density 1, nnz 25
 
 >> dF = double(sF)
dF =
 
Faust size 5x5, density 5, nnz_sum 125, 5 factor(s):
- FACTOR 0 (double) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 1 (double) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 2 (double) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 3 (double) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 4 (double) SPARSE, size 5x5, density 1, nnz 25

See also Faust.class, Faust.single

end()

function matfaust::Faust::end	(	F	,
		k	,
		n
	)

The last index when slicing or indexing a Faust.

size(F, K) == end when indexing the K-th dimension of F \((K \in {1, 2})\).

This function overloads a Matlab built-in function.

Example

% in a matlab terminal
>> rng(42) % for reproducibility
>> F = matfaust.Faust(rand(3, 3));
>> full(F)
 
ans =
 
    0.3745    0.5987    0.0581
    0.9507    0.1560    0.8662
    0.7320    0.1560    0.6011
 
>> full(F(2:end,1))
    ans =
 
        0.9507
        0.7320
 
>> full(F(1,1:2:end))
ans =
 
    0.3745    0.0581
 
>> full(F(1,1:end-1))
    ans =
 
        0.3745  0.5987

See also Faust.subsref, Faust.size

factors()

function matfaust::Faust::factors	(	F	,
		ids	,
		varargin
	)

Returns the i-th factor or a new Faust composed of F factors whose indices are listed in indices.

Note

Factors are not copied in memory if a subset greater than one is asked or if as_faust == true.

Usage

    factor = factors(F, i) returns the i-th factor of F.
    factor = factors(F, i:j) returns a new Faust formed of the F's factors from the i-th to the j-th included.

Parameters

F	the Faust object.
ids	the factor indices.
'as_faust',logical	(optional): true to return a Faust even if a single factor is asked (length(ids) == 1), otherwise (as_faust == false) and a dense or sparse matrix is returned.

Return values

factors

a matrix copy of the i-th factor if i is a single index or a new Faust composed of i-th to the j-th factors of F. The factors copies keep the storage organization of the source matrix (full or sparse).

Note

Matlab doesn't support float sparse matrices, but matfaust does! Hence when you call Faust.factors on a float sparse Faust to retrieve one factor you'll get a double sparse matrix as a copy of the float sparse matrix.

As well for BSR matrices that aren't not supported by Matlab, the function can't return a bsr matrix so it rather converts it on the fly to a sparse matrix that is finally returned (it applies also for other specialized matrix types).

Example

>> rng(42) % for reproducibility
>> F = matfaust.Faust({sprand(5, 5, .2), sprand(5, 5, .2), sprand(5, 5, .2)});
>> f1 = factors(F, 1)
f1 =
 
   (2,1)       0.9699
   (5,1)       0.1818
   (1,4)       0.0206
   (3,4)       0.8324
   (4,5)       0.2123
 
>> G = factors(F, 2:3) % a new Faust composed of the two last factors of F
G =
 
Faust size 5x5, density 0.36, nnz_sum 9, 2 factor(s):
- FACTOR 0 (double) SPARSE, size 5x5, density 0.16, nnz 4
- FACTOR 1 (double) SPARSE, size 5x5, density 0.2, nnz 5

See also Faust.numfactors

full()

function matfaust::Faust::full

(

F

)

The full matrix implemented by F.

This function overloads a Matlab built-in function.

Usage

    A = full(F)

Warning

using this function 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 dense matrix representation.

Return values

A	the Matlab native matrix such that A*x == F*x for any vector x.

Warning

Running the example below is likely to raise a memory error or freeze your computer for a certain amount of time.

Example

% in a matlab terminal
>> F = matfaust.rand(10^5, 10^5, 'num_factors', 2, 'density', 10^-4, 'fac_type', 'sparse')
 
F =
 
Faust size 100000x100000, density 0.00018, nnz_sum 1800000, 2 factor(s):
- FACTOR 0 (double) SPARSE, size 100000x100000, density 9e-05, nnz 900000
- FACTOR 1 (double) SPARSE, size 100000x100000, density 9e-05, nnz 900000
 
>> % an attempt to convert F to a full matrix is most likely to raise a memory error
>> % the sparse format is the only way to handle such a large Faust
>> full(F)
??? Error using mexFaustReal
std::bad_alloc

get_handle()

function matfaust::Faust::get_handle

(

F

)

Returns the Faust F C++ native object pointer as an integer.

Return values

H	handle (address as an integer).

Example

% in a matlab terminal
>> F = matfaust.rand(10, 10);
>> get_handle(F) % doctest: +ELLIPSIS
ans =
 
  uint64
 
   %>

horzcat()

function matfaust::Faust::horzcat

(

varargin

)

Horizontal concatenation [F,A, B, … ] where F is a Faust and A, B, … are Faust objects or sparse/full matrix.

It's equivalent to cat(2, F, A, B, …).

This function overloads a Matlab built-in function.

Usage

    C=HORZCAT(F,A) concatenates the Faust F and A horizontally. A is a Faust or a sparse/full matrix. The result is the Faust C. HORZCAT(F,A) is the same as [F,G].
    C=HORZCAT(F,A,B,…) concatenates horizontally F to A, B, etc. HORZCAT(F,A, B,…) is the same as [F,A,B,…].

Note

it could be wiser to encapsulate a Faust in a lazylinop.LazyLinearOp for a lazy concatenation.

See also Faust.vertcat, Faust.cat.

imag()

function matfaust::Faust::imag

(

F

)

Returns the imaginary part of the Faust F.

Example:

% in a matlab terminal
>> F = matfaust.rand(10, 10, 'field', 'complex')
 
F =
 
Faust size 10x10, density 2.5, nnz_sum 250, 5 factor(s):
- FACTOR 0 (complex) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 1 (complex) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 2 (complex) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 3 (complex) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 4 (complex) SPARSE, size 10x10, density 0.5, nnz 50
 
 
>> iF = imag(F)
 
iF =
 
Faust size 10x10, density 8, nnz_sum 800, 5 factor(s):
- FACTOR 0 (double) SPARSE, size 10x20, density 0.5, nnz 100
- FACTOR 1 (double) SPARSE, size 20x20, density 0.5, nnz 200
- FACTOR 2 (double) SPARSE, size 20x20, density 0.5, nnz 200
- FACTOR 3 (double) SPARSE, size 20x20, density 0.5, nnz 200
- FACTOR 4 (double) SPARSE, size 20x10, density 0.5, nnz 100
 
>> norm(full(iF) - imag(full(F))) < 1e-12
 
ans =
 
  logical
 
     1

See also Faust.real

imagesc()

function matfaust::Faust::imagesc	(	F	,
		varargin
	)

Displays image of F full matrix and its factors.

This function overloads a Matlab built-in function.

Usage

    imagesc(F)
    imagesc(F, 'faust_name') to name the Faust on the plotted figure.

Parameters

faust_name

(varargin{1}) The Faust name shown in the figure title (defaultly it's 'F').

Data is scaled to use the full colormap.

Example

% in a matlab terminal (without -nojvm flag)
>> F = matfaust.rand(5, 10);
>> imagesc(F) % imagesc(F, 'my faust') to name the faust differently than 'F'
>> print('test_imsc', '-dpng') % figure saved in test_imsc.png file

See also Faust.disp.

insert()

function matfaust::Faust::insert	(	F	,
		i	,
		new_factor
	)

Inserts new_factor at index i in a new Faust copy of F.

Note

this is not a true copy, only references to pre-existed factors are copied.

Parameters

i,int	the index of insertion.
new_factor,matrix	the factor to insert as the i-th factor of F.

Return values

G	a copy of F with new_factor inserted at index i.

Example

>> F = matfaust.rand(10, 10, 'num_factors', 5);
>> S = sprand(10, 10, .2);
>> G = insert(F, 3, S);
>> all(all(full(left(F, 2) * matfaust.Faust(S) * right(F, 3)) == full(G)))
 
ans =
 
 logical
 
  1

See also Faust.factors, Faust.left, Faust.right, Faust.replace

isdense()

function matfaust::Faust::isdense

(

F

)

Returns true if F factors are all dense matrices/arrays false otherwise.

Example

>> F = matfaust.rand(10, 10, 'fac_type', 'dense')
 
F =
 
Faust size 10x10, density 2.5, nnz_sum 250, 5 factor(s):
- FACTOR 0 (double) DENSE, size 10x10, density 0.5, nnz 50
- FACTOR 1 (double) DENSE, size 10x10, density 0.5, nnz 50
- FACTOR 2 (double) DENSE, size 10x10, density 0.5, nnz 50
- FACTOR 3 (double) DENSE, size 10x10, density 0.5, nnz 50
- FACTOR 4 (double) DENSE, size 10x10, density 0.5, nnz 50
 
>> isdense(F)
 
ans =
 
     1
 
>> F = matfaust.rand(10, 10, 'fac_type', 'sparse')
 
F =
 
Faust size 10x10, density 2.5, nnz_sum 250, 5 factor(s):
- FACTOR 0 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 1 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 2 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 3 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 4 (double) SPARSE, size 10x10, density 0.5, nnz 50
 
>> isdense(F)
 
ans =
 
     0
 
>> F = matfaust.rand(10, 10, 'fac_type', 'dense') * matfaust.Faust(speye(10))
 
F =
 
Faust size 10x10, density 2.6, nnz_sum 260, 6 factor(s):
- FACTOR 0 (double) DENSE, size 10x10, density 0.5, nnz 50
- FACTOR 1 (double) DENSE, size 10x10, density 0.5, nnz 50
- FACTOR 2 (double) DENSE, size 10x10, density 0.5, nnz 50
- FACTOR 3 (double) DENSE, size 10x10, density 0.5, nnz 50
- FACTOR 4 (double) DENSE, size 10x10, density 0.5, nnz 50
- FACTOR 5 (double) SPARSE, size 10x10, density 0.1, nnz 10
 
>> isdense(F)
 
ans =
 
     0

See also Faust.issparse, matfaust.rand, matfaust.rand_bsr

isFaust()

static function matfaust::Faust::isFaust ( obj  )

static

Returns true if obj is a Faust object, false otherwise.

Example

% in a matlab terminal
>> import matfaust.Faust
>> import matfaust.isFaust
>> F = matfaust.rand(5,10);
>> Faust.isFaust(F) % isFaust(F) alone works as well
 
ans =
 
 logical
 
    1
 
>> Faust.isFaust(1)
 
ans =
 
 logical
 
    0

See also Faust.Faust

isreal()

function matfaust::Faust::isreal

(

F

)

Indicates if F is a real Faust or a complex Faust.

This function overloads a Matlab built-in function.

Note

If F is a real Faust, all factors are real. If F is a complex Faust, at least one factor is complex.

Usage

    bool = isreal(F)

Return values

bool	1 if F is a real Faust, 0 if it's a complex Faust.

Example:

>> F = matfaust.rand(10, 10, 'field', 'real')
 
F =
 
Faust size 10x10, density 2.5, nnz_sum 250, 5 factor(s):
- FACTOR 0 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 1 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 2 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 3 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 4 (double) SPARSE, size 10x10, density 0.5, nnz 50
 
>> isreal(F)
 
ans =
 
  logical
 
   1
 
>> F = matfaust.rand(10, 10, 'field', 'complex')
 
F =
 
Faust size 10x10, density 2.5, nnz_sum 250, 5 factor(s):
- FACTOR 0 (complex) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 1 (complex) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 2 (complex) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 3 (complex) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 4 (complex) SPARSE, size 10x10, density 0.5, nnz 50
 
>> isreal(F)
 
ans =
 
  logical
 
   0

See also Faust.complex

issparse()

function matfaust::Faust::issparse	(	F	,
		varargin
	)

Returns true if F factors are all sparse matrices false otherwise.

What a sparse factor is, depends on csr and bsr arguments. Defaultly, only a Faust full of CSR matrices is taken as a sparse Faust.

Parameters

csr,bool	true to consider a CSR matrix as a sparse matrix, false otherwise (true by default).
bsr,bool	true to consider a BSR matrix as a sparse matrix, false otherwise (false by default).

Example:

% in a matlab terminal
>> F = matfaust.rand(10, 10, 'fac_type', 'sparse')
 
F =
 
Faust size 10x10, density 2.5, nnz_sum 250, 5 factor(s):
- FACTOR 0 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 1 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 2 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 3 (double) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 4 (double) SPARSE, size 10x10, density 0.5, nnz 50
 
>> issparse(F) % equivalent to issparse(F, 'csr', true)
 
ans =
 
     1
 
>> issparse(F, 'csr', false, 'bsr', false)
 ??? Error using matfaust.Faust/issparse
 It doesn't make sense to set csr=false and bsr=false as the function will
 always return false
 
>> F = matfaust.rand_bsr(10, 10, 2, 2, 2, .1)
 
F =
 
Faust size 10x10, density 0.6, nnz_sum 60, 5 factor(s):
- FACTOR 0 (double) BSR, size 10x10 (blocksize = 2x2), density 0.12, nnz 12 (nnz blocks: 3)
- FACTOR 1 (double) BSR, size 10x10 (blocksize = 2x2), density 0.12, nnz 12 (nnz blocks: 3)
- FACTOR 2 (double) BSR, size 10x10 (blocksize = 2x2), density 0.12, nnz 12 (nnz blocks: 3)
- FACTOR 3 (double) BSR, size 10x10 (blocksize = 2x2), density 0.12, nnz 12 (nnz blocks: 3)
- FACTOR 4 (double) BSR, size 10x10 (blocksize = 2x2), density 0.12, nnz 12 (nnz blocks: 3)
 
>> issparse(F) % default config. recognizes only csr
 
ans =
 
     0
 
>> issparse(F, 'bsr', true)
 
ans =
 
     1
 
>> F = matfaust.rand(10, 10, 'fac_type', 'dense')
 
F =
 
Faust size 10x10, density 2.5, nnz_sum 250, 5 factor(s):
- FACTOR 0 (double) DENSE, size 10x10, density 0.5, nnz 50
- FACTOR 1 (double) DENSE, size 10x10, density 0.5, nnz 50
- FACTOR 2 (double) DENSE, size 10x10, density 0.5, nnz 50
- FACTOR 3 (double) DENSE, size 10x10, density 0.5, nnz 50
- FACTOR 4 (double) DENSE, size 10x10, density 0.5, nnz 50
 
>> issparse(F)
 
ans =
 
     0

See also Faust.isdense, matfaust.rand, matfaust.rand_bsr

left()

function matfaust::Faust::left	(	F	,
		i	,
		varargin
	)

Returns the left hand side factors of F from index 1 to i included (in 1-base index).

Parameters

F	the Faust object.
i	the bound factor index.
'as_faust',logical	(optional): true to return a Faust even if a single factor is asked (length(ids) == 1), otherwise (as_faust == false) and a dense or sparse matrix is returned.

Return values

a	Faust if the number of factors to be returned is greater than 1, an array or a sparse matrix otherwise.

Example

%in a matlab terminal
>> F = matfaust.rand(8, 5, 'seed', 42)
 
F =
 
Faust size 8x5, density 3.675, nnz_sum 147, 5 factor(s):
- FACTOR 0 (double) SPARSE, size 8x7, density 0.714286, nnz 40
- FACTOR 1 (double) SPARSE, size 7x6, density 0.666667, nnz 28
- FACTOR 2 (double) SPARSE, size 6x6, density 0.666667, nnz 24
- FACTOR 3 (double) SPARSE, size 6x5, density 1, nnz 30
- FACTOR 4 (double) SPARSE, size 5x5, density 1, nnz 25
 
>> LF = left(F, 3)
 
LF =
 
Faust size 8x6, density 1.91667, nnz_sum 92, 3 factor(s):
- FACTOR 0 (double) SPARSE, size 8x7, density 0.714286, nnz 40
- FACTOR 1 (double) SPARSE, size 7x6, density 0.666667, nnz 28
- FACTOR 2 (double) SPARSE, size 6x6, density 0.666667, nnz 24

See also Faust.factors, Faust.right

length()

function matfaust::Faust::length

(

F

)

The number of factors of F.

Usage

    A = length(F)

Parameters

F	the Faust object.

Return values

num_factors

the number of factors.

Example

>> F = matfaust.rand(5, 10, 'num_factors', 6);
>> nf = length(F)
 
nf =
 
    6

See also Faust.numfactors

load()

static function matfaust::Faust::load ( filepath  , varargin    )

static

Loads a Faust from a .mat file.

Example

>> import matfaust.Faust
>> F = matfaust.rand(10,10);
>> save(F, 'F.mat')
>> F2 = matfaust.Faust.load('F.mat');
>> F3 = Faust('F.mat');
>> all(all(full(F2) == full(F)))
 
ans =
 
  logical
 
   1
 
>> all(all(full(F3) == full(F)))
 
ans =
 
  logical
 
   1

See also Faust.Faust, Faust.save

load_native()

static function matfaust::Faust::load_native ( filepath  )

static

Loads a Faust from a .mat file (native C++ version).

Example

>> import matfaust.Faust
>> F = matfaust.rand(10,10);
>> save(F, 'F.mat');
>> F2 = matfaust.Faust.load_native('F.mat');
>> F3 = Faust('F.mat');
>> all(all(full(F2) == full(F)))
 
ans =
 
  logical
 
   1
 
>> all(all(full(F3) == full(F)))
 
ans =
 
  logical
 
   1

See also Faust.Faust, Faust.save

minus()

function matfaust::Faust::minus

(

varargin

)

Minus.

This function overloads a Matlab built-in function.

Usage

    minus(F,G) or F-G subtracts the Faust G from F, sizes must be compatible.
    minus(F,A) or F-A subtracts a matrix A from F, sizes must be compatible.
    minus(F,s) or F-s subtracts a scalar s from F, such that full(F-s) == full(F)-s.

Parameters

F	(first arg.) The Faust object.
G,A,s,…	(2nd to n-th args) The variables to subtract from F; Fausts, matrices or scalars.

Return values

M	the difference as a Faust object.

Example:

>> F = matfaust.rand(10, 12);
>> G = matfaust.rand(10, 12);
>> FmG = F-G; % is a Faust
>> norm(full(FmG) - full(F) + full(G)) < 1e-12
 
ans =
 
  logical
 
   1
 
>> Fm2 = F-2; % is a Faust
>> norm(full(Fm2) - full(F) + 2) < 1e-12
 
ans =
 
  logical
 
   1
 
>> FmGm2 = F-G-2; % is a Faust
>> norm(full(FmGm2) - full(F) + full(G) + 2) < 1e-12
 
ans =
 
  logical
 
   1
 
>> H = F-G-F-2-F; % is a Faust
>> norm(full(H) - full(F) + 2*full(F) + full(G) + 2) < 1e-12
 
ans =
 
  logical
 
   1

See also Faust.plus

mldivide()

function matfaust::Faust::mldivide	(	F	,
		B
	)

\ Backslash or left full(F) divide.

Usage

    X = F\ B is the matrix division of full(F) into B, which is roughly the same as Faust.pinv(F)*B.

Warning

this function makes a call to Faust.full.

See also Faust.pinv, mldivide Matlab built-in.

mrdivide()

function matfaust::Faust::mrdivide	(	F	,
		s
	)

/ Slash or right Faust divide.

Usage

    G = F/s is the division of the Faust F by the scalar s, such that full(F)/s == full(F/s)
    G = MRDIVIDE(F,s) is called for the syntax 'F / s' when s is a scalar.

Parameters

F	The Faust object to divide.
s	The scalar to divide F with.

Return values

G	the division result as a Faust object.

See also Faust.mtimes

mtimes()

function matfaust::Faust::mtimes	(	F	,
		A
	)

Multiplies the Faust F by A which is a full matrix, a Faust object or a scalar.

This function overloads a Matlab built-in function.

The primary goal of this function is to implement “fast” multiplication by a Faust, which is the operation performed when A is a full matrix.
In the best case, F*A is rcg(F) times faster than performing the equivalent full(F)*A.

Other use cases are available for this function:

• If A is a Faust, no actual multiplication is performed, instead a new Faust is built to implement the multiplication. This Faust verifies that:

  full(F*A) == full(F)*full(A)

  Note

  an elementwise non-significant absolute difference between the two members is possible (not more than eps(1.0)).

• If A is a scalar, F*A is also a Faust such that:

  factors(F*A,1) == factors(F,1)*A

• Any Faust F (real or complex) can be multiplied by any (real or complex) Faust/array of appropriate dimensions or a scalar.

Usage

    G = mtimes(F, A)
    G = F*A with A and G being full matrices. A could also be a sparse matrix but note that often the Faust-sparse matrix multiplication is slower than performing F*full(A) multiplication. In some cases though, it stays quicker: moreover when the Faust is composed of a small number of factors.
    G = F*s with s a scalar and G a Faust.
    G = s*F with s a scalar and G a Faust.
    G = s*F' with s a scalar multiplying the conjugate-transpose of F.
    G = F'*s with s a scalar multiplying the conjugate-transpose of F.

Parameters

F	the Faust object.
A	either a full matrix, a Faust object or a scalar.

Return values

G	the multiplication result: When A is a full matrix, G = F*A is also a full matrix. When A is a Faust or a scalar, G = F*A is itself a Faust. When either F or A is complex, G=F*A is also complex.

Example

% in a matlab terminal
>> rng(42) % for reproducibility
>> F = matfaust.rand(5, 4, 'seed', 42);
>> A = rand(size(F,2), 5);
>> G = F * A;
>> norm(G - full(F) * A) < 1e-12
 
ans =
 
  logical
 
     1
 
>> % this is equivalent to G = mtimes(F, A)
 
>> G = matfaust.rand(size(F, 2), 15);
>> H = F * G; % H is a Faust because F and G are
>> matfaust.isFaust(H)
 
ans =
 
  logical
 
   1
 
>> Fs = F * 2;
>> sF = 2 * F; % sF == Fs, i.e. the Faust F times 2.
>> matfaust.isFaust(Fs) && matfaust.isFaust(sF)
 
ans =
 
  logical
 
   1

See also Faust.Faust, Faust.rcg, Faust.ctranspose, Faust.complex

nbytes()

function matfaust::Faust::nbytes

(

F

)

Gives the memory size of the Faust in bytes.

Return values

n	Faust size in bytes.

Example:

% in a matlab terminal
>> F = matfaust.rand(1024, 1024, 'num_factors', 6, 'seed', 42);
>> nbytes(F)
 
ans =
 
      393240
 
>> F = matfaust.rand(1024, 1024, 'num_factors', 6, 'fac_type', 'dense');
>> nbytes(F)
 
ans =
 
    50331648

nnz_sum()

function matfaust::Faust::nnz_sum

(

F

)

The total number of nonzeros in the factors of F.

The function sums together the number of nonzeros of each factor and returns the result. Note that for efficiency the sum is computed at Faust creation time and kept in cache.

Usage

    nz = nnz_sum(F)

Parameters

F	the Faust object.

Return values

nz	the number of non-zeros.

Example:

>> F = matfaust.rand(1024, 1024, 'num_factors', 6)
 
F =
 
Faust size 1024x1024, density 0.0292969, nnz_sum 30720, 6 factor(s):
- FACTOR 0 (double) SPARSE, size 1024x1024, density 0.00488281, nnz 5120
- FACTOR 1 (double) SPARSE, size 1024x1024, density 0.00488281, nnz 5120
- FACTOR 2 (double) SPARSE, size 1024x1024, density 0.00488281, nnz 5120
- FACTOR 3 (double) SPARSE, size 1024x1024, density 0.00488281, nnz 5120
- FACTOR 4 (double) SPARSE, size 1024x1024, density 0.00488281, nnz 5120
- FACTOR 5 (double) SPARSE, size 1024x1024, density 0.00488281, nnz 5120
 
>> nnz_sum(F)
 
ans =
 
       30720

See also Faust.rcg, Faust.density.

norm()

function matfaust::Faust::norm	(	F	,
		varargin
	)

The matrix norm of F.

This function overloads a Matlab built-in function.

Several types of norm are available: 1-norm, 2-norm, inf-norm and Frobenius norm.

The norm of F is equal to the norm of full(F).

Warning

The norm computation time can be expected to be of order n*min(F.shape) with n the time for multipliying F by a vector. Nevertheless, the implementation allows that memory usage remains controlled by avoiding to explicitly compute full(F). Please pay attention to the full_array (and batch_size) arguments for a better understanding. Usage

    n = norm(F, 2) the 2-norm or maximum singular value of F: approximately norm(full(F),2) == max(svd(full(F))).

    n = norm(F, 2, 'threshold', 0.001, 'max_num_its', 1000).

    n = norm(F) the same as norm(F, 2).

    n = norm(F, 1) the 1-norm of F: norm(full(F), 1) == max(sum(abs(full(F))))

    n = norm(F, inf) the inf-norm of F: norm(full(F), inf) == max(sum(abs(full(F)')))

    n = norm(F, 'fro') the Frobenius norm of F: norm(full(F), 'fro').

Parameters

F	the Faust object.
p	(optional) the norm order or type. Respectively 1, 2 or inf for the 1-norm, 2-norm and inf-norm or 'fro' for the Frobenius norm (by default the 2-norm is computed).
'threshold',real	(optional) power iteration algorithm threshold (default to .001). Used only for norm(2). It's passed in a key-value pair fashion: 'threshold', .001
'max_num_its',int	(optional) maximum number of iterations for power iteration algorithm. Used only for norm(2). It's passed in a key-value pair fashion: 'max_num_its', 1000.
'full_array',bool	(optional) this argument applies only for 1-norm, inf-norm and Frobenius norm. If true the Faust full array is computed before computing the norm otherwise it is not. By default it is set to false. Many configurations exist in which full_array == False can be more efficient but it needs to finetune the batch_size argument.
'batch_size',int	(optional) this argument applies only when the full_array argument is set to false (for the 1-norm, inf-norm and Frobenius norm). It determines the number of Faust columns (resp. rows) that are built in memory in order to compute the Frobenius norm and the 1-norm (resp. the inf-norm). This parameter is primary in the efficiency of the computation and memory consumption. By default, it is set to 1 (which is certainly not the optimal configuration in many cases in matter of computation time but always the best in term of memory cost).

Return values

n	the norm (real).

Example

% in a matlab terminal
>> F = matfaust.rand(50, 100, 'num_factors', 2, 'dim_sizes', [50, 100], 'density', .5)
>> norm(F)
ans =
436.4094
>> norm(F,2)
ans =
436.4094
>> norm(F, 'fro')
ans =
442.3946
>> norm(F, inf)
ans =
738.0057

See also Faust.normalize

normalize()

function matfaust::Faust::normalize	(	F	,
		varargin
	)

Returns the normalized F.

Usage

    normalize(F,'norm') normalizes columns with vector 2-norm.
    normalize(F,'norm',p) normalizes columns with vector p-norm (see Faust.norm).
    normalize(F,DIM,'norm', 2) normalizes rows (DIM=1) or columns (DIM=2, default) with vector 2-norm.
    normalize(F,DIM,'norm',p) normalizes rows (DIM=1) or columns (DIM=2, default) with vector p-norm.

Examples:

>> F = matfaust.rand(10, 10, 'seed', 42);
>> % normalize columns according to default 2-norm
>> % then test the second column is properly normalized
>> nF2 = normalize(F); % nF2 is a Faust
>> matfaust.isFaust(nF2)
 
ans =
 
  logical
 
   1
 
>> norm(full(nF2(:,2)) - full(F(:,2))/norm(F(:,2))) < 1e-15
 
ans =
 
  logical
 
   1
 
>> % this time normalize rows using 1-norm and test the third row
>> nF1 = normalize(F, 1, 'norm', 1);
>> norm(full(nF1(3, :)) - full(F(3,:))/norm(F(3,:), 1)) < 1e-15
 
ans =
 
  logical
 
   1
 
>> % and the same except  with inf-norm
>> nFinf = normalize(F, 1, 'norm', inf);
>> norm(full(nFinf(3, :)) - full(F(3,:))/norm(F(3,:), inf)) < 1e-15
 
ans =
 
  logical
 
   1

See also Faust.norm

numel()

function matfaust::Faust::numel

(

F

)

The number of elements in F.

It's equivalent to prod(size(F)).

Usage

    n = numel(F)

Parameters

F	the Faust object.

Return values

n	the number of elements of the Faust.

Example

>> F = matfaust.rand(5, 10);
>> n = numel(F)
 
n =
 
    50

See also Faust.size

numfactors()

function matfaust::Faust::numfactors

(

F

)

The number of factors of F.

Note

using length(F) is shorter!

Usage

    A = numfactors(F)

Parameters

F	the Faust object.

Return values

num_factors

the number of factors.

Example

>> F = matfaust.rand(5, 10, 'num_factors', 6);
>> nf = numfactors(F)
 
nf =
        6

See also Faust.factors

opt_butterfly()

static function matfaust::Faust::opt_butterfly ( F  )

static

Optimizes any Faust composed of butterfly factors.

The returned Faust will be more efficient if multiplied by a vector or a matrix. This optimization is based on the diagonals of each butterfly factor. Multiplying a butterfly factor B by a vector x (y = B*x) is equivalent to forming two diagonals D1 and D2 from B and compute y' = D1*x + D2*x(I) where I is set in the proper order to obtain y' = y.

Parameters

F	The Faust to optimize. If the factors of F are not set according to a butterfly structure, the result is not defined.

Return values

G	the optimized Faust.

Example:

% in a matlab terminal
 
>> F = matfaust.dft(32)
 
F =
 
Faust size 32x32, density 0.34375, nnz_sum 352, 6 factor(s):
- FACTOR 0 (complex) SPARSE, size 32x32, density 0.0625, nnz 64
- FACTOR 1 (complex) SPARSE, size 32x32, density 0.0625, nnz 64
- FACTOR 2 (complex) SPARSE, size 32x32, density 0.0625, nnz 64
- FACTOR 3 (complex) SPARSE, size 32x32, density 0.0625, nnz 64
- FACTOR 4 (complex) SPARSE, size 32x32, density 0.0625, nnz 64
- FACTOR 5 (complex) SPARSE, size 32x32, density 0.03125, nnz 32
 
>> oF = matfaust.Faust.opt_butterfly(F)
 
oF =
 
Faust size 32x32, density 0.34375, nnz_sum 352, 6 factor(s):
- FACTOR 0 (complex) Butterfly, size 32x32, density 0.0625, nnz 64
- FACTOR 1 (complex) Butterfly, size 32x32, density 0.0625, nnz 64
- FACTOR 2 (complex) Butterfly, size 32x32, density 0.0625, nnz 64
- FACTOR 3 (complex) Butterfly, size 32x32, density 0.0625, nnz 64
- FACTOR 4 (complex) Butterfly, size 32x32, density 0.0625, nnz 64
- FACTOR 5 (complex) PERM, size 32x32, density 0.03125, nnz 32

See also: matfaust.fact.butterfly, matfaust.dft, matfaust.rand_butterfly.

optimize()

function matfaust::Faust::optimize	(	F	,
		varargin
	)

Returns a Faust optimized with Faust.pruneout, Faust.optimize_memory and Faust.optimize_time.

Usage
    OF = optimize_time(F) returns an optimized Faust object.
    OF = optimize_time(F, 'transp', true) see Faust.optimize_time

Parameters

'transp',bool

(optional) default to false. if true optimize the Faust according to its transpose.

Return values

OF	The optimized Faust.

Note

this function is still experimental, you might use manually Faust.optimize_time, Faust.optimize_memory or Faust.pruneout to be more specific about the optimization to proceed.

Example:

>> F = matfaust.rand(2048, 2048, 'dim_sizes', [1, 1024], 'num_factors', 32, 'fac_type', 'mixed', 'seed', 42);
>> nbytes(F)
 
ans =
 
    14056612
 
>> oF = optimize(F);
>> nbytes(oF)
 
ans =
 
      975904
 
>> % oF is smaller in memory and should be Faster too
>> tic; full(F); tF = toc;
>> tic; full(oF); toF = toc;
>> toF < tF
 
ans =
 
  logical
 
   1
 
>> v = rand(size(F, 1), 1);
>> tic; F*v; tF = toc;
>> tic; oF*v; toF = toc;
>> toF < tF
 
ans =
 
  logical
 
   1

See also Faust.optimize_time, Faust.optimize_memory, Faust.pruneout, Lives Script about Faust optimizations

optimize_memory()

function matfaust::Faust::optimize_memory

(

F

)

Optimizes a Faust by changing the storage format of each factor in order to optimize the memory size.

Return values

OF	The optimized Faust.

Example:

>> F = matfaust.rand(1024, 1024, 'dim_sizes', [1, 1024], 'num_factors', 32, 'fac_type', 'mixed', 'seed', 42);
>> nbytes(F)
 
ans =
 
    13991076
 
>> oF = optimize_memory(F);
>> nbytes(oF)
 
ans =
 
      972672
 
>> % oF is smaller in memory

See also Faust.optimize

optimize_time()

function matfaust::Faust::optimize_time	(	F	,
		varargin
	)

Returns a Faust configured with the quickest Faust-matrix multiplication mode (benchmark ran on the fly).

Note

this function launches a small benchmark on the fly. Basically, the methods available differ by the order used to compute the matrix chain.

The evaluated methods in the benchmark are listed in matfaust.FaustMulMode. Although depending on the package you installed and the capability of your hardware the methods based on Torch library can be used.

Usage
    OF = optimize_time(F) returns a new object with the best product method enabled.
    OF = optimize_time(F, 'inplace', true) modifies directly F instead of creating a new Faust (i.e. OF references the same object as F).
    OF = optimize_time(F, 'transp', true) tries to optimize the Faust transpose instead of the Faust itself.
    OF = optimize_time(F, 'nsamples', 10) benchmarks the product methods by computing 10 products instead of one by default.

Parameters

F	the Faust object.
'inplace',bool	default to false. If true the current Faust is modified directly.
'transp',bool	default to false. If true optimize the Faust according to its transpose.
'nsamples',int	default to 1.The number of Faust-Dense matrix products calculated in order to measure time taken by each method (it could matter to discriminate methods when the performances are similar). By default, only one product is computed to evaluate the method.
'mat',matrix	Use this argument to run the benchmark on the Faust multiplication by the matrix mat instead of Faust.full(). Note that mat must be of the same scalar type as F.

Return values

OF	The optimized Faust.

Example:

>> F = matfaust.rand(2048, 2048, 'dim_sizes', [1, 2048], 'num_factors', 32, 'fac_type', 'dense', 'seed', 42);
>> oF = optimize_time(F); % doctest: +ELLIPSIS
%> >> % oF should be Faster too
>> tF = timeit(@() full(F));
>> toF = timeit(@() full(oF));
>> toF < tF % doctest: +ELLIPSIS
 
ans =
 
%>
   1

See also Faust.optimize, matfaust.FaustMulMode

pinv()

function matfaust::Faust::pinv

(

F

)

Pseudoinverse matrix of full(F).

This function overloads a Matlab built-in function.

Usage

    X = PINV(F) produces the matrix X of the same dimensions as F' so that F*(F'*X')' == full(F) (or approximately).

Warning

this function makes a call to Faust.full.

Example:

>> F = matfaust.rand(128, 32);
>> M = full(F);
>> norm(pinv(M)-pinv(F))/norm(pinv(M))
 
ans =
 
     0
 
>> norm(M-(F*(F'*pinv(F)')))/norm(M) < 1e-12
 
ans =
 
 logical
 
    1

See also Faust.mldivide, pinv Matlab built-in, matfaust.fact.pinvtj

plus()

function matfaust::Faust::plus

(

varargin

)

Plus.

This function overloads a Matlab built-in function.

Usage

    plus(F,G) or F+G adds two Faust together, sizes must be compatible.
    plus(F,A) or F+A adds a Faust and a matrix A, sizes must be compatible.
    plus(F,s) or F+s, with s being a scalar, such that full(F+s) == full(F)+s.

Parameters

F	(first arg.) The Faust object.
G,A,s,…	(2nd to n-th args) The variables to add to F; Fausts, matrices or scalars.

Return values

S	the sum as a Faust object.

Examples:

>> F = matfaust.rand(10, 12);
>> G = matfaust.rand(10, 12);
>> FpG = F+G; % is a Faust
>> matfaust.isFaust(FpG)
 
ans =
 
 logical
 
    1
 
>> norm(full(FpG) - full(F) - full(G)) < 1e-12
 
ans =
 
 logical
 
    1
 
>> Fp2 = F+2; % is a Faust
>> norm(full(Fp2) - full(F) - 2) < 1e-12
 
ans =
 
 logical
 
    1
 
>> FpGp2 = F+G+2; % is a Faust
>> norm(full(FpGp2) - full(F) - full(G) - 2) < 1e-12
 
ans =
 
 logical
 
    1
 
>> H = F+G+F+2+F; % is a Faust
>> norm(full(H) - 3*full(F) - full(G) - 2) < 1e-12
 
ans =
 
 logical
 
    1

See also Faust.minus

power_iteration()

function matfaust::Faust::power_iteration	(	F	,
		varargin
	)

Performs the power iteration algorithm to compute the greatest eigenvalue of the Faust.

For the algorithm to succeed the Faust should be diagonalizable (similar to a digonalizable Faust), ideally, a symmetric positive-definite Faust.

Parameters

'threshold',real	(optional) the precision required on the eigenvalue. Default value is 1e-3.
'maxiter',integer	(optional) the number of iterations above what the algorithm will stop anyway. Default value is 100.

Return values

lambda

the greatest eigenvalue approximate.

Example:

%in a matlab terminal
>> F = matfaust.rand(8, 5, 'seed', 42);
>> l1 = power_iteration(F*F');
>> % the 2-norm of F is its greatest singular value
>> % which is also the square root of the greatest eigenvalue of F*F'
>> abs(sqrt(l1) - norm(full(F), 2)) < 1e-12
 
ans =
 
  logical
 
     1

pruneout()

function matfaust::Faust::pruneout	(	F	,
		varargin
	)

Returns a Faust optimized by removing useless zero rows and columns as many times as needed.

Parameters

F	the Faust to optimize.
'thres',int	(optional) the threshold of number of nonzeros under what the rows/columns are removed.

Return values

G	The optimized Faust.

Example:

>> F = matfaust.rand(1024, 1024, 'dim_sizes', [1, 1024], 'num_factors', 32, 'fac_type', 'mixed', 'seed', 42);
>> pF = pruneout(F);
>> nbytes(pF) <  nbytes(F)
 
ans =
 
 logical
 
    1
 
>> % pF is smaller in memory and should be Faster too
>> tF = timeit(@() full(F));
>> tpF = timeit(@() full(pF));
>> tpF < tF
 
ans =
 
  logical
 
   1

See also Faust.optimize, Faust.nbytes

rcg()

function matfaust::Faust::rcg

(

F

)

The Relative Complexity Gain of F.

The RCG is the theoretical gain brought by the Faust representation relatively to its dense matrix equivalent.
The higher is the RCG, the more computational savings are made. This gain applies both for storage space and computation time.

Note

rcg(F) == 1/density(F)

Usage

    gain = rcg(F)

Parameters

F	the Faust object.

Return values

gain	the RCG value (real).

Example

>> F = matfaust.rand(1024, 1024)
 
F =
 
Faust size 1024x1024, density 0.0244141, nnz_sum 25600, 5 factor(s):
- FACTOR 0 (double) SPARSE, size 1024x1024, density 0.00488281, nnz 5120
- FACTOR 1 (double) SPARSE, size 1024x1024, density 0.00488281, nnz 5120
- FACTOR 2 (double) SPARSE, size 1024x1024, density 0.00488281, nnz 5120
- FACTOR 3 (double) SPARSE, size 1024x1024, density 0.00488281, nnz 5120
- FACTOR 4 (double) SPARSE, size 1024x1024, density 0.00488281, nnz 5120
 
>> rcg(F)
 
ans =
 
   40.9600
 
>> numel(F)/nnz_sum(F)
 
ans =
 
   40.9600

See also Faust.density, Faust.nnz_sum, Faust.size.

real()

function matfaust::Faust::real

(

F

)

Returns the real part of the Faust F.

Example:

% in a matlab terminal
>> F = matfaust.rand(10, 10, 'field', 'complex')
 
F =
 
Faust size 10x10, density 2.5, nnz_sum 250, 5 factor(s):
- FACTOR 0 (complex) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 1 (complex) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 2 (complex) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 3 (complex) SPARSE, size 10x10, density 0.5, nnz 50
- FACTOR 4 (complex) SPARSE, size 10x10, density 0.5, nnz 50
 
 
>> rF = real(F)
 
rF =
 
Faust size 10x10, density 8, nnz_sum 800, 5 factor(s):
- FACTOR 0 (double) SPARSE, size 10x20, density 0.5, nnz 100
- FACTOR 1 (double) SPARSE, size 20x20, density 0.5, nnz 200
- FACTOR 2 (double) SPARSE, size 20x20, density 0.5, nnz 200
- FACTOR 3 (double) SPARSE, size 20x20, density 0.5, nnz 200
- FACTOR 4 (double) SPARSE, size 20x10, density 0.5, nnz 100
 
>> norm(full(rF) - real(full(F))) < 1e-12
 
ans =
 
  logical
 
     1

See also Faust.imag

replace()

function matfaust::Faust::replace	(	F	,
		i	,
		new_factor
	)

Replaces the factor of index i by new_factor in a new Faust copy of F.

Note

this is not a true copy, only references to pre-existed factors are copied.

Parameters

i,int	the factor index to replace.
new_factor,matrix	the factor replacing the i-th factor of F.

Return values

G	a copy of F with the i-th factor replaced by new_factor.

Example

>> F = matfaust.rand(10, 10, 'num_factors', 5);
>> S = sprand(10, 10, .2);
>> G = replace(F, 3, S);
>> all(all(full(left(F, 2) * matfaust.Faust(S) * right(F, 4)) == full(G)))
 
ans =
 
 logical
 
  1

See also Faust.factors, Faust.left, Faust.right, Faust.insert

right()

function matfaust::Faust::right	(	F	,
		i	,
		varargin
	)

Returns the right hand side factors of F from index i to end (in 1-base index).

Parameters

F	the Faust object.
i	the bound factor index.
'as_faust',logical	(optional): true to return a Faust even if a single factor is asked (length(ids) == 1), otherwise (as_faust == false) and a dense or sparse matrix is returned.

Return values

a	Faust if the number of factors to be returned is greater than 1, an array or a sparse matrix otherwise.

Example

>> F = matfaust.rand(7,7, 'dim_sizes', [7, 10], 'seed', 42)
 
F =
 
Faust size 7x7, density 3.97959, nnz_sum 195, 5 factor(s):
- FACTOR 0 (double) SPARSE, size 7x9, density 0.555556, nnz 35
- FACTOR 1 (double) SPARSE, size 9x8, density 0.625, nnz 45
- FACTOR 2 (double) SPARSE, size 8x8, density 0.625, nnz 40
- FACTOR 3 (double) SPARSE, size 8x7, density 0.714286, nnz 40
- FACTOR 4 (double) SPARSE, size 7x7, density 0.714286, nnz 35
 
>> RF = right(F, 2)
 
RF =
 
Faust size 9x7, density 2.53968, nnz_sum 160, 4 factor(s):
- FACTOR 0 (double) SPARSE, size 9x8, density 0.625, nnz 45
- FACTOR 1 (double) SPARSE, size 8x8, density 0.625, nnz 40
- FACTOR 2 (double) SPARSE, size 8x7, density 0.714286, nnz 40
- FACTOR 3 (double) SPARSE, size 7x7, density 0.714286, nnz 35

See also Faust.factors, Faust.left

save()

function matfaust::Faust::save	(	F	,
		filepath
	)

Saves the Faust F into a file.

The file is saved in Matlab format version 5 (.mat extension).

Note

Storing F should typically use rcg(F) times less disk space than storing full(F). See Faust.nbytes for a precise size.

Usage

    save(F, filepath)

Parameters

F	the Faust object.
filepath	the path for saving the Faust. The filename should end with .mat and it must be a character array.

Example

>> import matfaust.Faust
>> F = matfaust.rand(5, 10);
>> save(F, 'F.mat')
>> G = Faust('F.mat');
>> all(all(full(F) == full(G)))
 
ans =
 
 logical
 
  1

See also Faust.Faust, Faust.rcg, Faust.load, Faust.load_native

single()

function matfaust::Faust::single

(

F

)

Returns a new Faust whose class is single. It allows to convert all the factors to single precision.

Usage

    sF = single(F)

Return values

sF	the single class/precision Faust.

Example:

>> dF = matfaust.rand(5, 5, 'field', 'real', 'class', 'double')
 
dF =
 
Faust size 5x5, density 5, nnz_sum 125, 5 factor(s):
- FACTOR 0 (double) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 1 (double) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 2 (double) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 3 (double) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 4 (double) SPARSE, size 5x5, density 1, nnz 25
 
>> sF = single(dF)
 
sF =
 
Faust size 5x5, density 5, nnz_sum 125, 5 factor(s):
- FACTOR 0 (float) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 1 (float) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 2 (float) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 3 (float) SPARSE, size 5x5, density 1, nnz 25
- FACTOR 4 (float) SPARSE, size 5x5, density 1, nnz 25

See also Faust.class, Faust.double

size()

function matfaust::Faust::size	(	F	,
		varargin
	)

The size of F.

The size is a pair of numbers: the number of rows and the number of columns of full(F).

Usage

    [nrows, ncols] = size(F)
    n = size(F,dim) with n being the size of the dim-th dimension of F.
                 In other words n == nrows if dim == 1, n == ncols if dim == 2.

Parameters

F	the Faust object.
dim	(optional) the index of the dimension to get the size of.

Example

>> F = matfaust.rand(5, 10);
>> [nrows, ncols] = size(F)
 
nrows =
 
     5
 
ncols =
 
    10
 
>> nrows = size(F, 1)
 
nrows =
 
     5
 
>> ncols = size(F, 2)
 
ncols =
 
    10

See also Faust.nnz_sum, Faust.numel

subsref()

function matfaust::Faust::subsref	(	F	,
		S
	)

Subscripted reference of a Faust.

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 overloads a Matlab built-in.

Warning

• It is not advised to use this function as an element accessor (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 repetitively.
• Subindexing a Faust which would create an empty Faust will raise an error.

Usage

    G = F(I,J) the Faust representing the sub-matrix of full(F) defined by the subscript vectors I and J (see examples below).

Parameters

F	the Faust object.
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).

Return values

The	Faust object requested or just the corresponding scalar if that Faust has a size equal to [1,1].

Example

>> F = matfaust.rand(50, 100);
>> fF = full(F);
>> i = randi(min(size(F)), 1, 2);
>> i1 = i(1); i2 = i(2);
>> F(i1, i2); % is the scalar element located
>> % at row i1, column i2 of the F dense matrix
>> F(i1,i2) == fF(i1,i2)
 
ans =
 
 logical
 
  1
 
>> F(:,i2); % full column i2
>> all(all(full(F(:,i2)) == fF(:,i2)))
 
ans =
 
 logical
 
  1
 
>> F(3:4,2:5); % from row 3 to line 4, each row containing only elements from column 2 to 5.
>> all(all(full(F(3:4,2:5)) == fF(3:4,2:5)))
 
ans =
 
 logical
 
  1
 
>> F(1:end,5:end-1); % from row 1 to end row, each one containing only elements from column 5 to column before the last one.
>> all(all(full(F(1:end,5:end-1)) == fF(1:end,5:end-1)))
 
ans =
 
 logical
 
  1
 
>> F(1:2:end,:); % every row of odd index
>> all(all(full(F(1:2:end,:)) == fF(1:2:end,:)))
 
ans =
 
 logical
 
  1
 
>> F(end:-2:1,:); %  starts from the last row and goes backward to take one in two rows until the first one (reversing row order of F)
>> all(all(full(F(end:-2:1,:)) == fF(end:-2:1,:)))
 
ans =
 
 logical
 
  1
 
>> F([1,18,2],:); % takes in this order the rows 1, 18 and 2.
>> all(all(full(F([1,18,2],:)) == fF([1,18,2],:)))
 
ans =
 
 logical
 
  1
 
>> F(:,[1,18,2]); % takes in this order the columns 1, 18 and 2
>> all(all(full(F(:,[1,18,2])) == fF(:,[1,18,2])))
 
ans =
 
 logical
 
  1
 
>> F([1,18,2], [1,2]); % takes the rows 1, 18 and 2 but keeps only columns 1 and 2 in these rows.
>> all(all(full(F([1,18,2], [1,2])) == fF([1,18,2], [1,2])))
 
ans =
 
 logical
 
  1

See also Faust.end.

transpose()

function matfaust::Faust::transpose

(

F

)

The transpose of F.

This function overloads a Matlab built-in function/operator.

Usage

    F_trans = transpose(F)
    F_trans = F.'

Parameters

F	the Faust object.

Return values

F_trans

a Faust object implementing the transpose of full(F) such that: full(F_trans) == full(F).' == transpose(full(F)).

Example

>> F = matfaust.rand(8, 2);
>> F_trans = F.';
>> size(F_trans)
ans =
 
     2     8
 
>> % is equivalent to
>> F_trans = transpose(F);
>> size(F_trans)
ans =
 
     2     8

See also Faust.conj, Faust.ctranspose

uminus()

function matfaust::Faust::uminus

(

F

)

Returns - F.

---

This function overloads a Matlab built-in function.

Example:

% in a matlab terminal
>> F = matfaust.rand(10, 10);
>> mF = -F;
>> all(all(full(mF) == - full(F)))
 
ans =
 
  logical
 
   1

See also Faust.sum, Faust.mtimes

uplus()

function matfaust::Faust::uplus

(

F

)

Returns + F.

---

This function overloads a Matlab built-in function.

Example:

% in a matlab terminal
>> F = matfaust.rand(10, 10);
>> pF = +F;
>> all(all(full(pF) == + full(F)))
 
ans =
 
  logical
 
   1

See also Faust.plus

vertcat()

function matfaust::Faust::vertcat

(

varargin

)

Vertical concatenation [F;A;B;…] where F is a Faust and A, B, … are Faust objects or sparse/full matrices.

It's equivalent to cat(1, F, A, B, …).

This function overloads a Matlab built-in function.

Usage

    C=VERTCAT(F,A) concatenates the Faust F and A vertically. A is a Faust or a sparse/full matrix. The result is the Faust C. VERTCAT(F,A) is the same as [F;G].
    C=VERTCAT(F, A, B,…) concatenates vertically F to A, B etc. VERTCAT(F, A, B,…) is the same as [F;A;B;…].

Note

it could be wiser to encapsulate a Faust in a lazylinop.LazyLinearOp for a lazy concatenation.

See also Faust.horzcat, Faust.cat.

Member Data Documentation

dev

Property matfaust::Faust::dev

protected

See Faust.device.

dtype

Property matfaust::Faust::dtype

protected

See Faust.class.

is_real

Property matfaust::Faust::is_real

protected

See Faust.isreal.

matrix

Property matfaust::Faust::matrix

protected

Underlying Faust native object handle.

---

The documentation for this class was generated from the following file:

• Faust.m