CombinationFunctions¶
Overview¶
Functions that combine multiple items with the same shape, yielding a result with a single item that has the same shape as the individual items.
All CombinationFunctions must have two attributes - multiplicative_param and additive_param - each of which is assigned the name of one of the function’s parameters; this is for use by ModulatoryProjections (and, in particular, GatingProjections, when the CombinationFunction is used as the function of an InputPort or OutputPort).
- class psyneulink.core.components.functions.combinationfunctions.Concatenate(default_variable=None, scale=None, offset=None, params=None, owner=None, prefs=None)¶
Concatenates items in outer dimension (axis 0) of
variable
into a single array, optionally scaling and/or adding an offset to the result after concatenating.function
returns a 1d array with length equal to the sum of the lengths of the items invariable
.derivative
returnsscale
.- Parameters
default_variable (list or np.array : default class_defaults.variable) – specifies a template for the value to be transformed and its default value; all entries must be numeric.
scale (float) – specifies a value by which to multiply each element of the output of
function
(seescale
for details)offset (float) – specifies a value to add to each element of the output of
function
(seeoffset
for details)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).
- default_variable¶
contains template of array(s) to be concatenated.
- Type
list or np.array
- scale¶
value is applied multiplicatively to each element of the concatenated, before applying the
offset
(if it is specified).- Type
float
- offset¶
value is added to each element of the concatentated array, after
scale
has been applied (if it is specified).- Type
float
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _validate_variable(variable, context=None)¶
Insure that list or array is 1d and that all elements are numeric
- Parameters
variable –
context –
- _validate_params(request_set, target_set=None, context=None)¶
Validate scale and offset parameters
Check that SCALE and OFFSET are scalars.
- _function(variable=None, context=None, params=None)¶
Use numpy hstack to concatenate items in outer dimension (axis 0) of variable.
- Parameters
variable (list or np.array : default class_defaults.variable) – a list or np.array of numeric values.
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
Concatenated array of items in variable – in an array that is one dimension less than
variable
.- Return type
array
- derivative(input)¶
Derivative of
function
at input.- Parameters
input (number) – value of the input to the function at which derivative is to be taken.
covariates (2d np.array : default class_defaults.variable[1:]) – the input(s) to the Concatenate function other than the one for which the derivative is being computed; these are ignored and are accepted for consistency with other functions.
- Returns
Scale of function
- Return type
number or array
- class psyneulink.core.components.functions.combinationfunctions.CombineMeans(default_variable=None, weights=None, exponents=None, operation=None, scale=None, offset=None, params=None, owner=None, prefs=None)¶
Calculate and combine mean(s) for arrays of values, optionally weighting and/or exponentiating each mean prior to combining, and scaling and/or offsetting after combining.
function
takes the mean of each array in the outermost dimension (axis 0) ofvariable
, and combines them either additively or multiplicatively (as specified byoperation
), applyingweights
and/orexponents
(if specified) to each mean prior to combining them, and applyingscale
and/oroffeset
(if specified) to the result after combining, and returns a scalar value.- Parameters
variable (1d or 2d np.array : default class_defaults.variable) – specifies a template for the arrays to be combined. If it is 2d, all items must have the same length.
weights (1d or 2d np.array : default None) – specifies values used to multiply the elements of each array in
variable
. If it is 1d, its length must equal the number of items invariable
; if it is 2d, the length of each item must be the same as those invariable
, and there must be the same number of items as there are invariable
(seeweights
for details)exponents (1d or 2d np.array : default None) – specifies values used to exponentiate the elements of each array in
variable
. If it is 1d, its length must equal the number of items invariable
; if it is 2d, the length of each item must be the same as those invariable
, and there must be the same number of items as there are invariable
(seeexponents
for details)operation (SUM or PRODUCT : default SUM) – specifies whether the
function
takes the sum or product of the means of the arrays invariable
.scale (float or np.ndarray : default None) – specifies a value by which to multiply the result of
function
(seescale
for details)offset (float or np.ndarray : default None) – specifies a value to add to the result of
function
(seeoffset
for details)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 to be combined by function. If it is 1d, the array is simply linearly transformed by and
scale
andoffset
. If it is 2d, the arrays (all of which must be of equal length) are weighted and/or exponentiated as specified byweights
and/orexponents
and then combined as specified byoperation
.- Type
1d or 2d np.array
- weights¶
if it is 1d, each element is used to multiply all elements in the corresponding array of
variable
; if it is 2d, then each array is multiplied elementwise (i.e., the Hadamard Product is taken) with the corresponding array ofvariable
. Allweights
are applied before any exponentiation (if it is specified).- Type
1d or 2d np.array : default NOne
- exponents¶
if it is 1d, each element is used to exponentiate the elements of the corresponding array of
variable
; if it is 2d, the element of each array is used to exponentiate the corresponding element of the corresponding array ofvariable
. In either case, exponentiating is applied after application of theweights
(if any are specified).- Type
1d or 2d np.array : default None
- operation¶
determines whether the
function
takes the elementwise (Hadamard) sum or product of the arrays invariable
.- Type
SUM or PRODUCT : default SUM
- scale¶
value is applied multiplicatively to each element of the array after applying the
operation
(seescale
for details); this done before applying theoffset
(if it is specified).- Type
float or np.ndarray : default None
- offset¶
value is added to each element of the array after applying the
operation
andscale
(if it is specified).- Type
float or np.ndarray : default None
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _validate_variable(variable, context=None)¶
Insure that all items of variable are numeric
- _validate_params(request_set, target_set=None, context=None)¶
Validate weights, exponents, scale and offset parameters
Check that WEIGHTS and EXPONENTS are lists or np.arrays of numbers with length equal to variable Check that SCALE and OFFSET are either scalars or np.arrays of numbers with length and shape equal to variable
- Note: the checks of compatibility with variable are only performed for validation calls during execution
(i.e., from check_args(), since during initialization or COMMAND_LINE assignment, a parameter may be re-assigned before variable assigned during is known
- _function(variable=None, context=None, params=None)¶
- Parameters
variable (1d or 2d np.array : default class_defaults.variable) – a single numeric array, or multiple arrays to be combined; if it is 2d, all arrays must have the same length.
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
combined means – the result of taking the means of each array in
variable
and combining them.- Return type
number
- class psyneulink.core.components.functions.combinationfunctions.Rearrange(default_variable=None, scale=None, offset=None, arrangement=None, params=None, owner=None, prefs=None)¶
Rearranges items in outer dimension (axis 0) of
variable
, as specified by arrangement, optionally scaling and/or adding an offset to the result after concatenating.The arrangement argument specifies how to rearrange the items of
variable
, possibly concatenating subsets of them into single 1d arrays. The specification must be an integer, a tuple of integers, or a list containing either or both. Each integer must be an index of an item in the outer dimension (axis 0) ofvariable
. Items referenced in a tuple are concatenated in the order specified into a single 1d array, and that 1d array is included in the resulting 2d array in the order it appears in arrangement. If arrangement is specified, then only the items ofvariable
referenced in the specification are included in the result; if arrangement is not specified, all of the items ofvariable
are concatenated into a single 1d array (i.e., it functions identically toConcatenate
).function
returns a 2d array with the items ofvariable
rearranged (and possibly concatenated) as specified by arrangement.Examples
>>> r = Rearrange(arrangement=[(1,2),(0)]) >>> print(r(np.array([[0,0],[1,1],[2,2]]))) [array([1., 1., 2., 2.]) array([0., 0.])]
>>> r = Rearrange() >>> print(r(np.array([[0,0],[1,1],[2,2]]))) [0. 0. 1. 1. 2. 2.]
- Parameters
default_variable (list or np.array : default class_defaults.variable) – specifies a template for the value to be transformed and its default value; all entries must be numeric.
arrangement (int, tuple, or list : default None) – specifies ordering of items in
variable
and/or ones to concatenate. (see above for details).scale (float) – specifies a value by which to multiply each element of the output of
function
(seescale
for details).offset (float) – specifies a value to add to each element of the output of
function
(seeoffset
for details).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).
- default_variable¶
contains template of array(s) to be concatenated.
- Type
list or np.array
- arrangement¶
determines ordering of items in
variable
and/or ones to concatenate (see above for additional details).- Type
list of one or more tuples
- scale¶
value is applied multiplicatively to each element of the concatenated, before applying the
offset
(if it is specified).- Type
float
- offset¶
value is added to each element of the concatentated array, after
scale
has been applied (if it is specified).- Type
float
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _validate_variable(variable, context=None)¶
Insure that all elements are numeric and that list or array is at least 2d
- _validate_params(request_set, target_set=None, context=None)¶
Validate arrangement, scale and offset parameters
- _instantiate_attributes_before_function(function=None, context=None)¶
Insure all items of arrangement are tuples and compatibility with default_variable
If arrangement is specified, convert all items to tuples If default_variable is NOT specified, assign with length in outer dimension = max index in arragnement If default_variable IS _user_specified, compatiblility with arrangement is checked in _validate_params
- _function(variable=None, context=None, params=None)¶
Rearrange items in outer dimension (axis 0) of variable according to
arrangement
.- Parameters
variable (list or np.array : default class_defaults.variable) – a list or np.array of numeric values.
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
Rearranged items of outer dimension (axis 0) of **variable** – in a 2d array.
- Return type
array
- class psyneulink.core.components.functions.combinationfunctions.Reduce(weights=None, exponents=None, default_variable=None, operation=None, scale=None, offset=None, params=None, owner=None, prefs=None)¶
Combines values in each of one or more arrays into a single value for each array, with optional weighting and/or exponentiation of each item within an array prior to combining, and scaling and/or offset of result after combining.
function
returns an array of scalar values, one for each array invariable
.- Parameters
default_variable (list or np.array : default class_defaults.variable) – specifies a template for the value to be transformed and its default value; all entries must be numeric.
weights (1d or 2d np.array : default None) – specifies values used to multiply the elements of each array in
variable
. If it is 1d, its length must equal the number of items invariable
; if it is 2d, the length of each item must be the same as those invariable
, and there must be the same number of items as there are invariable
(seeweights
for details)exponents (1d or 2d np.array : default None) – specifies values used to exponentiate the elements of each array in
variable
. If it is 1d, its length must equal the number of items invariable
; if it is 2d, the length of each item must be the same as those invariable
, and there must be the same number of items as there are invariable
(seeexponents
for details)operation (SUM or PRODUCT : default SUM) – specifies whether to sum or multiply the elements in
variable
offunction
.scale (float) – specifies a value by which to multiply each element of the output of
function
(seescale
for details)offset (float) – specifies a value to add to each element of the output of
function
(seeoffset
for details)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).
- default_variable¶
contains array(s) to be reduced.
- Type
list or np.array
- operation¶
determines whether elements of each array in
variable
offunction
are summmed or multiplied.- Type
SUM or PRODUCT
- scale¶
value is applied multiplicatively to each element of the array after applying the
operation
(seescale
for details); this done before applying theoffset
(if it is specified).- Type
float
- offset¶
value is added to each element of the array after applying the
operation
andscale
(if it is specified).- Type
float
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _validate_variable(variable, context=None)¶
Insure that list or array is 1d and that all elements are numeric
- Parameters
variable –
context –
- _validate_params(request_set, target_set=None, context=None)¶
Validate weghts, exponents, scale and offset parameters
Check that WEIGHTS and EXPONENTS are lists or np.arrays of numbers with length equal to variable. Check that SCALE and OFFSET are scalars.
- Note: the checks of compatibility with variable are only performed for validation calls during execution
(i.e., from check_args(), since during initialization or COMMAND_LINE assignment, a parameter may be re-assigned before variable assigned during is known
- _function(variable=None, context=None, params=None)¶
- Parameters
variable (list or np.array : default class_defaults.variable) – a list or np.array of numeric values.
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
Sum or product of arrays in variable – in an array that is one dimension less than
variable
.- Return type
array
- class psyneulink.core.components.functions.combinationfunctions.LinearCombination(default_variable=None, weights=None, exponents=None, operation=None, scale=None, offset=None, params=None, owner=None, prefs=None)¶
Linearly combine arrays of values, optionally weighting and/or exponentiating each array prior to combining, and scaling and/or offsetting after combining.
function
combines the arrays in the outermost dimension (axis 0) ofvariable
either additively or multiplicatively (as specified byoperation
), applyingweights
and/orexponents
(if specified) to each array prior to combining them, and applyingscale
and/oroffeset
(if specified) to the result after combining, and returns an array of the same length as the operand arrays.- Parameters
variable (1d or 2d np.array : default class_defaults.variable) – specifies a template for the arrays to be combined. If it is 2d, all items must have the same length.
weights (scalar or 1d or 2d np.array : default None) – specifies values used to multiply the elements of each array in variable. If it is 1d, its length must equal the number of items in
variable
; if it is 2d, the length of each item must be the same as those invariable
, and there must be the same number of items as there are invariable
(seeweights
for details of how weights are applied).exponents (scalar or 1d or 2d np.array : default None) – specifies values used to exponentiate the elements of each array in
variable
. If it is 1d, its length must equal the number of items invariable
; if it is 2d, the length of each item must be the same as those invariable
, and there must be the same number of items as there are invariable
(seeexponents
for details of how exponents are applied).operation (SUM, PRODUCT or CROSS_ENTROPY : default SUM) – specifies whether the
function
takes the elementwise (Hadamarad) sum, product or cross entropy of the arrays invariable
.scale (float or np.ndarray : default None) – specifies a value by which to multiply each element of the result of
function
(seescale
for details)offset (float or np.ndarray : default None) – specifies a value to add to each element of the result of
function
(seeoffset
for details)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 to be combined by function. If it is 1d, the array is simply linearly transformed by and
scale
andoffset
. If it is 2d, the arrays (all of which must be of equal length) are weighted and/or exponentiated as specified byweights
and/orexponents
and then combined as specified byoperation
.- Type
1d or 2d np.array
- weights¶
if it is a scalar, the value is used to multiply all elements of all arrays in
variable
; if it is a 1d array, each element is used to multiply all elements in the corresponding array ofvariable
; if it is a 2d array, then each array is multiplied elementwise (i.e., the Hadamard Product is taken) with the corresponding array ofvariable
. Allweights
are applied before any exponentiation (if it is specified).- Type
scalar or 1d or 2d np.array
- exponents¶
if it is a scalar, the value is used to exponentiate all elements of all arrays in
variable
; if it is a 1d array, each element is used to exponentiate the elements of the corresponding array ofvariable
; if it is a 2d array, the element of each array is used to exponentiate the corresponding element of the corresponding array ofvariable
. In either case, all exponents are applied after application of theweights
(if any are specified).- Type
scalar or 1d or 2d np.array
- operation¶
determines whether the
function
takes the elementwise (Hadamard) sum, product, or cross entropy of the arrays invariable
.- Type
SUM or PRODUCT
- scale¶
value is applied multiplicatively to each element of the array after applying the
operation
(seescale
for details); this done before applying theoffset
(if it is specified).- Type
float or np.ndarray
- offset¶
value is added to each element of the array after applying the
operation
andscale
(if it is specified).- Type
float or np.ndarray
- 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 usingclassPreferences
defined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- _validate_variable(variable, context=None)¶
Insure that all items of list or np.array in variable are of the same length
- Parameters
variable –
context –
- _validate_params(request_set, target_set=None, context=None)¶
Validate weghts, exponents, scale and offset parameters
Check that WEIGHTS and EXPONENTS are lists or np.arrays of numbers with length equal to variable Check that SCALE and OFFSET are either scalars or np.arrays of numbers with length and shape equal to variable
- Note: the checks of compatibility with variable are only performed for validation calls during execution
(i.e., from check_args(), since during initialization or COMMAND_LINE assignment, a parameter may be re-assigned before variable assigned during is known
- _function(variable=None, context=None, params=None)¶
- Parameters
variable (1d or 2d np.array : default class_defaults.variable) – a single numeric array, or multiple arrays to be combined; if it is 2d, all arrays must have the same length.
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
combined array – the result of linearly combining the arrays in
variable
.- Return type
1d array
- derivative(input)¶
Derivative of
function
at input.- Parameters
output (1d np.array : default class_defaults.variable[0]) –
value of the input to the Linear transform at which derivative is to be taken. a single numeric array or multiple arrays being combined, and at which derivative is to be taken.
output arg is used for consistency with other derivatives used by BackPropagation, and is ignored.
covariates (2d np.array : default class_defaults.variable[1:]) – the input(s) to the LinearCombination function other than the one for which the derivative is being computed; these are used to calculate the Jacobian of the LinearCombination function.
- Returns
Scale
- Return type
number (if input is 1d) or array (if input is 2d)
- class psyneulink.core.components.functions.combinationfunctions.PredictionErrorDeltaFunction(default_variable=None, gamma=None, params=None, owner=None, prefs=None)¶
Calculate temporal difference prediction error.
function
returns the prediction error using arrays invariable
:\[\delta(t) = r(t) + \gamma sample(t) - sample(t - 1)\]- _validate_variable(variable, context=None)¶
Insure that all items of variable are numeric
- Parameters
variable –
context –
- Returns
- Return type
variable if all items are numeric
- _validate_params(request_set, target_set=None, context=None)¶
Checks that WEIGHTS is a list or np.array of numbers with length equal to variable.
Note: the checks of compatibility with variable are only performed for validation calls during execution (i.e. from
check_args()
), since during initialization or COMMAND_LINE assignment, a parameter may be re-assigned before variable assigned during is known- Parameters
request_set –
target_set –
context –
- Returns
- Return type
None
- _function(variable=None, context=None, params=None)¶
- Parameters
variable (2d np.array : default class_defaults.variable) – a 2d array representing the sample and target values to be used to calculate the temporal difference delta values. Both arrays must have the same length
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
delta values
- Return type
1d np.array