Note

This documentation is for a development version. Click here for the latest stable release (v4.0.0).

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.

Filter design¶

Functions for filter design.

These are borrowed from SciPy and used under their license:

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

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