High-level API of PyNEST Topology Module

This file defines the user-level functions of NEST’s Python interface to the Topology module. The basic approach is the same as for the PyNEST interface to NEST:

  1. Function names are the same as in SLI.

  2. Nodes are identified by their GIDs.

  3. GIDs are always given as tuples or lists of integer(s).

  4. Commands returning GIDs return them as tuples.

  5. Other arguments can be

    • single items that are applied to all entries in a GID list
    • a list of the same length as the given list of GID(s) where each item is matched with the pertaining GID.
    Example
    layers = CreateLayer(({...}, {...}, {...}))
    creates three layers and returns a tuple of three GIDs.
    ConnectLayers(layers[:2], layers[1:], {...})
    connects layers[0] to layers[1] and layers[1] to layers[2] using the same dictionary to specify both connections.
    ConnectLayers(layers[:2], layers[1:], ({...}, {...}))

    connects the same layers, but the layers[0] to layers[1] connection is specified by the first dictionary, the layers[1] to layers[2] connection by the second.

Authors:Kittel Austvoll, Hans Ekkehard Plesser, Hakon Enger
hl_api.ConnectLayers(pre, post, projections)

Pairwise connect of pre- and postsynaptic (lists of) layers.

pre and post must be a tuple/list of GIDs of equal length. The GIDs must refer to layers created with CreateLayers. Layers in the pre and post lists are connected pairwise.

  • If projections is a single dictionary, it applies to all pre-post pairs.
  • If projections is a tuple/list of dictionaries, it must have the same length as pre and post and each dictionary is matched with the proper pre-post pair.

A minimal call of ConnectLayers expects a source layer pre, a target layer post and a connection dictionary projections containing at least the entry ‘connection_type’ (either ‘convergent’ or ‘divergent’).

When connecting two layers, the driver layer is the one in which each node is considered in turn. The pool layer is the one from which nodes are chosen for each node in the driver layer.

pre : tuple/list of int(s)
List of GIDs of presynaptic layers (sources)
post : tuple/list of int(s)
List of GIDs of postsynaptic layers (targets)
projections : (tuple/list of) dict(s)
Dictionary or list of dictionaries specifying projection properties
out : None
ConnectLayers returns None

CreateLayer : Create one or more Topology layer(s). CreateMask : Create a Mask object. Documentation on available spatial

masks. Masks can be used to specify the key ‘mask’ of the connection dictionary.
CreateParameter : Create a Parameter object. Documentation on available
parameters for distance dependency and randomization. Parameters can be used to specify the parameters ‘kernel’, ‘weights’ and ‘delays’ of the connection dictionary.

nest.GetConnections : Retrieve connections.

Available keys for the layer-specifying dictionary projections allow_autapses : bool, optional, default: True

An autapse is a synapse (connection) from a node onto itself. It is used together with the ‘number_of_connections’ option.
allow_multapses : bool, optional, default: True
Node A is connected to node B by a multapse if there are synapses (connections) from A to B. It is used together with the ‘number_of_connections’ option.
connection_type : str
The type of connections can be either ‘convergent’ or ‘divergent’. In case of convergent connections, the target layer is considered as driver layer and the source layer as pool layer - and vice versa for divergent connections.
delays : [float | dict | Parameter object], optional, default: 1.0
Delays can be constant, randomized or distance-dependent according to a provided function. Information on available functions can be found in the documentation on the function CreateParameter.
kernel : [float | dict | Parameter object], optional, default: 1.0
A kernel is a function mapping the distance (or displacement) between a driver and a pool node to a connection probability. The default kernel is 1.0, i.e., connections are created with certainty. Information on available functions can be found in the documentation on the function CreateParameter.
mask : [dict | Mask object], optional
The mask defines which pool nodes are considered as potential targets for each driver node. Parameters of the different available masks in 2 and 3 dimensions are also defined in dictionaries. If no mask is specified, all neurons from the pool layer are possible targets for each driver node. Information on available masks can be found in the documentation on the function CreateMask.
number_of_connections : int, optional
Prescribed number of connections for each driver node. The actual connections being created are picked at random from all the candidate connections.
synapse_model : str, optional
The default synapse model in NEST is used if not specified otherwise.
weights : [float | dict | Parameter object], optional, default: 1.0
Weights can be constant, randomized or distance-dependent according to a provided function. Information on available functions can be found in the documentation on the function CreateParameter.
  • In the case of free probabilistic connections (in contrast to prescribing the number of connections), each possible driver-pool pair is inspected exactly once so that there will be at most one connection between each driver-pool pair.
  • Periodic boundary conditions are always applied in the pool layer. It is irrelevant whether the driver layer has periodic boundary conditions or not.
  • By default, Topology does not accept masks that are wider than the pool layer when using periodic boundary conditions. Kernel, weight and delay functions always consider the shortest distance (displacement) between driver and pool node.
