# ContrastiveHebbianMechanism¶

## Overview¶

A ContrastiveHebbianMechanism is a subclass of RecurrentTransferMechanism that is customized for use with the Contrastive Hebbian learning rule. See the following references for a description of the learning rule, its relationship to the backpropagation learning rule, and its use in connectionist networks:

The features and operation of a ContrastiveHebbianMechanism that differ from those of a RecurrentTransferMechanism are described below.

## Creating a ContrastiveHebbianMechanism¶

### Size¶

The input_size argument of the constructor must always be specified (this is comparable to specifying the size or default_variable* arguments of other types of Mechanisms). If it is specified on its own, it determines the total number of processing units. If either the hidden_size and/or target_size arguments are specified, then those units are treated as distinct from the input units (see Execution for details).

### Phases¶

A ContrastiveHebbianMechanism executes in two phases, and has minus_phase_termination_condition and plus_phase_termination_condition arguments, and corresponding minus_phase_termination_threshold and plus_phase_termination_threshold arguments, that determine when the respective phases of execution are terminated. Other parameters can also be configured that influence processing (see Execution).

### OututPorts¶

The Mechanism is automatically assigned three of its five standard_output_ports: OUTPUT_ACTIVITY, CURRENT_ACTIVITY, and ACTIVITY_DIFFERENT (see below). Additional OutputPorts can be specified in the additional_output_ports argument of the constructor.

### Learning¶

A ContrastiveHebbianMechanism can be configured for learning either by specifying enable_learning as True or using the configure_learning method, with the following differences from a standard RecurrentTransferMechanism: it is automatically assigned ContrastiveHebbian as its learning_function; its learning_condition is automatically assigned as CONVERGENCE; and it is assigned a MappingProjection from its ACTIVITY_DIFFERENCE (rather than its primary) OutputPort to the ACTIVATION_INPUT of its learning_mechanism.

### SIMPLE_HEBBIAN mode¶

This replicates the function of a standard RecurrentTransferMechanism using Hebbian Learning (e.g., for validation or ease in comparing processing outcomes). It is configured by specifying the mode argument as SIMPLE_HEBBIAN, which automatically makes the following assignments:

separated = False;
clamp = SOFT_CLAMP;
learning_function = Hebbian.

These assignments override any others made in the constructor, and the hidden_size and target_size arguments are ignored.

## Structure¶

### Input¶

A ContrastiveHebbianMechanism always has two, and possibly three InputPorts:

• INPUT: receives external input to the Mechanism;
• TARGET: only implemented if target_size is specified, **separated = True (default), and mode is not SIMPLE_HEBBIAN; receives the target specified in the run method of any Composition to which the Mechanism belongs.

The sizes of these are determined by arguments in its constructor, which generally conform to one of two configurations.

Standard Configuration – if input_size, hidden_size and target_size are all specified,
the sizes of the InputPorts are as follows:

INPUT: size = input_size
RECURRENT: size = input_size + hidden_size + target_size
TARGET: size = input_size

Simple Configuration – if target_size = None or 0, separated = False, and/or mode =
SIMPLE_HEBBIAN, the sizes of the InputPorts are as follows:

INPUT: size = input_size
RECURRENT: size = input_size + hidden_size
TARGET: Not implemented

Note

If separated = False and target_size is specified, a TARGET InputPort will be created, but target_size must equal input_size or an error will be generated.

The values of input_size, hidden_size and target_size are assigned to the Mechanism’s input_size, hidden_size, and target_size attributes, respectively.

The input_size and target_size (if separated is True) attribute(s), together with the separated attribute are used to define the fields of the RECURRENT InputPort’s value and the current_activity attribute used for updating values during execution, as follows:

• hidden_field: the elements of the RECURRENT InputPort and current_activity that are not within the input_field and/or target_field;

### Functions¶

