3.1. Module ANNarchy

This the main module of ANNarchy, which contains both Python Code and wrapping of the C++ library.

3.1.1. Configuration and compilation

Contrary to other simulators, ANNarchy is entirely based on code generation. It provides a set of first level functions to ensure the network is correctly created. It is important to call these functions in the right order. ANNarchy.setup()

Before using any other function or classes of ANNarchy4 the user must call the setup() method in order to define global parameters.


The setup function is used to configure ANNarchy simulation environment. It takes various optional arguments:

  • dt – simulation step size (default: 1.0 ms).
  • paradigm – parallel framework for code generation. Accepted values: “openmp” or “cuda” (default: “openmp”).
  • method – default method to numerize ODEs. Default is the explicit forward Euler method (‘explicit’).
  • precision – default floating precision for variables in ANNarchy. Accepted values: “float” or “double” (default: “double”)
  • num_threads – number of treads used by openMP (overrides the environment variable OMP_NUM_THREADS when set, default = None).
  • structural_plasticity – allows synapses to be dynamically added/removed during the simulation (default: False).
  • seed – the seed (integer) to be used in the random number generators (default = -1 is equivalent to time(NULL)).

The following parameters are mainly for debugging and profiling, and should be ignored by most users:

  • verbose – shows details about compilation process on console (by default False). Additional some information of the network construction will be shown.
  • suppress_warnings – if True, warnings (e. g. from the mathematical parser) are suppressed.
  • show_time – if True, initialization times are shown. Attention: verbose should be set to True additionally.


This function should be used before any other functions of ANNarchy (including importing a network definition), right after from ANNarchy import *:

from ANNarchy import *
setup(dt=1.0, method='midpoint', num_threads=2)
... ANNarchy.compile()

The goal of this function is to generate all needed classes, compile all C++ sources and Cython wrappers needed to represent the network.

ANNarchy.compile(directory='annarchy', clean=False, populations=None, projections=None, compiler='default', compiler_flags='default', cuda_config={'device': 0}, annarchy_json='', silent=False, debug_build=False, profile_enabled=False, net_id=0)[source]

This method uses the network architecture to generate optimized C++ code and compile a shared library that will perform the simulation.


  • directory: name of the subdirectory where the code will be generated and compiled. Must be a relative path. Default: “annarchy/”.
  • clean: boolean to specifying if the library should be recompiled entirely or only the changes since last compilation (default: False).
  • populations: list of populations which should be compiled. If set to None, all available populations will be used.
  • projections: list of projection which should be compiled. If set to None, all available projections will be used.
  • compiler: C++ compiler to use. Default: g++ on GNU/Linux, clang++ on OS X. Valid compilers are [g++, clang++].
  • compiler_flags: platform-specific flags to pass to the compiler. Default: “-march=native -O2”. Warning: -O3 often generates slower code and can cause linking problems, so it is not recommended.
  • cuda_config: dictionary defining the CUDA configuration for each population and projection.
  • annarchy_json: compiler flags etc can be stored in a .json file normally placed in the home directory (see comment below). With this flag one can directly assign a file location.
  • silent: defines if the “Compiling… OK” should be printed.

The compiler, compiler_flags and part of cuda_config take their default value from the configuration file ~/.config/ANNarchy/annarchy.json.

The following arguments are for internal development use only:

  • debug_build: creates a debug version of ANNarchy, which logs the creation of objects and some other data (default: False).
  • profile_enabled: creates a profilable version of ANNarchy, which logs several computation timings (default: False). ANNarchy.clear()


Clears all variables (erasing already defined populations, projections, monitors and constants), as if you had just imported ANNarchy.

Useful when re-running Jupyter/IPython notebooks multiple times:

from ANNarchy import *

3.1.2. Simulation

Different methods are available to run the simulation:

ANNarchy.simulate(duration, measure_time=False, progress_bar=False, callbacks=True, net_id=0)[source]

Simulates the network for the given duration in milliseconds. The number of simulation steps is computed relative to the discretization step dt declared in setup() (default: 1ms):

  • duration – the duration in milliseconds.
  • measure_time – defines whether the simulation time should be printed. Default: False.
  • progress_bar – defines whether a progress bar should be printed. Default: False
  • callbacks – defines if the callback method (decorator every should be called). Default: True.
ANNarchy.simulate_until(max_duration, population, operator='and', measure_time=False, net_id=0)[source]

Runs the network for the maximal duration in milliseconds. If the stop_condition defined in the population becomes true during the simulation, it is stopped.

One can specify several populations. If the stop condition is true for any of the populations, the simulation will stop (‘or’ function).


pop1 = Population( ..., stop_condition = "r > 1.0 : any")
simulate_until(max_duration=1000.0. population=pop1)
  • duration – the maximum duration of the simulation in milliseconds.
  • population – the (list of) population whose stop_condition should be checked to stop the simulation.
  • operator – operator to be used (‘and’ or ‘or’) when multiple populations are provided (default: ‘and’).
  • measure_time – defines whether the simulation time should be printed (default=False).

the actual duration of the simulation in milliseconds.


