RecurrentTransferMechanism

Overview

A RecurrentTransferMechanism is a subclass of TransferMechanism that implements a single-layered recurrent network, in which each element is connected to every other element (instantiated in a recurrent AutoAssociativeProjection referenced by the Mechanism’s matrix parameter). It can report the energy and, if appropriate, the entropy of its output, and can be configured to implement autoassociative (e.g., Hebbian) learning.

Creating a RecurrentTransferMechanism

A RecurrentTransferMechanism is created directly by calling its constructor, for example:

import psyneulink as pnl
my_linear_recurrent_transfer_mechanism = pnl.RecurrentTransferMechanism(function=pnl.Linear)
my_logistic_recurrent_transfer_mechanism = pnl.RecurrentTransferMechanism(function=pnl.Logistic(gain=1.0,
                                                                                                bias=-4.0))

The recurrent projection is automatically created using (1) the matrix argument or (2) the auto and hetero arguments of the Mechanism’s constructor, and is assigned to the mechanism’s recurrent_projection attribute.

If the matrix argument is used to create the recurrent_projection, it must specify either a square matrix or an AutoAssociativeProjection that uses one (the default is HOLLOW_MATRIX).:

recurrent_mech_1 = pnl.RecurrentTransferMechanism(default_variable=[[0.0, 0.0, 0.0]],
                                                  matrix=[[1.0, 2.0, 2.0],
                                                          [2.0, 1.0, 2.0],
                                                          [2.0, 2.0, 1.0]])

recurrent_mech_2 = pnl.RecurrentTransferMechanism(default_variable=[[0.0, 0.0, 0.0]],
                                                  matrix=pnl.AutoAssociativeProjection)

If the auto and hetero arguments are used to create the recurrent_projection, they set the diagonal and off-diagonal terms, respectively.:

recurrent_mech_3 = pnl.RecurrentTransferMechanism(default_variable=[[0.0, 0.0, 0.0]],
                                                  auto=1.0,
                                                  hetero=2.0)

Note

In the examples above, recurrent_mech_1 and recurrent_mech_3 are identical.

In all other respects, a RecurrentTransferMechanism is specified in the same way as a standard TransferMechanism.

Configuring Learning