Example
import nest.topology as tp

# create a layer
l = tp.CreateLayer({'rows'      : 11,
                    'columns'   : 11,
                    'extent'    : [11.0, 11.0],
                    'elements'  : 'iaf_psc_alpha'})

# connectivity specifications with a mask
conndict1 = {'connection_type': 'divergent',
             'mask': {'rectangular': {'lower_left'  : [-2.0, -1.0],
                                      'upper_right' : [2.0, 1.0]}}}

# connect layer l with itself according to the given
# specifications
tp.ConnectLayers(l, l, conndict1)


# connection dictionary with distance-dependent kernel
# (given as Parameter object) and randomized weights
# (given as a dictionary)
gauss_kernel = tp.CreateParameter('gaussian', {'p_center' : 1.0,
                                               'sigma'    : 1.0})
conndict2 = {'connection_type': 'divergent',
             'mask': {'circular': {'radius': 2.0}},
             'kernel': gauss_kernel,
             'weights': {'uniform': {'min': 0.2, 'max': 0.8}}}
hl_api.CreateLayer(specs)

Create one ore more Topology layer(s) according to given specifications.

The Topology module organizes neuronal networks in layers. A layer is a special type of subnet which contains information about the spatial position of its nodes (simple or composite elements) in 2 or 3 dimensions.

If specs is a dictionary, a single layer is created. If it is a list of dictionaries, one layer is created for each dictionary.

Topology distinguishes between two classes of layers:

  • grid-based layers in which each element is placed at a location in a regular grid
  • free layers in which elements can be placed arbitrarily

Obligatory dictionary entries define the class of layer (grid-based layers: ‘columns’ and ‘rows’; free layers: ‘positions’) and the ‘elements’.

specs : (tuple/list of) dict(s)
Dictionary or list of dictionaries with layer specifications, see Notes.
out : tuple of int(s)
GID(s) of created layer(s)
ConnectLayers: Connect two (lists of) layers which were created with
CreateLayer pairwise according to specified projections.

Available parameters for the layer-specifying dictionary specs center : tuple/list of floats, optional, default: (0.0, 0.0)

Layers are centered about the origin by default, but the center coordinates can also be changed. ‘center’ has length 2 or 3 dependent on the number of dimensions.
columns : int, obligatory for grid-based layers
Number of columns. Needs ‘rows’; mutually exclusive with ‘positions’.
edge_wrap : bool, default: False
Periodic boundary conditions.
elements : (tuple/list of) str or str followed by int
Elements of layers are NEST network nodes such as neuron models or devices. For network elements with several nodes of the same type, the number of nodes to be created must follow the model name. For composite elements, a collection of nodes can be passed as list or tuple.
extent : tuple of floats, optional, default in 2D: (1.0, 1.0)
Size of the layer. It has length 2 or 3 dependent on the number of dimensions.
positions : tuple/list of coordinates (lists/tuples of floats),
obligatory for free layers Explicit specification of the positions of all elements. The coordinates have a length 2 or 3 dependent on the number of dimensions. All element positions must be within the layer’s extent. Mutually exclusive with ‘rows’ and ‘columns’.
rows : int, obligatory for grid-based layers
Number of rows. Needs ‘columns’; mutually exclusive with ‘positions’.
Example
import nest
import nest.topology as tp

# grid-based layer
gl = tp.CreateLayer({'rows'      : 5,
                     'columns'   : 5,
                     'elements'  : 'iaf_psc_alpha'})

# free layer
import numpy as np
pos = [[np.random.uniform(-0.5, 0.5), np.random.uniform(-0.5,0.5)]
        for i in range(50)]
fl = tp.CreateLayer({'positions' : pos,
                     'elements'  : 'iaf_psc_alpha'})

# extent, center and edge_wrap
el = tp.CreateLayer({'rows'      : 5,
                     'columns'   : 5,
                     'extent'    : [2.0, 3.0],
                     'center'    : [1.0, 1.5],
                     'edge_wrap' : True,
                     'elements'  : 'iaf_psc_alpha'})

# composite layer with several nodes of the same type
cl = tp.CreateLayer({'rows'      : 1,
                     'columns'   : 2,
                     'elements'  : ['iaf_cond_alpha', 10,
                                   'poisson_generator',
                                   'noise_generator', 2]})

# investigate the status dictionary of a layer
nest.GetStatus(gl)[0]['topology']
hl_api.CreateMask(masktype, specs, anchor=None)

Create a spatial mask for connections.

