Table of Contents

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.stateful.memoryfunctions.MemoryFunction(default_variable=None, rate=None, noise=None, initializer=None, params=None, owner=None, prefs=None, context=None, **kwargs)
class psyneulink.core.components.functions.stateful.memoryfunctions.Buffer(default_variable=None, rate=None, noise=None, history=None, initializer=None, 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 (initializer) – specifies a starting value for the deque; if none is specified, the deque is initialized with an empty list.

  • ndarray (list or) – 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

current input value appended to the end of the deque.

Type:

number or array

rate

multiplicatively applied to each item already in the deque on call to function; implements exponential decay of stored items.

Type:

float or 1d array with all elements in interval [0,1]

noise

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

Type:

float or Function

history

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.

Type:

int

initializer

value assigned as the first item of the deque when the Function is initialized, or reset if the new_previous_value argument is not specified in the call to reset.

Type:

float, list or ndarray

previous_value

state of the deque prior to appending variable in the current call.

Type:

1d array : default class_defaults.variable

owner

component to which the Function has been assigned.

Type:

Component

name

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

Type:

str

prefs

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 Preferences for details).

Type:

PreferenceSet or specification dict : Function.classPreferences

reset(previous_value=None, context=None)

Clears the previous_value deque.

If an argument is passed into reset 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.stateful.memoryfunctions.DictionaryMemory(default_variable=None, retrieval_prob=None, storage_prob=None, noise=None, rate=None, initializer=None, distance_function=None, selection_function=None, duplicate_keys=None, equidistant_keys_select=None, max_entries=None, seed=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, and values may vary in length from entry to entry, but all keys must be the same length. Duplicate keys can be allowed, disallowed, or overwritten using duplicate_keys), and how selection is made 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.

Structure

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 used to initialize the contents of memory by providing it in the initialzer argument of the DictionaryMemory’s constructor, or in a call to its reset 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.

