GatingSignal¶
Contents:¶
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’sgating_allocation
it should use as itsvalue
; 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(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]}],
... 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, size=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 thevariable
of the GatingSignal’sfunction
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 itsgating_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 thevalue
of the Port(s) to which the GatingSignal’s GatingProjection(s) project; same asgating_signal
.- Type
float
- gating_signal¶
result of the GatingSignal’s
function
(same as itsvalue
).- Type
number, list or np.ndarray
- modulation¶
determines the way in the which
value
of the GatingSignal is used to modify thevalue
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)¶