Functions¶
 Example function:
 Combination Functions:
 Transfer Functions:
 Integrator Functions:
 Distribution Functions:
 Objective Functions:
 Learning Functions:
 Custom Function:
Overview¶
A Function is a Component that “packages” a function (in its function
method)
for use by other Components. Every Component in PsyNeuLink is assigned a Function; when that Component is executed, its
Function’s function
is executed. The function
can be any callable
operation, although most commonly it is a mathematical operation (and, for those, almost always uses a call to one or
more numpy functions). There are two reasons PsyNeuLink packages functions in a Function Component:
 Manage parameters – parameters are attributes of a Function that either remain stable over multiple calls to the
function (e.g., the
gain
orbias
of aLogistic
function, or the learning rate of a learning function); or, if they change, they do so less frequently or under the control of different factors than the function’s variable (i.e., its input). As a consequence, it is useful to manage these separately from the function’s variable, and not have to provide them every time the function is called. To address this, every PsyNeuLink Function has a set of attributes corresponding to the parameters of the function, that can be specified at the time the Function is created (in arguments to its constructor), and can be modified independently of a call to itsfunction
. Modifications can be directly (e.g., in a script), or by the operation of other PsyNeuLink Components (e.g., Adaptive Mechanisms) by way of ControlProjections.
 Modularity – by providing a standard interface, any Function assigned to a Components in PsyNeuLink can be replaced with other PsyNeuLink Functions, or with userwritten custom functions so long as they adhere to certain standards (the PsyNeuLink Function API).
Creating a Function¶
A Function can be created directly by calling its constructor. Functions are also created automatically whenever
any other type of PsyNeuLink Component is created (and its function
is not otherwise specified). The
constructor for a Function has an argument for its variable
and each of the parameters of
its function
. The variable
argument is used both to format the
input to the function
, and assign its default value. The arguments for each parameter can
be used to specify the default value for that parameter; the values can later be modified in various ways as described
below.
Structure¶
Core Attributes¶
Every Function has the following core attributes:
function
– determines the computation carried out by the Function; it must be a callable object (that is, a python function or method of some kind). Unlike other PsyNeuLink Components, it cannot be (another) Function object (it can’t be “turtles” all the way down!). If the Function has been assigned to another Components, then itsfunction
is also assigned as the thefunction
attribute of the Component to which it has been assigned (i.e., itsowner
.
A Function also has an attribute for each of the parameters of its function
.
Owner¶
If a Function has been assigned to another Components, then it also has an owner
attribute
that refers to that Component. The Function itself is assigned as the Component’s
function_object
attribute. Each of the Function’s attributes is also assigned
as an attribute of the owner
, and those are each associated with with a
parameterState of the owner
. Projections to those parameterStates can be
used by ControlProjections to modify the Function’s parameters.
Modulatory Parameters¶
Some classes of Functions also implement a pair of modulatory parameters: multiplicative_param
and additive_param
.
Each of these is assigned the name of one of the function’s parameters. These are used by ModulatorySignals to modulate the output of the function (see figure). For
example, they are used by GatingSignals to modulate the function
of an
InputState or OutputState, and thereby its value
; and by the ControlSignal(s)
of an LCControlMechanism to modulate the multiplicative_param
of the function
of a
TransferMechanism.
Execution¶
Functions are not executable objects, but their function
can be called. This can be done
directly. More commonly, however, they are called when their owner
is executed. The parameters
of the function
can be modified when it is executed, by assigning a
parameter specification dictionary to the params argument in the
call to the function
.
For Mechanisms, this can also be done by specifying runtime_params in the Run method of their Compositions.
Class Reference¶

class
psyneulink.components.functions.function.
ModulationParam
¶ Specify parameter of a Function for modulation by a ModulatorySignal

MULTIPLICATIVE
¶ assign the
value
of the ModulatorySignal to the MULTIPLICATIVE_PARAM of the State’sfunction


class
psyneulink.components.functions.function.
Function_Base
(default_variable, params=None, owner=None, name=None, prefs=None)¶ Implement abstract class for Function category of Component class
Parameters:  variable (value : default ClassDefaults.variable) – specifies the format and a default value for the input to function.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ value – format and default value can be specified by the
variable
argument of the constructor; otherwise, they are specified by the Function’sClassDefaults.variable
.

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

class
psyneulink.components.functions.function.
ArgumentTherapy
(variable, propensity=Manner.CONTRARIAN, pertinacity=10.0 params=None, owner=None, name=None, prefs=None)¶ Return
True
orFalse
according to the manner of the therapist.Parameters:  variable (boolean or statement that resolves to one : default ClassDefaults.variable) – assertion for which a therapeutic response will be offered.
 propensity (Manner value : default Manner.CONTRARIAN) – specifies preferred therapeutic manner
 pertinacity (float : default 10.0) – specifies therapeutic consistency
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ boolean – assertion to which a therapeutic response is made.

propensity
¶ Manner value : default Manner.CONTRARIAN – determines therapeutic manner: tendency to agree or disagree.

pertinacity
¶ float : default 10.0 – determines consistency with which the manner complies with the propensity.

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

class
Manner
¶ An enumeration.

function
(variable=None, params=None, context=None)¶ Returns a boolean that is (or tends to be) the same as or opposite the one passed in.
Parameters:  variable (boolean : default ClassDefaults.variable) – an assertion to which a therapeutic response is made.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: therapeutic response
Return type: boolean

class
psyneulink.components.functions.function.
UserDefinedFunction
(custom_function=None, default_variable=None, params=None, owner=None, prefs: <function is_pref_set at 0x103bf0a60> = None, **kwargs)¶ UserDefinedFunction( custom_function=None, default_variable=None, params=None, owner=None, name=None, prefs=None )
A UserDefinedFunction (UDF) is used to “wrap” a Python function or method, including a lamdba function, as a PsyNeuLink Functions, so that it can be used as the
function
of a Component. This is done automatically if a Python function or method is assigned as thefunction
attribute of a Component. A Python function or method can also be wrapped on its own, by calling the UserDefinedFunction constructor, and assigning the Python function or method as its custom_function argument. The Python function or method must obey the following conventions to be treated correctly as a UserDefinedFunction (UDF): It must have at least one argument (that can be a positional or a keyword argument); this will be treated
as the
variable
attribute of the UDF’sfunction
. When the UDF calls the function or method that it wraps, an initial attempt is made to do so with variable as the name of the first argument; if that fails, it is called positionally. The argument is always passed as a 2d np.array, that may contain one or more items (elements in axis 0), depending upon the Component to which the UDF is assigned. It is the user’s responsibility to insure that the number of items expected in the first argument of the function or method is compatible with the circumstances in which it will be called.
 It may have have any number of additional arguments (positional and/or keyword); these are treated as parameters of the UDF, and can be modulated by ModulatorySignals like the parameters of ordinary PsyNeuLink Functions. If the UDF is assigned to (or automatically created for) a Mechanisms or Projection, these parameters are each automatically assigned a ParameterState so that they can be modulated by ControlSignals or LearningSignals, respectively. If the UDF is assigned to (or automatically created for) an InputState or OutputState, and any of the parameters are specified as Modulatory Parameters (see below), then they can be modulated by GatingSignals. The function or method wrapped by the UDF is called with these parameters by their name and with their current values (i.e., as determined by any ModulatorySignals assigned to them).
 It may include context and params arguments; these are not required, but can be included to receive information about the current conditions of execution. When the function or method is called, an initial attempt is made to do so with these arguments; if that fails, it is called again without them.
The parameters of a UDF can be specified as Modulatory Parameters in a parameter specification dictionary assigned to the params argument of the constructor for either the Python function or method, or of an explicitly defined UDF (see examples below). It can include either or both of the following two entries:
MULTIPLICATIVE_PARAM: <parameter name>
ADDITIVE_PARAM: <parameter name>
These are used only when the UDF is assigned as the
function
of an InputState or OutputState that receives one more more GatingProjections.
Tip
The format of the
variable
passed to thecustom_function
function can be verified by adding aprint(variable)
orprint(type(variable))
statement to the function.Assigning a custom function to a Mechanism
The following example assigns a simple lambda function that returns the sum of the elements of a 1d array) to a TransferMechanism:
>>> import psyneulink as pnl >>> my_mech = pnl.ProcessingMechanism(default_variable=[[0,0,0]], ... function=lambda x:sum(x[0])) >>> my_mech.execute(input = [1, 2, 3]) array([[6]])
Note that the function treats its argument, x, as a 2d array, and accesses its first item for the calculation. This is because the
variable
ofmy_mech
is defined in the size argument of its constructor as having a single item (a 1d array of length 3; (seesize
). In the following example, a function is defined for a Mechanism in which the variable has two items, that are summed by the function:>>> my_mech = pnl.ProcessingMechanism(default_variable=[[0],[0]], ... function=lambda x: x[0] + x[1]) >>> my_mech.execute(input = [[1],[2]]) array([[3]])
The function argument can also be assigned a function defined in Python:
>>> def my_fct(variable): ... return variable[0] + variable[1] >>> my_mech = pnl.ProcessingMechanism(default_variable=[[0],[0]], ... function=my_fct)
This will produce the same result as the last example. This can be useful for assigning the function to more than one Component.
More complicated functions, including ones with more than one parameter can also be used; for example:
>>> def my_sinusoidal_fct(input=[[0],[0]], ... phase=0, ... amplitude=1): ... frequency = input[0] ... t = input[1] ... return amplitude * np.sin(2 * np.pi * frequency * t + phase) >>> my_wave_mech = pnl.ProcessingMechanism(default_variable=[[0],[0]], ... function=my_sinusoidal_fct)
Note that in this example,
input
is used as the name of the first argument, instead ofvariable
as in the examples above. The name of the first argument of a function to be “wrapped” as a UDF does not matter; in general it is good practice to usevariable
, as thevariable
of the Component to which the UDF is assigned is what is passed to the function as its first argument. However, if it is helpful to name it something else, that is fine.Notice also that
my_sinusoidal_fct
takes two values in itsinput
argument, that it assigns to thefrequency
andt
variables of the function. While it could have been specified more compactly as a 1d array with two elements (i.e. [0,0]), it is specified in the example as a 2d array with two items to make it clear that it matches the format of the default_variable for the ProcessingMechanism to which it will be assigned, which requires it be formatted this way (since thevariable
of all Components are converted to a 2d array).my_sinusoidal_fct
also has two other arguments,phase
andamplitude
. When it is assigned tomy_wave_mech
, those parameters are assigned to ParameterStates ofmy_wave_mech
, which that be used to modify their values by ControlSignals (seeexample below
).In all of the examples above, a UDF was automatically created for the functions assigned to the Mechanism. A UDF can also be created explicitly, as follows:
>>> my_sinusoidal_UDF = pnl.UserDefinedFunction(custom_function=my_sinusoidal_fct) >>> my_wave_mech = pnl.ProcessingMechanism(default_variable=[[0],[0]], ... function=my_sinusoidal_UDF)
When the UDF is created explicitly, parameters of the function can be included as arguments to its constructor, to assign them default values that differ from the those in the definition of the function, or for parameters that don’t define default values. For example:
>>> my_sinusoidal_UDF = pnl.UserDefinedFunction(custom_function=my_sinusoidal_fct, ... phase=10, ... amplitude=3) >>> my_wave_mech = pnl.ProcessingMechanism(default_variable=[[0],[0]], ... function=my_sinusoidal_UDF)
assigns
my_sinusoidal_fct
as thefunction
formy_mech
, but with the default values of itsphase
andamplitude
parameters assigned new values. This can be useful for assigning the same function to different Mechanisms with different default values.Explicitly defining the UDF can also be used to specify control for parameters of the function, as in the following example:
>>> my_mech = pnl.ProcessingMechanism(default_variable=[[0],[0]], ... function=UserDefinedFunction(custom_function=my_sinusoidal_fct, ... amplitude=(1.0, pnl.CONTROL)))
This specifies that the default value of the
amplitude
parameter ofmy_sinusoidal_fct
be1.0
, but its value should be modulated by a ControlSignal.Custom functions can be as elaborate as desired, and can even include other PsyNeuLink Functions indirectly, such as:
>>> import psyneulink as pnl >>> L = pnl.Logistic(gain = 2) >>> def my_fct(variable): ... return L.function(variable) + 2 >>> my_mech = pnl.ProcessingMechanism(size = 3, function = my_fct) >>> my_mech.execute(input = [1, 2, 3]) array([[2.88079708, 2.98201379, 2.99752738]])
Assigning of a custom function to a State
A custom function can also be assigned as the
function
of an InputState or OutputState. For example, the following assignsmy_sinusoidal_fct
to thefunction
of an OutputState ofmy_mech
, rather the Mechanism’sfunction
:>>> my_wave_mech = pnl.ProcessingMechanism(size=1, ... function=pnl.Linear, ... output_states=[{pnl.NAME: 'SINUSOIDAL OUTPUT', ... pnl.VARIABLE: [(pnl.OWNER_VALUE, 0),pnl.EXECUTION_COUNT], ... pnl.FUNCTION: my_sinusoidal_fct}])
For details on how to specify a function of an OutputState, see OutputState Customization. Below is an example plot of the output of the ‘SINUSOIDAL OUTPUT’ OutputState from my_wave_mech above, as the execution count increments, when the input to the mechanism is 0.005 for 1000 runs:
The parameters of a custom function assigned to an InputState or OutputState can also be used for gating. However, this requires that its Modulatory Parameters be specified (see above). This can be done by including a params argument in the definition of the function itself:
>>> def my_sinusoidal_fct(input=[[0],[0]], ... phase=0, ... amplitude=1, ... params={pnl.ADDITIVE_PARAM:'phase', ... pnl.MULTIPLICATIVE_PARAM:'amplitude'}): ... frequency = input[0] ... t = input[1] ... return amplitude * np.sin(2 * np.pi * frequency * t + phase)
or in the explicit creation of a UDF:
>>> my_sinusoidal_UDF = pnl.UserDefinedFunction(custom_function=my_sinusoidal_fct, ... phase=0, ... amplitude=1, ... params={pnl.ADDITIVE_PARAM:'phase', ... pnl.MULTIPLICATIVE_PARAM:'amplitude'})
The
phase
andamplitude
parameters ofmy_sinusoidal_fct
can now be used as the Modulatory Parameters for gating any InputState or OutputState to which the function is assigned (see Specifying gating and Examples).Class Definition:
 custom_function : function
 specifies the function to “wrap.” It can be any function or method, including a lambda function; see above for additional details.
 params : Dict[param keyword: param value] : default None
a parameter dictionary that specifies the parameters for the function. This can be used to define an
additive_param
and/ormultiplicative_param
for the UDF, by including one or both of the following entries:ADDITIVE_PARAM: <param_name>
MULTIPLICATIVE_PARAM: <param_name>
Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner : Component
 component to which to assign the Function.
 name : str : default see
name
 specifies the name of the Function.
 prefs : PreferenceSet or specification dict : default Function.classPreferences
 specifies the
PreferenceSet
for the Function (seeprefs
for details).
 variable: value
 format and default value of the function “wrapped” by the UDF.
 custom_function : function
 the userspecified function: called by the Function’s
owner
when it is executed.  additive_param : str
 this contains the name of the additive_param, if one has been specified for the UDF (see above for details).
 multiplicative_param : str
 this contains the name of the multiplicative_param, if one has been specified for the UDF (see above for details).
 owner : Component
 component to which the Function has been assigned.
 name : str
 the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).
 prefs : PreferenceSet or specification dict
 the