Execution

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 the 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:

  • First, with probability retrieval_prob, an entry is retrieved from memory that has a key that is closest to the one in the call (first item of variable), as determined by the distance_function and selection_function. The distance_function generates a list of distances of each key in memory from the one in the call; the selection_function then determines which to select ones for consideration. If more than one entry from memory is identified, equidistant_keys_select is used to determine which to retrieve. If no retrieval occurs, an appropriately shaped zero-valued array is assigned as the retrieved memory (and returned by the function.

  • 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 constructor, it is applied to the key before storing, as follows:

\[variable[1] * rate + noise\]

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

type default_variable:

param default_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.

type default_variable:

list or 2d array : default class_defaults.variable

type retrieval_prob:

Union[int, float, None]

param retrieval_prob:

specifies probability of retrieiving a key from memory.

type retrieval_prob:

float in interval [0,1] : default 1.0

type storage_prob:

Union[int, float, None]

param storage_prob:

specifies probability of adding variable to memory.

type storage_prob:

float in interval [0,1] : default 1.0

type rate:

Union[int, float, list, ndarray, None]

param rate:

specifies a value used to multiply key (first item of variable) before storing in memory (see rate for details).

type rate:

float, list, or array : default 1.0

type noise:

Union[int, float, list, ndarray, Callable, None]

param noise:

specifies a random value added to key (first item of variable) before storing in memory (see noise for details).

type noise:

float, list, array, or Function : default 0.0

type initializer:

param initializer:

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 be 1d arrays or lists of the same length.

type initializer:

3d array or list : default None

type distance_function:

Union[Distance, Callable, None]

param distance_function:

specifies the function used during retrieval to compare the first item in variable with keys in memory.

type distance_function:

Distance or function : default Distance(metric=COSINE)

type selection_function:

Union[OneHot, Callable, None]

param selection_function:

specifies the function used during retrieval to evaluate the distances returned by distance_function and select the item to return.

type selection_function:

OneHot or function : default OneHot(mode=ARG_MIN_VAL)

type equidistant_keys_select:

Optional[Literal['random', 'oldest', 'newest']]

param equidistant_keys_select:

specifies which item is chosen for retrieval if two or more keys have the same distance from the first item of variable.

type equidistant_keys_select:

RANDOM | OLDEST | NEWEST : default RANDOM

type duplicate_keys:

Union[bool, Literal['overwrite'], None]

param duplicate_keys:

specifies whether entries with duplicate keys are allowed in memory (see duplicate_keys).

type duplicate_keys:

bool | OVERWRITE : default False

type max_entries:

param max_entries:

specifies the maximum number of entries allowed in memory (see max_entries).

type max_entries:

int : default None

type params:

Union[list, ndarray, None]

param params:

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.

type params:

Dict[param keyword: param value] : default None

type owner:

param owner:

component to which to assign the Function.

type owner:

Component

param name:

specifies the name of the Function.

type name:

str : default see name

type prefs:

Union[None, BasePreferenceSet, dict[Literal['_report_output_pref', '_log_pref', '_delivery_pref', '_param_validation_pref', '_verbose_pref', '_runtime_param_modulation_pref'], Any]]

param prefs:

specifies the PreferenceSet for the Function (see prefs for details).

type prefs:

PreferenceSet or specification dict : default Function.classPreferences

variable

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.

Type:

2d array

key_size

length of keys in memory.

Type:

int

val_size

length of values in memory.

Type:

int

retrieval_prob

probability of retrieving a value from memory.

Type:

float in interval [0,1]

storage_prob

probability of adding variable to memory;

Type:

float in interval [0,1]

rate

value applied multiplicatively to key (first item of variable) before storing in memory (see rate for additional details).

Type:

float or 1d array

noise

value added to key (first item of variable) before storing in memory (see noise for additional details).

Type:

float, 1d array or Function

initializer

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

Type:

3d array

memory

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

Type:

list

distance_function

function used during retrieval to compare the first item in variable with keys in memory.

Type:

Distance or function : default Distance(metric=COSINE)

selection_function

function used during retrieval to evaluate the distances returned by distance_function and select the item(s) to return.

Type:

OneHot or function : default OneHot(mode=ARG_MIN_VAL)

previous_value

state of the memory prior to storing variable in the current call.

Type:

1d array

duplicate_keys

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.

Type:

bool | OVERWRITE

equidistant_keys_select

deterimines which entry is retrieved when duplicate keys are identified or are indistinguishable by the distance_function.

Type:

RANDOM | OLDEST | NEWEST

max_entries

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

Type:

int

random_state

private pseudorandom number generator

Type:

numpy.RandomState

owner

component to which the Function has been assigned.

Type:

Component

name

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

Type:

str

prefs

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 Preferences for details).

Type:

PreferenceSet or specification dict : Function.classPreferences

returns:

value and key of entry that best matches first item of `variable <DictionaryMemory.variable>` – if no retrieval occures, an appropriately shaped zero-valued array is returned.

rtype:

2d array

reset(<new_dictionary> default={})

Clears the memory in previous_value.

If an argument is passed into reset 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.

