-: pyfaust Namespace Reference

The FAuST Python Wrapper More...

Namespaces
	demo
	The pyfaust demo module.

	fact
	The pyfaust factorization module.

	factparams
	The module for the parameterization of FAuST's algorithms (Palm4MSA and Hierarchical Factorization). See also: pyfaust.fact.hierarchical, pyfaust.fact.palm4msa.

	poly
	The pyfaust module for polynomial basis as Faust objects.

	proj
	This module provides matrix projectors.

	tools
	The pyfaust tools module.

Classes
class	Faust
	FAuST Python wrapper main class for using multi-layer sparse transforms. More...

class	FaustMulMode
	Enumeration class of all matrix chain multiplication methods available to multiply a Faust to a matrix or to compute Faust.toarray(). More...

Functions
def	version ()
	Returns the FAuST package version. More...

def	faust_fact (args, *kwargs)
	This function is a shorthand for pyfaust.fact.hierarchical. More...

def	license ()
	Prints the FAuST license. More...

def	norm (F, ord='fro', **kwargs)
	Returns Faust.norm(F, ord) or numpy.linalg.norm(F, ord) depending of F type. More...

def	dot (A, B, **kwargs)
	Returns Faust.dot(A,B) if A or B is a Faust object, returns numpy.dot(A,B) ortherwise. More...

def	pinv (F)
	A package function alias for the member function Faust.pinv(). More...

def	concatenate (_tuple, args, axis=0, *kwargs)
	A package function alias for the member function Faust.concatenate. More...

def	hstack (_tuple)
	Concatenates horizontally Faust-s and/or numpy.ndarray objects using Faust.concatenate(). More...

def	vstack (_tuple)
	Concatenates vertically Faust-s and/or numpy.ndarray arrays using Faust.concatenate(). More...

def	isFaust (obj)
	Package alias function of Faust.isFaust. More...

def	wht (n, normed=True, dev="cpu", dtype='float64')
	Constructs a Faust implementing the Walsh-Hadamard Transform (WHT) of order n. More...

def	bitrev_perm (n)
	Bitreversal permutation. More...

def	dft (n, normed=True, dev='cpu', diag_opt=False)
	Constructs a Faust F implementing the Discrete Fourier Transform (DFT) of order n. More...

def	dct (n, normed=True, dev='cpu', dtype='float64')
	Constructs a Faust implementing the Direct Cosine Transform (Type II) Faust of order n. More...

def	dst (n, normed=True, dev='cpu', dtype='float64')
	Constructs a Faust implementing the Direct Sine Transform (Type II) Faust of order n. More...

def	circ (c, dev='cpu', diag_opt=False)
	Returns a circulant Faust C defined by the vector c (which is the first column of C.toarray()). More...

def	anticirc (c, dev='cpu', diag_opt=False)
	Returns an anti-circulant Faust A defined by the vector c (which is the last column of A.toarray()). More...

def	toeplitz (c, r=None, dev='cpu', diag_opt=False)
	Constructs a toeplitz Faust whose first column is c and first row r. More...

def	eye (m, n=None, dtype='float64', dev="cpu")
	Faust identity. More...

def	rand_bsr (num_rows, num_cols, bnrows, bncols, num_factors=None, density=.1, dev='cpu', dtype='float64')
	Generates a random Faust composed only of BSR matrices. More...

def	rand (num_rows, num_cols, num_factors=None, dim_sizes=None, density=None, fac_type='sparse', per_row=True, dev='cpu', dtype='float64', field=None, seed=0)
	Generates a random Faust. More...

def	rand_butterfly (n, dtype='float64', dev='cpu', diag_opt=False)
	Constructs a Faust corresponding to the product of log2(n) square factors of size n with butterfly supports and random nonzero coefficients. More...

def	opt_butterfly_faust (F)
	Optimizes any Faust composed of butterfly factors. More...

def	enable_gpu_mod (libpaths=None, backend='cuda', silent=False, fatal=False)
	This function loads explicitly the gpu_mod library in memory. More...

def	is_gpu_mod_enabled ()
	Returns True if the gpu_mod plug-in has been loaded correctly, False otherwise. More...

def	is_gpu_mod_working ()
	This function returns True if gpu_mod is working properly False otherwise. More...

def	seed (s)
	(Re)Initializes the pyfaust pseudo-random generator. More...

def	faust_logo ()
	Generates the FAµST logo and returns it as a Faust. More...

Detailed Description

The FAuST Python Wrapper

Function Documentation

◆ anticirc()

