Add a notebook to introduce GPU pyfaust API and integrate it in the doxygen...

Add a notebook to introduce GPU pyfaust API and integrate it in the doxygen doc and notebook zip archive.

gen_doc/CMakeLists.txt

@@ -134,6 +134,8 @@ if(BUILD_DOCUMENTATION)
 	configure_file(${FAUST_DOC_SRC_DIR}/Use_of_Faust_objects_in_algorithms.html ${PROJECT_BINARY_DIR}/doc/html/Use_of_Faust_objects_in_algorithms.html COPYONLY)
 	configure_file(${FAUST_DOC_SRC_DIR}/faust_projectors.ipynb ${PROJECT_BINARY_DIR}/doc/html/faust_projectors.ipynb COPYONLY)
 	configure_file(${FAUST_DOC_SRC_DIR}/faust_projectors.html ${PROJECT_BINARY_DIR}/doc/html/faust_projectors.html COPYONLY)
+	configure_file(${FAUST_DOC_SRC_DIR}/using_gpu_pyfaust.ipynb ${PROJECT_BINARY_DIR}/doc/html/using_gpu_pyfaust.ipynb COPYONLY)
+	configure_file(${FAUST_DOC_SRC_DIR}/using_gpu_pyfaust.html ${PROJECT_BINARY_DIR}/doc/html/using_gpu_pyfaust.html COPYONLY)
 	# matfaust matlab livescripts (mlx and html)
 	configure_file(${FAUST_DOC_SRC_DIR}/Faust_creation.mlx ${PROJECT_BINARY_DIR}/doc/html/Faust_creation.mlx COPYONLY)
 	configure_file(${FAUST_DOC_SRC_DIR}/Faust_creation.mlx.html ${PROJECT_BINARY_DIR}/doc/html/Faust_creation.mlx.html COPYONLY)

gen_doc/mainpage_wrappers_inc.md

@@ -9,6 +9,7 @@ You might also be interested in this introduction to pyfaust through Jupyter Not
 - [How to Manipulate a Faust](./Faust_manipulation.html)
 - [Using the FAµST API in Algorithms](./Use_of_Faust_objects_in_algorithms.html)
 - [Using The FAµST Projectors API](./faust_projectors.html)
+- [Using GPU with pyfaust](./using_gpu_pyfaust.html)
 
 Download all the notebooks (.ipynb) [here](./pyfaust_notebooks.zip).
 

gen_doc/using_gpu_pyfaust.ipynb

