TransferFunctions¶

Deterministic

Identity
Linear
Exponential
Logistic
Tanh
ReLU
Gaussian

Probabilistic

GaussianDistort
BinomialDistort
Dropout
SoftMax

Other

Angle
TransferWithCosts

Overview¶

TransferFunctions transform their variable but maintain its shape. There are two subclasses of TransferFunctions – Deterministic and `Probabilistic <Probabilistic> – that have specialized attributes and/or methods.

Standard Attributes¶

All TransferFunctions have a range attribute that specifies the lower and upper limits of the function’s result. For some subclasses, this may be modified by other parameters. In addition, all TransferFunctions have a pair of modulable parameters as described below.

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

Derivatives¶

Most TransferFunctions have a derivative method. These take both an input and output argument. In general, the input is used to compute the derivative of the function at that value. If that is not provided, some Functions can compute the derivative using the function’s output, either directly (such as Logistic.derivative) or by inferring the input from the output and then computing the derivative for that value (such as ReLU.derivative)

TranferFunction Class References¶

class psyneulink.core.components.functions.nonstateful.transferfunctions.Angle(default_variable=None, params=None, owner=None, prefs=None)¶

function returns Angle transform of vector in variable:

Parameters:

default_variable (1array : default class_defaults.variable) – specifies a template for the value to be transformed; length must be at least 2.
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¶

contains value to be transformed.

Type:: 1d array

owner¶

component to which the Function has been assigned.

Type:: Component

name¶

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

Type:: str

prefs¶

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 Preferences for details).

Type:: PreferenceSet or specification dict : Function.classPreferences

class Parameters(owner, parent=None)¶

variable¶

see variable

Default value:: numpy.array([0.,0,])
Type:: numpy.ndarray
Read only:: True

class psyneulink.core.components.functions.nonstateful.transferfunctions.BinomialDistort(default_variable=None, p=None, seed=None, params=None, owner=None, prefs=None)¶

function returns variable with elements randomly zeroed with probability p:

\[\begin{split}if \ \ rand[0,1] > p: output_i=0 \\ else: \ output_i = variable_i\end{split}\]

derivative returns variable

Parameters:

default_variable (number or array : default class_defaults.variable) – specifies a template for the value(s) used as the mean of the Guassian distribution from which each sample is drawn.
p (float : default 0.5) – specifies the probability with which each element of variable is replaced with 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).

variable¶

each element determines mean of the Gaussian distribution from which each sample is drawn.

Type:: number or array

p¶

the probability with which each element of variable is replaced with zero.

Type:: float

random_state¶

private pseudorandom number generator

Type:: numpy.RandomState

owner¶

component to which the Function has been assigned.

Type:: Component

name¶

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

Type:: str

prefs¶

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 Preferences for details).

Type:: PreferenceSet or specification dict : Function.classPreferences

class Parameters(owner, parent=None)¶

p¶

see p

Default value:: 0.5
Type:: float

random_state¶

see random_state

Default value:: None
Type:: numpy.random.RandomState

class psyneulink.core.components.functions.nonstateful.transferfunctions.Dropout(default_variable=None, p=None, params=None, owner=None, prefs=None)¶

function returns variable with elements randomly zeroed with probability p during learning; otherwise functions as Identity Function. During learning, the output of the function is scaled by \(\frac{1}{(1-p)}\), which implements the inverse scaling form of dropout used by by PyTorch.

\[\begin{split}if \ (context.runmode == ContextFlags.LEARNING\_MODE) \ and \ (rand[0,1] > p): output_i = 0 \\ else: \ output_i = \frac{1}{(1-p)}variable_i\end{split}\]

derivative returns variable

Parameters:

default_variable (number or array : default class_defaults.variable) – specifies a template for the value to be transformed.
p (float : default 0.5) – specifies the probability with which each element of variable is replaced with 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).

variable¶

contains value to be transformed.

Type:: number or array

p¶

the probability with which each element of variable is replaced with zero.

Type:: float

random_state¶

private pseudorandom number generator

Type:: numpy.RandomState

owner¶

component to which the Function has been assigned.

Type:: Component

name¶

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

Type:: str

prefs¶

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 Preferences for details).

Type:: PreferenceSet or specification dict : Function.classPreferences

class Parameters(owner, parent=None)¶

p¶

see p

Default value:: 0.5
Type:: float

random_state¶

see random_state

Default value:: None
Type:: numpy.random.RandomState

derivative(input)¶

Derivative of function at input.

Parameters:

input (number or array) – value of the input to the Dropouput function at which derivative is to be taken.

Returns:

variable (number or array)

class psyneulink.core.components.functions.nonstateful.transferfunctions.Exponential(default_variable=None, rate=None, bias=None, scale=None, offset=None, params=None, owner=None, prefs=None)¶

function returns exponential transform of variable:

\[scale * e^{rate*variable+bias} + offset\]

derivative returns the derivative of the Exponential Function:

\[scale*rate*(input+bias)*e^{rate*input+bias}\]

Parameters:

default_variable (number or array : default class_defaults.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.
bias (float : default 0.0) – specifies a value to add to variable after multplying by rate and before exponentiation.
scale (float : default 1.0) – specifies the value by which the result of the function is multiplied, before offset is added.
offset (float : default 0.0) – specifies the value added to the result of the function after scale has been applied.
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¶

contains value to be transformed.

Type:: number or array

rate¶

value by which variable is multiplied before exponentiation; assigned as MULTILICATIVE_PARAM of the Exponential Function.

Type:: float

bias¶

value added to variable after multiplying by rate and before exponentiation; assigned as ADDITIVE_PARAM of the Exponential Function.

Type:: float

range¶

modified by scale if they are specified.

Type:: (0, None)

scale¶

determines the value by which the result of the function is multiplied, before offset is added.

Type:: float

offset¶

determines the value added to the result of the function after scale has been applied.

Type:: float

owner¶

component to which the Function has been assigned.

Type:: Component

name¶

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

Type:: str

prefs¶

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 Preferences for details).

Type:: PreferenceSet or specification dict : Function.classPreferences

class Parameters(owner, parent=None)¶

bias¶

see bias

Default value:: 0.0
Type:: float

rate¶

see rate

Default value:: 1.0
Type:: float

derivative(input)¶

Parameters:

input (number) – value of the input to the Exponential transform at which derivative is to be taken.
input. (Derivative of function at)

Returns:

derivative

Return type:

number or array

class psyneulink.core.components.functions.nonstateful.transferfunctions.Gaussian(default_variable=None, standard_deviation=None, bias=None, scale=None, offset=None, params=None, owner=None, prefs=None, **kwargs)¶

function returns Gaussian transform of variable:

\[scale*\frac{e^{-\frac{(varible-bias)^{2}}{2\sigma^{2}}}}{\sqrt{2\pi}\sigma}+offset\]

where \(\sigma\) = standard_deviation

Note

the value returned is deterministic (i.e., the value of the probability density function at variable), not a randomly chosen sample from the Gaussian distribution; for the latter, use GaussianDistort.

derivative returns derivative of the Gaussian transform of variable:

\[\frac{-(variable-bias)*e^{-\frac{(variable-bias)^{2}}{2\sigma^{2}}}}{\sqrt{2\pi}\sigma^{3}}\]

Parameters:

default_variable (number or array : default class_defaults.variable) – specifies a template for the value used as the mean for the Guassian transform.
standard_deviation (float : default 1.0) – specifies “width” of the Gaussian transform applied to each element of variable.
bias (float : default 0.0) – value to add to each element of variable before applying Gaussian transform.
scale (float : default 1.0) – specifies the value by which the result of the function is multiplied, before offset is added.
offset (float : default 0.0) – specifies the value added to the result of the function after scale has been applied.
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 used as the mean of the Gaussian transform.

Type:: number or array

standard_deviation¶

standard_deviation used for Gaussian transform.

Type:: float : default 1.0

bias¶

value added to each element of variable before applying the Gaussian transform.

Type:: float : default 0.0

range¶

modified by scale if they are specified.

Type:: (None, None)

scale¶

determines the value by which the result of the function is multiplied, before offset is added.

Type:: float

offset¶

determines the value added to the result of the function after scale has been applied.

Type:: float

owner¶

component to which the Function has been assigned.

Type:: Component

name¶

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

Type:: str

prefs¶

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 Preferences for details).

Type:: PreferenceSet or specification dict : Function.classPreferences

class Parameters(owner, parent=None)¶

bias¶

see bias

Default value:: 0.0
Type:: float

standard_deviation¶

see standard_deviation

Default value:: 1.0
Type:: float

derivative(input)¶

Derivative of function at input.

Parameters:

input (number) – value of the input of the Gaussian transform at which derivative is to be taken.

Returns:

Derivative of Guassian of variable (number or array)

class psyneulink.core.components.functions.nonstateful.transferfunctions.GaussianDistort(default_variable=None, variance=None, bias=None, scale=None, offset=None, seed=None, params=None, owner=None, prefs=None)¶

function returns random value from a Gaussian distribution with: mean = variable and variance = variance

Note

if the Gaussian transform of variable is desired (i.e., the value of the probability density function at variable, not a randomly chosen sample from the Gaussian distribution, then use Gaussian.

Parameters:

default_variable (number or array : default class_defaults.variable) – specifies a template for the value(s) used as the mean of the Guassian distribution from which each sample is drawn.
variance (float : default 1.0) – specifies “width” of the Gaussian distribution around each element of variable from which sample is drawn.
bias (float : default 0.0) – specifies value to add to each element of variable before drawing sample.
scale (float : default 1.0) – specifies value by which to multiply each sample.
offset (float : default 0.0) – specifies value to add to each sample after it is drawn and scale is applied
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¶

each element determines mean of the Gaussian distribution from which each sample is drawn.

Type:: number or array

variance¶

determines variance of Gaussian distribution from which each sample is drawn.

Type:: float

bias¶

determines value added to each element of variable before drawing sample.

Type:: float

scale¶

determines value by which each sample is multiplied after it is drawn.

Type:: float

offset¶

determines value added to each sample after it is drawn and scale is applied

Type:: float

random_state¶

private pseudorandom number generator

Type:: numpy.RandomState

owner¶

component to which the Function has been assigned.

Type:: Component

name¶

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

Type:: str

prefs¶

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 Preferences for details).

Type:: PreferenceSet or specification dict : Function.classPreferences

class Parameters(owner, parent=None)¶

bias¶

see bias

Default value:: 0.0
Type:: float

offset¶

see offset

Default value:: 0.0
Type:: float

random_state¶

see random_state

Default value:: None
Type:: numpy.random.RandomState

scale¶

see scale

Default value:: 1.0
Type:: float

variance¶

see variance

Default value:: 1.0
Type:: float

class psyneulink.core.components.functions.nonstateful.transferfunctions.Identity(default_variable=None, params=None, owner=None, prefs=None)¶

Returns variable.

Parameters:

variable (number or np.array : default class_defaults.variable) – specifies a template for the value to be returned.
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¶

contains value to be returned.

Type:: number or np.array

owner¶

component to which the Function has been assigned.

Type:: Component

name¶

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

Type:: str

prefs¶

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 Preferences for details).

Type:: PreferenceSet or specification dict : Function.classPreferences

class psyneulink.core.components.functions.nonstateful.transferfunctions.Linear(default_variable=None, slope=None, intercept=None, scale=None, offset=None, params=None, owner=None, prefs=None)¶

function returns linear transform of variable:

\[scale * (slope * variable + intercept) + offset\]

Note

Whereas scale and offset have effects similar to slope and intercept, they are applied after those Parameters have been applied to variable, and thus are not identical; rather, they can be thought of as “amplifying” and “displacing” the Linear function, respectively.

Note

The default values for slope, intercept, scale, and offset implement the IDENTITY_FUNCTION. This may cause the Linear function to be replaced with the Identity Function during some circumstances (e.g., compilation).

derivative returns the derivative of the Linear Function:

\[scale*slope\]

Parameters:

default_variable (number or array : default class_defaults.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.
scale (float : default 1.0) – specifies the value by which the result of the function is multiplied, before offset is added.
offset (float : default 0.0) – specifies the value added to the result of the function after scale has been applied.
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¶

contains value to be transformed.

Type:: number or array

slope¶

value by which each element of variable is multiplied before applying the intercept (if it is specified).

Type:: float

intercept¶

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

Type:: float

range¶

modified by scale if they are specified.

Type:: (None, None)

scale¶

determines the value by which the result of the function is multiplied, before offset is added.

Type:: float

offset¶

determines the value added to the result of the function after scale has been applied.

Type:: float

owner¶

component to which the Function has been assigned.

Type:: Component

name¶

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

Type:: str

prefs¶

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 Preferences for details).

Type:: PreferenceSet or specification dict : Function.classPreferences

class Parameters(owner, parent=None)¶

intercept¶

see intercept

Default value:: 0.0
Type:: float

slope¶

see slope

Default value:: 1.0
Type:: float

derivative(input)¶

Derivative of function at input.

Parameters:

input (number) – value of the input to the Linear transform at which derivative is to be taken.

Returns:

Slope of function (number or array)

class psyneulink.core.components.functions.nonstateful.transferfunctions.Logistic(default_variable=None, gain=None, x_0=None, bias=None, scale=None, offset=None, params=None, owner=None, prefs=None, **kwargs)¶

function returns logistic transform of variable:

\[scale * \frac{1}{1 + e^{ - gain ( variable + bias - x_{0} )}} + offset\]

(this is a vertically offset and scaled version of Tanh, which is centered on origin).

Note

The bias and x_0 Parameters have identical effects, apart from having opposite signs: bias is included to accommodate the convention in the machine learning community; x_0 is included to match the standard form of the Logistic Function (in which gain corresponds to the k parameter and scale corresponds to the L parameter); offset implements a translation of the function along the vertical axis that is not modulated by gain.

derivative returns the derivative of the Logistic using its output:

\[scale * gain * output * (1-output)\]

See note above for the effects of scale and offset.

Parameters:

default_variable (number or array : default class_defaults.variable) – specifies a template for the value to be transformed.
gain (float : default 1.0) – specifies value by which to multiply each element of variable after it is adjusted by bias and/or x_0, but before logistic transformation (see note above).
bias (float : default 0.0) – specifies value to add to each element of variable before applying gain; this argument has an effect identical to x_0, but with the opposite sign (see note above).
x_0 (float : default 0.0) – specifies value to add to each element of variable before applying gain; this argument has an effect identical to bias, but with the opposite sign (see note above).
scale (float : default 1.0) – specifies the value by which the result of the function is multiplied, before offset is added.
offset (float : default 0.0) – specifies the value added to the result of the function after scale has been applied.
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¶

contains value to be transformed.

Type:: number or array

gain¶

value by which to multiply each element of variable after it is adjusted by bias and/or x_0, but before logistic transformation has been applied (see note above).

Type:: float

bias¶

value to add to each element of variable before applying gain; this argument has an effect identical to x_0, but with the opposite sign (see note above).

Type:: float

x_0¶

value to add to each element of variable before applying gain; this argument has an effect identical to bias, but with the opposite sign (see note above).

Type:: float

range¶

modified by scale if they are specified.

Type:: (0, 1)

scale¶

determines the value by which the result of the function is multiplied, before offset is added.

Type:: float

offset¶

determines the value added to the result of the function after scale has been applied.

Type:: float

owner¶

component to which the Function has been assigned.

Type:: Component

name¶

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

Type:: str

prefs¶

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 Preferences for details).

Type:: PreferenceSet or specification dict : Function.classPreferences

class Parameters(owner, parent=None)¶

bias¶

see bias

Default value:: 0.0
Type:: float

gain¶

see gain

Default value:: 1.0
Type:: float

x_0¶

see x_0

Default value:: 0.0
Type:: float

derivative(input=None, output=None)¶

Derivative of function at either input or output.

Either input or output must be specified. If output is not specified, derivative is computed from input. If both are specified, input is ignored and derivative is computed from output .. technical_note:

allowing both to be specified is supported for consistency with `BackPropagation` `LearningFunction`
which uses output to compute Logistic

Parameters:

input (number) – value of the input to the Logistic transform at which derivative is to be taken.
output (number) – value of the output of the Logistic transform at which derivative is to be taken.

Returns:

derivative of logistic transform at output

Return type:

number or array

class psyneulink.core.components.functions.nonstateful.transferfunctions.ReLU(default_variable=None, gain=None, bias=None, leak=None, scale=None, offset=None, params=None, owner=None, prefs=None, **kwargs)¶

function returns rectified linear tranform of variable:

\[x = scale * gain * (variable - bias) + offset\]

\[max(x, leak * x) + offset\]

Commonly used by ReLU units in neural networks.

derivative returns the derivative of of the rectified linear tranform at its input:

\[scale * gain\ if\ input > 0,\ scale * gain * leak\ otherwise\]

Parameters:

default_variable (number or array : default class_defaults.variable) – specifies a template for the value to be transformed.
gain (float : default 1.0) – specifies a value by which to multiply variable after bias is subtracted from it.
bias (float : default 0.0) – specifies a value to subtract from each element of variable; functions as threshold.
leak (float : default 0.0) – specifies a scaling factor between 0 and 1 when (variable - bias) is less than or equal to 0.
scale (float : default 1.0) – specifies the value by which the result of the function is multiplied, before offset is added.
offset (float : default 0.0) – specifies the value added to the result of the function after scale has been applied.
owner (Component) – component to which to assign the 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.
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¶

contains value to be transformed.

Type:: number or array

gain¶

value by which to multiply variable after bias is subtracted from it.

Type:: float : default 1.0

bias¶

value to subtract from each element of variable; functions as threshold.

Type:: float : default 0.0

leak¶

scaling factor between 0 and 1 when (variable - bias) is less than or equal to 0.

Type:: float : default 0.0

range¶

modified by scale if they are specified.

Type:: (None, None)

scale¶

specifies the value by which the result of the function is multiplied, before offset is added.

Type:: float : default 1.0

offset¶

specifies the value added to the result of the function after scale has been applied.

Type:: float : default 0.0

owner¶

component to which the Function has been assigned.

Type:: Component

name¶

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

Type:: str

prefs¶

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 Preferences for details).

Type:: PreferenceSet or specification dict : Function.classPreferences

class Parameters(owner, parent=None)¶

bias¶

see bias

Default value:: 0.0
Type:: float

gain¶

see gain

Default value:: 1.0
Type:: float

leak¶

see leak

Default value:: 0.0
Type:: float

derivative(input or else output)¶

Derivative of function at input or output. If input is specified, that is used to compute the derivative; if input is not specified, it is inferred from the output and then used to compute the derivative.

Parameters:: input (number) – value of the input to the ReLU transform at which derivative is to be taken.
Returns:: derivative
Return type:: number or array

class psyneulink.core.components.functions.nonstateful.transferfunctions.SoftMax(default_variable=None, gain=None, mask_threshold=None, adapt_scale=None, adapt_base=None, adapt_entropy_weighting=None, output=None, per_item=None, params=None, owner=None, prefs=None)¶

SoftMax transform of variable

function returns SoftMax transform of variable:

\[\frac{e^{gain * variable_i}}{\sum\limits^{len(variable)}e^{gain * variable}}\]

filtered by output specification (see The Softmax function and its derivative for a nice discussion).

Note

If variable is all zeros, the SoftMax transform returns all zeros.

Thresholding and Adaptive Gain

For cases in which SoftMax is used with sparse vectors (e.g., one-hots), the value(s) of the most significant entries (e.g., the 1s in a one-hot) can be sensitive to (diminished by) the number of other values in the vector (i.e., its length). For example, whereas for [1 0] the SoftMax is [0.73105858 0.26894142], for [1 0 0 0] it is [0.47536689 0.1748777 0.1748777 0.1748777]. This can be addressed in one of two ways: either by thresholding variable before applying the SoftMax function, or by adapting the gain parametrically based on the variable:

mask_threshold – setting the mask_threshold argument to a scalar value causes the variable to be thresholded by that value before applying the SoftMax function; Each element in variable is first scaled by gain. Then, any elements with an absolute value below mask_threshold are set to negative infinity (-inf), effectively masking them since exp(-inf) = 0. The remaining values are then passed through the SoftMax function. This only applies if the gain argument is specified as a scalar; if it is specified as ADAPTIVE, then the mask_threshold argument is ignored.
ADAPTIVE – setting gain argument to ADAPTIVE causes it to be dynamically adjusted, based on the entropy and length of the variable, to keep the mass of the distribution around the highest values as consistent as possible over different sized vectors. If ADAPTIVE is specified, then the mask_threshold argument is ignored. The gain is adapted by calling the SoftMax function’s adapt_gain method. This can be finicky, and may need to be further tuned to the length of variable, which can be done using the SoftMax Function’s adapt_scale, adapt_base, and adapt_entropy_weighting arguments.

Derivative

derivative returns the derivative of the SoftMax. If OUTPUT_TYPE for the SoftMax is ALL, returns Jacobian matrix (derivative for each element of the output array with respect to each of the others):

\[D_jS_i = S_i(\delta_{i,j} - S_j),\ where\ \delta_{i,j}=1\ if\ i=j\ and\ \delta_{i,j}=0\ if\ i≠j.\]

If OUTPUT_TYPE is ARG_MAX, ARG_MAX_INDICATOR, MAX_VAL, MAX_INDICATOR, returns 1d array of the derivatives of the maximum value(s) with respect to the others (calculated as above). If OUTPUT_TYPE is PROB, raises an exception (since it is ambiguous as to which element would have been chosen by the SoftMax function)

Parameters:

default_variable (1d array : default class_defaults.variable) – specifies a template for the value to be transformed.
gain (scalar or ADAPTIVE : default 1.0) – specifies the value by which to multiply variable before SoftMax transformation, which functions as the inverse “temperature” of the function. If it is a scalar, it must be greater than zero. If ADAPTIVE is specified, the value is determined dynamically based on the variable; see Thresholding and Adaptive Gain for details).
mask_threshold (scalar : default None) – specifies whether to mask_threshold the variable before applying the SoftMax function; this only applies if gain is specified as a scalar; otherwise it is ignored (see Thresholding and Adaptive Gain for details).
adapt_scale (scalar : default 1) – specifies the scale parameter using by the adapt_gain method (see method for details).
adapt_base (scalar : default 1) – specifies the base parameter using by the adapt_gain method (see method for details).
adapt_entropy_weighting (default .1) – specifies the entropy_weighting parameter using by the adapt_gain method (see method for details).
output (ALL, ARG_MAX, ARG_MAX_INDICATOR, MAX_VAL, MAX_INDICATOR, or PROB : default ALL) – specifies the format of array returned by function (see output for details).
per_item (boolean : default True) – for 2d variables, determines whether the SoftMax function will be applied to the entire variable (per_item = False), or applied to each item in the variable separately (per_item = True).
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see name) – specifies the name of the Function.
prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the PreferenceSet for the Function (see prefs for details).

variable¶

contains value to be transformed.

Type:: 1d array

gain¶

determines how variable is scaled before the SoftMax transformation, determining the “sharpness” of the distribution (it is equivalent to the inverse of the temperature of the SoftMax function); if it is ‘ADAPTIVE’, it is determined dynamically adjusted using the adapt_gain method (see Thresholding and Adaptive Gain for additional details).

Type:: scalar or ADAPTIVE

mask_threshold¶

determines whether the variable is thresholded before applying the SoftMax function; if it is a scalar, each element of variable is first scaled by ` gain <SoftMax.gain>`. Then only elements with an absolute value greater than mask_threshold are considered when applying the SoftMax function, while all other elements are set to -inf effectively masking them since exp(-inf) = 0. This only applies if gain is specified as a scalar; otherwise it is ignored (see Thresholding and Adaptive Gain for details).

Type:: scalar or None

adapt_scale¶

determines the scale parameter using by the adapt_gain method (see method for details).

Type:: scalar

adapt_base¶

determines the base parameter using by the adapt_gain method (see method for details).

Type:: scalar

adapt_entropy_weighting¶

determines the entropy_weighting parameter using by the adapt_gain method (see method for details).

Type:: scalar

output¶

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

ARG_MAX: 1 for single element with the maximum SoftMax-transformed value, 0 for all others; (one with lowest index of there are multiple maximum values);

ARG_MAX_INDICATOR: 1 for a single element with the maximum SoftMax-transformed value, 0 for all others; (one with lowest index of there are multiple maximum values);

MAX_VAL: SoftMax-transformed value for the element(s) with the maximum such value, 0 for all others;

MAX_INDICATOR: 1 for the element(s) with the maximum SoftMax-transformed value, 0 for all others;

PROB: probabilistically chosen element based on SoftMax-transformed values after setting the sum of values to 1 (i.e., their Luce Ratio), 0 for all others.

Type:: ALL, ARG_MAX, ARG_MAX_INDICATOR, MAX_VAL, MAX_INDICATOR, or PROB

per_item¶

for 2d variables, determines whether the SoftMax function is applied to the entire variable (per_item = False), or applied to each item in the variable separately (per_item = True).

Type:: boolean : default True

range¶

Type:: None if output in {ARG_MAX, MAX_VAL}, else (0, 1) : default (0, 1)

owner¶

component to which the Function has been assigned.

Type:: Component

name¶

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

Type:: str

prefs¶

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 Preferences for details).

Type:: PreferenceSet or specification dict : Function.classPreferences

class Parameters(owner, parent=None)¶

variable¶

see variable

Default value:: numpy.array(0.)
Type:: numpy.ndarray
Read only:: True

adapt_scale¶

see adapt_scale

Default value:: 1.0
Type:: float

adapt_base¶

see adapt_base

Default value:: 1.0
Type:: float

adapt_entropy_weighting¶

see adapt_entropy_weighting

Default value:: 0.1
Type:: float

range¶

see range

Default value:: (0, 1)
Type:: <class ‘tuple’>

gain¶

see gain

Default value:: 1.0
Type:: float

output¶

see output

Default value:: ALL
Type:: str

per_item¶

see per_item

Default value:: True
Type:: bool

mask_threshold¶

see mask_threshold

Default value:: None
Type:: float

adapt_gain(v, context)¶

Compute the softmax gain (inverse temperature) based on the entropy of the distribution of values. Uses base, scale, and entropy_weighting parameters of SoftMax function to compute gain:

\[gain = scale * (base + (entropy\_weighting * log(entropy(logistic(v)))))\]

Return type:: float

derivative(output)¶

Returns:: derivative of values returned by SoftMax
Return type:: 1d or 2d array (depending on OUTPUT_TYPE of SoftMax)

class psyneulink.core.components.functions.nonstateful.transferfunctions.Tanh(default_variable=None, gain=None, x_0=None, bias=None, scale=None, offset=None, params=None, owner=None, prefs=None, **kwargs)¶

function returns hyperbolic tangent of variable:

\[\scale*frac{1 - e^{-2(gain*(variable+bias-x\_0)+offset)}}{1 + e^{-2(gain*(variable+bias-x\_0)+offset)}}\]

Note

The Tanh function is an offset and scaled version of this function. The parameters used here have the same meaning as those used for the Tanh Function.

derivative returns the derivative of the hyperbolic tangent at its input:

\[\frac{scale*gain}{(\frac{1+e^{-2(gain*(variable+bias-x\_0)+offset)}}{2e^{-(gain*( variable+bias-x\_0)+offset)}})^2}\]

Parameters:

default_variable (number or array : default class_defaults.variable) – specifies template for the value to be transformed.
gain (float : default 1.0) – specifies value by which to multiply variable before Tanh transformation
bias (float : default 0.0) – specifies value to add to each element of variable before applying gain and before Tanh transformation. This argument is identical to x_0, with the opposite sign.
x_0 (float : default 0.0) – specifies value to subtract from each element of variable before applying gain and before Tanh transformation. This argument is identical to bias, with the opposite sign.
scale (float : default 1.0) – specifies the value by which the result of the function is multiplied, before offset is added.
offset (float : default 0.0) – specifies the value added to the result of the function after scale has been applied.
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¶

contains value to be transformed.

Type:: number or array

gain¶

value by which each element of variable is multiplied before applying the bias (if it is specified).

Type:: float : default 1.0

bias¶

value added to each element of variable before applying the gain (if it is specified). This attribute is identical to x_0, with the opposite sign.

Type:: float : default 0.0

x_0¶

value subtracted from each element of variable before applying the gain (if it is specified). This attribute is identical to bias, with the opposite sign.

Type:: float : default 0.0

range¶

modified by scale if they are specified.

Type:: (None, None)

scale¶

determines the value by which the result of the function is multiplied, before offset is added.

Type:: float

offset¶

determines the value added to the result of the function after scale has been applied.

Type:: float

owner¶

component to which the Function has been assigned.

Type:: Component

name¶

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

Type:: str

prefs¶

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 Preferences for details).

Type:: PreferenceSet or specification dict : Function.classPreferences

class Parameters(owner, parent=None)¶

bias¶

see bias

Default value:: 0.0
Type:: float

gain¶

see gain

Default value:: 1.0
Type:: float

x_0¶

see x_0

Default value:: 0.0
Type:: float

derivative(input)¶

Derivative of function at input.

Parameters:: input (number) – value of the input to the Tanh transform at which derivative is to be taken.
Returns:: derivative
Return type:: number or array

class psyneulink.core.components.functions.nonstateful.transferfunctions.TransferFunction(default_variable, params, owner=None, name=None, prefs=None, context=None, **kwargs)¶

Function that transforms variable but maintains its shape.

Abstract base class for TransferFunctions.

In addition to the Parameters listed below, all TransferFunctions have a multiplicative_param and an additive_param – see multiplicative and additive params for additional information.

range¶

read-only Parameter that indicates the lower and upper limits of the function’s result. The two items of the tuple indicate the lower and upper bounds of range, respectively, with None as the entry if there are no bounds. Some subclasses of TransferFunction may have other Parameters that influence the range, which are described under the range attribute of the relevant subclasses.

Type:: tuple(lower bound: float, uppper bound: float)

default_range¶

class attribute that indicates the upper and lower limits of the Function’s result.

Type:: tuple(lower bound: float, uppper bound: float)

class Parameters(owner, parent=None)¶

range¶

see range

Default value:: (None, None)
Type:

class psyneulink.core.components.functions.nonstateful.transferfunctions.TransferWithCosts(default_variable=None, input_shapes=None, transfer_fct=None, enabled_cost_functions=None, intensity_cost_fct=None, adjustment_cost_fct=None, duration_cost_fct=None, combine_costs_fct=None, params=None, owner=None, prefs=None)¶

returns value of variable transformed by transfer_fct, after calling any cost functions that are enabled and assigning the result(s) to the corresponding parameter(s), as described below.

Cost Functions

The TransferWithCosts function has three individual cost functions that it can execute when its function is executed, which assign their results to the attributes indicated below:

intensity_cost_fct -> intensity_cost;
adjustment_cost_fct -> adjustment_cost;
duration_cost_fct -> duration_cost;

Which functions are called is determined by the settings in enabled_cost_functions, that can be initialized in the constructor using the enabled_cost_functions argument, and later modified using the enable_costs, disable_costs, toggle_cost and assign_costs methods. The value of any cost for which its function has never been enabled is None; otherwise, it is the value assigned when it was last enabled and executed (see duration_cost_fct for additional details concerning that function).

If any cost functions are enabled, then the combine_costs_fct function is executed, which sums the results of those that are enabled (Hadamard style, if the costs are arrays), and stores the result in the combined_costs attribute. Its value is None if no cost functions have ever been enabled; otherwise it is the value assigned the last time one or more cost functions were enabled.

Modulation of Cost Function Parameters

The multiplicative_param and additive_param of each cost function is assigned as a parameter of the TransferWithCost Function. This makes them accessible for modulation when the Function is assigned to a Port (e.g., as the default function of a ControlSignal), or a Mechanism. They can be referred to in the modulation argument of a ModulatorySignal's constructor (see Types of Modulation) using the following keywords:

INTENSITY_COST_FCT_MULTIPLICATIVE_PARAM INTENSITY_COST_FCT_ADDITIVE_PARAM ADJUSTMENT_COST_FCT_MULTIPLICATIVE_PARAM ADJUSTMENT_COST_FCT_ADDITIVE_PARAM DURATION_COST_FCT_MULTIPLICATIVE_PARAM DURATION_COST_FCT_ADDITIVE_PARAM COMBINE_COSTS_FCT_MULTIPLICATIVE_PARAM COMBINE_COSTS_FCT_ADDITIVE_PARAM

See example of how these keywords can be used to modulate the parameters of the cost functions of a TransferMechanism assigned to a ControlSignal.

Parameters:

variable (list or 1d array of numbers: Default class_defaults.variable) – specifies shape and default value of the array for variable used by transfer_fct on which costs are calculated.
input_shapes (int : None) – specifies length of the array for variable used by function and on which costs are calculated; can be used in place of default_value, in which case zeros are assigned as the value(s). An error is generated if both are specified but input_shapes != len(default_value).
transfer_fct (TransferFunction : Linear) – specifies the primary function, used to generate the value it returns.
enabled_cost_functions (CostFunctions or List[CostFunctions] : None) – specifies the costs to execute when function is called, and include in the computation of combined_costs.
intensity_cost_fct (Optional[TransferFunction] : default Exponential) – specifies the function used to compute the intensity_cost.
adjustment_cost_fct (Optional[TransferFunction] : default Linear) – specifies the function used to compute the adjustment_cost.
duration_cost_fct (IntegratorFunction : default IntegratorFunction) – specifies the function used to compute the duration_cost.
combine_costs_fct (function : default LinearCombination) – specifies the function used to compute combined_costs.
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 used by function, and on which intensity and associated costs are calculated.

Type:: 1d array

input_shapes¶

length of array for variable.

Type:: int

intensity¶

the result of the transfer_fct <TransferWithCosts.transfer_fct>`, and the value returned by function.

