nengo_spa.vocabulary

Classes

Vocabulary(dimensions[, strict, …])

A collection of semantic pointers, each with their own text label.

VocabularyMap([vocabs, rng])

Maps dimensionalities to corresponding vocabularies.

VocabularyMapParam(name[, default, …])

Nengo parameter that accepts VocabularyMap instances.

VocabularyOrDimParam(name[, default, …])

Nengo parameter that accepts Vocabulary or integer dimensionality.

class nengo_spa.vocabulary.Vocabulary(dimensions, strict=True, max_similarity=0.1, pointer_gen=None, name=None, algebra=None)[source]

A collection of semantic pointers, each with their own text label.

The Vocabulary can also act as a dictionary, with keys as the names of the semantic pointers and values as the SemanticPointer objects themselves. The names of Semantic Pointers must be valid Python 2 identifiers starting with a capital letter.

Every vocabulary knows the special elements AbsorbingElement, Identity, and Zero. However, these are not included in the keys returned by keys or the vectors returned by vectors.

Parameters
  • dimensions (int) – Number of dimensions for each semantic pointer.

  • strict (bool, optional) – Whether to automatically create missing semantic pointers. If a non-strict vocabulary is asked for a pointer that does not exist within the vocabulary, the missing pointer will be automatically added to the vocabulary. A strict vocabulary will throw an error if asked for a pointer that does not exist in the vocabulary.

  • max_similarity (float, optional) – When randomly generating pointers, ensure that the cosine of the angle between the new pointer and all existing pointers is less than this amount. If the system is unable to find such a pointer after 100 tries, a warning message is printed.

  • pointer_gen (generator or np.random.RandomState, optional) – Generator used to create vectors for new Semantic Pointers. Defaults to UnitLengthVectors. If a np.random.RandomState is passed, it will be used by UnitLengthVectors.

  • name (str) – A name to display in the string representation of this vocabulary.

  • algebra (AbstractAlgebra, optional) – Defines the vector symbolic operators used for Semantic Pointers in the vocabulary. Defaults to CircularConvolutionAlgebra.

keys

The names of all known semantic pointers (e.g., ['A', 'B', 'C']).

Type

sequence

max_similarity

When randomly generating pointers, ensure that the cosine of the angle between the new pointer and all existing pointers is less than this amount. If the system is unable to find such a pointer after 100 tries, a warning message is printed.

Type

float

strict

Whether to automatically create missing semantic pointers. If a non-strict vocabulary is asked for a pointer that does not exist within the vocabulary, the missing pointer will be automatically added to the vocabulary. A strict vocabulary will throw an error if asked for a pointer that does not exist in the vocabulary.

Type

bool

vectors

All of the semantic pointer vectors in a matrix, in the same order as in keys.

Type

ndarray

algebra

Defines the vector symbolic operators used for Semantic Pointers in the vocabulary.

Type

AbstractAlgebra, optional

create_pointer(attempts=100, transform=None)[source]

Create a new semantic pointer and add it to the vocabulary.

This will take into account the max_similarity attribute. If a pointer satisfying max_similarity is not generated after the specified number of attempts, the candidate pointer with lowest maximum cosine similarity with all existing pointers is returned.

Parameters
  • attempts (int, optional) – Maximum number of attempts to create a Semantic Pointer not exceeding max_similarity.

  • transform (str, optional) – A transform to apply to the generated vector. Needs to be the name of a method of SemanticPointer. Currently, the only sensible value is ‘unitary’.

Returns

The generated Semantic Pointer.

Return type

SemanticPointer

add(key, p)[source]

Add the semantic pointer p to the vocabulary.

Parameters
  • key (str) – Name of the Semantic Pointer. Must be a valid Python 2 identifier starting with a capital letter. Must not be AbsorbingElement, Identity, or Zero.

  • p (SemanticPointer or array_like) – Semantic Pointer to add.

populate(pointers)[source]

Populate the vocabulary with semantic pointers given an expression.

In its most basic form pointers is a string of names separated with ;:

vocab.populate('A; B; C')

Semantic Pointers can be constructed from other Semantic Pointers:

vocab.populate('A; B; C = 0.3 * A + 1.4 * C')

Those constructed Semantic Pointers are not normalized to unit-length. This can be done by appending a normalized() call. In the same way unitary Semantic Pointers can be obtained with unitary():

vocab.populate('A.unitary(); B; C = (A+B).normalized()')
Parameters

pointers (string) – The expression defining the semantic pointers to add to the vocabulary.

parse(text)[source]

Evaluate a text string and return the corresponding SemanticPointer.

This uses the Python eval() function, so any Python operators that have been defined for SemanticPointers are valid (+, -, *, ~, ()). Valid semantic pointer terms must start with a capital letter.

If the expression returns a scalar (int or float), a scaled version of the identity SemanticPointer will be returned.

parse_n(*texts)[source]

Applies parse to each item in texts and returns the result.

dot(v)[source]

Returns the dot product with all terms in the Vocabulary.

Parameters

v (SemanticPointer or array_like) – SemanticPointer to calculate dot product with.

transform_to(other, populate=None, keys=None, solver=None)[source]

Create a linear transform from one Vocabulary to another.

This is simply the sum of the outer products of the corresponding terms in each Vocabulary if no solver is given, otherwise a least-squares solution will be obtained.

Parameters
  • other (Vocabulary) – The vocabulary to translate into.

  • populate (Boolean) – Whether to add the missing keys from the original vocabulary to the new target vocabulary.

  • keys (list, optional) – Limits the Semantic Pointers considered from the original vocabulary if given.

  • solver (callable) – Solver to obtain least-squares solution to map one vocabulary to the other.

create_subset(keys)[source]

Returns a subset of this vocabulary.

Creates and returns a subset of the current vocabulary that contains all the semantic pointers found in keys.

Parameters

keys (sequence) – List or set of semantic pointer names to be copied over to the new vocabulary.

class nengo_spa.vocabulary.VocabularyMap(vocabs=None, rng=None)[source]

Maps dimensionalities to corresponding vocabularies.

Acts like a Python dictionary.

Parameters
  • vocabs (sequence of Vocabulary) – A list of vocabularies to add to the mapping. The dimensionalities will be determined from the vocabulary objects.

  • rng (numpy.random.RandomState) – Random number generator to use for newly created vocabularies (with get_or_create).

add(vocab)[source]

Add a vocabulary to the map.

The dimensionality will be determined from the vocabulary.

Parameters

vocab (Vocaublary) – Vocabulary to add.

discard(vocab)[source]

Discard (remove) a vocabulary from the mapping.

Parameters

vocab (int or Vocabulary) – If an integer is given, the vocabulary associated to the dimensionality will be discarded. If a Vocabulary is given, that specific instance will be discarded.

get_or_create(dimensions)[source]

Gets or creates a vocabulary of given dimensionality.

If the mapping already maps the given dimensionality to a vocabulary, it will be returned. Otherwise, a new vocabulary will be created, added to the mapping, and returned.

Parameters

dimensions (int) – Dimensionality of vocabulary to return.

Returns

Vocabulary of given dimensionality.

Return type

Vocabulary

class nengo_spa.vocabulary.VocabularyMapParam(name, default=Unconfigurable, optional=False, readonly=None)[source]

Nengo parameter that accepts VocabularyMap instances.

Sequences of Vocabulary will be coerced to VocabularyMap.

class nengo_spa.vocabulary.VocabularyOrDimParam(name, default=Unconfigurable, optional=False, readonly=None)[source]

Nengo parameter that accepts Vocabulary or integer dimensionality.

If an integer is assigned, the vocabulary will retrieved from the instance’s vocabs attribute with vocabs.get_or_create(dimensions). Thus, a class using VocabularyOrDimParam should also have an attribute vocabs of type VocabularyMap.

nengo_spa.vocabulary.iskeyword()

x.__contains__(y) <==> y in x.