ObjectiveFunctions¶
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 thematrix
, transformed using thetransfer_fct
(if specified), and then compared with its initial value using thedistance metric
specified bymetric
. Ifnormalize
isTrue
, 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
fromDistanceMetrics
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 (seeprefs
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 selfconnections 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. TheDistance
Function is used to compute the stability ofvariable
with respect to its value after its transformation bymatrix
andtransfer_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 ofvariable
. 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

prefs
¶ specifies the
PreferenceSet
for the Function (seeprefs
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 following2d 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 (selfconnections) 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 bymatrix
andtransfer_fct
(if specified), using the specifiedmetric
. Ifnormalize
isTrue
, the result is divided by the length ofvariable
. 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 thedistance metric
specified in themetric
attribute. Ifnormalize
isTrue
, 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 invariable
.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 (seeprefs
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 invariable
. Type
keyword in DistanceMetrics

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

prefs
¶ specifies the
PreferenceSet
for the Function (seeprefs
for details). Type
PreferenceSet or specification dict : default Function.classPreferences

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

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 (seeStablility
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 (seeprefs
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 selfconnections 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 (seeStability
for explanation). Type
function or method

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

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 (seeStability
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 (seeprefs
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 selfconnections 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 (seeStability
for explanation). Type
function or method

normalize
¶ if
True
, result of entropy calculation is normalized by the length ofvariable
. 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