Masks are used when creating connections in the Topology module. A mask describes the area of the pool layer that is searched for nodes to connect for any given node in the driver layer. Several mask types are available. Examples are the grid region, the rectangular, circular or doughnut region.

The command CreateMask creates a Mask object which may be combined with other Mask objects using Boolean operators. The mask is specified in a dictionary.

Mask objects can be passed to ConnectLayers in a connection dictionary with the key ‘mask’.

masktype : str, [‘rectangular’ | ‘circular’ | ‘doughnut’] for 2D masks, [‘box’ | ‘spherical’] for 3D masks, [‘grid’] only for grid-based layers in 2D
The mask name corresponds to the geometrical shape of the mask. There are different types for 2- and 3-dimensional layers.
specs : dict
Dictionary specifying the parameters of the provided masktype, see Notes.
anchor : [tuple/list of floats | dict with the keys ‘column’ and ‘row’ (for grid masks only)], optional, default: None
By providing anchor coordinates, the location of the mask relative to the driver node can be changed. The list of coordinates has a length of 2 or 3 dependent on the number of dimensions.

out : Mask object

ConnectLayers: Connect two (lists of) layers pairwise according to
specified projections. Mask objects can be passed in a connection dictionary with the key ‘mask’.

Mask types

Available mask types (masktype) and their corresponding parameter dictionaries:

  • 2D free and grid-based layers
    'rectangular' :
    {'lower_left' : [float, float],
     'upper_right': [float, float]}
#or
'circular' :
    {'radius' : float}
#or
'doughnut' :
    {'inner_radius' : float,
     'outer_radius' : float}
  • 3D free and grid-based layers
    'box' :
    {'lower_left' : [float, float, float],
     'upper_right' : [float, float, float]}
#or
'spherical' :
    {'radius' : float}
  • 2D grid-based layers only
    'grid' :
    {'rows' : float,
     'columns' : float}

    By default the top-left corner of a grid mask, i.e., the grid mask element with grid index [0, 0], is aligned with the driver node. It can be changed by means of the ‘anchor’ parameter:

    'anchor' :
    {'row' : float,
     'column' : float}
Example
import nest.topology as tp

# create a grid-based layer
l = tp.CreateLayer({'rows'      : 5,
                    'columns'   : 5,
                    'elements'  : 'iaf_psc_alpha'})

# create a circular mask
m = tp.CreateMask('circular', {'radius': 0.2})

# connectivity specifications
conndict = {'connection_type': 'divergent',
            'mask'           : m}

# connect layer l with itself according to the specifications
tp.ConnectLayers(l, l, conndict)
hl_api.CreateParameter(parametertype, specs)

Create a parameter for distance dependency or randomization.

Parameters are (spatial) functions which are used when creating connections in the Topology module for distance dependency or randomization. This command creates a Parameter object which may be combined with other Parameter objects using arithmetic operators. The parameter is specified in a dictionary.

A parameter may be used as a probability kernel when creating connections or as synaptic parameters (such as weight and delay), i.e., for specifying the parameters ‘kernel’, ‘weights’ and ‘delays’ in the connection dictionary passed to ConnectLayers.

parametertype : {‘constant’, ‘linear’, ‘exponential’, ‘gaussian’, ‘gaussian2D’, ‘uniform’, ‘normal’, ‘lognormal’}
Function types with or without distance dependency
specs : dict
Dictionary specifying the parameters of the provided ‘parametertype’, see Notes.

out : Parameter object

ConnectLayers : Connect two (lists of) layers pairwise according to
specified projections. Parameters can be used to specify the parameters ‘kernel’, ‘weights’ and ‘delays’ in the connection dictionary.

Parameters : Class for parameters for distance dependency or randomization.

Parameter types

Available parameter types (parametertype parameter), their function and acceptable keys for their corresponding specification dictionaries

  • Constant
    'constant' :
    {'value' : float} # constant value
  • With dependence on the distance d
    # p(d) = c + a * d
'linear' :
    {'a' : float, # slope, default: 1.0
     'c' : float} # constant offset, default: 0.0
# or
# p(d) = c + a*exp(-d/tau)
'exponential' :
    {'a'   : float, # coefficient of exponential term, default: 1.0
     'c'   : float, # constant offset, default: 0.0
     'tau' : float} # length scale factor, default: 1.0
# or
# p(d) = c + p_center*exp(-(d-mean)^2/(2*sigma^2))
'gaussian' :
    {'p_center' : float, # value at center, default: 1.0
     'mean'     : float, # distance to center, default: 0.0
     'sigma'    : float, # width of Gaussian, default: 1.0
     'c'        : float} # constant offset, default: 0.0
  • Bivariate Gaussian parameter:
    # p(x,y) = c + p_center *
