PrincetonUniversity / PsyNeuLink / 11978908787

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

# *******************************************  InputPort *****************************************************

#

"""

Contents

--------

* `InputPort_Overview`

* `InputPort_Creation`

    - `InputPort_Deferred_Initialization`

    - `InputPort_Primary`

    - `InputPort_Specification`

        • `Forms of Specification <InputPort_Forms_of_Specification>`

        • `Variable, Value and Mechanism <InputPort_Variable_and_Value>`

        • `Variable: Compatability and Constaints <InputPort_Compatability_and_Constraints>`

* `InputPort_Structure`

    - `Afferent Projections <InputPort_Afferent_Projections>`

    - `Variable <InputPort_Variable>`

    - `Function <InputPort_Function>`

    - `Value <InputPort_Value>`

    - `Weights ane Exponents <InputPort_Weights_And_Exponents>`

* `InputPort_Execution`

* `InputPort_Class_Reference`

.. _InputPort_Overview:

Overview

--------

The purpose of an InputPort is to receive and combine inputs to a `Mechanism <Mechanism>`, allow them to be modified,

and provide them to the Mechanism's `function <Mechanism_Base.function>`. An InputPort receives input to a Mechanism

provided by the `Projections <Projection>` to that Mechanism from others in a `Composition`.  If the InputPort belongs

to an `ORIGIN` Mechanism (see `Mechanism_Role_In_Compositions`), then it receives the input specified when that

Composition is `run <Run>`.  The `PathwayProjections <PathWayProjection>` received by an InputPort are listed in its

`path_afferents <Port_Base.path_afferents>`, and its `ModulatoryProjections <ModulatoryProjection>` in its

`mod_afferents <Port_Base.mod_afferents>` attribute.  Its `function <InputPort.function>` combines the values received

from its PathWayProjections, modifies the combined value according to value(s) any ModulatoryProjections it receives,

and provides the result to the assigned item of its owner Mechanism's `variable <Mechanism_Base.variable>` and

`input_values <Mechanism_Base.input_values>` attributes (see `below` and `Mechanism InputPorts <Mechanism_InputPorts>`

for additional details about the role of InputPorts in Mechanisms, and their assignment to the items of a Mechanism's

`variable <Mechanism_Base.variable>` attribute).

.. _InputPort_Creation:

Creating an InputPort

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

An InputPort can be created by calling its constructor, but in general this is not necessary as a `Mechanism

<Mechanism>` can usually automatically create the InputPort(s) it needs when it is created.  For example, if the

Mechanism isbeing created within the `pathway <Process.pathway>` of a `Process`, its InputPort is created and assigned

as the `receiver <MappingProjection.receiver>` of a `MappingProjection` from the  preceding Mechanism in the `pathway

<Process.pathway>`.  InputPorts can also be specified in the **input_ports** argument of a Mechanism's constructor

(see `below <InputPort_Specification>`).

The `variable <InputPort.variable>` of an InputPort can be specified using the **variable** or **input_shapes** arguments of

its constructor.  It can also be specified using the **projections** argument, if neither **variable** nor **input_shapes** is

specified.  The **projections** argument is used to `specify Projections <Port_Projections>` to the InputPort. If

neither the **variable** nor **input_shapes** arguments is specified, then the value of the `Projections(s) <Projection>` or

their `sender <Projection_Base.sender>`\\s (all of which must be the same length) is used to determine the `variable

<InputPort.variable>` of the InputPort.

If an InputPort is created using its constructor, and a Mechanism is specified in the **owner** argument,

it is automatically assigned to that Mechanism.  Note that its `value <InputPort.value>` (generally determined

by the size of its `variable <InputPort.variable>` -- see `below <InputPort_Variable_and_Value>`) must

be compatible (in number and type of elements) with the item of its owner's `variable <Mechanism_Base.variable>` to

which it is assigned (see `below <InputPort_Variable_and_Value>` and `Mechanism <Mechanism_Variable_and_InputPorts>`).

If the **owner** argument is not specified, `initialization <Port_Deferred_Initialization>` is deferred.

.. _InputPort_Deferred_Initialization:

*Owner Assignment and Deferred Initialization*

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

An InputPort must be owned by a `Mechanism <Mechanism>`.  When InputPort is specified in the constructor for a

Mechanism (see `below <InputPort_Specification>`), it is automatically assigned to that Mechanism as its owner. If

the InputPort is created on its own, its `owner <Port_Base.owner>` can specified in the **owner**  argument of its

constructor, in which case it is assigned to that Mechanism. If its **owner** argument is not specified, its

initialization is `deferred <Port_Deferred_Initialization>` until

COMMENT:

TBI: its `owner <Port_Base.owner>` attribute is assigned or

COMMENT

the InputPort is assigned to a Mechanism using the Mechanism's `add_ports <Mechanism_Base.add_ports>` method.

.. _InputPort_Primary:

*Primary InputPort*

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

Every Mechanism has at least one InputPort, referred to as its *primary InputPort*.  If InputPorts are not

`explicitly specified <InputPort_Specification>` for a Mechanism, a primary InputPort is automatically created

and assigned to its `input_port <Mechanism_Base.input_port>` attribute (note the singular), and also to the first

entry of the Mechanism's `input_ports <Mechanism_Base.input_ports>` attribute (note the plural).  The `value

<InputPort.value>` of the primary InputPort is assigned as the first (and often only) item of the Mechanism's

`variable <Mechanism_Base.variable>` and `input_values <Mechanism_Base.input_values>` attributes.

.. _InputPort_Specification:

*InputPort Specification*

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

Specifying InputPorts when a Mechanism is created

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

InputPorts can be specified for a `Mechanism <Mechanism>` when it is created, in the **input_ports** argument of the

Mechanism's constructor (see `examples <Port_Constructor_Argument_Examples>` in Port), or in an *INPUT_PORTS* entry

of a parameter dictionary assigned to the constructor's **params** argument.  The latter takes precedence over the

former (that is, if an *INPUT_PORTS* entry is included in the parameter dictionary, any specified in the

**input_ports** argument are ignored).

    .. _InputPort_Replace_Default_Note:

    .. note::

       Assigning InputPorts to a Mechanism in its constructor **replaces** any that are automatically generated for

       that Mechanism (i.e., those that it creates for itself by default).  If any of those are needed, they must be

       explicitly specified in the list assigned to the **input_ports** argument, or the *INPUT_PORTS* entry of the

       parameter dictionary in the **params** argument.  The number of InputPorts specified must also be equal to

       the number of items in the Mechanism's `variable <Mechanism_Base.variable>` attribute.

.. _InputPort_Variable_and_Value:

*InputPort's* `variable <InputPort.variable>`, `value <InputPort.value>` *and Mechanism's* `variable <Mechanism_Base.variable>`

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Each InputPort specified in the **input_ports** argument of a Mechanism's constructor must correspond to an item of

the Mechanism's `variable <Mechanism_Base.variable>` attribute (see `Mechanism <Mechanism_Variable_and_InputPorts>`),

and the `value <InputPort.value>` of the InputPort must be compatible with that item (that is, have the same number

and type of elements).  By default, this is also true of the InputPort's `variable <InputPort.variable>` attribute,

since the default `function <InputPort.function>` for an InputPort is a `LinearCombination`, the purpose of which

is to combine the inputs it receives and possibly modify the combined value (under the influence of any

`ModulatoryProjections <ModulatoryProjection>` it receives), but **not mutate its form**. Therefore, under most

circumstances, both the `variable <InputPort.variable>` of an InputPort and its `value <InputPort.value>` should

match the item of its owner's `variable <Mechanism_Base.variable>` to which the InputPort is assigned.

The format of an InputPort's `variable <InputPort.variable>` can be specified in a variety of ways.  The most

straightforward is in the **variable** argument of its constructor.  More commonly, however, it is determined by

the context in which it is being created, such as the specification for its owner Mechanism's `variable

<Mechanism_Base.variable>` or for the InputPort in the Mechanism's **input_ports** argument (see `below

<InputPort_Forms_of_Specification>` and `Mechanism InputPort specification <Mechanism_InputPort_Specification>`

for details).

Adding InputPorts to a Mechanism after it is created

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

InputPorts can also be **added** to a Mechanism, either by creating the InputPort on its own, and specifying the

Mechanism in the InputPort's **owner** argument, or by using the Mechanism's `add_ports <Mechanism_Base.add_ports>`

method (see `examples <Port_Create_Port_Examples>` in Port).

    .. _InputPort_Add_Port_Note:

    .. note::

       Adding InputPorts *does not replace* any that the Mechanism generates by default;  rather they are added to the

       Mechanism, and appended to the list of InputPorts in its `input_ports <Mechanism_Base.input_ports>` attribute.

       Importantly, the Mechanism's `variable <Mechanism_Base.variable>` attribute is extended with items that

       correspond to the `value <InputPort.value>` attribute of each added InputPort.  This may affect the

       relationship of the Mechanism's `variable <Mechanism_Base.variable>` to its `function

       <Mechanism_Base.function>`, as well as the number of its `OutputPorts <OutputPort>` (see `note

       <Mechanism_Add_InputPorts_Note>`).

If the name of an InputPort added to a Mechanism is the same as one that already exists, its name is suffixed with a

numerical index (incremented for each InputPort with that name; see `Registry_Naming`), and the InputPort is added to

the list (that is, it will *not* replace ones that already exist).

.. _InputPort_Forms_of_Specification:

Forms of Specification

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

InputPorts can be specified in a variety of ways, that fall into three broad categories:  specifying an InputPort

directly; use of a `Port specification dictionary <Port_Specification>`; or by specifying one or more Components that

should project to the InputPort. Each of these is described below:

    .. _InputPort_Direct_Specification:

    **Direct Specification of an InputPort**

    * existing **InputPort object** or the name of one -- If this is used to specify an InputPort in the

      constructor for a Mechanism, its `value <InputPort.value>` must be compatible with the corresponding item of

      the owner Mechanism's `variable <Mechanism_Base.variable>` (see `Mechanism InputPort specification

      <Mechanism_InputPort_Specification>` and `InputPort_Compatability_and_Constraints` below).  If the InputPort

      belongs to another Mechanism, then an InputPort is created along with Projections(s) that `shadow the inputs

      <InputPort_Shadow_Inputs>` to the specified InputPort.

    ..

    * **InputPort class**, **keyword** *INPUT_PORT*, or a **string** -- this creates a default InputPort; if used

      to specify an InputPort in the constructor for a Mechanism, the item of the owner Mechanism's `variable

      <Mechanism_Base.variable>` to which the InputPort is assigned is used as the format for the InputPort`s

      `variable <InputPort.variable>`; otherwise, the default for the InputPort is used.  If a string is specified,

      it is used as the `name <InputPort.name>` of the InputPort (see `example <Port_Constructor_Argument_Examples>`).

    .. _InputPort_Specification_by_Value:

    * **value** -- this creates a default InputPort using the specified value as the InputPort's `variable

      <InputPort.variable>`; if used to specify an InputPort in the constructor for a Mechanism, the format must be

      compatible with the corresponding item of the owner Mechanism's `variable <Mechanism_Base.variable>` (see

      `Mechanism InputPort specification <Mechanism_InputPort_Specification>`, `example

      <port_value_Spec_Example>`, and discussion `below <InputPort_Compatability_and_Constraints>`).

    .. _InputPort_Specification_Dictionary:

    **InputPort Specification Dictionary**

    * **InputPort specification dictionary** -- this can be used to specify the attributes of an InputPort, using

      any of the entries that can be included in a `Port specification dictionary <Port_Specification>` (see

      `examples <Port_Specification_Dictionary_Examples>` in Port).  If the dictionary is used to specify an

      InputPort in the constructor for a Mechanism, and it includes a *VARIABLE* and/or *VALUE* entry, the value

      must be compatible with the item of the owner Mechanism's `variable <Mechanism_Base.variable>` to which the

      InputPort is assigned (see `Mechanism InputPort specification <Mechanism_InputPort_Specification>`).

      The *PROJECTIONS* entry can include specifications for one or more Ports, Mechanisms and/or Projections that

      should project to the InputPort (including both `MappingProjections <MappingProjection>` and/or

      `ModulatoryProjections <ModulatoryProjection>`; however, this may be constrained by or have consequences for the

      InputPort's `variable <InputPort.variable>` (see `InputPort_Compatability_and_Constraints`).

      In addition to the standard entries of a `Port specification dictionary <Port_Specification>`, the dictionary

      can also include either or both of the following entries specific to InputPorts:

      * *WEIGHT*:<number>

          the value must be an integer or float, and is assigned as the value of the InputPort's `weight

          <InputPort.weight>` attribute (see `weight and exponent <InputPort_Weights_And_Exponents>`);

          this takes precedence over any specification in the **weight** argument of the InputPort's constructor.

      * *EXPONENT*:<number>

          the value must be an integer or float, and is assigned as the value of the InputPort's `exponent

          <InputPort.exponent>` attribute (see `weight and exponent <InputPort_Weights_And_Exponents>`);

          this takes precedence over any specification in the **exponent** argument of the InputPort's constructor.

    .. _InputPort_Projection_Source_Specification:

    **Specification of an InputPort by Components that Project to It**

    COMMENT:

    `examples

      <Port_Projections_Examples>` in Port)

    COMMENT

    COMMENT:

    ?? PUT IN ITS OWN SECTION ABOVE OR BELOW??

    Projections to an InputPort can be specified either as attributes, in the constructor for an

    InputPort (in its **projections** argument or in the *PROJECTIONS* entry of an `InputPort specification dictionary

    <InputPort_Specification_Dictionary>`), or used to specify the InputPort itself (using one of the

    `InputPort_Forms_of_Specification` described above. See `Port Projections <Port_Projections>` for additional

    details concerning the specification of

    Projections when creating a Port.

    COMMENT

    An InputPort can also be specified by specifying one or more Ports, Mechanisms or Projections that should project

    to it, as described below.  Specifying an InputPort in this way creates both the InputPort and any of the

    specified or implied Projection(s) to it (if they don't already exist). `MappingProjections <MappingProjection>`

    are assigned to the InputPort's `path_afferents <Port_Base.path_afferents>` attribute, while `ControlProjections

    <ControlProjection>` and `GatingProjections <GatingProjection>` to its `mod_afferents <Port_Base.mod_afferents>`

    attribute. Any of the following can be used to specify an InputPort by the Components that projection to it (see

    `below <InputPort_Compatability_and_Constraints>` for an explanation of the relationship between the `value` of

    these Components and the InputPort's `variable <InputPort.variable>`):

    * **OutputPort, GatingSignal, Mechanism, or list with any of these** -- creates an InputPort with Projection(s)

      to it from the specified Port(s) or Mechanism(s).  For each Mechanism specified, its `primary OutputPort

      <OutputPort_Primary>` (or GatingSignal) is used.

    ..

    * **Projection** -- any form of `Projection specification <Projection_Specification>` can be

      used;  creates an InputPort and assigns it as the Projection's `receiver <Projection_Base.receiver>`.

    .. _InputPort_Tuple_Specification:

    * **InputPort specification tuples** -- these are convenience formats that can be used to compactly specify an

      InputPort and Projections to it any of the following ways:

        .. _InputPort_Port_Mechanism_Tuple:

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

          `OutputPort` or `ModulatorySignal`, or a list of such names, and the 2nd item must be the Mechanism to

          which they all belong.  Projections of the relevant types are created for each of the specified Ports

          (see `Port 2-item tuple <Port_2_Item_Tuple>` for additional details).

        * **2-item tuple:** *(<value, Port specification, or list of Port specs>, <Projection specification>)* --

          this is a contracted form of the 4-item tuple described below;

        * **3 or 4-item tuple:** *(<value, Port spec, or list of Port specs>, weight, exponent, Projection

          specification)* -- this allows the specification of Port(s) that should project to the InputPort, together

          with a specification of the InputPort's `weight <InputPort.weight>` and/or `exponent <InputPort.exponent>`

          attributes of the InputPort, and (optionally) the Projection(s) to it.  This can be used to compactly

          specify a set of Ports that project the InputPort, while using the 4th item to determine its variable

          (e.g., using the matrix of the Projection specification) and/or attributes of the Projection(s) to it. Each

          tuple must have at least the following first three items (in the order listed), and can include the fourth:

            * **value, Port specification, or list of Port specifications** -- specifies either the `variable

              <InputPort.variable>` of the InputPort, or one or more Ports that should project to it.  The Port

              specification(s) can be a (Port name, Mechanism) tuple (see above), and/or include Mechanisms (in which

              case their `primary OutputPort <OutputPort_Primary>` is used.  All of the Port specifications must be

              consistent with (that is, their `value <Port_Base.value>` must be compatible with the `variable

              <Projection_Base.variable>` of) the Projection specified in the fourth item if that is included;

            * **weight** -- must be an integer or a float; multiplies the `value <InputPort.value>` of the InputPort

              before it is combined with others by the Mechanism's `function <Mechanism_Base.function>` (see

              ObjectiveMechanism for `examples <ObjectiveMechanism_Weights_and_Exponents_Example>`);

            * **exponent** -- must be an integer or float; exponentiates the `value <InputPort.value>` of the

              InputPort before it is combined with others by the ObjectiveMechanism's `function

              <ObjectiveMechanism.function>` (see ObjectiveMechanism for `examples

              <ObjectiveMechanism_Weights_and_Exponents_Example>`);

            * **Projection specification** (optional) -- `specifies a Projection <Projection_Specification>` that

              must be compatible with the Port specification(s) in the 1st item; if there is more than one Port

              specified, and the Projection specification is used, all of the Ports

              must be of the same type (i.e.,either OutputPorts or GatingSignals), and the `Projection

              Specification <Projection_Specification>` cannot be an instantiated Projection (since a

              Projection cannot be assigned more than one `sender <Projection_Base.sender>`).

    .. _InputPort_Shadow_Inputs:

    * **InputPorts of Mechanisms to shadow** -- either of the following can be used to create InputPorts that

      receive the same inputs as ("shadow") the ones specified:

      * *InputPort or [InputPort, ...]* -- each InputPort must belong to an existing Mechanism; creates a new

        InputPort for each one specified, along with Projections to it that parallel those of the one specified

        (see below).

      * *{SHADOW_INPUTS: <InputPort or Mechanism or [<InputPort or Mechanism>,...]>}* -- any InputPorts specified

        must belong to an existing Mechanism;  creates a new InputPort for each one specified, and for each of the

        InputPorts belonging to any Mechanisms specified, along with Projections to them that parallel those of the

        one(s) specified (see below).

      For each InputPort specified, and all of the InputPorts belonging to any Mechanisms specified, a new InputPort

      is created along with Projections to it that parallel those received by the corresponding InputPort in the list.

      That is, for each InputPort specified, one is created that receives exactly the same inputs from the same `senders

      <Projection_Base.sender>` as the ones specified (see `examples <InputPort_Shadow_Inputs_Figures>` below).

      If an InputPort shadows another, its `shadow_inputs <InputPort.shadow_inputs>` attribute identifies the InputPort

      that it shadows.

      .. _InputPort_Shadow_Nested_Note:

      .. note::

         Only InputPorts belonging to Mechanisms in the *same Composition*, or ones that are `INPUT <NodeRole.INPUT>`

         `Nodes <Composition_Nodes>` of a `nested <Composition_Nested>` can be specified for shadowing.  Note also that

         any Node that shadows an `INPUT <NodeRole.INPUT>` `Node <Composition_Nodes>` of the Composition to which it

         belongs is itself also assigned the role of `INPUT <NodeRole.INPUT>` Node.

      .. hint::

         If an InputPort needs to be shadowed that belongs to a Mechanism in a `nested <Composition_Nested>` that is

         not an `INPUT <NodeRole.INPUT>` `Node <Composition_Nodes>` of that Composition, this can be accomplished in

         one of two ways:  1) by assigning it `INPUT <NodeRole.INPUT>` as a `required NodeRole

         <Composition_Node_Role_Assignment>` where it is added to the nested Composition; and/or 2) by doing the

         following: a) add a Mechanism to the nested Composition with an InputPort that shadows the one to be

         shadowed; b) specify `INPUT <NodeRole.INPUT>` in the **required_roles** argument of the Composition's

         `Composition.add_node` method used to add that Mechanism to the Composition;  c) use that Mechanism as the

         `InputPort specification <InputPort_Specification>` for the shadowing InputPort.

      .. _InputPort_Shadow_Inputs_Figures:

                                        **Examples of InputPort Shadowing**

      .. figure:: _static/input_port_shadowing_1.svg

         :scale: 50 %

         :alt: Simple Shadowing

         **Simple case of shadowing**. The figure above shows a simple case in which ``Shadowing Mech`` is configured

         to shadow the input to ``Shadowed Mech``, as specified below::

            >>> A = ProcessingMechanism(name='Mech')

            >>> B = ProcessingMechanism(name='Shadowed Mech')

            >>> C = ProcessingMechanism(name='Shadowing Mech', input_ports=B.input_port)

            >>> ocomp = Composition(pathways=[[A, B], C],

            ...                     show_graph_attributes={'direction':'LR'})

            >>> ocomp.show_graph(show_node_structure=True)

      .. figure:: _static/input_port_shadowing_2.svg

         :alt: Shadowing Nested Mechanism

         **Shadowing a nested Mechanism**. This example shows a Composition in which the `InputPort` of

         ``shadowing_mech`` is configured to shadow the input to ``mech`` in ``nested_comp``. Accordingly

         ``shadowing_mech`` receives a Projection from the same Port of ``outer_comp``'s `input_CIM

         <Composition.input_CIM>` as the `input_CIM <Composition.input_CIM>` of ``nested_comp`` that projects to

         ``mech``. As a result, ``shadowing_mech`` will receive the same input as ``mech`` when ``outer_comp``

         is executed (as noted `above <InputPort_Shadow_Nested_Note>`, only the `INPUT <NodeRole.INPUT>` `Nodes

         <Composition_Nodes>` of a `nested Composition <Composition_Nested>` can be shadowed)::

             >>> import psyneulink as pnl

             >>> mech = pnl.ProcessingMechanism(name='Mech')

             >>> shadowing_mech = pnl.ProcessingMechanism(name='Shadowing Mech',

             ...                                      input_ports=mech.input_port)

             >>> nested_comp = pnl.Composition([mech], name='Nested Composition')

             >>> outer_comp = pnl.Composition(nodes=[nested_comp, shadowing_mech],

             ...                              name='Outer Composition')

             ...                              show_graph_attributes={'direction':'LR'})

             >>> outer_comp.show_graph(show_node_structure=True, show_cim=True)

.. _InputPort_Compatability_and_Constraints:

InputPort `variable <InputPort.variable>`: Compatibility and Constraints

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

The `variable <InputPort.variable>` of an InputPort must be compatible with the item of its owner Mechanism's

`variable <Mechanism_Base.variable>` to which it is assigned (see `Mechanism <Mechanism_Variable_and_InputPorts>`).

This may have consequences that must be taken into account when `specifying an InputPort by Components that project

to it <InputPort_Projection_Source_Specification>`.  These depend on the context in which the specification is made,

and possibly the value of other specifications.  These considerations and how they are handled are described below,

starting with constraints that are given the highest precedence:

  *  **InputPort is** `specified in a Mechanism's constructor <Mechanism_InputPort_Specification>` and the

    **default_variable** argument for the Mechanism is also specified -- the item of the variable to which the

    `InputPort is assigned <Mechanism_Variable_and_InputPorts>` is used to determine the InputPort's `variable must

    <InputPort.variable>`.  Any other specifications of the InputPort relevant to its `variable <InputPort.variable>`

    must be compatible with this (for example, `specifying it by value <InputPort_Specification_by_Value>` or by a

    `MappingProjection` or `OutputPort` that projects to it (see `above <InputPort_Projection_Source_Specification>`).

    COMMENT:

    ***XXX EXAMPLE HERE

    COMMENT

  ..

  * **InputPort is specified on its own**, or the **default_variable** argument of its Mechanism's constructor

    is not specified -- any direct specification of the InputPort's `variable <InputPort.variable>` is used to

    determine its format (e.g., `specifying it by value <InputPort_Specification_by_Value>`, or a *VARIABLE* entry

    in an `InputPort specification dictionary <InputPort_Specification_Dictionary>`.  In this case, the value of any

    `Components used to specify the InputPort <InputPort_Projection_Source_Specification>` that are relevant to its

    `variable <InputPort.variable>` must be compatible with it (see below).

    COMMENT:

    ***XXX EXAMPLE HERE

    COMMENT

  ..

  * If the InputPort's `variable <InputPort.variable>` is not constrained by any of the conditions above,

    then its format is determined by the `specification of Components that project to it

    <InputPort_Projection_Source_Specification>`:

    * **More than one Component is specified with the same `value` format** -- that format is used to determine

      the format of the InputPort's `variable <InputPort.variable>`.

    * **More than one Component is specified with different `value` formats** -- the InputPort's `variable

      <InputPort.variable>` is determined by item of the default `variable <Mechanism_Base.variable>` for

      the class of its owner Mechanism.

    * **A single Component is specified** -- its `value` is used to determine the format of the InputPort's

      `variable <InputPort.variable>`;  if the Component is a(n):

      * **MappingProjection** -- can be specified by its class, an existing MappingProjection, or a matrix:

        * `MappingProjection` **class** -- a default value is used both the for the InputPort's `variable

          <InputPort.variable>` and the Projection's `value <Projection_Base.value>` (since the Projection's

          `sender <Projection_Base.sender>` is unspecified, its `initialization is deferred

          <Projection_Deferred_Initialization>`.

        * **Existing MappingProjection** -- then its `value <Projection_Base.value>` determines the

          InputPort's `variable <InputPort.variable>`.

        * `Matrix specification <MappingProjection_Matrix_Specification>` -- its receiver dimensionality determines the

          format of the InputPort's `variable <InputPort.variable>`. For a standard 2d "weight" matrix (i.e., one that

          maps a 1d array from its `sender <Projection_Base.sender>` to a 1d array of its `receiver

          <Projection_Base.receiver>`), the receiver dimensionality is its outer dimension (axis 1, or its number of

          columns).  However, if the `sender <Projection_Base.sender>` has more than one dimension, then the

          dimensionality of the receiver (used for the InputPort's `variable <InputPort.variable>`) is the

          dimensionality of the matrix minus the dimensionality of the sender's `value <OutputPort.value>`

          (see `matrix dimensionality <Mapping_Matrix_Dimensionality>`).

      * **OutputPort or ProcessingMechanism** -- the `value <OutputPort.value>` of the OutputPort (if it is a

        Mechanism, then its `primary OutputPort <OutputPort_Primary>`) determines the format of the InputPort's

        `variable <InputPort.variable>`, and a MappingProjection is created from the OutputPort to the InputPort

        using an `IDENTITY_MATRIX`.  If the InputPort's `variable <InputPort.variable>` is constrained (as in some

        of the cases above), then a `FULL_CONNECTIVITY_MATRIX` is used which maps the shape of the OutputPort's `value

        <OutputPort.value>` to that of the InputPort's `variable <InputPort.variable>`.

      * **GatingProjection, GatingSignal or GatingMechanism** -- any of these can be used to specify an InputPort;

        their `value` does not need to be compatible with the InputPort's `variable <InputPort.variable>`, however

        it does have to be compatible with the `modulatory parameter <Function_Modulatory_Params>` of the InputPort's

        `function <InputPort.function>`.

.. _InputPort_Structure:

Structure

---------

Every InputPort is owned by a `Mechanism <Mechanism>`. It can receive one or more `MappingProjections

<MappingProjection>` from other Mechanisms or itself (e.g., `RecurrentTransferMechanism`), as well as from the

Composition to which its owner belongs (if it is the `ORIGIN` Mechanism for that Process or System).  It has the

following attributes, that includes ones specific to, and that can be used to customize the InputPort:

* `projections <Port_Base.projections>` -- all of the `Projections <Projection>` received by the InputPort.

.. _InputPort_Afferent_Projections:

* `path_afferents <Port_Base.path_afferents>` -- `MappingProjections <MappingProjection>` that project to the InputPort,

  the `value <Projection_Base.value>`\\s of which are combined by the InputPort's `function <InputPort.function>`,

  possibly `modulated <ModulatorySignal_Modulation>` by one or more `mod_afferent <Port_Base.mod_afferents>`

  `GatingProjections <GatingProjection>`, and assigned to the corresponding item of the owner Mechanism's

  `variable <Mechanism_Base.variable>`.

* `mod_afferents <Port_Base.mod_afferents>` -- `GatingProjections <GatingProjection>` that project to the

  InputPort, the `value <GatingProjection.value>` of which can modify the InputPort's `value <InputPort.value>`

  (see the descriptions of Modulation under `ModulatorySignals <ModulatorySignal_Modulation>` and `GatingSignals

  <GatingSignal_Modulation>` for additional details).  If the InputPort receives more than one GatingProjection,

  their values are combined before they are used to modify the `value <InputPort.value>` of InputPort.

  .. _InputPort_Internal_Only:

* `internal_only <InputPort.internal_only>` -- specifies whether an InputPort that belongs to an `INPUT

  <NodeRole.INPUT>` `Node <Composition_Nodes>` of a `Composition` receives `Projections <Projection>` *only from*

  other `Nodes <Composition_Nodes>` *within* the Composition to which its `owner <Port_Base.owner>` belongs; such

  InputPorts do not receive any `external inputs <Composition_Execution_Inputs>` to that Composition when it is

  `executed <Composition_Execution>` (see `Composition inputs <Composition_Input_External_InputPorts>`

  for additional information).

.. _InputPort_Variable:

* `variable <InputPort.variable>` -- serves as the template for the `value <Projection_Base.value>` of the

  `Projections <Projection>` received by the InputPort:  each must be compatible with (that is, match both the

  number and type of elements of) the InputPort's `variable <InputPort.variable>` (see `matrix <Mapping_Matrix>`

  for additional details). In general, this must also be compatible with the item of the owner Mechanism's `variable

  <Mechanism_Base.variable>` to which the InputPort is assigned (see `above <InputPort_Variable_and_Value>` and

  `Mechanism InputPort specification <Mechanism_InputPort_Specification>`).  The InputPort's `variable

  <InputPort.variable>` is composed of the concatenated `values <Projection_Base.value>` of its `path_afferent

  <Port_Base.path_afferents>` Projections.  If it has none, then the `variable <InputPort.variable>` is either assigned

  None or its `default value <Parameter_Defaults>`, as determined by its `default_input <InputPort.default_input>`

  setting.

.. _InputPort_Function:

* `function <InputPort.function>` -- combines the `value <Projection_Base.value>` of all of the `path_afferent

  <InputPort.path_afferents>` `Projections <Projection>` received by the InputPort, and assigns the result to the

  InputPort's `value <InputPort.value>` attribute.  The default function is `LinearCombination` that performs an

  elementwise (Hadamard) sum of the afferent values. However, the parameters of the `function <InputPort.function>`

  -- and thus the `value <InputPort.value>` of the InputPort -- can be modified by any `GatingProjections

  <GatingProjection>` received by the InputPort (listed in its `mod_afferents <Port_Base.mod_afferents>` attribute.

  A custom function can also be specified, so long as it generates a result that is compatible with the item of the

  Mechanism's `variable <Mechanism_Base.variable>` to which the `InputPort is assigned <Mechanism_InputPorts>`.

.. _InputPort_Value:

* `value <InputPort.value>` -- the result returned by its `function <InputPort.function>`,

  after aggregating the value of the `PathProjections <PathwayProjection>` it receives, possibly modified by any

  `GatingProjections <GatingProjection>` received by the InputPort. It must be compatible with the

  item of the owner Mechanism's `variable <Mechanism_Base.variable>` to which the `InputPort has been assigned

  <Mechanism_InputPorts>` (see `above <InputPort_Variable_and_Value>` and `Mechanism InputPort specification

  <Mechanism_InputPort_Specification>`).

.. _InputPort_Weights_And_Exponents:

* `weight <InputPort.weight>` and `exponent <InputPort.exponent>` -- these can be used by the Mechanism to which the

  InputPort belongs when that combines the `value <InputPort.value>`\\s of its Ports (e.g., an ObjectiveMechanism

  uses the weights and exponents assigned to its InputPorts to determine how the values it monitors are combined by

  its `function <ObjectiveMechanism>`).  The value of each must be an integer or float, and the default is 1 for both.

.. _InputPort_Execution:

Execution

---------

An InputPort cannot be executed directly.  It is executed when the Mechanism to which it belongs is executed.

When this occurs, the InputPort executes any `Projections <Projection>` it receives, calls its `function

<InputPort.function>` to combine the values received from any `MappingProjections <MappingProjection>` it receives

(listed in its its `path_afferents  <Port_Base.path_afferents>` attribute) and modulate them in response to any

`GatingProjections <GatingProjection>` (listed in its `mod_afferents <Port_Base.mod_afferents>` attribute),

and then assigns the result to the InputPort's `value <InputPort.value>` attribute. This, in turn, is assigned to

the item of the Mechanism's `variable <Mechanism_Base.variable>` and `input_values <Mechanism_Base.input_values>`

attributes  corresponding to that InputPort (see `Mechanism Variable and InputPorts <Mechanism_Variable_and_InputPorts>`

for additional details).  If an InputPort does not have any `path_afferent Projections <Port_Base.path_afferents>`,

by default its value is set to None which, when executed, generates an error;  however, if its `default_input

<InputPort.default_input>` attribute is *DEFAULT_VARIABLE*, then the `default value <Parameter_Defaults>` for the

InputPort's `variable <InputPort.variable>` is used as its value (see `default_input <InputPort.default_input>` for

additional details).

.. _InputPort_Class_Reference:

Class Reference

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

"""

    COMBINE, CONTROL_SIGNAL, DEFAULT_INPUT, DEFAULT_VARIABLE, EXPONENT, FUNCTION, GATING_SIGNAL, \

    INPUT_PORT, INPUT_PORTS, INPUT_PORT_PARAMS, \

    LEARNING_SIGNAL, MAPPING_PROJECTION, MATRIX, NAME, OPERATION, OUTPUT_PORT, OUTPUT_PORTS, OWNER, \

    PARAMS, PROJECTIONS, REFERENCE_VALUE, \

    SENDER, SHADOW_INPUTS, SHADOW_INPUT_NAME, INPUT_SHAPES, PORT_TYPE, SUM, VALUE, VARIABLE, WEIGHT

    append_type_to_name, is_numeric_scalar, convert_to_np_array, is_numeric, iscompatible, kwCompatibilityLength, convert_to_list, parse_valid_identifier

    'InputPort', 'InputPortError', 'port_type_keywords', 'SHADOW_INPUTS',

]

