PyNEST API

Here is a list of functions for the PyNEST interface.

Functions related to models

Functions for model handling

nest.lib.hl_api_models.ConnectionRules()

Return a typle of all available connection rules, sorted by name.

Returns

Available connection rules

Return type

tuple

nest.lib.hl_api_models.CopyModel(existing, new, params=None)

Create a new model by copying an existing one.

Parameters

• existing (str) – Name of existing model

• new (str) – Name of the copied model

• params (dict, optional) – Default parameters assigned to the copy. Not provided parameters are taken from the existing model.

nest.lib.hl_api_models.GetDefaults(model, keys=None, output='')

Return default parameters of the given model, specified by a string.

Parameters

• model (str) – Name of the model

• keys (str or list, optional) – String or a list of strings naming model properties. GetDefaults then returns a single value or a list of values belonging to the keys given.

• output (str, optional) – Whether the returned data should be in a format (output='json'). Default is ‘’.

Returns

• dict – A dictionary of default parameters.

• type – If keys is a string, the corrsponding default parameter is returned.

• list – If keys is a list of strings, a list of corrsponding default parameters is returned.

• str – If output is json, returns parameters in JSON format.

Raises

TypeError –

nest.lib.hl_api_models.Models(mtype='all', sel=None)

Return a tuple of model names, sorted by name.

All available models are neurons, devices and synapses.

Parameters

• mtype (str, optional) – Use 'mtype='nodes' to only see neuron and device models, or 'type='synapses' to only see synapse models.

• sel (str, optional) – String used to filter the result list and only return models containing it.

Returns

Available model names

Return type

tuple

Raises

ValueError – Description

Notes

• Synapse model names ending with '_hpc' provide minimal memory requirements by using thread-local target neuron IDs and fixing the 'rport' to 0.

• Synapse model names ending with '_lbl' allow to assign an individual integer label ('synapse_label') to created synapses at the cost of increased memory requirements.

nest.lib.hl_api_models.SetDefaults(model, params, val=None)

Set the default parameter values of the given model.

New default values are used for all subsequently created instances of the model.

Parameters

• model (str) – Name of the model

• params (str or dict) – Dictionary of new default parameter values

• val (str, optional) – If given, params has to be the name of a model property.

Functions related to the creation and retrieval of nodes (neurons, devices)

Functions for node handling

nest.lib.hl_api_nodes.Create(model, n=1, params=None)

Create one or more nodes.

Generates n new network objects of the supplied model type. If n is not given, a single node is created. Note that if setting parameters of the nodes fail, the nodes will still have been created.

Parameters

• model (str) – Name of the model to create

• n (int, optional) – Number of nodes to create

• params (dict or list, optional) – Parameters for the new nodes. A single dictionary or a list of dictionaries with size n. If omitted, the model’s defaults are used.

Returns

Global IDs of created nodes

Return type

list

Raises

NESTError – If setting node parameters fail. However, the nodes will still have been created.

nest.lib.hl_api_nodes.GetLID(gid)

Return the local id of a node with the global ID gid.

Deprecated since version 2.14: GetLID is deprecated and will be removed in NEST 3.0. Use index into GIDCollection instead.

Parameters

gid (int) – Global id of node

Returns

Local id of node

Return type

int

Raises

NESTError – If gid contains more than one GID

Functions related to setting and getting parameters

Functions to get information on NEST.

nest.lib.hl_api_info.authors()

Print the authors of NEST.

nest.lib.hl_api_info.get_argv()

Return argv as seen by NEST.

This is similar to Python sys.argv but might have changed after MPI initialization.

Returns

Argv, as seen by NEST

Return type

tuple

nest.lib.hl_api_info.GetStatus(nodes, keys=None, output='')

Return the parameter dictionaries of nodes or connections.

If keys is given, a list of values is returned instead. keys may also be a list, in which case the returned list contains lists of values.

Parameters

• nodes (list or tuple) – Either a list of global ids of nodes, or a tuple of connection handles as returned by GetConnections.

• keys (str or list, optional) – string or a list of strings naming model properties. GetDefaults then returns a single value or a list of values belonging to the keys given.

• output (str, optional) – Whether the returned data should be in a selected format (output='json'). Default is ‘’.

Returns

• dict – All parameters

• type – If keys is a string, the corrsponding default parameter is returned.

• list – If keys is a list of strings, a list of corrsponding default parameters is returned.

• str – If output is json, returns parameters in JSON format.

Raises

TypeError – If nodes or keys are on the wrong form.

See also

SetStatus()

nest.lib.hl_api_info.help(obj=None, pager=None, return_text=False)

