LCAMechanism¶
Overview¶
An LCAMechanism is a subclass of RecurrentTransferMechanism that implements a singlelayered leaky competitive accumulator
network, in which each element is connected to every other element with mutually inhibitory weights. The LCAMechanism’s recurrent
projection matrix always consists of self_excitation
on the diagonal and competition
offdiagonal.
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 can be created directly by calling its constructor.
The selfexcitatory and mutuallyinhibitory connections are implemented as a recurrent MappingProjection
with a matrix
in which the diagonal consists of uniform weights specified by self_excitation and the
offdiagonal consists of uniform weights specified by the negative of the competition argument.
The noise, leak, initial_value, and time_step_size arguments are used to implement the LeakyCompetingIntegrator
as the LCAMechanism.integrator_function
of the mechanism. integrator_mode determines whether the
LCAMechanism.integrator_function
will execute.
When integrator_mode is set to True:
the variable of the mechanism is first passed into the following equation:
The result of the integrator function above is then passed into the mechanism's function
. Note that on the
first execution, initial_value sets previous_value.
When integrator_mode is set to False:
The variable of the mechanism is passed into the function of the mechanism
. The mechanism’s
integrator_function
is skipped entirely, and all related arguments (noise, leak,
initial_value, and time_step_size) are ignored.
Structure¶
The key distinguishing features of an LCAMechanism are:
1. its integrator_function
, which implements the LeakyCompetingIntegrator
. (Note that a
standard RecurrentTransferMechanism would implement the AdaptiveIntegrator
as its integrator_function
)
2. its matrix
consisting of self_excitation
and competition
off diagonal.
In addition to its primary OutputState (which contains the current value of the elements of the LCAMechanism) and the OutputStates of a RecurrentTransferMechanism, it has two additional OutputStates:
MAX_VS_NEXT
MAX_VS_AVG
Both are two element arrays that track the element of the LCAMechanism with the currently highest value relative to the value of the others.
The two elements of the MAX_VS_NEXT
OutputState contain, respectively, the index of the
LCAMechanism element with the greatest value, and the difference between its value and the next highest one. MAX_VS_AVG
contains the index of the LCAMechanism element with the greatest value, and the difference between its value and the average
of all the others.
For an LCAMechanism with only two elements, MAX_VS_NEXT
implements a close approximation of the
threshold
parameter of 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_AVERAGE
implement threshold approximations with different properties
(see McMillen & Holmes, 2006).
Execution¶
The execution of an LCAMechanism is identical to that of RecurrentTransferMechanism.
Class Reference¶

class
psyneulink.library.components.mechanisms.processing.transfer.lcamechanism.
LCAMechanism_OUTPUT
¶ Standard OutputStates for LCAMechanism:
 RESULT : 1d np.array
 result of the
function
calculation
 OUTPUT_MEAN : float
 the mean of the result
 OUTPUT_VARIANCE : float
 the variance of the result
 ENERGY : float
 the energy of the result, which is calculated using the
Stability Function
with theENERGY
metric
 ENTROPY : float
 the entropy of the result, which is calculated using the
Stability Function
withENTROPY
metric (Note: this is only present if the Mechanism’sfunction
is bounded between 0 and 1)
 MAX_VS_NEXT : 1d np.array
 a twoelement Numpy array containing the index of the element of
RESULT
with the highest value (element 1) and the difference between that and the next highest one inTRANSFER_RESULT
(element 2)
 MAX_VS_AVG : 1d np.array
 a twoelement Numpy array containing the index of the element of
RESULT
with the highest value (element 1) and the difference between that and the average of the value of all ofRESULT
’s other elements

