Merge branch 'genn_5'

Author: neworderofjamie

.dockerignore

@@ -1,12 +1,9 @@
 .git
 build
 dist
-documentation
-doxygen
+docs
 lib
 obj*
 tests
-userproject
-!userproject/include
 **/*.so
 **/*.lib

Dockerfile

@@ -8,7 +8,7 @@ LABEL maintainer="J.C.Knight@sussex.ac.uk" \
     org.opencontainers.image.source="https://github.com/genn-team/genn" \
     org.opencontainers.image.title="GeNN Docker image"
 
-# Update APT database and upgrade any outdated packages and install Python, pip and swig
+# Update APT database and upgrade any outdated packages and install Python, pip and pkgconfig
 RUN apt-get update && \
     apt-get upgrade -y && \
     apt-get install -yq --no-install-recommends python3-dev python3-pip swig gosu nano
@@ -22,7 +22,7 @@ RUN update-alternatives --install /usr/bin/python python /usr/bin/python3 1
 
 # Upgrade pip itself and install numpy and jupyter
 RUN python -m pip install --upgrade pip && \
-    python -m pip install numpy jupyter matplotlib
+    python -m pip install numpy jupyter matplotlib psutil pybind11
 
 # Copy GeNN into /opt
 COPY . ${GENN_PATH}
@@ -31,9 +31,7 @@ COPY . ${GENN_PATH}
 WORKDIR ${GENN_PATH}
 
 # Install GeNN and PyGeNN
-RUN make install -j `lscpu -p | egrep -v '^#' | sort -u -t, -k 2,4 | wc -l`
-RUN make DYNAMIC=1 LIBRARY_DIRECTORY=${GENN_PATH}/pygenn/genn_wrapper/ -j `lscpu -p | egrep -v '^#' | sort -u -t, -k 2,4 | wc -l`
-RUN python setup.py develop
+RUN python3 setup.py develop
 
 # Start entrypoint
 # **NOTE** in 'exec' mode shell arguments aren't expanded so can't use environment variables

Jenkinsfile

@@ -2,64 +2,35 @@
 include src/genn/MakefileCommon
 
 # List of backends
-BACKENDS		:=single_threaded_cpu
+BACKENDS		:=single_threaded_cpu_backend
 ifdef CUDA_PATH
-	BACKENDS	+=cuda
+	BACKENDS	+=cuda_backend
 endif
 
 ifdef OPENCL_PATH
-	BACKENDS	+=opencl
+	BACKENDS	+=opencl_backend
 endif
 
 # Build list of libraries
-BACKEND_LIBS		:=$(BACKENDS:%=$(LIBRARY_DIRECTORY)/libgenn_%_backend$(GENN_PREFIX).$(LIBRARY_EXTENSION))
+BACKEND_LIBS		:=$(BACKENDS:%=$(LIBRARY_DIRECTORY)/libgenn_%$(GENN_PREFIX).$(LIBRARY_EXTENSION))
 
 # Default install location
 PREFIX 			?= /usr/local
 
-.PHONY: all clean install uninstall libgenn $(BACKENDS)
+.PHONY: all clean genn $(BACKENDS)
 
-all: libgenn $(BACKENDS)
+all: genn $(BACKENDS)
 
