nengo-spa 1.1.0

An implementation of the Semantic Pointer Architecture for Nengo

Implementation of the Semantic Pointer Architecture for Nengo

The Semantic Pointer Architecture provides an approach to building cognitive models implemented with large-scale spiking neural networks.

Feature highlights

• Write arbitrarily complex expressions with type checking involving neurally represented and static Semantic Pointers like dot((role * filler + BiasVector) * tag, cmp) >> target. Nengo SPA will take care of implementing the required neural networks.

• Quickly implement action selection systems based on a biological plausible model of the basal ganglia and thalamus.

• Neural representations are optimized for representing Semantic Pointers.

• Support for using different binding methods with algebras. Nengo SPA ships with implementations of circular convolution (default) and vector-derived transformation binding (VTB), which is particularly suitable for deep structures. Different binding operations/algebras can be mixed in a single model.

• Seamless integration with non-SPA Nengo models.

Project status

• All of the core functionality is implemented and the API is stable.

• While basic integration with the Nengo GUI works, it should be improved in the future. However, this will not be pursued until major improvements to Nengo GUI are released.

Installation

Nengo SPA depends on Nengo 2.7+, and we recommend that you install Nengo before installing Nengo SPA.

To install Nengo SPA:

pip install nengo-spa

Nengo SPA is tested to work on Python 3.5+.

If you need support for Python 2.7 or 3.4, Nengo SPA 0.6.2 is the last version with support for these earlier Python versions.

Documentation

The documentation can be found here.

Getting Help

Questions relating to Nengo and Nengo SPA, whether it’s use or it’s development, should be asked on the Nengo forum at https://forum.nengo.ai.

Release History

1.1.0 (June 23, 2020)

Added

