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 HrrAlgebra.

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.