# OutputState¶

## Overview¶

OutputState(s) represent the result(s) of executing a Mechanism. This may be the result(s) of its function and/or values derived from that result. The full set of results are stored in the Mechanism’s output_values attribute. OutputStates are used to represent individual items of the Mechanism’s value, and/or useful quantities derived from them. For example, the function of a TransferMechanism generates a single result (the transformed value of its input); however, a TransferMechanism can also be assigned OutputStates that represent its mean, variance or other derived values. In contrast, the function of a DDM Mechanism generates several results (such as decision accuracy and response time), each of which can be assigned as the value of a different OutputState. The OutputState(s) of a Mechanism can serve as the input to other Mechanisms (by way of projections), or as the output of a Process and/or System. The OutputState’s efferents attribute lists all of its outgoing projections.

## Creating an OutputState¶

An OutputState can be created by calling its constructor. However, in general this is not necessary, as a Mechanism automatically creates a default OutputState if none is explicitly specified, that contains the primary result of its function. For example, if the Mechanism is created within the pathway of a Process, an OutputState is created and assigned as the sender of a MappingProjection to the next Mechanism in the pathway, or to the Process’ output if the Mechanism is a TERMINAL Mechanism for that Process. Other configurations can also easily be specified using a Mechanism’s output_states argument (see OutputState Specification below). If it is created using its constructor, and a Mechanism is specified in the owner argument, it is automatically assigned to that Mechanism. If its **owner* is not specified, initialization is deferred.

### Owner Assignment and Deferred Initialization¶

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

### Primary OutputState¶

Every Mechanism has at least one OutputState, referred to as its primary OutputState. If OutputStates are not explicitly specified for a Mechanism, a primary OutputState is automatically created and assigned to its output_state attribute (note the singular), and also to the first entry of the Mechanism’s output_states attribute (note the plural). The primary OutputState is assigned an index of ‘0’, and therefore its value is assigned as the first (and often only) item of the Mechanism’s value attribute.

### OutputState Specification¶

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

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

Note

Assigning OutputStates 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 need to be retained, they must be explicitly specified in the list assigned to the output_states argument or the OUTPUT_STATES entry of the parameter dictionary in the params argument). In particular, if the default OutputState – that usually contains the result of the Mechanism’s function – is to be retained, it too must be specified along with any additional OutputStates desired.

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

OutputStates can also be added to a Mechanism, using the Mechanism’s add_states method. Unlike specification in the constructor, this does not replace any OutputStates already assigned to the Mechanism. Doing so appends them to the list of OutputStates in the Mechanism’s output_states attribute, and their values are appended to its output_values attribute. If the name of an OutputState added to a Mechanism is the same as one that is already exists on the Mechanism, its name is suffixed with a numerical index (incremented for each OutputState with that name; see Naming), and the OutputState is added to the list (that is, it does not replace the one that was already there).

##### OutputStatesvariableandvalue¶

Each OutputState created with or assigned to a Mechanism must reference one or more items of the Mechanism’s attributes, that serve as the OutputState’s variable, and are used by its function to generate the OutputState’s value. By default, it uses the first item of its owner Mechanism’s value. However, other attributes (or combinations of them) can be specified in the variable argument of the OutputState’s constructor, or the VARIABLE entry in an OutputState specification dictionary (see OutputState Customization). The specification must be compatible (in the number and type of items it generates) with the input expected by the OutputState’s function. The OutputState’s variable is used as the input to its function to generate the OutputState’s value, possibly modulated by a GatingSignal (see below). The OutputState’s value must, in turn, be compatible with any Projections that are assigned to it, or used to specify it.

The value of each OutputState of a Mechanism is assigned to a corresponding item of the Mechanism’s output_values attribute, in the order in which they are assigned in the output_states argument of its constructor, and listed in its output_states attribute.

Note

The output_values attribute of a Mechanism is not the same as its value attribute:

• a Mechanism’s value attribute contains the full and unmodified results of its function;
• a Mechanism’s output_values attribute contains a list of the value of each of its OutputStates.

#### Forms of Specification¶

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

Direct Specification of an OutputState

OutputState Specification Dictionary

Specifying an OutputState by Components to which it Projects

An OutputState can also be specified by specifying one or more Components to or from which it should be assigned Projection(s). Specifying an OutputState in this way creates both the OutputState and any of the specified or implied Projection(s) (if they don’t already exist). MappingProjections are assigned to the OutputState’s efferents 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 variable of these Components and the OutputState’s value):

