# 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.

## Creation¶

### Size¶

The input_size argument of the constructor must always be specified (this is comparable to specifying the size or default_variable* arugments 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_criterion and plus_phase_termination_criterion arguments, that determine when the respective phases of execution are terminated. Other parameters can also be configured that influence processing (see Execution).

### OututStates¶

The Mechanism is automatically assigned three of its five Standard OutputStates: OUTPUT_ACTIVITY_OUTPUT, CURRENT_ACTIVITY_OUTPUT, and ACTIVITY_DIFFERENT_OUTPUT (see below). Additional OutputStates can be specified in the additional_output_states 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_OUTPUT (rather than its primary) OutputState 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 InputStates:

• 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 System 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 InputStates 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 InputStates 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 InputState 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 InputState’s value and the current_activity attribute used for updating values during execution, as follows:

• hidden_field: the elements of the RECURRENT InputState 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 convergence_function, that 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 states”) 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 OutputStates:

• OUTPUT_ACTIVITY_OUTPUT: assigned as the primary OutputState, 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 InputState; 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_OUTPUT OutputState is the same as the INPUT InputState (see Input).
• CURRENT_ACTIVITY_OUTPUT: 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 InputState.

A ContrastiveHebbianMechanism also has two additional Standard OutputStatesMINUS_PHASE_OUTPUT and PLUS_PHASE_ACTIVITY_OUTPUT – that it can be assigned, as well as those of a RecurrentTransferMechanism or TransferMechanism.

## 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 InputState 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 convergence_function, together with the convergence criterion 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_OUTPUT OutputState 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.CONTRASTIVE_HEBBIAN_OUTPUT

Standard OutputStates for ContrastiveHebbianMechanism (in addition to those for RecurrentTransferMechanism and TransferMechanism):

OUTPUT_ACTIVITY_OUTPUT : 1d np.array
array with activity of the target_field of current_activity if a TARGET InputState is specified; otherwise, has activity of the input_field of current_activity.
CURRENT_ACTIVITY_OUTPUT : 1d np.array
array with current_activity.
ACTIVITY_DIFFERENCE_OUTPUT : 1d np.array
array of element-wise differences between plus_phase_activity and minus_phase_activity.
MINUS_PHASE_OUTPUT : 1d np.array
array minus_phase_activity (i.e., activity at the end of the minus phase of execution.
PLUS_PHASE_OUTPUT : 1d np.array
array plus_phase_activity (i.e., activity at the end of the plus phase of execution.
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, function=Linear, integrator_functon=AdapativeIntegrator, combination_function=LinearCombination, matrix=HOLLOW_MATRIX, auto=None, hetero=None, initial_value=None, noise=0.0, integration_rate=0.5, integrator_mode=False, integration_rate=0.5, clip=[float:min, float:max], minus_phase_termination_condition = CONVERGENCE, minus_phase_termination_criterion=.01, plus_phase_termination_condition = CONVERGENCE, plus_phase_termination_criterion=.01, convergence_function=Distance(metric=MAX_ABS_DIFF), max_passes=None, enable_learning=False, learning_rate=None, learning_function=ContrastiveHebbian, additional_input_states=None, additional_output_states=None, params=None, name=None, prefs=None)

Subclass of RecurrentTransferMechanism that implements a single-layer auto-recurrent network using two-phases of execution and the Contrastive Hebbian Learning algorithm

Parameters: input_size (int : default 0) – specifies the size of the INPUT InputState 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 InputState, number of units in the input_field of current_activity, and of the OUTPUT_ACTIVITY_OUTPUT OutputState. 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) InputStates; 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) InputStates are combined with the RECURRENT InputState in each execution (see clamp for additional details. function (TransferFunction : default Linear) – specifies the function used to transform the input; can be any function that takes and returns a 1d array of scalar values. matrix (list, np.ndarray, np.matrix, matrix keyword, or AutoAssociativeProjection : default HOLLOW_MATRIX) – specifies the matrix to use for recurrent_projection; see matrix argument of RecurrentTransferMechanism for details of specification. auto (number, 1D array, or None : default None) – specifies matrix with diagonal entries equal to auto; see auto argument of RecurrentTransferMechanism for details of specification. hetero (number, 2D array, or None : default None) – specifies a hollow matrix with all non-diagonal entries equal to hetero; see hetero argument of RecurrentTransferMechanism for details of specification. continuous (bool : default True) – specifies whether or not to reinitialize current_activity at the beginning of the minus phase of a trial. integrator_function (IntegratorFunction : default AdaptiveIntegrator) – specifies IntegratorFunction to use in integration_mode. initial_value (value, list or np.ndarray : default Transfer_DEFAULT_BIAS) – specifies the starting value for time-averaged input if integrator_mode is True. noise (float or function : default 0.0) – specifies value added to the result of the function, or to the result of integrator_function if integrator_mode is True; see noise for additional details. integration_rate (float : default 0.5) – the rate used for exponential time averaging of input when integrator_mode is True; see integration_rate for additional details. clip (list [float, float] : default None (Optional)) – specifies the allowable range for the result of function; see clip for additional details. 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_criterion (float : default 0.01) – specifies the value of delta used to determine when the minus_phase completes. 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_criterion (float : default 0.01) – specifies the value of delta used to determine when the plus_phase completes. convergence_function (function : default Distance(metric=MAX_ABS_DIFF)) – specifies the function that determines when a phase of execution 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 convergence_criterion, after which an error occurs; if None is specified, execution may continue indefinitely or until an interpreter exception is generated. enable_learning (boolean : default False) – specifies whether the Mechanism should be configured for learning. learning_rate (scalar, or list, 1d or 2d np.array, or np.matrix of numeric values: default False) – specifies the learning rate used by its learning function. If it is None, the default learning_rate for a LearningMechanism is used; if it is assigned a value, that is used as the learning_rate (see learning_rate for details). learning_function (function : default ContrastiveHebbian) – specifies the function for the LearningMechanism if learning is specified. It can be any function so long as it takes a list or 1d array of numeric values as its variable and returns a square matrix of numeric values with the same dimensions as the length of the input. params (Dict[param keyword: param value] : default None) – 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 constructor. name (str : default see name) – specifies the name of the ContrastiveHebbianMechanism. prefs (PreferenceSet or specification dict : default Mechanism.classPreferences) – specifies the PreferenceSet for the ContrastiveHebbianMechanism; see prefs for details. context (str : default componentType+INITIALIZING) – string used for contextualization of instantiation, hierarchical calls, executions, etc.
input_size

int – size of the INPUT InputState 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 InputState.

target_size

int – size of the TARGET InputState if specified and, if so, the number of units in target_activity, the target_field of current_activity, and the OUTPUT_ACTIVITY_OUTPUT OutputState.

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 InputState, current_activity, and CURRENT_ACTIVITY_OUTPUT OutputState.

mode

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

matrix

2d np.array – the matrix parameter of the recurrent_projection for the Mechanism.

recurrent_projection

AutoAssociativeProjection – an AutoAssociativeProjection that projects from the CURRENT_ACTIVITY_OUTPUT OutputState to the RECURRENT InputState.

variable

value – the input to Mechanism’s function.

combination_function

method or function – used to combine value of the INPUT and TARGET (if specified) InputStates with that of the RECURRENT InputState 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) InputStates replace (HARD_CLAMP) or are added to (SOFT_CLAMP) the value of the RECURRENT InputState 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.

