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:
-
denest.
run
(path, *overrides, output_dir=None, input_dir=None)¶ Run the simulation specified by the parameters at
path
.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.
Keyword Arguments: - input_dir (str | None) –
None
or the path to the input. Passed toSimulation
. If defined, overrides theinput_dir
simulation parameter. - output_dir (str | None) – None or the path to the output directory.
Passed to
Simulation
If defined, overrides theoutput_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 ofself.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 ofself.tree
-
init_kernel
(kernel_tree)¶ Initialize the NEST kernel.
- Call
nest.SetKernelStatus
withnest_params
- Set NEST kernel
data_path
and seed - Install extension modules
Adds
kernel_tree
as the'kernel'
child ofself.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 tonest.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.- Call
-
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 theirtype
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, theparams
of which may contain aprojections
key specifying all the individual population-to-population projections within the network as a list.Projection
objects are created from thetopology
parameters by theNetwork.build_projections()
method. Refer to this method for a description of thetopology
parameter.recorders
(ParamsTree
)- :class:
ParamsTree
object without children, theparams
of which may contain apopulation_recorders
and aprojection_recorders
key specifying all the network recorders.PopulationRecorder
andProjectionRecorder
objects are created from therecorders
parameters by theNetwork.build_recorders()
method. Refer to this method for a description of therecorders
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 aModel
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
orInputLayer
objecs depending on the value of thetype
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 thetopology
tree.Initialize
self.projections
with a list ofProjection
objects.Parameters: topology_tree (tree-like or ParamsTree) – Tree-like or
ParamsTree
without children, the parameters of which may contain aprojections
parameter entry. (Default:[]
). The value of theprojections
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 theprojection_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>
areNone
or the name of source and target populations for the created projection. IfNone
, 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 callsNetwork.build_population_recorders()
andNetwork.build_projection_recorders()
to initialize theNetwork.population_recorders()
andNetwork.projection_recorders()
attributes.Parameters: recorders_tree (tree-like or ParamsTree) – Tree-like or ParamsTree
object without children nornest_params
, the parameters of which may contain apopulation_recorders
(default:[]
) and aprojection_recorders
(default:[]
) entry specifying the network’s recorders. Thepopulation_recorders
andprojection_recorders
entries are passed toNetwork.build_population_recorders()
andNetwork.build_projection_recorders()
respectively.Returns: (list( PopulationRecorder
), list(ProjectionRecorder
))
-
get_recorders
(recorder_class=None, recorder_type=None)¶ Yield all
PopulationRecorder
andProjectionRecorder
objects.Parameters: - recorder_class (str or None) – Class of queried recorders.
"PopulationRecorder"
,"ProjectionRecorder"
orNone
. - recorder_type (str or None) – Type of queried recorders.
'multimeter'
,'spike_detector'
or'projection_recorder'
.
- recorder_class (str or None) – Class of queried recorders.
-
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 tonest.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. IfNone
, 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. IfNone
, 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 frominput_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 inparam_change
is used to set the<param_name>
parameter for all the population’s units.
- If
'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']
. Theelements
parameter is reserved. Please use thepopulations
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
- population (str) – Matches population name that has
-
shape
¶ Return layer shape (eg
(nrows, ncols)
)
-
layer_shape
¶ Return layer shape (eg
(nrows, ncols)
)
-
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
andnest_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
.