User interface¶

These are the main functions and classes that comprise deNEST’s user interface.

`load_trees`(path, *overrides)	Load a list of parameter files, optionally overriding some values.
`run`(path, *overrides[, output_dir, input_dir])	Run the simulation specified by the parameters at `path`.
`Simulation`([tree, input_dir, output_dir])	Represents a simulation.
`Session`(name, params[, start_time, input_dir])	Represents a sequence of stimuli.
`Network`([tree])	Represent a full network.
`network.Layer`(name, params, nest_params)	Represents a NEST layer composed of populations of units
`ParamsTree`([mapping, parent, name, validate])	A tree of nodes that inherit and override ancestors’ data.

deNEST: a declarative frontend for NEST

denest.load_trees(path, *overrides)¶

Load a list of parameter files, optionally overriding some values.

Parameters:	path (str) – The filepath to load. overrides (tree-like*) – Variable number of tree-like parameters that should override those from the path. Last in list is applied first.
Returns:	The loaded parameter tree with overrides applied.
Return type:	ParamsTree

denest.run(path, *overrides, output_dir=None, input_dir=None)¶

Run the simulation specified by the parameters at path.

Keyword Arguments:
Parameters:	path (str) – The filepath of a parameter file specifying the simulation. overrides (tree-like*) – Variable number of tree-like parameters that should override those from the path. Last in list is applied first.
	input_dir (str \| None) – `None` or the path to the input. Passed to `Simulation`. If defined, overrides the `input_dir` simulation parameter. output_dir (str \| None) – None or the path to the output directory. Passed to `Simulation` If defined, overrides the `output_dir` simulation parameter.

class denest.Simulation(tree=None, input_dir=None, output_dir=None)¶

Represents a simulation.

Handles building the network, running it with a series of sessions, and saving output.

Parameters:

tree (ParamsTree) –

Full simulation parameter tree. The following ParamsTree subtrees are expected:

simulation (ParamsTree)

Defines input and output paths, and the simulation steps performed. The following parameters (params field) are recognized:

output_dir (str)

Path to the output directory. (Default: 'output')

input_dir (str)

Path to the directory in which input files are searched for for each session. (Default: 'input')

sessions (list[str])

Order in which sessions are run. Elements of the list should be the name of session models defined in the session_models parameter subtree. (Default: [])

kernel (ParamsTree)

Used for NEST kernel initialization. Refer to Simulation.init_kernel() for a description of kernel parameters.

session_models (ParamsTree)

Parameter tree, the leaves of which define session models. Refer to Session for a description of session parameters.

network (ParamsTree)

Parameter tree defining the network in NEST. Refer to Network for a full description of network parameters.

Keyword Arguments:

input_dir (str | None) – None or the path to the input. If defined, overrides the input_dir simulation parameter.
output_dir (str | None) – None or the path to the output directory. If defined, overrides the output_dir simulation parameter.

Initialize simulation.

Set input and output paths
Initialize NEST kernel
Initialize and build Network in NEST
Create sessions
Save simulation metadata

create_network(network_tree)¶

Build and create the network.

Adds network_tree as 'network' child of self.tree

save_metadata(clear_output_dir=False)¶

Save simulation metadata.

Save parameters
Save deNEST git hash
Save sessions metadata (Session.save_metadata())
Save session times (start and end kernel time for each session)
Save network metadata (Network.save_metadata())

Keyword Arguments:
	clear_output_dir (bool) – If true, delete the contents of the output directory.

run()¶

Run simulation.

Run sessions in the order specified by the 'sessions' simulation parameter.

build_sessions(sessions_order)¶

Build a list of sessions.

Session params are inherited from session models.

build_session_models(tree)¶

Create session models from the leaves of a tree.

Adds tree as the 'session_models' child of self.tree

init_kernel(kernel_tree)¶

Initialize the NEST kernel.

Call nest.SetKernelStatus with nest_params
Set NEST kernel data_path and seed
Install extension modules

Adds kernel_tree as the 'kernel' child of self.tree.

Parameters:

kernel_tree (ParamsTree) –

Parameter tree without children. The following parameters (params field) are recognized:

extension_modules: (list(str))

List of modules to install. (Default: [])

nest_seed: (int)

Used to set NEST kernel’s RNG seed. (Default: 1)

