CompositionInterfaceMechanism

Related

• Mechanism
• Composition

Contents

• Overview

• Creation

• Structure

• Execution

• Class Reference

Overview

CompositionInterfaceMechanisms act as interfaces between a Composition and its inputs from and outputs to the environment, or the Components of another Composition within which it is nested.

The CompositionInterfaceMechanism provides both a standard interface through which other Components can interact with the environment and/or Compositions, as well as a means of preserving the modularity of Compositions for compilation. By providing the standard Components for communication among Mechanisms (InputPorts and OutputPorts), Mechanisms (and/or other Compositions) that are INPUT Nodes of a Composition can receive inputs from the environment in the same way that any other Node receives inputs, from afferent Projections (in this case, the input_CIM of the Composition to which they belong); and, similarly, Components that are OUTPUT Nodes of a Composition can either report their outputs to the Composition or, if they are in a nested Composition, send their outputs to Nodes in an enclosing Composition just like any others, using efferent Projections. Similarly, for Compilation, they provide a standard interface through which to provide inputs to a Composition and for aggregating outputs that, again, maintain a standard interface to other Components (which may not be compiled).

Creation

The following three CompositionInterfaceMechanisms are created and assigned automatically to a Composition when it is constructed (and should never be constructed manually): input_CIM, parameter_CIM and output_CIM (see CompositionInterfaceMechanisms for additional details).

Structure

A CompositionInterfaceMechanisms has a set of InputPort / OutputPort pairs that its function – the Identity Function – uses to transmit inputs to CompositionInterfaceMechanism to its outputs. These are listed in its port_map attribute, each entry of which is a key designating the Port of the Component with which the CompositionInterfaceMechanism communicates outside the Composition (i.e., from an input_CIM receives an afferent Projection, a parameter_CIM receives a modulatory projection, or an output_CIM sends an efferent Projection), and the value of which is a tuple containing the corresponding (InputPort, OutputPort) pair used to transmit the information to or from the CompositionInterfaceMechanism. CompositionIntefaceMechanisms can be seen graphically using the show_cim option of the Composition’s show_graph method (see figure below).

Examples of Projections to nested Compositions routed through CompositionInterfaceMechanisms. Panel A: Simple example showing a basic configuration. Panel B: More complex configuration, generated from script below, showing Projections automatically created from the Node of an outer Composition (X) to two INPUT Nodes of a nested Composition, a ControlProjection from a ControlMechanism in the outer Composition to a Node it modulates in the nested one, and from a PROBE Node (B) in the nested Composition to the ControlMechanism that monitors it.

A = ProcessingMechanism(name='A')
B = ProcessingMechanism(name='B')
C = ProcessingMechanism(name='C')
D = ProcessingMechanism(name='D')
E = ProcessingMechanism(name='E')
F = ProcessingMechanism(name='F')
nested_comp = Composition(pathways=[[A,B,C], [D,E,F]], name='NESTED COMPOSITION')
X = ProcessingMechanism(name='INPUT NODE')
Y = ProcessingMechanism(name='OUTPUT NODE')
C = ControlMechanism(name='CONTROL MECHANISM',
                     monitor_for_control=B,
                     control=("slope", E))
outer_comp = Composition(name='OUTER COMPOSITION', pathways=[X, nested_comp, Y, C])
outer_comp.show_graph(show_cim=NESTED, show_node_structure=True)

Execution

A CompositionInterface Mechanism is executed when the Composition to which it belongs is executed, and shown never be executed manually.

Class Reference

class psyneulink.core.components.mechanisms.processing.compositioninterfacemechanism.CompositionInterfaceMechanism(default_variable=None, input_shapes=None, input_ports=None, function=None, composition=None, port_map=None, params=None, name=None, prefs=None)

Subclass of ProcessingMechanism that acts as interface between a Composition and its inputs from and outputs to the environment or other Components (if it is a nested Composition).

See Mechanism for arguments and additional attributes.

function

the function used to transform the variable before assigning it to the Mechanism’s OutputPort(s)

Type

InterfaceFunction : default Identity

port_map

entries are comprised of keys designating a Component outside the Composition with which it communicates, and values tuples that designate the corresponding InputPort - OutputPort pairs used to transmit that information into or out of the Composition (see Structure, and CompositionInterfaceMechanisms under Composition for additional details).

Type

dict[Port:(InputPort,OutputPort)]

class Parameters(owner, parent=None)

function

see function

Default value

Identity

Type

Function

add_ports(ports)

