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, size=None, matrix=HOLLOW_MATRIX, metric=ENERGY                                   transfer_fct=None                               normalize=False, 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.

• size (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, np.matrix, 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, np.matrix, 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 or np.matrix

• 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=EUCLIDEAN                                 normalize=False, 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, size=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.

• size (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, np.matrix, 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, np.matrix, 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.

• size (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 size != len(default_value).

• matrix (list, np.ndarray, np.matrix, 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

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 entropy calculation.

Type

list, np.ndarray, np.matrix, 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