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
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
Requires-Dist: nengo (>=3.1.0)
Requires-Dist: mako
Requires-Dist: pyopencl
Provides-Extra: all
Requires-Dist: matplotlib (>=1.4) ; extra == 'all'
Requires-Dist: nbsphinx ; extra == 'all'
Requires-Dist: nengo-sphinx-theme (>=1.2.0) ; extra == 'all'
Requires-Dist: numpydoc (>=0.6.0) ; extra == 'all'
Requires-Dist: sphinx (>=1.8) ; extra == 'all'
Requires-Dist: pytest (>=3.6.0) ; extra == 'all'
Requires-Dist: pytest-allclose (>=1.0.0) ; extra == 'all'
Requires-Dist: pytest-plt (>=1.0.0) ; extra == 'all'
Requires-Dist: pytest-rng (>=1.0.0) ; extra == 'all'
Provides-Extra: docs
Requires-Dist: matplotlib (>=1.4) ; extra == 'docs'
Requires-Dist: nbsphinx ; extra == 'docs'
Requires-Dist: nengo-sphinx-theme (>=1.2.0) ; extra == 'docs'
Requires-Dist: numpydoc (>=0.6.0) ; extra == 'docs'
Requires-Dist: sphinx (>=1.8) ; extra == 'docs'
Provides-Extra: optional
Provides-Extra: tests
Requires-Dist: matplotlib (>=1.4) ; extra == 'tests'
Requires-Dist: pytest (>=3.6.0) ; extra == 'tests'
Requires-Dist: pytest-allclose (>=1.0.0) ; extra == 'tests'
Requires-Dist: pytest-plt (>=1.0.0) ; extra == 'tests'
Requires-Dist: pytest-rng (>=1.0.0) ; extra == 'tests'

****************************
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+.


