# Modulatory Signals¶

## Overview¶

A ModulatorySignal is a subclass of OutputState that belongs to an AdaptiveMechanism, and is used to modulate the value of one or more States by way of one or more ModulatoryProjections (see ModulatorySignal_Naming for conventions on how modulatory components are named). A ModulatorySignal modulates the value of a State by modifying a parameter of the State’s function. There are three types of ModulatorySignals, each of which is associated with a particular type of AdaptiveMechanism and ModulatoryProjection, and modifies the value of a different type of State, as described below (and shown in the figure):

Modulatory Components and their attributes are named according to the category of modulation:

• AdaptiveMechanism name: <Category>Mechanism (e.g., ControlMechanism)
• ModulatorySignal name: <Category>Signal (e.g., ControlSignal)
• ModulatoryProjection name: <Category>Projection (e.g., ControlProjection)
• List of an AdaptiveMechanism’s ModulatorySignals: <CategoryMechanism>.category_signals (e.g., ControlMechanism.control_signals)
• Value of a ModulatorySignal: <CategorySignal>.category_signal (e.g., ControlSignal.control_signal)

## Creating a ModulatorySignal¶

A ModulatorySignal is a base class, and cannot be instantiated directly. However, the three types of ModulatorySignals listed above can be created directly, by calling the constructor for the desired type. More commonly, however, ModulatorySignals are created automatically by the AdaptiveMechanism to which they belong, or by specifying them in the constructor for an AdaptiveMechanism (the details of which are described in the documentation for each type of ModulatorySignal).

## Structure¶

A ModulatorySignal is associated with one or more ModulatoryProjections of the corresponding type, that project to the State(s), the value(s) of which it modulates. The ModulatoryProjections received by a State are listed in its mod_afferents attribute. The method by which a ModulatorySignal modulates a State’s value is determined by the ModulatorySignal’s modulation attribute, as described below.

### Projections¶

A ModulatorySignal can be assigned one or more ModulatoryProjections, using either the projections argument of its constructor, or in an entry of a dictionary assigned to the params argument with the key PROJECTIONS. These are assigned to its efferents attribute. See State Projections for additional details concerning the specification of Projections when creating a State.

Note

Although a ModulatorySignal can be assigned more than one ModulatoryProjection, all of those Projections receive and convey the same modulatory value (received from the AdaptiveMechanism to which the ModulatorySignal belongs), and use the same form of modulation. This is a common use for some ModulatorySignals (e.g., the use of a single GatingSignal to gate multiple InputState(s) or OutputState(s)), but requires more specialized circumstances for others (e.g., the use of a single LearningSignal for more than one MappingProjection, or a single ControlSignal for the parameters of more than one Mechanism).

### Modulation¶

A ModulatorySignal modulates the value of a State either by modifying a parameter of the State’s function (which determines the State’s value), or by assigning a value to the State directly.

The function of every State designates one of its parameters as its MULTIPLICATIVE_PARAM and another as its ADDITIVE_PARAM; some may also designate other modulatory parameters. The modulation attribute of a ModulatorySignal determines which of these parameters are assigned its value, or which of two other actions to take when the State updates its value. It is specified using a value of ModulationParam.

The default for ControlSignals and GatingSignals is ModulationParam.MULTIPLICATIVE, which multiplicatively modifies the State’s variable by the value of the ModulatorySignal before passing it to the State’s function. The default for LearningSignals is ModulationParam.ADDITIVE, which additively modifies the value of the LearningSignal (i.e., the weight changes computed by the Learning Mechanism) to the State’s variable (i.e., the current weight matrix for the MappingProjection being learned).

The modulation attribute can be specified in the modulation argument of the ModulatorySignal’s constructor, or in a MODULATION entry of a State specification dictionary used to create the ModulatorySignal. If it is not specified when a ModulatorySignal is created, it is assigned the value of the modulation attribute for the AdaptiveMechanism to which it belongs.

Note

OVERRIDE can be specified for only one ModulatoryProjection to a State; specifying it for more than one causes an error.

Anatomy of Modulation

Detailed View of Modulation

## Execution¶

ModulatorySignals cannot be executed. They are updated when the AdaptiveMechanism to which they belong is executed. When a ModulatorySignal is updated, it calculates its value, which is then made available to the ModulatoryProjections listed in its efferents attribute. When those Projections execute, they convey the ModulatorySignal’s value to the function of the State to which they project. The State’s function then uses that value for the parameter designated by the modulation attribute of the ModulatorySignal when the State is updated.