Show the help page for the given object using the given pager.

The default pager is more (See .nestrc).

Parameters

• obj (object, optional) – Object to display help for

• pager (str, optional) – Pager to use

• return_text (bool, optional) – Option for returning the help text

Returns

The help text of the object if return_text is True.

Return type

None or str

nest.lib.hl_api_info.helpdesk()

Open the NEST helpdesk in browser.

Use the system default browser.

nest.lib.hl_api_info.message(level, sender, text)

Print a message using message system of NEST.

Parameters

• level – Level

• sender – Message sender

• text (str) – Text to be sent in the message

nest.lib.hl_api_info.SetStatus(nodes, params, val=None)

Set parameters of nodes or connections.

Parameters of nodes or connections, given in nodes, is set as specified by params. If val is given, params has to be a string with the name of an attribute, which is set to val on the nodes/connections. val can be a single value or a list of the same size as nodes.

Parameters

• nodes (list or tuple) – Either a list of global ids of nodes, or a tuple of connection handles as returned by GetConnections.

• params (str or dict or list) – Dictionary of parameters or list of dictionaries of parameters of same length as nodes. If val is given, this has to be the name of a model property as a str.

• val (str, optional) – If given, params has to be the name of a model property.

Raises

TypeError – If nodes is not a list of nodes or synapses, or if the number of parameters don’t match the number of nodes or synapses.

See also

GetStatus()

nest.lib.hl_api_info.sysinfo()

Print information on the platform on which NEST was compiled.

nest.lib.hl_api_info.version()

Return the NEST version.

Returns

The version of NEST

Return type

str

Functions related to connections

Functions for connection handling

nest.lib.hl_api_connections.CGConnect(pre, post, cg, parameter_map=None, model='static_synapse')

Connect neurons using the Connection Generator Interface.

Potential pre-synaptic neurons are taken from pre, potential post-synaptic neurons are taken from post. The connection generator cg specifies the exact connectivity to be set up. The parameter_map can either be None or a dictionary that maps the keys weight and delay to their integer indices in the value set of the connection generator.

This function is only available if NEST was compiled with support for libneurosim.

For further information, see * The NEST documentation on using the CG Interface at

https://www.nest-simulator.org/connection-generator-interface

• The GitHub repository and documentation for libneurosim at https://github.com/INCF/libneurosim/

• The publication about the Connection Generator Interface at https://doi.org/10.3389/fninf.2014.00043

Parameters

• pre (list or numpy.array) – must contain a list of GIDs

• post (list or numpy.array) – must contain a list of GIDs

• cg (connection generator) – libneurosim connection generator to use

• parameter_map (dict, optional) – Maps names of values such as weight and delay to value set positions

• model (str, optional) – Synapse model to use

Raises

kernel.NESTError –

nest.lib.hl_api_connections.CGParse(xml_filename)

Parse an XML file and return the corresponding connection generator cg.

The library to provide the parsing can be selected by CGSelectImplementation().

Parameters

xml_filename (str) – Filename of the xml file to parse.

Raises

kernel.NESTError –

nest.lib.hl_api_connections.CGSelectImplementation(tag, library)

Select a library to provide a parser for XML files and associate an XML tag with the library.

XML files can be read by CGParse().

Parameters

• tag (str) – XML tag to associate with the library

• library (str) – Library to use to parse XML files

Raises

kernel.NESTError –

nest.lib.hl_api_connections.Connect(pre, post, conn_spec=None, syn_spec=None, model=None)

Connect pre nodes to post nodes.

Nodes in pre and post are connected using the specified connectivity (all-to-all by default) and synapse type (static_synapse by default). Details depend on the connectivity rule.

Parameters

• pre (list) – Presynaptic nodes, as list of GIDs

• post (list) – Postsynaptic nodes, as list of GIDs

• conn_spec (str or dict, optional) – Specifies connectivity rule, see below

• syn_spec (str or dict, optional) – Specifies synapse model, see below

• model (str or dict, optional) – alias for syn_spec for backward compatibility

Raises

kernel.NESTError –

Notes

Connect does not iterate over subnets, it only connects explicitly specified nodes.

Connectivity specification (conn_spec)

Available rules and associated parameters:

- 'all_to_all' (default)
- 'one_to_one'
- 'fixed_indegree', 'indegree'
- 'fixed_outdegree', 'outdegree'
- 'fixed_total_number', 'N'
- 'pairwise_bernoulli', 'p'

See Connection Rules for more details, including example usage.

Synapse specification (syn_spec)