• InputState, GatingSignal, Mechanism, or list with any of these – creates an OutputState with the relevant Projection(s). A MappingProjection is created to each InputState or ProcessingMechanism specified (for a Mechanism, its primary InputState is used). A GatingProjection is created for each GatingSignal or GatingMechamism specified (for a GatingMechanism, its first GatingSignal is used).
• OutputState specification tuples – these are convenience formats that can be used to compactly specify an OutputState along with Projections to or from it in any of the following ways:

• 2-item tuple: (<State name or list of State names>, <Mechanism>) – 1st item must be the name of an InputState 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: (<State, Mechanism, or list of them>, <Projection specification>) – this is a contracted form of the 3-item tuple described below

• 3-item tuple: (<value, State spec, or list of State specs>, variable spec, Projection specification) – this allows the specification of State(s) to which the OutputState should project, together with a specification of its variable attribute, and (optionally) parameters of the Projection(s) to use (e.g., their weight and/or exponent attributes. Each tuple must have at least the first two items (in the order listed), and can include the third:

• 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 InputState 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.

• 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 InputStates or GatingSignals), and the Projection Specification cannot be an instantiated Projection (since a Projection cannot be assigned more than one receiver).

#### OutputState variable and value: Compatibility and Constraints¶

The format of an OutputStates’ variable may have consequences that must be taken into account when specifying an OutputState by Components to which it projects. 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:

#### Standard OutputStates¶

Most types of Mechanisms have a standard_output_states class attribute, that contains a list of predefined OutputStates relevant to that type of Mechanism (for example, the TransferMechanism class has OutputStates for calculating the mean, median, variance, and standard deviation of its result). The names of these are listed as attributes of a class with the name <ABBREVIATED_CLASS_NAME>_OUTPUT. For example, the TransferMechanism class defines TRANSFER_OUTPUT, with attributes OUTPUT_MEAN, OUTPUT_MEDIAN, OUTPUT_VARIANCE and OUTPUT_STD_DEV that are the names of predefined OutputStates in its standard_output_states attribute. These can be used in the list of OutputStates specified for a TransferMechanism object, as in the following example:

>>> import psyneulink as pnl
>>> my_mech = pnl.TransferMechanism(default_variable=[0,0],
...                                 function=pnl.Logistic(),
...                                 output_states=[pnl.TRANSFER_OUTPUT.RESULT,
...                                                pnl.TRANSFER_OUTPUT.MEAN,
...                                                pnl.TRANSFER_OUTPUT.VARIANCE])


In this example, my_mech is configured with three OutputStates; the first will be named RESULT and will represent logistic transform of the 2-element input vector; the second will be named OUTPUT_MEAN and will represent mean of the result (i.e., of its two elements); and the third will be named OUTPUT_VARIANCE and contain the variance of the result.

### OutputState Customization¶

An OutputState’s value can be customized by specifying its variable and/or function in the variable and function arguments of the OutputState’s constructor, the corresponding entries (VARIABLE and FUNCTION) of an OutputState specification dictionary, or in the variable spec (2nd) item of a 3-item tuple for the OutputState.

#### OutputStatevariable¶

By default, an OutputState uses the first (and usually only) item of the owner Mechanism’s value as its variable. However, this can be customized by specifying any other item of its owners value, the full value itself, other attributes of the owner, or any combination of these using the following:

OWNER_VALUE – keyword specifying the entire value of the OutputState’s owner.

(OWNER_VALUE, <int>) – tuple specifying an item of the owner’s value indexed by the int; indexing begins with 0 (e.g.; 1 references the 2nd item).

<attribute name> – the name of an attribute of the OutputState’s owner (must be one in the owner’s params_dict dictionary); returns the value of the named attribute for use in the OutputState’s variable.

PARAMS_DICT – keyword specifying the owner Mechanism’s entire params_dict dictionary, that contains entries for all of it accessible attributes. The OutputState’s function must be able to parse the dictionary.

List[<any of the above items>] – this assigns the value of each item in the list to the corresponding item of the OutputState’s variable. This must be compatible (in number and type of elements) with the input expected by the OutputState’s function.

#### OutputStatefunction¶

