ObjectiveFunctions¶

Stability
Energy
Entropy
Distance
LossFunction

Functions that return a scalar evaluation of their input.

class psyneulink.core.components.functions.objectivefunctions.ObjectiveFunction(default_variable, params, owner=None, name=None, prefs=None, context=None, **kwargs)¶: Abstract class of Function used for evaluating ports.

class psyneulink.core.components.functions.objectivefunctions.Stability(default_variable=None, input_shapes=None, matrix=None, metric=None, transfer_fct=None, normalize=None, params=None, owner=None, prefs=None)¶

Return the stability of variable based on a state transformation matrix.

The value of variable is passed through the matrix, transformed using the transfer_fct (if specified), and then compared with its initial value using the distance metric specified by metric. If normalize is True, the result is normalized by the length of (number of elements in) variable.

Parameters:

variable (list or 1d array of numbers: Default class_defaults.variable) – specifies shape and default value of the array for which stability is calculated.
input_shapes (int : None) – specifies length of the array over which stability is 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).
matrix (list, np.ndarray, or matrix keyword : default HOLLOW_MATRIX) – specifies the matrix of recurrent weights; must be a square matrix with the same width as the length of variable.
metric (keyword in DistanceMetrics : Default ENERGY) – specifies a metric from DistanceMetrics used to compute stability.
transfer_fct (function or method : Default None) – specifies the function used to transform output of weight matrix.
normalize (bool : Default False) – specifies whether to normalize the stability value by the length of variable.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see name) – specifies the name of the Function.
prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the PreferenceSet for the Function (see prefs for details).

variable¶

array for which stability is calculated.

Type:: 1d array

size¶

length of array for which stability is calculated.

Type:: int

matrix¶

weight matrix from each element of variable to each other; if a matrix other than HOLLOW_MATRIX is assigned, it is convolved with HOLLOW_MATRIX to eliminate self-connections from the stability calculation.

Type:: list, np.ndarray, function keyword, or MappingProjection : default HOLLOW_MATRIX

metric¶

metric used to compute stability; must be a DistanceMetrics keyword. The Distance Function is used to compute the stability of variable with respect to its value after its transformation by matrix and transfer_fct.

Type:: keyword in DistanceMetrics

transfer_fct¶

function used to transform output of weight matrix prior to computing stability.

Type:: function or method

normalize¶

if True, result of stability calculation is normalized by the length of variable.

Type:: bool

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

owner¶

component to which to assign the Function.

Type:: Component

prefs¶

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

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

_function(variable=None, context=None, params=None)¶

Calculate the stability of variable.

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

Returns:

stability (scalar)

_instantiate_attributes_before_function(function=None, context=None)¶

Instantiate matrix

Specified matrix is convolved with HOLLOW_MATRIX: to eliminate the diagonal (self-connections) from the calculation.

The Distance Function is used for all calculations except ENERGY (which is not really a distance metric). If ENTROPY is specified as the metric, convert to CROSS_ENTROPY for use with the Distance Function. :type function: :param function:

_validate_params(variable, request_set, target_set=None, context=None)¶

Validate matrix param

matrix argument must be one of the following

2d list, np.ndarray
ParameterPort for one of the above
MappingProjection with a parameterPorts[MATRIX] for one of the above

Parse matrix specification to insure it resolves to a square matrix (but leave in the form in which it was specified so that, if it is a ParameterPort or MappingProjection,

its current value can be accessed at runtime (i.e., it can be used as a “pointer”)

_validate_variable(variable, context=None)¶: Validates that variable is 1d array

class psyneulink.core.components.functions.objectivefunctions.Distance(default_variable=None, metric=None, normalize=None, params=None, owner=None, prefs=None)¶

Return the distance between the vectors in the two items of variable using the distance metric specified in the metric attribute. If normalize is True, the result is normalized by the length of (number of elements in) variable.

Parameters:

variable (2d array with two items : Default class_defaults.variable) – the arrays between which the distance is calculated.
metric (keyword in DistancesMetrics : Default EUCLIDEAN) – specifies a distance metric used to compute the distance between the two items in variable.
normalize (bool : Default False) – specifies whether to normalize the distance by the length of variable.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see name) – specifies the name of the Function.
prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the PreferenceSet for the Function (see prefs for details).

variable¶

contains the arrays between which the distance is calculated.

Type:: 2d array with two items

metric¶

determines the metric used to compute the distance between the two items in variable.

Type:: keyword in DistanceMetrics

normalize¶

determines whether the distance is normalized by the length of variable.

Type:: bool

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

owner¶

component to which to assign the Function.

Type:: Component

prefs¶

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

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

_function(variable=None, context=None, params=None)¶

Calculate the distance between the two vectors in variable.

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

Returns:

distance (scalar)

_validate_params(request_set, target_set=None, variable=None, context=None)¶: Validate that variable has two items of equal length

class psyneulink.core.components.functions.objectivefunctions.Energy(default_variable=None, input_shapes=None, normalize=None, transfer_fct=None, matrix=None, params=None, owner=None, prefs=None)¶