get_memory(query_key, context=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

add_to_memory(memories, context=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, key_only=True, context=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.

class psyneulink.core.components.functions.stateful.memoryfunctions.ContentAddressableMemory(default_variable=None, retrieval_prob=None, storage_prob=None, rate=None, noise=None, initializer=None, distance_field_weights=None, distance_function=None, selection_function=None, duplicate_entries_allowed=None, duplicate_threshold=None, equidistant_entries_select=None, max_entries=None, seed=None, params=None, owner=None, prefs=None)

Sections

Overview

The ContentAddressableMemory Function implements a configurable, content-addressable storage and retrieval of entries from memory. Storage is determined by storage_prob, retrieval of entries is determined by distance_function, selection_function, and retrieval_prob, with the contribution that each field of the cue makes to retrieval determined by the distance_field_weights parameter.

Entries and Fields. The default_variable argument specifies the shape of an entry in memory, each of which is a list or array of fields that are themselves lists or 1d arrays (see Memory Fields). An entry can have an arbitrary number of fields, and each field can have an arbitrary length. However, all entries must have the same number of fields, and the corresponding fields must all have the same length across entries. Fields can be weighted to determine the influence they have on retrieval, using the distance_field_weights parameter (see retrieval below).

Hint

Entries in memory can be assigned “labels” – i.e., values that are not used in the calculation of distance – by assigning them a weight of 0 or None in distance_field_weights); either can be used for labels that are numeric values; however, if non-numeric values are assigned to a field as labels, then None must be specified for that field in distance_field_weights.

Retrieval. Entries are retrieved from memory based on their distance from variable, used as the cue for retrieval. The distance is computed using the distance_function, which compares variable with each entry in memory. If memories have more than one field, then the distances are computed in one of two ways: i) as full vectors (i.e., with all fields of each concatenated into a single array) if distance_field_weights is a single scalar value or a list of identical values); or field-by-field, if distance_field_weights is a list of non-identical values, by computing the distance of each field in variable with the corresponding ones of each entry in memory, and then averaging those distances weighted by the coefficients specified in distance_field_weights. The distances computed between variable ` and each entry in memory are then used by selection_function to determine which entry is retrieved (or how to weight the sum of them based on their distances from the cue – see selection_type). The distance used for the last retrieval (i.e., between variable and the entry retrieved), the distances of each of their corresponding fields (weighted by distance_field_weights), and the distances to all other entries are stored in distance and distances_by_field, and distances_to_entries respectively.

Duplicate Entries. These can be allowed, disallowed, or overwritten during storage using duplicate_entries_allowed), and how selection is made among duplicate entries or ones indistinguishable by the distance_function can be specified using equidistant_entries_select.

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

Structure

An entry is stored and retrieved as an array containing a set of fields each of which is a 1d array. An array containing such entries can be used to initialize the contents of memory by providing it in the initializer argument of the ContentAddressableMemory’s constructor, or in a call to its reset method. The current contents of memory can be inspected using the memory attribute, which returns a list containing the current entries, each as a list containing all fields for that entry. The memory_num_fields contains the number of fields expected for each entry, memory_field_shapes their shapes, and memory_num_entries the total number of entries in memory.

Both memory and all entries are stored as np.ndarrays, the dimensionality of which is determined by the shape of the fields of an entry. If all fields have the same length (regular), then they are 2d arrays and memory is a 3d array. However, if fields vary in length (ragged) then, although each field is 1d, an entry is also 1d (with dtype=’object’), and memory is 2d (with dtype=’object’).

Execution

When the ContentAddressableMemory function is executed, it first retrieves the entry in memory that most closely matches variable in the call, stores the latter in memory, and returns the retrieved entry. If variable is an exact match of an entry in memory, and duplicate_entries_allowed is False, then the matching item is returned, but variable is not stored. These steps are described in more detail below.

  • Retrieval: first, with probability retrieval_prob, a retrieval is made from memory. This is either the entry closest to variable, or weighted sum of the entries in memory based on their distances to variable, as determined by selection_function and selection_type. The retrieval is made by calling, in order:

    • distance_function: generates a list of and compares distances between variable and each entry in memory, possibly weighted by distance_field_weights, as follows:

      • if distance_field_weights is either a scalar or an array of scalars that are all the same, then it is used simply to scale the distance computed between variable and each entry in memory, each of which is computed by concatenating all items of variable into a 1d array, similarly concatenating all memory_fields of an entry in memory, and then using distance_function to compute the distance betwen them.

      • if distance_field_weights is an array of non-identical scalars , then variable is compared with each entry in memory by using distance_function to compute the distance of each item in variable with the corresponding field of the entry in memory, and then averaging those distances weighted by the corresponding element of distance_field_weights.

        Note

        Fields assigned a weight of 0 or None are ignored in the distance calculation; that is, the distances between variable and entries for those fields are not included in the averaging of distances by field. If all of the distance_field_weights are 0 or None, then no memory is retrieved (this is equivalent to setting retrieval_prob to 0).

    • selection_function: called with the list of distances to determine how to generate a retrieval based on the distance of each entry in memory from variable. The type of retrieval is determined by the selection_type of the function (an attribute determined from the function on Construction of the ContentAddressableMemory function): if it is SINGLE, then the entry with the minimum distance is retrieved; if it is WEIGHTED, then the entries are weighted by their distance from variable and the weighted sum of the entries is retrieved. If selection_type is SINGLE and two or more entries have the lowest and equal distance from variable, the equidistant_entries_select attribued is used to determine which to retrieve. If no retrieval occurs, an appropriately shaped zero-valued array is assigned as the retrieved memory, and returned by the function.

    The distance between variable and the retrieved entry is assigned to distance `, the distance between of each of their fields is assigned to distances_by_field, and the distances of variable to all entries in memory is assigned to distances_to_entries.

  • Storage: after retrieval, an attempt is made to store variable in memory memory with probability storage_prob; if the attempt is made:

    • if variable is identical to an entry already in memory, as evaluated by distance_function and duplicate_threshold, then duplicate_entries_allowed determines whether or not to store the entry;

      if duplicate_entries_allowed is:

      • False – storage is skipped;

      • True – variable is stored as another duplicate;

      • OVERWRITE – the duplicate entry in memory is replaced with

      variable (which may be slightly different than the item it replaces, within the tolerance of duplicate_threshold), and the matching entry is returned;

      Note

      If duplicate_entries_allowed is OVERWRITE but a duplicate entry is nevertheless identified during retrieval (e.g., duplicate_entries_allowed was previously changed from True to False), a warning is issued, and duplicate entry is overwritten with variable.

    • if storage rate and/or noise arguments are specified in the constructor, they are applied to variable before storage as \(variable * rate + noise\);

    • finally, if the number of entries in memory exceeds max_entries, the first (oldest) entry is deleted. The current number of entries in memory is contained in the memory_num_entries attribute.

