Utilities

Nengo provides various utility functions in the nengo.utils module. In general, anything in this module should not be considered part of the core API. This functionality may move or change with less notice than we provide for the core API, and it is not as thoroughly tested.

These utilities are mainly designed for internal use within Nengo, but we expose them as they may be useful to some users.

Builder

Helper functions for backends generating their own Builder system.

nengo.utils.builder.full_transform

Compute the full transform matrix for a Dense connection transform.

nengo.utils.builder.default_n_eval_points

A heuristic to determine an appropriate number of evaluation points.

nengo.utils.builder.objs_and_connections

Given a Network, returns all (ensembles + nodes, connections).

nengo.utils.builder.generate_graphviz

Moved to nengo_extras.graphviz.

nengo.utils.builder.remove_passthrough_nodes

Returns a version of the model without passthrough Nodes.

nengo.utils.builder.find_all_io

Build up a list of all inputs and outputs for each object.

nengo.utils.builder.full_transform(conn, slice_pre=True, slice_post=True, allow_scalars=True)[source]

Compute the full transform matrix for a Dense connection transform.

Parameters
connConnection

The connection for which to compute the full transform.

slice_preboolean, optional (True)

Whether to compute the pre slice as part of the transform.

slice_postboolean, optional (True)

Whether to compute the post slice as part of the transform.

allow_scalarsboolean, optional (True)

If true (default), will not make scalars into full transforms when not using slicing, since these work fine in the reference builder. If false, these scalars will be turned into scaled identity matrices.

nengo.utils.builder.default_n_eval_points(n_neurons, dimensions)[source]

A heuristic to determine an appropriate number of evaluation points.

This is used by builders to generate a sufficiently large sample from a vector space in order to solve for accurate decoders.

Parameters
n_neuronsint

The number of neurons in the ensemble that will be sampled. For a connection, this would be the number of neurons in the pre ensemble.

dimensionsint

The number of dimensions in the ensemble that will be sampled. For a connection, this would be the number of dimensions in the pre ensemble.

nengo.utils.builder.objs_and_connections(network)[source]

Given a Network, returns all (ensembles + nodes, connections).

nengo.utils.builder.generate_graphviz(*args, **kwargs)[source]

Moved to nengo_extras.graphviz.

nengo.utils.builder.remove_passthrough_nodes(objs, connections, create_connection_fn=None)[source]

Returns a version of the model without passthrough Nodes.

For some backends (such as SpiNNaker), it is useful to remove Nodes that have ‘None’ as their output. These nodes simply sum their inputs and use that as their output. These nodes are defined purely for organizational purposes and should not affect the behaviour of the model. For example, the ‘input’ and ‘output’ Nodes in an EnsembleArray, which are just meant to aggregate data.

Note that removing passthrough nodes can simplify a model and may be useful for other backends as well. For example, an EnsembleArray connected to another EnsembleArray with an identity matrix as the transform should collapse down to D Connections between the corresponding Ensembles inside the EnsembleArrays.

Parameters
objslist of Nodes and Ensembles

All the objects in the model

connectionslist of Connections

All the Connections in the model

Returns the objs and connections of the resulting model. The passthrough
Nodes will be removed, and the Connections that interact with those Nodes
will be replaced with equivalent Connections that don’t interact with those
Nodes.
nengo.utils.builder.find_all_io(connections)[source]

Build up a list of all inputs and outputs for each object.

Cache

Utilities to convert to and from bytes.

Used by nengo.rc in order to present file sizes to users in human-readable formats.

This code adapted from https://web.archive.org/web/20200817051754/http://code.activestate.com/recipes/578019-bytes-to-human-human-to-bytes-converter/?in=user-4178764 under the MIT License.

nengo.utils.cache.bytes2human

Convert from a size in bytes to a human readable string.

nengo.utils.cache.human2bytes

Convert from a human readable string to a size in bytes.

nengo.utils.cache.byte_align

Returns the int larger than size aligned to alignment bytes.

nengo.utils.cache.bytes2human(n, fmt='%(value).1f %(symbol)s')[source]

Convert from a size in bytes to a human readable string.

Examples

from nengo.utils.cache import bytes2human

print(bytes2human(10000))
print(bytes2human(100001221))
9.8 KB
95.4 MB
nengo.utils.cache.human2bytes(s)[source]

Convert from a human readable string to a size in bytes.

Examples

from nengo.utils.cache import human2bytes

print(human2bytes('1 MB'))
print(human2bytes('1 GB'))
1048576
1073741824
nengo.utils.cache.byte_align(size, alignment)[source]

Returns the int larger than size aligned to alignment bytes.

Connection

nengo.utils.connection.eval_point_decoding

Get the targets and actual decoded values for a set of eval points.

nengo.utils.connection.eval_point_decoding(conn, sim, eval_points=None)[source]

Get the targets and actual decoded values for a set of eval points.

This function evaluates the static decoding (i.e. using the neuron type’s rates function) of a connection for a given set of evaluation points.

Parameters
connConnection

The Connection to evaluate the decoding of.

simSimulator

A Nengo simulator storing the built connection.

eval_pointsarray_like (N, E) (optional)

An N x E array of evaluation points to evaluate the decoding for, where N is the number of points and E is the dimensionality of the input ensemble (i.e. conn.size_in). If None (default), use the connection’s training evaluation points.

Returns
eval_pointsndarray (N, E)

A shallow copy of the evaluation points used. E is the dimensionality of the connection input ensemble (i.e. conn.size_in).

targetsndarray (N, D)

The target function value at each evaluation point.

decodedndarray (N, D)

The decoded function value at each evaluation point.

Ensemble

nengo.utils.ensemble.tuning_curves

Calculates the tuning curves of an ensemble.

nengo.utils.ensemble.response_curves

Calculates the response curves of an ensemble.

nengo.utils.ensemble.sorted_neurons

Sort neurons in an ensemble by encoder and intercept.