Type:: 1 array

function¶

primary function, specified by transfer_fct argument of constructor, and also stored in transfer_fct.

Type:: TransferFunction

transfer_fct¶

the TransferWithCosts Function’s primary function, used to generate the value it returns; same as function.

Type:: TransferMechanism

enabled_cost_functions¶

boolean combination of currently enabled CostFunctions; determines which cost functions are calculated when function is called, and are included in the computation of combined_costs (see Cost Functions for additional details).

Type:: CostFunctions or None

intensity_cost¶

cost computed by intensity_cost_fct for current intensity. Value is None if intensity_cost_fct has not been enabled (see Cost Functions for additional details).

Type:: float or None

intensity_cost_fct¶

calculates intensity_cost from the current value of intensity. It can be any TransferFunction, or any other function that takes and returns a scalar value. The default is Exponential.

Type:: TransferFunction

intensity_cost_fct_mult_param¶

references value of the multiplicative_param of intensity_cost_fct.

Type:: value

intensity_cost_fct_add_param¶

references value of the additive_param of intensity_cost_fct.

Type:: value

adjustment_cost¶

cost of change in intensity from the last time function was executed. Value is None if adjustment_cost_fct has not been enabled (see Cost Functions for additional details).

Type:: float or None

adjustment_cost_fct¶

