# InputState¶

## Overview¶

The purpose of an InputState is to receive and combine inputs to a Mechanisms, allow them to be modified, and provide them to the Mechanism’s function. An InputState receives input to a Mechanisms provided by the Projections to that Mechanism from others in a Process or System. If the InputState belongs to an ORIGIN Mechanism (see role of Mechanisms in Processes and Systems), then it receives the input specified when that Process or System is run. The PathwayProjections received by an InputState are listed in its path_afferents, and its ModulatoryProjections in its mod_afferents attribute. Its function combines the values received from its PathWayProjections, modifies the combined value according to value(s) any ModulatoryProjections it receives, and provides the result to the assigned item of its owner Mechanism’s variable and input_values attributes (see below and Mechanism InputStates for additional details about the role of InputStates in Mechanisms, and their assignment to the items of a Mechanism’s variable attribute).

## Creating an InputState¶

An InputState can be created by calling its constructor, but in general this is not necessary as a Mechanisms can usually automatically create the InputState(s) it needs when it is created. For example, if the Mechanism is being created within the pathway of a Process, its InputState is created and assigned as the receiver of a MappingProjection from the preceding Mechanism in the pathway. InputStates can also be specified in the input_states argument of a Mechanism’s constructor (see below).

The variable of an InputState can be specified using the variable or size arguments of its constructor. It can also be specified using the projections argument, if neither variable nor size is specified. The projections argument is used to specify Projections to the InputState. If neither the variable nor size arguments is specified, then the value of the Projections(s) or their senders (all of which must be the same length) is used to determine the variable of the InputState.

If an InputState is created using its constructor, and a Mechanism is specified in the owner argument, it is automatically assigned to that Mechanism. Note that its value (generally determined by the size of its variable – see below) must be compatible (in number and type of elements) with the item of its owner’s variable to which it is assigned (see below and Mechanism). If the owner argument is not specified, initialization is deferred.

### Owner Assignment and Deferred Initialization¶

An InputState must be owned by a Mechanism. When InputState is specified in the constructor for a Mechanism (see below), it is automatically assigned to that Mechanism as its owner. If the InputState is created on its own, its owner can specified in the owner argument of its constructor, in which case it is assigned to that Mechanism. If its owner argument is not specified, its initialization is deferred until the InputState is assigned to a Mechanism using the Mechanism’s add_states method.

### Primary InputState¶

Every Mechanism has at least one InputState, referred to as its primary InputState. If InputStates are not explicitly specified for a Mechanism, a primary InputState is automatically created and assigned to its input_state attribute (note the singular), and also to the first entry of the Mechanism’s input_states attribute (note the plural). The value of the primary InputState is assigned as the first (and often only) item of the Mechanism’s variable and input_values attributes.

### InputState Specification¶

#### Specifying InputStates when a Mechanism is created¶

InputStates can be specified for a Mechanism when it is created, in the input_states argument of the Mechanism’s constructor (see examples in State), or in an INPUT_STATES entry of a parameter dictionary assigned to the constructor’s params argument. The latter takes precedence over the former (that is, if an INPUT_STATES entry is included in the parameter dictionary, any specified in the input_states argument are ignored).

Note

Assigning InputStates to a Mechanism in its constructor replaces any that are automatically generated for that Mechanism (i.e., those that it creates for itself by default). If any of those are needed, they must be explicitly specified in the list assigned to the input_states argument, or the INPUT_STATES entry of the parameter dictionary in the params argument. The number of InputStates specified must also be equal to the number of items in the Mechanism’s variable attribute.

##### InputState’svariable, valueand Mechanism’svariable¶

Each InputState specified in the input_states argument of a Mechanism’s constructor must correspond to an item of the Mechanism’s variable attribute (see Mechanism), and the value of the InputState must be compatible with that item (that is, have the same number and type of elements). By default, this is also true of the InputState’s variable attribute, since the default function for an InputState is a LinearCombination, the purpose of which is to combine the inputs it receives and possibly modify the combined value (under the influence of any ModulatoryProjections it receives), but not mutate its form. Therefore, under most circumstances, both the variable of an InputState and its value should match the item of its owner’s variable to which the InputState is assigned.

The format of an InputState’s variable can be specified in a variety of ways. The most straightforward is in the variable argument of its constructor. More commonly, however, it is determined by the context in which it is being created, such as the specification for its owner Mechanism’s variable or for the InputState in the Mechanism’s input_states argument (see below and Mechanism InputState specification for details).