integrator_function
IntegratorFunction – the IntegratorFunction used when integrator_mode is set to

True (see integrator_mode for details).

Note

The ContrastiveHebbianMechanism’s integration_rate, noise, and initial_value parameters specify the respective parameters of its integrator_function (with initial_value corresponding to initializer of integrator_function.

initial_value : value, list or np.ndarray
determines the starting value for time-averaged input if integrator_mode is True. See TransferMechanism’s initial_value for additional details.
noise

float or function – When integrator_mode is set to True, noise is passed into the integrator_function. Otherwise, noise is added to the result of the function. See TransferMechanism’s noise for additional details.

integrator_mode

determines whether input is first processed by integrator_function before being passed to function; see TransferMechanism’s integrator_mode for additional details.

integrator_function

used by the Mechanism when it executes if integrator_mode is True. Uses the integration_rate parameter of the ContrastiveHebbianMechanism as the rate of the ContrastiveHebbianMechanism’s integrator_function; see TransferMechanism’s integrator_function and Execution above for additional details).

integration_rate

float – the rate used for exponential time averaging of input when integrator_mode is set to True; see TransferMechanism’s integration_rate for additional details.

function

Function – used to transform the input and generate the Mechanism’s value (see Execution for additional details).

clip

list [float, float] – determines the allowable range for the result of function see TransferMechanism’s clip for additional details.

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 InputState 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.

previous_value

1d array of floats – the value of current_activity on the previous execution in the current phase.

delta

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

is_converged

boolTrue when delta is less than or equal to the minus_phase_termination_criterion in the minus_phase) or plus_phase_termination_criterion in the minus_phase).

convergence_function

function – compares the value of current_activity with previous_value; result is assigned as the value of delta is complete if the termination condition for that phase is specified as CONVERGENCE.

minus_phase_termination_condition

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

minus_phase_termination_criterion

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

plus_phase_termination_condition

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

plus_phase_termination_criterion

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

max_passes

int or None – determines the maximum number of executions (passes) that can occur in an execution phase before reaching the corresponding convergence_criterion, 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.

learning_enabled

bool – indicates whether learning is enabled; see learning_enabled of RecurrentTransferMechanism for additional details.

learning_mechanism

LearningMechanism – created automatically if learning is specified, and used to train the recurrent_projection.

learning_rate

float, 1d or 2d np.array, or np.matrix of numeric values – determines the learning rate used by the learning_function of the learning_mechanism (see learning_rate for details concerning specification and default value assignment).

learning_function

function – the function used by the learning_mechanism to train the recurrent_projection if learning is configured; default is ContrastiveHebbian.

value

2d np.array – result of executing function; same value as first item of output_values.

output_states

Dict[str: OutputState] – an OrderedDict with the following OutputStates by default:

output_values

List[1d np.array] – a list with the value of each OutputState in output_states.

name

str – the name of the ContrastiveHebbianMechanism; 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).

prefs

PreferenceSet or specification dict – the PreferenceSet for the ContrastiveHebbianMechanism; 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).

Returns: instance of ContrastiveHebbianMechanism ContrastiveHebbianMechanism