LCAMechanism¶

Contents¶

Overview

Creating an LCAMechanism

Integration

Thresholding

Structure

Execution

Class Reference

Overview¶

An LCAMechanism is a subclass of RecurrentTransferMechanism that implements a single-layered leaky competitng accumulator (LCA) network. By default, it uses a LeakyCompetingIntegrator and a Logistic Function to compute the activity of the units, each of which has a self-excitatory connection (specified by the self_excitation argument) and mutually inhibitory connections with every other element (specified by the competition argument). These are implemented by its recurrent_projection, the matrix of which consists of diagnoal elements assign the value of self_excitation off-diagonal elements assigned the negative of the value of competition.

When all of the following conditions are true:

the LCAMechanism mechanism has two elements,
the value of its competition parameter is equal to its leak parameter,
competition and leak are of sufficient magnitude,

then the LCAMechanism implements a close approximation of a DDM Mechanism (see Usher & McClelland, 2001; and Bogacz et al (2006)).

Creating an LCAMechanism¶

An LCAMechanism is created by calling its constructor. Ordinarily, the self-excitation and competion arguments are used to specify the values of the diagonal and off-diagonal elements of the matrix of its recurrent_projection (see Structure below). However, if the matrix argument is specified, a warning is issued and the self_excitation and competition arguments are ignored.

Integration¶

The noise, leak, initial_value, and time_step_size arguments are used to implement the LeakyCompetingIntegrator as the LCAMechanism’s integrator_function. The leak argument is used to specify the leak parameter of the LeakyCompetingIntegrator. This function is only used used when integrator_mode is True (which it is by default). If integrator_mode is False, the LeakyCompetingIntegrator function is skipped entirely, and all related arguments (noise, leak, initial_value, and time_step_size) have no effect.

Thresholding¶

The threshold and threshold_criterion arguments specify the conditions under which execution of the LCAMechanism terminates if integrator_mode is True. If threshold is None (the default), then the LCAMechanism will update its value and the value of each OutputPort only once each time it is executed. If a threshold is specified, then it will continue to execute until the condition specified by threshold_criterion is True; this can be specified using one of the following keywords:

VALUE – (default) True when any element of the LCAMechanism’s value is equal to or greater than the threshold;

MAX_VS_NEXT – True when the element of the LCAMechanism’s value with the highest values is greater than the one with the next-highest value by an amount that equals or exceeds threshold;

MAX_VS_AVG – True when the element of the LCAMechanism’s value with the highest values is greater than the average of the others by an amount that equals or exceeds threshold;

CONVERGENCE – True when the no element of the LCAMechanism’s current value differs from its value on the previous update by more than threshold.

For an LCAMechanism with exactly two elements, MAX_VS_NEXT implements a close approximation of the threshold parameter of the DriftDiffusionIntegrator Function used by a DDM (see Usher & McClelland, 2001; and Bogacz et al (2006)). For an LCAMechanism with more than two elements, MAX_VS_NEXT and MAX_VS_AVG implements threshold approximations with different properties (see McMillen & Holmes, 2006). CONVERGENCE (the default for a TransferMechanism) implements a “settling” process, in which the Mechanism stops executing when updating produces sufficiently small changes.

Note that threshold and threshold_criterion are convenience arguments, and are not associated with similarly-named attributes. Rather, they are used to specify the termination_threshold, termination_measure, and termination_comparison_op attributes; these can also be specified directly as arguments of the LCAMechanism’s constructor in order to implement other termination conditions (see TransferMechanism for additional details).

Structure¶

The key state_features that disinguish an LCAMechanism from its parent class (RecurrentTransferMechainsm) are:

its default function is a Logistic Function (rather than Linear);
its default integrator_function is a LeakyCompetingIntegrator Function (rather than AdaptiveIntegrator);
the matrix of its recurrent_projection, by default, has diagonal elements with uniform weights assigned the value of self_excitation, and off-diagonal elements with uniform weights assigned the negative of the value of competition; however, if the matrix argument is specified, then self_excitation and competition are ignored.

Like any RecurrentTransferMechanism, by default an LCAMechanism has a single primary OutputPort named RESULT that contains the Mechanism’s current value. It also has two StandardOutputPorts in its standard_output_ports attribute – MAX_VS_NEXT and MAX_VS_AVG that are available for assignment, in addition to the standard_output_ports of a RecurrentTransferMechanism:

