# MappingProjection¶

## Overview¶

A MappingProjection transmits the value of an OutputPort of one ProcessingMechanism (its sender) to the InputPort of another (its receiver). The default function for a MappingProjection is LinearMatrix, which uses the MappingProjection’s matrix attribute to transform the value received from its sender and provide the result to its receiver.

## Creating a MappingProjection¶

A MappingProjection can be created in any of the ways that can be used to create a Projection (see Sender and Receiver for specifying its sender and receiver attributes, respectively), or simply by specifying it by its matrix parameter wherever a Projection can be specified.

MappingProjections are also generated automatically in the following circumstances, using a value for its matrix parameter appropriate to the circumstance:

### Specifying the Matrix Parameter¶

When a MappingProjection is created automatically, its matrix attribute is generally assigned using AUTO_ASSIGN_MATRIX, which determines its size by context: an IDENTITY_MATRIX is used if the sender and receiver are of equal length; otherwise a FULL_CONNECTIVITY_MATRIX (all 1’s) is used.

When a MappingProjection is created explicitly, the matrix argument of its constructor can be used to specify its matrix parameter. This is used by the MappingProjection’s function to transform the input from its sender into the value provided to its receiver. It can be specified in any of the following ways:

• List, array or matrix – if it is a list, each item must be a list or 1d np.array of numbers; otherwise, it must be a 2d np.array or np.matrix. In each case, the outer dimension (outer list items, array axis 0, or matrix rows) corresponds to the elements of the sender, and the inner dimension (inner list items, array axis 1, or matrix columns) corresponds to the weighting of the contribution that a given sender makes to the receiver (the number of which must match the length of the receiver’s variable).

• Matrix keyword – used to specify a standard type of matrix without having to specify its individual values, or to allow the type of matrix to be determined by context; any of the matrix keywords can be used.

• Random matrix function (random_matrix) – a convenience function that provides more flexibility than RANDOM_CONNECTIVITY_MATRIX. It generates a random matrix sized for a sender and receiver, with random numbers drawn from a uniform distribution within a specified range and with a specified offset.

• Tuple – used to specify the matrix along with a specification for learning; The tuple must have two items: the first can be any of the specifications described above; the second must be a learning specification.

### Specifying Learning¶

A MappingProjection is specified for learning in any of the following ways:

• in the matrix argument of the MappingProjection’s constructor, using the tuple format described above;

• specifying a MappingProjection in the pathway for a Process, using the tuple format to include a learning specification;

• specifying learning for a Process, which assigns LearningProjections to all of the MappingProjections in the Process’ pathway;

See Learning Mechanism documentation for an overview of learning components and a detailed description of Learning Configurations; see Learning below for a description of how learning modifies a MappingProjection.

#### Specifying Learning in a Tuple¶

A tuple can be used to specify learning for a MappingProjection in the matrix argument of its constructor or in the pathway of a Process. In both cases, the second item of the tuple must be a learning specification, which can be any of the following:

• a reference to the LearningProjection or LearningSignal class, or the keyword LEARNING or LEARNING_PROJECTION – a default set of learning Components is automatically created.

#### Specifying Learning for AutodiffCompositions¶

By default, all MappingProjections in an AutodiffComposition are treated as trainable PyTorch Parameters whose matrices are updated during backwards passes through the network. Optionally, users can specify during instantiation that a projection should not be updated. To do so, set the learnable argument to False in the constructor of the projection.

### Deferred Initialization¶

When a MappingProjection is created, its full initialization is deferred until its sender and receiver have been fully specified. This allows a MappingProjection 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 MappingProjection to be operational, initialization must be completed by calling its deferred_init method. This is not necessary if the MappingProjection is specified in the pathway argument of a Composition’s add_linear_processing_pathway or learning methods, or anywhere else that its sender and receiver can be determined by context.

## Structure¶

In addition to its sender, receiver, and function, a MappingProjection has the following characteristic attributes:

## Execution¶

