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

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

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

nest.lib.hl_api_simulation.EnableStructuralPlasticity()

Enable structural plasticity for the network simulation

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.

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

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.

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()
nest.lib.hl_api_simulation.SetKernelStatus(params)

Set parameters for the simulation kernel.

Parameters

params (dict) – Dictionary of parameters to set.

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

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 helper info

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

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

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