The synapse model and its properties can be given either as a string identifying a specific synapse model (default: static_synapse) or as a dictionary specifying the synapse model and its parameters.

Available keys in the synapse specification dictionary are:

- 'model'
- 'weight'
- 'delay'
- 'receptor_type'
- any parameters specific to the selected synapse model.

See Synapse Specification for details, including example usage.

All parameters are optional and if not specified, the default values of the synapse model will be used. The key ‘model’ identifies the synapse model, this can be one of NEST’s built-in synapse models or a user-defined model created via CopyModel().

If model is not specified the default model static_synapse will be used.

Any distributed parameter must be initialised with a further dictionary specifying the distribution type (distribution, e.g. normal) and any distribution-specific parameters (e.g. mu and sigma). See Distributed parameters for more info.

To see all available distributions, run: nest.slirun('rdevdict info')

To get information on a particular distribution, e.g. ‘binomial’, run: nest.help('rdevdict::binomial')

See also

Connection Management

nest.lib.hl_api_connections.DataConnect(pre, params=None, model='static_synapse')

Connect neurons from lists of connection data.

Parameters

• pre (list) – Presynaptic nodes, given as lists of GIDs or lists of synapse status dictionaries. See below.

• params (list, optional) – See below

• model (str, optional) – Synapse model to use, see below

Raises

TypeError –

Notes

Usage Variants

Variant 1:

Connect each neuron in pre to the targets given in params, using synapse type model

pre: [gid_1, ... gid_n]
params: [ {param_1}, ..., {param_n} ]
model= 'synapse_model'

The dictionaries param_1 to param_n must contain at least the following keys:

- 'target'
- 'weight'
- 'delay'

Each key must resolve to a list or numpy.ndarray of values.

Depending on the synapse model, other parameters can be given in the same format. All arrays in params must have the same length as ‘target’.

Variant 2:

Connect neurons according to a list of synapse status dictionaries, as obtained from GetStatus().

pre = [ {synapse_state1}, ..., {synapse_state_n}]
params=None
model=None

During connection, status dictionary misses will not raise errors, even if the kernel property dict_miss_is_error is True.

nest.lib.hl_api_connections.Disconnect(pre, post, conn_spec='one_to_one', syn_spec='static_synapse')

Disconnect pre neurons from post neurons.

Neurons in pre and post are disconnected using the specified disconnection rule (one-to-one by default) and synapse type (static_synapse by default). Details depend on the disconnection rule.

Parameters

• pre (list) – Presynaptic nodes, given as list of GIDs

• post (list) – Postsynaptic nodes, given as list of GIDs

• conn_spec (str or dict) – Disconnection rule, see below

• syn_spec (str or dict) – Synapse specifications, see below

Notes

conn_spec

Apply the same rules as for connectivity specs in the Connect method

Possible choices of the conn_spec are

- 'one_to_one'
- 'all_to_all'

syn_spec

The synapse model and its properties can be inserted either as a string describing one synapse model (synapse models are listed in the synapsedict) or as a dictionary as described below.

Note that only the synapse type is checked when we disconnect and that if syn_spec is given as a non-empty dictionary, the model parameter must be present.

If no synapse model is specified the default model static_synapse will be used.

Available keys in the synapse dictionary are

- 'model'
- 'weight'
- 'delay'
- 'receptor_type'
- parameters specific to the synapse model chosen

All parameters are optional and if not specified will use the default values determined by the current synapse model.

model determines the synapse type, taken from pre-defined synapse types in NEST or manually specified synapses created via CopyModel().

All other parameters are not currently implemented.

Disconnect does not iterate over subnets, it only disconnects explicitly specified nodes.

nest.lib.hl_api_connections.DisconnectOneToOne(source, target, syn_spec)

Disconnect a currently existing synapse.

Deprecated since version DisconnectOneToOne: is deprecated and will be removed in NEST-3.0. Use Disconnect instead.

Parameters

• source (int) – GID of presynaptic node

• target (int) – GID of postsynaptic node

• syn_spec (str or dict) – See Connect() for definition

nest.lib.hl_api_connections.GetConnections(source=None, target=None, synapse_model=None, synapse_label=None)

Return an array of connection identifiers.

Any combination of source, target, synapse_model and synapse_label parameters is permitted.

Parameters

• source (list, optional) – Source GIDs, only connections from these pre-synaptic neurons are returned

• target (list, optional) – Target GIDs, only connections to these post-synaptic neurons are returned

• synapse_model (str, optional) – Only connections with this synapse type are returned

• synapse_label (int, optional) – (non-negative) only connections with this synapse label are returned

Returns

