Brian Network Framework

Module for easy compartmental implementation of a BRIAN network.

Build parts of a network via subclassing NetworkComponent and NetworkAnalyser for recording and statistical analysis.

Specify a NetworkRunner (subclassing optionally) that handles the execution of your experiment in different subruns. Subruns can be defined as BrianParameter instances in a particular trajectory group. You must add to every parameter’s Annotations the attribute order. This order must be an integer specifying the index or order the subrun should about to be executed in.

The creation and management of a BRIAN network is handled by the NetworkManager (no need for subclassing). Pass your components, analyser and your runner to the manager.

Pass the run_network() function together with a NetworkManager to your main environment function f_run() to start a simulation and parallel parameter exploration. Be aware that in case of a pre-built network, successful parameter exploration requires parallel processing (see NetworkManager).

Quicklinks

These function can directly be called or used by the user.

run_network	Top-level simulation function, pass this together with a NetworkManager to the environment.
NetworkManager.add_parameters	Adds parameters for a network simulation.
NetworkManager.pre_run_network	Starts a network run before the individual run.
NetworkManager.pre_build	Pre-builds network components.

The private functions of the runner and the manager are also listed below to allow fast browsing of the source code.

Functions that can be implemented by a Subclass

These functions can be implemented in the subclasses:

NetworkComponent.build	Builds network objects at the beginning of each individual experimental run.
NetworkComponent.add_to_network	Can add network objects before a specific subrun.
NetworkComponent.remove_from_network	Can remove network objects before a specific subrun.
NetworkComponent.pre_build	Builds network objects before the actual experimental runs.
NetworkAnalyser.analyse	Can perform statistical analysis on a given network.

I would suggest in case one subclasses NetworkRunner to implement its add_parameters() method (inherited from NetworkComponent) in order to add BrianDurationParameter instances to traj.parameters.simulation.durations or traj.parameters.simulation.pre_durations to define the length and order of individual subruns.

For a description of the structure and different phases of an individual simulation run see run_network().

Top-Level run_network Function

pypet.brian.network.run_network(traj, network_manager)

Top-level simulation function, pass this together with a NetworkManager to the environment.

DEPRECATED: Please pass network_manager.run_network to the environment’s f_run function

Parameters:

• traj – Trajectory container
• network_manager –

  NetworkManager instance

  • Creates a BRIAN network.
  • Manages all NetworkComponent instances, all NetworkAnalyser and a single NetworkRunner.

NetworkManager

class pypet.brian.network.NetworkManager(network_runner, component_list, analyser_list=(), force_single_core=False, network_constructor=None)

Manages a BRIAN network experiment and creates the network.

An experiment consists of

Parameters:

• network_runner –

  A NetworkRunner

  Special component that handles the execution of several subruns. A NetworkRunner can be subclassed to implement the add_parameters() method to add BrianParameter instances defining the order and duration of subruns.

• component_list –

  List of NetworkComponents instances to create and manage individual parts of a network. They are build and added to the network in the order defined in the list.

  NetworkComponent always needs to be sublcassed and defines only an abstract interface. For instance, one could create her or his own subclass called NeuronGroupComponent that creates NeuronGroups, Whereas a SynapseComponent creates Synapses between the before built NeuronGroups. Accordingly, the SynapseComponent instance is listed after the NeuronGroupComponent.

• analyser_list – List of Analyser instances for recording and statistical evaluation of a BRIAN network. They should be used to add monitors to a network and to do further processing of the monitor data.

This division allows to create compartmental network models where one can easily replace parts of a network simulation.

Parameters:

• force_single_core –

  In case you pre_build() or even pre_run() a network, you usually cannot use single core processing. The problem with single core processing is that iterative exploration of the parameter space alters the network on every iteration and the network cannot be reset to the initial conditions holding before the very first experimental run. This is an inherent problem of BRIAN. The only way to overcome this problem is multiprocessing and copying (either by pickling or by forking) the whole BRIAN environment.

  If you are not bothered by not starting every experimental run with the very same network, you can set force_single_core=True. The NetworkManager will do iterative single processing and ignore the ongoing modification of the network throughout all runs.

  In case multiproc=True for your environment, the setting of force_single_core is irrelevant and has no effect.

• network_constructor – If you have a custom network constructor apart from the Brian one, pass it here.

_run_network(traj)

Starts a single run carried out by a NetworkRunner.

Called from the public function run_network().

Parameters:traj – Trajectory container

add_parameters(traj)

Adds parameters for a network simulation.

Calls add_parameters() for all components, analyser, and the network runner (in this order).

Parameters:traj – Trajectory container

build(traj)

Pre-builds network components.

Calls build() for all components, analysers and the network runner.

