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.

#  *********************************************  Port ********************************************************

"""

Contents

--------

  * `Port_Overview`

  * `Port_Creation`

      - `Port_Specification`

      - `Port_Projections`

      - `Port_Deferred_Initialization`

  * `Port_Structure`

      - `Port_Strucure_Owner`

      - `Port_Structure_Projections`

      - `Port_Structure_Variable_Function_Value`

      - `Port_Modulation`

  * `Port_Execution`

  * `Port_Examples`

  * `Port_Class_Reference`

.. _Port_Overview:

Overview

--------

A Port provides an interface to one or more `Projections <Projection>`, and receives the `value(s) <Projection>`

provided by them.  The value of a Port can be modulated by a `ModulatoryProjection <ModulatoryProjection>`. There are

three primary types of Ports (InputPorts, ParameterPorts and OutputPorts) as well as one subtype (ModulatorySignal,

used to send ModulatoryProjections), as summarized in the table below:

.. _Port_types_Table:

.. table:: **Port Types and Associated Projection Types**

   :align: left

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

   | *Port Type*       | *Owner*              |      *Description*    | *Modulated by*  |       *Specification*        |

   +===================+======================+=======================+=================+==============================+

   | `InputPort`       |  `Mechanism          |receives input from    |`ControlSignal`  |`InputPort` constructor;      |

   |                   |  <Mechanism>`        |`MappingProjection`    |or `GatingSignal`|`Mechanism <Mechanism>`       |

   |                   |                      |                       |                 |constructor or its            |

   |                   |                      |                       |                 |`add_ports` method            |

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

   |`ParameterPort`    |  `Mechanism          |represents parameter   |`ControlSignal`  |Implicitly whenever a         |

   |                   |  <Mechanism>` or     |value for a `Component |and/or           |parameter value is            |

   |                   |  `Projection         |<Component>`           |`LearningSignal` |`specified                    |

   |                   |  <Projection>`       |or its `function       |                 |<ParameterPort_Specification>`|

   |                   |                      |<Component.function>`  |                 |                              |

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

   | `OutputPort`      |  `Mechanism          |provides output to     |`ControlSignal`  |`OutputPort` constructor;     |

   |                   |  <Mechanism>`        |`MappingProjection`    |or `GatingSignal`|`Mechanism <Mechanism>`       |

   |                   |                      |                       |                 |constructor or its            |

   |                   |                      |                       |                 |`add_ports` method            |

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

   |`ModulatorySignal  |`ModulatoryMechanism  |provides value for     |                 |`ModulatoryMechanism          |

   |<ModulatorySignal>`|<ModulatoryMechanism>`|`ModulatoryProjection  |                 |<ModulatoryMechanism>`        |

   |                   |                      |<ModulatoryProjection>`|                 |constructor; tuple in Port    |

   |                   |                      |                       |                 |or parameter specification    |

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

COMMENT:

* `InputPort`:

    used by a Mechanism to receive input from `MappingProjections <MappingProjection>`;

    its value can be modulated by a `ControlSignal` or a `GatingSignal`.

* `ParameterPort`:

    * used by a Mechanism to represent the value of one of its parameters, or a parameter of its

      `function <Mechanism_Base.function>`, that can be modulated by a `ControlSignal`;

    * used by a `MappingProjection` to represent the value of its `matrix <MappingProjection.MappingProjection.matrix>`

      parameter, that can be modulated by a `LearningSignal`.

* `OutputPort`:

    used by a Mechanism to send its value to any efferent projections.  For

    `ProcessingMechanisms <ProcessingMechanism>` these are `PathwayProjections <PathwayProjection>`, most commonly

    `MappingProjections <MappingProjection>`.  For `ModulatoryMechanisms <ModulatoryMechanism>`, these are

    `ModulatoryProjections <ModulatoryProjection>` as described below. The `value <OutputPort.value>` of an

    OutputPort can be modulated by a `ControlSignal` or a `GatingSignal`.

* `ModulatorySignal <ModulatorySignal>`:

    a subclass of `OutputPort` used by `ModulatoryMechanisms <ModulatoryMechanism>` to modulate the value of the primary

    types of Ports listed above.  There are three types of ModulatorySignals:

    * `LearningSignal`, used by a `LearningMechanism` to modulate the *MATRIX* ParameterPort of a `MappingProjection`;

    * `ControlSignal`, used by a `ControlMechanism <ControlMechanism>` to modulate the `ParameterPort` of a `Mechanism

      <Mechanism>`;

    * `GatingSignal`, used by a `GatingMechanism` to modulate the `InputPort` or `OutputPort` of a `Mechanism

       <Mechanism>`.

    Modulation is discussed further `below <Port_Modulation>`, and described in detail under

    `ModulatorySignals <ModulatorySignal_Modulation>`.

COMMENT

.. _Port_Creation:

Creating a Port

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

In general, Ports are created automatically by the objects to which they belong (their `owner <Port_Strucure_Owner>`),

or by specifying the Port in the constructor for its owner.  For example, unless otherwise specified, when a

`Mechanism <Mechanism>` is created it creates a default `InputPort` and `OutputPort` for itself, and whenever any

Component is created, it automatically creates a `ParameterPort` for each of its `configurable parameters

<Component_Structural_Attributes>` and those of its `function <Component_Function>`. Ports are also created in

response to explicit specifications.  For example, InputPorts and OutputPorts can be specified in the constructor for

a Mechanism (see `Mechanism_Port_Specification`); and ParameterPorts are specified in effect when the value of a

parameter for any Component or its `function <Component.function>` is specified in the constructor for that Component

or function.  InputPorts and OutputPorts (but *not* ParameterPorts) can also be created directly using their

constructors, and then assigned to a Mechanism using the Mechanism's `add_ports <Mechanism_Base.add_ports>` method;

however, this should be done with caution as the Port must be compatible with other attributes of its owner (such as

its OutputPorts) and its `function <Mechanism_Base.function>` (for example, see `note <Mechanism_Add_InputPorts_Note>`

regarding InputPorts). Parameter Ports **cannot** on their own; they are always and only created when the Component

to which a parameter belongs is created.

COMMENT:

    IMPLEMENTATION NOTE:

    If the constructor for a Port is called programmatically other than on the command line (e.g., within a method)

    the **context** argument must be specified (by convention, as ContextFlags.METHOD); otherwise, it is assumed that

    it is being created on the command line.  This is taken care of when it is created automatically (e.g., as part

    of the construction of a Mechanism or Projection) by the _instantiate_port method that specifies a context

    when it calls the relevant Port constructor methods.

COMMENT

.. _Port_Specification:

*Specifying a Port*

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

A Port can be specified using any of the following:

    * existing **Port** object;

    ..

    * name of a **Port subclass** (`InputPort`, `ParameterPort`, or `OutputPort`) -- creates a default Port of the

      specified type, using a default value for the Port that is determined by the context in which it is specified.

    ..

    * **value** -- creates a default Port using the specified value as its default `value <Port_Base.value>`.

    .. _Port_Specification_Dictionary:

    * **Port specification dictionary** -- can use the following: *KEY*:<value> entries, in addition to those

      specific to the Port's type (see documentation for each Port type):

      * *PORT_TYPE*:<Port type>

          specifies type of Port to create (necessary if it cannot be determined from

          the context of the other entries or in which it is being created).

      ..

      * *NAME*:<str>

          the string is used as the name of the Port.

      ..

      * *VALUE*:<value>

          the value is used as the default value of the Port.

      A Port specification dictionary can also be used to specify one or more `Projections <Projection>' to or from

      the Port, including `ModulatoryProjection(s) <ModulatoryProjection>` used to modify the `value

      <Port_Base.value>` of the Port.  The type of Projection(s) created depend on the type of Port specified and

      context of the specification (see `examples <Port_Specification_Dictionary_Examples>`).  This can be done using

      any of the following entries, each of which can contain any of the forms used to `specify a Projection

      <Projection_Specification>`:

      * *PROJECTIONS*:List[<`projection specification <Projection_Specification>`>,...]

          the list must contain one or more `Projection specifications <Projection_Specification>` to or from

          the Port, and/or `ModulatorySignals <ModulatorySignal>` from which it should receive projections (see

          `Port_Projections` below).

      .. _Port_Port_Name_Entry:

      * *<str>*:List[<`projection specification <Projection_Specification>`>,...]

          this must be the only entry in the dictionary, and the string cannot be a PsyNeuLink

          keyword;  it is used as the name of the Port, and the list must contain one or more `Projection

          specifications <Projection_Specification>`.

      .. _Port_MECHANISM_PORTS_Entries:

      * *MECHANISM*:Mechanism

          this can be used to specify one or more Projections to or from the specified Mechanism.  If the entry appears

          without any accompanying Port specification entries (see below), the Projection is assumed to be a

          `MappingProjection` to the Mechanism's `primary InputPort <InputPort_Primary>` or from its `primary

          OutputPort <OutputPort_Primary>`, depending upon the type of Mechanism and context of specification.  It

          can also be accompanied by one or more Port specification entries described below, to create one or more

          Projections to/from those specific Ports (see `examples <Port_Port_Name_Entry_Example>`).

      ..

      * <PORTS_KEYWORD>:List[<str or Port.name>,...]

         this must accompany a *MECHANISM* entry (described above), and is used to specify its Port(s) by name.

         Each entry must use one of the following keywords as its key, and there can be no more than one of each:

            - *INPUT_PORTS*

            - *OUTPUT_PORTS*

            - *PARAMETER_PORTS*

            - *LEARNING_SIGNAL*

            - *CONTROL_SIGNAL*

            - *GATING_SIGNAL*.

         Each entry must contain a list Ports of the specified type, all of which belong to the Mechanism specified in

         the *MECHANISM* entry;  each item in the list must be the name of one the Mechanism's Ports, or a

         `ProjectionTuple <Port_ProjectionTuple>` the first item of which is the name of a Port. The types of

         Ports that can be specified in this manner depends on the type of the Mechanism and context of the

         specification (see `examples <Port_Port_Name_Entry_Example>`).

    * **Port, Mechanism, or list of these** -- creates a default Port with Projection(s) to/from the specified

      Ports;  the type of Port being created determines the type and directionality of the Projection(s) and,

      if Mechanism(s) are specified, which of their primary Ports are used (see Port subclasses for specifics).

   .. _Port_Tuple_Specification:

    * **Tuple specifications** -- these are convenience formats that can be used to compactly specify a Port

      by specifying other Components with which it should be connected by Projection(s). Different Ports support

      different forms, but all support the following two forms:

      .. _Port_2_Item_Tuple:

      * **2-item tuple:** *(<Port name or list of Port names>, <Mechanism>)* -- 1st item is the name of a Port or

        list of them, and the 2nd item is the Mechanism to which they belong; a Projection is created to or from each

        of the Ports specified.  The type of Projection depends on the type of Port being created, and the type of

        Ports specified in the tuple  (see `Projection_Table`).  For example, if the Port being created is an

        InputPort, and the Ports specified in the tuple are OutputPorts, then `MappingProjections

        <MappingProjection>` are used; if `ModulatorySignals <ModulatorySignal>` are specified, then the corresponding

        type of `ModulatoryProjections <ModulatoryProjection>` are created.  See Port subclasses for additional

        details and compatibility requirements.

      |

      .. _Port_ProjectionTuple:

      * `ProjectionTuple <Projection_ProjectionTuple>` -- a 4-item tuple that specifies one or more `Projections

        <Projection>` to or from other Port(s), along with a weight and/or exponent for each.

.. _Port_Projections:

*Projections*

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

When a Port is created, it can be assigned one or more `Projections <Projection>`, in either the **projections**

argument of its constructor, or a *PROJECTIONS* entry of a `Port specification dictionary

<Port_Specification_Dictionary>` (or a dictionary assigned to the **params** argument of the Port's constructor).

The following types of Projections can be specified for each type of Port:

    .. _Port_Projections_Table:

    .. table:: **Specifiable Projections for Port Types**

        :align: left

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

        | *Port Type*      | *PROJECTIONS* specification   | *Assigned to Attribute*             |

        +==================+===============================+=====================================+

        |`InputPort`       | `PathwayProjection(s)         | `path_afferents                     |

        |                  | <PathwayProjection>`          | <Port_Base.path_afferents>`         |

        |                  |                               |                                     |

        |                  | `ControlProjection(s)         | `mod_afferents                      |

        |                  | <ControlProjection>`          | <Port_Base.mod_afferents>`          |

        |                  |                               |                                     |

        |                  | `GatingProjection(s)          | `mod_afferents                      |

        |                  | <GatingProjection>`           | <Port_Base.mod_afferents>`          |

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

        |`ParameterPort`   | `ControlProjection(s)         | `mod_afferents                      |

        |                  | <ControlProjection>`          | <ParameterPort.mod_afferents>`      |

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

        |`OutputPort`      | `PathwayProjection(s)         | `efferents                          |

        |                  | <PathwayProjection>`          | <Port_Base.efferents>`              |

        |                  |                               |                                     |

        |                  | `ControlProjection(s)         | `mod_afferents                      |

        |                  | <ControlProjection>`          | <Port_Base.mod_afferents>`          |

        |                  |                               |                                     |

        |                  | `GatingProjection(s)          | `mod_afferents                      |

        |                  | <GatingProjection>`           | <Port_Base.mod_afferents>`          |

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

        |`ModulatorySignal`|  `ModulatoryProjection(s)     | `efferents                          |

        |                  |  <ModulatoryProjection>`      | <ModulatorySignal.efferents>`       |

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

Projections must be specified in a list.  Each entry must be either a `specification for a projection

<Projection_Specification>`, or for a `sender <Projection_Base.sender>` or `receiver <Projection_Base.receiver>` of

one, in which case the appropriate type of Projection is created.  A sender or receiver can be specified as a `Port

<Port>` or a `Mechanism <Mechanism>`. If a Mechanism is specified, its primary `InputPort <InputPort_Primary>` or

`OutputPort <OutputPort_Primary>`  is used, as appropriate.  When a sender or receiver is used to specify the

Projection, the type of Projection created is inferred from the Port and the type of sender or receiver specified,

as illustrated in the `examples <Port_Projections_Examples>` below.  Note that the Port must be `assigned to an

owner <Port_Creation>` in order to be functional, irrespective of whether any `Projections <Projection>` have been

assigned to it.

.. _Port_Deferred_Initialization:

*Deferred Initialization*

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

If a Port is created on its own, and its `owner <Port_Strucure_Owner>` Mechanism is specified, it is assigned to that

Mechanism; if its owner not specified, then its initialization is `deferred <Port_Deferred_Initialization>`.

Its initialization is completed automatically when it is assigned to an owner `Mechanism <Mechanism>` using the

owner's `add_ports <Mechanism_Base.add_ports>` method.  If the Port is not assigned to an owner, it will not be

functional (i.e., used during the execution of `Mechanisms <Mechanism_Execution>` and/or `Compositions

<Composition_Execution>`, irrespective of whether it has any `Projections <Projection>` assigned to it.

.. _Port_Structure:

Structure

---------

.. _Port_Strucure_Owner:

*Owner*

~~~~~~~

Every Port has an `owner <Port_Base.owner>`.  For `InputPorts <InputPort>` and `OutputPorts <OutputPort>`, the

owner must be a `Mechanism <Mechanism>`.  For `ParameterPorts <ParameterPort>` it can be a Mechanism or a

`PathwayProjection <PathwayProjection>`. For `ModulatorySignals <ModulatorySignal>`, it must be a `ModulatoryMechanism

<ModulatoryMechanism>`. When a Port is created as part of another Component, its `owner <Port_Base.owner>` is

assigned automatically to that Component.  It is also assigned automatically when the Port is assigned to a

`Mechanism <Mechanism>` using that Mechanism's `add_ports <Mechanism_Base.add_ports>` method.  Otherwise, it must be

specified explicitly in the **owner** argument of the constructor for the Port (in which case it is immediately

assigned to the specified Mechanism).  If the **owner** argument is not specified, the Port's initialization is

`deferred <Port_Deferred_Initialization>` until it has been assigned to an owner using the owner's `add_ports

<Mechanism_Base.add_ports>` method.

.. _Port_Structure_Projections:

*Projections*

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

Every Port has attributes that lists the `Projections <Projection>` it sends and/or receives.  These depend on the

type of Port, listed below (and shown in the `table <Port_Projections_Table>`):

.. table::  Port Projection Attributes

   :align: left

   ============================================ ============================================================

   *Attribute*                                  *Projection Type and Port(s)*

   ============================================ ============================================================

   `path_afferents <Port_Base.path_afferents>`  `MappingProjections <MappingProjection>` to `InputPort`

   `mod_afferents <Port_Base.mod_afferents>`    `ModulatoryProjections <ModulatoryProjection>` to any Port

   `efferents <Port_Base.efferents>`            `MappingProjections <MappingProjection>` from `OutputPort`

   ============================================ ============================================================

In addition to these attributes, all of the Projections sent and received by a Port are listed in its `projections

<Port_Base.projections>` attribute.

.. _Port_Structure_Variable_Function_Value:

*Variable, Function and Value*

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

In addition, like all PsyNeuLink Components, it also has the three following core attributes:

    * `variable <Port_Base.variable>`:  for an `InputPort` and `ParameterPort`,

      the value of this is determined by the value(s) of the Projection(s) that it receives (and that are listed in

      its `path_afferents <Port_Base.path_afferents>` attribute).  For an `OutputPort`, it is the item of the owner

      Mechanism's `value <Mechanism_Base.value>` to which the OutputPort is assigned (specified by the OutputPort's

      `index <OutputPort_Index>` attribute.

    ..

    * `function <Port_Base.function>`:  for an `InputPort` this combines the values of the Projections that the

      Port receives (the default is `LinearCombination` that sums the values), under the potential influence of a

      `GatingSignal`;  for a `ParameterPort`, it determines the value of the associated parameter, under the potential

      influence of a `ControlSignal` (for a `Mechanism <Mechanism>`) or a `LearningSignal` (for a `MappingProjection`);

      for an OutputPort, it conveys the result  of the Mechanism's function to its `output_values

      <Mechanism_Base.output_values>` attribute, under the potential influence of a `GatingSignal`.  See

      `ModulatorySignals <ModulatorySignal_Structure>` and the `ModulatoryMechanism <ModulatoryMechanism>` associated

      with each type for a description of how they can be used to modulate the `function <Port_Base.function>` of a

      Port.

    ..

    * `value <Port_Base.value>`:  for an `InputPort` this is the combined value of the `PathwayProjections` it

      receives;  for a `ParameterPort`, this represents the value of the parameter that will be used by the Port's

      owner or its `function <Component.function>`; for an `OutputPort`, it is the item of the  owner Mechanism's

      `value <Mechanisms.value>` to which the OutputPort is assigned, possibly modified by its `assign

      <OutputPort_Assign>` attribute and/or a `GatingSignal`, and used as the `value <Projection_Base.value>` of

      the Projections listed in its `efferents <OutputPort.path_efferents>` attribute.

.. _Port_Modulation:

*Modulation*

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

Every type of Port has a `mod_afferents <Port_Base.mod_afferents>` attribute, that lists the `ModulatoryProjections

<ModulatoryProjection>` it receives.  Each ModulatoryProjection comes from a `ModulatorySignal <ModulatorySignal>`

that specifies how it should modulate the Port's `value <Port_Base.value>` when the Port is updated (see

`ModulatorySignal_Modulation` and `ModulatorySignal_Anatomy_Figure`).  In most cases, a ModulatorySignal uses the

Port's `function <Port_Base.function>` to modulate its `value <Port_Base.value>`.  The function of every Port

assigns one of its parameters as its *ADDITIVE_PARAM* and another as its *MULTIPLICATIVE_PARAM*. The

`modulation <ModulatorySignal.modulation>` attribute of a ModulatorySignal determines which of these to modify when the

Port uses it `function <Port_Base.function>` to calculate its `value  <Port_Base.value>`.  However, the

ModulatorySignal can also be configured to override the Port's `value <Port_Base.value>` (i.e., assign it directly),

or to disable modulation, using either the keyword *OVERRIDE* or *DSIABLE*, respectively, to specify the value for its

`modulation <ModulatorySignal.modulation>` attribute (see `ModulatorySignal_Modulation` for a more detailed discussion).

.. _Port_Execution:

Execution

---------

Ports cannot be executed.  They are updated when the Component to which they belong is executed.  InputPorts and

ParameterPorts belonging to a Mechanism are updated before the Mechanism's function is called.  OutputPorts are

updated after the Mechanism's function is called.  When a Port is updated, it executes any Projections that project

to it (listed in its `all_afferents <Port_Base.all_afferents>` attribute.  It uses the values it receives from any

`PathWayProjections` (listed in its `path_afferents` attribute) as the variable for its

`function <Port_Base.function>`. It then executes all of the ModulatoryProjections it receives.  Different

ModulatorySignals may call for different forms of modulation (see `ModulatorySignal_Modulation`).  Accordingly,

it separately sums the values specified by any ModulatorySignals for the *MULTIPLICATIVE_PARAM* of its

`function <Port_Base.function>`, and similarly for the *ADDITIVE_PARAM*.  It then applies the summed value for each

to the corresponding parameter of its `function <Port_Base.function>`.  If any of the ModulatorySignals specifies

*OVERRIDE*, then the value of that ModulatorySignal is used as the Port's `value <Port_Base.value>`. Finally,

the Port calls its `function <Port_Base.function>` to determine its `value <Port_Base.value>`.

.. note::

   The change in the value of a `Port <Port>` does not occur until the Mechanism to which the Port belongs is next

   executed; This conforms to a "lazy evaluation" protocol (see `Lazy Evaluation <Component_Lazy_Updating>` for an

   explanation of "lazy" updating).

.. _Port_Examples:

Examples

========

.. _Port_Constructor_Examples:

Usually, Ports are created automatically by the Mechanism to which they belong.  For example, creating a

TransferMechanism::

    my_mech = pnl.TransferMechanism()

automatically creates an InputPort, ParameterPorts for its parameters, including the `slope <Linear.slope>` and

`intercept <Linear.intercept>` parameters of its `Linear` `Function <Function>` (its default `function

<Mechanism_Base.function>`), and an OutputPort (named *RESULT*)::

    print(my_mech.input_ports)

    > [(InputPort InputPort-0)]

    print(my_mech.parameter_ports)

    > [(ParameterPort intercept), (ParameterPort slope), (ParameterPort noise), (ParameterPort integration_rate)]

    print(my_mech.output_ports)

    > [(OutputPort RESULT)]

.. _Port_Constructor_Argument_Examples:

*Using the* **input_ports** *argument of a Mechanism constructor.*

When Ports are specified explicitly, it is usually in an argument of the constructor for the Mechanism to which they

belong.  For example, the following specifies that ``my_mech`` should have an InputPort named 'MY INPUT`::

    my_mech = pnl.TransferMechanism(input_ports=['MY INPUT'])

    print(my_mech.input_ports)

    > [(InputPort 'MY INPUT')]

The InputPort was specified by a string (for its name) in the **input_ports** argument.  It can also be specified in

a variety of other ways, as described `above <Port_Specification>` and illustrated in the examples below.

Note that when one or more Ports is specified in the argument of a Mechanism's constructor, it replaces any defaults

Ports created by the Mechanism when none are specified (see `note <Mechanism_Default_Port_Suppression_Note>`.

.. _port_value_Spec_Example:

For example, the following specifies the InputPort by a value to use as its `variable <InputPort.variable>` attribute::

    my_mech = pnl.TransferMechanism(input_ports=[[0,0])

The value is also used to format the InputPort's `value <InputPort.value>`, as well as the first (and, in this case,

only) item of the Mechanism's `variable <Mechanism_Base.variable>` (i.e., the one to which the InputPort is

assigned), as show below::

    print(my_mech.input_ports[0].variable)

    > [0 0]

    print (my_mech.input_port.value)

    > [ 0.  0.]

    print (my_mech.variable)

    > [[0 0]]

Note that in the first print port, the InputPort was referenced as the first one in the `input_ports

<Mechanism_Base.input_ports>` attribute of ``my_mech``;  the second print port references it directly,

as the `primary InputPort <Input_port.primary>` of ``my_mech``, using its `input_port <Mechanism_Base.input_port>`

attribute (note the singular).

.. _Port_Multiple_InputSates_Example:

*Multiple InputPorts*

The **input_ports** argument can also be used to create more than one InputPort::

    my_mech = pnl.TransferMechanism(input_ports=['MY FIRST INPUT', 'MY SECOND INPUT'])

    print(my_mech.input_ports)

    > [(InputPort MY FIRST INPUT), (InputPort MY SECOND INPUT)]

Here, the print statement uses the `input_ports <Mechanism_Base.input_ports>` attribute, since there is now more

than one InputPort.  OutputPorts can be specified in a similar way, using the **output_ports** argument.

    .. note::

        Although InputPorts and OutputPorts can be specified in a Mechanism's constructor, ParameterPorts cannot;

        those are created automatically when the Mechanism is created, for each of its `user configurable parameters

        <Component_User_Params>`  and those of its `function <Mechanism_Base.function>`.  However, the `value

        <ParameterPort.value>` can be specified when the Mechanism is created, or its `function

        <Mechanism_Base.function>` is assigned, and can be accessed and subsequently modified, as described under

        `ParameterPort_Specification>`.

.. _Port_Standard_OutputPorts_Example:

*OutputPorts*

The following example specifies two OutputPorts for ``my_mech``, using its `Standard OutputPorts

<OutputPort_Standard>`::

    my_mech = pnl.TransferMechanism(output_ports=['RESULT', 'MEAN'])

As with InputPorts, specification of OutputPorts in the **output_ports** argument suppresses the creation of any

default OutputPorts that would have been created if no OutputPorts were specified (see `note

<Mechanism_Default_Port_Suppression_Note>` above).  For example, TransferMechanisms create a *RESULT* OutputPort

by default, that contains the result of their `function <OutputPort.function>`.  This default behavior is suppressed

by any specifications in its **output_ports** argument.  Therefore, to retain a *RESULT* OutputPort,

it must be included in the **output_ports** argument along with any others that are specified, as in the example

above.  If the name of a specified OutputPort matches the name of a Standard OutputPort <OutputPort_Standard>` for

the type of Mechanism, then that is used (as is the case for both of the OutputPorts specified for the

`TransferMechanism` in the example above); otherwise, a new OutputPort is created.

.. _Port_Specification_Dictionary_Examples:

*Port specification dictionary*

Ports can be specified in greater detail using a `Port specification dictionary

<Port_Specification_Dictionary>`. In the example below, this is used to specify the variable and name of an

InputPort::

    my_mech = pnl.TransferMechanism(input_ports=[{PORT_TYPE: InputPort,

                                                   NAME: 'MY INPUT',

                                                   VARIABLE: [0,0]})

The *PORT_TYPE* entry is included here for completeness, but is not actually needed when the Port specification

dicationary is used in **input_ports** or **output_ports** argument of a Mechanism, since the Port's type

is clearly determined by the context of the specification;  however, where that is not clear, then the *PORT_TYPE*

entry must be included.

.. _Port_Projections_Examples:

*Projections*

A Port specification dictionary can also be used to specify projections to or from the Port, also in

a number of different ways.  The most straightforward is to include them in a *PROJECTIONS* entry.  For example, the

following specifies that the InputPort of ``my_mech`` receive two Projections,  one from ``source_mech_1`` and another

from ``source_mech_2``, and that its OutputPort send one to ``destination_mech``::

    source_mech_1 = pnl.TransferMechanism(name='SOURCE_1')

    source_mech_2 = pnl.TransferMechanism(name='SOURCE_2')

    destination_mech = pnl.TransferMechanism(name='DEST')

    my_mech = pnl.TransferMechanism(name='MY_MECH',

                                    input_ports=[{pnl.NAME: 'MY INPUT',

                                                   pnl.PROJECTIONS:[source_mech_1, source_mech_2]}],

                                    output_ports=[{pnl.NAME: 'RESULT',

                                                    pnl.PROJECTIONS:[destination_mech]}])

    # Print names of the Projections:

    for projection in my_mech.input_port.path_afferents:

        print(projection.name)

    > MappingProjection from SOURCE_1[RESULT] to MY_MECH[MY INPUT]

    > MappingProjection from SOURCE_2[RESULT] to MY_MECH[MY INPUT]

    for projection in my_mech.output_port.efferents:

        print(projection.name)

    > MappingProjection from MY_MECH[RESULT] to DEST[InputPort]

A *PROJECTIONS* entry can contain any of the forms used to `specify a Projection <Projection_Specification>`.

Here, Mechanisms are used, which creates Projections from the `primary InputPort <InputPort_Primary>` of

``source_mech``, and to the `primary OutputPort <OutputPort_Primary>` of ``destination_mech``.  Note that

MappingProjections are created, since the Projections specified are between InputPorts and OutputPorts.

`ModulatoryProjections` can also be specified in a similar way.  The following creates a `GatingMechanism`, and

specifies that the InputPort of ``my_mech`` should receive a `GatingProjection` from it::

    my_gating_mech = pnl.GatingMechanism()

    my_mech = pnl.TransferMechanism(name='MY_MECH',

                                    input_ports=[{pnl.NAME: 'MY INPUT',

                                                   pnl.PROJECTIONS:[my_gating_mech]}])

.. _Port_Modulatory_Projections_Examples:

Conversely, ModulatoryProjections can also be specified from a Mechanism to one or more Ports that it modulates.  In

the following example, a `ControlMechanism` is created that sends `ControlProjections <ControlProjection>` to the

`drift_rate <DriftDiffusionAnalytical.drift_rate>` and `threshold <DriftDiffusionAnalytical.threshold>`

ParameterPorts of a `DDM` Mechanism::

    my_mech = pnl.DDM(name='MY DDM')

    my_ctl_mech = pnl.ControlMechanism(control_signals=[{pnl.NAME: 'MY DDM DRIFT RATE AND THREHOLD CONTROL SIGNAL',

                                                         pnl.PROJECTIONS: [my_mech.parameter_ports[pnl.DRIFT_RATE],

                                                                           my_mech.parameter_ports[pnl.THRESHOLD]]}])

    # Print ControlSignals and their ControlProjections

    for control_signal in my_ctl_mech.control_signals:

        print(control_signal.name)

        for control_projection in control_signal.efferents:

            print("\t{}: {}".format(control_projection.receiver.owner.name, control_projection.receiver))

    > MY DDM DRIFT RATE AND THRESHOLD CONTROL SIGNAL

    >     MY DDM: (ParameterPort drift_rate)

    >     MY DDM: (ParameterPort threshold)

Note that a ControlMechanism uses a **control_signals** argument in place of an **output_ports** argument (since it

uses `ControlSignal <ControlSignals>` for its `OutputPorts <OutputPort>`.  Note also that, for specifying Projections

of a ControlSignal (i.e., its ControlProjections), the keyword *CONTROL* can be used in place of the more generic

*PROJECTIONS* keyword (as shown in the example below).

In the example above, both ControlProjections are assigned to a single ControlSignal.  However, they could each be

assigned to their own by specifying them in separate items of the **control_signals** argument::

    my_mech = pnl.DDM(name='MY DDM')

    my_ctl_mech = pnl.ControlMechanism(control_signals=[{pnl.NAME: 'DRIFT RATE CONTROL SIGNAL',

                                                         pnl.CONTROL: [my_mech.parameter_ports[pnl.DRIFT_RATE]]},

                                                        {pnl.NAME: 'THRESHOLD RATE CONTROL SIGNAL',

                                                         pnl.CONTROL: [my_mech.parameter_ports[pnl.THRESHOLD]]}])

    # Print ControlSignals and their ControlProjections...

    > DRIFT RATE CONTROL SIGNAL

    >     MY DDM: (ParameterPort drift_rate)

    > THRESHOLD RATE CONTROL SIGNAL

    >     MY DDM: (ParameterPort threshold)

Specifying Projections in a Port specification dictionary affords flexibility -- for example, naming the Port

and/or specifying other attributes.  However, if this is not necessary, the Projections can be used to specify

Ports directly.  For example, the following, which is much simpler, produces the same result as the previous

example (sans the custom name; though as the printout below shows, the default names are usually pretty clear)::

    my_ctl_mech = pnl.ControlMechanism(control_signals=[my_mech.parameter_ports[pnl.DRIFT_RATE],

                                                        my_mech.parameter_ports[pnl.THRESHOLD]])

    # Print ControlSignals and their ControlProjections...

    > MY DDM drift_rate ControlSignal

    >    MY DDM: (ParameterPort drift_rate)

    > MY DDM threshold ControlSignal

    >    MY DDM: (ParameterPort threshold)

.. _Port_Port_Name_Entry_Example:

*Convenience formats*

There are two convenience formats for specifying Ports and their Projections in a Port specification

dictionary.  The `first <Port_Port_Name_Entry>` is to use the name of the Port as the key for its entry,

and then a list of , as in the following example::

    source_mech_1 = pnl.TransferMechanism()

    source_mech_2 = pnl.TransferMechanism()

    destination_mech = pnl.TransferMechanism()

    my_mech_C = pnl.TransferMechanism(input_ports=[{'MY INPUT':[source_mech_1, source_mech_2]}],

                                      output_ports=[{'RESULT':[destination_mech]}])

This produces the same result as the first example under `Port specification dictionary <Port_Projections_Examples>`

above, but it is simpler and easier to read.

The second convenience format is used to specify one or more Projections to/from the Ports of a single Mechanism

by their name.  It uses the keyword *MECHANISM* to specify the Mechanism, coupled with a Port-specific entry to

specify Projections to its Ports.  This can be useful when a Mechanism must send Projections to several Ports

of another Mechanism, such as a ControlMechanism that sends ControlProjections to several parameters of a

given Mechanism, as in the following example::

    my_mech = pnl.DDM(name='MY DDM')

    my_ctl_mech = pnl.ControlMechanism(control_signals=[{pnl.MECHANISM: my_mech,

                                                         pnl.PARAMETER_PORTS: [pnl.DRIFT_RATE, pnl.THRESHOLD]}])

This produces the same result as the `earlier example <Port_Modulatory_Projections_Examples>` of ControlProjections,

once again in a simpler and easier to read form.  However, it be used only to specify Projections for a Port to or

from the Ports of a single Mechanism;  Projections involving other Mechanisms must be assigned to other Ports.

.. _Port_Create_Port_Examples:

*Create and then assign a port*

Finally, a Port can be created directly using its constructor, and then assigned to a Mechanism.

The following creates an InputPort ``my_input_port`` with a `MappingProjection` to it from the

`primary OutputPort <OutputPort_Primary>` of ``mech_A`` and assigns it to ``mech_B``::

    mech_A = pnl.TransferMechanism()

    my_input_port = pnl.InputPort(name='MY INPUTPORT',

                                    projections=[mech_A])

    mech_B = pnl.TransferMechanism(input_ports=[my_input_port])

    print(mech_B.input_ports)

    > [(InputPort MY INPUTPORT)]

The InputPort ``my_input_port`` could also have been assigned to ``mech_B`` in one of two other ways:

by explicity adding it using ``mech_B``\\'s `add_ports <Mechanism_Base.add_ports>` method::

    mech_A = pnl.TransferMechanism()

    my_input_port = pnl.InputPort(name='MY INPUTPORT',

                                    projections=[mech_A])

    mech_B = pnl.TransferMechanism()

    mech_B.add_ports([my_input_port])

or by constructing it after ``mech_B`` and assigning ``mech_B`` as its owner::

    mech_A = pnl.TransferMechanism()

    mech_B = pnl.TransferMechanism()

    my_input_port = pnl.InputPort(name='MY INPUTPORT',

                                    owner=mech_B,

                                    projections=[mech_A])

Note that, in both cases, adding the InputPort to ``mech_B`` does not replace its the default InputPort generated

when it was created, as shown by printing the `input_ports <Mechanism_Base.input_ports>` for ``mech_B``::

    print(mech_B.input_ports)

    > [(InputPort InputPort-0), (InputPort MY INPUTPORT)]

    > [(InputPort InputPort-0), (InputPort MY INPUTPORT)]

As a consequence, ``my_input_port`` is  **not** the `primary InputPort <InputPort_Primary>` for ``mech_B`` (i.e.,

input_ports[0]), but rather its second InputPort (input_ports[1]). This is differs from specifying the InputPort

as part of the constructor for the Mechanism, which suppresses generation of the default InputPort,

as in the first example above (see `note <Mechanism_Default_Port_Suppression_Note>`).

COMMENT:

*** ??ADD THESE TO EXAMPLES, HERE OR IN Projection??

    def test_mapping_projection_with_mech_and_port_Name_specs(self):

         R1 = pnl.TransferMechanism(output_ports=['OUTPUT_1', 'OUTPUT_2'])

         R2 = pnl.TransferMechanism(default_variable=[[0],[0]],

                                    input_ports=['INPUT_1', 'INPUT_2'])

         T = pnl.TransferMechanism(input_ports=[{pnl.MECHANISM: R1,

                                                  pnl.OUTPUT_PORTS: ['OUTPUT_1', 'OUTPUT_2']}],

                                   output_ports=[{pnl.MECHANISM:R2,

                                                   pnl.INPUT_PORTS: ['INPUT_1', 'INPUT_2']}])

   def test_transfer_mech_input_ports_specification_dict_spec(self):

        R1 = TransferMechanism(output_ports=['FIRST', 'SECOND'])

        T = TransferMechanism(default_variable=[[0],[0]],

                                      input_ports=[{NAME: 'FROM DECISION',

                                                     PROJECTIONS: [R1.output_ports['FIRST']]},

                                                    {NAME: 'FROM RESPONSE_TIME',

                                                     PROJECTIONS: R1.output_ports['SECOND']}])

   def test_transfer_mech_input_ports_projection_in_specification_dict_spec(self):

        R1 = TransferMechanism(output_ports=['FIRST', 'SECOND'])

        T = TransferMechanism(input_ports=[{NAME: 'My InputPort with Two Projections',

                                             PROJECTIONS:[R1.output_ports['FIRST'],

                                                          R1.output_ports['SECOND']]}])

    def test_transfer_mech_input_ports_mech_output_port_in_specification_dict_spec(self):

        R1 = TransferMechanism(output_ports=['FIRST', 'SECOND'])

        T = TransferMechanism(input_ports=[{MECHANISM: R1,

                                             OUTPUT_PORTS: ['FIRST', 'SECOND']}])

        assert len(T.input_ports)==1

        for input_port in T.input_ports:

            for projection in input_port.path_afferents:

                assert projection.sender.owner is R1

creates a `GatingSignal` with

`GatingProjections <GatingProjection>` to ``mech_B`` and ``mech_C``, and assigns it to ``my_gating_mech``::

    my_gating_signal = pnl.GatingSignal(projections=[mech_B, mech_C])

    my_gating_mech = GatingMechanism(gating_signals=[my_gating_signal]

The `GatingMechanism` created will gate the `primary InputPorts <InputPort_Primary>` of ``mech_B`` and ``mech_C``.

The following creates

   def test_multiple_modulatory_projections_with_mech_and_port_Name_specs(self):

        M = pnl.DDM(name='MY DDM')

        C = pnl.ControlMechanism(control_signals=[{pnl.MECHANISM: M,

                                                   pnl.PARAMETER_PORTS: [pnl.DRIFT_RATE, pnl.THRESHOLD]}])

        G = pnl.GatingMechanism(gating_signals=[{pnl.MECHANISM: M,

                                                 pnl.OUTPUT_PORTS: [pnl.DECISION_VARIABLE, pnl.RESPONSE_TIME]}])

        M = pnl.DDM(name='MY DDM')

        C = pnl.ControlMechanism(control_signals=[{'DECISION_CONTROL':[M.parameter_ports[pnl.DRIFT_RATE],

                                                                       M.parameter_ports[pnl.THRESHOLD]]}])

        G = pnl.GatingMechanism(gating_signals=[{'DDM_OUTPUT_GATE':[M.output_ports[pnl.DECISION_VARIABLE],

                                                                    M.output_ports[pnl.RESPONSE_TIME]]}])

COMMENT

.. _Port_Class_Reference:

Class Reference

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

"""

    Function, get_param_value_for_keyword, is_function_type, RandomMatrix

    ADDITIVE, ADDITIVE_PARAM, AUTO_ASSIGN_MATRIX, CONTEXT, CONTROL_PROJECTION_PARAMS, CONTROL_SIGNAL_SPECS, \

    DEFAULT_INPUT, DEFAULT_VARIABLE, DEFERRED_INITIALIZATION, DISABLE, \

    EXPONENT, FEEDBACK, FUNCTION, FUNCTION_PARAMS, GATING_PROJECTION_PARAMS, GATING_SIGNAL_SPECS, INPUT_PORTS, \

    LEARNING_PROJECTION_PARAMS, LEARNING_SIGNAL_SPECS, \

    MATRIX, MECHANISM, MODULATORY_PROJECTION, MODULATORY_PROJECTIONS, MODULATORY_SIGNAL, \

    MULTIPLICATIVE, MULTIPLICATIVE_PARAM, \

    NAME, OUTPUT_PORTS, OVERRIDE, OWNER, \

    PARAMETER_PORTS, PARAMS, PATHWAY_PROJECTIONS, PREFS_ARG, \

    PROJECTION_DIRECTION, PROJECTIONS, PROJECTION_PARAMS, PROJECTION_TYPE, \

    RECEIVER, REFERENCE_VALUE, REFERENCE_VALUE_NAME, SENDER, STANDARD_OUTPUT_PORTS, \

    PORT, PORT_COMPONENT_CATEGORY, PORT_CONTEXT, Port_Name, port_params, PORT_PREFS, PORT_TYPE, port_value, \

    VALUE, VARIABLE, WEIGHT

    ContentAddressableList, convert_all_elements_to_np_array, convert_to_np_array, get_args, is_numeric, is_value_spec, iscompatible, \

    MODULATION_OVERRIDE, try_extract_0d_array_item, type_match

    'Port_Base', 'port_keywords', 'port_type_keywords', 'PortError', 'PortRegistry', 'PORT_SPEC'

]

                      PORT_TYPE,

                      port_value,

                      port_params,

                      PATHWAY_PROJECTIONS,

                      MODULATORY_PROJECTIONS,

                      PROJECTION_TYPE,

                      PROJECTION_PARAMS,

                      LEARNING_PROJECTION_PARAMS,

                      LEARNING_SIGNAL_SPECS,

                      CONTROL_PROJECTION_PARAMS,

                      CONTROL_SIGNAL_SPECS,

                      GATING_PROJECTION_PARAMS,

                      GATING_SIGNAL_SPECS})

    # mimics cast to float when default is a float, which previously

    # happened in type_match

# Note:  This is created only for assignment of default projection types for each Port subclass (see .__init__.py)

#        Individual portRegistries (used for naming) are created for each Mechanism

# DOCUMENT:  INSTANTIATION CREATES AN ATTIRBUTE ON THE OWNER MECHANISM WITH THE PORT'S NAME + VALUE_SUFFIX

#            THAT IS UPDATED BY THE PORT'S value setter METHOD (USED BY LOGGING OF MECHANISM ENTRIES)

    """

    Port_Base(     \

        owner=None \

        )

    Base class for Port.

    The arguments below can be used in the constructor for any subclass of Port.

    See `Component <Component_Class_Reference>` for additional arguments and attributes.

    .. note::

       Port is an abstract class and should *never* be instantiated by a call to its constructor. It should be created

       by calling the constructor for a `subclass <Port_Subtypes>`, or by using any of the other methods for `specifying

       a Port <Port_Specification>`.

    .. technical_note::

        PortRegistry

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

            Used by .__init__.py to assign default Projection types to each Port subclass

            .. note::

              All Ports that belong to a given owner are registered in the owner's _portRegistry, which maintains a

              dict for each Port type that it uses, a count for all instances of that type, and a dictionary of those