nengo.utils.ensemble.tuning_curves(ens, sim, inputs=None)[source]

Calculates the tuning curves of an ensemble.

That is the neuron responses in dependence of the vector represented by the ensemble.

For 1-dimensional ensembles, the unpacked return value of this function can be passed directly to matplotlib.pyplot.plot.

Parameters
ensnengo.Ensemble

Ensemble to calculate the tuning curves of.

simnengo.Simulator

Simulator providing information about the built ensemble. (An unbuilt ensemble does not have tuning curves assigned to it.)

inputssequence of ndarray, optional

The inputs at which the tuning curves will be evaluated. For each of the D ensemble dimensions one array of dimensionality D is needed. The output of numpy.meshgrid() with indexing='ij' is in the right format.

Returns
inputssequence of ndarray

The passed or auto-generated inputs.

activitiesndarray

The activities of the individual neurons given the inputs. For ensembles with 1 dimension, the rows correspond to the inputs and the columns to individual neurons. For ensembles with > 1 dimension, the last dimension enumerates the neurons, the remaining dimensions map to inputs.

See also

response_curves
nengo.utils.ensemble.response_curves(ens, sim, inputs=None)[source]

Calculates the response curves of an ensemble.

That is the neuron responses in dependence of an already encoded value. This corresponds to the tuning curves along the neuron’s preferred directions.

Parameters
ensnengo.Ensemble

Ensemble to calculate the response curves of.

simnengo.Simulator

Simulator providing information about the built ensemble. (An unbuilt ensemble does not have response curves assigned to it.)

inputs1d array, optional

The inputs between -1 and 1 at which the neuron responses will be evaluated. They are assumed to be along each neuron’s preferred direction.

Returns
inputs1d array

The passed or auto-generated inputs.

activities2d array

The activities of the individual neurons given the inputs. The rows map to inputs and the columns to the neurons in the ensemble.

See also

tuning_curves
nengo.utils.ensemble.sorted_neurons(ensemble, sim, iterations=100, seed=None)[source]

Sort neurons in an ensemble by encoder and intercept.

Parameters
ensembleEnsemble

The population of neurons to be sorted.

simSimulator

Simulator providing information about the built ensemble.

iterations: int

The number of times to iterate during the sort.

seed: float

A random number seed.

Returns
indices: ndarray

An array with sorted indices into the neurons in the ensemble

Notes

The algorithm is for each encoder in the initial set, randomly pick another encoder and check to see if swapping those two encoders would reduce the average difference between the encoders and their neighbours. Difference is measured as the dot product. Each encoder has four neighbours (N, S, E, W), except for the ones on the edges which have fewer (no wrapping). This algorithm is repeated iterations times, so a total of iterations*N swaps are considered.

Examples

You can use this to generate an array of sorted indices for plotting. This can be done after collecting the data. E.g.

from nengo.utils.ensemble import sorted_neurons
from nengo.utils.matplotlib import rasterplot

with nengo.Network() as net:
    ens = nengo.Ensemble(10, 1)
    ens_p = nengo.Probe(ens.neurons)

with nengo.Simulator(net) as sim:
    sim.run(0.1)

    indices = sorted_neurons(ens, sim)
    rasterplot(sim.trange(), sim.data[ens_p][:, indices])

Filter design

Functions for filter design.


These are borrowed from SciPy and used under their license:

Copyright (c) 2001, 2002 Enthought, Inc. All rights reserved.

Copyright (c) 2003-2012 SciPy Developers. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  3. Neither the name of Enthought nor the names of the SciPy Developers may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nengo.utils.filter_design.BadCoefficients

nengo.utils.filter_design.tf2zpk

Return zero, pole, gain (z,p,k) representation from a numerator, denominator representation of a linear filter.

nengo.utils.filter_design.zpk2tf

Return polynomial transfer function representation from zeros and poles.

nengo.utils.filter_design.normalize

Normalize polynomial representation of a transfer function.

nengo.utils.filter_design.tf2ss

Transfer function to state-space representation.

nengo.utils.filter_design.abcd_normalize

Check state-space matrices and ensure they are rank-2.

nengo.utils.filter_design.ss2tf

State-space to transfer function.

nengo.utils.filter_design.zpk2ss

Zero-pole-gain representation to state-space representation.

nengo.utils.filter_design.ss2zpk

State-space representation to zero-pole-gain representation.

nengo.utils.filter_design.cont2discrete

Transform a continuous to a discrete state-space system.

exception nengo.utils.filter_design.BadCoefficients[source]
nengo.utils.filter_design.tf2zpk(b, a)[source]

Return zero, pole, gain (z,p,k) representation from a numerator, denominator representation of a linear filter.

Parameters
bndarray

Numerator polynomial.

andarray

Denominator polynomial.

Returns
zndarray

Zeros of the transfer function.

pndarray

Poles of the transfer function.

kfloat

System gain.

Notes

If some values of b are too close to 0, they are removed. In that case, a BadCoefficients warning is emitted.

nengo.utils.filter_design.zpk2tf(z, p, k)[source]

Return polynomial transfer function representation from zeros and poles.

Parameters
zndarray

Zeros of the transfer function.

pndarray

Poles of the transfer function.

kfloat

System gain.

Returns
bndarray

Numerator polynomial.

andarray

Denominator polynomial.

nengo.utils.filter_design.normalize(b, a)[source]

Normalize polynomial representation of a transfer function.

If values of b are too close to 0, they are removed. In that case, a BadCoefficients warning is emitted.

nengo.utils.filter_design.tf2ss(num, den)[source]

Transfer function to state-space representation.

Parameters
num, denarray_like

Sequences representing the numerator and denominator polynomials. The denominator needs to be at least as long as the numerator.

Returns
A, B, C, Dndarray

State space representation of the system.

nengo.utils.filter_design.abcd_normalize(A=None, B=None, C=None, D=None)[source]