Examples

Initialize memory with **default_variable

The format for entries in memory <ContentAddressableMemory.memory can be specified using either the default_variable or initializer arguments of the Function’s constructor. default_variable specifies the shape of entries, without creating any entries:

>>> c = ContentAddressableMemory(default_variable=[[0,0],[0,0,0]])
>>> c([[1,2]])
array([[0, 0]])

Since memory was not intialized, the first call to the Function returns an array of zeros, formatted as specified in defaul_variable. However, the input in the call to the Function ([[1,2]]) is stored as an entry in memory:

>>> c.memory
array([[[1., 2.]]])

and is returned on the next call:

>>> c([[2,5]])
array([[1., 2.]])

Note that even though default_variable and the inputs to the Function are specified as lists, the entries returned are arrays; memory and all of its entries are always formated as arrays.

Initialize memory with **initializer

The initializer argument of a ContentAddressableMemory’s constructor can be used to initialize its memory:

>>> c = ContentAddressableMemory(initializer=[[[1,2],[3,4,5]],
...                                            [[10,9],[8,7,6]]])
>>> c([[1,2],[3,4,6]])
array([array([1., 2.]), array([3., 4., 5.])], dtype=object)
>>> c([[1,2],[3,4,6]])
array([array([1., 2.]), array([3., 4., 6.])], dtype=object)

Note that there was no need to use default_variable, and in fact it would overidden if specified.

Weighting fields

The distance_field_weights argument can be used to differentially weight memory fields to modify their influence on retrieval (see distance_field_weights). For example, this can be used to configure the Function as a dictionary, using the first field for keys (on which retrieval is based) and the second for values (that are retrieved with a matching key), as follows:

