# GatingSignal¶

## Overview¶

A GatingSignal is a type of ModulatorySignal that is specialized for use with a Gating Mechanism and one or more GatingProjections, to modify the value(s) of the InputState(s) and/or OutputState(s) to which they project. A GatingSignal receives the value from the gating_policy of the GatingMechanism to which it belongs, and assigns that as the value of its gating_signal to its GatingProjection(s), each of which projects to an InputState or OutputState and is used to modulate the value of that State.

## Creating a GatingSignal¶

A GatingSignal is created automatically whenever an InputState or OutputState of a Mechanism is specified for gating. This can be done either in the gating_signals argument of the constructor for a GatingMechanism, or in the specification of projections to the InputState or OutputState. Although a GatingSignal can be created directly using its constructor (or any of the other ways for creating an OutputState), this is usually not necessary nor is it advisable, as a GatingSignal has dedicated components and requirements for configuration that must be met for it to function properly.

### Specifying GatingSignals¶

When a GatingSignal is specified in the gating_signals argument of the constructor for a Gating Mechanism, the InputState(s) and/or OutputState(s) it gates must be specified. This can take any of the following forms:

• InputState or OutputState of a Mechanism;
• specification dictionary – can take either of the following two forms:

• for gating a single state, the dictionary can have the following two entries:

• NAME: str
the string must be the name of the State to be gated; the GatingSignal will named by appending “_GatingSignal” to the name of the State.
• MECHANISM: Mechanism
the Mechanism must be the one to the which the State to be gated belongs.
• for gating multiple states, the dictionary can have the following entry:

• <str>:list
the string used as the key specifies the name to be used for the GatingSignal, and each item of the list must be a specification of a State to be gated by the GatingSignal (and that will receive a GatingProjection from it).

The dictionary can also contain entries for any other GatingSignal attributes to be specified (e.g., a MODULATION entry, the value of which determines how the GatingSignal modulates the value of the State(s) that it gates; or a VARIABLE entry specifying which item of the GatingMechanism’s gating_policy it should use as its value; see OutputState Customization).

• 2-item tuple – the 1st item must be the name of the State (or list of State names), and the 2nd item the Mechanism to which it (they) belong(s); this is a convenience format, which is simpler to use than a specification dictionary (see below), but precludes specification of parameters for the GatingSignal.

## Structure¶

A GatingSignal is owned by a Gating Mechanism, and associated with one or more GatingProjections, each of which projects to the InputState or OutputState that it gates.

### Projections¶

When a GatingSignal is created, it can be assigned one or more GatingProjections, 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 will be assigned to its efferents attribute. See State Projections for additional details concerning the specification of Projections when creating a State.

Note

Although a GatingSignal can be assigned more than one GatingProjection, all of those Projections will convey the same gating_signal (received from the GatingMechanism to which the GatingSignal belongs), and use the same form of modulation. This can be useful for implementing broadly projecting modulatory effects.

### Modulation¶

Each GatingSignal has a modulation attribute that determines how the GatingSignal’s value (i.e., its gating_signal) is used by the States to which it projects to modify their value s (see Modulation for an explanation of how the modulation attribute is specified and used to modulate the value of a State). The modulation attribute can be specified in the modulation argument of the constructor for a GatingSignal, or in a specification dictionary as described above. The value must be a value of ModulationParam; if it is not specified, its default is the value of the modulation attribute of the GatingMechanism to which the GatingSignal belongs (which is the same for all of the GatingSignals belonging to that GatingMechanism). The value of the modulation attribute of a GatingSignal is used by all of the GatingProjections that project from that GatingSignal.

## Execution¶

A GatingSignal cannot be executed directly. It is executed whenever the Gating Mechanism to which it belongs is executed. When this occurs, the GatingMechanism provides the GatingSignal with one of the values from its gating_policy, that is used by its function to generate its the value of its gating_signal. That, in turn, is used by its GatingProjection(s) to modulate the value of the States to which they project. How the modulation is executed is determined by the GatingSignal’s modulation attribute (see above, and Modulation for a more detailed explanation of how modulation operates).

Note

The change in the value of InputStates and OutputStates in response to the execution of a GatingSignal are not applied until the Mechanism(s) to which those states belong are next executed; see Lazy Evaluation for an explanation of “lazy” updating).

Examples

Gate an InputState and OutputState. In the following example, Gating Mechanism is configured to gate the primary InputState of one Mechanism, and the primary OutputState of another:

>>> import psyneulink as pnl
>>> my_mechanism_A = pnl.TransferMechanism(name="Mechanism A")
>>> my_mechanism_B = pnl.TransferMechanism(name="Mechanism B")
>>> my_gating_mechanism = pnl.GatingMechanism(gating_signals=[my_mechanism_A.input_state,
...                                                           my_mechanism_B.output_state])


Note that, in the gating_signals argument, the first item references a Mechanism (my_mechanism_A) rather than one of its states – this is all that is necessary, since the default for a GatingSignal is to modulate the primary InputState of a Mechanism. The second item explicitly specifies the State to be gated, since it is an OutputState. This will generate two GatingSignals, each of which will multiplicatively modulate the value of the State to which it projects. This is because, by default, the modulation attribute of a GatingSignal is the MULTIPLICATIVE_PARAM for the function of the State to which it projects. For an InputState, the default function is Linear and its MULTIPLICATIVE_PARAM is its slope parameter. Thus, the value of the GatingSignal is assigned to the slope, which multiplies the States variable (i.e., its input(s)) to determine its value.

Modulate the InputStates of several Mechanisms. In next example, a Gating Mechanism is created that modulates the InputState of all the layers in a 3-layered feedforward neural network. Ordinarily, gating modulates the MULTIPLICATIVE_PARAM of an InputState’s function. In the example, this is changed so that it adds the value of the GatingSignal to the value of each InputState:

>>> my_input_layer = pnl.TransferMechanism(size=3)
>>> my_hidden_layer = pnl.TransferMechanism(size=5)
>>> my_output_layer = pnl.TransferMechanism(size=2)
>>> my_gating_mechanism = pnl.GatingMechanism(gating_signals=[{pnl.NAME: 'GATE_ALL',
...                                                            pnl.PROJECTIONS: [my_input_layer,
...                                                                              my_hidden_layer,
...                                                                              my_output_layer]}],


Note that, again, the gating_signals are listed as Mechanisms, since in this case it is their primary InputStates that are to be gated. Since they are all listed in a single entry of a specification dictionary, they will all be gated by a single GatingSignal named GATE_ALL, that will send a GatingProjection to the InputState of each of the Mechanisms listed (the next example shows how different InputStates can be differentially gated by a Gating Mechanism). Finally, note that the ModulationParam specified for the Gating Mechanism (and therefore the default for its GatingSignals) pertains to the function of each InputState. By default that is a Linear function, the ADDITIVE_PARAM of which is its intercept parameter. Therefore, in the example above, each time the InputStates are updated, the value of the GatingSignal will be assigned as the intercept of each InputState’s function, thus adding that amount to the input to the State before determining its value.

Gate InputStates differentially. In the example above, the InputStates for all of the Mechanisms were gated using a single GatingSignal. In the example below, a different GatingSignal is assigned to the InputState of each Mechanism:

>>> my_gating_mechanism = pnl.GatingMechanism(gating_signals=[{pnl.NAME: 'GATING_SIGNAL_A',
...                                                            pnl.PROJECTIONS: my_input_layer},
...                                                           {pnl.NAME: 'GATING_SIGNAL_B',
...                                                            pnl.PROJECTIONS: [my_hidden_layer,
...                                                                              my_output_layer]}])


Here, two GatingSignals are specified as specification dictionaries, each of which contains an entry for the name of the GatingSignal, and a PROJECTIONS entry that specifies the States to which the GatingSignal should project (i.e., the ones to be gated). Once again, the specifications exploit the fact that the default is to gate the primary InputState of a Mechanism, so those are what are referenced. The first dict also contains a MODULATION entry that specifies the value of the modulation attribute for the GatingSignal. The second one does not, so the default will be used (which, for a GatingSignal, is ModulationParam.MULTIPLICATIVE). Thus, the InputState of my_input_layer will be additively modulated by GATING_SIGNAL_A, while the InputStates of my_hidden_layer and my_output_layer will be multiplicatively modulated by GATING_SIGNAL_B.

Creating and assigning stand-alone GatingSignals. GatingSignals can also be created on their own, and then later assigned to a GatingMechanism. In the example below, the same GatingSignals specified in the previous example are created directly and then assigned to my_gating_mechanism:

>>> my_gating_signal_A = pnl.GatingSignal(name='GATING_SIGNAL_A',
...                                       projections=my_input_layer)
>>> my_gating_signal_B = pnl.GatingSignal(name='GATING_SIGNAL_B',
...                                       projections=[my_hidden_layer,
...                                                    my_output_layer])
>>> my_gating_mechanism = pnl.GatingMechanism(gating_signals=[my_gating_signal_A,
...                                                           my_gating_signal_B])


## Class Reference¶

class psyneulink.components.states.modulatorysignals.gatingsignal.GatingSignal(owner, index=PRIMARY function=Linear(), modulation=ModulationParam.MULTIPLICATIVE, projections=None, params=None, name=None, prefs=None)

A subclass of ModulatorySignal used by a Gating Mechanism to modulate the value(s) of one more InputState(s) and/or OutputState(s).

Parameters: owner (GatingMechanism) – specifies the Gating Mechanism to which to assign the GatingSignal. index (int : default PRIMARY) – specifies the item of the owner GatingMechanism’s gating_policy used as the GatingSignal’s value. function (Function or method : default Linear) – specifies the function used to determine the value of the GatingSignal from the value of its owner. modulation (ModulationParam : default ModulationParam.MULTIPLICATIVE) – specifies the way in which the value the GatingSignal is used to modify the value of the State(s) to which the GatingSignal’s GatingProjection(s) project. projections (list of Projection specifications) – specifies the GatingProjection(s) to be assigned to the GatingSignal, and that will be listed in its efferents attribute (see Projections for additional details). 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 ModulatorySignal name) – specifies the name of the GatingSignal; see GatingSignal name for additional details. prefs (PreferenceSet or specification dict : default State.classPreferences) – specifies the PreferenceSet for the GatingSignal; see prefs for details.
owner

GatingMechanism – the Gating Mechanism to which the GatingSignal belongs.

variable

number, list or np.ndarray – used by function to compute the GatingSignal’s value.

function

TransferFunction : default Linear(slope=1, intercept=0) – provides the GatingSignal’s value; the default is an identity function that passes the input to the GatingMechanism as value for the GatingSignal.

value

number, list or np.ndarray – result of the GatingSignal’s function (same as its gating_signal).

index

int – the item of the owner GatingMechanism’s gating_policy used as the GatingSignal’s value.

gating_signal

number, list or np.ndarray – result of the GatingSignal’s function (same as its value).

modulation : ModulationParam
determines the way in the which value of the GatingSignal is used to modify the value of the State(s) to which the GatingSignal’s GatingProjection(s) project.
efferents : [List[GatingProjection]]
a list of the GatingProjections assigned to (i.e., that project from) the GatingSignal.
name : str

name of the GatingSignal; if not is specified in the name argument of its constructor, a default name is assigned (see name).

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 GatingSignal; 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).