API reference

This section details the modules, classes, and functions available in NengoDL. It is divided into two sections. The first section describes the objects relevant to NengoDL users. For a more 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.

Users

These objects are the main access points for the user-facing features of NengoDL.

Simulator

The Simulator class is the access point for the main features of NengoDL, including running and training a model.

class nengo_dl.simulator.Simulator(network, dt=0.001, seed=None, model=None, dtype=None, device=None, unroll_simulation=1, minibatch_size=None, tensorboard=None, progress_bar=True)

Simulate network using the nengo_dl backend.

Parameters

networkNetwork or None

A network object to be built and then simulated. If None, then a built model must be passed to model instead

dtfloat

Length of a simulator timestep, in seconds

seedint

Seed for all stochastic operators used in this simulator

modelModel

Pre-built model object

dtypetf.DType

Deprecated, use nengo_dl.configure_settings(dtype=...) instead.

deviceNone 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_simulationint

Unroll simulation loop by explicitly building the given number of iterations into the computation graph (improves simulation speed but increases build time)

minibatch_sizeint

The number of simultaneous inputs that will be passed through the network

tensorboardstr

If not None, save network output in the TensorFlow summary format to the given directory, which can be loaded into TensorBoard

progress_barbool

If True (default), display progress information when building a model

reset(self, seed=None)

Resets the simulator to initial conditions.

Parameters

seedint

If not None, overwrite the default simulator seed with this value (note: this becomes the new default simulator seed)

soft_reset(self, include_trainable=False, include_probes=False)

Resets the internal state of the simulation, but doesn’t rebuild the graph.

Parameters

include_trainablebool

If True, also reset any training that has been performed on network parameters (e.g., connection weights)

include_probesbool

If True, also clear probe data

step(self, **kwargs)

Run the simulation for one time step.

Parameters

kwargsdict

See run_steps

Notes

Progress bar is disabled by default when running via this method.

run(self, time_in_seconds, **kwargs)

Simulate for the given length of time.

Parameters

time_in_secondsfloat

Run the simulator for the given number of simulated seconds

kwargsdict

See run_steps

run_steps(self, n_steps, data=None, input_feeds=None, profile=False, progress_bar=True, extra_feeds=None)

Simulate for the given number of steps.

Parameters

n_stepsint

The number of simulation steps to be executed

datadict of {Node: ndarray}

Override the values of input Nodes with the given data. Arrays should have shape (sim.minibatch_size, n_steps, node.size_out).

input_feedsdict of {Node: ndarray}

Deprecated, use data instead.

profilebool

If True, collect TensorFlow profiling information while the simulation is running (this will slow down the simulation). Can also pass a string specifying a non-default filename for the saved profile data.

progress_barbool

If True, print information about the simulation status to standard output.

extra_feedsdict of {tf.Tensor: ndarray}

Can be used to feed a value for arbitrary Tensors in the simulation (will be passed directly to the TensorFlow session)

Notes

If unroll_simulation=x is specified, 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)

Optimize the trainable parameters of the network using the given optimization method, minimizing the objective value over the given inputs and targets.

Parameters

datadict of {Node 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.

optimizertf.train.Optimizer

TensorFlow optimizer, e.g. tf.train.GradientDescentOptimizer(learning_rate=0.1)

n_epochsint

Run training for the given number of epochs (complete passes through data)

objectivedict of {(tuple of) Probe: callable 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.

shufflebool

If True, randomize the data into different minibatches each epoch

truncation: int

If not None, use truncated backpropagation when training the network, with the given truncation length.

summarieslist of Connection 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.

profilebool

If True, collect TensorFlow profiling information while the simulation is running (this will slow down the simulation). Can also pass a string specifying a non-default filename for the saved profile data.

extra_feedsdict of {tf.Tensor: ndarray}

Can be used to feed a value for arbitrary Tensors in the simulation (will be passed directly to the TensorFlow session)

progress_barbool

If True, print information about the simulation status to standard output.

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 0x7fbad99b18c8>, extra_feeds=None, progress_bar=True, training=False)

Compute the loss value for the given objective and inputs/targets.

Parameters

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

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

combinecallable

Function used to combine objective values from each minibatch.

extra_feedsdict of {tf.Tensor: ndarray}

Can be used to feed a value for arbitrary Tensors in the simulation (will be passed directly to the TensorFlow session)

progress_barbool

If True, print information about the simulation status to standard output.

trainingbool

If True, run the network in training mode (where, e.g., spiking neuron models are swapped for the equivalent differentiable approximation).

Returns

lossfloat

Sum of computed error values for each function in objective.

run_batch(self, data, outputs, extra_feeds=None, extra_fetches=None, n_epochs=1, truncation=None, shuffle=False, profile=False, training=False, callback=None, combine=<function stack at 0x7fbad9929048>, isolate_state=True)

Run the simulation on a batch of input data, computing the given output functions.

Parameters

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

outputsdict of {(tuple of) Probe: callable or None}

Functions to apply to probe outputs. Functions can accept one positional argument (the output from that probe on one minibatch) or two (also passed the corresponding target value from data). If a tuple of Probes are given as the key then the first argument will be a list of probe outputs, and the second argument will be the corresponding list of target values. The function can return 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_feedsdict of {tf.Tensor: ndarray}

Can be used to feed a value for arbitrary Tensors in the simulation (will be passed directly to the TensorFlow session)

extra_fetches(list/tuple/dict of) tf.Tensor

Can be used to fetch arbitrary (structures of) Tensor values from the simulation (will be fetched directly from the TensorFlow session).

n_epochsint

Repeat data for n_epochs iterations.

truncationint

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.

shufflebool

If True, randomize the data into different minibatches each epoch.

profilebool

If True, collect TensorFlow profiling information while the simulation is running (this will slow down the simulation). Can also pass a string specifying a non-default filename for the saved profile data.

trainingbool

If True, run the network in training mode, otherwise run it in inference mode (this can affect things like the neuron model used).

callbackcallable

A function that will be called after each minibatch is evaluated. The function is passed two arguments; the first is a dictionary corresponding to outputs with the output values from each function, and the second is the value of extra_feeds.

combinecallable

The function that will be used to combine the outputs from each minibatch/truncation block. The values from each output function on each minibatch will be formed into a list and passed to combine in order to compute the final return values from this function. Note that if the output function returns multiple values, then combine will be applied separately to each of those outputs across the minibatches.

isolate_statebool

If True (default), isolate the simulation state for this run from the rest of the simulation (so the execution of this run is not affected by previous runs and will not affect future runs). If False, then this run begins from the terminal state of the last run, each minibatch will continue in sequence from the state of the previous, and future runs will resume from the terminal state of the last minibatch of this run.

Returns

output_valsdict 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(self, path, include_global=True, include_local=False)

Save network parameters to the given path.

Parameters

pathstr

Filepath of parameter output file

include_globalbool

If True (default True), save global/trainable network variables

include_localbool

If True (default False), save local (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)

Load network parameters from the given path.

Parameters

pathstr

Filepath of parameter input file

include_globalbool

If True (default True), load global (trainable) network variables

include_localbool

If True (default False), load local (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)

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(self, nengo_objs, as_dict=False)

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_dictbool

If True, return the values as a dictionary keyed by object label, instead of a list (the default). Note that in this case labels must be unique.

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(self, outputs=None, atol=1e-05, rtol=0.001)

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

outputstf.Tensor or list of tf.Tensor or list of Probe

Compute gradients wrt this output (if None, computes wrt each output probe)

atolfloat

Absolute error tolerance

rtolfloat

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)