The value of the MAX_VS_NEXT OutputPort contains the difference between the two elements of the LCAMechanism’s value with the highest values, and the value of the MAX_VS_AVG OutputPort contains the difference between the element with the highest value and the average of all the others (see above for their relationship to the output of a DDM Mechanism).

Execution¶

The execution of an LCAMechanism is identical to that of RecurrentTransferMechanism.

Class Reference¶

class psyneulink.library.components.mechanisms.processing.transfer.lcamechanism.LCAMechanism(default_variable=None, input_shapes=None, input_ports=None, function=None, initial_value=None, leak=None, competition=None, hetero=None, self_excitation=None, noise=None, integrator_mode=None, time_step_size=None, clip=None, output_ports=None, integrator_function=None, params=None, name=None, prefs=None, **kwargs)¶

Subclass of RecurrentTransferMechanism that implements a Leaky Competitive Accumulator. See RecurrentTransferMechanism for additional arguments and attributes.

Parameters

leak (value : default 0.5) – specifies the leak for the LeakyCompetingIntegrator Function (see leak for additional details).
competition (value : default 1.0) – specifies the magnitude of the off-diagonal terms in the LCAMechanism’s recurrent_projection (see competition for additional details).
self_excitation (value : default 0.0) – specifies the magnidute of the diagonal terms in the LCAMechanism’s recurrent_projection (see self_excitation for additional details).
time_step_size (float : default 0.1) – assigned as the time_step_size parameter of the LeakyCompetingIntegrator Function (see time_step_size for additional details).
threshold (float or None : default None) – specifes the value at which the Mechanism’s is_finished attribute is set to True (see Thresholding for additional details).
threshold_criterion (VALUE, MAX_VS_NEXT, MAX_VS_AVG, or CONVERGENCE) – specifies the criterion that is used to evaluate whether the threshold has been reached. If MAX_VS_NEXT or MAX_VS_AVG is specified, then the length of the LCAMCechanism’s value must be at least 2 (see Thresholding for additional details).

matrix¶

the matrix parameter of the recurrent_projection for the Mechanism, the self_excitation attribute sets the values on the diagonal, and the competition attribute sets the magnitude of the negative off-diagonal values.

Type: 2d np.array

leak¶

determines the leak for the LeakyCompetingIntegrator Function, which scales the contribution of its previous_value to the accumulation of its variable (\(x_{i}\)) on each time step (see LeakyCompetingIntegrator for additional details.

Type: value

competition¶

determines the magnitude of the off-diagonal terms in the LCAMechanism’s recurrent_projection, thereby scaling the contributions of the competing unit (all \(f(x)_{j}\) where \(j \neq i\)) to the accumulation of the LeakyCompetingIntegrator's variable (\(x_{i}\)) on each time step (see LeakyCompetingIntegrator for additional details.

Type: value

self_excitation¶

determines the diagonal terms in the LCAMechanism’s recurrent_projection, thereby scaling the contributions of each unit’s own recurrent value (\(f(x)_{i}\)) to the accumulation of the LeakyCompetingIntegrator's variable (\(x_{i}\)) on each time step (see LeakyCompetingIntegrator for additional details.

Type: value

time_step_size¶

parameter of the LeakyCompetingIntegrator Function that determines the timing precision of the integration process it implements, and used to scale its noise parameter appropriately.

Type: float

standard_output_ports¶

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

MAX_VS_NEXTfloat: the difference between the two elements of the LCAMechanism’s value with the highest values.

MAX_VS_AVGfloat: the difference between the element of the LCAMechanism’s value and the average of all of the other elements.

Type: list[str]

Returns: instance of LCAMechanism
Return type: LCAMechanism

_parse_threshold_args(kwargs)¶

Implements convenience arguments threshold and threshold_criterion

These are translated into the appropriate specifications for the termination_threshold, termination_measure, and termination_comparison_op for TransferMechanism.

Note: specifying (threshold and termination_threshold) and/or (threshold and threshold_criterion and termination_measure) causes an error.

exception psyneulink.library.components.mechanisms.processing.transfer.lcamechanism.LCAError(message, component=None)¶