Setting parameters with Configs

Building models with the Nengo frontend API involves constructing many objects, each with many parameters that can be set. To make setting all of these parameters easier, Nengo has a config system and pre-set configurations.

The config system

Nengo’s config system is used for two important functions:

1. Setting default parameters with a hierarchy of defaults.

2. Associating new information with Nengo classes and objects without modifying the classes and objects themselves.

A tutorial-style introduction to the config system can be found below:

• The config system
  • Setting default parameters
    • Defaults are filled in immediately
    • Resetting to default
    • Making new configs
  • Advanced: adding new parameters

config system API

Configuration system to set defaults and backend-specific info.

The idea here is that a backend can create a Config and ConfigItems to define the set of parameters that their backend supports. Parameters are done as Python descriptors, so backends can also specify error checking on those parameters.

A good writeup on descriptors (which has an example similar to Parameter) can be found at https://nbviewer.ipython.org/urls/gist.github.com/ChrisBeaumont/5758381/raw/descriptor_writeup.ipynb

nengo.Config	Configures network-level defaults and additional parameters.
nengo.config.ClassParams	A class to store extra parameters and defaults on configured classes.
nengo.config.InstanceParams	A class to store parameter value on configured objects.
nengo.config.SupportDefaultsMixin	Mixin to support assigning Default to parameters.

class nengo.Config(*configures)

Configures network-level defaults and additional parameters.

Every Network contains an associated Config object which can be manipulated to change network-specific defaults, and to store additional parameters (for example, those specific to a backend).

A Config object can configure objects of any class, but it has to be told the classes to configure first. This is either done on instantiation of the Config object or by calling the configures method. This sets up a mapping between configured class and a ClassParams object that sets the default values for that class. Attempting to configure an instance of a configure class will create a mapping from that instance to an InstanceParams object to configure additional parameters for that instance.

Parameters

*configures

The classes that this Config instance will configure.

Examples

To configure defaults on a network:

net = nengo.Network()
net.config[nengo.Ensemble].radius = 1.5
with net:
    ens = nengo.Ensemble(10, 1)
ens.radius == 1.5  # True

To add a new parameter to a Nengo object:

net.config[nengo.Ensemble].set_param(
    'location', nengo.params.Parameter('location')
)
net.config[ens].location = 'cortex'

To group together a set of parameters:

gaba = nengo.Config(nengo.Connection)
gaba[nengo.Connection].synapse = nengo.Lowpass(0.008)
with net, gaba:
    conn = nengo.Connection(ens, ens)
conn.synapse == nengo.Lowpass(0.008)  # True

To configure a new type of object:

class SynapseInfo:
    label = nengo.params.StringParam('label', default=None)
gaba.configures(SynapseInfo)
gaba[SynapseInfo].label = "GABA"  # Set default label

Attributes

paramsdict

Maps configured classes and instances to their ClassParams or InstanceParams object.

static all_defaults(nengo_cls=None)

Look up all of the default values in the current context.

Parameters

nengo_clsclass, optional

If specified, only the defaults for a particular class will be returned. If not specified, the defaults for all configured classes will be returned.

Returns

str

static default(nengo_cls, param)

Look up the current default value for a parameter.

The default is found by going through the config stack, from most specific to least specific. The network that an object is in is the most specific; the top-level network is the least specific. If no default is found there, then the parameter’s default value is returned.

configures(self, \*classes)

Start configuring a particular class and its instances.

class nengo.config.ClassParams(configures)

A class to store extra parameters and defaults on configured classes.

This is used by Config to associate defaults and new Parameter instances with existing objects. It should not be instantiated outside of Config.configures.

Parameters

configuresclass

The class with which to associate new defaults and parameters.

update(self, d)

Sets a number of parameters at once given a dictionary.

class nengo.config.InstanceParams(configures, clsparams)

A class to store parameter value on configured objects.

In contrast to ClassParams, the only thing that can be done with InstanceParams is get and set parameter values. Use the corresponding ClassParams to set defaults and create new parameters.

class nengo.config.SupportDefaultsMixin

Mixin to support assigning Default to parameters.

Implements __setattr__ to do so. If the inheriting class overrides this method, it has to call the mixin’s __setattr__.

This mixin may simplify the exception depending on the value of the simplified rc option.

Preset configs

Nengo includes preset configurations that can be dropped into your model to enable specific neural circuits.

Configuration presets for common use cases.

nengo.presets.ThresholdingEnsembles

Configuration preset for a thresholding ensemble.

nengo.presets.ThresholdingEnsembles(threshold, intercept_width=0.15, radius=1.0)

Configuration preset for a thresholding ensemble.

This preset adjust ensemble parameters for thresholding. The ensemble’s neurons will only fire for values above threshold. One can either decode the represented value (if it is above the threshold) or decode a step function if binary classification is desired.

This preset:

• Sets intercepts to be between threshold and radius with an exponential distribution (shape parameter of intercept_width). This clusters intercepts near the threshold for better approximation.

• Sets encoders to 1.

• Sets evaluation points to be uniformly distributed between threshold and radius.

• Sets the radius.

Parameters

thresholdfloat

Point at which ensembles should start firing.

intercept_widthfloat, optional

Controls how widely distributed the intercepts are. Smaller values give more clustering at the threshold, larger values give a more uniform distribution.

radiusfloat, optional

Ensemble radius.

Returns