Create a vector of times matching probed data.

Note that the range does not start at 0 as one might expect, but at the first timestep (i.e., dt).

Parameters

sample_everyfloat (Default: None)

The sampling period of the probe to create a range for. If None, a time value for every dt will be produced.

close(self)

Close the simulation, freeing resources.

Notes

The simulation cannot be restarted after it is closed. This is not a technical limitation, just a design decision made for all Nengo simulators.

property training_step

The number of training iterations that have been executed.

class nengo_dl.simulator.SimulationData(sim, minibatched)

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

simSimulator

The simulator from which data will be drawn

minibatchedbool

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)

Return the data associated with obj.

Parameters

objProbe or Ensemble or Connection

Object whose simulation data is being accessed

Returns

datandarray or BuiltEnsemble or BuiltConnection

Array containing probed data if obj is a Probe, otherwise the corresponding parameter object

get_params(self, *obj_attrs)

Returns the current parameter values for the given objects.

Parameters

obj_attrslist of (NengoObject, str)

The Nengo object and attribute of that object for which we want to know the parameter values (each object-attribute pair specified as a tuple argument to the function).

Returns

paramslist 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)

Inserts TensorFlow code into a Nengo model.

Parameters

tensor_funccallable

A function that maps node inputs to outputs

size_inint (Default: 0)

The number of elements in the input vector

size_outint (Default: None)

The number of elements in the output vector (if None, value will be inferred by calling tensor_func)

labelstr (Default: None)

A name for the node, used for debugging and visualization

property output

Ensure that nothing tries to evaluate the output attribute (indicating that something is trying to simulate this as a 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)

A utility function to construct TensorNodes that apply some function to their input (analogous to the tf.layers syntax).

Parameters

inputNengoObject

Object providing input to the layer

layer_funccallable 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_intuple of int

If not None, reshape the input to the given shape

synapsefloat or Synapse

Synapse to apply on connection from input to this layer

transformndarray

Transform matrix to apply on connection from input to this layer

return_connbool

If True, also return the connection linking this layer to input

layer_argsdict

These arguments will be passed to layer_func if it is callable, or Ensemble if layer_func is a NeuronType

Returns

nodeTensorNode 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

connConnection

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)

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

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

plannergraph planning algorithm

Pass one of the graph planners to change the default planner.

sortersignal sorting algorithm

Pass one of the sort algorithms to change the default sorter.

simplifications: list of graph simplification functions

Pass a list of graph simplification functions to change the default simplifications applied.

session_config: dict

Config options passed to tf.Session initialization (e.g., to change the GPU memory allocation method pass {"gpu_options.allow_growth": True}).

inference_onlybool

Set to True if the network will only be run in inference mode (i.e., no calls to Simulator.train). This may result in a small increase in the inference speed.

lif_smoothingfloat

If specified, use the smoothed SoftLIFRate neuron model, with the given smoothing parameter (sigma), to compute the gradient for LIF neurons (as opposed to using LIFRate).

dtypetf.DType

Set the floating point precision for simulation values.

keep_historybool

Adds a parameter to Nengo Probes that controls whether or not they will keep the history from all simulation timesteps or only the last simulation step. This can be further configured on a per-probe basis (e.g., net.config[my_probe].keep_history = False).

nengo_dl.config.get_setting(model, setting, default=None, obj=None)

Returns config settings (created by configure_settings).

Parameters

modelModel or Network

Built model or Network containing all the config settings.

settingstr

Name of the config option to return.

default

The default value to return if config option not set.

objNengoObject

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)

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

Parameters

sigmafloat

Amount of smoothing around the firing threshold. Larger values mean more smoothing.

tau_rcfloat

Membrane RC time constant, in seconds. Affects how quickly the membrane voltage decays to zero in the absence of input (larger = slower decay).

tau_reffloat

Absolute refractory period, in seconds. This is how long the membrane voltage is held at zero after a spike.

amplitudefloat

Scaling factor on the neuron output. Corresponds to the relative amplitude of the output spikes of the neuron.

Notes

Adapted from https://github.com/nengo/nengo-extras/blob/master/nengo_extras/neurons.py

References