NEST parameters (nest_params field) are passed to nest.SetKernelStatus. The following nest parameters are reserved: [data_path, 'grng_seed', 'rng_seed']. The NEST seeds should be set via the 'nest_seed' kernel parameter parameter.

class denest.Network(tree=None)¶

Represent a full network.

Parameters:

tree (ParamsTree) –

“network” parameter tree. The following children are expected:

neuron_models (ParamsTree): Parameter tree, the leaves of which define neuron models. Each leaf is used to initialize a Model object.
synapse_models (ParamsTree): Parameter tree, the leaves of which define synapse models. Each leaf is used to initialize a SynapseModel object.
layers (ParamsTree): Parameter tree, the leaves of which define layers. Each leaf is used to initialize a :class:Layer or :class:InputLayer object depending on the value of their type parameter.
projection_models (ParamsTree): Parameter tree, the leaves of which define projection models. Each leaf is used to initialize a :class:ProjectionModel object.
recorder_models (ParamsTree): Parameter tree, the leaves of which define recorder models. Each leaf is used to initialize a :class:Model object.
topology (ParamsTree): ParamsTree object without children, the params of which may contain a projections key specifying all the individual population-to-population projections within the network as a list. Projection objects are created from the topology parameters by the Network.build_projections() method. Refer to this method for a description of the topology parameter.
recorders (ParamsTree): :class:ParamsTree object without children, the params of which may contain a population_recorders and a projection_recorders key specifying all the network recorders. PopulationRecorder and ProjectionRecorder objects are created from the recorders parameters by the Network.build_recorders() method. Refer to this method for a description of the recorders parameter.

Initialize the network object without creating it in NEST.

build_neuron_models(tree)¶

Initialize self.neuron_models from the leaves of a tree.

Note

Overwrites the 'neuron_models' in the network’s parameters.

Parameters:	tree (tree-like or ParamsTree) – which define neuron models. Each leaf is used to initialize a `Model` object.

build_synapse_models(tree)¶

Initialize self.synapse_models from the leaves of a tree.

Note

Overwrites the 'synapse_models' in the network’s parameters.

Parameters:	tree (tree-like or ParamsTree) – which define neuron models. Each leaf is used to initialize a `SynapseModel` object.

build_recorder_models(tree)¶

Initialize self.recorder_models from the leaves of a tree.

Note

Overwrites the 'recorder_models' in the network’s parameters.

Parameters:	tree (tree-like or `ParamsTree`) – which define neuron models. Each leaf is used to initialize a `Model` object.

build_layers(tree)¶

Initialize self.layers from the leaves of a tree.

Note

Overwrites the 'layers' in the network’s parameters.

Parameters:	tree (tree-like or ParamsTree) – which define layers. Each leaf is used to initialize a `Layer` or `InputLayer` objecs depending on the value of the `type` parameter.

build_projection_models(tree)¶

Initialize self.projection_models from the leaves of a tree.

Note

Overwrites the 'projection_models' in the network’s parameters.

Parameters:	tree (tree-like or ParamsTree) – which define projection models. Each leaf is used to initialize a `ProjectionModel` object.

build_projections(topology_tree)¶

Initialize self.projections from the topology tree.

Initialize self.projections with a list of Projection objects.

Parameters:

topology_tree (tree-like or ParamsTree) –

Tree-like or ParamsTree without children, the parameters of which may contain a projections parameter entry. (Default: []). The value of the projections parameter is a list of items describing the projections to be created. Each item must be a dictionary of the following form:

{
    'projection_model' : <projection_model>,
    'source_layers': <source_layers_list>,
    'source_population': <source_population>,
    'target_layers': <target_layers_list>,
    'target_population': <target_population>,
}

where:

<projection_model> is the name of the projection model. Projection models are specified in the projection_models network parameter.
<source_layers_list> and <target_layers_list> are lists of source and target layer names. Projections are created for all (source_layer, target layer) pairs.
<source_population> and <target_population> are None or the name of source and target populations for the created projection. If None, all populations in the source or target layer are connected.

Together, <projection_model_name>, <source_layer_name>, <source_population_name>, <target_layer_name>, and <target_population_name> fully specify each individual projection and must be unique.

build_recorders(recorders_tree)¶

Initialize recorders from tree.

Validates the recorders parameter tree and calls Network.build_population_recorders() and Network.build_projection_recorders() to initialize the Network.population_recorders() and Network.projection_recorders() attributes.

