Merge pull request #787 from NeuralEnsemble/mc

Merge mc branch

.gitignore

@@ -15,6 +15,7 @@
 *.tmp*
 *.swp
 .idea
+.vscode
 
 # Compiled source
 *.py[ocd]
@@ -83,6 +84,6 @@ examples/*.svg
 tmp
 /pynnpg.sh
 /cleanpynn.sh
-
-.eggs/
+doc/logos
+docker_*.eggs/
 /test/system/tmp_serialization_test

doc/building_networks.txt

@@ -4,8 +4,8 @@ Building networks
 
 .. toctree::
    :maxdepth: 2
-   
+
    neurons
    connections
    space
-
+   mc_api

doc/conf.py

@@ -76,9 +76,9 @@ class MockNESTModule(mock.Mock):
 # built documents.
 #
 # The short X.Y version.
-version = '0.11'
+version = '2.0-alpha'
 # The full version, including alpha/beta/rc tags.
-release = '0.11.0'
+release = '2.0.0.alpha.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/index.txt

@@ -2,12 +2,20 @@
 PyNN: documentation
 ===================
 
+.. warning:: This documentation is for a future version of PyNN which is still under heavy development.
+             The API is liable to change before the final release.
+
 .. toctree::
    :maxdepth: 1
 
+..   mc_installation
+..   mc_aims
+..   mc_api
+..   mc_examples
+
    introduction
    installation
-   quickstart
+..   quickstart
    building_networks
    injecting_current
    recording
@@ -28,6 +36,7 @@ PyNN: documentation
 
    This is the documentation for version |release|. Earlier versions:
 
+     - `version 0.11`_
      - `version 0.10`_
      - `version 0.9`_
      - `version 0.8`_
@@ -71,6 +80,7 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+.. _`version 0.11`: http://neuralensemble.org/docs/PyNN/0.11/
 .. _`version 0.10`: http://neuralensemble.org/docs/PyNN/0.10/
 .. _`version 0.9`: http://neuralensemble.org/docs/PyNN/0.9/
 .. _`version 0.8`: http://neuralensemble.org/docs/PyNN/0.8/

doc/installation.txt

@@ -11,7 +11,7 @@ Installing PyNN requires:
     * a recent version of the NumPy_ package
     * the lazyarray_ package
     * the Neo_ package (>= 0.11.0)
-    * at least one of the supported simulators: e.g. NEURON, NEST, or Brian 2.
+    * at least one of the supported simulators: e.g. NEURON, NEST, Brian 2 or Arbor.
 
 Optional dependencies are:
 
@@ -23,43 +23,22 @@ Optional dependencies are:
 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
+    $ 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.11.0.tar.gz
-    $ pip install ./PyNN-0.11.0
+    $ tar xzf PyNN-0.12.0.tar.gz
+    $ pip install ./PyNN-0.12.0
 
 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,
-   then you will still be able to use pyNN.nest, just a small number of models will not be available.
-
-For NEURON, PyNN will compile PyNN-specific membrane mechanisms the first time you import the :mod:`neuron` module::
-
-    >>> import pyNN.neuron as sim
-
 
 Installing NEURON
 =================
@@ -105,11 +84,17 @@ Now test everything worked::
 
 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 can be downloaded from `<http://www.nest-simulator.org/download/>`_.
+NEST 3.4-3.6 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/>`_.
 
@@ -130,6 +115,19 @@ Now try it out::
 
 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
 =================
@@ -138,6 +136,17 @@ Instructions for downloading and installing `Brian 2`_ are available from `<http
 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
@@ -154,3 +163,4 @@ Note that this version of PyNN works with Brian 2. If you need to use Brian 1, t
 .. _Neo: http://neuralensemble.org/neo
 .. _virtualenv: https://virtualenv.readthedocs.org/
 .. _Conda: http://conda.pydata.org
+.. _Arbor: https://arbor-sim.org

doc/introduction.txt

@@ -4,15 +4,15 @@ Introduction
 
 PyNN_ (pronounced 'pine') is a simulator-independent language for building neuronal network models.
 
-In other words, you can write the code for a model once, using the PyNN API and the Python_ programming language, and then run it without modification on any simulator that PyNN supports (currently NEURON_, NEST_ and `Brian 2`_) as well as on certain neuromorphic hardware systems.
+In other words, you can write the code for a model once, using the PyNN API and the Python_ programming language, and then run it without modification on any simulator that PyNN supports (currently NEURON_, NEST_, `Brian 2`_, and Arbor_) as well as on certain neuromorphic hardware systems.
 
 The PyNN API aims to support modelling at a high-level of abstraction (populations of neurons, layers, columns and the connections between them) while still allowing access to the details of individual neurons and synapses when required. PyNN provides a library of standard neuron, synapse and synaptic plasticity models, which have been verified to work the same on the different supported simulators. PyNN also provides a set of commonly-used connectivity algorithms (e.g. all-to-all, random, distance-dependent, small-world) but makes it easy to provide your own connectivity in a simulator-independent way, either using the Connection Set Algebra (`Djurfeldt, 2012`_) or by writing your own Python code.
 
 Even if you don't wish to run simulations on multiple simulators, you may benefit from writing your simulation code using PyNN's powerful, high-level interface. In this case, you can use any neuron or synapse model supported by your simulator, and are not restricted to the standard models. PyNN transparently supports distributed simulations (using MPI) where the underlying simulator does.
 
 It is straightforward to port an existing model from a Python-supporting simulator to PyNN, since this can be done incrementally, replacing one piece of simulator-specific code at a time with the PyNN equivalent, and testing that the model behaviour is unchanged at each step.
 
-:doc:`Download<download>` the current stable release of the library (0.11.0) or get the development version from the `Git repository`_ .
+:doc:`Download<download>` the current stable release of the library (0.12.0) or get the development version from the `Git repository`_ .
 
 Licence
 -------
@@ -44,4 +44,5 @@ If you have questions or comments about PyNN, please post a message on the `Neur
 .. _`Git repository`: https://github.com/NeuralEnsemble/PyNN
 .. _`PyNN issue tracker`: https://github.com/NeuralEnsemble/PyNN/issues
 .. _`NeuralEnsemble Google group`: http://groups.google.com/group/neuralensemble
-.. _`Djurfeldt, 2012`: http://dx.doi.org/10.1007/s12021-012-9146-1
+.. _`Djurfeldt, 2012`: http://doi.org/10.1007/s12021-012-9146-1
+.. _Arbor: https://arbor-sim.org

doc/mc_aims.txt

@@ -0,0 +1,29 @@
+====================================================
+Multicompartmental modelling with PyNN: design goals
+====================================================
+
+The three principal aims of the PyNN project are:
+
+    (i) to make it easy to run models on different simulators (and on neuromorphic hardware), in order to facilitate cross-checking, reproducibility and re-use;
+    (ii) to provide a simulator-independent platform on which to build an ecosystem of tools for computational neuroscience (visualization libraries, workflow engines, etc.) rather than having tools that only work with one simulator;
+    (iii) to support modelling at a high-level of abstraction (populations of neurons, layers, columns and the connections between them) while still allowing access to the details of individual neurons and synapses when required.
+
+
+The scope of PyNN was originally limited to networks of point neurons (integrate-and-fire and related models).
+The primary reason for this was that at the time only the NEURON_ simulator had both support for multicompartment models and a Python interface.
+
+This situation has now changed, with the release of `Brian 2`_, the addition of Python support to MOOSE_, development of the Arbor_ simulation library, and support for multicompartment models in the future versions of the BrainScaleS and SpiNNaker neuromorphic chips.
+
+
+We are therefore adapting the PyNN API to support both point neuron models and morphologically-and-biophysically-detailed neuron models (and mixed networks of both model types). The principal design goals are:
+
+    (i) maintain the same main level of abstraction: populations of neurons and the sets of connections between populations (projections);
+    (ii) backwards compatibility (point neuron models created with PyNN 1.0 (not yet released) or later should work with no, or minimal, changes);
+    (iii) integrate with other open-source simulation tools and standards (e.g. NeuroML) wherever possible, rather than reinventing the wheel;
+    (iv) support neuromorphic hardware systems.
+
+
+.. _NEURON: https://www.neuron.yale.edu/neuron/
+.. _Arbor: https://github.com/eth-cscs/arbor
+.. _MOOSE: https://moose.ncbs.res.in
+.. _`Brian 2`: http://briansimulator.org