R31ac3a189156-1

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

rates(self, x, gain, bias)

Estimates steady-state firing rate given gain and bias.

step_math(self, dt, J, output)

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)

Normal distribution where any values more than some distance from the mean are resampled.

Parameters

meanfloat

Mean of the normal distribution

stddevfloat

Standard deviation of the normal distribution

limitfloat

Resample any values more than this distance from the mean. If None, then limit will be set to 2 standard deviations.

sample(self, n, d=None, rng=None)

Samples the distribution.

Parameters

nint

Number samples to take.

dint or None

The number of dimensions to return. If this is an int, the return value will be of shape (n, d). If None, the return value will be of shape (n,).

rngRandomState

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')

Variance scaling distribution for weight initialization (analogous to TensorFlow init_ops.VarianceScaling).

Parameters

scalefloat

Overall scale on values

mode“fan_in” or “fan_out” or “fan_avg”

Whether to scale based on input or output dimensionality, or average of the two

distribution: “uniform” or “normal”

Whether to use a uniform or normal distribution for weights

sample(self, n, d=None, rng=None)

Samples the distribution.

Parameters

nint

Number samples to take.

dint or None

The number of dimensions to return. If this is an int, the return value will be of shape (n, d). If None, the return value will be of shape (n,).

rngRandomState

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')

Weight initialization method from [1] (also known as Xavier initialization).

Parameters

scalefloat

Scale on weight distribution. For rectified linear units this should be sqrt(2), otherwise usually 1.

distribution: “uniform” or “normal”

Whether to use a uniform or normal distribution for weights

References

1

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

class nengo_dl.dists.He(scale=1, distribution='normal')

Weight initialization method from [1].

Parameters

scalefloat

Scale on weight distribution. For rectified linear units this should be sqrt(2), otherwise usually 1.

distribution: “uniform” or “normal”

Whether to use a uniform or normal distribution for weights

References

1

Kaiming He, Xiangyu Zhang, Shaoqing Ren, and Jian Sun. (2015): Delving deep into rectifiers: Surpassing 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)

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

outputstf.Tensor

Output values from a Probe in a network.

targetstf.Tensor

Target values for a Probe in a network.

Returns

msetf.Tensor

Tensor representing the mean squared error.

class nengo_dl.objectives.Regularize(order=2, axis=None, weight=None)

An objective function to apply regularization penalties.

Parameters

orderint or str

Order of the regularization norm (e.g. 1 for L1 norm, 2 for L2 norm). See https://www.tensorflow.org/api_docs/python/tf/norm for a full description of the possible values for this parameter.

axisint or None

The axis of the probed signal along which to compute norm. If None (the default), the signal is flattened and the norm is computed across the resulting vector. Note that these are only the axes with respect to the output on a single timestep (i.e. batch/time dimensions are not included).

weightfloat

Scaling weight to apply to regularization penalty.

Notes

The mean will be computed across all the non-axis dimensions after computing the norm (including batch/time) in order to compute the overall objective value.

Developers

These objects are only relevant to people interested in modifying the implementation of NengoDL (e.g., adding a new neuron type).

Builder

The builder manages the mapping between (groups of) Nengo operators and the builder objects that know how to translate those operators into a TensorFlow graph.

class nengo_dl.builder.Builder(plan, graph, signals, config)

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

Parameters

planlist of tuple of Operator

The groups of operators that will be built

graphtf.Graph

The simulation build graph

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

configBuildConfig

Configuration parameters for the build process

pre_build(self, progress=None)

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

Parameters

progressutils.ProgressBar

Progress bar for ops in plan

build(self, progress=None)

Build the computations implementing a single simulator timestep.

Parameters

progressutils.ProgressBar

Progress bar for ops in plan

Returns

side_effectslist of 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)

Calls post build functions for all ops in plan.

Parameters

sesstf.Session

The initialized simulation session

rngRandomState

Seeded random number generator

progressutils.ProgressBar

Progress bar for ops in plan

name_scope(self, ops)

Returns a new TensorFlow name scope for the given ops.

classmethod register(nengo_op)

A decorator for adding a class to the build function registry.

Parameters

nengo_opOperator

The operator associated with the build function being decorated.

class nengo_dl.builder.BuildConfig

Stores configuration parameters that may be relevant to parts of the build process.

Parameters

inference_onlybool

If True the network should be constructed in “inference only” mode (not including any support for training operations).

lif_smoothingfloat

Smoothing parameter for LIF gradient approximation.

cpu_onlybool

True if TensorFlow is only running on the CPU (because that was specified by the user or because tensorflow-gpu is not installed).

Create new instance of BuildConfig(inference_only, lif_smoothing, cpu_only)

class nengo_dl.builder.OpBuilder(ops, signals, config)

The constructor should set up any computations that are fixed for this op (i.e., things that do not need to be recomputed each timestep).

Parameters

opslist of Operator

The operator group to build into the model

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

configBuildConfig

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)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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(self, ops, signals, sess, rng)

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

opslist of Operator

The operator group to build into the model

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

sesstf.Session

The initialized simulation session

rngRandomState

Seeded random number generator

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

class nengo_dl.builder.NengoBuilder

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)

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

modelModel

The Model instance in which to store build artifacts.

objobject

The object to build into the model.

class nengo_dl.builder.NengoModel(*args, fail_fast=True, **kwargs)

Copy of the default Nengo model.

This allows us to override certain model behaviours.

Parameters

fail_fastbool

If True, try to call op.make_step when ops are added to the model. Note that NengoDL doesn’t actually 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)

Add an operator to the model.

Parameters

opOperator

Operator being added to the model.

Notes

This is a copy of the parent nengo.builder.Model.add_op, with the addition of the if self.fail_fast condition.

Operator builders

These objects are used to convert Nengo operators into TensorFlow graph elements.

Basic operators

Build classes for basic Nengo operators.