Performs a single simulation step (duration = dt).

class ANNarchy.every(period, offset=0.0, wait=0.0, net_id=0)[source]

Decorator to declare a callback method that will be called periodically during the simulation.

Example of setting increasing inputs to a population every 100 ms, with an offset of 90 ms (or -10 ms relative to the period):

@every(period=100., offset=-10.)
def step_input(n):
    pop.I = float(n) / 100.


step_input() will be called at times 90, 190, …, 9990 ms during the call to simulate().

The method must accept only n as parameter (an integer being 0 the first time the method is called, and incremented afterwards) and can not return anything.

The times at which the method is called are relative to the time when simulate() is called (if t is already 150 before calling simulate(), the first call will then be made at t=240 with the previous example).

If multiple callbacks are defined, they will be called in the order of their declaration if they occur at the same time.

  • period – interval in ms between two calls to the function. If less than dt, will be called every step.
  • offset – by default, the first call to the method will be made at the start of the simulation. The offset delays the call within the period (default: 0.0). Can be negative, in which case it will be counted from the end of the period.
  • wait – allows to wait for a certain amount of time (in ms) before starting to call the method.

wait can be combined with offset, so if period=100., offset=50. and wait=500., the first call will be made 550 ms after the call to simulate()


Enables all declared callbacks for the network.


Disables all callbacks for the network.


Clears the list of declared callbacks for the network.

Cannot be undone!

3.1.3. Reset the network

If you want to run multiple experiments with the same network, or if your experiment setup requires a pre learning phase, you can reset selectively neural or synaptic variables to their initial values.

ANNarchy.reset(populations=True, projections=False, synapses=False, net_id=0)[source]

Reinitialises the network to its state before the call to compile. The network time will be set to 0ms.

  • populations – if True (default), the neural parameters and variables will be reset to their initial value.
  • projections – if True, the synaptic parameters and variables (except the connections) will be reset (default=False).
  • synapses – if True, the synaptic weights will be erased and recreated (default=False).

3.1.4. Access to populations

ANNarchy.get_population(name, net_id=0)[source]

Returns the population with the given name.

Parameters:name – name of the population.
Returns:The requested Population object if existing, None otherwise.
ANNarchy.get_projection(name, net_id=0)[source]

Returns the projection with the given name.

Parameters:name – name of the projection.
Returns:The requested Projection object if existing, None otherwise.

3.1.5. Functions


Defines a global function which can be used by all neurons and synapses.

The function must have only one return value and use only the passed arguments.

Examples of valid functions:

logistic(x) = 1 / (1 + exp(-x))

piecewise(x, a, b) =    if x < a:
                            if x > b :

Please refer to the manual to know the allowed mathematical functions.

ANNarchy.functions(name, net_id=0)[source]

Allows to access a global function defined with add_function and use it from Python using arrays after compilation.

The name of the function is not added to the global namespace to avoid overloading.

add_function("logistic(x) = 1. / (1. + exp(-x))") 


result = functions('logistic')([0., 1., 2., 3., 4.])

Only lists or 1D Numpy arrays can be passed as arguments, not single values nor multidimensional arrays.

When passing several arguments, make sure they have the same size.

3.1.6. Constants

class ANNarchy.Constant(name, value, net_id=0)[source]

Constant parameter that can be used by all neurons and synapses.

  • name – name of the constant (unique), which can be used in equations.
  • value – the value of the constant, which must be a float, or a combination of Constants.

The class Constant derives from float, so any legal operation on floats (addition, multiplication) can be used.

If a Neuron/Synapse defines a parameter with the same name, the constant parameters will not be visible.


tau = Constant('tau', 20)
factor = Constant('factor', 0.1)
real_tau = Constant('real_tau', tau*factor)

neuron = Neuron(
        real_tau*dr/dt + r =1.0

The value of the constant can be changed anytime with the set() method. Assignments will have no effect (e.g. tau = 10.0 only creates a new float).

The value of constants defined as combination of other constants (real_tau) is not updated if the value of these constants changes (changing tau with tau.set(10.0) will not modify the value of real_tau).

3.1.7. Learning

ANNarchy.enable_learning(projections=None, period=None, offset=None, net_id=0)[source]

Enables learning for all projections. Optionally period and offset can be changed for all projections.

  • projections – the projections whose learning should be enabled. By default, all the existing projections are enabled.
  • period – determines how often the synaptic variables will be updated.
  • offset – determines the offset at which the synaptic variables will be updated relative to the current time.
ANNarchy.disable_learning(projections=None, net_id=0)[source]

Disables learning for all projections.

Parameters:projections – the projections whose learning should be disabled. By default, all the existing projections are disabled.

3.1.8. Access to simulation times


Returns the current time in ms.

ANNarchy.set_time(t, net_id=0)[source]

Sets the current time in ms.


Can be dangerous for some spiking models.


Returns the current simulation step.

ANNarchy.set_current_step(t, net_id=0)[source]

Sets the current simulation step (integer).


Can be dangerous for some spiking models.


Returns the simulation step size dt used in the simulation.