TransferFunctions¶
Overview¶
Functions that transform their variable but maintain its shape.
Standard Attributes¶
All TransferFunctions 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, withNone
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).
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.transferfunctions.Angle(default_variable, params=None, owner=None, name=None, prefs=None)¶
function
returns Angle transform of vector invariable
:- 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 (seeprefs
for details).
- variable¶
contains value to be transformed.
- Type
1d array
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _function(variable=None, context=None, params=None)¶
- Parameters
variable (ndarray : default class_defaults.variable) – an array of coordinates on a sphere to be transformed to n+1d angular coordinates; must be at least 2d.
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
Angle transformation of variable
- Return type
ndarray of variable.ndim+1
- _angle(value)¶
Take nd value and return n+1d coordinates for angle on a sphere
- class psyneulink.core.components.functions.transferfunctions.Exponential(default_variable, rate=1.0, bias=0.0, scale=1.0, offset=0.0, params=None, owner=None, name=None, prefs=None)¶
function
returns exponential transform ofvariable
:\[scale * e^{rate*variable+bias} + offset\]derivative
returns the derivative of the Exponential:\[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 byrate
and before exponentiation.scale (float : default 1.0) – specifies a value by which to multiply the exponentiated value of
variable
.offset (float : default 0.0) – specifies value to add to the exponentiated value of
variable
after multiplying byscale
.params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name
) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).
- variable¶
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 byrate
and before exponentiation; assigned as ADDITIVE_PARAM of the Exponential Function.- Type
float
- scale¶
value by which the exponentiated value is multiplied.
- Type
float
- offset¶
value added to exponentiated value after multiplying by
scale
.- Type
float
- bounds¶
- Type
(0, None)
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _function(variable=None, context=None, params=None)¶
- Parameters
variable (number or array : default class_defaults.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 array
- 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.transferfunctions.Gaussian(default_variable, standard_deviation=1.0, bias=0.0, scale=1.0, offset=0.0, params=None, owner=None, name=None, prefs=None)¶
function
returns Gaussian transform ofvariable
:\[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 ofvariable
:\[\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.offset (float : default 0.0) – value to add to each element after applying Gaussian transform and
scale
.scale (float : default 1.0) – value by which to multiply each element after applying Gaussian transform.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name
) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).
- variable¶
value 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
- scale¶
value by which each element is multiplied after applying the Gaussian transform.
- Type
float : default 0.0
- offset¶
value added to each element after applying the Gaussian transform and scale.
- Type
float : default 0.0
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _function(variable=None, context=None, params=None)¶
- Parameters
variable (number or array : default class_defaults.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
Gaussian transformation of variable
- Return type
number or array
- class psyneulink.core.components.functions.transferfunctions.GaussianDistort(default_variable, variance=1.0, bias=0.0, scale=1.0, offset=0.0, seed=None, params=None, owner=None, name=None, prefs=None)¶
function
returns random value from a Gaussian distribution with
Note
if the Gaussian transform of
variable
is desired (i.e., the value of the probability density function atvariable
, not a randomly chosen sample from the Gaussian distribution, then useGaussian
.- 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 appliedparams (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name
) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).
- variable¶
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
- scale¶
determines value by which each sample is multiplied after it is drawn.
- Type
float
- random_state¶
private pseudorandom number generator
- Type
numpy.RandomState
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _function(variable=None, context=None, params=None)¶
- Parameters
variable (number or array : default class_defaults.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
Sample from Gaussian distribution for each element of variable
- Return type
number or array
- class psyneulink.core.components.functions.transferfunctions.Identity(default_variable, params=None, owner=None, name=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 (seeprefs
for details).
- variable¶
contains value to be returned.
- Type
number or np.array
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _function(variable=None, context=None, params=None)¶
Return:
variable
- Parameters
variable (number or np.array : default class_defaults.variable) – a single value or array 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.
- Returns
variable
- Return type
number or np.array
- class psyneulink.core.components.functions.transferfunctions.Linear(default_variable, slope=1.0, intercept=0.0, params=None, owner=None, name=None, prefs=None)¶
function
returns linear transform ofvariable
:\[slope * variable + intercept\]Note: default values for
slope
andintercept
implement the IDENTITY_FUNCTION.derivative
returnsslope
.- 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 applyingslope
.params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name
) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).
- variable¶
contains value to be transformed.
- Type
number or array
- slope¶
value by which each element of
variable
is multiplied before applying theintercept
(if it is specified).- Type
float
- intercept¶
value added to each element of
variable
after applying theslope
(if it is specified).- Type
float
- bounds¶
determines the lower and upper limits of the result; if at least one bound is specified, the attribute is a tuple specifying the lower and upper bounds, respectively, with
None
as the entry for no bound.- Type
Tuple or None
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _function(variable=None, context=None, params=None)¶
- Parameters
variable (number or array : default class_defaults.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 array
- class psyneulink.core.components.functions.transferfunctions.LinearMatrix(default_variable, matrix=None, params=None, owner=None, name=None, prefs=None)¶
Matrix transform of
variable
.function
returns dot product of variable with matrix:\[variable \bullet matrix\]- Parameters
variable (list or 1d array : default class_defaults.variable) – specifies a template for the value to be transformed; length must equal the number of rows of
matrix
.matrix (number, list, 1d or 2d np.ndarray, np.matrix, function, or matrix keyword : default IDENTITY_MATRIX) –
specifies matrix used to transform
variable
(seematrix
for specification details).When LinearMatrix is the
function
of a projection:When LinearMatrix is instantiated on its own, or as the function of a Mechanism or Port:
bounds (None) –
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name
) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).
- variable¶
contains value to be transformed.
- Type
1d array
- matrix¶
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 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).
- Type
2d array
- 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 usingclassPreferences
defined in __init__.py (seePreferenceSet
for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _validate_params(request_set, target_set=None, context=None)¶
Validate params and assign to targets
This overrides the class method, to perform more detailed type checking (see explanation in class method). Note: this method (or the class version) is called only if the parameter_validation attribute is
True
- Parameters
request_set – (dict) - params to be validated
target_set – (dict) - destination of validated params
context – (str)
- Return none
- 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, context=None, params=None)¶
- Parameters
variable (list or 1d array) – array to be transformed; length must equal the number of rows of
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 array
- class psyneulink.core.components.functions.transferfunctions.Logistic(default_variable, gain=1.0, bias=0.0, x_0=0.0, offset=0.0, scale=1.0, params=None, owner=None, name=None, prefs=None)¶
function
returns logistic transform ofvariable
:\[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 arguments are identical, 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 form of bias that is not modulated by gain (i.e., it produces an offset of the function along the horizontal axis).
derivative
returns the derivative of the Logistic using its output:\[gain * scale * output * (1-output)\]- 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 bybias
and/orx_0
, but before adjustment byoffset
and logistic transformation (see note above).bias (float : default 0.0) – specifies value to add to each element of
variable
before applyinggain
; 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 applyinggain
; this argument has an effect identical to bias, but with the opposite sign (see note above).offset (float : default 0.0) – specifies value to add to each element of
variable
after adjusting bybias
and/orx_0
and applyinggain
, but before logistic transformation (see note above).scale (float : default 0.0) – specifies value by which to multiply each element of
variable
after all other parameters and logistic transformation have been applied (see note above).params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name
) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).
- variable¶
contains value to be transformed.
- Type
number or array
- gain¶
value by which to multiply each element of
variable
after it is adjusted bybias
and/orx_0
, but before adjustment byoffset
and logistic transformation (see note above).- Type
float
- bias¶
value to add to each element of
variable
before applyinggain
; 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 applyinggain
; this argument has an effect identical to bias, but with the opposite sign (see note above).- Type
float
- offset¶
value to add to each element of
variable
after adjusting bybias
and/orx_0
and applyinggain
, but before logistic transformation (see note above).- Type
float
- scale¶
value by which to multiply each element of
variable
after all other parameters and logistic transformation have been applied (see note above).- Type
float
- bounds¶
- Type
(0,1)
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _function(variable=None, context=None, params=None)¶
- Parameters
variable (number or array : default class_defaults.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 array
- 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
Deriviative of logistic transform at output
- Return type
number or array
- class psyneulink.core.components.functions.transferfunctions.ReLU(default_variable, gain=1.0, bias=0.0, leak=0.0, params=None, owner=None, name=None, prefs=None)¶
function
returns rectified linear tranform ofvariable
:\[x = gain*(variable - bias)\]\[max(x, leak * x)\]Commonly used by ReLU units in neural networks.
derivative
returns the derivative of of the rectified linear tranform at its input:\[gain\ if\ input > 0,\ 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
afterbias
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.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name
) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).
- variable¶
contains value to be transformed.
- Type
number or array
- gain¶
value by which to multiply
variable
afterbias
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
- bounds¶
- Type
(None,None)
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _function(variable=None, context=None, params=None)¶
- Parameters
variable (number or array : default class_defaults.variable) – a single value or array to be transformed.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
- Returns
ReLU transformation of variable
- Return type
number or array
- 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.transferfunctions.SoftMax(default_variable, gain=1.0, output=ALL, params=None, owner=None, name=None, prefs=None)¶
SoftMax transform of
variable
function
returns SoftMax transform ofvariable
:\[\frac{e^{gain * variable_i}}{\sum\limits^{len(variable)}e^{gain * variable}}\]filtered by
ouptput
specification (see The Softmax function and its derivative for a nice discussion).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 MAX_VAL or MAX_INDICATOR, returns 1d array of the derivatives of the maximum value 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 (float : default 1.0) – specifies a value by which to multiply
variable
before SoftMax transformation.output (ALL, MAX_VAL, MAX_INDICATOR, or PROB : default ALL) – specifies the format of array returned by
function
(seeoutput
for details).per_item (boolean : default True) – for 2d variables, determines whether the SoftMax function will be applied to the entire variable (per_item = False), or applied to each item in the variable separately (per_item = True).
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name
) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).
- variable¶
contains value to be transformed.
- Type
1d array
- gain¶
value by which
variable
is multiplied before the SoftMax transformation; determines the “sharpness” of the distribution.- Type
float
- output¶
determines how the SoftMax-transformed values of the elements in
variable
are reported in the array returned byfunction
: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 setting the sum of values to 1 (i.e., their Luce Ratio), 0 for all others.
- Type
ALL, 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
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _validate_variable(variable, context=None)¶
Validate variable and return validated variable
Convert self.class_defaults.variable specification and variable (if specified) to list of 1D np.ndarrays:
VARIABLE SPECIFICATION: ENCODING: Simple value variable: 0 -> [array([0])] Single state array (vector) variable: [0, 1] -> [array([0, 1])] Multiple port variables, each with a single value variable: [[0], [0]] -> [array[0], array[0]]
- Perform top-level type validation of variable against the self.class_defaults.variable;
if the type is OK, the value is returned (which should be used by the function)
This can be overridden by a subclass to perform more detailed checking (e.g., range, recursive, etc.) It is called only if the parameter_validation attribute is
True
(which it is by default)- IMPLEMENTATION NOTES:
future versions should add hierarchical/recursive content (e.g., range) checking
add request/target pattern?? (as per _validate_params) and return validated variable?
- Parameters
variable – (anything other than a dictionary) - variable to be validated:
context – (str)
- Return variable
validated variable
- _function(variable=None, context=None, params=None)¶
- Parameters
variable (1d array : default class_defaults.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 array
- 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.transferfunctions.Tanh(default_variable, gain=1.0, bias=0.0, x_0=0.0, offset=0.0, scale=1.0, params=None, owner=None, name=None, prefs=None)¶
function
returns hyperbolic tangent ofvariable
:\[\scale*frac{1 - e^{-2(gain*(variable+bias-x\_0)+offset)}}{1 + e^{-2(gain*(variable+bias-x\_0)+offset)}}\]Note
The
Logistic
function is an offset and scaled version of this function. The parameters used here have the same meaning as those used for theLogistic
Function.derivative
returns the derivative of the hyperbolic tangent at its input:\[\frac{gain*scale}{(\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 logistic transformationbias (float : default 0.0) – specifies value to add to each element of
variable
before applyinggain
and before logistic 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 applyinggain
and before logistic transformation. This argument is identical to bias, with the opposite sign.offset (float : default 0.0) – specifies value to add to each element of
variable
after applyinggain
but before logistic transformation.scale (float : default 1.0) – specifies value by which to multiply each element after applying Tanh transform.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name
) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSet
for the Function (seeprefs
for details).
- variable¶
contains value to be transformed.
- Type
number or array
- gain¶
value by which each element of
variable
is multiplied before applying thebias
(if it is specified).- Type
float : default 1.0
- bias¶
value added to each element of
variable
before applying thegain
(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 thegain
(if it is specified). This attribute is identical to bias, with the opposite sign.- Type
float : default 0.0
- offset¶
value to added to each element of
variable
after applyinggain
but before logistic transformation.- Type
float : default 0.0
- scale¶
value by which element is multiplied after applying Tanh transform.
- Type
float : default 1.0
- bounds¶
- Type
(0,1)
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _function(variable=None, context=None, params=None)¶
- Parameters
variable (number or array : default class_defaults.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
hyperbolic tangent of variable
- Return type
number or array
- class psyneulink.core.components.functions.transferfunctions.TransferFunction(default_variable, params, owner=None, name=None, prefs=None, context=None, **kwargs)¶
Function that transforms variable but maintains its shape.
All TransferFunctions MUST have the following attributes:
bounds
– specifies the lower and upper limits of the result; if there are none, the attribute is set toNone
; if it has at least one bound, the attribute is set to a tuple specifying the lower and upper bounds, respectively, withNone
as the entry for no bound.multiplicative_param 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.core.components.functions.transferfunctions.TransferWithCosts(default_variable=None, size=None, transfer_fct=Line enabled_cost_functions=None, intensity_fct=Exponential adjustment_fct=Linear duration_fct=SimpleIntegrator combine_costs_fct=LinearCombination params=None, owner=None, prefs=None)¶
returns value of
variable
transformed bytransfer_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: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 theenable_costs
,disable_costs
,toggle_cost
andassign_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 (seeduration_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 thecombined_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.size (int : None) – specifies length of the array for
variable
used byfunction
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 size != 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 ofcombined_costs
.intensity_cost_fct (Optional[
TransferFunction
] : defaultExponential
) – specifies the function used to compute theintensity_cost
.adjustment_cost_fct (Optional[
TransferFunction
] : defaultLinear
) – specifies the function used to compute theadjustment_cost
.duration_cost_fct (
IntegratorFunction
: defaultIntegratorFunction
) – specifies the function used to compute theduration_cost
.combine_costs_fct (function : default
LinearCombination
) – specifies the function used to computecombined_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 (seeprefs
for details).
- variable¶
value used by
function
, and on whichintensity
and associated costs are calculated.- Type
1d array
- 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
- transfer_fct¶
the TransferWithCosts Function’s primary function, used to generate the value it returns; same as
function
.- Type
- 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 ofcombined_costs
(see Cost Functions for additional details).- Type
CostFunctions or None
- intensity_cost¶
cost computed by
intensity_cost_fct
for currentintensity
. Value is None ifintensity_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 ofintensity
. It can be anyTransferFunction
, or any other function that takes and returns a scalar value. The default isExponential
.- Type
- 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 timefunction
was executed. Value is None ifadjustment_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 inintensity
from its value the last timefunction
was executed. It can be anyTransferFunction
, or any other function that takes and returns a scalar value.- Type
- 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 byduration_cost_fct
. Value is None ifduration_cost_fct
has not been enabled; othewise, the integral ofintensity
is only for those executions offunction
in whichfunction
was enabled.- Type
float or None
- duration_cost_fct¶
calculates an integral of
intensity
. It can be anyIntegratorFunction
, or any other function that takes a list or array of two values and returns a scalar value.- Type
- 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 bycombined_costs_fct
for currentintensity
. 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 tocost
. 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
- prefs¶
determines the
PreferenceSet
for the Function (seeprefs
for details).- Type
PreferenceSet or specification dict : default Function.classPreferences
- _instantiate_attributes_before_function(function=None, context=None)¶
Instantiate cost functions specified in
enabled_cost_functions
.
- _instantiate_cost_functions(context)¶
Instantiate cost functions and the multiplicative and additive modulatory parameters for them.
Parse specification of cost functions to enable Instantiate cost functions specified in construtor arguments, and enable ones in enabled_cost_functions Assign default value for multipicative and additive parameters for each, from the values of those parameters
on the respective cost functions just instantiated.
Initialize intensity_cost
- _function(variable=None, params=None, context=None)¶
- Parameters
variable (number or array : default class_defaults.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
transformation of variable using `transfer_fct <TransferWithCostss.transfer_fct>`
- Return type
number or array
- 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
- class psyneulink.core.components.functions.transferfunctions.CostFunctions(value)¶
Options for selecting constituent cost functions to be used by a
TransferWithCosts
Function.These can be used alone or in combination with one another, by enabling or disabling each using the
TransferWithCosts
Function’senable_costs
,disable_costs
,toggle_cost
andassign_costs
methods.- NONE¶
cost
is not computed.
- INTENSITY¶
duration_cost_fct
is used to calculate a contribution to thecost
based its currentintensity
value.
- ADJUSTMENT¶
adjustment_cost_fct
is used to calculate a contribution to thecost
based on the change in itsintensity
from its last value.
- DURATION¶
duration_cost_fct
is used to calculate a contribitution to thecost
based on its integral (i.e., it accumulated value over multiple executions).
- ALL¶
all of the cost functions are used to calculate
cost
.