class nengo_dl.op_builders.ResetInc(dst, value=0, tag=None)

A version of Reset that increments the target value rather than setting it.

property dst

Overridden to return from incs rather than sets.

class nengo_dl.op_builders.ResetBuilder(ops, signals, config)

Build a group of Reset operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

class nengo_dl.op_builders.CopyBuilder(ops, signals, config)

Build a group of Copy operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

class nengo_dl.op_builders.ElementwiseIncBuilder(ops, signals, config)

Build a group of ElementwiseInc operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

nengo_dl.op_builders.sparse_matmul(A_indices, A_data, A_shape, X)

Matrix multiplication between sparse matrix A and dense matrix X

Parameters

A_indicestf.Tensor

N, 2) rray of [row,col] non-zero entries

A_datatf.Tensor

(N,) array of data in the nonzero entries specified in A_indices

A_shapetuple of int

Shape of full A matrix

Xtf.Tensor

Dense matrix being multiplied by A

Returns

dottf.Tensor

Result of matrix multiplication between A and X

class nengo_dl.op_builders.DotIncBuilder(ops, signals, config)

Build a group of DotInc operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

class nengo_dl.op_builders.SimPyFuncBuilder(ops, signals, config)

Build a group of SimPyFunc operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

class nengo_dl.op_builders.SparseDotIncBuilder(ops, signals, config)

Build a group of SparseDotInc operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

Neuron types

Build classes for Nengo neuron operators.

class nengo_dl.neuron_builders.GenericNeuronBuilder(ops, signals, config)

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)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

class nengo_dl.neuron_builders.RectifiedLinearBuilder(ops, signals, config)

Build a group of RectifiedLinear neuron operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

class nengo_dl.neuron_builders.SpikingRectifiedLinearBuilder(ops, signals, config)

Build a group of SpikingRectifiedLinear neuron operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

class nengo_dl.neuron_builders.SigmoidBuilder(ops, signals, config)

Build a group of Sigmoid neuron operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

class nengo_dl.neuron_builders.LIFRateBuilder(ops, signals, config)

Build a group of LIFRate neuron operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

class nengo_dl.neuron_builders.SoftLIFRateBuilder(ops, signals, config)

Build a group of SoftLIFRate neuron operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

class nengo_dl.neuron_builders.LIFBuilder(ops, signals, config)

Build a group of LIF neuron operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

class nengo_dl.neuron_builders.SimNeuronsBuilder(ops, signals, config)

Builds a group of SimNeurons operators.

Calls the appropriate sub-build class for the different neuron types.

Attributes

TF_NEURON_IMPLdict of {NeuronType, builder.OpBuilder}

Mapping from neuron types to custom build classes (neurons without a custom builder will use the generic builder).

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

Learning rules

Build classes for Nengo learning rule operators.

class nengo_dl.learning_rule_builders.SimBCMBuilder(ops, signals, config)

Build a group of SimBCM operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

class nengo_dl.learning_rule_builders.SimOjaBuilder(ops, signals, config)

Build a group of SimOja operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

class nengo_dl.learning_rule_builders.SimVojaBuilder(ops, signals, config)

Build a group of SimVoja operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

nengo_dl.learning_rule_builders.build_pes(model, pes, rule)

Builds a nengo.PES object into a model.

Parameters

modelModel

The model to build into.

pesPES

Learning rule type to build.

ruleLearningRule

The learning rule object corresponding to the neuron type.

Notes

Does not modify model.params[] and can therefore be called more than once with the same nengo.PES instance.

class nengo_dl.learning_rule_builders.SimPESBuilder(ops, signals, config)

Build a group of SimPES operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

Processes

Build classes for Nengo process operators.

class nengo_dl.process_builders.GenericProcessBuilder(ops, signals, config)

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)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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(self, ops, signals, sess, rng)

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

opslist of Operator

The operator group to build into the model

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

sesstf.Session

The initialized simulation session

rngRandomState

Seeded random number generator

class nengo_dl.process_builders.LowpassBuilder(ops, signals, config)

Build a group of Lowpass synapse operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

class nengo_dl.process_builders.LinearFilterBuilder(ops, signals, config)

Build a group of LinearFilter synapse operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

class nengo_dl.process_builders.SimProcessBuilder(ops, signals, config)

Builds a group of SimProcess operators.

Calls the appropriate sub-build class for the different process types.

Attributes

TF_PROCESS_IMPLdict of {Process: builder.OpBuilder}

Mapping from process types to custom build classes (processes without a custom builder will use the generic builder).

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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(self, ops, signals, sess, rng)

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

opslist of Operator

The operator group to build into the model

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

sesstf.Session

The initialized simulation session

rngRandomState

Seeded random number generator

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

Transforms

Build classes for Nengo transform operators.

class nengo_dl.transform_builders.ConvIncBuilder(ops, signals, config)

Build a group of ConvInc operators.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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

static mergeable(x, y)

Compute the mergeability of two operators of this builder’s type.

Parameters

xOperator

The operator being tested

yOperator

The operator being merged into (this is representative of a group of operators that have already been merged)

Returns

mergeablebool

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

TensorNodes

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

class nengo_dl.tensor_node.SimTensorNode(func, time, input, output, tag=None)

Operator for TensorNodes (constructed by build_tensor_node).

Parameters

funccallable

The TensorNode function (tensor_func)

timeSignal

Signal representing the current simulation time

inputSignal or None

Input Signal for the TensorNode (or None if size_in==0)

outputSignal

Output Signal for the TensorNode

tagstr

A label associated with the operator, for debugging

Notes

1. sets [output]

2. incs []

3. reads [time] if input is None else [time, input]

4. updates []

nengo_dl.tensor_node.build_tensor_node(model, node)

This is the Nengo build function, so that Nengo knows what to do with TensorNodes.

