# TransferMechanism¶

## Overview¶

A TransferMechanism transforms its input using a simple mathematical function, that maintains the form (dimensionality) of its input. The input can be a single scalar value, a multidimensional array (list or numpy array), or several independent ones.

The function used to carry out the transformation can be selected from the following PsyNeuLink Functions: Linear, Exponential, Logistic, or SoftMax.

The integrator_mode argument can switch the transformation from an “instantaneous” to a “time averaged” (integrated) manner of execution. When integrator_mode is set to True, the mechanism’s input is first transformed by its integrator_function (the AdaptiveIntegrator). That result is then transformed by the mechanism’s function.

## Creating a TransferMechanism¶

A TransferMechanism is created by calling its constructor.

Its function is specified in the function argument, which can be the name of a Function class:

>>> import psyneulink as pnl
>>> my_linear_transfer_mechanism = pnl.TransferMechanism(function=pnl.Linear)


in which case all of the function’s parameters will be set to their default values. Alternatively, the function argument can be a call to a Function constructor, in which case values may be specified for the Function’s parameters:

>>> my_logistic_transfer_mechanism = pnl.TransferMechanism(function=pnl.Logistic(gain=1.0, bias=-4))


Next, the integrator_mode argument allows the TransferMechanism to operate in either an “instantaneous” or “time averaged” manner. By default, integrator_mode is set to False, meaning execution is instantaneous. In order to switch to time averaging, the integrator_mode argument of the constructor must be set to True.

>>> my_logistic_transfer_mechanism = pnl.TransferMechanism(function=pnl.Logistic(gain=1.0, bias=-4),
...                                                        integrator_mode=True)


When integrator_mode is True, the TransferMechanism uses its integrator_function to integrate its variable on each execution. The output of the integrator_function is then used as the input to function.

By default, the integrator_function of a TransferMechanism is AdaptiveIntegrator. However, any IntegratorFunction can be assigned. A TransferMechanism has three parameters that are used by most IntegratorFunctions: initial_value, integration_rate, and noise. If any of these are specified in the TransferMechanism’s constructor, their value is used to specify the corresponding parameter of its integrator_function. In the following example:

>>> my_logistic_transfer_mechanism = pnl.TransferMechanism(function=pnl.Logistic(gain=1.0, bias=-4),
...                                                        integrator_mode=True,
...                                                        initial_value=np.array([[0.2]]),
...                                                        integration_rate=0.1)


my_logistic_transfer_mechanism will be assigned an AdaptiveIntegrator (the default) as its integrator_function, with 0.2 as its initializer parameter, and 0. as its rate parameter. However, in this example:

>>> my_logistic_transfer_mechanism = pnl.TransferMechanism(function=pnl.Logistic(gain=1.0, bias=-4),
...                                                        integrator_mode=True,
...                                                        initial_value=np.array([[0.2]]),
...                                                        integration_rate=0.1)


the AdaptiveIntegrator’s rate parameter will be assigned 0.3, and this will also be assigned to the TransferMechanism’s integration_rate parameter, overriding the specified value of 0.1.

Note

If integrator_mode is False, then the arguments integration_rate and initial_value are ignored, as its integrator_function is not executed.

When switching between integrator_mode = True and integrator_mode = False, the behavior of the integrator_function is determined by on_resume_integrator_mode. There are three options for how the integrator_function may resume accumulating when the Mechanism returns to integrator_mode = True.

(1) INSTANTANEOUS_MODE_VALUE - reinitialize the Mechanism with its own current value, so that the value computed by

the Mechanism during “Instantaneous Mode” is where the integrator_function begins accumulating.
1. INTEGRATOR_MODE_VALUE - resume accumulation wherever the integrator_function left off the last time integrator_mode was True.

(3) REINITIALIZE - call the integrator_function's reinitialize method

<AdaptiveIntegrator.reinitialize> so that accumulation Mechanism begins at initial_value

Finally, the TransferMechanism has two arguments that can adjust the final result of the mechanism: clip and noise. If integrator_mode is False, clip and noise modify the value returned by the mechanism’s function before setting it as the mechanism’s value. If integrator_mode is True, noise is assigned to the TransferMechanism’s integrator_function (as its noise parameter – in the same manner as integration_rate and initial_value), whereas clip modifies the value returned by the mechanism’s function before setting it as the TransferMechanism’s value.

