# TransferMechanism¶

## Overview¶

A TransferMechanism is a subclass of ProcessingMechanism that adds the ability to integrate its input.

Like a ProcessingMechanism, it 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.

Its 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 ( 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.

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¶

### InputPorts¶

By default, a TransferMechanism has a single InputPort; however, more than one can be specified using the default_variable or size arguments of its constructor (see Mechanism). The value of each InputPort is used as a separate item of the Mechanism’s variable, and transformed independently by its function. Like any InputPorts, the value of any or all of the TransferMechanism’s InputPorts 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 InputPort is:

### OutputPorts¶

By default, or if the output_ports argument is specified using the keyword RESULTS, a TransferMechanism generates one OutputPort for each item in the outer dimension (axis 0) of its value (each of which is the result of the Mechanism’s function applied to the value of the corresponding InputPort). If there is only one OutputPort (i.e., the case in which there is only one InputPort and therefore only one item in Mechanism’s value), the OutputPort is named RESULT. If there is more than one item in value, then an OuputPort is assigned for each; the name of the first is RESULT-0, and the names of the subsequent ones are suffixed with an integer that is incremented for each successive one (e.g., RESULT-1, RESULT-2, etc.). Additional OutputPorts can be assigned using the TransferMechanism’s standard_output_ports (see Standard OutputPorts) or by creating custom OutputPorts (but see note below). Like any OutputPorts, the value of any or all of these can be modulated by one or more ControlSignals or GatingSignals.

Note

If any OutputPorts are specified in the output_ports argument of the TransferMechanism’s constructor, then, as with any Mechanism, its default OutputPorts are not automatically generated. Therefore, an OutputPort with the appropriate index must be explicitly specified for each and every item of the Mechanism’s value (corresponding to each InputPort) for which an OutputPort 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, the TransferMechanism’s function – applied to the value of each of its input_ports – generates a corresponding set of values, each of which is assigned as an item of the Mechanism’s value attribute, and the value of the corresponding OutputPort in its ouput_ports.

### Integration¶

If integrator_mode is False (the default), then the TransferMechanism updates its value and the value of its output_ports without using its integrator_function, as in the following example:

>>> my_mech = pnl.TransferMechanism(size=2)
>>> my_mech.execute([0.5, 1])
array([[0.5, 1. ]])


Notice that the result is the full linear transfer of the input (i.e., no integration occured).

If integrator_mode is True, then it can be configured to conduct a single step of integration per execution, or to continue to integrate until its termination condition is met, as specified by the termination_threshold, termination_measure, and termination_comparison_op arguments, which are assigned to the TransferMechanism’s termination_threshold, termination_measure, and termination_comparison_op attributes, respectively.

A single step of integration is executed if no termination_threshold is specified (i.e., it is None, the default), as in the following example:

>>> my_mech = pnl.TransferMechanism(size=2,
...                                 integrator_mode=True)
>>> my_mech.execute([0.5, 1])
array([[0.25, 0.5 ]])
>>> my_mech.execute([0.5, 1])
array([[0.375, 0.75 ]])
>>> my_mech.execute([0.5, 1])
array([[0.4375, 0.875 ]])


Notice that every call to the my_execute produces a single step of integration (at the default rate of 0.5), by executing its integrator_function once. A single step is also executed if the Mechanism’s execute_until_finished attribute is set to False, even if termination_threshold is specified. In both cases, the num_executions_before_finished attribute remains equal to 1, since the integrator_function is executed exactly once per call to the execute method (and no termination condition has been specified).

### Termination¶

If integrator_mode is True, and a termination_threshold is specified, then the TransferMechanism continues to execute, integrating its current input until its termination condition is met, or the number of executions reaches max_executions_before_finished. The numer of executions that have taken place since the last time the termination condition was met is contained in num_executions_before_finished; this is set to 0 each time the termination condition is met.

Note

Even after its termination condition is met, a TransferMechanism will continue to execute if it is called again, carrying out one step of integration each time it is called. This can be useful in cases where the initial execution of the Mechanism is meant to bring it to some state (e.g., as an initial “settling process”), after which subsequent executions are meant to occur in step with the execution of other Mechanisms in a Composition (see example below).

By default, execute_until_finished is True, and a convergence criterion is used to terminate integration, as in the following example:

>>> my_mech = pnl.TransferMechanism(size=2,
...                                 integrator_mode=True,
...                                 termination_threshold=0.1)
>>> my_mech.execute([0.5, 1])
array([[0.46875, 0.9375 ]])
>>> my_mech.num_executions_before_finished
4


In this case, the single call to my_mech.execute caused the Mechanism to integrate for 4 steps, until the difference between its current value and its previous value is less than the specified termination_threshold. However, the termination_measure and termination_comparison_op arguments can be used to congifure other termination conditions. There are two broad types of termination condition: convergence and boundary terination.

Convergence termination – execution terminates based on the difference between the TransferMechanism’s current value and its previous_value (as in the example above). This is implemented by specifying termination_measure with a function that accepts a 2d array with two items (1d arrays) as its argument, and returns a scalar (the default for a TransferMechanism is the Distance Function with MAX_ABS_DIFF as its metric). After each execution, the function is passed the Mechanism’s current value as well as its previous_value, and the scalar returned is compared to termination_threshold using the comparison operator specified by termination_comparison_op (which is LESS_THAN_OR_EQUAL by default). Execution continues until this returns True. Thus, in the example above, execution continued until the difference between the Mechanism’s current value and previous_value was less than or equal to 0.1. A Distance Function with other metrics (e.g., ENERGY or ENTROPY) can be specified as the termination_measure, as can any other function that accepts a single argument that is a 2d array with two entries.

Boundary termination – Two types of boundaries can be specified: value or time.

Termination by value. This terminates execution when the Mechanism’s value reaches the the value specified by the threshold argument. This implemented by specifying termination_measure with a function that accepts a 2d array with a single entry as its argument and returns a scalar. The single entry is the TransferMechanism’s current value (that is, previous_value is ignored). After each execution, the function is passed the Mechanism’s current value, and the scalar returned is compared to termination_threshold using the comparison operator specified by termination_comparison_op. Execution continues until this returns True, as in the following example:

>>> my_mech = pnl.TransferMechanism(size=2,
...                                 integrator_mode=True,
...                                 termination_measure=max,
...                                 termination_threshold=0.9,
...                                 termination_comparison_op=pnl.GREATER_THAN_OR_EQUAL)
>>> my_mech.execute([0.5, 1])
array([[0.46875, 0.9375 ]])
>>> my_mech.num_executions_before_finished
4


Here, my_mech continued to execute for 5 times, until the element of the Mechanism’s value with the greatest value exceeded 0.9. Note that GREATER_THAN_EQUAL is a keyword for the string “>=”, which is a key in the comparison_operators dict for the Python operator.ge; any of these can be used to specify termination_comparison_op).

