Auryn simulator

Simulator for spiking neural networks with synaptic plasticity

User Tools

Site Tools

Trace:
manual:start

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Next revisionBoth sides next revision
manual:start [2016/02/17 20:40] – [Runtime Exceptions] zenkemanual:start [2016/12/01 17:12] – [IO File Formats] zenke
Line 1: Line 1:
-======= Manual =======+====== Compiling the library ======
  
-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. +To get started you need to download and compile Auryn. See [[:quick start]] or [[CompileAuryn]] for instructions.
  
  
-===== Quick start =====+====== Building Blocks ======
  
-First, install cmake, git and some additional packages. Under Ubuntu or Debian simply  +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 [[examples:sim_coba_benchmark#the_important_bits|Vogels COBA network]]).
-<code>sudo apt-get install cmake git build-essential libboost-all-dev</code> +
-now download and compile Auryn with the following commands +
-<code> +
-git clone https://github.com/fzenke/auryn.git && cd auryn +
-mkdir build && cd build +
-cmake ../ -DCMAKE_BUILD_TYPE=Release && make +
-</code> +
-This will checkout the ''master'' branch and compile it in the subdirectory ''auryn/build/''. At this point cmake will complain about any missing [[required libraries|libraries]]. For more detailed instructions on where to download and how to compile go to [[manual:compileAuryn|howto compile Auryn]].+
  
-Now, let's run a first small Auryn simulation: +===== Simulation program =====
-<code> +
-cd examples +
-./sim_poisson +
-</code> +
-This will only take a few milliseconds and generate a bunch of Poisson spikes. If you have gnuplot installed (sudo apt-get install gnuplot) you can visualize them from the command line with +
-<code> +
-echo "plot 'poisson.0.ras' with dots lc rgb 'black'" | gnuplot -p +
-</code> +
-{{ :examples:poisson_output.png?300 |}} +
-For more details on this example go [[examples:sim_poisson|here]].  +
-===== Further steps =====+
  
-After you have [[manual:compileAuryn|compiled Auryn]], you will probably want to familiarize yourself with the simulator first using the supplied [[examples:start|examples]] provided under ''examples''. As a next step you might want to actually change things in these examples to learn how to use the simulator. To learn how to do that you can read [[compileAndRunAurynSimulations|here]].+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'':
  
-**Running in parallel with MPI.** +    System * sys; 
-Auryn natively compiles against MPI and most of the time you will want to use in parallel to get good performance. Parallel execution is relatively simple. See [[parallel_execution|how it's done]].+    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 [[examples::start|copied and pasted]].
-====== Building Blocks of Auryn simulations ====== +
- +
-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 [[examples:sim_coba_benchmark#the_important_bits|Vogels COBA network]]).+
  
 ===== Neurons and populations ===== ===== Neurons and populations =====
  
-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 [[AdExGroup|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 [[tutorials::neurongroup|creating your own NeuronGroup]]).+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.  
 +{{:manual:network_sketch1.png?150 |}} 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 [[NeuronGroup|neuron groups]] of a particular type for the excitatory and the inhibitory populations respectively. External Poisson neurons would be modeled as a third group and so forth. Each NeuronGroup is represented as a C++ object and synaptic connections are then defined between these objects (see below). 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 [[AdExGroup|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 [[tutorials::neurongroup|creating your own NeuronGroup]]).
  
  
Line 48: Line 27:
 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. 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 [[tutorials:writing_your_own_plasticity_model]].+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 most cases you will want to write your own plasticity model -- have a look at this tutorial which will help you to get started [[tutorials:writing_your_own_plasticity_model]].
  
 ===== External Input ===== ===== External Input =====
Line 62: Line 41:
 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 [[http://www.fzenke.net/auryn/doxygen/current/annotated.html|Class index]]; Monitor classes should be suffixes with ''Monitor'') or you can write your own for your specific needs.  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 [[http://www.fzenke.net/auryn/doxygen/current/annotated.html|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 [[Checker|Checkers]].+In most cases Auryn [[Monitor]] instances will individually record data to separate files on disk and perform a minimum of on-line analysis (here are some [[extensions|default extensions]] I am using for these output files). 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 [[Checker|Checkers]].
  
 ==== What's a Checker? ==== ==== What's a Checker? ====
Line 72: Line 51:
 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 [[manual:System]] class, an instance of which is global to each Auryn [[simulation]]. Similarly global is the the [[manual:Logger]] class which takes care of logging output on the console and into log files. 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 [[manual:System]] class, an instance of which is global to each Auryn [[simulation]]. Similarly global is the the [[manual:Logger]] class which takes care of logging output on the console and into log files.
  
 +The most complete description of available classes and how to use them you will find in the doxygen generated class library. However, below are some entries for commonly used simulation components (which might, in some cases, not be too up to date any more)
 ===== SpikingGroups ===== ===== SpikingGroups =====
  
Line 83: Line 63:
     * [[manual:IF2Group]]     * [[manual:IF2Group]]
     * [[manual:AdExGroup]]     * [[manual:AdExGroup]]
 +    * [[manual:IzhikevichGroup]]
     * [[manual:AIFGroup]]     * [[manual:AIFGroup]]
     * [[manual:AIF2Group]]     * [[manual:AIF2Group]]
Line 103: Line 84:
   * [[manual:WeightMonitor]]   * [[manual:WeightMonitor]]
  
-===== IO File Formats ===== +Most monitor instances write their output to an individual file. Many file formats are human readable, while others are binary. See [[IO File Formats]] for a more complete overview of typical 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). +
- +
-  * [[manual:ras]] files +
-  * [[manual:bras]] files +
-  * [[manual:wmat]] files +
-  * [[manual:mem]] and other 1d time series files (such as ampa, gaba, nmda) +
-  * [[manual:syn]] file +
-  * [[manual:prate]] file and [[manual:pact]] file +
-  * [[manual:pat]] files +
-  * [[manual:stim]] stim files+
  
  
manual/start.txt · Last modified: 2018/02/07 08:58 by zenke