PyCUDA and PyOpenCL backends for ASSET joint prob. matrix calculation (#404)

* accelerated pmat_neighbors function
* cluster_matrix_entries with chunking

Author: dizcza

.travis.yml

@@ -9,11 +9,12 @@ addons:
 
 matrix:
   include:
-    - name: "pip 3.6 requirements-extras"
+    - name: "conda 3.6 extras,opencl"
       python: 3.6
-      env: DISTRIB="pip"
+      env: DISTRIB="conda"
       before_install: sudo apt install -y libopenmpi-dev openmpi-bin
       before_script:
+        - conda install -c conda-forge pyopencl oclgrind clang=9.0.1
         - pip install -r requirements/requirements-extras.txt
         - pip install mpi4py
       script: mpiexec -n 1 python -m mpi4py.futures -m nose --with-coverage --cover-package=elephant
@@ -56,7 +57,7 @@ install:
       sed -i '/mpi4py/d' requirements/environment.yml;
       conda env create -f requirements/environment.yml;
       conda activate elephant;
-      pip list;
+      conda list;
     else
       pip install -r requirements/requirements.txt;
     fi

MANIFEST.in

@@ -8,11 +8,13 @@ include elephant/current_source_density_src/README.md
 include elephant/current_source_density_src/test_data.mat
 include elephant/spade_src/LICENSE
 recursive-include elephant/spade_src *.so *.pyd
+include elephant/asset/*
 include elephant/test/spike_extraction_test_data.txt
 recursive-include doc *
 prune doc/_build
 prune doc/tutorials/.ipynb_checkpoints
 prune doc/reference/toctree
 include doc/reference/toctree/kernels/*
 recursive-exclude * *.h5
+recursive-exclude * *.nix
 recursive-exclude * *~

doc/install.rst

@@ -148,6 +148,66 @@ For more information, refer to `mpi4py
 <https://mpi4py.readthedocs.io/en/stable/mpi4py.run.html>`_ documentation.
 
 
+CUDA and OpenCL support
+-----------------------
+
+:ref:`asset` module supports CUDA and OpenCL. These are experimental features.
+You can have one, both, or none installed in your system.
+
+.. tabs::
+
+    .. tab:: CUDA
+
+        To leverage CUDA acceleration on an NVIDIA GPU card, `CUDA toolkit
+        <https://developer.nvidia.com/cuda-downloads>`_ must installed on
+        your system. Then run the following command in a terminal:
+
+        .. code-block:: sh
+
+            pip install pycuda
+
+        In case you experience issues installing PyCUDA, `this guide
+        <https://medium.com/leadkaro/setting-up-pycuda-on-ubuntu-18-04-for-
+        gpu-programming-with-python-830e03fc4b81>`_ offers a step-by-step
+        installation manual.
+
+        If PyCUDA is detected and installed, CUDA backend is used by default in
+        Elephant ASSET module. To turn off CUDA support, set ``ELEPHANT_USE_CUDA``
+        environment flag to ``0``.
+
+
+    .. tab:: OpenCL
+
+        If you have a laptop with a built-in Intel Graphics Card, you can still
+        leverage significant performance optimization with OpenCL backend.
+        The simplest way to install PyOpenCL is to run a conda command:
+
+        .. code-block:: sh
+
+            conda install -c conda-forge pyopencl intel-compute-runtime
+
+        However, if you have root (sudo) privileges, it's recommended to install
+        up-to-date `Intel Graphics Compute Runtime
+        <https://github.com/intel/compute-runtime/releases>`_ system-wide and then
+        install PyOpenCL as follows:
+
+        .. code-block:: sh
+
+            conda install -c conda-forge pyopencl ocl-icd-system
+
+        Set ``ELEPHANT_USE_OPENCL`` environment flag to ``0`` to turn off
+        PyOpenCL support.
+
+        .. note::
+
+            Make sure you've disabled GPU Hangcheck as described in the
+            `Intel GPU developers documentation <https://software.intel.com/
+            content/www/us/en/develop/documentation/get-started-with-intel-
+            oneapi-base-linux/top/before-you-begin.html>`_. Do it with caution -
+            using your graphics card to perform computations may make the system
+            unresponsive until the compute program terminates.
+
+
 Dependencies
 ------------
 

doc/reference/asset.rst

@@ -1,3 +1,5 @@
+.. _asset:
+
 ===================================================
 Analysis of Sequences of Synchronous EvenTs (ASSET)
 ===================================================

doc/tutorials/asset.ipynb

@@ -35,6 +35,7 @@
    },
    "outputs": [],
    "source": [
+    "import os\n",
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
     "import quantities as pq\n",
@@ -248,7 +249,7 @@
     "\n",
     "The third step is postprocessing of the analytical probability matrix `pmat`, obtained from the previous step. Centered at each (i,j) entry of `pmat` matrix, we apply a diagonal kernel with shape `filter_shape` and select the top `nr_largest` probabilities of (i,j) neighborhood (defined by `filter_shape`), and compute the significance of these `nr_largest` joint neighbor probabilities. The resultant `jmat` matrix is a \"dilated\" version of `imat`.\n",
     "\n",
-    "This step is most time consuming."
+    "This step is most time consuming. If you have PyCUDA or PyOpenCL installed, set `ELEPHANT_USE_CUDA` or `ELEPHANT_USE_OPENCL` environment flag to `1`."
    ]
   },
   {
@@ -270,7 +271,8 @@
     }
    ],
    "source": [
-    "# hint: try different filter_shapes, e.g. filter_shape=(7,3)\n",
+    "os.environ['ELEPHANT_USE_OPENCL'] = '0'\n",
+    "# try different filter_shapes, e.g. filter_shape=(7,3)\n",
     "jmat = asset_obj.joint_probability_matrix(pmat, filter_shape=(11, 3), n_largest=3)"
    ]
   },