Control Mechanisms¶

Optimzation Control Mechanisms

Overview¶

A ControlMechanism is a subclass of ModulatoryMechanism that is restricted to using only ControlSignals and not GatingSignals. Accordingly, its constructor has a control_signals argument in place of a modulatory_signals argument. It also lacks any attributes related to gating. In all other respects it is identical to its parent class, ModulatoryMechanism.

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 and the function used to evaluated these:

>>> 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(monitor=[(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.core.components.mechanisms.adaptive.control.controlmechanism.ControlMechanism(system=None monitor_for_control=None, objective_mechanism=None, function=Linear, control_signals=None, modulation=ModulationParam.MULTIPLICATIVE combine_costs=np.sum, compute_reconfiguration_cost=None, compute_net_outcome=lambda x, y:x-y, 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.
monitor_for_control (List[OutputState or Mechanism] : default None) – specifies the OutputStates to be monitored by the ObjectiveMechanism specified in the objective_mechanism argument; for any Mechanisms specified, their primary OutputState are used.
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.
combine_costs (Function, function or method : default np.sum) – specifies function used to combine the cost of the ControlMechanism’s control_signals; must take a list or 1d array of scalar values as its argument and return a list or array with a single scalar value.
compute_reconfiguration_cost (Function, function or method : default None) – specifies function used to compute the ControlMechanism’s reconfiguration_cost; must take a list or 2d array containing two lists or 1d arrays, both with the same shape as the ControlMechanism’s control_allocation attribute, and return a scalar value.
compute_net_outcome (Function, function or method : default lambda outcome, cost: outcome-cost) – function used to combine the values of its outcome and costs attributes; must take two 1d arrays (outcome and cost) with scalar values as its arguments and return an array with a single scalar value.
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 OUTCOME input_state.

monitor_for_control¶: 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 Monitor for specification). The value of the OutputStates in the list 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 OutputState specified in monitor_for_control; 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).

outcome¶: 1d array – the value of the ControlMechanism’s primary InputState, which receives its Projection from the OUTCOME OutputState of its objective_mechanism.

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

control_allocation¶: 2d array – each item is the value assigned as the allocation for the corresponding ControlSignal listed in the control_signals attribute; the control_allocation 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

compute_reconfiguration_cost¶: Function, function or method – function used to compute the ControlMechanism’s reconfiguration_cost; result is a scalar value representing the difference — defined by the function — between the values of the ControlMechanism’s current and last control_alloction, that can be accessed by reconfiguration_cost attribute.

costs¶: list – current costs for the ControlMechanism’s control_signals, computed for each using its compute_costs method.

combine_costs¶: Function, function or method – function used to combine the cost of its control_signals; result is an array with a scalar value that can be accessed by combined_costs.

Note

This function is distinct from the combine_costs_function of a ControlSignal. The latter combines the different costs for an individual ControlSignal to yield its overall cost; the ControlMechanism’s combine_costs function combines those costs for its control_signals.

combined_costs¶: 1d array – result of the ControlMechanism’s combine_costs function.

compute_net_outcome¶: Function, function or method – function used to combine the values of its outcome and costs attributes; result is an array with a scalar value that can be accessed by the the net_outcome attribute.

net_outcome¶: 1d array – result of the ControlMechanism’s compute_net_outcome function.

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

assign_as_controller(system: psyneulink.core.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.

outputStateTypes¶: alias of ControlSignal