DeNSE¶

This page provides an overview of the DeNSE package.

For more information on the installation procedure, please see Installing the library.

We suggest starting with the @TODO TUTORIAL, before coming back to this page. Once you are familiar with the basic function of DeNSE, additional details can be found on the following pages:

Though the core of the simulator is written in C++ for efficiency, all relevant functions to create, configure and inspect objects are coded in python for convenience.

Example¶

import dense as ds
from dense.units import *

neuron = ds.create_neurons(params={"position": (0, 1)*um})

Content¶

`dense.create_neurites`(neurons[, ...])	Create neurites on the specified neurons.
`dense.create_neurons`([n, params, ...])	Create n neurons with specific parameters.
`dense.create_recorders`(targets, observables)	Create recorders to monitor the state of target neurons in the environment.
`dense.delete_neurites`([neurite_names, neurons])	Delete neurites.
`dense.delete_neurons`([neurons])	Delete neurons.
`dense.generate_model`(elongation, steering, ...)	Returns a Model object giving the method to use for each of the three main properties:
`dense.generate_simulation_id`(*args)	Generate the Hash from the elements passed and add date and time of the kernel initialization.
`dense.get_default_properties`(obj[, ...])	Returns the default status of an object.
`dense.get_environment`()	Return the environment as a `Shape` object.
`dense.get_kernel_status`([property_name])	Get the configuration properties.
`dense.get_models`([abbrev])	Get available models for an object type.
`dense.get_neurons`([as_ints])	Return the existing neurons
`dense.get_object_properties`(obj[, ...])	Return the object's properties.
`dense.get_object_state`(obj[, observable, ...])	Return the state of a neuron or neurite at the current time.
`dense.get_object_type`(gid)	Return the type of the object associated to gid.
`dense.get_recording`(recorder[, record_format])	Return the recorded data.
`dense.get_simulation_id`()	Get the identifier for the simulation
`dense.reset_kernel`()	Reset the whole simulator.
`dense.set_kernel_status`(status[, value, ...])	Set the simulator's configuration.
`dense.set_neurite_properties`(neuron, ...)	Set the status of a specific neurite on a specific neuron.
`dense.set_object_properties`(objects[, ...])	Update the status of the objects using the parameters contained in params.
`dense.simulate`(time[, force_resol])	Simulate the growth of the neurons.

Python/cython interface to the growth C++ code

dense.create_neurites(neurons, num_neurites=1, params=None, angles=None, names=None)[source]¶

Create neurites on the specified neurons.

Neurite types (axon or dendrite) are based on the neurite names: axon must always be named “axon”, all other names will be associated to a dendrite.

Parameters

neurons (Neuron, list, or GIDs) – Neurons on which neurites should be created.
num_neurites (int, optional (default: 1)) – Number of neurites that will be added to each neuron.
params (dict, optional (default: None)) – Parameters of the neurites.
angle (list, optional (default: automatically positioned)) – Angles of the newly created neurites.
names (list, optional (default: "axon" and "dendrite_X")) – Names of the created neurites, if not provided, will an “axon” or a dendrite with default name “dendrite_X” (X being a number) will be created, depending on whether the neuron is supposed to have an axon or not, and depending on the number of pre-existing neurites.

Note

When using this function, the same number and types of neurites will be created for each neuron; to create varying numbers, types, or relative angles for the neurites, the function must be called separately on the different sets of neurons.

dense.create_neurons(n=1, params=None, num_neurites=0, neurite_params=None, neurite_names=None, culture=None, on_area=None, neurites_on_area=False, return_ints=False, **kwargs)[source]¶

Create n neurons with specific parameters.

Parameters

n (int, optional (default: 1)) –
params (dict, optional (default: None)) – Parameters of the object (or shape object for obstacle).
neurite_params (dict, optional (default: same as params)) – Specific parameters for neurite growth. Entries of the dict can be lists to give different parameters for the neurites of each neuron. To provide different parameters for each neurite, one can provide neurite_params as a dict of dict, with the neurite names as keys.
num_neurites (int, optional (default: 0)) – Number of neurites (same for all neurons).
neurite_names (list, optional (default: None)) – Names of the neurites. If not provided, defaults to keys of dendrite_params. If dendrite_params is also empty, defaults to [“axon”, “dendrite_1”, dendrite_2”, …] (without “axon” if the neurite has “has_axon” set to False).
culture (Shape, optional (default: existing environment if any)) – Spatial environment where the neurons will grow.
on_area (str or list, optional (default: everywhere in culture)) – Restrict the space where neurons will be randomly seeded to an area or a set of areas.
neurites_on_area (bool, str, area, or list, optional (default: False)) – Restrict the points where neurites will extend from the soma. This is typically used to account for the fact that, when seeded on patterned surfaces, neurons will extend their neurites only on the patterns. If True, then on_area must be set and the same area will be used. If False, neurite are not constrained.
return_ints (bool, optional (default: False)) – Whether the neurons are returned as Neuron objects or simply as integers (the neuron gids).