class nengo_dl.tensor_node.SimTensorNodeBuilder(ops, signals, config)

Builds a SimTensorNode operator into a NengoDL model.

build_step(self, signals)

This function builds whatever computations need to be executed in each simulation timestep.

Parameters

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

Returns

side_effectslist 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(self, ops, signals, sess, rng)

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

opslist of Operator

The operator group to build into the model

signalssignals.SignalDict

Mapping from Signal to tf.Tensor (updated by operations)

sesstf.Session

The initialized simulation session

rngRandomState

Seeded random number generator

Graph construction

Manages all the data and build processes associated with the TensorFlow graph.

The TensorFlow graph is the symbolic description of the computations in the network, which will be executed by the simulator.

nengo_dl.tensor_graph.with_self(wrapped, instance, args, kwargs)

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)

Manages the construction of the TensorFlow symbolic computation graph.

Parameters

modelModel

Pre-built Nengo model describing the network to be simulated

dtfloat

Length of a simulator timestep, in seconds

unroll_simulationint

Unroll simulation loop by explicitly building unroll_simulation iterations into the computation graph

dtypetf.DType

Floating point precision to use for simulation

minibatch_sizeint

The number of simultaneous inputs that will be passed through the network

deviceNone or "/cpu:0" or "/gpu:[0-n]"

Device on which to execute computations (if None then uses the default device as determined by TensorFlow)

progressutils.ProgressBar

Progress bar for optimization stage

build(self, progress)

Constructs a new graph to simulate the model.

progressutils.ProgressBar

Progress bar for construction stage

build_step(self, progress)

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

Parameters

progressutils.ProgressBar

Progress bar for loop construction

Returns

probe_tensorslist of tf.Tensor

The Tensor objects representing the data required for each model Probe

side_effectslist of tf.Tensor

The output Tensors of computations that may have 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)

Build simulation loop.

Parameters

progressutils.ProgressBar

Progress bar for loop construction

build_inputs(self, progress)

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

Parameters

progressutils.ProgressBar

Progress bar for input construction

build_optimizer_func(self, optimizer, objective)

Adds elements into the graph to execute the given optimizer.

Parameters

optimizertf.train.Optimizer

Instance of a TensorFlow optimizer class

objectivedict 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_optimizercallable

A function that builds the operators required to implement the given optimizer update. Generally this function will then be passed to build_outputs.

Notes

This function caches its outputs, so if it is called again with the same arguments then it will return the previous function. This avoids building duplicates of the same operations over and over. This can also be important functionally, e.g. if the optimizer has internal state like momentum. By caching the output we ensure that subsequent calls share the same internal state.

build_outputs(self, outputs)

Adds elements into the graph to compute the given outputs.

Parameters

outputsdict of {(tuple of) Probe: callable or None}

The output function to be applied to each probe or group of probes. The function can accept one argument (the output of that probe) or two (output and target values for that probe). If a tuple of Probes are given as the key, then those output/target parameters will be the corresponding tuple of probe/target values. The function should return a tf.Tensor or tuple of Tensors representing the output we want from those probes. If None is given instead of a function then the output will simply be the output value from the corresponding probes.

Returns

output_valsdict of {(tuple of) Probe: (tuple of) tf.Tensor}

Tensors representing the result of applying the output functions to the probes.

new_vars_inittf.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(self, sess, rng)

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

sesstf.Session

The TensorFlow session for the simulator

rngRandomState

Seeded random number generator

build_summaries(self, summaries)

Adds ops to collect summary data for the given objects.

Parameters

summarieslist 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

optf.Tensor

Merged summary op for the given summaries

get_tensor(self, sig)

Returns a Tensor corresponding to the given Signal.

Parameters

sigSignal

A signal in the model

Returns

tensortf.Tensor

Tensor containing the value of the given Signal

mark_signals(self)

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)

Groups signal data together into larger arrays, and represent each individual signal as a slice into that array.

Parameters

sigslist of Signal

Base signals arranged into the order in which they should reside in memory (e.g., output from graph_optimizer.order_signals)

Signals

Represents and manages the internal simulation signals.

class nengo_dl.signals.TensorSignal(indices, key, dtype, shape, minibatch_size, constant, label='TensorSignal')

Represents a tensor as an indexed view into a base array.

Parameters

indicestuple or list or ndarray of int

Indices along the first axis of the base array corresponding to the data for this signal

keyobject

Key mapping to the base array that contains the data for this signal

dtypedtype

dtype of the values represented by this signal

shapetuple of int

View shape of this signal (may differ from shape of base array)

minibatch_sizeint

If not None then this signal contains a minibatch dimension with the given size

constantcallable

A function that returns a TensorFlow constant (will be provided by signals.SignalDict.get_tensor_signal)

labelstr

Name for this signal, used to make debugging easier

property indices

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

property ndim

The rank of this signal.

__getitem__(self, indices)

Create a new TensorSignal representing a subset (slice or advanced indexing) of the indices of this TensorSignal.

Parameters

indicesslice or list of int

The desired subset of the indices in this TensorSignal

Returns

sigsignals.TensorSignal

A new TensorSignal representing the subset of this TensorSignal

reshape(self, shape)

Create a new TensorSignal representing a reshaped view of the same data in this TensorSignal (size of data must remain unchanged).

Parameters

shapetuple of int

New shape for the signal (one dimension can be -1 to indicate an inferred dimension size, as in numpy)

Returns

sigsignals.TensorSignal

New TensorSignal representing the same data as this signal but with the given shape

broadcast(self, axis, length)

Add a new dimension by broadcasting this signal along axis for the given length.

Parameters

axis0 or -1

Where to insert the new dimension (currently only supports either the beginning or end of the array)

lengthint

The number of times to duplicate signal along the broadcast dimension

Returns

sigsignals.TensorSignal

TensorSignal with new broadcasted shape

property tf_shape