Termination by time. This terminates execution when the Mechanism has executed at least a number of times equal to the threshold at a particular TimeScale (e.g., within a RUN or a TRIAL). This is specified by assigning a TimeScale to termination_measure; execution terminates when the number of executions at that TimeScale equals the termination_threshold. Note that, in this case, the termination_comparison_op argument is ignored (the termination_comparison_op is automatically set to GREATER_THAN_OR_EQUAL). For example, my_mech is configured below to execute at least twice per trial:

>>> my_mech = pnl.TransferMechanism(size=2,
...                                 integrator_mode=True,
...                                 termination_measure=TimeScale.TRIAL,
...                                 termination_threshold=2)
>>> my_mech.execute([0.5, 1])
array([[0.375, 0.75 ]])
>>> my_mech.num_executions_before_finished
2


As noted above, it will continue to execute if it is called again, but only once per call:

>>> my_mech.execute([0.5, 1])
array([[0.4375, 0.875 ]])
>>> my_mech.num_executions_before_finished
1
>>> my_mech.execute([0.5, 1])
array([[0.46875, 0.9375 ]])
>>> my_mech.num_executions_before_finished
1


In the following example, this behavior is exploited to allow a recurrent form of TransferMechanism (attention) to integrate for a fixed number of steps (e.g., to simulate the time taken to encode an instruction regarding the which feature of the stimulus should be attended) before a stimulus is presented, and then allowing that Mechanism to continue to integrate the instruction and impact stimulus processing once the stimulus is presented:

>>> stim_input = pnl.ProcessingMechanism(size=2)
>>> stim_percept = pnl.TransferMechanism(size=2, function=pnl.Logistic)
>>> decision = pnl.TransferMechanism(name='Decision', size=2,
...                                  integrator_mode=True,
...                                  execute_until_finished=False,
...                                  termination_threshold=0.65,
...                                  termination_measure=max,
...                                  termination_comparison_op=pnl.GREATER_THAN)
>>> instruction_input = pnl.ProcessingMechanism(size=2, function=pnl.Linear(slope=10))
>>> attention = pnl.LCAMechanism(name='Attention', size=2, function=pnl.Logistic,
...                              leak=8, competition=8, self_excitation=0, time_step_size=.1,
...                              termination_threshold=3,
...                              termination_measure = pnl.TimeScale.TRIAL)
>>> response = pnl.ProcessingMechanism(name='Response', size=2)
...
>>> comp = pnl.Composition()
>>> comp.add_linear_processing_pathway([stim_input, [[1,-1],[-1,1]], stim_percept, decision, response])
...
>>> stim_percept.set_log_conditions([pnl.RESULT])
>>> attention.set_log_conditions([pnl.RESULT])
>>> decision.set_log_conditions([pnl.RESULT])
>>> response.set_log_conditions(['OutputPort-0'])
...
>>> inputs = {stim_input:        [[1, 1], [1, 1]],
...           instruction_input: [[1, -1], [-1, 1]]}
>>> comp.run(inputs=inputs)


This example implements a simple model of attentional selection in perceptual decision making. In the model, stim_input represents the stimulus input, which is passed to stim_percept, which also receives input from the attention Mechanism. stim_percpt passes its output to decision, which integrates its input until one of the features of the input (the first or second) reaches the threshold of 0.65, at which point response executes (specified by the condition (reponse, WhenFinished(decision)). In addition to the stim_input, the model an instruction on each trial in instruction_input that specifies which feature of the stimulus (i.e., the first or second element) should be “attended”. This is passed to the attention Mechanism, which uses it to select which feature of stim_percept should be passed to decision, and thereby determine the response. Like the decision Mechanism, the attention Mechanism integrates its input. However, its threshold_measure is specified as TimeScale.TRIAL and its threshold as 3, so it carries out 3 steps of integration the first time it is executed in each trial. Thus, when the input is presented at the beginning of each trial, first stim_input and instruction_input execute. Then attention executes, but stim_percept does not yet do so, since it receives input from attention and thus must wait for that to execute first. When attention executes, it carries out its three steps of integration, (giving it a chance to “encode” the instruction before the stimulus is processed by stim_percept). Then stim_perceptexecutes, followed by decision. However, the latter carries out only one step of integration, since its execute_until_finished is set to False. If its output does not meet its termination condition after that one step of integration, then response does not execute, since it has been assigned a condition that requires deciions to terminate before it does so. As a result, since response has not executed, the trial continues (see XXX for a full description of XXX). On the next pass, attention carries out only one step of integration, since its termination condition has already been met, as does decision since its termination condition has not yet been met. If it is met, then response executes and the trial ends (since all Mechanisms have now had an opportunity to execute). The value of the attention and decision Mechanisms after each execution are shown below:

>>> attention.log.print_entries(display=[pnl.TIME, pnl.VALUE])
Log for Attention:
Logged Item:   Time          Value
'RESULT'       0:0:0:1      [0.64565631 0.19781611]  # Trial 0
'RESULT'       0:0:0:1      [0.72347147 0.1422746 ]
'RESULT'       0:0:0:1      [0.74621565 0.1258587 ]
'RESULT'       0:0:1:1      [0.75306362 0.1208305 ]
'RESULT'       0:0:2:1      [0.75516272 0.11926922]
'RESULT'       0:0:3:1      [0.75581168 0.11878318]
'RESULT'       0:0:4:1      [0.75601306 0.11863188]
'RESULT'       0:1:0:1      [0.2955214  0.49852489]  # Trial 1
'RESULT'       0:1:0:1      [0.17185129 0.68187518]
'RESULT'       0:1:0:1      [0.13470156 0.73399742]
'RESULT'       0:1:1:1      [0.1235536  0.74936691]
'RESULT'       0:1:2:1      [0.12011584 0.75402671]

>>> decision.log.print_entries(display=[pnl.TIME, pnl.VALUE])
Log for Decision:
Logged Item:   Time          Value
'RESULT'       0:0:0:3      [0.33917677 0.2657116 ]  # Trial 0
'RESULT'       0:0:1:3      [0.50951133 0.39794126]
'RESULT'       0:0:2:3      [0.59490696 0.46386164]
'RESULT'       0:0:3:3      [0.63767534 0.49676128]
'RESULT'       0:0:4:3      [0.65908142 0.51319226]
'RESULT'       0:1:0:3      [0.59635299 0.59443706]  # Trial 1
'RESULT'       0:1:1:3      [0.56360108 0.6367389 ]
'RESULT'       0:1:2:3      [0.54679699 0.65839718]

>>> response.log.print_entries(display=[pnl.TIME, pnl.VALUE])
Log for Response:
Logged Item:   Time          Value
'OutputPort-0' 0:0:4:4      [0.65908142 0.51319226]  # Trial 0
'OutputPort-0' 0:1:2:4      [0.54679699 0.65839718]  # Trial 1


The Time signatures are run:trial:pass:time_step. Note that attention always executes in time_step 1 (after stim_input and instruction_input which execute in time_step 0). In trial 0, attention executes three times in pass 0 (to reach its specified threshold), and then again in passes 1, 2 and 3 and 4 along with decision (which executes in time_step 3, after stim_percept in time_step 2), as the trial continues and decision executes until reaching its threshold. Note that response executed only executed in pass 4, since it depends on the termination of decision. Note also that in trial 1 attention executes 3 times in pass 0 as it did in trial 0; however, decision executes only 3 times since it begins closer to its threshold in that trial.

### 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 reset method on the mechanism’s integrator_function, or the mechanisms’s own reset method.

The reset method of the integrator_function sets:

to the specified value.

The reset method of the TransferMechanism first sets:

• the Mechanismn’s previous_value attribute,

• the integrator_function’s previous_value attribute, and

• the integrator_function’s value attribute

to the specified value. Then:

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

A use case for reset 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 reset method and the TransferMechanism’s reset method are useful in cases when the integration should instead start over at the original initial value, or a new one.

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

>>> my_time_averaged_transfer_mechanism.integrator_function.reset(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 reset 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, reset was applied directly to the integrator function. The key difference between the integrator_function's reset and the TransferMechanism's reset is that the latter will also execute the mechanism’s function and update its output ports. This is useful if the mechanism’s value or any of its OutputPort 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¶

exception psyneulink.core.components.mechanisms.processing.transfermechanism.TransferError(error_value)
class psyneulink.core.components.mechanisms.processing.transfermechanism.TransferMechanism(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], termination_measure=Distance(metric=MAX_ABS_DIFF), termination_threshold=None, termination_comparison_op=LESS_THAN_OR_EQUAL, output_ports=RESULTS )

Subclass of ProcessingMechanism that performs a simple transform of its input. See Mechanism for additional arguments and attributes.

Parameters
• 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); can be one of the following keywords:

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

