PrincetonUniversity / PsyNeuLink / 15917088825

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

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

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

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

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

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

# **********************************************  Projection ***********************************************************

"""

Contents

--------

  * `Projection_Overview`

  * `Projection_Creation`

  * `Projection_Structure`

      - `Projection_Sender`

      - `Projection_Receiver`

  * `Projection_Execution`

  * `Projection_Class_Reference`

.. _Projection_Overview:

Overview

--------

Projections allow information to be passed between `Mechanisms <Mechanism>`.  A Projection takes its input from

its `sender <Projection_Base.sender>` and transmits that information to its `receiver <Projection_Base.receiver>`.  The

`sender <Projection_Base.sender>` and `receiver <Projection_Base.receiver>` of a Projection are always `Ports <Port>`:

the `sender <Projection_Base.sender>` is always the `OutputPort` of a `Mechanism <Mechanism>`; the `receiver

<Projection_Base.receiver>` depends upon the type of Projection.  There are two broad categories of Projections,

each of which has subtypes that differ in the type of information they transmit, how they do this, and the type of

`Port <Port>` to which they project (i.e., of their `receiver <Projection_Base.receiver>`):

* `PathwayProjection <PathwayProjection>`

    Used in conjunction with `ProcessingMechanisms <ProcessingMechanism>` to convey information along a processing

    `pathway <Process.pathway>`.  There is currently one on type of PathwayProjection:

  * `MappingProjection`

      takes the `value <OutputPort.value>` of an `OutputPort` of a `ProcessingMechanism <ProcessingMechanism>`

      converts it by convolving it with the MappingProjection's `matrix <MappingProjection.matrix>`

      parameter, and transmits the result to the `InputPort` of another ProcessingMechanism.  Typically,

      MappingProjections are used to connect Mechanisms in the `pathway` of a `Process`, though they can be use for

      other purposes as well (for example, to convey the output of an `ObjectiveMechanism` to a `ModulatoryMechanism

      <ModulatoryMechanism>`).

* `ModulatoryProjection <ModulatoryProjection>`

    takes the `value <OutputPort.value>` of a `ModulatorySignal <ModulatorySignal>` of a `ModulatoryMechanism

    <ProcessingMechanism>`, uses it to regulate modify the `value <Port_Base.value>` of an `InputPort`,

    `ParameterPort` or `OutputPort` of another Component.  ModulatorySignals are specialized types of `OutputPort`,

    that are used to specify how to modify the `value <Port_Base.value>` of the `Port <Port>` to which a

    ModulatoryProjection projects. There are three types of ModulatoryProjections, corresponding to the three types

    of ModulatoryMechanisms (and corresponding ModulatorySignals; see `figure <ModulatorySignal_Anatomy_Figure>`),

    that project to different types of `Ports <Port>`:

  * `LearningProjection`

      takes the `value <LearningSignal.value>` of a `LearningSignal` of a `LearningMechanism`, and transmits this

      to the `ParameterPort` of a `MappingProjection` that uses it to modify its `matrix <MappingProjection.matrix>`

      parameter. LearningProjections are used in the `learning Pathway(s) <Composition_Learning_Pathway>` of a

      `Composition`.

  ..

  * `ControlProjection`

      takes the `value <ControlSignal.value>` of a `ControlSignal` of a `ControlMechanism <ControlMechanism>`, and

      transmit this to the `ParameterPort of a `ProcessingMechanism <ProcessingMechanism>` that uses it to modify

      the parameter of the `Mechanism <Mechanism>` (or its `function <Mechanism_Base.function>`) for which it is

      responsible.

      COMMENT:

      ControlProjections are used in the `control Pathway(s) <Composition_Control_Pathway>` of a `Composition`.

      COMMENT

  ..

  * `GatingProjection`

      takes the `value <GatingSignal.value>` of a `GatingSignal` of a `GatingMechanism`, and transmits this to

      the `InputPort` or `OutputPort` of a `ProcessingMechanism <ProcessingMechanism>` that uses this to modify the

      Port's `value <Port_Base.value>`.  GatingProjections are a special subclass of ControlProjections.

.. _Projection_Creation:

Creating a Projection

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

A Projection can be created on its own, by calling the constructor for the desired type of Projection.  More

commonly, however, Projections are either specified `in context <Projection_Specification>`, or are `created

automatically <Projection_Automatic_Creation>`, as described below.

.. _Projection_Specification:

*Specifying a Projection*

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

Projections can be specified in a number of places where they are required or permitted, for example in the

specification of a `pathway <Process.pathway>` for a `Process`, where the value of a parameter is specified

(e.g., to assign a `ControlProjection`) or where a `MappingProjection` is specified  (to assign it a

`LearningProjection <MappingProjection_Tuple_Specification>`).  Any of the following can be used to specify a

Projection in context:

  * **Constructor** -- used the same way in context as it is ordinarily.

  ..

  * **Projection object** -- must be a reference to a Projection that has already been created.

  ..

  * **Projection subclass** -- creates a default instance of the specified Projection type.  The assignment or creation

    of the Projection's `sender <Projection_Base.sender>` is handled in the same manner as described below for keyword

    specifications.

  ..

  * **Keyword** -- creates a default instance of the specified type, which can be any of the following:

      * *MAPPING_PROJECTION* -- if the `sender <MappingProjection.sender>` and/or its `receiver

        <MappingProjection.receiver>` cannot be inferred from the context in which this specification occurs, then

        its `initialization is deferred <MappingProjection_Deferred_Initialization>` until both of those have been

        determined (e.g., it is used in the specification of a `Pathway` for a `Composition`). For MappingProjections,

        a `matrix specification <MappingProjection_Matrix_Specification>` can also be used to specify the Projection

        (see **value** below).

      COMMENT:

      * *LEARNING_PROJECTION*  (or *LEARNING*) -- this can only be used in the specification of a `MappingProjection`

        (see `tuple <MappingProjection_Matrix_Specification>` format).  If the `receiver <MappingProjection.receiver>`

        of the MappingProjection projects to a `LearningMechanism` or a `ComparatorMechanism` that projects to one,

        then a `LearningSignal` is added to that LearningMechanism and assigned as the LearningProjection's `sender

        <LearningProjection.sender>`;  otherwise, a LearningMechanism is `automatically created

        <LearningMechanism_Creation>`, along with a LearningSignal that is assigned as the LearningProjection's `sender

        <LearningProjection.sender>`. See `LearningMechanism_Learning_Configurations` for additional details.

      COMMENT

      COMMENT:

      # FIX 5/8/20 [JDC] ELIMINATE SYSTEM:  IS IT TRUE THAT CONTROL SIGNALS ARE AUTOMATICALLY CREATED BY COMPOSITIONS?

      COMMENT

      * *CONTROL_PROJECTION* (or *CONTROL*) -- this can be used when specifying a parameter using the `tuple format

        <ParameterPort_Tuple_Specification>`, to create a default `ControlProjection` to the `ParameterPort` for that

        parameter.  If the `Component <Component>` to which the parameter belongs is part of a `Composition`, then a

        `ControlSignal` is added to the Composition's `controller <Composition.controller>` and assigned as the

        ControlProjection's `sender <ControlProjection.sender>`;  otherwise, the ControlProjection's `initialization

        is deferred <ControlProjection_Deferred_Initialization>` until the Mechanism is assigned to a Composition, at

        which time the ControlSignal is added to the Composition's `controller <Composition.controller>` and assigned

        as its the ControlProjection's `sender <ControlProjection.sender>`.  See `ControlMechanism_ControlSignals` for

        additional details.

      * *GATING_PROJECTION* (or *GATE*) -- this can be used when specifying an `InputPort

        <InputPort_Projection_Source_Specification>` or an `OutputPort <OutputPort_Projections>`, to create a

        default `GatingProjection` to the `Port <Port>`. If the GatingProjection's `sender <GatingProjection.sender>`

        cannot be inferred from the context in which this specification occurs, then its `initialization is deferred

        <GatingProjection_Deferred_Initialization>` until it can be determined (e.g., a `GatingMechanism` or

        `GatingSignal` is created to which it is assigned).

  ..

  * **value** -- creates a Projection of a type determined by the context of the specification, and using the

    specified value as the `value <Projection_Base.value>` of the Projection, which must be compatible with the

    `variable <Port_Base.variable>` attribute of its `receiver <Projection_Base.receiver>`.  If the Projection is a

    `MappingProjection`, the value is interpreted as a `matrix specification <MappingProjection_Matrix_Specification>`

    and assigned as the `matrix <MappingProjection.matrix>` parameter of the Projection;  it must be compatible with the

    `value <Port_Base.value>` attribute of its `sender <MappingProjection.sender>` and `variable <Port_Base.variable>`

    attribute of its `receiver <MappingProjection.receiver>`.

  ..

  * **Mechanism** -- creates a `MappingProjection` to either the `primary InputPort <InputPort_Primary>` or

    `primary OutputPort <OutputPort_Primary>`, depending on the type of Mechanism and context of the specification.

  ..

  * **Port** -- creates a `Projection` to or from the specified `Port`, depending on the type of Port and the

    context of the specification.

  .. _Projection_Specification_Dictionary:

  * **Projection specification dictionary** -- can contain an entry specifying the type of Projection, and/or entries

    specifying the value of parameters used to instantiate it. These should take the following form:

      * *PROJECTION_TYPE*: *<name of a Projection type>* --

        if this entry is absent, a default Projection will be created that is appropriate for the context

        (for example, a `MappingProjection` for an `InputPort`, a `LearningProjection` for the `matrix

        <MappingProjection.matrix>` parameter of a `MappingProjection`, and a `ControlProjection` for any other

        type of parameter.

      * *PROJECTION_PARAMS*: *Dict[Projection argument, argument value]* --

        the key for each entry of the dictionary must be the name of a Projection parameter, and its value the value

        of the parameter.  It can contain any of the standard parameters for instantiating a Projection (in particular

        its `sender <Projection_Sender>` and `receiver <Projection_Receiver>`, or ones specific to a particular type

        of Projection (see documentation for subclass).  If the `sender <Projection_Sender>` and/or

        `receiver <Projection_Receiver>` are not specified, their assignment and/or creation are handled in the same

        manner as described above for keyword specifications.

      COMMENT:

          WHAT ABOUT SPECIFICATION USING OutputPort/ModulatorySignal OR Mechanism? OR Matrix OR Matrix keyword

      COMMENT

      COMMENT:  ??IMPLEMENTED FOR PROJECTION PARAMS??

        Note that parameter

        values in the specification dictionary will be used to instantiate the Projection.  These can be overridden

        during execution by specifying `runtime parameters <Mechanism_Runtime_Params>` for the Projection,

        either when calling the `execute <Mechanism_Base.execute>` or `run <Mechanism_Base.run>`

        method for a Mechanism directly, or where it is specified in the `pathway` of a Process.

      COMMENT

  .. _Projection_ProjectionTuple:

  * **ProjectionTuple** -- a 4-item tuple used in the context of a `Port specification <Port_Specification>` to

    create a Projection between it and another `Port <Port>`. It must have at least the first three of the following

    items in order, and can include the fourth optional item:

     * **Port specification** -- specifies the `Port <Port_Specification>` to connect with (**not** the one being

       connected; that is determined from context)

     * **weight** -- must be a value specifying the `weight <Projection_Base.weight>` of the Projection;  it can be

       `None`, in which case it is ignored, but there must be a specification present;

     * **exponent** -- must be a value specifying the `exponent <Projection_Base.exponent>` of the Projection;  it

       can be `None`, in which case it is ignored, but there must be a specification present;

     * **Projection specification** -- this is optional but, if included, msut be a `Projection specification

       <Projection_Specification>`;  it can take any of the forms of a Projection specification described above for

       any Projection subclass; it can be used to provide additional specifications for the Projection, such as its

       `matrix <MappingProjection.matrix>` if it is a `MappingProjection`.

    .. note::

       A ProjectionTuple should not be confused with a `4-item InputPort specification tuple

       <InputPort_Tuple_Specification>`, which also contains weight and exponent items.  In a ProjectionTuple, those

       items specify the weight and/or exponent assigned to the *Projection* (see `Projection_Weight_Exponent`),

       whereas in an `InputPort specification tuple <InputPort_Weights_And_Exponents>` they specify the weight

       and/or exponent of the **InputPort**.

    Any (but not all) of the items can be `None`.  If the Port specification is `None`, then there must be a

    Projection specification (used to infer the Port to be connected with).  If the Projection specification is

    `None` or absent, the Port specification cannot be `None` (as it is then used to infer the type of Projection).

    If weight and/or exponent is `None`, it is ignored.  If both the Port and Projection are specified, they must

    be compatible  (see `examples <Port_Projections_Examples>` in Port).

.. _Projection_Automatic_Creation:

*Automatic creation*

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

Under some circumstances Projections are created automatically. For example, a `Composition` automatically creates

a `MappingProjection` between adjacent `ProcessingMechanisms <ProcessingMechanism>` specified in the **pathways**

argument of its constructor (if none is specified) or in its `add_linear_processing_pathway

<Composition.add_linear_processing_pathway>` method;  and, similarly, `LearningProjections <LearningProjection>` are

automatically created when a `learning pathway <Composition_Learning_Pathway>` is added to a Composition.

.. _Projection_Deferred_Initialization:

*Deferred Initialization*

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

When a Projection is created, its full initialization is `deferred <Component_Deferred_Init>` until its `sender

<Projection_Base.sender>` and `receiver <Projection_Base.receiver>` have been fully specified.  This allows a

Projection to be created before its `sender <Projection_Base.sender>` and/or `receiver <Projection_Base.receiver>` have

been created (e.g., before them in a script), by calling its constructor without specifying its **sender** or

**receiver** arguments. However, for the Projection to be operational, initialization must be completed by calling

its `_deferred_init` method.  Under most conditions this occurs automatically (e.g., when the projection is assigned

to a type of Component that expects to be the `sender <Projection_Base.sender>` or `receiver <Projection_Base.receiver>`

for that type of Projection); these conditions are described in the section on *Deferred Initialization* for each type

of Projection.  Otherwise, the  Projection's `_deferred_init` method must be called explicitly, once the missing

attribute assignments have been made.

.. _Projection_Structure:

Structure

---------

In addition to its `function <Projection_Base.function>`, a Projection has two primary attributes: a `sender

<Projection_Base.sender>` and `receiver <Projection_Base.receiver>`.  The types of `Port(s) <Port>` that can be

assigned to these, and the attributes of those Ports to which Projections of each type are assigned, are

summarized in the following table, and described in greater detail in the subsections below.  In addition to the

Port attributes to which different types of Projections are assigned (shown in the table), all of the Projections

of a Port are listed in its `projections <Port_Base.projections>` attribute.

.. _Projection_Table:

.. table:: **Sender, Receiver and Attribute Assignments for Projection Types**

    :align: center

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

    |     Projection       |   sender                              |  receiver                                        |

    |                      |   *(attribute)*                       |  *(attribute)*                                   |

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

    | `MappingProjection`  | `OutputPort`                          | `InputPort`                                      |

    |                      | (`efferents <Port_Base.efferents>`)   | (`path_afferents <Port_Base.path_afferents>`)    |

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

    | `LearningProjection` | `LearningSignal`                      | `ParameterPort`                                  |

    |                      | (`efferents <Port_Base.efferents>`)   | (`mod_afferents <ParameterPort.mod_afferents>`)  |

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

    | `ControlProjection`  | `ControlSignal`                       | `InputPort`, `ParameterPort` or `OutputPort`     |

    |                      | (`efferents <Port_Base.efferents>`)   | (`mod_afferents <ParameterPort.mod_afferents>`)  |

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

    | `GatingProjection`   | `GatingSignal`                        | `InputPort` or `OutputPort`                      |

    |                      | (`efferents <Port_Base.efferents>`)   | (`mod_afferents <Port_Base.mod_afferents>`)      |

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

.. _Projection_Sender:

*Sender*

~~~~~~~~

This must be an `OutputPort` or a `ModulatorySignal <ModulatorySignal>` (a subclass of OutputPort specialized for

`ModulatoryProjections <ModulatoryProjection>`).  The Projection is assigned to the OutputPort or ModulatorySignal's

`efferents <Port_Base.efferents>` list and, for ModulatoryProjections, to the list of ModulatorySignals specific to

the `ModulatoryMechanism <ModulatoryMechanism>` from which it projects.  The OutputPort or ModulatorySignal's `value

<OutputPort.value>` is used as the `variable <Function.variable>` for Projection's `function

<Projection_Base.function>`.

A sender can be specified as:

  * an **OutputPort** or **ModulatorySignal**, as appropriate for the Projection's type, using any of the ways for

    `specifying an OutputPort <OutputPort_Specification>`.

  ..

  * a **Mechanism**;  for a `MappingProjection`, the Mechanism's `primary OutputPort <OutputPort_Primary>` is

    assigned as the `sender <Projection_Base.sender>`; for a `ModulatoryProjection <ModulatoryProjection>`, a

    `ModulatorySignal <ModulatorySignal>` of the appropriate type is created and assigned to the Mechanism.

If the `sender <Projection_Base.sender>` is not specified and it can't be determined from the context, or an OutputPort

specification is not associated with a Mechanism that can be determined from , then the initialization of the

Projection is `deferred <Projection_Deferred_Initialization>`.

.. _Projection_Receiver:

*Receiver*

~~~~~~~~~~

The `receiver <Projection_Base.receiver>` required by a Projection depends on its type, as listed below:

    * MappingProjection: `InputPort`

    * LearningProjection: `ParameterPort` (for the `matrix <MappingProjection>` of a `MappingProjection`)

    * ControlProjection: `ParameterPort`

    * GatingProjection: `InputPort` or OutputPort`

A `MappingProjection` (as a `PathwayProjection <PathwayProjection>`) is assigned to the `path_afferents

<Port_Base.path_afferents>` attribute of its `receiver <Projection_Base.receiver>`.  The ModulatoryProjections are

assigned to the `mod_afferents <Port.mod_afferents>` attribute of their `receiver <Projection_Base.receiver>`.

A `receiver <Projection_Base.receiver>` can be specified as:

  * an existing **Port**;

  ..

  * an existing **Mechanism** or **Projection**; which of these is permissible, and how a port is assigned to it, is

    determined by the type of Projection — see subclasses for details).

  ..

  * a **specification dictionary** (see subclasses for details).

.. _Projection_Weight_Exponent:

*Weight and Exponent*

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

Every Projection has a `weight <Projection_Base.weight>` and `exponent <Projection_Base.exponent>` attribute. These

are applied to its `value <Projection_Base.value>` before combining it with other Projections that project to the same

`Port`.  If both are specified, the `exponent <Projection_Base.exponent>` is applied before the `weight

<Projection_Base.weight>`.  These attributes determine both how the Projection's `value <Projection_Base.value>` is

combined with others to determine the `variable <Port_Base.variable>` of the Port to which they project.

.. note::

   The `weight <Projection_Base.weight>` and `exponent <Projection_Base.exponent>` attributes of a Projection are not

   the same as a Port's `weight <Port_Base.weight>` and `exponent <Port_Base.exponent>` attributes.  Also, they are

   not normalized: their aggregate effects contribute to the magnitude of the `variable <Port.variable>` to which

   they project.

*ParameterPorts and Parameters*

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

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

<Mechanism_Base.function>`.  ParameterPorts and their associated parameters are handled in the same way by

Projections as they are for Mechanisms (see `Mechanism_ParameterPorts` for details).  The ParameterPorts for a

Projection are listed in its `parameter_ports <Projection_Base.parameter_ports>` attribute.

.. _Projection_Execution:

Execution

---------

A Projection cannot be executed directly.  It is executed when the `Port <Port>` to which it projects (i.e., its

`receiver <Projection_Base.receiver>`) is updated;  that occurs when the Port's owner `Mechanism <Mechanism>` is

executed. When a Projection executes, it gets the value of its `sender <Projection_Base.sender>`, assigns this as the

`variable <Projection_Base.variable>` of its `function <Projection_Base.function>`, calls the `function

<Projection_Base.function>`, and provides the result as to its `receiver <Projection_Base.receiver>`.  The `function

<Projection_Base.function>` of a Projection converts the value received from its `sender <Projection_Base.sender>` to

a form suitable as input for its `receiver <Projection_Base.receiver>`.

COMMENT:

*** ADD EXAMPLES

GET FROM Scratch Pad

for example, if a ProjectionTuple is used in the context of an

    `InputPort specification

    <InputPort_Specification>` to specify a MappingProjection to it from an `OutputPort` that is specified

    in the first item of the tuple, and a Projection specification is included in the fourth, its sender (and/or the

    sending dimensions of its `matrix <MappingProjection.matrix>` parameter) must be compatible with the specified

    OutputPort (see `examples <XXX>` below)

COMMENT

.. _Projection_Class_Reference:

Class Reference

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

"""

    CONTROL, CONTROL_PROJECTION, CONTROL_SIGNAL, EXPONENT, FEEDBACK, FUNCTION_PARAMS, \

    GATE, GATING_PROJECTION, GATING_SIGNAL, \

    INPUT_PORT, LEARNING, LEARNING_PROJECTION, LEARNING_SIGNAL, \

    MAPPING_PROJECTION, MATRIX, MECHANISM, \

    MODEL_SPEC_ID_RECEIVER_MECH, MODEL_SPEC_ID_RECEIVER_PORT, \

    MODEL_SPEC_ID_SENDER_MECH, MODEL_SPEC_ID_SENDER_PORT, MODEL_SPEC_ID_METADATA, \

    NAME, OUTPUT_PORT, OUTPUT_PORTS, PARAMS, PATHWAY, PROJECTION, PROJECTION_PARAMS, \

    PROJECTION_RECEIVER, PROJECTION_SENDER, PROJECTION_TYPE, \

    RECEIVER, SENDER, STANDARD_ARGS, PORT, PORTS, WEIGHT, ADD_INPUT_PORT, ADD_OUTPUT_PORT, \

    PROJECTION_COMPONENT_CATEGORY

    Parameter,

    ParameterInvalidSourceError,

    ParameterNoValueError,

    check_user_specified,

    copy_parameter_value,

)

    ContentAddressableList, is_matrix, is_matrix_keyword, is_numeric, parse_valid_identifier, convert_to_list

    'Projection_Base', 'projection_keywords', 'PROJECTION_SPEC_KEYWORDS',

    'ProjectionError', 'DuplicateProjectionError', 'ProjectionRegistry',

    'kpProjectionTimeScaleLogEntry'

]

                            LEARNING: LEARNING_PROJECTION,

                            LEARNING_SIGNAL: LEARNING_PROJECTION,

                            LEARNING_PROJECTION: LEARNING_PROJECTION,

                            CONTROL: CONTROL_PROJECTION,

                            CONTROL_SIGNAL: CONTROL_PROJECTION,

                            CONTROL_PROJECTION: CONTROL_PROJECTION,

                            GATE: GATING_PROJECTION,

                            GATING_SIGNAL: GATING_PROJECTION,

                            GATING_PROJECTION: GATING_PROJECTION

                            }

    """Maps Projection type (key) to Projection parameter keywords (value) used for runtime_params specification

    Projection type is one specified in its componentType attribute, and registered in ProjectionRegistry

    """

            for k in list(ProjectionRegistry.keys())}