A tf.Tensor representing the shape of this signal.

property tf_indices

A tf.Tensor representing the indices of this signal.

property tf_slice

A tuple of tf.Tensors representing the (start, stop, stride) slice within the base array containing the data for this signal.

This can be used as a more efficient representation of TensorSignal.tf_indices.

property full_shape

Shape of the signal including the minibatch dimension.

property minibatched

Whether or not this TensorSignal contains a minibatch dimension.

class nengo_dl.signals.SignalDict(dtype, minibatch_size)

Handles the mapping from Signal to tf.Tensor.

Takes care of gather/scatter logic to read/write signals within the base arrays.

Parameters

dtypetf.DType

Floating point precision used in signals

minibatch_sizeint

Number of items in each minibatch

scatter(self, dst, val, mode='update')

Updates the base data corresponding to dst.

Parameters

dstTensorSignal

Signal indicating the data to be modified in base array

valtf.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(self, src, force_copy=False)

Fetches the data corresponding to src from the base array.

Parameters

srcTensorSignal

Signal indicating the data to be read from base array

force_copybool

If True, always perform a gather, not a slice (this forces a copy). Note that setting force_copy=False does not guarantee that a copy won’t be performed.

Returns

gatheredtf.Tensor

Tensor object corresponding to a dense subset of data from the base array

mark_gather(self, src)

Marks src as being gathered, but doesn’t actually perform a gather. Used to indicate that some computation relies on src.

Parameters

srcTensorSignal

Signal indicating the data being read

combine(self, sigs, label='Combine')

Combines several TensorSignals into one by concatenating along the first axis.

Parameters

sigslist of TensorSignal or Signal

Signals to be combined

labelstr

Name for combined signal (to help with debugging)

Returns

sigTensorSignal

New TensorSignal representing the concatenation of the data in sigs

make_internal(self, name, shape, minibatched=True)

Creates a variable to represent an internal simulation signal.

This is to handle the case where we want to add a signal that is not represented as a nengo.builder.Signal in the Nengo op graph.

Parameters

namestr

Name for the signal/variable.

shapetuple of int

Shape of the signal/variable.

minibatchedbool

Whether or not this signal contains a minibatch dimension.

Returns

sigTensorSignal

A TensorSignal representing the newly created variable.

get_tensor_signal(self, indices, key, dtype, shape, minibatched, signal=None, label='TensorSignal')

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

indicestuple or list or ndarray of int

Indices along the first axis of the base array corresponding to the data for this signal

keyobject

Key mapping to the base array that contains the data for this signal

dtypedtype

dtype of the values represented by this signal

shapetuple of int

View shape of this signal (may differ from shape of base array)

minibatchedbool

Whether or not this signal contains a minibatch dimension

signalSignal

If not None, associate the new TensorSignal with the given Signal in the sig_map

labelstr

Name for this signal, used to make debugging easier

Returns

sigTensorSignal

A new TensorSignal with the given properties

constant(self, value, dtype=None, cutoff=33554432)

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

valuendarray

Array containing the value of the constant

dtypedtype

The type for the constant (if None, the dtype of value will be used)

cutoffint

The size of constant (in bytes) for which we will switch from tf.constant to tf.Variable

Returns

constanttf.Tensor

A tensor representing the given value

op_constant(self, ops, op_sizes, attr, dtype, ndims=2)

Creates a tensor representing the constant parameters of an op group.

Parameters

opslist of object

The operators for some merged group of ops

op_sizeslist of int

The number of constant elements in each op

attrstr

The attribute of the op that describes the constant parameter

dtypedtype

Numeric type of the parameter

ndimsint

Empty dimensions will be added to the end of the returned tensor for all ndims > 1 (in the case that it is not a scalar).

Returns

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

Check if the given op can be merged with the candidate group

Parameters

opOperator

The operator to be merged

chosen_opslist of Operator

The operator group to be merged in to

Returns

mergeablebool

True if op can be merged into chosen_ops, else False

nengo_dl.graph_optimizer.greedy_planner(operators)

Combine mergeable operators into groups that will be executed as a single computation.

Parameters

operatorslist of Operator

All the nengo operators in a model (unordered)

Returns

planlist 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)

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_listlist of Operator

All the nengo operators in a model (unordered)

max_depthint

The planner will search this many steps ahead before selecting which group to schedule next

Returns

planlist of tuple of Operator

Operators combined into mergeable groups and in execution order

nengo_dl.graph_optimizer.transitive_planner(op_list)

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_listlist of Operator

All the nengo operators in a model (unordered)

Returns

planlist 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)

Computes the transitive closure for the given graph, restricted to the operators with the given builder type.

Parameters

dgdict of {int: set of int}

Dependency graph where dg[a] = {b, c} indicates that operators b and c are dependent on a

opslist of int

The operators for which we want to compute the transitive closure

transdict of {int: set of int}

The transitive closure for the graph (will be filled in-place)

builder_typetype

One of the nengo_dl build classes (e.g., CopyBuilder), specifying the type of operators to include in the transitive closure

builder_typeslist of type

The build class for each operator

cachedict of {frozenset of int: set of int}

Stores base sets which trans will reference (to reduce memory usage, since many elements 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)

Orders operators into a valid execution order, but does not perform any merging.

Parameters

operatorslist of Operator

All the nengo operators in a model (unordered)

Returns

planlist of tuple of Operator

Operators in execution order

nengo_dl.graph_optimizer.order_signals(plan, n_passes=10)

Orders signals and operators to try to structure reads/writes in contiguous blocks.

Parameters

planlist of tuple of Operator

Operator execution plan (e.g., output from greedy_planner)

n_passesint

Number of repeated passes through the operator reordering stage

Returns

signalslist of Signal

Signals organized into the order in which we want them arranged in memory

planlist of tuple of Operator

Input plan with operators reordered within groups to align with order of signals

