API reference¶
This section details the modules, classes, and functions available in NengoDL. It is divided into two sections. The first section describes the objects relevant to NengoDL users. For a more indepth description of how to use these objects, see the User guide. The second section describes objects that only NengoDL developers need to worry about.
Users¶
These objects are the main access points for the userfacing features of NengoDL.
Simulator¶
The Simulator class is the access point for the main features of NengoDL,
including running
and training
a model.

class
nengo_dl.simulator.
Simulator
(network, dt=0.001, seed=None, model=None, dtype=None, device=None, unroll_simulation=1, minibatch_size=None, tensorboard=None, progress_bar=True)[source]¶ Simulate network using the
nengo_dl
backend. Parameters
 network
Network
or None A network object to be built and then simulated. If None, then a built model must be passed to
model
instead dtfloat
Length of a simulator timestep, in seconds
 seedint
Seed for all stochastic operators used in this simulator
 model
Model
Prebuilt model object
 dtype
tf.DType
Deprecated, use
nengo_dl.configure_settings(dtype=...)
instead. deviceNone or
"/cpu:0"
or"/gpu:[0n]"
Device on which to execute computations (if None then uses the default device as determined by TensorFlow)
 unroll_simulationint
Unroll simulation loop by explicitly building the given number of iterations into the computation graph (improves simulation speed but increases build time)
 minibatch_sizeint
The number of simultaneous inputs that will be passed through the network
 tensorboardstr
If not None, save network output in the TensorFlow summary format to the given directory, which can be loaded into TensorBoard
 progress_barbool
If True (default), display progress information when building a model
 network

reset
(self, seed=None)[source]¶ Resets the simulator to initial conditions.
 Parameters
 seedint
If not None, overwrite the default simulator seed with this value (note: this becomes the new default simulator seed)

soft_reset
(self, include_trainable=False, include_probes=False)[source]¶ Resets the internal state of the simulation, but doesn’t rebuild the graph.
 Parameters
 include_trainablebool
If True, also reset any training that has been performed on network parameters (e.g., connection weights)
 include_probesbool
If True, also clear probe data

step
(self, **kwargs)[source]¶ Run the simulation for one time step.
 Parameters
 kwargsdict
See
run_steps
Notes
Progress bar is disabled by default when running via this method.

run
(self, time_in_seconds, **kwargs)[source]¶ Simulate for the given length of time.
 Parameters
 time_in_secondsfloat
Run the simulator for the given number of simulated seconds
 kwargsdict
See
run_steps

run_steps
(self, n_steps, data=None, input_feeds=None, profile=False, progress_bar=True, extra_feeds=None)[source]¶ Simulate for the given number of steps.
 Parameters
 n_stepsint
The number of simulation steps to be executed
 datadict of {
Node
:ndarray
} Override the values of input Nodes with the given data. Arrays should have shape
(sim.minibatch_size, n_steps, node.size_out)
. input_feedsdict of {
Node
:ndarray
} Deprecated, use
data
instead. profilebool
If True, collect TensorFlow profiling information while the simulation is running (this will slow down the simulation). Can also pass a string specifying a nondefault filename for the saved profile data.
 progress_barbool
If True, print information about the simulation status to standard output.
 extra_feedsdict of {
tf.Tensor
:ndarray
} Can be used to feed a value for arbitrary Tensors in the simulation (will be passed directly to the TensorFlow session)
Notes
If
unroll_simulation=x
is specified, andn_steps > x
, this will repeatedly executex
timesteps until the the number of steps executed is >=n_steps
.

train
(self, data, optimizer, n_epochs=1, objective=None, shuffle=True, truncation=None, summaries=None, profile=False, extra_feeds=None, progress_bar=True)[source]¶ Optimize the trainable parameters of the network using the given optimization method, minimizing the objective value over the given inputs and targets.
 Parameters
 datadict of {
Node
orProbe
:ndarray
} or int Input values for Nodes in the network or target values for Probes; arrays should have shape
(batch_size, n_steps, node.size_out/probe.size_in)
. If no input data is required, an integer can be given specifying the number of timesteps to run the simulation. optimizer
tf.train.Optimizer
TensorFlow optimizer, e.g.
tf.train.GradientDescentOptimizer(learning_rate=0.1)
 n_epochsint
Run training for the given number of epochs (complete passes through
data
) objectivedict of {(tuple of)
Probe
: callable orNone
} The objective to be minimized. The default applies
objectives.mse
to all probes indata
. This can be overridden by passing a dictionary mapping Probes to functionsf(output, target) > loss
that consume the actual output and target output for the given probe(s) and return atf.Tensor
representing a scalar loss value. The function may also accept a single argumentf(output) > loss
if targets are not required. Some common objective functions can be found innengo_dl.objectives
.Passing
None
as the probe value (instead of a callable) indicates that the error is being computed outside the simulation, and the value passed for that probe indata
directly specifies the output error gradient.If multiple probes are specified as the key, then the corresponding output/target values will be passed as a list to the objective function.
The overall loss value being minimized will be the sum across all the objectives specified.
 shufflebool
If True, randomize the data into different minibatches each epoch
 truncation: int
If not None, use truncated backpropagation when training the network, with the given truncation length.
 summarieslist of
Connection
orEnsemble
orNeurons
or"loss"
ortf.Tensor
If not None, collect data during the training process using TensorFlow’s
tf.summary
format. The summary objects can be a Connection (in which case data on the corresponding weights will be collected), Ensemble (encoders), Neurons (biases), or"loss"
(the loss value forobjective
). The user can also create their own summaries and pass in the Tensors representing the summary ops. profilebool
If True, collect TensorFlow profiling information while the simulation is running (this will slow down the simulation). Can also pass a string specifying a nondefault filename for the saved profile data.
 extra_feedsdict of {
tf.Tensor
:ndarray
} Can be used to feed a value for arbitrary Tensors in the simulation (will be passed directly to the TensorFlow session)
 progress_barbool
