============
Installation
============

The following instructions are for Linux and Mac OS X. It should be possible to
install and run PyNN on Windows, but this has not been tested.

Installing PyNN requires:

    * Python (version 2.7, 3.6+)
    * a recent version of the NumPy_ package
    * the lazyarray_ package
    * the Neo_ package (>= 0.8.0)
    * at least one of the supported simulators: e.g. NEURON, NEST, or Brian 2.

Optional dependencies are:

    * mpi4py_ (if you wish to run distributed simulations using MPI)
    * either Jinja2_ or Cheetah_ (templating engines)
    * the CSA_ library
    * h5py (to use the SONATA format)

Installing PyNN
===============

.. note:: if using NEURON or NEST, it is easiest if you install NEURON/NEST *before* you install PyNN (see below).

The easiest way to get PyNN is to use pip_::

    $ pip install pyNN

If you would prefer to install manually, :doc:`download the latest
source distribution <download>`, then run the setup script, e.g.::

    $ tar xzf PyNN-0.10.0.tar.gz
    $ cd PyNN-0.10.0
    $ python setup.py install

This will install it to your Python :file:`site-packages` directory, and may
require root privileges. We strongly recommend, however, that you use a
virtualenv_ or a Conda_ environment. We assume you have already installed the
simulator(s) you wish to use it with. If this is not the case, see below for
installation instructions.

Test it using something like the following::

    >>> import pyNN.nest as sim
    >>> sim.setup()
    >>> sim.end()

(This assumes you have NEST installed).

.. warning::

   If you get a warning "Unable to install NEST extensions. Certain models may not be available" then ensure the
   program :command:`nest-config` is on your system PATH.
   If you still get this message even after adding the directory containing :command:`nest-config` to the PATH,
   try ``pip uninstall PyNN``, then re-install with ``pip install --no-binary :all: PyNN``

With NEURON as the simulator, make sure you install NEURON *before* you install PyNN.
The PyNN installation will then compile PyNN-specific membrane mechanisms, which are loaded when importing the :mod:`neuron` module::

    >>> import pyNN.neuron as sim
    NEURON -- Release 7.4 (1370:16a7055d4a86) 2015-11-09
    Duke, Yale, and the BlueBrain Project -- Copyright 1984-2015
    See http://www.neuron.yale.edu/neuron/credits

    loading membrane mechanisms from /home/docker/dev/PyNN/pyNN/neuron/nmodl/x86_64/.libs/libnrnmech.so
    Additional mechanisms from files
     adexp.mod alphaisyn.mod alphasyn.mod expisyn.mod gap.mod gsfa_grr.mod hh_traub.mod
     izhikevich.mod netstim2.mod refrac.mod reset.mod stdwa_guetig.mod stdwa_softlimits.mod
     stdwa_songabbott.mod stdwa_symm.mod stdwa_vogels2011.mod tmgsyn.mod tmisyn.mod
     tsodyksmarkram.mod vecstim.mod

If you installed PyNN before installing NEURON, or if you update your PyNN installation,
you will need to manually run :command:`nrnivmodl` in the :file:`pyNN/neuron/nmodl` directory.

Installing NEURON
=================

Download the sources for NEURON 7.4 or later, in ``.tar.gz`` format, from `<http://www.neuron.yale.edu/neuron/download/getstd>`_.
Also download Interviews from the same location.

Compile Interviews and NEURON according to the instructions given at `<http://www.neuron.yale.edu/neuron/static/download/compilestd_unix.html>`_,
except that when you run :command:`configure`, add the options :option:`--with-nrnpython` and, optionally, :option:`--with-paranrn`, i.e.::

    $ ./configure --prefix=`pwd` --with-nrnpython --with-paranrn
    $ make
    $ make install

Make sure that you add the Interviews and NEURON :file:`bin` directories to your path.
Test that the Python support has been enabled by running::

    $ nrniv -python
    NEURON -- Release 7.4 (1370:16a7055d4a86) 2015-11-09
    Duke, Yale, and the BlueBrain Project -- Copyright 1984-2015
    See http://www.neuron.yale.edu/neuron/credits

    >>> import hoc
    >>> import nrn

Now you can compile and install NEURON as a Python package::

    $ cd src/nrnpython
    $ python setup.py install

Now test everything worked::

    $ python
    >>> import neuron
    NEURON -- Release 7.4 (1370:16a7055d4a86) 2015-11-09
    Duke, Yale, and the BlueBrain Project -- Copyright 1984-2015
    See http://www.neuron.yale.edu/neuron/credits

If you run into problems, check out the `NEURON Forum`_.


Installing NEST and PyNEST
==========================

NEST 2.18.0 can be downloaded from `<http://www.nest-simulator.org/download/>`_.
Earlier versions of NEST may not work with this version of PyNN.
The full installation instructions are available in the file INSTALL, which you can find in the NEST source package,
or at `<http://www.nest-simulator.org/installation/>`_.

Now try it out::

    $ cd ~
    $ python
    >>> import nest
                 -- N E S T --
      Copyright (C) 2004 The NEST Initiative

    Version: v2.20.0

    ...
    >>> nest.Models()
    (u'ac_generator', u'aeif_cond_alpha', u'aeif_cond_alpha_RK5', u'aeif_cond_alpha_multisynapse',
    ...

Check that ``'aeif_cond_alpha'`` is in the list of models. If it is not, you may need to install a newer version of the `GNU Scientific Library`_ and then recompile NEST.


Installing Brian2
=================

Instructions for downloading and installing `Brian 2`_ are available from `<https://briansimulator.org/install/>`_.
Note that this version of PyNN works with Brian 2. If you need to use Brian 1, try PyNN 0.9.6.


.. _PyNN: http://neuralensemble.org/PyNN
.. _NumPy: http://www.numpy.org/
.. _lazyarray: https://pypi.python.org/pypi/lazyarray
.. _CSA: https://software.incf.org/software/csa/
.. _Jinja2: http://jinja.pocoo.org/
.. _Cheetah: http://www.cheetahtemplate.org/
.. _mpi4py: http://mpi4py.scipy.org/
.. _pip: http://www.pip-installer.org/
.. _Brian 2: http://briansimulator.org/
.. _`PyNN download page`: https://neuralensemble.org/trac/PyNN/wiki/Download
.. _`distutils`: http://docs.python.org/2/install/index.html
.. _`GNU Scientific Library`: http://www.gnu.org/software/gsl/
.. _`NEURON Forum`: http://www.neuron.yale.edu/phpBB/index.php
.. _Neo: http://neuralensemble.org/neo
.. _virtualenv: https://virtualenv.readthedocs.org/
.. _Conda: http://conda.pydata.org
