LCControlMechanism¶

Overview¶

An LCControlMechanism is a ControlMechanism that multiplicatively modulates the function of one or more Mechanisms (usually TransferMechanisms). It implements an abstract model of the locus coeruleus (LC) that uses an FHNIntegrator Function to generate its output. This is modulated by a mode parameter that regulates its function between "tonic" and "phasic" modes of operation. The Mechanisms modulated by an LCControlMechanism can be listed using its show method. When used with an AGTControlMechanism to regulate the mode parameter of its FHNIntegrator Function, it implements a form of the Adaptive Gain Theory of the locus coeruleus-norepinephrine (LC-NE) system.

Creating an LCControlMechanism¶

An LCControlMechanism can be created in any of the ways used to create a ControlMechanism. The following sections describe how to specify the inputs that drive the LCControlMechanism’s response, and the Mechanisms that it controls.

ObjectiveMechanism and Monitored OutputStates¶

Like all ControlMechanisms, when an LCControlMechanism is created it automatically creates an ObjectiveMechanism, from which it receives its input. The ObjectiveMechanism receives its input from any OutputStates specified in monitor_for_control argument of the constructor for LCControlMechanism (or of a System for which it is assigned as a controller; see ObjectiveMechanism). By default, the ObjectiveMechanism is assigned a CombineMeans Function as its function (see ObjectiveMechanism). The ObjectiveMechanism can be customized using the objective_mechanism argument of the LCControlMechanism’s constructor; however, the value of its OUTCOME OutputState must be a scalar value (that is used as the input to the LCControlMechanism’s function to drive its phasic response.

Mechanisms to Modulate¶

The Mechanisms to be modulated by an LCControlMechanism are specified in the modulated_mechanisms argument of its constructor. An LCControlMechanism controls a Mechanism by modifying the multiplicative_param of the Mechanism’s function. Therefore, any Mechanism specified for control by an LCControlMechanism must be either a TransferMechanism, or a Mechanism that uses a TransferFunction or a class of Function that implements a multiplicative_param. The modulate_mechanisms argument must be a list of such Mechanisms. The keyword ALL can also be used to specify all of the eligible ProcessMechanisms in all of the Compositions to which the LCControlMechanism belongs. If a Mechanism specified in the modulated_mechanisms argument does not implement a multiplicative_param, it is ignored. A ControlProjection is automatically created that projects from the LCControlMechanism to the ParameterState for the multiplicative_param of every Mechanism specified in the modulated_mechanisms argument. The Mechanisms modulated by an LCControlMechanism are listed in its modulated_mechanisms attribute).

Structure¶

Input¶

An LCControlMechanism has a single (primary) InputState, the value of which is a scalar that is provided by a MappingProjection from the OUTCOME OutputState of the LCControlMechanism’s ObjectiveMechanism. That value is used as the input to the LCControlMechanism’s function, which drives its phasic response.

ObjectiveMechanism¶

The ObjectiveMechanism for an LCControlMechanism receives its inputs from the OutputState(s) specified the monitor_for_control argument of the LCControlMechanism constructor, or the montiored_output_states argument of the LCControlMechanism’s ObjectiveMechanism. By default, the ObjectiveMechanism is assigned a CombineMeans Function with a default operation of SUM; this takes the mean of each array that the ObjectiveMechanism receives from the value of each of the OutputStates that it monitors, and returns the sum of these means. The value of each OutputState can be weighted (multiplicatively and/or exponentially), by specifying this in the monitor_for_control argument of the LCControlMechanism (see ObjectiveMechanism for details). As with any ControlMechanism, its ObjectiveMechanism can be explicitly specified to customize its function or any of its other parameters, by specifyihng it in the objective_mechanism argument of the LCControlMechanism’s constructor.

Note

If an ObjectiveMechanism is specified in the objective_mechanism argument of the LCControlMechanism’s constructor, then its attribute values (including any defaults) override those used by a LCControlMechanism for creating its objective_mechanism. In particular, whereas an ObjectiveMechanism uses LinearCombination as the default for its function, an LCControlMechanism uses CombineMeans as the function of its objective_mechanism. As a consequence, if an ObjectiveMechanism is explicitly specified in the LCControlMechanism’s objective_mechanism argument, and its function argument is not also explicitly specified as CombineMeans, then LinearCombination will be used for the ObjectiveMechanism’s function. To insure that CombineMeans is used, it must be specified explicitly in the function argument of the constructor for the ObjectiveMechanism (for an example of a similar condition for an EVCControlMechanism see 1st example under Specifying Control for a System).

The ObjectiveFunction is listed in the LCControlMechanism’s objective_mechanism attribute. The OutputStates it monitors are listed in the ObjectiveMechanism’s monitored_output_states attribute) as well as the LCControlMechanism’s monitor_for_control attribute. These can be displayed using the LCControlMechanism’s show method.

