MappingProjection

Contents

• Overview

• Creating a MappingProjection

  • Specifying the Matrix Parameter

  • Specifying Learning

  • Deferred Initialization

• Structure

  • MappingProjection_Matrix

  • MappingProjection_Matrix_ParameterPort

• Execution

  • Learning

• Class Reference

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 MatrixTransform, 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:

• by a Composition, when two adjacent Mechanisms in its pathway do not already have a Projection assigned between them (AUTO_ASSIGN_MATRIX is used as the matrix specification, which determines the appropriate matrix by context);

• by an ObjectiveMechanism, from each OutputPort listed in its monitored_output_ports attribute to the corresponding InputPort of the ObjectiveMechanism (AUTO_ASSIGN_MATRIX is used as the matrix specification, which determines the appropriate matrix by context);

• by a LearningMechanism, between it and the other components required to implement learning (see Learning Configurations for details);

• by a ControlMechanism, from the OUTCOME OutputPort of the ObjectiveMechanism that it creates to its OUTCOME InputPort, and from the OutputPorts listed in the ObjectiveMechanism’s monitored_output_ports attribute to the ObjectiveMechanism’s primary InputPort (as described above; an IDENTITY_MATRIX is used for all of these).

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 or array – 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. 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.

• RandomMatrix – assigns a matrix sized appropriately for the sender and receiver, with random values drawn from a uniform distribution with a specified center and range.

• 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 learning method of a Composition, using the tuple format to include a learning specification;

• specifying the MappingProjection (or its MATRIX ParameterPort) as the receiver of a LearningProjection;

• specifying the MappingProjection (or its MATRIX ParameterPort) in the projections argument of the constructor for a LearningSignal

• specifying the MappingProjection (or its MATRIX ParameterPort) in the learning_signals argument of the constructor for a LearningMechanism

Learning can be disabled for a MappingProjection by specifying its learnable argument as False in its constructor. This can be useful for disabling specific MappingProjections in the learning pathway `learning pathway of a Composition.

By default, the learning_rate for a MappingProjection is None, which causes it to inherit the value of the learning_rate Parameter of the Composition to which it belongs. However, a Projection-specific value can be assigned in the learning_rate argument of the MappingProjection’s constructor, or in either the constructor for a Composition or its learn method. See learning_rate and Learning Rate for additional details.

See LearningMechanism for an overview of learning components and a detailed description of Learning Configurations; Learning in a Composition for a description of how learning is implemented within a Composition; 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:

• an existing LearningProjection, LearningSignal, or a constructor for one – the specified Component is used, and defaults are automatically created for the other learning Components;

• 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 that are updated during backwards passes through the network, and then used to update the MappingProjection’s matrix after each batch of train. However, this can be disabled for an individual MappingProjection by specifying the learnable argument as False in its constructor.

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, one of the add learning `pathway 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:

• matrix parameter - used by the MappingProjection’s function to carry out a matrix transformation of its input, that is then provided to its receiver. It can be specified in a variety of ways, as described above.

  • Matrix Dimensionality – this must match the dimensionality of the MappingProjection’s sender and receiver. For a standard 2d “weight” matrix (i.e., one that maps a 1d array from its sender to a 1d array of its receiver), the dimensionality of the sender is the number of rows and of the receiver the number of columns. More generally, the sender dimensionality is the number of outer dimensions (i.e., starting with axis 0 of numpy array) equal to the number of dimensions of its sender’s value, and the receiver dimensionality is the number of inner dimensions equal to its receiver’s variable (equal to the dimensionality of the matrix minus its sender dimensionality).

• MATRIX ParameterPort - this receives any LearningProjections that are assigned to the MappingProjection (see Specifying Learning above), and updates the current value of the MappingProjection’s matrix parameter in response to learning. The function of a MATRIX ParameterPort is an AccumulatorIntegrator, which accumulates the weight changes received from the LearningProjections that project to it (see Learning below). This can be replaced by any function that defines an ADDITIVE_PARAM modulatory parameter), and that takes as its input an array or matrix and returns one of the same size.

• weight and exponent - applied to the value of the MappingProjection before it is combined with other MappingProjections to the same InputPort to determine its value (see description under Projection for additional details).

  Note

  The weight and exponent attributes of a MappingProjection are distinct from those of the InputPort to which it projects. It is also important to recognize that, as noted under Projection, they are not normalized, and thus contribute to the magnitude of the InputPort’s variable and therefore its relationship to that of other InputPorts that may belong to the same Mechanism.

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, governed by its learnable and learning_rate Parameters. Learning 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 MatrixTransform). 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 MatrixTransform 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(message, component=None)

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

MappingProjection( sender=None, receiver=None, matrix=DEFAULT_MATRIX, learnable) 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 (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 MappingProjection is used, or its initialization will be deferred.

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

• matrix (list, np.ndarray, function, RandomMatrix or keyword : default DEFAULT_MATRIX) – specifies the matrix used by function (default: LinearCombination) to transform the value of the sender into a form suitable for the variable of its receiver InputPort (see Specifying the Matrix Parameter for additional details).

• learnable (bool : default True) – specifies whether the MappingProjection’s matrix parameter can be modified by learning (see learnable for additional details).

• learning_rate (float, int or bool : default None) – specifies Projection-specific learning_rate; assigning this if learnable is False raises an error (see learning_rate for additional details).

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

learnable

determines whether the MappingProjection’s matrix parameter can be modified by learning. If it is False, learning is precluded from ever occuring for the MappingProjection, irrespective of value of its learning_rate Parameter or of any for the Composition to which the MappingProjection belongs, and any attempts to assign a `learning_rate <MappingProjection.learning_rate>’ (other than False) raises an error.

Type:

bool

learning_rate

determines Projection-specific learning_rate, that takes effect only if the MappingProjection’s learnable attribute is True. If it is a numeric value, that value is used, unless it is overridden by a value specified for the MappingProjection in the learn method of the Composition to which it belongs (see Learning Rate for additional details); if it is False no learning occurs, even if learnable attribute is True; however, this can later be changed, and also overridden by a specification of the learning_rate for the MappingProjection in the learn method of the Composition. If learning_rate is True or None, the Projection is assigned the value of the learning_rate Parameter of the Composition to which the MappingProjection belongs. The value assigned to learning_rate in the MappingProjection at construction is saved in <MappingProjection>.learning_rate (also accessible as <MappingProjection.parameters.learning_rate.get(None), and remains the same even if the Projection has been assigned a different learning rate in a Composition. If the latter is the case, the value assigned in the constructor to that Composition can be accessed as <MappingProjection>.parameters.learning_rate.get(<Composition.name>_default), and a value assigned in the Composition’s learn method can be accessed as ``<MappingProjection>.parameters.learning_rate.get(<context>) (see Learning Rate for additional details.

Type:

float, int, bool or None

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

alias of OutputPort

_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