#          exp( -( (x-mean_x)^2/sigma_x^2 + (y-mean_y)^2/sigma_y^2
#          + 2*rho*(x-mean_x)*(y-mean_y)/(sigma_x*sigma_y) ) /
#          (2*(1-rho^2)) )
'gaussian2D' :
    {'p_center' : float, # value at center, default: 1.0
     'mean_x'   : float, # x-coordinate of center, default: 0.0
     'mean_y'   : float, # y-coordinate of center, default: 0.0
     'sigma_x'  : float, # width in x-direction, default: 1.0
     'sigma_y'  : float, # width in y-direction, default: 1.0
     'rho'      : float, # correlation of x and y, default: 0.0
     'c'        : float} # constant offset, default: 0.0
  • Without distance dependency, for randomization
    # random parameter with uniform distribution in [min,max)
'uniform' :
    {'min' : float, # minimum value, default: 0.0
     'max' : float} # maximum value, default: 1.0
# or
# random parameter with normal distribution, optionally truncated
# to [min,max)
'normal':
    {'mean' : float, # mean value, default: 0.0
     'sigma': float, # standard deviation, default: 1.0
     'min'  : float, # minimum value, default: -inf

     'max'  : float} # maximum value, default: +inf
# or
# random parameter with lognormal distribution,
# optionally truncated to [min,max)
'lognormal' :
    {'mu'   : float, # mean value of logarithm, default: 0.0
     'sigma': float, # standard deviation of log, default: 1.0
     'min'  : float, # minimum value, default: -inf
     'max'  : float} # maximum value, default: +inf
Example
import nest.topology as tp

# create a grid-based layer
l = tp.CreateLayer({'rows'      : 5,
                    'columns'   : 5,
                    'elements'  : 'iaf_psc_alpha'})

# parameter for delay with linear distance dependency
d = tp.CreateParameter('linear', {'a': 0.2,
                                  'c': 0.2})

# connectivity specifications
conndict = {'connection_type': 'divergent',
            'delays': d}

tp.ConnectLayers(l, l, conndict)
hl_api.Displacement(from_arg, to_arg)

Get vector of lateral displacement from node(s) from_arg to node(s) to_arg.

Displacement is always measured in the layer to which the to_arg node belongs. If a node in the from_arg list belongs to a different layer, its location is projected into the to_arg layer. If explicit positions are given in the from_arg list, they are interpreted in the to_arg layer. Displacement is the shortest displacement, taking into account periodic boundary conditions where applicable.

  • If one of from_arg or to_arg has length 1, and the other is longer, the displacement from/to the single item to all other items is given.
  • If from_arg and to_arg both have more than two elements, they have to be lists of the same length and the displacement for each pair is returned.
from_arg : [tuple/list of int(s) | tuple/list of tuples/lists of floats]
List of GIDs or position(s)
to_arg : tuple/list of int(s)
List of GIDs
out : tuple
Displacement vectors between pairs of nodes in from_arg and to_arg

Distance : Get lateral distances between nodes. DumpLayerConnections : Write connectivity information to file. GetPosition : Return the spatial locations of nodes.

  • The functions GetPosition, Displacement and Distance now only works for nodes local to the current MPI process, if used in a MPI-parallel simulation.
Example
import nest.topology as tp

# create a layer
l = tp.CreateLayer({'rows'      : 5,
                    'columns'   : 5,
                    'elements'  : 'iaf_psc_alpha'})

# displacement between node 2 and 3
print(tp.Displacement([2], [3]))

# displacment between the position (0.0., 0.0) and node 2
print(tp.Displacement([(0.0, 0.0)], [2]))
hl_api.Distance(from_arg, to_arg)

Get lateral distances from node(s) from_arg to node(s) to_arg.

The distance between two nodes is the length of its displacement.

Distance is always measured in the layer to which the to_arg node belongs. If a node in the from_arg list belongs to a different layer, its location is projected into the to_arg layer. If explicit positions are given in the from_arg list, they are interpreted in the to_arg layer. Distance is the shortest distance, taking into account periodic boundary conditions where applicable.

  • If one of from_arg or to_arg has length 1, and the other is longer, the displacement from/to the single item to all other items is given.
  • If from_arg and to_arg both have more than two elements, they have to be lists of the same length and the distance for each pair is returned.
from_arg : [tuple/list of ints | tuple/list with tuples/lists of floats]
List of GIDs or position(s)
to_arg : tuple/list of ints
List of GIDs
out : tuple
Distances between from and to

