# 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. Note that its variable must be compatible (in number and type of elements) with the item of its owner’s value specified by the OutputState’s index attribute. 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 already exists, 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 ones that were already created).

OutputState’s variable, value, and Mechanism’s value

Each OutputState created with or assigned to a Mechanism must reference one or more items of the Mechanism’s value attribute, that it uses to generate its own value. The item(s) referenced are specified by its index attribute. The OutputState’s variable must be compatible (in number and type of elements) with the item(s) of the Mechanism’s value referenced by its index; by default this is ‘0’, referring to the first item of the Mechanism’s value. The OutputState’s variable is used as the input to its function, which may modify the value under the influence of a GatingSignal; the result may be further modified by the OutputState’s calculate function (e.g., to combine, compare, or otherwise evaluate the index items of the Mechanism’s value), before being assigned to its value (see OutputState Customization for additional details). 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 that the output_values attribute of a Mechanism is not the same as its value attribute, which contains the full and unmodified results of the Mechanism’s function (since, as noted above, OutputStates may modify the item of the Mechanisms value to which they refer).

#### 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

• value – creates a default OutputState using the specified value as the OutputState’s variable. This must be compatible with (have the same number and type of elements as) the item of the owner Mechanism’s value to which the OutputState is assigned (the first item by default, or the one designated by its index attribute). A default name is assigned based on the name of the Mechanism (see Naming).

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>, index, Projection specification) – this allows the specification of State(s) to which the OutputState should project, together with a specification of its index 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 value: Compatibility and Constraints¶

The variable of an OutputState must be compatible with the item of its owner Mechanism’s value referenced by its index attribute. This 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 MEAN, MEDIAN, VARIANCE and STANDARD_DEVIATION 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 MEAN and will represent mean of the result (i.e., of its two elements); and the third will be named VARIANCE and contain the variance of the result.

### OutputState Customization¶

The default OutputState uses the first (and usually only) item of the owner Mechanism’s value as its value. However, this can be modified in two ways, using the OutputState’s index and calculate attributes (see Structure below). If the Mechanism’s function returns a value with more than one item (i.e., a list of lists, or a 2d np.array), then an OutputState can be assigned to any of those items by specifying its index attribute. An OutputState can also be configured to transform the value of the item, by specifying a function for its calculate attribute; the result will then be assigned as the OutputState’s value. An OutputState’s index and calculate attributes can be assigned when the OutputState is assigned to a Mechanism, by including INDEX and CALCULATE entries in a specification dictionary for the OutputState, as in the following example:

>>> my_mech = pnl.DDM(function=pnl.BogaczEtAl(),
...                   output_states=[pnl.DDM_OUTPUT.DECISION_VARIABLE,
...                                  pnl.DDM_OUTPUT.PROBABILITY_UPPER_THRESHOLD,
...                                  {pnl.NAME: 'DECISION ENTROPY',
...                                   pnl.INDEX: 2,
...                                   pnl.CALCULATE: pnl.Stability(metric=pnl.ENTROPY).function }])


In this example, my_mech is configured with three OutputStates. 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 Entropy Function for its calculate attribute, and INDEX is assigned 2 to reference the third item of the DDM’s value attribute (items are indexed starting with 0), which contains the probability of crossing the upper threshold. 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',
...                                                 index=2,
...                                                 calculate=pnl.Stability(metric=pnl.ENTROPY).function)


and then assigned either as:

>>> my_mech = pnl.DDM(function=pnl.BogaczEtAl(),
...                   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',
...                                                index=2,
...                                                calculate=pnl.Stability(metric=pnl.ENTROPY).function)
>>> my_mech2 = pnl.DDM(function=pnl.BogaczEtAl(),
...                    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 produce 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, that includes ones 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, it places the results of its execution in its value attribute. The OutputState’s index attribute designates the item of the Mechanism’s value for use by the OutputState. The OutputState is updated by calling the function specified by its calculate attribute with the designated item of the Mechanism’s value as its input. This is used by the Mechanism’s function, modified by any GatingProjections it receives (listed in its mod_afferents attribute), to generate 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.components.states.outputstate.OutputState(owner, reference_value, variable=None, size=None, function=Linear(), index=PRIMARY, calculate=Linear, 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 item of the owner Mechanism’s value attribute to which the OutputState will be assigned (specified by the index argument). This must match (in number and type of elements) the OutputState’s variable argument. It is used to insure the compatibility of the source of the input for the OutputState with its variable. variable (number, list or np.ndarray) – specifies the template for the OutputState’s variable. size (int, list or 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. As an example, the following mechanisms are equivalent: T1 = TransferMechanism(size = [3, 2]) T2 = TransferMechanism(default_variable = [[0, 0, 0], [0, 0]])  function (Function, function, or method : default Linear) – specifies the function used to transform the item of the owner Mechanism’s value designated by the OutputState’s index attribute, under the possible influence of GatingProjections received by the OutputState. index (int : default PRIMARY) – specifies the item of the owner Mechanism’s value used as input for the function specified by the OutputState’s calculate attribute, to determine the OutputState’s value. calculate (Function, function, or method : default Linear) – specifies the function used to convert the designated item of the owner Mechanism’s value (specified by the OutputState’s index attribute), before it is assigned as the OutputState’s value. The function must accept a value that has the same format (number and type of elements) as the item of the Mechanism’s value. 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 – assigned the item of the owner Mechanism’s value specified by the OutputState’s index attribute.

index

int – the item of the owner Mechanism’s value used as input for the function specified by its calculate attribute (see index for additional details).

calculate

function or method : default Linear(slope=1, intercept=0)) – function used to convert the item of the owner Mechanism’s value specified by the OutputState’s index attribute. The result is combined with the result of the OutputState’s function to determine both the value of the OutputState, as well as the value of the corresponding item of the owner Mechanism’s output_values. The default (Linear) transfers the value unmodified (see calculate for additional details)

function

TransferFunction : default Linear(slope=1, intercept=0)) – function used to assign the result of the OutputState’s calculate function, under the possible influence of GatingProjections received by the OutputState, to its value, as well as to the corresponding item of the owner’s output_values attribute.

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.

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 psyneulink.components.states.outputstate.StandardOutputStates(owner: psyneulink.components.component.Component, output_state_dicts: list, indices: <typecheck.framework.optional object at 0x104f9e0f0> = None)

Collection of OutputState specification dictionaries for standard OutputStates of a class

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 INDEX entry for each dict listed in output_state_dicts; The effects of each value of indices are as follows: PRIMARY – assigns the INDEX for the owner’s primary OutputState to all output_states for which an INDEX entry is not already specified; SEQUENTIAL – assigns sequentially incremented int to each INDEX entry, ignoring any INDEX entries previously specified for individual OutputStates; list of ints – assigns each int to the corresponding entry in output_state_dicts; ignoring any INDEX entries previously specified for individual OutputStates; None – assigns None to INDEX 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

psyneulink.components.states.outputstate.make_readonly_property(val)