Check state-space matrices and ensure they are rank-2.

If enough information on the system is provided, that is, enough properly-shaped arrays are passed to the function, the missing ones are built from this information, ensuring the correct number of rows and columns. Otherwise a ValueError is raised.

Parameters
A, B, C, Darray_like, optional

State-space matrices. All of them are None (missing) by default.

Returns
A, B, C, Darray

Properly shaped state-space matrices.

Raises
ValueError

If not enough information on the system was provided.

nengo.utils.filter_design.ss2tf(A, B, C, D, input=0)[source]

State-space to transfer function.

Parameters
A, B, C, Dndarray

State-space representation of linear system.

inputint, optional

For multiple-input systems, the input to use.

Returns
num2-D ndarray

Numerator(s) of the resulting transfer function(s). num has one row for each of the system’s outputs. Each row is a sequence representation of the numerator polynomial.

den1-D ndarray

Denominator of the resulting transfer function(s). den is a sequence representation of the denominator polynomial.

nengo.utils.filter_design.zpk2ss(z, p, k)[source]

Zero-pole-gain representation to state-space representation.

Parameters
z, psequence

Zeros and poles.

kfloat

System gain.

Returns
A, B, C, Dndarray

State-space matrices.

nengo.utils.filter_design.ss2zpk(A, B, C, D, input=0)[source]

State-space representation to zero-pole-gain representation.

Parameters
A, B, C, Dndarray

State-space representation of linear system.

inputint, optional

For multiple-input systems, the input to use.

Returns
z, psequence

Zeros and poles.

kfloat

System gain.

nengo.utils.filter_design.cont2discrete(sys, dt, method='zoh', alpha=None)[source]

Transform a continuous to a discrete state-space system.

Parameters
sysa tuple describing the system.

The following gives the number of elements in the tuple and the interpretation:

  • 2: (num, den)

  • 3: (zeros, poles, gain)

  • 4: (A, B, C, D)

dtfloat

The discretization time step.

method{“gbt”, “bilinear”, “euler”, “backward_diff”, “zoh”}

Which method to use:

  • gbt: generalized bilinear transformation

  • bilinear: Tustin’s approximation (“gbt” with alpha=0.5)

  • euler: Euler (or forward differencing) method (“gbt” with alpha=0)

  • backward_diff: Backwards differencing (“gbt” with alpha=1.0)

  • zoh: zero-order hold (default)

alphafloat within [0, 1]

The generalized bilinear transformation weighting parameter, which should only be specified with method=”gbt”, and is ignored otherwise

Returns
sysdtuple containing the discrete system

Based on the input type, the output will be of the form

  • (num, den, dt) for transfer function input

  • (zeros, poles, gain, dt) for zeros-poles-gain input

  • (A, B, C, D, dt) for state-space system input

Notes

By default, the routine uses a Zero-Order Hold (zoh) method to perform the transformation. Alternatively, a generalized bilinear transformation may be used, which includes the common Tustin’s bilinear approximation, an Euler’s method technique, or a backwards differencing technique.

The Zero-Order Hold (zoh) method is based on [1], the generalized bilinear approximation is based on [2] and [3].

References

1

https://en.wikipedia.org/wiki/Discretization #Discretization_of_linear_state_space_models

2

http://techteach.no/publications/discretetime_signals_systems/discrete.pdf

3

G. Zhang, X. Chen, and T. Chen, Digital redesign via the generalized bilinear transformation, Int. J. Control, vol. 82, no. 4, pp. 741-754, 2009.

Functions

nengo.utils.functions.function_name

Returns the name of a function.

nengo.utils.functions.function_name(func)[source]

Returns the name of a function.

Unlike accessing func.__name__, this function is robust to the different types of objects that can be considered a function in Nengo.

Parameters
funccallable or array_like

Object used as function argument.

Returns
str

Name of function object.

Graphs

Simple graph manipulation algorithms.

Nengo models are essentially graphs where ensembles, nodes, and networks are graph vertices, and connections are edges. We make use of this fact in some places in the code; this file contains functions to help with that.


toposort and reverse_edges are adapted from Theano (theano/gof/sched.py). This modified code is included under the terms of their license:

Theano is copyright (c) 2008–2013 Theano Development Team.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of Theano nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ‘’AS IS’’ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nengo.utils.graphs.BidirectionalDAG

Directed acyclic graph supporting bidirectional traversal.

nengo.utils.graphs.toposort

Topological sort algorithm by Kahn [1].

nengo.utils.graphs.transitive_closure

Constructs the transitive closure of a directed acyclic graph (DAG).

nengo.utils.graphs.reverse_edges

Reverses direction of dependence dict.

nengo.utils.graphs.add_edges

Add new edges to graph.

class nengo.utils.graphs.BidirectionalDAG(forward)[source]

Directed acyclic graph supporting bidirectional traversal.

Parameters
forwarddict

Forward edges for each vertex in the form {1: {2, 3}, 2: {3}, 3: set()}.

Attributes
forwarddict

Maps vertices to edges in forward direction.

backwarddict

Maps vertices to edges in backward direction.

merge(vertices, merged_vertex)[source]

Merges vertices in the graph.

Parameters
verticesset

Vertices that are being merged.

merged_vertex

The vertex that replaces vertices.

nengo.utils.graphs.toposort(edges)[source]

Topological sort algorithm by Kahn [1].

Complexity is O(nodes + vertices).

Parameters
edgesdict

Dict of the form {a: {b, c}} where b and c depend on a

Returns
An ordered list of nodes that satisfy the dependencies of edges

Notes

Closely follows the wikipedia page [2].

References

1(1,2)

Kahn, Arthur B. (1962), “Topological sorting of large networks”, Communications of the ACM

2

https://en.wikipedia.org/wiki/Toposort#Algorithms

Examples

from nengo.utils.graphs import toposort