Connections as 5-tuples with entries (source-gid, target-gid, target-thread, synapse-id, port)

Return type

array

Raises

TypeError –

Notes

Only connections with targets on the MPI process executing the command are returned.

Functions related to simulation

Functions for simulation control

nest.lib.hl_api_simulation.Cleanup()

Cleans up resources after a Run call. Not needed for Simulate.

Closes state for a series of runs, such as flushing and closing files. A Prepare is needed after a Cleanup before any more calls to Run.

See also

Run(), Prepare()

nest.lib.hl_api_simulation.DisableStructuralPlasticity()

Disable structural plasticity for the network simulation

See also

EnableStructuralPlasticity()

nest.lib.hl_api_simulation.EnableStructuralPlasticity()

Enable structural plasticity for the network simulation

See also

DisableStructuralPlasticity()

nest.lib.hl_api_simulation.GetKernelStatus(keys=None)

Obtain parameters of the simulation kernel.

Parameters

keys (str or list, optional) – Single parameter name or list of parameter names

Returns

• dict – Parameter dictionary, if called without argument

• type – Single parameter value, if called with single parameter name

• list – List of parameter values, if called with list of parameter names

Raises

TypeError – If keys are of the wrong type.

See also

SetKernelStatus()

nest.lib.hl_api_simulation.GetStructuralPlasticityStatus(keys=None)

Get the current structural plasticity parameters

Parameters

keys (str or list, optional) – Keys indicating the values of interest to be retrieved by the get call

See also

SetStructuralPlasticityStatus()

nest.lib.hl_api_simulation.Install(module_name)

Load a dynamically linked NEST module.

Parameters

module_name (str) – Name of the dynamically linked module

Returns

NEST module identifier, required for unloading

Return type

handle

Notes

Dynamically linked modules are searched in the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH under OSX).

Example

nest.lib.hl_api_simulation.Prepare()

Calibrate the system before a Run call. Not needed for Simulate.

Call before the first Run call, or before calling Run after changing the system, calling SetStatus or Cleanup.

See also

Run(), Cleanup()

nest.lib.hl_api_simulation.ResetKernel()

Reset the simulation kernel.

This will destroy the network as well as all custom models created with CopyModel(). Calling this function is equivalent to restarting NEST.

In particular,

• all network nodes

• all connections

• all user-defined neuron and synapse models

are deleted, and

• time

• random generators

are reset. The only exception is that dynamically loaded modules are not unloaded. This may change in a future version of NEST.

nest.lib.hl_api_simulation.ResetNetwork()

Reset all nodes and connections to their original state.

Deprecated since version 2.18: ResetNetwork is deprecated and will be removed in NEST 3.0, because this function is not fully able to reset network and simulator state. The only reliable way to reset state is to call ResetKernel and then rebuild the network.

Resets the dynamic state of the entire network to its original state. The dynamic state comprises typically the membrane potential, synaptic currents, buffers holding input that has been delivered, but not yet become effective, and all events pending delivery. Node parameters, such as time constants and threshold potentials, are not affected.

However, note that

• Time and random number generators are NOT reset.

• Files belonging to recording devices (spike detector, multimeter, voltmeter, etc) are closed. You must change the file name before simulating again. Otherwise the files can be overwritten or you will receive an error.

• ResetNetwork will reset the nodes to the state values stored in the model prototypes. So if you have used SetDefaults to change a state value of a model since simulating the first time, the network will NOT be reset to the status at T=0.

• The dynamic state of synapses with internal dynamics (STDP, facilitation) is NOT reset at present. This will be implemented in a future version of NEST.

See also

ResetKernel()

nest.lib.hl_api_simulation.Run(t)

Simulate the network for t milliseconds.

Parameters

t (float) – Time to simulate in ms

Notes

Call between Prepare and Cleanup calls, or within a with RunManager clause.

Simulate(t): t’ = t/m; Prepare(); for _ in range(m): Run(t’); Cleanup()

Prepare must be called before Run to calibrate the system, and Cleanup must be called after Run to close files, cleanup handles, and so on. After Cleanup, Prepare can and must be called before more Run calls. Any calls to SetStatus between Prepare and Cleanup have undefined behaviour.

See also

Prepare(), Cleanup(), RunManager(), Simulate()

nest.lib.hl_api_simulation.RunManager()

ContextManager for Run

Calls Prepare before a series of Run calls, and calls Cleanup at end.

E.g.:

with RunManager():
    for i in range(10):
        Run()

See also

Prepare(), Run(), Cleanup(), Simulate()

nest.lib.hl_api_simulation.SetKernelStatus(params)

