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.

# ****************************************  MECHANISM MODULE ***********************************************************

"""

Contents

--------

  * `Mechanism_Overview`

  * `Mechanism_Creation`

  * `Mechanism_Structure`

      - `Mechanism_Function`

      - `Mechanism_Ports`

          • `Mechanism_InputPorts`

          • `Mechanism_ParameterPorts`

          • `Mechanism_OutputPorts`

      - `Mechanism_Additional_Attributes`

      - `Mechanism_in_Composition`

  * `Mechanism_Execution`

      - `Mechanism_Execution_Composition`

      - `Mechanism_Runtime_Params`

  * `Mechanism_Class_Reference`

.. _Mechanism_Overview:

Overview

--------

A Mechanism takes an input, transforms it in some way, and makes the result available as its output.  There are two

types of Mechanisms in PsyNeuLink:

    * `ProcessingMechanisms <ProcessingMechanism>` aggregate the input they receive from other Mechanisms, and/or the

      input to the `Composition` to which they belong, transform it in some way, and provide the result as input to

      other Mechanisms in the Composition, or as the output for the Composition itself.  There are a variety of

      different types of ProcessingMechanism, that accept various forms of input and transform them in different ways

      (see `ProcessingMechanisms <ProcessingMechanism>` for a list).

      to modulate the parameters of other Mechanisms or Projections.  There are three basic ModulatoryMechanisms:

      * `LearningMechanism <LearningMechanism>` - these receive training (target) values, and compare them with the

        output of a Mechanism to generate `LearningSignals <LearningSignal>` that are used to modify `MappingProjections

        <MappingProjection>` (see `learning <Process_Execution_Learning>`).

      * `ControlMechanism <ControlMechanism>` - these evaluate the output of a specified set of Mechanisms, and

        generate `ControlSignals <ControlSignal>` used to modify the parameters of those or other Mechanisms.

      * `GatingMechanism <GatingMechanism>` - these use their input(s) to determine whether and how to modify the

        `value <Port_Base.value>` of the `InputPort(s) <InputPort>` and/or `OutputPort(s) <OutputPort>` of other

        Mechanisms.

      Each type of ModulatoryMechanism is associated with a corresponding type of `ModulatorySignal <ModulatorySignal>`

      (a type of `OutputPort` specialized for use with the ModulatoryMechanism) and `ModulatoryProjection

      <ModulatoryProjection>`.

Every Mechanism is made up of four fundamental components:

    * `InputPort(s) <InputPort>` used to receive and represent its input(s);

    * `Function <Function>` used to transform its input(s) into its output(s);

    * `ParameterPort(s) <ParameterPort>` used to represent the parameters of its Function (and/or any

      parameters that are specific to the Mechanism itself);

    * `OutputPort(s) <OutputPort>` used to represent its output(s)

These are described in the sections on `Mechanism_Function` and `Mechanism_Ports` (`Mechanism_InputPorts`,

`Mechanism_ParameterPorts`, and `Mechanism_OutputPorts`), and shown graphically in a `figure <Mechanism_Figure>`,

under `Mechanism_Structure` below.

.. _Mechanism_Creation:

Creating a Mechanism

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

Mechanisms are created by calling the constructor for a particular type.  PsyNeuLink also automatically

creates one or more Mechanisms under some circumstances. For example, a `ComparatorMechanism` and `LearningMechanism

<LearningMechanism>` are created automatically when `learning is specified <Composition_Learning>` for a `Composition`;

and an `ObjectiveMechanism` may be created when a `ControlMechanism <ControlMechanism>` is created.

COMMENT:

Mechanisms can be created in several ways.  The simplest is to call the constructor for the desired type of Mechanism.

Alternatively, the `mechanism` command can be used to create a specific type of Mechanism or an instance of

`default_mechanism <Mechanism_Base.default_mechanism>`. Mechanisms can also be specified "in context," for example in

the `pathway <Composition.pathway>` attribute of a `Process`; the Mechanism can be specified in either of the ways

mentioned above, or using one of the following:

  * the name of an **existing Mechanism**;

  * the name of a **Mechanism type** (subclass);

  * a **specification dictionary** -- this can contain an entry specifying the type of Mechanism,

    and/or entries specifying the value of parameters used to instantiate it.

    These should take the following form:

      * *MECHANISM_TYPE*: <name of a Mechanism type>

          if this entry is absent, a `default_mechanism <Mechanism_Base.default_mechanism>` will be created.

      * *NAME*: <str>

          the string will be used as the `name <Mechanism_Base.name>` of the Mechanism;  if this entry is absent,

          the name will be the name of the Mechanism's type, suffixed with an index if there are any others of the

          same type for which a default name has been assigned.

      * <name of parameter>:<value>

          this can contain any of the `standard parameters <Mechanism_Additional_Attributes>` for instantiating a

          Mechanism or ones specific to a particular type of Mechanism (see documentation for the type).  The key must

          be the name of the argument used to specify the parameter in the Mechanism's constructor, and the value must

          be a legal value for that parameter, using any of the ways allowed for `specifying a parameter

          <ParameterPort_Specification>`. The parameter values specified will be used to instantiate the Mechanism.

          These can be overridden during execution by specifying `Mechanism_Runtime_Params`, either when calling

          the Mechanism's `execute <Mechanism_Base.execute>` method, or in the `execution method

          <Composition_Execution_Methods>` of a Composition.

  * **automatically** -- PsyNeuLink automatically creates one or more Mechanisms under some circumstances. For example,

    a `ComparatorMechanism` and `LearningMechanism <LearningMechanism>` are created automatically when `learning is

    specified <Composition_Learning>` for a Composition; and an `ObjectiveMechanism` may be created when a

    `ControlMechanism <ControlMechanism>` is created.

COMMENT

.. _Mechanism_Port_Specification:

*Specifying Ports*

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

Every Mechanism has one or more `InputPorts <InputPort>`, `ParameterPorts <ParameterPort>`, and `OutputPorts

<OutputPort>` (described `below <Mechanism_Ports>`) that allow it to receive and send `Projections <Projection>`,

and to execute its `function <Mechanism_Base.function>`).  When a Mechanism is created, it automatically creates the

ParameterPorts it needs to represent its parameters, including those of its `function <Mechanism_Base.function>`.

It also creates any InputPorts and OutputPorts required for the Projections it has been assigned. InputPorts and

OutputPorts, and corresponding Projections (including those from `ModulatorySignals <ModulatorySignal>`) can also be

specified explicitly in the **input_ports** and **output_ports** arguments of the Mechanism's constructor (see

`Mechanism_InputPorts` and `Mechanism_OutputPorts`, respectively, as well as the `first example <Mechanism_Example_1>`

below, and `Port_Examples`).  They can also be specified in a `parameter specification dictionary

<ParameterPort_Specification>` assigned to the Mechanism's **params** argument, using entries with the keys

*INPUT_PORTS* and *OUTPUT_PORTS*, respectively (see `second example <Mechanism_Example_2>` below).  While

specifying the **input_ports** and **output_ports** arguments directly is simpler and more convenient,

the dictionary format allows parameter sets to be created elsewhere and/or re-used.  The value of each entry can be

any of the allowable forms for `specifying a port <Port_Specification>`. InputPorts and OutputPorts can also be

added to an existing Mechanism using its `add_ports <Mechanism_Base.add_ports>` method, although this is generally

not needed and can have consequences that must be considered (e.g., see `note <Mechanism_Add_InputPorts_Note>`),

and therefore is not recommended.

.. _Mechanism_Default_Port_Suppression_Note:

    .. note::

       When Ports are specified in the **input_ports** or **output_ports** arguments of a Mechanism's constructor,

       they replace any default Ports generated by the Mechanism when it is created (if no Ports were specified).

       This is particularly relevant for OutputPorts, as most Mechanisms create one or more `Standard OutputPorts

       <OutputPort_Standard>` by default, that have useful properties.  To retain those Ports if any are specified in

       the **output_ports** argument, they must be included along with those ports in the **output_ports** argument

       (see `examples <Port_Standard_OutputPorts_Example>`).  The same is true for default InputPorts and the

       **input_ports** argument.

       This behavior differs from adding a Port once the Mechanism is created.  Ports added to Mechanism using the

       Mechanism's `add_ports <Mechanism_Base.add_ports>` method, or by assigning the Mechanism in the **owner**

       argument of the Port's constructor, are added to the Mechanism without replacing any of its existing Ports,

       including any default Ports that may have been generated when the Mechanism was created (see `examples

       <Port_Create_Port_Examples>` in Port).

Examples

^^^^^^^^

.. _Mechanism_Example_1:

The following example creates an instance of a TransferMechanism that names the default InputPort ``MY_INPUT``,

and assigns three `Standard OutputPorts <OutputPort_Standard>`::

    >>> import psyneulink as pnl

    >>> my_mech = pnl.TransferMechanism(input_ports=['MY_INPUT'],

    ...                                 output_ports=[pnl.RESULT, pnl.MEAN, pnl.VARIANCE])

.. _Mechanism_Example_2:

This shows how the same Mechanism can be specified using a dictionary assigned to the **params** argument::

     >>> my_mech = pnl.TransferMechanism(params={pnl.INPUT_PORTS: ['MY_INPUT'],

     ...                                         pnl.OUTPUT_PORTS: [pnl.RESULT, pnl.MEAN, pnl.VARIANCE]})

See `Port <Port_Examples>` for additional examples of specifying the Ports of a Mechanism.

.. _Mechanism_Parameter_Specification:

*Specifying Parameters*

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

As described `below <Mechanism_ParameterPorts>`, Mechanisms have `ParameterPorts <ParameterPort>` that provide the

current value of a parameter used by the Mechanism and/or its `function <Mechanism_Base.function>` when it is `executed

<Mechanism_Execution>`. These can also be used by a `ControlMechanism <ControlMechanism>` to control the parameters of

the Mechanism and/or it `function <Mechanism_Base.function>`.  The value of any of these, and their control, can be

specified in the corresponding argument of the constructor for the Mechanism and/or its `function

<Mechanism_Base.function>`,  or in a parameter specification dictionary assigned to the **params** argument of its

constructor, as described under `ParameterPort_Specification`.

.. _Mechanism_Structure:

Structure

---------

.. _Mechanism_Function:

*Function*

~~~~~~~~~~

The core of every Mechanism is its function, which transforms its input to generate its output.  The function is

specified by the Mechanism's `function <Mechanism_Base.function>` attribute.  Every type of Mechanism has at least one

(primary) function, and some have additional (auxiliary) ones (for example, `TransferMechanism` and

`EVCControlMechanism`). Mechanism functions are generally from the PsyNeuLink `Function` class.  Most Mechanisms

allow their function to be specified, using the `function` argument of the Mechanism's constructor.  The function can

be specified using the name of `Function <Function>` class, or its constructor (including arguments that specify its

parameters).  For example, the `function <Mechanism_Base.function>` of a `TransferMechanism`, which is `Linear` by

default, can be specified to be the `Logistic` function as follows::

    >>> my_mechanism = pnl.TransferMechanism(function=pnl.Logistic(gain=1.0, bias=-4))

Notice that the parameters of the :keyword:`function` (in this case, `gain` and `bias`) can be specified by including

them in its constructor.  Some Mechanisms support only a single function.  In that case, the :keyword:`function`

argument is not available in the Mechanism's constructor, but it does include arguments for the function's

parameters.  For example, the :keyword:`function` of a `ComparatorMechanism` is always the `LinearCombination` function,

so the Mechanisms' constructor does not have a :keyword:`function` argument.  However, it does have a

**comparison_operation** argument, that is used to set the LinearCombination function's `operation` parameter.

The parameters for a Mechanism's primary function can also be specified as entries in a *FUNCTION_PARAMS* entry of a

`parameter specification dictionary <ParameterPort_Specification>` in the **params** argument of the Mechanism's

constructor.  For example, the parameters of the `Logistic` function in the example above can

also be assigned as follows::

    >>> my_mechanism = pnl.TransferMechanism(function=pnl.Logistic,

    ...                                      params={pnl.FUNCTION_PARAMS: {pnl.GAIN: 1.0, pnl.BIAS: -4.0}})

Again, while not as simple as specifying these as arguments in the function's constructor, this format is more flexible.

Any values specified in the parameter dictionary will **override** any specified within the constructor for the function

itself (see `DDM <DDM_Creation>` for an example).

COMMENT:

.. _Mechanism_Function_Attribute:

`function <Mechanism_Base.function>` *attribute*

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

The `Function <Function>` assigned as the primary function of a Mechanism is assigned to the Mechanism's

`function <Component.function>` attribute, and its `function <Function_Base.function>` is assigned

to the Mechanism's `function <Mechanism_Base.function>` attribute.

COMMENT

.. note::

   It is important to recognize the distinction between a `Function <Function>` and its `function

   <Function_Base.function>` attribute (note the difference in capitalization).  A *Function* is a PsyNeuLink `Component

   <Component>`, that can be created using a constructor; a *function* is an attribute that contains a callable method

   belonging to a Function, and that is executed when the Component to which the Function belongs is executed.

   Functions are used to assign, store, and apply parameter values associated with their function (see `Function

   <Function_Overview>` for a more detailed explanation).

The parameters of a Mechanism's `function <Mechanism_Base.function>` are attributes of its `function

<Component.function>`, and can be accessed using standard "dot" notation for that object.  For

example, the `gain <Logistic.gain>` and `bias <Logistic.bias>` parameters of the `Logistic` function in the example

above can be access as ``my_mechanism.function.gain`` and ``my_mechanism.function.bias``.  They are

also assigned to a dictionary in the Mechanism's `function_params <Mechanism_Base.function_params>` attribute,

and can be  accessed using the parameter's name as the key for its entry in the dictionary.  For example,

the parameters in the  example above could also be accessed as ``my_mechanism.function_params[GAIN]`` and

``my_mechanism.function_params[GAIN]``

Some Mechanisms have auxiliary functions that are inherent (i.e., not made available as arguments in the Mechanism's

constructor;  e.g., the `integrator_function <TransferMechanism.integrator_function>` of a `TransferMechanism`);

however, the Mechanism may include parameters for those functions in its constructor (e.g., the **noise** argument in

the constructor for a `TransferMechanism` is used as the `noise <AdaptiveIntegrator.noise>` parameter of the

`AdaptiveIntegrator` assigned to the TransferMechanism's `integrator_function <TransferMechanism.integrator_function>`).

COMMENT:

NOT CURRENTLY IMPLEMENTED

For Mechanisms that offer a selection of functions for the primary function (such as the `TransferMechanism`), if all

of the functions use the same parameters, then those parameters can also be specified as entries in a `parameter

specification dictionary <ParameterPort_Specification>` as described above;  however, any parameters that are unique

to a particular function must be specified in a constructor for that function.  For Mechanisms that have additional,

auxiliary functions, those must be specified in arguments for them in the Mechanism's constructor, and their parameters

must be specified in constructors for those functions unless documented otherwise.

COMMENT

COMMENT:

    FOR DEVELOPERS:

    + FUNCTION : function or method :  method used to transform Mechanism input to its output;

        This must be implemented by the subclass, or an exception will be raised;

        each item in the variable of this method must be compatible with a corresponding InputPort;

        each item in the output of this method must be compatible  with the corresponding OutputPort;

        for any parameter of the method that has been assigned a ParameterPort,

        the output of the ParameterPort's own execute method must be compatible with

        the value of the parameter with the same name in params[FUNCTION_PARAMS] (EMP)

    + FUNCTION_PARAMS (dict):

        NOTE: function parameters can be specified either as arguments in the Mechanism's __init__ method,

        or by assignment of the function_params attribute.

        Only one of these methods should be used, and should be chosen using the following principle:

        - if the Mechanism implements one function, then its parameters should be provided as arguments in the __init__

        - if the Mechanism implements several possible functions and they do not ALL share the SAME parameters,

            then the function should be provided as an argument but not they parameters; they should be specified

            as arguments in the specification of the function

        each parameter is instantiated as a ParameterPort

        that will be placed in <Mechanism_Base>._parameter_ports;  each parameter is also referenced in

        the <Mechanism>.function_params dict, and assigned its own attribute (<Mechanism>.<param>).

COMMENT

.. _Mechanism_Custom_Function:

Custom Functions

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

A Mechanism's `function <Mechanism_Base.function>` can be customized by assigning a user-defined function (e.g.,

a lambda function), so long as it takes arguments and returns values that are compatible with those of the

Mechanism's defaults for that function.  This is also true for auxiliary functions that appear as arguments in a

Mechanism's constructor (e.g., the `EVCControlMechanism`).  A user-defined function can be assigned

directly to the corresponding attribute of the Mechanism

(for its primary function, its `function <Mechanism_Base.function>` attribute). When a user-defined function is

specified, it is automatically converted to a `UserDefinedFunction`.

.. note::

   It is *strongly advised* that auxiliary functions that are inherent to a Mechanism

   (i.e., ones that do *not* appear as an argument in the Mechanism's constructor,

   such as the `integrator_function <TransferMechanism.integrator_function>` of a

   `TransferMechanism`) *not* be assigned custom functions;  this is because their

   parameters are included as arguments in the constructor for the Mechanism,

   and thus changing the function could produce confusing and/or unpredictable effects.

COMMENT:

    When a custom function is specified,

    the function itself is assigned to the Mechanism's designated attribute.  At the same time, PsyNeuLink automatically

    creates a `UserDefinedFunction` object, and assigns the custom function to its

    `function <UserDefinedFunction.function>` attribute.

COMMENT

.. _Mechanism_Variable_and_Value:

`variable <Mechanism_Base.variable>` *and* `value <Mechanism_Base.value>` *attributes*

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

The input to a Mechanism's `function <Mechanism_Base.function>` is provided by the Mechanism's `variable

<Mechanism_Base.variable>` attribute.  This is an ndarray that is at least 2d, with one item of its outermost

dimension (axis 0) for each of the Mechanism's `input_ports <Mechanism_Base.input_ports>` (see

`below <Mechanism_InputPorts>`).  The result of the  `function <Mechanism_Base.function>` is placed in the

Mechanism's `value <Mechanism_Base.value>` attribute which is  also at least a 2d array.  The Mechanism's `value

<Mechanism_Base.value>` is referenced by its `OutputPorts <Mechanism_OutputPorts>` to generate their own `value

<OutputPort.value>` attributes, each of which is assigned as the value of an item of the list in the Mechanism's

`output_values <Mechanism_Base.output_values>` attribute (see `Mechanism_OutputPorts` below), which is the value

returned by a call to the Mechanism's `execute <Mechanism_Base.execute>` method.

.. note::

   The input to a Mechanism is not necessarily the same as the input to its `function <Mechanism_Base.function>`. The

   input to a Mechanism is first processed by its `InputPort(s) <Mechanism_InputPorts>`, and then assigned to the

   Mechanism's `variable <Mechanism_Base.variable>` attribute, which is used as the input to its `function

   <Mechanism_Base.function>`. Similarly, the result of a Mechanism's function is not necessarily the same as the

   Mechanism's output.  The result of the `function <Mechanism_Base.function>` is assigned to the Mechanism's  `value

   <Mechanism_Base.value>` attribute, which is then used by its `OutputPort(s) <Mechanism_OutputPorts>` to assign

   items to its `output_values <Mechanism_Base.output_values>` attribute.

.. _Mechanism_Ports:

*Ports*

~~~~~~~~

Every Mechanism has one or more of each of three types of Ports:  `InputPort(s) <InputPort>`,

`ParameterPort(s) <ParameterPort>`, `and OutputPort(s) <OutputPort>`.  Generally, these are created automatically

when the Mechanism is created.  InputPorts and OutputPorts (but not ParameterPorts) can also be specified explicitly

for a Mechanism, or added to an existing Mechanism using its `add_ports <Mechanism_Base.add_ports>` method, as

described `above <Mechanism_Port_Specification>`).

.. _Mechanism_Figure:

The three types of Ports are shown schematically in the figure below, and described briefly in the following sections.

.. figure:: _static/Mechanism_Ports_fig.svg

   :alt: Mechanism Ports

   :align: left

   **Schematic of a Mechanism showing its three types of Ports** (`InputPort`, `ParameterPort` and `OutputPort`).

   Every Mechanism has at least one (`primary <InputPort_Primary>`) InputPort and one (`primary

   <OutputPort_Primary>`) OutputPort, but can have additional ports of each type.  It also has one

   `ParameterPort` for each of its parameters and the parameters of its `function <Mechanism_Base.function>`.

   The `value <InputPort.value>` of each InputPort is assigned as an item of the Mechanism's `variable

   <Mechanism_Base.variable>`, and the result of its `function <Mechanism_Base.function>` is assigned as the Mechanism's

   `value <Mechanism_Base.value>`, the items of which are referenced by its OutputPorts to determine their own

   `value <OutputPort.value>`\\s (see `Mechanism_Variable_and_Value` above, and more detailed descriptions below).

.. _Mechanism_InputPorts:

InputPorts

^^^^^^^^^^^

These receive, potentially combine, and represent the input to a Mechanism, and provide this to the Mechanism's

`function <Mechanism_Base.function>`. Usually, a Mechanism has only one (`primary <InputPort_Primary>`) `InputPort`,

identified in its `input_port <Mechanism_Base.input_port>` attribute. However some Mechanisms have more than one

InputPort. For example, a `ComparatorMechanism` has one InputPort for its **SAMPLE** and another for its **TARGET**

input. All of the Mechanism's InputPorts (including its primary InputPort <InputPort_Primary>` are listed in its

`input_ports <Mechanism_Base.input_ports>` attribute (note the plural).

.. technical_note::

   The `input_ports <Mechanism_Base.input_ports>` attribute is a ContentAddressableList

   -- a PsyNeuLink-defined subclass of the Python class `UserList

   <https://docs.python.org/3.6/library/collections.html?highlight=userlist#collections.UserList>`_ --

   that allows a specific InputPort in the list to be accessed using its name as the index for the list

   (e.g., ``my_mechanism['InputPort name']``).

.. _Mechanism_Variable_and_InputPorts:

The `value <InputPort.value>` of each InputPort for a Mechanism is assigned to a different item of the Mechanism's

`variable <Mechanism_Base.variable>` attribute (a 2d np.array), as well as to a corresponding item of its `input_values

<Mechanism_Base.input_values>` attribute (a list).  The `variable <Mechanism_Base.variable>` provides the input to the

Mechanism's `function <Mechanism_Base.function>`, while its `input_values <Mechanism_Base.input_values>` provides a

convenient way of accessing the value of its individual items.  Because there is a one-to-one correspondence between

a Mechanism's InputPorts and the items of its `variable <Mechanism_Base.variable>`, their size along their outermost

dimension (axis 0) must be equal; that is, the number of items in the Mechanism's `variable <Mechanism_Base.variable>`

attribute must equal the number of InputPorts in its `input_ports <Mechanism_Base.input_ports>` attribute. A

Mechanism's constructor does its best to insure this:  if its **default_variable** and/or its **input_shapes** argument is

specified, it constructs a number of InputPorts (and each with a `value <InputPort.value>`) corresponding to the

items specified for the Mechanism's `variable <Mechanism_Base.variable>`, as in the examples below::

    my_mech_A = pnl.TransferMechanism(default_variable=[[0],[0,0]])

    print(my_mech_A.input_ports)

    > [(InputPort InputPort-0), (InputPort InputPort-1)]

    print(my_mech_A.input_ports[0].value)

    > [ 0.]

    print(my_mech_A.input_ports[1].value)

    > [ 0.  0.]

    my_mech_B = pnl.TransferMechanism(default_variable=[[0],[0],[0]])

    print(my_mech_B.input_ports)

    > [(InputPort InputPort-0), (InputPort InputPort-1), (InputPort InputPort-2)]

Conversely, if the **input_ports** argument is used to specify InputPorts for the Mechanism, they are used to format

the Mechanism's variable::

    my_mech_C = pnl.TransferMechanism(input_ports=[[0,0], 'Hello'])

    print(my_mech_C.input_ports)

    > [(InputPort InputPort-0), (InputPort Hello)]

    print(my_mech_C.variable)

    > [array([0, 0]) array([0])]

If both the **default_variable** (or **input_shapes**) and **input_ports** arguments are specified, then the number and format

of their respective items must be the same (see `Port <Port_Examples>` for additional examples of specifying Ports).

If InputPorts are added using the Mechanism's `add_ports <Mechanism_Base.add_ports>` method, then its

`variable <Mechanism_Base.variable>` is extended to accommodate the number of InputPorts added (note that this must

be coordinated with the Mechanism's `function <Mechanism_Base.function>`, which takes the Mechanism's `variable

<Mechanism_Base.variable>` as its input (see `note <Mechanism_Add_InputPorts_Note>`).

The order in which `InputPorts are specified <Mechanism_InputPort_Specification>` in the Mechanism's constructor,

and/or `added <Mechanism_Add_InputPorts>` using its `add_ports <Mechanism_Base.add_ports>` method,  determines the

order of the items to which they are assigned assigned in he Mechanism's `variable  <Mechanism_Base.variable>`,

and are listed in its `input_ports <Mechanism_Base.input_ports>` and `input_values <Mechanism_Base.input_values>`

attribute.  Note that a Mechanism's `input_values <Mechanism_Base.input_values>` attribute has the same information as

the Mechanism's `variable <Mechanism_Base.variable>`, but in the form of a list rather than an ndarray.

.. _Mechanism_InputPort_Specification:

**Specifying InputPorts and a Mechanism's** `variable <Mechanism_Base.variable>` **Attribute**

When a Mechanism is created, the number and format of the items in its `variable <Mechanism_Base.variable>`

attribute, as well as the number of InputPorts it has and their `variable <InputPort.variable>` and `value

<InputPort.value>` attributes, are determined by one of the following arguments in the Mechanism's constructor:

* **default_variable** (at least 2d ndarray) -- determines the number and format of the items of the Mechanism's

  `variable <Mechanism_Base.variable>` attribute.  The number of items in its outermost dimension (axis 0) determines

  the number of InputPorts created for the Mechanism, and the format of each item determines the format for the

  `variable <InputPort.variable>` and `value  <InputPort.value>` attributes of the corresponding InputPort.

  If any InputPorts are specified in the **input_ports** argument or an *INPUT_PORTS* entry of

  a specification dictionary assigned to the **params** argument of the Mechanism's constructor, then the number

  must match the number of items in **default_variable**, or an error is generated.  The format of the items in

  **default_variable** are used to specify the format of the `variable <InputPort.variable>` or `value

  <InputPort.value>` of the corresponding InputPorts for any that are not explicitly specified in the

  **input_ports** argument or *INPUT_PORTS* entry (see below).

..

* **input_shapes** (int, list or ndarray) -- specifies the number and length of items in the Mechanism's variable,

  if **default_variable** is not specified. For example, the following mechanisms are equivalent::

    T1 = TransferMechanism(input_shapes = [3, 2])

    T2 = TransferMechanism(default_variable = [[0, 0, 0], [0, 0]])

  The relationship to any specifications in the **input_ports** argument or

  *INPUT_PORTS* entry of a **params** dictionary is the same as for the **default_variable** argument,

  with the latter taking precedence (see above).

..

* **input_ports** (list) -- this can be used to explicitly `specify the InputPorts <InputPort_Specification>`

  created for the Mechanism. Each item must be an `InputPort specification <InputPort_Specification>`, and the number

  of items must match the number of items in the **default_variable** argument or **input_shapes** argument

  if either of those is specified.  If the `variable <InputPort.variable>` and/or `value <InputPort.value>`

  is `explicitly specified for an InputPort <InputPort_Variable_and_Value>` in the **input_ports** argument or

  *INPUT_PORTS* entry of a **params** dictionary, it must be compatible with the value of the corresponding

  item of **default_variable**; otherwise, the format of the item in **default_variable** corresponding to the

  InputPort is used to specify the format of the InputPort's `variable <InputPort.variable>` (e.g., the InputPort is

  `specified using an OutputPort <InputPort_Projection_Source_Specification>` to project to it;).  If

  **default_variable** is not specified, a default value is specified by the Mechanism.  InputPorts can also be

  specifed that `shadow the inputs <InputPort_Shadow_Inputs>` of other InputPorts and/or Mechanisms; that is, receive

  Projections from all of the same `senders <Projection_Base.sender>` as those specified.

COMMENT:

    *** ADD SOME EXAMPLES HERE (see `examples <XXX>`)

COMMENT

COMMENT:

    *** ADD THESE TO ABOVE WHEN IMPLEMENTED:

        If more InputPorts are specified than there are items in `variable <Mechanism_Base.variable>,

            the latter is extended to  match the former.

        If the Mechanism's `variable <Mechanism_Base.variable>` has more than one item, it may still be assigned

            a single InputPort;  in that case, the `value <InputPort.value>` of that InputPort must have the same

            number of items as the Mechanisms's `variable <Mechanism_Base.variable>`.

COMMENT

..

* *INPUT_PORTS* entry of a params dict (list) -- specifications are treated in the same manner as those in the

  **input_ports** argument, and take precedence over those.

.. _Mechanism_Add_InputPorts:

**Adding InputPorts**

InputPorts can be added to a Mechanism using its `add_ports <Mechanism_Base.add_ports>` method;  this extends its

`variable <Mechanism_Base.variable>` by a number of items equal to the number of InputPorts added, and each new item

is assigned a format compatible with the `value <InputPort.value>` of the corresponding InputPort added;  if the

InputPort's `variable <InputPort.variable>` is not specified, it is assigned the default format for an item of the

owner's `variable <Mechanism_Base.variable>` attribute. The InputPorts are appended to the end of the list in the

Mechanism's `input_ports <Mechanism_Base.input_ports>` attribute.  Adding in Ports in this manner does **not**

replace any existing Ports, including any default Ports generated when the Mechanism was constructed (this is

contrast to Ports specified in a Mechanism's constructor which **do** `replace any default Port(s) of the same type

<Mechanism_Default_Port_Suppression_Note>`).

.. _Mechanism_Add_InputPorts_Note:

.. note::

    Adding InputPorts to a Mechanism using its `add_ports <Mechanism_Base.add_ports>` method may introduce an

    incompatibility with the Mechanism's `function <Mechanism_Base.function>`, which takes the Mechanism's `variable

    <Mechanism_Base.variable>` as its input; such an incompatibility will generate an error.  It may also influence

    the number of OutputPorts created for the Mechanism. It is the user's responsibility to ensure that the

    assignment of InputPorts to a Mechanism using the `add_ports <Mechanism_Base.add_ports>` is coordinated with

    the specification of its `function <Mechanism_Base.function>`, so that the total number of InputPorts (listed

    in the Mechanism's `input_ports <Mechanism_Base.input_ports>` attribute matches the number of items expected

    for the input to the function specified in the Mechanism's `function <Mechanism_Base.function>` attribute

    (i.e., its length along axis 0).

.. _Mechanism_InputPort_Projections:

**Projections to InputPorts**

Each InputPort of a Mechanism can receive one or more `Projections <Projection>` from other Mechanisms.  When a

Mechanism is created, a `MappingProjection` is created automatically for any OutputPorts or Projections from them that

are in its `InputPort specification <InputPort_Specification>`, using `AUTO_ASSIGN_MATRIX` as the Projection's `matrix

specification <MappingProjection_Matrix_Specification>`.  However, if a specification in the **input_ports** argument

or an *INPUT_PORTS* entry of a **params** dictionary cannot be resolved to an instantiated OutputPort at the time the

Mechanism is created, no MappingProjection is assigned to the InputPort, and this must be done by some other means;

any specifications in the Mechanism's `input_ports <Mechanism_Base.input_ports>` attribute that are not

associated with an instantiated OutputPort at the time the Mechanism is executed are ignored.

The `PathwayProjections <PathwayProjection>` (e.g., `MappingProjections <MappingProjection>`) it receives are listed

in its `path_afferents <Port_Base.path_afferents>` attribute.  If the Mechanism is an `ORIGIN` Mechanism of a

`Composition`, this includes a Projection from the Composition's `input_CIM <Composition.input_CIM>`.  Any

`ControlProjections <ControlProjection>` or `GatingProjections <GatingProjection>` it receives are listed in its

`mod_afferents <Port.mod_afferents>` attribute.

.. _Mechanism_ParameterPorts:

*ParameterPorts and Parameters*

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

`ParameterPorts <ParameterPort>` provide the value for each parameter of a Mechanism and its `function

<Mechanism_Base.function>`.  One ParameterPort is assigned to each of the parameters of the Mechanism and/or its

`function <Mechanism_Base.function>` (corresponding to the arguments in their constructors). The ParameterPort takes

the value specified for a parameter (see `below <Mechanism_Parameter_Value_Specification>`) as its `variable

<ParameterPort.variable>`, and uses it as the input to the ParameterPort's `function <ParameterPort.function>`,

which `modulates <ModulatorySignal_Modulation>` it in response to any `ControlProjections <ControlProjection>` received

by the ParameterPort (specified in its `mod_afferents <ParameterPort.mod_afferents>` attribute), and assigns the

result to the ParameterPort's `value <ParameterPort.value>`.  This is the value used by the Mechanism or its

`function <Mechanism_Base.function>` when the Mechanism `executes <Mechanism_Execution>`.  Accordingly, when the value

of a parameter is accessed (e.g., using "dot" notation, such as ``my_mech.my_param``), it is actually the

*ParameterPort's* `value <ParameterPort.value>` that is returned (thereby accurately reflecting the value used

during the last execution of the Mechanism or its `function <Mechanism_Base.function>`).  The ParameterPorts for a

Mechanism are listed in its `parameter_ports <Mechanism_Base.parameter_ports>` attribute.

.. _Mechanism_Parameter_Value_Specification:

The "base" value of a parameter (i.e., the unmodulated value used as the ParameterPort's `variable

<ParameterPort.variable>` and the input to its `function <ParameterPort.function>`) can specified when a Mechanism

and/or its `function <Mechanism_Base.function>` are first created,  using the corresponding arguments of their

constructors (see `Mechanism_Function` above).  Parameter values can also be specified later, by direct assignment of a

value to the attribute for the parameter, or by using the Mechanism's `assign_param` method (the recommended means;

see `ParameterPort_Specification`).  Note that the attributes for the parameters of a Mechanism's `function

<Mechanism_Base.function>` usually belong to the `Function <Function_Overview>` referenced in its `function

<Component.function>` attribute, not the Mechanism itself, and therefore must be assigned to the Function

Component (see `Mechanism_Function` above).

.. _Mechanism_OutputPorts:

OutputPorts

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

These represent the output(s) of a Mechanism. A Mechanism can have several `OutputPorts <OutputPort>`, and each can

send Projections that transmit its value to other Mechanisms and/or as the output of the `Composition` to which

the Mechanism belongs.  Every Mechanism has at least one OutputPort, referred to as its `primary OutputPort

<OutputPort_Primary>`.  If OutputPorts are not explicitly specified for a Mechanism, a primary OutputPort is

automatically created and assigned to its `output_port <Mechanism_Base.output_port>` attribute (note the singular),

and also to the first entry of the Mechanism's `output_ports <Mechanism_Base.output_ports>` attribute (note the

plural).  The `value <OutputPort.value>` of the primary OutputPort is assigned as the first (and often only) item

of the Mechanism's `value <Mechanism_Base.value>` attribute, which is the result of the Mechanism's `function

<Mechanism_Base.function>`.  Additional OutputPorts can be assigned to represent values corresponding to other items

of the Mechanism's `value <Mechanism_Base.value>` (if there are any) and/or values derived from any or all of those

items. `Standard OutputPorts <OutputPort_Standard>` are available for each type of Mechanism, and custom ones can

be configured (see `OutputPort Specification <OutputPort_Specification>`. These can be assigned in the

**output_ports** argument of the Mechanism's constructor.

All of a Mechanism's OutputPorts (including the primary one) are listed in its `output_ports

<Mechanism_Base.output_ports>` attribute (note the plural). The `output_ports <Mechanism_Base.output_ports>`

attribute is a ContentAddressableList -- a PsyNeuLink-defined subclass of the Python class

`UserList <https://docs.python.org/3.6/library/collections.html?highlight=userlist#collections.UserList>`_ -- that

allows a specific OutputPort in the list to be accessed using its name as the index for the list (e.g.,

``my_mechanism['OutputPort name']``).  This list can also be used to assign additional OutputPorts to the Mechanism

after it has been created.

The `value <OutputPort.value>` of each of the Mechanism's OutputPorts is assigned as an item in the Mechanism's

`output_values <Mechanism_Base.output_values>` attribute, in the same order in which they are listed in its

`output_ports <Mechanism_Base.output_ports>` attribute.  Note, that the `output_values <Mechanism_Base.output_values>`

attribute of a Mechanism is distinct from its `value <Mechanism_Base.value>` attribute, which contains the full and

unmodified results of its `function <Mechanism_Base.function>` (this is because OutputPorts can modify the item of

the Mechanism`s `value <Mechanism_Base.value>` to which they refer -- see `OutputPorts <OutputPort_Customization>`).

.. _Mechanism_Additional_Attributes:

*Additional Attributes*

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

.. _Mechanism_Constructor_Arguments:

*Additional Constructor Arguments*

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

In addition to the `standard attributes <Component_Structure>` of any `Component <Component>`, Mechanisms have a set of

Mechanism-specific attributes (listed below). These can be specified in arguments of the Mechanism's constructor,

in a `parameter specification dictionary <ParameterPort_Specification>` assigned to the **params** argument of the

Mechanism's constructor, by direct reference to the corresponding attribute of the Mechanisms after it has been

constructed (e.g., ``my_mechanism.param``). The Mechanism-specific

attributes are listed below by their argument names / keywords, along with a description of how they are specified:

    * **input_ports** / *INPUT_PORTS* - a list specifying the Mechanism's input_ports

      (see `InputPort_Specification` for details of specification).

    ..

    * **input_labels** / *INPUT_LABEL_DICTS* - a dict specifying labels that can be used as inputs

      (see `Mechanism_Labels_Dicts` for details of specification).

    ..

    * **output_ports** / *OUTPUT_PORTS* - specifies specialized OutputPorts required by a Mechanism subclass

      (see `OutputPort_Specification` for details of specification).

    ..

    * **output_labels** / *OUTPUT_LABEL_DICTS* - a dict specifying labels that can be for reporting outputs

      (see `Mechanism_Labels_Dicts` for details of specification).

    ..

    COMMENT:

    * **monitor_for_control** / *MONITOR_FOR_CONTROL* - specifies which of the Mechanism's OutputPorts is monitored by

      the `controller` for the Composition to which the Mechanism belongs (see `specifying monitored OutputPorts

      <ObjectiveMechanism_Monitor>` for details of specification).

    COMMENT

    ..

    * **monitor_for_learning** / *MONITOR_FOR_LEARNING* - specifies which of the Mechanism's OutputPorts is used for

      learning (see `Learning <LearningMechanism_Activation_Output>` for details of specification).

.. _Mechanism_Convenience_Properties:

*Projection Convenience Properties*

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

A Mechanism also has several convenience properties, listed below, that list its `Projections <Projection>` and the

Mechanisms that send/receive these:

    * `projections <Mechanism_Base.projections>` -- all of the Projections sent or received by the Mechanism;

    * `afferents <Mechanism_Base.afferents>` -- all of the Projections received by the Mechanism;

    * `path_afferents <Mechanism_Base.afferents>` -- all of the PathwayProjections received by the Mechanism;

    * `mod_afferents <Mechanism_Base.afferents>` -- all of the ModulatoryProjections received by the Mechanism;

    * `efferents <Mechanism_Base.efferents>` -- all of the Projections sent by the Mechanism;

    * `senders <Mechanism_Base.senders>` -- all of the Mechanisms that send a Projection to the Mechanism

    * `modulators <Mechanism_Base.modulators>` -- all of the ModulatoryMechanisms that send a ModulatoryProjection to

      the Mechanism

    * `receivers <Mechanism_Base.receivers>` -- all of the Mechanisms that receive a Projection from the Mechanism

Each of these is a `ContentAddressableList`, which means that the names of the Components in each list can be listed by

appending ``.names`` to the property.  For examples, the names of all of the Mechanisms that receive a Projection from

``my_mech`` can be accessed by ``my_mech.receivers.names``.

.. _Mechanism_Labels_Dicts:

*Value Label Dictionaries*

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

*Overview*

Mechanisms have two attributes that can be used to specify labels for the values of its InputPort(s) and

OutputPort(s):

    * *INPUT_LABELS_DICT* -- used to specify labels for values of the InputPort(s) of the Mechanism;  if specified,

      the dictionary is contained in the Mechanism's `input_labels_dict <Mechanism_Base.input_labels_dict>` attribute.

    * *OUTPUT_LABELS_DICT* -- used to specify labels for values of the OutputPort(s) of the Mechanism;  if specified,

      the dictionary is contained in the Mechanism's `output_labels_dict <Mechanism_Base.output_labels_dict>` attribute.

The labels specified in these dictionaries can be used to:

    - specify items in the `inputs <Composition_Execution_Inputs>` argument of the `run <Composition.run>` method of a

      `Composition`, or the `targets <Composition_Targret_Inputs>` argument of its `learn <Composition.learn>` method.

    - report the values of the InputPort(s) and OutputPort(s) of a Mechanism

    - visualize the inputs and outputs of the Composition's Mechanisms

*Specifying Label Dictionaries*

Label dictionaries can only be specified in a parameters dictionary assigned to the **params** argument of the

Mechanism's constructor, using the keywords described above.  A standard label dictionary contains key:value pairs of

the following form:

    * *<port name or index>:<sub-dictionary>* -- this is used to specify labels that are specific to individual Ports

      of the type corresponding to the dictionary;

        - *key* - either the name of a Port of that type, or its index in the list of Ports of that type (i.e,

          `input_ports <Mechanism_Base.input_ports>` or `output_ports <Mechanism_Base.output_ports>`);

        - *value* - a dictionary containing *label:value* entries to be used for that Port, where the label is a string

          and the shape of the value matches the shape of the `InputPort value <InputPort.value>` or `OutputPort

          value <OutputPort.value>` for which it is providing a *label:value* mapping.

      For example, if a Mechanism has two InputPorts, named *SAMPLE* and *TARGET*, then *INPUT_LABELS_DICT* could be

      assigned two entries, *SAMPLE*:<dict> and *TARGET*:<dict> or, correspondingly, 0:<dict> and 1:<dict>, in which

      each dictionary contains separate *label:value* entries for the *SAMPLE* and *TARGET* InputPorts.

>>> input_labels_dictionary = {pnl.SAMPLE: {"red": [0],

...                                         "green": [1]},

...                            pnl.TARGET: {"red": [0],

...                                         "green": [1]}}

In the following two cases, a shorthand notation is allowed:

    - a Mechanism has only one port of a particular type (only one InputPort or only one OutputPort)

    - only the index zero InputPort or index zero OutputPort needs labels

In these cases, a label dictionary for that type of port may simply contain the *label:value* entries described above.

The *label:value* mapping will **only** apply to the index zero port of the port type for which this option is used.

Any additional ports of that type will not have value labels. For example, if the input_labels_dictionary below were

applied to a Mechanism with multiple InputPort, only the index zero InputPort would use the labels "red" and "green".

>>> input_labels_dictionary = {"red": [0],

...                            "green": [1]}

*Using Label Dictionaries*

When using labels to specify items in the `inputs <Composition_Execution_Inputs>` arguments of the `run

<Composition.run>` method, labels may directly replace any or all of the `InputPort values <InputPort.value>` in an

input specification dictionary. Keep in mind that each label must be specified in the `input_labels_dict

<Mechanism_Base.input_labels_dict>` of the `INPUT` Mechanism to which inputs are being specified, and must map to a

value that would have been valid in that position of the input dictionary.

        >>> import psyneulink as pnl

        >>> input_labels_dict = {"red": [[1, 0, 0]],

        ...                      "green": [[0, 1, 0]],

        ...                      "blue": [[0, 0, 1]]}

        >>> M = pnl.ProcessingMechanism(default_variable=[[0, 0, 0]],

        ...                             params={pnl.INPUT_LABELS_DICT: input_labels_dict})

        >>> C = pnl.Composition(pathways=[M])

        >>> input_dictionary = {M: ['red', 'green', 'blue', 'red']}

        >>> # (equivalent to {M: [[[1, 0, 0]], [[0, 1, 0]], [[0, 0, 1]], [[1, 0, 0]]]}, which is a valid input specification)

        >>> results = C.run(inputs=input_dictionary)

The same general rules apply when using labels to specify `target values <Run_Targets>` for a pathway with learning.

With target values, however, the labels must be included in the `output_labels_dict <Mechanism_Base.output_labels_dict>`

of the Mechanism that projects to the `TARGET` Mechanism (see `TARGET Mechanisms <LearningMechanism_Targets>`), or in

other words, the last Mechanism in a `learning pathway <LearningMechanism_Multilayer_Learning>`. This is the same

Mechanism used to specify target values for a particular learning pathway in the `targets dictionary <Run_Targets>`.

        >>> input_labels_dict_M1 = {"red": [[1]],

        ...                         "green": [[0]]}

        >>> output_labels_dict_M2 = {"red": [1],

        ...                         "green": [0]}

        >>> M1 = pnl.ProcessingMechanism(params={pnl.INPUT_LABELS_DICT: input_labels_dict_M1})

        >>> M2 = pnl.ProcessingMechanism(params={pnl.OUTPUT_LABELS_DICT: output_labels_dict_M2})

        >>> C = pnl.Composition()

        >>> learning_pathway = C.add_backpropagation_learning_pathway(pathway=[M1, M2], learning_rate=0.25)

        >>> input_dictionary = {M1: ['red', 'green', 'green', 'red']}

        >>> # (equivalent to {M1: [[[1]], [[0]], [[0]], [[1]]]}, which is a valid input specification)

        >>> target_dictionary = {M2: ['red', 'green', 'green', 'red']}

        >>> # (equivalent to {M2: [[1], [0], [0], [1]]}, which is a valid target specification)

        >>> results = C.learn(inputs=input_dictionary,

        ...                   targets=target_dictionary)

Several attributes are available for viewing the labels for the current value(s) of a Mechanism's InputPort(s) and

OutputPort(s).

    - The `label <InputPort.labeled_value>` attribute of an InputPort or OutputPort returns the current label of

      its value, if one exists, and its numeric value otherwise.

    - The `labeled_input_values <Mechanism_Base.labeled_input_values>` and `labeled_output_values

      <Mechanism_Base.labeled_output_values>` attributes of a Mechanism return lists containing the labels

      corresponding to the value(s) of the InputPort(s) or OutputPort(s) of the Mechanism, respectively. If the

      current value of a Port does not have a corresponding label, then its numeric value is reported instead.

        >>> output_labels_dict = {"red": [1, 0, 0],

        ...                      "green": [0, 1, 0],

        ...                      "blue": [0, 0, 1]}

        >>> M = pnl.ProcessingMechanism(default_variable=[[0, 0, 0]],

        ...                             params={pnl.OUTPUT_LABELS_DICT: output_labels_dict})

        >>> C = pnl.Composition(pathways=[M])

        >>> input_dictionary =  {M: [[1, 0, 0]]}

        >>> results = C.run(inputs=input_dictionary)

        >>> M.labeled_output_values(C)

        ['red']

        >>> M.output_ports[0].labeled_value(C)

        'red'

Labels may be used to visualize the input and outputs of Mechanisms in a Composition with the **show_structure** option

of the Composition's `show_graph`show_graph <ShowGraph.graph>` method with the keyword **LABELS**.

        >>> C.show_graph(show_mechanism_structure=pnl.LABELS)  #doctest: +SKIP

.. note::

    A given label dictionary only applies to the Mechanism to which it belongs, and a given label only applies to its

    corresponding InputPort. For example, the label 'red', may translate to different values on different InputPorts

    of the same Mechanism, and on different Mechanisms of a Composition.

.. _Mechanism_in_Composition:

*Mechanisms in Compositions*

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

Mechanisms are most commonly used as `Nodes <Composition_Nodes>` in a `Composition's graph <Composition_Graph>`,

where they are connected to other Nodes using `Projections <Projection>`.

.. _Mechanism_Role_In_Compositions:

*Role in Compositions*

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

When a Mechanism is added to a `Composition_Addition_Methods>`, it is assigned as a `Node <Composition_Nodes>` in the

`graph <Composition_Graph>` of that Comopsition, and one or more `NodeRoles <NodeRole>` indicating the role(s) that

the Node play(s) in the Composition.  These can be listed by calling the `Comopsition's `get_roles_by_nodes

<Comopsition.get_roles_by_nodes>` with the Mechanism as its argument.  The NodeRoles assigned to a Mechanism can

be different for different Compositions.  If a Mechanism is designated as an `INPUT` Node, it receives a

`MappingProjection` to its `primary InputPort <InputPort_Primary>` from the Composition.  When the Composition is

`executed <Composition_Execution>`, that InputPort receives the input specified for the Mechanism in the `inputs

<Composition_Execution_Inputs>` argument of the Composition's `execution method <Composition_Execution_Methods>`; or,

if it is a `nested Composition <Composition_Nested>`, then the Mechanism gets its input from a Node that projects to

it from the outer Composition.  If a Mechanism is designated as an `OUTPUT` Node, its `output_values

<Mechanism_Base.output_values>` are included in the value returned by its `execution method

<Composition_Execution_Methods>` and the Composition's `results <Composition.results>` attribute.

.. _Mechanism_Execution:

Execution

---------

When a Mechanism executes, the following sequence of actions is carried out:

    - The Mechanism updates its `InputPort`\\(s) by executing the `function <InputPort.function>` of each.  The

      resulting `value <InputPort.value>`\\(s) are used to assemble the Mechanism's `variable<Mechanism_Base.variable>`.

      Each `value <InputPort.value>` is added to an outer array, such that each item of the Mechanism's `variable

      <Mechanism_Base.variable>` corresponds to an InputPort `value <InputPort.value>`.  The array is placed in

      the Mechanism's `input_values <Mechanism_Base.input_values>` attribute, and also passed as the input to the

      Mechanism's `function <Mechanism_Base.function>` after updating its `ParameterPorts <ParamterPorts>`.

    - The Mechanism updates its `ParameterPort`\\(s) by executing each of their `functions <ParameterPort.function>`,

      the results of which are assigned as the values used for the corresponding Parameters, which include those of the

      Mechanism's `function <Mechanism_Base.function>`.

    - The Mechanism's `variable <Mechanism_Base.variable>` is passed as the input to the its `function

      <Mechanism_Base.function>`, and the function is execute using the parameter values generating by the execution

      of its ParameterPorts. The result of the Mechanism's `function <Mechanism_Base.function>` is placed in the

      Mechanism's `value <Mechanism_Base.value>` attribute.

    - The Mechanism updates its `OutputPort`\\(s) are updated based on `value <Mechanism_Base.value>`, by executing the

      `function <OutputPort.function>` of each. The resulting `value <OutputPort.value>` for each Outport is placed

      in the Mechanism's `output_values <Mechanism_Base.output_values>` attribute.

A Mechanism may be executed by calling its `execute <Mechanism_Base.execute>` method directly:

    >>> my_simple_mechanism = pnl.ProcessingMechanism()      #doctest: +SKIP

    >>> my_simple_mechanism.execute(1.0)                     #doctest: +SKIP

This can be useful for testing a Mechanism and/or debugging.  However, more typically, Mechanisms are `executed as

part of a Composition <Composition_Execution>`.

.. _Mechanism_Execution_Composition:

*Execution in a Composition*

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

A Mechanism can be assigned to one or more Compositions;  the values of its `parameters <Component_Parameters>`,

including its `variable <Mechanism_Base.variable>` and `value <Mechanism_Base.value>` attributes, are maintained

separately for each `context in which it is executed <Composition_Execution_Context>` which, by default, is distinct

for each Composition in which it is executed;  these execution-specific values can be accessed using the parameter's

`get <Parameter.get>` method. A parameter's value can also be accessed using standard `dot <Parameter_Dot_Notation>`,

which returns its most recenty assigned value, irrespective of the context (including Composition) in which it was

assigned.

.. _Mechanism_Runtime_Params:

*Runtime Parameters*

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