build does not need to be called by the user. If ~pypet.brian.network.run_network is passed to an Environment with this Network manager, build is automatically called for each individual experimental run.

Parameters:traj – Trajectory container

pre_build(traj)

Pre-builds network components.

Calls pre_build() for all components, analysers, and the network runner.

pre_build is not automatically called but either needs to be executed manually by the user, either calling it directly or by using pre_run().

This function does not create a BRIAN network, but only it’s components.

Parameters:traj – Trajectory container

pre_run_network(traj)

Starts a network run before the individual run.

Useful if a network needs an initial run that can be shared by all individual experimental runs during parameter exploration.

Needs to be called by the user. If pre_run_network is started by the user, pre_build() will be automatically called from this function.

This function will create a new BRIAN network which is run by the NetworkRunner and it’s execute_network_pre_run().

To see how a network run is structured also take a look at run_network().

Parameters:traj – Trajectory container

run_network(traj)

Top-level simulation function, pass this to the environment

Performs an individual network run during parameter exploration.

run_network does not need to be called by the user. If the top-level ~pypet.brian.network.run_network method (not this one of the NetworkManager) is passed to an Environment with this NetworkManager, run_network and build() are automatically called for each individual experimental run.

This function will create a new BRIAN network in case one was not pre-run. The execution of the network run is carried out by the NetworkRunner and it’s execute_network_run() (also take a look at this function’s documentation to see the structure of a network run).

Parameters:traj – Trajectory container

NetworkRunner

class pypet.brian.network.NetworkRunner(report='text', report_period=None, durations_group_name='simulation.durations', pre_durations_group_name='simulation.pre_durations')

Specific NetworkComponent to carry out the running of a BRIAN network experiment.

A NetworRunner only handles the execution of a network simulation, the BRIAN network is created by a NetworkManager.

