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
-
nest.lib.hl_api_models.
CopyModel
(existing, new, params=None)¶ Create a new model by copying an existing one.
-
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
-
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
- Returns
Available model names
- Return type
- 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.
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
- Returns
Global IDs of created nodes
- Return type
- 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.
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
-
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
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
-
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).
-
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.
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
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()
.
-
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
-
nest.lib.hl_api_connections.
DataConnect
(pre, params=None, model='static_synapse')¶ Connect neurons from lists of connection data.
- Parameters
- Raises
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
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.
-
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
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.
-
nest.lib.hl_api_simulation.
DisableStructuralPlasticity
()¶ Disable structural plasticity for the network simulation
See also
-
nest.lib.hl_api_simulation.
EnableStructuralPlasticity
()¶ Enable structural plasticity for the network simulation
See also
-
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
-
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
-
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.
-
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
-
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
-
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.
See also
-
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
-
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
-
nest.lib.hl_api_parallel_computing.
Rank
()¶ Return the MPI rank of the local process.
- Returns
MPI rank of the local process
- Return type
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.
-
nest.lib.hl_api_parallel_computing.
SetMaxBuffered
(port_name, size)¶ Set the maximum buffer size for a MUSIC port.
-
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.
-
nest.lib.hl_api_helper.
deprecated
(alt_func_name, text=None)¶ Decorator for deprecated functions.
Shows a warning and calls the original 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
-
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).
-
nest.lib.hl_api_helper.
is_coercible_to_sli_array
(seq)¶ Checks whether a given object is coercible to a SLI array
-
nest.lib.hl_api_helper.
is_iterable
(seq)¶ Return True if the given object is an iterable, False otherwise.
-
nest.lib.hl_api_helper.
is_literal
(obj)¶ Check whether obj is a “literal”: a unicode string or SLI literal
-
nest.lib.hl_api_helper.
is_sequence_of_connections
(seq)¶ Checks whether low-level API accepts seq as a sequence of connections.
-
nest.lib.hl_api_helper.
is_sequence_of_gids
(seq)¶ Checks whether the argument is a potentially valid sequence of GIDs (non-negative integers).
-
nest.lib.hl_api_helper.
is_string
(obj)¶ Check whether obj is a unicode string
-
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.
-
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.
-
nest.lib.hl_api_helper.
show_help_with_pager
(hlpobj, pager=None)¶ Output of doc in python with pager or print
-
nest.lib.hl_api_helper.
to_json
(data)¶ Serialize data to JSON.