Projection¶

Contents¶

Overview

Creating a Projection

Structure

Sender

Receiver

Execution

Class Reference

Overview¶

Projections allow information to be passed between Mechanisms. A Projection takes its input from its sender and transmits that information to its receiver. The sender and receiver of a Projection are always Ports: the sender is always the OutputPort of a Mechanism; the 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 to which they project (i.e., of their receiver):

PathwayProjection
Used in conjunction with ProcessingMechanisms to convey information along a processing pathway. There is currently one on type of PathwayProjection:
- MappingProjection
  takes the value of an OutputPort of a ProcessingMechanism converts it by convolving it with the MappingProjection’s 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).
ModulatoryProjection
takes the value of a ModulatorySignal of a ModulatoryMechanism, uses it to regulate modify the 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 of the Port to which a ModulatoryProjection projects. There are three types of ModulatoryProjections, corresponding to the three types of ModulatoryMechanisms (and corresponding ModulatorySignals; see figure), that project to different types of Ports:
- LearningProjection
  takes the value of a LearningSignal of a LearningMechanism, and transmits this to the ParameterPort of a MappingProjection that uses it to modify its matrix parameter. LearningProjections are used in the learning Pathway(s) of a Composition.
- ControlProjection
  takes the value of a ControlSignal of a ControlMechanism, and transmit this to the ParameterPort of a `ProcessingMechanism that uses it to modify the parameter of the Mechanism (or its function) for which it is responsible.
- GatingProjection
  takes the value of a GatingSignal of a Gating Mechanism, and transmits this to the InputPort or OutputPort of a ProcessingMechanism that uses this to modify the Port’s value. GatingProjections are a special subclass of ControlProjections.

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, or are created automatically, as described below.

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 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). 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 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 and/or its receiver cannot be inferred from the context in which this specification occurs, then its initialization is deferred 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 can also be used to specify the Projection (see value below).

CONTROL_PROJECTION (or CONTROL) – this can be used when specifying a parameter using the tuple format, to create a default ControlProjection to the ParameterPort for that parameter. If the Component to which the parameter belongs is part of a Composition, then a ControlSignal is added to the Composition’s controller and assigned as the ControlProjection’s sender; otherwise, the ControlProjection’s initialization is deferred until the Mechanism is assigned to a Composition, at which time the ControlSignal is added to the Composition’s controller and assigned as its the ControlProjection’s sender. See Specifying Parameters to Control for additional details.

GATING_PROJECTION (or GATE) – this can be used when specifying an InputPort or an OutputPort, to create a default GatingProjection to the Port. If the GatingProjection’s sender cannot be inferred from the context in which this specification occurs, then its initialization is deferred until it can be determined (e.g., a Gating Mechanism 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 of the Projection, which must be compatible with the variable attribute of its receiver. If the Projection is a MappingProjection, the value is interpreted as a matrix specification and assigned as the matrix parameter of the Projection; it must be compatible with the value attribute of its sender and variable attribute of its receiver.

Mechanism – creates a MappingProjection to either the primary InputPort or primary OutputPort, 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 – 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 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 and receiver, or ones specific to a particular type of Projection (see documentation for subclass). If the sender and/or receiver are not specified, their assignment and/or creation are handled in the same manner as described above for keyword specifications.

ProjectionTuple – a 4-item tuple used in the context of a Port specification to create a Projection between it and another 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 to connect with (not the one being connected; that is determined from context)

weight – must be a value specifying the 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 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; 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 if it is a MappingProjection.

Note

A ProjectionTuple should not be confused with a 4-item InputPort specification tuple, which also contains weight and exponent items. In a ProjectionTuple, those items specify the weight and/or exponent assigned to the Projection (see Weight and Exponent), whereas in an InputPort specification tuple 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 in Port).

Automatic creation¶

Under some circumstances Projections are created automatically. For example, a Composition automatically creates a MappingProjection between adjacent ProcessingMechanisms specified in the pathways argument of its constructor (if none is specified) or in its add_linear_processing_pathway method; and, similarly, LearningProjections are automatically created when a learning pathway is added to a Composition.

Deferred Initialization¶

When a Projection is created, its full initialization is deferred until its sender and receiver have been fully specified. This allows a Projection to be created before its sender and/or 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 or 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.

Structure¶

In addition to its function, a Projection has two primary attributes: a sender and receiver. The types of Port(s) 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 attribute.

**Sender, Receiver and Attribute Assignments for Projection Types**¶
Projection	sender (attribute)	receiver (attribute)
MappingProjection	OutputPort (`efferents`)	InputPort (`path_afferents`)
LearningProjection	LearningSignal (`efferents`)	ParameterPort (`mod_afferents`)
ControlProjection	ControlSignal (`efferents`)	InputPort, ParameterPort or OutputPort (`mod_afferents`)
GatingProjection	GatingSignal (`efferents`)	InputPort or OutputPort (`mod_afferents`)

Sender¶

This must be an OutputPort or a ModulatorySignal (a subclass of OutputPort specialized for ModulatoryProjections). The Projection is assigned to the OutputPort or ModulatorySignal’s efferents list and, for ModulatoryProjections, to the list of ModulatorySignals specific to the ModulatoryMechanism from which it projects. The OutputPort or ModulatorySignal’s value is used as the variable for Projection’s 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.

a Mechanism; for a MappingProjection, the Mechanism’s primary OutputPort is assigned as the sender; for a ModulatoryProjection, a ModulatorySignal of the appropriate type is created and assigned to the Mechanism.

If the 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.

Receiver¶

The receiver required by a Projection depends on its type, as listed below:

MappingProjection: InputPort

LearningProjection: ParameterPort (for the matrix of a MappingProjection)

ControlProjection: ParameterPort

GatingProjection: InputPort or OutputPort`

