Control Mechanism¶

Overview¶

A ControlMechanism is an AdaptiveMechanism that modifies the parameter(s) of one or more Components, in response to an evaluative signal received from an ObjectiveMechanism. The ObjectiveMechanism monitors a specified set of OutputStates, and from these generates the evaluative signal that is used by the ControlMechanism’s function to calculate an allocation_policy: a list of allocation values for each of its ControlSignals. Each ControlSignal uses its allocation to calculate its intensity, which is then conveyed by the ControlSignal’s ControlProjection(s) to the ParameterState(s) to which they project. Each ParameterState then uses the value received by a ControlProjection to modify the value of the parameter for which it is responsible (see Modulation for a more detailed description of how modulation operates). A ControlMechanism can regulate only the parameters of Components in the System to which it belongs. The OutputStates used to determine the ControlMechanism’s allocation_policy, the ObjectiveMechanism used to evalute these, and the parameters controlled by the ControlMechanism can be listed using its show method.

ControlMechanisms and a System¶

A ControlMechanism can be assigned to and executed within one or more Systems (listed in its systems attribute), just like any other Mechanism. It also be assigned as the controller of a System, that has a special relation to the System: it is used to control any and all parameters that have been specified for control in that System. A ControlMechanism can be the controller for only one System, and a System can have only one one controller. The System’s controller is executed after all of the other Components in the System have been executed, including any other ControlMechanisms that belong to it (see System Execution). A ControlMechanism can be assigned as the controller for a System by specifying it in the controller argument of the System’s constructor, or by specifying the System as the system argument of either the ControlMechanism’s constructor or its assign_as_controller method. A System’s controller and its associated Components can be displayed using the System’s show_graph method with its show_control argument assigned as True.

Creating a ControlMechanism¶

A ControlMechanism can be created using the standard Python method of calling the constructor for the desired type. A ControlMechanism is also created automatically whenever a System is created, and the ControlMechanism class or one of its subtypes is specified in the controller argument of the System’s constructor (see Creating a System). If the ControlMechanism is created explicitly (using its constructor), the ObjectiveMechanism it uses to monitor and evaluate OutputStates is specified in the objective_mechanism argument of its constructor, and the parameters it controls are specified in the control_signals argument. If the ControlMechanism is created automatically by a System, then the specification of OutputStates to be monitored and parameters to be controlled are made on the System and/or the Components themselves (see Specifying Control). In either case the Components needed to monitor the specified OutputStates (an ObjectiveMechanism and Projections to it) and to control the specified parameters (ControlSignals and corresponding ControlProjections) are created automatically, as described below.

ObjectiveMechanism and Monitored OutputStates¶

When a ControlMechanism is created, it is associated with an ObjectiveMechanism that is used to monitor and evaluate a set of OutputStates upon which it bases it allocation_policy. If the ControlMechanism is created explicitly, its ObjectiveMechanism can be specified in the objective_mechanism argument of its constructor, using either of the following:

an existing ObjectiveMechanism, or a constructor for one; in this case the monitored_output_states argument of the ObjectiveMechanism’s constructor is used to specify the OutputStates to be monitored and evaluated (see Examples); note that, in this case, the default values for the attributes of the ObjectiveMechanism override any that ControlMechanism uses for its default objective_mechanism, including those of its function (see note in EVCControlMechanism for an example);

a list of OutputState specifications; in this case, a default ObjectiveMechanism is created, using the list of OutputState specifications as the monitored_output_states argument of the ObjectiveMechanism’s constructor.

If the objective_mechanism argument is not specified, a default ObjectiveMechanism is created that is not assigned any OutputStates to monitor; this must then be done explicitly after the ControlMechanism is created.

When a ControlMechanism is created automatically as part of a System:

a default ObjectiveMechanism is created for the ControlMechanism, using the list of OutputStates specified in the monitor_for_control argument of the System’s contructor, and any others within the System that have been specified to be monitored (using the MONITOR_FOR_CONTROL keyword), as the monitored_output_states argument for the ObjectiveMechanism’s constructor (see Specifying Control).

In all cases, the ObjectiveMechanism is assigned to the ControlMechanism’s objective_mechanism attribute, and a MappingProjection is created that projects from the ObjectiveMechanism’s OUTCOME OutputState to the ControlMechanism’s primary InputState.

OutputStates to be monitored can be added to an existing ControlMechanism by using the add_monitored_output_states method of the ControlMechanism’s objective_mechanism.

Specifying Parameters to Control¶

A ControlMechanism is used to control the parameter values of other Components. A ControlSignal is assigned for each parameter controlled by a ControlMechanism, and a ControlProjection is assigned from each ControlSignal to the ParameterState for the corresponding parameter to be controlled.

The parameters to be controlled by a ControlMechanism can be specified where it is created.

If it is created explicitly, the parameters to be controlled can be specified in the control_signals argument of its constructor. The argument must be a specification for one more ControlSignals.

If the ControlMechanism is created as part of a System, the parameters to be controlled by it can be specified in one of two ways:

in the control_signals argument of the System’s constructor, using one or more ControlSignal specifications;

