MemoryFunctions

Functions that store and can retrieve a record of their current input.

Overview

Functions that store and can return a record of their input.

class psyneulink.core.components.functions.statefulfunctions.memoryfunctions.Buffer(default_variable=None, rate=1.0, noise=0.0, history=None, initializer, params=None, owner=None, prefs=None)

Append variable to the end of previous_value (i.e., right-append to deque of previous inputs).

Note

Every appended item must have same shape as the first.

If specified, rate and/or noise are applied to items already stored in the array, as follows:

\[stored\_item * rate + noise\]

Note

Because rate and noise are applied on every call, their effects accumulative exponentially over calls to function.

If the length of the result exceeds history, delete the first item. Return previous_value appended with variable.

Parameters:
  • default_variable (number, list or array : default class_defaults.variable) – specifies a template for the value to be integrated; if it is a list or array, each element is independently integrated.
  • rate (float, list or 1d array : default 1.0) – specifies a value applied multiplicatively to each item already stored in the deque on each call to function; must be in interval [0,1]
  • noise (float or Function : default 0.0) – specifies a random value added to each item already in the deque on each call to function (see noise for details).
  • history (int : default None) – specifies the maxlen of the deque, and hence value.
  • float, list or ndarray (initializer) – specifies a starting value for the deque; if none is specified, the deque is initialized with an empty list.
  • params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
  • owner (Component) – component to which to assign the Function.
  • name (str : default see name) – specifies the name of the Function.
  • prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the PreferenceSet for the Function (see prefs for details).
variable

number or array – current input value appended to the end of the deque.

rate

float or 1d array with all elements in interval [0,1] – multiplicatively applied to each item already in the deque on call to function; implements exponential decay of stored items.

noise

float or Function – random value added to each item of the deque in each call to function (see noise for additional details).

history

int – determines maxlen of the deque and the value returned by the function. If appending variable to previous_value exceeds history, the first item of previous_value is deleted, and variable is appended to it, so that value maintains a constant length. If history is not specified, the value returned continues to be extended indefinitely.

initializer

float, list or ndarray – value assigned as the first item of the deque when the Function is initialized, or reinitialized if the new_previous_value argument is not specified in the call to reinitialize.

previous_value

1d array : default class_defaults.variable – state of the deque prior to appending variable in the current call.

owner

Componentcomponent to which the Function has been assigned.

name

str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs

PreferenceSet or specification dict : Function.classPreferences – the PreferenceSet for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned using classPreferences defined in __init__.py (see PreferenceSet for details).

function(variable=None, execution_id=None, params=None, context=None)
Parameters:
  • variable (number, list or array : default class_defaults.variable) – a single value or array of values to be integrated.
  • params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns:

updated value of deque

Return type:

deque

reinitialize(*args, execution_context=None)

Clears the previous_value deque.

If an argument is passed into reinitialize or if the initializer attribute contains a value besides [], then that value is used to start the new previous_value deque. Otherwise, the new previous_value deque starts out empty.

value takes on the same value as previous_value.

class psyneulink.core.components.functions.statefulfunctions.memoryfunctions.ContentAddressableMemory(default_variable=None, retrieval_prob=1.0 storage_prob=1.0 rate=None, noise=0.0, initializer=None, distance_function=Distance(metric=COSINE), selection_function=OneHot(mode=MIN_VAL), equidistant_keys_select=RANDOM, duplicate_keys=False, max_entries=None, params=None, owner=None, prefs=None)

Implement a configurable, dictionary-style storage and retrieval of key-value pairs, in which storage is determined by storage_prob, and retrieval of items is determined by distance_function, selection_function, and retrieval_prob. Keys and values may have different lengths, but all keys must be the same length. Duplicate keys can be allowed, disallowed, or overwritten using duplicate_keys), and selection among duplicate keys or ones indistinguishable by the distance_function can be specified using equidistant_keys_select.