Can potentially be subclassed to allow the adding of parameters via add_parameters(). These parameters should specify an experimental run with a :class:~pypet.brian.parameter.BrianParameter` to define the order and duration of network subruns. For the actual experimental runs, all subruns must be stored in a particular trajectory group. By default this traj.parameters.simulation.durations. For a pre-run the default is traj.parameters.simulation.pre_durations. These default group names can be changed at runner initialisation (see below).

The network runner will look in the v_annotations property of each parameter in the specified trajectory group. It searches for the entry order to determine the order of subruns.

Parameters:

• report –

  How simulation progress should be reported, see also the parameters of run(...) in a BRIAN network and the magic run method.

• report_period – How often progress is reported. If not specified 10 seconds is chosen.
• durations_group_name – Name where to look for BrianParameter instances in the trajectory which specify the order and durations of subruns.
• pre_durations_group_name – As above, but for pre running a network.

Moreover, in your subclass you can log messages with the private attribute _logger which is initialised in _set_logger().

_execute_network_run(traj, network, network_dict, component_list, analyser_list, pre_run=False)

Generic execute_network_run function, handles experimental runs as well as pre-runs.

See also execute_network_run() and

execute_network_pre_run().

_extract_subruns(traj, pre_run=False)

Extracts subruns from the trajectory.

Parameters:

• traj – Trajectory container
• pre_run – Boolean whether current run is regular or a pre-run

Raises:

RuntimeError if orders are duplicates or even missing

execute_network_pre_run(traj, network, network_dict, component_list, analyser_list)

Runs a network before the actual experiment.

Called by a NetworkManager. Similar to run_network().

Subruns and their durations are extracted from the trajectory. All BrianParameter instances found under traj.parameters.simulation.pre_durations (default, you can change the name of the group where to search for durations at runner initialisation). The order is determined from the v_annotations.order attributes. There must be at least one subrun in the trajectory, otherwise an AttributeError is thrown. If two subruns equal in their order property a RuntimeError is thrown.

Parameters:

• traj – Trajectory container
• network –

  BRIAN network

• network_dict – Dictionary of items shared among all components
• component_list – List of NetworkComponent objects
• analyser_list – List of NetworkAnalyser objects

execute_network_run(traj, network, network_dict, component_list, analyser_list)

Runs a network in an experimental run.

Called by a NetworkManager.

A network run is divided into several subruns which are defined as BrianParameter instances.

These subruns are extracted from the trajectory. All BrianParameter instances found under traj.parameters.simulation.durations (default, you can change the name of the group where to search for durations at runner initialisation). The order is determined from the v_annotations.order attributes. An error is thrown if no orders attribute can be found or if two parameters have the same order.

There must be at least one subrun in the trajectory, otherwise an AttributeError is thrown. If two subruns equal in their order property a RuntimeError is thrown.

For every subrun the following steps are executed:

1. Calling add_to_network() for every every NetworkComponent in the order as they were passed to the NetworkManager.
2. Calling add_to_network() for every every NetworkAnalyser in the order as they were passed to the NetworkManager.
3. Calling add_to_network() of the NetworkRunner itself (usually the network runner should not add or remove anything from the network, but this step is executed for completeness).
4. Running the BRIAN network for the duration of the current subrun by calling the network’s run function.
5. Calling analyse() for every every NetworkAnalyser in the order as they were passed to the NetworkManager.
6. Calling remove_from_network() of the NetworkRunner itself (usually the network runner should not add or remove anything from the network, but this step is executed for completeness).
7. Calling remove_from_network() for every every NetworkAnalyser in the order as they were passed to the NetworkManager
8. Calling remove_from_network() for every every NetworkComponent in the order as they were passed to the NetworkManager.

These 8 steps are repeated for every subrun in the subrun_list. The subrun_list passed to all add_to_network, analyse and remove_from_network methods can be modified within these functions to potentially alter the order of execution or even erase or add upcoming subruns if necessary.

For example, a NetworkAnalyser checks for epileptic pathological activity and cancels all coming subruns in case of undesired network dynamics.

Parameters:

• traj – Trajectory container
• network – BRIAN network
• network_dict – Dictionary of items shared among all components
• component_list – List of NetworkComponent objects
• analyser_list – List of NetworkAnalyser objects

NetworkComponent

class pypet.brian.network.NetworkComponent

Abstract class to define a component of a BRIAN network.

Can be subclassed to define the construction of NeuronGroups or Connections, for instance.

add_parameters(traj)

Adds parameters to traj.

Function called from the NetworkManager to define and add parameters to the trajectory container.

add_to_network(traj, network, current_subrun, subrun_list, network_dict)

Can add network objects before a specific subrun.

Called by a NetworkRunner before a the given subrun.

Potentially one wants to add some BRIAN objects later to the network than at the very beginning of an experimental run. For example, a monitor might be added at the second subrun after an initial phase that is not supposed to be recorded.

Parameters:

• traj – Trajectoy container
• network –

  BRIAN network where elements could be added via add(...).

• current_subrun – BrianParameter specifying the very next subrun to be simulated.
• subrun_list – List of BrianParameter objects that are to be run after the current subrun.
• network_dict – Dictionary of items shared by all components.

build(traj, brian_list, network_dict)

Builds network objects at the beginning of each individual experimental run.

Function called from the NetworkManager at the beginning of every experimental run,

Parameters:

• traj – Trajectory container
• brian_list –

  Add BRIAN network objects like NeuronGroups or Connections to this list. These objects will be automatically added at the instantiation of the network in case the network was not pre-run via Network(*brian_list) (see the BRIAN network class).

• network_dict – Add any item to this dictionary that should be shared or accessed by all your components and which are not part of the trajectory container. It is recommended to also put all items from the brian_list into the dictionary for completeness.

For convenience I recommend documenting the implementation of build and pre-build and so on in the subclass like the following. Use statements like Adds for items that are added to the list and the dict and statements like Expects for what is needed to be part of the network_dict in order to build the current component.

brian_list:

Adds:

4 Connections, between all types of neurons (e->e, e->i, i->e, i->i)

network_dict:

Expects:

‘neurons_i’: Inhibitory neuron group

‘neurons_e’: Excitatory neuron group

Adds:

‘connections’: List of 4 Connections,

between all types of neurons (e->e, e->i, i->e, i->i)

pre_build(traj, brian_list, network_dict)

Builds network objects before the actual experimental runs.

Function called from the NetworkManager if components can be built before the actual experimental runs or in case the network is pre-run.

Parameters are the same as for the build() method.

remove_from_network(traj, network, current_subrun, subrun_list, network_dict)

Can remove network objects before a specific subrun.

Called by a NetworkRunner after a given subrun and shortly after analysis (see NetworkAnalyser).

Parameters:

• traj – Trajectoy container
• network –

  BRIAN network where elements could be removed via remove(...).

• current_subrun – BrianParameter specifying the current subrun that was executed shortly before.
• subrun_list – List of BrianParameter objects that are to be run after the current subrun.
• network_dict – Dictionary of items shared by all components.

NetworkAnalyser

class pypet.brian.network.NetworkAnalyser

Specific NetworkComponent that analysis a network experiment.

Can be subclassed to create components for statistical analysis of a network and network monitors.

analyse(traj, network, current_subrun, subrun_list, network_dict)

Can perform statistical analysis on a given network.

Called by a NetworkRunner directly after a given subrun.

Parameters:

• traj – Trajectoy container
• network –

  BRIAN network

• current_subrun – BrianParameter specifying the current subrun that was executed shortly before.
• subrun_list – List of BrianParameter objects that are to be run after the current subrun. Can be deleted or added to change the actual course of the experiment.
• network_dict – Dictionary of items shared by all components.