nengo_dl.graph_optimizer.hamming_sort(blocks)

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

blocksdict of {Signal: frozenset of int}

Dictionary indicating which io blocks each signal is a part of

Returns

sort_idxsdict 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)

Rearrange operators to match the order of signals.

Note: the same operators can be associated with multiple read blocks if they have multiple inputs, so rearranging the operators according to one of those blocks could mess up the order with respect to the other read block. We iterate through the read blocks in increasing size so that the largest blocks win out.

Parameters

sorted_iolist of tuple of (Operator, int)

The operators that form each io block, sorted by increasing size of the block. In the case that a group of operators participate in multiple io blocks, the integer distinguishes which one of those blocks this block is associated with.

sigslist of Signal

Signals that have been arranged into a given order by other parts of the algorithm

sig_idxsdict of {Signal: int}

Sorted indices of signals

new_plandict of {tuple of Operator: tuple of Operator}

Mapping from original operator group to the sorted operators

blocksdict of {Signal: frozenset of int}

Indicates which io blocks each signal participates in

op_sigsdict of {Operator: list of Signal}

The signals accessed by each operator

Returns

new_plandict of {tuple of Operator: tuple of Operator}

Mapping from original operator group to the sorted operators

sig_idxsdict 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)

Attempts to rearrange sigs so that it is in the same order as operator signals, without changing the overall block order.

Parameters

sorted_iolist of tuple of (Operator, int)

The operators that form each io block, sorted by increasing size of the io block. In the case that a group of operators participate in multiple io blocks, the integer distinguishes which one of those blocks this block is associated with.

sigslist of Signal

Signals to be sorted

sig_idxsdict of {Signal: int}

Sorted indices of signals

new_plandict of {tuple of Operator: tuple of Operator}

Mapping from original operator group to the sorted operators

blocksdict of {Signal: frozenset of int}

Indicates which io blocks each signal participates in

op_sigsdict of {Operator: list of Signal}

The signals accessed by each operator

Returns

sig_idxsdict of {Signal: int}

Sorted indices of signals

nengo_dl.graph_optimizer.noop_order_signals(plan, **_)

A version of graph_optimizer.order_signals that doesn’t do any reordering, for debugging.

nengo_dl.graph_optimizer.remove_unmodified_resets(operators)

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

operatorslist of Operator

Operators in the model

Returns

new_operatorslist of Operator

Modified list of operators

nengo_dl.graph_optimizer.remove_zero_incs(operators)

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

operatorslist of Operator

Operators in the model

Returns

new_operatorslist of Operator

Modified list of operators

nengo_dl.graph_optimizer.remove_constant_copies(operators)

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

operatorslist of Operator

Operators in the model

Returns

new_operatorslist of Operator

Modified list of operators

nengo_dl.graph_optimizer.remove_identity_muls(operators)

Change y=x*1 ops to y=x Copy ops.

If one of the inputs to a DotInc/ElementwiseInc is 1 then we can skip the multiplication and change it to a Copy op.

Parameters

operatorslist of Operator

Operators in the model

Returns

new_operatorslist of Operator

Modified list of operators

nengo_dl.graph_optimizer.signal_io_dicts(operators)

Organizes operators into dictionaries according to the signals they set/inc/read/update.

Parameters

operatorslist of Operator

Operators in the model

Returns

setsdict of {Signal: list of Operator}

A dictionary indicating all the Operators that set each signal.

incsdict of {Signal: list of Operator}

A dictionary indicating all the Operators that inc each signal.

readsdict of {Signal: list of Operator}

A dictionary indicating all the Operators that read each signal.

updatesdict of {Signal: list of Operator}

A dictionary indicating all the Operators that update each signal.

nengo_dl.graph_optimizer.display_signal_blocks(operators, all_signals)

Creates a visual depiction of the signals blocks read by each operator group.

Parameters

operatorslist of tuple of Operator

Operator execution plan

all_signalslist of Signal

Base signals arranged into some order

Returns

signal_blocksstr

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

Utilities

Utility objects used throughout the code base.

nengo_dl.utils.sanitize_name(name)

Remove illegal TensorFlow name characters from string.

Valid TensorFlow name characters are [A-Za-z0-9_.\-/]

Parameters

namestr

Name to be sanitized

Returns

sanitizedstr

Sanitized name

nengo_dl.utils.function_name(func, sanitize=True)

Get the name of the callable object func.

Parameters

funccallable

Callable object (e.g., function, callable class)

sanitizebool

If True, remove any illegal TensorFlow name characters from name

Returns

namestr

Name of func (optionally sanitized)

nengo_dl.utils.align_func(output_shape, output_dtype)

Decorator that ensures the output of func is an ndarray with the given shape and dtype.

Parameters

output_shape(list of) tuple of int

Desired shape for function output(s) (must have the same size as actual function output)

output_dtype(list of) tf.DType or dtype

Desired dtype of function output(s)

Raises

nengo.exceptions.SimulationError

If the function returns None or a non-finite value.

nengo_dl.utils.print_op(input, message)

Inserts a print statement into the TensorFlow graph.

Parameters

inputtf.Tensor

The value of this tensor will be printed whenever it is computed in the graph

messagestr

String prepended to the value of input, to help with logging

Returns

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

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.

Parameters

inputslist of tf.Tensor

Input tensors

outputslist of tf.Tensor

Output tensors

class nengo_dl.utils.ProgressBar(present='', past=None, max_value=1, vars=None, **kwargs)

Handles progress bar display for some tracked process.

Parameters

presentstr

Description of process in present (e.g., “Simulating”)

paststr

Description of process in past (e.g., “Simulation”)

max_valueint or None

The maximum number of steps in the tracked process (or None if the maximum number of steps is unknown)

varslist of str

Extra variables that will be displayed at the end of the progress bar

Notes

Launches a separate thread to handle the progress bar display updates.

