# LCAMechanism¶

## Overview¶

An LCAMechanism is a subclass of RecurrentTransferMechanism that implements a single-layered 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 off-diagonal.

When all of the following conditions are true:

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 self-excitatory and mutually-inhibitory connections are implemented as a recurrent MappingProjection with a matrix in which the diagonal consists of uniform weights specified by self_excitation and the off-diagonal 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:

$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’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
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 the ENERGY metric
ENTROPY : float
the entropy of the result, which is calculated using the Stability Function with ENTROPY metric (Note: this is only present if the Mechanism’s function is bounded between 0 and 1)
MAX_VS_NEXT : 1d np.array
a two-element 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 in TRANSFER_RESULT (element 2)
MAX_VS_AVG : 1d np.array
a two-element 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 of RESULT’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 the LeakyCompetingIntegrator. (where rate = leak)

2. its matrix consisting of self_excitation and competition 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 or run method; also serves as a template to specify the length of variable for function, 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 time-averaged 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's previous_value 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. competition (value : default 1.0) – sets 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 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 of integrator_function, depending on whether integrator_mode is True or False. See noise for more details. integrator_mode (boolean : default True) – determines whether the LCAMechanism will execute its integrator_function. See integrator_mode for more details. time_step_size (float : default 0.1) – sets the time_step_size used by the mechanism’s integrator_function. See integrator_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 of clip 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; see prefs for details.
context : str : default ‘’componentType+INITIALIZNG’‘
string used for contextualization of instantiation, hierarchical calls, executions, etc.
variable

value – the input to the Mechanism’s function.

function

Function – the function used to transform the input.

matrix

2d np.array – 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.

leak

value : default 0.5 – sets the rate on the LeakyCompetingIntegrator function, which scales the contribution of the LeakyCompetingIntegrator's previous_value 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.

competition

value : default 1.0 – sets 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 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 time-averaged 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 the LeakyCompetingIntegrator. See LeakyCompetingIntegrator for more details on what it computes. Keep in mind that the leak parameter of the LCAMechanism determines the rate of the LeakyCompetingIntegrator.

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’s integrator_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 the integrator_function. Otherwise, noise is added to the output of the function.

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 of clip that it exceeds.
value : 2d np.array [array(float64)]
result of executing function; same value as fist item of output_values.

contains the following OutputStates: * TRANSFER_RESULT, the value of which is the result of function; * TRANSFER_MEAN, the value of which is the mean of the result; * TRANSFER_VARIANCE, the value of which is the variance of the result; * ENERGY, the value of which is the energy of the result,

calculated using the Stability Function with the ENERGY metric;
• ENTROPY, the value of which is the entropy of the result, calculated using the Stability Function with the ENTROPY metric; note: this is only present if the Mechanism’s function is bounded between 0 and 1 (e.g., the Logistic function);
• MAX_VS_NEXT, the value 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, the value 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 using classPreferences defined in __init__.py (see PreferenceSet for details).
Returns: instance of LCAMechanism LCAMechanism