RecurrentTransferMechanism¶
Contents¶
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, size=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, 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.
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 usingLinearCombination
before being passed to the RecurrentTransferMechanism’sfunction
.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, or np.matrix of numeric values: default False) – specifies the learning rate used by its
learning function
. If it isNone
, the default learning_rate for a LearningMechanism is used; if it is assigned a value, that is used as the learning_rate (seelearning_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 thetermination_threshold
is satisfied; this is equivalent to a WhenFinished(rec_mech
) Condition in whichrec_mech
is the RecurrentTransferMechanism.
See
learning_condition
for additional details.
- matrix¶
the
matrix
parameter of therecurrent_projection
for the Mechanism.- Type
2d np.array
- recurrent_projection¶
an AutoAssociativeProjection that projects from the Mechanism’s primary OutputPort to its primary InputPort.
- 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 usingLinearCombination
before being passed to the RecurrentTransferMechanism’sfunction
.- Type
boolean
- combination_function¶
the Function used to combine the RECURRENT and EXTERNAL InputPorts if
has_recurrent_input_port
isTrue
. By default this is aLinearCombination
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 assignedTrue
, or when it is configured for learning using theconfigure_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 setlearning_enabled
toTrue
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
- learning_rate¶
determines the learning rate used by the
learning_function
of thelearning_mechanism
(seelearning_rate
for details concerning specification and default value assignment).- Type
float, 1d or 2d np.array, or np.matrix of numeric values : default None
- learning_function¶
the function used by the
learning_mechanism
to train therecurrent_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 itsconfigure_learning
method. By default, it executes immediately after the RecurrentTransferMechanism executes.Note
The
learning_mechanism
is an AutoAssociativeLearningMechanism, which executes during theexecution phase
of the System’s execution. Note that this is distinct from the behavior of supervised learning algorithms (such asReinforcement
andBackPropagation
), that are executed during thelearning phase
of a System’s execution- Type
- 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 theStability
Function using theENERGY
metric.
- ENTROPYfloat
the entropy of the elements in the LCAMechanism’s
value
, calculated using theStability
Function using theENTROPY
metric.
- Type
list[str]
- Returns
instance of RecurrentTransferMechanism
- Return type
- _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)
- property _dependent_components¶
Returns a set of Components that will be executed if this Component is executed