Set parameters for the simulation kernel.

Parameters

params (dict) – Dictionary of parameters to set.

See also

GetKernelStatus()

nest.lib.hl_api_simulation.SetStructuralPlasticityStatus(params)

Set structural plasticity parameters for the network simulation.

Parameters

params (dict) – Dictionary of structural plasticity parameters to set

See also

GetStructuralPlasticityStatus()

nest.lib.hl_api_simulation.Simulate(t)

Simulate the network for t milliseconds.

Parameters

t (float) – Time to simulate in ms

See also

RunManager(), ResumeSimulation()

Functions related to parallel computing

Functions for parallel computing

nest.lib.hl_api_parallel_computing.NumProcesses()

Return the overall number of MPI processes.

Returns

Number of overall MPI processes

Return type

int

nest.lib.hl_api_parallel_computing.Rank()

Return the MPI rank of the local process.

Returns

MPI rank of the local process

Return type

int

Note

DO NOT USE Rank() TO EXECUTE ANY FUNCTION IMPORTED FROM THE nest MODULE ON A SUBSET OF RANKS IN AN MPI-PARALLEL SIMULATION.

This will lead to unpredictable behavior. Symptoms may be an error message about non-synchronous global random number generators or deadlocks during simulation. In the worst case, the simulation may complete but generate nonsensical results.

nest.lib.hl_api_parallel_computing.SetAcceptableLatency(port_name, latency)

Set the acceptable latency (in ms) for a MUSIC port.

Parameters

• port_name (str) – MUSIC port to set latency for

• latency (float) – Latency in ms

nest.lib.hl_api_parallel_computing.SetMaxBuffered(port_name, size)

Set the maximum buffer size for a MUSIC port.

Parameters

• port_name (str) – MUSIC port to set buffer size for

• size (int) – Buffer size

nest.lib.hl_api_parallel_computing.SyncProcesses()

Synchronize all MPI processes.

Functions related to subnets

Warning

Subnets will be deprecated in NEST 3.0

Functions for hierarchical networks

nest.lib.hl_api_subnets.BeginSubnet(label=None, params=None)

Create a new subnet and change into it.

Parameters

• label (str, optional) – Name of the new subnet

• params (dict, optional) – The customdict of the new subnet

nest.lib.hl_api_subnets.ChangeSubnet(subnet)

Make given subnet the current.

Parameters

subnet (int) – GID of the subnet

Raises

kernel.NESTError –

nest.lib.hl_api_subnets.CurrentSubnet()

Returns the global id of the current subnet.

Returns

GID of current subnet

Return type

int

nest.lib.hl_api_subnets.EndSubnet()

Change to the parent subnet and return the gid of the current.

Raises

kernel.NESTError – Description

nest.lib.hl_api_subnets.GetChildren(subnets, properties=None, local_only=False)

Return the global ids of the immediate children of the given subnets.

Parameters

• subnets (list) – GIDs of subnets

• properties (dict, optional) – Only global ids of nodes matching the properties given in the dictionary exactly will be returned. Matching properties with float values (e.g. the membrane potential) may fail due to tiny numerical discrepancies and should be avoided.

• local_only (bool, optional) – If True, only GIDs of nodes simulated on the local MPI process will be returned. By default, global ids of nodes in the entire simulation will be returned. This requires MPI communication and may slow down the script.

Returns

GIDs of leaf nodes

Return type

list

See also

GetLeaves(), GetNodes()

nest.lib.hl_api_subnets.GetLeaves(subnets, properties=None, local_only=False)

Return the GIDs of the leaf nodes of the given subnets.

Leaf nodes are all nodes that are not subnets.

Parameters

• subnets (list) – GIDs of subnets

• properties (dict, optional) – Only global ids of nodes matching the properties given in the dictionary exactly will be returned. Matching properties with float values (e.g. the membrane potential) may fail due to tiny numerical discrepancies and should be avoided.

• local_only (bool, optional) – If True, only GIDs of nodes simulated on the local MPI process will be returned. By default, global ids of nodes in the entire simulation will be returned. This requires MPI communication and may slow down the script.

Returns

GIDs of leaf nodes

Return type

list

See also

GetNodes(), GetChildren()

nest.lib.hl_api_subnets.GetNetwork(gid, depth)

Return a nested list with the children of subnet id at level depth.

Parameters

• gid (int) – GID of subnet

• depth (int) – Depth of list to return. If depth==0, the immediate children of the subnet are returned. The returned list is depth+1 dimensional.

Returns

nested lists of GIDs of child nodes

Return type

list

Raises

kernel.NESTError –