print(toposort({1: {2, 3}, 2: {3}, 3: set()}))
[1, 2, 3]
nengo.utils.graphs.transitive_closure(edges, topo_sorted=None)[source]

Constructs the transitive closure of a directed acyclic graph (DAG).

The complexity is O(nodes + vertices).

Parameters
edgesdict

Dict of the form {a: {b, c}} where b and c depend on a. Must not contain cycles.

topo_sortedsequence, optional

The topological sorting of the vertices. If not passed in, the algorithm will do a topological sort.

Returns
The transitive closure using the same data structure as edges: a dict
of the form {a: {b, c}} where b and c are nodes that either
directly or indirectly depend on a.
nengo.utils.graphs.reverse_edges(edges)[source]

Reverses direction of dependence dict.

Parameters
edgesdict

Dict of the form {a: {b, c}, b: set(), c: set()} where b and c depend on a.

Returns
Dict of the form {a: set(), b: {a}, c: {a}} where b and c depend on a.
nengo.utils.graphs.add_edges(edges, new_edge_iter)[source]

Add new edges to graph.

IPython

Functions for easy interactions with IPython and IPython notebooks.

nengo.utils.ipython.check_ipy_version

Check that ipython version is >= min_version.

nengo.utils.ipython.hide_input

Hide the input of the Jupyter notebook input block this is executed in.

nengo.utils.ipython.load_notebook

Load notebook from file.

nengo.utils.ipython.export_py

Convert notebook to Python script.

nengo.utils.ipython.iter_cells

Iterate over cells of a notebok.

nengo.utils.ipython.check_ipy_version(min_version)[source]

Check that ipython version is >= min_version.

nengo.utils.ipython.hide_input()[source]

Hide the input of the Jupyter notebook input block this is executed in.

Returns a link to toggle the visibility of the input block.

nengo.utils.ipython.load_notebook(nb_path)[source]

Load notebook from file.

nengo.utils.ipython.export_py(nb, dest_path=None)[source]

Convert notebook to Python script.

Optionally saves script to dest_path.

nengo.utils.ipython.iter_cells(nb, cell_type='code')[source]

Iterate over cells of a notebok.

Lock

nengo.utils.lock.FileLock

Lock access to a file (for multithreading).

class nengo.utils.lock.FileLock(filename, timeout=10.0, poll=0.1)[source]

Lock access to a file (for multithreading).

Magic

nengo.utils.magic.decorator(wrapper)[source]

Decorate decorators.

This imposes a particular style of writing descriptors. The descriptor must accept four positional arguments:

  • wrapped: the function being wrapped

  • instance: the instance that is bound to the function in the case of bound functions (None in the case of plain functions)

  • args: the positional arguments passed to the wrapped function

  • kwargs: the keyword arguments passed to the wrapped function

Examples

Decorating a normal function (i.e., instance will always be None):

from nengo.utils.magic import decorator

@decorator
def my_decorator(wrapped, instance, args, kwargs):
    return wrapped(*args, **kwargs)

@my_decorator
def f():
    return 1

Decorating a bound function:

@decorator
def my_decorator(wrapped, instance, args, kwargs):
    return wrapped(*args, **kwargs)

class MyClass:
    @my_decorator
    def f(self):
        return self.num + 1

Matplotlib

nengo.utils.matplotlib.get_color_cycle

Get matplotlib colour cycle.

nengo.utils.matplotlib.set_color_cycle

Set matplotlib colour cycle.

nengo.utils.matplotlib.axis_size

Get axis width and height in pixels.

nengo.utils.matplotlib.implot

Image plot of general data (like imshow but with non-pixel axes).

nengo.utils.matplotlib.rasterplot

Generate a raster plot of the provided spike data.

nengo.utils.matplotlib.get_color_cycle()[source]

Get matplotlib colour cycle.

nengo.utils.matplotlib.set_color_cycle(colors, ax=None)[source]

Set matplotlib colour cycle.

nengo.utils.matplotlib.axis_size(ax=None)[source]

Get axis width and height in pixels.

Based on a StackOverflow response: https://stackoverflow.com/questions/19306510/determine-matplotlib-axis-size-in-pixels

Parameters
axaxis object

The axes to determine the size of. Defaults to current axes.

Returns
widthfloat

Width of axes in pixels.

heightfloat

Height of axes in pixels.

nengo.utils.matplotlib.implot(plt_, x, y, Z, ax=None, colorbar=True, **kwargs)[source]

Image plot of general data (like imshow but with non-pixel axes).

Parameters
plt_plot object

Plot object, typically matplotlib.pyplot.

x(M,) array_like

Vector of x-axis points, must be linear (equally spaced).

y(N,) array_like

Vector of y-axis points, must be linear (equally spaced).

Z(M, N) array_like

Matrix of data to be displayed, the value at each (x, y) point.

axaxis object (optional)

A specific axis to plot on (defaults to plt.gca()).

colorbar: boolean (optional)

Whether to plot a colorbar.

**kwargs

Additional arguments for ax.imshow.

nengo.utils.matplotlib.rasterplot(time, spikes, ax=None, use_eventplot=False, **kwargs)[source]

Generate a raster plot of the provided spike data.

Parameters
timearray

Time data from the simulation

spikesarray

The spike data with columns for each neuron and 1s indicating spikes

axmatplotlib.axes.Axes, optional

The figure axes to plot into. If None, we will use current axes.

use_eventplotboolean, optional

Whether to use the new Matplotlib eventplot routine. It is slower and makes larger image files, so we do not use it by default.

Returns
axmatplotlib.axes.Axes

The axes that were plotted into

Examples

from nengo.utils.matplotlib import rasterplot

with nengo.Network() as net:
    a = nengo.Ensemble(20, 1)
    p = nengo.Probe(a.neurons)

with nengo.Simulator(net) as sim:
    sim.run(1)

rasterplot(sim.trange(), sim.data[p])

NCO

Implementation of the Nengo cache object (NCO) protocol.