calculates adjustment_cost based on the change in intensity from its value the last time function was executed. It can be any TransferFunction, or any other function that takes and returns a scalar value.

Type:: TransferFunction

adjustment_cost_fct_mult_param¶

references value of the multiplicative_param of adjustment_cost_fct.

Type:: value

adjustment_cost_fct_add_param¶

references value of the additive_param of adjustment_cost_fct.

Type:: value

duration_cost¶

integral of intensity, computed by duration_cost_fct. Value is None if duration_cost_fct has not been enabled; othewise, the integral of intensity is only for those executions of function in which function was enabled.

Type:: float or None

duration_cost_fct¶

calculates an integral of intensity. It can be any IntegratorFunction, or any other function that takes a list or array of two values and returns a scalar value.

Type:: IntegratorFunction

duration_cost_fct_mult_param¶

references value of the multiplicative_param of duration_cost_fct.

Type:: value

duration_cost_fct_add_param¶

references value of the additive_param of duration_cost_fct.

Type:: value

combined_costs¶

combined result of all cost functions that are enabled; computed by combined_costs_fct for current intensity. Value is None if no costs have been enabled (see Cost Functions for additional details).

Type:: float or None

combine_costs_fct¶

combines the results of all cost functions that are enabled, and assigns the result to cost. It can be any function that takes an array and returns a scalar value.

