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.
Compute the full transform matrix for a Dense connection transform. |
|
A heuristic to determine an appropriate number of evaluation points. |
|
Given a Network, returns all (ensembles + nodes, connections). |
|
Moved to nengo_extras.graphviz. |
|
Returns a version of the model without passthrough Nodes. |
|
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.
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.
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.
Convert from a size in bytes to a human readable string. |
|
Convert from a human readable string to a size in bytes. |
|
Returns the int larger than |
-
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
Connection¶
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¶
Calculates the tuning curves of an ensemble. |
|
Calculates the response curves of an ensemble. |
|
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 dimensionalityD
is needed. The output ofnumpy.meshgrid()
withindexing='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 theinputs
and the columns to individual neurons. For ensembles with > 1 dimension, the last dimension enumerates the neurons, the remaining dimensions map toinputs
.
See also
-
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 toinputs
and the columns to the neurons in the ensemble.
See also
-
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 ofiterations*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:
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.
Return zero, pole, gain (z,p,k) representation from a numerator, denominator representation of a linear filter. |
|
Return polynomial transfer function representation from zeros and poles |
|
Normalize polynomial representation of a transfer function. |
|
Transfer function to state-space representation. |
|
Check state-space matrices and ensure they are rank-2. |
|
State-space to transfer function. |
|
Zero-pole-gain representation to state-space representation |
|
State-space representation to zero-pole-gain representation. |
|
Transform a continuous to a discrete state-space system. |
-
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¶
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.
Directed acyclic graph supporting bidirectional traversal. |
|
Topological sort algorithm by Kahn [1]. |
|
Constructs the transitive closure of a directed acyclic graph (DAG). |
|
Reverses direction of dependence dict. |
|
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.
-
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
- An ordered list of nodes that satisfy the dependencies of
Notes
Closely follows the wikipedia page [2].
References
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}}
whereb
andc
depend ona
. 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}}
whereb
andc
are nodes that either - directly or indirectly depend on
a
.
- The transitive closure using the same data structure as
IPython¶
Functions for easy interactions with IPython and IPython notebooks.
Check that ipython version is >= |
|
Hide the input of the Jupyter notebook input block this is executed in. |
|
Load notebook from file. |
|
Convert notebook to Python script. |
|
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.
Lock¶
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 wrappedinstance
: 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 functionkwargs
: 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¶
Get matplotlib colour cycle. |
|
Set matplotlib colour cycle. |
|
Get axis width and height in pixels. |
|
Image plot of general data (like imshow but with non-pixel axes). |
|
Generate a raster plot of the provided spike data. |
-
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).
A file-like object for limiting reads to a subrange of a file. |
|
Writes a Nengo cache object. |
|
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.
Network¶
Wraps a method with |
|
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.
Check if |
|
Check if |
|
Check if |
|
Check if |
|
Check if |
|
Check if |
|
Return -1/0/1 if a is less/equal/greater than b. |
|
Return a tuple if |
|
Pad a shape with ones following standard Numpy broadcasting. |
|
Create numpy array with some extra configuration. |
|
Simple fast array hash function. |
|
Get offset of array data from base data in bytes. |
|
Compute the Euclidean norm. |
|
Multidimensional meshgrid. |
|
Compute the root-mean-square amplitude. |
|
Compute the root-mean-square error. |
|
Compute the root-mean-square (RMS) error normalized by the RMS of |
-
nengo.utils.numpy.
as_shape
(x, min_dim=0)[source]¶ Return a tuple if
x
is iterable or(x,)
ifx
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 bydims
ormin_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
, pickn
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.
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. Seenp.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.
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. Seenp.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. Seenp.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. Seenp.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.
Convert timestamp to timedelta. |
|
Stores and tracks information about the progress of some process. |
|
Visualizes the progress of a process. |
|
A progress bar that does not display anything. |
|
A progress bar that is displayed as ASCII output on |
|
A progress bar using a virtual DOM representation. |
|
A progress bar using a HTML representation. |
|
Progress bar using the VDOM or HTML progress bar. |
|
ProgressBar for IPython>=5 environments. |
|
Writes progress to a file. |
|
Suppresses the progress bar unless the ETA exceeds a threshold. |
|
Tracks the progress of some process with a progress bar. |
|
The default progress bar to use depending on the execution environment. |
|
Converts to a |
-
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. Usestep()
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
-
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.
-
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.
-
class
nengo.utils.progress.
TerminalProgressBar
[source]¶ A progress bar that is displayed as ASCII output on
stdout
.
-
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.
-
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.
-
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 HMTL version where VDOM is not supported.
-
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.
-
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.
-
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.
-
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.
-
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 ifprogress_bar
isTrue
, andNoProgressBar
if it isNone
orFalse
.
Simulator¶
Sort operators in a directed graph based on read/write dependencies. |
|
Validate operator reads/writes. |
stdlib¶
Functions that extend the Python Standard Library.
WeakKeyDictionary that allows to define a default. |
|
WeakKeyDictionary that uses object ID to hash. |
|
Uses weak references to store the items in the set. |
|
A set that preserves insertion order and is hashable. |
|
A set that preserves insertion order and is mutable. |
|
Calls |
|
Execute a Python script in the (mandatory) globals namespace. |
|
Group objects based on a key. |
|
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.
-
class
nengo.utils.stdlib.
WeakSet
(items=None)[source]¶ Uses weak references to store the items in the set.
-
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.
-
class
nengo.utils.stdlib.
CheckedCall
(value, invoked)[source]¶ Create new instance of CheckedCall(value, invoked)
-
property
invoked
¶ Alias for field number 1
-
property
value
¶ Alias for field number 0
-
property
-
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 offunc
, 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 asglobals
, 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)
thenobj1
andobj2
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 inobjects
, 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 thegroup
iterator in each(key, group)
pair, to be lists.
- Returns
- keygroupsiterable
An iterable of
(key, group)
pairs, wherekey
is the key used for grouping, andgroup
is an iterable of the items in the group. The nature of the iterables depends on the value offorce_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¶
Ensure all signal elements are within tolerances. |
|
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
andsignals
.- 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 andassert_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.
-
-
class