GatingSignal

Contents:

• Overview

• Creating a GatingSignal

  • Specifying GatingSignals

• Structure

  • Projections

  • Modulation

• Execution

• Examples

• Class Reference

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 InputPort(s) and/or OutputPort(s) to which they project. A GatingSignal receives the value from the gating_allocation 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 InputPort or OutputPort and is used to modulate the value of that Port.

Creating a GatingSignal

A GatingSignal is created automatically whenever an InputPort or OutputPort of a Mechanism is specified for gating. This can be done either in the gate argument of the constructor for a GatingMechanism, or in the specification of projections to the InputPort or OutputPort. Although a GatingSignal can be created directly using its constructor (or any of the other ways for creating an OutputPort), 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 gate argument of the constructor for a Gating Mechanism, the InputPort(s) and/or OutputPort(s) it gates must be specified. This can take any of the following forms:

• InputPort or OutputPort of a Mechanism;

• Mechanism – the primary `InputPort or OutputPort is used;

• specification dictionary – can take either of the following two forms:

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

    • NAME: str

      the string must be the name of the Port to be gated; the GatingSignal will named by appending “_GatingSignal” to the name of the Port.

    • MECHANISM: Mechanism

      the Mechanism must be the one to the which the Port to be gated belongs.

  • for gating multiple ports, 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 Port 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 Port(s) that it gates; or a VARIABLE entry specifying which item of the GatingMechanism’s gating_allocation it should use as its value; see Custom OutputPorts).

• 2-item tuple: (<Port name or list of Port names>, <Mechanism>) – the 1st item must be the name of the Port (or list of Port 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 InputPort or OutputPort 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 Port Projections for additional details concerning the specification of Projections when creating a Port.

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 Ports 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 Port). The modulation attribute can be specified in the modulation argument of the constructor for a GatingSignal, or in a specification dictionary as described above. 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_allocation, 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 Ports 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 InputPorts and OutputPorts in response to the execution of a GatingSignal are not applied until the Mechanism(s) to which those ports belong are next executed; see Lazy Evaluation for an explanation of “lazy” updating).

Examples

Gate an InputPort and OutputPort. In the following example, Gating Mechanism is configured to gate the primary InputPort of one Mechanism, and the primary OutputPort 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(gate=[my_mechanism_A.input_port,
...                                                 my_mechanism_B.output_port])

Note that, in the gate argument, the first item references a Mechanism (my_mechanism_A) rather than one of its ports – this is all that is necessary, since the default for a GatingSignal is to modulate the primary InputPort of a Mechanism. The second item explicitly specifies the Port to be gated, since it is an OutputPort. This will generate two GatingSignals, each of which will multiplicatively modulate the value of the Port to which it projects. This is because, by default, the modulation attribute of a GatingSignal is the MULTIPLICATIVE_PARAM for the function of the Port to which it projects. For an InputPort, 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 Port`s variable (i.e., its input(s)) to determine its value.

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

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

Note that, again, the gate are listed as Mechanisms, since in this case it is their primary InputPorts 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 InputPort of each of the Mechanisms listed (the next example shows how different InputPorts can be differentially gated by a Gating Mechanism). Finally, note that the value of the modulation arguent specified for the Gating Mechanism (and therefore the default for its GatingSignals) pertains to the function of each InputPort. By default that is a Linear function, the ADDITIVE_PARAM of which is its intercept parameter. Therefore, in the example above, each time the InputPorts are updated, the value of the GatingSignal will be assigned as the intercept of each InputPort’s function, thus adding that amount to the input to the Port before determining its value.

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

>>> my_gating_mechanism = pnl.GatingMechanism(gating_signals=[{pnl.NAME: 'GATING_SIGNAL_A',
...                                                            pnl.MODULATION: pnl.ADDITIVE,
...                                                            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 Ports 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 InputPort 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 MULTIPLICATIVE). Thus, the InputPort of my_input_layer will be additively modulated by GATING_SIGNAL_A, while the InputPorts of my_hidden_layer and my_output_layer will be multiplicativelymodulated 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',
...                                       modulation=pnl.ADDITIVE,
...                                       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.core.components.ports.modulatorysignals.gatingsignal.GatingSignal(owner=None, reference_value=None, default_allocation=0.5, input_shapes=None, transfer_function=None, modulation=None, gate=None, params=None, name=None, prefs=None, **kwargs)

A subclass of ModulatorySignal used by a Gating Mechanism to modulate the value(s) of one more InputPort(s) and/or OutputPort(s). See ControlSignal for additional arguments and attributes).

Parameters

• default_allocation (scalar, list or np.ndarray : defaultGatingAllocation) – specifies the template and default value used for allocation.

• gate (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).

• function (Function or method : default Linear) – specifies the function used to determine the value of the GatingSignal from the value of its owner.

allocation

value assigned by the GatingSignal’s owner, and used as the variable of the GatingSignal’s function to determine its`GatingSignal.intensity`.

Type

float : default: defaultGatingAllocation

function

provides the GatingSignal’s value; the default is an identity function that passes the input to the GatingMechanism as value for the GatingSignal.

Type

TransferFunction : default Linear(slope=1, intercept=0)

value

result of the GatingSignal’s function (same as its gating_signal).

Type

number, list or np.ndarray

intensity

result of the GatingSignal’s function; assigned as the value of the GatingSignal’s GatingProjection, and used to modify the value of the Port(s) to which the GatingSignal’s GatingProjection(s) project; same as gating_signal.

Type

float

gating_signal

result of the GatingSignal’s function (same as its value).

Type

number, list or np.ndarray

modulation

determines the way in the which value of the GatingSignal is used to modify the value of the InputPort(s) and/or OutputPort(s) to which the GatingSignal’s GatingProjection(s) project.

Type

str

efferents

a list of the GatingProjections assigned to (i.e., that project from) the GatingSignal.

Type

[List[GatingProjection]]

errorType

alias of psyneulink.core.components.ports.modulatorysignals.gatingsignal.GatingSignalError

projection_type

alias of psyneulink.core.components.projections.modulatory.gatingprojection.GatingProjection

_instantiate_cost_functions(context)

Override ControlSignal as GatingSignal has not cost functions

exception psyneulink.core.components.ports.modulatorysignals.gatingsignal.GatingSignalError(message, component=None)