Type:: function

combined_costs_fct_mult_param¶

references value of the multiplicative_param of combined_costs_fct.

Type:: value

combined_costs_fct_add_param¶

references value of the additive_param of combined_costs_fct.

Type:: value

params¶

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.

Type:: Dict[param keyword: param value] : default None

name¶

name of the Function.

Type:: str

owner¶

component to which to assign the Function.

Type:: Component

prefs¶

determines the PreferenceSet for the Function (see prefs for details).

Type:: PreferenceSet or specification dict : default Function.classPreferences

class Parameters(owner, parent=None)¶

variable¶

see variable

Default value:: numpy.array([0])
Type:: numpy.ndarray

LinearCombination¶

see LinearCombination

Default value:: LinearCombination
Type:: Function

SimpleIntegrator¶

see SimpleIntegrator

Default value:: SimpleIntegrator
Type:: Function

adjustment_cost¶

see adjustment_cost

Default value:: None
Type:

adjustment_cost_fct¶

see adjustment_cost_fct

Default value:: Linear
Type:: Function

adjustment_cost_fct_add_param¶

see adjustment_cost_fct_add_param

Default value:: None
Type:

adjustment_cost_fct_mult_param¶

see adjustment_cost_fct_mult_param

Default value:: None
Type:

combine_costs_fct¶

