RecurrentTransferMechanism¶

Contents¶

Overview

Creating a RecurrentTransferMechanism

Configuring Learning

Structure

Execution

Learning

Class Reference

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). Like a TransferMechanism, it can integrate its input prior to executing its function. It can also 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 AutoAssociativeLearningMechanism 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 OutputPort back to its primary InputPort. This can be parameterized using its matrix, auto, and hetero attributes, and is stored in its recurrent_projection attribute. Using the has_recurrent_input_port attribute, the recurrent_projection can also be made to project to a separate RECURRENT InputPort rather, than the primary one (named EXTERNAL). In this case, the InputPorts’ results will be combined using the combination_function before being passed to the RecurrentTransferMechanism’s function.

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

Finally, if it has been specified for learning, the RecurrentTransferMechanism is associated with an AutoAssociativeLearningMechanism 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 OutputPort on the previous execution, and the matrix of the recurrent_projection.

Like any TransferMechanism, the function used to update each element can be specified in the function argument of its constructor. This transforms its input (including from the recurrent_projection) using the specified function and parameters (see Execution), and returns the results in its OutputPorts. Also like a TransferMechanism, a RecurrentTransferMechanism can be configured to integrate its input, by setting its integration_mode to True (see Execution With Integration), and to do so for a single step of integration or until it reaches some termination condition each time it is executed (see Termination). Finally, it can be reset using its reset method (see TransferMechanism_Execution_Integration_Reinitialization).

Learning¶

If the RecurrentTransferMechanism has been configured for learning and is executed as part of a Composition, then its learning_mechanism is executed when the learning_condition is satisfied. By default, the learning_mechanism executes, and updates the recurrent_projection immediately after the RecurrentTransferMechanism executes.

Class Reference¶

exception psyneulink.library.components.mechanisms.processing.transfer.recurrenttransfermechanism.RecurrentTransferError(message, component=None)¶

class psyneulink.library.components.mechanisms.processing.transfer.recurrenttransfermechanism.RecurrentTransferMechanism(default_variable=None, input_shapes=None, input_ports=None, has_recurrent_input_port=None, combination_function=None, function=None, matrix=None, auto=None, hetero=None, integrator_mode=None, integrator_function=None, initial_value=None, integration_rate=None, noise=None, clip=None, enable_learning=None, learning_rate=None, learning_function=None, learning_condition=None, output_ports=None, params=None, name=None, prefs=None, **kwargs)¶

Subclass of TransferMechanism that implements a single-layer auto-recurrent network. See TransferMechanism for additional arguments and attributes.

Parameters

matrix (list, np.ndarray, 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.
has_recurrent_input_port (boolean : default False) – specifies whether the mechanism’s recurrent_projection points to a separate InputPort. By default, if False, the recurrent_projection points to its primary InputPort. If True, the recurrent_projection points to a separate InputPort, and the values of all input ports 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 InputPorts; 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.
enable_learning (boolean : default False) – specifies whether the Mechanism should be configured for learning method.
learning_rate (scalar, or list, 1d or 2d np.array 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
- CONVERGENCE: learning_mechanism is executed whenever the the termination_threshold is satisfied; this is equivalent to a WhenFinished(rec_mech) Condition in which rec_mech is the RecurrentTransferMechanism.
See learning_condition for additional details.

matrix¶

the matrix parameter of the recurrent_projection for the Mechanism.

Type: 2d np.array

recurrent_projection¶

an AutoAssociativeProjection that projects from the Mechanism’s primary OutputPort to its primary InputPort.

Type: AutoAssociativeProjection

has_recurrent_input_port¶

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

Type: boolean

combination_function¶

the Function used to combine the RECURRENT and EXTERNAL InputPorts if has_recurrent_input_port is True. By default this is a LinearCombination Function that simply adds them.

Type: function

learning_enabled¶

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.

Type: bool

learning_mechanism¶

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

Type: LearningMechanism

learning_rate¶

determines the learning rate used by the learning_function of the learning_mechanism (see learning_rate for details concerning specification and default value assignment).

Type: float, 1d or 2d np.array of numeric values : default None

learning_function¶

the function used by the learning_mechanism to train the recurrent_projection if learning is specified.

Type: function

learning_condition¶

determines the condition under which the learning_mechanism is executed in the context of a Composition; 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 AutoAssociativeLearningMechanism, 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

Type: Condition

standard_output_ports¶

list of Standard OutputPorts that includes the following in addition to the standard_output_ports of a TransferMechanism:

ENERGYfloat: the energy of the elements in the LCAMechanism’s value, calculated using the Stability Function using the ENERGY metric.

ENTROPYfloat: the entropy of the elements in the LCAMechanism’s value, calculated using the Stability Function using the ENTROPY metric.

Type: list[str]

Returns: instance of RecurrentTransferMechanism
Return type: RecurrentTransferMechanism

_validate_params(request_set, target_set=None, context=None)¶: Validate shape and size of auto, hetero, matrix.

_instantiate_attributes_before_function(function=None, context=None)¶: using the matrix argument the user passed in (which is now stored in function_params), instantiate ParameterPorts for auto and hetero if they haven’t already been instantiated. This is useful if auto and hetero were None in the initialization call. :param function:

_instantiate_attributes_after_function(context=None)¶: Instantiate recurrent_projection, matrix, and the functions for the ENERGY and ENTROPY OutputPorts

_instantiate_recurrent_projection(mech, matrix='HollowMatrix', context=None)¶: Instantiate an AutoAssociativeProjection from Mechanism to itself

configure_learning(learning_function=None, learning_rate=None, learning_condition=None, context=None)¶

Provide user-accessible-interface to _instantiate_learning_mechanism

Configure RecurrentTransferMechanism for learning. Creates the following Components:

an AutoAssociativeLearningMechanism – 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;

a MappingProjection from the RecurrentTransferMechanism’s primary OutputPort to the AutoAssociativeLearningMechanism’s ACTIVATION_INPUT InputPort;

a LearningProjection from the AutoAssociativeLearningMechanism’s LEARNING_SIGNAL OutputPort to the RecurrentTransferMechanism’s recurrent_projection.

_execute(variable=None, context=None, runtime_params=None)¶: Execute TransferMechanism function and return transform of input

_parse_function_variable(variable, context=None)¶: Parses the variable passed in to a Component into a function_variable that can be used with the Function associated with this Component

_get_variable_from_input(input, context=None)¶: Return array of results from each InputPort function executed with corresponding input item as its variable This is called when Mechanism is executed on its own (e.g., during init or from the command line). It: - bypasses call to Port._update(), thus ignoring any afferent Projections assigned to the Mechanism; - assigns each item of input to variable of corresponding InputPort; - executes function of each InputPort using corresponding item of input as its variable; - returns array of values generated by execution of each InputPort function.

property _learning_signal_source¶: Return default source of learning signal (Primary OutputPort <OutputPort_Primary>) Subclass can override this to provide another source (e.g., see ContrastiveHebbianMechanism)