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
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
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).
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.
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
attribute. See State Projections for additional details concerning the specification of
Projections when creating a State.
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).
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
It is specified using a value of
The default for ControlSignals and GatingSignals is
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
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
modulation attribute for the AdaptiveMechanism to
which it belongs.
OVERRIDE can be specified for only one ModulatoryProjection to a State; specifying it for more than one causes an error.
Anatomy of Modulation
|Modulatory Component||Default ModulationParam for ModulatorySignal||Recipient State||Default Function (mod param) for Recipient State|
|Control (blue)||MULTIPLICATIVE||Mechanism ParameterState||
|Gating (brown)||MULTIPLICATIVE||Mechanism InputState/OutputState||
|Learning (green)||ADDITIVE||MappingProjection ParameterState||
Detailed View of Modulation
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
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
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
then it will be assigned to the slope parameter of the ParameterState’s
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).
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).
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.
- 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
- 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
PreferenceSetfor the LearningSignal; see
AdaptiveMechanism – the AdaptiveMechanism to which the ModulatorySignal belongs.
ModulationParam – determines how the output of the ModulatorySignal is used to modulate the value of the state(s) being modulated.
[List[GatingProjection]] – a list of the ModulatoryProjections assigned to the ModulatorySignal.
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
- one Modulatory Projections – the following template is used:
“<target Mechanism name> <target State name> <ModulatorySignal type name>”
'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>”
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>”
'ControlMechanism divergent ControlSignal'or
'GatingMechanism divergent GatingSignal').
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.
PreferenceSet or specification dict – the
PreferenceSetfor the ModulatorySignal; if it is not specified in the prefs argument of the constructor, a default is assigned using
classPreferencesdefined in __init__.py (see PreferenceSet for details).