Nengo cache objects store a Numpy array and some associated, picklable Python object in a single, uncompressed file. These files are not platform independent as they are optimized for fast reading and writing, and cached data is not supposed to be shared across platforms.

The protocol version 0 is as follows:

  • A header consisting of:
    • 3 bytes with the magic string ‘NCO’

    • 1 unsigned byte indicating the protocol version

    • unsigned long int denoting the start of the Python object data

    • unsigned long int denoting the end of the Python object data

    • unsigned long int denoting the start of the array data

    • unsigned long int denoting the end of the array data

  • Potentially some padding bytes.

  • The Python object data pickled by the (c)pickle module using the highest available protocol.

  • Potentially some padding bytes.

  • The array data in NPY format.

Files will be written with padding to have both the Python object data and the array data an alignment of 16 bytes.

The Numpy NPY format is documented here: https://numpy.org/devdocs/reference/generated/numpy.lib.format.html

As of legacy version 1 of the cache, multiple NCO files will be concatenated into one file. The start and end of each subfile will be stored in a cache index, but can also be recovered from reading the headers of the NCO files in order as each one gives the start of the next header (corresponding to the end of the array data).

nengo.utils.nco.Subfile

A file-like object for limiting reads to a subrange of a file.

nengo.utils.nco.write

Writes a Nengo cache object.

nengo.utils.nco.read

Reads a Nengo cache object.

class nengo.utils.nco.Subfile(fileobj, start, end)[source]

A file-like object for limiting reads to a subrange of a file.

This class only supports reading and seeking. Writing is not supported.

Parameters
fileobjfile-like object

Complete files.

startint

Offset of the first readable position in the file.

endint

Offset of the last readable position + 1 in the file.

nengo.utils.nco.write(fileobj, metadata, array)[source]

Writes a Nengo cache object.

Parameters
fileobjfile-like object

File object to write the data to.

metadataobject

Python object with metadata (will be pickled).

arrayndarray

Numpy array with the actual data to store.

nengo.utils.nco.read(fileobj)[source]

Reads a Nengo cache object.

Parameters
fileobjfile-like object

The file object to read from.

Returns
metadata, array

Returns a tuple with the Python object containing the metadata as first element and the array with the actual data as second element.

Network

nengo.utils.network.with_self

Wraps a method with with network:.

nengo.utils.network.activate_direct_mode

Activates direct mode for a network.

nengo.utils.network.with_self(method, network, args, kwargs)[source]

Wraps a method with with network:.

This makes it easy to add methods to a network that create new Nengo objects. Instead of writing with self at the top of the method and indenting everything over, you can instead use this decorator.

Examples

The two methods in the following class do the same thing:

from nengo.utils.network import with_self

class MyNetwork(nengo.Network):
    def add_one_1(self):
        with self:
            node = nengo.Node(output=1)

    @with_self
    def add_one_2(self):
        node = nengo.Node(output=1)
nengo.utils.network.activate_direct_mode(network)[source]

Activates direct mode for a network.

This sets the neuron type of all ensembles to a nengo.Direct instance unless:

  • there is a connection to or from the ensemble’s neurons

  • there is a probe on an ensemble’s neurons

  • the ensemble has a connection with a learning rule attached.

Parameters
networkNetwork

Network to activate direct mode for.

Numpy

Extra functions to extend the capabilities of Numpy.

nengo.utils.numpy.is_spmatrix

Check if obj is a sparse matrix.

nengo.utils.numpy.is_integer

Check if obj is an integer type.

nengo.utils.numpy.is_iterable

Check if obj is an iterable.

nengo.utils.numpy.is_number

Check if obj is a numeric type.

nengo.utils.numpy.is_array

Check if obj is a numpy array.

nengo.utils.numpy.is_array_like

Check if obj is an array like object.

nengo.utils.numpy.compare

Return -1/0/1 if a is less/equal/greater than b.

nengo.utils.numpy.as_shape

Return a tuple if x is iterable or (x,) if x is integer.

nengo.utils.numpy.broadcast_shape

Pad a shape with ones following standard Numpy broadcasting.

nengo.utils.numpy.array

Create numpy array with some extra configuration.

nengo.utils.numpy.array_hash

Simple fast array hash function.

nengo.utils.numpy.array_offset

Get offset of array data from base data in bytes.

nengo.utils.numpy.norm

Compute the Euclidean norm.

nengo.utils.numpy.meshgrid_nd

Multidimensional meshgrid.

nengo.utils.numpy.rms

Compute the root-mean-square amplitude.

nengo.utils.numpy.rmse

Compute the root-mean-square error.

nengo.utils.numpy.nrmse

Compute the root-mean-square (RMS) error normalized by the RMS of b.

nengo.utils.numpy.is_spmatrix(obj)[source]

Check if obj is a sparse matrix.

nengo.utils.numpy.is_integer(obj)[source]

Check if obj is an integer type.

nengo.utils.numpy.is_iterable(obj)[source]

Check if obj is an iterable.

nengo.utils.numpy.is_number(obj, check_complex=False)[source]

Check if obj is a numeric type.

nengo.utils.numpy.is_array(obj)[source]

Check if obj is a numpy array.

nengo.utils.numpy.is_array_like(obj)[source]

Check if obj is an array like object.

nengo.utils.numpy.compare(a, b)[source]

Return -1/0/1 if a is less/equal/greater than b.

nengo.utils.numpy.as_shape(x, min_dim=0)[source]

Return a tuple if x is iterable or (x,) if x is integer.

nengo.utils.numpy.broadcast_shape(shape, length)[source]

Pad a shape with ones following standard Numpy broadcasting.

nengo.utils.numpy.array(x, dims=None, min_dims=0, readonly=False, **kwargs)[source]

Create numpy array with some extra configuration.

This is a wrapper around np.array.

