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 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 itsinput <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 thethresholdparameter), 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(modulated_mechanisms=None, initial_w_FitzHughNagumo=0.0, initial_v_FitzHughNagumo=0.0, time_step_size_FitzHughNagumo=0.05, t_0_FitzHughNagumo=0.0, a_v_FitzHughNagumo=-1/3, 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, threshold_FitzHughNagumo=-1.0 time_constant_v_FitzHughNagumo=1.0, a_w_FitzHughNagumo=1.0, b_w_FitzHughNagumo=-0.8, c_w_FitzHughNagumo=0.7, mode_FitzHughNagumo=1.0, uncorrelated_activity_FitzHughNagumo=0.0 time_constant_w_FitzHughNagumo = 12.5, integration_method="RK4" base_level_gain=0.5, scaling_factor_gain=3.0)¶ Subclass of ControlMechanism that modulates the multiplicative_param of the
functionof 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
functionthat 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_won the LCControlMechanism’s FitzHughNagumoIntegrator functioninitial_v_FitzHughNagumo (float : default 0.0) – sets
initial_von the LCControlMechanism’s FitzHughNagumoIntegrator functiontime_step_size_FitzHughNagumo (float : default 0.0) – sets
time_step_sizeon the LCControlMechanism’s FitzHughNagumoIntegrator functiont_0_FitzHughNagumo (float : default 0.0) – sets
t_0on the LCControlMechanism’s FitzHughNagumoIntegrator functiona_v_FitzHughNagumo (float : default -1/3) – sets
a_von the LCControlMechanism’s FitzHughNagumoIntegrator functionb_v_FitzHughNagumo (float : default 0.0) – sets
b_von the LCControlMechanism’s FitzHughNagumoIntegrator functionc_v_FitzHughNagumo (float : default 1.0) – sets
c_von the LCControlMechanism’s FitzHughNagumoIntegrator functiond_v_FitzHughNagumo (float : default 0.0) – sets
d_von the LCControlMechanism’s FitzHughNagumoIntegrator functione_v_FitzHughNagumo (float : default -1.0) – sets
e_von the LCControlMechanism’s FitzHughNagumoIntegrator functionf_v_FitzHughNagumo (float : default 1.0) – sets
f_von the LCControlMechanism’s FitzHughNagumoIntegrator functionthreshold_FitzHughNagumo (float : default -1.0) – sets
thresholdon the LCControlMechanism’s FitzHughNagumoIntegrator functiontime_constant_v_FitzHughNagumo (float : default 1.0) – sets
time_constant_won the LCControlMechanism’s FitzHughNagumoIntegrator functiona_w_FitzHughNagumo (float : default 1.0) – sets
a_won the LCControlMechanism’s FitzHughNagumoIntegrator functionb_w_FitzHughNagumo (float : default -0.8,) – sets
b_won the LCControlMechanism’s FitzHughNagumoIntegrator functionc_w_FitzHughNagumo (float : default 0.7) – sets
c_won the LCControlMechanism’s FitzHughNagumoIntegrator functionmode_FitzHughNagumo (float : default 1.0) – sets
modeon the LCControlMechanism’s FitzHughNagumoIntegrator functionuncorrelated_activity_FitzHughNagumo (float : default 0.0) – sets
uncorrelated_activityon the LCControlMechanism’s FitzHughNagumoIntegrator functiontime_constant_w_FitzHughNagumo (float : default 12.5) – sets
time_constant_won the LCControlMechanism’s FitzHughNagumoIntegrator functionintegration_method (float : default "RK4") – sets
integration_methodon the LCControlMechanism’s FitzHughNagumoIntegrator functionbase_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’smonitored_output_portsattribute); these are used by the ObjectiveMechanism to generate the ControlMechanism’s input, which drives the phasic response of itsfunction.- 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 themonitored_output_ports_weights_and_exponentsattribute of theobjective_mechanism, and are used by the ObjectiveMechanism’sfunctionto 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
FitzHughNagumoIntegratorFunction’smodeattribute (see Function for additional details).
-
control_allocation¶ contains a single item — the result of the LCControlMechanism’s
function— that is assigned as theallocationfor the LCControlMechanism’s single ControlSignal, listed in itscontrol_signalsattribute; the control_allocation is the same as the ControlMechanism’svalueattribute).- 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_mechanismsattribute.- 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
functionof one of the Mechanisms listed inmodulated_mechanismsattribute.- Type
List[ControlProjection]
-
modulated_mechanisms¶ list of Mechanisms modulated by the LCControlMechanism.
initial_w_FitzHughNagumo : float : default 0.0 sets
initial_won the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
List[Mechanism]
-
initial_v_FitzHughNagumo¶ sets
initial_von the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default 0.0
-
time_step_size_FitzHughNagumo¶ sets
time_step_sizeon the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default 0.0
-
t_0_FitzHughNagumo¶ sets
t_0on the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default 0.0
-
a_v_FitzHughNagumo¶ sets
a_von the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default -1/3
-
b_v_FitzHughNagumo¶ sets
b_von the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default 0.0
-
c_v_FitzHughNagumo¶ sets
c_von the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default 1.0
-
d_v_FitzHughNagumo¶ sets
d_von the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default 0.0
-
e_v_FitzHughNagumo¶ sets
e_von the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default -1.0
-
f_v_FitzHughNagumo¶ sets
f_von the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default 1.0
-
threshold_FitzHughNagumo¶ sets
thresholdon the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default -1.0
-
time_constant_v_FitzHughNagumo¶ sets
time_constant_won the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default 1.0
-
a_w_FitzHughNagumo¶ sets
a_won the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default 1.0
-
b_w_FitzHughNagumo¶ sets
b_won the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default -0.8,
-
c_w_FitzHughNagumo¶ sets
c_won the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default 0.7
-
mode_FitzHughNagumo¶ sets
modeon the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default 1.0
sets
uncorrelated_activityon the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default 0.0
-
time_constant_w_FitzHughNagumo¶ sets
time_constant_won the LCControlMechanism’s FitzHughNagumoIntegrator function- Type
float : default 12.5
-
integration_method¶ sets
integration_methodon 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
-
_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
functionthat has a multiplicative_param.
-
_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.
-
_check_for_composition(context=None)¶ Allow Component to check whether it or its attributes are suitable for inclusion in a Composition Called by Composition.add_node.
-
_execute(variable=None, context=None, runtime_params=None)¶ Updates LCControlMechanism’s ControlSignal based on input and mode parameter value
-
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_mechanismand the multiplicative_params modulated by the LCControlMechanism.
-
exception
psyneulink.library.components.mechanisms.modulatory.control.agt.lccontrolmechanism.LCControlMechanismError(error_value)¶