>>> c = ContentAddressableMemory(initializer=[[[1,2],[3,4]],
...                                            [[1,5],[10,11]]],
...                              distance_field_weights=[1,0])
>>> c([[1,2.5],[10,11]])
array([[1., 2.],
       [3., 4.]])

Note that the first entry [[1,2],[3,4]] in memory was retrieved, even though the cue used in the call ([[1,2.5],[10,11]]) was an exact match to the second field of the second entry ([[1,5],[10,11]]). However, since that field was assigned 0 in distance_field_weights, it was ignored and, using only the first entry, the cue was closer to the first entry. This is confirmed by repeating the example without specifying distance_field_weights:

>>> c = ContentAddressableMemory(initializer=[[[1,2],[3,4]],
...                                            [[1,5],[10,11]]])
>>> c([[1,2.5],[10,11]])
array([[ 1.,  5.],
       [10., 11.]])

Duplicate entries

By default, duplicate entries are precluded from a ContentAddressableMemory’s memory. So, for an initializer with identical entries, only one copy of the duplicates will be stored:

>>> c = ContentAddressableMemory(initializer=[[[1,2],[3,4]],
...                                           [[1,2],[3,4]]])
>>> c.memory
array([[[1., 2.],
        [3., 4.]]])

and using the same array as input to the function will retrieve that array but not store another copy:

>>> c([[1,2],[3,4]])
array([[1., 2.],
       [3., 4.]])
>>> c.memory
array([[[1., 2.],
        [3., 4.]]])

Only fields with non-zero weights in distance_field_weights are considered when evaluating whether entries are duplicates. So, in the following example, where the weight for the second field is 0, the two entries are considered duplicates and only the first is stored:

>>> c = ContentAddressableMemory(initializer=[[[1,2],[3,4]],
...                                           [[1,2],[5,6]]],
...                              distance_field_weights=[1,0])
>>> c.memory
array([[[1., 2.],
        [3., 4.]]])

Duplicates can be allowed by setting the duplicate_entries_allowed argument to True or OVERWRITE. Setting it to True allows duplicate entries to accumulate in memory, as shown here:

>>> c = ContentAddressableMemory(initializer=[[[1,2],[3,4]],
...                                            [[1,5],[10,11]]],
...                              duplicate_entries_allowed=True)
>>> c([[1,2],[3,4]])
array([[1., 2.],
       [3., 4.]])
>>> c.memory
array([[[ 1.,  2.],
        [ 3.,  4.]],

       [[ 1.,  5.],
        [10., 11.]],

       [[ 1.,  2.],
        [ 3.,  4.]]])

Duplicates are determined by comparing entries using the functions distance_function; if the distance is less than duplicate_threshold, they are considered to be duplicates; otherwise they are treated a distinct entries. By default, duplicate_threshold is 0. In the folloiwng example it is increased, so that two very similar, but non-identical entries, are nonetheless treated as duplicates:

>>> c = ContentAddressableMemory(initializer=[[[1, 2.0], [3, 4]],
...                                           [[1, 2.5], [3, 4]]],
...                              duplicate_entries_allowed=False,
...                              duplicate_threshold=0.2)

>>> c.memory
array([[[1., 2.],
        [3., 4.]]])

Setting duplicate_entries_allowed argument to OVERWRITE allows an entry to replace one that is considered duplicate, even if it is not identical, as in the following example:

>>> c.duplicate_entries_allowed=OVERWRITE
>>> c([[1, 2.1], [3, 4]])
array([[1., 2.],
       [3., 4.]])
>>> c.memory
array([[[1. , 2.1],
        [3. , 4. ]]])

