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 functioning 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, an LCControlMechanism receives its input from an ObjectiveMechanism that, in turn, receives its input from a specified list of OutputStates. These are used to drive the phasic response of the LCControlMechanism. The ObjectiveMechanism and/or the OutputStates from which it gets its input can be specified in the standard way for a ControlMechanism). By default, an LCControlMechanism creates an ObjectiveMechanism that uses a CombineMeans Function to sum the means of the values of the OutputStates from which it gets its input. However, this can be customized by specifying a different ObjectiveMechanism or its function, so long as these generate a result that is a scalar value.

Specifying Mechanisms to Modulate¶

The Mechanisms to be modulated by an LCControlMechanism are specified in its modulated_mechanisms argument. 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 (and listed in its modulated_mechanisms attribute).

Structure¶

Input¶

ObjectiveMechanism¶

Like any ControlMechanism, an LCControlMechanism receives its input from the OUTCOME OutputState of an ObjectiveMechanism, via a MappingProjection to its primary InputState. The ObjectiveFunction is listed in the LCControlMechanism’s objective_mechanism attribute. By default, the ObjectiveMechanism’s function is a CombineMeans function with its default operation of SUM; this takes the mean of the value of each of the OutputStates that it monitors (listed in its monitored_output_states attribute, and returns the sum of those means. However, this can be customized in a variety of ways:

by specifying a different function for the ObjectiveMechanism (see ObjectiveMechanism_Weights_and_Exponents_Example for an example);

using a list to specify the OutputStates to be monitored (and the tuples format to specify weights and/or exponents for them) in the objective_mechanism argument of the EVCControlMechanism’s constructor;

using the monitored_output_states argument of the objective_mechanism’s constructor;

specifying a different ObjectiveMechanism in the LCControlMechanism’s objective_mechanism argument of the EVCControlMechanism’s constructor. The result of the objective_mechanism’s function is used as the input to the LCControlMechanism.

Note

If a constructor for an ObjectiveMechanism is used for the objective_mechanism argument of the LCControlMechanism’s constructor, then the default values of its attributes override any used by the LCControlMechanism for its objective_mechanism. In particular, whereas an ObjectiveMechanism uses LinearCombination as the default for its function, an LCControlMechanism typically uses CombineMeans for the function of its objective_mechanism. As a consequence, if the constructor for an ObjectiveMechanism is used to specify the LCControlMechanism’s objective_mechanism argument, and the function argument is not specified, LinearCombination rather than CombineMeans 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 OutputStates monitored by the LC’s ObjectiveMechanism are listed in its monitored_output_states attribute), as well as in the monitored_output_states attribute of the LCControlMechanism itself. These can be displayed using the LCControlMechanism’s show method.

Function¶

An LCControlMechanism uses the FHNIntegrator as its function <LCControlMechanism.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 takes the input to the LCControlMechanism as its variable. All of the FHNIntegrator function parameters are exposed on 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 LC 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 ControlSignal for each Mechanism listed in its modulated_mechanisms attribute. All of its ControlSignals are assigned the same value: the result of the LCControlMechanism’s function. Each ControlSignal is assigned a ControlProjection to the ParameterState for the multiplicative_param of function for the Mechanism in modulated_mechanisms to which it corresponds. The Mechanisms modulated by an LCControlMechanism 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.

monitored_output_states¶: List[OutputState] – list of the OutputStates that project to objective_mechanism (and listed in its monitored_output_states attribute), and used to drive the LCControlMechanism’s phasic response.

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).

control_signals¶: List[ControlSignal] – list of the ControlSignals for each Mechanism listed in the LCControlMechanism’s modulated_mechanisms attribute (same as the LCControlMechanism’s output_states attribute); each sends a Control Projections to the ParameterState for the multiplicative_param of the `function <Mechanism_Base.function>corresponding Mechanism.

control_projections¶: List[ControlProjection] – list of all of the ControlProjections sent by the ControlSignals listed in control_signals.

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.