def pyfaust.anticirc	(	c,
		dev = `'cpu'`,
		diag_opt = `False`
	)

Returns an anti-circulant Faust A defined by the vector c (which is the last column of A.toarray()).

Parameters

c	(np.ndarray) the vector to define the anti-circulant Faust.
dev	(str) the device on which the Faust is created, 'cpu' (default) or 'gpu'.
diag_opt	(bool) cf. pyfaust.circ.

Examples

>>> from pyfaust import anticirc
>>> import numpy as np
>>> c = [1, 2, 3, 4, 5, 6, 7, 8]
>>> A = anticirc(c)
>>> A

Faust size 8x8, density 1.5, nnz_sum 96, 6 factor(s):

FACTOR 0 (complex) SPARSE, size 8x8, density 0.25, nnz 16
FACTOR 1 (complex) SPARSE, size 8x8, density 0.25, nnz 16
FACTOR 2 (complex) SPARSE, size 8x8, density 0.25, nnz 16
FACTOR 3 (complex) SPARSE, size 8x8, density 0.25, nnz 16
FACTOR 4 (complex) SPARSE, size 8x8, density 0.25, nnz 16
FACTOR 5 (complex) SPARSE, size 8x8, density 0.25, nnz 16

>>> np.allclose(A.toarray()[:, -1], c)
True
>>> np.real(A.toarray())
array([[2., 3., 4., 5., 6., 7., 8., 1.],
[3., 4., 5., 6., 7., 8., 1., 2.],
[4., 5., 6., 7., 8., 1., 2., 3.],
[5., 6., 7., 8., 1., 2., 3., 4.],
[6., 7., 8., 1., 2., 3., 4., 5.],
[7., 8., 1., 2., 3., 4., 5., 6.],
[8., 1., 2., 3., 4., 5., 6., 7.],
[1., 2., 3., 4., 5., 6., 7., 8.]])
>>> # Look at the density of a larger anticirculant Faust
>>> # it indicates a speedup of the Faust-matrix/vector product
>>> anticirc(np.random.rand(1024)).density()
0.0390625

See also: pyfaust.circ, pyfaust.toeplitz

◆ bitrev_perm()

def pyfaust.bitrev_perm ( n )

Bitreversal permutation.

Parameters

n	(int) the size of the permutation, it must be a power of two. P dimensions will be n x n

Returns: P a scipy csr_matrix defining the bit-reversal permutation.

See also: pyfaust.dft

◆ circ()

def pyfaust.circ	(	c,
		dev = `'cpu'`,
		diag_opt = `False`
	)

Returns a circulant Faust C defined by the vector c (which is the first column of C.toarray()).

Parameters

c	(np.ndarray) the vector to define the circulant Faust.
dev	(str) the device on which the Faust is created, 'cpu' (default) or 'gpu'.
diag_opt	(bool) if True then the returned Faust is optimized using pyfaust.opt_butterfly_faust (because the DFT is used to implement circ).

Examples

>>> from pyfaust import circ
>>> import numpy as np
>>> c = [1, 2, 3, 4, 5, 6, 7, 8]
>>> C = circ(c)
>>> C

Faust size 8x8, density 1.5, nnz_sum 96, 6 factor(s):

FACTOR 0 (complex) SPARSE, size 8x8, density 0.25, nnz 16
FACTOR 1 (complex) SPARSE, size 8x8, density 0.25, nnz 16
FACTOR 2 (complex) SPARSE, size 8x8, density 0.25, nnz 16
FACTOR 3 (complex) SPARSE, size 8x8, density 0.25, nnz 16
FACTOR 4 (complex) SPARSE, size 8x8, density 0.25, nnz 16
FACTOR 5 (complex) SPARSE, size 8x8, density 0.25, nnz 16

>>> np.allclose(C.toarray()[:, 0], c)
True
>>> np.real(C.toarray())
array([[1., 8., 7., 6., 5., 4., 3., 2.],
[2., 1., 8., 7., 6., 5., 4., 3.],
[3., 2., 1., 8., 7., 6., 5., 4.],
[4., 3., 2., 1., 8., 7., 6., 5.],
[5., 4., 3., 2., 1., 8., 7., 6.],
[6., 5., 4., 3., 2., 1., 8., 7.],
[7., 6., 5., 4., 3., 2., 1., 8.],
[8., 7., 6., 5., 4., 3., 2., 1.]])
>>> # Look at the density of a larger circulant Faust
>>> # it indicates a speedup of the Faust-matrix/vector product
>>> circ(np.random.rand(1024)).density()
0.0390625

