diff --git a/doxygen/01_Installation.dox b/doxygen/01_Installation.dox index c18aa960c1..5f785904f7 100644 --- a/doxygen/01_Installation.dox +++ b/doxygen/01_Installation.dox @@ -10,13 +10,13 @@ Point your browser to \a https://github.com/genn-team/genn/releases and download a release from the list by clicking the relevant source code button. Note that GeNN is only distributed in the form of source code due to its code generation design. Binary distributions would not -make sense in this framework and are not provided. +make sense in this framework and hence are not provided. After downloading continue to install GeNN as described in the \ref installing section below. \section GitSnapshot Obtaining a Git snapshot If it is not yet installed on your system, download and install Git -(\a http://git-scm.com/). Then clone the GeNN repository from Github +(\a http://git-scm.com/).Then clone the GeNN repository from Github \code git clone https://github.com/genn-team/genn.git \endcode @@ -29,14 +29,14 @@ source version upon which the next release will be based. There are other branches in the repository that are used for specific development purposes and are opened and closed without warning. -As an alternative to using git you can also download the full content of -GeNN sources clicking on the "Download ZIP" button on the bottom right +An alternative to using git is to download the full content of +GeNN sources by clicking on the "Download ZIP" button on the bottom right of the GeNN Github page (\a https://github.com/genn-team/genn). \section installing Installing GeNN Installing GeNN comprises a few simple steps to create the GeNN -development environment. +development environment: \note 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. @@ -49,7 +49,7 @@ repository. \code export PATH=$PATH:$HOME/GeNN/bin \endcode - to your login script (e.g. `.profile` or `.bashrc`. If you are using + to your login script (e.g. `.profile` or `.bashrc`). If you are using WINDOWS, the path should be a windows path as it will be interpreted by the Visual C++ compiler `cl`, and environment variables are best set using `SETX` in a Windows cmd window. @@ -65,22 +65,19 @@ repository. For Windows, download Microsoft Visual Studio Community Edition from \a 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' and the 'Windows 8.1 SDK' and 'Windows + development with C++' configuration and the 'Windows 8.1 SDK' and 'Windows Universal CRT' individual components. Mac users should download and set up Xcode from \a https://developer.apple.com/xcode/index.html - Linux users should install the GNU compiler collection gcc and g++ + , Linux users should install the GNU compiler collection gcc and g++ from their Linux distribution repository, or alternatively from \a https://gcc.gnu.org/index.html - Be sure to pick CUDA and C++ compiler versions which are compatible - with each other. The latest C++ compiler is not necessarily - compatible with the latest CUDA toolkit. - + (v) If your machine has a GPU and you haven't installed CUDA already, obtain a fresh installation of the NVIDIA CUDA toolkit from \a https://developer.nvidia.com/cuda-downloads Again, be sure to pick CUDA and C++ compiler versions which are compatible - with each other. The latest C++ compiler is not necessarily + with each other. The latest C++ compiler need not necessarily be compatible with the latest CUDA toolkit. (vi) Set the `CUDA_PATH` variable if it is not already set by the @@ -91,14 +88,14 @@ repository. in your login script (or, if CUDA is installed in a non-standard location, the appropriate path to the main CUDA directory). For most people, this will be done by the CUDA install script and - the default value of /usr/local/cuda is fine. In Windows, CUDA_PATH - is normally already set after installing the CUDA toolkit. If not, + the default value of /usr/local/cuda is fine. In Windows, usually CUDA_PATH + is already set after installing the CUDA toolkit. If not, set this variable with: \code setx CUDA_PATH C:\path\to\cuda \endcode -This normally completes the installation. Windows useres must close +This normally completes the installation. Windows users must close and reopen their command window to ensure variables set using `SETX` are initialised. @@ -106,9 +103,9 @@ 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 wish to +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. - + ----- \link Installation Top\endlink | \link Quickstart Next\endlink diff --git a/doxygen/02_Quickstart.dox b/doxygen/02_Quickstart.dox index 6a5e7f569e..45d332c243 100644 --- a/doxygen/02_Quickstart.dox +++ b/doxygen/02_Quickstart.dox @@ -14,20 +14,20 @@ //---------------------------------------------------------------------------- /*! \page Quickstart Quickstart -GeNN is based on the idea of code generation for the involved GPU or -CPU simulation code for neuronal network models but leaves a lot of -freedom how to use the generated code in the final -application. To facilitate the use of GeNN on the background of this +GeNN is based on the idea of code generation for the code that simulates neuronal network models, +either on GPU or CPU. At the same time, it leaves a lot of freedom to users, +how to use the generated code in their final applications. +To facilitate the use of GeNN on the background of this philosophy, it comes with a number of complete examples containing both the model description code that is used by GeNN for code generation -and the "user side code" to run the generated model and safe the -results. Some of the example models such as the \ref ex_mbody use an `generate_run` executable which automates the building and simulation of the model. -Using these executables, running these complete examples should be achievable in a few minutes. +and the "user side code" to run the generated model as well as save the +results. Some of the example models, such as the \ref ex_mbody, uses a `generate_run` executable which automates the building and simulation of the model. +Using these executables, running the complete examples should be achievable in a few minutes. The necessary steps are described below. \section example Running an Example Model \subsection unix_quick Unix -In order to build the `generate_run` executable as well as any additional tools required for the model, open a +In order to build the `generate_run` executable as well as other additional tools required for the model, open a shell and navigate to the `userproject/MBody1_project` directory. Then type \code @@ -60,11 +60,11 @@ generate_run --cpu-only test1 \endcode \subsection quick_visualising Visualising results -These steps will build and simulate a model of the locust olfactory system with default parameters of 100 projection neurons, +These steps build and simulate a model of the locust olfactory system with default parameters of 100 projection neurons, 1000 Kenyon cells, 20 lateral horn interneurons and 100 output neurons in the mushroom body lobes. \note If the model isn't build in CPU_ONLY mode it will be simulated on an automatically chosen GPU. -The generate_run tool generates input patterns and writes them to file, compiles and runs the model using these files as inputs and finally output the +The generate_run executable generates input patterns and writes them to a file, compiles and runs the model using these files as inputs and finally output the resulting spiking activity. For more information of the options passed to this command see the \ref ex_mbody section. The results of the simulation can be plotted with \code diff --git a/userproject/MBody1_project/README.txt b/userproject/MBody1_project/README.txt index 19519f0c1d..1d29dc8b6d 100644 --- a/userproject/MBody1_project/README.txt +++ b/userproject/MBody1_project/README.txt @@ -2,6 +2,107 @@ Locust olfactory system (Nowotny et al. 2005) ============================================= +This project implements the insect olfaction model by Nowotny et al. that demonstrates +self-organized clustering of odours in a simulation of the insect antennal lobe and +mushroom body. As provided, the model works with conductance based Hodgkin-Huxley neurons +and several different synapse types, conductance based (but pulse-coupled) excitatory +synapses, graded inhibitory synapses and synapses with a simplified STDP rule. +This example project contains a helper executable called "generate_run", which +prepares input pattern data, before compiling and executing the model. + +To compile it, navigate to genn/userproject/MBody1_project and type: + +msbuild ..\userprojects.sln /t:generate_mbody1_runner /p:Configuration=Release + +for Windows users, or: + +make + +for Linux, Mac and other UNIX users. + + +USAGE +----- + +generate_run [OPTIONS] + +Mandatory arguments: +outname: The base name of the output location and output files + +Optional arguments: +--debug: Builds a debug version of the simulation and attaches the debugger +--cpu-only: Uses CPU rather than CUDA backend for GeNN +--timing: Uses GeNN's timing mechanism to measure performance and displays it at the end of the simulation +--ftype: Sets the floating point precision of the model to either float or double (defaults to float) +--gpu-device: Sets which GPU device to use for the simulation (defaults to -1 which picks automatically) +--num-al: Number of neurons in the antennal lobe (AL), the input neurons to this model (defaults to 100) +--num-kc: Number of Kenyon cells (KC) in the "hidden layer" (defaults to 1000) +--num-lhi: Number of lateral horn interneurons, implementing gain control (defaults to 20) +--num-dn: Number of decision neurons (DN) in the output layer (defaults to 100) +--gscale: A general rescaling factor for synaptic strength (defaults to 0.0025) +--bitmask: Use bitmasks to represent sparse PN->KC connectivity rather than dense connectivity +--delayed-synapses: Rather than use constant delays of DT throughough, use delays of (5 * DT) ms on KC->DN and +of (3 * DT) ms on DN->DN synapse populations + +An example invocation of generate_run using these defaults and recording results with a base name of `test' would be: + +generate_run.exe test + +for Windows users, or: + +./generate_run test + +for Linux, Mac and other UNIX users. + +Such a command would generate a locust olfaction model with 100 antennal lobe neurons, +1000 mushroom body Kenyon cells, 20 lateral horn interneurons and 100 mushroom body +output neurons, and launch a simulation of it on a CUDA-enabled GPU using single +precision floating point numbers. All output files will be prefixed with "test" +and will be created under the "test" directory. The model that is run is defined +in `model/MBody1.cc`, debugging is switched off and the model would be simulated using +float (single precision floating point) variables. + +In more details, what generate_run program does is: +a) use other tools to generate input patterns. + +b) build the source code for the model by writing neuron numbers into + ./model/sizes.h, and executing "genn-buildmodel.sh ./model/MBody1.cc. + +c) compile the generated code by invoking "make clean && make" + running the code, e.g. "./classol_sim r1". + +Another example of an invocation that runs the simulation using CPU rather than GPU, +records timing information and uses bitmask connectivity would be: + +generate_run.exe --cpu-only --timing --bitmask test + +for Windows users, or: + +./generate_run --cpu-only --timing --bitmask test + +for Linux, Mac and other UNIX users. + +As provided, the model outputs `test.dn.st', `test.kc.st', `test.lhi.st' and `test.pn.st' files +which contain the spiking activity observed in each population in the simulation. There are two +columns in this ASCII file, the first one containing the time of a spike and the second one, +the ID of the neuron that spiked. MATLAB users can use the scripts in the `matlab` directory to plot +the results of a simulation and Python users can use the plot_spikes.py script in userproject/python. +For more about the model itself and the scientific insights gained from it, see Nowotny et al. referenced below. + + +MODEL INFORMATION +----------------- + +For information regarding the locust olfaction model implemented in this example project, see: + +T. Nowotny, R. Huerta, H. D. I. Abarbanel, and M. I. Rabinovich Self-organization in the +olfactory system: One shot odor recognition in insects, Biol Cyber, 93 (6): 436-446 (2005), +doi:10.1007/s00422-005-0019-7 +======= + +Locust olfactory system (Nowotny et al. 2005) +============================================= + This project implements the insect olfaction model by Nowotny et al. that demonstrates self-organized clustering of odours in a simulation of the insect antennal lobe and mushroom body. As provided @@ -99,4 +200,4 @@ For information regarding the locust olfaction model implemented in this example T. Nowotny, R. Huerta, H. D. I. Abarbanel, and M. I. Rabinovich Self-organization in the olfactory system: One shot odor recognition in insects, Biol Cyber, 93 (6): 436-446 (2005), -doi:10.1007/s00422-005-0019-7 +doi:10.1007/s00422-005-0019-7 \ No newline at end of file diff --git a/userproject/Model_Schmuker_2014_classifier_project/README.txt b/userproject/Model_Schmuker_2014_classifier_project/README.txt index 40b22988f3..ce0f4cf8fa 100644 --- a/userproject/Model_Schmuker_2014_classifier_project/README.txt +++ b/userproject/Model_Schmuker_2014_classifier_project/README.txt @@ -1,66 +1,62 @@ -Author: Alan Diamond, University of Sussex, 2014 +A neuromorphic network for generic multivariate data classification +=================================================================== -This project recreates using GeNN the spiking classifier design used in the paper +This project recreates the spiking classifier proposed in the paper by +Michael Schmuker, Thomas Pfeil and Martin Paul Nawrota using GeNN. The classifier design is based on an +abstraction of the insect olfactory system. This example uses the IRIS standard data set +as a test for the classifier. -"A neuromorphic network for generic multivariate data classification" - Authors: Michael Schmuker, Thomas Pfeil, Martin Paul Nawrota - -The classifier design is based on an abstraction of the insect olfactory system. -This example uses the IRIS stadard data set as a test for the classifier +To build the model using the GENN meta compiler, navigate to genn/userproject/Model_Schmuker_2014_project and type: -BUILD / RUN INSTRUCTIONS - -Install GeNN from the internet released build, following instruction on setting your PATH etc - -Start a terminal session - -cd to this project directory (userproject/Model_Schmuker_2014_project) +genn-buildmodel.bat Model_Schmuker_2014_classifier.cc -To build the model using the GENN meta compiler type: +for Windows users (add -d for a debug build), or: genn-buildmodel.sh Model_Schmuker_2014_classifier.cc -for Linux, Mac and other UNIX systems, or: +for Linux, Mac and other UNIX users. -genn-buildmodel.bat Model_Schmuker_2014_classifier.cc +You would only have to do this at the start, or when you change your actual network model, +i.e. on editing the file, Model_Schmuker_2014_classifier.cc -for Windows systems (add -d for a debug build). +Then to compile the experiment and the GeNN created C/CUDA code type: -You should only have to do this at the start, or when you change your actual network model (i.e. editing the file Model_Schmuker_2014_classifier.cc ) +msbuild Schmuker2014_classifier.vcxproj /p:Configuration=Release -Then to compile the experiment plus the GeNN created C/CUDA code type:- +for Windows users (change Release to Debug if using debug mode), or: make -for Linux, Mac and other UNIX users (add DEBUG=1 if using debug mode), or: +for Linux, Mac and other UNIX users (add DEBUG=1 if using debug mode). -msbuild Schmuker2014_classifier.vcxproj /p:Configuration=Release - -for Windows users (change Release to Debug if using debug mode). +Once it compiles you should be able to run the classifier against the included Iris dataset by typing: -Once it compiles you should be able to run the classifier against the included Iris dataset. +Schmuker2014_classifier . -type +for Windows users, or: ./experiment . -for Linux, Mac and other UNIX systems, or: - -Schmuker2014_classifier . - -for Windows systems. +for Linux, Mac and other UNIX systems. -This is how it works roughly. -The experiment (experiment.cu) controls the experiment at a high level. It mostly does this by instructing the classifier (Schmuker2014_classifier.cu) which does the grunt work. +This is how it works roughly. The experiment (experiment.cu) controls the experiment at a high level. +It mostly does this by instructing the classifier (Schmuker2014_classifier.cu) which does the grunt work. -So the experiment first tells the classifier to set up the GPU with the model and synapse data. +So the experiment first tells the classifier to set up the GPU with the model and the synapse data. Then it chooses the training and test set data. -It runs through the training set , with plasticity ON , telling the classifier to run with the specfied observation and collecting the classifier decision. +It runs through the training set with plasticity ON, telling the classifier to run with the specfied +observation and collecting the classifier decisions. -Then it runs through the test set with plasticity OFF and collects the results in various reporting files. +Then it runs through the test set with plasticity OFF and collects the results in various reporting files. -At the highest level it also has a loop where you can cycle through a list of parameter values e.g. some threshold value for the classifier to use. It will then report on the performance for each value. You should be aware that some parameter changes won't actually affect the classifier unless you invoke a re-initialisation of some sort. E.g. anything to do with VRs will require the input data cache to be reset between values, anything to do with non-plastic synapse weights won't get cleared down until you upload a changed set to the GPU etc. +At the highest level, it also has a loop where you can cycle through a list of parameter values e.g. some +threshold value for the classifier to use. It will then report on the performance for each value. +You should be aware that some parameter changes won't actually affect the classifier unless you invoke +a re-initialisation of some sort. E.g. anything to do with VRs will require the input data cache to be +reset between values, anything to do with non-plastic synapse weights won't get cleared down until you +upload a changed set to the GPU etc. -You should also note there is no option currently to run on CPU, this is not due to the demanding task, it just hasn't been tweaked yet to allow for this (small change). +You should also note there is no option currently to run on CPU, this is not due to the demanding task, but +just hasn't been tweaked yet to allow for this (a small change).