see combine_costs_fct

Default value:: LinearCombination
Type:: Function

combine_costs_fct_add_param¶

see combine_costs_fct_add_param

Default value:: None
Type:

combine_costs_fct_mult_param¶

see combine_costs_fct_mult_param

Default value:: None
Type:

combined_costs¶

see combined_costs

Default value:: None
Type:

duration_cost¶

see duration_cost

Default value:: None
Type:

duration_cost_fct¶

see duration_cost_fct

Default value:: SimpleIntegrator
Type:: Function

duration_cost_fct_add_param¶

see duration_cost_fct_add_param

Default value:: None
Type:

duration_cost_fct_mult_param¶

see duration_cost_fct_mult_param

Default value:: None
Type:

enabled_cost_functions¶

see enabled_cost_functions

Default value:: CostFunctions.INTENSITY
Type:: CostFunctions

intensity¶

see intensity

Default value:: numpy.array([0])
Type:: numpy.ndarray

intensity_cost¶

see intensity_cost

Default value:: None
Type:

intensity_cost_fct¶

see intensity_cost_fct

Default value:: Exponential
Type:: Function

intensity_cost_fct_add_param¶

see intensity_cost_fct_add_param

Default value:: None
Type:

intensity_cost_fct_mult_param¶

see intensity_cost_fct_mult_param