See also: scipy.linalg.circulant, pyfaust.anticirc, pyfaust.toeplitz

◆ concatenate()

def pyfaust.concatenate	(		_tuple,
		*	args,
			axis = `0`,
		**	kwargs
	)

A package function alias for the member function Faust.concatenate.

Examples

>>> from pyfaust import *
>>> seed(42) # just for reproducibility
>>> F1 = rand(5,50)
>>> F2 = rand(5,50)
>>> concatenate((F1, F2), axis=0)

Faust size 10x50, density 2.17, nnz_sum 1085, 6 factor(s):

FACTOR 0 (double) SPARSE, size 10x67, density 0.0746269, nnz 50
FACTOR 1 (double) SPARSE, size 67x33, density 0.151515, nnz 335
FACTOR 2 (double) SPARSE, size 33x31, density 0.16129, nnz 165
FACTOR 3 (double) SPARSE, size 31x56, density 0.0892857, nnz 155
FACTOR 4 (double) SPARSE, size 56x100, density 0.05, nnz 280
FACTOR 5 (double) SPARSE, size 100x50, density 0.02, nnz 100

See also: numpy.concatenate, Faust.concatenate,

◆ dct()

def pyfaust.dct	(	n,
		normed = `True`,
		dev = `'cpu'`,
		dtype = `'float64'`
	)

Constructs a Faust implementing the Direct Cosine Transform (Type II) Faust of order n.

The analytical formula of DCT II used here is: \(2 \sum_{i=0}^{n-1} x_i cos \left( {\pi k (2i + 1)} \over {2n} \right)\)

Parameters

n	(int) the order of the DCT (must be a power of two).
normed	(bool) default to True to normalize the DFT Faust as if you called Faust.normalize() and False otherwise.
dev	(str) the device on which the Faust is created.
dtype	(str) 'float64' (default) or 'float32'.

Returns: The DCT Faust.

Examples

>>> from pyfaust import dct
>>> from scipy.fft import dct as scipy_dct
>>> import numpy as np
>>> DCT8 = dct(8, normed=False)
>>> x = np.arange(8).astype('double')
>>> np.real(DCT8@x)
array([ 56.        , -25.76929209,   0.        ,  -2.6938192 ,
0.        ,  -0.80361161,   0.        ,  -0.20280929])
>>> scipy_dct(x)
array([ 56.        , -25.76929209,   0.        ,  -2.6938192 ,
0.        ,  -0.80361161,   0.        ,  -0.20280929])
>>> np.allclose(DCT8@x, scipy_dct(x))
True
>>> # check the density with a larger DCT Faust of size 1024
>>> dct(1024).density()
0.076171875
>>> # it is smaller than 1

See also: pyfaust.dft, pyfaust.dst, scipy.fft.dct, pyfaust.fact.butterfly, pyfaust.rand_butterfly, pyfaust.Faust.density

◆ dft()

def pyfaust.dft	(	n,
		normed = `True`,
		dev = `'cpu'`,
		diag_opt = `False`
	)

Constructs a Faust F implementing the Discrete Fourier Transform (DFT) of order n.

The factorization corresponds to the butterfly structure of the Cooley-Tukey FFT algorithm. The resulting Faust is complex and has (log2(n)+1) sparse factors. The log2(n) first has 2 nonzeros per row and per column. The last factor is a bit-reversal permutation matrix.

Parameters

n	(int) order of the Discrete Fourier Transform (must be a power of two).
normed	(bool) default to True to normalize the DFT Faust as if you called Faust.normalize() and False otherwise.
dev	(str) device to create the Faust on ('cpu' or 'gpu').
diag_opt	(bool) if True then the returned Faust is optimized using pyfaust.opt_butterfly_faust.

Returns: The Faust implementing the DFT of dimension n.

Examples

>>> from pyfaust import dft

>>> dft(1024)

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

>>> dft(1024, normed=True) # is equiv. to next call

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

>>> dft(1024, normed=False).normalize()

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

See also: pyfaust.bitrev, pyfaust.wht, pyfaust.dct, pyfaust.dst, scipy.fft.fft, pyfaust.fact.butterfly, pyfaust.rand_butterfly.

◆ dot()

def pyfaust.dot	(		A,
			B,
		**	kwargs
	)

Returns Faust.dot(A,B) if A or B is a Faust object, returns numpy.dot(A,B) ortherwise.

See also: Faust.norm,

◆ dst()

def pyfaust.dst	(	n,
		normed = `True`,
		dev = `'cpu'`,
		dtype = `'float64'`
	)