## Structure¶

### InputStates¶

By default, a TransferMechanism has a single InputState; however, more than one can be specified using the default_variable or size arguments of its constructor (see Mechanisms). The value of each InputState is used as a separate item of the Mechanism’s variable, and transformed independently by its function. Like any InputStates, the value of any or all of the TransferMechanism’s InputStates can be modulated by one or more GatingSignals prior to transformation by its function.

### Function¶

Function. The default function for a TransferMechanism is Linear. A custom function can be specified in the function argument of the constructor. This can be any PsyNeuLink Function that is a subtype of either TransferFunction or NormalizationFunction. It can also be any python function or method, with the constraint that it returns an output that is identical in shape to its input; the function or method is “wrapped” as UserDefinedFunction, and assigned as the TransferMechanism’s function attribute.

The result of the function applied to the value of each InputState is:

### OutputStates¶

By default, a TransferMechanism generates one OutputState for each of its InputStates. The first (and primary) OutputState is named RESULT; subsequent ones use that as the base name, suffixed with an incrementing integer starting at ‘-1’ for each additional OutputState (e.g., RESULT-1, RESULT-2, etc.; see Naming). The value of each OutputState is assigned the result of the Mechanism’s function applied to the value of the corresponding InputState.

Additional OutputStates can be assigned using the TransferMechanism’s Standard OutputStates (see Standard OutputStates) or by creating custom OutputStates (but see note below). Like any OutputStates, the value of any or all of these can be modulated by one or more GatingSignals.

Note

If any OutputStates are specified in the output_states argument of the TransferMechanism’s constructor, then, as with any Mechanism, its default OutputStates are not automatically generated. Therefore, an OutputState with the appropriate index must be explicitly specified for each and every item of the Mechanism’s value (corresponding to each InputState) for which an OutputState is needed.

## Execution¶

When a TransferMechanism is executed, it transforms its input using its function and the following parameters (in addition to any specified for the function):

<TransferMechanism.integrator_mode>
attribute is set to True, the integration_rate attribute is the rate of integration (a higher value specifies a faster rate); if integrator_mode is False, integration_rate is ignored and time-averaging does not occur.

After each execution of the Mechanism the result of function applied to each InputState is assigned as an item of the Mechanism’s value, and the value of each of its OutputStates, and to the 1st item of the Mechanism’s output_values attribute.

### Reinitialization¶

In some cases, it may be useful to reset the accumulation of a mechanism back to its original starting point, or a new starting point. This is done using the reinitialize method on the mechanism’s integrator_function, or the mechanisms’s own reinitialize method.

The reinitialize method of the integrator_function sets:

to the specified value.

The reinitialize method of the TransferMechanism first sets:

to the specified value. Then:

executed - the TransferMechanism’s value attribute is set to the output of the function - the TransferMechanism updates its output_states

A use case for reinitialize is demonstrated in the following example:

Create a System with a TransferMechanism in integrator_mode:

>>> my_time_averaged_transfer_mechanism = pnl.TransferMechanism(function=pnl.Linear,
...                                                        integrator_mode=True,
...                                                        integration_rate=0.1,
...                                                        initial_value=np.array([[0.2]]))
>>> my_process = pnl.Process(pathway=[my_time_averaged_transfer_mechanism])
>>> my_system = pnl.System(processes=[my_process])


Then run the system for 5 trials:

>>> # RUN 1:
>>> my_system.run(inputs={my_time_averaged_transfer_mechanism: [1.0]},
...               num_trials=5)
>>> assert np.allclose(my_time_averaged_transfer_mechanism.value,  0.527608)


After RUN 1, my_time_averaged_transfer_mechanism’s integrator_function will preserve its state (its position along its path of integration).

Run the system again to observe that my_time_averaged_transfer_mechanism’s integrator_function continues accumulating where it left off:

>>> # RUN 2:
>>> my_system.run(inputs={my_time_averaged_transfer_mechanism: [1.0]},
...               num_trials=5)
>>> assert np.allclose(my_time_averaged_transfer_mechanism.value,  0.72105725)


The integrator_function’s reinitialize method and the TransferMechanism’s reinitialize method are useful in cases when the integration should instead start over at the original initial value, or a new one.

Use reinitialize to re-start the integrator_function’s accumulation at 0.2:

>>> my_time_averaged_transfer_mechanism.integrator_function.reinitialize(np.array([[0.2]]))


Run the system again to observe that my_time_averaged_transfer_mechanism’s integrator_function will begin accumulating at 0.2, following the exact same trajectory as in RUN 1:

>>> # RUN 3
>>> my_system.run(inputs={my_time_averaged_transfer_mechanism: [1.0]},
...               num_trials=5)
>>> assert np.allclose(my_time_averaged_transfer_mechanism.value,  0.527608)


Because reinitialize was set to 0.2 (its original initial_value), my_time_averaged_transfer_mechanism’s integrator_function effectively started RUN 3 in the same state as it began RUN 1. As a result, it arrived at the exact same value after 5 trials (with identical inputs).

In the examples above, reinitialize was applied directly to the integrator function. The key difference between the integrator_function's reinitialize and the TransferMechanism's reinitialize is that the latter will also execute the mechanism’s function and update its output states. This is useful if the mechanism’s value or any of its output state values will be used or checked before the mechanism’s next execution. (This may be true if, for example, the mechanism is recurrent, the mechanism is responsible for modulating <ModulatorySignal_Modulation other components, or if a Scheduler condition depends on the mechanism’s activity.)

## Class Reference¶

class psyneulink.core.components.mechanisms.processing.transfermechanism.TRANSFER_OUTPUT
RESULT : 1d np.array
first item of TransferMechanism’s value (corresponding to input from its first InputState)
RESULTS : 2d np.array
each item of TransferMechanism’s value (corresponding to input from each of its input_states) is assigned as the value of a corresponding OutputState of its output_states.
OUTPUT_MEAN : float
mean of value.
OUTPUT_MEDIAN : float
median of value.
OUTPUT_STD_DEV : float
standard deviation of value.
OUTPUT_VARIANCE : float
variance of output_state.value.
MECHANISM_VALUE : list
TransferMechanism’s value used as OutputState’s value.
class psyneulink.core.components.mechanisms.processing.transfermechanism.TransferMechanism( default_variable=None, size=None, input_states=None, function=Linear, integrator_mode=False, integrator_function=AdaptiveIntegrator, on_resume_integrator_mode=INSTANTANEOUS_MODE_VALUE, initial_value=None, integration_rate=0.5, noise=0.0, clip=[float:min, float:max], convergence_function=Distance(metric=DIFFERENCE), convergence_criterion=None, max_passes=None, output_states=RESULTS params=None, name=None, prefs=None)

Subclass of ProcessingMechanism that performs a simple transform of its input.

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 default_variable as array(s) of zeros if default_variable is not passed as an argument; if default_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]])  input_states (str, list, dict, or np.ndarray) – specifies the InputStates for the TransferMechanism; by default, a single InputState is created using the value of default_variable as its variable; if more than one is specified, the number and, if specified, their values must be compatible with any specifications in default_variable or size (see InputStates); see input_states for additional details. function (TransferFunction : default Linear) – specifies the function used to transform the input; can be Linear, Logistic, Exponential, or a custom function. integrator_mode (bool : False) – specifies whether or not the TransferMechanism should be executed using its integrator_function to integrate its variable ( when set to True), or simply report the asymptotic value of the output of its function (when set to False). integrator_function (IntegratorFunction : default AdaptiveIntegrator) – specifies IntegratorFunction to use in integration_mode. initial_value (value, list or np.ndarray : default Transfer_DEFAULT_BIAS) – specifies the starting value for time-averaged input (only relevant if integrator_mode is True). integration_rate (float : default 0.5) – specifies the rate of integration of variable when the TransferMechanism is executed with integrator_mode set to True. on_resume_integrator_mode (keyword : default INSTANTANEOUS_MODE_VALUE) – specifies how the integrator_function should resume its accumulation when the Mechanism was most recently in “Instantaneous Mode” (integrator_mode = False) and has just switched to “IntegratorFunction Mode” (integrator_mode = True). INSTANTANEOUS_MODE_VALUE - reinitialize the Mechanism with its own current value, so that the value computed by the Mechanism during “Instantaneous Mode” is where the integrator_function begins accumulating. INTEGRATOR_MODE_VALUE - resume accumulation wherever the integrator_function left off the last time integrator_mode was True. REINITIALIZE - call the integrator_function's reinitialize method so that accumulation Mechanism begins at initial_value noise (float or function : default 0.0) – specifies a value to be added to the result of the TransferMechanism’s function or its integrator_function, depending on whether integrator_mode is True or False. See noise for 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 of clip that it exceeds. convergence_function (function : default Distance(metric=DIFFERENCE)) – 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. output_states (str, list or np.ndarray : default RESULTS) – specifies the OutputStates for the TransferMechanism; by default, one is created for each InputState specified in input_states; see note, and output_states for additional details). 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 TransferMechanism. prefs (PreferenceSet or specification dict : default Mechanism.classPreferences) – specifies the PreferenceSet for the TransferMechanism; see prefs for details. context (str : default componentType+INITIALIZING) – string used for contextualization of instantiation, hierarchical calls, executions, etc.
variable

