Udpate 'Faust creation' jupyter notebook.

- pyfaust.rand() prototype changes. - add a footer with the pyfaust version used.

Udpate 'Faust creation' jupyter notebook.
5588d2b6 · hhakim · a312f720 · 5588d2b6 · 5588d2b6
Commit 5588d2b6 authored 4 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
@@ -10,7 +10,7 @@
    "\n",
    "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.\n",
    "\n",
-    "Below is a creation of a Faust containing 5 factors, alternating sparse and dense factors.\n"
+    "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.\n"
   ]
  },
  {
@@ -38,7 +38,7 @@
   "cell_type": "markdown",
   "metadata": {},
   "source": [
-    "Note that sparse factors are in csr format but you can also use csc format (other formats for sparse matrices are not supported).\n",
+    "Note that sparse factors are in CSR format but you can also use CSC format (other formats for sparse matrices are not supported).\n",
    "\n",
    "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)."
   ]
@@ -113,7 +113,7 @@
   "cell_type": "markdown",
   "metadata": {},
   "source": [
-    "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."
+    "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."
   ]
  },
  {
@@ -135,15 +135,15 @@
   "outputs": [],
   "source": [
    "from pyfaust import rand\n",
-    "F = rand(2, 10, density=.5, field='complex')\n",
+    "F = rand(2, 10, num_factors=2, density=.5, field='complex')\n",
-    "G = rand([2, 5], [10, 20], density=.5, fac_type='dense')"
+    "G = rand(10, 20, num_factors=[2, 5], dim_sizes=[10, 20], density=.5, fac_type='dense')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
-    "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 randomly dense or sparse."
+    "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."
   ]
  },
  {
@@ -159,7 +159,7 @@
   "cell_type": "markdown",
   "metadata": {},
   "source": [
-    "G is a real Faust (the default scalar type). The [rand()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/namespacepyfaust.html#a270bdf9e09799e86c95a21f16bc612b8) call first argument (```[2, 5]```) is the bounds in which we want the number of factors to be and likewise the second argument defines the bounds in which to randomly choose the sizes of the two dimensions of each factor composing the Faust. The sizes are chosen to keep G consistent though, this is a matrix product!"
+    "G is a real Faust (the default scalar type). 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! "
   ]
  },
  {
@@ -187,6 +187,23 @@
    "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.\n",
    "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",
+   "metadata": {},
+   "source": [
+    "**Note**: this notebook was executed using the following pyfaust version:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pyfaust\n",
+    "pyfaust.version()"
+   ]
  }
 ],
 "metadata": {

 %% 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 containing 5 factors, alternating sparse and dense factors.
+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).
+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 these informations.
 %% Cell type:code id: tags:
 ``` python
 F.display()
 print(F)
 ```
 %% 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.
+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, density=.5, field='complex')
+F = rand(2, 10, num_factors=2, density=.5, field='complex')
-G = rand([2, 5], [10, 20], density=.5, fac_type='dense')
+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 randomly dense or sparse.
+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). The [rand()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/namespacepyfaust.html#a270bdf9e09799e86c95a21f16bc612b8) call first argument (```[2, 5]```) is the bounds in which we want the number of factors to be and likewise the second argument defines the bounds in which to randomly choose the sizes of the two dimensions of each factor composing the Faust. The sizes are chosen to keep G consistent though, this is a matrix product!
+G is a real Faust (the default scalar type). 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 that 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()
+```