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
 dt : float
Length of a simulator timestep, in seconds
 seed : int
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.
 device : None or
"/cpu:0" or "/gpu:[0n]"
Device on which to execute computations (if None then uses the
default device as determined by TensorFlow)
 unroll_simulation : int
Unroll simulation loop by explicitly building the given number of
iterations into the computation graph (improves simulation speed
but increases build time)
 minibatch_size : int
The number of simultaneous inputs that will be passed through the
network
 tensorboard : str
If not None, save network output in the TensorFlow summary format to
the given directory, which can be loaded into TensorBoard
 progress_bar : bool
If True (default), display progress information when building a model


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


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


step
(**kwargs)[source]
Run the simulation for one time step.
Notes
Progress bar is disabled by default when running via this method.

run
(time_in_seconds, **kwargs)[source]
Simulate for the given length of time.
Parameters: 
 time_in_seconds : float
Run the simulator for the given number of simulated seconds
 kwargs : dict
See run_steps


run_steps
(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_steps : int
The number of simulation steps to be executed
 data : dict 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_feeds : dict of {
Node : ndarray }
Deprecated, use data instead.
 profile : bool
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_bar : bool
If True, print information about the simulation status to standard
output.
 extra_feeds : dict 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, and n_steps > x
, this will
repeatedly execute x
timesteps until the the number of steps
executed is >= n_steps
.

train
(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: 
 data : dict of {
Node or Probe : 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_epochs : int
Run training for the given number of epochs (complete passes
through data )
 objective : dict of {(tuple of)
Probe : callable or None }
The objective to be minimized. The default applies
objectives.mse to all probes in data . This can be
overridden by passing 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 a tf.Tensor
representing a scalar loss value. The function may also accept a
single argument f(output) > loss if targets are not required.
Some common objective functions can be found in
nengo_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 in data 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.
 shuffle : bool
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.
 summaries : list of
Connection or Ensemble or Neurons or "loss" or tf.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 for objective ). The user can also create their
own summaries and pass in the Tensors representing the summary ops.
 profile : bool
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_feeds : dict 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_bar : bool
If True, print information about the simulation status to standard
output.

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 (see
process_builders.SimProcessBuilder
/
neuron_builders.SimNeuronsBuilder
)

loss
(data, objective=None, combine=<function mean>, extra_feeds=None, progress_bar=True, training=False)[source]
Compute the loss value for the given objective and inputs/targets.
Parameters: 
 data : dict of {
Node or Probe : 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.
 objective : dict of {(tuple of)
Probe : callable}
The objective to compute the loss. The default applies
objectives.mse to all probes in data . This can be
overridden by passing 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 a tf.Tensor
representing a scalar loss value. The function may also accept a
single argument f(output) > loss if targets are not required.
Some common objective functions can be found in
nengo_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.
 combine : callable
Function used to combine objective values from each minibatch.
 extra_feeds : dict 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_bar : bool
If True, print information about the simulation status to standard
output.
 training : bool
If True, run the network in training mode (where, e.g., spiking
neuron models are swapped for the equivalent differentiable
approximation).

Returns: 
 loss : float
Sum of computed error values for each function in objective .


run_batch
(data, outputs, extra_feeds=None, extra_fetches=None, n_epochs=1, truncation=None, shuffle=False, profile=False, training=False, callback=None, combine=<function stack>, isolate_state=True)[source]
Run the simulation on a batch of input data, computing the given
output functions.
Parameters: 
 data : dict of {
Node or Probe : 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.
 outputs : dict 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 a tf.Tensor , or tuple of Tensors,
which will be evaluated on each minibatch of data. If None
is given then the return value will be the output value from that
probe.
 extra_feeds : dict 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_epochs : int
Repeat data for n_epochs iterations.
 truncation : int
If not None, run the simulation truncation timesteps at a time.
Outputs from each truncation block will be passed sequentially to
combine , 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.
 shuffle : bool
If True, randomize the data into different minibatches each epoch.
 profile : bool
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.
 training : bool
If True, run the network in training mode, otherwise run it in
inference mode (this can affect things like the neuron model
used).
 callback : callable
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 of extra_feeds .
 combine : callable
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, then combine will be applied separately to each of
those outputs across the minibatches.
 isolate_state : bool
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.

Returns: 
 output_vals : dict of {(tuple of)
Probe : (tuple of) ndarray }
The result of computing outputs on simulation probe values,
given data . 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).

Notes
In general, users should call one of the wrappers for this function
(e.g., run_steps
, train
, or loss
),
according to their use case. However, this function can be called
directly to run the simulation in a customized way.

save_params
(path, include_global=True, include_local=False)[source]
Save network parameters to the given path
.
Parameters: 
 path : str
Filepath of parameter output file
 include_global : bool
If True (default True), save global/trainable network variables
 include_local : bool
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
(path, include_global=True, include_local=False)[source]
Load network parameters from the given path
.
Parameters: 
 path : str
Filepath of parameter input file
 include_global : bool
If True (default True), load global (trainable) network variables
 include_local : bool
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
(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.

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
(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 or Connection
A single object or list of objects for which we want to get the
parameters.
 as_dict : bool
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.

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 if as_dict=True ) of kwargs corresponding to multiple
input objects.


check_gradients
(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 of tf.Tensor or list of Probe
Compute gradients wrt this output (if None, computes wrt each
output probe)
 atol : float
Absolute error tolerance
 rtol : float
Relative (to numeric grad) error tolerance

Notes
Calling this function will reset all values in the network, so it
should not be intermixed with calls to Simulator.run
.

trange
(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_every : float (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
()[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.

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 via Simulator.train
, the updated
encoder values for an ensemble can be accessed via
trained_encoders = sim.data[my_ens].encoders
.
Parameters: 
 sim :
Simulator
The simulator from which data will be drawn
 minibatched : bool
If False, discard the minibatch dimension on probe data

Notes
SimulationData shouldn’t be created/accessed directly by the user, but
rather via sim.data
(which is an instance of SimulationData).

__getitem__
(obj)[source]
Return the data associated with obj
.

get_params
(*obj_attrs)[source]
Returns the current parameter values for the given objects.
Parameters: 
 obj_attrs : list 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).

Returns: 
 params : list of
ndarray
Current values of the requested parameters

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_func : callable
A function that maps node inputs to outputs
 size_in : int (Default: 0)
The number of elements in the input vector
 size_out : int (Default: None)
The number of elements in the output vector (if None, value will be
inferred by calling tensor_func )
 label : str (Default: None)
A name for the node, used for debugging and visualization


output
Ensure that nothing tries to evaluate the output
attribute
(indicating that something is trying to simulate this as a regular
nengo.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_func : callable or
NeuronType
A function that takes the value from input (represented as a
tf.Tensor ) and maps it to some output value, or a Nengo neuron
type, defining a nonlinearity that will be applied to input .
 shape_in : tuple of int
If not None, reshape the input to the given shape
 synapse : float 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_conn : bool
If True, also return the connection linking this layer to input
 layer_args : dict
These arguments will be passed to layer_func if it is callable, or
Ensemble if layer_func is a NeuronType

Returns: 
 node :
TensorNode or Neurons
A TensorNode that implements the given layer function (if
layer_func was a callable), or a Neuron object with the given
neuron type, connected to input
 conn :
Connection
If return_conn is True, also returns the connection object linking
input and 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 set trainable
use configure_settings(trainable=True)
.
Parameters: 
 trainable : bool or None
Adds a parameter to Nengo Ensembles/Connections/Networks that controls
whether or not they will be optimized by Simulator.train .
Passing None will use the default nengo_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.
 planner : graph planning algorithm
Pass one of the graph planners to change the
default planner.
 sorter : signal 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_only : bool
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_smoothing : float
If specified, use the smoothed SoftLIFRate neuron
model, with the given smoothing parameter (sigma ),
to compute the gradient for LIF neurons (as
opposed to using LIFRate ).
 dtype :
tf.DType
Set the floating point precision for simulation values.
 keep_history : bool
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: 
 model :
Model or Network
Built model or Network containing all the config settings.
 setting : str
Name of the config option to return.
 default
The default value to return if config option not set.
 obj :
NengoObject
The object on which config setting is stored (defaults to the toplevel
network).

Returns: 
 config_val
Value of setting if it has been specified, else default .

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 [1].
Parameters: 
 sigma : float
Amount of smoothing around the firing threshold. Larger values mean
more smoothing.
 tau_rc : float
Membrane RC time constant, in seconds. Affects how quickly the membrane
voltage decays to zero in the absence of input (larger = slower decay).
 tau_ref : float
Absolute refractory period, in seconds. This is how long the
membrane voltage is held at zero after a spike.
 amplitude : float
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

rates
(x, gain, bias)[source]
Always use LIFRate to determine rates.

step_math
(dt, J, output)[source]
Compute rates in Hz for input current (incl. bias)
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: 
 mean : float
Mean of the normal distribution
 stddev : float
Standard deviation of the normal distribution
 limit : float
Resample any values more than this distance from the mean. If None,
then limit will be set to 2 standard deviations.


sample
(n, d=None, rng=None)[source]
Samples the distribution.
Parameters: 
 n : int
Number samples to take.
 d : int 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 :
numpy.random.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: 
 scale : float
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
(n, d=None, rng=None)[source]
Samples the distribution.
Parameters: 
 n : int
Number samples to take.
 d : int 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 :
numpy.random.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: 
 scale : float
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

class
nengo_dl.dists.
He
(scale=1, distribution='normal')[source]
Weight initialization method from [1].
Parameters: 
 scale : float
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]  (1, 2) 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
are nan
, 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.

Returns: 
 mse :
tf.Tensor
Tensor representing the mean squared error.


class
nengo_dl.objectives.
Regularize
(order=2, axis=None, weight=None)[source]
An objective function to apply regularization penalties.
Parameters: 
 order : int 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.
 axis : int 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).
 weight : float
Scaling weight to apply to regularization penalty.

Notes
The mean will be computed across all the nonaxis
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: 
 plan : list 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 to
tf.Tensor (updated by operations)
 config :
BuildConfig
Configuration parameters for the build process


pre_build
(progress=None)[source]
Setup step for build classes, in which they compute any of the
values that are constant across simulation timesteps.

build
(progress=None)[source]
Build the computations implementing a single simulator timestep.
Parameters: 
 progress :
utils.ProgressBar
Progress bar for ops in plan

Returns: 
 side_effects : list 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.


post_build
(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


name_scope
(ops)[source]
Returns a new TensorFlow name scope for the given ops.

classmethod
register
(nengo_op)[source]
A decorator for adding a class to the build function registry.
Parameters: 
 nengo_op :
Operator
The operator associated with the build function being decorated.


class
nengo_dl.builder.
BuildConfig
[source]
Stores configuration parameters that may be relevant to parts of the
build process.
Parameters: 
 inference_only : bool
If True the network should be constructed in “inference only” mode
(not including any support for training operations).
 lif_smoothing : float
Smoothing parameter for LIF gradient approximation.
 cpu_only : bool
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: 
 ops : list of
Operator
The operator group to build into the model
 signals :
signals.SignalDict
Mapping from Signal to
tf.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).


build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


build_post
(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: 
 ops : list of
Operator
The operator group to build into the model
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)
 sess :
tf.Session
The initialized simulation session
 rng :
RandomState
Seeded random number generator


static
mergeable
(x, y)[source]
Compute the mergeability of two operators of this builder’s type.
Parameters: 
 x :
Operator
The operator being tested
 y :
Operator
The operator being merged into (this is representative of a group
of operators that have already been merged)

Returns: 
 mergeable : bool
True if x and y can be merged into a single built op,
else False .


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
into model
.
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: 
 model : Model
The Model instance in which to store build
artifacts.
 obj : object
The object to build into the model.


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_fast : bool
If True, try to call op.make_step when ops are added to the model.
Note that NengoDL doesn’t actually use make_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
(op)[source]
Add an operator to the model.
Parameters: 
 op :
Operator
Operator being added to the model.

Notes
This is a copy of the parent nengo.builder.Model.add_op
, with the
addition of the if 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.

class
nengo_dl.op_builders.
ResetBuilder
(ops, signals, config)[source]
Build a group of Reset
operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


static
mergeable
(x, y)[source]
Compute the mergeability of two operators of this builder’s type.
Parameters: 
 x :
Operator
The operator being tested
 y :
Operator
The operator being merged into (this is representative of a group
of operators that have already been merged)

Returns: 
 mergeable : bool
True if x and y can be merged into a single built op,
else False .


class
nengo_dl.op_builders.
CopyBuilder
(ops, signals, config)[source]
Build a group of Copy
operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


static
mergeable
(x, y)[source]
Compute the mergeability of two operators of this builder’s type.
Parameters: 
 x :
Operator
The operator being tested
 y :
Operator
The operator being merged into (this is representative of a group
of operators that have already been merged)

Returns: 
 mergeable : bool
True if x and y can be merged into a single built op,
else False .


class
nengo_dl.op_builders.
ElementwiseIncBuilder
(ops, signals, config)[source]
Build a group of ElementwiseInc
operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


static
mergeable
(x, y)[source]
Compute the mergeability of two operators of this builder’s type.
Parameters: 
 x :
Operator
The operator being tested
 y :
Operator
The operator being merged into (this is representative of a group
of operators that have already been merged)

Returns: 
 mergeable : bool
True if x and y can be merged into a single built op,
else False .


class
nengo_dl.op_builders.
DotIncBuilder
(ops, signals, config)[source]
Build a group of DotInc
operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


static
mergeable
(x, y)[source]
Compute the mergeability of two operators of this builder’s type.
Parameters: 
 x :
Operator
The operator being tested
 y :
Operator
The operator being merged into (this is representative of a group
of operators that have already been merged)

Returns: 
 mergeable : bool
True if x and y can be merged into a single built op,
else False .


class
nengo_dl.op_builders.
SparseDotIncBuilder
(ops, signals, config)[source]
Build a group of DotInc
operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


class
nengo_dl.op_builders.
SimPyFuncBuilder
(ops, signals, config)[source]
Build a group of SimPyFunc
operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


static
mergeable
(x, y)[source]
Compute the mergeability of two operators of this builder’s type.
Parameters: 
 x :
Operator
The operator being tested
 y :
Operator
The operator being merged into (this is representative of a group
of operators that have already been merged)

Returns: 
 mergeable : bool
True if x and y can be merged into a single built op,
else False .

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
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


class
nengo_dl.neuron_builders.
RectifiedLinearBuilder
(ops, signals, config)[source]
Build a group of RectifiedLinear
neuron operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


class
nengo_dl.neuron_builders.
SpikingRectifiedLinearBuilder
(ops, signals, config)[source]
Build a group of SpikingRectifiedLinear
neuron
operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


class
nengo_dl.neuron_builders.
SigmoidBuilder
(ops, signals, config)[source]
Build a group of Sigmoid
neuron operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


class
nengo_dl.neuron_builders.
LIFRateBuilder
(ops, signals, config)[source]
Build a group of LIFRate
neuron operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


class
nengo_dl.neuron_builders.
SoftLIFRateBuilder
(ops, signals, config)[source]
Build a group of SoftLIFRate
neuron operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


class
nengo_dl.neuron_builders.
LIFBuilder
(ops, signals, config)[source]
Build a group of LIF
neuron operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


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_IMPL : dict of {
NeuronType , builder.OpBuilder }
Mapping from neuron types to custom build classes (neurons without
a custom builder will use the generic builder).


build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


static
mergeable
(x, y)[source]
Compute the mergeability of two operators of this builder’s type.
Parameters: 
 x :
Operator
The operator being tested
 y :
Operator
The operator being merged into (this is representative of a group
of operators that have already been merged)

Returns: 
 mergeable : bool
True if x and y can be merged into a single built op,
else False .

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
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


static
mergeable
(x, y)[source]
Compute the mergeability of two operators of this builder’s type.
Parameters: 
 x :
Operator
The operator being tested
 y :
Operator
The operator being merged into (this is representative of a group
of operators that have already been merged)

Returns: 
 mergeable : bool
True if x and y can be merged into a single built op,
else False .


class
nengo_dl.learning_rule_builders.
SimOjaBuilder
(ops, signals, config)[source]
Build a group of SimOja
operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


static
mergeable
(x, y)[source]
Compute the mergeability of two operators of this builder’s type.
Parameters: 
 x :
Operator
The operator being tested
 y :
Operator
The operator being merged into (this is representative of a group
of operators that have already been merged)

Returns: 
 mergeable : bool
True if x and y can be merged into a single built op,
else False .


class
nengo_dl.learning_rule_builders.
SimVojaBuilder
(ops, signals, config)[source]
Build a group of SimVoja
operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


static
mergeable
(x, y)[source]
Compute the mergeability of two operators of this builder’s type.
Parameters: 
 x :
Operator
The operator being tested
 y :
Operator
The operator being merged into (this is representative of a group
of operators that have already been merged)

Returns: 
 mergeable : bool
True if x and y can be merged into a single built op,
else False .


class
nengo_dl.learning_rule_builders.
SimPES
(pre_filtered, error, delta, learning_rate, tag=None)[source]
Calculate connection weight change according to the PES rule.
Implements the PES learning rule of the form
\[\Delta \omega_{ij} = \frac{\kappa}{n} e_j a_i\]
where
 \(\kappa\) is a scalar learning rate,
 \(n\) is the number of presynaptic neurons
 \(e_j\) is the error for the jth output dimension, and
 \(a_i\) is the activity of a presynaptic neuron.
Parameters: 
 pre_filtered : Signal
The presynaptic activity, \(a_i\).
 error : Signal
The error signal, \(e_j\).
 delta : Signal
The synaptic weight change to be applied, \(\Delta \omega_{ij}\).
 learning_rate : float
The scalar learning rate, \(\kappa\).
 tag : str (Default: None)
A label associated with the operator, for debugging purposes.

Notes
 sets
[delta]
 incs
[]
 reads
[pre_filtered, error]
 updates
[]
Attributes: 
 pre_filtered : Signal
The presynaptic activity, \(a_i\).
 error : Signal
The error signal, \(e_j\).
 delta : Signal
The synaptic weight change to be applied, \(\Delta \omega_{ij}\).
 learning_rate : float
The scalar learning rate, \(\kappa\).
 tag : str (Default: None)
A label associated with the operator, for debugging purposes.


nengo_dl.learning_rule_builders.
build_pes
(model, pes, rule)[source]
Builds a nengo.PES
object into a model.
Parameters: 
 model : Model
The model to build into.
 pes : PES
Learning rule type to build.
 rule : LearningRule
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 same nengo.PES
instance.

class
nengo_dl.learning_rule_builders.
SimPESBuilder
(ops, signals, config)[source]
Build a group of SimPES
operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


static
mergeable
(x, y)[source]
Compute the mergeability of two operators of this builder’s type.
Parameters: 
 x :
Operator
The operator being tested
 y :
Operator
The operator being merged into (this is representative of a group
of operators that have already been merged)

Returns: 
 mergeable : bool
True if x and y can be merged into a single built op,
else False .

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
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


build_post
(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: 
 ops : list of
Operator
The operator group to build into the model
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)
 sess :
tf.Session
The initialized simulation session
 rng :
RandomState
Seeded random number generator


class
nengo_dl.process_builders.
LowpassBuilder
(ops, signals, config)[source]
Build a group of Lowpass
synapse operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


class
nengo_dl.process_builders.
LinearFilterBuilder
(ops, signals, config)[source]
Build a group of LinearFilter
synapse operators.

build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


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_IMPL : dict of {
Process : builder.OpBuilder }
Mapping from process types to custom build classes (processes without
a custom builder will use the generic builder).


build_step
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


build_post
(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: 
 ops : list of
Operator
The operator group to build into the model
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)
 sess :
tf.Session
The initialized simulation session
 rng :
RandomState
Seeded random number generator


static
mergeable
(x, y)[source]
Compute the mergeability of two operators of this builder’s type.
Parameters: 
 x :
Operator
The operator being tested
 y :
Operator
The operator being merged into (this is representative of a group
of operators that have already been merged)

Returns: 
 mergeable : bool
True if x and y can be merged into a single built op,
else False .

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: 
 func : callable
The TensorNode function (tensor_func )
 time :
Signal
Signal representing the current simulation time
 input :
Signal or None
Input Signal for the TensorNode (or None if size_in==0)
 output :
Signal
Output Signal for the TensorNode
 tag : str
A label associated with the operator, for debugging

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
(signals)[source]
This function builds whatever computations need to be executed in
each simulation timestep.
Parameters: 
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)

Returns: 
 side_effects : list 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


build_post
(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: 
 ops : list of
Operator
The operator group to build into the model
 signals :
signals.SignalDict
Mapping from Signal to
tf.Tensor (updated by operations)
 sess :
tf.Session
The initialized simulation session
 rng :
RandomState
Seeded random number generator

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
 dt : float
Length of a simulator timestep, in seconds
 unroll_simulation : int
Unroll simulation loop by explicitly building unroll_simulation
iterations into the computation graph
 dtype :
tf.DType
Floating point precision to use for simulation
 minibatch_size : int
The number of simultaneous inputs that will be passed through the
network
 device : None 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


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

build_step
(progress)[source]
Build the operators that execute a single simulation timestep
into the graph.
Parameters: 
 progress :
utils.ProgressBar
Progress bar for loop construction

Returns: 
 probe_tensors : list of
tf.Tensor
The Tensor objects representing the data required for each model
Probe
 side_effects : list 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


build_loop
(progress)[source]
Build simulation loop.

build_inputs
(progress)[source]
Sets up the inputs in the model (which will be computed outside of
TensorFlow and fed in each simulation block).

build_optimizer_func
(optimizer, objective)[source]
Adds elements into the graph to execute the given optimizer.
Parameters: 
 optimizer :
tf.train.Optimizer
Instance of a TensorFlow optimizer class
 objective : dict of {
Probe : callable or None }
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 a tf.Tensor
representing a scalar loss value. The function may also accept a
single argument f(output) > loss if targets are not required.
Some common objective functions can be found in
nengo_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 in data 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.

Returns: 
 apply_optimizer : callable
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
(outputs)[source]
Adds elements into the graph to compute the given outputs.
Parameters: 
 outputs : dict 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. If None is
given instead of a function then the output will simply be the
output value from the corresponding probes.

Returns: 
 output_vals : dict 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.

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
(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


build_summaries
(summaries)[source]
Adds ops to collect summary data for the given objects.
Parameters: 
 summaries : list of dict or
Connection or Ensemble or Neurons or tf.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.

Returns: 
 op :
tf.Tensor
Merged summary op for the given summaries


get_tensor
(sig)[source]
Returns a Tensor corresponding to the given Signal.
Parameters: 
 sig :
Signal
A signal in the model

Returns: 
 tensor :
tf.Tensor
Tensor containing the value of the given Signal


mark_signals
()[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
(sigs)[source]
Groups signal data together into larger arrays, and represent each
individual signal as a slice into that array.
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: 
 indices : tuple or list or
ndarray of int
Indices along the first axis of the base array corresponding to the
data for this signal
 key : object
Key mapping to the base array that contains the data for this signal
 dtype :
dtype
dtype of the values represented by this signal
 shape : tuple of int
View shape of this signal (may differ from shape of base array)
 minibatch_size : int
If not None then this signal contains a minibatch dimension with the
given size
 constant : callable
A function that returns a TensorFlow constant (will be provided
by signals.SignalDict.get_tensor_signal )
 label : str
Name for this signal, used to make debugging easier


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

ndim
The rank of this signal.

__getitem__
(indices)[source]
Create a new TensorSignal representing a subset (slice or advanced
indexing) of the indices of this TensorSignal.
Parameters: 
 indices : slice 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


reshape
(shape)[source]
Create a new TensorSignal representing a reshaped view of the
same data in this TensorSignal (size of data must remain unchanged).
Parameters: 
 shape : tuple 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


broadcast
(axis, length)[source]
Add a new dimension by broadcasting this signal along axis
for the given length.
Parameters: 
 axis : 0 or 1
Where to insert the new dimension (currently only supports either
the beginning or end of the array)
 length : int
The number of times to duplicate signal along the broadcast
dimension

Returns: 
 sig :
signals.TensorSignal
TensorSignal with new broadcasted shape


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

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

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
.

full_shape
Shape of the signal including the minibatch dimension.

minibatched
Whether or not this TensorSignal contains a minibatch dimension.

class
nengo_dl.signals.
SignalDict
(dtype, minibatch_size)[source]
Handles the mapping from Signal
to tf.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_size : int
Number of items in each minibatch


scatter
(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 with val


gather
(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_copy : bool
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.

Returns: 
 gathered :
tf.Tensor
Tensor object corresponding to a dense subset of data from the
base array


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


combine
(sigs, label='Combine')[source]
Combines several TensorSignals into one by concatenating along
the first axis.
Parameters: 
 sigs : list of
TensorSignal or Signal
Signals to be combined
 label : str
Name for combined signal (to help with debugging)

Returns: 
 sig :
TensorSignal
New TensorSignal representing the concatenation of the data in
sigs


make_internal
(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: 
 name : str
Name for the signal/variable.
 shape : tuple of int
Shape of the signal/variable.
 minibatched : bool
Whether or not this signal contains a minibatch dimension.

Returns: 
 sig :
TensorSignal
A TensorSignal representing the newly created variable.


get_tensor_signal
(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: 
 indices : tuple or list or
ndarray of int
Indices along the first axis of the base array corresponding to the
data for this signal
 key : object
Key mapping to the base array that contains the data for this
signal
 dtype :
dtype
dtype of the values represented by this signal
 shape : tuple of int
View shape of this signal (may differ from shape of base array)
 minibatched : bool
Whether or not this signal contains a minibatch dimension
 signal :
Signal
If not None, associate the new TensorSignal with the given
Signal in the sig_map
 label : str
Name for this signal, used to make debugging easier

Returns: 
 sig :
TensorSignal
A new TensorSignal with the given properties


constant
(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
a tf.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: 
 value :
ndarray
Array containing the value of the constant
 dtype :
tf.DType
The type for the constant (if None , the dtype of value
will be used)
 cutoff : int
The size of constant (in bytes) for which we will switch from
tf.constant to tf.Variable

Returns: 
 constant :
tf.Tensor
A tensor representing the given value


op_constant
(ops, op_sizes, attr, dtype, ndims=2)[source]
Creates a tensor representing the constant parameters of an op group.
Parameters: 
 ops : list of object
The operators for some merged group of ops
 op_sizes : list of int
The number of constant elements in each op
 attr : str
The attribute of the op that describes the constant parameter
 dtype :
tf.DType
Numeric type of the parameter
 ndims : int
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.

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
Parameters: 
 op :
Operator
The operator to be merged
 chosen_ops : list of
Operator
The operator group to be merged in to

Returns: 
 mergeable : bool
True if op can be merged into chosen_ops , else False


nengo_dl.graph_optimizer.
greedy_planner
(operators)[source]
Combine mergeable operators into groups that will be executed as a
single computation.
Parameters: 
 operators : list of
Operator
All the nengo operators in a model (unordered)

Returns: 
 plan : list of tuple of
Operator
Operators combined into mergeable groups and in execution order

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 to
greedy_planner
, and max_depth==len(op_list)
is full tree
search (guaranteed to find the optimal plan, but likely very slow).
Parameters: 
 op_list : list of
Operator
All the nengo operators in a model (unordered)
 max_depth : int
The planner will search this many steps ahead before selecting which
group to schedule next

Returns: 
 plan : list of tuple of
Operator
Operators combined into mergeable groups and in execution order


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
and
tree_planner
; it can improve simulation time over the greedy
planner, but comes with potentially significant build time increases.
Parameters: 
 op_list : list of
Operator
All the nengo operators in a model (unordered)

Returns: 
 plan : list of tuple of
Operator
Operators combined into mergeable groups and in execution order


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: 
 dg : dict of {int: set of int}
Dependency graph where dg[a] = {b, c} indicates that operators
b and c are dependent on a
 ops : list of int
The operators for which we want to compute the transitive closure
 trans : dict of {int: set of int}
The transitive closure for the graph (will be filled inplace)
 builder_type : type
One of the nengo_dl build classes (e.g.,
CopyBuilder ), specifying the type of operators
to include in the transitive closure
 builder_types : list of type
The build class for each operator
 cache : dict of {frozenset of int: set of int}
Stores base sets which trans will reference (to reduce memory
usage, since many elements in trans 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.
Parameters: 
 operators : list of
Operator
All the nengo operators in a model (unordered)

Returns: 
 plan : list of tuple of
Operator
Operators in execution order


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: 
 plan : list of tuple of
Operator
Operator execution plan (e.g., output from greedy_planner )
 n_passes : int
Number of repeated passes through the operator reordering stage

Returns: 
 signals : list of
Signal
Signals organized into the order in which we want them arranged in
memory
 plan : list of tuple of
Operator
Input plan with operators reordered within groups to align with order
of signals


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).
Parameters: 
 blocks : dict of {
Signal : frozenset of int}
Dictionary indicating which io blocks each signal is a part of

Returns: 
 sort_idxs : dict of {
Signal : int}
Indices indicating where each signal should be in the sorted list


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_io : list 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.
 sigs : list of
Signal
Signals that have been arranged into a given order by other parts
of the algorithm
 sig_idxs : dict of {
Signal : int}
Sorted indices of signals
 new_plan : dict of {tuple of
Operator : tuple of Operator }
Mapping from original operator group to the sorted operators
 blocks : dict of {
Signal : frozenset of int}
Indicates which io blocks each signal participates in
 op_sigs : dict of {
Operator : list of Signal }
The signals accessed by each operator

Returns: 
 new_plan : dict of {tuple of
Operator : tuple of Operator }
Mapping from original operator group to the sorted operators
 sig_idxs : dict of {
Signal : int}
Signal indices, possibly updated to match new op order


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_io : list 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.
 sigs : list of
Signal
Signals to be sorted
 sig_idxs : dict of {
Signal : int}
Sorted indices of signals
 new_plan : dict of {tuple of
Operator : tuple of Operator }
Mapping from original operator group to the sorted operators
 blocks : dict of {
Signal : frozenset of int}
Indicates which io blocks each signal participates in
 op_sigs : dict of {
Operator : list of Signal }
The signals accessed by each operator

Returns: 
 sig_idxs : dict of {
Signal : int}
Sorted indices of signals


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).
Parameters: 
 operators : list of
Operator
Operators in the model

Returns: 
 new_operators : list of
Operator
Modified list of operators


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.
Parameters: 
 operators : list of
Operator
Operators in the model

Returns: 
 new_operators : list of
Operator
Modified list of operators


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.
Parameters: 
 operators : list of
Operator
Operators in the model

Returns: 
 new_operators : list of
Operator
Modified list of operators


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.
Parameters: 
 operators : list of
Operator
Operators in the model

Returns: 
 new_operators : list of
Operator
Modified list of operators


nengo_dl.graph_optimizer.
signal_io_dicts
(operators)[source]
Organizes operators into dictionaries according to the signals they
set/inc/read/update.
Parameters: 
 operators : list of
Operator
Operators in the model

Returns: 
 sets : dict of {
Signal : list of Operator }
A dictionary indicating all the Operators that set each signal.
 incs : dict of {
Signal : list of Operator }
A dictionary indicating all the Operators that inc each signal.
 reads : dict of {
Signal : list of Operator }
A dictionary indicating all the Operators that read each signal.
 updates : dict of {
Signal : list of Operator }
A dictionary indicating all the Operators that update each signal.


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: 
 operators : list of tuple of
Operator
Operator execution plan
 all_signals : list of
Signal
Base signals arranged into some order

Returns: 
 signal_blocks : str
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: 
 name : str
Name to be sanitized

Returns: 
 sanitized : str
Sanitized name


nengo_dl.utils.
function_name
(func, sanitize=True)[source]
Get the name of the callable object func
.
Parameters: 
 func : callable
Callable object (e.g., function, callable class)
 sanitize : bool
If True, remove any illegal TensorFlow name characters from name

Returns: 
 name : str
Name of func (optionally sanitized)


nengo_dl.utils.
align_func
(output_shape, output_dtype)[source]
Decorator that ensures the output of func
is an
ndarray
with the given shape and dtype.
Parameters: 
 output_shape : tuple of int
Desired shape for function output (must have the same size as actual
function output)
 output_dtype :
tf.DType or dtype
Desired dtype of function output

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
 message : str
String prepended to the value of input , to help with logging

Returns: 
 op :
tf.Tensor
New tensor representing the print operation applied to input

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
and outputs
(elements that would prevent us from
computing d_outputs / d_inputs
.
Parameters: 
 inputs : list of
tf.Tensor
Input tensors
 outputs : list of
tf.Tensor
Output tensors


class
nengo_dl.utils.
MessageBar
(msg='', finish_msg='', **kwargs)[source]
ProgressBar widget for progress bars with possibly unknown duration.
Parameters: 
 msg : str
A message to be displayed in the middle of the progress bar
 finish_msg : str
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: 
 present : str
Description of process in present (e.g., “Simulating”)
 past : str
Description of process in past (e.g., “Simulation”)
 max_value : int or None
The maximum number of steps in the tracked process (or None if
the maximum number of steps is unknown)
 vars : list 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.

start
(**kwargs)[source]
Start tracking process, initialize display.

finish
(**kwargs)[source]
Stop tracking process, finish display.

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


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


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.

finish
()[source]
Finishing a subprogress bar doesn’t start a new line.

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.

sub
(*args, **kwargs)[source]
Noop for creating a subprogress bar.

step
(**kwargs)[source]
Noop for incrementing the progress bar.

nengo_dl.utils.
minibatch_generator
(data, minibatch_size, shuffle=True, truncation=None, rng=None)[source]
Generator to yield minibatch_sized
subsets from inputs
and
targets
.
Parameters: 
 data : dict of {
NengoObject : ndarray }
Data arrays to be divided into minibatches.
 minibatch_size : int
The number of items in each minibatch
 shuffle : bool
If True, the division of items into minibatches will be randomized each
time the generator is created
 truncation : int
If not None, divide the data up into sequences of truncation
timesteps.
 rng :
RandomState
Seeded random number generator

Yields: 
 offset : int
The simulation step at which the returned data begins (will only be
nonzero if truncation is not None ).
 inputs : dict of {
Node : ndarray }
The same structure as inputs , but with each array reduced to
minibatch_size elements along the first dimension
 targets : dict of {
Probe : ndarray }
The same structure as targets , but with each array reduced to
minibatch_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: 
 dimensions : int
Number of dimensions for vector values
 neurons_per_d : int
Number of neurons to use per vector dimension
 neuron_type :
NeuronType
Simulation neuron type

Returns: 
 net :
nengo.Network
benchmark network


nengo_dl.benchmarks.
integrator
(dimensions, neurons_per_d, neuron_type)[source]
Single integrator ensemble benchmark.
Parameters: 
 dimensions : int
Number of dimensions for vector values
 neurons_per_d : int
Number of neurons to use per vector dimension
 neuron_type :
NeuronType
Simulation neuron type

Returns: 
 net :
nengo.Network
benchmark network


nengo_dl.benchmarks.
pes
(dimensions, neurons_per_d, neuron_type)[source]
PES learning rule benchmark.
Parameters: 
 dimensions : int
Number of dimensions for vector values
 neurons_per_d : int
Number of neurons to use per vector dimension
 neuron_type :
NeuronType
Simulation neuron type

Returns: 
 net :
nengo.Network
benchmark network


nengo_dl.benchmarks.
basal_ganglia
(dimensions, neurons_per_d, neuron_type)[source]
Basal ganglia network benchmark.
Parameters: 
 dimensions : int
Number of dimensions for vector values
 neurons_per_d : int
Number of neurons to use per vector dimension
 neuron_type :
NeuronType
Simulation neuron type

Returns: 
 net :
nengo.Network
benchmark network


nengo_dl.benchmarks.
mnist
(use_tensor_layer=True)[source]
A network designed to stresstest tensor layers (based on mnist net).
Parameters: 
 use_tensor_layer : bool
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


nengo_dl.benchmarks.
spaun
(dimensions)[source]
Builds the Spaun network from [1]
Parameters: 
 dimensions : int
Number of dimensions for vector values

Returns: 
 net :
nengo.Network
benchmark network

Notes
This network needs to be installed via
pip install git+https://github.com/drasmuss/spaun2.0.git
References
[1]  (1, 2) 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: 
 dimensions : int
Number of dimensions for vector values
 neurons_per_d : int
Number of neurons to use per vector dimension
 neuron_type :
NeuronType
Simulation neuron type
 n_ensembles : int
Number of ensembles in the network
 connections_per_ensemble : int
Outgoing connections from each ensemble

Returns: 
 net :
nengo.Network
benchmark network


nengo_dl.benchmarks.
run_profile
(net, train=False, n_steps=150, do_profile=True, **kwargs)[source]
Run profiler on a benchmark network.
Parameters: 
 net :
Network
The nengo Network to be profiled.
 train : bool
If True, profile the sim.train function. Otherwise, profile the
sim.run function.
 n_steps : int
The number of timesteps to run the simulation.
 do_profile : bool
Whether or not to run profiling

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