By default, the function of an OutputState is Linear, which simply assigns the OutputState’s variable as its value. However, a different function can be assigned, to transform and/or combine the item(s) of the OutputState’s variable for use as its value. The function can be a PsyNeuLink Function or any Python function or method, so long as the input it expects is compatible (in number and format of elements) with the OutputState’s variable.

Examples

In the following example, a DDM Mechanism named my_mech is configured with three OutputStates:

>>> my_mech = pnl.DDM(function=pnl.DriftDiffusionAnalytical(),
...                   output_states=[pnl.DDM_OUTPUT.DECISION_VARIABLE,
...                                  pnl.DDM_OUTPUT.PROBABILITY_UPPER_THRESHOLD,
...                                  {pnl.NAME: 'DECISION ENTROPY',
...                                   pnl.VARIABLE: (pnl.OWNER_VALUE, 2),
...                                   pnl.FUNCTION: pnl.Stability(metric=pnl.ENTROPY) }])


The first two are Standard OutputStates that represent the decision variable of the DDM and the probability of it crossing of the upper (vs. lower) threshold. The third is a custom OutputState, that computes the entropy of the probability of crossing the upper threshold. It uses the 3rd item of the DDM’s value (items are indexed starting with 0), which contains the probability of crossing the upper threshold, and uses this as the input to the Stability Function assigned as the OutputState’s function, that computes the entropy of the probability. The three OutputStates will be assigned to the output_states attribute of my_mech, and their values will be assigned as items in its output_values attribute, in the order in which they are listed in the output_states argument of the constructor for my_mech.

Custom OutputStates can also be created on their own, and separately assigned or added to a Mechanism. For example, the DECISION ENTROPY OutputState could be created as follows:

>>> decision_entropy_output_state = pnl.OutputState(name='DECISION ENTROPY',
...                                                 variable=(OWNER_VALUE, 2),
...                                                 function=pnl.Stability(metric=pnl.ENTROPY))


and then assigned either as:

>>> my_mech = pnl.DDM(function=pnl.DriftDiffusionAnalytical(),
...                   output_states=[pnl.DDM_OUTPUT.DECISION_VARIABLE,
...                                  pnl.DDM_OUTPUT.PROBABILITY_UPPER_THRESHOLD,
...                                  decision_entropy_output_state])


or:

>>> another_decision_entropy_output_state = pnl.OutputState(name='DECISION ENTROPY',
...                                                variable=(OWNER_VALUE, 2),
...                                                function=pnl.Stability(metric=pnl.ENTROPY))
>>> my_mech2 = pnl.DDM(function=pnl.DriftDiffusionAnalytical(),
...                    output_states=[pnl.DDM_OUTPUT.DECISION_VARIABLE,
...                                   pnl.DDM_OUTPUT.PROBABILITY_UPPER_THRESHOLD])