Unlike np.array, the additional single-dimensional indices added by dims or min_dims will appear at the end of the shape (for example, array([1, 2, 3], dims=4).shape == (3, 1, 1, 1)).

Parameters
dimsint or None

If not None, force the output array to have exactly this many indices. If the input has more than this number of indices, this throws an error.

min_dimsint

Force the output array to have at least this many indices (ignored if dims is not None).

readonlybool

Make the output array read-only.

**kwargs

Additional keyword arguments to pass to np.array.

nengo.utils.numpy.array_hash(a, n=100)[source]

Simple fast array hash function.

For arrays with size larger than n, pick n elements at random to hash. This strategy should work well for dense arrays, but for sparse arrays (those with few non-zero elements) it is more likely to give hash collisions.

For sparse matrices, we apply the same logic on the underlying elements (data, indices) of the sparse matrix.

nengo.utils.numpy.array_offset(x)[source]

Get offset of array data from base data in bytes.

nengo.utils.numpy.norm(x, axis=None, keepdims=False)[source]

Compute the Euclidean norm.

Parameters
xarray_like

Array to compute the norm over.

axisNone or int or tuple of ints, optional

Axis or axes to sum across. None sums all axes. See np.sum.

keepdimsbool, optional

If True, the reduced axes are left in the result. See np.sum in newer versions of Numpy (>= 1.7).

nengo.utils.numpy.meshgrid_nd(*args)[source]

Multidimensional meshgrid.

nengo.utils.numpy.rms(x, axis=None, keepdims=False)[source]

Compute the root-mean-square amplitude.

Parameters
xarray_like

Array to compute RMS amplitude over.

axisNone or int or tuple of ints, optional

Axis or axes to sum across. None sums all axes. See np.sum.

keepdimsbool, optional

If True, the reduced axes are left in the result. See np.sum in newer versions of Numpy (>= 1.7).

nengo.utils.numpy.rmse(x, y, axis=None, keepdims=False)[source]

Compute the root-mean-square error.

Equivalent to rms(x - y, axis=axis, keepdims=keepdims).

Parameters
x, yarray_like

Arrays to compute RMS amplitude over.

axisNone or int or tuple of ints, optional

Axis or axes to sum across. None sums all axes. See np.sum.

keepdimsbool, optional

If True, the reduced axes are left in the result. See np.sum in newer versions of Numpy (>= 1.7).

nengo.utils.numpy.nrmse(a, b, axis=None, keepdims=False)[source]

Compute the root-mean-square (RMS) error normalized by the RMS of b.

Equivalent to rms(a - b, **kwargs) / rms(b, **kwargs)

Parameters
a, barray_like

Arrays to compute RMS error over, normalized by the rms amplitude of b.

axisNone or int or tuple of ints, optional

Axis or axes to sum across. None sums all axes. See np.sum.

keepdimsbool, optional

If True, the reduced axes are left in the result. See np.sum in newer versions of Numpy (>= 1.7).

Paths

Progress bars

Utilities for progress tracking and display to the user.

nengo.utils.progress.MemoryLeakWarning

nengo.utils.progress.timestamp2timedelta

Convert timestamp to timedelta.

nengo.utils.progress.Progress

Stores and tracks information about the progress of some process.

nengo.utils.progress.ProgressBar

Visualizes the progress of a process.

nengo.utils.progress.NoProgressBar

A progress bar that does not display anything.

nengo.utils.progress.TerminalProgressBar

A progress bar that is displayed as ASCII output on stdout.

nengo.utils.progress.VdomProgressBar

A progress bar using a virtual DOM representation.

nengo.utils.progress.HtmlProgressBar

A progress bar using a HTML representation.

nengo.utils.progress.VdomOrHtmlProgressBar

Progress bar using the VDOM or HTML progress bar.

nengo.utils.progress.IPython5ProgressBar

ProgressBar for IPython>=5 environments.

nengo.utils.progress.WriteProgressToFile

Writes progress to a file.

nengo.utils.progress.AutoProgressBar

Suppresses the progress bar unless the ETA exceeds a threshold.

nengo.utils.progress.ProgressTracker

Tracks the progress of some process with a progress bar.

nengo.utils.progress.get_default_progressbar

The default progress bar to use depending on the execution environment.

nengo.utils.progress.to_progressbar

Converts to a ProgressBar instance.

exception nengo.utils.progress.MemoryLeakWarning[source]
nengo.utils.progress.timestamp2timedelta(timestamp)[source]

Convert timestamp to timedelta.

class nengo.utils.progress.Progress(name_during='', name_after=None, max_steps=None)[source]

Stores and tracks information about the progress of some process.

This class is to be used as part of a with statement. Use step() to update the progress.

Parameters
max_stepsint

The total number of calculation steps of the process.

name_duringstr, optional

Short description of the task to be used while it is running.

name_afterstr, optional

Short description of the task to be used after it has finished. Defaults to name_during.

Examples

from nengo.utils.progress import Progress

max_steps = 10
with Progress(max_steps=max_steps) as progress:
    for i in range(max_steps):
        # do something
        progress.step()
Attributes
max_stepsint, optional

The total number of calculation steps of the process, if known.

name_afterstr

Name of the task to be used after it has finished.

name_duringstr

Name of the task to be used while it is running.

stepsint

Number of completed steps.

successbool or None

Whether the process finished successfully. None if the process did not finish yet.

time_endfloat

Time stamp of the time the process was finished or aborted.

time_startfloat

Time stamp of the time the process was started.

property progress

The current progress as a number from 0 to 1 (inclusive).

Returns
float
elapsed_seconds()[source]

The number of seconds passed since entering the with statement.

Returns
float
eta()[source]

The estimated number of seconds until the process is finished.

Stands for estimated time of arrival (ETA). If no estimate is available -1 will be returned.

Returns
float
step(n=1)[source]

Advances the progress.

Parameters
nint

Number of steps to advance the progress by.

class nengo.utils.progress.ProgressBar[source]