-install: libgenn $(BACKENDS)
-	@# Make install directories
-	@mkdir -p $(PREFIX)/bin
-	@mkdir -p $(PREFIX)/include/genn
-	@mkdir -p $(PREFIX)/share/genn
-	@mkdir -p $(PREFIX)/lib
-	@mkdir -p $(PREFIX)/src/genn/generator
-	@# Deploy libraries, headers and data
-	@cp -f $(LIBRARY_DIRECTORY)/libgenn*.a $(PREFIX)/lib
-	@cp -rf $(GENN_DIR)/include/genn/* $(PREFIX)/include/genn/
-	@cp -rf $(GENN_DIR)/share/genn/* $(PREFIX)/share/genn/
-	@# Deploy minimal set of Makefiles for building generator
-	@cp -r $(GENN_DIR)/src/genn/MakefileCommon $(PREFIX)/src/genn
-	@cp -r $(GENN_DIR)/src/genn/generator/Makefile* $(PREFIX)/src/genn/generator
-	@# Deploy genn_generator source and shell scripts
-	@cp -r $(GENN_DIR)/src/genn/generator/generator.cc $(PREFIX)/src/genn/generator
-	@cp -r $(GENN_DIR)/bin/genn-buildmodel.sh $(PREFIX)/bin
-	@cp -r $(GENN_DIR)/bin/genn-create-user-project.sh $(PREFIX)/bin
-
-uninstall:
-	@# Delete installed resources
-	@rm -rf $(PREFIX)/src/genn
-	@rm -rf $(PREFIX)/lib/libgenn*.a
-	@rm -rf $(PREFIX)/include/genn
-	@rm -f $(PREFIX)/share/genn
-	# Delete installed executables
-	@rm -f $(PREFIX)/bin/genn-buildmodel.sh
-	@rm -f $(PREFIX)/bin/genn-create-user-project.sh
-
-libgenn:
+genn:
 	$(MAKE) -C src/genn/genn
 
-single_threaded_cpu:
+single_threaded_cpu_backend: genn
 	$(MAKE) -C src/genn/backends/single_threaded_cpu
 
-cuda:
+cuda_backend: genn
 	$(MAKE) -C src/genn/backends/cuda
 
-opencl:
+opencl_backend: genn
 	$(MAKE) -C src/genn/backends/opencl
 
 clean:

LICENSE

@@ -33,74 +33,55 @@ purposes and are opened and closed without warning.
 
 ### Installing GeNN
 
-Installing GeNN comprises a few simple steps [^1] to create the GeNN
-development environment:
-
-[^1]: While GeNN models are normally simulated using CUDA on NVIDIA GPUs, if you want to use GeNN on a machine without an NVIDIA GPU, you can skip steps v and vi and use GeNN in "CPU_ONLY" mode.
-
-1.  If you have downloaded a zip file, unpack GeNN.zip in a convenient
-    location. Otherwise enter the directory where you downloaded the Git
-    repository.
-
-2.  Add GeNN's 'bin' directory to your path, e.g. if you are running Linux or Mac OS X and extracted/downloaded GeNN to
-    ``$HOME/GeNN``, this can be done with:
-    ```bash
-    export PATH=$PATH:$HOME/GeNN/bin
-    ```
-    to make this change persistent, this can be added to your login script (e.g. `.profile` or `.bashrc`) using your favourite text editor or with:
-    ```bash
-    echo "export PATH=$PATH:$CUDA_PATH/bin" >> ~/.bash_profile
-    ```
-     If you are using Windows, the easiest way to modify the path is 
-     by using the 'Environment variables' GUI, which can be accessed by clicking start and searching for 
-     (by starting to type) 'Edit environment variables for your account'.
-     In the upper 'User variables' section, scroll down until you see 'Path',
-     select it and click 'Edit'.
-     Now add a new directory to the path by clicking 'New' in the 'Edit environment variable' window e.g.:
-     ![Screenshot of windows edit environment variable window](/doxygen/images/path_windows.png)
-     if GeNN is installed in a sub-directory of your home directory (``%USERPROFILE%`` is an environment variable which points to the current user's home directory) called ``genn``.
-
-3.  Install the C++ compiler on the machine, if not already present.
-     For Windows, download Microsoft Visual Studio Community Edition from
-     https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx.
-     When installing Visual Studio, one should select the 'Desktop 
-    development with C++' configuration.
-     Mac users should download and set up Xcode from
-     https://developer.apple.com/xcode/index.html
-     , Linux users should install the GNU compiler collection gcc and g++
-     from their Linux distribution repository, or alternatively from
-     https://gcc.gnu.org/index.html
-     
-4.  If your machine has a GPU and you haven't installed CUDA already, 
+In future we plan on providing binary builds of GeNN via conda. However, for now, GeNN
+needs to be installed from source.
+
+#### Pre-installation
+
+1.  Install the C++ compiler on the machine, if not already present.
+    For Windows, Visual Studio 2019 or above is required. The Microsoft Visual Studio 
+    Community Edition can be downloaded from
+    https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx.
+    When installing Visual Studio, one should select the 'Desktop 
+    development with C++' configuration. On Linux, the GNU Compiler 
+    Collection (GCC) 7.5 or above is required. This can be obtained from your
+    Linux distribution repository, for example on Ubuntu by running ``sudo apt-get install g++``, 
+    or alternatively from https://gcc.gnu.org/index.html.
+2.  If your machine has an NVIDIA GPU and you haven't installed CUDA already, 
     obtain a fresh installation of the NVIDIA CUDA toolkit from
     https://developer.nvidia.com/cuda-downloads
-    Again, be sure to pick CUDA and C++ compiler versions which are compatible
+    Be sure to pick CUDA and C++ compiler versions which are compatible
     with each other. The latest C++ compiler need not necessarily be
     compatible with the latest CUDA toolkit.
-
-5.  GeNN uses the ``CUDA_PATH`` environment variable to determine which 
+3.  GeNN uses the ``CUDA_PATH`` environment variable to determine which 
     version of CUDA to build against. On Windows, this is set automatically when 
     installing CUDA. However, if you choose, you can verify which version is 
-    selected by looking for the ``CUDA_PATH`` environment variable in the lower 'System variables' section of the GUI you used to configure the path:
-    ![Screenshot of windows edit environment variable window](/doxygen/images/cuda_path_windows.png)
-    here, CUDA 10.1 and 11.4 are installed and CUDA 11.4 is selected via ``CUDA_PATH``.
-    However, on Linux and Mac you need to set ``CUDA_PATH`` manually with:
-    ```bash
-    export CUDA_PATH=/usr/local/cuda
-    ```
+    selected by running ``echo %CUDA_PATH`` in a command prompt.
+    However, on Linux, you need to set ``CUDA_PATH`` manually with:
+    ``export CUDA_PATH=/usr/local/cuda``
     assuming CUDA is installed in /usr/local/cuda (the standard location 
     on Ubuntu Linux). Again, to make this change persistent, this can
     be added to your login script (e.g. ``.profile`` or ``.bashrc``)
-
-This normally completes the installation. Windows users must close
-and reopen their command window so changes to the path take effect.
-
-If you are using GeNN in Windows, the Visual Studio development
-environment must be set up within every instance of the CMD.EXE command
-window used. One can open an instance of CMD.EXE with the development
-environment already set up by navigating to Start - All Programs - 
-Microsoft Visual Studio - Visual Studio Tools - x64 Native Tools Command Prompt. You may also wish to
-create a shortcut for this tool on the desktop, for convenience.
+4.  Either download the latest release of GeNN and extract into your 
+    home directory or clone using git from https://github.com/genn-team/genn
+5.  On Linux, install the development version of libffi. For example, on Ubuntu you can do this
+    by running ``sudo apt-get install libffi-dev``.
+6.  Install the pybind11, psutil and numpy packages with pip i.e. ``pip install pybind11 psutil numpy``.
+
+
+#### Building with setup.py
+From the GeNN directory, the GeNN libraries and python package can be built
+with ``python setup.py install``. If you wish to create an editable install
+(most useful if you are intending to modify GeNN yourself) you can also used
+``python setup.py develop``. On Linux (or Windows if you have a debug version
+of the python libraries installed) you can build a debug version of GeNN with
+``python setup.py build_ext --debug develop``.
+
+#### Building with pip
+From the GeNN directory, the GeNN libraries and python package can be built
+with ``pip install .``. If you wish to create an editable install
+(most useful if you are intending to modify GeNN yourself) you can also used
+``pip install --editable .``.
 
 ### Docker
 You can also use GeNN through our CUDA-enabled docker container which comes with GeNN pre-installed.
@@ -158,116 +139,15 @@ docker run --gpus=all -e LOCAL_USER_ID=`id -u $USER` -e LOCAL_GROUP_ID=`id -g $U
 
 ### Sample projects
 
-At the moment, the following C++ example projects are provided with GeNN:
-
-- Self-organisation with STDP in the locust olfactory system \([Nowotny et al. 2005][@Nowotnyetal2005]\):
-    - with all-to-all connectivity, using built-in neuron and synapse models \(for benchmarks see [Yavuz et al. 2016][@Yavuzetal2016]\)
-    - with sparse connectivity for some synapses, using user-defined neuron-and synapse models \(for benchmarks see [Yavuz et al. 2016][@Yavuzetal2016]\)
-    - using BITMASK connectivity
-    - using synapses with axonal delays
-- Pulse-coupled network of Izhikevich neurons \([Izhikevich 2003][@Izhikevich2003]\) (for benchmarks see [Yavuz et al. 2016][@Yavuzetal2016])
-
-- Genetic algorithm for tracking parameters in a Hodgkin-Huxley model cell
-
-- Classifier based on an abstraction of the insect olfactory system \([Schmuker et al. 2014][@Schmukeretal2014]\)
+At the moment, the following Python example projects are provided with GeNN:
 
 - Cortical microcircuit model \([Potjans et al. 2014][@Potjans2014]\)
+- SuperSpike model \([Zenke et al. 2018][@Zenke2018]\)
+- MNIST classifier using an insect-inspired mushroom body model
 
-- Toy examples:
-    - Single neuron population of Izhikevich neuron(s) receiving Poisson spike trains as input
-    - Single neuron population of Izhikevich neuron(s) with no synapses
-    - Network of Izhikevich neurons with delayed synapses
-
-In order to get a quick start and run one of the the provided example models, navigate to one of the example project directories in the userproject sub-directory, and then follow the instructions in the README file contained within.
-
-## Simulating a new model
-
-The sample projects listed above are already quite highly integrated examples. If you wanted to use GeNN to develop a new C++ model, you would do the following:
-
-1. The neuronal network of interest is defined in a model definition file,
-    e.g. ``Example1.cc``.  
-
-2.  Within the the model definition file ``Example1.cc``, the following tasks
-    need to be completed:
-
-    1.  The GeNN file ``modelSpec.h`` needs to be included,
-        ```c++
-        #include "modelSpec.h"
-        ```
-
-    2.  The values for initial variables and parameters for neuron and synapse
-        populations need to be defined, e.g.
-        ```c++
-        NeuronModels::PoissonNew::ParamValues poissonParams(
-        10.0);      // 0 - firing rate
-        ```
-        would define the (homogeneous) parameters for a population of Poisson
-        neurons [^2].
-        [^2]: The number of required parameters and their meaning is defined by the
-        neuron or synapse type. Refer to the [User manual](https://genn-team.github.io/genn/documentation/4/html/dc/d05/UserManual.html) for details. We recommend, however, to use comments like
-        in the above example to achieve maximal clarity of each parameter's
-        meaning.
-
-        If heterogeneous parameter values are required for a particular
-        population of neurons (or synapses), they need to be defined as "variables"
-        rather than parameters.  See the [User manual](https://genn-team.github.io/genn/documentation/4/html/dc/d05/UserManual.html) for how to define new neuron (or synapse) types and the [Variable initialisation](https://genn-team.github.io/genn/documentation/4/html/d4/dc6/sectVariableInitialisation.html) section for more information on 
-        initialising these variables to hetererogenous values.
-
-    3.  The actual network needs to be defined in the form of a function
-        ``modelDefinition`` [^3], i.e. 
-        ```c++
-        void modelDefinition(ModelSpec &model); 
-        ```
-        [^3]: The name ``modelDefinition`` and its parameter of type ``ModelSpec&``
-        are fixed and cannot be changed if GeNN is to recognize it as a
-        model definition.
-
-    4.  Inside ``modelDefinition()``, The time step ``DT`` needs to be defined, e.g.
-        ```c++
-        model.setDT(0.1);
-        ```
-        \note
-        All provided examples and pre-defined model elements in GeNN work with
-        units of mV, ms, nF and uS. However, the choice of units is entirely
-        left to the user if custom model elements are used.
-
-    [MBody1.cc](userproject/MBody1_project/model/MBody1.cc) shows a typical example of a model definition function. In
-    its core it contains calls to ``ModelSpec::addNeuronPopulation`` and
-    ``ModelSpec::addSynapsePopulation`` to build up the network. For a full range
-    of options for defining a network, refer to the [User manual](https://genn-team.github.io/genn/documentation/4/html/dc/d05/UserManual.html).
-
-3.  The programmer defines their own "simulation" code similar to
-    the code in [MBody1Sim.cc](userproject/MBody1_project/model/MBody1Sim.cc). In this code,
-
-    1.  They can manually define the connectivity matrices between neuron groups. 
-        Refer to the \ref subsect34 section for the required format of
-        connectivity matrices for dense or sparse connectivities.
-
-    2.  They can define input patterns or individual initial values for neuron and 
-        / or synapse variables.
-        \note
-        The initial values or initialisation "snippets" given in the ``modelDefinition`` are automatically applied. 
-
-    3.  They use ``stepTime()`` to run one time step on either the CPU or GPU depending on the options passed to genn-buildmodel.
-    
-    4.  They use functions like ``copyStateFromDevice()`` etc to transfer the
-        results from GPU calculations to the main memory of the host computer
-        for further processing.
-
-    5.  They analyze the results. In the most simple case this could just be
-        writing the relevant data to output files.
+In order to get a quick start and run one of the the provided example models, navigate to the userproject directory, and run the python script with ``--help`` to see what options are available.
 
 For more details on how to use GeNN, please see [documentation](http://genn-team.github.io/genn/).
 
-If you use GeNN in your work, please cite "Yavuz, E., Turner, J. and Nowotny, T. GeNN: a code generation framework for accelerated brain simulations. Scientific Reports, 6. (2016)"
-
-
-[@Izhikevich2003]: https://doi.org/10.1109/TNN.2003.820440 "Izhikevich, E. M. Simple model of spiking neurons. IEEE transactions on neural networks 14, 1569–1572 (2003)"
-
-[@Nowotnyetal2005]: https://doi.org/10.1007/s00422-005-0019-7 "Nowotny, T., Huerta, R., Abarbanel, H. D. & Rabinovich, M. I. Self-organization in the olfactory system: one shot odor recognition in insects. Biological cybernetics 93, 436–446 (2005)"
-
 [@Potjans2014]: https://doi.org/10.1093/cercor/bhs358 "Potjans, T. C., & Diesmann, M. The Cell-Type Specific Cortical Microcircuit: Relating Structure and Activity in a Full-Scale Spiking Network Model. Cerebral Cortex, 24(3), 785–806 (2014)"
-
-[@Schmukeretal2014]: https://doi.org/10.1073/pnas.1303053111 "Schmuker, M., Pfeil, T. and Nawrot, M.P. A neuromorphic network for generic multivariate data classification. Proceedings of the National Academy of Sciences, 111(6), pp.2081-2086 (2014)"
-
-[@Yavuzetal2016]: https://doi.org/10.1038%2Fsrep18854 "Yavuz, E., Turner, J. and Nowotny, T. GeNN: a code generation framework for accelerated brain simulations. Scientific reports, 6. (2016)"
+[@Zenke2018]: https://doi.org/10.1162/neco_a_01086  "Zenke, F., & Ganguli, S. (2018). SuperSpike: Supervised Learning in Multilayer Spiking Neural Networks. Neural Computation, 30(6), 1514–1541."