A ComparatorMechanism is a subclass of ObjectiveMechanism that receives two inputs (a sample and a target), compares
them using its
function, and places the calculated discrepancy between the two in its
Creating a ComparatorMechanism
ComparatorMechanisms are generally created automatically when other PsyNeuLink components are created (such as
LearningMechanisms). A ComparatorMechanism can also be created directly by calling
its constructor. Its sample and target arguments are used to specify the OutputStates that provide the
sample and target inputs, respectively (see
ObjectiveMechanism_Monitored_States for details concerning their
specification, which are special versions of an ObjectiveMechanism’s monitor argument). When the
ComparatorMechanism is created, two InputStates are created, one each for its sample and target inputs (and named,
by default, SAMPLE and TARGET). Each is assigned a MappingProjection from the corresponding OutputState specified
in the sample and target arguments.
It is important to recognize that the value of the SAMPLE and TARGET InputStates must have the same length and type,
so that they can be compared using the ComparatorMechanism’s
function. By default,
they use the format of the OutputStates specified in the sample and target arguments, respectively,
and the MappingProjection to each uses an
IDENTITY_MATRIX. Therefore, for the default configuration, the
OutputStates specified in the sample and target arguments must have values of the same length and type.
If these differ, the input_states argument can be used to explicitly specify the format of the ComparatorMechanism’s
SAMPLE and TARGET InputStates, to insure they are compatible with one another (as well as to customize their
names, if desired). If the input_states argument is used, both the sample and target InputStates must be
specified. Any of the formats for specifying InputStates can be used in the argument.
If values are assigned for the InputStates, they must be of equal length and type. Their types must
also be compatible with the value of the OutputStates specified in the sample and target arguments. However,
the length specified for an InputState can differ from its corresponding OutputState; in that case, by default, the
MappingProjection created uses a
FULL_CONNECTIVITY matrix. Thus, OutputStates of differing lengths can be mapped
to the sample and target InputStates of a ComparatorMechanism (see the example below),
so long as the latter are of the same length. If a projection other than a
FULL_CONNECTIVITY matrix is needed, this
can be specified using the PROJECTION entry of a State specification dictionary for the
InputState in the input_states argument.
A ComparatorMechanism has two
input_states, each of which receives a
MappingProjection from a corresponding OutputState specified in the sample and target arguments of its
constructor. The InputStates are listed in the Mechanism’s
and named, respectively, SAMPLE and TARGET. The OutputStates from which they receive their projections (specified
in the sample and target arguments) are listed in the Mechanism’s
target attributes as well as in its
function compares the value of the sample and target
InputStates. By default, it uses a
LinearCombination function, assigning the sample InputState a
weight of -1 and the target a
weight of 1, so that the sample
is subtracted from the target. However, the
function can be customized, so long as
it is replaced with one that takes two arrays with the same format as its inputs and generates a similar array as its
result. The result is assigned as the value of the Comparator Mechanism’s OUTCOME (primary)
When a ComparatorMechanism is executed, it updates its input_states with the values of the OutputStates specified
in its sample and target arguments, and then uses its
compare these. By default, the result is assigned to the
value of its OUTCOME
output_state, and as the first item of the Mechanism’s
Formatting InputState values
The default_variable argument can be used to specify a particular format for the SAMPLE and/or TARGET InputStates
of a ComparatorMechanism. This can be useful when one or both of these differ from the format of the
OutputState(s) specified in the sample and target arguments. For example, for
Reinforcement Learning, a ComparatorMechanism is used to monitor an action selection Mechanism (the sample), and compare
this with a reinforcement signal (the target). In the example below, the action selection Mechanism is a
TransferMechanism that uses the
SoftMax function (and the
PROB as its output format) to select
an action. This generates a vector with a single non-zero value (the selected action). Because the output is a vector,
specifying it as the ComparatorMechanism’s sample argument will generate a corresponding InputState with a vector
as its value. This will not match the reward signal specified in the ComparatorMechanism’s target argument, the
value of which is a single scalar. This can be dealt with by explicitly specifying the format for the SAMPLE and
TARGET InputStates in the default_variable argument of the ComparatorMechanism’s constructor, as follows:
>>> import psyneulink as pnl
>>> my_action_selection_mech = pnl.TransferMechanism(size=5,
>>> my_reward_mech = pnl.TransferMechanism()
>>> my_comparator_mech = pnl.ComparatorMechanism(default_variable = [,],
my_action_selection_mechanism is specified to take an array of length 5 as its input, and therefore
generate one of the same length as its primary output. Since it is assigned as the sample
of the ComparatorMechanism, by default this will create a SAMPLE InputState of length 5, that will not match the
length of the TARGET InputState (the default for which is length 1). This is taken care of, by specifying the
default_variable argument as an array with two single-value arrays (corresponding to the SAMPLE and TARGET
InputStates). (In this example, the sample and target arguments are specified as Mechanisms since,
by default, each has only a single (primary) OutputState, that will be used; if either had
more than one OutputState, and one of those was desired, it would have had to be specified explicitly in the
sample or target argument).
Standard OutputStates for ComparatorMechanism
- the value of the sum squared error of the Mechanism’s function
- the value of the mean squared error of the Mechanism’s function
ComparatorMechanism( sample, target, input_states=[SAMPLE,TARGET] function=LinearCombination(weights=[[-1],], output_states=OUTCOME params=None, name=None, prefs=None)
Subclass of ObjectiveMechanism that compares the values of two OutputStates.
- sample (OutputState, Mechanism, value, or string) – specifies the value to compare with the
target by the
- target (OutputState, Mechanism, value, or string) – specifies the value with which the
sample is compared by the
- input_states (List[InputState, value, str or dict] or Dict : default [SAMPLE, TARGET]) – specifies the names and/or formats to use for the values of the sample and target InputStates;
by default they are named SAMPLE and TARGET, and their formats are match the value of the OutputStates
specified in the sample and target arguments, respectively (see Structure
for additional details).
- function (Function, function or method : default Distance(metric=DIFFERENCE)) – specifies the
function used to compare the
sample with the
- output_states (List[OutputState, value, str or dict] or Dict : default [OUTCOME]) – specifies the OutputStates for the Mechanism;
- params (Optional[Dict[param keyword: param value]]) – a parameter dictionary that can be used to specify the parameters for
the Mechanism, its function, and/or a custom function and its parameters. Values specified for parameters in
the dictionary override any assigned to those parameters in arguments of the
- name (str : default see
name) – specifies the name of the ComparatorMechanism.
- prefs (PreferenceSet or specification dict : default Mechanism.classPreferences) – specifies the
PreferenceSet for the ComparatorMechanism; see
prefs for details.
OutputState – determines the value to compare with the
target by the
OutputState – determines the value with which
sample is compared by the
ContentAddressableList[InputState, InputState] – contains the two InputStates named, by default, SAMPLE and TARGET, each of which receives a
MappingProjection from the OutputStates referenced by the
(see Structure for additional details).
CombinationFunction, function or method – used to compare the
sample with the
target. It can be any PsyNeuLink
or a python function that takes a 2d array with two items and returns a 1d array of the same length
as the two input items.
1d np.array – the result of the comparison carried out by the
OutputState – contains the primary OutputState of the ComparatorMechanism; the default is
its OUTCOME OutputState, the value of which is equal to the
attribute of the ComparatorMechanism.
ContentAddressableList[OutputState] – contains, by default, only the OUTCOME (primary) OutputState of the ComparatorMechanism.
2d np.array – contains one item that is the value of the OUTCOME OutputState.
str – the name of the ComparatorMechanism; if it is not specified in the name argument of the constructor, a
default is assigned by MechanismRegistry (see Naming for conventions used for default and duplicate names).
PreferenceSet or specification dict – the
PreferenceSet for the ComparatorMechanism; if it is not specified in the prefs argument of the
constructor, a default is assigned using
classPreferences defined in __init__.py (see PreferenceSet for details).