Displacement : Get vector of lateral displacements between nodes. DumpLayerConnections : Write connectivity information to file. GetPosition : Return the spatial locations of nodes.

  • The functions GetPosition, Displacement and Distance now only works for nodes local to the current MPI process, if used in a MPI-parallel simulation.
Example
import nest.topology as tp

# create a layer
l = tp.CreateLayer({'rows'      : 5,
                    'columns'   : 5,
                    'elements'  : 'iaf_psc_alpha'})

# distance between node 2 and 3
print(tp.Distance([2], [3]))

# distance between the position (0.0., 0.0) and node 2
print(tp.Distance([(0.0, 0.0)], [2]))
hl_api.DumpLayerConnections(layers, synapse_model, outname)

Write connectivity information to file.

This function writes connection information to file for all outgoing connections from the given layers with the given synapse model. Data for all layers in the list is combined.

For each connection, one line is stored, in the following format:
source_gid target_gid weight delay dx dy [dz]

where (dx, dy [, dz]) is the displacement from source to target node. If targets do not have positions (eg spike detectors outside any layer), NaN is written for each displacement coordinate.

layers : tuple/list of int(s)
List of GIDs of a Topology layer
synapse_model : str
NEST synapse model
outname : str
Name of file to write to (will be overwritten if it exists)

out : None

DumpLayerNodes : Write layer node positions to file. GetPosition : Return the spatial locations of nodes. nest.GetConnections : Return connection identifiers between

sources and targets
  • If calling this function from a distributed simulation, this function will write to one file per MPI rank.
  • File names are formed by inserting the MPI Rank into the file name before the file name suffix.
  • Each file stores data for local nodes.
Example
import nest.topology as tp

# create a layer
l = tp.CreateLayer({'rows'      : 5,
                    'columns'   : 5,
                    'elements'  : 'iaf_psc_alpha'})
tp.ConnectLayers(l,l, {'connection_type': 'divergent',
                       'synapse_model': 'static_synapse'})

# write connectivity information to file
tp.DumpLayerConnections(l, 'static_synapse', 'connections.txt')
hl_api.DumpLayerNodes(layers, outname)

Write GID and position data of layer(s) to file.

Write GID and position data to layer(s) file. For each node in a layer, a line with the following information is written:

GID x-position y-position [z-position]

If layers contains several GIDs, data for all layers will be written to a single file.

layers : tuple/list of int(s)
List of GIDs of a Topology layer
outname : str
Name of file to write to (existing files are overwritten)

out : None

DumpLayerConnections : Write connectivity information to file. GetPosition : Return the spatial locations of nodes.

  • If calling this function from a distributed simulation, this function will write to one file per MPI rank.
  • File names are formed by adding the MPI Rank into the file name before the file name suffix.
  • Each file stores data for nodes local to that file.
Example
import nest.topology as tp

# create a layer
l = tp.CreateLayer({'rows'     : 5,
                    'columns'  : 5,
                    'elements' : 'iaf_psc_alpha'})

# write layer node positions to file
tp.DumpLayerNodes(l, 'positions.txt')
hl_api.FindCenterElement(layers)

Return GID(s) of node closest to center of layers.

layers : tuple/list of int(s)
List of layer GIDs
out : tuple of int(s)
A list containing for each layer the GID of the node closest to the center of the layer, as specified in the layer parameters. If several nodes are equally close to the center, an arbitrary one of them is returned.
FindNearestElement : Return the node(s) closest to the location(s) in the
given layer(s).

GetElement : Return the node(s) at the location(s) in the given layer(s). GetPosition : Return the spatial locations of nodes.

Example
import nest.topology as tp

# create a layer
l = tp.CreateLayer({'rows'      : 5,
                    'columns'   : 5,
                    'elements'  : 'iaf_psc_alpha'})

# get GID of the element closest to the center of the layer
tp.FindCenterElement(l)
hl_api.FindNearestElement(layers, locations, find_all=False)

Return the node(s) closest to the location(s) in the given layer(s).

This function works for fixed grid layers only.

  • If layers contains a single GID and locations is a single 2-element array giving a grid location, return a list of GIDs of layer elements at the given location.
  • If layers is a list with a single GID and locations is a list of coordinates, the function returns a list of lists with GIDs of the nodes at all locations.
  • If layers is a list of GIDs and locations single 2-element array giving a grid location, the function returns a list of lists with the GIDs of the nodes in all layers at the given location.
  • If layers and locations are lists, it returns a nested list of GIDs, one list for each layer and each location.
layers : tuple/list of int(s)
List of layer GIDs
locations : tuple(s)/list(s) of tuple(s)/list(s)
2-element list with coordinates of a single position, or list of 2-element list of positions
find_all : bool, default: False
If there are several nodes with same minimal distance, return only the first found, if False. If True, instead of returning a single GID, return a list of GIDs containing all nodes with minimal distance.
out : tuple of int(s)
List of node GIDs