For example, consider a ControlSignal that modulates the bias f parameter of a Logistic Function used by a TransferMechanism, and assume that the ParameterState for the bias parameter (to which the ControlSignal projects) uses a Linear function to update its value (which is the default for a ParameterState). If the modulation attribute of the ControlSignal is ModulationParam.MULTIPLICATIVE, then it will be assigned to the slope parameter of the ParameterState’s function. Accordingly, when the ParameterState is updated it will multiply the bias parameter’s value by the value of the ControlSignal to determine the value of the bias parameter. The result will used as the value of the bias for the Logistic Function when the TransferMechanism is executed (see Execution for additional details).

Note

The change in the value of a State in response to a ModulatorySignal does not occur until the Mechanism to which the state belongs is next executed; see Lazy Evaluation for an explanation of “lazy” updating).

## Class Reference¶

class psyneulink.core.components.states.modulatorysignals.modulatorysignal.ModulatorySignal(owner, function=LinearCombination(operation=SUM), modulation=ModulationParam.MULTIPLICATIVE projections=None, params=None, name=None, prefs=None)

Subclass of OutputState used by an AdaptiveMechanism to modulate the value of one more States.

Note

ModulatorySignal is an abstract class and should NEVER be instantiated by a call to its constructor. It should be instantiated using the constructor for a subclass.

Parameters: owner (GatingMechanism) – specifies the Gating Mechanism to which to assign the ModulatorySignal. function (Function or method : default Linear) – specifies the function used to determine the value of the ModulatorySignal from the value of its owner. modulation (ModulationParam : default ModulationParam.MULTIPLICATIVE) – specifies the type of modulation the ModulatorySignal uses to determine the value of the State(s) it modulates. params (Dict[param keyword: param value] : default None) – a parameter dictionary that can be used to specify the parameters for the ControlSignal and/or a custom function and its parameters. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor. name (str : default see name) – specifies the name of the ModulatorySignal. prefs (PreferenceSet or specification dict : default State.classPreferences) – specifies the PreferenceSet for the LearningSignal; see prefs for details.
owner

variable

number, list or np.ndarray – value assigned by the ModulatorySignal’s owner, and used by the ModulatorySignal’s function to compute its value.

function

TransferFunction : default Linear(slope=1, intercept=0) – provides the ModulatorySignal’s value; the default is an identity function that assigns variable as ModulatorySignal’s value.

value

number, list or np.ndarray – result of function, used to determine the value of the State(s) being modulated.

modulation

ModulationParam – determines how the output of the ModulatorySignal is used to modulate the value of the state(s) being modulated.

efferents

[List[GatingProjection]] – a list of the ModulatoryProjections assigned to the ModulatorySignal.

name

str – the name of the ModulatorySignal. If the ModulatorySignal’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 ModulatorySignal, it is appended with an indexed suffix, incremented for each State 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 as follows; if the ModulatorySignal has:

• no projections (which are used to name it) – the name of its class is used, with an index that is

incremented for each ModulatorySignal with a default named assigned to its owner;

• one Modulatory Projections – the following template is used: “<target Mechanism name> <target State name> <ModulatorySignal type name>” (for example, 'Decision[drift_rate] ControlSignal', or 'Input Layer[InputState-0] GatingSignal');
• multiple ModulatoryProjections, all to States of the same Mechanism – the following template is used: “<target Mechanism name> (<target State name>,…) <ModulatorySignal type name>” (for example, Decision (drift_rate, threshold) ControlSignal, or 'Input Layer[InputState-0, InputState-1] GatingSignal');
• multiple ModulatoryProjections to States of different Mechanisms – the following template is used: “<owner Mechanism’s name> divergent <ModulatorySignal type name>” (for example, 'ControlMechanism divergent ControlSignal' or 'GatingMechanism divergent GatingSignal').

Note

Unlike other PsyNeuLink components, State names are “scoped” within a Mechanism, meaning that States with the same name are permitted in different Mechanisms. However, they are not permitted in the same Mechanism: States within a Mechanism with the same base name are appended an index in the order of their creation.

prefs

PreferenceSet or specification dict – the PreferenceSet for the ModulatorySignal; 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).