-
3.39.12
|
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... | |
The FAuST Python Wrapper
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()).
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
Faust size 8x8, density 1.5, nnz_sum 96, 6 factor(s):
def pyfaust.bitrev_perm | ( | n | ) |
Bitreversal permutation.
n | (int) the size of the permutation, it must be a power of two. P dimensions will be n x n |
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()).
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
Faust size 8x8, density 1.5, nnz_sum 96, 6 factor(s):
def pyfaust.concatenate | ( | _tuple, | |
* | args, | ||
axis = 0 , |
|||
** | kwargs | ||
) |
A package function alias for the member function Faust.concatenate.
Examples
Faust size 10x50, density 2.17, nnz_sum 1085, 6 factor(s):
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)\)
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'. |
Examples
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.
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. |
Examples
Faust size 1024x1024, density 0.0205078, nnz_sum 21504, 11 factor(s):
Faust size 1024x1024, density 0.0205078, nnz_sum 21504, 11 factor(s):
Faust size 1024x1024, density 0.0205078, nnz_sum 21504, 11 factor(s):
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.
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)\)
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'. |
Examples
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.
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. |
def pyfaust.eye | ( | m, | |
n = None , |
|||
dtype = 'float64' , |
|||
dev = "cpu" |
|||
) |
Faust identity.
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
Faust size 5x5, density 0.2, nnz_sum 5, 1 factor(s):
Faust size 5x4, density 0.2, nnz_sum 4, 1 factor(s):
Faust size 5x5, density 0.2, nnz_sum 5, 1 factor(s):
def pyfaust.faust_fact | ( | * | args, |
** | kwargs | ||
) |
This function is a shorthand for pyfaust.fact.hierarchical.
def pyfaust.faust_logo | ( | ) |
Generates the FAµST logo and returns it as a Faust.
Examples
Faust size 50x50, density 1.3412, nnz_sum 3353, 5 factor(s):
def pyfaust.hstack | ( | _tuple | ) |
Concatenates horizontally Faust-s and/or numpy.ndarray objects using Faust.concatenate().
See also numpy.hstack
Examples
Faust size 5x100, density 1.99, nnz_sum 995, 6 factor(s):
def pyfaust.is_gpu_mod_enabled | ( | ) |
Returns True if the gpu_mod plug-in has been loaded correctly, False otherwise.
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.
def pyfaust.isFaust | ( | obj | ) |
Package alias function of Faust.isFaust.
def pyfaust.license | ( | ) |
Prints the FAuST license.
def pyfaust.norm | ( | F, | |
ord = 'fro' , |
|||
** | kwargs | ||
) |
Returns Faust.norm(F, ord) or numpy.linalg.norm(F, ord) depending of F type.
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.
F | The Faust to optimize. If the factors of F are not set according to a butterfly structure, the result is not defined. |
def pyfaust.pinv | ( | F | ) |
A package function alias for the member function Faust.pinv().
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.
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). |
Examples
Faust size 2x10, density 2.6, nnz_sum 52, 5 factor(s):
Faust size 10x20, density 1.65, nnz_sum 330, 4 factor(s):
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.
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
Faust size 100x100, density 0.6, nnz_sum 6000, 6 factor(s):
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).
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. |
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
Faust size 1024x1024, density 0.017313, nnz_sum 18154, 5 factor(s):
def pyfaust.toeplitz | ( | c, | |
r = None , |
|||
dev = 'cpu' , |
|||
diag_opt = False |
|||
) |
Constructs a toeplitz Faust whose first column is c and first row r.
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. |
Examples
Faust size 10x10, density 5.52, nnz_sum 552, 10 factor(s):
Faust size 10x10, density 5.52, nnz_sum 552, 10 factor(s):
def pyfaust.version | ( | ) |
Returns the FAuST package version.
def pyfaust.vstack | ( | _tuple | ) |
Concatenates vertically Faust-s and/or numpy.ndarray arrays using Faust.concatenate().
See also numpy.vstack
Examples
Faust size 10x50, density 2.17, nnz_sum 1085, 6 factor(s):
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.
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'. |
Examples
Faust size 1024x1024, density 0.0195312, nnz_sum 20480, 10 factor(s):
Faust size 1024x1024, density 0.0195312, nnz_sum 20480, 10 factor(s):