# Projection factory method:

# def projection(name=NotImplemented, params=NotImplemented, context=None):

#         """Instantiates default or specified subclass of Projection

#

#         If called w/o arguments or 1st argument=NotImplemented, instantiates default subclass (ParameterPort)

#         If called with a name string:

#             - if registered in ProjectionRegistry class dictionary as name of a subclass, instantiates that class

#             - otherwise, uses it as the name for an instantiation of the default subclass, and instantiates that

#         If a params dictionary is included, it is passed to the subclass

#

#         :param name:

#         :param param_defaults:

#         :return:

#         """

#

#         # Call to instantiate a particular subclass, so look up in MechanismRegistry

#         if name in ProjectionRegistry:

#             return ProjectionRegistry[name].mechanismSubclass(params)

#         # Name is not in MechanismRegistry or is not provided, so instantiate default subclass

#         else:

#             # from Components.Defaults import DefaultProjection

#             return DefaultProjection(name, params)

#

    """

    Projection_Base(           \

        sender=None,           \

        function=MatrixTransform, \

        receiver=None,         \

        feedback=None          \

        )

    Abstract base class for all Projections.

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

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

    .. note::

       Projection is an abstract class and should *never* be instantiated by a direct call to its constructor.

       It should be created by calling the constructor for a subclass` or by using any of the other methods for

       `specifying a Projection <Projection_Specification>`.

    COMMENT:

    Gotchas

    -------

        When referring to the Mechanism that is a Projection's sender or receiver Mechanism, must add ".owner"

    ProjectionRegistry

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

        All Projections are registered in ProjectionRegistry, which maintains a dict for each subclass,

        a count for all instances of that type, and a dictionary of those instances

    COMMENT

    Arguments

    ---------

    sender : OutputPort or Mechanism : default None

        specifies the source of the Projection's input. If a `Mechanism <Mechanism>` is specified, its

        `primary OutputPort <OutputPort_Primary>` is used. If it is not specified, it is assigned in

        the context in which the Projection is used, or its initialization will be `deferred

        <Projection_Deferred_Initialization>`.

    function : TransferFunction : default MatrixTransform

        specifies function used to convey (and potentially convert) `value <Port_Base.value>` of `sender

        <Projection_Base.sender>` `Port` to `variable <Port_Base.variable>` of `receiver <Projection_Base.receiver>`

        Port.

    receiver : InputPort or Mechanism : default None

        specifies the destination of the Projection's output.  If a `Mechanism <Mechanism>` is specified, its

        `primary InputPort <InputPort_Primary>` will be used. If it is not specified, it will be assigned in

        the context in which the Projection is used, or its initialization will be `deferred

        <Projection_Deferred_Initialization>`.

    feedback : bool or FEEDBACK : default None

        specifies whether Projection is configured as a feedback edge in the graph of a `Composition` to which

        it is assigned (see `Composition_Cycles_and_Feedback`); specifying True or the keyword *FEEDBACK* forces its

        assignment as a *feedback* Projection, whereas False precludes it from being assigned as a feedback Projection;

        None (the default) allows the Composition to determine whether it is assigned as a feedback Projection.

    exclude_in_autodiff : bool : default False

        specifies whether Projection is included in `AutodiffComposition` gradient calculations.

    Attributes

    ----------

    variable : value

        input to Projection, received from `value <OutputPort.value>` of `sender <Projection_Base.sender>`.

    sender : Port

        Port from which Projection receives its input (see `Projection_Sender` for additional information).

    receiver : Port

        Port to which Projection sends its output  (see `Projection_Receiver` for additional information)

    function :  TransferFunction

        conveys (and potentially converts) `variable <Projection_Base.variable>` to `value <Projection_Base.value>`.

    value : value

        output of Projection, transmitted to variable of function of its `receiver <Projection_Base.receiver>`.

    parameter_ports : ContentAddressableList[str, ParameterPort]

        a read-only list of the Projection's `ParameterPorts <Mechanism_ParameterPorts>`, one for each of its

        `modulable parameters <ParameterPort_Modulable_Parameters>`, including those of its `function

        <Projection_Base.function>`.  The value of the parameters of the Projection and its `function

        <Projection_Base.function>` are also accessible as (and can be modified using) attributes of the Projection,

        in the same manner as they can for a `Mechanism <Mechanism_ParameterPorts>`).

    exclude_in_autodiff : bool : default False

        determines whether Projection is included in `AutodiffComposition` gradient calculations.

    weight : number

       multiplies the `value <Projection_Base.value>` of the Projection after applying the `exponent

       <Projection_Base.exponent>`, and before combining with any other Projections that project to the same `Port`

       to determine that Port's `variable <Port_Base.variable>` (see `Projection_Weight_Exponent` for details).

    exponent : number

        exponentiates the `value <Projection_Base.value>` of the Projection, before applying `weight

        <Projection_Base.weight>`, and before combining it with any other Projections that project to the same `Port`

        to determine that Port's `variable <Port_Base.variable>` (see `Projection_Weight_Exponent` for details).

    name : str

        the name of the Projection. If the Projection's `initialization has been deferred

        <Projection_Deferred_Initialization>`, it is assigned a temporary name (indicating its deferred initialization

        status) until initialization is completed, at which time it is assigned its designated name.  If that is the

        name of an existing Projection, it is appended with an indexed suffix, incremented for each Projection with the

        same base name (see `Registry_Naming`). If the name is not  specified in the **name** argument of its

        constructor, a default name is assigned by the subclass (see subclass for details)

    """

        """

            Attributes

            ----------

                exponent

                    see `exponent <Projection_Base.exponent>`

                    :default value: None

                    :type:

                function

                    see `function <Projection_Base.function>`

                    :default value: `MatrixTransform`

                    :type: `Function`

                weight

                    see `weight <Projection_Base.weight>`

                    :default value: None

                    :type:

        """

                 receiver,

                 sender=None,

                 weight=None,

                 exponent=None,

                 function=None,

                 feedback:Optional[Union[bool,Literal[FEEDBACK]]]=None,

                 exclude_in_autodiff=False,

                 params=None,

                 name=None,

                 prefs=None,

                 context=None,

                 **kwargs

                 ):

        """Assign sender, receiver, and execute method and register Mechanism with ProjectionRegistry

        This is an abstract class, and can only be called from a subclass;

           it must be called by the subclass with a context value

        # DOCUMENT:  MOVE TO ABOVE, UNDER INSTANTIATION

        Initialization arguments:

            - sender (Mechanism, Port or dict):

                specifies source of input to Projection (default: senderDefault)

            - receiver (Mechanism, Port or dict)

                 destination of Projection (default: none)

            - params (dict) - dictionary of Projection params:

                + FUNCTION:<method>

        - name (str): if it is not specified, a default based on the class is assigned in register_category,

                            of the form: className+n where n is the n'th instantiation of the class

            - prefs (PreferenceSet or specification dict):

                 if it is omitted, a PreferenceSet will be constructed using the classPreferences for the subclass

                 dict entries must have a preference keyPath as key, and a PreferenceEntry or setting as their value

                 (see Description under PreferenceSet for details)

            - context (str): must be a reference to a subclass, or an exception will be raised

        NOTES:

        * Receiver is required, since can't instantiate a Projection without a receiving Port

        * If sender and/or receiver is a Mechanism, the appropriate Port is inferred as follows:

            MappingProjection:

                sender = <Mechanism>.output_port

                receiver = <Mechanism>.input_port

            ControlProjection:

                sender = <Mechanism>.output_port

                receiver = <Mechanism>.<param> IF AND ONLY IF there is a single one

                            that is a ParameterPort;  otherwise, an exception is raised

        * _instantiate_sender, _instantiate_receiver must be called before _instantiate_function:

            - _validate_params must be called before _instantiate_sender, as it validates PROJECTION_SENDER

            - instantatiate_sender may alter self.defaults.variable, so it must be called before _validate_function

            - instantatiate_receiver must be called before _validate_function,

                 as the latter evaluates receiver.value to determine whether to use self.function or FUNCTION

        * If variable is incompatible with sender's output, it is set to match that and revalidated (_instantiate_sender)

        * if FUNCTION is provided but its output is incompatible with receiver value, self.function is tried

        * registers Projection with ProjectionRegistry

        :param sender: (Port or dict)

        :param receiver: (Port or dict)

        :param param_defaults: (dict)

        :param name: (str)

        :param context: (str)

        :return: None

        """

         # Register with ProjectionRegistry or create one

                          base_class=Projection_Base,

                          name=name,

                          registry=ProjectionRegistry)

        # Create projection's _portRegistry and ParameterPort entry

                          base_class=Port_Base,

                          registry=self._portRegistry)

        # FIX: ADD _validate_variable, THAT CHECKS FOR SENDER?

        # FIX: NEED TO KNOW HERE IF SENDER IS SPECIFIED AS A MECHANISM OR PORT

            # this should become _default_value when that is fully implemented

                              format(self.sender, self.name, self.class_defaults.variable))

        # Assume that if receiver was specified as a Mechanism, it should be assigned to its (primary) InputPort

        # MODIFIED 11/1/17 CW: Added " hasattr(self, "prefs") and" in order to avoid errors. Otherwise, this was being

        # called and yielding an error: " AttributeError: 'MappingProjection' object has no attribute '_prefs' "

                    (self.prefs.verbosePref or self.receiver.prefs.verbosePref)):

                      format(self.receiver.owner.name, self.name))

       # Validate variable, function and params

        # Note: pass name of Projection (to override assignment of componentName in super.__init__)

            default_variable=variable,

            function=function,

            param_defaults=params,

            weight=weight,

            exponent=exponent,

            name=self.name,

            prefs=prefs,

            **kwargs

        )

        """Validate PROJECTION_SENDER and/or sender arg (current self.sender), and assign one of them as self.sender

        Check:

        - that PROJECTION_SENDER is a Mechanism or Port

        - if it is different from .projection_sender, use it

        - if it is the same or is invalid, check if sender arg was provided to __init__ and is valid

        - if sender arg is valid use it (if PROJECTION_SENDER can't be used);

        - if both were not provided, use .projection_sender

        - otherwise, if one was not provided and the other is invalid, generate error

        - when done, sender is assigned to self.sender

        Note: check here only for sender's type, NOT content (e.g., length, etc.); that is done in _instantiate_sender

        :param request_set:

        :param target_set:

        :param context:

        :return:

        """

        # FIX: 10/3/17 SHOULD ADD CHECK THAT RECEIVER/SENDER SOCKET SPECIFICATIONS ARE CONSISTENT WITH

        # FIX:         PROJECTION_TYPE SPECIFIED BY THE CORRESPONDING PORT TYPES

        # Validate sender

                not (target_set[PROJECTION_SENDER] in {None, self.projection_sender})):

            # If PROJECTION_SENDER is specified it will be the sender

        else:

            # PROJECTION_SENDER is not specified or None, so sender argument of constructor will be the sender

                 (inspect.isclass(sender) and issubclass(sender, (Mechanism, Port))))):

            raise ProjectionError(f"Specification of {sender_string} for {self.name} ({sender}) is invalid; "

                                  "it must be a {Mechanism.__name__}, {Port.__name__} or a class of one of these.")

        # Validate receiver

            # If PROJECTION_RECEIVER is specified it will be the receiver

        else:

            # PROJECTION_RECEIVER is not specified or None, so receiver argument of constructor will be the receiver

                 (inspect.isclass(receiver) and issubclass(receiver, (Mechanism, Port))))):

            raise ProjectionError(f"Specification of {receiver_string} for {self.name} ({sender}) is invalid; "

                                  "it must be a {Mechanism.__name__}, {Port.__name__} or a class of one of these.")

        # MODIFIED JDC 7/11/23 NEW:

        # # Validate matrix spec

        # if MATRIX in target_set and target_set[MATRIX] is not None:

        #     matrix = target_set[MATRIX]

        #     # If matrix_spec is keyword and sender and receiver have been instantiated, implement matrix

        #     #   so that it can be passed to function (e.g., MatrixTransform) if needed.

        #     if not is_matrix(matrix):

        #         raise ProjectionError(f"Matrix ('{matrix}') specified for '{self.name}' is not a legal matrix spec.")

        #     if self.sender_instantiated and self.receiver_instantiated:

        #         if isinstance(matrix, (list, np.ndarray)):

        #             # use default value for sender if necessary

        #             sender_len = \

        #                 len(self.sender.value) if self.sender.value is not None \

        #                 else  len(self.sender.defaults.value)

        #             # reduce receiver to 1d array if necessary

        #             receiver_len = len(np.atleast_1d(np.squeeze(self.receiver.variable)))

        #             if matrix.shape != (sender_len, receiver_len):

        #                 raise ProjectionError(f"Shape of matrix ('{matrix.shape}') specified for '{self.name}' "

        #                                       f"does not shapes of its sender and/or receiver "

        #                                       f"({(len(self.sender.value), len(self.receiver.variable))}).")

        # MODIFIED JDC 7/11/23 END

            keyword, self.sender.socket_width, self.receiver.socket_width

        )

        # If Projection has a matrix parameter, it is specified as a keyword arg in the constructor,

        #    and sender and receiver have been instantiated, then implement it:

            else:

                    is_matrix_keyword(matrix)

                    and self.sender_instantiated

                    and self.receiver_instantiated

                ):