RecurrentTransferMechanism¶
Overview¶
A RecurrentTransferMechanism is a subclass of TransferMechanism that implements a singlelayered 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 offdiagonal 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 selfprojecting 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.
Also like a TransferMechanism, the function used to integrate its input before passing it to function
RecurrentTransferMechanism.function
(when integrator_mode
is True
)
can be specified in the integrator_function argument of its constructor.
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.components.mechanisms.processing.transfer.recurrenttransfermechanism.
RECURRENT_OUTPUT
¶ Standard OutputStates for RecurrentTransferMechanism
 RESULT : 1d np.array
 the result of the
function
of the Mechanism
 OUTPUT_MEAN : float
 the mean of the result
 OUTPUT_VARIANCE : float
 the variance of the result
 ENERGY : float
 the energy of the result, which is calculated using the
Stability Function
with theENERGY
metric

class
psyneulink.library.components.mechanisms.processing.transfer.recurrenttransfermechanism.
RecurrentTransferMechanism
( default_variable=None, size=None, function=Linear, matrix=HOLLOW_MATRIX, auto=None, hetero=None, has_recurrent_input_state=False combination_function=LinearCombination, integrator_mode=False, integrator_function=AdaptiveIntegrator, initial_value=None, integration_rate=0.5, noise=0.0, clip=[float:min, float:max], 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 singlelayer autorecurrent 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
orrun
method; also serves as a template to specify the length ofvariable
forfunction
, 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 offdiagonal terms are determined by matrix.
 If hetero and matrix are both specified, the diagonal terms are determined by matrix and the offdiagonal 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 nondiagonal 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.
 setting auto to 1 and hetero to 1 sets matrix to have a diagonal of
1 and all nondiagonal entries 1:
 hetero (number, 2D array, or None : default None) –
specifies matrix as a hollow matrix with all nondiagonal 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 nonzero 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_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 usingLinearCombination
before being passed to the RecurrentTransferMechanism’sfunction
.  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.
 integrator_mode (bool : False) – specifies whether or not the RecurrentTransferMechanism should be executed using its integrator_function to integrate its
variable
( when set toTrue
), or simply report the asymptotic value of the output of itsfunction
(when set toFalse
).  integrator_function (IntegratorFunction : default AdaptiveIntegrator) – specifies
IntegratorFunction
to use inintegration_mode
.  initial_value (value, list or np.ndarray : default Transfer_DEFAULT_BIAS) – specifies the starting value for timeaveraged input if
integrator_mode
isTrue
).  integration_rate (float : default 0.5) –
the rate used for integrating
variable
whenintegrator_mode
is set toTrue
:result = (integration_rate * variable) + (1integration_rate * input to mechanism's function on the previous time step)
 noise (float or function : default 0.0) – a value added to the result of the
function
or to the result ofintegrator_function
, depending on whetherintegrator_mode
isTrue
orFalse
. Seenoise
for additional details.  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 ofclip
that it exceeds.  convergence_function (function : default Distance(metric=MAX_ABS_DIFF)) – specifies the function that calculates
delta
, and determines whenis_converged
isTrue
.  convergence_criterion (float : default 0.01) – specifies the value of
delta
at whichis_converged
isTrue
.  max_passes (int : default 1000) – specifies maximum number of executions (
passes
) that can occur in a trial before reaching theconvergence_criterion
, after which an error occurs; ifNone
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 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 theconvergence_criterion
is satisfied; this is equivalent to a WhenFinished(rec_mech
) Condition in whichrec_mech
is the RecurrentTransferMechanism.
See
learning_condition
for additional details.  UPDATE:
 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; seeprefs
for details.  context (str : default componentType+INITIALIZING) – string used for contextualization of instantiation, hierarchical calls, executions, etc.

function
¶ Function – the Function used to transform the input.

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

recurrent_projection
¶ AutoAssociativeProjection –
 an AutoAssociativeProjection that projects from the Mechanism’s primary OutputState
 to its primary InputState.

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 usingLinearCombination
before being passed to the RecurrentTransferMechanism’sfunction
.

combination_function
¶ function – the Function used to combine the RECURRENT and EXTERNAL InputStates if
has_recurrent_input_state
isTrue
. By default this is aLinearCombination
Function that simply adds them.

initial_value
¶ value, list or np.ndarray : Transfer_DEFAULT_BIAS – determines the starting value for timeaveraged input (only relevant if
integration_rate
parameter is not 1.0).
 integrator_mode :
When integrator_mode is set to True:
the variable of the mechanism is first passed into the following equation:
\[value = previous\_value(1integration\_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 theintegrator_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’sintegrator_function
is skipped entirely, and all related arguments (noise, leak, initial_value, and time_step_size) are ignored. integrator_mode : bool
determines whether the RecurrentTransferMechanism uses its
integrator_function
to integrate itsvariable
when it executes.If integrator_mode is set to
True
:the RecurrentTransferMechanism’s
variable
is first passed to itsintegrator_function
, and then the result is passed to itsfunction
which computes the RecurrentTransferMechanism’svalue
.Note
The RecurrentTransferMechanism’s
integration_rate
,noise
, andinitial_value
parameters specify the respective parameters of itsintegrator_function
(withinitial_value
corresponding toinitializer
andintegration_rate
corresponding torate
ofintegrator_function
). However, if there are any disagreements between these (e.g., any of these parameters is specified in the constructor for anIntegratorFunction
assigned as the integration_function arg of the RecurrentTransferMechanism), the values specified for theintegrator_function
take precedence, and their value(s) are assigned as those of the corresponding parameters on the RecurrentTransferMechanism.If integrator_mode is set to
False
:ifnoise
is nonzero, it is applied to the RecurrentTransferMechanism’s variable which is htne passed directly to itsfunction
– that is, itsintegrator_function
is bypassed, and its related attributes (initial_value
andintegration_rate
) are ignored. integrator_function : IntegratorFunction
 the
IntegratorFunction
used whenintegrator_mode
is set toTrue
(seeintegrator_mode
for details).  integration_rate : float : default 0.5
the rate used for integrating of
variable
whenintegrator_mode
is set toTrue
:result = (integration_rate * current input) + (1integration_rate * result on previous time_step)
 noise : float or function : default 0.0
When
integrator_mode
is set toTrue
, noise is passed into theintegrator_function
. Otherwise, noise is added to the result of thefunction
.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. 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 None
value
after the previous execution of the Mechanism; it is assignedNone
until the 2nd execution, and when the Mechanism’sreinitialize
method is called.Note
The RecurrentTransferMechanism’s
previous_value
attribute is distinct from theprevious_value
attribute of itsintegrator_function
. delta : scalar
 value returned by
convergence_function
; used to determined whenis_converged
isTrue
.  is_converged : bool
True
ifdelta
is less than or equal toconvergence_criterion
. convergence_function : function
 compares
value
withprevious_value
; result is used to determine whenis_converged
isTrue
.  convergence_criterion : float
 determines the value of
delta
at whichis_converged
isTrue
.  max_passes : int or None
 determines maximum number of executions (
passes
) that can occur in a trial before reaching theconvergence_criterion
, after which an error occurs; ifNone
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 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.  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 thelearning_mechanism
(seelearning_rate
for details concerning specification and default value assignment).  learning_function : function : default Hebbian
 the function used by the
learning_mechanism
to train therecurrent_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 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 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 asReinforcement
andBackPropagation
), 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 ofoutput_values
.  output_states : Dict[str: OutputState]
an OrderedDict with the following OutputStates:
TRANSFER_RESULT
, thevalue
of which is the result offunction
;TRANSFER_MEAN
, thevalue
of which is the mean of the result;TRANSFER_VARIANCE
, thevalue
of which is the variance of the result;ENERGY
, thevalue
of which is the energy of the result, calculated using theStability
Function with the ENERGY metric;ENTROPY
, thevalue
of which is the entropy of the result, calculated using theStability
Function with the ENTROPY metric; note: this is only present if the Mechanism’sfunction
is bounded between 0 and 1 (e.g., theLogistic
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).
 result of the
 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 usingclassPreferences
defined in __init__.py (see PreferenceSet for details).
Returns: instance of RecurrentTransferMechanism Return type: RecurrentTransferMechanism 
configure_learning
(learning_function: <typecheck.framework.optional object at 0x10758d320> = None, learning_rate: <typecheck.framework.optional object at 0x10758d3c8> = None, learning_condition: <typecheck.tc_predicates.any object at 0x10758d518> = None, context=None)¶ Provide useraccessibleinterface 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;
 a MappingProjection from the RecurrentTransferMechanism’s primary OutputState to the AutoAssociativeLearningMechanism’s ACTIVATION_INPUT InputState;
 a LearningProjection from the AutoAssociativeLearningMechanism’s LEARNING_SIGNAL OutputState to
the RecurrentTransferMechanism’s
recurrent_projection
.
 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