FindCenterElement : Return GID(s) of node closest to center of layers. GetElement : Return the node(s) at the location(s) in the given layer(s). GetPosition : Return the spatial locations of nodes.

Example
import nest.topology as tp

# create a layer
l = tp.CreateLayer({'rows'      : 5,
                    'columns'   : 5,
                    'elements'  : 'iaf_psc_alpha'})

# get GID of element closest to some location
tp.FindNearestElement(l, [3.0, 4.0], True)
hl_api.GetElement(layers, locations)

Return the node(s) at the location(s) in the given layer(s).

This function works for fixed grid layers only.

  • If layers contains a single GID and locations is a single 2-element array giving a grid location, return a list of GIDs of layer elements at the given location.
  • If layers is a list with a single GID and locations is a list of coordinates, the function returns a list of lists with GIDs of the nodes at all locations.
  • If layers is a list of GIDs and locations single 2-element array giving a grid location, the function returns a list of lists with the GIDs of the nodes in all layers at the given location.
  • If layers and locations are lists, it returns a nested list of GIDs, one list for each layer and each location.
layers : tuple/list of int(s)
List of layer GIDs
locations : [tuple/list of floats | tuple/list of tuples/lists of floats]
2-element list with coordinates of a single grid location, or list of 2-element lists of coordinates for 2-dimensional layers, i.e., on the format [column, row]
out : tuple of int(s)
List of GIDs

GetLayer : Return the layer to which nodes belong. FindNearestElement: Return the node(s) closest to the location(s) in the

given layer(s).

GetPosition : Return the spatial locations of nodes.

Example
import nest.topology as tp

# create a layer
l = tp.CreateLayer({'rows'      : 5,
                    'columns'   : 4,
                    'elements'  : 'iaf_psc_alpha'})

# get GID of element in last row and column
tp.GetElement(l, [3, 4])
hl_api.GetLayer(nodes)

Return the layer to which nodes belong.

nodes : tuple/list of int(s)
List of neuron GIDs
out : tuple of int(s)
List of layer GIDs

GetElement : Return the node(s) at the location(s) in the given layer(s). GetPosition : Return the spatial locations of nodes.

Example
import nest.topology as tp

# create a layer
l = tp.CreateLayer({'rows'      : 5,
                    'columns'   : 5,
                    'elements'  : 'iaf_psc_alpha'})

# get layer GID of nodes in layer
tp.GetLayer(nest.GetNodes(l)[0])
hl_api.GetPosition(nodes)

Return the spatial locations of nodes.

nodes : tuple/list of int(s)
List of GIDs
out : tuple of tuple(s)
List of positions as 2- or 3-element lists

Displacement : Get vector of lateral displacement between nodes. Distance : Get lateral distance between nodes. DumpLayerConnections : Write connectivity information to file. DumpLayerNodes : Write layer node positions to file.

  • The functions GetPosition, Displacement and Distance now only works for nodes local to the current MPI process, if used in a MPI-parallel simulation.
Example
import nest
import nest.topology as tp

# create a layer
l = tp.CreateLayer({'rows'      : 5,
                    'columns'   : 5,
                    'elements'  : 'iaf_psc_alpha'})

# retrieve positions of all (local) nodes belonging to the layer
gids = nest.GetNodes(l, {'local_only': True})[0]
tp.GetPosition(gids)
hl_api.GetTargetNodes(sources, tgt_layer, tgt_model=None, syn_model=None)

Obtain targets of a list of sources in given target layer.

sources : tuple/list of int(s)
List of GID(s) of source neurons
tgt_layer : tuple/list of int(s)
Single-element list with GID of tgt_layer
tgt_model : [None | str], optional, default: None
Return only target positions for a given neuron model.
syn_model : [None | str], optional, default: None
Return only target positions for a given synapse model.
out : tuple of list(s) of int(s)

List of GIDs of target neurons fulfilling the given criteria. It is a list of lists, one list per source.

For each neuron in sources, this function finds all target elements in tgt_layer. If tgt_model is not given (default), all targets are returned, otherwise only targets of specific type, and similarly for syn_model.

GetTargetPositions : Obtain positions of targets of a list of sources in a
given target layer.
nest.GetConnections : Return connection identifiers between
sources and targets
  • For distributed simulations, this function only returns targets on the local MPI process.
Example
import nest.topology as tp

# create a layer
l = tp.CreateLayer({'rows'      : 11,
                    'columns'   : 11,
                    'extent'    : [11.0, 11.0],
                    'elements'  : 'iaf_psc_alpha'})

