• Github
Table of Contents
0.13.0.0
  • Welcome to PsyNeuLink
  • Basics and Primer
  • Quick Reference
  • Core
  • Library
  • Contributors Guide
  • Docs >
  • TransferFunctions
Shortcuts

TransferFunctions¶

  • Identity

  • Linear

  • Exponential

  • Logistic

  • Tanh

  • ReLU

  • Angle

  • Gaussian

  • GaussianDistort

  • SoftMax

  • LinearMatrix

  • TransferWithCosts

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, with None as the entry for no bound.

  • multiplicative_param and additive_param: each of these is assigned the name of one of the function’s parameters and used by ModulatoryProjections to modulate the output of the TransferFunction’s function (see Modulatory Parameters).

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

_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 of variable:

\[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 by rate 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 by scale.

  • 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

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)

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

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

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

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

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

_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

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

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

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

_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 (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

_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 of variable:

\[slope * variable + intercept\]

Note: default values for slope and intercept implement the IDENTITY_FUNCTION.

derivative returns 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.

  • 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

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

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

_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

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

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 (see matrix for specification details).

    When LinearMatrix is the function of a projection:

    • the matrix specification must be compatible with the variables of the sender and receiver

    • a matrix keyword specification generates a matrix based on the sender and receiver shapes

    When LinearMatrix is instantiated on its own, or as the function of a Mechanism or Port:

    • the matrix specification must be compatible with the function’s own variable

    • if matrix is not specified, a square identity matrix is generated based on the number of columns in variable

    • matrix keywords are not valid matrix specifications

  • bounds (None) –

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

  • owner (Component) – component to which to assign the Function.

  • name (str : default see name) – specifies the name of the Function.

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

variable¶

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

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 PreferenceSet 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 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 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 by bias and/or x_0, but before adjustment by offset and 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).

  • offset (float : default 0.0) – specifies value to add to each element of variable after adjusting by bias and/or x_0 and applying gain, 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 (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 adjustment by offset and logistic transformation (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

offset¶

value to add to each element of variable after adjusting by bias and/or x_0 and applying gain, 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)

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

_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 of variable:

\[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 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.

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

bounds¶
Type

(None,None)

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

_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 of variable:

\[\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 (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¶

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

  • ALL: array of all SoftMax-transformed values (the default);

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

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

  • PROB: probabilistically chosen element based on SoftMax-transformed values after 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

bounds¶
Type

None if output == 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

_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 of variable:

\[\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 the Logistic 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 transformation

  • bias (float : default 0.0) – specifies value to add to each element of variable before applying gain 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 applying gain 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 applying gain 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 (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

offset¶

value to added to each element of variable after applying gain 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)

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

_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

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.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 to None; if it has at least one bound, the attribute is set to a tuple specifying the lower and upper bounds, respectively, with None as the entry for no bound.

multiplicative_param and additive_param – each of these is assigned the name of one of the function’s parameters and used by ModulatoryProjections to modulate the output of the TransferFunction’s function (see Modulatory Parameters).

class psyneulink.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 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.

  • size (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 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 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

size¶

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

_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’s enable_costs, disable_costs, toggle_cost and assign_costs methods.

NONE¶

cost is not computed.

INTENSITY¶

duration_cost_fct is used to calculate a contribution to the cost based its current intensity value.

ADJUSTMENT¶

adjustment_cost_fct is used to calculate a contribution to the cost based on the change in its intensity from its last value.

DURATION¶

duration_cost_fct is used to calculate a contribitution to the cost based on its integral (i.e., it accumulated value over multiple executions).

ALL¶

all of the cost functions are used to calculate cost.

DEFAULTS¶

assign default set of cost functions as INTENSITY).


© Copyright 2016, Jonathan D. Cohen.

Built with Sphinx using a theme provided by Read the Docs.
  • TransferFunctions
    • Overview
      • Standard Attributes
      • Derivatives
    • TranferFunction Class References
  • Github