# Gating Mechanism¶

## Overview¶

A GatingMechanism is a subclass of ControlMechanism that is restricted to using only GatingSignals, which modulate the input or output of a Mechanism, but not the paramaters of its function. Accordingly, its constructor has a gate argument in place of a control argument. It also lacks several attributes related to control, including those related to costs and net_outcome. In all other respects it is identical to its parent class, ControlMechanism.

## Creating A GatingMechanism¶

A GatingMechanism is created by calling its constructor. When a GatingMechanism is created, the OutputPorts it monitors and the InputPorts and/or OutputPorts it modulates can be specified in the montior_for_gating and gate arguments of its constructor, respectively. Each can be specified in several ways, paralleling those used for a ControlMechanism, and described in Specifying OutputPorts to be monitored and Specifying Parameters to Control respectively. If neither the montior_for_gating or gate arguments is specified, then only the GatingMechanism is constructed, and its inputs and the InputPorts and/or OutputPorts it modulates must be specified in some other way.

### Specifying gating¶

A GatingMechanism is used to modulate the value of an InputPort or OutputPort. An InputPort or OutputPort can be specified for gating by assigning it a GatingProjection or GatingSignal anywhere that the Projections to a Port or its ModulatorySignals can be specified. A Mechanism can also be specified for gating, in which case the primary InputPort of the specified Mechanism is used. Ports (and/or Mechanisms) can also be specified in the gate argument of the constructor for a GatingMechanism. The gate argument must be a list, each item of which must refer to one or more Ports (or the Mechanism(s) to which they belong) to be gated by that GatingSignal. The specification for each item in the list can use any of the forms used to specify a GatingSignal.

#### GatingSignals¶

A GatingSignal is created for each item listed in the gate argument of the constructor, and all of the GatingSignals for a GatingMechanism are listed in its gating_signals attribute. Each GatingSignal is assigned one or more GatingProjections to the InputPort(s) and/or OutputPort(s) it gates. By default, the function of GatingMechanism generates a value – its gating_allocation – with a single item, that is used by all of the GatingMechanism’s GatingSignals. However, if a custom function is specified that generates a gating_allocation with more than one item, different GatingSignals can be assigned to the different items (see Function below).

#### Modulation¶

Each GatingMechanism has a modulation attribute, that provides a default for the way in which its GatingSignals modulate the value of the Ports they gate (see modulation for an explanation of how this attribute is specified and used to modulate the value of a Port). Each GatingSignal uses this value, unless its value is individually specified.

## Structure¶

### Input¶

The input to a GatingMechanism is determined in the same manner as the input to any ControlMechanism.

### Function¶

A GatingMechanism’s function is determined and operates in the same manner as the function of any ControlMechanism.

### Output¶

The OutputPorts of a GatingMechanism are GatingSignals (listed in its gating_signals attribute). It has a GatingSignal for each InputPort and/or OutputPort specified in the gate argument of its constructor, that sends a GatingProjection to those Ports. The GatingSignals are listed in the gating_signals attribute; since they are a type of OutputPort, they are also listed in the GatingMechanism’s output_ports attribute. The InputPorts and/or OutputPorts modulated by a GatingMechanism’s GatingSignals can be displayed using its show method. If the GatingMechanism’s function generates a gating_allocation with a single value (the default), then this is used as the allocation for all of the GatingMechanism’s gating_signals. If the gating_allocation has multiple items, and this is the same as the number of GatingSignals, then each GatingSignal is assigned the value of the corresponding item in the gating_allocation. If there is a different number of gating_signals than the number of items in the gating_allocation, then the index attribute of each GatingSignal must be specified (e.g., in a specification dictionary in the gating_signal argument of the GatingMechanism’s constructor), or an error is generated. The default_allocation attribute can be used to specify a default allocation for GatingSignals that have not been assigned their own default_allocation. The allocation is used by each GatingSignal to determine its intensity, which is then assigned to the value of the GatingSignal’s GatingProjection. The value of the GatingProjection is used to modify the value of the InputPort and/or OutputPort it gates (see Modulation for description of how a GatingSignal modulates the value of a parameter).

## Execution¶

A GatingMechanism executes in the same way as a ProcessingMechanism, based on its place in the Composition’s graph. Because GatingProjections are likely to introduce cycles (recurrent connection loops) in the graph, the effects of a GatingMechanism and its projections will generally not be applied in the first TRIAL (see feedback argument for the add_projection method of Composition for a description of how to configure the initialization of feedback loops in a Composition; also see Scheduler for a description of detailed ways in which a GatingMechanism and its dependents can be scheduled to execute).

When executed, a GatingMechanism uses its input to determine the value of its gating_allocation, each item of which is used by a corresponding GatingSignal to determine its gating_signal and assign to its GatingProjections. In the subsequent TRIAL, each GatingProjection’s value is used by the Port to which it projects to modulate the value of that Port (see modulation fon an explanation of how the value of a Port is modulated).

Note

A Port that receives a GatingProjection does not update its value (and therefore does not reflect the influence of its GatingSignal) until that Port’s owner Mechanism executes (see Lazy Evaluation for an explanation of “lazy” updating).

## Class Reference¶

class psyneulink.core.components.mechanisms.modulatory.gating.gatingmechanism.GatingMechanism(default_gating_allocation=None, monitor_for_gating=None, function=Linear(slope=1, intercept=0), default_allocation=None, gate=None, modulation=MULTIPLICATIVE)