If True, print information about the simulation status to standard output.
 datadict of {
Notes
Most deep learning methods require the network to be differentiable, which means that trying to train a network with nondifferentiable elements will result in an error. Examples of common nondifferentiable elements include
LIF
,Direct
, or processes/neurons that don’t have a custom TensorFlow implementation (seeprocess_builders.SimProcessBuilder
/neuron_builders.SimNeuronsBuilder
)

loss
(self, data, objective=None, combine=<function mean at 0x7f9a5e884268>, extra_feeds=None, progress_bar=True, training=False)[source]¶ Compute the loss value for the given objective and inputs/targets.
 Parameters
 datadict of {
Node
orProbe
:ndarray
} or int Input values for Nodes in the network or target values for Probes; arrays should have shape
(batch_size, n_steps, node.size_out/probe.size_in)
. If no input data is required, an integer can be given specifying the number of timesteps to run the simulation. objectivedict of {(tuple of)
Probe
: callable} The objective to compute the loss. The default applies
objectives.mse
to all probes indata
. This can be overridden by passing a dictionary mapping Probes to functionsf(output, target) > loss
that consume the actual output and target output for the given probe(s) and return atf.Tensor
representing a scalar loss value. The function may also accept a single argumentf(output) > loss
if targets are not required. Some common objective functions can be found innengo_dl.objectives
.If multiple probes are specified as the key, then the corresponding output/target values will be passed as a list to the objective function.
The overall value returned will be the sum across all the objectives specified.
 combinecallable
Function used to combine objective values from each minibatch.
 extra_feedsdict of {
tf.Tensor
:ndarray
} Can be used to feed a value for arbitrary Tensors in the simulation (will be passed directly to the TensorFlow session)
 progress_barbool
If True, print information about the simulation status to standard output.
 trainingbool
If True, run the network in training mode (where, e.g., spiking neuron models are swapped for the equivalent differentiable approximation).
 datadict of {
 Returns
 lossfloat
Sum of computed error values for each function in
objective
.

run_batch
(self, data, outputs, extra_feeds=None, extra_fetches=None, n_epochs=1, truncation=None, shuffle=False, profile=False, training=False, callback=None, combine=<function stack at 0x7f9a5e7f78c8>, isolate_state=True)[source]¶ Run the simulation on a batch of input data, computing the given output functions.
 Parameters
 datadict of {
Node
orProbe
:ndarray
} or int Input values for Nodes in the network or target values for Probes; arrays should have shape
(batch_size, n_steps, node.size_out/probe.size_in)
. If no input data is required, an integer can be given specifying the number of timesteps to run the simulation. outputsdict of {(tuple of)
Probe
: callable or None} Functions to apply to probe outputs. Functions can accept one positional argument (the output from that probe on one minibatch) or two (also passed the corresponding target value from
data
). If a tuple of Probes are given as the key then the first argument will be a list of probe outputs, and the second argument will be the corresponding list of target values. The function can return atf.Tensor
, or tuple of Tensors, which will be evaluated on each minibatch of data. IfNone
is given then the return value will be the output value from that probe. extra_feedsdict of {
tf.Tensor
:ndarray
} Can be used to feed a value for arbitrary Tensors in the simulation (will be passed directly to the TensorFlow session)
 extra_fetches(list/tuple/dict of)
tf.Tensor
Can be used to fetch arbitrary (structures of) Tensor values from the simulation (will be fetched directly from the TensorFlow session).
 n_epochsint
Repeat
data
forn_epochs
iterations. truncationint
If not None, run the simulation
truncation
timesteps at a time. Outputs from each truncation block will be passed sequentially tocombine
, in the same way as minibatch blocks. Note that the simulation state is preserved between truncation blocks, so the sequence forms one continuous run within each minibatch. shufflebool
If True, randomize the data into different minibatches each epoch.
 profilebool
If True, collect TensorFlow profiling information while the simulation is running (this will slow down the simulation). Can also pass a string specifying a nondefault filename for the saved profile data.
 trainingbool
If True, run the network in training mode, otherwise run it in inference mode (this can affect things like the neuron model used).
 callbackcallable
A function that will be called after each minibatch is evaluated. The function is passed two arguments; the first is a dictionary corresponding to
outputs
with the output values from each function, and the second is the value ofextra_feeds
. combinecallable
The function that will be used to combine the outputs from each minibatch/truncation block. The values from each output function on each minibatch will be formed into a list and passed to
combine
in order to compute the final return values from this function. Note that if the output function returns multiple values, thencombine
will be applied separately to each of those outputs across the minibatches. isolate_statebool
If True (default), isolate the simulation state for this run from the rest of the simulation (so the execution of this run is not affected by previous runs and will not affect future runs). If False, then this run begins from the terminal state of the last run, each minibatch will continue in sequence from the state of the previous, and future runs will resume from the terminal state of the last minibatch of this run.
 datadict of {
 Returns
 output_valsdict of {(tuple of)
Probe
: (tuple of)ndarray
} The result of computing
outputs
on simulation probe values, givendata
. This pseudocode may help to understand how the return values are constructed given the various parameters of this function:output_vals = {} for probe, func in outputs.items(): probe_vals = [] for i in range(n_epochs): for minibatch in data: network_output = run_network(minibatch) probe_vals.append(func(network_output[probe])) output_vals[probe] = combine(output_values)
Note that this is not how the values are computed in practice, as it would be quite inefficient. This pseudocode also omits some of the finer details (e.g. truncation and state isolation).
 output_valsdict of {(tuple of)
Notes
In general, users should call one of the wrappers for this function (e.g.,
run_steps
,train
, orloss
), according to their use case. However, this function can be called directly to run the simulation in a customized way.

save_params
(self, path, include_global=True, include_local=False)[source]¶ Save network parameters to the given
path
. Parameters
 pathstr
Filepath of parameter output file
 include_globalbool
If True (default True), save global/trainable network variables
 include_localbool
If True (default False), save local (nontrainable) network variables
Notes
This function is useful for saving/loading entire models; for saving/loading individual objects within a model, see
get_nengo_params
.

load_params
(self, path, include_global=True, include_local=False)[source]¶ Load network parameters from the given
path
. Parameters
 pathstr
Filepath of parameter input file
 include_globalbool
If True (default True), load global (trainable) network variables
 include_localbool
If True (default False), load local (nontrainable) network variables
Notes
This function is useful for saving/loading entire models; for saving/loading individual objects within a model, see
get_nengo_params
.

freeze_params
(self, objs)[source]¶ Stores the live parameter values from the simulation back into a Nengo object definition.
This can be helpful for reusing a NengoDL model inside a different Simulator. For example:
with nengo.Network() as net: < build network > with nengo_dl.Simulator(net) as sim: < run some optimization > sim.freeze_params(net) with nengo.Simulator(net) as sim2: # run the network in the default Nengo simulator, with the # trained parameters sim2.run(1.0)
 Parameters
 obj(list of)
NengoObject
The Nengo object(s) into which parameter values will be stored. Note that these objects must be members of the Network used to initialize the Simulator.
 obj(list of)
Notes
This modifies the source object inplace, and it may slightly modify the structure of that object. The goal is to have the object produce the same output as it would if run in the NengoDL simulator. It may not be possible to accurately freeze all possible object; if you run into errors in this process, try manually extracting the parameters you need in your model (from
sim.data
).

get_nengo_params
(self, nengo_objs, as_dict=False)[source]¶ Extract model parameters in a form that can be used to initialize Nengo objects in a different model.
For example:
with nengo.Network() as net: a = nengo.Ensemble(10, 1) b = nengo.Ensemble(10, 1) c = nengo.Connection(a, b) with nengo_dl.Simulator(net) as sim: # < do some optimization > params = sim.get_nengo_params([a, b, c]) with nengo.Network() as new_net: # < build some other network > # now we want to insert two connected ensembles with # the same parameters as our previous network: d = nengo.Ensemble(10, 1, **params[0]) e = nengo.Ensemble(10, 1, **params[1]) f = nengo.Connection(d, e, **params[2])
 Parameters
 nengo_objs(list of)
Ensemble
orConnection
A single object or list of objects for which we want to get the parameters.
 as_dictbool
If True, return the values as a dictionary keyed by object label, instead of a list (the default). Note that in this case labels must be unique.
 nengo_objs(list of)
 Returns
 params(list or dict) of dicts
kwarg dicts corresponding to
nengo_objs
(passing these dicts as kwargs when creating new Nengo objects will result in a new object with the same parameters as the source object). A single kwarg dict if a single object was passed in, or a list (dict ifas_dict=True
) of kwargs corresponding to multiple input objects.

check_gradients
(self, outputs=None, atol=1e05, rtol=0.001)[source]¶ Perform gradient checks for the network (used to verify that the analytic gradients are correct).
Raises a simulation error if the difference between analytic and numeric gradient is greater than
atol + rtol * numeric_grad
(elementwise). Parameters
 outputs
tf.Tensor
or list oftf.Tensor
or list ofProbe
Compute gradients wrt this output (if None, computes wrt each output probe)
 atolfloat
Absolute error tolerance
 rtolfloat
Relative (to numeric grad) error tolerance
 outputs
Notes
Calling this function will reset all values in the network, so it should not be intermixed with calls to
Simulator.run
.

trange
(self, sample_every=None, dt=None)[source]¶ Create a vector of times matching probed data.
Note that the range does not start at 0 as one might expect, but at the first timestep (i.e.,
dt
). Parameters
 sample_everyfloat (Default: None)
The sampling period of the probe to create a range for. If None, a time value for every
dt
will be produced.

close
(self)[source]¶ Close the simulation, freeing resources.
Notes
The simulation cannot be restarted after it is closed. This is not a technical limitation, just a design decision made for all Nengo simulators.

property
training_step
¶ The number of training iterations that have been executed.

class
nengo_dl.simulator.
SimulationData
(sim, minibatched)[source]¶ Data structure used to access simulation data from the model.
The main use case for this is to access Probe data; for example,
probe_data = sim.data[my_probe]
. However, it is also used to access the parameters of objects in the model; for example, after the model has been optimized viaSimulator.train
, the updated encoder values for an ensemble can be accessed viatrained_encoders = sim.data[my_ens].encoders
. Parameters
 sim
Simulator
The simulator from which data will be drawn
 minibatchedbool
If False, discard the minibatch dimension on probe data
 sim
Notes
SimulationData shouldn’t be created/accessed directly by the user, but rather via
sim.data
(which is an instance of SimulationData).
__getitem__
(self, obj)[source]¶ Return the data associated with
obj
. Parameters
 obj
Probe
orEnsemble
orConnection
Object whose simulation data is being accessed
 obj
 Returns
 data
ndarray
orBuiltEnsemble
orBuiltConnection
Array containing probed data if
obj
is aProbe
, otherwise the corresponding parameter object
 data

get_params
(self, *obj_attrs)[source]¶ Returns the current parameter values for the given objects.
 Parameters
 obj_attrslist of (
NengoObject
, str) The Nengo object and attribute of that object for which we want to know the parameter values (each objectattribute pair specified as a tuple argument to the function).
 obj_attrslist of (
 Returns
 paramslist of
ndarray
Current values of the requested parameters
 paramslist of
Notes
Parameter values should be accessed through
sim.data
(which will call this function if necessary), rather than directly through this function.
TensorNodes¶
TensorNodes allow parts of a model to be defined using TensorFlow and smoothly integrated with the rest of a Nengo model.

class
nengo_dl.tensor_node.
TensorNode
(tensor_func, size_in=Default, size_out=Default, label=Default)[source]¶ Inserts TensorFlow code into a Nengo model.
 Parameters
 tensor_funccallable
A function that maps node inputs to outputs
 size_inint (Default: 0)
The number of elements in the input vector
 size_outint (Default: None)
The number of elements in the output vector (if None, value will be inferred by calling
tensor_func
) labelstr (Default: None)
A name for the node, used for debugging and visualization

property
output
¶ Ensure that nothing tries to evaluate the
output
attribute (indicating that something is trying to simulate this as a regularnengo.Node
rather than a TensorNode.

nengo_dl.tensor_node.
tensor_layer
(input, layer_func, shape_in=None, synapse=None, transform=1, return_conn=False, **layer_args)[source]¶ A utility function to construct TensorNodes that apply some function to their input (analogous to the
tf.layers
syntax). Parameters
 input
NengoObject
Object providing input to the layer
 layer_funccallable or
NeuronType
A function that takes the value from
input
(represented as atf.Tensor
) and maps it to some output value, or a Nengo neuron type, defining a nonlinearity that will be applied toinput
. shape_intuple of int
If not None, reshape the input to the given shape
 synapsefloat or
Synapse
Synapse to apply on connection from
input
to this layer transform
ndarray
Transform matrix to apply on connection from
input
to this layer return_connbool
If True, also return the connection linking this layer to
input
 layer_argsdict
These arguments will be passed to
layer_func
if it is callable, orEnsemble
iflayer_func
is aNeuronType
 input
 Returns
 node
TensorNode
orNeurons
A TensorNode that implements the given layer function (if
layer_func
was a callable), or a Neuron object with the given neuron type, connected toinput
 conn
Connection
If
return_conn
is True, also returns the connection object linkinginput
andnode
.
 node
Configuration system¶
The configuration system is used to change NengoDL’s default behaviour in various ways.

nengo_dl.config.
configure_settings
(**kwargs)[source]¶ Pass settings to
nengo_dl
by setting them as parameters on the toplevel Network config.The settings are passed as keyword arguments to
configure_settings
; e.g., to settrainable
useconfigure_settings(trainable=True)
. Parameters
 trainablebool or None
Adds a parameter to Nengo Ensembles/Connections/Networks that controls whether or not they will be optimized by
Simulator.train
. PassingNone
will use the defaultnengo_dl
trainable settings, or True/False will override the default for all objects. In either case trainability can be further configured on a perobject basis (e.g.net.config[my_ensemble].trainable = True
. See the documentation for more details. plannergraph planning algorithm
Pass one of the graph planners to change the default planner.
 sortersignal sorting algorithm
Pass one of the sort algorithms to change the default sorter.
 simplifications: list of graph simplification functions
Pass a list of graph simplification functions to change the default simplifications applied.
 session_config: dict
Config options passed to
tf.Session
initialization (e.g., to change the GPU memory allocation method pass{"gpu_options.allow_growth": True}
). inference_onlybool
Set to True if the network will only be run in inference mode (i.e., no calls to
Simulator.train
). This may result in a small increase in the inference speed. lif_smoothingfloat
If specified, use the smoothed
SoftLIFRate
neuron model, with the given smoothing parameter (sigma
), to compute the gradient forLIF
neurons (as opposed to usingLIFRate
). dtype
tf.DType
Set the floating point precision for simulation values.
 keep_historybool
Adds a parameter to Nengo Probes that controls whether or not they will keep the history from all simulation timesteps or only the last simulation step. This can be further configured on a perprobe basis (e.g.,
net.config[my_probe].keep_history = False
).

nengo_dl.config.
get_setting
(model, setting, default=None, obj=None)[source]¶ Returns config settings (created by
configure_settings
). Parameters
 Returns
 config_val
Value of
setting
if it has been specified, elsedefault
.
Neuron types¶
Additions to the neuron types included with Nengo
.

class
nengo_dl.neurons.
SoftLIFRate
(sigma=1.0, **lif_args)[source]¶ LIF neuron with smoothing around the firing threshold.
This is a rate version of the LIF neuron whose tuning curve has a continuous first derivative, due to the smoothing around the firing threshold. It can be used as a substitute for LIF neurons in deep networks during training, and then replaced with LIF neurons when running the network [R31ac3a1891561].
 Parameters
 sigmafloat
Amount of smoothing around the firing threshold. Larger values mean more smoothing.
 tau_rcfloat
Membrane RC time constant, in seconds. Affects how quickly the membrane voltage decays to zero in the absence of input (larger = slower decay).
 tau_reffloat
Absolute refractory period, in seconds. This is how long the membrane voltage is held at zero after a spike.
 amplitudefloat
Scaling factor on the neuron output. Corresponds to the relative amplitude of the output spikes of the neuron.
Notes
Adapted from https://github.com/nengo/nengoextras/blob/master/nengo_extras/neurons.py
References
 R31ac3a1891561
Eric Hunsberger and Chris Eliasmith (2015): Spiking deep networks with LIF neurons. https://arxiv.org/abs/1510.08829.
Distributions¶
Additions to the distributions included with Nengo
.
These distributions are usually used to initialize weight matrices, e.g.
nengo.Connection(a.neurons, b.neurons, transform=nengo_dl.dists.Glorot())
.

class
nengo_dl.dists.
TruncatedNormal
(mean=0, stddev=1, limit=None)[source]¶ Normal distribution where any values more than some distance from the mean are resampled.
 Parameters
 meanfloat
Mean of the normal distribution
 stddevfloat
Standard deviation of the normal distribution
 limitfloat
Resample any values more than this distance from the mean. If None, then limit will be set to 2 standard deviations.

sample
(self, n, d=None, rng=None)[source]¶ Samples the distribution.
 Parameters
 nint
Number samples to take.
 dint or None
The number of dimensions to return. If this is an int, the return value will be of shape
(n, d)
. If None, the return value will be of shape(n,)
. rng
RandomState
Random number generator state (if None, will use the default numpy random number generator).
 Returns
 samples(n,) or (n, d) array_like
Samples as a 1d or 2d array depending on
d
. The second dimension enumerates the dimensions of the process.

class
nengo_dl.dists.
VarianceScaling
(scale=1, mode='fan_avg', distribution='uniform')[source]¶ Variance scaling distribution for weight initialization (analogous to TensorFlow
init_ops.VarianceScaling
). Parameters
 scalefloat
Overall scale on values
 mode“fan_in” or “fan_out” or “fan_avg”
Whether to scale based on input or output dimensionality, or average of the two
 distribution: “uniform” or “normal”
Whether to use a uniform or normal distribution for weights

sample
(self, n, d=None, rng=None)[source]¶ Samples the distribution.
 Parameters
 nint
Number samples to take.
 dint or None
The number of dimensions to return. If this is an int, the return value will be of shape
(n, d)
. If None, the return value will be of shape(n,)
. rng
RandomState
Random number generator state (if None, will use the default numpy random number generator).
 Returns
 samples(n,) or (n, d) array_like
Samples as a 1d or 2d array depending on
d
. The second dimension enumerates the dimensions of the process.

class
nengo_dl.dists.
Glorot
(scale=1, distribution='uniform')[source]¶ Weight initialization method from [1] (also known as Xavier initialization).
 Parameters
 scalefloat
Scale on weight distribution. For rectified linear units this should be sqrt(2), otherwise usually 1.
 distribution: “uniform” or “normal”
Whether to use a uniform or normal distribution for weights
References
 1
Xavier Glorot and Yoshua Bengio (2010): Understanding the difficulty of training deep feedforward neural networks. International conference on artificial intelligence and statistics. http://proceedings.mlr.press/v9/glorot10a/glorot10a.pdf.

class
nengo_dl.dists.
He
(scale=1, distribution='normal')[source]¶ Weight initialization method from [1].
 Parameters
 scalefloat
Scale on weight distribution. For rectified linear units this should be sqrt(2), otherwise usually 1.
 distribution: “uniform” or “normal”
Whether to use a uniform or normal distribution for weights
References
 1
Kaiming He, Xiangyu Zhang, Shaoqing Ren, and Jian Sun. (2015): Delving deep into rectifiers: Surpassing humanlevel performance on ImageNet classification. https://arxiv.org/abs/1502.01852.
Objectives¶
Some common objective functions (for use with the objective
argument in
Simulator.train
or Simulator.loss
).

nengo_dl.objectives.
mse
(outputs, targets)[source]¶ Compute Mean Squared Error between given outputs and targets.
If any values in
targets
arenan
, that will be treated as zero error for those elements. Parameters
 outputs
tf.Tensor
Output values from a Probe in a network.
 targets
tf.Tensor
Target values for a Probe in a network.
 outputs
 Returns
 mse
tf.Tensor
Tensor representing the mean squared error.
 mse

class
nengo_dl.objectives.
Regularize
(order=2, axis=None, weight=None)[source]¶ An objective function to apply regularization penalties.
 Parameters
 orderint or str
Order of the regularization norm (e.g.
1
for L1 norm,2
for L2 norm). See https://www.tensorflow.org/api_docs/python/tf/norm for a full description of the possible values for this parameter. axisint or None
The axis of the probed signal along which to compute norm. If None (the default), the signal is flattened and the norm is computed across the resulting vector. Note that these are only the axes with respect to the output on a single timestep (i.e. batch/time dimensions are not included).
 weightfloat
Scaling weight to apply to regularization penalty.
Notes
The mean will be computed across all the non
axis
dimensions after computing the norm (including batch/time) in order to compute the overall objective value.
Developers¶
These objects are only relevant to people interested in modifying the implementation of NengoDL (e.g., adding a new neuron type).
Builder¶
The builder manages the mapping between (groups of) Nengo operators and the builder objects that know how to translate those operators into a TensorFlow graph.

class
nengo_dl.builder.
Builder
(plan, graph, signals, config)[source]¶ Manages the operator build classes known to the
nengo_dl
build process. Parameters
 planlist of tuple of
Operator
The groups of operators that will be built
 graph
tf.Graph
The simulation build graph
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations) config
BuildConfig
Configuration parameters for the build process
 planlist of tuple of

pre_build
(self, progress=None)[source]¶ Setup step for build classes, in which they compute any of the values that are constant across simulation timesteps.
 Parameters
 progress
utils.ProgressBar
Progress bar for ops in plan
 progress

build
(self, progress=None)[source]¶ Build the computations implementing a single simulator timestep.
 Parameters
 progress
utils.ProgressBar
Progress bar for ops in plan
 progress
 Returns
 side_effectslist of
tf.Tensor
Outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used.
 side_effectslist of

post_build
(self, sess, rng, progress=None)[source]¶ Calls post build functions for all ops in plan.
 Parameters
 sess
tf.Session
The initialized simulation session
 rng
RandomState
Seeded random number generator
 progress
utils.ProgressBar
Progress bar for ops in plan
 sess

class
nengo_dl.builder.
BuildConfig
[source]¶ Stores configuration parameters that may be relevant to parts of the build process.
 Parameters
 inference_onlybool
If True the network should be constructed in “inference only” mode (not including any support for training operations).
 lif_smoothingfloat
Smoothing parameter for
LIF
gradient approximation. cpu_onlybool
True if TensorFlow is only running on the CPU (because that was specified by the user or because tensorflowgpu is not installed).
Create new instance of BuildConfig(inference_only, lif_smoothing, cpu_only)

class
nengo_dl.builder.
OpBuilder
(ops, signals, config)[source]¶ The constructor should set up any computations that are fixed for this op (i.e., things that do not need to be recomputed each timestep).
 Parameters
 opslist of
Operator
The operator group to build into the model
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations) config
BuildConfig
General repository for config information builders might want (conglomerated into this object so that we can add/remove config data without having to change the function signature all the time).
 opslist of

build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of

build_post
(self, ops, signals, sess, rng)[source]¶ This function will be called after the graph has been built and session/variables initialized.
This should be used to build any random aspects of the operator.
Note that this function may be called multiple times per session, so it should modify the graph inplace.
 Parameters
 opslist of
Operator
The operator group to build into the model
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations) sess
tf.Session
The initialized simulation session
 rng
RandomState
Seeded random number generator
 opslist of

class
nengo_dl.builder.
NengoBuilder
[source]¶ Copy of the default Nengo builder.
This class is here so that we can register new build functions for Nengo DL without affecting the default Nengo build process.

classmethod
build
(model, obj, *args, **kwargs)[source]¶ Build
obj
intomodel
.This method looks up the appropriate build function for
obj
and calls it with the model and other arguments provided.In addition to the parameters listed below, further positional and keyword arguments will be passed unchanged into the build function.
 Parameters
 modelModel
The
Model
instance in which to store build artifacts. objobject
The object to build into the model.

classmethod

class
nengo_dl.builder.
NengoModel
(*args, fail_fast=True, **kwargs)[source]¶ Copy of the default Nengo model.
This allows us to override certain model behaviours.
 Parameters
 fail_fastbool
If True, try to call
op.make_step
when ops are added to the model. Note that NengoDL doesn’t actually usemake_step
, so errors in that function are not necessarily errors in NengoDL (which is why we want to disable that check). But it might still be useful when debugging new op/build functions, which is why we leave the option.

add_op
(self, op)[source]¶ Add an operator to the model.
 Parameters
 op
Operator
Operator being added to the model.
 op
Notes
This is a copy of the parent
nengo.builder.Model.add_op
, with the addition of theif self.fail_fast
condition.
Operator builders¶
These objects are used to convert Nengo operators into TensorFlow graph elements.
Basic operators¶
Build classes for basic Nengo operators.

class
nengo_dl.op_builders.
ResetInc
(dst, value=0, tag=None)[source]¶ A version of Reset that increments the target value rather than setting it.

property
dst
¶ Overridden to return from incs rather than sets.

property

class
nengo_dl.op_builders.
ResetBuilder
(ops, signals, config)[source]¶ Build a group of
Reset
operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.op_builders.
CopyBuilder
(ops, signals, config)[source]¶ Build a group of
Copy
operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.op_builders.
ElementwiseIncBuilder
(ops, signals, config)[source]¶ Build a group of
ElementwiseInc
operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


nengo_dl.op_builders.
sparse_matmul
(A_indices, A_data, A_shape, X)[source]¶ Matrix multiplication between sparse matrix A and dense matrix X
 Parameters
 A_indices
tf.Tensor
N, 2) rray of [row,col] nonzero entries
 A_data
tf.Tensor
(N,) array of data in the nonzero entries specified in
A_indices
 A_shapetuple of int
Shape of full A matrix
 X
tf.Tensor
Dense matrix being multiplied by A
 A_indices
 Returns
 dot
tf.Tensor
Result of matrix multiplication between A and X
 dot

class
nengo_dl.op_builders.
DotIncBuilder
(ops, signals, config)[source]¶ Build a group of
DotInc
operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.op_builders.
SimPyFuncBuilder
(ops, signals, config)[source]¶ Build a group of
SimPyFunc
operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.op_builders.
SparseDotIncBuilder
(ops, signals, config)[source]¶ Build a group of
SparseDotInc
operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of

Neuron types¶
Build classes for Nengo neuron operators.

class
nengo_dl.neuron_builders.
GenericNeuronBuilder
(ops, signals, config)[source]¶ Builds all neuron types for which there is no custom Tensorflow implementation.
Notes
These will be executed as native Python functions, requiring execution to move in and out of TensorFlow. This can significantly slow down the simulation, so any performancecritical neuron models should consider adding a custom TensorFlow implementation for their neuron type instead.

build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.neuron_builders.
RectifiedLinearBuilder
(ops, signals, config)[source]¶ Build a group of
RectifiedLinear
neuron operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.neuron_builders.
SpikingRectifiedLinearBuilder
(ops, signals, config)[source]¶ Build a group of
SpikingRectifiedLinear
neuron operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.neuron_builders.
SigmoidBuilder
(ops, signals, config)[source]¶ Build a group of
Sigmoid
neuron operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.neuron_builders.
LIFRateBuilder
(ops, signals, config)[source]¶ Build a group of
LIFRate
neuron operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.neuron_builders.
SoftLIFRateBuilder
(ops, signals, config)[source]¶ Build a group of
SoftLIFRate
neuron operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.neuron_builders.
LIFBuilder
(ops, signals, config)[source]¶ Build a group of
LIF
neuron operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.neuron_builders.
SimNeuronsBuilder
(ops, signals, config)[source]¶ Builds a group of
SimNeurons
operators.Calls the appropriate subbuild class for the different neuron types.
 Attributes
 TF_NEURON_IMPLdict of {
NeuronType
,builder.OpBuilder
} Mapping from neuron types to custom build classes (neurons without a custom builder will use the generic builder).
 TF_NEURON_IMPLdict of {

build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of
Learning rules¶
Build classes for Nengo learning rule operators.

class
nengo_dl.learning_rule_builders.
SimBCMBuilder
(ops, signals, config)[source]¶ Build a group of
SimBCM
operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.learning_rule_builders.
SimOjaBuilder
(ops, signals, config)[source]¶ Build a group of
SimOja
operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.learning_rule_builders.
SimVojaBuilder
(ops, signals, config)[source]¶ Build a group of
SimVoja
operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


nengo_dl.learning_rule_builders.
build_pes
(model, pes, rule)[source]¶ Builds a
nengo.PES
object into a model. Parameters
 modelModel
The model to build into.
 pesPES
Learning rule type to build.
 ruleLearningRule
The learning rule object corresponding to the neuron type.
Notes
Does not modify
model.params[]
and can therefore be called more than once with the samenengo.PES
instance.

class
nengo_dl.learning_rule_builders.
SimPESBuilder
(ops, signals, config)[source]¶ Build a group of
SimPES
operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of

Processes¶
Build classes for Nengo process operators.

class
nengo_dl.process_builders.
GenericProcessBuilder
(ops, signals, config)[source]¶ Builds all process types for which there is no custom TensorFlow implementation.
Notes
These will be executed as native Python functions, requiring execution to move in and out of TensorFlow. This can significantly slow down the simulation, so any performancecritical processes should consider adding a custom TensorFlow implementation for their type instead.

build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of

build_post
(self, ops, signals, sess, rng)[source]¶ This function will be called after the graph has been built and session/variables initialized.
This should be used to build any random aspects of the operator.
Note that this function may be called multiple times per session, so it should modify the graph inplace.
 Parameters
 opslist of
Operator
The operator group to build into the model
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations) sess
tf.Session
The initialized simulation session
 rng
RandomState
Seeded random number generator
 opslist of


class
nengo_dl.process_builders.
LowpassBuilder
(ops, signals, config)[source]¶ Build a group of
Lowpass
synapse operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.process_builders.
LinearFilterBuilder
(ops, signals, config)[source]¶ Build a group of
LinearFilter
synapse operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of


class
nengo_dl.process_builders.
SimProcessBuilder
(ops, signals, config)[source]¶ Builds a group of
SimProcess
operators.Calls the appropriate subbuild class for the different process types.
 Attributes
 TF_PROCESS_IMPLdict of {
Process
:builder.OpBuilder
} Mapping from process types to custom build classes (processes without a custom builder will use the generic builder).
 TF_PROCESS_IMPLdict of {

build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of

build_post
(self, ops, signals, sess, rng)[source]¶ This function will be called after the graph has been built and session/variables initialized.
This should be used to build any random aspects of the operator.
Note that this function may be called multiple times per session, so it should modify the graph inplace.
 Parameters
 opslist of
Operator
The operator group to build into the model
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations) sess
tf.Session
The initialized simulation session
 rng
RandomState
Seeded random number generator
 opslist of
Transforms¶
Build classes for Nengo transform operators.

class
nengo_dl.transform_builders.
ConvIncBuilder
(ops, signals, config)[source]¶ Build a group of
ConvInc
operators.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of

TensorNodes¶
To build TensorNode
objects we need to define a new Nengo operator
(tensor_node.SimTensorNode
), a build function that adds that operator
into a Nengo graph (tensor_node.build_tensor_node
), and a NengoDL
build class that maps that new Nengo operator to TensorFlow operations
(tensor_node.SimTensorNodeBuilder
).

class
nengo_dl.tensor_node.
SimTensorNode
(func, time, input, output, tag=None)[source]¶ Operator for TensorNodes (constructed by
build_tensor_node
). Parameters
Notes
sets
[output]
incs
[]
reads
[time] if input is None else [time, input]
updates
[]

nengo_dl.tensor_node.
build_tensor_node
(model, node)[source]¶ This is the Nengo build function, so that Nengo knows what to do with TensorNodes.

class
nengo_dl.tensor_node.
SimTensorNodeBuilder
(ops, signals, config)[source]¶ Builds a
SimTensorNode
operator into a NengoDL model.
build_step
(self, signals)[source]¶ This function builds whatever computations need to be executed in each simulation timestep.
 Parameters
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations)
 signals
 Returns
 side_effectslist of
tf.Tensor
If not None, the returned tensors correspond to outputs with possible sideeffects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
 side_effectslist of

build_post
(self, ops, signals, sess, rng)[source]¶ This function will be called after the graph has been built and session/variables initialized.
This should be used to build any random aspects of the operator.
Note that this function may be called multiple times per session, so it should modify the graph inplace.
 Parameters
 opslist of
Operator
The operator group to build into the model
 signals
signals.SignalDict
Mapping from
Signal
totf.Tensor
(updated by operations) sess
tf.Session
The initialized simulation session
 rng
RandomState
Seeded random number generator
 opslist of

Graph construction¶
Manages all the data and build processes associated with the TensorFlow graph.
The TensorFlow graph is the symbolic description of the computations in the network, which will be executed by the simulator.

nengo_dl.tensor_graph.
with_self
(wrapped, instance, args, kwargs)[source]¶ A decorator that can be used to ensure that any ops created within the wrapped method will be added to the TensorGraph object’s graph.

class
nengo_dl.tensor_graph.
TensorGraph
(model, dt, unroll_simulation, dtype, minibatch_size, device, progress)[source]¶ Manages the construction of the TensorFlow symbolic computation graph.
 Parameters
 model
Model
Prebuilt Nengo model describing the network to be simulated
 dtfloat
Length of a simulator timestep, in seconds
 unroll_simulationint
Unroll simulation loop by explicitly building
unroll_simulation
iterations into the computation graph dtype
tf.DType
Floating point precision to use for simulation
 minibatch_sizeint
The number of simultaneous inputs that will be passed through the network
 deviceNone or
"/cpu:0"
or"/gpu:[0n]"
Device on which to execute computations (if None then uses the default device as determined by TensorFlow)
 progress
utils.ProgressBar
Progress bar for optimization stage
 model

build
(self, progress)[source]¶ Constructs a new graph to simulate the model.
 progress
utils.ProgressBar
Progress bar for construction stage
 progress

build_step
(self, progress)[source]¶ Build the operators that execute a single simulation timestep into the graph.
 Parameters
 progress
utils.ProgressBar
Progress bar for loop construction
 progress
 Returns
 probe_tensorslist of
tf.Tensor
The Tensor objects representing the data required for each model Probe
 side_effectslist of
tf.Tensor
The output Tensors of computations that may have sideeffects (e.g.,
Node
functions), meaning that they must be executed each time step even if their output doesn’t appear to be used in the simulation
 probe_tensorslist of

build_loop
(self, progress)[source]¶ Build simulation loop.
 Parameters
 progress
utils.ProgressBar
Progress bar for loop construction
 progress

build_inputs
(self, progress)[source]¶ Sets up the inputs in the model (which will be computed outside of TensorFlow and fed in each simulation block).
 Parameters
 progress
utils.ProgressBar
Progress bar for input construction
 progress

build_optimizer_func
(self, optimizer, objective)[source]¶ Adds elements into the graph to execute the given optimizer.
 Parameters
 optimizer
tf.train.Optimizer
Instance of a TensorFlow optimizer class
 objectivedict of {
Probe
: callable orNone
} The objective to be minimized. This is a dictionary mapping Probes to functions
f(output, target) > loss
that consume the actual output and target output for the given probe(s) and return atf.Tensor
representing a scalar loss value. The function may also accept a single argumentf(output) > loss
if targets are not required. Some common objective functions can be found innengo_dl.objectives
.Passing
None
as the probe value (instead of a callable) indicates that the error is being computed outside the simulation, and the value passed for that probe indata
directly specifies the output error gradient.If multiple probes are specified as the key, then the corresponding output/target values will be passed as a list to the objective function.
The overall loss value being minimized will be the sum across all the objectives specified.
 optimizer
 Returns
 apply_optimizercallable
A function that builds the operators required to implement the given optimizer update. Generally this function will then be passed to
build_outputs
.
Notes
This function caches its outputs, so if it is called again with the same arguments then it will return the previous function. This avoids building duplicates of the same operations over and over. This can also be important functionally, e.g. if the optimizer has internal state like momentum. By caching the output we ensure that subsequent calls share the same internal state.

build_outputs
(self, outputs)[source]¶ Adds elements into the graph to compute the given outputs.
 Parameters
 outputsdict of {(tuple of)
Probe
: callable or None} The output function to be applied to each probe or group of probes. The function can accept one argument (the output of that probe) or two (output and target values for that probe). If a tuple of Probes are given as the key, then those output/target parameters will be the corresponding tuple of probe/target values. The function should return a
tf.Tensor
or tuple of Tensors representing the output we want from those probes. IfNone
is given instead of a function then the output will simply be the output value from the corresponding probes.
 outputsdict of {(tuple of)
 Returns
 output_valsdict of {(tuple of)
Probe
: (tuple of)tf.Tensor
} Tensors representing the result of applying the output functions to the probes.
 new_vars_init
tf.Tensor
or None Initialization op for any new variables created when building the outputs.
 output_valsdict of {(tuple of)
Notes
This function caches its outputs, so if it is called again with the same arguments then it will return the previous Tensors. This avoids building duplicates of the same operations over and over. This can also be important functionally, e.g. if the outputs have internal state. By caching the output we ensure that subsequent calls share the same internal state.

build_post
(self, sess, rng)[source]¶ Executes postbuild processes for operators (after the graph has been constructed and session/variables initialized).
Note that unlike other build functions, this is called every time the simulator is reset.
 Parameters
 sess
tf.Session
The TensorFlow session for the simulator
 rng
RandomState
Seeded random number generator
 sess

build_summaries
(self, summaries)[source]¶ Adds ops to collect summary data for the given objects.
 Parameters
 summarieslist of dict or
Connection
orEnsemble
orNeurons
ortf.Tensor
} List of objects for which we want to collect data. Object can be a Connection (in which case data on weights will be collected), Ensemble (encoders), Neurons (biases), a dict of
{probe: objective}
that indicates a loss function that will be tracked, or a prebuilt summary tensor.
 summarieslist of dict or
 Returns
 op
tf.Tensor
Merged summary op for the given summaries
 op

get_tensor
(self, sig)[source]¶ Returns a Tensor corresponding to the given Signal.
 Parameters
 sig
Signal
A signal in the model
 sig
 Returns
 tensor
tf.Tensor
Tensor containing the value of the given Signal
 tensor

mark_signals
(self)[source]¶ Mark all the signals in
self.model
according to whether they represent trainable parameters of the model (parameters that can be optimized by deep learning methods).Trainable parameters include connection weights, ensemble encoders, and neuron biases. Unless one of those signals is targeted by a Nengo learning rule (otherwise the learning rule update conflicts with the deep learning optimization).
Users can manually specify whether signals are trainable or not using the config system (e.g.,
net.config[nengo.Ensemble].trainable = False
)

create_signals
(self, sigs)[source]¶ Groups signal data together into larger arrays, and represent each individual signal as a slice into that array.
 Parameters
 sigslist of
Signal
Base signals arranged into the order in which they should reside in memory (e.g., output from
graph_optimizer.order_signals
)
 sigslist of
Signals¶
Represents and manages the internal simulation signals.

class
nengo_dl.signals.
TensorSignal
(indices, key, dtype, shape, minibatch_size, constant, label='TensorSignal')[source]¶ Represents a tensor as an indexed view into a base array.
 Parameters
 indicestuple or list or
ndarray
of int Indices along the first axis of the base array corresponding to the data for this signal
 keyobject
Key mapping to the base array that contains the data for this signal
 dtype
dtype
dtype of the values represented by this signal
 shapetuple of int
View shape of this signal (may differ from shape of base array)
 minibatch_sizeint
If not None then this signal contains a minibatch dimension with the given size
 constantcallable
A function that returns a TensorFlow constant (will be provided by
signals.SignalDict.get_tensor_signal
) labelstr
Name for this signal, used to make debugging easier
 indicestuple or list or

property
indices
¶ The indices containing the data for this signal in the base array.

property
ndim
¶ The rank of this signal.

__getitem__
(self, indices)[source]¶ Create a new TensorSignal representing a subset (slice or advanced indexing) of the indices of this TensorSignal.
 Parameters
 indicesslice or list of int
The desired subset of the indices in this TensorSignal
 Returns
 sig
signals.TensorSignal
A new TensorSignal representing the subset of this TensorSignal
 sig

reshape
(self, shape)[source]¶ Create a new TensorSignal representing a reshaped view of the same data in this TensorSignal (size of data must remain unchanged).
 Parameters
 shapetuple of int
New shape for the signal (one dimension can be 1 to indicate an inferred dimension size, as in numpy)
 Returns
 sig
signals.TensorSignal
New TensorSignal representing the same data as this signal but with the given shape
 sig

broadcast
(self, axis, length)[source]¶ Add a new dimension by broadcasting this signal along
axis
for the given length. Parameters
 axis0 or 1
Where to insert the new dimension (currently only supports either the beginning or end of the array)
 lengthint
The number of times to duplicate signal along the broadcast dimension
 Returns
 sig
signals.TensorSignal
TensorSignal with new broadcasted shape
 sig

property
tf_shape
¶ A
tf.Tensor
representing the shape of this signal.

property
tf_indices
¶ A
tf.Tensor
representing the indices of this signal.

property
tf_slice
¶ A tuple of
tf.Tensors
representing the(start, stop, stride)
slice within the base array containing the data for this signal.This can be used as a more efficient representation of
TensorSignal.tf_indices
.

property
full_shape
¶ Shape of the signal including the minibatch dimension.

property
minibatched
¶ Whether or not this TensorSignal contains a minibatch dimension.

class
nengo_dl.signals.
SignalDict
(dtype, minibatch_size)[source]¶ Handles the mapping from
Signal
totf.Tensor
.Takes care of gather/scatter logic to read/write signals within the base arrays.
 Parameters
 dtype
tf.DType
Floating point precision used in signals
 minibatch_sizeint
Number of items in each minibatch
 dtype

scatter
(self, dst, val, mode='update')[source]¶ Updates the base data corresponding to
dst
. Parameters
 dst
TensorSignal
Signal indicating the data to be modified in base array
 val
tf.Tensor
Update data (same shape as
dst
, i.e. a dense array <= the size of the base array) mode“update” or “inc”
Overwrite/add the data at
dst
withval
 dst

gather
(self, src, force_copy=False)[source]¶ Fetches the data corresponding to
src
from the base array. Parameters
 src
TensorSignal
Signal indicating the data to be read from base array
 force_copybool
If True, always perform a gather, not a slice (this forces a copy). Note that setting
force_copy=False
does not guarantee that a copy won’t be performed.
 src
 Returns
 gathered
tf.Tensor
Tensor object corresponding to a dense subset of data from the base array
 gathered

mark_gather
(self, src)[source]¶ Marks
src
as being gathered, but doesn’t actually perform a gather. Used to indicate that some computation relies onsrc
. Parameters
 src
TensorSignal
Signal indicating the data being read
 src

combine
(self, sigs, label='Combine')[source]¶ Combines several TensorSignals into one by concatenating along the first axis.
 Parameters
 sigslist of
TensorSignal
orSignal
Signals to be combined
 labelstr
Name for combined signal (to help with debugging)
 sigslist of
 Returns
 sig
TensorSignal
New TensorSignal representing the concatenation of the data in
sigs
 sig

make_internal
(self, name, shape, minibatched=True)[source]¶ Creates a variable to represent an internal simulation signal.
This is to handle the case where we want to add a signal that is not represented as a
nengo.builder.Signal
in the Nengo op graph. Parameters
 namestr
Name for the signal/variable.
 shapetuple of int
Shape of the signal/variable.
 minibatchedbool
Whether or not this signal contains a minibatch dimension.
 Returns
 sig
TensorSignal
A TensorSignal representing the newly created variable.
 sig

get_tensor_signal
(self, indices, key, dtype, shape, minibatched, signal=None, label='TensorSignal')[source]¶ Creates a new
TensorSignal
with the given properties.This should be used rather than instantiating a new TensorSignal directly, as it handles some extra bookkeeping (e.g., using the custom
constant
function). Parameters
 indicestuple or list or
ndarray
of int Indices along the first axis of the base array corresponding to the data for this signal
 keyobject
Key mapping to the base array that contains the data for this signal
 dtype
dtype
dtype of the values represented by this signal
 shapetuple of int
View shape of this signal (may differ from shape of base array)
 minibatchedbool
Whether or not this signal contains a minibatch dimension
 signal
Signal
If not None, associate the new
TensorSignal
with the givenSignal
in thesig_map
 labelstr
Name for this signal, used to make debugging easier
 indicestuple or list or
 Returns
 sig
TensorSignal
A new
TensorSignal
with the given properties
 sig

constant
(self, value, dtype=None, cutoff=33554432)[source]¶ Returns a constant Tensor containing the given value.
The returned Tensor may be underpinned by a
tf.constant
op, or atf.Variable
that will be initialized to the constant value. We use the latter in order to avoid storing large constant values in the TensorFlow GraphDef, which has a hardcoded limit of 2GB at the moment. Parameters
 Returns
 constant
tf.Tensor
A tensor representing the given value
 constant

op_constant
(self, ops, op_sizes, attr, dtype, ndims=2)[source]¶ Creates a tensor representing the constant parameters of an op group.
 Parameters
 opslist of object
The operators for some merged group of ops
 op_sizeslist of int
The number of constant elements in each op
 attrstr
The attribute of the op that describes the constant parameter
 dtype
dtype
Numeric type of the parameter
 ndimsint
Empty dimensions will be added to the end of the returned tensor for all ndims > 1 (in the case that it is not a scalar).
 Returns
 constant
tf.Tensor
Tensor containing the values of
attr
for the given ops. This will be a scalar if all the ops have the same parameter value, or an array giving the parameter value for each element in each op.
 constant
Graph optimization¶
These functions are used to restructure the Nengo operator graph so that it can be simulated more efficiently when converted into a TensorFlow graph.

nengo_dl.graph_optimizer.
mergeable
(op, chosen_ops)[source]¶ Check if the given op can be merged with the candidate group

nengo_dl.graph_optimizer.
greedy_planner
(operators)[source]¶ Combine mergeable operators into groups that will be executed as a single computation.
 Parameters
 operatorslist of
Operator
All the
nengo
operators in a model (unordered)
 operatorslist of
 Returns
 planlist of tuple of
Operator
Operators combined into mergeable groups and in execution order
 planlist of tuple of
Notes
Originally based on
nengo_ocl
greedy planner

nengo_dl.graph_optimizer.
tree_planner
(op_list, max_depth=3)[source]¶ Create merged execution plan through exhaustive tree search.
The
max_depth
parameter scales the planner between full tree search and greedy search.max_depth==1
is equivalent togreedy_planner
, andmax_depth==len(op_list)
is full tree search (guaranteed to find the optimal plan, but likely very slow).

nengo_dl.graph_optimizer.
transitive_planner
(op_list)[source]¶ Create merged execution plan through transitive closure construction.
This is something like a middle ground between
greedy_planner
andtree_planner
; it can improve simulation time over the greedy planner, but comes with potentially significant build time increases.

nengo_dl.graph_optimizer.
transitive_closure_recurse
(dg, ops, trans, builder_type, builder_types, cache)[source]¶ Computes the transitive closure for the given graph, restricted to the operators with the given builder type.
 Parameters
 dgdict of {int: set of int}
Dependency graph where
dg[a] = {b, c}
indicates that operatorsb
andc
are dependent ona
 opslist of int
The operators for which we want to compute the transitive closure
 transdict of {int: set of int}
The transitive closure for the graph (will be filled inplace)
 builder_typetype
One of the
nengo_dl
build classes (e.g.,CopyBuilder
), specifying the type of operators to include in the transitive closure builder_typeslist of type
The build class for each operator
 cachedict of {frozenset of int: set of int}
Stores base sets which
trans
will reference (to reduce memory usage, since many elements intrans
will have the same value)
Notes
This function uses ints to refer to operators, where the int indicates the index of the operator in the overall op list (this is done to save memory). See
transitive_planner
.

nengo_dl.graph_optimizer.
noop_planner
(operators)[source]¶ Orders operators into a valid execution order, but does not perform any merging.

nengo_dl.graph_optimizer.
order_signals
(plan, n_passes=10)[source]¶ Orders signals and operators to try to structure reads/writes in contiguous blocks.
 Parameters
 planlist of tuple of
Operator
Operator execution plan (e.g., output from
greedy_planner
) n_passesint
Number of repeated passes through the operator reordering stage
 planlist of tuple of
 Returns

nengo_dl.graph_optimizer.
hamming_sort
(blocks)[source]¶ Reorder signals using heuristics to try to place signals that are accessed by the same operators into adjacent positions (giving priority to larger blocks).

nengo_dl.graph_optimizer.
sort_ops_by_signals
(sorted_io, sigs, sig_idxs, new_plan, blocks, op_sigs)[source]¶ Rearrange operators to match the order of signals.
Note: the same operators can be associated with multiple read blocks if they have multiple inputs, so rearranging the operators according to one of those blocks could mess up the order with respect to the other read block. We iterate through the read blocks in increasing size so that the largest blocks win out.
 Parameters
 sorted_iolist of tuple of (
Operator
, int) The operators that form each io block, sorted by increasing size of the block. In the case that a group of operators participate in multiple io blocks, the integer distinguishes which one of those blocks this block is associated with.
 sigslist of
Signal
Signals that have been arranged into a given order by other parts of the algorithm
 sig_idxsdict of {
Signal
: int} Sorted indices of signals
 new_plandict of {tuple of
Operator
: tuple ofOperator
} Mapping from original operator group to the sorted operators
 blocksdict of {
Signal
: frozenset of int} Indicates which io blocks each signal participates in
 op_sigsdict of {
Operator
: list ofSignal
} The signals accessed by each operator
 sorted_iolist of tuple of (
 Returns

nengo_dl.graph_optimizer.
sort_signals_by_ops
(sorted_io, sigs, sig_idxs, new_plan, blocks, op_sigs)[source]¶ Attempts to rearrange
sigs
so that it is in the same order as operator signals, without changing the overall block order. Parameters
 sorted_iolist of tuple of (
Operator
, int) The operators that form each io block, sorted by increasing size of the io block. In the case that a group of operators participate in multiple io blocks, the integer distinguishes which one of those blocks this block is associated with.
 sigslist of
Signal
Signals to be sorted
 sig_idxsdict of {
Signal
: int} Sorted indices of signals
 new_plandict of {tuple of
Operator
: tuple ofOperator
} Mapping from original operator group to the sorted operators
 blocksdict of {
Signal
: frozenset of int} Indicates which io blocks each signal participates in
 op_sigsdict of {
Operator
: list ofSignal
} The signals accessed by each operator
 sorted_iolist of tuple of (
 Returns
 sig_idxsdict of {
Signal
: int} Sorted indices of signals
 sig_idxsdict of {

nengo_dl.graph_optimizer.
noop_order_signals
(plan, **_)[source]¶ A version of
graph_optimizer.order_signals
that doesn’t do any reordering, for debugging.

nengo_dl.graph_optimizer.
remove_unmodified_resets
(operators)[source]¶ Remove any Reset operators that are targeting a signal that is never modified.
If a signal is reset, but never inced/updated after that, we can just set the default signal value to the reset value and remove the reset. Note: this wouldn’t normally happen, but it can happen if we removed some of the incs (e.g. in remove_zero_incs).

nengo_dl.graph_optimizer.
remove_zero_incs
(operators)[source]¶ Remove any operators where we know the input (and therefore output) is zero.
If the input to a DotInc/ElementwiseInc/Copy is zero then we know that the output of the op will be zero, so we can just get rid of it.

nengo_dl.graph_optimizer.
remove_constant_copies
(operators)[source]¶ Change Copies with constant input to Resets.
If a Copy has no dependencies, or just one Reset() dependency, then we can change it to an op that just directly sets the output signal to the Copy input value.

nengo_dl.graph_optimizer.
remove_identity_muls
(operators)[source]¶ Change y=x*1 ops to y=x Copy ops.
If one of the inputs to a DotInc/ElementwiseInc is 1 then we can skip the multiplication and change it to a Copy op.

nengo_dl.graph_optimizer.
signal_io_dicts
(operators)[source]¶ Organizes operators into dictionaries according to the signals they set/inc/read/update.
 Parameters
 operatorslist of
Operator
Operators in the model
 operatorslist of
 Returns
 setsdict of {
Signal
: list ofOperator
} A dictionary indicating all the Operators that set each signal.
 incsdict of {
Signal
: list ofOperator
} A dictionary indicating all the Operators that inc each signal.
 readsdict of {
Signal
: list ofOperator
} A dictionary indicating all the Operators that read each signal.
 updatesdict of {
Signal
: list ofOperator
} A dictionary indicating all the Operators that update each signal.
 setsdict of {

nengo_dl.graph_optimizer.
display_signal_blocks
(operators, all_signals)[source]¶ Creates a visual depiction of the signals blocks read by each operator group.
 Parameters
 Returns
 signal_blocksstr
A string where each row corresponds to one operator group, and the nonblank characters in the line indicate that the operator group reads/writes that signal (with a number used to distinguish the different signal blocks within the operator group).
Utilities¶
Utility objects used throughout the code base.

nengo_dl.utils.
sanitize_name
(name)[source]¶ Remove illegal TensorFlow name characters from string.
Valid TensorFlow name characters are
[AZaz09_.\/]
 Parameters
 namestr
Name to be sanitized
 Returns
 sanitizedstr
Sanitized name

nengo_dl.utils.
function_name
(func, sanitize=True)[source]¶ Get the name of the callable object
func
. Parameters
 funccallable
Callable object (e.g., function, callable class)
 sanitizebool
If True, remove any illegal TensorFlow name characters from name
 Returns
 namestr
Name of
func
(optionally sanitized)

nengo_dl.utils.
align_func
(output_shape, output_dtype)[source]¶ Decorator that ensures the output of
func
is anndarray
with the given shape and dtype. Parameters
 output_shape(list of) tuple of int
Desired shape for function output(s) (must have the same size as actual function output)
 output_dtype(list of)
tf.DType
ordtype
Desired dtype of function output(s)
 Raises
nengo.exceptions.SimulationError
If the function returns
None
or a nonfinite value.

nengo_dl.utils.
print_op
(input, message)[source]¶ Inserts a print statement into the TensorFlow graph.
 Parameters
 input
tf.Tensor
The value of this tensor will be printed whenever it is computed in the graph
 messagestr
String prepended to the value of
input
, to help with logging
 input
 Returns
 op
tf.Tensor
New tensor representing the print operation applied to
input
 op
Notes
This is what
tf.Print
is supposed to do, but it doesn’t seem to work consistently.

nengo_dl.utils.
find_non_differentiable
(inputs, outputs)[source]¶ Searches through a TensorFlow graph to find nondifferentiable elements between
inputs
andoutputs
(elements that would prevent us from computingd_outputs / d_inputs
. Parameters
 inputslist of
tf.Tensor
Input tensors
 outputslist of
tf.Tensor
Output tensors
 inputslist of

class
nengo_dl.utils.
MessageBar
(msg='', finish_msg='', **kwargs)[source]¶ ProgressBar widget for progress bars with possibly unknown duration.
 Parameters
 msgstr
A message to be displayed in the middle of the progress bar
 finish_msgstr
A message to be displayed when the progress bar is finished

class
nengo_dl.utils.
ProgressBar
(present='', past=None, max_value=1, vars=None, **kwargs)[source]¶ Handles progress bar display for some tracked process.
 Parameters
 presentstr
Description of process in present (e.g., “Simulating”)
 paststr
Description of process in past (e.g., “Simulation”)
 max_valueint or None
The maximum number of steps in the tracked process (or
None
if the maximum number of steps is unknown) varslist of str
Extra variables that will be displayed at the end of the progress bar
Notes
Launches a separate thread to handle the progress bar display updates.

step
(self, **vars)[source]¶ Advance the progress bar one step.
 Parameters
 varsdict of {str: str}
Values for the extra variables displayed at the end of the progress bar (defined in
__init__
)

sub
(self, msg=None, **kwargs)[source]¶ Creates a new progress bar for tracking a subprocess.
 Parameters
 msgstr
Description of subprocess

property
max_steps
¶ Alias for max_value to allow this to work with Nengo progress bar interface.

class
nengo_dl.utils.
SubProgressBar
(present='', past=None, max_value=1, vars=None, **kwargs)[source]¶ A progress bar representing a subtask within an overall progress bar.

class
nengo_dl.utils.
NullProgressBar
(present='', past=None, max_value=1, vars=None, **kwargs)[source]¶ A progress bar that does nothing.
Used to replace ProgressBar when we want to disable output.

nengo_dl.utils.
minibatch_generator
(data, minibatch_size, shuffle=True, truncation=None, rng=None)[source]¶ Generator to yield
minibatch_sized
subsets frominputs
andtargets
. Parameters
 datadict of {
NengoObject
:ndarray
} Data arrays to be divided into minibatches.
 minibatch_sizeint
The number of items in each minibatch
 shufflebool
If True, the division of items into minibatches will be randomized each time the generator is created
 truncationint
If not None, divide the data up into sequences of
truncation
timesteps. rng
RandomState
Seeded random number generator
 datadict of {
 Yields
 offsetint
The simulation step at which the returned data begins (will only be nonzero if
truncation
is notNone
). inputsdict of {
Node
:ndarray
} The same structure as
inputs
, but with each array reduced tominibatch_size
elements along the first dimension targetsdict of {
Probe
:ndarray
} The same structure as
targets
, but with each array reduced tominibatch_size
elements along the first dimension
Benchmarks¶
Benchmark networks and utilities for evaluating NengoDL’s performance.

nengo_dl.benchmarks.
cconv
(dimensions, neurons_per_d, neuron_type)[source]¶ Circular convolution (EnsembleArray) benchmark.
 Parameters
 dimensionsint
Number of dimensions for vector values
 neurons_per_dint
Number of neurons to use per vector dimension
 neuron_type
NeuronType
Simulation neuron type
 Returns
 net
nengo.Network
benchmark network
 net

nengo_dl.benchmarks.
integrator
(dimensions, neurons_per_d, neuron_type)[source]¶ Single integrator ensemble benchmark.
 Parameters
 dimensionsint
Number of dimensions for vector values
 neurons_per_dint
Number of neurons to use per vector dimension
 neuron_type
NeuronType
Simulation neuron type
 Returns
 net
nengo.Network
benchmark network
 net

nengo_dl.benchmarks.
pes
(dimensions, neurons_per_d, neuron_type)[source]¶ PES learning rule benchmark.
 Parameters
 dimensionsint
Number of dimensions for vector values
 neurons_per_dint
Number of neurons to use per vector dimension
 neuron_type
NeuronType
Simulation neuron type
 Returns
 net
nengo.Network
benchmark network
 net

nengo_dl.benchmarks.
basal_ganglia
(dimensions, neurons_per_d, neuron_type)[source]¶ Basal ganglia network benchmark.
 Parameters
 dimensionsint
Number of dimensions for vector values
 neurons_per_dint
Number of neurons to use per vector dimension
 neuron_type
NeuronType
Simulation neuron type
 Returns
 net
nengo.Network
benchmark network
 net

nengo_dl.benchmarks.
mnist
(use_tensor_layer=True)[source]¶ A network designed to stresstest tensor layers (based on mnist net).
 Parameters
 use_tensor_layerbool
If True, use individual tensor_layers to build the network, as opposed to a single TensorNode containing all layers.
 Returns
 net
nengo.Network
benchmark network
 net

nengo_dl.benchmarks.
spaun
(dimensions)[source]¶ Builds the Spaun network from [1]
 Parameters
 dimensionsint
Number of dimensions for vector values
 Returns
 net
nengo.Network
benchmark network
 net
Notes
This network needs to be installed via
pip install git+https://github.com/drasmuss/spaun2.0.git
References
 1
Chris Eliasmith, Terrence C. Stewart, Xuan Choo, Trevor Bekolay, Travis DeWolf, Yichuan Tang, and Daniel Rasmussen (2012). A largescale model of the functioning brain. Science, 338:12021205.

nengo_dl.benchmarks.
random_network
(dimensions, neurons_per_d, neuron_type, n_ensembles, connections_per_ensemble, seed=0)[source]¶ Basal ganglia network benchmark.
 Parameters
 dimensionsint
Number of dimensions for vector values
 neurons_per_dint
Number of neurons to use per vector dimension
 neuron_type
NeuronType
Simulation neuron type
 n_ensemblesint
Number of ensembles in the network
 connections_per_ensembleint
Outgoing connections from each ensemble
 Returns
 net
nengo.Network
benchmark network
 net

nengo_dl.benchmarks.
run_profile
(net, train=False, n_steps=150, do_profile=True, reps=1, **kwargs)[source]¶ Run profiler on a benchmark network.
 Parameters
 net
Network
The nengo Network to be profiled.
 trainbool
If True, profile the
sim.train
function. Otherwise, profile thesim.run
function. n_stepsint
The number of timesteps to run the simulation.
 do_profilebool
Whether or not to run profiling
 repsint
Repeat the run this many times (only profile data from the last run will be kept).
 net
 Returns
 exec_timefloat
Time (in seconds) taken to run the benchmark, taking the minimum over
reps
.
Notes
kwargs will be passed on to
Simulator
Interface¶
The benchmark module also includes a commandline interface for building and running the benchmarks:
benchmarks¶
Commandline interface for benchmarks.
benchmarks [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...
build¶
Builds one of the benchmark networks
benchmarks build [OPTIONS]
Options

benchmark
<benchmark>
¶ Name of benchmark network

dimensions
<dimensions>
¶ Number of dimensions

neurons_per_d
<neurons_per_d>
¶ Neurons per dimension

neuron_type
<neuron_type>
¶ Nengo neuron model

kwarg
<kwarg>
¶ Arbitrary kwarg to pass to benchmark network (key=value)
matmulvsreduce¶
Compares two different approaches to batched matrix multiplication (tf.matmul vs tf.multiply+tf.reduce_sum).
This is relevant for figuring out which approach is more efficient on a given system for different matrix shapes (determining which method we use in DotIncBuilder).
benchmarks matmulvsreduce [OPTIONS]
profile¶
Runs profiling on a network (call after ‘build’)
benchmarks profile [OPTIONS]
Options

train
,
notrain
¶
Whether to profile training (as opposed to running) the network

n_steps
<n_steps>
¶ Number of steps for which to run the simulation

batch_size
<batch_size>
¶ Number of inputs to the model

device
<device>
¶ TensorFlow device on which to run the simulation

unroll
<unroll>
¶ Number of steps for which to unroll the simulation

timeonly
¶
Only count total time, rather than profiling internals