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 in-depth description of how to use these objects, see the User guide. The second section describes objects that only NengoDL developers need to worry about.
These objects are the main access points for the user-facing features of NengoDL.
The Simulator class is the access point for the main features of NengoDL,
including running
and training
a model.
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.
Network
or NoneA network object to be built and then simulated. If None,
then a built model must be passed to model
instead
Length of a simulator timestep, in seconds
Seed for all stochastic operators used in this simulator
Model
Pre-built model object
tf.DType
Deprecated, use nengo_dl.configure_settings(dtype=...)
instead.
"/cpu:0"
or "/gpu:[0-n]"
Device on which to execute computations (if None then uses the default device as determined by TensorFlow)
Unroll simulation loop by explicitly building the given number of iterations into the computation graph (improves simulation speed but increases build time)
The number of simultaneous inputs that will be passed through the network
If not None, save network output in the TensorFlow summary format to the given directory, which can be loaded into TensorBoard
If True (default), display progress information when building a model
reset
(self, seed=None)[source]¶Resets the simulator to initial conditions.
If not None, overwrite the default simulator seed with this value (note: this becomes the new default simulator seed)
soft_reset
(self, include_trainable=False, include_probes=False)[source]¶Resets the internal state of the simulation, but doesn’t rebuild the graph.
If True, also reset any training that has been performed on network parameters (e.g., connection weights)
If True, also clear probe data
step
(self, **kwargs)[source]¶Run the simulation for one time step.
See run_steps
Notes
Progress bar is disabled by default when running via this method.
run
(self, time_in_seconds, **kwargs)[source]¶Simulate for the given length of time.
Run the simulator for the given number of simulated seconds
See run_steps
run_steps
(self, n_steps, data=None, input_feeds=None, profile=False, progress_bar=True, extra_feeds=None)[source]¶Simulate for the given number of steps.
The number of simulation steps to be executed
Node
: ndarray
}Override the values of input Nodes with the given data. Arrays
should have shape (sim.minibatch_size, n_steps, node.size_out)
.
Node
: ndarray
}Deprecated, use data
instead.
If True, collect TensorFlow profiling information while the simulation is running (this will slow down the simulation). Can also pass a string specifying a non-default filename for the saved profile data.
If True, print information about the simulation status to standard output.
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
(self, data, optimizer, n_epochs=1, objective=None, shuffle=True, truncation=None, summaries=None, profile=False, extra_feeds=None, progress_bar=True)[source]¶Optimize the trainable parameters of the network using the given optimization method, minimizing the objective value over the given inputs and targets.
Node
or Probe
: ndarray
} or intInput 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.
tf.train.Optimizer
TensorFlow optimizer, e.g.
tf.train.GradientDescentOptimizer(learning_rate=0.1)
Run training for the given number of epochs (complete passes
through data
)
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.
If True, randomize the data into different minibatches each epoch
If not None, use truncated backpropagation when training the network, with the given truncation length.
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.
If True, collect TensorFlow profiling information while the simulation is running (this will slow down the simulation). Can also pass a string specifying a non-default filename for the saved profile data.
tf.Tensor
: ndarray
}Can be used to feed a value for arbitrary Tensors in the simulation (will be passed directly to the TensorFlow session)
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 non-differentiable
elements will result in an error. Examples of common
non-differentiable elements include LIF
,
Direct
, or processes/neurons that don’t have a
custom TensorFlow implementation (see
process_builders.SimProcessBuilder
/
neuron_builders.SimNeuronsBuilder
)
loss
(self, data, objective=None, combine=<function mean at 0x7effc19d6d08>, extra_feeds=None, progress_bar=True, training=False)[source]¶Compute the loss value for the given objective and inputs/targets.
Node
or Probe
: ndarray
} or intInput 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.
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.
Function used to combine objective values from each minibatch.
tf.Tensor
: ndarray
}Can be used to feed a value for arbitrary Tensors in the simulation (will be passed directly to the TensorFlow session)
If True, print information about the simulation status to standard output.
If True, run the network in training mode (where, e.g., spiking neuron models are swapped for the equivalent differentiable approximation).
Sum of computed error values for each function in objective
.
run_batch
(self, data, outputs, extra_feeds=None, extra_fetches=None, n_epochs=1, truncation=None, shuffle=False, profile=False, training=False, callback=None, combine=<function stack at 0x7effc198ca60>, isolate_state=True)[source]¶Run the simulation on a batch of input data, computing the given output functions.
Node
or Probe
: ndarray
} or intInput 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.
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.
tf.Tensor
: ndarray
}Can be used to feed a value for arbitrary Tensors in the simulation (will be passed directly to the TensorFlow session)
tf.Tensor
Can be used to fetch arbitrary (structures of) Tensor values from the simulation (will be fetched directly from the TensorFlow session).
Repeat data
for n_epochs
iterations.
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.
If True, randomize the data into different minibatches each epoch.
If True, collect TensorFlow profiling information while the simulation is running (this will slow down the simulation). Can also pass a string specifying a non-default filename for the saved profile data.
If True, run the network in training mode, otherwise run it in inference mode (this can affect things like the neuron model used).
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
.
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.
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.
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
(self, path, include_global=True, include_local=False)[source]¶Save network parameters to the given path
.
Filepath of parameter output file
If True (default True), save global/trainable network variables
If True (default False), save local (non-trainable) network variables
Notes
This function is useful for saving/loading entire models; for
saving/loading individual objects within a model, see
get_nengo_params
.
load_params
(self, path, include_global=True, include_local=False)[source]¶Load network parameters from the given path
.
Filepath of parameter input file
If True (default True), load global (trainable) network variables
If True (default False), load local (non-trainable) network variables
Notes
This function is useful for saving/loading entire models; for
saving/loading individual objects within a model, see
get_nengo_params
.
freeze_params
(self, objs)[source]¶Stores the live parameter values from the simulation back into a Nengo object definition.
This can be helpful for reusing a NengoDL model inside a different Simulator. For example:
with nengo.Network() as net:
< build network >
with nengo_dl.Simulator(net) as sim:
< run some optimization >
sim.freeze_params(net)
with nengo.Simulator(net) as sim2:
# run the network in the default Nengo simulator, with the
# trained parameters
sim2.run(1.0)
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 in-place, and it may slightly modify
the structure of that object. The goal is to have the object produce
the same output as it would if run in the NengoDL simulator. It may
not be possible to accurately freeze all possible object; if you run
into errors in this process, try manually extracting the parameters you
need in your model (from sim.data
).
get_nengo_params
(self, nengo_objs, as_dict=False)[source]¶Extract model parameters in a form that can be used to initialize Nengo objects in a different model.
For example:
with nengo.Network() as net:
a = nengo.Ensemble(10, 1)
b = nengo.Ensemble(10, 1)
c = nengo.Connection(a, b)
with nengo_dl.Simulator(net) as sim:
# < do some optimization >
params = sim.get_nengo_params([a, b, c])
with nengo.Network() as new_net:
# < build some other network >
# now we want to insert two connected ensembles with
# the same parameters as our previous network:
d = nengo.Ensemble(10, 1, **params[0])
e = nengo.Ensemble(10, 1, **params[1])
f = nengo.Connection(d, e, **params[2])
Ensemble
or Connection
A single object or list of objects for which we want to get the parameters.
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.
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
(self, outputs=None, atol=1e-05, 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).
tf.Tensor
or list of tf.Tensor
or list of Probe
Compute gradients wrt this output (if None, computes wrt each output probe)
Absolute error tolerance
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
(self, sample_every=None, dt=None)[source]¶Create a vector of times matching probed data.
Note that the range does not start at 0 as one might expect, but at
the first timestep (i.e., dt
).
The sampling period of the probe to create a range for.
If None, a time value for every dt
will be produced.
close
(self)[source]¶Close the simulation, freeing resources.
Notes
The simulation cannot be restarted after it is closed. This is not a technical limitation, just a design decision made for all Nengo simulators.
training_step
¶The number of training iterations that have been executed.
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
.
Simulator
The simulator from which data will be drawn
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__
(self, obj)[source]¶Return the data associated with obj
.
Probe
or Ensemble
or Connection
Object whose simulation data is being accessed
ndarray
or BuiltEnsemble
or BuiltConnection
Array containing probed data if obj
is a
Probe
, otherwise the corresponding
parameter object
get_params
(self, *obj_attrs)[source]¶Returns the current parameter values for the given objects.
NengoObject
, str)The Nengo object and attribute of that object for which we want to know the parameter values (each object-attribute pair specified as a tuple argument to the function).
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 allow parts of a model to be defined using TensorFlow and smoothly integrated with the rest of a Nengo model.
nengo_dl.tensor_node.
TensorNode
(tensor_func, size_in=Default, size_out=Default, label=Default)[source]¶Inserts TensorFlow code into a Nengo model.
A function that maps node inputs to outputs
The number of elements in the input vector
The number of elements in the output vector (if None, value will be
inferred by calling tensor_func
)
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).
NengoObject
Object providing input to the layer
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
.
If not None, reshape the input to the given shape
Synapse
Synapse to apply on connection from input
to this layer
ndarray
Transform matrix to apply on connection from input
to this layer
If True, also return the connection linking this layer to input
These arguments will be passed to layer_func
if it is callable, or
Ensemble
if layer_func
is a NeuronType
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
Connection
If return_conn
is True, also returns the connection object linking
input
and node
.
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
top-level Network config.
The settings are passed as keyword arguments to configure_settings
;
e.g., to set trainable
use configure_settings(trainable=True)
.
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 per-object basis (e.g.
net.config[my_ensemble].trainable = True
. See the documentation
for more details.
Pass one of the graph planners to change the default planner.
Pass one of the sort algorithms to change the default sorter.
Pass a list of graph simplification functions to change the default simplifications applied.
Config options passed to tf.Session
initialization (e.g., to change
the GPU memory allocation method
pass {"gpu_options.allow_growth": True}
).
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.
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
).
tf.DType
Set the floating point precision for simulation values.
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 per-probe 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
).
Value of setting
if it has been specified, else default
.
Additions to the neuron types included with Nengo
.
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 [R31ac3a189156-1].
Amount of smoothing around the firing threshold. Larger values mean more smoothing.
Membrane RC time constant, in seconds. Affects how quickly the membrane voltage decays to zero in the absence of input (larger = slower decay).
Absolute refractory period, in seconds. This is how long the membrane voltage is held at zero after a spike.
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/nengo-extras/blob/master/nengo_extras/neurons.py
References
Eric Hunsberger and Chris Eliasmith (2015): Spiking deep networks with LIF neurons. https://arxiv.org/abs/1510.08829.
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())
.
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.
Mean of the normal distribution
Standard deviation of the normal distribution
Resample any values more than this distance from the mean. If None, then limit will be set to 2 standard deviations.
sample
(self, n, d=None, rng=None)[source]¶Samples the distribution.
Number samples to take.
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,)
.
numpy.random.RandomState
Random number generator state (if None, will use the default numpy random number generator).
Samples as a 1d or 2d array depending on d
. The second
dimension enumerates the dimensions of the process.
nengo_dl.dists.
VarianceScaling
(scale=1, mode='fan_avg', distribution='uniform')[source]¶Variance scaling distribution for weight initialization (analogous to
TensorFlow init_ops.VarianceScaling
).
Overall scale on values
Whether to scale based on input or output dimensionality, or average of the two
Whether to use a uniform or normal distribution for weights
sample
(self, n, d=None, rng=None)[source]¶Samples the distribution.
Number samples to take.
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,)
.
numpy.random.RandomState
Random number generator state (if None, will use the default numpy random number generator).
Samples as a 1d or 2d array depending on d
. The second
dimension enumerates the dimensions of the process.
nengo_dl.dists.
Glorot
(scale=1, distribution='uniform')[source]¶Weight initialization method from [1] (also known as Xavier initialization).
Scale on weight distribution. For rectified linear units this should be sqrt(2), otherwise usually 1.
Whether to use a uniform or normal distribution for weights
References
Xavier Glorot and Yoshua Bengio (2010): Understanding the difficulty of training deep feedforward neural networks. International conference on artificial intelligence and statistics. http://proceedings.mlr.press/v9/glorot10a/glorot10a.pdf.
nengo_dl.dists.
He
(scale=1, distribution='normal')[source]¶Weight initialization method from [1].
Scale on weight distribution. For rectified linear units this should be sqrt(2), otherwise usually 1.
Whether to use a uniform or normal distribution for weights
References
Kaiming He, Xiangyu Zhang, Shaoqing Ren, and Jian Sun. (2015): Delving deep into rectifiers: Surpassing human-level performance on ImageNet classification. https://arxiv.org/abs/1502.01852.
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.
tf.Tensor
Output values from a Probe in a network.
tf.Tensor
Target values for a Probe in a network.
tf.Tensor
Tensor representing the mean squared error.
nengo_dl.objectives.
Regularize
(order=2, axis=None, weight=None)[source]¶An objective function to apply regularization penalties.
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.
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).
Scaling weight to apply to regularization penalty.
Notes
The mean will be computed across all the non-axis
dimensions after
computing the norm (including batch/time) in order to compute the overall
objective value.
These objects are only relevant to people interested in modifying the implementation of NengoDL (e.g., adding a new neuron type).
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.
nengo_dl.builder.
Builder
(plan, graph, signals, config)[source]¶Manages the operator build classes known to the nengo_dl
build process.
Operator
The groups of operators that will be built
tf.Graph
The simulation build graph
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
BuildConfig
Configuration parameters for the build process
pre_build
(self, progress=None)[source]¶Setup step for build classes, in which they compute any of the values that are constant across simulation timesteps.
utils.ProgressBar
Progress bar for ops in plan
build
(self, progress=None)[source]¶Build the computations implementing a single simulator timestep.
utils.ProgressBar
Progress bar for ops in plan
tf.Tensor
Outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used.
post_build
(self, sess, rng, progress=None)[source]¶Calls post build functions for all ops in plan.
tf.Session
The initialized simulation session
RandomState
Seeded random number generator
utils.ProgressBar
Progress bar for ops in plan
nengo_dl.builder.
BuildConfig
[source]¶Stores configuration parameters that may be relevant to parts of the build process.
If True the network should be constructed in “inference only” mode (not including any support for training operations).
Smoothing parameter for LIF
gradient approximation.
True if TensorFlow is only running on the CPU (because that was specified by the user or because tensorflow-gpu is not installed).
Create new instance of BuildConfig(inference_only, lif_smoothing, cpu_only)
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).
Operator
The operator group to build into the model
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
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
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
build_post
(self, ops, signals, sess, rng)[source]¶This function will be called after the graph has been built and session/variables initialized.
This should be used to build any random aspects of the operator.
Note that this function may be called multiple times per session, so it should modify the graph in-place.
Operator
The operator group to build into the model
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Session
The initialized simulation session
RandomState
Seeded random number generator
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.
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.
The Model
instance in which to store build
artifacts.
The object to build into the model.
nengo_dl.builder.
NengoModel
(*args, fail_fast=True, **kwargs)[source]¶Copy of the default Nengo model.
This allows us to override certain model behaviours.
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
(self, op)[source]¶Add an operator to the model.
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.
These objects are used to convert Nengo operators into TensorFlow graph elements.
Build classes for basic Nengo operators.
nengo_dl.op_builders.
ResetInc
(dst, value=0, tag=None)[source]¶A version of Reset that increments the target value rather than setting it.
dst
¶Overridden to return from incs rather than sets.
nengo_dl.op_builders.
ResetBuilder
(ops, signals, config)[source]¶Build a group of Reset
operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.op_builders.
CopyBuilder
(ops, signals, config)[source]¶Build a group of Copy
operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.op_builders.
ElementwiseIncBuilder
(ops, signals, config)[source]¶Build a group of ElementwiseInc
operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.op_builders.
DotIncBuilder
(ops, signals, config)[source]¶Build a group of DotInc
operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.op_builders.
SparseDotIncBuilder
(ops, signals, config)[source]¶Build a group of DotInc
operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.op_builders.
SimPyFuncBuilder
(ops, signals, config)[source]¶Build a group of SimPyFunc
operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
Build classes for Nengo neuron operators.
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 performance-critical neuron models should consider adding a custom TensorFlow implementation for their neuron type instead.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.neuron_builders.
RectifiedLinearBuilder
(ops, signals, config)[source]¶Build a group of RectifiedLinear
neuron operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.neuron_builders.
SpikingRectifiedLinearBuilder
(ops, signals, config)[source]¶Build a group of SpikingRectifiedLinear
neuron
operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.neuron_builders.
SigmoidBuilder
(ops, signals, config)[source]¶Build a group of Sigmoid
neuron operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.neuron_builders.
LIFRateBuilder
(ops, signals, config)[source]¶Build a group of LIFRate
neuron operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.neuron_builders.
SoftLIFRateBuilder
(ops, signals, config)[source]¶Build a group of SoftLIFRate
neuron operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.neuron_builders.
LIFBuilder
(ops, signals, config)[source]¶Build a group of LIF
neuron operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.neuron_builders.
SimNeuronsBuilder
(ops, signals, config)[source]¶Builds a group of SimNeurons
operators.
Calls the appropriate sub-build class for the different neuron types.
NeuronType
, builder.OpBuilder
}Mapping from neuron types to custom build classes (neurons without a custom builder will use the generic builder).
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
Build classes for Nengo learning rule operators.
nengo_dl.learning_rule_builders.
SimBCMBuilder
(ops, signals, config)[source]¶Build a group of SimBCM
operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.learning_rule_builders.
SimOjaBuilder
(ops, signals, config)[source]¶Build a group of SimOja
operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.learning_rule_builders.
SimVojaBuilder
(ops, signals, config)[source]¶Build a group of SimVoja
operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
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
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.
The presynaptic activity, \(a_i\).
The error signal, \(e_j\).
The synaptic weight change to be applied, \(\Delta \omega_{ij}\).
The scalar learning rate, \(\kappa\).
A label associated with the operator, for debugging purposes.
Notes
sets [delta]
incs []
reads [pre_filtered, error]
updates []
The presynaptic activity, \(a_i\).
The error signal, \(e_j\).
The synaptic weight change to be applied, \(\Delta \omega_{ij}\).
The scalar learning rate, \(\kappa\).
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.
The model to build into.
Learning rule type to build.
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.
nengo_dl.learning_rule_builders.
SimPESBuilder
(ops, signals, config)[source]¶Build a group of SimPES
operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
Build classes for Nengo process operators.
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 performance-critical processes should consider adding a custom TensorFlow implementation for their type instead.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
build_post
(self, ops, signals, sess, rng)[source]¶This function will be called after the graph has been built and session/variables initialized.
This should be used to build any random aspects of the operator.
Note that this function may be called multiple times per session, so it should modify the graph in-place.
Operator
The operator group to build into the model
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Session
The initialized simulation session
RandomState
Seeded random number generator
nengo_dl.process_builders.
LowpassBuilder
(ops, signals, config)[source]¶Build a group of Lowpass
synapse operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.process_builders.
LinearFilterBuilder
(ops, signals, config)[source]¶Build a group of LinearFilter
synapse operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
nengo_dl.process_builders.
SimProcessBuilder
(ops, signals, config)[source]¶Builds a group of SimProcess
operators.
Calls the appropriate sub-build class for the different process types.
Process
: builder.OpBuilder
}Mapping from process types to custom build classes (processes without a custom builder will use the generic builder).
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
build_post
(self, ops, signals, sess, rng)[source]¶This function will be called after the graph has been built and session/variables initialized.
This should be used to build any random aspects of the operator.
Note that this function may be called multiple times per session, so it should modify the graph in-place.
Operator
The operator group to build into the model
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Session
The initialized simulation session
RandomState
Seeded random number generator
Build classes for Nengo transform operators.
nengo_dl.transform_builders.
ConvIncBuilder
(ops, signals, config)[source]¶Build a group of ConvInc
operators.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
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
).
nengo_dl.tensor_node.
SimTensorNode
(func, time, input, output, tag=None)[source]¶Operator for TensorNodes (constructed by build_tensor_node
).
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.
nengo_dl.tensor_node.
SimTensorNodeBuilder
(ops, signals, config)[source]¶Builds a SimTensorNode
operator into a NengoDL
model.
build_step
(self, signals)[source]¶This function builds whatever computations need to be executed in each simulation timestep.
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Tensor
If not None, the returned tensors correspond to outputs with possible side-effects, i.e. computations that need to be executed in the TensorFlow graph even if their output doesn’t appear to be used
build_post
(self, ops, signals, sess, rng)[source]¶This function will be called after the graph has been built and session/variables initialized.
This should be used to build any random aspects of the operator.
Note that this function may be called multiple times per session, so it should modify the graph in-place.
Operator
The operator group to build into the model
signals.SignalDict
Mapping from Signal
to
tf.Tensor
(updated by operations)
tf.Session
The initialized simulation session
RandomState
Seeded random number generator
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.
nengo_dl.tensor_graph.
TensorGraph
(model, dt, unroll_simulation, dtype, minibatch_size, device, progress)[source]¶Manages the construction of the TensorFlow symbolic computation graph.
Model
Pre-built Nengo model describing the network to be simulated
Length of a simulator timestep, in seconds
Unroll simulation loop by explicitly building unroll_simulation
iterations into the computation graph
tf.DType
Floating point precision to use for simulation
The number of simultaneous inputs that will be passed through the network
"/cpu:0"
or "/gpu:[0-n]"
Device on which to execute computations (if None then uses the default device as determined by TensorFlow)
utils.ProgressBar
Progress bar for optimization stage
build
(self, progress)[source]¶Constructs a new graph to simulate the model.
utils.ProgressBar
Progress bar for construction stage
build_step
(self, progress)[source]¶Build the operators that execute a single simulation timestep into the graph.
utils.ProgressBar
Progress bar for loop construction
tf.Tensor
The Tensor objects representing the data required for each model Probe
tf.Tensor
The output Tensors of computations that may have side-effects
(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
(self, progress)[source]¶Build simulation loop.
utils.ProgressBar
Progress bar for loop construction
build_inputs
(self, progress)[source]¶Sets up the inputs in the model (which will be computed outside of TensorFlow and fed in each simulation block).
utils.ProgressBar
Progress bar for input construction
build_optimizer_func
(self, optimizer, objective)[source]¶Adds elements into the graph to execute the given optimizer.
tf.train.Optimizer
Instance of a TensorFlow optimizer class
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.
A function that builds the operators required to implement the
given optimizer update. Generally this function will then be
passed to build_outputs
.
Notes
This function caches its outputs, so if it is called again with the same arguments then it will return the previous function. This avoids building duplicates of the same operations over and over. This can also be important functionally, e.g. if the optimizer has internal state like momentum. By caching the output we ensure that subsequent calls share the same internal state.
build_outputs
(self, outputs)[source]¶Adds elements into the graph to compute the given outputs.
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.
Probe
: (tuple of) tf.Tensor
}Tensors representing the result of applying the output functions to the probes.
tf.Tensor
or NoneInitialization 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
(self, sess, rng)[source]¶Executes post-build 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.
tf.Session
The TensorFlow session for the simulator
RandomState
Seeded random number generator
build_summaries
(self, summaries)[source]¶Adds ops to collect summary data for the given objects.
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 pre-built summary tensor.
tf.Tensor
Merged summary op for the given summaries
get_tensor
(self, sig)[source]¶Returns a Tensor corresponding to the given Signal.
Signal
A signal in the model
tf.Tensor
Tensor containing the value of the given Signal
mark_signals
(self)[source]¶Mark all the signals in self.model
according to whether they
represent trainable parameters of the model (parameters that can be
optimized by deep learning methods).
Trainable parameters include connection weights, ensemble encoders, and neuron biases. Unless one of those signals is targeted by a Nengo learning rule (otherwise the learning rule update conflicts with the deep learning optimization).
Users can manually specify whether signals are trainable or not using
the config system (e.g.,
net.config[nengo.Ensemble].trainable = False
)
create_signals
(self, sigs)[source]¶Groups signal data together into larger arrays, and represent each individual signal as a slice into that array.
Signal
Base signals arranged into the order in which they should reside in
memory (e.g., output from graph_optimizer.order_signals
)
Represents and manages the internal simulation signals.
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.
ndarray
of intIndices along the first axis of the base array corresponding to the data for this signal
Key mapping to the base array that contains the data for this signal
dtype
dtype of the values represented by this signal
View shape of this signal (may differ from shape of base array)
If not None then this signal contains a minibatch dimension with the given size
A function that returns a TensorFlow constant (will be provided
by signals.SignalDict.get_tensor_signal
)
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__
(self, indices)[source]¶Create a new TensorSignal representing a subset (slice or advanced indexing) of the indices of this TensorSignal.
The desired subset of the indices in this TensorSignal
signals.TensorSignal
A new TensorSignal representing the subset of this TensorSignal
reshape
(self, shape)[source]¶Create a new TensorSignal representing a reshaped view of the same data in this TensorSignal (size of data must remain unchanged).
New shape for the signal (one dimension can be -1 to indicate an inferred dimension size, as in numpy)
signals.TensorSignal
New TensorSignal representing the same data as this signal but with the given shape
broadcast
(self, axis, length)[source]¶Add a new dimension by broadcasting this signal along axis
for the given length.
Where to insert the new dimension (currently only supports either the beginning or end of the array)
The number of times to duplicate signal along the broadcast dimension
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.
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.
tf.DType
Floating point precision used in signals
Number of items in each minibatch
scatter
(self, dst, val, mode='update')[source]¶Updates the base data corresponding to dst
.
TensorSignal
Signal indicating the data to be modified in base array
tf.Tensor
Update data (same shape as dst
, i.e. a dense array <= the size
of the base array)
Overwrite/add the data at dst
with val
gather
(self, src, force_copy=False)[source]¶Fetches the data corresponding to src
from the base array.
TensorSignal
Signal indicating the data to be read from base array
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.
tf.Tensor
Tensor object corresponding to a dense subset of data from the base array
mark_gather
(self, src)[source]¶Marks src
as being gathered, but doesn’t actually perform a
gather. Used to indicate that some computation relies on src
.
TensorSignal
Signal indicating the data being read
combine
(self, sigs, label='Combine')[source]¶Combines several TensorSignals into one by concatenating along the first axis.
TensorSignal
or Signal
Signals to be combined
Name for combined signal (to help with debugging)
TensorSignal
New TensorSignal representing the concatenation of the data in
sigs
make_internal
(self, name, shape, minibatched=True)[source]¶Creates a variable to represent an internal simulation signal.
This is to handle the case where we want to add a signal that is
not represented as a nengo.builder.Signal
in the Nengo op graph.
Name for the signal/variable.
Shape of the signal/variable.
Whether or not this signal contains a minibatch dimension.
TensorSignal
A TensorSignal representing the newly created variable.
get_tensor_signal
(self, indices, key, dtype, shape, minibatched, signal=None, label='TensorSignal')[source]¶Creates a new TensorSignal
with the given properties.
This should be used rather than instantiating a new TensorSignal
directly, as it handles some extra book-keeping (e.g., using the
custom constant
function).
ndarray
of intIndices along the first axis of the base array corresponding to the data for this signal
Key mapping to the base array that contains the data for this signal
dtype
dtype of the values represented by this signal
View shape of this signal (may differ from shape of base array)
Whether or not this signal contains a minibatch dimension
Signal
If not None, associate the new TensorSignal
with the given
Signal
in the sig_map
Name for this signal, used to make debugging easier
TensorSignal
A new TensorSignal
with the given properties
constant
(self, value, dtype=None, cutoff=33554432)[source]¶Returns a constant Tensor containing the given value.
The returned Tensor may be underpinned by a tf.constant
op, or
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 hard-coded limit of 2GB at the moment.
ndarray
Array containing the value of the constant
tf.DType
The type for the constant (if None
, the dtype of value
will be used)
The size of constant (in bytes) for which we will switch from
tf.constant
to tf.Variable
tf.Tensor
A tensor representing the given value
op_constant
(self, ops, op_sizes, attr, dtype, ndims=2)[source]¶Creates a tensor representing the constant parameters of an op group.
The operators for some merged group of ops
The number of constant elements in each op
The attribute of the op that describes the constant parameter
tf.DType
Numeric type of the parameter
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).
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.
These functions are used to restructure the Nengo operator graph so that it can be simulated more efficiently when converted into a TensorFlow graph.
nengo_dl.graph_optimizer.
mergeable
(op, chosen_ops)[source]¶Check if the given op can be merged with the candidate group
nengo_dl.graph_optimizer.
greedy_planner
(operators)[source]¶Combine mergeable operators into groups that will be executed as a single computation.
Operator
All the nengo
operators in a model (unordered)
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).
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.
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.
Dependency graph where dg[a] = {b, c}
indicates that operators
b
and c
are dependent on a
The operators for which we want to compute the transitive closure
The transitive closure for the graph (will be filled in-place)
One of the nengo_dl
build classes (e.g.,
CopyBuilder
), specifying the type of operators
to include in the transitive closure
The build class for each operator
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.
nengo_dl.graph_optimizer.
order_signals
(plan, n_passes=10)[source]¶Orders signals and operators to try to structure reads/writes in contiguous blocks.
Operator
Operator execution plan (e.g., output from greedy_planner
)
Number of repeated passes through the operator reordering stage
nengo_dl.graph_optimizer.
hamming_sort
(blocks)[source]¶Reorder signals using heuristics to try to place signals that are accessed by the same operators into adjacent positions (giving priority to larger blocks).
nengo_dl.graph_optimizer.
sort_ops_by_signals
(sorted_io, sigs, sig_idxs, new_plan, blocks, op_sigs)[source]¶Rearrange operators to match the order of signals.
Note: the same operators can be associated with multiple read blocks if they have multiple inputs, so rearranging the operators according to one of those blocks could mess up the order with respect to the other read block. We iterate through the read blocks in increasing size so that the largest blocks win out.
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.
Signal
Signals that have been arranged into a given order by other parts of the algorithm
Signal
: int}Sorted indices of signals
Operator
: tuple of Operator
}Mapping from original operator group to the sorted operators
Signal
: frozenset of int}Indicates which io blocks each signal participates in
Operator
: list of Signal
}The signals accessed by each operator
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.
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.
Signal
Signals to be sorted
Signal
: int}Sorted indices of signals
Operator
: tuple of Operator
}Mapping from original operator group to the sorted operators
Signal
: frozenset of int}Indicates which io blocks each signal participates in
Operator
: list of Signal
}The signals accessed by each operator
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).
nengo_dl.graph_optimizer.
remove_zero_incs
(operators)[source]¶Remove any operators where we know the input (and therefore output) is zero.
If the input to a DotInc/ElementwiseInc/Copy is zero then we know that the output of the op will be zero, so we can just get rid of it.
nengo_dl.graph_optimizer.
remove_constant_copies
(operators)[source]¶Change Copies with constant input to Resets.
If a Copy has no dependencies, or just one Reset() dependency, then we can change it to an op that just directly sets the output signal to the Copy input value.
nengo_dl.graph_optimizer.
remove_identity_muls
(operators)[source]¶Change y=x*1 ops to y=x Copy ops.
If one of the inputs to a DotInc/ElementwiseInc is 1 then we can skip the multiplication and change it to a Copy op.
nengo_dl.graph_optimizer.
signal_io_dicts
(operators)[source]¶Organizes operators into dictionaries according to the signals they set/inc/read/update.
Operator
Operators in the model
Signal
: list of Operator
}A dictionary indicating all the Operators that set each signal.
Signal
: list of Operator
}A dictionary indicating all the Operators that inc each signal.
Signal
: list of Operator
}A dictionary indicating all the Operators that read each signal.
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.
A string where each row corresponds to one operator group, and the non-blank 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).
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 [A-Za-z0-9_.\-/]
Name to be sanitized
Sanitized name
nengo_dl.utils.
function_name
(func, sanitize=True)[source]¶Get the name of the callable object func
.
Callable object (e.g., function, callable class)
If True, remove any illegal TensorFlow name characters from name
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.
Desired shape for function output (must have the same size as actual function output)
tf.DType
or dtype
Desired dtype of function output
nengo.exceptions.SimulationError
If the function returns None
or a non-finite value.
nengo_dl.utils.
print_op
(input, message)[source]¶Inserts a print statement into the TensorFlow graph.
tf.Tensor
The value of this tensor will be printed whenever it is computed in the graph
String prepended to the value of input
, to help with logging
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 non-differentiable elements
between inputs
and outputs
(elements that would prevent us from
computing d_outputs / d_inputs
.
tf.Tensor
Input tensors
tf.Tensor
Output tensors
nengo_dl.utils.
MessageBar
(msg='', finish_msg='', **kwargs)[source]¶ProgressBar widget for progress bars with possibly unknown duration.
A message to be displayed in the middle of the progress bar
A message to be displayed when the progress bar is finished
nengo_dl.utils.
ProgressBar
(present='', past=None, max_value=1, vars=None, **kwargs)[source]¶Handles progress bar display for some tracked process.
Description of process in present (e.g., “Simulating”)
Description of process in past (e.g., “Simulation”)
The maximum number of steps in the tracked process (or None
if
the maximum number of steps is unknown)
Extra variables that will be displayed at the end of the progress bar
Notes
Launches a separate thread to handle the progress bar display updates.
step
(self, **vars)[source]¶Advance the progress bar one step.
Values for the extra variables displayed at the end of the progress
bar (defined in __init__
)
sub
(self, msg=None, **kwargs)[source]¶Creates a new progress bar for tracking a sub-process.
Description of sub-process
max_steps
¶Alias for max_value to allow this to work with Nengo progress bar interface.
nengo_dl.utils.
SubProgressBar
(present='', past=None, max_value=1, vars=None, **kwargs)[source]¶A progress bar representing a sub-task within an overall progress bar.
nengo_dl.utils.
NullProgressBar
(present='', past=None, max_value=1, vars=None, **kwargs)[source]¶A progress bar that does nothing.
Used to replace ProgressBar when we want to disable output.
nengo_dl.utils.
minibatch_generator
(data, minibatch_size, shuffle=True, truncation=None, rng=None)[source]¶Generator to yield minibatch_sized
subsets from inputs
and
targets
.
NengoObject
: ndarray
}Data arrays to be divided into minibatches.
The number of items in each minibatch
If True, the division of items into minibatches will be randomized each time the generator is created
If not None, divide the data up into sequences of truncation
timesteps.
RandomState
Seeded random number generator
The simulation step at which the returned data begins (will only be
nonzero if truncation
is not None
).
Node
: ndarray
}The same structure as inputs
, but with each array reduced to
minibatch_size
elements along the first dimension
Probe
: ndarray
}The same structure as targets
, but with each array reduced to
minibatch_size
elements along the first dimension
Benchmark networks and utilities for evaluating NengoDL’s performance.
nengo_dl.benchmarks.
cconv
(dimensions, neurons_per_d, neuron_type)[source]¶Circular convolution (EnsembleArray) benchmark.
Number of dimensions for vector values
Number of neurons to use per vector dimension
NeuronType
Simulation neuron type
nengo.Network
benchmark network
nengo_dl.benchmarks.
integrator
(dimensions, neurons_per_d, neuron_type)[source]¶Single integrator ensemble benchmark.
Number of dimensions for vector values
Number of neurons to use per vector dimension
NeuronType
Simulation neuron type
nengo.Network
benchmark network
nengo_dl.benchmarks.
pes
(dimensions, neurons_per_d, neuron_type)[source]¶PES learning rule benchmark.
Number of dimensions for vector values
Number of neurons to use per vector dimension
NeuronType
Simulation neuron type
nengo.Network
benchmark network
nengo_dl.benchmarks.
basal_ganglia
(dimensions, neurons_per_d, neuron_type)[source]¶Basal ganglia network benchmark.
Number of dimensions for vector values
Number of neurons to use per vector dimension
NeuronType
Simulation neuron type
nengo.Network
benchmark network
nengo_dl.benchmarks.
mnist
(use_tensor_layer=True)[source]¶A network designed to stress-test tensor layers (based on mnist net).
If True, use individual tensor_layers to build the network, as opposed to a single TensorNode containing all layers.
nengo.Network
benchmark network
nengo_dl.benchmarks.
spaun
(dimensions)[source]¶Builds the Spaun network from [1]
Number of dimensions for vector values
nengo.Network
benchmark network
Notes
This network needs to be installed via
pip install git+https://github.com/drasmuss/spaun2.0.git
References
Chris Eliasmith, Terrence C. Stewart, Xuan Choo, Trevor Bekolay, Travis DeWolf, Yichuan Tang, and Daniel Rasmussen (2012). A large-scale model of the functioning brain. Science, 338:1202-1205.
nengo_dl.benchmarks.
random_network
(dimensions, neurons_per_d, neuron_type, n_ensembles, connections_per_ensemble, seed=0)[source]¶Basal ganglia network benchmark.
Number of dimensions for vector values
Number of neurons to use per vector dimension
NeuronType
Simulation neuron type
Number of ensembles in the network
Outgoing connections from each ensemble
nengo.Network
benchmark network
nengo_dl.benchmarks.
run_profile
(net, train=False, n_steps=150, do_profile=True, reps=1, **kwargs)[source]¶Run profiler on a benchmark network.
Network
The nengo Network to be profiled.
If True, profile the sim.train
function. Otherwise, profile the
sim.run
function.
The number of timesteps to run the simulation.
Whether or not to run profiling
Repeat the run this many times (only profile data from the last run will be kept).
Time (in seconds) taken to run the benchmark, taking the minimum over
reps
.
Notes
kwargs will be passed on to Simulator
The benchmark module also includes a command-line interface for building and running the benchmarks:
Command-line interface for benchmarks.
benchmarks [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...
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)
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 matmul-vs-reduce [OPTIONS]
Runs profiling on a network (call after ‘build’)
benchmarks profile [OPTIONS]
Options
--train
,
--no-train
¶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
--time-only
¶Only count total time, rather than profiling internals