API reference¶

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 Pre-built model object dtype : tf.DType Deprecated, use nengo_dl.configure_settings(dtype=...) instead. device : None or "/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 : 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.

Parameters:	kwargs : dict See run_steps

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 non-default 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 non-default 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 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(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 non-default 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 (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(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 (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(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 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(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=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).

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.

Parameters:	obj : Probe or Ensemble or Connection Object whose simulation data is being accessed
Returns:	data : ndarray or BuiltEnsemble or BuiltConnection Array containing probed data if obj is a Probe, otherwise the corresponding parameter object

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 object-attribute 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 top-level 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 per-object 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 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).

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 top-level 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/nengo-extras/blob/master/nengo_extras/neurons.py

References

[1]	(1, 2) Eric Hunsberger and Chris Eliasmith (2015): Spiking deep networks with LIF neurons. https://arxiv.org/abs/1510.08829.

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

[1]	(1, 2) Xavier Glorot and Yoshua Bengio (2010): Understanding the difficulty of training deep feedforward neural networks. International conference on artificial intelligence and statistics. http://proceedings.mlr.press/v9/glorot10a/glorot10a.pdf.

class nengo_dl.dists.He(scale=1, distribution='normal')[source]¶

Weight initialization method from [1].

Parameters:	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 human-level 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 non-axis dimensions after computing the norm (including batch/time) in order to compute the overall objective value.

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[source]¶

Manages the operator build classes known to the nengo_dl build process.

classmethod pre_build(ops, signals, op_builds, config)[source]¶

Setup step for build classes, in which they compute any of the values that are constant across simulation timesteps.

Parameters:	ops : tuple of Operator The operator group to build into the model signals : signals.SignalDict Mapping from Signal to tf.Tensor (updated by operations) op_builds : dict of {tuple of Operator, OpBuilder} pre_build will populate this dictionary with the OpBuilder objects (which execute the pre-build step in their __init__)

classmethod build(ops, signals, op_builds)[source]¶

Build the computations implementing a single simulator timestep.

Parameters:	ops : tuple of Operator The operator group to build into the model signals : signals.SignalDict Mapping from Signal to tf.Tensor (updated by operations) op_builds : dict of {tuple of Operator, ~`.op_builders.OpBuilder`} Mapping from operator groups to the pre-built builder objects

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 tensorflow-gpu 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 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(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.

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.

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 Pre-built 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:[0-n]" 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()[source]¶

Build the operators that execute a single simulation timestep into the graph.

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 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(progress)[source]¶

Build simulation loop.

Parameters:	progress : utils.ProgressBar Progress bar for loop construction

build_inputs(progress)[source]¶

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

Parameters:	progress : utils.ProgressBar Progress bar for input construction

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

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 pre-built 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.

Parameters:	sigs : list of Signal Base signals arranged into the order in which they should reside in memory (e.g., output from graph_optimizer.order_signals)

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 book-keeping (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 hard-coded 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 in-place) 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