Subclass of ModulatoryMechanism that gates (modulates) the value(s) of one or more Ports. See Mechanism for additional arguments and attributes.

Parameters
• default_gating_allocation (value, list or ndarray : default defaultGatingAllocation) – the default value for each of the GatingMechanism’s GatingSignals; its length must equal the number of items specified in the gate argument.

• size (int, list or 1d np.array of ints) –

specifies default_gating_allocation as an array of zeros if default_gating_allocation is not passed as an argument; if default_gating_allocation is specified, it takes precedence over the specification of size. As an example, the following mechanisms are equivalent:

T1 = TransferMechanism(size = [3, 2])
T2 = TransferMechanism(default_variable = [[0, 0, 0], [0, 0]])


• monitor_for_gating (List[OutputPort or Mechanism] : default None) – specifies the OutputPorts to be monitored by the ObjectiveMechanism, if specified in an objective_mechanism argument (see Objective Mechanism), or directly by the GatingMechanism itself if objective_mechanism is not specified. If any specification is a Mechanism (rather than its OutputPort), its primary OutputPort is used (see Specifying OutputPorts to be monitored for additional details).

• function (TransferFunction : default Linear(slope=1, intercept=0)) – specifies the function used to transform the GatingMechanism’s variable to a gating_allocation.

• default_allocation (number, list or 1d array : None) – specifies the default_allocation of any gating_signals for which the default_allocation was not specified in its constructor (see default_allocation <GatingMechanism.default_allocation> for additional details).

• gate (list[GatingSignal, InputPort, OutputPort, Mechanism, tuple[str, Mechanism], or dict]) – specifies the InputPorts and/or OutputPorts to be gated by the GatingMechanism; the number of items must equal the length of the default_gating_allocation argument; if a Mechanism is specified, its primary InputPort is used (see GatingMechanism_GatingSignals for details).

• modulation (str : MULTIPLICATIVE) – specifies the default form of modulation used by the GatingMechanism’s GatingSignals, unless they are individually specified.

• params (Dict[param keyword: param value] : default None) – a parameter dictionary that can be used to specify the parameters for the Mechanism, parameters for its function, 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 GatingMechanism.

• prefs (PreferenceSet or specification dict : default Mechanism.classPreferences) – specifies the PreferenceSet for the GatingMechanism; see prefs for details.

variable

used as the input to the GatingMechanism’s function. Its format is determined by the default_gating_allocation or size argument of the GatingMechanism’s constructor (see above), and is the same format as its gating_allocation (unless a custom function has been assigned).

Type

value, list or ndarray

monitor_for_gating

each item is an OutputPort monitored by the GatingMechanism or its objective_mechanism if that is specified (see Objective Mechanism); in the latter case, the list returned is ObjectiveMechanism’s monitor attribute.

Type

List[OutputPort]

function

determines the function used to transform the GatingMechanism’s variable to a gating_allocation; the default is an identity function that simply assigns variable as the gating_allocation.

Type

TransferFunction

default_allocation

determines the default_allocation of any gating_signals for which the default_allocation was not specified in its constructor; if it is None (not specified) then the GatingSignal’s parameters.allocation.default_value is used. See documentation for default_allocation argument of GatingSignal constructor for additional details.

Type

number, list or 1d array

gating_allocation

each item is the value assigned as the allocation for the corresponding GatingSignal listed in the gating_signals attribute; the gating_allocation is the same as the GatingMechanism’s value attribute).

Type

2d array

gating_signals

list of GatingSignals for the GatingMechanism, each of which sends GatingProjection(s) to the InputPort(s) and/or OutputPorts that it gates; same as GatingMechanism output_ports attribute.

Type

gating_projections

list of all of the GatingProjections assigned to the GatingMechanism’s GatingSignals (i.e., listed in its gating_signals attribute.

Type

List[GatingProjection]

value

the result of the GatingMechanism’s function; each item is the value assigned to the corresponding GatingSignal listed in gating_signals, and used by each GatingSignal to generate the gating_signal assigned to its GatingProjections; same as the GatingMechanism’s gating_allocation attribute. Default is a single item used by all of the gating_signals.

Type

scalar or 1d np.array of ints

gating_allocation

the result of the GatingMechanism’s function; each item is the value assigned to the corresponding GatingSignal listed in gating_signals, and used by each GatingSignal to generate the gating_signal assigned to its GatingProjections; same as the GatingMechanism’s value attribute. Default is a single item used by all of the gating_signals.

Type

scalar or 1d np.array of ints

modulation

the default form of modulation used by the GatingMechanism’s GatingSignals, unless they are individually specified.

Type

str

name

the name of the GatingMechanism; if it is not specified in the name argument of the constructor, a default is assigned by MechanismRegistry (see Naming for conventions used for default and duplicate names).

Type

str

prefs

the PreferenceSet for the GatingMechanism; if it is not specified in the prefs argument of the constructor, a default is assigned using classPreferences defined in __init__.py (see Preferences for details).

Type

PreferenceSet or specification dict

outputPortTypes
_instantiate_control_signal_type(gating_signal_spec, context)

Instantiate actual ControlSignal, or subclass if overridden

_check_for_duplicates(control_signal, control_signals, context)

Override ControlMechanism to check in self.gating_signals rather than self.control_signals

exception psyneulink.core.components.mechanisms.modulatory.gating.gatingmechanism.GatingMechanismError(error_value)