Function¶

An LCControlMechanism uses the FHNIntegrator as its function; this implements a FitzHugh-Nagumo model often used to describe the spiking of a neuron, but in this case the population activity of the LC (see Gilzenrat et al., 2002). The FHNIntegrator Function of an LCControlMechanism takes a scalar as its variable, received from the the input to the LCControlMechanism, and the result serves as the allocation_policy for the LCControlMechanism. All of the parameters of the FHNIntegrator function are accessible as attributes of the LCControlMechanism.

LC Modes of Operation¶

The mode parameter of the LCControlMechanism’s FHNIntegrator Function regulates its operation between “tonic” and “phasic” modes:

in the tonic mode (low value of mode), the output of the LCControlMechanism is moderately low and constant; that is, it is relatively unaffected by its input <LCControlMechanism_Input. This blunts the response of the Mechanisms that the LCControlMechanism controls to their inputs.

in the phasic mode (high value of mode), when the input to the LCControlMechanism is low, its output is even lower than when it is in the tonic regime, and thus the response of the Mechanisms it controls to their outputs is even more blunted. However, when the LCControlMechanism’s input rises above a certain value (determined by the threshold parameter), its output rises sharply generating a “phasic response”, and inducing a much sharper response of the Mechanisms it controls to their inputs.

Output¶

An LCControlMechanism has a single ControlSignal, that uses its allocation_policy (the scalar value generated by its function) to modulate the function of the Mechanism(s) it controls. The ControlSignal is assigned a ControlProjection to the ParameterState for the multiplicative_param of the function for each of those Mechanisms. The Mechanisms modulated by an LCControlMechanism are listed in its modulated_mechanisms attribute) and can be displayed using its show method.

Examples

The following example generates an LCControlMechanism that modulates the function of two TransferMechanisms, one that uses a Linear function and the other a Logistic function:

>>> import psyneulink as pnl
>>> my_mech_1 = pnl.TransferMechanism(function=pnl.Linear,
...                                   name='my_linear_mechanism')
>>> my_mech_2 = pnl.TransferMechanism(function=pnl.Logistic,
...                                   name='my_logistic_mechanism')

>>> LC = LCControlMechanism(modulated_mechanisms=[my_mech_1, my_mech_2],
...                         name='my_LC')

Calling LC.show() generates the following report:

my_LC

  Monitoring the following Mechanism OutputStates:

  Modulating the following parameters:
    my_logistic_mechanism: gain
    my_linear_mechanism: slope

Note that the LCControlMechanism controls the multiplicative_param of the function of each Mechanism: the gain parameter for my_mech_1, since it uses a Logistic Function; and the slope parameter for my_mech_2, since it uses a Linear Function.

Execution¶

An LCControlMechanism executes within a Compositions at a point specified in the Composition’s Scheduler or, if it is the controller for a Compositions, after all of the other Mechanisms in the Composition have executed in a TRIAL. It’s function takes the value of the LCControlMechanism’s primary InputState as its input, and generates a response – under the influence of its mode parameter – that is assigned as the allocation of its ControlSignals. The latter are used by its ControlProjections to modulate the response – in the next TRIAL of execution – of the Mechanisms the LCControlMechanism controls.

Note

A ParameterState that receives a ControlProjection does not update its value until its owner Mechanism executes (see Lazy Evaluation for an explanation of “lazy” updating). This means that even if a LCControlMechanism has executed, the multiplicative_param parameter of the function of a Mechanism that it controls will not assume its new value until that Mechanism has executed.

Class Reference¶

class psyneulink.library.subsystems.agt.lccontrolmechanism.LCControlMechanism(system=None, objective_mechanism=None, modulated_mechanisms=None, initial_w_FHN=0.0, initial_v_FHN=0.0, time_step_size_FHN=0.05, t_0_FHN=0.0, a_v_FHN=-1/3, b_v_FHN=0.0, c_v_FHN=1.0, d_v_FHN=0.0, e_v_FHN=-1.0, f_v_FHN=1.0, threshold_FHN=-1.0 time_constant_v_FHN=1.0, a_w_FHN=1.0, b_w_FHN=-0.8, c_w_FHN=0.7, mode_FHN=1.0, uncorrelated_activity_FHN=0.0 time_constant_w_FHN = 12.5, integration_method="RK4" base_level_gain=0.5, scaling_factor_gain=3.0, modulation=None, params=None, name=None, prefs=None)¶

Subclass of ControlMechanism that modulates the multiplicative_param of the function of one or more Mechanisms.

Parameters:

system (System : default None) – specifies the System for which the LCControlMechanism should serve as a controller; the LCControlMechanism will inherit any OutputStates specified in the monitor_for_control argument of the system’s constructor, and any ControlSignals specified in its control_signals argument.
objective_mechanism (ObjectiveMechanism, List[OutputState or Tuple[OutputState, list or 1d np.array, list or 1d np.array]] : default ObjectiveMechanism(function=CombineMeans)) – specifies either an ObjectiveMechanism to use for the LCControlMechanism or a list of the OutputStates it should monitor; if a list of OutputState specifications is used, a default ObjectiveMechanism is created and the list is passed to its monitored_output_states argument.
modulated_mechanisms (List[Mechanisms] or ALL) – specifies the Mechanisms to be modulated by the LCControlMechanism. If it is a list, every item must be a Mechanism with a function that implements a multiplicative_param; alternatively the keyword ALL can be used to specify all of the ProcessingMechanisms in the Composition(s) to which the LCControlMechanism belongs.
initial_w_FHN (float : default 0.0) – sets initial_w on the LCControlMechanism’s FHNIntegrator function
initial_v_FHN (float : default 0.0) – sets initial_v on the LCControlMechanism’s FHNIntegrator function
time_step_size_FHN (float : default 0.0) – sets time_step_size on the LCControlMechanism’s FHNIntegrator function
t_0_FHN (float : default 0.0) – sets t_0 on the LCControlMechanism’s FHNIntegrator function
a_v_FHN (float : default -1/3) – sets a_v on the LCControlMechanism’s FHNIntegrator function
b_v_FHN (float : default 0.0) – sets b_v on the LCControlMechanism’s FHNIntegrator function
c_v_FHN (float : default 1.0) – sets c_v on the LCControlMechanism’s FHNIntegrator function
d_v_FHN (float : default 0.0) – sets d_v on the LCControlMechanism’s FHNIntegrator function
e_v_FHN (float : default -1.0) – sets e_v on the LCControlMechanism’s FHNIntegrator function
f_v_FHN (float : default 1.0) – sets f_v on the LCControlMechanism’s FHNIntegrator function
threshold_FHN (float : default -1.0) – sets threshold on the LCControlMechanism’s FHNIntegrator function
time_constant_v_FHN (float : default 1.0) – sets time_constant_w on the LCControlMechanism’s FHNIntegrator function
a_w_FHN (float : default 1.0) – sets a_w on the LCControlMechanism’s FHNIntegrator function
b_w_FHN (float : default -0.8,) – sets b_w on the LCControlMechanism’s FHNIntegrator function
c_w_FHN (float : default 0.7) – sets c_w on the LCControlMechanism’s FHNIntegrator function
mode_FHN (float : default 1.0) – sets mode on the LCControlMechanism’s FHNIntegrator function
uncorrelated_activity_FHN (float : default 0.0) – sets uncorrelated_activity on the LCControlMechanism’s FHNIntegrator function
time_constant_w_FHN (float : default 12.5) – sets time_constant_w on the LCControlMechanism’s FHNIntegrator function
integration_method (float : default "RK4") – sets integration_method on the LCControlMechanism’s FHNIntegrator function
base_level_gain (float : default 0.5) –
sets the base value in the equation used to compute the time-dependent gain value that the LCControl applies to each of the mechanisms it modulates

\[g(t) = G + k w(t)\]

base_level_gain = G
scaling_factor_gain (float : default 3.0) –
sets the scaling factor in the equation used to compute the time-dependent gain value that the LCControl applies to each of the mechanisms it modulates

\[g(t) = G + k w(t)\]

scaling_factor_gain = k
params (Dict[param keyword: param value] : default None) – a parameter dictionary that can be used to specify the parameters for the Mechanism, parameters for 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 LCControlMechanism.
prefs (PreferenceSet or specification dict : default Mechanism.classPreferences) – specifies the PreferenceSet for the LCControlMechanism; see prefs for details.

system¶: System_Base – the System for which LCControlMechanism is the controller; the LCControlMechanism inherits any OutputStates specified in the monitor_for_control argument of the system’s constructor, and any ControlSignals specified in its control_signals argument.

objective_mechanism¶: ObjectiveMechanism : ObjectiveMechanism(function=CombinedMeans)) – the ‘ObjectiveMechanism’ used by the LCControlMechanism to aggregate the values of the OutputStates used to drive its phasic response.

monitor_for_control¶: List[OutputState] – list of the OutputStates that project to objective_mechanism (and also listed in the ObjectiveMechanism’s monitored_output_states attribute); these are used by the ObjectiveMechanism to generate the ControlMechanism’s input, which drives the phasic response of its function.

