LCControlMechanism¶

Contents¶

Overview

Creating an LCControlMechanism

ObjectiveMechanism and Monitored OutputPorts

Mechanisms to Modulate

Structure

Input

ObjectiveMechanism

Function

LC Modes of Operation

Output

Execution

Examples

Class Reference

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 FitzHughNagumoIntegrator 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 FitzHughNagumoIntegrator 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 OutputPorts¶

If the objective_mechanism argument is specified then, as with a standard ControlMechanism, the specified ObjectiveMechanism is assigned to its objective_mechanism attribute. The value of the ObjectiveMechanism’s OUTCOME OutputPort must be a scalar (that is used as the input to the LCControlMechanism’s function to drive its phasic response. An ObjectiveMechanism can also be constructed automatically, by specifying objective_mechanism as True; that is assigned a CombineMeans Function as its function (see ObjectiveMechanism).

If an ObjectiveMechanism is assigned to the LCControlMechanism (whether by specifying one explicitly or that it be created automatically), the LCControlMechanism receives its input from that ObjectiveMechanism, which receives its input from any OutputPorts specified in monitor_for_control argument of the constructor for LCControlMechanism.

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 ProcessingMechanism, or a Mechanism that uses as its function a class of Function that implements a multiplicative_param. The modulate_mechanisms argument must be either a list of such Mechanisms, or a Composition (to modulate all of the ProcessingMechanisms in a Composition – see below). see below). 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 ParameterPort 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).

If Composition is assigned as the value of modulate_mechanisms, then the LCControlMechanism will modulate all of the Processing Mechanisms in that Composition, with the exception of any ObjectiveMechanisms that are assigned a the objective_mechanism of another ControlMechanism. Note that only the Mechanisms that already belong to that Composition are included at the time the LCControlMechanism is constructed. Therefore, to include all Mechanisms in the Composition at the time it is run, the LCControlMechanism should be constructed and added to the Composition using the Composition's `add_node method) after all of the other Mechanisms have been added.

Structure¶

Input¶

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

ObjectiveMechanism¶

If an ObjectiveMechanism is automatically created specified the monitor_for_control argument of the LCControlMechanism constructor, or the montiored_output_ports 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 OutputPorts that it monitors, and returns the sum of these means. The value of each OutputPort can be weighted (multiplicatively and/or exponentially), by specifying this in the monitor_for_control argument of the LCControlMechanism (see Specifying OutputPorts to be monitored 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 see example under ControlMechanism_ObjectiveMechanism_Function).

The ObjectiveFunction is listed in the LCControlMechanism’s objective_mechanism attribute. The OutputPorts it monitors are listed in the ObjectiveMechanism’s monitored_output_ports 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 FitzHughNagumoIntegrator 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 FitzHughNagumoIntegrator Function of an LCControlMechanism takes a scalar as its variable, received from the input to the LCControlMechanism, and the result serves as the control_allocation for the LCControlMechanism. All of the parameters of the FitzHughNagumoIntegrator function are accessible as attributes of the LCControlMechanism.

LC Modes of Operation¶