A MappingProjection uses its function and matrix parameter to transform its sender into a form suitable for the variable of its receiver. A MappingProjection cannot be executed directly. It is executed when the InputPort to which it projects (i.e., its receiver) is updated; that occurs when the InputPort’s owner Mechanism is executed. When executed, the MappingProjection’s MATRIX ParameterPort updates its matrix parameter based on any LearningProjection(s) it receives (listed in the ParameterPort’s mod_afferents attribute). This brings into effect any changes that occurred due to learning. Since this does not occur until the Mechanism that receives the MappingProjection is executed (in accord with Lazy Evaluation), any changes due to learning do not take effect, and are not observable (e.g., through inspection of the matrix attribute or the value of its ParameterPort) until the next TRIAL of execution (see Lazy Evaluation for an explanation of “lazy” updating).

### Learning¶

Learning modifies the matrix parameter of a MappingProjection, under the influence of one or more LearningProjections that project to its MATRIX ParameterPort. This conforms to the general procedures for modulation used by ModulatoryProjections A LearningProjection modulates the function of the MATRIX ParameterPort, which is responsible for keeping a record of the value of the MappingProjection’s matrix, and providing it to the MappingProjection’s function (usually LinearMatrix). By default, the function for the MATRIX ParameterPort is an AccumulatorIntegrator. A LearningProjection modulates it by assigning the value of its additive_param (increment), which is added to its previous_value attribute each time it is executed. The result is that each time the MappingProjection is executed, and in turn executes its MATRIX ParameterPort, the weight changes conveyed to the MappingProjection from any LearningProjection(s) are added to the record of the matrix kept by the MATRIX ParameterPort’s AccumulatorIntegrator function in its previous_value attribute. This is then the value of the matrix used by the MappingProjection’s LinearMatrix function when it is executed. It is important to note that the accumulated weight changes received by a MappingProjection from its LearningProjection(s) are stored by the MATRIX ParameterPort’s function, and not the MappingProjection’s matrix parameter itself; the latter stores the original value of the matrix before learning (that is, its unmodulated value, conforming to the general protocol for modulation in PsyNeuLink). The most recent value of the matrix used by the MappingProjection is stored in the value of its MATRIX ParameterPort. As noted above, however, this does not reflect any changes due to learning on the current TRIAL of execution; those are assigned to the ParameterPort’s value when it executes, which does not occur until the Mechanism that receives the MappingProjection is executed in the next TRIAL of execution (see Lazy Evaluation for an explanation of “lazy” updating).

## Class Reference¶

exception psyneulink.core.components.projections.pathway.mappingprojection.MappingError(error_value)
class psyneulink.core.components.projections.pathway.mappingprojection.MappingProjection(sender=None, receiver=None, weight=None, exponent=None, matrix=None, function=None, params=None, name=None, prefs=None, context=None, learnable=True, **kwargs)

Subclass of Projection that transmits the value of the OutputPort of one Mechanism to the InputPort of another (or possibly itself). See Projection for additional arguments and attributes.

Parameters
sender

the OutputPort of the Mechanism that is the source of the Projection’s input.

Type

OutputPort

receiver

the InputPort of the Mechanism that is the destination of the Projection’s output.

Type

InputPort

matrix

the matrix used by function to transform the input from the MappingProjection’s sender into the value provided to its receiver.

Type

2d np.array

has_learning_projection

identifies the LearningProjection assigned to the MappingProjection’s MATRIX ParameterPort.

Type

bool : None

learning_mechanism

source of the learning signal that determines the changes to the matrix when learning is used.

Type

LearningMechanism

name

the name of the MappingProjection. If the specified name is the name of an existing MappingProjection, it is appended with an indexed suffix, incremented for each MappingProjection 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 using the following format: ‘MappingProjection from <sender Mechanism>[<OutputPort>] to <receiver Mechanism>[InputPort]’ (for example, 'MappingProjection from my_mech_1[OutputPort-0] to my_mech2[InputPort-0]'). If either the sender or receiver has not yet been assigned (the MappingProjection is in deferred initialization), then the parenthesized name of class is used in place of the unassigned attribute (for example, if the sender has not yet been specified: 'MappingProjection from (OutputPort-0) to my_mech2[InputPort-0]').

Type

str

projection_sender
_instantiate_receiver(context=None)

Determine matrix needed to map from sender to receiver

Assign specification to self.matrix_spec attribute Assign matrix to self.matrix attribute