Table of Contents

ComparatorMechanism

Contents

Overview

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 OUTCOME OutputPort.

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 OutputPorts that provide the sample and target inputs, respectively (see ObjectiveMechanism_Monitored_ports for details concerning their specification, which are special versions of an ObjectiveMechanism’s monitor argument). When the ComparatorMechanism is created, two InputPorts 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 OutputPort specified in the sample and target arguments.

It is important to recognize that the value of the SAMPLE and TARGET InputPorts 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 OutputPorts specified in the sample and target arguments, respectively, and the MappingProjection to each uses an IDENTITY_MATRIX. Therefore, for the default configuration, the OutputPorts specified in the sample and target arguments must have values of the same length and type. If these differ, the input_ports argument can be used to explicitly specify the format of the ComparatorMechanism’s SAMPLE and TARGET InputPorts, to insure they are compatible with one another (as well as to customize their names, if desired). If the input_ports argument is used, both the sample and target InputPorts must be specified. Any of the formats for specifying InputPorts can be used in the argument. If values are assigned for the InputPorts, they must be of equal length and type. Their types must also be compatible with the value of the OutputPorts specified in the sample and target arguments. However, the length specified for an InputPort can differ from its corresponding OutputPort; in that case, by default, the MappingProjection created uses a FULL_CONNECTIVITY matrix. Thus, OutputPorts of differing lengths can be mapped to the sample and target InputPorts 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 Port specification dictionary for the InputPort in the input_ports argument.

Structure

A ComparatorMechanism has two input_ports, each of which receives a MappingProjection from a corresponding OutputPort specified in the sample and target arguments of its constructor. The InputPorts are listed in the Mechanism’s input_ports attribute and named, respectively, SAMPLE and TARGET. The OutputPorts from which they receive their projections (specified in the sample and target arguments) are listed in the Mechanism’s sample and target attributes as well as in its monitor attribute. The ComparatorMechanism’s function compares the value of the sample and target InputPorts. By default, it uses a LinearCombination function, assigning the sample InputPort 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) OutputPort.

Execution

When a ComparatorMechanism is executed, it updates its input_ports with the values of the OutputPorts specified in its sample and target arguments, and then uses its function to compare these. By default, the result is assigned to the value of its OUTCOME output_port, and as the first item of the Mechanism’s output_values attribute.

Example

Formatting InputPort values

The default_variable argument can be used to specify a particular format for the SAMPLE and/or TARGET InputPorts of a ComparatorMechanism. This can be useful when one or both of these differ from the format of the OutputPort(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 InputPort 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 InputPorts in the default_variable argument of the ComparatorMechanism’s constructor, as follows:

>>> import psyneulink as pnl
>>> my_action_selection_mech = pnl.TransferMechanism(input_shapes=5,
...                                                  function=pnl.SoftMax(output=pnl.PROB))

>>> my_reward_mech = pnl.TransferMechanism()

>>> my_comparator_mech = pnl.ComparatorMechanism(default_variable = [[0],[0]],
...                                              sample=my_action_selection_mech,
...                                              target=my_reward_mech)

Note that 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 InputPort of length 5, that will not match the length of the TARGET InputPort (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 InputPorts). (In this example, the sample and target arguments are specified as Mechanisms since, by default, each has only a single (primary) OutputPort, that will be used; if either had more than one OutputPort, and one of those was desired, it would have had to be specified explicitly in the sample or target argument).

Class Reference

class psyneulink.library.components.mechanisms.processing.objective.comparatormechanism.ComparatorMechanism(default_variable=None, sample=None, target=None, function=None, output_ports=None, params=None, name=None, prefs=None, **kwargs)

Subclass of ObjectiveMechanism that compares the values of two OutputPorts. See ObjectiveMechanism for additional arguments and attributes.

Parameters

  • sample (OutputPort, Mechanism, value, or string) – specifies the value to compare with the target by the function.

  • target (OutputPort, Mechanism, value, or string) – specifies the value with which the sample is compared by the function.

  • input_ports (List[InputPort, 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 InputPorts; by default they are named SAMPLE and TARGET, and their formats are match the value of the OutputPorts 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 target.

sample

determines the value to compare with the target by the function.

Type

OutputPort

target

determines the value with which sample is compared by the function.

Type

OutputPort

input_ports

contains the two InputPorts named, by default, SAMPLE and TARGET, each of which receives a MappingProjection from the OutputPorts referenced by the sample and target attributes (see Structure for additional details).

Type

ContentAddressableList[InputPort, InputPort]

function

used to compare the sample with the target. It can be any TransformFunction, 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.

Type

TransformFunction, function or method

output_port

contains the primary OutputPort of the ComparatorMechanism; the default is its OUTCOME OutputPort, the value of which is equal to the value attribute of the ComparatorMechanism.

Type

OutputPort

output_ports

contains, by default, only the OUTCOME (primary) OutputPort of the ComparatorMechanism.

Type

ContentAddressableList[OutputPort]

output_values

contains one item that is the value of the OUTCOME OutputPort.

Type

2d np.array

standard_output_ports

list of Standard OutputPorts that includes the following in addition to the standard_output_ports of an ObjectiveMechanism:

SUM

the sum of the terms in in the array returned by the Mechanism’s function.

SSE

the sum of squares of the terms in the array returned by the Mechanism’s function.

MSE

the mean of the squares of the terms returned by the Mechanism’s function.

Type

list[str]

_validate_params(request_set, target_set=None, context=None)

If sample and target values are specified, validate that they are compatible

exception psyneulink.library.components.mechanisms.processing.objective.comparatormechanism.ComparatorMechanismError(message, component=None)