class
psyneulink.library.components.mechanisms.processing.transfer.lcamechanism.
LCAMechanism
( default_variable=None, size=None, function=Logistic, initial_value=None, leak=0.5, competition=1.0, self_excitation=0.0, noise=0.0, integrator_mode = True time_step_size = 0.1 clip=[float:min, float:max], params=None, name=None, prefs=None)¶ Subclass of RecurrentTransferMechanism that implements a Leaky Competitive Accumulator.
The key distinguishing features of an LCAMechanism are:
1. its
integrator_function
, which implements theLeakyCompetingIntegrator
. (where rate = leak)2. its
matrix
consisting ofself_excitation
andcompetition
off diagonal.Parameters:  default_variable (number, list or np.ndarray : default Transfer_DEFAULT_BIAS) – specifies the input to the Mechanism to use if none is provided in a call to its
execute
orrun
method; also serves as a template to specify the length ofvariable
forfunction
, and the primary OutputState of the Mechanism.  size (int, list or np.ndarray of ints) –
specifies variable as array(s) of zeros if variable is not passed as an argument; if variable is specified, it takes precedence over the specification of size. As an example, the following mechanisms are equivalent:
T1 = TransferMechanism(size = [3, 2]) T2 = TransferMechanism(default_variable = [[0, 0, 0], [0, 0]])
 function (TransferFunction : default Linear) – specifies the function used to transform the input; can be
Linear
,Logistic
,Exponential
, or a custom function.  initial_value (value, list or np.ndarray : default Transfer_DEFAULT_BIAS) – specifies the starting value for timeaveraged input (only relevant if
beta
is not 1.0).  leak (value : default 0.5) – sets the
rate
on the LeakyCompetingIntegrator function, which scales the contribution of the LeakyCompetingIntegrator'sprevious_value
to the accumulation of theLeakyCompetingIntegrator's value
(\(x_{i}\)) on each time step. See LeakyCompetingIntegrator for more details on what the LeakyCompetingIntegrator function computes.  competition (value : default 1.0) – sets the magnitude of the offdiagonal 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 value
(\(x_{i}\)) on each time step. See LeakyCompetingIntegrator for more details on what the LeakyCompetingIntegrator function computes.  self_excitation (value : default 0.0) – sets 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 value
(\(x_{i}\)) on each time step. See LeakyCompetingIntegrator for more details on what the LeakyCompetingIntegrator function computes.  noise (float or function : default 0.0) – a value added to the result of the
function
or to the result ofintegrator_function
, depending on whetherintegrator_mode
is True or False. Seenoise
for more details.  integrator_mode (boolean : default True) – determines whether the LCAMechanism will execute its
integrator_function
. Seeintegrator_mode
for more details.  time_step_size (float : default 0.1) – sets the time_step_size used by the mechanism’s
integrator_function
. Seeintegrator_mode
for more details.  clip (list [float, float] : default None (Optional)) – specifies the allowable range for the result of
function
the item in index 0 specifies the minimum allowable value of the result, and the item in index 1 specifies the maximum allowable value; any element of the result that exceeds the specified minimum or maximum value is set to the value ofclip
that it exceeds.
 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 LCAMechanism Mechanism.
 prefs : PreferenceSet or specification dict : default Mechanism.classPreferences
 specifies the
PreferenceSet
for the LCAMechanism Mechanism; seeprefs
for details.  context : str : default ‘’componentType+INITIALIZNG’‘
 string used for contextualization of instantiation, hierarchical calls, executions, etc.

function
¶ Function – the function used to transform the input.

matrix
¶ 2d np.array – 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 offdiagonal values.

leak
¶ value : default 0.5 – sets the
rate
on the LeakyCompetingIntegrator function, which scales the contribution of the LeakyCompetingIntegrator'sprevious_value
to the accumulation of theLeakyCompetingIntegrator's value
(\(x_{i}\)) on each time step. See LeakyCompetingIntegrator for more details on what the LeakyCompetingIntegrator function computes.

competition
¶ value : default 1.0 – sets the magnitude of the offdiagonal 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 value
(\(x_{i}\)) on each time step. See LeakyCompetingIntegrator for more details on what the LeakyCompetingIntegrator function computes.

self_excitation
¶ value : default 0.0 – sets 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 value
(\(x_{i}\)) on each time step. See LeakyCompetingIntegrator for more details on what the LeakyCompetingIntegrator function computes.