#### Adding InputStates to a Mechanism after it is created¶

InputStates can also be added to a Mechanism, either by creating the InputState on its own, and specifying the Mechanism in the InputState’s owner argument, or by using the Mechanism’s add_states method (see examples in State).

Note

Adding InputStates does not replace any that the Mechanism generates by default; rather they are added to the Mechanism, and appended to the list of InputStates in its input_states attribute. Importantly, the Mechanism’s variable attribute is extended with items that correspond to the value attribute of each added InputState. This may affect the relationship of the Mechanism’s variable to its function, as well as the number of its OutputStates (see note).

If the name of an InputState added to a Mechanism is the same as one that already exists, its name is suffixed with a numerical index (incremented for each InputState with that name; see Naming), and the InputState is added to the list (that is, it will not replace ones that already exist).

#### Forms of Specification¶

InputStates can be specified in a variety of ways, that fall into three broad categories: specifying an InputState directly; use of a State specification dictionary; or by specifying one or more Components that should project to the InputState. Each of these is described below:

Direct Specification of an InputState

• InputState class, keyword INPUT_STATE, or a string – this creates a default InputState; if used to specify an InputState in the constructor for a Mechanism, the item of the owner Mechanism’s variable to which the InputState is assigned is used as the format for the InputStates variable; otherwise, the default for the InputState is used. If a string is specified, it is used as the name of the InputState (see example).

InputState Specification Dictionary

• InputState specification dictionary – this can be used to specify the attributes of an InputState, using any of the entries that can be included in a State specification dictionary (see examples in State). If the dictionary is used to specify an InputState in the constructor for a Mechanism, and it includes a VARIABLE and/or VALUE or entry, the value must be compatible with the item of the owner Mechanism’s variable to which the InputState is assigned (see Mechanism InputState specification).