• termination_measure (function or TimesScale : default Distance(metric=MAX_ABS_DIFF)) – specifies measure used to determine when execution of TransferMechanism is complete if execute_until_finished is True. If it is a function, it must take at least one argument, and optionally a second, both of which must be arrays, and must return either another array or a scalar; see termination_measure for additional details.

• termination_threshold (None or float : default None) – specifies value against which termination_measure_value is compared to determine when execution of TransferMechanism is complete; see termination_measure for additional details.

• termination_comparison_op (comparator keyword : default LESS_THAN_OR_EQUAL) – specifies how termination_measure_value is compared with termination_threshold to determine when execution of TransferMechanism is complete; see termination_measure for additional details.

• output_ports (str, list or np.ndarray : default RESULTS) – specifies the OutputPorts for the TransferMechanism; the keyword RESULTS (the default) specifies that one OutputPort be generated for each InputPort specified in the input_ports argument (see OutputPorts for additional details, and note <TransferMechanism_OutputPorts_Note> in particular).

integrator_mode

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

Type

bool

integrator_function

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

Type

IntegratorFunction

initial_value

determines the starting value for the integrator_function; only relevant if integrator_mode is True and integration_rate is not 1.0 (see integrator_mode for additional details).

Type

value, list or np.ndarray

integration_rate

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

Type

float

on_resume_integrator_mode

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 - reset the Mechanism with its own current value, so that the value cmoputed 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. RESET - call the integrator_function's reset method so that accumulation Mechanism begins at initial_value

Type

keyword

noise

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.

Type

float or function

clip

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.

Type

list [float, float]

termination_measure

used to determine when execution of the TransferMechanism is complete (i.e., is_finished is True), if execute_until_finished is True. If it is a TimeScale, then execution terminates when the value of the Mechanism’s num_executions at that TimeScale is is equal to termination_threshold. If it is a function, it is passed the value and previous_value of the TransferMechanism; its result (termination_measure_value) is compared with termination_threshold using TransferMechanism.termination_comparison_op, the result of which is used as the value of is_finished.

Note

A Mechanism’s previous_value attribute is distinct from the previous_value attribute of its integrator_function.

Type