where the parameter is specified, by including a ControlProjection or ControlSignal in a tuple specification for the parameter.

When a ControlMechanism is created as part of a System, a ControlSignal is created and assigned to the ControlMechanism for every parameter of any Component in the System that has been specified for control using either of the methods above.

Parameters to be controlled can be added to an existing ControlMechanism by using its assign_params method to add a ControlSignal for each additional parameter.

All of the ControlSignals for a ControlMechanism are listed in its control_signals attribute, and all of its ControlProjections are listed in its control_projections attribute.

Structure¶

Input¶

A ControlMechanism has a single ERROR_SIGNAL InputState, the value of which is used as the input to the ControlMechanism’s function, that determines the ControlMechanism’s allocation_policy. The ERROR_SIGNAL InputState receives its input via a MappingProjection from the OUTCOME OutputState of an ObjectiveMechanism. The Objective Mechanism is specified in the objective_mechanism argument of its constructor, and listed in its objective_mechanism attribute. The OutputStates monitored by the ObjectiveMechanism (listed in its monitored_output_states attribute) are also listed in the monitored_output_states of the ControlMechanism (see ObjectiveMechanism and Monitored OutputStates for how the ObjectiveMechanism and the OutputStates it monitors are specified). The OutputStates monitored by the ControlMechanism’s objective_mechanism can be displayed using its show method. The ObjectiveMechanism’s function evaluates the specified OutputStates, and the result is conveyed as the input to the ControlMechanism.

Function¶

A ControlMechanism’s function uses the value of its ERROR_SIGNAL InputState to generate an allocation_policy. By default, each item of the allocation_policy is assigned as the allocation of the corresponding ControlSignal in control_signals; however, subtypes of ControlMechanism may assign values differently (for example, an LCControlMechanism assigns a single value to all of its ControlSignals).

Output¶

A ControlMechanism has a ControlSignal for each parameter specified in its control_signals attribute, that sends a ControlProjection to the ParameterState for the corresponding parameter. ControlSignals are a type of OutputState, and so they are also listed in the ControlMechanism’s output_states attribute. The parameters modulated by a ControlMechanism’s ControlSignals can be displayed using its show method. By default, each value of each ControlSignal is assigned the value of the corresponding item from the ControlMechanism’s allocation_policy; however, subtypes of ControlMechanism may assign values differently. The allocation is used by each ControlSignal to determine its intensity, which is then assigned as the value of the ControlSignal’s ControlProjection. The value of the ControlProjection is used by the ParameterState to which it projects to modify the value of the parameter it controls (see Modulation for description of how a ControlSignal modulates the value of a parameter).

Execution¶

A ControlMechanism that is a System’s controller is always the last Mechanism to be executed in a TRIAL for that System (see System Control and Execution). The ControlMechanism’s function takes as its input the value of its ERROR_SIGNAL input_state, and uses that to determine its allocation_policy which specifies the value assigned to the allocation of each of its ControlSignals. Each ControlSignal uses that value to calculate its intensity, which is used by its ControlProjection(s) to modulate the value of the ParameterState(s) for the parameter(s) it controls, which are then used in the subsequent TRIAL of execution.

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 ControlMechanism has executed, a parameter that it controls will not assume its new value until the Mechanism to which it belongs has executed.

Examples

The following example creates a ControlMechanism by specifying its objective_mechanism using a constructor that specifies the OutputStates to be monitored by its objective_mechanism:

>>> import psyneulink as pnl
>>> my_transfer_mech_A = pnl.TransferMechanism(name="Transfer Mech A")
>>> my_DDM = pnl.DDM(name="My DDM")
>>> my_transfer_mech_B = pnl.TransferMechanism(function=pnl.Logistic,
...                                            name="Transfer Mech B")

>>> my_control_mech = pnl.ControlMechanism(
...                          objective_mechanism=pnl.ObjectiveMechanism(monitored_output_states=[(my_transfer_mech_A, 2, 1),
...                                                                                               my_DDM.output_states[pnl.RESPONSE_TIME]],
...                                                                     name="Objective Mechanism"),
...                          function=pnl.LinearCombination(operation=pnl.PRODUCT),
...                          control_signals=[(pnl.THRESHOLD, my_DDM),
...                                           (pnl.GAIN, my_transfer_mech_B)],
...                          name="My Control Mech")

This creates an ObjectiveMechanism for the ControlMechanism that monitors the primary OutputState of my_Transfer_mech_A and the RESPONSE_TIME OutputState of my_DDM; its function first multiplies the former by 2 before, then takes product of their values and passes the result as the input to the ControlMechanism. The ControlMechanism’s function uses this value to determine the allocation for its ControlSignals, that control the value of the threshold parameter of my_DDM and the gain parameter of the Logistic Function for my_transfer_mech_B.

The following example specifies the same set of OutputStates for the ObjectiveMechanism, by assigning them directly to the objective_mechanism argument:

>>> my_control_mech = pnl.ControlMechanism(
...                             objective_mechanism=[(my_transfer_mech_A, 2, 1),
...                                                  my_DDM.output_states[pnl.RESPONSE_TIME]],
...                             control_signals=[(pnl.THRESHOLD, my_DDM),
...                                              (pnl.GAIN, my_transfer_mech_B)])
...

