Functions

Example function:
Combination Functions:
TransferMechanism 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 or bias of a Logistic 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 its function. 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 user-written 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 its function is also assigned as the the function attribute of the Component to which it has been assigned (i.e., its owner.

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 for the Mechanism when it is executed.

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’s function

ADDITIVE

assign the value of the ModulatorySignal to the ADDITIVE_PARAM of the State’s function

OVERRIDE

assign the value of the ModulatorySignal directly to the State’s value (ignoring its variable and function)

DISABLE

ignore the ModulatorySignal when calculating the State’s value

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 (see prefs 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’s ClassDefaults.variable.

function

function – called by the Function’s owner when it is executed.

owner

Componentcomponent 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 using classPreferences 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 or False 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 (see prefs 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.

owner

Componentcomponent 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 using classPreferences 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 0x104d4cc80> = 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 the function 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’s function. 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 the custom_function function can be verified by adding a print(variable) or print(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 of my_mech is defined in the size argument of its constructor as having a single item (a 1d array of length 3; (see size). 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 of variable 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 use variable, as the variable 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 its input argument, that it assigns to the frequency and t 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 the variable of all Components are converted to a 2d array).

my_sinusoidal_fct also has two other arguments, phase and amplitude. When it is assigned to my_wave_mech, those parameters are assigned to ParameterStates of my_wave_mech, which that be used to modify their values by ControlSignals (see example 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 the function for my_mech, but with the default values of its phase and amplitude 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 of my_sinusoidal_fct be 1.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 assigns my_sinusoidal_fct to the function of an OutputState of my_mech, rather the Mechanism’s function:

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

Sinusoid function

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 and amplitude parameters of my_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/or multiplicative_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 (see prefs for details).
variable: value
format and default value of the function “wrapped” by the UDF.
custom_function : function
the user-specified 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 using classPreferences defined in __init__.py (see PreferenceSet for details).
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 in variable; if it is 2d, the length of each item must be the same as those in variable, and there must be the same number of items as there are in variable (see weights 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 in variable; if it is 2d, the length of each item must be the same as those in variable, and there must be the same number of items as there are in variable (see exponents for details)
  • operation (SUM or PRODUCT : default SUM) – specifies whether to sum or multiply the elements in variable of function.
  • scale (float) – specifies a value by which to multiply each element of the output of function (see scale for details)
  • offset (float) – specifies a value to add to each element of the output of function (see offset 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 (see prefs 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 of function are summmed or multiplied.

scale

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

offset

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

owner

Componentcomponent 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 using classPreferences 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, apply scale and/or offset, 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 in variable, and there must be the same number of items as there are in variable (see weights 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 in variable; if it is 2d, the length of each item must be the same as those in variable, and there must be the same number of items as there are in variable (see exponents 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 in variable.
  • scale (float or np.ndarray : default None) – specifies a value by which to multiply each element of the result of function (see scale for details)
  • offset (float or np.ndarray : default None) – specifies a value to add to each element of the result of function (see offset 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 (see prefs 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 and offset. If it is 2d, the arrays (all of which must be of equal length) are weighted and/or exponentiated as specified by weights and/or exponents and then combined as specified by operation.

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 of variable; if it is a 2d array, then each array is multiplied elementwise (i.e., the Hadamard Product is taken) with the corresponding array of variable. All weights 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 of variable; if it is a 2d array, the element of each array is used to exponentiate the corresponding element of the corresponding array of variable. In either case, all exponents are applied after application of the weights (if any are specified).

operation

SUM or PRODUCT – determines whether the function takes the elementwise (Hadamard) sum or product of the arrays in variable.

scale

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

offset

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

owner

Componentcomponent 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 using classPreferences defined in __init__.py (see PreferenceSet for details).

function(variable=None, params=None, context=None)

Apply weights and/or exponents to the arrays in variable, then take their sum or product (as specified by operation), apply scale and/or offset, 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.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 to None; if it has at least one bound, the attribute is set to a tuple specifying the lower and upper bounds, respectively, with None as the entry for no bound.

multiplicative_param and additive_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 and intercept implement the IDENTITY_FUNCTION

Parameters:
  • 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 applying slope.
  • 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 (see prefs 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 the intercept (if it is specified).

intercept

float – value added to each element of variable after applying the slope (if it is specified).

bounds

None

owner

Componentcomponent 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 using classPreferences 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

derivative()

Derivative of function.

Returns:derivative – current value of slope.
Return type:number
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 (see prefs for details).
variable

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

rate

float – value by which variable is multiplied before exponentiation.

scale

float – value by which the exponentiated value is multiplied.

bounds

(0, None)

owner

Componentcomponent 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 using classPreferences 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

derivative(input)

Derivative of function.

Returns:derivativerate * input.
Return type:number
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 applying gain and before logistic transformation.
  • offset (float : default 0.0) – specifies a value to add to each element of variable after applying gain 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 (see prefs 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 the bias (if it is specified).

bias

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

bounds

(0,1)

owner

Componentcomponent 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 using classPreferences 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

derivative(output)

Derivative of function.

Returns:derivative – output * (1 - output).
Return type:number
class psyneulink.components.functions.function.OneHot(default_variable, mode=MAX_VAL, params=None, owner=None, name=None, prefs=None)

Return an array with one non-zero value.

The mode parameter determines the nature of the non-zero 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 non-zero value in the array returned by function (see mode 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 (see prefs 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 non-zero 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.
owner

Componentcomponent 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 using classPreferences defined in __init__.py (see PreferenceSet for details).

function(variable=None, params=None, context=None)

Return array of len(variable) with single non-zero value specified by mode.

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 non-zero value

Return type:

np.array

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 (see output 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 (see prefs 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 SoftMax-transformed values of the elements in variable are reported in the array returned by function:

  • ALL: array of all SoftMax-transformed values (the default);
  • MAX_VAL: SoftMax-transformed value for the element with the maximum such value, 0 for all others;
  • MAX_INDICATOR: 1 for the element with the maximum SoftMax-transformed value, 0 for all others;
  • PROB: probabilistically chosen element based on SoftMax-transformed values after normalizing the sum of values to 1 (i.e., their Luce Ratio), 0 for all others.
bounds

None if output == MAX_VAL, else (0,1) : default (0,1)

owner

Componentcomponent 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 using classPreferences defined in __init__.py (see PreferenceSet for details).

function(variable=None, params=None, context=None)

Return: e**(gain * variable) / sum(e**(gain * variable)), filtered by ouptput 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):

DjSi = Si(𝜹i,j - Sj), 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:

function returns dot product of variable and matrix.
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 (see matrix for specification details).

    When LinearMatrix is the function of a projection:

    • the matrix specification must be compatible with the variables of the sender and receiver
    • 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 function’s own variable
    • if matrix is not specified, a square identity matrix is generated based on the number of columns in variable
    • matrix keywords are not valid matrix specifications
  • 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 (see prefs 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).

owner

Componentcomponent 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 using classPreferences 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)

Return: variablematrix

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

class psyneulink.components.functions.function.Integrator(default_variable=None, rate: <function parameter_spec at 0x104de0d90> = 1.0, noise=0.0, initializer=None, params: <typecheck.framework.optional object at 0x1043d8f98> = None, owner=None, prefs: <function is_pref_set at 0x104d4cc80> = None, context=None)
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 (see rate 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. (see noise 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 (see initializer 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 (see prefs 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 of variable.

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 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, while variable 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.

previous_value

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

owner

Componentcomponent 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 using classPreferences defined in __init__.py (see PreferenceSet for details).

reinitialize(new_previous_value=None, **kwargs)

Effectively begins accumulation over again at the specified value.

Sets

to the quantity specified.

For specific types of Integrator functions, additional values, such as initial time, must be specified, and additional attributes are reset.

If no arguments are specified, then the instance default for initializer is used.

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 (see rate 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. (see noise 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 (see initializer 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 (see prefs 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 of variable.

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 using classPreferences defined in __init__.py (see PreferenceSet for details).
function(variable=None, params=None, context=None)

Return: variable combined with previous_value according to previous_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.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 the value 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. (see noise 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 (see initializer 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 (see prefs 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 the value on each time step. If rate has a single element, it applies to all elements of variable; if rate has more than one element, each element applies to the corresponding element of variable.

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.

owner

Componentcomponent 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 using classPreferences 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.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 and noise. (Ignores variable).

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 (see rate 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. (see noise 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 (see initializer 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 (see prefs 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 and noise will be added.

owner

Componentcomponent 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 using classPreferences defined in __init__.py (see PreferenceSet for details).

function(variable=None, params=None, context=None)

Return: the sum of previous_value, rate, and noise.

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.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 (see rate 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. (see noise 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 (see initializer 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 (see prefs 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 (and previous_value); if it has more than one element, each element is applied to the corresponding element of variable (and 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 time-averaging (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.

owner

Componentcomponent 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 using classPreferences defined in __init__.py (see PreferenceSet for details).

function(variable=None, params=None, context=None)

Return: some fraction of variable combined with some fraction of previous_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. (see noise 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 (see initializer 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 using

  • 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 (see prefs 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

  1. 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 mechanism

Otherwise, threshold does not influence the function at all.

owner

Componentcomponent 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 using classPreferences 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

reinitialize(new_previous_value=None, new_previous_time=None)

In effect, begins accumulation over again at the original starting point and time, or new ones.

Sets

to the value specified in the first argument.

Sets previous_time to the value specified in the second argument.

If no arguments are specified, then the instance defaults for initializer and t0 are used.

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. (see noise 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 (see initializer 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 (see prefs for details).
variable

number or np.array – represents the stimulus component of drift. The product of variable and rate is multiplied by time_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 and variable is multiplied by time_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.

owner

Componentcomponent 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 using classPreferences 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
reinitialize(new_previous_value=None, new_previous_time=None)

In effect, begins accumulation over again at the original starting point and time, or new ones.

Sets

to the value specified in the first argument.

Sets previous_time to the value specified in the second argument.

If no arguments are specified, then the instance defaults for initializer and t0 are used.

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 Fitzhugh-Nagumo model using a choice of Euler or 4th Order Runge-Kutta 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 Fitzhugh-Nagumo 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\,(1-mode)}{time\, constant_w}\]

The three formulations that the FHNIntegrator was designed to allow are:

  1. Fitzhugh-Nagumo 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.

  2. Modified FHN Model

    Fast, Excitatory Variable:

    \[\frac{dv}{dt} = v(a-v)(v-1) - 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
  3. Modified FHN Model as implemented in Gilzenrat (2002)

    Fast, Excitatory Variable:

    [Eq. (6) in Gilzenrat (2002) ]

    \[\tau_v \frac{dv}{dt} = v(a-v)(v-1) - u + w_{vX_1}\, f(X_1)\]

    Slow, Inactivating Variable:

    [Eq. (7) & Eq. (8) in Gilzenrat (2002) ]

    \[\tau_u \frac{du}{dt} = Cv + (1-C)\, 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 Runge-Kutta) 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 (see prefs 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

owner

Componentcomponent to which the Function has been assigned.

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

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

prefs

PreferenceSet or specification dict : default Function.classPreferences – the PreferenceSet for the Function (see prefs 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_activity
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:current value of v , current value of w
Return type:float, list, or np.array
reinitialize(new_previous_v=None, new_previous_w=None, new_previous_time=None)

Effectively begins accumulation over again at the specified v, w, and time.

Sets

  • previous_v
  • initial_v

to the quantity specified in the first argument.

Sets

  • previous_w
  • initial_w

to the quantity specified in the second argument.

Sets previous_time to the quantity specified in the third argument.

If no arguments are specified, then the instance defaults for initial_v, initial_w and t_0 are used.

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 by rate and adding increment and noise. Ignores variable).

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 as variable.
  • increment (float, list or 1d np.array : default 0.0) – specifies an amount to be added to previous_value in each call to function (see increment for details). If it is a list or array, it must be the same length as variable (see increment 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 to function. If it is a list or array, it must be the same length as variable (see noise 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 (see initializer 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 (see prefs for details).
variable

number or np.arrayIgnored 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 to function. If it is a list or array, it must be the same length as variable and each element is used to multiply the corresponding element of previous_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 of previous_value.

increment

float, function, list, or 1d np.array – determines the amount added to previous_value in each call to function. If it is a list or array, it must be the same length as variable and each element is added to the corresponding element of previous_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 of previous_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 as variable and each element is added to the corresponding element of previous_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 of previous_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 as variable.

previous_value

1d np.array : default ClassDefaults.variable – stores previous value to which rate and noise will be added.

owner

Componentcomponent 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 using classPreferences defined in __init__.py (see PreferenceSet for details).

function(variable=None, params=None, context=None)

Return: previous_value combined with rate and noise.

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.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 = [1-short_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 (see prefs 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

owner

Componentcomponent 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 using classPreferences defined in __init__.py (see PreferenceSet for details).

function(variable=None, params=None, context=None)

Return: some fraction of variable combined with some fraction of previous_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

to the quantity specified in the first argument.

Sets

to the quantity specified in the second argument.

sets value by computing it based on the newly updated values for previous_short_term_utility and previous_long_term_utility.

If no arguments are specified, then the instance defaults for initial_short_term_utility and initial_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 non-decision 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 (see prefs for details).
variable

number or 1d np.array – holds initial value assigned to default_variable argument; ignored by function.

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 non-decision time to determine the response time returned by the solution.

bias

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

owner

Componentcomponent 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 using classPreferences 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 and drift_rate.
Return type:List[float, float)
class psyneulink.components.functions.function.NavarroAndFuss(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)

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 non-decision 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 (see prefs for details).
variable

number or 1d np.array – holds initial value assigned to default_variable argument; ignored by function.

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 (bound) 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 non-decision time to determine the response time returned by the solution.

bias

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

owner

Componentcomponent 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 using classPreferences defined in __init__.py (see PreferenceSet for details).

function(variable=None, params=None, context=None)

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 (see prefs 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.

owner

Componentcomponent 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 (see prefs 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/randn-matlab-python)

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 (see prefs 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.

owner

Componentcomponent 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 (see prefs 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 (see prefs 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.

owner

Componentcomponent 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 (see prefs 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 (see prefs 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.

owner

Componentcomponent 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 (see prefs 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 (see prefs 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.

owner

Componentcomponent 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 (see prefs 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 using classPreferences 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.

owner

Componentcomponent 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 using classPreferences 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 0x104520748> = 'energy', transfer_fct: <typecheck.framework.optional object at 0x104520828> = None, normalize: bool = False, params=None, owner=None, prefs: <function is_pref_set at 0x104d4cc80> = 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 the matrix, transformed using the transfer_fct (if specified), and then compared with its initial value using the distance metric specified by metric. If normalize is True, 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 from DistanceMetrics 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 (see prefs 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 self-connections from the stability calculation.
metric : keyword in DistanceMetrics
metric used to compute stability; must be a DistanceMetrics keyword. The Distance Function is used to compute the stability of variable with respect to its value after its transformation by matrix and transfer_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 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.
prefs : PreferenceSet or specification dict : default Function.classPreferences
specifies the PreferenceSet for the Function (see prefs for details).
function(variable=None, params=None, context=None)

Calculate the stability of variable.

Compare the value of variable with its value after transformation by matrix and transfer_fct (if specified), using the specified metric. If normalize is True, the result is divided by the length of variable.

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 the distance metric specified in the metric attribute. If normalize is True, 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 in variable.
  • 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 (see prefs 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 in variable.

normalize

bool – determines whether the distance is normalized 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

Componentcomponent to which to assign the Function.

prefs

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

function(variable=None, params=None, context=None)

Calculate the distance between the two vectors in variable.

Use the distance metric specified in metric to calculate the distance. If normalize is True, the result is divided by the length of variable.

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 pair-wise 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’s owner belongs (see learning_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 (see prefs for details).
variable

1d np.array – activation values, the pair-wise 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 the function. If specified, it supersedes any learning_rate specified for the Process and/or System to which the function’s owner 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 the variable <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 is None, then the learning_rate specified for the Process to which the owner belongs is used; and, if that is None, then the learning_rate for the System to which it belongs is used. If all are None, then the default_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 the learning_rate to generate the weight change matrix returned by the function.

owner

ComponentMechanism to which the Function belongs.

prefs

PreferenceSet or specification dict : default Function.classPreferences – the PreferenceSet for the Function (see prefs 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 the learning_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 non-zero value (activation_output), and returns an array of the same length with the single non-zero value replaced by the error_signal scaled by the learning_rate. The non-zero item in activation_output can be thought of as the predicted likelihood of a stimulus or value of an action, and the error_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 the activation_output and error_signal attributes, respectively);
  • the Reinforcement function returns two copies of the error array (the first is a “place-marker”, 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):

  • learning_rate (float : default default_learning_rate) – supersedes any specification for the Process and/or System to which the function’s owner belongs (see learning_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 (see prefs for details).
variable

2d np.array

specifies three values used as input to the function:

activation_input

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

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 non-zero 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’s owner belongs. If it is None, then the learning_rate specified for the Process to which the owner belongs is used; and, if that is None, then the learning_rate for the System to which it belongs is used. If all are None, then the default_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.

owner

ComponentMechanism to which the Function belongs.

prefs

PreferenceSet or specification dict : default Function.classPreferences – the PreferenceSet for the Function (see prefs 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 non-zero value in the same position as the non-zero item in activation_output (2nd item of the variable argument), that is the error_signal (3rd item of variable argument) scaled by the learning_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):

  • 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 non-zero error term.

Return type:

List[1d np.array, 1d np.array]

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 backpropagation

learning 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 the error_signal with respect to the weights;

\(\frac{\delta E}{\delta A}\) = error_matrix \(\cdot\) error_signal

is the derivative of the error with respect to activation_output (i.e., the weighted contribution to the error_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 generating activation_output at the point that generates each of its entries.

The values of activation_input, activation_output and error_signal are specified as items of the variable both in the constructor for the BackPropagation Function, and in calls to its function. Although error_matrix is not specified in the constructor, it is required as an argument of the function; 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 (see learning_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 (see prefs for details).
variable

2d np.array – contains the three values used as input to the function: activation_input, activation_output, and error_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 the error_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/or system to which the function’s owner belongs. If it is None, then the learning_rate specified for the process to which the owner belongs is used; and, if that is None, then the learning_rate for the system to which it belongs is used. If all are None, then the default_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 of activation_output as a function of the error_matrix.

owner

ComponentMechanism to which the Function belongs.

prefs

PreferenceSet or specification dict : default Function.classPreferences – the PreferenceSet for the Function (see prefs 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:
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 of activation_output as a function of error_matrix.

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. See Reinforcement for class details.