ObjectiveFunctions¶

Stability
Energy
Entropy
Distance

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

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

_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”)

_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. :param function:

_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
Return type: scalar

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

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

_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
Return type: scalar

class psyneulink.core.components.functions.objectivefunctions.Energy(default_variable=None, input_shapes=None, normalize=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 Stablility 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, normalize=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