PrincetonUniversity / PsyNeuLink / 11423570547

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

# ******************************************  OutputPort *****************************************************

"""

Contents

--------

* `OutputPort_Overview`

* `OutputPort_Creation`

    - `OutputPort_Deferred_Initialization`

    - `OutputPort_Primary`

    - `OutputPort_Specification`

        • `OutputPort_Forms_of_Specification`

        • `Variable and Value <OutputPort_Variable_and_Value>`

        • `Compatibility and Constraints <OutputPort_Compatibility_and_Constraints>`

        • `OutputPort_Standard`

        • `OutputPort_Customization`

            * `Custom Variable <OutputPort_Custom_Variable>`

            * `Custom Function <OutputPort_Custom_Function>`

* `OutputPort_Structure`

* `OutputPort_Execution`

* `OutputPort_Class_Reference`

.. _OutputPort_Overview:

Overview

--------

OutputPort(s) represent the result(s) of executing a Mechanism.  This may be the result(s) of its

`function <OutputPort.function>` and/or values derived from that result.  The full set of results are stored in the

Mechanism's `output_values <Mechanism_Base.output_values>` attribute.  OutputPorts are used to represent

individual items of the Mechanism's `value <Mechanism_Base.value>`, and/or useful quantities derived from

them.  For example, the `function <Mechanism_Base.function>` of a `TransferMechanism` generates

a single result (the transformed value of its input);  however, a TransferMechanism can also be assigned OutputPorts

that represent its mean, variance or other derived values.  In contrast, the `function <DDM.DDM.function>`

of a `DDM` Mechanism generates several results (such as decision accuracy and response time), each of which can be

assigned as the `value <OutputPort.value>` of a different OutputPort.  The OutputPort(s) of a Mechanism can serve

as the input to other  Mechanisms (by way of `projections <Projections>`), or as the output of a Process and/or

System.  The OutputPort's `efferents <Port_Base.efferents>` attribute lists all of its outgoing

projections.

.. _OutputPort_Creation:

Creating an OutputPort

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

An OutputPort can be created by calling its constructor. However, in general this is not necessary, as a Mechanism

automatically creates a default OutputPort if none is explicitly specified, that contains the primary result of its

`function <Mechanism_Base.function>`.  For example, if the Mechanism is created within the `pathway` of a

`Process <Process>`, an OutputPort is created and assigned as the `sender <MappingProjection.MappingProjection.sender>`

of a `MappingProjection` to the next Mechanism in the pathway, or to the Process' `output <Process_Input_And_Output>`

if the Mechanism is a `TERMINAL` Mechanism for that Process. Other configurations can also easily be specified using

a Mechanism's **output_ports** argument (see `OutputPort_Specification` below).  If it is created using its

constructor, and a Mechanism is specified in the **owner** argument, it is automatically assigned to that Mechanism.

If its **owner** is not specified, `initialization` is deferred.

.. _OutputPort_Deferred_Initialization:

*Owner Assignment and Deferred Initialization*

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

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

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

its owner. If the OutputPort is created directly, its `owner <Port.owner>` Mechanism can specified in the

**owner** argument of its constructor, in which case it is assigned to the specified Mechanism.  Otherwise, its

initialization is `deferred <Port_Deferred_Initialization>` until

COMMENT:

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

COMMENT

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

.. _OutputPort_Primary:

*Primary OutputPort*

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

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

`explicitly specified <OutputPort_Specification>` for a Mechanism, a primary OutputPort is automatically created

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

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

(note the plural).  The primary OutputPort is assigned an `index <OutputPort.index>` of '0', and therefore its

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

<Mechanism_Base.value>` attribute.

.. _OutputPort_Specification:

*OutputPort Specification*

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

Specifying OutputPorts when a Mechanism is created

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

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

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

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

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

**output_ports** argument are ignored).

    .. _OutputPort_Replace_Default_Note:

    .. note::

        Assigning OutputPorts 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 need to be retained, they

        must be explicitly specified in the list assigned to the **output_ports** argument or the *OUTPUT_PORTS* entry

        of the parameter dictionary in the **params** argument).  In particular, if the default OutputPort -- that

        usually contains the result of the Mechanism's `function <Mechanism_Base.function>` -- is to be retained,

        it too must be specified along with any additional OutputPorts desired.

Adding OutputPorts to a Mechanism after it is created

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

OutputPorts can also be added to a Mechanism, using the Mechanism's `add_ports <Mechanism_Base.add_methods>` method.

Unlike specification in the constructor, this **does not** replace any OutputPorts already assigned to the Mechanism.

Doing so appends them to the list of OutputPorts in the Mechanism's `output_ports <Mechanism_Base.output_ports>`

attribute, and their values are appended to its `output_values <Mechanism_Base.output_values>` attribute.  If the name

of an OutputPort added to a Mechanism is the same as one that is already exists on the Mechanism, its name is suffixed

with a numerical index (incremented for each OutputPort with that name; see `Registry_Naming`), and the OutputPort is

added to the list (that is, it does *not* replace the one that was already there).

.. _OutputPort_Variable_and_Value:

*OutputPorts* `variable <OutputPort.variable>` *and* `value <OutputPort.value>`

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

Each OutputPort created with or assigned to a Mechanism must reference one or more items of the Mechanism's attributes,

that serve as the OutputPort's `variable <OutputPort.variable>`, and are used by its `function <OutputPort.function>`

to generate the OutputPort's `value <OutputPort.value>`.  By default, it uses the first item of its `owner

<Port.owner>` Mechanism's `value <Mechanism_Base.value>`.  However, other attributes (or combinations of them)

can be specified in the **variable** argument of the OutputPort's constructor, or the *VARIABLE* entry in an

`OutputPort specification dictionary <OutputPort_Specification_Dictionary>` (see `OutputPort_Customization`).

The specification must be compatible (in the number and type of items it generates) with the input expected by the

OutputPort's `function <OutputPort.function>`. The OutputPort's `variable <OutputPort.variable>` is used as the

input to its `function <OutputPort.function>` to generate the OutputPort's `value <OutputPort.value>`, possibly

modulated by a `GatingSignal` (see `below <OutputPort_Modulatory_Projections>`).  The OutputPort's `value

<OutputPort.value>` must, in turn, be compatible with any Projections that are assigned to it, or `used to specify

it <OutputPort_Projection_Destination_Specification>`.

The `value <OutputPort.value>` of each OutputPort of a Mechanism is assigned to a corresponding item of the

Mechanism's `output_values <Mechanism_Base.output_values>` attribute, in the order in which they are assigned in

the **output_ports** argument of its constructor, and listed in its `output_ports <Mechanism_Base.output_ports>`

attribute.

    .. note::

       The `output_values <Mechanism_Base.output_values>` attribute of a Mechanism is **not the same** as its `value

       <Mechanism_Base.value>` attribute:

           * a Mechanism's `value <Mechanism.value>` attribute contains the full and unmodified results of its

             `function <Mechanism_Base.function>`;

           * a Mechanism's `output_values <Mechanism.output_values>` attribute contains a list of the `value

             <OutputPort.value>` of each of its OutputPorts.

.. _OutputPort_Forms_of_Specification:

Forms of Specification

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

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

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

which it should project. Each of these is described below:

    .. _OutputPort_Direct_Specification:

    **Direct Specification of an OutputPort**

    * existing **OutputPort object** or the name of one -- it cannot belong to another Mechanism, and the format of

      its `variable <OutputPort.variable>` must be compatible with the aributes of the `owner <Port.owner>`

      Mechanism specified for the OutputPort's `variable <OutputPort.variable>` (see `OutputPort_Customization`).

    ..

    * **OutputPort class**, **keyword** *OUTPUT_PORT*, or a **string** -- creates a default OutputPort that uses

      the first item of the `owner <Port.owner>` Mechanism's `value <Mechanism_Base.value>` as its `variable

      <OutputPort.variable>`, and assigns it as the `owner <Port.owner>` Mechanism's `primary OutputPort

      <OutputPort_Primary>`. If the class name or *OUTPUT_PORT* keyword is used, a default name is assigned to

      the Port; if a string is specified, it is used as the `name <OutputPort.name>` of the OutputPort

      (see `Registry_Naming`).

    .. _OutputPort_Specification_by_Variable:

    * **variable** -- creates an OutputPort using the specification as the OutputPort's `variable

      <OutputPort.variable>` (see `OutputPort_Customization`).  This must be compatible with (have the same number

      and type of elements as) the OutputPort's `function <OutputPort.function>`.  A default name is assigned based

      on the name of the Mechanism (see `Registry_Naming`).

    ..

    .. _OutputPort_Specification_Dictionary:

    **OutputPort Specification Dictionary**

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

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

      (see `examples <Port_Specification_Dictionary_Examples>` in Port), including:

      * *VARIABLE*:<keyword or list> - specifies the attribute(s) of its `owner <Port.owner>` Mechanism to use

        as the input to the OutputPort's `function <OutputPort.function>` (see `OutputPort_Customization`); this

        must be compatible (in the number and format of the items it specifies) with the OutputPort's `function

        <OutputPort.function>`.

      * *FUNCTION*:<`Function <Function>`, function or method> - specifies the function used to transform and/or

        combine the item(s) specified for the OutputPort's `variable <OutputPort.variable>` into its

        `value <OutputPort.value>`;  its input must be compatible (in the number and format of elements) with the

        specification of the OutputPort's `variable <OutputPort.variable>` (see `OutputPort_Customization`).

      * *PROJECTIONS* or *MECHANISMS*:<list of `Projections <Projection>` and/or `Mechanisms <Mechanism>`> - specifies

        one or more efferent `MappingProjections <MappingProjection>` from the OutputPort, Mechanims that should

        receive them, and/or `ModulatoryProjections <ModulatoryProjection>` for it to receive;  this may be constrained

        by or have consequences for the OutputPort's `variable <InputPort.variable>` and/or its `value

        <OutputPort.value>` (see `OutputPort_Compatibility_and_Constraints`).

        .. note::

           The *INDEX* and *ASSIGN* attributes described below have been deprecated in version 0.4.5, and should be

           replaced by use of the *VARIABLE* and *FUNCTION* entries, respectively.  Although use of *INDEX* and *ASSIGN*

           is currently being supported for backward compatibility, this may be eliminated in a future version.

      * *INDEX*:<int> *[DEPRECATED in version 0.4.5]* - specifies the item of the `owner <Port.owner>`

        Mechanism's `value <Mechanism_Base.value>` to be used for the OutputPort's `variable <OutputPort.variable>`;

        equivalent to specifying (OWNER_VALUE, <int>) for *VARIABLE* (see `OutputPort_Customization`), which should be

        used for compatibility with future versions.

      * *ASSIGN*:<function> *[DEPRECATED in version 0.4.5]* - specifies the OutputPort's `function`

        <OutputPort.assign>` attribute;  *FUNCTION* should be used for compatibility with future versions.

    .. _OutputPort_Projection_Destination_Specification:

    **Specifying an OutputPort by Components to which it Projects**

    COMMENT:

    `examples

      <Port_Projections_Examples>` in Port)

    COMMENT

    COMMENT:

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

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

    Projections from an OutputPort can be specified either as attributes, in the constructor for an OutputPort (in

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

    <OutputPort_Specification_Dictionary>`), or used to specify the OutputPort itself (using one of the

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

    details concerning the specification of Projections when creating a Port.

    .. _OutputPort_Projections:

    *Projections*

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

    When an OutputPort is created, it can be assigned one or more `Projections <Projection>`, using either the

    **projections** argument of its constructor, or in an entry of a dictionary assigned to the **params** argument with

    the key *PROJECTIONS*.  An OutputPort can be assigned either `MappingProjection(s) <MappingProjection>` or

    `GatingProjection(s) <GatingProjection>`.  MappingProjections are assigned to its `efferents <Port_Base.efferents>`

    attribute and GatingProjections to its `mod_afferents <OutputPort.mod_afferents>` attribute.  See

    `Port Projections <Port_Projections>` for additional details concerning the specification of Projections when

    creating a Port.

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

    COMMENT

    An OutputPort can also be specified by specifying one or more Components to or from which it should be assigned

    Projection(s). Specifying an OutputPort in this way creates both the OutputPort and any of the specified or

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

    are assigned to the OutputPort's `efferents <Port_Base.efferents>` attribute, while `ControlProjections

    <ControlProjection>` and `GatingProjections <GatingProjection>` are assigned to its `mod_afferents

    <Port.mod_afferents>` attribute. Any of the following can be used to specify an InputPort by the Components that

    projection to it (see `below <OutputPort_Compatibility_and_Constraints>` for an explanation of the relationship

    between the `variable` of these Components and the OutputPort's `value <OutputPort.value>`):

    * **InputPort, GatingSignal, Mechanism, or list with any of these** -- creates an OutputPort with

      the relevant Projection(s).  A `MappingProjection` is created to each InputPort or ProcessingMechanism specified

      (for a Mechanism, its `primary InputPort <InputPort_Primary>` is used). A `GatingProjection` is created for

      each GatingSignal or GatingMechamism specified (for a GatingMechanism, its first GatingSignal is used).

    ..

    * **Projection** -- any form of `Projection specification <Projection_Specification>` can be used; creates an

      OutputPort and assigns it as the `sender <MappingProjection.sender>` for any MappingProjections specified, and

      as the `receiver <GatingProjection.receiver>` for any GatingProjections specified.

    .. _OutputPort_Tuple_Specification:

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

      OutputPort along with Projections to or from it in any of the following ways:

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

          `InputPort` 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:** *(<Port, Mechanism, or list of them>, <Projection specification>)* -- this is a contracted

          form of the 3-item tuple described below

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

          this allows the specification of Port(s) to which the OutputPort should project, together with a

          specification of its `variable <OutputPort.variable>` attribute, and (optionally) parameters of the

          Projection(s) to use (e.g., their `weight <Projection_Base.weight>` and/or `exponent

          <Projection_Base.exponent>` attributes.  Each tuple must have at least the first two items (in the

          order listed), and can include the third:

            * **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 InputPort <InputPortPrimary>` 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.

            * **variable spec** -- specifies the attributes of the OutputPort's `owner <Port.owner>` Mechanism

              used for its `variable <OutputPort.variable>` (see `OutputPort_Customization`).

            * **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 InputPorts or GatingSignals), and the `Projection

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

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

.. _OutputPort_Compatibility_and_Constraints:

OutputPort `variable <OutputPort.variable>` and `value <OutputPort.value>`: Compatibility and Constraints

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

The format of an OutputPorts' `variable <OutputPort.variable>` may have consequences that must be taken into

account when `specifying an OutputPort by Components to which it projects

<OutputPort_Projection_Destination_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:

  * **OutputPort specified in a Mechanism's constructor** -- the specification of the OutputPort's `variable

    <OutputPort.variable>`, together with its `function <OutputPort.function>` determine the OutputPort's `value

    <OutputPort.value>` (see `above <OutputPort_Variable_and_Value>`).  Therefore, any specifications of the

    OutputPort relevant to its `value <OutputPort.value>` must also be compatible with these factors (for example,

    `specifying it by variable <OutputPort_Specification_by_Variable>` or by a `MappingProjection` or an

    `InputPort` to which it should project (see `above <OutputPort_Projection_Destination_Specification>`).

    COMMENT:

    ***XXX EXAMPLE HERE

    COMMENT

  ..

  * **OutputPort specified on its own** -- any direct specification of the OutputPort's `variable

    <OutputPort.variable>` is used to determine its format (e.g., `specifying it by variable

    <OutputPort_Specification_by_Variable>`, or a *VARIABLE* entry in an `OutputPort specification dictionary

    <OutputPort_Specification_Dictionary>`.  In this case, the value of any `Components used to specify the

    OutputPort <OutputPort_Projection_Destination_Specification>` must be compatible with the specification of its

    `variable <OutputPort.variable>` and the consequences this has for its `value <OutputPort.value>` (see below).

    COMMENT:

    ***XXX EXAMPLE HERE

    COMMENT

  ..

  * **OutputPort's** `value <OutputPort.value>` **not constrained by any of the conditions above** -- then its

    `variable <OutputPort.variable>` is determined by the default for an OutputPort (the format of the first

    item of its `owner <Port.owner>` Mechanism's `value <Mechanism_Base.value>` ). If the OutputPort is

    `specified to project to any other Components <OutputPort_Projection_Destination_Specification>`, then if the

    Component is a:

    * **InputPort or Mechanism** (for which its `primary InputPort <InputPort_Primary>` is used) -- if its

      `variable <Port_Base.variable>` matches the format of the OutputPort's `value <OutputPort.value>`, a

      `MappingProjection` is created using an `IDENTITY_MATRIX`;  otherwise, a `FULL_CONNECTIVITY_MATRIX` is used

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

    * **MappingProjection** -- if its `matrix <MappingProjection.matrix>` is specified, then the `sender dimensionality

      <Mapping_Matrix_Dimensionality>` of the matrix must be the same as that of the OutputPort's `value

      <OutputPort.value>`; if its `receiver <MappingProjection.receiver>` is specified, but not its `matrix

      <MappingProjection.matrix>`, then a matrix is chosen that appropriately maps from the OutputPort to the

      receiver (as described just above);  if neither its `matrix <MappingProjection.matrix>` or its `receiver

      <MappingProjection.receiver>` are specified, then the Projection's `initialization is deferred

      <MappingProjection_Deferred_Initialization>` until its `receiver <MappingProjection.receiver>` is specified.

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

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

      `value <OutputPort.value>`, however it does have to be compatible with the `modulatory parameter

      <Function_Modulatory_Params>` of the OutputPort's `function <OutputPort.function>`.

.. _OutputPort_Standard:

Standard OutputPorts

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

# FIX: 11/9/19: REPLACE RECURRENTTRANSFERMECHNISM EXAMPLE WITH TRANSFERMECHANISM

Mechanisms have a `standard_output_ports <Mechanism_Base.standard_output_ports>` attribute, that contains a list of

`StandardOutputPorts`: `OutputPort specification dictionaries <OutputPort_Specification_Dictionary>` that can be

assigned as `output_ports <Mechanism_Base.output_ports>`. There is a base set of StandardOutputPorts for all

Mechanisms. Subclasses of Mechanisms may add ones that are specific to that type of Mechanism (for example, the

`RecurrentTransferMechanism` class has `standard_output_ports <RecurrentTransferMechanism.standard_output_ports>`

for calculating the energy and entropy of its `value <Mechanism_Base.value>`.  The names of the `standard_output_ports`

are listed in the Mechanism's `standard_output_port_names <Mechanism_Base.standard_output_port_names>` attribute.

These can be used to specify the `output_ports <Mechanism_Base.output_ports>` of a Mechanism, as in the following

example for a `ProcessingMechanism <ProcessingMechanism>`::

    >>> import psyneulink as pnl

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

    ...                                   function=pnl.Logistic,

    ...                                   output_ports=[pnl.RESULT,

    ...                                                 pnl.MEAN,

    ...                                                 pnl.VARIANCE])

In this example, ``my_mech`` is configured with three OutputPorts;  the first will be named *RESULT* and will

represent logistic transform of the 2-element input vector;  the second will be named  *MEAN* and will

represent mean of the result (i.e., of its two elements); and the third will be named *VARIANCE* and contain

the variance of the result.

.. _OutputPort_Customization:

*Custom OutputPorts*

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

An OutputPort's `value <OutputPort.value>` can be customized by specifying its `variable <OutputPort.variable>`

and/or `function <OutputPort.function>` in the **variable** and **function** arguments of the OutputPort's

constructor, the corresponding entries (*VARIABLE* and *FUNCTION*) of an `OutputPort specification

dictionary <OutputPort_Specification_Dictionary>`, or in the variable spec (2nd) item of a `3-item tuple

<OutputPort_Tuple_Specification>` for the OutputPort.

.. _OutputPort_Custom_Variable:

*OutputPort* `variable <OutputPort.variable>`

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

By default, an OutputPort uses the first (and often only) item of the owner Mechanism's `value

<Mechanism_Base.value>` as its `variable <OutputPort.variable>`, which usuall corresponds to the `value

<InputPort.value>` of the Mechanism's first (primary) `InputPort <InputPort_Primary>`.  However, this can be

customized by specifying any other item of its `owner <Port.owner>`\\s `value <Mechanism_Base.value>`, the full

`value <Mechanism_Base.value>` itself, other attributes of the `owner <Port.owner>`, or any combination of these

using the following:

    *OWNER_VALUE* -- keyword specifying the entire `value <Mechanism_Base.value>` of the OutputPort's `owner

    <Port.owner>`.

    *(OWNER_VALUE, <int>)* -- tuple specifying an item of the `owner <Port.owner>`\\'s `value

    <Mechanism_Base.value>` indexed by the int;  indexing begins with 0 (e.g.; 1 references the 2nd item).

    *<attribute name>* -- the name of an attribute of the OutputPort's `owner <Port.owner>` (must be one

    in the `owner <Port.owner>`\\'s `Parameters <Mechanism.Parameters>` class); returns the value

    of the named attribute for use in the OutputPort's `variable <OutputPort.variable>`.

    *PARAMS_DICT* -- keyword specifying the `owner <Port.owner>` Mechanism's

    entire dictionary of Parameters, that contains its own Parameters, its

    `function <Mechanism.function`\\'s Parameters, and the current `variable`

    for the Mechanism's `input_ports <Mechanism.input_ports>`. The

    OutputPort's `function <OutputPort.function>` must be able to parse the dictionary.

    COMMENT

    ??WHERE CAN THE USER GET THE LIST OF ALLOWABLE ATTRIBUTES?  USER_PARAMS?? aTTRIBUTES_DICT?? USER ACCESSIBLE PARAMS??

    <obj>.parameters

    COMMENT

    *List[<any of the above items>]* -- this assigns the value of each item in the list to the corresponding item of

    the OutputPort's `variable <OutputPort.variable>`.  This must be compatible (in number and type of elements) with

    the input expected by the OutputPort's `function <OutputPort.function>`.

.. _OutputPort_Custom_Function:

*OutputPort* `function <OutputPort.function>`

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

By default, the `function <OutputPort.function>` of an OutputPort is `Linear`, which simply assigns the

OutputPort's `variable <OutputPort.variable>` as its `value <OutputPort.value>`.  However, a different function

can be assigned, to transform and/or combine the item(s) of the OutputPort's `variable <OutputPort.variable>`

for use as its `value <OutputPort.value>`. The function can be a PsyNeuLink `Function <Function>` or any Python

function or method, so long as the input it expects is compatible (in number and format of elements) with the

OutputPort's `variable <OutputPort.variable>`.

Examples

--------

In the following example, a `DDM` Mechanism named ``my_mech`` is configured with three OutputPorts:

COMMENT:

(also see `OutputPort_Structure` below). If the

Mechanism's `function

<Mechanism_Base.function>` returns a value with more than one item (i.e., a list of lists, or a 2d np.array), then an

OutputPort can be assigned to any of those items by specifying its `index <OutputPort.index>` attribute. An

OutputPort can also be configured to transform the value of the item, by specifying a function for its `assign

<OutputPort.assign>` attribute; the result will then be assigned as the OutputPort's `value <OutputPort.value>`.

An OutputPort's `index <OutputPort.index>` and `assign <OutputPort.assign>` attributes can be assigned when

the OutputPort is assigned to a Mechanism, by including *INDEX* and *ASSIGN* entries in a `specification dictionary

<OutputPort_Specification>` for the OutputPort, as in the following example::

COMMENT

    >>> my_mech = pnl.DDM(function=pnl.DriftDiffusionAnalytical(),

    ...                   output_ports=[pnl.DECISION_VARIABLE,

    ...                                  pnl.PROBABILITY_UPPER_THRESHOLD,

    ...                                  {pnl.NAME: 'DECISION ENTROPY',

    ...                                   pnl.VARIABLE: (pnl.OWNER_VALUE, 2),

    ...                                   pnl.FUNCTION: pnl.Stability(metric=pnl.ENTROPY) }])

COMMENT:

   ADD VERSION IN WHICH INDEX IS SPECIFIED USING DDM_standard_output_ports

   CW 3/20/18: TODO: this example is flawed: if you try to execute() it, it gives divide by zero error.

COMMENT

The first two are `Standard OutputPorts <OutputPort_Standard>` that represent the decision variable of the DDM and

the probability of it crossing of the upper (vs. lower) threshold. The third is a custom OutputPort, that computes

the entropy of the probability of crossing the upper threshold.  It uses the 3rd item of the DDM's `value <DDM.value>`

(items are indexed starting with 0), which contains the `probability of crossing the upper threshold

<DDM_PROBABILITY_UPPER_THRESHOLD>`, and uses this as the input to the `Stability` Function assigned as the

OutputPort's `function <OutputPort.function>`, that computes the entropy of the probability. The three OutputPorts

will be assigned to the `output_ports <Mechanism_Base.output_ports>` attribute of ``my_mech``, and their values

will be assigned as items in its `output_values <Mechanism_Base.output_values>` attribute, in the order in which they

are listed in the **output_ports** argument of the constructor for ``my_mech``.

Custom OutputPorts can also be created on their own, and separately assigned or added to a Mechanism.  For example,

the ``DECISION ENTROPY`` OutputPort could be created as follows::

    >>> decision_entropy_output_port = pnl.OutputPort(name='DECISION ENTROPY',

    ...                                                 variable=(OWNER_VALUE, 2),

    ...                                                 function=pnl.Stability(metric=pnl.ENTROPY))

and then assigned either as::

    >>> my_mech = pnl.DDM(function=pnl.DriftDiffusionAnalytical(),

    ...                   output_ports=[pnl.DECISION_VARIABLE,

    ...                                  pnl.PROBABILITY_UPPER_THRESHOLD,

    ...                                  decision_entropy_output_port])

or::

    >>> another_decision_entropy_output_port = pnl.OutputPort(name='DECISION ENTROPY',

    ...                                                variable=(OWNER_VALUE, 2),

    ...                                                function=pnl.Stability(metric=pnl.ENTROPY))

    >>> my_mech2 = pnl.DDM(function=pnl.DriftDiffusionAnalytical(),

    ...                    output_ports=[pnl.DECISION_VARIABLE,

    ...                                   pnl.PROBABILITY_UPPER_THRESHOLD])

    >>> my_mech2.add_ports(another_decision_entropy_output_port) # doctest: +SKIP

Note that another new OutputPort had to be used for the second example, as trying to

add the first one created for ``my_mech`` to ``my_mech2`` would have produced an error (since a Port already

belonging to one Mechanism can't be added to another.

.. _OutputPort_Structure:

Structure

---------

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

<MappingProjection>` to other Mechanisms.  If its owner is a `TERMINAL` Mechanism of a Process and/or System, then the

OutputPort will also be treated as the output of that `Process <Process_Input_And_Output>` and/or of a System.  It has

the following attributes, some of which can be specified in ways that are specific to, and that can be used to

`customize, the OutputPort <OutputPort_Customization>`:

COMMENT:

.. _OutputPort_Index:

* `index <OutputPort.index>`: this determines the item of its owner Mechanism's `value <Mechanism_Base.value>` to

  which it is assigned.  By default, this is set to 0, which assigns it to the first item of the Mechanism's `value

  <Mechanism_Base.value>`.  The `index <Mechanism_Base.index>` must be equal to or less than one minus the number of

  OutputPorts listed in the Mechanism's `output_ports <Mechanism_Base.output_ports>` attribute.  The `variable

  <OutputPort.variable>` of the OutputPort must also match (in the number and type of its elements) the item of the

  Mechanism's `value <Mechanism_Base.value>` designated by the `index <OutputPort.index>`.

.. _OutputPort_Assign:

* `assign <OutputPort.assign>`:  this specifies a function used to convert the item of the owner Mechanism's

  `value <Mechanism_Base.value>` (designated by the OutputPort's `index <OutputPort.index>` attribute), before

  providing it to the OutputPort's `function <OutputPort.function>`.  The `assign <OutputPort.assign>`

  attribute can be assigned any function that accept the OutputPort's `variable <OutputPort.variable>` as its input,

  and that generates a result that can be used the input for the OutputPort's `function <OutputPort.function>`.

  The default is an identity function (`Linear` with **slope**\\ =1 and **intercept**\\ =0), that simply assigns the

  specified item of the Mechanism's `value <Mechanism_Base.value>` unmodified as the input for OutputPort's

  `function <OutputPort.function>`.

COMMENT

..

* `variable <OutputPort.variable>` -- references attributes of the OutputPort's `owner <Port.owner>` that

  are used as the input to the OutputPort's `function <OutputPort.function>`, to determine its `value

  <OutputPort.value>`.  The specification must match (in both the number and types of elements it generates)

  the input to the OutputPort's `function <OutputPort.function>`.  By default, the first item of the `owner

  <Port.owner>` Mechanisms' `value <Mechanism_Base.value>` is used.  However, this can be customized as

  described under `OutputPort_Customization`.

* `function <OutputPort.function>` -- takes the OutputPort's `variable <OutputPort.variable>` as its input, and

  generates the OutputPort's `value <OutputPort.value>` as its result.  The default function is `Linear` that simply

  assigns the OutputPort's `variable <OutputPort.variable>` as its `value <OutputPort.value>`.  However, the

  parameters of the `function <OutputPort.function>` -- and thus the `value <OutputPort.value>` of the OutputPort --

  can be modified by `GatingProjections <GatingProjection>` received by the OutputPort (listed in its

  `mod_afferents <OutputPort.mod_afferents>` attribute.  A custom function can also be specified, so long as it can

  take as its input a value that is compatible with the OutputPort's `variable <OutputPort.variable>`.

* `projections <Port.projections>` -- all of the `Projections <Projection>` sent and received by the OutputPort;

.. _OutputPort_Efferent_Projections:

* `efferents <Port_Base.efferents>` -- `MappingProjections <MappingProjection>` that project from the OutputPort.

.. _OutputPort_Modulatory_Projections:

* `mod_afferents <Port.mod_afferents>` -- `ControlProjections <ControlProjection>` or `GatingProjections

  <GatingProjection>` that project to the OutputPort, the `value <Projection_Base.value>` of which can modify the

  OutputPort's `value <InputPort.value>` (see the descriptions of Modulation under `ModulatorySignals

  <ModulatorySignal_Modulation>`, `ControlSignals <ControlSignal_Modulation>`, and `GatingSignals

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

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

..

* `value <OutputPort.value>`:  assigned the result of the OutputPort's `function <OutputPort.function>`, possibly

  modified by any `GatingProjections <GatingProjection>` received by the OutputPort. It is used as the input to any

  projections that the OutputStatue sends.

.. _OutputPort_Execution:

Execution

---------

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

When the Mechanism is executed, the values of its attributes specified for the OutputPort's `variable

<OutputPort.variable>` (see `OutputPort_Customization`) are used as the input to the OutputPort's `function

<OutputPort.function>`. The OutputPort is updated by calling its `function <OutputPort.function>`.  The result,

modified by any `GatingProjections <GatingProjection>` the OutputPort receives (listed in its `mod_afferents

<OutputPort.mod_afferents>` attribute), is assigned as the `value <OutputPort.value>` of the OutputPort.  This is

assigned to a corresponding item of the Mechanism's `output_values <Mechanism_Base.output_values>` attribute,

and is used as the input to any projections for which the OutputPort is the `sender <Projection_Base.sender>`.

.. _OutputPort_Class_Reference:

Class Reference

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

"""

    ALL, ASSIGN, CALCULATE, CONTEXT, CONTROL_SIGNAL, FUNCTION, GATING_SIGNAL, INDEX, INPUT_PORT, INPUT_PORTS, \

    MAPPING_PROJECTION, MECHANISM_VALUE, NAME, OUTPUT_PORT, OUTPUT_PORTS, OUTPUT_PORT_PARAMS, \

    OWNER_VALUE, PARAMS, PARAMS_DICT, PROJECTION, PROJECTIONS, RECEIVER, REFERENCE_VALUE, STANDARD_OUTPUT_PORTS, PORT, \

    VALUE, VARIABLE, \

    output_port_spec_to_parameter_name, INPUT_PORT_VARIABLES, SHARED_COMPONENT_TYPES

    convert_all_elements_to_np_array, convert_to_np_array, is_numeric, iscompatible, make_readonly_property, recursive_update, parse_valid_identifier

    'OutputPort', 'OutputPortError', 'PRIMARY', 'SEQUENTIAL', 'StandardOutputPorts', 'StandardOutputPortsError',

    'port_type_keywords',

]