Initializes a progress bar with sane defaults

start(self, **kwargs)

Start tracking process, initialize display.

finish(self, **kwargs)

Stop tracking process, finish display.

step(self, **vars)

Advance the progress bar one step.

Parameters

varsdict of {str: str}

Values for the extra variables displayed at the end of the progress bar (defined in __init__)

sub(self, msg=None, **kwargs)

Creates a new progress bar for tracking a sub-process.

Parameters

msgstr

Description of sub-process

property max_steps

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

class nengo_dl.utils.SubProgressBar(present='', past=None, max_value=1, vars=None, **kwargs)

A progress bar representing a sub-task within an overall progress bar.

Initializes a progress bar with sane defaults

finish(self)

Finishing a sub-progress bar doesn’t start a new line.

class nengo_dl.utils.NullProgressBar(present='', past=None, max_value=1, vars=None, **kwargs)

A progress bar that does nothing.

Used to replace ProgressBar when we want to disable output.

Initializes a progress bar with sane defaults

sub(self, *args, **kwargs)

Noop for creating a sub-progress bar.

step(self, **kwargs)

Noop for incrementing the progress bar.

nengo_dl.utils.minibatch_generator(data, minibatch_size, shuffle=True, truncation=None, rng=None)

Generator to yield minibatch_sized subsets from inputs and targets.

Parameters

datadict of {NengoObject: ndarray}

Data arrays to be divided into minibatches.

minibatch_sizeint

The number of items in each minibatch

shufflebool

If True, the division of items into minibatches will be randomized each time the generator is created

truncationint

If not None, divide the data up into sequences of truncation timesteps.

rngRandomState

Seeded random number generator

Yields

offsetint

The simulation step at which the returned data begins (will only be nonzero if truncation is not None).

inputsdict of {Node: ndarray}

The same structure as inputs, but with each array reduced to minibatch_size elements along the first dimension

targetsdict of {Probe: ndarray}

The same structure as targets, but with each array reduced to minibatch_size elements along the first dimension

Benchmarks

Benchmark networks and utilities for evaluating NengoDL’s performance.

nengo_dl.benchmarks.cconv(dimensions, neurons_per_d, neuron_type)

Circular convolution (EnsembleArray) benchmark.

Parameters

dimensionsint

Number of dimensions for vector values

neurons_per_dint

Number of neurons to use per vector dimension

neuron_typeNeuronType

Simulation neuron type

Returns

netnengo.Network

benchmark network

nengo_dl.benchmarks.integrator(dimensions, neurons_per_d, neuron_type)

Single integrator ensemble benchmark.

Parameters

dimensionsint

Number of dimensions for vector values

neurons_per_dint

Number of neurons to use per vector dimension

neuron_typeNeuronType

Simulation neuron type

Returns

netnengo.Network

benchmark network

nengo_dl.benchmarks.pes(dimensions, neurons_per_d, neuron_type)

PES learning rule benchmark.

Parameters

dimensionsint

Number of dimensions for vector values

neurons_per_dint

Number of neurons to use per vector dimension

neuron_typeNeuronType

Simulation neuron type

Returns

netnengo.Network

benchmark network

nengo_dl.benchmarks.basal_ganglia(dimensions, neurons_per_d, neuron_type)

Basal ganglia network benchmark.

Parameters

dimensionsint

Number of dimensions for vector values

neurons_per_dint

Number of neurons to use per vector dimension

neuron_typeNeuronType

Simulation neuron type

Returns

netnengo.Network

benchmark network

nengo_dl.benchmarks.mnist(use_tensor_layer=True)

A network designed to stress-test tensor layers (based on mnist net).

Parameters

use_tensor_layerbool

If True, use individual tensor_layers to build the network, as opposed to a single TensorNode containing all layers.

Returns

netnengo.Network

benchmark network

nengo_dl.benchmarks.spaun(dimensions)

Builds the Spaun network from [1]

Parameters

dimensionsint

Number of dimensions for vector values

Returns

netnengo.Network

benchmark network

Notes

This network needs to be installed via

pip install git+https://github.com/drasmuss/spaun2.0.git

References

1

Chris Eliasmith, Terrence C. Stewart, Xuan Choo, Trevor Bekolay, Travis DeWolf, Yichuan Tang, and Daniel Rasmussen (2012). A 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)

Basal ganglia network benchmark.

Parameters

dimensionsint

Number of dimensions for vector values

neurons_per_dint

Number of neurons to use per vector dimension

neuron_typeNeuronType

Simulation neuron type

n_ensemblesint

Number of ensembles in the network

connections_per_ensembleint

Outgoing connections from each ensemble

Returns

netnengo.Network

benchmark network

nengo_dl.benchmarks.run_profile(net, train=False, n_steps=150, do_profile=True, reps=1, **kwargs)

Run profiler on a benchmark network.

Parameters

netNetwork

The nengo Network to be profiled.

trainbool

If True, profile the sim.train function. Otherwise, profile the sim.run function.

n_stepsint

The number of timesteps to run the simulation.

do_profilebool

Whether or not to run profiling

repsint

Repeat the run this many times (only profile data from the last run will be kept).

Returns

exec_timefloat

Time (in seconds) taken to run the benchmark, taking the minimum over reps.

Notes

kwargs will be passed on to Simulator

Interface

The benchmark module also includes a command-line interface for building and running the benchmarks:

benchmarks

Command-line interface for benchmarks.

benchmarks [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

build

Builds one of the benchmark networks

benchmarks build [OPTIONS]

Options

--benchmark <benchmark>

Name of benchmark network

--dimensions <dimensions>

Number of dimensions

--neurons_per_d <neurons_per_d>

Neurons per dimension

--neuron_type <neuron_type>

Nengo neuron model

--kwarg <kwarg>

Arbitrary kwarg to pass to benchmark network (key=value)

matmul-vs-reduce

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]

profile

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