Returns

neurons – By default, returns a Neuron object if a single neuron is requested, a Popuulation if several neurons are created, or a tuple of the neurons’ GIDs if return_ints is True.

Return type

Neuron, Population, or ints

Example

Creating one neuron:

neuron_prop = {
    "position": (5., 12.)*um,
    "description": "my_special_neuron"
}

neurite_prop = {
    "axon": {
        "speed_growth_cone": 1.*um/hour,
        "persistence_length": 300.*um
    },
    "dendrite_1": {"speed_growth_cone": 0.2*um/hour},
    "dendrite_2": {"speed_growth_cone": 0.3*um/hour}
}

neuron = ds.create_neurons(params=neuron_prop,
                           num_neurites=3, # axon + 2 dendrites
                           neurite_params=neurite_prop)

Note

When specifying num_neurites, the first neurite created is an axon unless has_axon is set to False, the subsequent neurites are dendrites. If has_axon is set to False, then only dendrites are created.

dense.create_recorders(targets, observables, sampling_intervals=None, start_times=None, end_times=None, levels='auto', restrict_to=None, record_to='memory', buffer_size=100)[source]¶

Create recorders to monitor the state of target neurons in the environment. One recorder is created on each thread containing target neurons for every observable.

Note

One recorder records only from the neurons located on the same thread. This means that, when using multithreading, several recorders might be created even for only one observable if the target neurons are handled by several different threads.

Note

For observables that are available at different levels, the recording at the upper levels is the sum of the values at the lower levels. E.g. for “length”, the neurite level give the sum of all branch lengths and the neuron level the sum of all neurite lengths.

Parameters

targets (int or array of ints) – Gids of the neurons to record from.
observables (string or list of strings) – Names of the properties that will be recorded for each of the target neurons. One recorder will be in charge of only one observable. (see below for the list of possible observables)
sampling_intervals (int or list of ints, optional (default: resolution)) – Interval between two successive recordings for a continuous observable, expressed in seconds. Must be a multiple of the resolution for the current simulation.
start_times (Time or list of Times, optional (default: initial time)) – Time at which the recording should start. (not implemented yet)
end_times (Time or list of Times, optional (default: final time)) – Time at which the recording should stop. (not implemented yet)
levels (string or list of strings, optional (default: "auto")) – Level at which the observable should be recorded, if several levels are possible (e.g. “length” can be measure at the “growth_cone”, “neurite”, or full “neuron” level, each higher level being the sum of its sublevels).
restrict_to (string or list of strings, optional (default: None)) – Restrict recording to a specific neurite, either “axon” or one of the dendrites (“dendriteX”, with X the dendrite number).
record_to (string or list of strings (default: "memory")) – Where the recordings should be stored. Default is in memory, otherwise a filename can be passed, to which the recording will be saved.
buffer_size (int or list of ints, optional (default: 100)) – Number of measurements that will be kept in memory before the recorder writes to the file. Only used if record_to contains a filename.

Returns

recorders – Gids of the recorders created. recorders contains one entry per value in observables since at least recorder in created for each observable.

Return type

tuple

See also

generate_model()

dense.get_neurons(as_ints=False)[source]¶

Return the existing neurons

Parameters

as_ints (bool, optional (default: False)) – Whether only the ids of the neurons should be returned instead of Neuron objects. Useful for large simulations to reduce the memory footprint.

Returns