# connectivity specifications with a mask
conndict = {'connection_type': 'divergent',
            'mask': {'rectangular': {'lower_left' : [-2.0, -1.0],
                                     'upper_right': [2.0, 1.0]}}}

# connect layer l with itself according to the given
# specifications
tp.ConnectLayers(l, l, conndict)

# get the GIDs of the targets of the source neuron with GID 5
tp.GetTargetNodes([5], l)
hl_api.GetTargetPositions(sources, tgt_layer, tgt_model=None, syn_model=None)

Obtain positions of targets of a list of sources in a given target layer.

sources : tuple/list of int(s)
List of GID(s) of source neurons
tgt_layer : tuple/list of int(s)
Single-element list with GID of tgt_layer
tgt_model : [None | str], optional, default: None
Return only target positions for a given neuron model.
syn_type : [None | str], optional, default: None
Return only target positions for a given synapse model.
out : tuple of tuple(s) of tuple(s) of floats

Positions of target neurons fulfilling the given criteria as a nested list, containing one list of positions per node in sources.

For each neuron in sources, this function finds all target elements in tgt_layer. If tgt_model is not given (default), all targets are returned, otherwise only targets of specific type, and similarly for syn_model.

GetTargetNodes : Obtain targets of a list of sources in a given target
layer.
  • For distributed simulations, this function only returns targets on the local MPI process.
Example
import nest.topology as tp

# create a layer
l = tp.CreateLayer({'rows'      : 11,
                    'columns'   : 11,
                    'extent'    : [11.0, 11.0],
                    'elements'  : 'iaf_psc_alpha'})

# connectivity specifications with a mask
conndict1 = {'connection_type': 'divergent',
             'mask': {'rectangular': {'lower_left'  : [-2.0, -1.0],
                                      'upper_right' : [2.0, 1.0]}}}

# connect layer l with itself according to the given
# specifications
tp.ConnectLayers(l, l, conndict1)

# get the positions of the targets of the source neuron with GID 5
tp.GetTargetPositions([5], l)
class hl_api.Mask(datum)

Bases: object

Class for spatial masks.

Masks are used when creating connections in the Topology module. A mask describes which area of the pool layer shall be searched for nodes to connect for any given node in the driver layer. Masks are created using the CreateMask command.

Inside(point)

Test if a point is inside a mask.

point : tuple/list of float values
Coordinate of point
out : bool
True if the point is inside the mask, False otherwise
class hl_api.Parameter(datum)

Bases: object

Class for parameters for distance dependency or randomization.

Parameters are spatial functions which are used when creating connections in the Topology module. A parameter may be used as a probability kernel when creating connections or as synaptic parameters (such as weight and delay). Parameters are created using the CreateParameter command.

GetValue(point)

Compute value of parameter at a point.

point : tuple/list of float values
coordinate of point
out : value
The value of the parameter at the point

CreateParameter : create parameter for e.g., distance dependency

Example
import nest.topology as tp

#linear dependent parameter
P = tp.CreateParameter('linear', {'a' : 2., 'c' : 0.})

#get out value
P.GetValue(point=[3., 4.])
hl_api.PlotKernel(ax, src_nrn, mask, kern=None, mask_color='red', kernel_color='red')

Add indication of mask and kernel to axes.

Adds solid red line for mask. For doughnut mask show inner and outer line. If kern is Gaussian, add blue dashed lines marking 1, 2, 3 sigma. This function ignores periodic boundary conditions. Usually, this function is invoked by PlotTargets.

ax : matplotlib.axes.AxesSubplot,
subplot reference returned by PlotTargets
src_nrn : int
GID of source neuron (as single element list), mask and kernel plotted relative to it
mask : dict
Mask used in creating connections.
kern : [None | dict], optional, default: None
Kernel used in creating connections
mask_color : [None | any matplotlib color], optional, default: ‘red’
Color used for line marking mask
kernel_color : [None | any matplotlib color], optional, default: ‘red’
Color used for lines marking kernel

out : None

CreateMask : Create a Mask object. Documentation on available spatial
masks.
CreateParameter : Create a Parameter object. Documentation on available
parameters for distance dependency and randomization.

PlotLayer : Plot all nodes in a layer.

  • Do not use this function in distributed simulations.
Example
import nest.topology as tp
import matplotlib.pyplot as plt

# create a layer
l = tp.CreateLayer({'rows'      : 11,
                    'columns'   : 11,
                    'extent'    : [11.0, 11.0],
                    'elements'  : 'iaf_psc_alpha'})

# connectivity specifications
mask_dict = {'rectangular': {'lower_left'  : [-2.0, -1.0],
                             'upper_right' : [2.0, 1.0]}}