Note that another new OutputState had to be used for the second example, as trying to add the first one created for my_mech to my_mech2 would have produced an error (since a State already belonging to one Mechanism can’t be added to another.

## Structure¶

Every OutputState is owned by a Mechanism. It can send one or more MappingProjections to other Mechanisms. If its owner is a TERMINAL Mechanism of a Process and/or System, then the OutputState will also be treated as the output of that Process and/or of a System. It has the following attributes, some of which can be specified in ways that are specific to, and that can be used to customize, the OutputState:

## Execution¶

An OutputState cannot be executed directly. It is executed when the Mechanism to which it belongs is executed. When the Mechanism is executed, the values of its attributes specified for the OutputState’s variable (see OutputState Customization) are used as the input to the OutputState’s function. The OutputState is updated by calling its function. The result, modified by any GatingProjections the OutputState receives (listed in its mod_afferents attribute), is assigned as the value of the OutputState. This is assigned to a corresponding item of the Mechanism’s output_values attribute, and is used as the input to any projections for which the OutputState is the sender.

## Class Reference¶

class psyneulink.core.components.states.outputstate.OutputState(owner, reference_value, variable=None, size=None, function=Linear(), index=PRIMARY, assign=None, projections=None, params=None, name=None, prefs=None, context=None)

Subclass of State that calculates and represents an output of a Mechanism.

Parameters: owner (Mechanism) – the Mechanism to which the OutputState belongs; it must be specified or determinable from the context in which the OutputState is created. reference_value (number, list or np.ndarray) – a template that specifies the format of the OutputState’s variable; if it is specified in addition to the variable argument, then these must be compatible (both in the number and type of elements). It is used to insure the compatibility of the source of the input for the OutputState with its function. variable (number, list or np.ndarray) – specifies the attributes of the OutputState’s owner Mechanism to be used by the OutputState’s function in generating its value. function (Function, function, or method : default Linear) – specifies the function used to transform and/or combine the items designated by the OutputState’s variable into its value, under the possible influence of GatingProjections received by the OutputState. projections (list of Projection specifications) – species the MappingProjection(s) to be sent by the OutputState, and/or GatingProjections(s) to be received (see OutputState_Projections for additional details); these will be listed in its efferents and mod_afferents attributes, respectively (see OutputState_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 OutputState, 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 OutputState; see OutputState name for details. prefs (PreferenceSet or specification dict : default State.classPreferences) – specifies the PreferenceSet for the OutputState; see prefs for details.
owner

Mechanism – the Mechanism to which the OutputState belongs.

mod_afferents

variable

value, list or np.ndarray – the value(s) of the item(s) of the owner Mechanism’s attributes specified in the variable argument of the constructor, or a VARIABLE entry in the OutputState specification dictionary used to construct the OutputState.

function

Function, function, or method – function used to transform and/or combine the value of the items of the OutputState’s variable into its value, under the possible influence of GatingProjections received by the OutputState.

value

number, list or np.ndarray – assigned the result of function; the same value is assigned to the corresponding item of the owner Mechanism’s output_values attribute.

label

string or number – the string label that represents the current value of the OutputState, according to the owner mechanism’s output_labels_dict. If the current value of the OutputState does not have a corresponding label, then the numeric value is returned.

efferents

List[MappingProjection]MappingProjections sent by the OutputState (i.e., for which the OutputState is a sender).

projections

List[Projection] – all of the Projections received and sent by the OutputState.

name

str – the name of the OutputState; if it is not specified in the name argument of the constructor, a default is assigned by the OutputStateRegistry of the Mechanism to which the OutputState belongs. Note that most Mechanisms automatically create one or more Standard OutputStates, that have pre-specified names. However, if any OutputStates are specified in the input_states argument of the Mechanism’s constructor, those replace its Standard OutputStates (see note); standard naming conventions apply to the OutputStates 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 OutputState; 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).

class Parameters(owner, parent=None)
variable
Default value: numpy.array([0]) numpy.ndarray True
owner_value_index

Return index or indices of items of owner.value for any to which OutputState’s variable has been assigned If the OutputState has been assigned to: - the entire owner value (i.e., OWNER_VALUE on its own, not in a tuple)

return owner.value
• a single item of owner.value (i.e., owner.value==(OWNER,index))
return the index of the item
• more than one, return a list of indices
• to no items of owner.value (but possibly other params), return None
class psyneulink.core.components.states.outputstate.StandardOutputStates(owner: psyneulink.core.components.component.Component, output_state_dicts: list, indices: <typecheck.framework.optional object at 0x114d40be0> = None)

Collection of OutputState specification dicts for standard OutputStates of a class.

Parses specification of VARIABLE, assigning indices to OWNER_VALUE if specified. Adds <NAME_INDEX> of each OutputState as property of the owner’s class, that returns the index of the OutputState in the list.

Parameters: owner (Component) – the Component to which this OutputState belongs output_state_dicts (list of dicts) – list of dictionaries specifying OutputStates for the Component specified by owner indices (PRIMARY,) – list of ints (SEQUENTIAL,) – specifies how to assign the (OWNER_VALUE, int) entry for each dict listed in output_state_dicts; The effects of each value of indices are as follows: PRIMARY – assigns (OWNER_VALUE, PRIMARY) to all output_states for which a VARIABLE entry is not specified; SEQUENTIAL – assigns sequentially incremented int to (OWNER_VALUE, int) spec of each OutputState, ignoring any VARIABLE entries previously specified for individual OutputStates; list of ints – assigns each int to an (OWNER_VALUE, int) entry of the corresponding OutputState in output_state_dicts, ignoring any VARIABLE entries previously specified for individual OutputStates; None – assigns None to VARIABLE entries for all OutputStates for which it is not already specified.
data

dict – dictionary of OutputState specification dictionaries

indices

list – list of default indices for each OutputState specified

names

list – list of the default names for each OutputState

get_state_dict(name)

returns a copy of the designated OutputState specification dictionary

get_state_dict(name: str)

Return a copy of the named OutputState dict