The mode parameter of the LCControlMechanism’s FitzHughNagumoIntegrator 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 control_allocation (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 ParameterPort 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.

Execution¶

An LCControlMechanism executes within a Composition at a point specified in the Composition’s Scheduler or, if it is the controller for a Composition, 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 InputPort 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 ParameterPort 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.

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 OutputPorts:

  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.

Class Reference¶

class psyneulink.library.components.mechanisms.modulatory.control.agt.lccontrolmechanism.LCControlMechanism(default_variable=None, objective_mechanism=None, monitor_for_control=None, modulated_mechanisms=None, modulation=None, integration_method='RK4', initial_w_FitzHughNagumo=0.0, initial_v_FitzHughNagumo=0.0, time_step_size_FitzHughNagumo=0.05, t_0_FitzHughNagumo=0.0, a_v_FitzHughNagumo=-0.3333333333333333, b_v_FitzHughNagumo=0.0, c_v_FitzHughNagumo=1.0, d_v_FitzHughNagumo=0.0, e_v_FitzHughNagumo=-1.0, f_v_FitzHughNagumo=1.0, time_constant_v_FitzHughNagumo=1.0, a_w_FitzHughNagumo=1.0, b_w_FitzHughNagumo=-0.8, c_w_FitzHughNagumo=0.7, threshold_FitzHughNagumo=-1.0, time_constant_w_FitzHughNagumo=12.5, mode_FitzHughNagumo=1.0, uncorrelated_activity_FitzHughNagumo=0.0, base_level_gain=None, scaling_factor_gain=None, params=None, name=None, prefs=None)¶

Subclass of ControlMechanism that modulates the multiplicative_param of the function of one or more Mechanisms. See ControlMechanism for additional arguments and attributes.

Parameters:

modulated_mechanisms (List[Mechanism] 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_FitzHughNagumo (float : default 0.0) – sets initial_w on the LCControlMechanism’s FitzHughNagumoIntegrator function
initial_v_FitzHughNagumo (float : default 0.0) – sets initial_v on the LCControlMechanism’s FitzHughNagumoIntegrator function
time_step_size_FitzHughNagumo (float : default 0.0) – sets time_step_size on the LCControlMechanism’s FitzHughNagumoIntegrator function
t_0_FitzHughNagumo (float : default 0.0) – sets t_0 on the LCControlMechanism’s FitzHughNagumoIntegrator function
a_v_FitzHughNagumo (float : default -1/3) – sets a_v on the LCControlMechanism’s FitzHughNagumoIntegrator function
b_v_FitzHughNagumo (float : default 0.0) – sets b_v on the LCControlMechanism’s FitzHughNagumoIntegrator function
c_v_FitzHughNagumo (float : default 1.0) – sets c_v on the LCControlMechanism’s FitzHughNagumoIntegrator function
d_v_FitzHughNagumo (float : default 0.0) – sets d_v on the LCControlMechanism’s FitzHughNagumoIntegrator function
e_v_FitzHughNagumo (float : default -1.0) – sets e_v on the LCControlMechanism’s FitzHughNagumoIntegrator function
f_v_FitzHughNagumo (float : default 1.0) – sets f_v on the LCControlMechanism’s FitzHughNagumoIntegrator function
threshold_FitzHughNagumo (float : default -1.0) – sets threshold on the LCControlMechanism’s FitzHughNagumoIntegrator function
time_constant_v_FitzHughNagumo (float : default 1.0) – sets time_constant_w on the LCControlMechanism’s FitzHughNagumoIntegrator function
a_w_FitzHughNagumo (float : default 1.0) – sets a_w on the LCControlMechanism’s FitzHughNagumoIntegrator function
b_w_FitzHughNagumo (float : default -0.8,) – sets b_w on the LCControlMechanism’s FitzHughNagumoIntegrator function
c_w_FitzHughNagumo (float : default 0.7) – sets c_w on the LCControlMechanism’s FitzHughNagumoIntegrator function
mode_FitzHughNagumo (float : default 1.0) – sets mode on the LCControlMechanism’s FitzHughNagumoIntegrator function
uncorrelated_activity_FitzHughNagumo (float : default 0.0) – sets uncorrelated_activity on the LCControlMechanism’s FitzHughNagumoIntegrator function
time_constant_w_FitzHughNagumo (float : default 12.5) – sets time_constant_w on the LCControlMechanism’s FitzHughNagumoIntegrator function
integration_method (float : default "RK4") – sets integration_method on the LCControlMechanism’s FitzHughNagumoIntegrator 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

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

monitored_output_ports_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_ports; these are the same as those in the monitored_output_ports_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¶: FitzHughNagumoIntegrator – takes the LCControlMechanism’s input and generates its response <LCControlMechanism_Output>` under the influence of the FitzHughNagumoIntegrator Function’s mode attribute (see Function for additional details).

control_allocation¶: 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 control_allocation 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 ParameterPort 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_FitzHughNagumo : float : default 0.0 sets initial_w on the LCControlMechanism’s FitzHughNagumoIntegrator function

initial_v_FitzHughNagumo¶: float : default 0.0 – sets initial_v on the LCControlMechanism’s FitzHughNagumoIntegrator function

time_step_size_FitzHughNagumo¶: float : default 0.0 – sets time_step_size on the LCControlMechanism’s FitzHughNagumoIntegrator function

t_0_FitzHughNagumo¶: float : default 0.0 – sets t_0 on the LCControlMechanism’s FitzHughNagumoIntegrator function

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

b_v_FitzHughNagumo¶: float : default 0.0 – sets b_v on the LCControlMechanism’s FitzHughNagumoIntegrator function

c_v_FitzHughNagumo¶: float : default 1.0 – sets c_v on the LCControlMechanism’s FitzHughNagumoIntegrator function

d_v_FitzHughNagumo¶: float : default 0.0 – sets d_v on the LCControlMechanism’s FitzHughNagumoIntegrator function

e_v_FitzHughNagumo¶: float : default -1.0 – sets e_v on the LCControlMechanism’s FitzHughNagumoIntegrator function

f_v_FitzHughNagumo¶: float : default 1.0 – sets f_v on the LCControlMechanism’s FitzHughNagumoIntegrator function

threshold_FitzHughNagumo¶: float : default -1.0 – sets threshold on the LCControlMechanism’s FitzHughNagumoIntegrator function

time_constant_v_FitzHughNagumo¶: float : default 1.0 – sets time_constant_w on the LCControlMechanism’s FitzHughNagumoIntegrator function

a_w_FitzHughNagumo¶: float : default 1.0 – sets a_w on the LCControlMechanism’s FitzHughNagumoIntegrator function

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

c_w_FitzHughNagumo¶: float : default 0.7 – sets c_w on the LCControlMechanism’s FitzHughNagumoIntegrator function

mode_FitzHughNagumo¶: float : default 1.0 – sets mode on the LCControlMechanism’s FitzHughNagumoIntegrator function

uncorrelated_activity_FitzHughNagumo¶: float : default 0.0 – sets uncorrelated_activity on the LCControlMechanism’s FitzHughNagumoIntegrator function

time_constant_w_FitzHughNagumo¶: float : default 12.5 – sets time_constant_w on the LCControlMechanism’s FitzHughNagumoIntegrator function

integration_method¶: float : default “RK4” – sets integration_method on the LCControlMechanism’s FitzHughNagumoIntegrator 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

_execute(variable=None, context=None, runtime_params=None)¶: Updates LCControlMechanism’s ControlSignal based on input and mode parameter value

_instantiate_output_ports(context=None)¶

Instantiate ControlSignals and assign ControlProjections to Mechanisms in self.modulated_mechanisms

If modulated_mechanisms argument of constructor was specified as ALL, assign all ProcessingMechanisms: in Compositions to which LCControlMechanism belongs to self.modulated_mechanisms.
Instantiate ControlSignal with Projection to the ParameterPort for the multiplicative_param of every: Mechanism listed in self.modulated_mechanisms.

_validate_params(request_set, target_set=None, context=None)¶

Validate modulated_mechanisms argument.

Validate that modulated_mechanisms is either a Composition or a list of eligible Mechanisms . Eligible Mechanisms are ones with a function that has a multiplicative_param.

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

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

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