Add one or more Ports to the Mechanism. Only InputPorts and OutputPorts can be added; ParameterPorts cannot be added to a Mechanism after it has been constructed.

If the owner of a Port specified in the ports argument is not the same as the Mechanism to which it is being added an error is generated. If the name of a specified Port is the same as an existing one with the same name, an index is appended to its name, and incremented for each Port subsequently added with the same name (see naming conventions). If a specified Port already belongs to the Mechanism, the request is ignored.

Note

Adding InputPorts to a Mechanism changes the size of its variable attribute, which may produce an incompatibility with its function (see Mechanism InputPorts for a more detailed explanation).

Parameters

• ports (Port or List[Port]) – one more InputPorts or OutputPorts to be added to the Mechanism. Port specification(s) can be an InputPort or OutputPort object, class reference, class keyword, or Port specification dictionary (the latter must have a PORT_TYPE entry specifying the class or keyword for InputPort or OutputPort).

• entries (Returns a dictionary with two) –

• added. (containing the list of InputPorts and OutputPorts) –

• ------- –

• added (Dictionary with entries containing InputPorts and/or OutputPorts) –

remove_ports(ports)

Remove one or more Ports from the Mechanism. Only InputPorts can be removed; ParameterPorts cannot be removed from a Mechanism.

Each Specified port must be owned by the Mechanism, otherwise the request is ignored.

Note

Removing InputPorts from a Mechanism changes the size of its variable attribute, which may produce an incompatibility with its function (see Mechanism InputPorts for more detailed information).

Parameters

ports (Port or List[Port]) – one more ports to be removed from the Mechanism. Port specification(s) can be an Port object or the name of one.

_get_source_node_for_input_CIM(port, start_comp=None)

Return Port, Node and Composition for source of projection to input_CIM from (possibly nested) outer comp Return None if there is no source Node (i.e., port receives input direcdtly from input to outermost Composition) port InputPort or OutputPort of the input_CIM from which the local projection projects; comp Composition at which to begin the search (or continue it when called recursively;

assumes the current CompositionInterfaceMechanism’s Composition by default

Return type

tuple

_get_destination_info_from_input_CIM(port, comp=None)

Return Port, Node and Composition for “ultimate” destination of projection to port. port: InputPort or OutputPort of the input_CIM to which the projection of interest projects;

used to find destination (key) in output_CIM’s port_map.

comp: Composition at which to begin the search (or continue it when called recursively);

assumes the Composition for the input_CIM to which port belongs by default

_get_modulated_info_from_parameter_CIM(port, comp=None)

Return Port, Node and Composition for parameter modulated by ControlSignal that projects to parameter_CIM. port: InputPort or OutputPort of the parameter_CIM to which the ControlSignal projects;

used to find destination (key) in parameter_CIM’s port_map.

comp: Composition at which to begin the search (or continue it when called recursively);

assumes the Composition for the parameter_CIM to which port belongs by default.

_get_source_of_modulation_for_parameter_CIM(port, comp=None)

Return ControlSignal, Node and Composition that projects to a ParameterPort from (possibly nested) outer comp port: InputPort or OutputPort of the parameter_CIM from which the local ControlSignal projects;

used to find source (key) in parameter_CIM’s port_map.

comp: Composition at which to begin the search (or continue it when called recursively);

assumes the Composition for the parameter_CIM to which port belongs by default.

_get_source_info_from_output_CIM(port, comp=None)

Return Port, Node and Composition for “original” source of projection from port. port InputPort or OutputPort of the output_CIM from which the projection of interest projects;

used to find source (key) in output_CIM’s port_map.

comp Composition at which to begin the search (or continue it when called recursively);

assumes the current CompositionInterfaceMechanism’s Composition by default.

Return type

tuple

_get_destination_info_for_output_CIM(port, comp=None)

Return Port, Node and Composition for “ultimate” destination(s) of projection to port. port: InputPort or OutputPort of the output_CIM to which the projection of interest projects;

used to find source (key=SENDER PORT) of the projection to the output_CIM.

comp: Composition at which to begin the search (or continue it when called recursively);

assumes the Composition for the output_CIM to which port belongs by default

Return list of tuples, one for each destination, if there is more than one destination;

this occurs if the source of the projection to the output_CIM (SENDER PORT) is a Node in a nested Composition that is specified to project to more than one Node in the outer Composition

Return None if there are no destination Nodes (i.e., source is output of outermost Composition

Return type

list

_sender_is_probe(output_port)

Return True if source of output_port is a PROBE Node of the Composition to which it belongs