Table of Contents

LCControlMechanism

Contents

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 basis for the control_allocation for the LCControlMechanism (see Output below. 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 Mechanism’s control_allocation to modulate the function of the Mechanisms it controls. The control_allocation is value returned by executing the LCControlMechanism (computed from the values returned by its function; see Execution below). The LCControlMechanism’s ControlSignal is assigned a ControlProjection to the ParameterPort for the multiplicative_param of the function of each of the Mechanisms it modulates, and uses the LCControlMechanism’s control_allocation to modulate those parameters. The Mechanisms modulated by an LCControlMechanism are listed in its modulated_mechanisms attribute) and can be displayed using its show method.

Warning

The value of an LCControlMechanism is not the same as its control_allocation nor its output_values attribute (see descriptions of those attributes for details).

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, default_allocation=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 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.

Type

List[OutputPort]

monitored_output_ports_weights_and_exponents

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

Type

List[Tuple(float, float)]

function

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

Type

FitzHughNagumoIntegrator

control_allocation

contains a single item computed from the LCControlMechanism’s scaling_factor_gain and base_level_gain parameters and the w term (2nd value) returned by the LCControlMechanism’s FitzHughNagumoIntegrator function; this is assigned as the allocation for the LCControlMechanism’s single ControlSignal (listed in its control_signals attribute), and is the same as the LCControlMechanism’s output_values attribute.

Type

2d np.array

control_signals

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.

Type

List[ControlSignal]

control_projections

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.

Type

List[ControlProjection]

modulated_mechanisms

list of Mechanisms modulated by the LCControlMechanism.

initial_w_FitzHughNagumo : float : default 0.0 sets initial_w on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

List[Mechanism]

initial_v_FitzHughNagumo

sets initial_v on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default 0.0

time_step_size_FitzHughNagumo

sets time_step_size on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default 0.0

t_0_FitzHughNagumo

sets t_0 on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default 0.0

a_v_FitzHughNagumo

sets a_v on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default -1/3

b_v_FitzHughNagumo

sets b_v on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default 0.0

c_v_FitzHughNagumo

sets c_v on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default 1.0

d_v_FitzHughNagumo

sets d_v on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default 0.0

e_v_FitzHughNagumo

sets e_v on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default -1.0

f_v_FitzHughNagumo

sets f_v on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default 1.0

threshold_FitzHughNagumo

sets threshold on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default -1.0

time_constant_v_FitzHughNagumo

sets time_constant_w on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default 1.0

a_w_FitzHughNagumo

sets a_w on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default 1.0

b_w_FitzHughNagumo

sets b_w on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default -0.8,

c_w_FitzHughNagumo

sets c_w on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default 0.7

mode_FitzHughNagumo

sets mode on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default 1.0

uncorrelated_activity_FitzHughNagumo

sets uncorrelated_activity on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default 0.0

time_constant_w_FitzHughNagumo

sets time_constant_w on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default 12.5

integration_method

sets integration_method on the LCControlMechanism’s FitzHughNagumoIntegrator function

Type

float : default “RK4”

base_level_gain

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

Type

float : default 0.5

scaling_factor_gain

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

Type

float : default 3.0

value

contains four values; the first is the control_allocation, followed by the three values – the w, v, and x terms – returned by the LCControlMechanism’s FitzHughNagumoIntegrator function.

Note

This is not the same as the output_values attribute, which contains only its control_allocation.

this is the value returned by the LCControlMechanism’s _execute method, which uses values returned by the LCControlMechanism’s function to compute its control_allocation LCControlMechanism.control_allocation>.

Type

ndarray

output_values

contains the value returned by the LCControlMechanism when it is executed, which is the same as its control_allocation.

Type

ndarray

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

_instantiate_output_ports(context=None)

Override to insure that ControlSignals are instantiated even thought self.control is not specified LCControlMechanism automatically assigns ControlSignals, so no control specification is needed in constructor super._instantiate_output_ports does not call _instantiate_control_signals if self.control is not specified; so, override is needed to insure _instantiate_control_signals is called

_instantiate_control_signals(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.

_execute(variable=None, context=None, runtime_params=None)

Updates LCControlMechanism’s ControlSignal based on input and mode parameter value

Return type

(<class ‘numpy.ndarray’>, <class ‘numpy.ndarray’>, <class ‘numpy.ndarray’>, <class ‘numpy.ndarray’>)

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.

exception psyneulink.library.components.mechanisms.modulatory.control.agt.lccontrolmechanism.LCControlMechanismError(message, data=None)