Visualizes the progress of a process.

This is an abstract base class that progress bar classes some inherit from. Progress bars should visually displaying the progress in some way.

update(progress)[source]

Updates the displayed progress.

Parameters
progressProgress

The progress information to display.

close()[source]

Closes the progress bar.

Indicates that not further updates will be made.

class nengo.utils.progress.NoProgressBar[source]

A progress bar that does not display anything.

Helpful in headless situations or when using Nengo as a library.

update(progress)[source]

Updates the displayed progress.

Parameters
progressProgress

The progress information to display.

class nengo.utils.progress.TerminalProgressBar[source]

A progress bar that is displayed as ASCII output on stdout.

update(progress)[source]

Updates the displayed progress.

Parameters
progressProgress

The progress information to display.

close()[source]

Closes the progress bar.

Indicates that not further updates will be made.

class nengo.utils.progress.VdomProgressBar[source]

A progress bar using a virtual DOM representation.

This HTML representation can be used in Jupyter lab (>=0.32) environments.

update(progress)[source]

Updates the displayed progress.

Parameters
progressProgress

The progress information to display.

class nengo.utils.progress.HtmlProgressBar[source]

A progress bar using a HTML representation.

This HTML representation can be used in Jupyter notebook environments and is provided by the _repr_html_ method that will be automatically used by IPython interpreters.

If the kernel frontend does not support HTML (e.g., in Jupyter qtconsole), a warning message will be issued as the ASCII representation.

update(progress)[source]

Updates the displayed progress.

Parameters
progressProgress

The progress information to display.

class nengo.utils.progress.VdomOrHtmlProgressBar[source]

Progress bar using the VDOM or HTML progress bar.

This progress bar will transmit both representations as part of a MIME bundle and it is up to the Jupyter client to pick the preferred version. Usually this will be the VDOM if supported, and the HTML version where VDOM is not supported.

update(progress)[source]

Updates the displayed progress.

Parameters
progressProgress

The progress information to display.

class nengo.utils.progress.IPython5ProgressBar[source]

ProgressBar for IPython>=5 environments.

Provides a VDOM/HTML representation, except for in a pure terminal IPython (i.e. not an IPython kernel that was connected to via ZMQ), where a ASCII progress bar will be used.

Note that some Jupyter environments (like qtconsole) will try to use the VDOM/HTML version, but do not support HTML and will show a warning instead of an actual progress bar.

update(progress)[source]

Updates the displayed progress.

Parameters
progressProgress

The progress information to display.

class nengo.utils.progress.WriteProgressToFile(filename)[source]

Writes progress to a file.

This is useful for remotely and intermittently monitoring progress. Note that this file will be overwritten on each update of the progress!

Parameters
filenamestr

Path to the file to write the progress to.

update(progress)[source]

Updates the displayed progress.

Parameters
progressProgress

The progress information to display.

class nengo.utils.progress.AutoProgressBar(delegate, min_eta=1.0)[source]

Suppresses the progress bar unless the ETA exceeds a threshold.

Parameters
delegateProgressBar

The actual progress bar to display, if ETA is high enough.

min_etafloat, optional

The minimum ETA threshold for displaying the progress bar.

update(progress)[source]

Updates the displayed progress.

Parameters
progressProgress

The progress information to display.

close()[source]

Closes the progress bar.

Indicates that not further updates will be made.

class nengo.utils.progress.ProgressTracker(progress_bar, total_progress, update_interval=0.1)[source]

Tracks the progress of some process with a progress bar.

Parameters
progress_barProgressBar or bool or None

The progress bar to display the progress (or True to use the default progress bar, False/None to disable progress bar).

total_progressint

Maximum number of steps of the process.

update_intervalfloat, optional

Time to wait (in seconds) between updates to progress bar display.

next_stage(name_during='', name_after=None, max_steps=None)[source]

Begin tracking progress of a new stage.

Parameters
max_stepsint, optional

The total number of calculation steps of the process.

name_duringstr, optional

Short description of the task to be used while it is running.

name_afterstr, optional

Short description of the task to be used after it has finished. Defaults to name_during.

update_loop()[source]

Update the progress bar display (will run in a separate thread).

nengo.utils.progress.get_default_progressbar()[source]

The default progress bar to use depending on the execution environment.

Returns
ProgressBar
nengo.utils.progress.to_progressbar(progress_bar)[source]

Converts to a ProgressBar instance.

Parameters
progress_barNone, bool, or ProgressBar

Object to be converted to a ProgressBar.

Returns
ProgressBar

Return progress_bar if it is already a progress bar, the default progress bar if progress_bar is True, and NoProgressBar if it is None or False.

Simulator

nengo.utils.simulator.operator_dependency_graph

Sort operators in a directed graph based on read/write dependencies.

nengo.utils.simulator.validate_ops

Validate operator reads/writes.

nengo.utils.simulator.operator_dependency_graph(operators)[source]

Sort operators in a directed graph based on read/write dependencies.

nengo.utils.simulator.validate_ops(sets, ups, incs)[source]

Validate operator reads/writes.

stdlib

Functions that extend the Python Standard Library.

nengo.utils.stdlib.WeakKeyDefaultDict

WeakKeyDictionary that allows to define a default.

nengo.utils.stdlib.WeakKeyIDDictionary

WeakKeyDictionary that uses object ID to hash.

nengo.utils.stdlib.WeakSet

Uses weak references to store the items in the set.

nengo.utils.stdlib.FrozenOrderedSet

A set that preserves insertion order and is hashable.

nengo.utils.stdlib.OrderedSet

A set that preserves insertion order and is mutable.

nengo.utils.stdlib.CheckedCall

nengo.utils.stdlib.checked_call

Calls func and checks that invocation was successful.

nengo.utils.stdlib.execfile

Execute a Python script in the (mandatory) globals namespace.

nengo.utils.stdlib.groupby

Group objects based on a key.