Subclass of Stability Function that returns the energy of an array.

Parameters:

variable (list or 1d array of numbers: Default class_defaults.variable) – specifies shape and default value of the array for which energy is calculated.
input_shapes (int : None) – specifies length of the array over which energy is 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).
matrix (list, np.ndarray, or matrix keyword : default INVERSE_HOLLOW_MATRIX) – specifies the matrix of recurrent weights; must be a square matrix with the same width as the length of variable.
transfer_fct (function or method : Default None) – specifies the function used to transform output of matrix prior to the energy calculation (see Stability for explanation).
normalize (bool : Default False) – specifies whether to normalize the energy value by the length of variable.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see name) – specifies the name of the Function.
prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the PreferenceSet for the Function (see prefs for details).

variable¶

array for which energy is calculated.

Type:: 1d array

size¶

length of array for which energy is calculated.

Type:: int

matrix¶

weight matrix from each element of variable to each other; if a matrix other than INVERSE_HOLLOW_MATRIX is assigned, it is convolved with HOLLOW_MATRIX to eliminate self-connections from the energy calculation.

Type:: list, np.ndarray, or matrix keyword

transfer_fct¶

function used to transform output of matrix prior to computing energy (see Stability for explanation).

Type:: function or method

normalize¶

if True, result of energy calculation is normalized by the length of variable.

Type:: bool

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

owner¶

component to which to assign the Function.

Type:: Component

prefs¶

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

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

class psyneulink.core.components.functions.objectivefunctions.Entropy(default_variable=None, input_shapes=None, normalize=None, matrix=None, transfer_fct=None, params=None, owner=None, prefs=None)¶

Subclass of Stability Function that returns the entropy of an array.

Parameters:

variable (list or 1d array of numbers: Default class_defaults.variable) – specifies shape and default value of the array for which entropy is calculated.
input_shapes (int : None) – specifies length of the array over which entropy is calculated; can be used in place of default_value, in which case zeros are assigned as the value(s). An error is generated if both are specified but input_shapes != len(default_value).
matrix (list, np.ndarray, or matrix keyword : default INVERSE_HOLLOW_MATRIX) – specifies the matrix of recurrent weights; must be a square matrix with the same width as the length of variable.
transfer_fct (function or method : Default None) – specifies the function used to transform output of matrix prior to the entropy calculation (see Stability for explanation).
normalize (bool : Default False) – specifies whether to normalize the entropy value by the length of variable.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see name) – specifies the name of the Function.
prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the PreferenceSet for the Function (see prefs for details).

variable¶

array for which entropy is calculated.

Type:: 1d array

input_shapes¶

length of array for which energy is calculated.

Type:: int

matrix¶

weight matrix from each element of variable to each other; if a matrix other than INVERSE_HOLLOW_MATRIX is assigned, it is convolved with HOLLOW_MATRIX to eliminate self-connections from the entropy calculation.

Type:: list, np.ndarray, or matrix keyword

transfer_fct¶

function used to transform output of matrix prior to computing entropy (see Stability for explanation).

Type:: function or method

normalize¶

if True, result of entropy calculation is normalized by the length of variable.

Type:: bool

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

owner¶

component to which to assign the Function.

Type:: Component

prefs¶

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

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

class psyneulink.core.components.functions.objectivefunctions.LossFunction(default_variable=None, loss=None, normalize=None, params=None, owner=None, prefs=None)¶

Loss( default_variable=None, loss=Loss.MSE function=None, normalize=False, params=None, owner=None, prefs=None )

Return the loss calculated for the sample array (first item of variable) with respect to the target array (second item of variable, using the Loss specified in the loss attribute. If normalize is True, the result is normalized by the length of (number of elements in) the sample and target arrays.

Loss uses the Distance Function to compute the loss where possible, using the the loss attribute to specify the appropriate metric argument of Distance.

Parameters:

default_variable (2d array with two items : Default class_defaults.variable) – specifies the shape and default value for the sample and target arrays; these are, respectively, the first and second items of the <variable <LossFunction.variable>` attribute (variable[0] and variable[1]) used to compute the loss.
loss (member of keyword in Loss enum : Default Loss.MSE) – specifies the loss which is computed for the sample array (variable[0]) with respect to the target array (variable[1]).
normalize (bool : Default False) –

specifies whether to normalize the loss by the length of the sample and `target
<LossFunction.target>` arrays variable.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see name) – specifies the name of the Function.
prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the PreferenceSet for the Function (see prefs for details).

variable¶

contains the sample array (first item) for which the loss is computed with respect to target array (second item).

Type:: 2d array with two items

loss¶

determines the loss computed for the sample array with respect to the target array.

Type:: Loss

normalize¶

determines whether the loss is normalized by the length of sample and target arrays in variable.

Type:: bool

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

owner¶

component to which to assign the Function.

Type:: Component

prefs¶

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

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

_function(variable=None, context=None, params=None)¶

Calculate the loss between a sample and target vector in variable.

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

Returns:

distance (scalar)

_validate_params(request_set, target_set=None, variable=None, context=None)¶: Validate that variable has two items of equal length