# 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 has an integrator_function which it applies to its variable on each execution. The output of the integrator_function is then used as the input to its function.

The integrator_function of a TransferMechanism is always the AdaptiveIntegrator. Two parameters of the AdaptiveIntegrator are exposed on the TransferMechanism. Specifying the arguments integration_rate and/or initial_value in the mechanism’s constructor will actually set the mechanism’s integrator_function to an AdaptiveIntegrator with those values specified for rate and initializer, respectively.

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


Note

If integrator_mode is False, then the arguments integration_rate and initial_value are ignored, because the mechanism does not have an integrator_function to construct.

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 simply handed to the mechanism’s integrator_function (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 mechanism’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):

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:

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.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.
MEAN : float
mean of value.
MEDIAN : float
median of value.
STANDARD_DEVIATION : float
standard deviation of value.
VARIANCE : float
variance of output_state.value.
MECHANISM_VALUE : list
TransferMechanism’s value used as OutputState’s value.
class psyneulink.components.mechanisms.processing.transfermechanism.TransferMechanism( default_variable=None, size=None, input_states=None, function=Linear, initial_value=None, noise=0.0, integration_rate=0.5, integrator_mode=False, 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 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. 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). 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. integration_rate (float : default 0.5) – specifies the smoothing factor used for exponential time averaging of input when the TransferMechanism is executed with integrator_mode set to True. integrator_mode (bool : False) – specifies whether or not the TransferMechanism should be executed using its integrator_function to integrate (exponentialy time-average) its variable ( when set to True), or simply report the asymptotic value of the output of its function (when set to False). 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. instance of TransferMechanism TransferMechanism
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.

initial_value

value, list or np.ndarray – specifies the starting value for time-averaged input (only relevant if integrator_mode is True and integration_rate is not 1.0).

noise

float or function – When integrator_mode is set to True, noise is passed into the integrator_function. 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.

integrator_mode

bool – determines whether the TransferMechanism uses its integrator_function to exponentially time average its variable when it executes.

If integrator_mode is set to True:

the TransferMechanism’s variable is first passed into the AdaptiveIntegrator Function, that carries out the following calculation:

$result = previous\_value(1-integration\_rate) + variable \cdot integration\_rate + noise$

where previous_value is set to the value of the TransferMechanism’s initial_value attribute on the first execution, and integration_rate and noise are determined by the TransferMechanism’s integration_rate and noise attributes, respectively. The result is then passed to the TransferMechanism’s function which computes the TransferMechanism’s value.

If integrator_mode is set to False:

the TransferMechanism’s variable is passed directly to its function – that is, its integrator_function is bypassed, and all related attributes (initial_value, integration_rate <TransferMechanism.integration_rate>, and noise) are ignored.
integrator_function

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

Note

The TransferMechanism’s integration_rate parameter specifies the rate of the AdaptiveIntegrator Function.

integration_rate

float – the rate used for exponential time averaging of the TransferMechanism’s variable when it is executed with integrator_mode set to True (see integrator_mode for details).

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).