Constructs a Faust implementing the Direct Sine Transform (Type II) Faust of order n.

The analytical formula of DST II used here is: \(2 \sum_{i=0}^{n-1} x_i sin \left( {\pi (k+1) (2i + 1)} \over {2n} \right)\)

Parameters

n	(int) the order of the DST (must be a power of two).
normed	(bool) default to True to normalize the Hadamard Faust as if you called Faust.normalize() and False otherwise.
dev	(str) the device on which the Faust is created.
dtype	(str) 'float64' (default) or 'float32'.

Returns: The DST Faust.

Examples

>>> from pyfaust import dst
>>> from scipy.fft import dst as scipy_dst
>>> import numpy as np
>>> DST8 = dst(8, normed=False)
>>> x = np.ones(8)
>>> np.real(DST8@x)
array([1.02516618e+01, 4.93038066e-32, 3.59990489e+00, 3.94430453e-31,
2.40537955e+00, 9.86076132e-32, 2.03918232e+00, 0.00000000e+00])
>>> scipy_dst(x)
array([10.25166179,  0.        ,  3.59990489,  0.        ,  2.40537955,
0.        ,  2.03918232,  0.        ])
>>> np.allclose(DST8@x, scipy_dst(x))
True
>>> # check the density with a larger DST Faust of size 1024
>>> dst(1024).density()
0.201171875
>>> # it is smaller than 1

See also: pyfaust.dft, pyfaust.dct, scipy.fft.dst, pyfaust.fact.butterfly, pyfaust.rand_butterfly, pyfaust.Faust.density

◆ enable_gpu_mod()

def pyfaust.enable_gpu_mod	(	libpaths = `None`,
		backend = `'cuda'`,
		silent = `False`,
		fatal = `False`
	)

This function loads explicitly the gpu_mod library in memory.

Normally it's not required to load the library manually, but it could be useful to set a non-default path or to diagnose a loading issue.

Parameters

libpaths	(list[str]) the absolute or relative paths where to search the dynamic library (gm) to load. By default, it's none to auto-find the library (if possible).
backend	(str) the GPU backend to use, only 'cuda' is available for now.
silent	(bool) if True nothing or almost will be displayed on loading, otherwise all messages are visible.

◆ eye()

def pyfaust.eye	(	m,
		n = `None`,
		dtype = `'float64'`,
		dev = `"cpu"`
	)

Faust identity.

Parameters

m	(int) number of rows,
n	(int) number of columns, set to m by default.
dtype	(str) the dtype of the identity ('float32', the default 'float64'/'double', or 'complex'/'complex128').

Examples

>>> from pyfaust import eye

>>> eye(5)

Faust size 5x5, density 0.2, nnz_sum 5, 1 factor(s):

FACTOR 0 (double) SPARSE, size 5x5, density 0.2, nnz 5 identity matrix flag

>>> eye(5, 4)

Faust size 5x4, density 0.2, nnz_sum 4, 1 factor(s):

FACTOR 0 (double) SPARSE, size 5x4, density 0.2, nnz 4 identity matrix flag

>>> eye(5, dtype='complex')

Faust size 5x5, density 0.2, nnz_sum 5, 1 factor(s):

FACTOR 0 (complex) SPARSE, size 5x5, density 0.2, nnz 5 identity matrix flag

◆ faust_fact()

def pyfaust.faust_fact	(	*	args,
		**	kwargs
	)

This function is a shorthand for pyfaust.fact.hierarchical.

See also: pyfaust.fact.hierarchical

◆ faust_logo()

def pyfaust.faust_logo ( )

Generates the FAµST logo and returns it as a Faust.

Examples

>>> import pyfaust as pf
>>> pf.seed(42)
>>> logo = pf.faust_logo()
>>> logo

Faust size 50x50, density 1.3412, nnz_sum 3353, 5 factor(s):

FACTOR 0 (double) DENSE, size 50x50, density 0.2372, nnz 593
FACTOR 1 (double) DENSE, size 50x50, density 0.3228, nnz 807
FACTOR 2 (double) DENSE, size 50x50, density 0.2432, nnz 608
FACTOR 3 (double) DENSE, size 50x50, density 0.3564, nnz 891
FACTOR 4 (double) DENSE, size 50x50, density 0.1816, nnz 454

>>> # logo.imshow()
>>> # import matplotlib.pyplot as plt
>>> # plot.show()

◆ hstack()

def pyfaust.hstack ( _tuple )

