============
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 3.9+)
* a recent version of the NumPy_ package
* the lazyarray_ package
* the Neo_ package (>= 0.13.4)
* at least one of the supported simulators: e.g. NEURON, NEST, Brian 2 or Arbor.

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
===============

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

.. parsed-literal::

    $ tar xzf PyNN-|release|.tar.gz
    $ pip install ./PyNN-|release|

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.


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

For recent versions of NEURON,

::

    $ pip install neuron

may be all you need. If you have more complex needs, try the following.

Download the sources for NEURON 8.0 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 -- VERSION 8.2.2 release/8.2 (93d41fafd) 2022-12-15
    Duke, Yale, and the BlueBrain Project -- Copyright 1984-2022
    See http://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

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

Now test that NEURON works with PyNN:

    >>> import pyNN.neuron as sim

(The first time you do this, PyNN will compile some PyNN-specific membrane mechanisms).


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

NEST 3.4-3.7 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 at `<https://nest-simulator.readthedocs.io/en/v3.4/installation/index.html/>`_.

Now try it out::

    $ cd ~
    $ python
    >>> import nest

                -- N E S T --
    Copyright (C) 2004 The NEST Initiative

    Version: 3.4
    ...

    >>> nest.node_models
    ('weight_recorder', 'gauss_rate_ipn', 'lin_rate_ipn', 'sigmoid_rate_ipn', 'sigmoid_rate_gg_1998_ipn', 'tanh_rate_ipn', ...)

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.

Now test NEST together with PyNN using something like the following::

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

.. 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,
   then you will still be able to use pyNN.nest, just a small number of models will not be available.


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.


Installing Arbor
================

Instructions for installing Arbor_ are available from `<https://docs.arbor-sim.org/en/latest/install>`_.

.. warning::

    At present, Arbor only works with the experimental multi-compartment neuron models;
    support for point neuron models is planned for the next release.


.. _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
.. _Arbor: https://arbor-sim.org