Parameters: recorders_tree (tree-like or ParamsTree) – Tree-like or ParamsTree object without children nor nest_params, the parameters of which may contain a population_recorders (default: []) and a projection_recorders (default: []) entry specifying the network’s recorders. The population_recorders and projection_recorders entries are passed to Network.build_population_recorders() and Network.build_projection_recorders() respectively.

Returns: (list(PopulationRecorder), list(ProjectionRecorder))

get_recorders(recorder_class=None, recorder_type=None)¶

Yield all PopulationRecorder and ProjectionRecorder objects.

Parameters:	recorder_class (str or None) – Class of queried recorders. `"PopulationRecorder"`, `"ProjectionRecorder"` or `None`. recorder_type (str or None) – Type of queried recorders. `'multimeter'`, `'spike_detector'` or `'projection_recorder'`.

static change_synapse_states(synapse_changes)¶

Change parameters for some projections of a population.

Parameters:

synapse_changes (list) –

List of dictionaries each of the form:

{
    'synapse_model': <synapse_model>,
    'params': {<param1>: <value1>}
}

where the dictionary in params is passed to nest.SetStatus() to set the parameters for all projections with synapse model <synapse_model>.

set_state(unit_changes=None, synapse_changes=None, input_dir=None)¶

Set the state of some units and synapses.

Parameters:

unit_changes (list) –

List of dictionaries specifying the changes applied to the networks units:

{
    'layers': <layer_name_list>,
    'population': <pop_name>,
    'change_type': <change_type>,
    'from_array': <from_array>,
    'nest_params': {
        <param_name>: <param_change>,
    },
}

where <layer_name_list> and <population_name> specify all the individual populations to which the changes are applied:

<layer_name_list> (list(str) | None) is the list of names of the considered layers. If None, the changes may be applied to populations from all the layers. (Default: [])
<population_name> (str | None) is the name of the considered population in each layer. If None, changes are applied to all the populations of each considered layer. (Default: None)

and <change_type>, <from_array> and 'nest_params' specify the changes applied to units from each of those populations:

<change_type> (‘constant’, ‘multiplicative’ or ‘additive’). If ‘multiplicative’ (resp. ‘additive’), the set value for each unit and parameter is the product (resp. sum) between the preexisting value and the given value. If ‘constant’, the given value for each unit is set without regard for the preexisting value. (Default: 'constant')
<from_array> (bool) specifies how the <param_change> value given for each parameter is interpreted:
- If True, param_change should be a numpy array or the relative path from input_dir to a numpy array. The given or loaded array should have the same dimension as the considered population, and its values are mapped to the population’s units to set the <param_name> parameter.
- If False, the value in param_change is used to set the <param_name> parameter for all the population’s units.
'nest_params' (Default: {}) is the dictionary specifying the parameter changes applied to the population units. Items are the name of the modified NEST parameters (<param_name>) and the values set (<param_change>). The <change_type> and <from_array> parameters specify the interpretation of the <param_change> value.

Examples

>>> # Load parameter files and create the network object
>>> import denest
>>> network = denest.Network(denest.ParamsTree.read('<path_to_parameter_file>'))

>>> # Instantiate the network in the NEST kernel
>>> network.create()

>>> # Set the same spike times for all the units of a population of spike
... # generators
>>> network.set_state({
...     'layers': ['input_layer'],
...     'population_name': 'spike_generator',
...     'change_type': 'constant',
...     'from_array': False,
...     'nest_params': {'spike_times': [1.0, 2.0, 3.0]}
... })

>>> # Set the voltage from values for multiple 2x2 population of neurons: specify
... # the array directly
>>> voltages = np.array([[-70.0, -65.0], [-70.0, -65.0]])
>>> network.set_state({
...     'layers': ['l1', 'l2'],
...     'population_name': None,
...     'change_type': 'constant',
...     'from_array': True,
...     'nest_params': {'V_m': voltages}
... })

>>> # Set the voltage from values for a 2x2 population of neurons: pass
... # the path to the array
>>> np.save(voltages, './voltage_change.npy')
>>> network.set_state({
...     'layers': ['l1'],
...     'population_name': 'l1_exc',
...     'change_type': 'constant',
...     'from_array': True,
...     'nest_params': {'V_m': './voltage_change.npy'}
... })

