This is an old revision of the document!
Table of Contents
Auryn is a set of lightweight classes combined with some examples of how to use them. The power of the framework derives from its speed and extensibility if you do not hesitate to write a few lines of C++ code.
Building Blocks
Auryn was written to simulate networks of spiking neurons. To facilitate the process of building your own network simulation, Auryn handles neurons in populations and synaptic connections between them. For instance, if you were to create a balanced network model you do not have to create individual neurons, but you would create two populations: one for the excitatory neurons and for the inhibitory neurons. You would then connect them using Connection objects that operate on those populations. This allows to specify network models in a relatively compact notation (see for example Vogels COBA network).
Simulation program
Each Auryn simulation is a fully qualified C++ program. However, to qualify as an Auryn simulation it must initialize instances of two specific Auryn classes. These classes must be made accessible through the following three global pointers declared in auryn_global.h:
System * sys; Logger * logger;
sys provides the basic scaffolding which holds together and manages an Auryn simulation. NeuronGroups and Connection instances register to the System class, the System class takes care of syncing spikes between nodes in parallel simulations, and simulations are run by calling sys→run( ). logger provides a basic logging interface. In most cases the initialization of sys and logger can be copied and pasted.
Neurons and populations
Objects exchanging spikes such as neurons are simulated as groups in Auryn (in most cases you won't use Auryn to simulate one neuron in isolation, but many of them). Managing neurons in groups makes allows efficient simulation through vectorization, but it also makes it easier to declare and connect a simulation, because these groups can best be thought of as populations of functionally identical (or at least similar) units. A vanilla balanced network can, for instance, be thought of as consisting of a population of excitatory and inhibitory neurons and maybe a third population of Poisson input neurons. In a Auryn simulation this would correspond to distinct neuron groups of a particular type. For instance, Auryn comes with a bunch of standard integrate-and-fire neuron models already implemented. They are all descendants of NeuronGroup. A good general purpose neuron model to start which implements conductance based synapses is for instance IFGroup (or TIFGroup if you don't want a slow NMDA-like conductance) or the AdEx model by Brette and Gerstner (2005). If you are used to delta-current synaptic input you might want to take a look at IafPscDeltaGroup, which was written after the example of a neuron model in NEST with the same name. Finally, in many cases you will ultimately want to write your own neuron model which is straight forward in Auryn (see creating your own NeuronGroup).
Connections and plasticity
In many cases you will want to connect at least some of your populations with random sparse connectivity. To do so you simply instantiate an object of type SparseConnection which does exactly that. SparseConnection comes with a set of tools to directly add Hebbian assemblies or other simple structures into the synaptic weight matrix. However, if you want even more structure SparseConnection can import MatrixMarket files, which conveniently allows you to build complicated connectivity structures in MATLAB or Python and then load them into your simulation.
If you want to simulate plastic synapses simply use a Connection object of type STPDConnection or for instance TripletConnection for triplet STDP (after Pfister and Gerstner). You want short-term plasticity instead, then STPConnection is for you. It implements the Tsodyks-Markram model. You want to define arbitrarily shaped STDP windows and do not care about all-to-all spike interactions? Use PairInteractionConnection. In man cases you will want to write your own plasticity model – have a look at this tutorial which will help you to get started writing_your_own_plasticity_model.
External Input
In most cases you will want to give some external input. Auryn has multiple classes which allow you to give spiking or current input to your neurons in a network. The most simple form of external input comes in the form of a homogeneous population of Poisson neurons which fire at constant rate PoissonGroup. If you want the input population to have a spatial firing rate profile instead use ProfilePoissonGroup. To give Poisson input with temporally varying firing rates use FileModulatedPoissonGroup. The latter will read the firing rates from a time series file (tiser) which you supply in text format. Finally if you want to stimulate your network with time varying Poisson input from multiple sub-populations within the external Poisson neuron population StimulusGroup might be right pick for you. If you want more control just create a ras file in your favourite programming language (e.g. Python) and simply load it into the Auryn simulation from an external file using FileInputGroup. If that's not enough you can write highly specific input groups for different purposes; see for instance AuditoryBeepGroup for an example.
Monitoring and Readout
Per default Auryn does not record any information. To see what is happening in your network, you will have to define Monitor objects. Each Monitor specializes on reading out one specific quantity from a network simulation. For instance, a SpikeMonitor records the spikes generated from one specific SpikingGroup or NeuronGroup. Typically you will at least use one of those. If you would like to know about the membrane voltage of one specific neuron in a NeuronGroup you can use an instance of VoltageMonitor. If you are interested in other internal states of a Neuron (e.g. conductances, etc…), have a look at StateMonitor. Think carefully which information you actually need from your simulation, because recording values slows your simulation down and quickly produces enormous amounts of data.
Auryn was specifically designed to study synaptic plasticity. To see plasticity in action you can monitor single synaptic weights or groups of them using a WeightMonitor object. If you are only interested in let's say the mean weight change in one of the plastic Connection objects your defined (i.e. the mean weight between two neuronal populations in your simulation), you can use WeightStatsMonitor. You will find other Monitor classes in the Auryn src directory (see also the Class index; Monitor classes should be suffixes with Monitor) or you can write your own for your specific needs.
In most cases Auryn Monitor objects will record data to files on disk on perform a minimum of online analysis. This can be cumbersome if you would for instance like to monitor the activity in your network and stop a simulation if the activity explodes or the network falls quiescent. To tackle this problem, Auryn has a specific class which allows minimalistic online monitoring. They are called Checkers.
What's a Checker?
Suppose you are running a simulation of a plastic network, but every now and then the activity in your simulations explodes, because something is wrong with your plasticity parameters. Instead of storing hours and gigabytes of synchronous high frequency spiking from this run you can define a RateChecker with specific firing rate limits of one specific target population in your simulation. If the firing rate goes out of your predefined bounds the Checker will terminate the run. You can define multiple Checkers for different populations and you can write your own Checker with the functionality you need.
Simulator Structure
Most objects in Auryn that have a direct network function can be subdivided into SpikingGroup, Connection and Monitor. These three base classes implement the important interfaces that are called consecutively during the Auryn duty cycle. Instances of their descendants are registered and managed by the System class, an instance of which is global to each Auryn simulation. Similarly global is the the Logger class which takes care of logging output on the console and into log files.
SpikingGroups
Connections
Monitors
IO File Formats
To minimize complicated IO operations Auryn dumps most of its monitor data directly into human readable text files that can be post processes using standard Linux command line software and visualized easily (e.g. with Gnuplot).