Table of Contents

ContrastiveHebbianMechanism

Contents

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 state_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 input_shapes or default_variable* arguments of other types of Mechanism). 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:

  • input_field: the leftmost number of elements determined by input_size;

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

  • target_field: the rightmost number of elements determined by target_size if separated is True; otherwise, the same as input_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

exception psyneulink.library.components.mechanisms.processing.transfer.contrastivehebbianmechanism.ContrastiveHebbianError(message, component=None)
class psyneulink.library.components.mechanisms.processing.transfer.contrastivehebbianmechanism.ContrastiveHebbianMechanism(input_size, hidden_size=None, target_size=None, separated=None, mode=None, continuous=None, clamp=None, combination_function=None, function=None, matrix=None, auto=None, hetero=None, integrator_function=None, initial_value=None, noise=None, integration_rate=None, integrator_mode=None, clip=None, minus_phase_termination_condition=None, minus_phase_termination_threshold=None, plus_phase_termination_condition=None, plus_phase_termination_threshold=None, phase_convergence_function=None, max_passes=None, enable_learning=None, learning_rate=None, learning_function=None, additional_input_ports=None, additional_output_ports=None, params=None, name=None, prefs=None, **kwargs)

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 reset 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

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

Type

int

hidden_size

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

Type

int

target_size

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.

Type

int

target_start

index of first unit of target_field.

Type

int

target_end

index of first unit after target_field.

Type

int

separated

determines whether target_field is different from input_field (True) or the same (False).

Type

bool : default True

recurrent_size

size of RECURRENT InputPort, current_activity, and CURRENT_ACTIVITY OutputPort.

Type

int

mode

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

Type

SIMPLE_HEBBIAN or None

recurrent_projection

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

Type

AutoAssociativeProjection

combination_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).

Type

method or function

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.

Type

HARD_CLAMP or SOFT_CLAMP

continuous

determines whether or not current_activity is reset at the beginning of the minus phase of execution. If False, it is set to initial_value.

Type

bool : default True

current_activity

the value of the actvity of the ContrastiveHebbianMechanism following its last execution.

Type

1d array of floats

input_activity

value of units in the input_field of current_activity.

Type

1d array of floats

hidden_activity

value of units in the hidden_field of current_activity; None if hidden_size = 0 or mode = SIMPLE_HEBBIAN.

Type

1d array of floats or None

target_activity

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.

Type

1d array of floats or None

recurrent_activity

same as current_activity

Type

1d array of floats

minus_phase_activity

the value of the current_activity at the end of the minus phase of execution.

Type

1d array of floats

plus_phase_activity

the value of the current_activity at the end of the plus phase of execution.

Type

1d array of floats

delta

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

Type

scalar

is_converged

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.

Type

bool

phase_convergence_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 the previous value; result is assigned as the value of delta.

Type

function

minus_phase_termination_condition

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.

Type

CONVERGENCE or COUNT: default CONVERGENCE

minus_phase_termination_threshold

the value used for the specified minus_phase_termination_condition to determine when the minus phase of execution terminates.

Type

float or int

plus_phase_termination_condition

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.

Type

CONVERGENCE or COUNT : default CONVERGENCE

plus_phase_termination_threshold

the value used for the specified plus_phase_termination_condition to determine when the plus phase of execution terminates.

Type

float or int

max_passes

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.

Type

int or None

execution_phase

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

Type

bool

output_ports

contains the following OutputPorts by default:

Type

ContentAddressableList[OutputPort]

standard_output_ports

list of Standard OutputPorts that includes the following in addition to the standard_output_ports of a RecurrentTransferMechanism:

OUTPUT_ACTIVITY1d 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_ACTIVITY1d np.array

array with current_activity.

ACTIVITY_DIFFERENCE1d np.array

array of element-wise differences between plus_phase_activity and minus_phase_activity.

MINUS_PHASE_ACTIVITY1d np.array

array minus_phase_activity (i.e., activity at the end of the minus phase of execution.

PLUS_PHASE_ACTIVITY1d np.array

array plus_phase_activity (i.e., activity at the end of the plus phase of execution.

Type

list[str]

Returns

instance of ContrastiveHebbianMechanism

Return type

ContrastiveHebbianMechanism

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

Validate shape and size of auto, hetero, matrix.

_instantiate_input_ports(input_ports=None, reference_value=None, context=None)

Call Port._instantiate_input_ports to instantiate orderedDict of InputPort(s)

This is a stub, implemented to allow Mechanism subclasses to override _instantiate_input_ports

or process InputPorts before and/or after call to _instantiate_input_ports

_instantiate_attributes_before_function(function=None, context=None)

using the matrix argument the user passed in (which is now stored in function_params), instantiate ParameterPorts for auto and hetero if they haven’t already been instantiated. This is useful if auto and hetero were None in the initialization call. :param function:

_instantiate_recurrent_projection(mech, matrix='HollowMatrix', context=None)

Instantiate an AutoAssociativeProjection from Mechanism to itself

_execute(variable=None, context=None, function_variable=None, runtime_params=None)

Execute TransferMechanism function and return transform of input

property _learning_signal_source

Override default to use ACTIVITY_DIFFERENCE as source of learning signal