Note that the entry considered to be the duplicate ([[1, 2.1], [3, 4]]) is returned, and then replaced in memory. Finally, if duplicate_entries_allowed is True, and duplicates have accumulated, the equidistant_entries_select attribute can be used to specify how to select among them for retrieval, either by chosing randomly (RANDOM) or selecting either the first one (OLDEST) or last one (NEWEST) stored.

Class Reference

Parameters:

  • default_variable (list or 2d array : default class_defaults.variable) – specifies a template for an entry in the dictionary; the list or array can have any number of items, each of which must be a list or array of any length; however, at present entries are constrained to be at most 2d.

  • retrieval_prob (float in interval [0,1] : default 1.0) – specifies probability of retrieving an entry 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 variable before storing in memory (see rate for details).

  • noise (float, list, 2d array, or Function : default 0.0) – specifies random value(s) added to variable before storing in memory; if a list or 2d array, it must be the same shape as variable ContentAddressableMemory.variable> (see noise for details).

  • initializer (3d array or list : default None) – specifies an initial set of entries for memory (see initializer for additional details).

  • distance_field_weights (1d array : default None) – specifies the weight to use in computing the distance between each item of variable and the corresponding memory_field of each item in memory (see distance_field_weights for additional details).

  • distance_function (Distance or function : default Distance(metric=COSINE)) – specifies the function used during retrieval to compare variable with entries 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 retrieve.

  • duplicate_entries_allowed (bool : default False) – specifies whether duplicate entries are allowed in memory (see duplicate entries for additional details).

  • duplicate_threshold (float : default 0) – specifies how similar variable must be to an entry in memory based on distance_function to be considered a duplicate (see duplicate entries for additional details).

  • equidistant_entries_select (RANDOM | OLDEST | NEWEST : default RANDOM) – specifies which entry in memory is chosen for retrieval if two or more have the same distance from variable.

  • max_entries (int : default None) – specifies the maximum number of entries allowed in memory (see max_entries for additional details).

  • 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

used to retrieve an entry from memory, and then stored there.

Type:

2d array

retrieval_prob

probability of retrieiving a value from memory.

Type:

float in interval [0,1]

storage_prob

probability of adding variable to memory.

Note

storage_prob does not apply to initializer, the entries of which are added to memory irrespective of storage_prob.

Type:

float in interval [0,1]

rate

value applied multiplicatively to variable) before storing in`memory <ContentAddressableMemory.memory>` (see rate for additional details).

Type:

float or 1d array

noise

value added to variable) before storing in memory (see noise for additional details). If a 2d array (or Function that returns one), its shape must be the same as variable; that is, each array in the outer dimension (axis 0) must have the same length as the corresponding one in variable, so that it can be added Hadamard style to variable before storing it in memory.

Type:

float, 2d array or Function

initializer

initial set of entries for memory. It should be either a 3d regular array or a 2d ragged array (if the fields of an entry have different lengths), but it can be specified in the initializer argument of the constructor using some simpler forms for convenience. Specifically, scalars, 1d and regular 2d arrays are allowed, which are interpreted as a single entry that is converted to a 3d array to initialize memory.

Type:

ndarray

memory

list of entries in ContentAddressableMemory, each of which is an array of fields containing stored items; the fields of an entry must be lists or arrays, each of which can be different shapes, but the corresponding fields of all entries must have the same shape; for example, the following could be a pair of entries in memory:

entry 1

entry 2

field1

field2

field3

field1

field2

field3

[[ [a],

[b,c,d],

[[e],[f]] ],

[ [u],

[v,w,x],

[[y],[z]] ]]
Type:

list

distance_field_weights

determines the weight used in computing the distance between each item of variable and the corresponding memory_field of each entry in memory; if all elements are identical, it is treated as a scalar coefficient on distance (see ContentAddressableMemory_Distance_Field_Weights for additional details).

Type:

1d array : default None

distance_function

function used during retrieval to compare variable with entries in memory.

Type:

Distance or function : default Distance(metric=COSINE)

distance

