Repository files navigation

Doryta (not an acronym) is a spiking neural network (SNN) simulator written in C using the(massively) parallelizableROSS library for Parallel Discrete Event Simulation (PDES).

Doryta requires CMake and a C compiler with support forMPI. To download and compilein as little steps, run the instructions below. (In order to keep Doryta as lean aspossible, all example models are stored in a separate git submodule repo. That's why theslightly longer and complicated sequence of commands.)

git clone --recurse-submodules https://github.com/helq/doryta --depth=1mkdir doryta/build&&cd doryta/buildcmake .. -DBUILD_TESTING=OFFmake -j4

After compiling, you will find the executable under the folder:doryta/build/src

Optionally, you can runmake install to copy doryta to the folder where binaries arestored in your computer (/usr/bin for example). If you wish to change the defaultdirectory, for example todoryta/build/bin instead of/usr/bin, run cmake with theflag-DCMAKE_INSTALL_PREFIX="$(pwd -P)/".

To check whether doryta has been compiled properly, run the following:

mpirun -np 2 src/doryta --sync=3 --five-example --probe-firing --probe-voltage --end=1

This will run a five-neuron fully connected network, on top of which a fully connectedlayer of two neurons is layered. The input to the network is a fixed set of spikes, andthe parameters of the network are always the same, so that the execution of the networkmust always produce the same output.

The output of running the model can be found atoutput/. The small Python scriptplot_neuron_spikes_voltage.py undertools/general can be used to analyze the behaviourof neurons and their spikes.

Multiple network models for MNIST can be found underdata/models/whetstone. Whetstone isa library for training SNNs using the Keras backend. The code to generate the model can befound underdata/models/whetstone/code. The testing MNIST dataset has been spikified inorder to be readable for Doryta (which only understands spikes as an input).

To inference the class of the first 20 images in the dataset, run the following command:

mpirun -np 2 src/doryta --spike-driven --synch=3 --extramem=1000000 \    --load-model=../data/models/mnist/snn-models/ffsnn-mnist.doryta.bin \    --load-spikes=../data/models/mnist/spikes/spikified-mnist/spikified-images-all.bin \    --output-dir=fully-20 \    --probe-firing --probe-firing-output-only --probe-firing-buffer=100000 --end=19.5

The output will be stored under the pathfully-20. The scripttools/whetstone-mnist/check_doryta_inference.py checks this output with the expectedoutput from whetstone.

A step of game of life can be simulated using two layers of convolutional neural networks.Luckily the translation into Spiking NNs is straightforward, and, even more, the output ofthe network can be fed back to the input layer, which means that doryta can simulate thegame of life out of the box. To run a built-in example of GoL, run the followingcommand:

src/doryta --gol-model --load-spikes=../data/models/gol-spikes/20x20/gol-blinker.bin --probe-firing --spike-driven --end=10.5# orsrc/doryta --gol-model --load-spikes=../data/models/gol-spikes/20x20/gol-glider.bin --probe-firing --spike-driven --end=40.5

To visualize the simulation use the scripttools/gol/show_state.py.

Doryta comes with two modes of execution: needy and spike-driven. InNeedy mode, Dorytawill update the state of each neuron every delta time just as any other ordinarysimulation framework. Inspike-driven mode, Doryta will only update the state of theneuron when it receives a spike, and it's, thus, much faster thanneedy. The mainassumption forspike-driven to behave asneedy is that there must NEVER be positiveleak on the system, ie, neurons cannot spike on their own if there don't have a inputstimulous (spike).

The MNIST example (above) uses thespike-driven mode, which runs faster than theneedymode, but it doesn't compute the step by step change on voltage. This means that we cannotanalyze the voltage behaviour of neurons. If you want to analyze the voltage change,remove the--spike-driven flag, activate the voltage probe (--probe-voltage) andassign enough buffer space (--probe-voltage-buffer) to store voltage for all neurons onthe determined time step.

Note on custom models: There might be some discrepancies when running a model on thespike-driven mode opposed to needy mode. To reduce such discrepancies, we recommend tomake the heartbeat interval (the delta of the approximation) small enough. By the verynature of simulation, breaking a continuous equation into discrete steps, there willalways be a tradeoff between computation time and fidelity.

To get the clean, non-debug, faster implementation use:

cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

To run tests you have to compile them first and then run ctest:

cmake .. -DBUILD_TESTING=ONmake -j4ctest -j4

Remember to run CMake again whenever a new test is added. CMake generates the rules tocompile the tests and run them. Unfortunatelly, CMake is not triggered when newtests/folders are added to thetest folder.