# class OutputPortLog(IntEnum):

#     NONE            = 0

#     TIME_STAMP      = 1 << 0

#     ALL = TIME_STAMP

#     DEFAULTS = NONE

# Used to specify how StandardOutputPorts are indexed

    """Return variable for OutputPort based on VARIABLE entry of owner's params dict

    The format of the VARIABLE entry determines the format returned:

    - if it is a single item, or a single item in a list, a single item is returned;

    - if it is a list with more than one item, a list is returned.

    :return:

    """

            # Tuple indexing item of owner's attribute (e.g.,: OWNER_VALUE, int))

                # context is None during initialization, and we don't want to

                # incur the cost of .get during execution

                else:

                raise OutputPortError(f"Can't parse variable ({spec}) for "

                                       f"{output_port_name or OutputPort.__name__} of {owner.name}.")

            # Specifies passing owner's params_dict as variable

                **{p.name: p._get(context) for p in owner.parameters},

                **{p.name: p._get(context) for p in owner.function.parameters},

                **{

                    INPUT_PORT_VARIABLES:

                    [

                        input_port.parameters.variable._get(context)

                        for input_port in owner.input_ports

                    ]

                }

            }

            # Owner's full value or attribute other than its value

                # context is None during initialization, and we don't want to

                # incur the cost of .get during execution

                else:

                    else:

                    raise OutputPortError(f"Can't parse variable ({spec}) for "

                                           f"{output_port_name or OutputPort.__name__} of {owner.name}.")

        else:

            raise OutputPortError(f"'{VARIABLE.upper()}' entry for {output_port_name or OutputPort.__name__} "

                                   f"specification dictionary of {owner.name} ({spec}) must be "

                                   "numeric or a list of {owner.__class__.__name__} attribute names.")

    else:

    """

    OutputPort(            \

        reference_value,   \

        function=Linear(), \

        projections=None)

    Subclass of `Port <Port>` that calculates and represents an output of a `Mechanism <Mechanism>`.

    See `Port_Class_Reference` for additional arguments and attributes.

    COMMENT:

    PortRegistry

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

        All OutputPorts 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

        a template that specifies the format of the OutputPort's `variable <OutputPort.variable>`;  if it is

        specified in addition to the **variable** argument, then these must be compatible (both in the number and

        type of elements).  It is used to insure the compatibility of the source of the input for the OutputPort

        with its `function <OutputPort.function>`.

    variable : number, list or np.ndarray

        specifies the attributes of the  OutputPort's `owner <Port.owner>` Mechanism to be used by the

        OutputPort's `function <OutputPort.function>`  in generating its `value <OutputPort.value>`.

    function : Function, function, or method : default Linear

        specifies the function used to transform and/or combine the items of its `owner <Port.owner>`\'s `value

        <Mechanism_Base.value>` (designated by the OutputPort's `variable <OutputPort.variable>`) into its `value

        <OutputPort.value>`, under the possible influence of `ControlProjections <ControlProjection>` or

        `GatingProjections <GatingProjection>` received by the OutputPort.

    COMMENT:

    index : int : default PRIMARY

        specifies the item of the owner Mechanism's `value <Mechanism_Base.value>` used as input for the

        function specified by the OutputPort's `assign <OutputPort.assign>` attribute, to determine the

        OutputPort's `value <OutputPort.value>`.

    assign : Function, function, or method : default Linear

        specifies the function used to convert the designated item of the owner Mechanism's

        `value <Mechanism_Base.value>` (specified by the OutputPort's :keyword:`index` attribute),

        before it is assigned as the OutputPort's `value <OutputPort.value>`.  The function must accept a value that

        has the same format (number and type of elements) as the item of the Mechanism's

        `value <Mechanism_Base.value>`.

    COMMENT

    projections : list of Projection specifications

        specifies the `MappingProjection(s) <MappingProjection>` to be sent by the OutputPort, and/or

        `ControlProjections <ControlProjection>` and/or `GatingProjections(s) <GatingProjection>` to be received (see

        `OutputPort_Projections` for additional details); these are listed in its `efferents <Port_Base.efferents>` and

        `mod_afferents <Port.mod_afferents>` attributes, respectively (see `OutputPort_Projections` for additional

        details).

    Attributes

    ----------

    variable : value, list or np.ndarray

        the value(s) of the item(s) of the `owner <Port.owner>` Mechanism's attributes specified in the

        **variable** argument of the constructor, or a *VARIABLE* entry in the `OutputPort specification dictionary

        <OutputPort_Specification_Dictionary>` used to construct the OutputPort.

    COMMENT:

    index : int

        the item of the owner Mechanism's `value <Mechanism_Base.value>` used as input for the function specified by

        its `assign <OutputPort.assign>` attribute (see `index <OutputPort_Index>` for additional details).

    assign : function or method

        function used to convert the item of the owner Mechanism's `value <Mechanism_Base.value>` specified by

        the OutputPort's `index <OutputPort.index>` attribute.  The result is combined with the result of the

        OutputPort's `function <OutputPort.function>` to determine both the `value <OutputPort.value>` of the

        OutputPort, as well as the value of the corresponding item of the owner Mechanism's `output_values

        <Mechanism_Base.output_values>`. The default (`Linear`) transfers the value unmodified  (see `assign

        <OutputPort_Assign>` for additional details)

    COMMENT

    function : Function, function, or method

        function used to transform and/or combine the value of the items of the OutputPort's `variable

        <OutputPort.variable>` into its `value <OutputPort.value>`, under the possible influence of

        `ControlProjections <ControlProjection>` or `GatingProjections <GatingProjection>` received by the OutputPort.

    value : number, list or np.ndarray

        assigned the result of `function <OutputPort.function>`;  the same value is assigned to the corresponding item

        of the owner Mechanism's `output_values <Mechanism_Base.output_values>` attribute.

    label : string or number

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

        owner mechanism's `output_labels_dict <Mechanism.output_labels_dict>`. If the current

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

        `value <OutputPort.value>` is returned.

    name : str

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

        assigned by the OutputPortRegistry of the Mechanism to which the OutputPort belongs.  Note that most

        Mechanisms automatically create one or more `Standard OutputPorts <OutputPort_Standard>`, that have

        pre-specified names.  However, if any OutputPorts are specified in the **input_ports** argument of the

        Mechanism's constructor, those replace its Standard OutputPorts (see `note

        <Mechanism_Default_Port_Suppression_Note>`);  `standard naming conventions <Registry_Naming>` apply to the

        OutputPorts specified, as well as any that are added to the Mechanism once it is created (see `note

        <Port_Naming_Note>`).

    """

    #region CLASS ATTRIBUTES

    # portAttributes = Port_Base.portAttributes | {INDEX, ASSIGN}