Add a note about Faust deletion in jupyter notebook.

Issue #258.

Add a note about Faust deletion in jupyter notebook.
134238c1 · hhakim · 5b89c89c · 134238c1 · 134238c1
Commit 134238c1 authored 2 years ago by hhakim
--- a/gen_doc/Faust_creation.html
+++ b/gen_doc/Faust_creation.html
--- a/gen_doc/Faust_creation.ipynb
+++ b/gen_doc/Faust_creation.ipynb
@@ -72,6 +72,13 @@
    "print(F)"
   ]
  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that when you don't need ``F`` anymore, you can delete it with the instruction ``del F``. Normally, that's the role of the garbage collector but it might happen that your Faust is very eager in memory and a manual deletion with a manual garbage collection is necessary (calling ``gc.collect()`` after one or several ``del``)."
+   ]
+  },
  {
   "cell_type": "markdown",
   "metadata": {},
@@ -135,7 +142,7 @@
   "outputs": [],
   "source": [
    "from pyfaust import rand\n",
-    "F = rand(2, 10, num_factors=2, density=.5, field='complex')\n",
+    "F = rand(2, 10, num_factors=2, density=.5, dtype='complex')\n",
    "G = rand(10, 20, num_factors=[2, 5], dim_sizes=[10, 20], density=.5, fac_type='dense')"
   ]
  },
@@ -208,7 +215,7 @@
 ],
 "metadata": {
  "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
@@ -222,7 +229,7 @@
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
-   "version": "3.7.10"
+   "version": "3.11.1"
  }
 },
 "nbformat": 4,

 %% Cell type:markdown id: tags:

 # How to Create a Faust

 ### 1. Setting the Factors Manually

 Let's start by creating a [Faust](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html) manually, that is factor by factor.

 Below is a creation of a [Faust](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html) containing 5 factors, alternating sparse and dense factors.

 %% Cell type:code id: tags:

 ``` python
 from pyfaust import Faust
 import numpy as np
 from scipy import sparse
 factors = []
 is_sparse = False
 for i in range(0,5):
    if(is_sparse):
        factors += [ sparse.random(100,100, dtype=np.float64, format='csr',
                                  density=0.1)]
    else:
        factors += [ np.random.rand(100, 100).astype(np.float64) ]
    is_sparse = not is_sparse
 F = Faust(factors)
 ```

 %% Cell type:markdown id: tags:

 Note that sparse factors are in CSR format but you can also use CSC format (other formats for sparse matrices are not supported).

 It can be interesting to look at the [scipy.sparse](https://docs.scipy.org/doc/scipy/reference/sparse.html) module documentation, in particular: [csr_matrix](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csr_matrix.html), [csc_matrix](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csc_matrix.html).

 %% Cell type:code id: tags:

 ``` python
 F
 ```

 %% Cell type:markdown id: tags:

 As you noticed, the Faust output contains the list of factors and their features but also a header describing the Faust operator itself: its size, its density, the number of nonzeros it contains (```nnz_sum```) along with all its factors.
 You can also call **[F.display()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html#a34bdc939e28dd9d1cd102ad715e6fb91)** or simply ```print(F)``` to get all the information.

 %% Cell type:code id: tags:

 ``` python
 F.display()
 print(F)
 ```

 %% Cell type:markdown id: tags:

+Note that when you don't need ``F`` anymore, you can delete it with the instruction ``del F``. Normally, that's the role of the garbage collector but it might happen that your Faust is very eager in memory and a manual deletion with a manual garbage collection is necessary (calling ``gc.collect()`` after one or several ``del``).
+
+%% Cell type:markdown id: tags:
+
 ### 2. Faust File Loading

 It's really handy to create a Faust and retrieve it from a file later. Let's see in the code below how to proceed.

 First save the Faust.

 %% Cell type:code id: tags:

 ``` python
 F.save('F.mat')
 ```

 %% Cell type:markdown id: tags:

 Now let's get it back from file.

 %% Cell type:code id: tags:

 ``` python
 file_F = Faust(filepath='F.mat')
 file_F
 ```

 %% Cell type:markdown id: tags:

 The file storage format used is matlab v7. This format allows the compatibility between pyfaust and [matfaust](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/namespacematfaust.html), the Matlab wrapper. You can easily reload the ``F.mat`` file from matfaust.

 %% Cell type:markdown id: tags:

 ### 3. Generating a Random Faust

 The pyfaust package provides functions for generating Faust objects by many manners.
 One noticeable function of this package is [rand()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/namespacepyfaust.html#a270bdf9e09799e86c95a21f16bc612b8). This function allows to generate a random Faust satisfying certain constraints; the number of factors, the size of these factors, the density, the scalar type, etc.

 Below are examples of (pseudo-)random generations.

 %% Cell type:code id: tags:

 ``` python
 from pyfaust import rand
-F = rand(2, 10, num_factors=2, density=.5, field='complex')
+F = rand(2, 10, num_factors=2, density=.5, dtype='complex')
 G = rand(10, 20, num_factors=[2, 5], dim_sizes=[10, 20], density=.5, fac_type='dense')
 ```

 %% Cell type:markdown id: tags:

 F is a complex Faust. Its rate of nonzeros, for *each factor*, is about 0.5. Since the ``fac_type`` argument is not set, each factor is sparse.

 %% Cell type:code id: tags:

 ``` python
 F
 ```

 %% Cell type:markdown id: tags:

 G is a real Faust (the default scalar type is double). The [rand()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/namespacepyfaust.html#a270bdf9e09799e86c95a21f16bc612b8) call ``num_factors`` value  (``[2, 5]``) defines the bounds in which we want the number of factors to be and likewise the ``dim_sizes`` argument defines the bounds in which to randomly choose the sizes of the two dimensions of each intermediary factor composing the Faust. The sizes are chosen to keep G consistent though, this is a matrix product!

 %% Cell type:code id: tags:

 ``` python
 G
 ```

 %% Cell type:markdown id: tags:

 The [rand()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/namespacepyfaust.html#a270bdf9e09799e86c95a21f16bc612b8) function will surely be of a great help if you want to test the [Faust](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html) member functions. A second notebook might guide you in this road: [How to Manipulate a Faust](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/Faust_manipulation.html).

 %% Cell type:markdown id: tags:

 ### 4. Other Ways of Creation

 There exist many ways to create a Faust, please look at the package [documentation](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/namespacepyfaust.html) for more information.
 It would be the topic of another notebook! If you want, for example, to learn about Faust generation based on the FAµST's factorization algorithms, check this notebook: [Using the FAµST Factorization Wrappers](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/Faust_factorization.html).

 %% Cell type:markdown id: tags:

 **Note**: this notebook was executed using the following pyfaust version:

 %% Cell type:code id: tags:

 ``` python
 import pyfaust
 pyfaust.version()
 ```