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 a standard set of Functions (such as Linear, Exponential, Logistic, and SoftMax) or specified using a user-defined custom function. The transformation can be carried out instantaneously or in “time averaged” (integrated) manner, as described in Execution.

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 (first example below), or a call to a Function constructor that can include arguments specifying the Function’s parameters (second example):

>>> import psyneulink as pnl
>>> my_linear_transfer_mechanism = pnl.TransferMechanism(function=pnl.Linear)
>>> my_logistic_transfer_mechanism = pnl.TransferMechanism(function=pnl.Logistic(gain=1.0, bias=-4))

In addition to Function-specific parameters, noise and smoothing_factor parameters can be specified for the Mechanism (see Execution).

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 function can be selected from one of four standard PsyNeuLink Functions: Linear, Logistic, Exponential or SoftMax; or a custom function can be specified, so long as it returns a numeric value or a list or numpy array of numeric values. The result of the function applied to the value of each InputState is to an item of an array as the TransferMechanism’s value, and as the value of each of its OutputStates (one corresponding to each InputState).

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

  • noise: applied element-wise to the input before transforming it.
  • clip: caps all elements of the function result by the lower and upper values specified by clip.
  • integrator_mode: determines whether the input will be time-averaged before passing through the function of the mechanisms. When integrator_mode is set to True, the TransferMechanism exponentially time-averages its input before transforming it.

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.

Class Reference

class psyneulink.components.mechanisms.processing.transfermechanism.TRANSFER_OUTPUT

Standard OutputStates for TransferMechanism:

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, smoothing_factor=0.5, integrator_mode=False, clip=(float:min, float:max), 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) – a stochastically-sampled value added to the result of the function: if it is a float, it must be in the interval [0,1] and is used to scale the variance of a zero-mean Gaussian; if it is a function, it must return a scalar value.
  • smoothing_factor (float : default 0.5) –

    the smoothing factor for exponential time averaging of input when the Mechanism is executed with integrator_mode set to True:

    result = (smoothing_factor * current input) + ((1-smoothing_factor) * result on previous time_step)
    
  • clip (Optional[Tuple[float, float]]) – specifies the allowable range for the result of function: the first item specifies the minimum allowable value of the result, and the second its 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.
  • 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.
Returns:

instance of TransferMechanism

Return type:

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 : Transfer_DEFAULT_BIAS – specifies the starting value for time-averaged input (only relevant if integrator_mode is True and smoothing_factor is not 1.0).

noise

float or function – a stochastically-sampled value added to the output of the function: if it is a float, it must be in the interval [0,1] and is used to scale the variance of a zero-mean Gaussian; if it is a function, it must return a scalar value.

smoothing_factor

float : default 0.5 – the smoothing factor for exponential time averaging of input when the Mechanism is executed with integrator_mode set to True:

result = (smoothing_factor * current input) + ( (1-smoothing_factor) * result on previous time_step)
integrator_mode

booleane – when set to True, the Mechanism time averages its input according to an exponentially weighted moving average (see smoothing_factor).

clip

Optional[Tuple[float, float]] – determines the allowable range of the result: the first value specifies the minimum allowable value and the second the maximum allowable value; any element of the result that exceeds minimum or maximum is set to the value of clip it exceeds. If function is Logistic, clip is set by default to (0,1).

value

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

previous_value

float – the value on the previous execution of the Mechanism.

delta

float – the change in value from the previous execution of the Mechanism (i.e., value - previous_value).

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