Note

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

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)

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 vectors returned by vectors.

Parameters

dimensionsint

Number of dimensions for each semantic pointer.

strictbool, 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_similarityfloat, 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_gengenerator 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.

namestr

A name to display in the string representation of this vocabulary.

algebraAbstractAlgebra, optional

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

Attributes

max_similarityfloat

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.

strictbool

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.

vectorsndarray

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

algebraAbstractAlgebra, optional

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

create_pointer(attempts=100, transform=None)

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

attemptsint, optional

Maximum number of attempts to create a Semantic Pointer not exceeding max_similarity.

transformstr, 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

SemanticPointer

The generated Semantic Pointer.

add(key, p)

Add the semantic pointer p to the vocabulary.

Parameters

keystr

Name of the Semantic Pointer. Must be a valid Python 2 identifier starting with a capital letter. Must not be AbsorbingElement, Identity, or Zero.

pSemanticPointer or array_like

Semantic Pointer to add.

populate(pointers)

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

pointersstring

The expression defining the semantic pointers to add to the vocabulary.

parse(text)

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)

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

dot(v)

Returns the dot product with all terms in the Vocabulary.

Parameters

vSemanticPointer or array_like

SemanticPointer to calculate dot product with.

transform_to(other, populate=None, keys=None, solver=None)

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

otherVocabulary

The vocabulary to translate into.

populateBoolean

Whether to add the missing keys from the original vocabulary to the new target vocabulary.

keyslist, 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)

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

keyssequence

List or set of semantic pointer names to be copied over to the new vocabulary.

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

Maps dimensionalities to corresponding vocabularies.

Acts like a Python dictionary.

Parameters

vocabssequence of Vocabulary

A list of vocabularies to add to the mapping. The dimensionalities will be determined from the vocabulary objects.

rngnumpy.random.RandomState

Random number generator to use for newly created vocabularies (with get_or_create).

add(vocab)

Add a vocabulary to the map.

The dimensionality will be determined from the vocabulary.

Parameters

vocabVocaublary

Vocabulary to add.

discard(vocab)

Discard (remove) a vocabulary from the mapping.

Parameters

vocabint 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)

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

dimensionsint

Dimensionality of vocabulary to return.

Returns

Vocabulary

Vocabulary of given dimensionality.

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

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)

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.