PreferenceSet
for the Function; if it is not specified in the prefs argument of the constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).
 It must have at least one argument (that can be a positional or a keyword argument); this will be treated
as the

class
psyneulink.components.functions.function.
Reduce
(default_variable=ClassDefaults.variable, weights=None, exponents=None, operation=SUM, scale=1.0, offset=0.0, params=None, owner=None, prefs=None)¶ Combine values in each of one or more arrays into a single value for each array, with optional weighting and/or exponentiation of each item within an array prior to combining, and scaling and/or offset of result.
Returns a scalar value for each array of the input.
Parameters:  default_variable (list or np.array : default ClassDefaults.variable) – specifies a template for the value to be transformed and its default value; all entries must be numeric.
 weights (1d or 2d np.array : default None) – specifies values used to multiply the elements of each array in
variable
. If it is 1d, its length must equal the number of items invariable
; if it is 2d, the length of each item must be the same as those invariable
, and there must be the same number of items as there are invariable
(seeweights
for details)  exponents (1d or 2d np.array : default None) – specifies values used to exponentiate the elements of each array in
variable
. If it is 1d, its length must equal the number of items invariable
; if it is 2d, the length of each item must be the same as those invariable
, and there must be the same number of items as there are invariable
(seeexponents
for details)  operation (SUM or PRODUCT : default SUM) – specifies whether to sum or multiply the elements in
variable
offunction
.  scale (float) – specifies a value by which to multiply each element of the output of
function
(seescale
for details)  offset (float) – specifies a value to add to each element of the output of
function
(seeoffset
for details)  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

default_variable
¶ list or np.array – contains array(s) to be reduced.

operation
¶ SUM or PRODUCT – determines whether elements of each array in
variable
offunction
are summmed or multiplied.

scale
¶ float – value is applied multiplicatively to each element of the array after applying the
operation
(seescale
for details); this done before applying theoffset
(if it is specified).

offset
¶ float – value is added to each element of the array after applying the
operation
andscale
(if it is specified).

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Calculate sum or product of the elements for each array in
variable
, applyscale
and/oroffset
, and return array of resulting values.Parameters:  variable (list or np.array : default ClassDefaults.variable) – a list or np.array of numeric values.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: Sum or product of arrays in variable – in an array that is one dimension less than
variable
.Return type: np.array

class
psyneulink.components.functions.function.
LinearCombination
(default_variable, weights=None, exponents=None, operation=SUM, scale=None, offset=None, params=None, owner=None, name=None, prefs=None)¶ Linearly combine arrays of values, with optional weighting and/or exponentiation of each array prior to combining, and scaling and/or offset of result.
Combines the arrays in the items of the
variable
argument. Each array can be individually weighted and/or exponentiated; they can combined additively or multiplicatively; and the resulting array can be multiplicatively transformed and/or additively offset.Parameters:  variable (1d or 2d np.array : default ClassDefaults.variable) – specifies a template for the arrays to be combined. If it is 2d, all items must have the same length.
 weights (scalar or 1d or 2d np.array : default None) – specifies values used to multiply the elements of each array in variable.
If it is 1d, its length must equal the number of items in
variable
; if it is 2d, the length of each item must be the same as those invariable
, and there must be the same number of items as there are invariable
(seeweights
for details of how weights are applied).  exponents (scalar or 1d or 2d np.array : default None) – specifies values used to exponentiate the elements of each array in
variable
. If it is 1d, its length must equal the number of items invariable
; if it is 2d, the length of each item must be the same as those invariable
, and there must be the same number of items as there are invariable
(seeexponents
for details of how exponents are applied).  operation (SUM or PRODUCT : default SUM) – specifies whether the
function
takes the elementwise (Hadamarad) sum or product of the arrays invariable
.  scale (float or np.ndarray : default None) – specifies a value by which to multiply each element of the result of
function
(seescale
for details)  offset (float or np.ndarray : default None) – specifies a value to add to each element of the result of
function
(seeoffset
for details)  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ 1d or 2d np.array – contains the arrays to be combined by function. If it is 1d, the array is simply linearly transformed by and
scale
andoffset
. If it is 2d, the arrays (all of which must be of equal length) are weighted and/or exponentiated as specified byweights
and/orexponents
and then combined as specified byoperation
.

weights
¶ scalar or 1d or 2d np.array – if it is a scalar, the value is used to multiply all elements of all arrays in
variable
; if it is a 1d array, each element is used to multiply all elements in the corresponding array ofvariable
; if it is a 2d array, then each array is multiplied elementwise (i.e., the Hadamard Product is taken) with the corresponding array ofvariable
. Allweights
are applied before any exponentiation (if it is specified).

exponents
¶ scalar or 1d or 2d np.array – if it is a scalar, the value is used to exponentiate all elements of all arrays in
variable
; if it is a 1d array, each element is used to exponentiate the elements of the corresponding array ofvariable
; if it is a 2d array, the element of each array is used to exponentiate the corresponding element of the corresponding array ofvariable
. In either case, all exponents are applied after application of theweights
(if any are specified).

operation
¶ SUM or PRODUCT – determines whether the
function
takes the elementwise (Hadamard) sum or product of the arrays invariable
.

scale
¶ float or np.ndarray – value is applied multiplicatively to each element of the array after applying the
operation
(seescale
for details); this done before applying theoffset
(if it is specified).

offset
¶ float or np.ndarray – value is added to each element of the array after applying the
operation
andscale
(if it is specified).

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Apply
weights
and/orexponents
to the arrays invariable
, then take their sum or product (as specified byoperation
), applyscale
and/oroffset
, and return the resulting array.Parameters:  variable (1d or 2d np.array : default ClassDefaults.variable) – a single numeric array, or multiple arrays to be combined; if it is 2d, all arrays must have the same length.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: combined array – the result of linearly combining the arrays in
variable
.Return type: 1d np.array

class
psyneulink.components.functions.function.
CombineMeans
(default_variable, weights=None, exponents=None, operation=SUM, scale=None, offset=None, params=None, owner=None, name=None, prefs=None)¶ Linearly combines the means of one or more arrays of values with optional scaling and/or offset applied to result.
Takes the mean of the array in each item of its
variable
argument, and combines them as specified by theoperation
parameter, taking either their sum (the default) or their product. The mean of each array can be individually weighted and/or exponentiated prior to being combined, and the resulting scalar can be multiplicatively transformed and/or additively offset.Parameters:  variable (1d or 2d np.array : default ClassDefaults.variable) – specifies a template for the arrays to be combined. If it is 2d, all items must have the same length.
 weights (1d or 2d np.array : default None) – specifies values used to multiply the elements of each array in
variable
. If it is 1d, its length must equal the number of items invariable
; if it is 2d, the length of each item must be the same as those invariable
, and there must be the same number of items as there are invariable
(seeweights
for details)  exponents (1d or 2d np.array : default None) – specifies values used to exponentiate the elements of each array in
variable
. If it is 1d, its length must equal the number of items invariable
; if it is 2d, the length of each item must be the same as those invariable
, and there must be the same number of items as there are invariable
(seeexponents
for details)  operation (SUM or PRODUCT : default SUM) – specifies whether the
function
takes the sum or product of the means of the arrays invariable
.  scale (float or np.ndarray : default None) – specifies a value by which to multiply the result of
function
(seescale
for details)  offset (float or np.ndarray : default None) – specifies a value to add to the result of
function
(seeoffset
for details)  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ 1d or 2d np.array – contains the arrays to be combined by function. If it is 1d, the array is simply linearly transformed by and
scale
andoffset
. If it is 2d, the arrays (all of which must be of equal length) are weighted and/or exponentiated as specified byweights
and/orexponents
and then combined as specified byoperation
.

weights
¶ 1d or 2d np.array : default NOne – if it is 1d, each element is used to multiply all elements in the corresponding array of
variable
; if it is 2d, then each array is multiplied elementwise (i.e., the Hadamard Product is taken) with the corresponding array ofvariable
. Allweights
are applied before any exponentiation (if it is specified).

exponents
¶ 1d or 2d np.array : default None – if it is 1d, each element is used to exponentiate the elements of the corresponding array of
variable
; if it is 2d, the element of each array is used to exponentiate the corresponding element of the corresponding array ofvariable
. In either case, exponentiating is applied after application of theweights
(if any are specified).

operation
¶ SUM or PRODUCT : default SUM – determines whether the
function
takes the elementwise (Hadamard) sum or product of the arrays invariable
.

scale
¶ float or np.ndarray : default None – value is applied multiplicatively to each element of the array after applying the
operation
(seescale
for details); this done before applying theoffset
(if it is specified).

offset
¶ float or np.ndarray : default None – value is added to each element of the array after applying the
operation
andscale
(if it is specified).

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Calculate and combine means of items in
variable
.Take mean of each item of
variable
; Applyweights
and/orexponents
(if specified) to the means; Take their sum or product, as specified byoperation
; Applyscale
(if specified) multiplicatively to the result; Applyoffset
(if specified) to the result; Return scalarParameters:  variable (1d or 2d np.array : default ClassDefaults.variable) – a single numeric array, or multiple arrays to be combined; if it is 2d, all arrays must have the same length.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: combined array – the result of linearly combining the arrays in
variable
.Return type: 1d np.array

class
psyneulink.components.functions.function.
PredictionErrorDeltaFunction
(default_variable=None, gamma: <typecheck.framework.optional object at 0x104f7a3c8> = 1.0, params=None, owner=None, prefs: <function is_pref_set at 0x103bf0a60> = None)¶ Function that calculates the temporal difference prediction error