monitored_output_states_weights_and_exponents¶: List[Tuple(float, float)] – each tuple in the list contains the weight and exponent associated with a corresponding item of monitored_output_states; these are the same as those in the monitored_output_states_weights_and_exponents attribute of the objective_mechanism, and are used by the ObjectiveMechanism’s function to parametrize the contribution made to its output by each of the values that it monitors (see ObjectiveMechanism Function).

function¶: FHNIntegrator – takes the LCControlMechanism’s input and generates its response <LCControlMechanism_Output>` under the influence of the FHNIntegrator Function’s mode attribute (see Function for additional details).

allocation_policy¶: 2d np.array – contains a single item — the result of the LCControlMechanism’s function — that is assigned as the allocation for the LCControlMechanism’s single ControlSignal, listed in its control_signals attribute; the allocation_policy is the same as the ControlMechanism’s value attribute).

control_signals¶: List[ControlSignal] – contains the LCControlMechanism’s single ControlSignal, which sends ControlProjections to the multiplicative_param of each of the Mechanisms listed in the LCControlMechanism’s modulated_mechanisms attribute.

control_projections¶: List[ControlProjection] – list of ControlProjections sent by the LCControlMechanism’s ControlSignal, each of which projects to the ParameterState for the multiplicative_param of the function of one of the Mechanisms listed in modulated_mechanisms attribute.

modulated_mechanisms¶

List[Mechanism] – list of Mechanisms modulated by the LCControlMechanism.

initial_w_FHN : float : default 0.0 sets initial_w on the LCControlMechanism’s FHNIntegrator function

initial_v_FHN¶: float : default 0.0 – sets initial_v on the LCControlMechanism’s FHNIntegrator function

time_step_size_FHN¶: float : default 0.0 – sets time_step_size on the LCControlMechanism’s FHNIntegrator function

t_0_FHN¶: float : default 0.0 – sets t_0 on the LCControlMechanism’s FHNIntegrator function

a_v_FHN¶: float : default -1/3 – sets a_v on the LCControlMechanism’s FHNIntegrator function

b_v_FHN¶: float : default 0.0 – sets b_v on the LCControlMechanism’s FHNIntegrator function

c_v_FHN¶: float : default 1.0 – sets c_v on the LCControlMechanism’s FHNIntegrator function

d_v_FHN¶: float : default 0.0 – sets d_v on the LCControlMechanism’s FHNIntegrator function

e_v_FHN¶: float : default -1.0 – sets e_v on the LCControlMechanism’s FHNIntegrator function

f_v_FHN¶: float : default 1.0 – sets f_v on the LCControlMechanism’s FHNIntegrator function

threshold_FHN¶: float : default -1.0 – sets threshold on the LCControlMechanism’s FHNIntegrator function

time_constant_v_FHN¶: float : default 1.0 – sets time_constant_w on the LCControlMechanism’s FHNIntegrator function

a_w_FHN¶: float : default 1.0 – sets a_w on the LCControlMechanism’s FHNIntegrator function

b_w_FHN¶: float : default -0.8, – sets b_w on the LCControlMechanism’s FHNIntegrator function

c_w_FHN¶: float : default 0.7 – sets c_w on the LCControlMechanism’s FHNIntegrator function

mode_FHN¶: float : default 1.0 – sets mode on the LCControlMechanism’s FHNIntegrator function

uncorrelated_activity_FHN¶: float : default 0.0 – sets uncorrelated_activity on the LCControlMechanism’s FHNIntegrator function

time_constant_w_FHN¶: float : default 12.5 – sets time_constant_w on the LCControlMechanism’s FHNIntegrator function

integration_method¶: float : default “RK4” – sets integration_method on the LCControlMechanism’s FHNIntegrator function

base_level_gain¶

float : default 0.5 – sets the base value in the equation used to compute the time-dependent gain value that the LCControl applies to each of the mechanisms it modulates

\[g(t) = G + k w(t)\]

base_level_gain = G

scaling_factor_gain¶

float : default 3.0 – sets the scaling factor in the equation used to compute the time-dependent gain value that the LCControl applies to each of the mechanisms it modulates

\[g(t) = G + k w(t)\]

scaling_factor_gain = k

modulation¶: ModulationParam : default ModulationParam.MULTIPLICATIVE – the default value of ModulationParam that specifies the form of modulation used by the LCControlMechanism’s ControlProjections unless they are individually specified.

name¶: str – the name of the LCControlMechanism; 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 LCControlMechanism; 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).

add_modulated_mechanisms(mechanisms: list)¶: Add ControlProjections to the specified Mechanisms.

remove_modulated_mechanisms(mechanisms: list)¶: Remove the ControlProjections to the specified Mechanisms.

show()¶: Display the OutputStates monitored by the LCControlMechanism’s objective_mechanism and the multiplicative_params modulated by the LCControlMechanism.