nest.lib.hl_api_subnets.GetNodes(subnets, properties=None, local_only=False)

Return the global ids of the all nodes of the given subnets.

Parameters

• subnets (list) – GIDs of subnets

• properties (dict, optional) – Only global ids of nodes matching the properties given in the dictionary exactly will be returned. Matching properties with float values (e.g. the membrane potential) may fail due to tiny numerical discrepancies and should be avoided.

• local_only (bool, optional) – If True, only GIDs of nodes simulated on the local MPI process will be returned. By default, global ids of nodes in the entire simulation will be returned. This requires MPI communication and may slow down the script.

Returns

GIDs of leaf nodes

Return type

list

See also

GetLeaves(), GetChildren()

nest.lib.hl_api_subnets.LayoutNetwork(model, dim, label=None, params=None)

Create a subnetwork of dimension dim with nodes of type model and return a list of ids.

params is a dictionary, which will be set as customdict of the newly created subnet.

Parameters

• model (str) – Neuron model to use

• dim (int) – Dimension of subnetwork

• label (str, optional) – Name of the new subnet

• params (dict, optional) – The customdict of the new subnet. Not the parameters for the neurons in the subnetwork.

Raises

ValueError – Description

nest.lib.hl_api_subnets.PrintNetwork(depth=1, subnet=None)

Print the network tree up to depth, starting at subnet.

If subnet is omitted, the current subnet is used instead.

Parameters

• depth (int, optional) – Depth to print to

• subnet (TYPE, optional) – Subnet to start at

Raises

kernel.NESTError –

Functions related to topology

Note

The topology module will be integrated into nest in 3.0

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

pynest.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.

Parameters

• 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

Returns

out – ConnectLayers returns None

Return type

None

See also

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.

GetConnections()

Retrieve connections.

Other Parameters

• 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.

Notes

• 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}}}

pynest.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’.

Parameters

specs ((tuple/list of) dict(s)) – Dictionary or list of dictionaries with layer specifications, see Notes.

Returns

out – GID(s) of created layer(s)

Return type

tuple of int(s)

See also

ConnectLayers()

Connect two (lists of) layers which were created with CreateLayer pairwise according to specified projections.

Other Parameters

• 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’.

Notes

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']

pynest.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’.

Parameters

• masktype (str, ['rectangular' | 'circular' | 'doughnut' | 'elliptical']) – for 2D masks, [‘box’ | ‘spherical’ | ‘ellipsoidal] 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.

Returns

out

Return type

Mask object

See also

ConnectLayers()

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

Notes

• All angles must be given in degrees.

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],
       'azimuth_angle': float  # default:0.0}
  #or
  'circular' :
      {'radius' : float}
  #or
  'doughnut' :
      {'inner_radius' : float,
       'outer_radius' : float}
  #or
  'elliptical' :
      {'major_axis' : float,
       'minor_axis' : float,
       'azimuth_angle' : float,   # default: 0.0,
       'anchor' : [float, float], # default: [0.0, 0.0]}
  

• 3D free and grid-based layers

  'box' :
      {'lower_left'  : [float, float, float],
       'upper_right' : [float, float, float],
       'azimuth_angle: float  # default: 0.0,
       'polar_angle  : float  # defualt: 0.0}
  #or
  'spherical' :
      {'radius' : float}
  #or
  'ellipsoidal' :
      {'major_axis' : float,
       'minor_axis' : float,
       'polar_axis' : float
       'azimuth_angle' : float,   # default: 0.0,
       'polar_angle' : float,     # default: 0.0,
       'anchor' : [float, float, float], # default: [0.0, 0.0, 0.0]}}
  

• 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)

pynest.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.

Parameters

• 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.

Returns

out

Return type

Parameter object

See also

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.

Notes

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)

pynest.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.

Parameters

• 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

Returns

out – Displacement vectors between pairs of nodes in from_arg and to_arg

Return type

tuple

See also

Distance()

Get lateral distances between nodes.

DumpLayerConnections()

Write connectivity information to file.

GetPosition()

Return the spatial locations of nodes.

Notes

• 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]))

pynest.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.

Parameters

• 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

Returns

out – Distances between from and to

Return type

tuple

See also

Displacement()

Get vector of lateral displacements between nodes.

DumpLayerConnections()

Write connectivity information to file.

GetPosition()

Return the spatial locations of nodes.

Notes

• 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]))

pynest.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.

Parameters

• 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)

Returns

out

Return type

None

See also

DumpLayerNodes()

Write layer node positions to file.

GetPosition()

Return the spatial locations of nodes.

GetConnections()

Return connection identifiers between sources and targets

