Brian2 Documentation

The code generation system is organized into several key modules:

• brian2.codegen: The core code generation logic.
• brian2.codegen.generators: Snippet generation, including CodeGenerator classes and default function implementations.
• brian2.codegen.runtime: Templates, compilation, and running of code, including CodeObject and runtime-specific functions.
• brian2.parsing: General tools for parsing expressions.
• brian2.parsing.rendering: AST tools for rendering Python expressions into other languages.
• brian2.core.functions & brian2.core.variables: Definitions of variable values and core functions.

By default, refractoriness only prevents threshold crossings from triggering new spikes. All differential equations continue to update normally.

To stop specific state variables from updating during the refractory period, append the (unless refractory) flag to the variable declaration in the model string. Variables marked this way are 'clamped' (held constant) during refractoriness. Additionally, variables in a refractory neuron are treated as read-only; incoming synaptic inputs will not affect their values until the refractory period ends.

# 'v' is clamped during refractoriness, but 'w' continues to update
G = NeuronGroup(N, '''dv/dt = -(v + w)/ tau_v : 1 (unless refractory)
                      dw/dt = -w / tau_w : 1''', 
                threshold='v > 1', reset='v=0; w+=0.1', refractory=2*ms)

A TimedArray acts as a function of time where values are explicitly defined at specific time points. This is useful for non-continuous or block-based stimulation.

• 1D Array: Returns the same value for all neurons at a given time.
• 2D Array: The first dimension is time, and the second dimension is the neuron/synapse index. This allows for different values (e.g., shared noise) per neuron.

Semantics Note: For TimedArray([x1, x2, ...], dt=my_dt), the value x1 is returned for 0 <= t < my_dt, x2 for my_dt <= t < 2*my_dt, etc.

# Example: 2D TimedArray for shared noise between even/odd neurons
runtime = 1*second
stimulus = TimedArray(np.random.rand(int(runtime/defaultclock.dt), 2), 
                      dt=defaultclock.dt)
G = NeuronGroup(100, 'dv/dt = (-v + stimulus(t, i % 2))/(10*ms) : 1', 
                threshold='v>1', reset='v=0')

Brian2 loads preferences from a hierarchy of files. Each subsequent level overrides the values from the previous level. If a file is missing, no error is raised.

1. Global defaults: Stored in the installation directory.
2. User defaults: Stored in ~/.brian/preferences (works on Windows and Linux).
3. Local preferences: The file brian_preferences located in the current working directory.

A shared variable is a variable that has a common value for all neurons in a group. This is useful for modeling external stimuli that change over time.

• Declaration: Use the (shared) flag in the model description.
• Restrictions: Shared variables cannot be written to in contexts that apply to only a subset of neurons (like reset statements). If mixing shared and vector writes, shared statements must come first.
• Subexpressions: By default, subexpressions are re-evaluated. Use the (constant over dt) flag for subexpressions that should only be evaluated once per time step (e.g., when using rand()).

G = NeuronGroup(10, '''shared_input : volt (shared)
                       dv/dt = (-v + shared_input)/tau : volt
                       tau : second''', name='neurons')

# Setting the shared value
G.shared_input = '(4.0/N)*mV'

Brian2 supports stochastic differential equations using the term xi. This represents Gaussian noise with mean 0 and standard deviation 1, scaling with units of 1/sqrt(second).

Note: If you use noise in multiple equations within the same NeuronGroup or Synapses, you must use suffixed names to distinguish them.

# Example: Ornstein-Uhlenbeck process for a leaky integrate-and-fire neuron
G = NeuronGroup(10, 'dv/dt = -v/tau + sigma*sqrt(2/tau)*xi : volt')

Brian offers two primary modes for running simulations, balancing flexibility and speed:

1. Runtime mode (Default): The simulation loop runs in Python, but the heavy numerical work (integration, propagation) is compiled into a target language. This mode allows you to combine Brian's computations with arbitrary Python code using NetworkOperation.
2. Standalone C++ mode: The entire simulation is compiled to C++. This is generally much faster for many simulation types but is less flexible and cannot be used for all simulations.

To enable Standalone C++ mode, call set_device('cpp_standalone') after importing Brian but before defining your simulation code.

from brian2 import *
set_device('cpp_standalone')

# ... rest of your simulation code

Brian 2 uses Jinja2 templates to transform code snippets into runnable blocks. Templates come in two forms:

1. Single Template: Used when code generation only requires a single block of code.
2. Macro Templates: Define multiple Jinja macros, where each macro represents a separate code block.

A CodeObject specifies which template to use and which macros to define. Runtime templates can be found in the brian2/codegen/runtime directory.