A MappingProjection (as a PathwayProjection) is assigned to the path_afferents attribute of its receiver. The ModulatoryProjections are assigned to the mod_afferents attribute of their receiver.

A 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).

Weight and Exponent¶

Every Projection has a weight and exponent attribute. These are applied to its value before combining it with other Projections that project to the same Port. If both are specified, the exponent is applied before the weight. These attributes determine both how the Projection’s value is combined with others to determine the variable of the Port to which they project.

Note

The weight and exponent attributes of a Projection are not the same as a Port’s weight and exponent attributes. Also, they are not normalized: their aggregate effects contribute to the magnitude of the variable to which they project.

ParameterPorts and Parameters¶

ParameterPorts provide the value for each parameter of a Projection and its function. ParameterPorts and their associated parameters are handled in the same way by Projections as they are for Mechanisms (see ParameterPorts and Parameters for details). The ParameterPorts for a Projection are listed in its parameter_ports attribute.

Execution¶

A Projection cannot be executed directly. It is executed when the Port to which it projects (i.e., its receiver) is updated; that occurs when the Port’s owner Mechanism is executed. When a Projection executes, it gets the value of its sender, assigns this as the variable of its function, calls the function, and provides the result as to its receiver. The function of a Projection converts the value received from its sender to a form suitable as input for its receiver.

Class Reference¶

class psyneulink.core.components.projections.projection.Projection_Base(receiver, sender=None, weight=None, exponent=None, function=None, feedback=None, exclude_in_autodiff=False, params=None, name=None, prefs=None, context=None, **kwargs)¶

Base class for all Projections.

The arguments below can be used in the constructor for any subclass of Mechanism. See Component 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.

Parameters

sender (OutputPort or Mechanism : default None) – specifies the source of the Projection’s input. If a Mechanism is specified, its primary OutputPort 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.
function (TransferFunction : default MatrixTransform) – specifies function used to convey (and potentially convert) value of sender Port to variable of receiver Port.
receiver (InputPort or Mechanism : default None) – specifies the destination of the Projection’s output. If a Mechanism is specified, its primary InputPort 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.
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 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.

variable¶

input to Projection, received from value of sender.

Type: value

sender¶

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

Type: Port

receiver¶

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

Type: Port

function¶

conveys (and potentially converts) variable to value.

Type: TransferFunction

value¶

output of Projection, transmitted to variable of function of its receiver.

Type: value

parameter_ports¶

a read-only list of the Projection’s ParameterPorts, one for each of its modulable parameters, including those of its function. The value of the parameters of the Projection and its function are also accessible as (and can be modified using) attributes of the Projection, in the same manner as they can for a Mechanism).

Type: ContentAddressableList[str, ParameterPort]

exclude_in_autodiff¶

determines whether Projection is included in AutodiffComposition gradient calculations.

Type: bool : default False

weight¶

multiplies the value of the Projection after applying the exponent, and before combining with any other Projections that project to the same Port to determine that Port’s variable (see Weight and Exponent for details).

Type: number

exponent¶

exponentiates the value of the Projection, before applying weight, and before combining it with any other Projections that project to the same Port to determine that Port’s variable (see Weight and Exponent for details).

Type: number

name¶

the name of the Projection. If the Projection’s initialization has been deferred, 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 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)

Type: str

_validate_params(request_set, target_set=None, context=None)¶

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

Parameters

request_set –
target_set –
context –

Returns

_instantiate_sender(sender, context=None)¶

Assign self.sender to OutputPort of sender

Assume self.sender has been assigned in _validate_params, from either sender arg or PROJECTION_SENDER Validate, and assign projection to sender’s efferents attribute

If self.sender is a Mechanism, re-assign it to <Mechanism>.output_port If self.sender is a Port class reference, validate that it is a OutputPort Assign projection to sender’s efferents attribute

_instantiate_receiver(context=None)¶

Call receiver’s owner to add projection to its afferents list

Notes: * Assume that subclasses implement this method in which they:

test whether self.receiver is a Mechanism and, if so, replace with Port appropriate for projection

calls this method (as super) to assign projection to the Mechanism

Constraint that self.value is compatible with receiver.input_port.value
is evaluated and enforced in _instantiate_function, since that may need to be modified (see below)
Verification that projection has not already been assigned to receiver is handled by _add_projection_to;
if it has, a warning is issued and the assignment request is ignored

Parameters: context – (str)
Returns

_delete_projection(context=None)¶: Delete Projection, its entries in receiver and sender Ports, and in ProjectionRegistry

_projection_added(projection, context=None)¶: Stub that can be overidden by subclasses that need to know when a projection is added to the Projection

property parameter_ports¶: Read-only access to _parameter_ports

property _dependent_components¶: Returns a set of Components that will be executed if this Component is executed

property _model_spec_parameter_blacklist¶: A set of Parameter names that should not be added to the generated constructor string