<p><strong>Note about Python 2.7</strong>: the operations op+F, op*F, op-F, where op is of type numpy.ndarray or numpy.matrix are not supported in pyfaust for Python 2.7 (contrary to F+op, F-op, F*op that are supported for Python 2.7).</p>
<p><strong>Note about Python 2.7</strong>: the operations op*F where op is of type numpy.ndarray or numpy.matrix are not supported in pyfaust for Python 2.7 (contrary to F*op that is supported for Python 2.7).</p>
<p>The FAµST API proposes a group of normalizations. They correspond to the norms available and discussed above.</p>
<p>It's possible to normalize along columns or rows with any type of these norms.</p>
<p><strong>NOTE for Windows users:</strong> Faust.normalize() is currently buggy in only one case: you're using python3 on Windows and you installed pyfaust with a pip pre-compiled package. Sorry for the inconvenience, the bug is on the to-fix list.</p>
</div>
</div>
...
...
@@ -14572,8 +15039,8 @@ This function is really close to <code>numpy.linalg.norm</code> function.</p>
<p>Sometimes you need to access the dense matrix corresponding to a Faust or an element of it (by the way, note that it's costly).</p>
<p><strong>NOTE for Windows users:</strong> Faust slicing (for more than one item) is currently buggy in only one case: you're using python3 on Windows and you installed pyfaust with a pip pre-compiled package. Sorry for the inconvenience, the bug is on the to-fix list.</p>
<p>Let's access a Faust item:</p>
</div>
...
...
@@ -15046,7 +15512,7 @@ Besides, it's possible to concatenate an arbitrary number of Faust objects.</p>
<p><strong>NOTE for Windows users:</strong> Faust fancy indexing is currently buggy on Windows platforms. Sorry for the inconvenience, the bug is on the to-fix list.</p>
"**Note about Python 2.7**: the operations op+F, op\\*F, op-F, where op is of type numpy.ndarray or numpy.matrix are not supported in pyfaust for Python 2.7 (contrary to F+op, F-op, F\\*op that are supported for Python 2.7)."
"**Note about Python 2.7**: the operations op\\*F where op is of type numpy.ndarray or numpy.matrix are not supported in pyfaust for Python 2.7 (contrary to F\\*op that is supported for Python 2.7)."
]
},
{
...
...
@@ -1389,9 +1389,7 @@
"source": [
"The FAµST API proposes a group of normalizations. They correspond to the norms available and discussed above.\n",
"\n",
"It's possible to normalize along columns or rows with any type of these norms.\n",
"\n",
"**NOTE for Windows users:** Faust.normalize() is currently buggy in only one case: you're using python3 on Windows and you installed pyfaust with a pip pre-compiled package. Sorry for the inconvenience, the bug is on the to-fix list."
"It's possible to normalize along columns or rows with any type of these norms.\n"
]
},
{
...
...
@@ -1578,8 +1576,6 @@
"source": [
"Sometimes you need to access the dense matrix corresponding to a Faust or an element of it (by the way, note that it's costly).\n",
"\n",
"**NOTE for Windows users:** Faust slicing (for more than one item) is currently buggy in only one case: you're using python3 on Windows and you installed pyfaust with a pip pre-compiled package. Sorry for the inconvenience, the bug is on the to-fix list.\n",
"\n",
"Let's access a Faust item:"
]
},
...
...
@@ -1681,9 +1677,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Yes it is!\n",
"\n",
"**NOTE for Windows users:** Faust fancy indexing is currently buggy on Windows platforms. Sorry for the inconvenience, the bug is on the to-fix list."
"Yes it is!\n"
]
},
{
...
...
@@ -1717,7 +1711,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.6.8"
"version": "3.6.5"
}
},
"nbformat": 4,
...
...
%% Cell type:markdown id: tags:
# How to Manipulate a Faust
<aname="start"></a>
This notebook is intended to gently introduce the operations available to manipulate a Faust object.
It comes after the first notebook (available [here](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/Faust_creation.ipynb) for download or [here](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/Faust_creation.html) as a web page), so it's assumed you already know how to create a Faust object from one way or another.
Keep in mind that a full API doc is available [here](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/namespacepyfaust.html) every time you need details. In particular the Faust class is documented [here](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html).
**NOTE**: the notebook is made to be executed sequentially, otherwise, skipping some cells, you would end up on an import error.
# Table of Contents:
[**1. Getting Basic Information about a Faust Object**](#1.-Getting-Basic-Information-about-a-Faust-Object)<br/>
[1.1 Obtaining Dimension and Scalar Type Information](#1.1-Obtaining-Dimension-and-Scalar-Type-Information)<br/>
[1.2 Obtaining Other Faust Specific Information](#1.2-Obtaining-Other-Faust-Specific-Information)<br/>
[1.3 Plotting a Faust](#1.3-Plotting-a-Faust)<br/>
[1.4 About Sparsity!](#1.4-About-Sparsity!)<br/>
[**2. Faust Algebra and other Operations**](#2.-Faust-Algebra-and-other-Operations)<br/>
[2.7 Faust Indexing and Slicing](#2.7-Faust-Indexing-and-Slicing)<br/>
# 1. Getting Basic Information about a Faust Object
First of all, given any object, you might ask yourself if it's a Faust or not (typically when you receive an object in a function, python being built on dynamic types, you can't say for sure it's a Faust).
[Faust.isFaust()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html#a965047e6c0161e59a1c3e08f2b60e806) is the function to verify an object is a Faust.
It's use is straighforward as you can see in the [documentation](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html#a965047e6c0161e59a1c3e08f2b60e806).
### 1.1 Obtaining Dimension and Scalar Type Information
Firstly, let's list basic Faust informative methods/attributes you're probably used to for numpy arrays:
To keep it really clear, let's show some examples operated on a random Faust.
%% Cell type:code id: tags:
``` python
frompyfaustimportFaustFactoryasFF
F=FF.rand(5,10)
print(F)
```
%% Cell type:code id: tags:
``` python
F.shape
```
%% Cell type:code id: tags:
``` python
F.size
```
%% Cell type:code id: tags:
``` python
F.dtype
```
%% Cell type:markdown id: tags:
If the attributes printed out above seem not clear to you, you're probably not a numpy user. Anyway you'll find all descriptive informations in the FAµST API documentation (see the links [above](#start)).
As a complement, you can also refer to the numpy API documentation:
About shape, it's noteworthy that contrary to what numpy is capable of, you _cannot_ [reshape](https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.reshape.html) a Faust.
%% Cell type:markdown id: tags:
### 1.2 Obtaining Other Faust Specific Information
As you've seen in this notebook and the [first one](#start), when you print a Faust object, several pieces of information appear.
Most of them are also available independently with specific functions.
For instance, if you want information about factors, nothing is more simple than calling directly the next functions:
-[get_num_factors()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html#a2b46d3c068ef20d74bb90e382848014e) ; which gives you the number of factors (aka layers) a Faust object is composed of.
-[get_factor()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html#adc91fd04c17ccaa2f32b7423955ef37d) ; which allows you to copy any of the Faust's factors givens its index.
Going back to our F object, let's call these functions:
%% Cell type:code id: tags:
``` python
F.get_num_factors()
```
%% Cell type:markdown id: tags:
For example, try to copy the third factor:
%% Cell type:code id: tags:
``` python
f3=F.get_factor(2)
f3
```
%% Cell type:markdown id: tags:
Note that, since Faust 2.3, the function doesn't alterate the factor format. If the Faust object contains a sparse factor then you'll receive a sparse (CSR) matrix.
%% Cell type:markdown id: tags:
Contrary to what the singular form of 'get_factor' indicates, it's possible (since Faust 2.3 again) to retrieve a sub-sequence of Faust factors.
Go straight to the example, extracting factors from F:
%% Cell type:code id: tags:
``` python
F.get_factor(range(2,4))
```
%% Cell type:markdown id: tags:
Hmm... something is different from the previous example. We indeed received a Faust as return type, great! You've just learned another way to create a Faust from another, additionally to what you've seen in the first [notebook](#start).
Without this function, you'd surely have written something similar to:
%% Cell type:code id: tags:
``` python
frompyfaustimportFaust
F2=Faust([F.get_factor(2),F.get_factor(3)])
F2
```
%% Cell type:markdown id: tags:
OK, that's not awful but I let you imagine how much complicated it is with more factors (even with a list comprehension, it's longer to write).
### 1.3 Plotting a Faust
It's quite useful to print a Faust as we've seen before, calling ``print(F)`` or ``F.display()`` or just ``F`` in an interactive terminal but this is wordy.
How about plotting a Faust in a more graphical fashion ?
%% Cell type:code id: tags:
``` python
importmatplotlib.pyplotasplt
%matplotlibinline
F.imshow()
plt.show()
```
%% Cell type:markdown id: tags:
What do we see above ? On the bottom left is the dense matrix associated to F, obtained with ```F.toarray()```. On the top are the indexed factors of F.
Note that you can change the default [colormap](https://matplotlib.org/tutorials/colors/colormaps.html) in matplotlib parameters.
Another example is worth a thousand words.
%% Cell type:code id: tags:
``` python
frompyfaustimportFaust
fromnumpyimporteye
Faust([eye(5,4),eye(4,10)]).imshow()
```
%% Cell type:markdown id: tags:
The dimension ratio of the factors is respected in the figure.
### 1.4 About Sparsity!
Three functions of the Faust class are here to evaluate the sparsity of a Faust object.
Let's call the first one:
%% Cell type:code id: tags:
``` python
F.nnz_sum()
```
%% Cell type:markdown id: tags:
I'm sure you guessed exactly what the function returns, if you doubt it, here is the doc: [Faust.nnz_sum()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html#a216c598bb384d92b4e37843b67c42255). The smaller ```nnz_sum```, the sparser the Faust.
Next comes the function: [Faust.density()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html#af73ecb7c5fca3c7673c665d8ba4058f6).
This function along with its reciprocal [Faust.rcg()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html#a6a51a05c20041504a0b8f2a73dd8d05a) can give you a big hint on how much your Faust is potentially optimized both for storage and calculation. The sparser the Faust, the larger the Relative Complexity Gain (RCG)!
%% Cell type:code id: tags:
``` python
F.density()
```
%% Cell type:code id: tags:
``` python
F.rcg()
```
%% Cell type:markdown id: tags:
According to its RCG, this Faust doesn't seem to be of any help for optimization but look at the graphic the next script generates:
Isn't it obvious now that the smaller the density the better?! Indeed, for two Faust objects of the same shape and the same number of factors, a smaller density (linearly) implies a smaller file size for storage.
This point applies also to the memory (RAM) space to work on a Faust.
We'll see later how the computation can benefit of a bigger RCG (or smaller density). But let's point out right now that the sparsity is often a tradeoff with accuracy, as the following plot shows about the truncated [SVD](https://docs.scipy.org/doc/numpy/reference/generated/numpy.linalg.svd.html) of a matrix $M \in {\mathbb R}^{512 \times 512}$. Note beforehand that the SVD of M (truncated or not) can be seen as a Faust which approximates M.
Here is the script to reproduce the last figure: [test_svd_rc_vs_err.py](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/test_svd_rc_vs_err.py)
%% Cell type:markdown id: tags:
# 2. Faust Algebra and other Operations
%% Cell type:markdown id: tags:
In order to write some nice algorithms using Faust objects, you'll have to use the basic "stable" operations a Faust is capable of. Let's make a tour of them.
You are probably familiar with [T](https://docs.scipy.org/doc/numpy/reference/generated/numpy.matrix.T.html) and [H](https://docs.scipy.org/doc/numpy/reference/generated/numpy.matrix.H.html) attributes/properties from numpy/scipy. Well, they are also used in the Faust class.
%% Cell type:code id: tags:
``` python
G=FF.rand(5,[10,15],field='complex')
```
%% Cell type:code id: tags:
``` python
G.T
```
%% Cell type:code id: tags:
``` python
G.conj()
```
%% Cell type:code id: tags:
``` python
G.H
```
%% Cell type:markdown id: tags:
What really matters here is that the results of G.T, G.conj() and G.H are all Faust objects. Behind the scene, there is just one memory zone allocated to the factors. Strictly speaking they are memory views shared between G, G.T and G.H. So don't hesitate to use!
%% Cell type:markdown id: tags:
### 2.2 Add, Subtract and Multiply
%% Cell type:code id: tags:
``` python
F=FF.rand(5,G.shape[0])
G=FF.rand(5,G.shape[0])
F+G
```
%% Cell type:markdown id: tags:
Go ahead and verify it's accurate.
%% Cell type:code id: tags:
``` python
fromnumpy.linalgimportnorm
norm((F+G).toarray()-(F.toarray()+G.toarray()))
```
%% Cell type:markdown id: tags:
Some points are noticeable here:
- F is real (dtype float), but G is complex. The Faust API is able to return the proper type for the resulting Faust, that is a complex Faust.
- F+G is composed of 8 factors, however F and G are both 5 factors long. It's due to the way the addition is implemented (Faust concatenation is hiding behind).
Subtracting is not different:
%% Cell type:code id: tags:
``` python
F-G
```
%% Cell type:markdown id: tags:
You can also add/subtract scalars to Faust objects.
%% Cell type:code id: tags:
``` python
F+2
```
%% Cell type:markdown id: tags:
Note that here again ```(F+2).get_num_factors() != F.get_num_factors()```
But conversely you can also add/subtract a Faust to a scalar (pay attention to the order of operands):
%% Cell type:code id: tags:
``` python
2+F
```
%% Cell type:code id: tags:
``` python
2-F
```
%% Cell type:markdown id: tags:
The FAµST API support equally the Faust to array addition and subtraction.
Faust scalar multiplication is also available and here again the result is a Faust object!
%% Cell type:code id: tags:
``` python
F*2# or 2*F
```
%% Cell type:markdown id: tags:
**Note about Python 2.7**: the operations op+F, op\*F, op-F, where op is of type numpy.ndarray or numpy.matrix are not supported in pyfaust for Python 2.7 (contrary to F+op, F-op, F\*op that are supported for Python 2.7).
**Note about Python 2.7**: the operations op\*F where op is of type numpy.ndarray or numpy.matrix are not supported in pyfaust for Python 2.7 (contrary to F\*op that is supported for Python 2.7).
%% Cell type:markdown id: tags:
### 2.3 Faust Multiplication by a Vector or a Matrix
When you multiply a Faust by a vector or a matrix (which must be dense by the way -- more precisely, a ```numpy.ndarray``` with good ```ndim``` and ```shape```), you'll get respectively a vector or a matrix as result.
%% Cell type:code id: tags:
``` python
fromnumpy.randomimportrand
vec=rand(F.shape[1],1)
F*vec# or F.dot(vec), F*vec, (or only with python3) F@vec
```
%% Cell type:markdown id: tags:
Let's launch a timer to compare the execution times of Faust-vector multiplication and Faust's dense matrix-vector multiplication
Note that appliying a Faust on a ```numpy.ndarray``` or a ```numpy.matrix``` can be done with the function dot(), the operator @ (python3 only) or \* exactly as ```numpy.matrix``` allows. Indeed, a Faust is to be seen as a ```numpy.matrix``` not a ```numpy.ndarray``` (for the latter the two operators are not the same, \* performs an elementwise multiplication while @ or dot() is the matrix product).
%% Cell type:code id: tags:
``` python
timeitF*vec
```
%% Cell type:code id: tags:
``` python
FD=F.todense()# be careful: todense() returns a matrix while toarray() a ndarray
```
%% Cell type:code id: tags:
``` python
timeitFD*vec
```
%% Cell type:code id: tags:
``` python
fromnumpyimportallclose
allclose(F*vec,FD*vec)
```
%% Cell type:code id: tags:
``` python
F.rcg()
```
%% Cell type:markdown id: tags:
When the RCG is lower than 1 the Faust-vector multiplication is slower. Making a random Faust with a large RCG (small density) shows better results.
%% Cell type:code id: tags:
``` python
G=FF.rand(3,1024,density=.001,fac_type='sparse')
GD=G.todense()
vec2=rand(1024,1)
```
%% Cell type:code id: tags:
``` python
timeitG*vec2
```
%% Cell type:code id: tags:
``` python
timeitGD*vec2
```
%% Cell type:code id: tags:
``` python
G.rcg()
```
%% Cell type:markdown id: tags:
It goes without saying that a big RCG gives a big speedup to the Faust-vector multiplication relatively to the corresponding (dense) matrix-vector multiplication.
I hope the example above has finished to convince you.
Just to convince you as well of the Faust-vector multiplication accuracy:
%% Cell type:code id: tags:
``` python
fromnumpy.linalgimportnorm
norm(G*vec2-GD*vec2)
```
%% Cell type:markdown id: tags:
What applies to Faust-vector multiplication remains valid about Faust-matrix multiplication. Take a look:
%% Cell type:code id: tags:
``` python
M=rand(1024,32)
```
%% Cell type:code id: tags:
``` python
timeitG*M
```
%% Cell type:code id: tags:
``` python
timeitGD*M
```
%% Cell type:code id: tags:
``` python
norm(GD*M-G*M)/norm(GD*M)
```
%% Cell type:markdown id: tags:
Well, what do we see? A quicker Faust-matrix multiplication than the matrix-matrix corresponding multiplication, though a good accuracy of the Faust-matrix multiplication is also clearly confirmed.
These examples are somehow theoretical because we cherry-pick the Faust to ensure that the RCG is good to accelerate the muplication, but at least it shows the potential speedup using Faust objects.
%% Cell type:markdown id: tags:
### 2.4 Faust Norms
The Faust class provides a norm function which handles different types of norms.
This function is really close to ```numpy.linalg.norm``` function.
In the following example, three of four norms available are computed.
%% Cell type:code id: tags:
``` python
F.norm(1)
```
%% Cell type:code id: tags:
``` python
F.norm(np.inf)
```
%% Cell type:code id: tags:
``` python
F.norm('fro')
```
%% Cell type:markdown id: tags:
Now, check the values are not far from the Faust's dense matrix.
%% Cell type:code id: tags:
``` python
fromnumpy.linalgimportnorm
norm(F.todense(),1)
```
%% Cell type:code id: tags:
``` python
norm(F.todense(),np.inf)
```
%% Cell type:code id: tags:
``` python
norm(F.todense(),'fro')
```
%% Cell type:markdown id: tags:
Perfect! But a last norm is available, this is the Faust's 2-norm. Let's see in the next small benchmark how the Faust 2-norm is being computed faster than the Faust's dense matrix 2-norm.
%% Cell type:code id: tags:
``` python
timeit-n10G.norm(2)
```
%% Cell type:code id: tags:
``` python
timeit-n10norm(GD,2)# sorry, it could be slow
```
%% Cell type:markdown id: tags:
The power-iteration algorithm implemented in the FAµST C++ core is faster on G and the relative error is not bad too. The norm computation is faster as it benefits from faster Faust-vector multiplication
%% Cell type:code id: tags:
``` python
err=abs((G.norm(2)-norm(GD,2))/norm(GD,2))
err
```
%% Cell type:markdown id: tags:
### 2.5 Faust Normalizations
%% Cell type:markdown id: tags:
The FAµST API proposes a group of normalizations. They correspond to the norms available and discussed above.
It's possible to normalize along columns or rows with any type of these norms.
**NOTE for Windows users:** Faust.normalize() is currently buggy in only one case: you're using python3 on Windows and you installed pyfaust with a pip pre-compiled package. Sorry for the inconvenience, the bug is on the to-fix list.
%% Cell type:code id: tags:
``` python
F=FF.rand(5,10)
NF=F.normalize()
```
%% Cell type:markdown id: tags:
The API doc is [here](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html#ae93af25bb48c768fd0d08e71631e9dac).
%% Cell type:markdown id: tags:
What's interesting here is the fact that ```Faust.normalize``` returns a Faust object. Combined with slicing (that you will see soon), ```normalize``` is useful to write algorithms such as Orthonormal Matching Pursuit (OMP), which require matrices with L2-normalized columns, in a way that makes them able to leverage the acceleration offered by the FAµST API.
The normalization coded in C++ is memory optimized (it never builds the dense matrix ```F.toarray()``` to compute the norms of the columns/rows). In the same goal the factors composing the Faust object NF are not duplicated in memory from same factors F, they're used as is with an additional factor giving the appropriate scaling.
The difference of the two concatenations is full of zeros, so of course it works!
As you noticed the Faust concatenation is stable, you give two Fausts and you get a Faust again.
Besides, it's possible to concatenate an arbitrary number of Faust objects.
%% Cell type:code id: tags:
``` python
F.concatenate(F,C,C,F,axis=1)
```
%% Cell type:markdown id: tags:
As an exercise, you can write the factors of the Faust ```F.concatenate(F)```, F being any Faust.
**Hint**: the block-diagonal matrices are around here.
%% Cell type:markdown id: tags:
### 2.7 Faust Indexing and Slicing
%% Cell type:markdown id: tags:
Sometimes you need to access the dense matrix corresponding to a Faust or an element of it (by the way, note that it's costly).
**NOTE for Windows users:** Faust slicing (for more than one item) is currently buggy in only one case: you're using python3 on Windows and you installed pyfaust with a pip pre-compiled package. Sorry for the inconvenience, the bug is on the to-fix list.
Let's access a Faust item:
%% Cell type:code id: tags:
``` python
F[2,3]
```
%% Cell type:markdown id: tags:
Why is it costly? Because it essentially converts the Faust to its dense form (modulo some optimizations) to just access one item.
%% Cell type:code id: tags:
``` python
timeitF[2,3]
```
%% Cell type:code id: tags:
``` python
timeitFD[2,3]
```
%% Cell type:markdown id: tags:
It's totally the same syntax as numpy but much slower so use it with care.
The more advanced slicing operation uses also the same syntax as numpy:
%% Cell type:code id: tags:
``` python
F[2:5,3:10]
```
%% Cell type:markdown id: tags:
Here again, the result is another Faust. But this is not a full copy, it makes profit of memory views implemented behind in C++. Solely the first and last factors of the sliced Faust are new in memory, the other are just referenced from the initial Faust F. So use it with no worry for a Faust with a lot of factors!
%% Cell type:markdown id: tags:
The numpy's fancy indexing has also been implemented in the FAµST C++ core, let's try it:
%% Cell type:code id: tags:
``` python
FI=F[[1,3,2],:]
Faust.isFaust(FI)
```
%% Cell type:markdown id: tags:
Again, it's a Faust but is it really working? Verify!
%% Cell type:code id: tags:
``` python
(FI.todense()[0]==F.todense()[1]).all()and \
(FI.todense()[1]==F.todense()[3]).all()and \
(FI.todense()[2]==F.todense()[2]).all()
```
%% Cell type:markdown id: tags:
Yes it is!
**NOTE for Windows users:** Faust fancy indexing is currently buggy on Windows platforms. Sorry for the inconvenience, the bug is on the to-fix list.
%% Cell type:markdown id: tags:
-----
%% Cell type:markdown id: tags:
This is the notebook's end, you have now a global view of what the Faust class is able and what kind of high-level algorithms it is ready for. You might be interested to read other notebooks, just go back to the [page](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/index.html) where you got this one.
