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

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.

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

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), 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 dict 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 dict.
  • storage_prob (float in interval [0,1] : default 1.0) – specifies probability of adding variable to dict.
  • rate (float, list, or array : default 1.0) – specifies a value used to multiply key (first item of variable) before storing in dict (see `rate <DND.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 dict (see `noise <DND.noise> for details).
  • dict (initializer) – specifies an initial set of entries for dict; each key must have the same shape as the first item of variable and each value must have the same shape as its second item.
  • 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 dict.
  • 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.
  • max_entries (int : default None) – specifies the maximum number of entries allowed in dict (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 dict, and 2nd item (variable[1]) is the value of the entry, paired with key and added to the dict.

key_size

int – length of keys in dict.

retrieval_prob

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

storage_prob

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

rate

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

noise

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

initializer dict

default {} – initial set of entries for dict.

dict

dict – dictionary with current set of entries maintained by DND.

distance_function

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

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 dict prior to storing variable in the current call.

max_entries

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

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 <DND.variable>` – if no retrieval occures, an appropriately shaped zero-valued array is returned.
Return type:2d array
reinitialize(<new_dictionary> default={})

Clears the dict 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 dict in previous_value. Otherwise, the new previous_value dict starts out empty.

value takes on the same value as previous_value.

function(variable=None, execution_id=None, params=None, context=None)

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

If the length of dict 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 dict.
  • 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 <DND.variable>`

Return type:

1d array

get_memory(query_key, execution_id=None)

Retrieve memory from dict 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 dict.
Returns:value and key for item retrieved – if no retrieval occurs, returns appropriately shaped zero-valued array.
Return type:2d array
insert_memories(memories, execution_id=None)

add key-value pairs to dict.

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.