Notes

• 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')

pynest.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.

Parameters

• 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)

Returns

out

Return type

None

See also

DumpLayerConnections()

Write connectivity information to file.

GetPosition()

Return the spatial locations of nodes.

Notes

• 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')

pynest.hl_api.FindCenterElement(layers)

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

Parameters

layers (tuple/list of int(s)) – List of layer GIDs

Returns

out – 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.

Return type

tuple of int(s)

See also

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.

Notes

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)

pynest.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.

Parameters

• 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.

Returns

out – List of node GIDs

Return type

tuple of int(s)

See also

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.

Notes

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)

pynest.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.

Parameters

• 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]

Returns

out – List of GIDs

Return type

tuple of int(s)

See also

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.

Notes

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])

pynest.hl_api.GetLayer(nodes)

Return the layer to which nodes belong.

Parameters

nodes (tuple/list of int(s)) – List of neuron GIDs

Returns

out – List of layer GIDs

Return type

tuple of int(s)

See also

GetElement()

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

GetPosition()

Return the spatial locations of nodes.

Notes

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])

pynest.hl_api.GetPosition(nodes)

Return the spatial locations of nodes.

Parameters

nodes (tuple/list of int(s)) – List of GIDs

Returns

out – List of positions as 2- or 3-element lists

Return type

tuple of tuple(s)

See also

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.

Notes

• 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)

pynest.hl_api.GetTargetNodes(sources, tgt_layer, tgt_model=None, syn_model=None)

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

Parameters

• 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.

Returns

out – 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.

Return type

tuple of list(s) of int(s)

See also

GetTargetPositions()

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

GetConnections()

Return connection identifiers between sources and targets

Notes

• 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)

pynest.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.

Parameters

• 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.

Returns

out – 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.

Return type

tuple of tuple(s) of tuple(s) of floats

See also

GetTargetNodes()

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

Notes

• 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 pynest.hl_api.Mask(datum)

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.

Parameters

point (tuple/list of float values) – Coordinate of point

Returns

out – True if the point is inside the mask, False otherwise

Return type

bool

class pynest.hl_api.Parameter(datum)

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.

Parameters

point (tuple/list of float values) – coordinate of point

Returns

out – The value of the parameter at the point

Return type

value

See also

CreateParameter()

create parameter for e.g., distance dependency

Notes

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.])

pynest.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. Usually, this function is invoked by PlotTargets.

Parameters

• 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

Returns

out

Return type

None

See also

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.

Notes

• 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)

pynest.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.

Parameters

• 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

Returns

out

Return type

matplotlib.figure.Figure object

See also

PlotKernel()

Add indication of mask and kernel to axes.

PlotTargets()

Plot all targets of a given source.

matplotlib.figure.Figure()

matplotlib Figure class

Notes

• 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()

pynest.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.

Parameters

• 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

Returns

out

Return type

matplotlib.figure.Figure object

See also

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.

Notes

• 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()

pynest.hl_api.SelectNodesByMask(layer, anchor, mask_obj)

Obtain the GIDs inside a masked area of a topology layer.

The function finds and returns all the GIDs inside a given mask of a single layer. It works on both 2-dimensional and 3-dimensional masks and layers. All mask types are allowed, including combined masks.

Parameters

• layer (tuple/list of int) – List containing the single layer to select nodes from.

• anchor (tuple/list of double) – List containing center position of the layer. This is the point from where we start to search.

• mask_obj (object) – Mask object specifying chosen area.

Returns

out – GID(s) of nodes/elements inside the mask.

Return type

list of int(s)

Functions related to helper info

These are helper functions to ease the definition of the high-level API of the PyNEST wrapper.

nest.lib.hl_api_helper.broadcast(item, length, allowed_types, name='item')

Broadcast item to given length.

Parameters

• item (object) – Object to broadcast

• length (int) – Length to broadcast to

• allowed_types (list) – List of allowed types

• name (str, optional) – Name of item

Returns

The original item broadcasted to sequence form of length

Return type

object

Raises

TypeError –

nest.lib.hl_api_helper.deprecated(alt_func_name, text=None)

Decorator for deprecated functions.

Shows a warning and calls the original function.

Parameters

• alt_func_name (str, optional) – Name of the function to use instead, may be empty string

• text (str, optional) – Text to display instead of standard text

Returns

Decorator function

Return type

function

nest.lib.hl_api_helper.get_help_filepath(hlpobj)

Get file path of help object

Prints message if no help is available for hlpobj.

Parameters

hlpobj (string) – Object to display help for

Returns

Filepath of the help object or None if no help available