Concatenates horizontally Faust-s and/or numpy.ndarray objects using Faust.concatenate().

See also numpy.hstack

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

Examples

>>> from pyfaust import *
>>> seed(42) # just for reproducibility
>>> F1 = rand(5,50)
>>> F2 = rand(5,50)
>>> hstack((F1, F2))

Faust size 5x100, density 1.99, nnz_sum 995, 6 factor(s):

FACTOR 0 (double) SPARSE, size 5x10, density 0.2, nnz 10
FACTOR 1 (double) SPARSE, size 10x67, density 0.0746269, nnz 50
FACTOR 2 (double) SPARSE, size 67x33, density 0.151515, nnz 335
FACTOR 3 (double) SPARSE, size 33x31, density 0.16129, nnz 165
FACTOR 4 (double) SPARSE, size 31x56, density 0.0892857, nnz 155
FACTOR 5 (double) SPARSE, size 56x100, density 0.05, nnz 280

◆ is_gpu_mod_enabled()

def pyfaust.is_gpu_mod_enabled ( )

Returns True if the gpu_mod plug-in has been loaded correctly, False otherwise.

See also: pyfaust.is_gpu_mod_working

◆ is_gpu_mod_working()

def pyfaust.is_gpu_mod_working ( )

This function returns True if gpu_mod is working properly False otherwise.

is_gpu_mod_working comes as a complement of pyfaust.is_gpu_mod_enabled The latter ensures that gpu_mod shared library/plugin is properly loaded in memory but doesn't ensure that the GPU is available (for example, the NVIDIA driver might not be installed). The former ensures both that the gpu_mod is loaded and the GPU (device 0) is properly available for computing.

◆ isFaust()

def pyfaust.isFaust ( obj )

Package alias function of Faust.isFaust.

See also: Faust.__init__, Faust.isFaust.,

◆ license()

def pyfaust.license ( )

Prints the FAuST license.

◆ norm()

def pyfaust.norm	(		F,
			ord = `'fro'`,
		**	kwargs
	)

Returns Faust.norm(F, ord) or numpy.linalg.norm(F, ord) depending of F type.

See also: Faust.norm

◆ opt_butterfly_faust()

def pyfaust.opt_butterfly_faust ( F )

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 diagonal matrices 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.

Returns: The optimized Faust.

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

◆ pinv()

def pyfaust.pinv ( F )

A package function alias for the member function Faust.pinv().

◆ rand()

def pyfaust.rand	(	num_rows,
		num_cols,
		num_factors = `None`,
		dim_sizes = `None`,
		density = `None`,
		fac_type = `'sparse'`,
		per_row = `True`,
		dev = `'cpu'`,
		dtype = `'float64'`,
		field = `None`,
		seed = `0`
	)

Generates a random Faust.

Parameters

num_rows	the Faust number of rows.
num_cols	the Faust number of columns.
num_factors	if it's an integer it is the number of random factors to set in the Faust. If num_factors is a list or tuple of 2 integers then the number of factors is set randomly between num_factors[0] and num_factors[1] (inclusively). Defaultly, num_factors is None, it means a 5 factors long Faust is generated.
dim_sizes	if it's an integer all Faust factors are square matrices (except maybe the first and last ones, depending on num_rows and num_cols). The size of the intermediary square factors is size_dims**2. If it's a list or tuple of 2 integers then the number of rows and columns are both a random number between size_dims[0] and size_dims[1] (inclusively). Note that the first factor number of rows and the last factor number of columns are always fixed (they are the dimension sizes of the Faust: num_rows, num_cols arguments). if dim_sizes is None then dim_sizes is defaultly [num_rows, num_cols].
density	the approximate density of factors. The default value is such that each factor gets 5 non-zero elements per row, if per_row is True, or per column otherwise. It should be a floating point number greater than 0 and lower or equal to 1. A density of zero is equivalent to the default case.
fac_type	the storage representation of factors. It must be 'sparse', 'dense' or 'mixed'. The latter designates a mix of dense and sparse matrices in the generated Faust (the choice is made according to a uniform distribution).
dtype	the dtype of the Faust ('float32', 'float64' or 'complex').
per_row	if True the factor matrix is constructed per row applying the density to each row. If False the construction is made with the density applied on each column.
dev	the device on which to create the Faust ('cpu' or 'gpu').
field	(DEPRECATED, use dtype) a str to set the Faust field: 'real' or 'complex'.
seed	set PRNG initialization, useful for reproducibility of this function calls, otherwise seed argument shouldn't be used (the PRNG is automatically initialized).

Returns: the random Faust.