>>> # Multiply the leak potential by 2 for all the units
>>> network.set_state({
...     'layers': ['l1'],
...     'population_name': 'l1_exc',
...     'change_type': 'multiplicative',
...     'from_array': False,
...     'nest_params': {'g_peak_AMPA': 2.0}
... })

save_metadata(output_dir)¶

Save network metadata.

Save recorder metadata

populations_by_gids(layer_type='Layer')¶: Return a dict of the form {'gid': (layer_name, pop_name)}.

class denest.network.Layer(name, params, nest_params)¶

Represents a NEST layer composed of populations of units

Parameters:

name (str) – Name of the layer
params (dict-like) –
Dictionary of parameters. The following parameters are expected:

populations (dict): Dictionary of the form ``{<model>: <number>}

specifying the elements within the layer. Analogous to the elements nest.Topology parameter
nest_params (dict-like) – Dictionary of parameters that will be passed to NEST during the nest.CreateLayer call. The following parameters are mandatory: ['rows', 'columns']. The elements parameter is reserved. Please use the populations parameter instead to specify layer elements.

create()¶: Create the layer in NEST and update attributes.

gids(population=None, location=None, population_location=None)¶

Return element GIDs, optionally filtered by population/location.

Parameters:	population (str) – Matches population name that has `population` as a substring. location (tuple[int]) – The location within the layer to filter by. population_location (tuple[int]) – The location within the population to filter by.
Returns:	The GID(s).
Return type:	list

shape¶: Return layer shape (eg (nrows, ncols))

layer_shape¶: Return layer shape (eg (nrows, ncols))

population_shapes¶

(nrows, ncols, nunits)``

Type:	Return population shapes
Type:	``{<pop_name>

locations¶

index}`` dict of locations within the layer.

Type:	Return ``{<gid>

population_locations¶

index}`` dict of locations within the population.

There’s an extra (last) dimension for the population locations compared to the [layer] locations, corresponding to the index of the unit within the population.

Type:	Return ``{<gid>

population_names¶: Return a list of population names within this layer.

recordable_population_names¶: Return list of names of recordable population names in this layer.

class denest.ParamsTree(mapping=None, parent=None, name=None, validate=True)¶

A tree of nodes that inherit and override ancestors’ data.

A tree is created from a tree-like mapping. The key-value pairs containing the node’s data are defined in self.DATA_KEYS (params and nest_params). Data is inherited from ancestors for each of those keys. Note that the order of traversals is undefined.

Keyword Arguments:
	mapping (Mapping) – A dictionary-like object that maps names to children, but with special key-value pairs containing the node’s data. Defaults to an empty dictionary. parent (ParamsTree) – The parent tree. Data from each of the data keys is inherited from ancestors.

name¶

Name of the node.

Type:	str \| None

children¶

A dictionary of named children.

Type:	dict

parent¶

The parent of this node.

Type:	type(self)

data¶

Dictionary containing the data accessible from this node (i.e., the node’s data and that inherited from its parents). Keys are values of self.DATA_KEYS ('params' and 'nest_params').

Type:	dict

params, nest_params

Contain the node data. Syntactic sugar to allow access to the node’s data.

Type:	dict-like

node_data¶: The data associated with this node (not inherited from parents).

parent: This node’s parent. None if node is the root.

name: This name of this node.

children: A dictionary of this node’s children

ancestors()¶

Return a list of ancestors of this node.

Doesn’t include self. More recent ancestors appear earlier in the list.

leaves(root=True)¶

Return a list of leaf nodes of the tree.

Traversal order is not defined. If root is False and there is not children, returns an empty list

named_leaves(root=True)¶

Return list of (<name>, <node>) tuples for all the leaves.

Traversal order is not defined. If root is False and there is not children, returns an empty list

classmethod merge(*trees, parent=None, name=None)¶

Merge trees into a new tree. Earlier trees take precedence.

If a node exists at the same location in more than one tree and these nodes have duplicate keys, the values from the nodes in the trees that appear earlier in the argument list will take precedence over those from later trees.

Equivalent nodes’ data is merged horizontally before hierarchical inheritance.

copy()¶: Copy this ParamsTree.

asdict()¶: Convert this ParamsTree to a nested dictionary.

classmethod read(path)¶: Load a YAML representation of a tree from disk.

write(path)¶: Write a YAML representation of a tree to disk.

validate(mapping, path=None)¶: Check that a mapping is a valid ParamsTree.