OutputPort¶

Overview¶

OutputPort(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. OutputPorts 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 OutputPorts 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 OutputPort. The OutputPort(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 OutputPort’s efferents attribute lists all of its outgoing projections.

Creating an OutputPort¶

An OutputPort can be created by calling its constructor. However, in general this is not necessary, as a Mechanism automatically creates a default OutputPort 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 OutputPort 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_ports argument (see OutputPort 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 OutputPort must be owned by a Mechanism. When OutputPort is specified in the constructor for a Mechanism (see below), it is automatically assigned to that Mechanism as its owner. If the OutputPort 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 OutputPort is assigned to a Mechanism using the Mechanism’s add_ports method.

Primary OutputPort¶

Every Mechanism has at least one OutputPort, referred to as its primary OutputPort. If OutputPorts are not explicitly specified for a Mechanism, a primary OutputPort is automatically created and assigned to its output_port attribute (note the singular), and also to the first entry of the Mechanism’s output_ports attribute (note the plural). The primary OutputPort 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.

OutputPort Specification¶

Specifying OutputPorts when a Mechanism is created¶

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

Note

Assigning OutputPorts 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_ports argument or the OUTPUT_PORTS entry of the parameter dictionary in the params argument). In particular, if the default OutputPort – that usually contains the result of the Mechanism’s function – is to be retained, it too must be specified along with any additional OutputPorts desired.

Adding OutputPorts to a Mechanism after it is created¶

OutputPorts can also be added to a Mechanism, using the Mechanism’s add_ports method. Unlike specification in the constructor, this does not replace any OutputPorts already assigned to the Mechanism. Doing so appends them to the list of OutputPorts in the Mechanism’s output_ports attribute, and their values are appended to its output_values attribute. If the name of an OutputPort 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 OutputPort with that name; see Naming), and the OutputPort is added to the list (that is, it does not replace the one that was already there).

OutputPortsvariableandvalue¶

Each OutputPort created with or assigned to a Mechanism must reference one or more items of the Mechanism’s attributes, that serve as the OutputPort’s variable, and are used by its function to generate the OutputPort’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 OutputPort’s constructor, or the VARIABLE entry in an OutputPort specification dictionary (see Custom OutputPorts). The specification must be compatible (in the number and type of items it generates) with the input expected by the OutputPort’s function. The OutputPort’s variable is used as the input to its function to generate the OutputPort’s value, possibly modulated by a GatingSignal (see below). The OutputPort’s value must, in turn, be compatible with any Projections that are assigned to it, or used to specify it.

The value of each OutputPort 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_ports argument of its constructor, and listed in its output_ports 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 OutputPorts.

Forms of Specification¶

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

Direct Specification of an OutputPort

• OutputPort class, keyword OUTPUT_PORT, or a string – creates a default OutputPort that uses the first item of the owner Mechanism’s value as its variable, and assigns it as the owner Mechanism’s primary OutputPort. If the class name or OUTPUT_PORT keyword is used, a default name is assigned to the Port; if a string is specified, it is used as the name of the OutputPort (see Naming).

OutputPort Specification Dictionary

Specifying an OutputPort by Components to which it Projects

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

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

• 2-item tuple: (<Port name or list of Port names>, <Mechanism>) – 1st item must be the name of an InputPort or ModulatorySignal, 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 Ports (see Port 2-item tuple for additional details).

• 2-item tuple: (<Port, Mechanism, or list of them>, <Projection specification>) – this is a contracted form of the 3-item tuple described below

• 3-item tuple: (<value, Port spec, or list of Port specs>, variable spec, Projection specification) – this allows the specification of Port(s) to which the OutputPort 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, Port specification, or list of Port specifications – specifies either the variable of the InputPort, or one or more Ports that should project to it. The Port specification(s) can be a (Port name, Mechanism) tuple (see above), and/or include Mechanisms, in which case their primary InputPort is used. All of the Port 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.
• variable spec – specifies the attributes of the OutputPort’s owner Mechanism used for its variable (see Custom OutputPorts).
• Projection specification (optional) – specifies a Projection that must be compatible with the Port specification(s) in the 1st item; if there is more than one Port specified, and the Projection specification is used, all of the Ports must be of the same type (i.e.,either InputPorts or GatingSignals), and the Projection Specification cannot be an instantiated Projection (since a Projection cannot be assigned more than one receiver).

OutputPort variable and value: Compatibility and Constraints¶

The format of an OutputPorts’ variable may have consequences that must be taken into account when specifying an OutputPort 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 OutputPorts¶

# FIX: 11/9/19: REPLACE RECURRENTTRANSFERMECHNISM EXAMPLE WITH TRANSFERMECHANISM Mechanisms have a standard_output_ports attribute, that contains a list of StandardOutputPorts: OutputPort specification dictionaries that can be assigned as output_ports. There is a base set of StandardOutputPorts for all Mechanisms. Subclasses of Mechanisms may add ones that are specific to that type of Mechanism (for example, the RecurrentTransferMechanism class has standard_output_ports for calculating the energy and entropy of its value. The names of the standard_output_ports are listed in the Mechanism’s standard_output_port_names attribute. These can be used to specify the output_ports of a Mechanism, as in the following example for a ProcessingMechanism:

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


In this example, my_mech is configured with three OutputPorts; 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.

Custom OutputPorts¶

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

OutputPortvariable¶

By default, an OutputPort uses the first (and often 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 OutputPort’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 OutputPort’s owner (must be one in the owner’s Parameters class); returns the value of the named attribute for use in the OutputPort’s variable.

PARAMS_DICT – keyword specifying the owner Mechanism’s entire dictionary of Parameters, that contains its own Parameters, its function <Mechanism.function’s Parameters, and the current variable for the Mechanism’s input_ports. The OutputPort’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 OutputPort’s variable. This must be compatible (in number and type of elements) with the input expected by the OutputPort’s function.

OutputPortfunction¶

By default, the function of an OutputPort is Linear, which simply assigns the OutputPort’s variable as its value. However, a different function can be assigned, to transform and/or combine the item(s) of the OutputPort’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 OutputPort’s variable.

Examples

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

>>> my_mech = pnl.DDM(function=pnl.DriftDiffusionAnalytical(),
...                   output_ports=[pnl.DECISION_VARIABLE,
...                                  pnl.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 OutputPorts 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 OutputPort, 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 OutputPort’s function, that computes the entropy of the probability. The three OutputPorts will be assigned to the output_ports 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_ports argument of the constructor for my_mech.

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

>>> decision_entropy_output_port = pnl.OutputPort(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_ports=[pnl.DECISION_VARIABLE,
...                                  pnl.PROBABILITY_UPPER_THRESHOLD,
...                                  decision_entropy_output_port])


or:

>>> another_decision_entropy_output_port = pnl.OutputPort(name='DECISION ENTROPY',
...                                                variable=(OWNER_VALUE, 2),
...                                                function=pnl.Stability(metric=pnl.ENTROPY))
>>> my_mech2 = pnl.DDM(function=pnl.DriftDiffusionAnalytical(),
...                    output_ports=[pnl.DECISION_VARIABLE,
...                                   pnl.PROBABILITY_UPPER_THRESHOLD])



Note that another new OutputPort 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 Port already belonging to one Mechanism can’t be added to another.

Structure¶

Every OutputPort 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 OutputPort 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 OutputPort:

Execution¶

An OutputPort 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 OutputPort’s variable (see Custom OutputPorts) are used as the input to the OutputPort’s function. The OutputPort is updated by calling its function. The result, modified by any GatingProjections the OutputPort receives (listed in its mod_afferents attribute), is assigned as the value of the OutputPort. 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 OutputPort is the sender.

Class Reference¶

class psyneulink.core.components.ports.outputport.OutputPort(owner=None, reference_value=None, variable=None, size=None, function=None, projections=None, params=None, name=None, prefs=None, index=None, assign=None, **kwargs)

Subclass of Port that calculates and represents an output of a Mechanism. See Class Reference for additional arguments and attributes.

Parameters: reference_value (number, list or np.ndarray) – a template that specifies the format of the OutputPort’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 OutputPort with its function. variable (number, list or np.ndarray) – specifies the attributes of the OutputPort’s owner Mechanism to be used by the OutputPort’s function in generating its value. function (Function, function, or method : default Linear) – specifies the function used to transform and/or combine the items of its owner’s value (designated by the OutputPort’s variable) into its value, under the possible influence of ControlProjections or GatingProjections received by the OutputPort. projections (list of Projection specifications) – specifies the MappingProjection(s) to be sent by the OutputPort, and/or ControlProjections and/or GatingProjections(s) to be received (see OutputPort_Projections for additional details); these are listed in its efferents and mod_afferents attributes, respectively (see OutputPort_Projections for additional details).
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 OutputPort specification dictionary used to construct the OutputPort.

function

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

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 OutputPort, according to the owner mechanism’s output_labels_dict. If the current value of the OutputPort does not have a corresponding label, then the numeric value is returned.

name

str – the name of the OutputPort; if it is not specified in the name argument of the constructor, a default is assigned by the OutputPortRegistry of the Mechanism to which the OutputPort belongs. Note that most Mechanisms automatically create one or more Standard OutputPorts, that have pre-specified names. However, if any OutputPorts are specified in the input_ports argument of the Mechanism’s constructor, those replace its Standard OutputPorts (see note); standard naming conventions apply to the OutputPorts specified, as well as any that are added to the Mechanism once it is created (see note).

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

Check if projection is redundant with one in efferents of OutputPort

Check for any instantiated projection in efferents with the same receiver as projection or one in deferred_init status with receiver specification that is the same type as projection.

Returns redundant Projection if found, otherwise False.

_instantiate_attributes_before_function(function=None, context=None)

Instantiate default variable if it is None or numeric :param function:

_instantiate_projections(projections, context=None)

Instantiate Projections specified in PROJECTIONS entry of params arg of Port’s constructor

Assume specification in projections as ModulatoryProjection if it is a:
ModulatoryProjection ModulatorySignal ModulatoryMechanism

Call _instantiate_projections_to_port to assign ModulatoryProjections to .mod_afferents

Assume all remaining specifications in projections are for outgoing MappingProjections;
these should be either Mechanisms, Ports or MappingProjections to one of those

Call _instantiate_projections_from_port to assign MappingProjections to .efferents

Store result of function as self.function_value function_value is converted to returned value by assign function

_parse_port_specific_specs(owner, port_dict, port_specific_spec)

Get variable spec and/or connections specified in an OutputPort specification tuple

Tuple specification can be:
(port_spec, connections) (port_spec, variable spec, connections)

Returns: 1st item of tuple - params dict with VARIABLE and/or PROJECTIONS entries if either of them was specified port_spec
_validate_against_reference_value(reference_value)

Validate that Port.variable is compatible with the reference_value

reference_value is the value of the Mechanism to which the OutputPort is assigned

owner_value_index

Return index or indices of items of owner.value for any to which OutputPort’s variable has been assigned If the OutputPort 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
projection_type

alias of MappingProjection

class psyneulink.core.components.ports.outputport.StandardOutputPorts(owner, output_port_dicts, indices=None)

Collection of OutputPort specification dicts for standard OutputPorts of a class.

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

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

dict – dictionary of OutputPort specification dictionaries

indices

list – list of default indices for each OutputPort specified

names

list – list of the default names for each OutputPort

get_port_dict(name)

returns a copy of the designated OutputPort specification dictionary

get_port_dict(name)

Return a copy of the named OutputPort dict