value – the input to Mechanism’s function.

input_states

ContentAddressableList[InputState] – list of Mechanism’s InputStates (see InputStates for additional details).

function

Function – the Function used to transform the input.

integrator_mode

bool – determines whether the TransferMechanism uses its integrator_function to integrate its variable when it executes.

If integrator_mode is set to True:

the TransferMechanism’s variable is first passed to its integrator_function, and then the result is passed to the TransferMechanism’s function which computes the TransferMechanism’s value.

Note

The TransferMechanism’s integration_rate, noise, and initial_value parameters specify the respective parameters of its integrator_function (with initial_value corresponding to initializer and integration_rate corresponding to rate of integrator_function). However, if there are any disagreements between these (e.g., any of these parameters is specified in the constructor for an IntegratorFunction assigned as the integration_function arg of the TransferMechanism), the values specified for the integrator_function take precedence, and their value(s) are assigned as those of the corresponding parameters on the TransferMechanism.

If integrator_mode is set to False:

if noise is non-zero, it is applied to the TransferMechanism’s variable which is htne passed directly to its function

– that is, its integrator_function is bypassed, and its related attributes (initial_value and

integration_rate) are ignored.

integrator_function

IntegratorFunction – the IntegratorFunction used when integrator_mode is set to True (see integrator_mode for details).

initial_value

value, list or np.ndarray – specifies the starting value for the integration_function; only relevant if integrator_mode is True and integration_rate is not 1.0 (see integrator_mode for additional details).

integration_rate

float – the rate at which the TransferMechanism’s variable is integrated when it is executed with integrator_mode set to True (see integrator_mode for additional details).

on_resume_integrator_mode

keyword – specifies how the integrator_function should resume its accumulation when the Mechanism was most recently in “Instantaneous Mode” (integrator_mode = False) and has just switched to “IntegratorFunction Mode” (integrator_mode = True). There are three options:

1. INSTANTANEOUS_MODE_VALUE - reinitialize the Mechanism with its own current value, so that the value computed by the Mechanism during “Instantaneous Mode” is where the integrator_function begins accumulating.
2. INTEGRATOR_MODE_VALUE - resume accumulation wherever the integrator_function left off the last time integrator_mode was True.
3. REINITIALIZE - call the integrator_function's reinitialize method so that accumulation Mechanism begins at initial_value
noise

float or function – When integrator_mode is set to True, noise is passed into the integrator_function (see integrator_mode for additional details). Otherwise, noise is added to the output 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 element of variable. In the case that noise is specified as a function, the function will be executed separately for each element of variable.

Note

In order to generate random noise, a probability distribution function should be used (see Distribution Functions for details), that 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] – specifies the allowable range for the result of function. The 1st item (index 0) specifies the minimum allowable value of the result, and the 2nd item (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.

value

2d np.array [array(float64)] – result of executing function.

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 TransferMechanism’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.

output_states

ContentAddressableList[OutputState] – list of Mechanism’s OutputStates; by default there is one OutputState for each InputState, with the base name RESULT (see OutputStates for additional details).

output_values

List[array(float64)] – each item is the value of the corresponding OutputState in output_states. The default is a single item containing the result of the TransferMechanism’s function; additional ones may be included, based on the specifications made in the output_states argument of the Mechanism’s constructor (see TransferMechanism Standard OutputStates).

name

str – the name of the TransferMechanism; 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 TransferMechanism; 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 TransferMechanism TransferMechanism