PrincetonUniversity / PsyNeuLink / 15917088825

# Princeton University licenses this file to You under the Apache License, Version 2.0 (the "License");

# you may not use this file except in compliance with the License.  You may obtain a copy of the License at:

#     http://www.apache.org/licenses/LICENSE-2.0

# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed

# on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and limitations under the License.

# **************************************  ControlMechanism ************************************************

"""

Contents

--------

  * `ControlMechanism_Overview`

  * `ControlMechanism_Composition_Controller`

  * `ControlMechanism_Creation`

      - `ControlMechanism_Monitor_for_Control`

      - `ControlMechanism_ObjectiveMechanism`

      - `ControlMechanism_ControlSignals`

  * `ControlMechanism_Structure`

      - `ControlMechanism_Input`

      - `ControlMechanism_Function`

      - `ControlMechanism_Output`

      - `ControlMechanism_Costs_NetOutcome`

  * `ControlMechanism_Execution`

  * `ControlMechanism_Examples`

  * `ControlMechanism_Class_Reference`

.. _ControlMechanism_Overview:

Overview

--------

A ControlMechanism is a `ModulatoryMechanism` that `modulates the value(s) <ModulatorySignal_Modulation>` of one or

more `Ports <Port>` of other Mechanisms in the `Composition` to which it belongs. In general, a ControlMechanism is

used to modulate the `ParameterPort(s) <ParameterPort>` of one or more Mechanisms, that determine the value(s) of

the parameter(s) of the `function(s) <Mechanism_Base.function>` of those Mechanism(s). However, a ControlMechanism

can also be used to modulate the function of `InputPorts <InputPort>` and/or `OutputPort <OutputPorts>`,

much like a `GatingMechanism`.  A ControlMechanism's `function <ControlMechanism.function>` calculates a

`control_allocation <ControlMechanism.control_allocation>`: one or more values used as inputs for its `control_signals

<ControlMechanism.control_signals>`.  Its control_signals are `ControlSignal` OutputPorts that are used to modulate

the parameters of other Mechanisms' `function <Mechanism_Base.function>` (see `ControlSignal_Modulation` for a more

detailed description of how modulation operates).  A ControlMechanism can be configured to monitor the outputs of

other Mechanisms in order to determine its `control_allocation <ControlMechanism.control_allocation>`, by specifying

these in the **monitor_for_control** `argument <ControlMechanism_Monitor_for_Control_Argument>` of its constructor,

or in the **monitor** `argument <ObjectiveMechanism_Monitor>` of an ObjectiveMechanism` assigned to its

**objective_mechanism** `argument <ControlMechanism_Objective_Mechanism_Argument>` (see `ControlMechanism_Creation`

below).  A ControlMechanism can also be assigned as the `controller <Composition.controller>` of a `Composition`,

which has a special relation to that Composition: it generally executes either before or after all of the other

Mechanisms in that Composition (see `Composition_Controller_Execution`).  The OutputPorts monitored by the

ControlMechanism or its `objective_mechanism <ControlMechanism.objective_mechanism>`, and the parameters it modulates

can be listed using its `show <ControlMechanism.show>` method.

.. _ControlMechanism_Composition_Controller:

*ControlMechanisms and a Composition*

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A ControlMechanism can be assigned to a `Composition` and executed just like any other Mechanism. It can also be

assigned as the `controller <Composition.controller>` of a `Composition`, that has a special relation

to the Composition: it is used to control all of the parameters that have been `specified for control

<ControlMechanism_ControlSignals>` in that Composition.  A ControlMechanism can be the `controller

<Composition.controller>` for only one Composition, and a Composition can have only one `controller

<Composition.controller>`.  When a ControlMechanism is assigned as the `controller <Composition.controller>` of a

Composition (either in the Composition's constructor, or using its `add_controller <Composition.add_controller>`

method, the ControlMechanism assumes control over all of the parameters that have been `specified for control

<ControlMechanism_ControlSignals>` for Components in the Composition.  The Composition's `controller

<Composition.controller>` is executed either before or after all of the other Components in the Composition are

executed, including any other ControlMechanisms that belong to it (see `Composition_Controller_Execution`).  A

ControlMechanism can be assigned as the `controller <Composition.controller>` for a Composition by specifying it in

the **controller** argument of the Composition's constructor, or by using the Composition's `add_controller

<Composition.add_controller>` method.  A Composition's `controller <Composition.controller>` and its associated

Components can be displayed using the Composition's `show_graph <ShowGraph.show_graph>` method with its

**show_control** argument assigned as `True`.

.. _ControlMechanism_Creation:

Creating a ControlMechanism

---------------------------

A ControlMechanism is created by calling its constructor.  When a ControlMechanism is created, the OutputPorts it

monitors and the Ports it modulates can be specified in the **montior_for_control** and **objective_mechanism**

arguments of its constructor, respectively.  Each can be specified in several ways, as described below. If neither of

those arguments is specified, then only the ControlMechanism is constructed, and its inputs and the parameters it

modulates must be specified in some other way.

.. _ControlMechanism_Monitor_for_Control:

*Specifying OutputPorts to be monitored*

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A ControlMechanism can be configured to monitor the output of other Mechanisms either directly (by receiving direct

Projections from their OutputPorts), or by way of an `ObjectiveMechanism` that evaluates those outputs and passes the

result to the ControlMechanism (see `below <ControlMechanism_ObjectiveMechanism>` for more detailed description).

The following figures show an example of each:

+-------------------------------------------------------------------------+----------------------------------------------------------------------+

| .. figure:: _static/ControlMechanism_without_ObjectiveMechanism_fig.svg | .. figure:: _static/ControlMechanism_with_ObjectiveMechanism_fig.svg |

+-------------------------------------------------------------------------+----------------------------------------------------------------------+

COMMENT:

FIX: USE THIS IF MOVED TO SECTION AT END THAT CONSOLIDATES EXAMPLES

**ControlMechanism with and without ObjectiveMechanism**

+-------------------------------------------------------------------------+-------------------------------------------------------------------------+

| >>> mech_A = ProcessingMechanism(name='ProcessingMechanism A')          | .. figure:: _static/ControlMechanism_without_ObjectiveMechanism_fig.svg |

| >>> mech_B = ProcessingMechanism(name='ProcessingMechanism B')          |                                                                         |

| >>> ctl_mech = ControlMechanism(name='ControlMechanism',                |                                                                         |

| ...                             monitor_for_control=[mech_A,            |                                                                         |

| ...                                                  mech_B],           |                                                                         |

| ...                             control_signals=[(SLOPE,mech_A),        |                                                                         |

| ...                                              (SLOPE,mech_B)])       |                                                                         |

| >>> comp = Composition()                                                |                                                                         |

| >>> comp.add_linear_processing_pathway([mech_A,mech_B, ctl_mech])       |                                                                         |

| >>> comp.show_graph()                                                   |                                                                         |

+-------------------------------------------------------------------------+-------------------------------------------------------------------------+

| >>> mech_A = ProcessingMechanism(name='ProcessingMechanism A')          | .. figure:: _static/ControlMechanism_with_ObjectiveMechanism_fig.svg    |

| >>> mech_B = ProcessingMechanism(name='ProcessingMechanism B')          |                                                                         |

| >>> ctl_mech = ControlMechanism(name='ControlMechanism',                |                                                                         |

| ...                             monitor_for_control=[mech_A,            |                                                                         |

| ...                                                  mech_B],           |                                                                         |

| ...                             objective_mechanism=True,               |                                                                         |

| ...                             control_signals=[(SLOPE,mech_A),        |                                                                         |

| ...                                              (SLOPE,mech_B)])       |                                                                         |

| >>> comp = Composition()                                                |                                                                         |

| >>> comp.add_linear_processing_pathway([mech_A,mech_B, ctl_mech])       |                                                                         |

| >>> comp.show_graph()                                                   |                                                                         |

+-------------------------------------------------------------------------+-------------------------------------------------------------------------+

COMMENT

Note that, in the figures above, the `ControlProjections <ControlProjection>` are designated with square "arrowheads",

and the ControlMechanisms are shown as septagons to indicate that their ControlProjections create a feedback loop

(see `Composition_Cycles_and_Feedback`;  also, see `below <ControlMechanism_Add_Linear_Processing_Pathway>`

regarding specification of a ControlMechanism and associated ObjectiveMechanism in a Composition's

`add_linear_processing_pathway <Composition.add_linear_processing_pathway>` method).

Which configuration is used is determined by how the following arguments of the ControlMechanism's constructor are

specified (also see `ControlMechanism_Examples`):

  .. _ControlMechanism_Monitor_for_Control_Argument:

  * **monitor_for_control** -- a list of `OutputPort specifications <OutputPort_Specification>`.  If the

    **objective_mechanism** argument is not specified (or is *False* or *None*) then, when the ControlMechanism is

    added to a `Composition`, a `MappingProjection` is created from each OutputPort specified to InputPorts

    created on the ControlMechanism (see `ControlMechanism_Input` for details). If the **objective_mechanism** `argument

    <ControlMechanism_Objective_Mechanism_Argument>` is specified, then the OutputPorts specified in

    **monitor_for_control** are assigned to the `ObjectiveMechanism` rather than the ControlMechanism itself (see

    `ControlMechanism_ObjectiveMechanism` for details).

  .. _ControlMechanism_Objective_Mechanism_Argument:

  * **objective_mechanism** -- if this is specfied in any way other than **False** or **None** (the default),

    then an ObjectiveMechanism is created that projects to the ControlMechanism and, when added to a `Composition`,

    is assigned Projections from all of the OutputPorts specified either in the  **monitor_for_control** argument of

    the ControlMechanism's constructor, or the **monitor** `argument <ObjectiveMechanism_Monitor>` of the

    ObjectiveMechanism's constructor (see `ControlMechanism_ObjectiveMechanism` for details).  The

    **objective_mechanism** argument can be specified in any of the following ways:

    - *False or None* -- no ObjectiveMechanism is created and, when the ControlMechanism is added to a

      `Composition`, Projections from the OutputPorts specified in the ControlMechanism's **monitor_for_control**

      argument are sent directly to ControlMechanism (see specification of **monitor_for_control** `argument

      <ControlMechanism_Monitor_for_Control_Argument>`).

    - *True* -- an `ObjectiveMechanism` is created that projects to the ControlMechanism, and any OutputPorts

      specified in the ControlMechanism's **monitor_for_control** argument are assigned to ObjectiveMechanism's

      **monitor** `argument <ObjectiveMechanism_Monitor>` instead (see `ControlMechanism_ObjectiveMechanism` for

      additional details).

    - *a list of* `OutputPort specifications <ObjectiveMechanism_Monitor>`; an ObjectiveMechanism is created that

      projects to the ControlMechanism, and the list of OutputPorts specified, together with any specified in the

      ControlMechanism's **monitor_for_control** `argument <ControlMechanism_Monitor_for_Control_Argument>`, are

      assigned to the ObjectiveMechanism's **monitor** `argument <ObjectiveMechanism_Monitor>` (see

      `ControlMechanism_ObjectiveMechanism` for additional details).

    - *a constructor for an* `ObjectiveMechanism` -- the specified ObjectiveMechanism is created, adding any

      OutputPorts specified in the ControlMechanism's **monitor_for_control** `argument

      <ControlMechanism_Monitor_for_Control_Argument>` to any specified in the ObjectiveMechanism's **monitor**

      `argument <ObjectiveMechanism_Monitor>` .  This can be used to specify the `function

      <ObjectiveMechanism.function>` used by the ObjectiveMechanism to evaluate the OutputPorts monitored as well as

      how it weights those OutputPorts when they are evaluated  (see `below

      <ControlMechanism_ObjectiveMechanism_Function>` for additional details).

    - *an existing* `ObjectiveMechanism` -- for any OutputPorts specified in the ControlMechanism's

      **monitor_for_control** `argument <ControlMechanism_Monitor_for_Control_Argument>`, an InputPort is added to the

      ObjectiveMechanism, along with `MappingProjection` to it from the specified OutputPort.    This can be used to

      specify an ObjectiveMechanism with a custom `function <ObjectiveMechanism.function>` and weighting of the

      OutputPorts monitored (see `below <ControlMechanism_ObjectiveMechanism_Function>` for additional details).

  .. _ControlMechanism_Allow_Probes:

  * **allow_probes** -- this argument allows values of Components of a `nested Composition <Composition_Nested>` other

    than its `OUTPUT <NodeRole.OUTPUT>` `Nodes <Composition_Nodes>` to be specified in the **monitor_for_control**

    argument of the ControlMechanism's constructor or, if **objective_mechanism** is specified, in the

    **monitor** argument of the ObjectiveMechanism's constructor (see above).  If the Composition's `allow_probes

    <Composition.allow_probes>` attribute is False, it is set to *CONTROL*, and only a ControlMechanism can receive

    projections from `PROBE <NodeRole.PROBE>` Nodes of a nested Composition (the current one as well as any others in

    the same Composition);  if the Composition's `allow_probes <Composition.allow_probes>` attribute is True, then it

    is left that way, and any node within the Comopsition, including the ControlMechanism, can receive projections from

    `PROBE <NodeRole.PROBE>` Nodes (see `Probes <Composition_Probes>` for additional details).

The OutputPorts monitored by a ControlMechanism or its `objective_mechanism <ControlMechanism.objective_mechanism>`

are listed in the ControlMechanism's `monitor_for_control <ControlMechanism.monitor_for_control>` attribute

(and are the same as those listed in the `monitor <ObjectiveMechanism.monitor>` attribute of the

`objective_mechanism <ControlMechanism.objective_mechanism>`, if specified).

.. _ControlMechanism_Add_Linear_Processing_Pathway:

Note that the MappingProjections created by specification of a ControlMechanism's **monitor_for_control** `argument

<ControlMechanism_Monitor_for_Control_Argument>` or the **monitor** argument in the constructor for an

ObjectiveMechanism in the ControlMechanism's **objective_mechanism** `argument

<ControlMechanism_Objective_Mechanism_Argument>` supersede any MappingProjections that would otherwise be created for

them when included in the **pathway** argument of a Composition's `add_linear_processing_pathway

<Composition.add_linear_processing_pathway>` method.

.. _ControlMechanism_ObjectiveMechanism:

Objective Mechanism

^^^^^^^^^^^^^^^^^^^

COMMENT:

TBI FOR COMPOSITION

If the ControlMechanism is created automatically by a System (as its `controller <System.controller>`), then the

specification of OutputPorts to be monitored and parameters to be controlled are made on the System and/or the

Components themselves (see `System_Control_Specification`).  In either case, the Components needed to monitor the

specified OutputPorts (an `ObjectiveMechanism` and `Projections <Projection>` to it) and to control the specified

parameters (`ControlSignals <ControlSignal>` and corresponding `ControlProjections <ControlProjection>`) are created

automatically, as described below.

COMMENT

If an `ObjectiveMechanism` is specified for a ControlMechanism (in the **objective_mechanism** `argument

<ControlMechanism_Objective_Mechanism_Argument>` of its constructor; also see `ControlMechanism_Examples`),

it is assigned to the ControlMechanism's `objective_mechanism <ControlMechanism.objective_mechanism>` attribute,

and a `MappingProjection` is created automatically that projects from the ObjectiveMechanism's *OUTCOME*

`output_port <ObjectiveMechanism_Output>` to the *OUTCOME* `input_port <ControlMechanism_Input>` of the

ControlMechanism.

The `objective_mechanism <ControlMechanism.objective_mechanism>` is used to monitor the OutputPorts

specified in the **monitor_for_control** `argument <ControlMechanism_Monitor_for_Control_Argument>` of the

ControlMechanism's constructor, as well as any specified in the **monitor** `argument <ObjectiveMechanism_Monitor>` of

the ObjectiveMechanism's constructor.  Specifically, for each OutputPort specified in either place, an `input_port

<ObjectiveMechanism.input_ports>` is added to the ObjectiveMechanism.  OutputPorts to be monitored (and

corresponding `input_ports <ObjectiveMechanism.input_ports>`) can be added to the `objective_mechanism

<ControlMechanism.objective_mechanism>` later, by using its `add_to_monitor <ObjectiveMechanism.add_to_monitor>` method.

The set of OutputPorts monitored by the `objective_mechanism <ControlMechanism.objective_mechanism>` are listed in

its `monitor <ObjectiveMechanism>` attribute, as well as in the ControlMechanism's `monitor_for_control

<ControlMechanism.monitor_for_control>` attribute.

When the ControlMechanism is added to a `Composition`, the `objective_mechanism <ControlMechanism.objective_mechanism>`

is also automatically added, and MappingProjectons are created from each of the OutputPorts that it monitors to

its corresponding `input_ports <ObjectiveMechanism.input_ports>`.  When the Composition is run, the `value

<OutputPort.value>`\\(s) of the OutputPort(s) monitored are evaluated using the `objective_mechanism`\\'s `function

<ObjectiveMechanism.function>`, and the result is assigned to its *OUTCOME* `output_port

<ObjectiveMechanism_Output>`.  That `value <ObjectiveMechanism.value>` is then passed to the ControlMechanism's

*OUTCOME* `input_port <ControlMechanism_Input>`, which is used by the ControlMechanism's `function

<ControlMechanism.function>` to determine its `control_allocation <ControlMechanism.control_allocation>`.

.. _ControlMechanism_ObjectiveMechanism_Function:

If a default ObjectiveMechanism is created by the ControlMechanism (i.e., when *True* or a list of OutputPorts is

specified for the **objective_mechanism** `argument <ControlMechanism_Objective_Mechanism_Argument>` of the

constructor), then the ObjectiveMechanism is created with its standard default `function <ObjectiveMechanism.function>`

(`LinearCombination`), but using *PRODUCT* (rather than the default, *SUM*) as the value of the function's `operation

<LinearCombination.operation>` parameter. The result is that the `objective_mechanism

<ControlMechanism.objective_mechanism>` multiplies the `value <OutputPort.value>`\\s of the OutputPorts that it

monitors, which it passes to the ControlMechanism.  However, if the **objective_mechanism** is specified using either

a constructor for, or an existing ObjectiveMechanism, then the defaults for the `ObjectiveMechanism` class -- and any

attributes explicitly specified in its construction -- are used.  In that case, if the `LinearCombination` with

*PRODUCT* as its `operation <LinearCombination.operation>` parameter are still desired, this must be explicitly

specified.  This is illustrated in the following examples.

The following example specifies a `ControlMechanism` that automatically constructs its `objective_mechanism

<ControlMechanism.objective_mechanism>`::

    >>> from psyneulink import *

    >>> my_ctl_mech = ControlMechanism(objective_mechanism=True)

    >>> assert isinstance(my_ctl_mech.objective_mechanism.function, LinearCombination)

    >>> assert my_ctl_mech.objective_mechanism.function.operation == PRODUCT

Notice that `LinearCombination` was assigned as the `function <ObjectiveMechanism.function>` of the `objective_mechanism

<ControlMechanism.objective_mechanism>`, and *PRODUCT* as its `operation <LinearCombination.operation>` parameter.

By contrast, the following example explicitly specifies the **objective_mechanism** argument using a constructor for

an ObjectiveMechanism::

    >>> my_ctl_mech = ControlMechanism(objective_mechanism=ObjectiveMechanism())

    >>> assert isinstance(my_ctl_mech.objective_mechanism.function, LinearCombination)

    >>> assert my_ctl_mech.objective_mechanism.function.operation == SUM

In this case, the defaults for the ObjectiveMechanism's class are used for its `function <ObjectiveMechanism.function>`,

which is a `LinearCombination` function with *SUM* as its `operation <LinearCombination.operation>` parameter.

Specifying the ControlMechanism's `objective_mechanism <ControlMechanism.objective_mechanism>` with a constructor

also provides greater control over how ObjectiveMechanism evaluates the OutputPorts it monitors.  In addition to

specifying its `function <ObjectiveMechanism.function>`, the **monitor_weights_and_exponents** `argument

<ObjectiveMechanism_Monitor_Weights_and_Exponents>` can be used to parameterize the relative contribution made by the

monitored OutputPorts when they are evaluated by that `function <ObjectiveMechanism.function>` (see

`ControlMechanism_Examples`).

COMMENT:

TBI FOR COMPOSITION

When a ControlMechanism is created for or assigned as the `controller <Composition.controller>` of a `Composition` (see

`ControlMechanism_Composition_Controller`), any OutputPorts specified to be monitored by the System are assigned as

inputs to the ObjectiveMechanism.  This includes any specified in the **monitor_for_control** argument of the

System's constructor, as well as any specified in a MONITOR_FOR_CONTROL entry of a Mechanism `parameter specification

dictionary <ParameterPort_Specification>` (see `Mechanism_Constructor_Arguments` and `System_Control_Specification`).

FOR DEVELOPERS:

    If the ObjectiveMechanism has not yet been created, these are added to the **monitored_output_ports** of its

    constructor called by ControlMechanism._instantiate_objective_mechanism;  otherwise, they are created using the

    ObjectiveMechanism.add_to_monitor method.

COMMENT

.. _ControlMechanism_ControlSignals:

*Specifying Parameters to Control*

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This can be specified in either of two ways (see `ControlSignal_Examples` in `ControlSignal`):

*With a ControlMechanism itself*

The parameters controlled by a ControlMechanism can be specified in the **control** argument of its constructor;

the argument must be a `specification for one more ControlSignals <ControlSignal_Specification>`.  The parameter to

be controlled must belong to a Component in the same `Composition` as the ControlMechanism when it is added to the

Composition, or an error will occur.

*With a Parameter to be controlled by the* `controller <Composition.controller>` *of a* `Composition`

Control can also be specified for a parameter where the `parameter itself is specified <ParameterPort_Specification>`,

by including the specification of a `ControlSignal`, `ControlProjection`, or the keyword `CONTROL` in a `tuple

specification <ParameterPort_Tuple_Specification>` for the parameter.  In this case, the specified parameter will be

assigned for control by the `controller <Composition.controller>` of any `Composition` to which its Component belongs,

when the Component is added to the Composition (see `ControlMechanism_Composition_Controller`).  Conversely, when

a ControlMechanism is assigned as the `controller <Composition.controller>` of a Composition, a `ControlSignal` is

created and assigned to the ControlMechanism for every parameter of any `Component <Component>` in the Composition

that has been `specified for control <ParameterPort_Modulatory_Specification>`.

In general, a `ControlSignal` is created for each parameter specified to be controlled by a ControlMechanism.  These

are a type of `OutputPort` that send a `ControlProjection` to the `ParameterPort` of the parameter to be

controlled. All of the ControlSignals for a ControlMechanism are listed in its `control_signals

<ControlMechanism.control_signals>` attribute, and all of its ControlProjections are listed in

its `control_projections <ControlMechanism.control_projections>` attribute (see `ControlMechanism_Examples`).

.. _ControlMechanism_Structure:

Structure

---------

.. _ControlMechanism_Input:

*Input*

~~~~~~~

By default, a ControlMechanism has a single `input_port <Mechanism_Base.input_port>` named *OUTCOME*. If it has an

`objective_mechanism <ControlMechanism.objective_mechanism>`, then the *OUTCOME* `input_port

<ControlMechanism.outcome_input_ports>` receives a single `MappingProjection` from the `objective_mechanism

<ControlMechanism.objective_mechanism>`\\'s *OUTCOME* `OutputPort <OutputPort>` (see

`ControlMechanism_ObjectiveMechanism` for additional details). If the ControlMechanism has no `objective_mechanism

<ControlMechanism.objective_mechanism>` then, when it is added to a `Composition`, MappingProjections are created

from the items specified in `monitor_for_control <ControlMechanism.monitor_for_control>` directly to InputPorts on

the ControlMechanism (see `ControlMechanism_Monitor_for_Control` for additional details). The number of InputPorts

created, and how the items listed in `monitor_for_control <ControlMechanism.monitor_for_control>` project to them is

deterimined by the ControlMechanism's `outcome_input_ports_option <ControlMechanism.outcome_input_ports_option>`.

All of the Inports that receive Projections from those items, or the `objective_mechanism

<ControlMechanism.objective_mechanism>` if the ControlMechanism has one, are listed in its `outcome_input_ports

<ControlMechanism.outcome_input_ports>` attribute, and their values in the `outcome <ControlMechanism.outcome>`

attribute.  The latter is used as the input to the ControlMechanism's `function <ControlMechanism.function>` to

determine its `control_allocation <ControlMechanism.control_allocation>`.

.. _ControlMechanism_Function:

*Function*

~~~~~~~~~~

A ControlMechanism's `function <ControlMechanism.function>` uses its `outcome <ControlMechanism.outcome>`

attribute (the `value <InputPort.value>` of its *OUTCOME* `InputPort`) to generate one or more values used

for ControlMechanism's `control_allocation <ControlMechanism.control_allocation>`.  By default, its `function

<ControlMechanism.function>` is assigned the `Identity` Function, which takes a single value as its input and returns

it as its output.  That is then used as the ControlSignal's `control_allocation <ControlMechanism.control_allocation>`,

which in turn is assigned as the allocation for all of the ControlMechanism's `control_signals

<ControlMechanism.control_signals>`. That is, by default, the ControlMechanism's input is distributed as the

allocation to each of its `control_signals <ControlMechanism.control_signals>`. This same behavior also occurs for

any custom function assigned to a ControlMechanism that returns a 2d array with a single item in its outer dimension

(axis 0).  If a function is assigned that returns a 2d array with more than one item, and the number of those items

(i.e., the length of the 2d array) is the same as the number of `control_signals <ControlMechanism.control_signals>`,

then each item is assigned to a corresponding `ControlSignal` (in the order in which they are specified in the

**control_signals** argument of the ControlMechanism's constructor).  However, these default behaviors can be modified

by specifying that individual ControlSignals reference different items in the ControlMechanism's `value

<Mechanism_Base.value>` (see `OutputPort_Custom_Variable`).

.. _ControlMechanism_Output:

*Output*

~~~~~~~~

The OutputPorts of a ControlMechanism are `ControlSignals <ControlSignal>` (listed in its `control_signals

<ControlMechanism.control_signals>` attribute). It has a `ControlSignal` for each parameter specified in the

**control** argument of its constructor, that sends a `ControlProjection` to the `ParameterPort` for the

corresponding parameter.  The ControlSignals are listed in the `control_signals <ControlMechanism.control_signals>`

attribute;  since they are a type of `OutputPort`, they are also listed in the ControlMechanism's `output_ports

<Mechanism_Base.output_ports>` attribute. The parameters modulated by a ControlMechanism's ControlSignals can be

displayed using its `show <ControlMechanism.show>` method.

By default, each `ControlSignal` is assigned as its `allocation <ControlSignal.allocation>` the value of the

corresponding item of the ControlMechanism's `control_allocation <ControlMechanism.control_allocation>`;  however,

subtypes of ControlMechanism may assign allocations differently. The **default_allocation** argument of the

ControlMechanism's constructor can be used to specify a default allocation for ControlSignals that

have not been assigned their own `default_allocation <ControlSignal.default_allocation>`.

.. warning::

    the **default_variable** argument of the ControlMechanism's constructor is **not** used to specify a default

    allocation;  the **default_allocation** argument must be used for that purpose.  The **default_variable** argument

    should only be used to specify the format of the `value <ControlMechanism.value>` of the ControlMechanism's

    `input_port (see `Mechanism_InputPorts` for additional details), and its default input when it does not receive

    any Projections (see `default_variable <Component_Variable>` for additional details).

.. note::

   While specifying **default_allocation** will take effect the first time the ControlMechanism is executed,

   a value specified for **default_variable** will not take effect (i.e., in determining `control_allocation

   <ControlMechanism.control_allocation>` or `value <ControlSignal.value>`\\s of the ControlSignals) until after

   the ControlMechahnism is executed, and thus will not influence the parameters it controls until the next round of

   execution (see `Composition_Timing` for a detailed description of the sequence of events during a Composition's

   execution).

COMMENT:

    The `value <ControlSignal.value>` of a ControlSignal is not necessarily the same as its `allocation.

    <ControlSignal.allocation>`  The former is the result of the ControlSignal's `function <ControlSignal.function>`,

    which is executed when the ControlSignal is updated;  the latter is the value assigned to the ControlSignal's

COMMENT

The `allocation <ControlSignal.allocation>` is used by each ControlSignal to determine its `intensity

<ControlSignal.intensity>`, which is then assigned to the `value <ControlProjection.value>`

of the ControlSignal's `ControlProjection`.   The `value <ControlProjection.value>` of the ControlProjection

is used by the `ParameterPort` to which it projects to modify the value of the parameter it controls (see

`ControlSignal_Modulation` for a description of how a ControlSignal modulates the value of a parameter).

.. _ControlMechanism_Costs_NetOutcome:

*Costs and Net Outcome*

~~~~~~~~~~~~~~~~~~~~~~~

A ControlMechanism's `control_signals <ControlMechanism.control_signals>` are each associated with a set of `costs

<ControlSignal_Costs>`, that are computed individually by each `ControlSignal` when they are `executed

<ControlSignal_Execution>` by the ControlMechanism.  The costs last computed by the `control_signals

<ControlMechanism>` are assigned to the ControlMechanism's `costs <ControlSignal.costs>` attribute.  A ControlMechanism

also has a set of methods -- `combine_costs <ControlMechanism.combine_costs>`, `compute_reconfiguration_cost

<ControlMechanism.compute_reconfiguration_cost>`, and `compute_net_outcome <ControlMechanism.compute_net_outcome>` --

that can be used to compute the `combined costs <ControlMechanism.combined_costs>` of its `control_signals

<ControlMechanism.control_signals>`, a `reconfiguration_cost <ControlSignal.reconfiguration_cost>` based on their change

in value, and a `net_outcome <ControlMechanism.net_outcome>` (the `value <InputPort.value>` of the ControlMechanism's

*OUTCOME* `InputPort <ControlMechanism_Input>` minus its `combined costs <ControlMechanism.combined_costs>`),

respectively (see `ControlMechanism_Costs_Computation` below for additional details). These methods are used by some

subclasses of ControlMechanism (e.g., `OptimizationControlMechanism`) to compute their `control_allocation

<ControlMechanism.control_allocation>`.  Each method is assigned a default function, but can be assigned a custom

functions in a corrsponding argument of the ControlMechanism's constructor (see links to attributes for details).

.. _ControlMechanism_Reconfiguration_Cost:

*Reconfiguration Cost*

A ControlMechanism's `reconfiguration_cost <ControlMechanism.reconfiguration_cost>` is distinct from the

costs of the ControlMechanism's `ControlSignals <ControlSignal>`, and in particular it is not the same as their

`adjustment_cost <ControlSignal.adjustment_cost>`.  The latter, if specified by a ControlSignal, is computed

individually by that ControlSignal using its `adjustment_cost_function <ControlSignal.adjustment_cost_function>`, based

on the change in its `intensity <ControlSignal.intensity>` from its last execution. In contrast, a ControlMechanism's

`reconfiguration_cost  <ControlMechanism.reconfiguration_cost>` is computed by its `compute_reconfiguration_cost

<ControlMechanism.compute_reconfiguration_cost>` function, based on the change in its `control_allocation

ControlMechanism.control_allocation>` from the last execution, that will be applied to *all* of its

`control_signals <ControlMechanism.control_signals>`. By default, `compute_reconfiguration_cost

<ControlMechanism.compute_reconfiguration_cost>` is assigned as the `Distance` function with the `EUCLIDEAN` metric).

.. _ControlMechanism_Execution:

Execution

---------

A ControlMechanism is executed using the same sequence of actions as any `Mechanism <Mechanism_Execution>`, with the

following additions.

# FIX: 11/3/21: MODIFY TO INCLUDE POSSIBLITY OF MULTIPLE OUTCOME_INPUT_PORTS

The ControlMechanism's `function <ControlMechanism.function>` takes as its input the `value <InputPort.value>` of

its *OUTCOME* `input_port <ControlMechanism.input_port>` (also contained in `outcome <ControlSignal.outcome>`).

It uses that to determine the `control_allocation <ControlMechanism.control_allocation>`, which specifies the value

assigned to the `allocation <ControlSignal.allocation>` of each of its `ControlSignals <ControlSignal>`.  Each

ControlSignal uses that value to calculate its `intensity <ControlSignal.intensity>`, as well as its `cost

<ControlSignal.cost>.  The `intensity <ControlSignal.intensity>`is used by its `ControlProjection(s)

<ControlProjection>` to modulate the value of the ParameterPort(s) for the parameter(s) it controls.  Note that

the modulated value of the parameter may not be used until the subsequent `TRIAL <TimeScale.TRIAL>` of execution,

if the ControlMechansim is not executed until after the Component to which the paramter belongs is executed

(see `note <ModulatoryMechanism_Lazy_Evaluation_Note>`).

.. _ControlMechanism_Costs_Computation:

*Computation of Costs and Net_Outcome*

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once the ControlMechanism's `function <ControlMechanism.function>` has executed, if `compute_reconfiguration_cost

<ControlMechanism.compute_reconfiguration_cost>` has been specified, then it is used to compute the

`reconfiguration_cost <ControlMechanism.reconfiguration_cost>` for its `control_allocation

<ControlMechanism.control_allocation>` (see `above <ControlMechanism_Reconfiguration_Cost>`. After that, each

of the ControlMechanism's `control_signals <ControlMechanism.control_signals>` calculates its `cost

<ControlSignal.cost>`, based on its `intensity  <ControlSignal.intensity>`.  The ControlMechanism then combines these

with the `reconfiguration_cost <ControlMechanism.reconfiguration_cost>` using its `combine_costs

<ControlMechanism.combine_costs>` function, and the result is assigned to the `costs <ControlMechanism.costs>`

attribute.  Finally, the ControlMechanism uses this, together with its `outcome <ControlMechanism.outcome>` attribute,

to compute a `net_outcome <ControlMechanism.net_outcome>` using its `compute_net_outcome

<ControlMechanism.compute_net_outcome>` function.  This is used by some subclasses of ControlMechanism

(e.g., `OptimizationControlMechanism`) to  compute its `control_allocation <ControlMechanism.control_allocation>`

for the next `TRIAL <TimeScale.TRIAL>` of execution.

.. _ControlMechanism_Controller_Execution:

*Execution as Controller of a Composition*

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

if a ControlMechanism is assigned as the `controller of a `Composition <ControlMechanism_Composition_Controller>`,

then it is executed either before or after all of the other  `Mechanisms <Mechanism>` executed in a `TRIAL

<TimeScale.TRIAL>` for that Composition, depending on the value assigned to the Composition's `controller_mode

<Composition.controller_mode>` attribute (see `Composition_Controller_Execution`).  If a ControlMechanism is added to

a Composition for which it is not a `controller <Composition.controller>`, then it executes in the same way as any

`Mechanism <Mechanism>`, based on its place in the Composition's `graph <Composition.graph>`.  Because

`ControlProjections <ControlProjection>` are likely to introduce cycles (recurrent connection loops) in the

graph, the effects of a ControlMechanism and its projections will generally not be applied in the first `TRIAL

<TimeScale.TRIAL>` (see `Composition_Cycles_and_Feedback` for configuring the initialization of feedback

loops in a Composition; also see `Scheduler` for a description of additional ways in which a ControlMechanism and its

dependents can be scheduled to execute).

.. _ControlMechanism_Examples:

Examples

--------

The examples below focus on the specification of the `objective_mechanism <ControlMechanism.objective_mechanism>`

for a ControlMechanism.  See `Control Signal Examples <ControlSignal_Examples>` for examples of how to specify the

ControlSignals for a ControlMechanism.

The following example creates a ControlMechanism by specifying its **objective_mechanism** using a constructor

that specifies the OutputPorts to be monitored by its `objective_mechanism <ControlMechanism.objective_mechanism>`

and the function used to evaluate these::

    >>> my_mech_A = ProcessingMechanism(name="Mech A")

    >>> my_DDM = DDM(name="My DDM")

    >>> my_mech_B = ProcessingMechanism(function=Logistic,

    ...                                 name="Mech B")

    >>> my_control_mech = ControlMechanism(

    ...                          objective_mechanism=ObjectiveMechanism(monitor=[(my_mech_A, 2, 1),

    ...                                                                           my_DDM.output_ports[RESPONSE_TIME]],

    ...                                                                 name="Objective Mechanism"),

    ...                          function=LinearCombination(operation=PRODUCT),

    ...                          control_signals=[(THRESHOLD, my_DDM),

    ...                                           (GAIN, my_mech_B)],

    ...                          name="My Control Mech")

This creates an ObjectiveMechanism for the ControlMechanism that monitors the `primary OutputPort <OutputPort_Primary>`

of ``my_mech_A`` and the *RESPONSE_TIME* OutputPort of ``my_DDM``;  its function first multiplies the former by ``2``,

then takes product of their values and passes the result as the input to the ControlMechanism.  The ControlMechanism's

`function <ControlMechanism.function>` uses this value to determine the allocation for its ControlSignals, that control

the value of the `threshold <DriftDiffusionAnalytical.threshold>` parameter of the `DriftDiffusionAnalytical` Function

for ``my_DDM`` and the  `gain <Logistic.gain>` parameter of the `Logistic` Function for ``my_transfer_mech_B``.

The following example specifies the same set of OutputPorts for the ObjectiveMechanism, by assigning them directly

to the **objective_mechanism** argument::

    >>> my_control_mech = ControlMechanism(

    ...                             objective_mechanism=[(my_mech_A, 2, 1),

    ...                                                  my_DDM.output_ports[RESPONSE_TIME]],

    ...                             control_signals=[(THRESHOLD, my_DDM),

    ...                                              (GAIN, my_mech_B)])

Note that, while this form is more succinct, it precludes specifying the ObjectiveMechanism's function.  Therefore,

the values of the monitored OutputPorts 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 = ObjectiveMechanism(monitored_output_ports=[(my_mech_A, 2, 1),

    ...                                                            my_DDM.output_ports[RESPONSE_TIME]],

    ...                                      function=LinearCombination(operation=PRODUCT))

    >>> my_control_mech = ControlMechanism(

    ...                        objective_mechanism=my_obj_mech,

    ...                        control_signals=[(THRESHOLD, my_DDM),

    ...                                         (GAIN, my_mech_B)])

Here, as in the first example, the constructor for the ObjectiveMechanism can be used to specify its function, as well

as the OutputPort that it monitors.

COMMENT:

FIX 8/27/19 [JDC]:  ADD TO COMPOSITION

See `System_Control_Examples` for examples of how a ControlMechanism, the OutputPorts its

`objective_mechanism <ControlSignal.objective_mechanism>`, and its `control_signals <ControlMechanism.control_signals>`

can be specified for a System.

COMMENT

.. _ControlMechanism_Class_Reference:

Class Reference

---------------

"""

    AUTO_ASSIGN_MATRIX, COMBINE, CONTROL, CONTROL_PROJECTION, CONTROL_SIGNAL, CONTROL_SIGNALS, CONCATENATE, \

    EID_SIMULATION, FEEDBACK, FUNCTION, GATING_SIGNAL, INIT_EXECUTE_METHOD_ONLY, INTERNAL_ONLY, NAME, \

    MECHANISM, MULTIPLICATIVE, MODULATORY_SIGNALS, MONITOR_FOR_CONTROL, MONITOR_FOR_MODULATION, \

    OBJECTIVE_MECHANISM, OUTCOME, OWNER_VALUE, PARAMS, PORT_TYPE, PRODUCT, PROJECTION_TYPE, PROJECTIONS, \

    REFERENCE_VALUE, SEPARATE, INPUT_SHAPES, VALUE

    'CONTROL_ALLOCATION', 'GATING_ALLOCATION', 'ControlMechanism', 'ControlMechanismError',

]

                           ControlSignal,

                           ControlProjection)):

                                                      ControlSignal,

                                                      ControlProjection)):

    else:

            # If it is a dict, parse to validate that it is an InputPort specification dict

            #    (for InputPort of ObjectiveMechanism to be assigned to the monitored_output_port)

            # Get the OutputPort, to validate that it is in the ControlMechanism's Composition (below);

            #    presumes that the monitored_output_port is the first in the list of projection_specs

            #    in the InputPort port specification dictionary returned from the parse,

            #    and that it is specified as a projection_spec (parsed into that in the call

            #    to _parse_connection_specs by _parse_port_spec)

                raise ControlMechanismError(

                    f"Mechanism class ({spec.__name__}) specified in '{MONITOR_FOR_CONTROL}' arg "

                    f"of {owner.name}; it must be an instantiated {Mechanism.__name__} or "

                    f"{OutputPort.__name__} of one."

                )

                raise ControlMechanismError(

                    f"{spec.__class__.__name__} specified in '{MONITOR_FOR_CONTROL}' arg of {owner.name} "

                    f"({spec.name} of {spec.owner.name}); "

                    f"it must be an {OutputPort.__name__} or {Mechanism.__name__}."

                )

            else:

                raise ControlMechanismError(

                    f"Erroneous specification of '{MONITOR_FOR_CONTROL}' arg for {owner.name} ({spec}); "

                    f"it must be an {OutputPort.__name__} or a {Mechanism.__name__}."

                )

    # NOTE: In cases where there is a reconfiguration_cost, that cost is not returned by this method

            (

                c.compute_costs(c.parameters.value._get(context), context=context)

                if c.initialization_status != ContextFlags.DEFERRED_INIT else None

            )

            for c in owning_component.control_signals

            if hasattr(c, 'compute_costs')

        ])  # GatingSignals don't have cost fcts

    """Return array of values of outcome_input_ports"""

                        dytpe=object)

    # NOTE: In cases where there is a reconfiguration_cost, that cost is not included in the net_outcome

            c.parameters.outcome._get(context),

            c.combine_costs()

        )

            v.parameters.variable._get(context) for v in owning_component.control_signals

        ])

    """

    ControlMechanism(                        \

        monitor_for_control=None,            \

        objective_mechanism=None,            \

        allow_probes=False,                  \

        outcome_input_ports_option=SEPARATE  \

        function=Linear,                     \

        default_allocation=None,             \

        control=None,                        \

        modulation=MULTIPLICATIVE,           \

        combine_costs=np.sum,                \

        compute_reconfiguration_cost=None,   \

        compute_net_outcome=lambda x,y:x-y)

    Subclass of `ModulatoryMechanism <ModulatoryMechanism>` that modulates the parameter(s) of one or more

    `Component(s) <Component>`.  See `Mechanism <Mechanism_Class_Reference>` for additional arguments and attributes.

    COMMENT: FIX 5/8/20

        Description:

            Protocol for instantiating unassigned ControlProjections (i.e., w/o a sender specified):

               If sender is not specified for a ControlProjection (e.g., in a parameter specification tuple)

                   it is flagged for deferred_init() in its __init__ method

               If ControlMechanism is instantiated or assigned as the controller for a System:

                   the System calls its _get_monitored_output_ports() method which returns all of the OutputPorts

                       within the System that have been specified to be MONITORED_FOR_CONTROL, and then assigns

                       them (along with any specified in the **monitored_for_control** arg of the System's constructor)

                       to the `objective_mechanism` argument of the ControlMechanism's constructor;

                   the System calls its _get_control_signals_for_system() method which returns all of the parameters

                       that have been specified for control within the System, assigns them a ControlSignal

                       (with a ControlProjection to the ParameterPort for the parameter), and assigns the

                       ControlSignals (alogn with any specified in the **control** argument of the System's

                       constructor) to the **control** argument of the ControlMechanism's constructor

            OBJECTIVE_MECHANISM param determines which Ports will be monitored.

                specifies the OutputPorts of the terminal Mechanisms in the System to be monitored by ControlMechanism

                this specification overrides any in System.], but can be overridden by mechanism.params[

                ?? if MonitoredOutputPorts appears alone, it will be used to determine how Ports are assigned from

                    System.execution_graph by default

                if MonitoredOutputPortsOption is used, it applies to any Mechanisms specified in the list for which

                    no OutputPorts are listed; it is overridden for any Mechanism for which OutputPorts are

                    explicitly listed

                TBI: if it appears in a tuple with a Mechanism, or in the Mechamism's params list, it applies to

                    just that Mechanism

    COMMENT

    Arguments

    ---------

    monitor_for_control : List[OutputPort or Mechanism] : default None

        specifies the `OutputPorts <OutputPort>` to be monitored by the `ObjectiveMechanism`, if specified in the

        **objective_mechanism** argument (see `ControlMechanism_ObjectiveMechanism`), or directly by the

        ControlMechanism itself if an **objective_mechanism** is not specified.  If any specification is a Mechanism

        (rather than its OutputPort), its `primary OutputPort <OutputPort_Primary>` is used (see

        `ControlMechanism_Monitor_for_Control` for additional details).

    objective_mechanism : ObjectiveMechanism or List[OutputPort specification] : default None

        specifies either an `ObjectiveMechanism` to use for the ControlMechanism, or a list of the OutputPorts it

        should monitor; if a list of `OutputPort specifications <ObjectiveMechanism_Monitor>` is used,

        a default ObjectiveMechanism is created and the list is passed to its **monitor** argument, along with any

        OutputPorts specified in the ControlMechanism's **monitor_for_control** `argument

        <ControlMechanism_Monitor_for_Control_Argument>`.

    allow_probes : bool : default False

        specifies whether Components of a `nested Composition <Composition_Nested>` that are not OUTPUT

        <NodeRole.OUTPUT>` `Nodes <Composition_Nodes>` of that Composition can be specified as items in the

        ControlMechanism's  **monitor_for_control** argument or, if **objective_mechanism**

        is specified, in the ObjectiveMechanism's **monitor** argument (see `allow_probes

        <ControlMechanism_Allow_Probes>` for additional information).

    outcome_input_ports_option : COMBINE, CONCATENATE, SEPARATE : default SEPARATE

        if **objective_mechanism** is not specified, this specifies whether `MappingProjections <MappingProjection>`

        from items specified in **monitor_for_control** are each assigned their own `InputPort` (*SEPARATE*)

        or to a single *OUTCOME* InputPort (*CONCATENATE*, *COMBINE*); (see `outcome_input_ports_option

        <ControlMechanism.outcome_input_ports_option>` for additional details.

    function : TransferFunction : default Linear(slope=1, intercept=0)

        specifies function used to combine values of monitored OutputPorts.

    control : ControlSignal specification or list[ControlSignal specification, ...]

        specifies the parameters to be controlled by the ControlMechanism; a `ControlSignal` is created for each

        (see `ControlSignal_Specification` for details of specification).

    modulation : str : MULTIPLICATIVE

        specifies the default form of modulation used by the ControlMechanism's `ControlSignals <ControlSignal>`,

        unless they are `individually specified <ControlSignal_Specification>`.

    combine_costs : Function, function or method : default np.sum

        specifies function used to combine the `cost <ControlSignal.cost>` of the ControlMechanism's `control_signals

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

        <ControlMechanism.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 <ControlMechanism.outcome>` and `costs

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

    Attributes

    ----------

    monitor_for_control : List[OutputPort]

        each item is an `OutputPort` monitored by the ControlMechanism or its `objective_mechanism

        <ControlMechanism.objective_mechanism>` if that is specified (see `ControlMechanism_Monitor_for_Control`);

        in the latter case, the list returned is ObjectiveMechanism's `monitor <ObjectiveMechanism.monitor>` attribute.

    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_port <Mechanism_Base.input_port>`.

    allow_probes : bool

        indicates status of the `allow_probes <Composition.allow_probes>` attribute of the Composition

        to which the ControlMechanism belongs.  If False, items specified in the `monitor_for_control

        <ControlMechanism.monitor_for_control>` are all `OUTPUT <NodeRole.OUTPUT>` `Nodes <Composition_Nodes>`

        of that Composition.  If True, they may be `INPUT <NodeRole.INPUT>` or `INTERNAL <NodeRole.INTERNAL>`

        `Nodes <Composition_Nodes>` of `nested Composition <Composition_Nested>` (see `allow probes

        <ControlMechanism_Allow_Probes>` and `Composition_Probes` for additional information).