nengo.utils.stdlib.Timer

A context manager for timing a block of code.

class nengo.utils.stdlib.WeakKeyDefaultDict(default_factory, items=None, **kwargs)[source]

WeakKeyDictionary that allows to define a default.

class nengo.utils.stdlib.WeakKeyIDDictionary(*args, **kwargs)[source]

WeakKeyDictionary that uses object ID to hash.

This ignores the __eq__ and __hash__ functions on objects, so that objects are only considered equal if one is the other.

get(key, default=None)[source]

Return item from dictionary.

keys()[source]

Return dictionary keys.

items()[source]

Return dictionary key, value pairs.

update(in_dict)[source]

Update with items from other dictionary.

class nengo.utils.stdlib.WeakSet(items=None)[source]

Uses weak references to store the items in the set.

add(value)[source]

Add an element.

discard(value)[source]

Remove an element. Do not raise an exception if absent.

class nengo.utils.stdlib.FrozenOrderedSet(data=None)[source]

A set that preserves insertion order and is hashable.

class nengo.utils.stdlib.OrderedSet(data=None)[source]

A set that preserves insertion order and is mutable.

add(value)[source]

Add an element.

discard(value)[source]

Remove an element. Do not raise an exception if absent.

class nengo.utils.stdlib.CheckedCall(value, invoked)[source]

Create new instance of CheckedCall(value, invoked)

invoked

Alias for field number 1

value

Alias for field number 0

nengo.utils.stdlib.checked_call(func, *args, **kwargs)[source]

Calls func and checks that invocation was successful.

The namedtuple (value=func(*args, **kwargs), invoked=True) is returned if the call is successful. If an exception occurs inside of func, then that exception will be raised. Otherwise, if the exception occurs as a result of invocation, then (value=None, invoked=False) is returned.

Assumes that func is callable.

nengo.utils.stdlib.execfile(path, globals, locals=None)[source]

Execute a Python script in the (mandatory) globals namespace.

This is similar to the Python 2 builtin execfile, but it also works on Python 3, and globals is mandatory. This is because getting the calling frame’s globals would be non-trivial, and it makes sense to be explicit about the namespace being modified.

If locals is not specified, it will have the same value as globals, as in the execfile builtin.

nengo.utils.stdlib.groupby(objects, key, hashable=None, force_list=True)[source]

Group objects based on a key.

Unlike itertools.groupby, this function does not require the input to be sorted.

Parameters
objectsIterable

The objects to be grouped.

keycallable

The key function by which to group the objects. If key(obj1) == key(obj2) then obj1 and obj2 are in the same group, otherwise they are not.

hashableboolean (optional)

Whether to use the key’s hash to determine equality. By default, this will be determined by calling key on the first item in objects, and if it is hashable, the hash will be used. Using a hash is faster, but not possible for all keys.

force_listboolean (optional)

Whether to force the returned key_groups iterator, as well as the group iterator in each (key, group) pair, to be lists.

Returns
keygroupsiterable

An iterable of (key, group) pairs, where key is the key used for grouping, and group is an iterable of the items in the group. The nature of the iterables depends on the value of force_list.

class nengo.utils.stdlib.Timer[source]

A context manager for timing a block of code.

Examples

import time
from nengo.utils.stdlib import Timer

with Timer() as t:
   time.sleep(1)
assert t.duration >= 1
Attributes
durationfloat

The difference between the start and end time (in seconds). Usually this is what you care about.

startfloat

The time at which the timer started (in seconds).

endfloat

The time at which the timer ended (in seconds).

Testing

nengo.utils.testing.signals_allclose

Ensure all signal elements are within tolerances.

nengo.utils.testing.ThreadedAssertion

Performs assertions in parallel.

nengo.utils.testing.signals_allclose(t, targets, signals, atol=1e-08, rtol=1e-05, buf=0, delay=0, plt=None, labels=None, individual_results=False, allclose=<function allclose>)[source]

Ensure all signal elements are within tolerances.

Allows for delay, removing the beginning of the signal, and plotting.

Parameters
tarray_like (T,)

Simulation time for the points in target and signals.

targetsarray_like (T, 1) or (T, N)

Reference signal or signals for error comparison.

signalsarray_like (T, N)

Signals to be tested against the target signals.

atol, rtolfloat

Absolute and relative tolerances.

buffloat

Length of time (in seconds) to remove from the beginnings of signals.

delayfloat

Amount of delay (in seconds) to account for when doing comparisons.

pltmatplotlib.pyplot or mock

Pyplot interface for plotting the results, unless it’s mocked out.

labelslist of string, length N

Labels of each signal to use when plotting.

individual_resultsbool

If True, returns a separate allclose result for each signal.

allclosecallable

Function to compare two arrays for similarity.

class nengo.utils.testing.ThreadedAssertion(n_threads)[source]

Performs assertions in parallel.

Starts a number of threads, waits for each thread to execute some initialization code, and then executes assertions in each thread.

To use this class, create a derived class that implements init_thread to start each thread running and assert_thread to check that the thread has run successfully. finish_thread can be used for any cleanup/shutdown of the thread.

class AssertionWorker(parent, barriers, n)[source]

This constructor should always be called with keyword arguments. Arguments are:

group should be None; reserved for future extension when a ThreadGroup class is implemented.

target is the callable object to be invoked by the run() method. Defaults to None, meaning nothing is called.

name is the thread name. By default, a unique name is constructed of the form “Thread-N” where N is a small decimal number.

args is the argument tuple for the target invocation. Defaults to ().

kwargs is a dictionary of keyword arguments for the target invocation. Defaults to {}.

If a subclass overrides the constructor, it must make sure to invoke the base class constructor (Thread.__init__()) before doing anything else to the thread.

run()[source]

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

Threading

nengo.utils.threading.ThreadLocalStack

class nengo.utils.threading.ThreadLocalStack(maxsize=None)[source]