A RecurrentTransferMechanism can be configured for learning when it is created by assigning True to the enable_learning argument of its constructor. This creates an AutoAssociativeMechanism that is used to train its recurrent_projection, and assigns as its function the one specified in the learning_function argument of the RecurrentTransferMechanism’s constructor. By default, this is the Hebbian Function; however, it can be replaced by any other function that is suitable for autoassociative learning; that is, one that takes a list or 1d array of numeric values (an “activity vector”) and returns a 2d array or square matrix (the “weight change matrix”) with the same dimensions as the length of the activity vector. The AutoAssociativeLearningMechanism is assigned to the learning_mechanism attribute and is used to modify the matrix parameter of its recurrent_projection (also referenced by the RecurrentTransferMechanism’s own matrix parameter.

If a RecurrentTransferMechanism is created without configuring learning (i.e., enable_learning is assigned False in its constructor – the default value), then learning cannot be enabled for the Mechanism until it has been configured for learning; any attempt to do so will issue a warning and then be ignored. Learning can be configured once the Mechanism has been created by calling its configure_learning method, which also enables learning.

Structure

The distinguishing feature of a RecurrentTransferMechanism is its recurrent_projection attribute: a self-projecting AutoAssociativeProjection. By default, recurrent_projection projects from the Mechanism’s primary OutputState back to its primary InputState. This can be parameterized using its matrix, auto, and hetero attributes, and is stored in its recurrent_projection attribute. Using the has_recurrent_input_state attribute, the recurrent_projection can also be made to project to a separate RECURRENT InputState rather, than the primary one (named EXTERNAL). In this case, the InputStates’ results will be combined using the combination_function before being passed to the RecurrentTransferMechanism’s function.

A RecurrentTransferMechanism also has two additional OutputStates: an ENERGY OutputState and, if its function is bounded between 0 and 1 (e.g., a Logistic function), an ENTROPY OutputState. Each of these report the respective values of the vector in it its RESULTS (primary) OutputState.

Finally, if it has been specified for learning, the RecurrentTransferMechanism is associated with an AutoAssociativeMechanism that is used to train its AutoAssociativeProjection. The learning_enabled attribute indicates whether learning is enabled or disabled for the Mechanism. If learning was not configured when the Mechanism was created, then it cannot be enabled until the Mechanism is configured for learning.

In all other respects the Mechanism is identical to a standard TransferMechanism.

Execution

When a RecurrentTransferMechanism executes, its variable, as is the case with all mechanisms, is determined by the projections the mechanism receives. This means that a RecurrentTransferMechanism’s variable is determined in part by the value of its own primary OutputState on the previous execution, and the matrix of the recurrent_projection.

Like a TransferMechanism, the function used to update each element can be specified in the function argument of its constructor. It then transforms its input (including from the recurrent_projection) using the specified function and parameters (see Execution), and returns the results in its OutputStates.

If a convergence_criterion is specified, then on each execution the convergence_function is evaluated, and execution in the current trial continues until the result returned is less than or equal to the convergence_criterion or the number of executions reaches max_passes (if it is specified).

If it has been configured for learning and is executed as part of a System, then its learning_mechanism is executed when the learning_condition is satisfied, during the execution phase of the System’s execution. Note that this is distinct from the behavior of supervised learning algorithms (such as Reinforcement and BackPropagation), that are executed during the learning phase of a System’s execution. By default, the learning_mechanism executes, and updates the recurrent_projection immediately after the RecurrentTransferMechanism executes.

Class Reference

class psyneulink.library.mechanisms.processing.transfer.recurrenttransfermechanism.RECURRENT_OUTPUT

Standard OutputStates for RecurrentTransferMechanism

RESULT : 1d np.array
the result of the function of the Mechanism
MEAN : float
the mean of the result
VARIANCE : float
the variance of the result
ENERGY : float
the energy of the result, which is calculated using the Stability Function with the ENERGY metric
ENTROPY : float
The entropy of the result, which is calculated using the Stability Function with the ENTROPY metric (Note: this is only present if the Mechanism’s function is bounded between 0 and 1 (e.g. the Logistic Function)).
class psyneulink.library.mechanisms.processing.transfer.recurrenttransfermechanism.RecurrentTransferMechanism( default_variable=None, size=None, function=Linear, matrix=HOLLOW_MATRIX, auto=None, hetero=None, initial_value=None, noise=0.0, integrator_mode=False, integration_rate=0.5, clip=[float:min, float:max], has_recurrent_input_state=False combination_function=LinearCombination, convergence_function=Distance(metric=MAX_ABS_DIFF), convergence_criterion=None, max_passes=None, enable_learning=False, learning_rate=None, learning_function=Hebbian, learning_condition=UPDATE, params=None, name=None, prefs=None)

Subclass of TransferMechanism that implements a single-layer auto-recurrent network.

Parameters:
  • default_variable (number, list or np.ndarray : default Transfer_DEFAULT_BIAS) – specifies the input to the Mechanism to use if none is provided in a call to its execute or run method; also serves as a template to specify the length of variable for function, and the primary OutputState of the Mechanism.
  • size (int, list or np.ndarray of ints) –

    specifies variable as array(s) of zeros if variable is not passed as an argument; if variable is specified, it takes precedence over the specification of size. As an example, the following mechanisms are equivalent:

    T1 = TransferMechanism(size = [3, 2])
    T2 = TransferMechanism(default_variable = [[0, 0, 0], [0, 0]])
    
  • function (TransferFunction : default Linear) – specifies the function used to transform the input; can be Linear, Logistic, Exponential, or a custom function.
  • matrix (list, np.ndarray, np.matrix, matrix keyword, or AutoAssociativeProjection : default HOLLOW_MATRIX) –

    specifies the matrix to use for creating a recurrent AutoAssociativeProjection, or an AutoAssociativeProjection to use.

    • If auto and matrix are both specified, the diagonal terms are determined by auto and the off-diagonal terms are determined by matrix.
    • If hetero and matrix are both specified, the diagonal terms are determined by matrix and the off-diagonal terms are determined by hetero.
    • If auto, hetero, and matrix are all specified, matrix is ignored in favor of auto and hetero.
  • auto (number, 1D array, or None : default None) –

    specifies matrix as a diagonal matrix with diagonal entries equal to auto, if auto is not None; If auto and hetero are both specified, then matrix is the sum of the two matrices from auto and hetero.

    In the following examples, assume that the default variable of the mechanism is length 4:

    • setting auto to 1 and hetero to -1 sets matrix to have a diagonal of 1 and all non-diagonal entries -1:
      \[\begin{split}\begin{bmatrix} 1 & -1 & -1 & -1 \\ -1 & 1 & -1 & -1 \\ -1 & -1 & 1 & -1 \\ -1 & -1 & -1 & 1 \\ \end{bmatrix}\end{split}\]
    • setting auto to [1, 1, 2, 2] and hetero to -1 sets matrix to:
      \[\begin{split}\begin{bmatrix} 1 & -1 & -1 & -1 \\ -1 & 1 & -1 & -1 \\ -1 & -1 & 2 & -1 \\ -1 & -1 & -1 & 2 \\ \end{bmatrix}\end{split}\]
    • setting auto to [1, 1, 2, 2] and hetero to [[3, 3, 3, 3], [3, 3, 3, 3], [4, 4, 4, 4], [4, 4, 4, 4]] sets matrix to:
      \[\begin{split}\begin{bmatrix} 1 & 3 & 3 & 3 \\ 3 & 1 & 3 & 3 \\ 4 & 4 & 2 & 4 \\ 4 & 4 & 4 & 2 \\ \end{bmatrix}\end{split}\]

    See matrix for details on how auto and hetero may overwrite matrix.

    Can be modified by control.

  • hetero (number, 2D array, or None : default None) –

    specifies matrix as a hollow matrix with all non-diagonal entries equal to hetero, if hetero is not None; If auto and hetero are both specified, then matrix is the sum of the two matrices from auto and hetero.

    When diagonal entries of hetero are specified with non-zero values, these entries are set to zero before hetero is used to produce a matrix.

    See hetero (above) for details on how various auto and hetero specifications are summed to produce a matrix.

    See matrix (above) for details on how auto and hetero may overwrite matrix.

    Can be modified by control.

  • initial_value (value, list or np.ndarray : default Transfer_DEFAULT_BIAS) – specifies the starting value for time-averaged input if integrator_mode is True).
  • noise (float or function : default 0.0) – a value added to the result of the function or to the result of integrator_function, depending on whether integrator_mode is True or False. See noise for additional details.
  • integration_rate (float : default 0.5) –

    the rate used for exponential time averaging of input when integrator_mode is set to True:

    result = (integration_rate * variable) +
    (1-integration_rate * input to mechanism's function on the previous time step)
    
  • clip (list [float, float] : default None (Optional)) – specifies the allowable range for the result of function the item in index 0 specifies the minimum allowable value of the result, and the item in index 1 specifies the maximum allowable value; any element of the result that exceeds the specified minimum or maximum value is set to the value of clip that it exceeds.
  • convergence_function (function : default Distance(metric=MAX_ABS_DIFF)) – specifies the function that calculates delta, and determines when is_converged is True.
  • convergence_criterion (float : default 0.01) – specifies the value of delta at which is_converged is True.
  • max_passes (int : default 1000) – specifies maximum number of executions (passes) that can occur in a trial before reaching the convergence_criterion, after which an error occurs; if None is specified, execution may continue indefinitely or until an interpreter exception is generated.
  • enable_learning (boolean : default False) – specifies whether the Mechanism should be configured for learning; if it is not (the default), then learning cannot be enabled until it is configured for learning by calling the Mechanism’s configure_learning method.
  • learning_rate (scalar, or list, 1d or 2d np.array, or np.matrix of numeric values: default False) – specifies the learning rate used by its learning function. If it is None, the default learning_rate for a LearningMechanism is used; if it is assigned a value, that is used as the learning_rate (see learning_rate for details).
  • learning_function (function : default Hebbian) – specifies the function for the LearningMechanism if learning has been specified for the RecurrentTransferMechanism. It can be any function so long as it takes a list or 1d array of numeric values as its variable and returns a sqaure matrix of numeric values with the same dimensions as the length of the input.
  • learning_condition (Condition, UPDATE, CONVERGENCE : default UPDATE) –

    specifies the Condition assigned to learning_mechanism; A Condition can be used, or one of the following two keywords:

    • UPDATE: learning_mechanism is executed immediately after every execution of the RecurrentTransferMechanism; this is equivalent to assigning no Condition

    See learning_condition for additional details.

  • has_recurrent_input_state (boolean : default False) – specifies whether the mechanism’s recurrent_projection points to a separate input state. By default, if False, the recurrent_projection points to its primary InputState. If True, the recurrent_projection points to a separate input state, and the values of all input states are combined using LinearCombination before being passed to the RecurrentTransferMechanism’s function.
  • combination_function (function : default LinearCombination) – specifies function used to combine the RECURRENT and INTERNAL InputStates; must accept a 2d array with one or two items of the same length, and generate a result that is the same size as each of these; default simply adds the two items.
  • params (Dict[param keyword: param value] : default None) – a parameter dictionary that can be used to specify the parameters for the Mechanism, its function, and/or a custom function and its parameters. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
  • name (str : default see name) – specifies the name of the RecurrentTransferMechanism.
  • prefs (PreferenceSet or specification dict : default Mechanism.classPreferences) – specifies the PreferenceSet for the RecurrentTransferMechanism; see prefs for details.
  • context (str : default componentType+INITIALIZING) – string used for contextualization of instantiation, hierarchical calls, executions, etc.
variable

2d np.array with one item in axis 0. – the input to Mechanism’s function.

combination_function

function – the Function used to combine the RECURRENT and EXTERNAL InputStates if has_recurrent_input_state is True. By default this is a LinearCombination Function that simply adds them.

function

Function – the Function used to transform the input.

matrix

2d np.array – the matrix parameter of the recurrent_projection for the Mechanism.

recurrent_projection

AutoAssociativeProjection

an AutoAssociativeProjection that projects from the Mechanism’s primary OutputState
to its primary InputState.
initial_value

value, list or np.ndarray : Transfer_DEFAULT_BIAS – determines the starting value for time-averaged input (only relevant if integration_rate parameter is not 1.0).

integrator_function

When integrator_mode is set to True, the RecurrentTransferMechanism executes its integrator_function, which is the AdaptiveIntegrator. See AdaptiveIntegrator for more details on what it computes. Keep in mind that the integration_rate parameter of the RecurrentTransferMechanism corresponds to the rate parameter of the RecurrentTransferMechanism’s integrator_function.

integrator_mode

When integrator_mode is set to True:

the variable of the mechanism is first passed into the following equation:

\[value = previous\_value(1-integration\_rate) + variable \cdot integration\_rate + noise\]

The result of the integrator function above is then passed into the mechanism’s function. Note that on the first execution, initial_value determines the integrator_function's previous_value.

When integrator_mode is set to False:

The variable of the mechanism is passed into the function of the mechanism. The Mechanism’s integrator_function is skipped entirely, and all related arguments (noise, leak, initial_value, and time_step_size) are ignored.

noise

float or function : default 0.0 – When integrator_mode is set to True, noise is passed into the integrator_function. Otherwise, noise is added to the result of the function.

If noise is a list or array, it must be the same length as variable.

If noise is specified as a single float or function, while variable is a list or array, noise will be applied to each variable element. In the case of a noise function, this means that the function will be executed separately for each variable element.

Note

In order to generate random noise, we recommend selecting a probability distribution function (see Distribution Functions for details), which will generate a new noise value from its distribution on each execution. If noise is specified as a float or as a function with a fixed output, then the noise will simply be an offset that remains the same across all executions.

integration_rate

float : default 0.5 – the rate used for exponential time averaging of input when integrator_mode is set to True:

result = (integration_rate * current input) + (1-integration_rate * result on previous time_step)
clip

list [float, float] : default None (Optional) – specifies the allowable range for the result of function

the item in index 0 specifies the minimum allowable value of the result, and the item in index 1 specifies the maximum allowable value; any element of the result that exceeds the specified minimum or maximum value is set to the value of clip that it exceeds.

previous_value

2d np.array [array(float64)] : default Nonevalue after the previous execution of the Mechanism. It is assigned None on the first execution, and when the Mechanism’s reinitialize method is called.

Note

The RecurrentTransferMechanism’s previous_value attribute is distinct from the previous_value attribute of its integrator_function.

delta

scalar – value returned by convergence_function; used to determined when is_converged is True.

is_converged

boolTrue if delta is less than or equal to convergence_criterion.

convergence_function

function – compares value with previous_value; result is used to determine when is_converged is True.

convergence_criterion

float – determines the value of delta at which is_converged is True.

max_passes

int or None – determines maximum number of executions (passes) that can occur in a trial before reaching the convergence_criterion, after which an error occurs; if None is specified, execution may continue indefinitely or until an interpreter exception is generated.

learning_enabled

bool : default False – indicates whether learning has been enabled for the RecurrentTransferMechanism. It is set to True if learning is specified at the time of construction (i.e., if the enable_learning argument of the Mechanism’s constructor is assigned True, or when it is configured for learning using the configure_learning method. Once learning has been configured, learning_enabled can be toggled at any time to enable or disable learning; however, if the Mechanism has not been configured for learning, an attempt to set learning_enabled to True elicits a warning and is then ignored.

learning_mechanism

LearningMechanism – created automatically if learning is specified, and used to train the recurrent_projection.

learning_rate

float, 1d or 2d np.array, or np.matrix of numeric values : default None – determines the learning rate used by the learning_function of the learning_mechanism (see learning_rate for details concerning specification and default value assignment).

learning_function

function : default Hebbian – the function used by the learning_mechanism to train the recurrent_projection if learning is specified.

learning_condition

Condition : default None – determines the condition under which the learning_mechanism is executed in the context of a Compositions; it can be specified in the learning_condition argument of the Mechanism’s constructor or of its configure_learning method. By default, it executes immediately after the RecurrentTransferMechanism executes.

Note

The learning_mechanism is an AutoAssociativeMechanism, which executes during the execution phase of the System’s execution. Note that this is distinct from the behavior of supervised learning algorithms (such as Reinforcement and BackPropagation), that are executed during the learning phase of a System’s execution

value

2d np.array [array(float64)] – result of executing function; same value as first item of output_values.

previous_value

2d np.array [array(float64)] : default Nonevalue after the previous execution of the Mechanism; it is assigned None until the 2nd execution, and when the Mechanism’s reinitialize method is called.

output_states

Dict[str: OutputState] – an OrderedDict with the following OutputStates:

  • TRANSFER_RESULT, the value of which is the result of function;
  • TRANSFER_MEAN, the value of which is the mean of the result;
  • TRANSFER_VARIANCE, the value of which is the variance of the result;
  • ENERGY, the value of which is the energy of the result, calculated using the Stability Function with the ENERGY metric;
  • ENTROPY, the value of which is the entropy of the result, calculated using the Stability Function with the ENTROPY metric; note: this is only present if the Mechanism’s function is bounded between 0 and 1 (e.g., the Logistic function).
output_values

List[array(float64), float, float] – a list with the following items:

  • result of the function calculation (value of TRANSFER_RESULT OutputState);
  • mean of the result (value of TRANSFER_MEAN OutputState)
  • variance of the result (value of TRANSFER_VARIANCE OutputState);
  • energy of the result (value of ENERGY OutputState);
  • entropy of the result (if the ENTROPY OutputState is present).
has_recurrent_input_state

boolean – specifies whether the mechanism’s recurrent_projection points to a separate input state. If False, the recurrent_projection points to its primary InputState. If True, the recurrent_projection points to a separate input state, and the values of all input states are combined using LinearCombination before being passed to the RecurrentTransferMechanism’s function.

name

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

prefs

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

Returns:instance of RecurrentTransferMechanism
Return type:RecurrentTransferMechanism
configure_learning(learning_function: <typecheck.framework.optional object at 0x104ef9748> = None, learning_rate: <typecheck.framework.optional object at 0x104ef9860> = None, learning_condition: <typecheck.tc_predicates.any object at 0x104ef99b0> = None, context=None)

Provide user-accessible-interface to _instantiate_learning_mechanism

Configure RecurrentTransferMechanism for learning. Creates the following Components:

  • an AutoAssociativeMechanism – if the learning_function and/or learning_rate arguments are specified, they are used to construct the LearningMechanism, otherwise the values specified in the RecurrentTransferMechanism’s constructor are used;