In addition to its primary function, if either the minus_phase_termination_condition or plus_phase_termination_condition is specified as CONVERGENCE, then its phase_phase_convergence_function is used to determine when the corresponding phase of execution is complete. Its learning_function is automatically assigned as ContrastiveHebbian, but this can be replaced by any function that takes two 1d arrays (“activity ports”) and compares them to determine the matrix of the Mechanism’s recurrent_projection. If mode is specified as SIMPLE_HEBBIAN), the default function is Hebbian, but can be replaced by any function that takes and returns a 1d array.

### Output¶

A ContrastiveHebbianMechanism is automatically assigned three OutputPorts:

• OUTPUT_ACTIVITY: assigned as the primary OutputPort, and contains the pattern of activity the Mechanism is trained to generate. If target_size is specified, then it has the same size as the TARGET InputPort; if target_size is not specified or is 0, if separated is False, or if mode is SIMPLE_HEBBIAN, then the size of the OUTPUT_ACTIVITY OutputPort is the same as the INPUT InputPort (see Input).
• CURRENT_ACTIVITY: assigned the value of the current_activity attribute after each execution of the Mechanism, which contains the activity of all processing units in the Mechanism (input, hidden and/or target); has the same size as the RECURRENT InputPort.

These also appear in the ContrastiveHebbianMechanism’s standard_output_ports, along with two others – MINUS_PHASE_ACTIVITY and PLUS_PHASE_ACTIVITY – that it can be assigned, in addition to the standard_output_ports of a RecurrentTransferMechanism.

## Execution¶

### Processing¶

A ContrastiveHebbianMechanism always executes in two sequential phases, that together constitute a trial of execution:

The value of the INPUT, and possibly TARGET, InptutState(s) are combined with that of its RECURRENT InputPort using the combination_function. The manner in which these are combined is determined by the clamp attribute: if it is HARD_CLAMP they are used to replace the corresponding fields of RECURRENT; if it is SOFT_CLAMP, INPUT (and possibly TARGET) are added to RECURRENT; . The result is passed to the Mechanism’s integrator_function (if integrator_mode is True) and then its function.

If the termination condition for either phase is specified as CONVERGENCE, it uses the Mechanism’s phase_convergence_function, together with the termination_threshold specified for that phase, to determine when execution of that phase terminates. If max_passes is specified, and the number of executions in either phase reaches that value, an error is generated. Otherwise, once a trial of execution is complete (i.e, after completion of the minus phase), the following computations and assignments are made:

### Learning¶

If a ContrastiveHebbianMechanism is configured for learning, at the end of each trial of execution the value of its ACTIVITY_DIFFERENCE OutputPort is passed to its learning_mechanism. If the Mechanism is part of a System, then the learning_mechanism is executed during the execution phase of the System’s execution. Note that this is distinct from the behavior of supervised learning algorithms (such as Reinforcement and BackPropagation), that are executed during the learning phase of a System’s execution

## Class Reference¶

class psyneulink.library.components.mechanisms.processing.transfer.contrastivehebbianmechanism.ContrastiveHebbianMechanism(input_size=2, hidden_size=None, target_size=None, separated:bool=True, mode=None, continuous=True, clamp=HARD_CLAMP, minus_phase_termination_condition = CONVERGENCE, minus_phase_termination_threshold=.01, plus_phase_termination_condition = CONVERGENCE, plus_phase_termination_threshold=.01, phase_convergence_function=Distance(metric=MAX_ABS_DIFF), max_passes=None, additional_input_ports=None, additional_output_ports=None)

Subclass of RecurrentTransferMechanism that implements a single-layer auto-recurrent network using two-phases of execution and the Contrastive Hebbian Learning algorithm. See RecurrentTransferMechanism for additional arguments and attributes.