function or TimeScale

termination_measure_value

value returned by termination_measure; used to determine when is_finished is True.

Type

array or scalar

termination_threshold

value with which termination_measure_value is compared to determine when execution of TransferMechanism is complete if execute_until_finished is True.

Type

None or float

termination_comparison_op

used to compare termination_measure_value with termination_threshold to determine when execution of TransferMechanism is complete if execute_until_finished is True.

Type

Comparator

standard_output_ports

list of Standard OutputPort that includes the following in addition to the standard_output_ports of a ProcessingMechanism:

COMBINE1d array

Element-wise (Hadamard) sum of all items of the TransferMechanism’s value (requires that they all have the same dimensionality).

Type

list[dict]

Returns

instance of TransferMechanism

Return type

TransferMechanism

_validate_params(request_set, target_set=None, context=None)

Validate FUNCTION and Mechanism params

_instantiate_parameter_ports(function=None, context=None)

Call Port._instantiate_parameter_ports to instantiate a ParameterPort for each parameter with modulable=True

This is a stub, implemented to allow Mechanism subclasses to override _instantiate_parameter_ports

or process InputPorts before and/or after call to _instantiate_parameter_ports :param function:

_instantiate_output_ports(context=None)

Call Port._instantiate_output_ports to instantiate orderedDict of OutputPort(s)

This is a stub, implemented to allow Mechanism subclasses to override _instantiate_output_ports

or process InputPorts before and/or after call to _instantiate_output_ports

_execute(variable=None, context=None, runtime_params=None)

Execute TransferMechanism function and return transform of input

Execute TransferMechanism function on input, and assign to output_values:
• Activation value for all units

• Mean of the activation values across units

• Variance of the activation values across units

Returns

value of input transformed by TransferMechanism function in outputPort[TransferOuput.RESULT].value mean of items in RESULT outputPort[TransferOuput.MEAN].value variance of items in RESULT outputPort[TransferOuput.VARIANCE].value

Arguments:

# CONFIRM: variable (float): set to self.value (= self.input_value) - params (dict): runtime_params passed from Mechanism, used as one-time value for current execution:

• NOISE (float)

• INTEGRATION_RATE (float)

• RANGE ([float, float])

• context (str)

Returns the following values in self.value (2D np.array) and in

the value of the corresponding outputPort in the self.output_ports list: - activation value (float) - mean activation value (float) - standard deviation of activation values (float)

Parameters

self

:param variable (float) :param params: (dict) :param context: (str) :rtype self.outputPort.value: (number)

reset(*args, force=False, context=None, **kwargs)

Reset value if Mechanisms is stateful.

If the mechanism’s function is an IntegratorFunction, or if the mechanism has and integrator_function (see TransferMechanism), this method effectively begins the function’s accumulation over again at the specified value, and updates related attributes on the mechanism. It also clears the value history <Parameter.history, thus effectively setting the previous value to None.

If the mechanism’s function is an IntegratorFunction, its reset method:

1. Calls the function’s own reset method (see Note below for details)

2. Sets the mechanism’s value to the output of the function’s reset method

3. Updates its output ports based on its new value

If the mechanism has an integrator_function, its reset method:

(1) Calls the integrator_function's <TransferMechanism.integrator_function> own reset
<IntegratorFunction.reset> method (see Note below for details)

(2) Executes its function <Mechanism_Base.function> using the output of the integrator_function's
<TransferMechanism.integrator_function> reset <IntegratorFunction.reset> method as
the function's variable

(3) Sets the mechanism's value <Mechanism_Base.value> to the output of its function

(4) Updates its output ports <Mechanism_Base.output_port> based on its new value
<Mechanism_Base.value>


Note

The reset method of an IntegratorFunction Function typically resets the function’s previous_value (and any other stateful_attributes) and value to the quantity (or quantities) specified. If reset is called without arguments, the initializer value (or the values of each of the attributes in initializers) is used instead. The reset method may vary across different Integrators. See individual functions for details on their stateful_attributes, as well as other reinitialization steps that the reset method may carry out.

_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

_instantiate_attributes_after_function(context=None)

Determine numberr of items expected by termination_measure

_report_mechanism_execution(input, params=None, output=None, context=None)

Override super to report previous_input rather than input, and selected params

is_finished(context=None)

Returns True when value of Mechanism reaches threhsold or if threshold is None.

Note: if threshold is None or Mechanism not in integartor_mode,

implements single update (cycle) per call to _execute method (equivalent to setting Component.execute_until_finished = False)