Note that, while this form is more succinct, it precludes specifying the ObjectiveMechanism’s function. Therefore, the values of the monitored OutputStates will be added (the default) rather than multiplied.

The ObjectiveMechanism can also be created on its own, and then referenced in the constructor for the ControlMechanism:

>>> my_obj_mech = pnl.ObjectiveMechanism(monitored_output_states=[(my_transfer_mech_A, 2, 1),
...                                                               my_DDM.output_states[pnl.RESPONSE_TIME]],
...                                      function=pnl.LinearCombination(operation=pnl.PRODUCT))

>>> my_control_mech = pnl.ControlMechanism(
...                        objective_mechanism=my_obj_mech,
...                        control_signals=[(pnl.THRESHOLD, my_DDM),
...                                         (pnl.GAIN, my_transfer_mech_B)])

Here, as in the first example, the constructor for the ObjectiveMechanism can be used to specify its function, as well as the OutputState that it monitors.

See Specifying Control for a System for examples of how a ControlMechanism, the OutputStates its objective_mechanism, and its control_signals can be specified for a System.

Class Reference¶

class psyneulink.components.mechanisms.adaptive.control.controlmechanism.ControlMechanism(system=None objective_mechanism=None, function=Linear, control_signals=None, modulation=ModulationParam.MULTIPLICATIVE params=None, name=None, prefs=None)¶

Subclass of AdaptiveMechanism that modulates the parameter(s) of one or more Component(s).

Parameters:

system (System or bool : default None) – specifies the System to which the ControlMechanism should be assigned as its controller.
objective_mechanism (ObjectiveMechanism or List[OutputState specification] : default None) – specifies either an ObjectiveMechanism to use for the ControlMechanism, 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.
function (TransferFunction : default Linear(slope=1, intercept=0)) – specifies function used to combine values of monitored OutputStates.
control_signals (ControlSignal specification or List[ControlSignal specification, ..]) – specifies the parameters to be controlled by the ControlMechanism; a ControlSignal is created for each (see Specifying ControlSignals for details of specification).
modulation (ModulationParam : ModulationParam.MULTIPLICATIVE) – specifies the default form of modulation used by the ControlMechanism’s ControlSignals, unless they are individually specified.
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 ControlMechanism.
prefs (PreferenceSet or specification dict : default Mechanism.classPreferences) – specifies the PreferenceSet for the ControlMechanism; see prefs for details.

system¶: System_Base – The System for which the ControlMechanism is a controller. Note that this is distinct from a Mechanism’s systems attribute, which lists all of the Systems to which a Mechanisms belongs – a ControlMechanism can belong to but not be the controller of a System.

objective_mechanism¶: ObjectiveMechanism – ObjectiveMechanism that monitors and evaluates the values specified in the ControlMechanism’s objective_mechanism argument, and transmits the result to the ControlMechanism’s ERROR_SIGNAL input_state.

monitored_output_states¶: List[OutputState] – each item is an OutputState monitored by the ObjectiveMechanism listed in the ControlMechanism’s objective_mechanism attribute; it is the same as that ObjectiveMechanism’s monitored_output_states attribute (see Monitored OutputStates for specification). The value of the OutputStates listed are used by the ObjectiveMechanism to generate the ControlMechanism’s input.

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¶: TransferFunction : default Linear(slope=1, intercept=0) – determines how the value s of the OutputStates specified in the monitor_for_control argument of the ControlMechanism’s constructor are used to generate its allocation_policy.

allocation_policy¶: 2d np.array – each item is the value assigned as the allocation for the corresponding ControlSignal listed in the control_signals attribute; the allocation_policy is the same as the ControlMechanism’s value attribute).

control_signals¶: ContentAddressableList[ControlSignal] – list of the ControlSignals for the ControlMechanism, including any inherited from a system for which it is a controller (same as ControlMechanism’s output_states attribute); each sends a ControlProjection to the ParameterState for the parameter it controls

control_projections¶: List[ControlProjection] – list of ControlProjections, one for each ControlSignal in control_signals.

modulation¶: ModulationParam – the default form of modulation used by the ControlMechanism’s ControlSignals, unless they are individually specified.

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

outputStateType¶: alias of ControlSignal

show()¶: Display the OutputStates monitored by ControlMechanism’s objective_mechanism and the parameters modulated by its control_signals.

add_monitored_output_states(monitored_output_states, context=None)¶

Instantiate OutputStates to be monitored by ControlMechanism’s objective_mechanism.

monitored_output_states can be any of the following:

If any item is a Mechanism, its primary OutputState is used. OutputStates must belong to Mechanisms in the same System as the ControlMechanism.

assign_as_controller(system: psyneulink.components.shellclasses.System_Base, context=<ContextFlags.COMMAND_LINE: 512>)¶

Assign ControlMechanism as controller for a System.

system must be a System for which the ControlMechanism should be assigned as the controller. If the specified System already has a controller, it will be replaced by the current one, and the current one will inherit any ControlSignals previously specified for the old controller or the System itself. If the current one is already the controller for another System, it will be disabled for that System.