Parameters: input_size (int : default 0) – specifies the size of the INPUT InputPort and number of units in the input_field of current_activity. hidden_size (int : default None) – specifies the number of units in the hidden_field of current_activity. target_size (int : default None) – specifies the size of the TARGET InputPort, number of units in the input_field of current_activity, and of the OUTPUT_ACTIVITY OutputPort. separated (bool : default True) – specifies whether target_field should be different from the input_field. mode (SIMPLE_HEBBIAN or None : default None) – specifies configuratoin that emulates standard RecurrentTransferMechanism using Hebbian learning (see SIMPLE_HEBBIAN mode for details). combination_function (function : default None) – specifies function used to combine the INPUT, RECURRENT and TARGET (if specified) InputPorts; must accept a 2d array with two or three items of the same length, and generate a result that is the same size as recurrent_size; if None, the ContrastiveHebbianMechanism’s combination_function method is used. clamp (HARD_CLAMP or SOFT_CLAMP : default HARD_CLAMP) – specifies the manner in which the value of the INPUT and TARGET (if specified) InputPorts are combined with the RECURRENT InputPort in each execution (see clamp for additional details. continuous (bool : default True) – specifies whether or not to reinitialize current_activity at the beginning of the minus phase of a trial. minus_phase_termination_condition (COUNT or CONVERGENCE : default CONVERGENCE) – specifies the type of condition used to terminate the minus_phase of execution (see minus_phase_termination_condition for additional details). minus_phase_termination_threshold (float or int : default 0.01) – specifies the value used to determine when the minus_phase terminates; should be a float if minus_phase_termination_condition is CONVERGENCE, and int if it is COUNT (see minus_phase_termination_threshold for additional details). plus_phase_termination_condition (COUNT or CONVERGENCE : default CONVERGENCE) – specifies the type of condition used to terminate the plus_phase of execution (see plus_phase_termination_condition for additional details). plus_phase_termination_threshold (float or int : default 0.01) – specifies the value used to determine when the minus_phase terminates; should be a float if plus_phase_termination_condition is CONVERGENCE, and int if it is COUNT (see plus_phase_termination_threshold for additional details). phase_convergence_function (function : default Distance(metric=MAX_ABS_DIFF)) – specifies the function that determines when a phase of execution is complete if the termination condition for that phase is specified as CONVERGENCE, by comparing current_activity with the previous_value of the Mechanism; can be any function that takes two 1d arrays of the same length as variable and returns a scalar value. The default is the Distance Function, using the MAX_ABS_DIFF metric which computes the elementwise difference between two arrays and returns the difference with the maximum absolute value. max_passes (int : default 1000) – specifies maximum number of executions (passes) that can occur in an execution phase before reaching the termination_threshold for that phase, after which an error occurs; if None is specified, execution may continue indefinitely or until an interpreter exception is generated.
input_size

int – size of the INPUT InputPort and input_activity, and the number of units in the input_field of of current_activity.

hidden_size

int – size of hidden_activity, and number of units in current_activity and the hidden_field of the RECURRENT InputPort.

target_size

int – size of the TARGET InputPort if specified and, if so, the number of units in target_activity, the target_field of current_activity, and the OUTPUT_ACTIVITY OutputPort.

target_start

int – index of first unit of target_field.

target_end

int – index of first unit after target_field.

separated

bool : default True – determines whether target_field is different from input_field (True) or the same (False).

recurrent_size

int – size of RECURRENT InputPort, current_activity, and CURRENT_ACTIVITY OutputPort.

mode

SIMPLE_HEBBIAN or None – indicates whether SIMPLE_HEBBIAN was used for configuration (see SIMPLE_HEBBIAN mode for details).

recurrent_projection

AutoAssociativeProjection – an AutoAssociativeProjection that projects from the CURRENT_ACTIVITY OutputPort to the RECURRENT InputPort.

combination_function

method or function – used to combine value of the INPUT and TARGET (if specified) InputPorts with that of the RECURRENT InputPort to determine the variable passed to the Mechanism’s integrator_function and/or its function (see Execution for details).

clamp

HARD_CLAMP or SOFT_CLAMP – determines whether the value of the INPUT and TARGET (if specified) InputPorts replace (HARD_CLAMP) or are added to (SOFT_CLAMP) the value of the RECURRENT InputPort by combination_function.

continuous

bool : default True – determines whether or not current_activity is reinitialized at the beginning of the minus phase of execution. If False, it (and the Mechanism’s previous_value attribute) are set to initial_value.

current_activity

1d array of floats – the value of the actvity of the ContrastiveHebbianMechanism following its last execution.

input_activity

1d array of floats – value of units in the input_field of current_activity.

hidden_activity

1d array of floats or None – value of units in the hidden_field of current_activity; None if hidden_size = 0 or mode = SIMPLE_HEBBIAN.

target_activity

1d array of floats or None – value of units in the target_field of current_activity if TARGET InputPort is specified. Same as input_activity if separated is False; None if target_size = 0 or mode = SIMPLE_HEBBIAN.

recurrent_activity

1d array of floats – same as current_activity

minus_phase_activity

1d array of floats – the value of the current_activity at the end of the minus phase of execution.

plus_phase_activity

1d array of floats – the value of the current_activity at the end of the plus phase of execution.

delta

scalar – value returned by phase_convergence_function; used to determined when is_converged is True.

is_converged

bool – indicates when a phase of execution is complete, if the termination condition for that phase is specified as CONVERGENCE. True when delta is less than or equal to the termination_threshold speified for the corresponding phase.

phase_convergence_function

function – determines when a phase of execution is complete if the termination condition for that phase is specified as CONVERGENCE. Compares the value of current_activity with previous_value; result is assigned as the value of delta <ContrastiveHebbianMechanism.delta>.

minus_phase_termination_condition

CONVERGENCE or COUNT: default CONVERGENCE – determines the type of condition used to terminate the minus_phase of execution. If it is CONVERGENCE, execution continues until the value returned by phase_convergence_function is less than or equal to minus_phase_termination_threshold; if it is COUNT, the Mechanism is executed the number of times specified in minus_phase_termination_threshold.

minus_phase_termination_threshold

float or int – the value used for the specified minus_phase_termination_condition to determine when the minus phase of execution terminates.

plus_phase_termination_condition

CONVERGENCE or COUNT : default CONVERGENCE – determines the type of condition used to terminate the plus_phase of execution. If it is CONVERGENCE, execution continues until the value returned by phase_convergence_function is less than or equal to plus_phase_termination_threshold; if it is COUNT, the Mechanism is executed the number of times specified in plus_phase_termination_threshold.

plus_phase_termination_threshold

float or int – the value used for the specified plus_phase_termination_condition to determine when the plus phase of execution terminates.

max_passes

int or None – determines the maximum number of executions (passes) that can occur in an execution phase before reaching the corresponding termination_threshold for that phase, after which an error occurs; if None is specified, execution may continue indefinitely or until an interpreter exception is generated.

execution_phase

bool – indicates current phase of execution. False = minus phase; True = plus phase.

output_ports

ContentAddressableList[OutputPort] – contains the following OutputPorts by default:

standard_output_ports

list[str] – list of Standard OutputPorts that includes the following in addition to the standard_output_ports of a RecurrentTransferMechanism:

OUTPUT_ACTIVITY : 1d np.array
array with activity of the target_field of current_activity if a TARGET InputPort is specified; otherwise, has activity of the input_field of current_activity.
CURRENT_ACTIVITY : 1d np.array
array with current_activity.
ACTIVITY_DIFFERENCE : 1d np.array
array of element-wise differences between plus_phase_activity and minus_phase_activity.
MINUS_PHASE_ACTIVITY : 1d np.array
array minus_phase_activity (i.e., activity at the end of the minus phase of execution.
PLUS_PHASE_ACTIVITY : 1d np.array
array plus_phase_activity` (i.e., activity at the end of the plus phase of execution.
Returns: instance of ContrastiveHebbianMechanism ContrastiveHebbianMechanism