Return type

string

nest.lib.hl_api_helper.get_unistring_type()

Returns string type dependent on python version.

Returns

Depending on Python version

Return type

str or basestring

nest.lib.hl_api_helper.get_verbosity()

Return verbosity level of NEST’s messages.

• M_ALL=0, display all messages

• M_INFO=10, display information messages and above

• M_DEPRECATED=18, display deprecation warnings and above

• M_WARNING=20, display warning messages and above

• M_ERROR=30, display error messages and above

• M_FATAL=40, display failure messages and above

Returns

The current verbosity level

Return type

int

nest.lib.hl_api_helper.get_wrapped_text(text, width=80)

Formats a given multiline string to wrap at a given width, while preserving newlines (and removing excessive whitespace).

Parameters

text (str) – String to format

Returns

Wrapped string

Return type

str

nest.lib.hl_api_helper.is_coercible_to_sli_array(seq)

Checks whether a given object is coercible to a SLI array

Parameters

seq (object) – Object to check

Returns

True if object is coercible to a SLI array

Return type

bool

nest.lib.hl_api_helper.is_iterable(seq)

Return True if the given object is an iterable, False otherwise.

Parameters

seq (object) – Object to check

Returns

True if object is an iterable

Return type

bool

nest.lib.hl_api_helper.is_literal(obj)

Check whether obj is a “literal”: a unicode string or SLI literal

Parameters

obj (object) – Object to check

Returns

True if obj is a “literal”

Return type

bool

nest.lib.hl_api_helper.is_sequence_of_connections(seq)

Checks whether low-level API accepts seq as a sequence of connections.

Parameters

seq (object) – Object to check

Returns

True if object is an iterable of dictionaries or subscriptables of CONN_LEN

Return type

bool

nest.lib.hl_api_helper.is_sequence_of_gids(seq)

Checks whether the argument is a potentially valid sequence of GIDs (non-negative integers).

Parameters

seq (object) – Object to check

Returns

True if object is a potentially valid sequence of GIDs

Return type

bool

nest.lib.hl_api_helper.is_string(obj)

Check whether obj is a unicode string

Parameters

obj (object) – Object to check

Returns

True if obj is a unicode string

Return type

bool

nest.lib.hl_api_helper.load_help(hlpobj)

Returns documentation of the object

Parameters

hlpobj (object) – Object to display help for

Returns

The documentation of the object or None if no help available

Return type

string

nest.lib.hl_api_helper.model_deprecation_warning(model)

Checks whether the model is to be removed in a future verstion of NEST. If so, a deprecation warning is issued.

Parameters

model (str) – Name of model

nest.lib.hl_api_helper.serializable(data)

Make data serializable for JSON.

Parameters

data (str, int, float, SLILiteral, list, tuple, dict, ndarray) –

Returns

result

Return type

str, int, float, list, dict

nest.lib.hl_api_helper.set_verbosity(level)

Change verbosity level for NEST’s messages.

• M_ALL=0, display all messages

• M_INFO=10, display information messages and above

• M_DEPRECATED=18, display deprecation warnings and above

• M_WARNING=20, display warning messages and above

• M_ERROR=30, display error messages and above

• M_FATAL=40, display failure messages and above

Parameters

level (str) – Can be one of ‘M_FATAL’, ‘M_ERROR’, ‘M_WARNING’, ‘M_DEPRECATED’, ‘M_INFO’ or ‘M_ALL’.

nest.lib.hl_api_helper.show_deprecation_warning(func_name, alt_func_name=None, text=None)

Shows a deprecation warning for a function.

Parameters

• func_name (str) – Name of the deprecated function

• alt_func_name (str, optional) – Name of the function to use instead

• text (str, optional) – Text to display instead of standard text

nest.lib.hl_api_helper.show_help_with_pager(hlpobj, pager=None)

Output of doc in python with pager or print

Parameters

• hlpobj (object) – Object to display

• pager (str, optional) – pager to use, False if you want to display help using print().

class nest.lib.hl_api_helper.SuppressedDeprecationWarning(no_dep_funcs)

Context manager turning off deprecation warnings for given methods.

Think thoroughly before use. This context should only be used as a way to make sure examples do not display deprecation warnings, that is, used in functions called from examples, and not as a way to make tedious deprecation warnings dissapear.

nest.lib.hl_api_helper.to_json(data)

Serialize data to JSON.

Parameters

data (str, int, float, SLILiteral, list, tuple, dict, ndarray) –

Returns

data_json – JSON format of the data

Return type

str

nest.lib.hl_api_helper.uni_str

alias of builtins.str