File	Date	Author	Commit
SpineML_to_GeNN	2014-07-04	Esin Yavuz	[103798] Sparse connectivity should also be supported no...
brianInterface	2014-06-05	Esin Yavuz	[038e6d] Fixed generateKernels.cc for small networks wit...
doxygen	2014-08-04	Esin Yavuz	[75f559] Updated the documentation. Minor fix in classol...
lib	2014-08-12	Thomas Nowotny	[a08ebc] switched block size debugging off.
tools	2014-08-12	Thomas Nowotny	[afff48] adjusted synapse level in generate_run.
userproject	2014-08-12	Thomas Nowotny	[896e80] merged a few remaining changes from the default...
www	2014-01-10	Esin Yavuz	[c47ae5] Sparse connectivity is possible now. Numerical ...
README	2014-08-08	Esin Yavuz	[4db2b0] Fixed the CPU code for Poisson neuron time-step...
makedoc	2014-01-22	Esin Yavuz	[45a20a] Post-synaptic mechanisms made flexible, using a...
publishdoc	2013-06-28	Thomas Nowotny	[0d4d53] added the script for publishing the documentati...

Read Me

WARNING: CYGWIN SUPPORT IS AN EXPERIMENTAL FEATURE AND MAY NOT WORK AS INTENDED

INSTALLATION OF GeNN:

(i) Unpack GeNN.zip in a convenient location.

(ii) Define the environment variable "GeNNPATH" to point to the main GeNN 
     directory, e.g. if you extracted GeNN to /usr/local/GeNN, then you can add
     "export GeNNPATH=/usr/local/GeNN" to your login script. If you are using CYGWIN,
     the path should be a windows path or a mixed path (i.e. with normal slashes
     instead of backslashes) as it will be interpreted by cl.

(iii) Add $GeNNPATH/lib/bin to your PATH variable, e.g.
      "export PATH=$PATH:$GeNNPATH/lib/bin". Under CYGWIN, it is safer to enter full 
      linux path (such as: export PATH=$PATH:/usr/local/GeNN/lib/bin) 

(iv) Get a fresh installation of the Nvidia cuda toolkit from
     https://developer.nvidia.com/cuda-downloads

(v) Set the CUDA_PATH variable in $GeNNPATH/lib/include/makefile_common.mk to
    the location of your Nvidia cuda toolkit installation, if it is not already
    set by the system.
    For most people, the default value of /usr/local/cuda is fine.

(vi) Modify Makefile examples under $GeNNPATH/lib/src/ and $GeNNPATH/userproject/
     to add extra linker-, include- and compiler-flags on a per-project basis, or
     modify global default flags in $GeNNPATH/lib/include/makefile_common.mk.

This completes the installation.

If you are using GeNN under CYGWIN with cl, you have to source vscvsrs.bat script under Visual Studio directory first.
Note that the debugging option is not available under CYGWIN.

------

HOW TO USE GeNN: 

In order to get a quick start and run one of the the provided example models, go to GeNN/tools

type "make".

At the moment, there are 5 example projects provided with GeNN.

1: Locust olfactory system example (Nowotny et al. 2005):
For a first complete test, the system is best used with a full driver program such as
 
tools/generate_run [CPU/GPU] [nAL] [nKC] [nLH] [nDN] [gscale] [DIR] [EXE] [MODEL] [DEBUG OFF/ON]. 

To use it, navigate to the "userproject/MBody1_project" directory and type
"../../tools/generate_run 1 100 1000 20 100 0.00117 outname classol_sim MBody1 0" 
which would generate a model of the locust olfactory system. 
The tool generate_run will generate connectivity files for the model
MBody1, compile and run it on the GPU, with 100 antennal lobe neurons, 1000 mushroom body Kenyon cells, 
20 lateral horn interneurons and 100 mushroom body output neurons. All output files 
will be prefixed with "outname" and will be created under the "outname" directory.

In more details, what generate_run program does is: 
a) use some other tools to generate the appropriate connectivity
matrices and store them in files.

b) build the source code for the model by writing neuron numbers into
userproject/include/sizes.h, and executing "buildmodel MBody1 [DEBUG OFF/ON]".  