+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Using The GPU FAµST API\n",
+    "\n",
+    "In this notebook we'll see quickly how to leverage the GPU computing power with pyfaust.  \n",
+    "Since pyfaust 2.9.0 the API has been modified to make the GPU available directly from the python wrapper.\n",
+    "Indeed, a GPU plug-in (aka ``gpu_mod``) has been developed in that purpose.  \n",
+    "\n",
+    "The first question you might ask is: does it work on my computer? Here is the answer: the loading of this plug-in is quite transparent, if a NVIDIA GPU is available and CUDA properly installed on your system, you have normally nothing to do except installing pyfaust to get the GPU implementations at your fingertips. We'll see in the end of this notebook how to load manually the plug-in and how to get further information in case of error. \n",
+    "\n",
+    "It is worthy to note two drawbacks about the pyfaust GPU support:\n",
+    "- Mac OS X is not supported because NVIDIA has stopped to support this OS.\n",
+    "- On Windows and Linux, the pyfaust GPU support is currently limited to CUDA 9.2 version.\n",
+    "\n",
+    "In addition to these drawbacks, please notice that the GPU pyfaust support is still considered in beta status as the code is relatively young and still evolving. However the API shouldn't move that much in a near future."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Creating a GPU Faust object\n",
+    "\n",
+    "Let's start with some basic Faust creation on the GPU. Almost all the ways of creating a Faust object in CPU memory are also available to create a GPU Faust.  \n",
+    "First of all, creating a Faust using the constructor works seamlessly on GPU, the only need is to specify the ``dev`` keyword argument, as follows:\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pyfaust import Faust\n",
+    "from numpy.random import rand\n",
+    "M, N = rand(10,10), rand(10,15)\n",
+    "gpuF = Faust([M, N], dev='gpu')\n",
+    "gpuF"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "It's clearly indicated in the output that the Faust object is instantiated in GPU memory (the N and M numpy arrays are copied from the CPU to the GPU memory). However it's also possible to check this programmatically:\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gpuF.device"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In ``gpuF`` the factors are dense matrices but it's totally possible to instantiate sparse matrices on the GPU as you can do on CPU side."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pyfaust import Faust\n",
+    "from scipy.sparse import random, csr_matrix\n",
+    "S, T = csr_matrix(random(10, 15, density=0.25)), csr_matrix(random(15, 10, density=0.05))\n",
+    "sparse_gpuF = Faust([S, T], dev='gpu')\n",
+    "sparse_gpuF"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can also create a GPU Faust by explicitly copying a CPU Faust to the GPU memory. Actually, at anytime you can copy a CPU Faust to GPU and conversely. The ``clone()`` member function is here in that purpose. Below we copy ``gpuF`` to CPU and back again to GPU in the new Faust ``gpuF2``."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cpuF = gpuF.clone('cpu')\n",
+    "gpuF2 = cpuF.clone('gpu')\n",
+    "gpuF2"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Generating a GPU Faust\n",
+    "\n",
+    "Many of the functions for generating a Faust object on CPU are available on GPU too. It is always the same, you precise the ``dev`` argument by assigning the ``'gpu'`` value and you'll get a GPU Faust instead of a CPU Faust.\n",
+    "\n",
+    "For example, the code below will successively create a random GPU Faust, a Hadamard transform GPU Faust and finally an identity GPU Faust.\n",
+    "Note that the [dft](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/namespacepyfaust.html#aa29a92f23ffb210ad9bdcdc4c740c2b2) function is not yet available as the complex GPU support is not yet linked into the pyfaust wrapper (even if the C++ core is already complex-compatible)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pyfaust import rand  as frand, eye as feye, wht\n",
+    "print(\"Random GPU Faust:\", frand(10,10, num_factors=11, dev='gpu'))\n",
+    "print(\"Hadamard GPU Faust:\", wht(32, dev='gpu'))\n",
+    "print(\"Identity GPU Faust:\", feye(16, dev='gpu'))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Manipulating GPU Fausts and CPU interoperability\n",
+    "\n",
+    "Once you've created GPU Faust objects, you can perform operations on them staying in GPU world (that is, with no array transfer to CPU memory). That's of course not always possible.\n",
+    "For example, let's consider Faust-scalar multiplication and Faust-matrix product. In the first case the scalar is copied to the GPU memory and likewise in the second case the matrix is copied from CPU to GPU in order to proceed to the computation. However in both cases the Faust factors stay into GPU memory and don't move during the computation."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Faust-scalar multiplication\n",
+    "2*gpuF"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Faust-matrix product (the matrix is copied to GPU then the multiplication is performed on GPU)\n",
+    "gpuF@rand(gpuF.shape[1],15)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "On the contrary, and that matters for optimization, there is no CPU-GPU transfer at all when you create another GPU Faust named for example ``gpuF2`` on the GPU and decide to multiply the two of them like this:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pyfaust import rand as frand\n",
+    "gpuF2 = frand(gpuF.shape[1],18, dev='gpu')\n",
+    "gpuF3 = gpuF@gpuF2\n",
+    "gpuF3"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Besides, it's important to note that ``gpuF3`` factors are not duplicated in memory because they already exist for ``gpuF`` and ``gpuF2``, that's an extra optimization: ``gpuF3`` is just a memory view of ``gpuF`` and ``gpuF2`` factors (the same GPU arrays are shared between ``Faust`` objects). That works pretty well the same for CPU ``Faust`` objects.\n",
+    "\n",
+    "Finally, please notice that CPU Faust objects are not directly interoperable with GPU Fausts objects. You can try, it'll end up on an error."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cpuF = frand(5,5,5, dev='cpu')\n",
+    "gpuF = frand(5,5,6, dev='gpu')\n",
+    "try:\n",
+    "    cpuF@gpuF\n",
+    "except:\n",
+    "    print(\"it doesn't work, you must either convert cpuF to GPU Faust or gpuF to CPU Faust before.\")\n",
+    "cpuF.clone('gpu')@gpuF # this is what you should do"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Benchmarking your GPU with pyfaust!\n",
+    "\n",
+    "Of course when we run some code on GPU rather than on CPU, it is clearly to enhance the performances. So let's try your GPU and find out if it is worth it or not compared to your CPU.\n",
+    "\n",
+    "First, measure how much time it takes on CPU to compute a Faust norm and its product:\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pyfaust import rand as frand\n",
+    "cpuF = frand(1024, 1024, num_factors=10, fac_type='dense')\n",
+    "%timeit cpuF.norm(2)\n",
+    "%timeit cpuF.toarray()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now let's make some GPU heat with norms and matrix products!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gpuF = cpuF.clone(dev='gpu')\n",
+    "%timeit gpuF.norm(2)\n",
+    "%timeit gpuF.toarray()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Running some FAµST algorithms on GPU\n",
+    "\n",
+    "Some of the FAµST algorithms implemented in the C++ core are now also available in pure GPU mode.\n",
+    "For example, let's compare the factorization times taken by the hierarchical factorization when launched on CPU and GPU.\n",
+    "When running on GPU, the matrix to factorize is copied in GPU memory and almost all operations executed during the algorithm don't imply the CPU in any manner (the only exception at this stage of development is the proximal operators that only run on CPU).\n",
+    "\n",
+    "**Warning**: the computation can last thirty minutes or so on CPU."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def factorize_MEG(dev='cpu'):\n",
+    "    from pyfaust.fact import hierarchical\n",
+    "    from scipy.io import loadmat\n",
+    "    from pyfaust.demo import get_data_dirpath\n",
+    "    from time import time\n",
+    "    from numpy.linalg import norm\n",
+    "    d = loadmat(get_data_dirpath()+'/matrix_MEG.mat')\n",
+    "    MEG = d['matrix'].T\n",
+    "    num_facts = 9\n",
+    "    k = 10\n",
+    "    s = 8\n",
+    "    t_start = time()\n",
+    "    MEG16 = hierarchical(MEG, ['rectmat', num_facts, k, s], backend=2020, on_gpu=dev=='gpu', full_gpu=dev=='gpu')\n",
+    "    total_time = time()-t_start\n",
+    "    err = norm(MEG16.toarray()-MEG)/norm(MEG)\n",
+    "    return MEG16, total_time, err"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gpuMEG16, gpu_time, gpu_err = factorize_MEG(dev='gpu')\n",
+    "print(\"GPU time, error:\", gpu_time, gpu_err)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cpuMEG16, cpu_time, cpu_err = factorize_MEG(dev='cpu')\n",
+    "print(\"CPU time, error:\", cpu_time, cpu_err)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Depending on you GPU card and CPU the results may vary, so below are showed some results obtained on specific hardware.\n",
+    "\n",
+    "<table align=\"left\">\n",
+    "    <tr align=\"center\">\n",
+    "        <th>Implementation</th> \n",
+    "        <th> Hardware </th>\n",
+    "        <th> Time </th> \n",
+    "        <th>Error Faust vs MEG matrix </th>\n",
+    "    </tr>\n",
+    "    <tr>\n",
+    "        <td>CPU</td>\n",
+    "        <td>Intel(R) Xeon(R) CPU E5-2620 0 @ 2.00GHz</td>\n",
+    "        <td>2230.77</td>\n",
+    "        <td>.129</td>\n",
+    "    </tr>\n",
+    "    <tr>\n",
+    "        <td>GPU</td>\n",
+    "        <td>NVIDIA GTX980</td>\n",
+    "        <td>465.42</td>\n",
+    "        <td>.129</td>\n",
+    "    </tr>\n",
+    "    <tr>\n",
+    "        <td>GPU</td>\n",
+    "        <td>NVIDIA Tesla V100</td>\n",
+    "        <td>321.50</td>\n",
+    "        <td>.129</td>\n",
+    "    </tr>\n",
+    "    </table>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Manually loading the pyfaust GPU plug-in\n",
+    "\n",
+    "If something goes wrong when trying to use the GPU pyfaust extension, here is how to manually load the plug-in and obtain more information.\n",
+    "\n",
+    "The key is the function [enable_gpu_mod](https://faustgrp.gitlabpages.inria.fr/faust/last-doc/html/namespacepyfaust.html#aea03fff2525fc834f2a56e63fd30a54f). This function allows to give another try to ``gpu_mod`` loading with the verbose mode enabled."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pyfaust\n",
+    "pyfaust.enable_gpu_mod(silent=False, fatal=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Afterward you can call ``pyfaust.is_gpu_mod_enabled()`` to verify it works in your script.\n",
+    "<hr style=\"width:50%;text-align:left;margin-left:0\">"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "**Note**: this notebook was executed using the following pyfaust version:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pyfaust\n",
+    "pyfaust.version()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Thanks for reading this notebook! Many other are available at [faust.inria.fr](https://faust.inria.fr)."
+   ]
+  }
+ ],
+ "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.7.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}