kernel_dict = {'gaussian': {'p_center' : 1.0,
                            'sigma'    : 1.0}}
conndict = {'connection_type': 'divergent',
            'mask'   : mask_dict,
            'kernel' : kernel_dict}

# connect layer l with itself according to the given
# specifications
tp.ConnectLayers(l, l, conndict)

# set up figure
fig, ax = plt.subplots()

# plot layer nodes
tp.PlotLayer(l, fig)

# choose center element of the layer as source node
ctr_elem = tp.FindCenterElement(l)

# plot mask and kernel of the center element
tp.PlotKernel(ax, ctr_elem, mask=mask_dict, kern=kernel_dict)
hl_api.PlotLayer(layer, fig=None, nodecolor='b', nodesize=20)

Plot all nodes in a layer.

This function plots only top-level nodes, not the content of composite nodes.

layer : tuple/list of int(s)
GID of layer to plot, must be tuple/list of length 1
fig : [None | matplotlib.figure.Figure object], optional, default: None
Matplotlib figure to plot to. If not given, a new figure is created.
nodecolor : [None | any matplotlib color], optional, default: ‘b’
Color for nodes
nodesize : float, optional, default: 20
Marker size for nodes

out : matplotlib.figure.Figure object

PlotKernel : Add indication of mask and kernel to axes. PlotTargets : Plot all targets of a given source. matplotlib.figure.Figure : matplotlib Figure class

  • Do not use this function in distributed simulations.
Example
import nest.topology as tp
import matplotlib.pyplot as plt

# create a layer
l = tp.CreateLayer({'rows'      : 11,
                    'columns'   : 11,
                    'extent'    : [11.0, 11.0],
                    'elements'  : 'iaf_psc_alpha'})

# plot layer with all its nodes
tp.PlotLayer(l)
plt.show()
hl_api.PlotTargets(src_nrn, tgt_layer, tgt_model=None, syn_type=None, fig=None, mask=None, kernel=None, src_color='red', src_size=50, tgt_color='blue', tgt_size=20, mask_color='red', kernel_color='red')

Plot all targets of source neuron src_nrn in a target layer tgt_layer.

src_nrn : int
GID of source neuron (as single-element list)
tgt_layer : tuple/list of int(s)
GID of tgt_layer (as single-element list)
tgt_model : [None | str], optional, default: None
Show only targets of a given model.
syn_type : [None | str], optional, default: None
Show only targets connected to with a given synapse type
fig : [None | matplotlib.figure.Figure object], optional, default: None
Matplotlib figure to plot to. If not given, a new figure is created.
mask : [None | dict], optional, default: None
Draw topology mask with targets; see PlotKernel for details.
kernel : [None | dict], optional, default: None
Draw topology kernel with targets; see PlotKernel for details.
src_color : [None | any matplotlib color], optional, default: ‘red’
Color used to mark source node position
src_size : float, optional, default: 50
Size of source marker (see scatter for details)
tgt_color : [None | any matplotlib color], optional, default: ‘blue’
Color used to mark target node positions
tgt_size : float, optional, default: 20
Size of target markers (see scatter for details)
mask_color : [None | any matplotlib color], optional, default: ‘red’
Color used for line marking mask
kernel_color : [None | any matplotlib color], optional, default: ‘red’
Color used for lines marking kernel

out : matplotlib.figure.Figure object

GetTargetNodes : Obtain targets of a list of sources in a given target
layer.
GetTargetPositions : Obtain positions of targets of a list of sources in a
given target layer.

PlotKernel : Add indication of mask and kernel to axes. PlotLayer : Plot all nodes in a layer. matplotlib.pyplot.scatter : matplotlib scatter plot.

  • Do not use this function in distributed simulations.
Example
import nest.topology as tp
import matplotlib.pyplot as plt

# create a layer
l = tp.CreateLayer({'rows'      : 11,
                    'columns'   : 11,
                    'extent'    : [11.0, 11.0],
                    'elements'  : 'iaf_psc_alpha'})

# connectivity specifications with a mask
conndict = {'connection_type': 'divergent',
             'mask': {'rectangular': {'lower_left'  : [-2.0, -1.0],
                                      'upper_right' : [2.0, 1.0]}}}

# connect layer l with itself according to the given
# specifications
tp.ConnectLayers(l, l, conndict)

# plot the targets of the source neuron with GID 5
tp.PlotTargets([5], l)
plt.show()
hl_api.topology_func(slifunc, *args)

Execute SLI function slifunc with arguments args in Topology namespace.

slifunc : str
SLI namespace expression
args : dict
An arbitrary number of arguments
out :
Values from SLI function slifunc

nest.sli_func

Module contents