LCAMechanism¶
Contents¶
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 itsleak
parameter,competition
andleak
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 aLogistic
Function (rather thanLinear
);its default
integrator_function
is aLeakyCompetingIntegrator
Function (rather thanAdaptiveIntegrator
);the
matrix
of itsrecurrent_projection
, by default, has diagonal elements with uniform weights assigned the value ofself_excitation
, and off-diagonal elements with uniform weights assigned the negative of the value ofcompetition
; however, if the matrix argument is specified, thenself_excitation
andcompetition
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(leak=0.5, competition=1.0, self_excitation=0.0, time_step_size=0.1, threshold = None threshold_criterion = VALUE)¶
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 theLeakyCompetingIntegrator
Function (seeleak
for additional details).competition (value : default 1.0) – specifies the magnitude of the off-diagonal terms in the LCAMechanism’s
recurrent_projection
(seecompetition
for additional details).self_excitation (value : default 0.0) – specifies the magnidute of the diagonal terms in the LCAMechanism’s
recurrent_projection
(seeself_excitation
for additional details).time_step_size (float : default 0.1) – assigned as the
time_step_size
parameter of theLeakyCompetingIntegrator
Function (seetime_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 therecurrent_projection
for the Mechanism, theself_excitation
attribute sets the values on the diagonal, and thecompetition
attribute sets the magnitude of the negative off-diagonal values.- Type
2d np.array
- leak¶
determines the
leak
for theLeakyCompetingIntegrator
Function, which scales the contribution of itsprevious_value
to the accumulation of itsvariable
(\(x_{i}\)) on each time step (seeLeakyCompetingIntegrator
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 theLeakyCompetingIntegrator's
variable
(\(x_{i}\)) on each time step (seeLeakyCompetingIntegrator
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 theLeakyCompetingIntegrator's
variable
(\(x_{i}\)) on each time step (seeLeakyCompetingIntegrator
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 itsnoise
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
- _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(error_value)¶