Metadata-Version: 2.0
Name: nengo-ocl
Version: 1.2.0
Summary: OpenCL-backed neural simulations using the Neural Engineering Framework
Home-page: https://github.com/nengo/nengo_ocl
Author: Applied Brain Research
Author-email: info@appliedbrainresearch.com
License: Free for non-commercial use
Description-Content-Type: UNKNOWN
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: Free for non-commercial use
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: mako
Requires-Dist: nengo
Requires-Dist: pyopencl

****************************
OpenCL-based Nengo Simulator
****************************

This project 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()

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 Nengo OCL. 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
Nengo OCL developers at one point in time.

AMD OCL on Debian Unstable
--------------------------

On Debian unstable (sid) there are packages in non-free and contrib
to install AMD's OCL 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 OCL 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 OCL 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:

   - Features
   - Improvements
   - Bugfixes
   - Documentation

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