nengo.Config

Configuration with presets.

Quirks

• Context matters, membership doesn’t
  • Context details

Parameters

Under the hood, Nengo objects store information using Parameter instances, which are also used by the config system. Most users will not need to know about Parameter objects.

nengo.dists.DistributionParam	A Distribution.
nengo.dists.DistOrArrayParam	Can be a Distribution or samples from a distribution.
nengo.learning_rules.LearningRuleTypeParam
nengo.learning_rules.LearningRuleTypeSizeInParam
nengo.neurons.NeuronTypeParam
nengo.processes.PiecewiseDataParam	Piecewise-specific validation for the data dictionary.
nengo.solvers.SolverParam	A parameter in which the value is a Solver instance.
nengo.synapses.SynapseParam
nengo.transforms.ChannelShapeParam	A parameter where the value must be a shape with channels.
nengo.transforms.SparseInitParam
nengo.params.DefaultType	Placeholder object used to represent default values for a parameter.
nengo.params.is_param	Check if obj is a Parameter.
nengo.params.iter_params	Iterate over the names of all parameters of an object.
nengo.params.equal	Check if two (possibly array-like) objects are equal.
nengo.params.Parameter	Simple descriptor for storing configuration parameters.
nengo.params.ObsoleteParam	A parameter that is no longer supported.
nengo.params.BoolParam	A parameter where the value is a boolean.
nengo.params.NumberParam	A parameter where the value is a number.
nengo.params.IntParam	A parameter where the value is an integer.
nengo.params.StringParam	A parameter where the value is a string.
nengo.params.EnumParam	A parameter where the value must be one of a finite set of strings.
nengo.params.TupleParam	A parameter where the value is a tuple.
nengo.params.ShapeParam	A parameter where the value is a tuple of integers.
nengo.params.DictParam	A parameter where the value is a dictionary.
nengo.params.NdarrayParam	A parameter where the value is a NumPy ndarray.
nengo.params.FunctionInfo
nengo.params.FunctionParam	A parameter where the value is a function.
nengo.params.FrozenObject	An object with parameters that cannot change value after instantiation.

class nengo.params.DefaultType(name)

Placeholder object used to represent default values for a parameter.

nengo.params.is_param(obj)

Check if obj is a Parameter.

nengo.params.iter_params(obj)

Iterate over the names of all parameters of an object.

nengo.params.equal(a, b)

Check if two (possibly array-like) objects are equal.

class nengo.params.Parameter(name, default=Unconfigurable, optional=False, readonly=None)

Simple descriptor for storing configuration parameters.

Parameters

namestr

Name of the parameter.

defaultobject

The value returned if the parameter hasn’t been explicitly set.

optionalbool, optional

Whether this parameter accepts the value None. By default, parameters are not optional (i.e., cannot be set to None).

readonlybool, optional

If true, the parameter can only be set once. By default, parameters can be set multiple times.

Attributes

coerce_defaultsbool

If True, validate values for this parameter when they are set in a Config object. Setting a parameter directly on an object will always be validated.

equatablebool

If True, parameter values can be compared for equality (a==b); otherwise equality checks will just compare object identity (a is b).

hashvalue(self, instance)

Returns a hashable value (hash can be called on the output).

class nengo.params.ObsoleteParam(name, short_msg, since=None, url=None)

A parameter that is no longer supported.

class nengo.params.BoolParam(name, default=Unconfigurable, optional=False, readonly=None)

A parameter where the value is a boolean.

class nengo.params.NumberParam(name, default=Unconfigurable, low=None, high=None, low_open=False, high_open=False, optional=False, readonly=None)

A parameter where the value is a number.

class nengo.params.IntParam(name, default=Unconfigurable, low=None, high=None, low_open=False, high_open=False, optional=False, readonly=None)

A parameter where the value is an integer.

class nengo.params.StringParam(name, default=Unconfigurable, optional=False, readonly=None)

A parameter where the value is a string.

class nengo.params.EnumParam(name, default=Unconfigurable, values=, lower=True, optional=False, readonly=None)

A parameter where the value must be one of a finite set of strings.

class nengo.params.TupleParam(name, default=Unconfigurable, length=None, optional=False, readonly=None)

A parameter where the value is a tuple.

class nengo.params.ShapeParam(name, default=Unconfigurable, length=None, low=0, optional=False, readonly=None)

A parameter where the value is a tuple of integers.

class nengo.params.DictParam(name, default=Unconfigurable, optional=False, readonly=None)

A parameter where the value is a dictionary.

class nengo.params.NdarrayParam(name, default=Unconfigurable, shape=None, dtype=None, optional=False, readonly=None)

A parameter where the value is a NumPy ndarray.

If the passed value is an ndarray, a view onto that array is stored. If the passed value is not an ndarray, it will be cast to an ndarray of dtype and stored.

property coerce_defaults

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

hashvalue(self, instance)

Returns a hashable value (hash can be called on the output).

class nengo.params.FunctionInfo(function, size)

Create new instance of FunctionInfo(function, size)

property function

Alias for field number 0

property size

Alias for field number 1

class nengo.params.FunctionParam(name, default=Unconfigurable, optional=False, readonly=None)

A parameter where the value is a function.

class nengo.params.FrozenObject

An object with parameters that cannot change value after instantiation.

Since such objects are read-only (“frozen”), they can be safely used in multiple locations, compared, etc.