Examples

>>> from pyfaust import rand, seed
>>> seed(42)
>>> F = rand(2, 10, density=.5, dtype='complex')
>>> G = rand(10, 20, num_factors=[2, 5], density=.5, fac_type="dense")
>>> F

Faust size 2x10, density 2.6, nnz_sum 52, 5 factor(s):

FACTOR 0 (complex) SPARSE, size 2x8, density 0.5, nnz 8
FACTOR 1 (complex) SPARSE, size 8x4, density 0.5, nnz 16
FACTOR 2 (complex) SPARSE, size 4x5, density 0.4, nnz 8
FACTOR 3 (complex) SPARSE, size 5x3, density 0.333333, nnz 5
FACTOR 4 (complex) SPARSE, size 3x10, density 0.5, nnz 15

>>> G

Faust size 10x20, density 1.65, nnz_sum 330, 4 factor(s):

FACTOR 0 (double) DENSE, size 10x15, density 0.466667, nnz 70
FACTOR 1 (double) DENSE, size 15x12, density 0.5, nnz 90
FACTOR 2 (double) DENSE, size 12x11, density 0.454545, nnz 60
FACTOR 3 (double) DENSE, size 11x20, density 0.5, nnz 110

See also: Faust.__init__, pyfaust.rand_bsr

◆ rand_bsr()

def pyfaust.rand_bsr	(	num_rows,
		num_cols,
		bnrows,
		bncols,
		num_factors = `None`,
		density = `.1`,
		dev = `'cpu'`,
		dtype = `'float64'`
	)

Generates a random Faust composed only of BSR matrices.

Parameters

num_rows	(int) the Faust number of rows.
num_cols	(int) the Faust number of columns.
bnrows	(int) the nonzero block number of rows (must divide num_rows).
bncols	(int) the nonzero block number of columns (must divide num_cols).
num_factors	(int or tuple(int,int) or NoneType) If it's an integer it will be the number of random factors to set in the Faust. If num_factors is a tuple of 2 integers then the number of factors will be set randomly between num_factors[0] and num_factors[1] (inclusively). If num_factors is None then 5 factors are generated.
density	(float) the Faust factor density (it determines the number of nonzero blocks). It must be between 0 and 1.
dev	(str) the device on which the Faust is created, 'cpu' (default) or 'gpu'.
dtype	(str) the numpy dtype of the Faust.

Examples

>>> from pyfaust import rand_bsr

>>> rand_bsr(100, 100, 20, 10, num_factors=6)

Faust size 100x100, density 0.6, nnz_sum 6000, 6 factor(s):

FACTOR 0 (double) BSR, size 100x100 (blocksize = 20x10), density 0.1, nnz 1000 (nnz blocks: 5)
FACTOR 1 (double) BSR, size 100x100 (blocksize = 20x10), density 0.1, nnz 1000 (nnz blocks: 5)
FACTOR 2 (double) BSR, size 100x100 (blocksize = 20x10), density 0.1, nnz 1000 (nnz blocks: 5)
FACTOR 3 (double) BSR, size 100x100 (blocksize = 20x10), density 0.1, nnz 1000 (nnz blocks: 5)
FACTOR 4 (double) BSR, size 100x100 (blocksize = 20x10), density 0.1, nnz 1000 (nnz blocks: 5)
FACTOR 5 (double) BSR, size 100x100 (blocksize = 20x10), density 0.1, nnz 1000 (nnz blocks: 5)

See also: bsr_matrix, Faust.__init__, pyfaust.rand

◆ rand_butterfly()

def pyfaust.rand_butterfly	(	n,
		dtype = `'float64'`,
		dev = `'cpu'`,
		diag_opt = `False`
	)

Constructs a Faust corresponding to the product of log2(n) square factors of size n with butterfly supports and random nonzero coefficients.

The random coefficients are drawn i.i.d. according to a standard Gaussian (real or complex circular according to the type).

Parameters

n	order of the butterfly (must be a power of two).
diag_opt	if True then the returned Faust is optimized using
pyfaust.opt_butterfly_faust.
dtype	'float32', 'float64' or 'complex', the dtype of the random Faust.
dev	'cpu' or 'gpu', the device where the Faust is created.

Returns: F, a random butterfly support Faust.

See also: pyfaust.fact.butterfly, pyfaust.dft, pyfaust.opt_butterfly_faust

◆ seed()

def pyfaust.seed ( s )

(Re)Initializes the pyfaust pseudo-random generator.

It is useful to reproduce some code based for example on pyfaust.rand or pyfaust.rand_bsr.

