Metadata-Version: 2.1
Name: nengo-ocl
Version: 2.1.0
Summary: OpenCL-based simulator for Nengo neural models
Home-page: https://labs.nengo.ai/nengo-ocl/
Author: Applied Brain Research
Author-email: info@appliedbrainresearch.com
License: Free for non-commercial use
Description: ****************************
        OpenCL-based Nengo Simulator
        ****************************
        
        NengoOCL is an OpenCL-based simulator for
        brain models built using `Nengo <https://github.com/nengo/nengo>`_.
        It can be orders of magnitude faster than the reference simulator
        in ``nengo`` for large models.
        
        Usage
        =====
        
        To use the ``nengo_ocl`` project's OpenCL simulator,
        build a Nengo model as usual,
        but use ``nengo_ocl.Simulator`` when creating a simulator for your model::
        
            import numpy as np
            import matplotlib.pyplot as plt
            import nengo
            import nengo_ocl
        
            # define the model
            with nengo.Network() as model:
                stim = nengo.Node(np.sin)
                a = nengo.Ensemble(100, 1)
                b = nengo.Ensemble(100, 1)
                nengo.Connection(stim, a)
                nengo.Connection(a, b, function=lambda x: x**2)
        
                probe_a = nengo.Probe(a, synapse=0.01)
                probe_b = nengo.Probe(b, synapse=0.01)
        
            # build and run the model
            with nengo_ocl.Simulator(model) as sim:
                sim.run(10)
        
            # plot the results
            plt.plot(sim.trange(), sim.data[probe_a])
            plt.plot(sim.trange(), sim.data[probe_b])
            plt.show()
        
        If you are running within ``nengo_gui`` make sure the ``PYOPENCL_CTX``
        environment variable has been set. If this variable is not set it will open
        an interactive prompt which will cause ``nengo_gui`` to get stuck during build.
        
        Dependencies and Installation
        =============================
        
        The requirements are the same as Nengo, with the additional Python packages
        ``mako`` and ``pyopencl`` (where the latter requires installing OpenCL).
        
        General:
        
        * Python 2.7+ or Python 3.3+ (same as Nengo)
        * One or more OpenCL implementations (test with e.g. PyOpenCl)
        
        A working installation of OpenCL is the most difficult
        part of installing NengoOCL. See below for more details
        on how to install OpenCL.
        
        Python packages:
        
        * NumPy
        * nengo
        * mako
        * PyOpenCL
        
        In the ideal case, all of the Python dependencies
        will be automatically installed when installing ``nengo_ocl`` with
        
        .. code-block:: bash
        
           pip install nengo-ocl
        
        If that doesn't work, then do a developer install
        to figure out what's going wrong.
        
        Developer Installation
        ----------------------
        
        First, ``pip install nengo``.
        For best performance, first make sure a fast version of Numpy is installed
        by following the instructions in the
        `Nengo README <http://github.com/nengo/nengo/blob/master/README.rst>`_.
        
        This repository can then be installed with:
        
        .. code-block:: bash
        
           git clone https://github.com/nengo/nengo-ocl.git
           cd nengo-ocl
           python setup.py develop --user
        
        If you’re using a ``virtualenv`` (recommended!)
        then you can omit the ``--user`` flag.
        Check the output to make sure everything installed correctly.
        Some dependencies (e.g. ``pyopencl``) may require manual installation.
        
        Installing OpenCL
        =================
        
        How you install OpenCL is dependent on your hardware and operating system.
        A good resource for various cases is found in the PyOpenCL documentation:
        
        * `Installing PyOpenCL on Windows <http://wiki.tiker.net/PyOpenCL/Installation/Windows>`_
        * `Installing PyOpenCL on Mac OS X <http://wiki.tiker.net/PyOpenCL/Installation/Mac>`_
        * `Installing PyOpenCL on Linux <http://wiki.tiker.net/PyOpenCL/Installation/Linux>`_,
          and a `more detailed guide <http://wiki.tiker.net/OpenCLHowTo>`_
        
        Below are instructions that have worked for the
        NengoOCL developers at one point in time.
        
        AMD OpenCL on Debian Unstable
        -----------------------------
        
        On Debian unstable (sid) there are packages in non-free and contrib
        to install AMD's OpenCL implementation easily.
        Actually, the easiest thing would be to apt-get install
        `python-pyopencl <http://packages.debian.org/sid/python-pyopencl>`_.
        But if you're using a virtual environment, you can
        ``sudo apt-get install opencl-headers libboost-python-dev amd-opencl-icd amd-libopencl1``
        and then ``pip install pyopencl``.
        
        Nvidia OpenCL on Debian/Ubuntu Linux
        ------------------------------------
        
        On Debian unstable (sid) there are packages
        for installing the Nvidia OpenCL implementation as well.
        
        .. code-block:: bash
        
           sudo apt-get install nvidia-opencl-common nvidia-libopencl1
        
        Ensure that the Nvidia driver version matches the OpenCL library version.
        You can check the Nvidia driver version by running ``nvidia-smi`` in the
        command line. You can find the OpenCL library version by looking at the
        libnvidia-opencl.so.XXX.XX file in the ``/usr/lib/x86_64-linux-gnu/`` folder.
        
        Intel OpenCL on Debian/Ubuntu Linux
        -----------------------------------
        
        The Intel SDK for OpenCL is no longer available. Intel OpenCL drivers
        can be found `on Intel's website <https://software.intel.com/en-us/articles/opencl-drivers>`_.
        See `the PyOpenCL wiki <http://wiki.tiker.net/OpenCLHowTo#Installing_the_Intel_CPU_ICD>`_
        for instructions.
        
        Running Tests
        =============
        
        From the ``nengo-ocl`` source directory, run:
        
        .. code-block:: bash
        
            py.test nengo_ocl/tests --pyargs nengo -v
        
        This will run the tests using the default context. If you wish to use another
        context, configure it with the ``PYOPENCL_CTX`` environment variable
        (run the Python command ``pyopencl.create_some_context()`` for more info).
        
        ***************
        Release History
        ***************
        
        .. Changelog entries should follow this format:
        
           version (release date)
           ======================
        
           **section**
        
           - One-line description of change (link to Github issue/PR)
        
        .. Changes should be organized in one of several sections:
        
           - Added
           - Changed
           - Deprecated
           - Removed
           - Fixed
        
        2.1.0 (Nov 23, 2020)
        ====================
        
        *Compatible with Nengo 3.1.0*
        
        **Added**
        
        - Added ``remove_zero_incs`` and ``remove_unmodified_resets`` simplifications for
          the operator list. These are enabled by default, and remove unnecessary operators
          (e.g. that are multiplying by zero and adding that to a signal). This increases both
          build speed and run speed. These simplifications can be disabled by modifying
          ``nengo_ocl.operators.simplifications``. (`#183`_)
        
        **Changed**
        
        - Added support for Nengo 3.1.0, and retired support for Nengo 3.0.0. (`#180`_)
        - Changes to improve benchmarks, including comparing between benchmarks. (`#182`_)
        
        .. _#180: https://github.com/nengo-labs/nengo-ocl/pull/180
        .. _#182: https://github.com/nengo-labs/nengo-ocl/pull/182
        .. _#183: https://github.com/nengo-labs/nengo-ocl/pull/183
        
        2.0.0 (Sept 4, 2020)
        ====================
        
        *Compatible with Nengo 3.0.0*
        
        **Added**
        
        - The documentation is now online at https://labs.nengo.ai/nengo-ocl/ (`#179`_)
        - ``Sparse`` transforms are now supported. (`#176`_)
        - Added ``Simulator.clear_probes`` method to clear probe data stored in memory.
          (`#179`_)
        
        **Changed**
        
        - Now requires Python >= 3.5. (`#172`_)
        - Now supports Nengo 3.0.0. Note that support for previous Nengo
          versions has been dropped. (`#172`_)
        - ``Convolution`` transforms are now supported. The previous code supporting ``Conv2d``
          and ``Pool2d`` processes (from NengoExtras) has been removed. (`#172`_)
        
        .. _#172: https://github.com/nengo-labs/nengo-ocl/pull/172
        .. _#176: https://github.com/nengo-labs/nengo-ocl/pull/176
        .. _#179: https://github.com/nengo-labs/nengo-ocl/pull/179
        
        1.4.0 (July 4, 2018)
        ====================
        
        **Improvements**
        
        - Supports recent Nengo versions, up to 2.8.0.
        - Supports the new ``SpikingRectifiedLinear`` neuron type.
        
        
        1.3.0 (October 6, 2017)
        =======================
        
        **Improvements**
        
        - Supports recent Nengo versions, up to 2.6.0.
        
        **Bugfixes**
        
        - Fixed an issue in which stochastic processes would not be
          fully reset on simulator reset.
        - Fixed an issue in which building a model multiple times
          could result in old probe data persisting.
        
        1.2.0 (February 23, 2017)
        =========================
        
        **Improvements**
        
        - Supports all Nengo versions from 2.1.2 to 2.3.1.
        - ``nengo_ocl.Simulator`` is no longer a subclass of ``nengo.Simulator``,
          reducing the chances that Nengo OCL will be affected by changes in Nengo.
        
        1.1.0 (November 30, 2016)
        =========================
        
        **Features**
        
        - Added support for ``RectifiedLinear`` and ``Sigmoid`` neuron types.
        - Added support for arbitrary ``Process`` subclasses. Unlike the processes
          that are explicitly supported like ``WhiteSignal``, these processes
          may not fully utilize the OpenCL device.
        - Added support for applying synaptic filters to matrices,
          which is commonly done when probing connection weights.
        
        **Improvements**
        
        - Supports all Nengo versions from 2.1.2 to 2.3.0.
        - The ``LIF`` model is now more accurate, and matches the implementation
          in Nengo (see `Nengo#975 <https://github.com/nengo/nengo/pull/975>`_).
        - Several operators have been optimized and should now run faster.
        
        **Bugfixes**
        
        - Fixed compatibility issues with Python 3,
          and certain versions of NumPy and Nengo.
        
        1.0.0 (June 6, 2016)
        ====================
        
        Release in support of Nengo 2.1.0. Since Nengo no longer supports Python 2.6,
        we now support Python 2.7+ and 3.3+.
        
        **Features**
        
        - Added support for ``Process`` class and subclasses, new in Nengo in 2.1.0.
          We specifically support the ``WhiteNoise``, ``WhiteSignal``, and
          ``PresentInput`` processes. We also support the ``Conv2d`` and ``Pool2d``
          processes in ``nengo_extras``.
        - ``LinearFilter`` is now fully supported, allowing for general synapses.
        
        **Improvements**
        
        - The Numpy simulator in this project (``sim_npy``) has been phased out and
          combined with the OCL simulator (``sim_ocl``). It is now called ``Simulator``
          and resides in ``simulator.py``.
        - Operator scheduling (i.e. the planner) is much faster. We still have only
          one planner (``greedy_planner``), which now resides in ``planners.py``.
        - Many small speed improvements, including a number of cases where data was
          needlessly copied off the device to check sizes, dtypes, etc.
        
        **Documentation**
        
        - Updated examples to use up-to-date Nengo syntax.
        
        0.1.0 (June 8, 2015)
        ====================
        
        Initial release of Nengo OpenCL!
        Supports Nengo 2.0.x on Python 2.6+ and 3.3+.
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Nengo
Classifier: Intended Audience :: Science/Research
Classifier: License :: Free for non-commercial use
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.5
Provides-Extra: all
Provides-Extra: optional
Provides-Extra: docs
Provides-Extra: tests