The PROJECTIONS entry can include specifications for one or more States, Mechanisms and/or Projections that should project to the InputState (including both MappingProjections and/or ModulatoryProjections; however, this may be constrained by or have consequences for the InputState’s variable (see InputState variable: Compatibility and Constraints).

In addition to the standard entries of a State specification dictionary, the dictionary can also include either or both of the following entries specific to InputStates:

• WEIGHT:<number>
the value must be an integer or float, and is assigned as the value of the InputState’s weight attribute (see weight and exponent); this takes precedence over any specification in the weight argument of the InputState’s constructor.

• EXPONENT:<number>
the value must be an integer or float, and is assigned as the value of the InputState’s exponent attribute (see weight and exponent); this takes precedence over any specification in the exponent argument of the InputState’s constructor.

Specification of an InputState by Components that Project to It

An InputState can also be specified by specifying one or more States, Mechanisms or Projections that should project to it, as described below. Specifying an InputState in this way creates both the InputState and any of the specified or implied Projection(s) to it (if they don’t already exist). MappingProjections are assigned to the InputState’s path_afferents attribute, and GatingProjections to its mod_afferents attribute. Any of the following can be used to specify an InputState by the Components that projection to it (see below for an explanation of the relationship between the value of these Components and the InputState’s variable):

• OutputState, GatingSignal, Mechanism, or list with any of these – creates an InputState with Projection(s) to it from the specified State(s) or Mechanism(s). For each Mechanism specified, its primary OutputState (or GatingSignal) is used.
• InputState specification tuples – these are convenience formats that can be used to compactly specify an InputState and Projections to it any of the following ways:

• 2-item tuple: (<State name or list of State names>, <Mechanism>) – 1st item must be the name of an OutputState or Modulatory Signals, or a list of such names, and the 2nd item must be the Mechanism to which they all belong. Projections of the relevant types are created for each of the specified States (see State 2-item tuple for additional details).

• 2-item tuple: (<value, State specification, or list of State specs>, <Projection specification>) – this is a contracted form of the 4-item tuple described below;

• 4-item tuple: (<value, State spec, or list of State specs>, weight, exponent, Projection specification) – this allows the specification of State(s) that should project to the InputState, together with a specification of the InputState’s weight and/or exponent attributes of the InputState, and (optionally) the Projection(s) to it. This can be used to compactly specify a set of States that project the InputState, while using the 4th item to determine its variable (e.g., using the matrix of the Projection specification) and/or attributes of the Projection(s) to it. Each tuple must have at least the following first three items (in the order listed), and can include the fourth:

• value, State specification, or list of State specifications – specifies either the variable of the InputState, or one or more States that should project to it. The State specification(s) can be a (State name, Mechanism) tuple (see above), and/or include Mechanisms (in which case their primary OutputState is used. All of the State specifications must be consistent with (that is, their value must be compatible with the variable of) the Projection specified in the fourth item if that is included;

• weight – must be an integer or a float; multiplies the value of the InputState before it is combined with others by the Mechanism’s function (see ObjectiveMechanism for examples);

• Projection specification (optional) – specifies a Projection that must be compatible with the State specification(s) in the 1st item; if there is more than one State specified, and the Projection specification is used, all of the States must be of the same type (i.e.,either OutputStates or GatingSignals), and the Projection Specification cannot be an instantiated Projection (since a Projection cannot be assigned more than one sender).
• InputStates of Mechanisms to shadow – either of the following can be used to create InputStates that receive the same inputs as (“shadow”) the ones specified:

• InputState or [InputState, …] – each InputState must belong to an existing Mechanism; creates a new InputState for each one specified, along with Projections to it that parallel those of the one specified (see below).

• {SHADOW_INPUTS: <InputState or Mechanism or [<InputState or Mechanism>,…]>} – any InputStates specified must belong to an existing Mechanism; creates a new InputState for each one specified, and for each of the InputStates belonging to any Mechanisms specified, along with Projections to them that parallel those of the one(s) specified (see below).

For each InputState specified, and all of the InputStates belonging to any Mechanisms specified using the formats above, a new InputState is created along with Projections to it that parallel those received by the corresponding InputState – that is, that have the same senders as those that project to the specified InputState, but that project to the one being created. Thus, for each InputState specified, a new one is created that receives exactly the same inputs; that is, “shadows” it.

#### InputState variable: Compatibility and Constraints¶

The variable of an InputState must be compatible with the item of its owner Mechanism’s variable to which it is assigned (see Mechanism_Variable_and_InputStates>). This may have consequences that must be taken into account when specifying an InputState by Components that project to it. These depend on the context in which the specification is made, and possibly the value of other specifications. These considerations and how they are handled are described below, starting with constraints that are given the highest precedence:

default_variable argument for the Mechanism is also specified – the item of the variable to which the InputState is assigned is used to determine the InputState’s variable must. Any other specifications of the InputState relevant to its variable must be compatible with this (for example, specifying it by value or by a MappingProjection or OutputState that projects to it (see above).

## Structure¶

Every InputState is owned by a Mechanism. It can receive one or more MappingProjections from other Mechanisms, as well as from the Process or System to which its owner belongs (if it is the ORIGIN Mechanism for that Process or System). It has the following attributes, that includes ones specific to, and that can be used to customize the InputState:

• weight and exponent – these can be used by the Mechanism to which the InputState belongs when that combines the values of its States (e.g., an ObjectiveMechanism uses the weights and exponents assigned to its InputStates to determine how the values it monitors are combined by its function). The value of each must be an integer or float, and the default is 1 for both.

## Execution¶

An InputState cannot be executed directly. It is executed when the Mechanism to which it belongs is executed. When this occurs, the InputState executes any Projections it receives, calls its function to aggregate the values received from any MappingProjections it receives (listed in its its path_afferents attribute) and modulate them in response to any GatingProjections (listed in its mod_afferents attribute), and then assigns the result to the InputState’s value attribute. This, in turn, is assigned to the item of the Mechanism’s variable and input_values attributes corresponding to that InputState (see Mechanism Variable and InputStates for additional details).

## Class Reference¶

class psyneulink.core.components.states.inputstate.InputState(owner=None, variable=None, size=None, function=LinearCombination(operation=SUM), combine=None, projections=None, weight=None, exponent=None, internal_only=False, params=None, name=None, prefs=None)

Subclass of State that calculates and represents the input to a Mechanism from one or more PathwayProjections.

Parameters: owner (Mechanism) – the Mechanism to which the InputState belongs; it must be specified or determinable from the context in which the InputState is created. reference_value (number, list or np.ndarray) – the value of the item of the owner Mechanism’s variable attribute to which the InputState is assigned; used as the template for the InputState’s value attribute. variable (number, list or np.ndarray) – specifies the template for the InputState’s variable attribute. size (int, list or np.ndarray of ints) – specifies variable as array(s) of zeros if variable is not passed as an argument; if variable is specified, it takes precedence over the specification of size. function (Function or method : default LinearCombination(operation=SUM)) – specifies the function applied to the variable. The default value combines the values of the Projections received by the InputState. Any function can be assigned, however: a) it must produce a result that has the same format (number and type of elements) as the item of its owner Mechanism’s variable to which the InputState has been assigned; b) if it is not a CombinationFunction, it may produce unpredictable results if the InputState receives more than one Projection (see function. combine (SUM or PRODUCT : default None) – specifies the operation argument used by the default LinearCombination function, which determines how the value of the InputState’s projections are combined. This is a convenience argument, that allows the operation to be specified without having to specify the LinearCombination function; it assumes that LinearCombination (the default) is used as the InputState’s function – if it conflicts with a specification of function an error is generated. projections (list of Projection specifications) – specifies the MappingProjection(s) and/or GatingProjection(s) to be received by the InputState, and that are listed in its path_afferents and mod_afferents attributes, respectively (see InputState variable: Compatibility and Constraints for additional details). If projections but neither variable nor size are specified, then the value of the Projection(s) or their senders specified in projections argument are used to determine the InputState’s variable. weight (number : default 1) – specifies the value of the weight attribute of the InputState. exponent (number : default 1) – specifies the value of the exponent attribute of the InputState. internal_only (bool : False) – specifies whether external input is required by the InputState’s owner if its role is EXTERNAL_INPUT (see internal_only for details). params (Dict[param keyword: param value] : default None) – a parameter dictionary that can be used to specify the parameters for the InputState or 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 InputState; see InputState name for details. prefs (PreferenceSet or specification dict : default State.classPreferences) – specifies the PreferenceSet for the InputState; see prefs for details.
owner

Mechanism – the Mechanism to which the InputState belongs.

path_afferents

List[MappingProjection]MappingProjections that project to the InputState (i.e., for which it is a receiver).

mod_afferents

List[GatingProjection]GatingProjections that project to the InputState.

projections

List[Projection] – all of the Projections received by the InputState.

variable

value, list or np.ndarray – the template for the value of each Projection that the InputState receives, each of which must match the format (number and types of elements) of the InputState’s variable. If neither the variable or size argument is specified, and projections is specified, then variable is assigned the value of the Projection(s) or its sender.

function

Function – If it is a CombinationFunction, it combines the values of the PathwayProjections (e.g., MappingProjections) received by the InputState (listed in its path_afferents attribute), under the possible influence of GatingProjections received by the InputState (listed in its mod_afferents attribute). The result is assigned to the InputState’s value attribute. For example, the default (LinearCombination with SUM as it operation) performs an element-wise (Hadamard) sum of its Projection values, and assigns to value an array that is of the same length as each of the Projection values. If the InputState receives only one Projection, then any other function can be applied and it will generate a value that is the same length as the Projection’s value. However, if the InputState receives more than one Projection and uses a function other than a CombinationFunction, a warning is generated and only the value of the first Projection list in path_afferents is used by the function, which may generate unexpected results when executing the Mechanism or Composition to which it belongs.

value

value or ndarray – the output of the InputState’s function, that is assigned to an item of the owner Mechanism’s variable attribute.

label : string or number
the string label that represents the current value of the InputState, according to the owner mechanism’s input_labels_dict. If the current value of the InputState does not have a corresponding label, then the numeric value is returned.
weight : number
see weight and exponent for description.
exponent : number
see weight and exponent for description.
internal_only : bool
determines whether input is required for this InputState from Run or another Composition when the InputState’s owner is executed, and its role is designated as EXTERNAL_INPUT; if True, external input is not required or allowed; otherwise, external input is required.
name : str

the name of the InputState; if it is not specified in the name argument of the constructor, a default is assigned by the InputStateRegistry of the Mechanism to which the InputState belongs. Note that some Mechanisms automatically create one or more non-default InputStates, that have pre-specified names. However, if any InputStates are specified in the input_states argument of the Mechanism’s constructor, those replace those InputStates (see note), and standard naming conventions apply to the InputStates specified, as well as any that are added to the Mechanism once it is created.

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