Default value:: None
Type:

transfer_fct¶

see transfer_fct

Default value:: Linear
Type:: Function

transfer_fct_add_param¶

see transfer_fct_add_param

Default value:: None
Type:

transfer_fct_mult_param¶

see transfer_fct_mult_param

Default value:: None
Type:

assign_costs(cost_functions, execution_context=None)¶

Assigns specified functions; all others are disabled.

Parameters:: cost_functions (CostFunctions or List[CostFunctions]) – cost function or list of ones to be used; all other will be disabled.
Returns:: enabled_cost_functions – current value of enabled_cost_functions.
Return type:: boolean combination of CostFunctions

enable_costs(cost_functions, execution_context=None)¶

Enable specified cost functions; settings for all other cost functions are left intact.

Parameters:: cost_functions (CostFunctions or List[CostFunctions]) – cost function or list of ones to be enabled, in addition to any that are already enabled.
Returns:: enabled_cost_functions – current value of enabled_cost_functions.
Return type:: boolean combination of CostFunctions

disable_costs(cost_functions, execution_context=None)¶

Disable specified cost functions; settings for all other cost functions are left intact.

Parameters:: cost_functions (CostFunction or List[CostFunctions]) – cost function or list of ones to be disabled.
Returns:: enabled_cost_functions – current value of enabled_cost_functions.
Return type:: boolean combination of CostFunctions

toggle_cost(cost_function_name, assignment=True, execution_context=None)¶

Enable/disable a cost functions.

Parameters:: cost_function_name (str or CostFunction) – Must be the name of a cost function or a value of CostFunction enum.
Returns:: enabled_cost_functions – current value of enabled_cost_functions.
Return type:: boolean combination of CostFunctions

CostFunctions

private-members:
exclude-members:: Parameters