c) compile the generated code by invoking "make clean && make" 
running the code, e.g. "linux/release/classol_sim r1 1".

This is already a quite highly integrated example. If one was to use
the library for GPU code generation only, the following would be done:

a) The model in question is defined in a file, say "Model1.cc".  

b) this file needs to 
  (i) define "DT" 
  (ii) include "modelSpec.h" and "modelSpec.cc"
  (iii) contains the model's definition in the form of a function 
  "void modelDefinition(NNmodel &model)" 
  ("MBody1.cc") shows a typical example)

c) The programmer defines his/her own modeling code along similar lines as
"map_classol.*" together with "classol_sim.*". In this code, 

- she defines the connectivity matrices between neuron groups. (In the
example here those are read from files).  

- she defines input patterns (e.g. for Poisson neurons like in the
example) 

- she uses "stepTimeGPU(x, y, z);" to run one time step on the GPU or
"stepTimeCPU(x, y, z);" to run one on the CPU. (both versions are
always compiled). However, mixing the two does not make too much
sense. The host version uses the same memory whereto results from the
GPU version are copied (see next point) 

- she uses functions like "copyStateFromDevice();" etc to obtain
results from GPU calculations.

- the simulation code is then produced in two steps:
"buildmodel Model1 [DEBUG OFF/ON]" and
"make clean && make"

2: Izhikevich network receiving Poisson input spike trains:

Can be used as:
tools/generate_run_PoissonIzh [CPU/GPU] [nPoisson] [nIzhikevich] [pConn] [gscale] [DIR] [EXE] [MODEL] [DEBUG OFF/ON]

Navigate to the "userproject/PoissonIzh_project" directory and type
"../../tools/generate_run_PoissonIzh 1 100 10 0.5 2 Outdir PoissonIzh_sim PoissonIzh 0"

This will generate a network of 100 Poisson neurons connected to 10 Izhikevich neurons with a 0.4 probability. The same network 
with sparse connectivity can be used by addind the synapse population with sparse connectivity in PoissonIzh.cc and by
uncommenting the lines following the "//SPARSE CONNECTIVITY" tag in PoissonIzh.cu.

3: Single compartment Izhikevich neuron(s)

For a first minimal test, the system may be used with 

tools/generate_run_1comp [CPU/GPU] [n] [nKC] [DIR] [EXE] [MODEL] [DEBUG OFF/ON].

This would create a set of tonic spiking Izhikevich neurons with no connectivity, 
receiving a constant identical 4 nA input. 
To use it, navigate to the "userproject/OneComp_project" directory and type
"../../tools/generate_run_1comp 1 1 Outdir OneComp_sim OneComp 0".

4: Pulse-coupled Izhikevich network

Can be used as: 
tools/generate_run_1comp generate_izhikevich_network_bm [CPU/GPU] [nNeurons] [nConn] [gscale] [outdir] [executable name] [model name] [debug OFF/ON] [use previous connectivity OFF/ON]


This example creates a pulse-coupled network with 80% excitatory 20% inhibitory connections, each connecting to nConn neurons with sparse connectivity.

To use an example, navigate to the "userproject/Izh_sparse_project" directory and type
"../../tools/generate_izhikevich_network_run 1 10000 1000 1 Outdir Izh_sim_sparse Izh_sparse 0 0"

5:Izhikevich network with delayed synapses

This example project demonstrates the delayed synapse feature of GeNN. It creates
a network of three Izhikevich neuron groups, connected all-to-all with fast, medium
and slow synapse groups. Neurons in the output group only spike if they are
simultaneously innervated by the input neurons, via slow synapses, and the
interneurons, via faster synapses. 

To run this example project, cd to "$GeNNPATH/userproject/SynDelay_project" and type
"buildmodel SynDelay && make clean && make && ./bin/release/syn_delay 1 output"

DEBUGGING
The last argument to generate_run or similar files enables the debugging flags while compiling 
generateAll.cc under lib/src/ and *.cu under individual user project directory, 
and will run the corresponding executables with cuda-gdb consecutively. 
If you want to skip one of these debugging steps, simply press r while on the debugging screen.
 
-----

For more about the complete example model provided by generate_run 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