contains distance used for retrieval last cue to last entry returned in a given context.

Type:

float : default 0

distances_by_field

contains array of distances between each memory field of the last cue and the corresponding ones of the last entry returned in a given context.

Type:

array : default [0]

distances_to_entries

contains array of distances between last cue retrieved in a given context an all entries at that time.

Type:

array : default [0]

memory_num_entries

contains the number of entries in memory.

Type:

int

memory_num_fields

contains the number of memory fields in each entry of memory.

Type:

int

memory_field_shapes

contains the shapes of each memory field in each entry of memory.

Type:

array

selection_function

function used during retrieval to evaluate the distances returned by distance_function and select the item(s) to return.

Type:

OneHot or function

selection_type

indicates whether selection_function returns a single item (e.g., the default: OneHot using MIN_INDICATOR for its mode attribute) or a weighted sum over the items in memory (e.g., using SoftMax with ALL, its default, as its output along each field, weighted by the corresponding element of distance_field_weights.

This attribute is assigned by evaluating the selection_function in the ContentAddressableMemory’s _instantiate_attributes_before_function method

Type:

SINGLE | WEIGHTED

duplicate_entries_allowed

determines whether duplicate entries are allowed in memory, as evaluated by distance_function and duplicate_threshold. (see duplicate entries for additional details).

Type:

bool | OVERWRITE

duplicate_threshold

determines how similar variable must be to an entry in memory ` based on distance_function to be considered a duplicate (see duplicate entries for additional details).

Type:

float

equidistant_entries_select

determines which entry is retrieved when duplicate entries are identified or are indistinguishable by the distance_function.

Type:

RANDOM | OLDEST | NEWEST

max_entries

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

Type:

int

previous_value

state of the memory prior to storing variable in the current call.

Type:

ndarray

random_state

private pseudorandom number generator

Type:

numpy.RandomState

owner

component to which the Function has been assigned.

Type:

Component

name

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

Type:

str

prefs

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 Preferences for details).

Type:

PreferenceSet or specification dict : Function.classPreferences

Returns:

entry from `memory <ContentAddressableMemory.memory>` that best matches `variable <ContentAddressableMemory.variable>` – if no retrieval occurs, an appropriately shaped zero-valued array is returned.

Return type:

2d array

_update_default_variable(new_default_variable, context=None)

Override method on parent (StatefulFunction) since it can’t handle arbitrarily-shaped fields

reset(<new_dictionary> default={})

Clears the memory in previous_value.

If new_value is passed into reset 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 as None.

value takes on the same value as previous_value.

get_memory(cue, field_weights=None, context=None)

Retrieve entry from memory based on distance_function and selection_function.

Parameters:

cue (list or 2d array) – must have same number and shapes of fields as existing entries in memory.

Returns:

entry retrieved – if no retrieval occurs, returns appropriately shaped zero-valued array.

Return type:

2d array

add_to_memory(entries, context=None)

Add one or more entries into memory

Parameters:

entries (list or array) – a single entry (list or array) or list or array of entries, each of which must be a valid entry; each must have the same number of and shapes of corresponding fields; items are added to memory in the order listed.

delete_from_memory(entries, fields=None, context=None)

Delete one or more entries from memory

Parameters:

  • memories (list or array) – a single entry (list or 2d array) or list or array of entries, each of which must be a valid entry (i.e. same number of fields and shapes of each as entries already in memory.

  • fields (int or list : default None) – if None, delete all entries in memory that are identical to any of the memories specified; if int or list, delete all entries with the same values as those in the field(s) specified.

store(entry, context=None, **kwargs)

Store value in memory. Convenience method for storing entry in memory.

retrieve(entry, context=None, **kwargs)

Retrieve value from memory. Convenience method for retrieving entry from memory.

property memory

Return entries in self._memory as lists in an outer np.array; use np.array for multi-line printout

property memory_num_entries

Return number of entries in self._memory.