• Support division with constant scalars. (#249, #253, #257)

Changed

• Make AbstractAlgebra an actual abstract base class (using ABCMeta as meta-class). While still supported, this deprecates pure duck-typing for algebras. (#240)

• Raise an exception when a Semantic Pointer is added to a vocabulary with a differing algebra. (#239, #240)

• All examples now have seeds to ensure that occasional “bad seeds” do not create problems in the documentation. (#248)

Fixed

• SemanticPointer.translate and PointerSymbol.translate now use the keys argument; previously, this argument was mistakenly ignored. (#248)

• Fixed an issue where the names of iteratively generated semantic pointers could grow exponentially in length, by truncating them at 1 KB. (#244, #246)

• Allow NumPy scalars in place of Python scalars for binary operations on SemanticPointer instances. (#250, #257)

• The SPA sequence example was not working properly due to a missing connection. (#258, #259)

1.0.1 (December 14, 2019)

Changed

• Add redirects from old URLs to documentation. (#237, #238)

1.0.0 (December 12, 2019)

Changed

• Ensure compatibility with Nengo 3. (#225, #233, #236)

• Modules and networks no longer set a default label. This will give more useful labels by default in Nengo GUI (assuming the latest dev version). (#234, #235)

• All networks have been converted to classes. This will give more useful labels by default in Nengo GUI (assuming the latest dev version). (#234, #235)

Removed

• Dropped support for Python 2.7 and 3.4. (#233, #236)

0.6.2 (June 21, 2019)

Added

• Add previously missing documentation on the vector_generation module as well as the reinterpret and translate methods of SemanticPointer. (#228, #229)

Fixed

• Fixed a bug where an exception within an ActionSelection block would lead to every subsequent ActionSelection block to raise an exception. (#230, #231)

• Nengo SPA is now compatible with pytest 4. Support for earlier versions has been dropped. (#227)

0.6.1 (April 26, 2019)

Changed

• Minor documentation improvements. (#217, #218)

0.6.0 (September 17, 2018)

Added

• Support for algebras that allow to use binding operations other than circular convolution. This includes an implementation of vector-derived transformation binding (VTB) and the nengo_spa.networks.VTB network to perform this particular binding operation. (#69, #198)

• Added generators for vectors with different properties that can be used to define how vectors are created in a vocabulary (e.g., axis-aligned, orthogonal, unitary). (#201, #129)

• Added a matrix multiplication network nengo_spa.networks.MatrixMult based on the nengo-extras implementation. (#198)

• Allow to connect to the utility node returned by ifmax with the SPA >> operator. (#190, #194)

• The Semantic Pointer names AbsorbingElement, Identity, and Zero now have a special meaning in Vocabulary and nengo_spa.sym and will return the respective special Semantic Pointers. (#195, #176)

• SemanticPointer instance can now track names for improved labeling in Nengo GUI. (#202, #184)

• Label the utility nodes for the action selection. (#202)

Changed

• A number of module names have been changed for better naming consistency. In particular,

  • nengo_spa.actions to nengo_spa.action_selection,

  • nengo_spa.pointer to nengo_spa.semantic_pointer,

  • nengo_spa.vocab to nengo_spa.vocabulary,

  • and nengo_spa.modules.assoc_mem to nengo_spa.modules.associative_memory.

  (#199, #205)

• Require the mapping argument for associative memories. In addition to dictionaries and the string 'by-key', a sequence of strings can be passed in to create an auto-associative memory. (#177)

• Changed the rng argument for Vocabulary to pointer_gen. (#201)

• Renamed input_a and input_b of the nengo_spa.Bind module to input_left and input_right to account for non-commutative binding methods where the order of operands matters. Also, renamed the invert_a and invert_b arguments to unbind_left and unbind_right to reflect that some binding methods might not have inverse vectors, but might still be able to do unbinding. (#69, #198)

• Renamed the nengo_spa.State parameter represent_identity to represent_cc_identity to reflect that it only optimizes for the circular convolution identity, but not the identity for other binding operations. (#212)

Removed

• Removed nengo_spa.networks.circularconvolution.circconv because nengo_spa.algebras.CircularConvolutionAlgebra provides the same functionality. (#198)

• The SemanticPointer class does no longer accept a single integer as dimensionality to create a random vector. Use the new generators in nengo_spa.vector_generation instead. (#201)

Fixed

• Raise an exception instead of returning incorrect results from prob_cleanup. Also, fix the function’s incorrect documentation. (#203, #206)

• Fix nengo_spa.ActionSelection.keys() when no named actions have been provided. (#210)

• Do not create an unnecessary compare network when computing a dot product with a SemanticPointer instance. (#202)

• Handle SemanticPointer instances correctly as first argument to nengo_spa.dot. (#202)

0.5.2 (July 6, 2018)

Fixed

• SPA modules will use the same default vocabularies even if not instantiated in the context of a spa.Network. (#174, #185)

• Disallow Python keywords, including None, True, and False, as well as unicode characters from Python names. (#188, #187)

• Allow action rules without name to have no effects. (#189, #191)

• Raise exception when using NumPy arrays in SPA operations which would give unexpected results. (#192, #193)

0.5.1 (June 7, 2018)

Added

• Transcode now supports SemanticPointer and PointerSymbol output types. (#175, #178)

Fixed

• Allow integer values for vocabularies in associative memories. (#171)

• Implement reinterpret operator for pointer symbols. (#169, #179)

0.5.0 (June 1, 2018)

Added

• One-dimensional outputs of Nengo objects can be used as scalars in action rules. (#139, #157)

• Syntactic sugar for complex symbolic expressions: nengo_spa.sym('A + B * C'). (#138, #159)

• Include the achieved similarity in warning issued when desired maximum similarity could not be obtained. (#117, #158)

• Possibility to name Vocabulary instances for debugging. (#163, #165)

Changed

• Make the error message for incompatible types more informative. (#131, #160

0.4.1 (May 18, 2018)

This release fixes problems with the online documentation. Local installs are not affected.

0.4.0 (May 17, 2018)

This release increases the minimum required Nengo version to Nengo 2.7 (previously Nengo 2.4).

Added

• Added documentation and build tools for the documentation. (#68)

Changed

• This release introduces a new syntax for SPA action rules. (#114)

Remove

• Unnecessary vocab argument from Transcode. (#68)

Fixed

• Validation of VocabOrDimParam and VocabularyMapParam. (#95, #98)

• Allow the configuration of instance parameters with nengo_spa.Network.config. (#112, #113)

• Fix an undeclared input to the IAAssocMem module. (#118, #120)

0.3.2 (November 17, 2017)

Added

• Add all_bgs and all_thals methods to AstAccessor to enable easy access to these objects. (#61, #28)

Fixed

• Allow the spa.Actions string to be empty. (#107, #109)

• The pass keyword can now be used to create blocks in action rules that do not have any effect. (#101, #103)

• Allow comments at various places in actions rules. (#102, #104)

0.3.1 (November 7, 2017)

Changed

• Clearer error message as a SpaTypeError something is used as input/output in an action rule without being declared as such. (#82, #89)

Fixed

• Allow leading comments in actions rules. (#81, #85)

• Gave the basal ganglia a default label. (#84, #88)

• Fixed warning produce by the create_inhibit_node function. (#90)

• Prevent whitespace from being completely removed in action rules. (#92, #93)

• Have the intercept_width argument of IA actually take effect. (#94, #97)

0.3.0 (October 16, 2017)

Added

• Add add_output and add_neuron_output methods to IdentityEnsembleArray to provide the full API that is provided by the regular Nengo EnsembleArray. (#61, #28)

• Add create_inhibit_node function to create nodes that inhibit complete Nengo networks. (#65, #26)

• Add a solver argument to the action rule’s translate to use a solver instead of an outer product to obtain the transformation matrix which can give slightly better results. (#62, #57)

Changed

• Actions rules do not require module to be assigned to the model any longer. They will access exactly the same variables as are available in the surrounding Python code. This means that existing action rules need to be changed to reference the correct names. (#63)

• The action rule syntax changed significantly. (#54, #72)

• Actions will be build automatically without an explicit call to build(). (#59, #45, #55)

• Consolidated the functionality of Encode and Decode into Transcode. (#67, #58)

Fixed

• Fix some operations changing the dimensionality of semantic pointers with an odd initial dimensionality. (#52, #53)

• When building actions the basal ganglia and thalamus will only be created when actually required. (#60, #42)

• The vocabulary translate mechanism will properly ignore missing keys in the target vocabulary when populate=False. (#62, #56)

• Allow empty string as argument to Vocabulary.populate. (#73)

0.2 (June 22, 2017)

Added

• Tutorial explaining what has changed in nengo_spa compared to the legacy SPA implementation. (#46)

• Examples can be extracted with python -m nengo_spa extract-examples <destination>. (#49, #7)

Changed

• Replaced input_keys and output_keys arguments of associative memories with a single mapping argument. (#29, #8)

• Replaced ampa_config and gaba_config parameters of the BasalGanglia with ampa_synapse and gaba_synapse parameters. Removed the general_config parameter. (#30, #23)

Fixed

• Improved a number of error messages. (#35, #32, #34)

• Improved accuracy by fixing choice of evaluation point and intercept distributions. (#39)

• Correctly apply transforms on first vector in vocabularies on on non-strict vocabularies. (#43)

0.1.1 (May 19, 2017)

Fixed

• Updated the 0.1 changelog.

0.1 (May 19, 2017)

Initial release of Nengo SPA with core functionality, but excluding

• updates and completion the documentation,

• proper integration with Nengo GUI.

The API is still conisdered unstable in some parts of it are likely to change in the future.

Main features compared to the SPA implementation shipped with Nengo are:

• neural representations have been optimized for higher accuracy,

• support for arbitrarily complex action rules,

• SPA networks can be used as normal Nengo networks,

• and SPA networks can be nested.