# 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. updated value of deque 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.DND(default_variable=None, rate=None, noise=0.0, initializer=None, distance_function=Distance(metric=COSINE), selection_function=OneHot(mode=MIN_VAL), duplicate_keys_allowed=False, duplicate_keys_select=RANDOM, max_entries=None, params=None, owner=None, prefs=None)

Implements simple form of Differential Neural Dictionary described in Ritter et al.

Based on implementation in dlstm by Qihong Lu (see also Kaiser et al. and Pritzel et al.).

• Then, with probability storage_prob add new entry using the first item of variable as the key and its second item as the value. If specified, the values of the rate and noise arguments are applied to the key before storing:
$variable[1] * rate + noise$

Note

• Keys in memory are stored as tuples (since lists and arrays are not hashable); they are converted to arrays for evaluation during retrieval.
• All keys must be the same length (for comparision during retrieval).
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 value 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 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 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, and similarly for the values. 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. duplicate_keys_allowed (bool : default False) – specifies whether entries with duplicate keys are allowed in memory (see duplicate_keys_allowed). duplicate_keys_select (RANDOM | OLDEST | NEWEST : default RANDOM) – if duplicate_keys_allowed is True, specifies which entry is retrieved from a set with 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 DND: [[[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 to return.

previous_value

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

duplicate_keys_allowed

bool – determines whether entries with duplicate keys are allowed in memory. If False, then an attempt to store and item with a key that is already in memory is ignored. If True, such items can be stored, and on retrieval using that key, a random entry matching the key is selected.

duplicate_keys_select

RANDOM | OLDEST | NEWEST – if duplicate_keys_allowed is True, deterimines which entry is retrieved from a set with duplicate keys.

max_entries

int – maximum number of entries allowed in memory; if an attempt is made to add an additional entry an error is generated.

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  – if no retrieval occures, an appropriately shaped zero-valued array is returned. 2d array
function(variable=None, execution_id=None, params=None, context=None)

Return value of entry in memory best matched by first item of variable, then add variable to memory.

If the length of memory exceeds max_entries, generate an error.

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. value of entry that best matches first item of variable  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. value and key for item retrieved – if no retrieval occurs, returns appropriately shaped zero-valued array. 2d array as list
insert_memories(memories, execution_id=None)

add key-value pairs to memory.

Parameters: memories (list or array) – a list or array of 2d arrays, each of which must be a valid “memory” consisting of two items, a key and a value, each of which is a list of numbers or 1d array; the keys must all be the same length and equal to the length as key(s) of any existing entries in dict.
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.