Examples

>>> from pyfaust import rand, seed
>>> seed(42) # just for reproducibility
>>> F = rand(1024, 1024, dim_sizes=[1, 1024], num_factors=5, fac_type='mixed')
>>> # F will always be the same
>>> F

Faust size 1024x1024, density 0.017313, nnz_sum 18154, 5 factor(s):

FACTOR 0 (double) SPARSE, size 1024x754, density 0.0066313, nnz 5120
FACTOR 1 (double) SPARSE, size 754x386, density 0.0129534, nnz 3770
FACTOR 2 (double) DENSE, size 386x1000, density 0.004, nnz 1544
FACTOR 3 (double) SPARSE, size 1000x544, density 0.00919118, nnz 5000
FACTOR 4 (double) SPARSE, size 544x1024, density 0.00488281, nnz 2720

◆ toeplitz()

def pyfaust.toeplitz	(	c,
		r = `None`,
		dev = `'cpu'`,
		diag_opt = `False`
	)

Constructs a toeplitz Faust whose first column is c and first row r.

Parameters

c	(np.ndarray) the first column of the toeplitz Faust.
r	(np.ndarray) the first row of the toeplitz Faust. If none then r = np.conjugate(c). r[0] is ignored, the first row is always [c[0], r[1:]].
dev	(str) the device on which the Faust is created, 'cpu' (default) or 'gpu'.
diag_opt	(bool) cf. pyfaust.circ.

Returns: The toeplitz Faust.

Examples

>>> from pyfaust import toeplitz
>>> import numpy as np
>>> c = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> T = toeplitz(c)
>>> T

Faust size 10x10, density 5.52, nnz_sum 552, 10 factor(s):

FACTOR 0 (complex) SPARSE, size 10x32, density 0.0625, nnz 20
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.0625, nnz 64
FACTOR 6 (complex) SPARSE, size 32x32, density 0.0625, nnz 64
FACTOR 7 (complex) SPARSE, size 32x32, density 0.0625, nnz 64
FACTOR 8 (complex) SPARSE, size 32x32, density 0.0625, nnz 64
FACTOR 9 (complex) SPARSE, size 32x10, density 0.0625, nnz 20

>>> np.allclose(T.toarray()[:, 0], c)
True
>>> np.allclose(T.toarray()[0, :], c)
True
>>> np.real(T.toarray())
array([[ 1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.,  9., 10.],
[ 2.,  1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.,  9.],
[ 3.,  2.,  1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.],
[ 4.,  3.,  2.,  1.,  2.,  3.,  4.,  5.,  6.,  7.],
[ 5.,  4.,  3.,  2.,  1.,  2.,  3.,  4.,  5.,  6.],
[ 6.,  5.,  4.,  3.,  2.,  1.,  2.,  3.,  4.,  5.],
[ 7.,  6.,  5.,  4.,  3.,  2.,  1.,  2.,  3.,  4.],
[ 8.,  7.,  6.,  5.,  4.,  3.,  2.,  1.,  2.,  3.],
[ 9.,  8.,  7.,  6.,  5.,  4.,  3.,  2.,  1.,  2.],
[10.,  9.,  8.,  7.,  6.,  5.,  4.,  3.,  2.,  1.]])
>>> r = [11, 12, 13, 14, 15, 16, 17, 18, 19, 20]
>>> T2 = toeplitz(c, r)
>>> T2

Faust size 10x10, density 5.52, nnz_sum 552, 10 factor(s):

FACTOR 0 (complex) SPARSE, size 10x32, density 0.0625, nnz 20
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.0625, nnz 64
FACTOR 6 (complex) SPARSE, size 32x32, density 0.0625, nnz 64
FACTOR 7 (complex) SPARSE, size 32x32, density 0.0625, nnz 64
FACTOR 8 (complex) SPARSE, size 32x32, density 0.0625, nnz 64
FACTOR 9 (complex) SPARSE, size 32x10, density 0.0625, nnz 20