recurrent_projection
¶ MappingProjection – a MappingProjection that projects from the Mechanism’s primary OutputState back to it primary inputState.

initial_value
¶ value, list or np.ndarray : Transfer_DEFAULT_BIAS – determines the starting value for timeaveraged input (only relevant if
beta
parameter is not 1.0).

integrator_function
¶ When integrator_mode is set to True, the LCAMechanism executes its
integrator_function
, which is theLeakyCompetingIntegrator
. See LeakyCompetingIntegrator for more details on what it computes. Keep in mind that theleak
parameter of the LCAMechanism determines therate
of theLeakyCompetingIntegrator
.

integrator_mode
¶ When integrator_mode is set to True:
the variable of the mechanism is first passed into the following equation:
\[leak \cdot previous\_value + variable + noise \sqrt{time\_step\_size}\]The result of the integrator function above is then passed into the
mechanism's function
. Note that on the first execution, initial_value sets previous_value.When integrator_mode is set to False:
The variable of the mechanism is passed into the
function of the mechanism
. The mechanism’sintegrator_function
is skipped entirely, and all related arguments (noise, leak, initial_value, and time_step_size) are ignored.

noise
¶ float or function : default 0.0 – When
integrator_mode
is set to True, noise is passed into theintegrator_function
. Otherwise, noise is added to the output of thefunction
.If noise is a list or array, it must be the same length as
variable
.If noise is specified as a single float or function, while
variable
is a list or array, noise will be applied to each variable element. In the case of a noise function, this means that the function will be executed separately for each variable element.Note
In order to generate random noise, we recommend selecting a probability distribution function (see
Distribution Functions
for details), which will generate a new noise value from its distribution on each execution. If noise is specified as a float or as a function with a fixed output, then the noise will simply be an offset that remains the same across all executions.

clip
¶ list [float, float] : default None (Optional) – specifies the allowable range for the result of
function
the item in index 0 specifies the minimum allowable value of the result, and the item in index 1 specifies the maximum allowable value; any element of the result that exceeds the specified minimum or maximum value is set to
the value ofclip
that it exceeds.
 value : 2d np.array [array(float64)]
 result of executing
function
; same value as fist item ofoutput_values
.  output_states : ContentAddressableList[OutputState]
contains the following OutputStates: *
TRANSFER_RESULT
, thevalue
of which is the result offunction
; *TRANSFER_MEAN
, thevalue
of which is the mean of the result; *TRANSFER_VARIANCE
, thevalue
of which is the variance of the result; *ENERGY
, thevalue
of which is the energy of the result,calculated using theStability
Function with the ENERGY metric;ENTROPY
, thevalue
of which is the entropy of the result, calculated using theStability
Function with the ENTROPY metric; note: this is only present if the Mechanism’sfunction
is bounded between 0 and 1 (e.g., theLogistic
function);MAX_VS_NEXT
, thevalue
of which is a two element array: the first is the index of the element of RESULT with the highest value, and the second the difference between that and the next highest one in RESULT;MAX_VS_AVG
, thevalue
of which is a two element array: the first is the index of the element of RESULT with the highest value, and the second the difference between that and the average of the value of all its other elements;
 output_values : List[array(float64), float, float]
 a list with the following items:
* result of the
function
calculation (value of TRANSFER_RESULT OutputState); * mean of the result (value
of TRANSFER_MEAN OutputState) * variance of the result (value
of TRANSFER_VARIANCE OutputState); * energy of the result (value
of ENERGY OutputState); * entropy of the result (if the ENTROPY OutputState is present); * max_vs_next of the result (value
of MAX_VS_NEXT OutputState); * max_vs_avg of the result (value
of MAX_VS_AVG OutputState).  name : str
 the name of the LCAMechanism Mechanism; 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 LCAMechanism Mechanism; if it is not specified in the prefs argument of the constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).
Returns: instance of LCAMechanism Return type: LCAMechanism  default_variable (number, list or np.ndarray : default Transfer_DEFAULT_BIAS) – specifies the input to the Mechanism to use if none is provided in a call to its