function
(variable=None, params=None, context=None)¶ Calculates the prediction error using the arrays in
variable
and returns the resulting array.Parameters:  variable (2d np.array : default ClassDefaults.variable) – a 2d array representing the sample and target values to be used to calculate the temporal difference delta values. Both arrays must have the same length
 params (Dict[param keyword, param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: delta values –
 the result of
math: delta(t) = r(t) + gamma sample(t)  sample(t  1)
Return type: 1d np.array


class
psyneulink.components.functions.function.
TransferFunction
(default_variable, params, owner, prefs, context)¶ Function that transforms variable but maintains its shape
All TransferFunctions must have the following attributes:
bounds
– specifies the lower and upper limits of the result; if there are none, the attribute is set toNone
; if it has at least one bound, the attribute is set to a tuple specifying the lower and upper bounds, respectively, withNone
as the entry for no bound.multiplicative_param
andadditive_param
– each of these is assigned the name of one of the function’s parameters and used by ModulatoryProjections to modulate the output of the TransferFunction’s function (see Modulatory Parameters).

class
psyneulink.components.functions.function.
Linear
(default_variable, slope=1.0, intercept=0.0, params=None, owner=None, name=None, prefs=None)¶ Linearly transform variable.
Note: default values for
slope
andintercept
implement the IDENTITY_FUNCTIONParameters:  variable (number or np.array : default ClassDefaults.variable) – specifies a template for the value to be transformed.
 slope (float : default 1.0) – specifies a value by which to multiply
variable
.  intercept (float : default 0.0) – specifies a value to add to each element of
variable
after applyingslope
.  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – contains value to be transformed.

slope
¶ float – value by which each element of
variable
is multiplied before applying theintercept
(if it is specified).

intercept
¶ float – value added to each element of
variable
after applying theslope
(if it is specified).

bounds
¶ None

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return:
slope
*variable
+intercept
.Parameters:  variable (number or np.array : default ClassDefaults.variable) – a single value or array to be transformed.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: linear transformation of variable
Return type: number or np.array

class
psyneulink.components.functions.function.
Exponential
(default_variable, scale=1.0, rate=1.0, params=None, owner=None, name=None, prefs=None)¶ Exponentially transform variable.
Parameters:  variable (number or np.array : default ClassDefaults.variable) – specifies a template for the value to be transformed.
 rate (float : default 1.0) – specifies a value by which to multiply
variable
before exponentiation.  scale (float : default 1.0) – specifies a value by which to multiply the exponentiated value of
variable
.  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – contains value to be transformed.

scale
¶ float – value by which the exponentiated value is multiplied.

bounds
¶ (0, None)

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return:
scale
\(*\) e**(rate
\(*\)variable
).Parameters:  variable (number or np.array : default ClassDefaults.variable) – a single value or array to be exponentiated.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: exponential transformation of variable
Return type: number or np.array

class
psyneulink.components.functions.function.
Logistic
(default_variable, gain=1.0, bias=0.0, offset=0.0, params=None, owner=None, name=None, prefs=None)¶ Logistically transform variable.
Parameters:  variable (number or np.array : default ClassDefaults.variable) – specifies a template for the value to be transformed.
 gain (float : default 1.0) – specifies a value by which to multiply
variable
before logistic transformation  bias (float : default 0.0) – specifies a value to add to each element of
variable
before applyinggain
and before logistic transformation.  offset (float : default 0.0) – specifies a value to add to each element of
variable
after applyinggain
but before logistic transformation.  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – contains value to be transformed.

gain
¶ float : default 1.0 – value by which each element of
variable
is multiplied before applying thebias
(if it is specified).

bias
¶ float : default 0.0 – value added to each element of
variable
after applying thegain
(if it is specified).

bounds
¶ (0,1)

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return:
\[\frac{1}{1 + e^{  gain ( variable  bias ) + offset}}\]Parameters:  variable (number or np.array : default ClassDefaults.variable) – a single value or array to be transformed.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: logistic transformation of variable
Return type: number or np.array

class
psyneulink.components.functions.function.
ReLU
(default_variable, gain=1.0, bias=0.0, leak=0.0, params=None, owner=None, name=None, prefs=None)¶ Perform rectified linear transformation on variable,
Commonly used by ReLU units in neural networks.
Parameters:  variable (number or np.array : default ClassDefaults.variable) – specifies a template for the value to be transformed.
 gain (float : default 1.0) – specifies a value by which to multiply
variable
afterbias
is subtracted from it, if (variable  bias) is greater than 0.  bias (float : default 0.0) – specifies a value to subtract from each element of
variable
before checking if the result is greater than 0 and multiplying by either gain or leak based on the result.  leak (float : default 0.0) – specifies a value by which to multiply
variable
afterbias
is subtracted from it if (variable  bias) is lesser than or equal to 0.  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – contains value to be transformed.

gain
¶ float : default 1.0 – value multiplied with
variable
afterbias
is subtracted from it if (variable  bias) is greater than 0.

bias
¶ float : default 0.0 – value subtracted from each element of
variable
before checking if the result is greater than 0 and multiplying by either gain or leak based on the result.

leak
¶ float : default 0.0 – value multiplied with
variable
afterbias
is subtracted from it if (variable  bias) is lesser than or equal to 0.

bounds
¶ (None,None)

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Returns: \(gain*(variable  bias)\ if\ (variable  bias) > 0,\ leak*(variable  bias)\ otherwise\)
Parameters:  variable (number or np.array : default ClassDefaults.variable) – a single value or array to be transformed.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: ReLU transformation of variable
Return type: number or np.array

class
psyneulink.components.functions.function.
OneHot
(default_variable, mode=MAX_VAL, params=None, owner=None, name=None, prefs=None)¶ Return an array with one nonzero value.
The
mode
parameter determines the nature of the nonzero value:Parameters:  variable (2d np.array : default ClassDefaults.variable) – First (possibly only) item specifies a template for the array to be transformed; if
mode
is PROB then a 2nd item must be included that is a probability distribution with same length as 1st item.  mode (MAX_VAL, MAX_ABS_VAL, MAX_INDICATOR, or PROB : default MAX_VAL) – specifies the nature of the single nonzero value in the array returned by
function
(seemode
for details).  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 bounds (None) –
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – 1st item contains value to be transformed; if
mode
is PROB, 2nd item is a probability distribution, each element of which specifies the probability for selecting the corresponding element of the 1st item.

mode
¶ MAX_VAL, MAX_ABS_VAL, MAX_INDICATOR, or PROB : default MAX_VAL –
 determines the nature of the single nonzero value in the array returned by
function
:  MAX_VAL: element with the maximum signed value in the original array;
 MAX_ABS_VAL: element with the maximum absolute value;
 MAX_INDICATOR: 1 in place of the element with the maximum signed value;
 MAX_ABS_INDICATOR: 1 in place of the element with the maximum absolute value;
 PROB: probabilistically chosen element based on probabilities passed in second item of
 PROB_INDICATOR: same as PROB but chosen item is assigned a value of 1.
 determines the nature of the single nonzero value in the array returned by

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return array of len(
variable
) with single nonzero value specified bymode
.Parameters:  variable (2d np.array : default ClassDefaults.variable) – 1st item is an array to be transformed; if
mode
is PROB, 2nd item must be an array of probabilities (i.e., elements between 0 and 1) of equal length to the 1st item.  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: array with single nonzero value
Return type: np.array
 variable (2d np.array : default ClassDefaults.variable) – 1st item is an array to be transformed; if
 variable (2d np.array : default ClassDefaults.variable) – First (possibly only) item specifies a template for the array to be transformed; if

class
psyneulink.components.functions.function.
SoftMax
(default_variable, gain=1.0, output=ALL, params=None, owner=None, name=None, prefs=None)¶ SoftMax transform of variable (see The Softmax function and its derivative for a nice discussion).
Parameters:  default_variable (1d np.array : default ClassDefaults.variable) – specifies a template for the value to be transformed.
 gain (float : default 1.0) – specifies a value by which to multiply
variable
before SoftMax transformation.  output (ALL, MAX_VAL, MAX_INDICATOR, or PROB : default ALL) – specifies the format of array returned by
function
(seeoutput
for details).  per_item (boolean : default True) – for 2d variables, determines whether the SoftMax function will be applied to the entire variable (per_item = False), or applied to each item in the variable separately (per_item = True).
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ 1d np.array – contains value to be transformed.

gain
¶ float – value by which
variable
is multiplied before the SoftMax transformation; determines the “sharpness” of the distribution.

output
¶ ALL, MAX_VAL, MAX_INDICATOR, or PROB – determines how the SoftMaxtransformed values of the elements in
variable
are reported in the array returned byfunction
: ALL: array of all SoftMaxtransformed values (the default);
 MAX_VAL: SoftMaxtransformed value for the element with the maximum such value, 0 for all others;
 MAX_INDICATOR: 1 for the element with the maximum SoftMaxtransformed value, 0 for all others;
 PROB: probabilistically chosen element based on SoftMaxtransformed values after normalizing the sum of values to 1 (i.e., their Luce Ratio), 0 for all others.

per_item
¶ boolean : default True – for 2d variables, determines whether the SoftMax function will be applied to the entire variable (per_item = False), or applied to each item in the variable separately (per_item = True).

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return: e**(
gain
*variable
) / sum(e**(gain
*variable
)), filtered byouptput
specification.Parameters:  variable (1d np.array : default ClassDefaults.variable) – an array to be transformed.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: SoftMax transformation of variable
Return type: number or np.array

derivative
(output)¶ Calculate the derivative of
function
. If OUTPUT_TYPE for the SoftMax Function is ALL, return Jacobian matrix (derivative for each element of the output array with respect to each of the others):D_{j}S_{i} = S_{i}(𝜹_{i,j}  S_{j}), where 𝜹_{i,j}=1 if i=j and 𝜹_{i,j}=0 if i≠j.If OUTPUT_TYPE is MAX_VAL or MAX_INDICATOR, return 1d array of the derivatives of the maximum value with respect to the others (calculated as above). If OUTPUT_TYPE is PROB, raise an exception (since it is ambiguous as to which element would have been chosen by the SoftMax function)
Returns: derivative – derivative of values returns by SoftMax. Return type: 1d or 2d np.array (depending on OUTPUT_TYPE of SoftMax)

class
psyneulink.components.functions.function.
LinearMatrix
(default_variable, matrix=None, params=None, owner=None, name=None, prefs=None)¶ Matrix transform of variable:
Parameters:  variable (list or 1d np.array : default ClassDefaults.variable) – specifies a template for the value to be transformed; length must equal the number of rows of
matrix
.  matrix (number, list, 1d or 2d np.ndarray, np.matrix, function, or matrix keyword : default IDENTITY_MATRIX) –
specifies matrix used to transform
variable
(seematrix
for specification details).When LinearMatrix is the
function
of a projection: the matrix specification must be compatible with the variables of the
sender
andreceiver
 a matrix keyword specification generates a matrix based on the sender and receiver shapes
When LinearMatrix is instantiated on its own, or as the function of Mechanisms or States:
 the matrix specification must be compatible with the variables of the
 bounds (None) –
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ 1d np.array – contains value to be transformed.

matrix
¶ 2d np.array – matrix used to transform
variable
. Can be specified as any of the following: number  used as the filler value for all elements of the
matrix
(call to np.fill);  list of arrays, 2d np.array or np.matrix  assigned as the value of
matrix
;  matrix keyword  see
MatrixKeywords
for list of options.
Rows correspond to elements of the input array (outer index), and columns correspond to elements of the output array (inner index).
 number  used as the filler value for all elements of the

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

instantiate_matrix
(specification, context=None)¶ Implements matrix indicated by specification
Specification is derived from MATRIX param (passed to self.__init__ or self.function)
 Specification (validated in _validate_params):
 single number (used to fill self.matrix)
 matrix keyword (see get_matrix)
 2D list or np.ndarray of numbers
Return matrix: (2D list)

function
(variable=None, params=None, context=None)¶ 
Parameters:  variable (list or 1d np.array) – array to be transformed; length must equal the number of rows of ‘matrix <LinearMatrix.matrix>`.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: dot product of variable and matrix – length of the array returned equals the number of columns of
matrix
.Return type: 1d np.array
 variable (list or 1d np.array : default ClassDefaults.variable) – specifies a template for the value to be transformed; length must equal the number of rows of

class
psyneulink.components.functions.function.
Integrator
(default_variable=None, rate=1.0, noise=0.0, time_step_size=1.0, initializer, params=None, owner=None, prefs=None)¶ Integrate current value of
variable
with its prior value.Parameters:  default_variable (number, list or np.array : default ClassDefaults.variable) – specifies a template for the value to be integrated; if it is a list or array, each element is independently integrated.
 rate (float, list or 1d np.array : default 1.0) – specifies the rate of integration. If it is a list or array, it must be the same length as
variable
(seerate
for details).  noise (float, PsyNeuLink Function, list or 1d np.array : default 0.0) – specifies random value to be added in each call to
function
. (seenoise
for details).  time_step_size (float : default 0.0) – determines the timing precision of the integration process
 float, list or 1d np.array (initializer) – specifies starting value for integration. If it is a list or array, it must be the same length as
default_variable
(seeinitializer
for details).  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – current input value some portion of which (determined by
rate
) that will be added to the prior value; if it is an array, each element is independently integrated.

rate
¶ float or 1d np.array – determines the rate of integration based on current and prior values. If integration_type is set to ADAPTIVE, all elements must be between 0 and 1 (0 = no change; 1 = instantaneous change). If it has a single element, it applies to all elements of
variable
; if it has more than one element, each element applies to the corresponding element ofvariable
.

noise
¶ float, function, list, or 1d np.array – specifies random value to be added in each call to
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, whilevariable
is a list or array, noise will be applied to each variable element. In the case of a noise function, this means that the function will be executed separately for each variable element.Note that in the case of DIFFUSION, noise must be specified as a float (or list or array of floats) because this value will be used to construct the standard DDM probability distribution. For all other types of integration, in order to generate random noise, we recommend that you instead select a probability distribution function (see
Distribution Functions
for details), which will generate a new noise value from its distribution on each execution. If noise is specified as a float or as a function with a fixed output (or a list or array of these), then the noise will simply be an offset that remains the same across all executions.

initializer
¶ 1d np.array or list – determines the starting value for integration (i.e., the value to which
previous_value
is set.If initializer is a list or array, it must be the same length as
variable
. If initializer is specified as a single float or function, whilevariable
is a list or array, initializer will be applied to each variable element. In the case of an initializer function, this means that the function will be executed separately for each variable element.

initializers
¶ list – stores the names of the initialization attributes for each of the stateful attributes of the function. The index i item in initializers provides the initialization value for the index i item in
stateful_attributes
.

stateful_attributes
¶ list – stores the names of each of the stateful attributes of the function. The index i item in stateful_attributes is initialized by the value of the initialization attribute whose name is stored in index i of
initializers
. In most cases, the stateful_attributes, in that order, are the return values of the function.

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

reinitialize
(*args)¶ Effectively begins accumulation over again at the specified value(s).
If arguments are passed into the reinitialize method, then reinitialize sets each of the attributes in
stateful_attributes
to the value of the corresponding argument. Next, it sets thevalue
to a list containing each of the argument values.If reinitialize is called without arguments, then it sets each of the attributes in
stateful_attributes
to the value of the corresponding attribute ininitializers
. Next, it sets thevalue
to a list containing the values of each of the attributes ininitializers
.Often, the only attribute in
stateful_attributes
isprevious_value
and the only attribute ininitializers
isinitializer
, in which case the reinitialize method setsprevious_value
andvalue
to either the value of the argument (if an argument was passed into reinitialize) or the current value ofinitializer
.For specific types of Integrator functions, the reinitialize method may carry out other reinitialization steps.

class
psyneulink.components.functions.function.
SimpleIntegrator
(default_variable=None, rate=1.0, noise=0.0, initializer, params=None, owner=None, prefs=None)¶ Integrate current value of
variable
with its prior value:previous_value
+rate
*variable
+noise
;Parameters:  default_variable (number, list or np.array : default ClassDefaults.variable) – specifies a template for the value to be integrated; if it is a list or array, each element is independently integrated.
 rate (float, list or 1d np.array : default 1.0) – specifies the rate of integration. If it is a list or array, it must be the same length as
variable
(seerate
for details).  noise (float, PsyNeuLink Function, list or 1d np.array : default 0.0) – specifies random value to be added in each call to
function
. (seenoise
for details).  float, list or 1d np.array (initializer) – specifies starting value for integration. If it is a list or array, it must be the same length as
default_variable
(seeinitializer
for details).  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – current input value some portion of which (determined by
rate
) will be added to the prior value; if it is an array, each element is independently integrated.

rate
¶ float or 1d np.array – determines the rate of integration based on current and prior values. If it has a single element, it applies to all elements of
variable
; if it has more than one element, each element applies to the corresponding element ofvariable
.

noise
¶ float, function, list, or 1d np.array – specifies random value to be added in each call to
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 variable element. In the case of a noise function, this means that the function will be executed separately for each variable element.Note
In order to generate random noise, we recommend selecting a probability distribution function (see
Distribution Functions
for details), which will generate a new noise value from its distribution on each execution. If noise is specified as a float or as a function with a fixed output, then the noise will simply be an offset that remains the same across all executions.
 initializer : float, 1d np.array or list
determines the starting value for integration (i.e., the value to which
previous_value
is set.If initializer is a list or array, it must be the same length as
variable
. previous_value : 1d np.array : default ClassDefaults.variable
 stores previous value with which
variable
is integrated.  owner : Component
 component to which the Function has been assigned.
 name : str
 the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).
 prefs : PreferenceSet or specification dict : Function.classPreferences
 the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return:
variable
combined withprevious_value
according toprevious_value
+rate
*variable
+noise
;Parameters:  variable (number, list or np.array : default ClassDefaults.variable) – a single value or array of values to be integrated.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: updated value of integral
Return type: 2d np.array

class
psyneulink.components.functions.function.
ConstantIntegrator
(default_variable=None, rate=1.0, noise=0.0, scale: parameter_spec = 1.0, offset: parameter_spec = 0.0, initializer, params=None, owner=None, prefs=None)¶ Integrates prior value by adding
rate
andnoise
. (Ignoresvariable
).previous_value
+rate
+noise
Parameters:  default_variable (number, list or np.array : default ClassDefaults.variable) – specifies a template for the value to be integrated; if it is a list or array, each element is independently integrated.
 rate (float, list or 1d np.array : default 1.0) – specifies the rate of integration. If it is a list or array, it must be the same length as
variable
(seerate
for details).  noise (float, PsyNeuLink Function, list or 1d np.array : default 0.0) – specifies random value to be added in each call to
function
. (seenoise
for details).  float, list or 1d np.array (initializer) – specifies starting value for integration. If it is a list or array, it must be the same length as
default_variable
(seeinitializer
for details).  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array –
 Ignored by the ConstantIntegrator function. Refer to LCAIntegrator or AdaptiveIntegrator for integrator
 functions that depend on both a prior value and a new value (variable).

rate
¶ float or 1d np.array – determines the rate of integration.
If it has a single element, that element is added to each element of
previous_value
.If it has more than one element, each element is added to the corresponding element of
previous_value
.

noise
¶ float, function, list, or 1d np.array – specifies random value to be added in each call to
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 variable element. In the case of a noise function, this means that the function will be executed separately for each variable element.Note
In order to generate random noise, we recommend selecting a probability distribution function (see
Distribution Functions
for details), which will generate a new noise value from its distribution on each execution. If noise is specified as a float or as a function with a fixed output, then the noise will simply be an offset that remains the same across all executions.

initializer
¶ float, 1d np.array or list – determines the starting value for integration (i.e., the value to which
previous_value
is set.If initializer is a list or array, it must be the same length as
variable
.

previous_value
¶ 1d np.array : default ClassDefaults.variable – stores previous value to which
rate
andnoise
will be added.

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return: the sum of
previous_value
,rate
, andnoise
.Parameters: params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor. Returns: updated value of integral Return type: 2d np.array

class
psyneulink.components.functions.function.
Buffer
(default_variable=None, rate=None, noise=0.0, history=None, initializer, params=None, owner=None, prefs=None)¶ Appends
variable
to the end ofprevious_value
(i.e., rightappends) which is a deque of previous inputs. If specified, the values of the rate and noise arguments are applied to each item in the deque (including the newly added one) on each call, as follows:Note
Because rate and noise are applied on every call, their effects are cumulative over calls.
Parameters:  default_variable (number, list or np.array : default ClassDefaults.variable) – specifies a template for the value to be integrated; if it is a list or array, each element is independently integrated.
 rate (float : default None) – specifies a value applied to each item in the deque on each call.
 noise (float or Function : default 0.0) – specifies a random value added to each item in the deque on each call.
 history (int : default None) – specifies the maxlen of the deque, and hence
value
.  float, list or ndarray (initializer) – specifies a starting value for the deque; if none is specified, the deque is initialized with an empty list.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – current input value appended to the end of the deque.

rate
¶ float – value added to each item of the deque on each call.

noise
¶ float or Function – random value added to each item of the deque in each call.
Note
In order to generate random noise, a probability distribution function should be used (see
Distribution Functions
for details), which will generate a new noise value from its distribution on each execution. If noise is specified as a float or as a function with a fixed output, then the noise will simply be an offset that remains the same across all executions.

history
¶ int – determines maxlen of the deque and the value returned by the
function
. If appendingvariable
toprevious_value
exceeds history, the first item ofprevious_value
is deleted, andvariable
is appended to it, so thatvalue
maintains a constant length. If history is not specified, the value returned continues to be extended indefinitely.

initializer
¶ float, list or ndarray – the value assigned as the first item of the deque when the Function is initialized, or reinitialized if the new_previous_value argument is not specified in the call to
reinitialize
.

previous_value
¶ 1d np.array : default ClassDefaults.variable – state of the deque prior to appending
variable
in the current call.

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

reinitialize
(*args)¶ Clears the
previous_value
deque.If an argument is passed into reinitialize or if the
initializer
attribute contains a value besides [], then that value is used to start the newprevious_value
deque. Otherwise, the newprevious_value
deque starts out empty.value
takes on the same value asprevious_value
.

function
(variable=None, params=None, context=None)¶ Return:
previous_value
appended withvariable
*rate
+noise
;If the length of the result exceeds
history
, delete the first item.Parameters:  variable (number, list or np.array : default ClassDefaults.variable) – a single value or array of values to be integrated.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: updated value of deque
Return type: deque

class
psyneulink.components.functions.function.
AdaptiveIntegrator
(default_variable=None, rate=1.0, noise=0.0, scale: parameter_spec = 1.0, offset: parameter_spec = 0.0, initializer, params=None, owner=None, prefs=None)¶ Computes an exponentially weighted moving average.
(1 
rate
) *previous_value
+rate
*variable
+noise
Parameters:  default_variable (number, list or np.array : default ClassDefaults.variable) – specifies a template for the value to be integrated; if it is a list or array, each element is independently integrated.
 rate (float, list or 1d np.array : default 1.0) – specifies the smoothing factor of the EWMA. If it is a list or array, it must be the same length as
variable
(seerate
for details).  noise (float, PsyNeuLink Function, list or 1d np.array : default 0.0) – specifies random value to be added in each call to
function
. (seenoise
for details).  float, list or 1d np.array (initializer) – specifies starting value for integration. If it is a list or array, it must be the same length as
default_variable
(seeinitializer
for details).  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – current input value some portion of which (determined by
rate
) will be added to the prior value; if it is an array, each element is independently integrated.

rate
¶ float or 1d np.array – determines the smoothing factor of the EWMA. All rate elements must be between 0 and 1 (rate = 0 –> no change,
variable
is ignored; rate = 1 –>previous_value
is ignored).If rate is a float, it is applied to all elements of
variable
(andprevious_value
); if it has more than one element, each element is applied to the corresponding element ofvariable
(andprevious_value
).

noise
¶ float, function, list, or 1d np.array – specifies random value to be added in each call to
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 variable element. In the case of a noise function, this means that the function will be executed separately for each variable element.Note
In order to generate random noise, we recommend selecting a probability distribution function (see
Distribution Functions
for details), which will generate a new noise value from its distribution on each execution. If noise is specified as a float or as a function with a fixed output, then the noise will simply be an offset that remains the same across all executions.

initializer
¶ float, 1d np.array or list – determines the starting value for timeaveraging (i.e., the value to which
previous_value
is originally set).If initializer is a list or array, it must be the same length as
variable
.

previous_value
¶ 1d np.array : default ClassDefaults.variable – stores previous value with which
variable
is integrated.

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return: some fraction of
variable
combined with some fraction ofprevious_value
.Parameters:  variable (number, list or np.array : default ClassDefaults.variable) – a single value or array of values to be integrated.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: updated value of integral
Return type: 2d np.array

class
psyneulink.components.functions.function.
DriftDiffusionIntegrator
(default_variable=None, rate=1.0, noise=0.0, scale= 1.0, offset= 0.0, time_step_size=1.0, t0=0.0, decay=0.0, threshold=1.0 initializer, params=None, owner=None, prefs=None)¶ Accumulates evidence over time based on a stimulus, rate, previous position, and noise. Stops accumulating at a threshold.
Parameters:  default_variable (number, list or np.array : default ClassDefaults.variable) – specifies the stimulus component of drift rate – the drift rate is the product of variable and rate
 rate (float, list or 1d np.array : default 1.0) – specifies the attentional component of drift rate – the drift rate is the product of variable and rate
 noise (float, PsyNeuLink Function, list or 1d np.array : default 0.0) – scales the random value to be added in each call to
function
. (seenoise
for details).  time_step_size (float : default 0.0) – determines the timing precision of the integration process (see
time_step_size
for details.  t0 (float) – determines the start time of the integration process and is used to compute the RESPONSE_TIME output state of the DDM Mechanism.
 initializer (float, list or 1d np.array : default 0.0) – specifies starting value for integration. If it is a list or array, it must be the same length as
default_variable
(seeinitializer
for details).  threshold (float : default 0.0) –
specifies the threshold (boundaries) of the drift diffusion process (i.e., at which the integration process is assumed to terminate).
Once the magnitude of the decision variable has exceeded the threshold, the function will simply return the threshold magnitude (with the appropriate sign) for that execution and any future executions.
If the function is in a DDM mechanism, crossing the threshold will also switch the
is_finished
attribute from False to True. This attribute may be important for the Scheduler when usingConditions such asWhenFinished
.  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – current input value, which represents the stimulus component of drift.

rate
¶ float or 1d np.array – specifies the attentional component of drift rate – the drift rate is the product of variable and rate

noise
¶ float, function, list, or 1d np.array – scales the random value to be added in each call to `function <DriftDiffusionIntegrator.function> according to the standard DDM probability distribution.
On each call to
function <DriftDiffusionIntegrator.function>, :math:
sqrt{time_step_size cdot noise} cdot Sample,From,Normal,distribution` is added to the accumulated evidence.Noise must be specified as a float (or list or array of floats).

time_step_size
¶ float – determines the timing precision of the integration process and is used to scale the
noise
parameter according to the standard DDM probability distribution.

t0
¶ float – determines the start time of the integration process and is used to compute the RESPONSE_TIME output state of the DDM Mechanism.

initializer
¶ float, 1d np.array or list – determines the starting value for integration (i.e., the value to which
previous_value
is set.If initializer is a list or array, it must be the same length as
variable
.

previous_time
¶ float – stores previous time at which the function was executed and accumulates with each execution according to
time_step_size
.

previous_value
¶ 1d np.array : default ClassDefaults.variable – stores previous value with which
variable
is integrated.

threshold
¶ float : default 0.0 – when used properly determines the threshold (boundaries) of the drift diffusion process (i.e., at which the integration process is assumed to terminate).
If the system is assembled as follows, then the DriftDiffusionIntegrator function stops accumulating when its value reaches +threshold or threshold
 the function is used in the DDM mechanism
(2) the mechanism is part of a System with a Scheduler which applies the
WhenFinished
Condition to the mechanismOtherwise,
threshold
does not influence the function at all.

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return: One time step of evidence accumulation according to the Drift Diffusion Model
\[previous\_value + rate \cdot variable \cdot time\_step\_size + \sqrt{time\_step\_size \cdot noise} \cdot Sample\,from\,Normal\,Distribution\]Parameters:  variable (number, list or np.array : default ClassDefaults.variable) – specifies the stimulus component of drift rate – the drift rate is the product of variable and rate
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: updated value of integral
Return type: 2d np.array

class
psyneulink.components.functions.function.
OrnsteinUhlenbeckIntegrator
(default_variable=None, rate=1.0, noise=0.0, offset= 0.0, time_step_size=1.0, t0=0.0, decay=1.0, initializer=0.0, params=None, owner=None, prefs=None)¶ Accumulate evidence overtime based on a stimulus, noise, decay, and previous position.
Parameters:  default_variable (number, list or np.array : default ClassDefaults.variable) – specifies a template for the stimulus component of drift rate – the drift rate is the product of variable and rate
 rate (float, list or 1d np.array : default 1.0) – specifies the attentional component of drift rate – the drift rate is the product of variable and rate
 noise (float, PsyNeuLink Function, list or 1d np.array : default 0.0) – scales random value to be added in each call to
function
. (seenoise
for details).  time_step_size (float : default 0.0) – determines the timing precision of the integration process (see
time_step_size
for details.  t0 (float : default 0.0) – represents the starting time of the model and is used to compute
previous_time
 float, list or 1d np.array (initializer) – specifies starting value for integration. If it is a list or array, it must be the same length as
default_variable
(seeinitializer
for details).  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – represents the stimulus component of drift. The product of
variable
andrate
is multiplied bytime_step_size
to model the accumulation of evidence during one step.

rate
¶ float or 1d np.array – represents the attentional component of drift. The product of
rate
andvariable
is multiplied bytime_step_size
to model the accumulation of evidence during one step.

noise
¶ float, function, list, or 1d np.array – scales the random value to be added in each call to
function
Noise must be specified as a float (or list or array of floats) because this value will be used to construct the standard DDM probability distribution.

time_step_size
¶ float – determines the timing precision of the integration process and is used to scale the
noise
parameter appropriately.

initializer
¶ float, 1d np.array or list – determines the starting value for integration (i.e., the value to which
previous_value
is originally set.)If initializer is a list or array, it must be the same length as
variable
.

previous_value
¶ 1d np.array : default ClassDefaults.variable – stores previous value with which
variable
is integrated.

previous_time
¶ float – stores previous time at which the function was executed and accumulates with each execution according to
time_step_size
.

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return: One time step of evidence accumulation according to the Ornstein Uhlenbeck Model
previous_value + decay * (previous_value  rate * variable) + \(\sqrt{time_step_size * noise}\) * random sample from Normal distribution
Parameters: variable (number, list or np.array : default ClassDefaults.variable) – the stimulus component of drift rate in the Drift Diffusion Model.  params : Dict[param keyword: param value] : default None
 a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: updated value of integral Return type: 2d np.array

class
psyneulink.components.functions.function.
FHNIntegrator
(default_variable=1.0, scale: parameter_spec = 1.0, offset: parameter_spec = 0.0, initial_w=0.0, initial_v=0.0, time_step_size=0.05, t_0=0.0, a_v=1/3, b_v=0.0, c_v=1.0, d_v=0.0, e_v=1.0, f_v=1.0, threshold=1.0 time_constant_v=1.0, a_w=1.0, b_w=0.8, c_w=0.7, mode=1.0, uncorrelated_activity=0.0 time_constant_w = 12.5, integration_method="RK4" params=None, owner=None, prefs=None)¶ The FHN Integrator function in PsyNeuLink implements the FitzhughNagumo model using a choice of Euler or 4th Order RungeKutta numerical integration.
In order to support several common representations of the model, the FHNIntegrator includes many parameters, some of which would not be sensible to use in combination. The equations of the FitzhughNagumo model are expressed below in terms of all of the parameters exposed in PsyNeuLink:
Fast, Excitatory Variable:
\[\frac{dv}{dt} = \frac{a_v v^{3} + b_v v^{2} (1+threshold)  c_v v\, threshold + d_v + e_v\, previous_w + f_v\, variable)}{time\, constant_v}\]Slow, Inactivating Variable:
\[\frac{dw}{dt} = \frac{a_w\, mode\, previous_v + b_w w + c_w + uncorrelated\,activity\,(1mode)}{time\, constant_w}\]The three formulations that the FHNIntegrator was designed to allow are:
FitzhughNagumo Model
Fast, Excitatory Variable:
\[\frac{dv}{dt} = v  \frac{v^3}{3}  w + I_{ext}\]Slow, Inactivating Variable:
\[\frac{dw}{dt} = \frac{v + a  bw}{T}\]\(\frac{dw}{dt}\) often has the following parameter values:
\[\frac{dw}{dt} = 0.08\,(v + 0.7  0.8 w)\]How to implement this model in PsyNeuLink:
In PsyNeuLink, the default parameter values of the FHNIntegrator function implement the above equations.
Modified FHN Model
Fast, Excitatory Variable:
\[\frac{dv}{dt} = v(av)(v1)  w + I_{ext}\]Slow, Inactivating Variable:
\[\frac{dw}{dt} = bv  cw\]Mahbub Khan (2013) provides a nice summary of why this formulation is useful.
How to implement this model in PsyNeuLink:
In order to implement the modified FHN model, the following PsyNeuLink parameter values must be set in the equation for \(\frac{dv}{dt}\):
PNL Parameter a_v b_v c_v d_v e_v f_v time_constant_v Value 1.0 1.0 1.0 0.0 1.0 1.0 1.0 When the parameters above are set to the listed values, the PsyNeuLink equation for \(\frac{dv}{dt}\) reduces to the Modified FHN formulation, and the remaining parameters in the \(\frac{dv}{dt}\) equation correspond as follows:
PNL Parameter threshold
variable
Modified FHN Parameter a \(I_{ext}\) In order to implement the modified FHN model, the following PsyNeuLink parameter values must be set in the equation for \(\frac{dw}{dt}\):
PNL Parameter c_w mode time_constant_w uncorrelated_activity Value 0.0 1.0 1.0 0.0 When the parameters above are set to the listed values, the PsyNeuLink equation for \(\frac{dw}{dt}\) reduces to the Modified FHN formulation, and the remaining parameters in the \(\frac{dw}{dt}\) equation correspond as follows:
PNL Parameter a_w
NEGATIVE b_w
Modified FHN Parameter b c Modified FHN Model as implemented in Gilzenrat (2002)
Fast, Excitatory Variable:
[Eq. (6) in Gilzenrat (2002) ]
\[\tau_v \frac{dv}{dt} = v(av)(v1)  u + w_{vX_1}\, f(X_1)\]Slow, Inactivating Variable:
[Eq. (7) & Eq. (8) in Gilzenrat (2002) ]
\[\tau_u \frac{du}{dt} = Cv + (1C)\, d  u\]How to implement this model in PsyNeuLink:
In order to implement the Gilzenrat 2002 model, the following PsyNeuLink parameter values must be set in the equation for \(\frac{dv}{dt}\):
PNL Parameter a_v b_v c_v d_v e_v Value 1.0 1.0 1.0 0.0 1.0 When the parameters above are set to the listed values, the PsyNeuLink equation for \(\frac{dv}{dt}\) reduces to the Gilzenrat formulation, and the remaining parameters in the \(\frac{dv}{dt}\) equation correspond as follows:
PNL Parameter threshold
variable
f_v
time_constant_v
Gilzenrat Parameter a \(f(X_1)\) \(w_{vX_1}\) \(T_{v}\) In order to implement the Gilzenrat 2002 model, the following PsyNeuLink parameter values must be set in the equation for \(\frac{dw}{dt}\):
PNL Parameter a_w b_w c_w Value 1.0 1.0 0.0 When the parameters above are set to the listed values, the PsyNeuLink equation for \(\frac{dw}{dt}\) reduces to the Gilzenrat formulation, and the remaining parameters in the \(\frac{dw}{dt}\) equation correspond as follows:
PNL Parameter mode
uncorrelated_activity
time_constant_v
Gilzenrat Parameter C d \(T_{u}\)
Parameters:  default_variable (number, list or np.array : default ClassDefaults.variable) – specifies a template for the external stimulus
 initial_w (float, list or 1d np.array : default 0.0) – specifies starting value for integration of dw/dt. If it is a list or array, it must be the same length as
default_variable
 initial_v (float, list or 1d np.array : default 0.0) – specifies starting value for integration of dv/dt. If it is a list or array, it must be the same length as
default_variable
 time_step_size (float : default 0.1) – specifies the time step size of numerical integration
 t_0 (float : default 0.0) – specifies starting value for time
 a_v (float : default 1/3) – coefficient on the v^3 term of the dv/dt equation
 b_v (float : default 0.0) – coefficient on the v^2 term of the dv/dt equation
 c_v (float : default 1.0) – coefficient on the v term of the dv/dt equation
 d_v (float : default 0.0) – constant term in the dv/dt equation
 e_v (float : default 1.0) – coefficient on the w term in the dv/dt equation
 f_v (float : default 1.0) – coefficient on the external stimulus (
variable
) term in the dv/dt equation  time_constant_v (float : default 1.0) – scaling factor on the dv/dt equation
 a_w (float : default 1.0,) – coefficient on the v term of the dw/dt equation
 b_w (float : default 0.8,) – coefficient on the w term of the dv/dt equation
 c_w (float : default 0.7,) – constant term in the dw/dt equation
 threshold (float : default 1.0) – specifies a value of the input below which the LC will tend not to respond and above which it will
 mode (float : default 1.0) – coefficient which simulates electrotonic coupling by scaling the values of dw/dt such that the v term (representing the input from the LC) increases when the uncorrelated_activity term (representing baseline activity) decreases
 uncorrelated_activity (float : default 0.0) – constant term in the dw/dt equation
 time_constant_w (float : default 12.5) – scaling factor on the dv/dt equation
 integration_method (str : default "RK4") – selects the numerical integration method. Currently, the choices are: “RK4” (4th Order RungeKutta) or “EULER” (Forward Euler)
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – External stimulus

previous_v
¶ 1d np.array : default ClassDefaults.variable – stores accumulated value of v during integration

previous_w
¶ 1d np.array : default ClassDefaults.variable – stores accumulated value of w during integration

previous_t
¶ float – stores accumulated value of time, which is incremented by time_step_size on each execution of the function

initial_w
¶ float, list or 1d np.array : default 0.0 – specifies starting value for integration of dw/dt. If it is a list or array, it must be the same length as
default_variable

initial_v
¶ float, list or 1d np.array : default 0.0 – specifies starting value for integration of dv/dt. If it is a list or array, it must be the same length as
default_variable

time_step_size
¶ float : default 0.1 – specifies the time step size of numerical integration

t_0
¶ float : default 0.0 – specifies starting value for time

a_v
¶ float : default 1/3 – coefficient on the v^3 term of the dv/dt equation

b_v
¶ float : default 0.0 – coefficient on the v^2 term of the dv/dt equation

c_v
¶ float : default 1.0 – coefficient on the v term of the dv/dt equation

d_v
¶ float : default 0.0 – constant term in the dv/dt equation

e_v
¶ float : default 1.0 – coefficient on the w term in the dv/dt equation

f_v
¶ float : default 1.0 – coefficient on the external stimulus (
variable
) term in the dv/dt equation

time_constant_v
¶ float : default 1.0 – scaling factor on the dv/dt equation

a_w
¶ float : default 1.0 – coefficient on the v term of the dw/dt equation

b_w
¶ float : default 0.8 – coefficient on the w term of the dv/dt equation

c_w
¶ float : default 0.7 – constant term in the dw/dt equation

threshold
¶ float : default 1.0 – coefficient that scales both the v^2 [ (1+threshold)*v^2 ] and v [ (threshold)*v ] terms in the dv/dt equation under a specific formulation of the FHN equations, the threshold parameter behaves as a “threshold of excitation”, and has the following relationship with variable (the external stimulus):
 when the external stimulus is below the threshold of excitation, the system is either in a stable state, or will emit a single excitation spike, then reach a stable state. The behavior varies depending on the magnitude of the difference between the threshold and the stimulus.
 when the external stimulus is equal to or above the threshold of excitation, the system is unstable, and will emit many excitation spikes
 when the external stimulus is too far above the threshold of excitation, the system will emit some excitation spikes before reaching a stable state.

mode
¶ float : default 1.0 – coefficient which simulates electrotonic coupling by scaling the values of dw/dt such that the v term (representing the input from the LC) increases when the uncorrelated_activity term (representing baseline activity) decreases
float : default 0.0 – constant term in the dw/dt equation

time_constant_w
¶ float : default 12.5 – scaling factor on the dv/dt equation

prefs
¶ PreferenceSet or specification dict : default Function.classPreferences – the
PreferenceSet
for the Function (seeprefs
for details).

function
(variable=None, params=None, context=None)¶ Return: current v, current w
The model is defined by the following system of differential equations:
time_constant_v \(* \frac{dv}{dt} =\)
a_v \(* v^3 + (1 + threshold) *\) b_v \(* v^2 + ( threshold) *\) c_v \(* v^2 +\) d_v \(+\) e_v \(* w +\) f_v \(* I_{ext}\)time_constant_w \(* dw/dt =\)
\(mode *\) a_w \(* v +\) b_w \(* w +\) c_w \(+ (1  self.mode) *\) self.uncorrelated_activityParameters: params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor. Returns: current value of v , current value of w Return type: float, list, or np.array

class
psyneulink.components.functions.function.
AccumulatorIntegrator
(default_variable=None, rate=1.0, noise=0.0, scale: parameter_spec = 1.0, offset: parameter_spec = 0.0, initializer, params=None, owner=None, prefs=None)¶ Integrates prior value by multiplying
previous_value
byrate
and addingincrement
andnoise
. Ignoresvariable
).Parameters:  default_variable (number, list or np.array : default ClassDefaults.variable) – specifies a template for the value to be integrated; if it is a list or array, each element is independently integrated.
 rate (float, list or 1d np.array : default 1.0) – specifies the multiplicative decrement of
previous_value
(i.e., the rate of exponential decay). If it is a list or array, it must be the same length asvariable
.  increment (float, list or 1d np.array : default 0.0) – specifies an amount to be added to
previous_value
in each call tofunction
(seeincrement
for details). If it is a list or array, it must be the same length asvariable
(seeincrement
for details).  noise (float, PsyNeuLink Function, list or 1d np.array : default 0.0) – specifies random value to be added to
prevous_value
in each call tofunction
. If it is a list or array, it must be the same length asvariable
(seenoise
for details).  float, list or 1d np.array (initializer) – specifies starting value for integration. If it is a list or array, it must be the same length as
default_variable
(seeinitializer
for details).  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – Ignored by the AccumulatorIntegrator function. Refer to LCAIntegrator or AdaptiveIntegrator for integrator functions that depend on both a prior value and a new value (variable).

rate
¶ float or 1d np.array – determines the multiplicative decrement of
previous_value
(i.e., the rate of exponential decay) in each call tofunction
. If it is a list or array, it must be the same length asvariable
and each element is used to multiply the corresponding element ofprevious_value
(i.e., it is used for Hadamard multiplication). If it is a scalar or has a single element, its value is used to multiply all the elements ofprevious_value
.

increment
¶ float, function, list, or 1d np.array – determines the amount added to
previous_value
in each call tofunction
. If it is a list or array, it must be the same length asvariable
and each element is added to the corresponding element ofprevious_value
(i.e., it is used for Hadamard addition). If it is a scalar or has a single element, its value is added to all the elements ofprevious_value
.

noise
¶ float, function, list, or 1d np.array – determines a random value to be added in each call to
function
. If it is a list or array, it must be the same length asvariable
and each element is added to the corresponding element ofprevious_value
(i.e., it is used for Hadamard addition). If it is a scalar or has a single element, its value is added to all the elements ofprevious_value
. If it is a function, it will be executed separately and added to each element.Note
In order to generate random noise, a probability distribution function should be selected (see
Distribution Functions
for details), which will generate a new noise value from its distribution on each execution. If noise is specified as a float or as a function with a fixed output, then the noise will simply be an offset that remains the same across all executions.

initializer
¶ float, 1d np.array or list – determines the starting value for integration (i.e., the value to which
previous_value
is set. If initializer is a list or array, it must be the same length asvariable
.

previous_value
¶ 1d np.array : default ClassDefaults.variable – stores previous value to which
rate
andnoise
will be added.

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return:
previous_value
combined withrate
andnoise
.Parameters: params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor. Returns: updated value of integral Return type: 2d np.array

class
psyneulink.components.functions.function.
LCAIntegrator
(default_variable=None, noise=0.0, initializer=0.0, rate=1.0, offset=None, time_step_size=0.1, params=None, owner=None, prefs=None)¶ Integrate current value of
variable
with its prior value:\[rate \cdot previous\_value + variable + noise \sqrt{time\_step\_size}\]Parameters:  default_variable (number, list or np.array : default ClassDefaults.variable) – specifies a template for the value to be integrated; if it is a list or array, each element is independently integrated.
 rate (float, list or 1d np.array : default 1.0) – scales the contribution of
previous_value
to the accumulation of thevalue
on each time step  noise (float, PsyNeuLink Function, list or 1d np.array : default 0.0) – specifies random value to be added in each call to
function
. (seenoise
for details).  initializer (float, list or 1d np.array : default 0.0) – specifies starting value for integration. If it is a list or array, it must be the same length as
default_variable
(seeinitializer
for details).  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – current input value some portion of which (determined by
rate
) will be added to the prior value; if it is an array, each element is independently integrated.

rate
¶ float or 1d np.array – scales the contribution of
previous_value
to the accumulation of thevalue
on each time step. If rate has a single element, it applies to all elements ofvariable
; if rate has more than one element, each element applies to the corresponding element ofvariable
.

noise
¶ float, function, list, or 1d np.array – specifies a value to be added in each call to
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 variable element. In the case of a noise function, this means that the function will be executed separately for each variable element.Note
In order to generate random noise, we recommend selecting a probability distribution function (see
Distribution Functions
for details), which will generate a new noise value from its distribution on each execution. If noise is specified as a float or as a function with a fixed output, then the noise will simply be an offset that remains the same across all executions.

initializer
¶ float, 1d np.array or list – determines the starting value for integration (i.e., the value to which
previous_value
is set.If initializer is a list or array, it must be the same length as
variable
.

previous_value
¶ 1d np.array : default ClassDefaults.variable – stores previous value with which
variable
is integrated.

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return:
\[rate \cdot previous\_value + variable + noise \sqrt{time\_step\_size}\]Parameters:  variable (number, list or np.array : default ClassDefaults.variable) – a single value or array of values to be integrated.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: updated value of integral
Return type: 2d np.array

class
psyneulink.components.functions.function.
AGTUtilityIntegrator
(default_variable=None, rate=1.0, noise=0.0, scale: parameter_spec = 1.0, offset: parameter_spec = 0.0, initializer, initial_short_term_utility = 0.0, initial_long_term_utility = 0.0, short_term_gain = 1.0, long_term_gain =1.0, short_term_bias = 0.0, long_term_bias=0.0, short_term_rate=1.0, long_term_rate=1.0, params=None, owner=None, prefs=None)¶ Computes an exponentially weighted moving average on the variable using two sets of parameters:
short_term_utility =
long_term_utility =
then takes the logistic of each utility value, using the corresponding (short term and long term) gain and bias.
Finally, computes a single value which combines the two values according to:
value = [1short_term_utility_logistic]*long_term_utility_logistic
Parameters:  rate (float, list or 1d np.array : default 1.0) – specifies the overall smoothing factor of the EWMA used to combine the long term and short term utility values
 noise (float, PsyNeuLink Function, list or 1d np.array : default 0.0) – TBI?
 initial_short_term_utility (float : default 0.0) – specifies starting value for integration of short_term_utility
 initial_long_term_utility (float : default 0.0) – specifies starting value for integration of long_term_utility
 short_term_gain (float : default 1.0) – specifies gain for logistic function applied to short_term_utility
 long_term_gain (float : default 1.0) – specifies gain for logistic function applied to long_term_utility
 short_term_bias (float : default 0.0) – specifies bias for logistic function applied to short_term_utility
 long_term_bias (float : default 0.0) – specifies bias for logistic function applied to long_term_utility
 short_term_rate (float : default 1.0) – specifies smoothing factor of EWMA filter applied to short_term_utility
 long_term_rate (float : default 1.0) – specifies smoothing factor of EWMA filter applied to long_term_utility
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or np.array – current input value used in both the short term and long term EWMA computations

noise
¶ float, PsyNeuLink Function, list or 1d np.array : default 0.0 – TBI?

initial_short_term_utility
¶ float : default 0.0 – specifies starting value for integration of short_term_utility

initial_long_term_utility
¶ float : default 0.0 – specifies starting value for integration of long_term_utility

short_term_gain
¶ float : default 1.0 – specifies gain for logistic function applied to short_term_utility

long_term_gain
¶ float : default 1.0 – specifies gain for logistic function applied to long_term_utility

short_term_bias
¶ float : default 0.0 – specifies bias for logistic function applied to short_term_utility

long_term_bias
¶ float : default 0.0 – specifies bias for logistic function applied to long_term_utility

short_term_rate
¶ float : default 1.0 – specifies smoothing factor of EWMA filter applied to short_term_utility

long_term_rate
¶ float : default 1.0 – specifies smoothing factor of EWMA filter applied to long_term_utility

previous_short_term_utility
¶ 1d np.array – stores previous value with which
variable
is integrated using the EWMA filter and short term parameters

previous_long_term_utility
¶ 1d np.array – stores previous value with which
variable
is integrated using the EWMA filter and long term parameters

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return: some fraction of
variable
combined with some fraction ofprevious_value
.Parameters:  variable (number, list or np.array : default ClassDefaults.variable) – a single value or array of values to be integrated.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: updated value of integral
Return type: 2d np.array

reinitialize
(short=None, long=None)¶ Effectively begins accumulation over again at the specified utilities.
Sets
previous_short_term_utility
to the quantity specified in the first argument andprevious_long_term_utility
to the quantity specified in the second argument.Sets
value
by computing it based on the newly updated values forprevious_short_term_utility
andprevious_long_term_utility
.If no arguments are specified, then the current values of
initial_short_term_utility
andinitial_long_term_utility
are used.

class
psyneulink.components.functions.function.
BogaczEtAl
(default_variable=None, drift_rate=1.0, threshold=1.0, starting_point=0.0, t0=0.2 noise=0.5, params=None, owner=None, prefs=None)¶ Return terminal value of decision variable, mean accuracy, and mean response time computed analytically for the drift diffusion process as described in Bogacz et al (2006).
Parameters:  default_variable (number, list or np.array : default ClassDefaults.variable) – specifies a template for decision variable(s); if it is list or array, a separate solution is computed independently for each element.
 drift_rate (float, list or 1d np.array : default 1.0) – specifies the drift_rate of the drift diffusion process. If it is a list or array,
it must be the same length as
default_variable
.  threshold (float, list or 1d np.array : default 1.0) – specifies the threshold (boundary) of the drift diffusion process. If it is a list or array,
it must be the same length as
default_variable
.  starting_point (float, list or 1d np.array : default 1.0) – specifies the initial value of the decision variable for the drift diffusion process. If it is a list or
array, it must be the same length as
default_variable
.  noise (float, list or 1d np.array : default 0.0) – specifies the noise term (corresponding to the diffusion component) of the drift diffusion process.
If it is a float, it must be a number from 0 to 1. If it is a list or array, it must be the same length as
default_variable
and all elements must be floats from 0 to 1.  t0 (float, list or 1d np.array : default 0.2) – specifies the nondecision time for solution. If it is a float, it must be a number from 0 to 1. If it is a
list or array, it must be the same length as
default_variable
and all elements must be floats from 0 to 1.  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ number or 1d np.array – holds initial value assigned to
default_variable
argument; ignored byfunction
.

drift_rate
¶ float or 1d np.array – determines the drift component of the drift diffusion process.

threshold
¶ float or 1d np.array – determines the threshold (boundary) of the drift diffusion process (i.e., at which the integration process is assumed to terminate).

starting_point
¶ float or 1d np.array – determines the initial value of the decision variable for the drift diffusion process.

noise
¶ float or 1d np.array – determines the diffusion component of the drift diffusion process (used to specify the variance of a Gaussian random process).

t0
¶ float or 1d np.array – determines the assumed nondecision time to determine the response time returned by the solution.

bias
¶ float or 1d np.array – normalized starting point: (
starting_point
+threshold
) / (2 *threshold
)

name
¶ str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

function
(variable=None, params=None, context=None)¶ Return: terminal value of decision variable (equal to threshold), mean accuracy (error rate; ER) and mean response time (RT)
Parameters:  variable (2d np.array) – ignored.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: Decision variable, mean ER, mean RT
Return type: (float, float, float)

derivative
(output, input)¶ Calculate the derivative of \(\frac{1}{reward rate}\) with respect to the threshold (output arg) and drift_rate (input arg). Reward rate (\(RR\)) is assumed to be:
\(RR = delay_{ITI} + \frac{Z}{A} + ED\);the derivative of \(\frac{1}{RR}\) with respect to the
threshold
is:\(\frac{1}{A}  \frac{E}{A}  2\frac{A}{c^2}ED\);and the derivative of 1/RR with respect to the
drift_rate
is:\(\frac{Z}{A^2} + \frac{Z}{A^2}E  \frac{2Z}{c^2}ED\)where:
A =
drift_rate
,Z =
threshold
,c =
noise
,E = \(e^{2\frac{ZA}{c^2}}\),
D = \(delay_{ITI} + delay_{penalty}  \frac{Z}{A}\),
\(delay_{ITI}\) is the intertrial interval and \(delay_{penalty}\) is a penalty delay.
Returns: derivatives – of \(\frac{1}{RR}\) with respect to threshold
anddrift_rate
.Return type: List[float, float)
Note
Use of this Function requires that the MatLab engine is installed.
Parameters:  default_variable (number, list or np.array : default ClassDefaults.variable) – specifies a template for decision variable(s); if it is list or array, a separate solution is computed independently for each element.
 drift_rate (float, list or 1d np.array : default 1.0) – specifies the drift_rate of the drift diffusion process. If it is a list or array,
it must be the same length as
default_variable
.  threshold (float, list or 1d np.array : default 1.0) – specifies the threshold (boundary) of the drift diffusion process. If it is a list or array,
it must be the same length as
default_variable
.  starting_point (float, list or 1d np.array : default 1.0) – specifies the initial value of the decision variable for the drift diffusion process. If it is a list or
array, it must be the same length as
default_variable
.  noise (float, list or 1d np.array : default 0.0) – specifies the noise term (corresponding to the diffusion component) of the drift diffusion process.
If it is a float, it must be a number from 0 to 1. If it is a list or array, it must be the same length as
default_variable
and all elements must be floats from 0 to 1.  t0 (float, list or 1d np.array : default 0.2) – specifies the nondecision time for solution. If it is a float, it must be a number from 0 to 1. If it is a
list or array, it must be the same length as
default_variable
and all elements must be floats from 0 to 1.  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).
number or 1d np.array – holds initial value assigned to
default_variable
argument; ignored byfunction
.
float or 1d np.array – determines the drift component of the drift diffusion process.
float or 1d np.array – determines the threshold (bound) of the drift diffusion process (i.e., at which the integration process is assumed to terminate).
float or 1d np.array – determines the initial value of the decision variable for the drift diffusion process.
float or 1d np.array – determines the diffusion component of the drift diffusion process (used to specify the variance of a Gaussian random process).
float or 1d np.array – determines the assumed nondecision time to determine the response time returned by the solution.
float or 1d np.array – normalized starting point: (
starting_point
+threshold
) / (2 *threshold
)
Component – component to which the Function has been assigned.
str – the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).
PreferenceSet or specification dict : Function.classPreferences – the
PreferenceSet
for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).
Return: terminal value of decision variable, mean accuracy (error rate; ER), mean response time (RT), correct RT mean, correct RT variance and correct RT skew. Requires that the MatLab engine is installed.
Parameters:  variable (2d np.array) – ignored.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: Decision variable, mean ER, mean RT, correct RT mean, correct RT variance, correct RT skew
Return type: (float, float, float, float, float, float)

class
psyneulink.components.functions.function.
NormalDist
(mean=0.0, standard_dev=1.0, params=None, owner=None, prefs=None)¶ Return a random sample from a normal distribution using numpy.random.normal
Parameters:  mean (float : default 0.0) – The mean or center of the normal distribution
 standard_dev (float : default 1.0) – Standard deviation of the normal distribution. Must be > 0.0
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

mean
¶ float : default 0.0 – The mean or center of the normal distribution

standard_dev
¶ float : default 1.0 – Standard deviation of the normal distribution. Must be > 0.0

params
¶ Dict[param keyword: param value] : default None – a parameter dictionary that specifies the parameters for the function. 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 Function.

prefs
¶ PreferenceSet or specification dict : default Function.classPreferences – specifies the
PreferenceSet
for the Function (seeprefs
for details).

class
psyneulink.components.functions.function.
UniformToNormalDist
(mean=0.0, standard_dev=1.0, params=None, owner=None, prefs=None)¶ Return a random sample from a normal distribution using first np.random.rand(1) to generate a sample from a uniform distribution, and then converting that sample to a sample from a normal distribution with the following equation:
\[normal\_sample = \sqrt{2} \cdot standard\_dev \cdot scipy.special.erfinv(2 \cdot uniform\_sample  1) + mean\]The uniform –> normal conversion allows for a more direct comparison with MATLAB scripts.
Note
This function requires SciPy.
(https://github.com/jonasrauber/randnmatlabpython)
Parameters:  mean (float : default 0.0) – The mean or center of the normal distribution
 standard_dev (float : default 1.0) – Standard deviation of the normal distribution
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

mean
¶ float : default 0.0 – The mean or center of the normal distribution

standard_dev
¶ float : default 1.0 – Standard deviation of the normal distribution

params
¶ Dict[param keyword: param value] : default None – a parameter dictionary that specifies the parameters for the function. 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 Function.

prefs
¶ PreferenceSet or specification dict : default Function.classPreferences – specifies the
PreferenceSet
for the Function (seeprefs
for details).

class
psyneulink.components.functions.function.
ExponentialDist
(beta=1.0, params=None, owner=None, prefs=None)¶ Return a random sample from a exponential distribution using numpy.random.exponential
Parameters:  beta (float : default 1.0) – The scale parameter of the exponential distribution
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

beta
¶ float : default 1.0 – The scale parameter of the exponential distribution

params
¶ Dict[param keyword: param value] : default None – a parameter dictionary that specifies the parameters for the function. 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 Function.

prefs
¶ PreferenceSet or specification dict : default Function.classPreferences – specifies the
PreferenceSet
for the Function (seeprefs
for details).

class
psyneulink.components.functions.function.
UniformDist
(low=0.0, high=1.0, params=None, owner=None, prefs=None)¶ Return a random sample from a uniform distribution using numpy.random.uniform
Parameters:  low (float : default 0.0) – Lower bound of the uniform distribution
 high (float : default 1.0) – Upper bound of the uniform distribution
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

low
¶ float : default 0.0 – Lower bound of the uniform distribution

high
¶ float : default 1.0 – Upper bound of the uniform distribution

params
¶ Dict[param keyword: param value] : default None – a parameter dictionary that specifies the parameters for the function. 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 Function.

prefs
¶ PreferenceSet or specification dict : default Function.classPreferences – specifies the
PreferenceSet
for the Function (seeprefs
for details).

class
psyneulink.components.functions.function.
GammaDist
(scale=1.0, dist_shape=1.0, params=None, owner=None, prefs=None)¶ Return a random sample from a gamma distribution using numpy.random.gamma
Parameters:  scale (float : default 1.0) – The scale of the gamma distribution. Should be greater than zero.
 dist_shape (float : default 1.0) – The shape of the gamma distribution. Should be greater than zero.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

scale
¶ float : default 1.0 – The dist_shape of the gamma distribution. Should be greater than zero.

dist_shape
¶ float : default 1.0 – The scale of the gamma distribution. Should be greater than zero.

params
¶ Dict[param keyword: param value] : default None – a parameter dictionary that specifies the parameters for the function. 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 Function.

prefs
¶ PreferenceSet or specification dict : default Function.classPreferences – specifies the
PreferenceSet
for the Function (seeprefs
for details).

class
psyneulink.components.functions.function.
WaldDist
(scale=1.0, mean=1.0, params=None, owner=None, prefs=None)¶ Return a random sample from a Wald distribution using numpy.random.wald
Parameters:  scale (float : default 1.0) – Scale parameter of the Wald distribution. Should be greater than zero.
 mean (float : default 1.0) – Mean of the Wald distribution. Should be greater than or equal to zero.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 prefs (PreferenceSet or specification dict : default Function.classPreferences) – the
PreferenceSet
for the Function. If it is not specified, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

scale
¶ float : default 1.0 – Scale parameter of the Wald distribution. Should be greater than zero.

mean
¶ float : default 1.0 – Mean of the Wald distribution. Should be greater than or equal to zero.

params
¶ Dict[param keyword: param value] : default None – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.

prefs
¶ PreferenceSet or specification dict : default Function.classPreferences – the
PreferenceSet
for the Function. If it is not specified, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

class
psyneulink.components.functions.function.
Stability
(default_variable=None, matrix='HollowMatrix', metric: <typecheck.tc_predicates.any object at 0x1035bcbe0> = 'energy', transfer_fct: <typecheck.framework.optional object at 0x1035bccc0> = None, normalize: bool = False, params=None, owner=None, prefs: <function is_pref_set at 0x103bf0a60> = None)¶ Stability( default_variable=None, matrix=HOLLOW_MATRIX, metric=ENERGY transfer_fct=None normalize=False, params=None, owner=None, prefs=None )
Return the stability of
variable
based on a state transformation matrix.The value of
variable
is passed through thematrix
, transformed using thetransfer_fct
(if specified), and then compared with its initial value using thedistance metric
specified bymetric
. Ifnormalize
isTrue
, the result is normalized by the length of (number of elements in)variable
. variable : list of numbers or 1d np.array : Default ClassDefaults.variable
 the array for which stability is calculated.
 matrix : list, np.ndarray, np.matrix, function keyword, or MappingProjection : default HOLLOW_MATRIX
 specifies the matrix of recurrent weights; must be a square matrix with the same width as the
length of
variable
.  metric : keyword in DistanceMetrics : Default ENERGY
 specifies a
metric
fromDistanceMetrics
used to compute stability.  transfer_fct : function or method : Default None
 specifies the function used to transform output of weight
matrix
.  normalize : bool : Default False
 specifies whether to normalize the stability value by the length of
variable
.  params : Dict[param keyword: param value] : default None
 a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner : Component
 component to which to assign the Function.
 name : str : default see
name
 specifies the name of the Function.
 prefs : PreferenceSet or specification dict : default Function.classPreferences
 specifies the
PreferenceSet
for the Function (seeprefs
for details).
 variable : 1d np.array
 array for which stability is calculated.
 matrix : list, np.ndarray, np.matrix, function keyword, or MappingProjection : default HOLLOW_MATRIX
 weight matrix from each element of
variable
to each other; if a matrix other than HOLLOW_MATRIX is assigned, it is convolved with HOLLOW_MATRIX to eliminate selfconnections from the stability calculation.  metric : keyword in DistanceMetrics
 metric used to compute stability; must be a
DistanceMetrics
keyword. TheDistance
Function is used to compute the stability ofvariable
with respect to its value after its transformation bymatrix
andtransfer_fct
.  transfer_fct : function or method
 function used to transform output of weight
matrix
prior to computing stability.  normalize : bool
 if
True
, result of stability calculation is normalized by the length ofvariable
.  params : Dict[param keyword: param value] : default None
 a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner : Component
 component to which to assign the Function.
 prefs : PreferenceSet or specification dict : default Function.classPreferences
 specifies the
PreferenceSet
for the Function (seeprefs
for details).

function
(variable=None, params=None, context=None)¶ Calculate the stability of
variable
.Compare the value of
variable
with its value after transformation bymatrix
andtransfer_fct
(if specified), using the specifiedmetric
. Ifnormalize
isTrue
, the result is divided by the length ofvariable
.Returns: stability Return type: scalar

class
psyneulink.components.functions.function.
Distance
(default_variable=None, metric=EUCLIDEAN normalize=False, params=None, owner=None, prefs=None)¶ Return the distance between the vectors in the two items of
variable
using thedistance metric
specified in themetric
attribute. Ifnormalize
isTrue
, the result is normalized by the length of (number of elements in)variable
.Parameters:  variable (2d np.array with two items : Default ClassDefaults.variable) – the arrays between which the distance is calculated.
 metric (keyword in DistancesMetrics : Default EUCLIDEAN) – specifies a
distance metric
used to compute the distance between the two items invariable
.  normalize (bool : Default False) – specifies whether to normalize the distance by the length of
variable
.  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ 2d np.array with two items – contains the arrays between which the distance is calculated.

metric
¶ keyword in DistanceMetrics – determines the
metric
used to compute the distance between the two items invariable
.

params
¶ Dict[param keyword: param value] : default None – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.

prefs
¶ PreferenceSet or specification dict : default Function.classPreferences – specifies the
PreferenceSet
for the Function (seeprefs
for details).

function
(variable=None, params=None, context=None)¶ Calculate the distance between the two vectors in
variable
.Use the
distance metric
specified inmetric
to calculate the distance. Ifnormalize
isTrue
, the result is divided by the length ofvariable
.Returns: distance Return type: scalar

class
psyneulink.components.functions.function.
LearningFunction
(default_variable, params, function=None, owner=None, name=None, prefs=None, context=None)¶ Abstract class of Function used for learning.

class
psyneulink.components.functions.function.
Hebbian
(default_variable=None, learning_rate=None, params=None, name=None, prefs=None)¶ Implements a function that calculates a matrix of weight changes using the Hebbian (correlational) learning rule.
Parameters:  variable (List[number] or 1d np.array : default ClassDefaults.variable) – specifies the activation values, the pairwise products of which are used to generate the a weight change matrix.
 learning_rate (scalar or list, 1d or 2d np.array, or np.matrix of numeric values: default default_learning_rate) – specifies the learning rate used by the
function
; supersedes any specification for the Process and/or System to which the function’sowner
belongs (seelearning_rate
for details).  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ 1d np.array – activation values, the pairwise products of which are used to generate the weight change matrix returned by the
function
.

learning_rate
¶ float, 1d or 2d np.array – used by the
function
to scale the weight change matrix returned by thefunction
. If specified, it supersedes any learning_rate specified for theProcess
and/or System to which the function’sowner
belongs. If it is a scalar, it is multiplied by the weight change matrix; if it is a 1d np.array, it is multiplied Hadamard (elementwise) by thevariable
<Hebbian.variable>` before calculating the weight change matrix; if it is a 2d np.array, it is multiplied Hadamard (elementwise) by the weight change matrix; if it isNone
, then thelearning_rate
specified for the Process to which theowner
belongs is used; and, if that isNone
, then thelearning_rate
for the System to which it belongs is used. If all areNone
, then thedefault_learning_rate
is used.

default_learning_rate
¶ float – the value used for the
learning_rate
if it is not otherwise specified.

function
¶ function – calculates the pairwise product of all elements in the
variable
, and then scales that by thelearning_rate
to generate the weight change matrix returned by the function.

prefs
¶ PreferenceSet or specification dict : default Function.classPreferences – the
PreferenceSet
for the Function (seeprefs
for details).

function
(variable=None, params=None, context=None) Calculate a matrix of weight changes from a 1d array of activity values using Hebbian learning function.
The weight change matrix is calculated as:
learning_rate * \(a_ia_j\) if \(i \neq j\), else \(0\)where \(a_i\) and \(a_j\) are elements of
variable
.Parameters:  variable (List[number] or 1d np.array : default ClassDefaults.variable) – array of activity values, the pairwise products of which are used to generate a weight change matrix.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: weight change matrix – matrix of pairwise products of elements of
variable
scaled by thelearning_rate
, with all diagonal elements = 0 (i.e., hollow matix).Return type: 2d np.array

class
psyneulink.components.functions.function.
ContrastiveHebbian
(default_variable=None, learning_rate=None, params=None, name=None, prefs=None)¶ Implements a function that calculates a matrix of weight changes using the ContrastiveHebbian learning rule.
Parameters:  variable (List[number] or 1d np.array : default ClassDefaults.variable) – specifies the activation values, the pairwise products of which are used to generate the a weight change matrix.
 learning_rate (scalar or list, 1d or 2d np.array, or np.matrix of numeric values: default default_learning_rate) – specifies the learning rate used by the
function
; supersedes any specification for the Process and/or System to which the function’sowner
belongs (seelearning_rate
for details).  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ 1d np.array – activation values, the pairwise products of which are used to generate the weight change matrix returned by the
function
.

learning_rate
¶ float, 1d or 2d np.array – used by the
function
to scale the weight change matrix returned by thefunction
. If specified, it supersedes any learning_rate specified for theProcess
and/or System to which the function’sowner
belongs. If it is a scalar, it is multiplied by the weight change matrix; if it is a 1d np.array, it is multiplied Hadamard (elementwise) by thevariable
<ContrastiveHebbian.variable>` before calculating the weight change matrix; if it is a 2d np.array, it is multiplied Hadamard (elementwise) by the weight change matrix; if it isNone
, then thelearning_rate
specified for the Process to which theowner
belongs is used; and, if that isNone
, then thelearning_rate
for the System to which it belongs is used. If all areNone
, then thedefault_learning_rate
is used.

default_learning_rate
¶ float – the value used for the
learning_rate
if it is not otherwise specified.

function
¶ function – calculates the pairwise product of all elements in the
variable
, and then scales that by thelearning_rate
to generate the weight change matrix returned by the function.

prefs
¶ PreferenceSet or specification dict : default Function.classPreferences – the
PreferenceSet
for the Function (seeprefs
for details).

function
(variable=None, params=None, context=None) Calculate a matrix of weight changes from a 1d array of activity values using ContrastiveHebbian learning function.
The weight change matrix is calculated as:
Parameters:  variable (List[number] or 1d np.array : default ClassDefaults.variable) – array of activity values, the pairwise products of which are used to generate a weight change matrix.
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: weight change matrix – matrix of pairwise products of elements of
variable
scaled by thelearning_rate
, with all diagonal elements = 0 (i.e., hollow matix).Return type: 2d np.array

class
psyneulink.components.functions.function.
Reinforcement
(default_variable=None, learning_rate=None, params=None, name=None, prefs=None)¶ Implements a function that returns an error term for a single item in an input array, scaled by the learning_rate.
Reinforcement takes an array with a single nonzero value (
activation_output
), and returns an array of the same length with the single nonzero value replaced by theerror_signal
scaled by thelearning_rate
. The nonzero item inactivation_output
can be thought of as the predicted likelihood of a stimulus or value of an action, and theerror_signal
as the error in the prediction for that value.Note
To preserve compatibility with other LearningFunctions:
 the variable argument of both the constructor and calls to the Reinforcement
function
must have three items, although only the 2nd and 3rd items are used (for theactivation_output
anderror_signal
attributes, respectively);
 the Reinforcement
function
returns two copies of the error array (the first is a “placemarker”, where a matrix of weights changes is often returned).
Parameters:  variable (List or 2d np.array [length 3 in axis 0] : default ClassDefaults.variable) –
template for the three items provided as the variable in the call to the
function
(in order):activation_input
(1d np.array);activation_output
(1d np.array with a single nonzero value);error_signal
(1d np.array with a single value).
 learning_rate (float : default default_learning_rate) – supersedes any specification for the Process and/or System to which the function’s
owner
belongs (seelearning_rate
for details).  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

activation_input
¶ 1d np.array – first item of
variable
; this is not used (it is implemented for compatibility with otherLearningFunctions
).

activation_output
¶ 1d np.array – an array containing a single “prediction” or “action” value as one of its elements, the remainder of which are zero.

error_signal
¶ 1d np.array – contains a single item, specifying the error associated with the nonzero item in
activation_output
.

learning_rate
¶ float – the learning rate used by the function. If specified, it supersedes any learning_rate specified for the
Process
and/or System to which the function’sowner
belongs. If it isNone
, then thelearning_rate
specified for the Process to which theowner
belongs is used; and, if that isNone
, then thelearning_rate
for the System to which it belongs is used. If all areNone
, then thedefault_learning_rate
is used.

default_learning_rate
¶ float – the value used for the
learning_rate
if it is not otherwise specified.

function
¶ function – the function that computes the weight change matrix, and returns that along with the
error_signal
received.

prefs
¶ PreferenceSet or specification dict : default Function.classPreferences – the
PreferenceSet
for the Function (seeprefs
for details).

function
(variable=None, params=None, context=None, **kwargs) Return an error array for the specified item of activation_output scaled by the learning_rate.
Returns a 1d error array with a single nonzero value in the same position as the nonzero item in
activation_output
(2nd item of the variable argument), that is theerror_signal
(3rd item of variable argument) scaled by thelearning_rate
.Note
In order to preserve compatibilty with other
LearningFunctions
: variable must have three items, although only the 2nd and 3rd are used;
function
returns two copies of the error array.
Parameters:  variable (List or 2d np.array [length 3 in axis 0] : default ClassDefaults.variable) –
must have three items that are the values for (in order):
activation_input
(not used),activation_output
(1d np.array with a single nonzero value),error_signal
(1d np.array with a single item).
 params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns: error array – Two copies of a 1d array with a single nonzero error term.
Return type: List[1d np.array, 1d np.array]
 the variable argument of both the constructor and calls to the Reinforcement

class
psyneulink.components.functions.function.
BackPropagation
(default_variable=None, activation_derivative_fct=Logistic().derivative, learning_rate=None, params=None, name=None, prefs=None)¶ Implements a
function
that calculate a matrix of weight changes using the backpropagationlearning algorithm. The weight change matrix is computed as:
weight_change_matrix =
learning_rate
*activation_input
* \(\frac{\delta E}{\delta W}\)where:
\(\frac{\delta E}{\delta W}\) = \(\frac{\delta E}{\delta A} * \frac{\delta A}{\delta W}\)
is the derivative of theerror_signal
with respect to the weights;\(\frac{\delta E}{\delta A}\) =
error_matrix
\(\cdot\)error_signal
is the derivative of the error with respect toactivation_output
(i.e., the weighted contribution to theerror_signal
of each unit that receives activity from the weight matrix being learned); and\(\frac{\delta A}{\delta W}\) =
activation_derivative_fct
(input =activation_input
, output =activation_output
)is the derivative of the activation function responsible for generatingactivation_output
at the point that generates each of its entries.The values of
activation_input
,activation_output
anderror_signal
are specified as items of thevariable
both in the constructor for the BackPropagation Function, and in calls to itsfunction
. Althougherror_matrix
is not specified in the constructor, it is required as an argument of thefunction
; it is assumed that it’s value is determined in context at the time of execution (e.g., by a LearningMechanism that uses the BackPropagation LearningFunction).The BackPropagation
function
returns the weight_change_matrix as well as \(\frac{\delta E}{\delta W}\).Parameters:  variable (List or 2d np.array [length 3 in axis 0] : default ClassDefaults.variable) – specifies a template for the three items provided as the variable in the call to the
function
(in order):activation_input
(1d np.array),activation_output
(1d np.array),error_signal
(1d np.array).  activation_derivative_fct (Function or function) – specifies the derivative for the function of the Mechanism that generates
activation_output
.  learning_rate (float : default default_learning_rate) – supersedes any specification for the Process and/or System to which the function’s
owner
belongs (seelearning_rate
for details).  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
 owner (Component) – component to which to assign the Function.
 name (str : default see
name
) – specifies the name of the Function.  prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).

variable
¶ 2d np.array – contains the three values used as input to the
function
:activation_input
,activation_output
, anderror_signal
.

activation_input
¶ 1d np.array – the input to the matrix being modified; same as 1st item of
variable
.

activation_output
¶ 1d np.array – the output of the function for which the matrix being modified provides the input; same as 2nd item of
variable
.

activation_derivative_fct
¶ Function or function – the derivative for the function of the Mechanism that generates
activation_output
.

error_signal
¶ 1d np.array – the error signal for the next matrix (layer above) in the learning sequence, or the error computed from the target (training signal) and the output of the last Mechanism in the sequence; same as 3rd item of
variable
.

error_matrix
¶ 2d np.array or ParameterState – matrix, the input of which is
activation_output
and the output of which is used to calculate theerror_signal
; if it is a ParameterState, it refers to the MATRIX parameterState of the MappingProjection being learned.

learning_rate
¶ float – the learning rate used by the function. If specified, it supersedes any learning_rate specified for the
process
and/orsystem
to which the function’sowner
belongs. If it isNone
, then the learning_rate specified for the process to which theowner
belongs is used; and, if that isNone
, then the learning_rate for the system to which it belongs is used. If all areNone
, then thedefault_learning_rate
is used.

default_learning_rate
¶ float – the value used for the
learning_rate
if it is not otherwise specified.

function
¶ function – the function that computes the weight change matrix, and returns that along with the
error_signal
received, weighted by the contribution made by each element ofactivation_output
as a function of theerror_matrix
.

prefs
¶ PreferenceSet or specification dict : default Function.classPreferences – the
PreferenceSet
for the Function (seeprefs
for details).

function
(variable=None, error_matrix=None, params=None, context=None, **kwargs) Calculate and return a matrix of weight changes from arrays of inputs, outputs and error terms.
Note that both variable and error_matrix must be specified for the function to execute.
Parameters:  variable (List or 2d np.array [length 3 in axis 0]) – must have three items that are the values for (in order):
activation_input
(1d np.array),activation_output
(1d np.array),error_signal
(1d np.array).  error_matrix (List, 2d np.array, np.matrix, ParameterState, or MappingProjection) – matrix of weights that were used to generate the
error_signal
(3rd item ofvariable
fromactivation_output
; its dimensions must be the length ofactivation_output
(rows) x length oferror_signal
(cols).  params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
Returns:  weight change matrix (2d np.array) – the modifications to make to the matrix.
 weighted error signal (1d np.array) –
error_signal
, weighted by the contribution made by each element ofactivation_output
as a function oferror_matrix
.
 variable (List or 2d np.array [length 3 in axis 0]) – must have three items that are the values for (in order):
 variable (List or 2d np.array [length 3 in axis 0] : default ClassDefaults.variable) – specifies a template for the three items provided as the variable in the call to the

class
psyneulink.components.functions.function.
TDLearning
(default_variable=array([[0], [0], [0]]), learning_rate=0.05, params=None, owner=None, prefs=None)¶ This class is used to implement temporal difference learning via the
Reinforcement
function. SeeReinforcement
for class details.