# InputPortPreferenceSet = BasePreferenceSet(log_pref=logPrefTypeDefault,

#                                                          reportOutput_pref=reportOutputPrefTypeDefault,

#                                                          verbose_pref=verbosePrefTypeDefault,

#                                                          param_validation_pref=paramValidationTypeDefault,

#                                                          level=PreferenceLevel.TYPE,

#                                                          name='InputPortClassPreferenceSet')

    """

    InputPort(                                     \

        variable=None,                             \

        reference_value=None,                      \

        function=LinearCombination(operation=SUM), \

        combine=None,                              \

        projections=None,                          \

        weight=None,                               \

        exponent=None,                             \

        internal_only=False)

    Subclass of `Port <Port>` that calculates and represents the input to a `Mechanism <Mechanism>` from one or more

    `PathwayProjections <PathwayProjection>`.  See `Port_Class_Reference` for additional arguments and attributes.

    COMMENT:

    PortRegistry

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

        All InputPorts are registered in PortRegistry, which maintains an entry for the subclass,

        a count for all instances of it, and a dictionary of those instances

    COMMENT

    Arguments

    ---------

    reference_value : number, list or np.ndarray

        the value of the item of the owner Mechanism's `variable <Mechanism_Base.variable>` attribute to which

        the InputPort is assigned; used as the template for the InputPort's `value <InputPort.value>` attribute.

    default_input : None or DEFAULT_VARIABLE : default None

        specifies value to use as variable if the InputPort has no `path_afferent <Port_Base.path_afferents>`

        `Projections <Projection>`. If None (the default), then None is returned; otherwise the `default value

        <Parameter_Defaults>` for the InputPort's `variable <InputPort.variable>` is used (see `default_input

        <InputPort.default_input>` for additional details).

    variable : number, list or np.ndarray

        specifies the shape of the  InputPort's `variable <InputPort.variable>`, which may be used to define the

        shape of the `matrix <MappingProjection.matrix>` parameter of the `MappingProjection` that projects to the

        Inputport (see `variable <InputPort_Variable>` for additional details).

    function : Function or method : default LinearCombination(operation=SUM)

        specifies the function applied to the variable. The default value combines the `values

        <Projection_Base.value>` of the `Projections <Projection>` received by the InputPort.  Any function

        can be assigned, however:  a) it must produce a result that has the same format (number and type of elements)

        as the item of its owner Mechanism's `variable <Mechanism_Base.variable>` to which the InputPort has been

        assigned;  b) if it is not a TransformFunction, it may produce unpredictable results if the InputPort

        receives more than one Projection (see `function <InputPort.function>`.

    combine : SUM or PRODUCT : default None

        specifies the **operation** argument used by the default `LinearCombination` function, which determines how

        the `value <Projection_Base.value>` of the InputPort's `projections <Port_Base.projections>` are combined.

        This is a convenience argument, that allows the **operation** to be specified without having to specify the

        LinearCombination function; it assumes that LinearCombination (the default) is used as the InputPort's function

        -- if it conflicts with a specification of **function** an error is generated.

    projections : list of Projection specifications

        specifies the `MappingProjection(s) <MappingProjection>`, `ControlProjection(s) <ControlProjection>` and/or

        `GatingProjection(s) <GatingProjection>` to be received by the InputPort, and that are listed in its

        `path_afferents <Port_Base.path_afferents>` and `mod_afferents <Port_Base.mod_afferents>` attributes,

        respectively (see `InputPort_Compatability_and_Constraints` for additional details).  If **projections** but

        neither **variable** nor **input_shapes** are specified, then the `value <Projection_Base.value>` of the Projection(s)

        or their `senders <Projection_Base.sender>` specified in **projections** argument are used to determine the

        InputPort's `variable <InputPort.variable>`.

    weight : number : default 1

        specifies the value of the `weight <InputPort.weight>` attribute of the InputPort.

    exponent : number : default 1

        specifies the value of the `exponent <InputPort.exponent>` attribute of the InputPort.

    internal_only : bool : False

        specifies whether the InputPort requires external input when its `owner <Port_Base.owner>` is the `INPUT`

        `Node <Composition_Nodes>` of a `Composition (see `internal_only <InputPort.internal_only>` for details).

    Attributes

    ----------

    variable : value, list or np.ndarray

        the template for the `value <Projection_Base.value>` of each Projection that the InputPort receives,

        each of which must match the format (number and types of elements) of the InputPort's

        `variable <InputPort.variable>`.  If neither the **variable** or **input_shapes** argument is specified, and

        **projections** is specified, then `variable <InputPort.variable>` is assigned the `value

        <Projection_Base.value>` of the Projection(s) or its `sender <Projection_Base.sender>`.

    default_input : None or DEFAULT_VARIABLE

        determines the value used as `variable <InputPort.variable>` if the InputPort has no `path_afferent

        <Port_Base.path_afferent>` `Projections <Projection>`. If None (the default), then None is used. This is the

        default behavior, as it is useful for identifying "orphaned" InputPorts (i.e., ones that do not receive

        any inputs) and the `Mechanisms <Mechanism>` to which they belong, as an error is returned if an InputPort

        is executed and its variable is assigned None. If *default_input* is assigned *DEFAULT_VARIABLE*, then the

        `default value <Parameter_Defaults>` for the InputPort's `variable <InputPort.variable>` is used as its value.

        This  is useful for assignment to a Mechanism that needs a constant (i.e., fixed value) as the input to its

        `function <Mechanism_Base.function>` (such as a `bias unit <AutodiffComposition_Bias_Parameters>` in an

        `AutodiffComposition`).

        .. note::

           If `default_input <InputPort.default_input>` is assigned *DEFAULT_VARIABLE*, then its `internal_only

           <InputPort.internal_only>` attribute is automatically assigned True. This is so that if the `Mechanism`

           to which the InputPort belongs is assigned to a `Composition`, it is not treated as an `INPUT

           <NodeRole.INPUT>` `Node <Composition_Nodes>` of that Composition (and automatically assigned a Projection

           from its `input_CIM <Composition.input_CIM>`.

    input_shape : 1d array

        shows the shape of the input to the InputPort;  that is, the shape of the `value <Projection_Base.value>`

        expected for any `path_afferent Projections <Port_Base.path_afferents>`.

    function : Function

        if it is a `TransformFunction <Transformfunctions>`, it combines the `values <Projection_Base.value>` of

        the `PathwayProjections <PathwayProjection>` (e.g., `MappingProjections <MappingProjection>`) received by the

        InputPort  (listed in its `path_afferents <Port_Base.path_afferents>` attribute), under the possible

        influence of `GatingProjections <GatingProjection>` received by the InputPort (listed in its `mod_afferents

        <Port_Base.mod_afferents>` attribute). The result is assigned to the InputPort's `value <InputPort.value>`

        attribute. For example, the the default (`LinearCombination` with *SUM* as it **operation**) performs an

        element-wise (Hadamard) sum of its Projection `values <Projection_Base.value>`, and assigns to `value

        <InputPort.value>` an array that is of the same length as each of the Projection `values

        <Projection_Base.value>`.  If the InputPort receives only one Projection, then any other function can be

        applied and it will generate a value that is the same length as the Projection's `value

        <Projection_Base.value>`. However, if the InputPort receives more than one Projection and

        uses a function other than a TransformFunction, a warning is generated and only the `value

        <Projection_Base.value>` of the first Projection listed in `path_afferents <Port_Base.path_afferents>`

        is used by the function, which may generate unexpected results when executing the Mechanism or Composition

        to which it belongs.

    value : value or ndarray

        the output of the InputPort's `function <InputPort.function>`, that is assigned to an item of the owner

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

    label : string or number

        the string label that represents the current `value <InputPort.value>` of the InputPort, according to the

        owner mechanism's `input_labels_dict <Mechanism.input_labels_dict>`. If the current `value <InputPort.value>`

        of the InputPort does not have a corresponding label, then the numeric `value <InputPort.value>` is returned.

    weight : number

        see `weight and exponent <InputPort_Weights_And_Exponents>` for description.

    exponent : number

        see `weight and exponent <InputPort_Weights_And_Exponents>` for description.

    internal_only : bool

        determines whether `input from a Composition <Composition_Execution_Inputs>` must be specified for this

        InputPort from a Composition's `execution method <Composition_Execution_Methods>` if the InputPort's `owner

        <Port_Base.owner>` is an `INPUT` `Node <Composition_Nodes>` of that Composition; if `True`, external input is

        *not* required or allowed.

    shadow_inputs : InputPort

        identifies the InputPort of another `Mechanism` that is being shadowed by this InputPort.

    name : str

        the name of the InputPort; if it is not specified in the **name** argument of the constructor, a default is

        assigned by the InputPortRegistry of the Mechanism to which the InputPort belongs.  Note that some Mechanisms

        automatically create one or more non-default InputPorts, that have pre-specified names.  However, if any

        InputPorts are specified in the **input_ports** argument of the Mechanism's constructor, those replace those

        InputPorts (see `note <Mechanism_Default_Port_Suppression_Note>`), and `standard naming conventions

        <Registry_Naming>` apply to the InputPorts specified, as well as any that are added to the Mechanism once it

        is created (see `note <Port_Naming_Note>`).

    """

    #region CLASS ATTRIBUTES

                    LEARNING_SIGNAL,

                    GATING_SIGNAL,

                    CONTROL_SIGNAL

                    ]

    # Any preferences specified below will override those specified in TYPE_DEFAULT_PREFERENCES

    # Note: only need to specify setting;  level will be assigned to TYPE automatically

    # classPreferences = {

    #     PREFERENCE_SET_NAME: 'InputPortCustomClassPreferences',

    #     PREFERENCE_KEYWORD<pref>: <setting>...}

    # Note: the following enforce encoding as 1D np.ndarrays (one variable/value array per port)

        """

            Attributes

            ----------

                combine

                    see `combine <InputPort.combine>`

                    :default value: None

                    :type:

                default_input

                    see 'default_input <InputPort.default_input>`

                    :default value: None

                    :type: None or DEFAULT_VARIABLE

                exponent

                    see `exponent <InputPort.exponent>`

                    :default value: None

                    :type:

                function

                    see `function <InputPort_Function>`

                    :default value: `LinearCombination`

                    :type: `Function`

                internal_only

                    see `internal_only <InputPort.internal_only>`

                    :default value: False

                    :type: ``bool``

                shadow_inputs

                    specifies whether InputPort shadows inputs of another InputPort;

                    if not None, must be assigned another InputPort

                    :default value: None

                    :type:

                    :read only: True

                weight

                    see `weight <InputPort.weight>`

                    :default value: None

                    :type:

        """

                                  constructor_argument='default_input')

    #endregion

                 owner=None,

                 reference_value=None,

                 variable=None,

                 input_shapes=None,

                 default_input=None,

                 function=None,

                 projections=None,

                 combine: Optional[Literal['sum', 'product']] = None,

                 weight=None,

                 exponent=None,

                 internal_only: Optional[bool] = None,

                 params=None,

                 name=None,

                 prefs:   Optional[ValidPrefSet] = None,

                 context=None,

                 **kwargs):