Add a Jupyter Notebook to introduce the different ways to create a pyfaust.Faust.

gen_doc/CMakeLists.txt

@@ -87,7 +87,9 @@ if(BUILD_DOCUMENTATION)
 	file(REMOVE ${PROJECT_BINARY_DIR}/doc/README_install_part.html)
 	configure_file(${FAUST_DOC_SRC_DIR}/bin_pkgs/README_template.md ${PROJECT_BINARY_DIR}/doc/README.md)
 	configure_file(${FAUST_DOC_SRC_DIR}/faq.md ${PROJECT_BINARY_DIR}/doc/faq.md)
-endif(BUILD_DOCUMENTATION) 
+	configure_file(${FAUST_DOC_SRC_DIR}/Faust_creation.ipynb ${PROJECT_BINARY_DIR}/doc/html/Faust_creation.ipynb COPYONLY)
+	configure_file(${FAUST_DOC_SRC_DIR}/Faust_creation.html ${PROJECT_BINARY_DIR}/doc/html/Faust_creation.html COPYONLY)
+endif(BUILD_DOCUMENTATION)
 
 
 

gen_doc/Faust_creation.ipynb

+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# How to Create a Faust\n",
+    "\n",
+    "### 1. Setting the factors manually\n",
+    "\n",
+    "Let's start by creating a Faust manually, that is factor by factor.\n",
+    "\n",
+    "Below is a creation of a Faust containing 5 factors, alternating sparse and dense factors.\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 the scipy.sparse module documentation.\n",
+    "\n",
+    "https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csr_matrix.html\n",
+    "\n",
+    "https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csc_matrix.html"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pyfaust import FaustFactory, Faust\n",
+    "import numpy as np\n",
+    "from scipy import sparse\n",
+    "factors = []\n",
+    "is_sparse = False\n",
+    "for i in range(0,5):\n",
+    "    if(is_sparse):\n",
+    "        factors += [ sparse.random(100,100, dtype=np.float64, format='csr',\n",
+    "                                  density=0.1)]\n",
+    "    else:\n",
+    "        factors += [ np.random.rand(100, 100).astype(np.float64) ]\n",
+    "    is_sparse = not is_sparse\n",
+    "F = Faust(factors)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "F"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "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 all its factors.\n",
+    "You can also call **[F.display()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1Faust.html#a34bdc939e28dd9d1cd102ad715e6fb91)** to get these informations."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "F.display()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 2. Faust File Loading \n",
+    "\n",
+    "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.\n",
+    "\n",
+    "First save the Faust."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "F.save('F.mat')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now let's get it back from file."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "file_F = Faust(filepath='F.mat')\n",
+    "file_F"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The format used is matlab v7. This format allows the compatibility between pyfaust and matfaust, the matlab wrapper. You can easily reload the F.mat file from matfaust."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 3. Generating a random Faust\n",
+    "\n",
+    "The pyfaust package provides a class called FaustFactory responsible for generating Faust objects by many manners.\n",
+    "One noticeable function of this class is [rand()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1FaustFactory.html#a92535c4d3532acdc60847e5f86c63394). This function allows to generate a random Faust defined under certain constraints; the number of factors, the size of these factors, the density, the scalar type, etc.\n",
+    "\n",
+    "Below are an example of random generations."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pyfaust import FaustFactory as FF\n",
+    "F = FF.rand(2, 10, .5, field='complex')\n",
+    "G = FF.rand([2, 5], [10, 20], .5, fac_type=\"dense\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "F is a complex Faust. Its factors are of the both formats (dense or sparse) with a half of nonzeros coefficients (density of .5)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "F"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "G is a real Faust (the default scalar type). The first argument ([2, 5]) in the [rand()](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1FaustFactory.html#a92535c4d3532acdc60847e5f86c63394) call 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."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "G"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 4. Other Ways of Creation\n",
+    "\n",
+    "There exist many ways to create a Faust, please look the [FaustFactory](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/classpyfaust_1_1FaustFactory.html) to get insights of all these methods.\n",
+    "It will be the topic of another notebook!"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.6.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

gen_doc/mainpage_wrappers_inc.md

@@ -4,4 +4,5 @@ This documentation details the [API](annotated.html) of those frontends (a.k.a.
 
 Please refer to this [README](./md_README.html) for a quick guide on how to install and use FAµST wrappers.
 
-
+You might also be interested in this introduction through Jupyter Notebook:
+- [How to Create a Faust with pyfaust](./Faust_creation.html) (Here for [downloading it](./Faust_creation.ipynb))