The class also provides methods for directly retrieving an entry (get_memory), and adding (add_to_memory) and deleting (delete_from_memory) one or more entries.

An item is stored and retrieved as a 2d array containing a key-value pair ([[key][value]]). A 3d array of such pairs can be assigned to the initialzer argument of the ContentAddressableMemory’s constructor, or in a call to its reinitialize method. The current contents of the memory can be inspected using the memory attribute, which returns a list containing the current entries, each as a 2 item list containing a key-value pair.

When function is executed, it first retrieves the item in memory with the key that most closely matches the key of the item (key-value pair) in the call, stores the latter in memory, and returns the retrieved item (key-value pair). If key of the pair in the call is an exact match of a key in memory and duplicate_keys is False, then the matching item is returned, but the pair in the call is not stored. These steps are described in more detail below:

  • After retrieval, the key-value pair in the call (variable) is stored in
memory with probability storage_prob.
If the key (variable[0]) is identical to one already in memory and duplicate_keys is set to False, storage is skipped; if it is set to OVERWRITE, the value of the key in memory is replaced with the one in the call. If rate and/or noise arguments are specified in the construtor, it is applied to the key before storing, as follows:
\[variable[1] * rate + noise\]

If the number of entries exceeds `max_entries <ContentAddressableMemory.max_entries>, the first (oldest) item in memory is deleted.

Parameters:
  • default_variable (list or 2d array : default class_defaults.variable) – specifies a template for the key and value entries of the dictionary; list must have two entries, each of which is a list or array; first item is used as key, and second as value entry of dictionary.
  • retrieval_prob (float in interval [0,1] : default 1.0) – specifies probability of retrieiving a key from memory.
  • storage_prob (float in interval [0,1] : default 1.0) – specifies probability of adding variable to memory.
  • rate (float, list, or array : default 1.0) – specifies a value used to multiply key (first item of variable) before storing in memory (see `rate <ContentAddressableMemory.noise> for details).
  • noise (float, list, array, or Function : default 0.0) – specifies a random value added to key (first item of variable) before storing in memory (see `noise <ContentAddressableMemory.noise> for details).
  • initializer (3d array or list : default None) – specifies an initial set of entries for memory. It must be of the following form: [[[key],[value]], [[key],[value]], …], such that each item in the outer dimension (axis 0) is a 2d array or list containing a key and a value pair for that entry. All of the keys must 1d arrays or lists of the same length.
  • distance_function (Distance or function : default Distance(metric=COSINE)) – specifies the function used during retrieval to compare the first item in variable with keys in memory.
  • selection_function (OneHot or function : default OneHot(mode=MIN_VAL)) – specifies the function used during retrieval to evaluate the distances returned by distance_function and select the item to return.
  • equidistant_keys_select (RANDOM | OLDEST | NEWEST : default RANDOM) – specifies which item is chosen for retrieval if two or more keys have the same distance from the first item of variable.
  • duplicate_keys (bool | OVERWRITE : default False) – specifies whether entries with duplicate keys are allowed in memory (see duplicate_keys).
  • max_entries (int : default None) – specifies the maximum number of entries allowed in memory (see max_entries).
  • params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
  • owner (Component) – component to which to assign the Function.
  • name (str : default see name) – specifies the name of the Function.
  • prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the PreferenceSet for the Function (see prefs for details).
variable

2d array – 1st item (variable[0] is the key used to retrieve an enrtry from memory, and 2nd item (variable[1]) is the value of the entry, paired with key and added to the memory.

key_size

int – length of keys in memory.

val_size

int – length of values in memory.

retrieval_prob

float in interval [0,1] – probability of retrieiving a value from memory.

storage_prob

float in interval [0,1] – probability of adding variable to memory.

rate

float or 1d array – value applied multiplicatively to key (first item of variable) before storing in memory (see rate for additional details).

noise

float, 1d array or Function – value added to key (first item of variable) before storing in memory (see noise for additional details).

initializer

3d array – initial set of entries for memory; each entry is a 2d array with a key-value pair.

memory

list – list of key-value pairs containing entries in ContentAddressableMemory: [[[key 1], [value 1]], [[key 2], value 2]]…]

distance_function

Distance or function : default Distance(metric=COSINE) – function used during retrieval to compare the first item in variable with keys in memory.

selection_function

OneHot or function : default OneHot(mode=MIN_VAL) – function used during retrieval to evaluate the distances returned by distance_function and select the item(s) to return.

previous_value

1d array – state of the memory prior to storing variable in the current call.

duplicate_keys

bool | OVERWRITE – determines whether entries with duplicate keys are allowed in memory. If True (the default), items with keys that are the same as ones in memory can be stored; on retrieval, a single one is selected based on equidistant_keys_select. If False, then an attempt to store and item with a key that is already in memory is ignored, and the entry already in memory with that key is retrieved. If a duplicate key is identified during retrieval (e.g., duplicate_keys is changed from True to False), a warning is issued and zeros are returned. If OVERWRITE, then retrieval of a cue with an identical key causes the value at that entry to be overwritten with the new value.

equidistant_keys_select

RANDOM | OLDEST | NEWEST – deterimines which entry is retrieved when duplicate keys are identified or are indistinguishable by the distance_function.

max_entries

int – maximum number of entries allowed in memory; if storing a memory exceeds the number, the oldest memory is deleted.

random_state

numpy.RandomState instance

owner

Componentcomponent to which the Function has been assigned.

name

str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs

PreferenceSet or specification dict : Function.classPreferences – the PreferenceSet for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned using classPreferences defined in __init__.py (see PreferenceSet for details).

Returns:value and key of entry that best matches first item of `variable <ContentAddressableMemory.variable>` – if no retrieval occures, an appropriately shaped zero-valued array is returned.
Return type:2d array
add_to_memory(memories: <typecheck.tc_predicates.any object at 0x11284c978>, execution_id=None)

Add one or more key-value pairs into memory

Parameters:memories (list or array) – a single memory (list or 2d array) or list or array of memorys, each of which must be a valid entry consisting of two items (e.g., [[key],[value]] or [[[key1],[value1]],[[key2],[value2]]]. The keys must all be the same length and equal to the length as key(s) of any existing entries in dict. Items are added to memory in the order listed.
delete_from_memory(memories: <typecheck.tc_predicates.any object at 0x11284ca20>, key_only: bool = True, execution_id=None)

Delete one or more key-value pairs from memory

Parameters:
  • memories (list or array) – a single memory (list or 2d array) or list or array of memorys, each of which must be a valid entry consisting of two items (e.g., [[key],[value]] or [[[key1],[value1]],[[key2],[value2]]].
  • key_only (bool : default True) – if True, delete all memories with the same keys as those listed in memories; if False, delete only memories that have the same key and value as those listed in memories.
function(variable=None, execution_id=None, params=None, context=None)

Return entry in memory that key of which best matches first item of variable (query key), then add variable to memory (see above for additional details).

Parameters:
  • variable (list or 2d array : default class_defaults.variable) – first item (variable[0]) is treated as the key for retrieval; second item (variable[1]), paired with key, is added to memory.
  • params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns:

value of entry that best matches first item of `variable <ContentAddressableMemory.variable>`

Return type:

1d array

get_memory(query_key, execution_id=None)

Retrieve memory from memory based on distance_function and selection_function.

Parameters:query_key (list or 1d array) – must be same length as key(s) of any existing entries in memory.
Returns:value and key for item retrieved – if no retrieval occurs, returns appropriately shaped zero-valued array.
Return type:2d array as list
reinitialize(<new_dictionary> default={})

Clears the memory in previous_value.

If an argument is passed into reinitialize or if the initializer attribute contains a value besides [], then that value is used to start the new memory in previous_value. Otherwise, the new previous_value memory starts out empty.

value takes on the same value as previous_value.