A (class:~dense.elements.Population` object if several neurons are created,)
a Neuron if a single neuron is created, or a tuple
of ints if as_ints is True.

dense.get_object_properties(obj, property_name=None, level=None, neurite=None, settables_only=False, return_iterable=False)[source]¶

Return the object’s properties.

Parameters

obj (Neuron, list of neurons/gids, Neurite or list of neurites) – Elements for which the state will be returned.
property_name (str, optional (default: None)) – Name of the property that should be queried. By default, the full dictionary is returned.
level (str, optional (default: highest)) – Level at which the status should be obtained (only for neurons). Should be among “neuron”, “neurite”, or “growth_cone”.
neurite (str optional (default: None)) – Neurite of neurons gids that should be queried (either axon or dendrites). By default, both dictionaries are returned inside the neuronal status dictionary. If neurite is specified, only the parameters of this neurite will be returned.
settables_only (bool, optional (default: False)) – Return only settable values; read-only values are hidden.
return_iterable (bool, optional (default: False)) – If true, returns a dict or an array, even if only one gid is passed.

Returns

status – Properties of the objects’ status:

single value if gids contained only one node and property_name was specified (unless return_iterable is True)
dict if gids contained only one node and property_name was not specified.
array of values if gids contained several nodes and property_name was specified.
array of ``dict``s if gids contained several nodes and property_name was not specified.

Return type

variable

dense.get_object_state(obj, observable=None, level=None, return_iterable=False)[source]¶

Return the state of a neuron or neurite at the current time.

Parameters

obj (Neuron, list of neurons/gids, Neurite or list of neurites) – Elements for which the state will be returned.
observable (str, optional (default: all observables)) – Name of the property that should be queried.
level (str, optional (default: "neuron")) – Level at which the status should be obtained (either “neuron”, “axon”, or a specific dendrite name). This entry is valid only if obj is a neuron or a list of neurons.
return_iterable (bool, optional (default: False)) – If true, returns a dict or an array, even if only one gid is passed.

Returns

state

Return type

float or list of floats

dense.get_object_type(gid)[source]¶

Return the type of the object associated to gid. An error is thrown if the GID does not exist.

Parameters: gid (int) – The object GID in the simulator
Returns
Return type: A string describing the object, e.g. “neuron” or “recorder”.

dense.get_recording(recorder, record_format='detailed')[source]¶

Return the recorded data.

Parameters

recorder (gid or list of gids) – Id(s) of the recorder(s).
record_format (str, optional (default: "detailed")) – Formatting of the record. This is only useful if the recording occurs at neurite or growth cone level. If “detailed”, is used, the record dict first contains all neurons ids; each entry is then a new dict with the neurite ids as entries; if level is “growth_cone”, then there is a final dict with the growth cone ids as entries. If “compact” is used, only one id per recorded item is used; for growth cones.

Examples

At neurite level:

>>> get_recording(rec)
>>> {
>>>     observable: {
>>>         neuron0: {"axon": [...], "dendrite1": [...], ...},
>>>         neuron1: {"axon": [...], "dendrite1": [...], ...}, ...
>>>     },
>>>     "times": [...]
>>> }

>>> get_recording(rec, "compact")
>>> {
>>>     observable: {
>>>         "data": {
>>>             (neuron0, "axon"): [...],
>>>             (neuron0, "dendrite1"): [...], ...
>>>             (neuron1, "axon"): [...], ...
>>>          },
>>>          "times": [...]}
>>>     }
>>> }

dense.get_simulation_id()[source]¶: Get the identifier for the simulation

dense.reset_kernel()[source]¶: Reset the whole simulator.

dense.set_kernel_status(status, value=None, simulation_id=None)[source]¶

Set the simulator’s configuration.

Parameters

status (dict or string) – Dictionary containing the configuration options.
value (object, optional (default: None)) – Used to set a single value.
simulation_id (str) – Unique identifier of the simulation, generally simulation_id = Hash(kernel_status, params)

Note

Available options are:

"adaptive_timestep" (float) - Value by which the step should be divided when growth cones are interacting. Set to -1 to disable adaptive timestep.
"environment_required" (bool) - Whether a spatial environment should be provided or not.
"interactions" (bool) - Whether neurites interact with one another.
"max_allowed_resolution" (time) - Maximum timestep allowed.
"num_local_threads" (int) - the number of OpenMP thread per MPI process.
"print_time" (bool) - whether time should be printed during the simulation.
"resolution" (time) - the simulation timestep.
"seeds" (array) - array of seeds for the random number generators (one per processus, total number needs to be the same as num_virtual_processes)

dense.set_neurite_properties(neuron, neurite, params)[source]¶

Set the status of a specific neurite on a specific neuron.

Parameters

neuron (Neuron or int) – Neuron containing the neurite to update.
neurite (Neuron or str) – Neurite to update.
params (dict) – Parameters of the neurite.

dense.set_object_properties(objects, params=None, neurite_params=None)[source]¶

Update the status of the objects using the parameters contained in params.

Parameters

objects (object or int) – Objects to update (either neurons or recorders).
params (dict, optional (default: None)) – New parameters of the objects.
neurite_params (dict, optional (default: None)) – New neurite parameters if objects are neurons.

dense.simulate(time, force_resol=False)[source]¶

Simulate the growth of the neurons.

Parameters: time (float or int (dimensionned quantity)) – Duration of the simulation.