MappingProjection

Overview

A MappingProjection transmits the value of an OutputState of one ProcessingMechanism (its sender) to the InputState 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 by specifying it by its matrix parameter.

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 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;

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

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 of Process, 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 two 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 <MappingProjection.reciever>. 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 ParameterState - 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 ParameterState 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 can take as its input an array or matrix, and return 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 InputState 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 InputState 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 InputState’s variable and therefore its relationship to that of other InputStates 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 InputState to which it projects (i.e., its receiver) is updated; that occurs when the InputState’s owner Mechanism is executed. When executed, the MappingProjection’s MATRIX ParameterState updates its matrix parameter based on any LearningProjection(s) it receives (listed in the ParameterState’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 ParameterState) 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 ParameterState. This conforms to the general procedures for modulation used by ModulatoryProjections A LearningProjection modulates the function of the MATRIX ParameterState, 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 ParameterState 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 ParameterState, the weight changes conveyed to the MappingProjection from any LearningProjection(s) are added to the record of the matrix kept by the MATRIX ParameterState’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 ParameterState’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 ParameterState. As noted above, however, this does not reflect any changes due to learning on the current TRIAL of execution; those are assigned to the ParameterState’s value when it executes, which does not occur until the Mechanism that receives the MappingProjection is executed in the next TRIAL of execution.

Class Reference

class psyneulink.components.projections.pathway.mappingprojection.MappingProjection(sender=None, receiver=None, matrix=DEFAULT_MATRIX, weight=None, exponent=None, params=None, name=None, prefs=None)

Implements a Projection that transmits the output of one Mechanism to the input of another.

Parameters:
  • sender (Optional[OutputState or Mechanism]) – specifies the source of the Projection’s input. If a Mechanism is specified, its primary OutputState 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.
  • receiver (Optional[InputState or Mechanism]) – specifies the destination of the Projection’s output. If a Mechanism is specified, its primary InputState 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.
  • weight (number : default None) – specifies the value by which to multiply the MappingProjection’s value before combining it with others (see weight for additional details).
  • exponent (number : default None) – specifies the value by which to exponentiate the MappingProjection’s value before combining it with others (see exponent for additional details).
  • matrix (list, np.ndarray, np.matrix, function or keyword : default DEFAULT_MATRIX) – the matrix used by function (default: LinearCombination) to transform the value of the sender into a form suitable for the variable of its receiver.
  • params (Dict[param keyword: param value] : default None) – a parameter dictionary that can be used to specify the parameters for the Projection, its function, and/or a custom function and its parameters. By default, it contains an entry for the Projection’s default assignment (LinearCombination). Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
  • name (str : default see MappingProjection name) – specifies the name of the MappingProjection.
  • prefs (PreferenceSet or specification dict : default State.classPreferences) – specifies the PreferenceSet for the MappingProjection; see prefs for details.
componentType

MAPPING_PROJECTION

sender

OutputState – the OutputState of the Mechanism that is the source of the Projection’s input

receiver

InputState – the InputState of the Mechanism that is the destination of the Projection’s output.

matrix

2d np.array – the matrix used by function to transform the input from the MappingProjection’s sender into the value provided to its receiver.

has_learning_projection

bool : False – identifies whether the MappingProjection’s MATRIX ParameterState has been assigned a LearningProjection.

learning_mechanism

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

value

ndarray – output of MappingProjection, transmitted to variable of its receiver.

weight

number – multiplies value of the MappingProjection after applying exponent, and before combining with any others that project to the same InputState to determine that InputState’s variable (see description above for details).

exponent

number – exponentiates the value of the MappingProjection, before applying weight, and before combining it with any others that project to the same InputState to determine that InputState’s variable (see description above for details).

name

str – 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>[<OutputState>] to <receiver Mechanism>[InputState]’ (for example, 'MappingProjection from my_mech_1[OutputState-0] to my_mech2[InputState-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 (OutputState-0) to my_mech2[InputState-0]').

prefs : PreferenceSet or specification dict
the PreferenceSet for the MappingProjection; if it is not specified in the prefs argument of the constructor, a default is assigned using classPreferences defined in __init__.py (see PreferenceSet for details).