>>> np.allclose(T2.toarray()[0, :], np.hstack((c[0:1], r[1:])))
True
>>> np.allclose(T2.toarray()[:, 0], c)
True
>>> np.real(T2.toarray())
array([[ 1., 12., 13., 14., 15., 16., 17., 18., 19., 20.],
[ 2.,  1., 12., 13., 14., 15., 16., 17., 18., 19.],
[ 3.,  2.,  1., 12., 13., 14., 15., 16., 17., 18.],
[ 4.,  3.,  2.,  1., 12., 13., 14., 15., 16., 17.],
[ 5.,  4.,  3.,  2.,  1., 12., 13., 14., 15., 16.],
[ 6.,  5.,  4.,  3.,  2.,  1., 12., 13., 14., 15.],
[ 7.,  6.,  5.,  4.,  3.,  2.,  1., 12., 13., 14.],
[ 8.,  7.,  6.,  5.,  4.,  3.,  2.,  1., 12., 13.],
[ 9.,  8.,  7.,  6.,  5.,  4.,  3.,  2.,  1., 12.],
[10.,  9.,  8.,  7.,  6.,  5.,  4.,  3.,  2.,  1.]])
>>> # Look at the density of a larger Toeplitz Faust
>>> # it indicates a speedup of the Faust-matrix/vector product
>>> toeplitz(np.random.rand(1024), np.random.rand(1024)).density()
0.08203125

See also: scipy.linalg.toeplitz, pyfaust.circ, pyfaust.anticirc

◆ version()

def pyfaust.version ( )

Returns the FAuST package version.

◆ vstack()

def pyfaust.vstack ( _tuple )

Concatenates vertically Faust-s and/or numpy.ndarray arrays using Faust.concatenate().

See also numpy.vstack

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

Examples

>>> from pyfaust import *
>>> seed(42) # just for reproducibility
>>> F1 = rand(5,50)
>>> F2 = rand(5,50)
>>> vstack((F1, F2))

Faust size 10x50, density 2.17, nnz_sum 1085, 6 factor(s):

FACTOR 0 (double) SPARSE, size 10x67, density 0.0746269, nnz 50
FACTOR 1 (double) SPARSE, size 67x33, density 0.151515, nnz 335
FACTOR 2 (double) SPARSE, size 33x31, density 0.16129, nnz 165
FACTOR 3 (double) SPARSE, size 31x56, density 0.0892857, nnz 155
FACTOR 4 (double) SPARSE, size 56x100, density 0.05, nnz 280
FACTOR 5 (double) SPARSE, size 100x50, density 0.02, nnz 100

◆ wht()

def pyfaust.wht	(	n,
		normed = `True`,
		dev = `"cpu"`,
		dtype = `'float64'`
	)

Constructs a Faust implementing the Walsh-Hadamard Transform (WHT) of order n.

The resulting Faust has log2(n) sparse factors of order n, each one having 2 nonzeros per row and per column.

Parameters

n	(int) order of the WHT (must be a power of two).
normed	(bool) default to True to normalize the Hadamard Faust as if you called Faust.normalize() and False otherwise.
dev	(str) device on which to create the Faust ('cpu' or 'gpu').
dtype	(str) the Faust dtype, it must be 'float32', 'float64' or 'complex'.

Returns: The Faust implementing the Hadamard transform of dimension n.

Examples

>>> from pyfaust import wht

>>> wht(1024)

Faust size 1024x1024, density 0.0195312, nnz_sum 20480, 10 factor(s):

FACTOR 0 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 1 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 2 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 3 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 4 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 5 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 6 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 7 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 8 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 9 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048

>>> wht(1024, normed=True) # is equiv. to next call

Faust size 1024x1024, density 0.0195312, nnz_sum 20480, 10 factor(s):
FACTOR 0 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 1 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 2 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 3 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 4 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 5 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 6 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 7 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 8 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 9 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048

>>> wht(1024, normed=False).normalize() # which is less optimized though

Faust size 1024x1024, density 0.0195312, nnz_sum 20480, 10 factor(s):

FACTOR 0 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 1 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 2 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 3 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 4 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 5 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 6 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 7 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 8 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
FACTOR 9 (double) SPARSE, size 1024x1024, density 0.00195312, nnz 2048

See also: scipy.linalg.hadamard, pyfaust.dft, pyfaust.fact.butterfly,

Namespaces

Classes

Functions

Detailed Description

Function Documentation

◆ anticirc()

◆ bitrev_perm()

◆ circ()

◆ concatenate()

◆ dct()

◆ dft()

◆ dot()

◆ dst()

◆ enable_gpu_mod()

◆ eye()

◆ faust_fact()

◆ faust_logo()

◆ hstack()

◆ is_gpu_mod_enabled()

◆ is_gpu_mod_working()

◆ isFaust()

◆ license()

◆ norm()

◆ opt_butterfly_faust()

◆ pinv()

◆ rand()

◆ rand_bsr()

◆ rand_butterfly()

◆ seed()

◆ toeplitz()

◆ version()

◆ vstack()

◆ wht()