Composition

Overview

Composition is the base class for objects that combine PsyNeuLink Components into an executable model. It defines a common set of attributes possessed, and methods used by all Composition objects.

Composition “Nodes” are Mechanisms and/or nested Compositions. Projections connect two Nodes. The Composition’s graph stores the structural relationships among the Nodes of a Composition and the Projections that connect them.

The Composition’s scheduler generates an execution queue based on these structural dependencies, allowing for other user-specified scheduling and termination conditions to be mixed in.

Creating a Composition

A generic Composition can be created by calling the constructor, and then adding Components using the following Composition methods:

  • add_node
    Adds a node to the Composition
  • add_nodes
    Adds mutiple nodes to the Composition
  • add_projection
    Adds a connection between a pair of nodes in the Composition
  • add_projections
    Adds connection between multiple pairs of nodes in the Composition
  • add_linear_processing_pathway
    Adds and connects a list of nodes and/or Projections to the Composition; Inserts a default Projection between any adjacent Nodes

Note

Only Nodes and Projections added to a Composition via the methods above constitute a Composition, even if other Nodes and/or Projections are constructed in the same script.

In the following script comp_0, comp_1 and comp_2 are identical, but constructed using different methods.

Create Mechanisms:

>>> import psyneulink as pnl
>>> A = pnl.ProcessingMechanism(name='A')
>>> B = pnl.ProcessingMechanism(name='B')
>>> C = pnl.ProcessingMechanism(name='C')

Create Projections:

>>> A_to_B = pnl.MappingProjection(name="A-to-B")
>>> B_to_C = pnl.MappingProjection(name="B-to-C")

Create Composition; Add Nodes (Mechanisms) and Projections via the add_linear_processing_pathway method:

>>> comp_0 = pnl.Composition(name='comp-0')
>>> comp_0.add_linear_processing_pathway(pathway=[A, A_to_B, B, B_to_C, C])

Create Composition; Add Nodes (Mechanisms) and Projections via the add_nodes and add_projection methods:

>>> comp_1 = pnl.Composition(name='comp-1')
>>> comp_1.add_nodes(nodes=[A, B, C])
>>> comp_1.add_projection(projection=A_to_B)
>>> comp_1.add_projection(projection=B_to_C)

Create Composition; Add Nodes (Mechanisms) and Projections via the add_node and add_projection methods:

>>> comp_2 = pnl.Composition(name='comp-2')
>>> comp_2.add_node(node=A)
>>> comp_2.add_node(node=B)
>>> comp_2.add_node(node=C)
>>> comp_2.add_projection(projection=A_to_B)
>>> comp_2.add_projection(projection=B_to_C)

Run each Composition:

>>> input_dict = {A: [[[1.0]]]}
>>> comp_0_output = comp_0.run(inputs=input_dict)
>>> comp_1_output = comp_1.run(inputs=input_dict)
>>> comp_2_output = comp_2.run(inputs=input_dict)

Running a Composition

Inputs

The run method presents the inputs for each TRIAL to the input_states of the INPUT Nodes in the scope of execution. These input values are specified in the inputs argument of a Composition’s execute or run method.

The standard way to specificy inputs is a Python dictionary in which each key is an INPUT Node and each value is a list. The lists represent the inputs to the key INPUT Nodes, such that the i-th element of the list represents the input value to the key Node on trial i.

Example input specifications with input states

Each input value must be compatible with the shape of the key INPUT Node’s external_input_values. As a result, each item in the list of inputs is typically a 2d list/array, though some shorthand notations are allowed.

>>> import psyneulink as pnl
>>> a = pnl.TransferMechanism(name='a',
...                           default_variable=[[0.0, 0.0]])
>>> b = pnl.TransferMechanism(name='b',
...                           default_variable=[[0.0], [0.0]])
>>> c = pnl.TransferMechanism(name='c')
>>> pathway1 = [a, c]
>>> pathway2 = [b, c]
>>> comp = Composition(name='comp')
>>> comp.add_linear_processing_pathway(pathway1)
>>> comp.add_linear_processing_pathway(pathway2)
>>> input_dictionary = {a: [[[1.0, 1.0]], [[1.0, 1.0]]],
...                     b: [[[2.0], [3.0]], [[2.0], [3.0]]]}
>>> comp.run(inputs=input_dictionary)

Note

A Node’s external_input_values attribute is always a 2d list in which the index i element is the value of the Node’s index i external_input_state. In many cases, external_input_values is the same as variable. Keep in mind that any InputStates marked as “internal” are excluded from external_input_values, and do not receive user-specified input values.

If num_trials is not in use, the number of inputs provided determines the number of trials in the run. For example, if five inputs are provided for each INPUT Node, and num_trials is not specified, the Composition executes five times.

Trial # 0 1 2 3 4
Input to Mechanism a 1.0 2.0 3.0 4.0 5.0
>>> import psyneulink as pnl
>>> a = pnl.TransferMechanism(name='a')
>>> b = pnl.TransferMechanism(name='b')
>>> pathway1 = [a, b]
>>> comp = Composition(name='comp')
>>> comp.add_linear_processing_pathway(pathway1)
>>> input_dictionary = {a: [[[1.0]], [[2.0]], [[3.0]], [[4.0]], [[5.0]]]}
>>> comp.run(inputs=input_dictionary)

The number of inputs specified must be the same for all Nodes in the input dictionary (except for any Nodes for which only one input is specified). In other words, all of the values in the input dictionary must have the same length as each other (or length 1).

If num_trials is in use, run iterates over the inputs until num_trials is reached. For example, if five inputs are provided for each INPUT Node, and num_trials = 7, the system executes seven times. The input values from trials 0 and 1 are used again on trials 5 and 6, respectively.

Trial # 0 1 2 3 4 5 6
Input to Mechanism a 1.0 2.0 3.0 4.0 5.0 1.0 2.0
>>> import psyneulink as pnl
>>> a = pnl.TransferMechanism(name='a')
>>> b = pnl.TransferMechanism(name='b')
>>> pathway1 = [a, b]
>>> comp = Composition(name='comp')
>>> comp.add_linear_processing_pathway(pathway1)
>>> input_dictionary = {a: [[[1.0]], [[2.0]], [[3.0]], [[4.0]], [[5.0]]]}
>>> comp.run(inputs=input_dictionary,
...          num_trials=7)

For convenience, condensed versions of the input specification described above are also accepted in the following situations:

  • Case 1: INPUT Node has only one input state
Trial # 0 1 2 3 4
Input to Mechanism a 1.0 2.0 3.0 4.0 5.0

Complete input specification:

>>> import psyneulink as pnl
>>> a = pnl.TransferMechanism(name='a')
>>> b = pnl.TransferMechanism(name='b')
>>> pathway1 = [a, b]
>>> comp = Composition(name='comp')
>>> comp.add_linear_processing_pathway(pathway1)
>>> input_dictionary = {a: [[[1.0]], [[2.0]], [[3.0]], [[4.0]], [[5.0]]]}
>>> comp.run(inputs=input_dictionary)

Shorthand - drop the outer list on each input because Mechanism a only has one input state:

>>> input_dictionary = {a: [[1.0], [2.0], [3.0], [4.0], [5.0]]}
>>> comp.run(inputs=input_dictionary)

Shorthand - drop the remaining list on each input because Mechanism a’s one input state’s value is length 1:

>>> input_dictionary = {a: [1.0, 2.0, 3.0, 4.0, 5.0]}
>>> comp.run(inputs=input_dictionary)
  • Case 2: Only one input is provided for the INPUT Node
Trial # 0
Input to Mechanism a [[1.0], [2.0]]

Complete input specification:

>>> import psyneulink as pnl
>>> a = pnl.TransferMechanism(name='a',
                              default_variable=[[0.0], [0.0]])
>>> b = pnl.TransferMechanism(name='b')
>>> pathway1 = [a, b]
>>> comp = Composition(name='comp')
>>> comp.add_linear_processing_pathway(pathway1)
>>> input_dictionary = {a: [[[1.0], [2.0]]]}
>>> comp.run(inputs=input_dictionary)

Shorthand - drop the outer list on Mechanism a’s input specification because there is only one trial:

>>> input_dictionary = {a: [[1.0], [2.0]]}
>>> comp.run(inputs=input_dictionary)
  • Case 3: The same input is used on all trials
Trial # 0 1 2 3 4
Input to Mechanism a [[1.0], [2.0]] [[1.0], [2.0]] [[1.0], [2.0]] [[1.0], [2.0]] [[1.0], [2.0]]

Complete input specification:

>>> import psyneulink as pnl

>>> a = pnl.TransferMechanism(name='a',
...                           default_variable=[[0.0], [0.0]])
>>> b = pnl.TransferMechanism(name='b')

>>> pathway1 = [a, b]

>>> comp = Composition(name='comp')

>>> comp.add_linear_processing_pathway(pathway1)

>>> input_dictionary = {a: [[[1.0], [2.0]], [[1.0], [2.0]], [[1.0], [2.0]], [[1.0], [2.0]], [[1.0], [2.0]]]}

>>> comp.run(inputs=input_dictionary)

Shorthand - drop the outer list on Mechanism a’s input specification and use num_trials to repeat the input value

>>> input_dictionary = {a: [[1.0], [2.0]]}

>>> comp.run(inputs=input_dictionary,
...          num_trials=5)
  • Case 4: There is only one INPUT Node
Trial # 0 1
Input to Mechanism a [1.0, 2.0, 3.0] [1.0, 2.0, 3.0]

Complete input specification:

>>> import psyneulink as pnl

>>> a = pnl.TransferMechanism(name='a',
...                           default_variable=[[1.0, 2.0, 3.0]])
>>> b = pnl.TransferMechanism(name='b')

>>> pathway1 = [a, b]

>>> comp = Composition(name='comp')

>>> comp.add_linear_processing_pathway(pathway1)

>>> input_dictionary = input_dictionary = {a: [[1.0, 2.0, 3.0], [1.0, 2.0, 3.0]]}

>>> comp.run(inputs=input_dictionary)

Shorthand - specify Mechanism a’s inputs in a list because it is the only INPUT Node

>>> input_list = [[1.0, 2.0, 3.0], [1.0, 2.0, 3.0]]

>>> comp.run(inputs=input_list)

Interactive Inputs

An alternative way to specify inputs is with a function. The function must return a dictionary that satisfies the rules above for standard input specification. The only difference is that on each execution, the function returns the input values for each INPUT Node for a single trial.

Execution Contexts

An execution context is a scope of execution which has its own set of values for Components and their parameters. This is designed to prevent computations from interfering with each other, when Components are reused, which often occurs when using multiple or nested Compositions, or running simulations. Each execution context is or is associated with an execution_id, which is often a user-readable string. An execution_id can be specified in a call to Composition.run, or left unspecified, in which case the Composition’s default execution_id would be used. When looking for values after a run, it’s important to know the execution context you are interested in, as shown below

>>> import psyneulink as pnl
>>> c = pnl.Composition()
>>> d = pnl.Composition()
>>> t = pnl.TransferMechanism()
>>> c.add_node(t)
>>> d.add_node(t)

>>> t.execute(1)
array([[1.]])
>>> c.run({t: 5})
[[array([5.])]]
>>> d.run({t: 10})
[[array([10.])]]
>>> c.run({t: 20}, execution_id='custom execution id')
[[array([20.])]]

# context None
>>> print(t.parameters.value.get())
[[1.]]
>>> print(t.parameters.value.get(c))
[[5.]]
>>> print(t.parameters.value.get(d))
[[10.]]
>>> print(t.parameters.value.get('custom execution id'))
[[20.]]

In general, anything that happens outside of a Composition run and without an explicit setting of execution context occurs in the None execution context.

For Developers

  • The parameter values for any execution context can be copied into another execution context by using Component._initialize_from_context, which when called on a Component copies the values for all its parameters and recursively for all of the Component’s _dependent_components
  • _dependent_components should be added to for any new Component that requires other Components to function properly (beyond “standard” things like Component.function, or Mechanism.input_states, as these are added in the proper classes’ _dependent_components)
    • the intent is that with _dependent_components set properly, calling obj._initialize_from_context(new_execution_id, base_execution_id) should be sufficient to run obj under new_execution_id
    • a good example of a “nonstandard” override is OptimizationControlMechanism._dependent_components

If you receive an error like below, while checking for a context value for example,

self.parameters.context.get(execution_id).execution_phase == ContextStatus.PROCESSING
AttributeError: 'NoneType' object has no attribute 'execution_phase'

this means that there was no context value found for execution_id, and can be indicative that execution_id was not initialized to the values of another execution context, which normally happens during execution. See Execution Contexts initialization.

Timing

When run is called by a Composition, it calls that Composition’s execute method once for each input (or set of inputs) specified in the call to run, which constitutes a TRIAL of execution. For each TRIAL, the Component makes repeated calls to its Scheduler, executing the Components it specifies in each TIME_STEP, until every Component has been executed at least once or another termination condition is met. The Scheduler can be used in combination with Condition specifications for individual Components to execute different Components at different time scales.

Runtime Params

Visualizing a Composition

The show_graph method generates a display of the graph structure of Nodes (Mechanisms and Nested Compositions) and Projections in the Composition (based on the Composition’s processing graph).

By default, Nodes are shown as ovals labeled by their names, with the Composition’s INPUT Mechanisms shown in green, its OUTPUT Mechanisms shown in red, and Projections shown as unlabeled arrows, as illustrated for the Composition in the example below:

Note that the Composition’s controller is not shown by default. However this can be shown, along with other information, using options in the Composition’s show_graph method. The figure below shows several examples.

Output of show_graph using different options

System graph examples

Displays of the Composition used in the example above, generated using various options of its show_graph method. Panel A shows the graph with its Projections labeled and Component dimensions displayed. Panel B shows the controller for the Composition and its associated ObjectiveMechanism using the show_controller option (controller-related Components are displayed in blue by default). Panel C adds the Composition’s CompositionInterfaceMechanisms using the show_cim option. Panel D shows a detailed view of the Mechanisms using the show_node_structure option, that includes their States and their roles in the Composition. Panel E show an even more detailed view using show_node_structure as well as show_cim.

If a Composition has one ore more Compositions nested as Nodes within it, then these can be shown using the show_nested option. For example, if two Compositions identical to comp in the example above are added as the nodes of the linear processing pathway of a third* comp *, these can be shown as follows:

>>> comp.show_graph()
_images/nested.svg
>>> comp.show_graph(show_nested=True)
_images/show_nested.svg

Class Reference

class psyneulink.core.compositions.composition.Composition(name=None, controller=None, enable_controller=None, controller_mode: <typecheck.tc_predicates.enum object at 0x11454a358> = 'after', controller_condition: psyneulink.core.scheduling.condition.Condition = <psyneulink.core.scheduling.condition.Always object>, **param_defaults)
Parameters:
  • name (str) –
  • controller (OptimizationControlmechanism) – must be specified if the OptimizationControlMechanism runs simulations of its own Composition.
  • enable_controller (bool) – when set to True, executes the controller. When False, ignores the controller.
  • controller_mode (AFTER) – specifies whether the controller is executed before or after the rest of the Composition is executed in each trial. Must be either the keyword BEFORE or AFTER.
  • controller_condition (Always) – specifies whether the controller is executed in a given trial. Must be a Condition.
graph

Graph – The full Graph associated with this Composition. Contains both Nodes (Mechanisms or Compositions) and Projections

nodes

list[Mechanisms and Compositions] – A list of all Nodes (Mechanisms and/or Compositions) contained in this Composition

input_CIM

CompositionInterfaceMechanism – Aggregates input values for the INPUT nodes of the Composition. If the Composition is nested, then the input_CIM and its InputStates serve as proxies for the Composition itself in terms of afferent projections.

output_CIM

CompositionInterfaceMechanism – Aggregates output values from the OUTPUT nodes of the Composition. If the Composition is nested, then the output_CIM and its OutputStates serve as proxies for the Composition itself in terms of efferent projections.

input_CIM_states

dict – A dictionary in which keys are InputStates of INPUT Nodes in a composition, and values are lists containing two items: the corresponding InputState and OutputState on the input_CIM.

output_CIM_states

dict – A dictionary in which keys are OutputStates of OUTPUT Nodes in a composition, and values are lists containing two items: the corresponding InputState and OutputState on the input_CIM.

env

Gym Forager Environment : default: None – Stores a Gym Forager Environment so that the Composition may interact with this environment within a single call to run.

shadows

dict – A dictionary in which the keys are all in the Composition and the values are lists of any Nodes that shadow the original Node’s input.

controller

OptimizationControlMechanism – If the Composition contains an OptimizationControlMechanism that runs simulations of its own Composition, then the OCM is stored here.

enable_controller

bool – When True, executes the Composition’s controller in each trial (see controller_mode <Composition.controller_mode>` for timing of execution).

controller_mode

BEFORE or AFTER – Determines whether the controller is executed before or after the rest of the Composition is executed on each trial.

controller_condition

Condition – Specifies whether the controller is executed in a given trial. The default is Always, which executes the controller on every trial.

default_execution_id

if no execution_id is specified in a call to run, this execution_id is used.

Default value:the Composition’s name
execution_ids

set – Stores all execution_ids used by this Composition.

add_controller(controller)

Adds an OptimizationControlMechanism as the controller of the Composition, which gives the OCM access to the Composition’s evaluate method. This allows the OCM to use simulations to determine an optimal Control policy.

add_node(node, required_roles=None)

Adds a Composition Node (Mechanisms or Composition) to the Composition, if it is not already added

Parameters:
add_pathway(path)

Adds an existing Pathway to the current Composition

Parameters:path (the Pathway (Composition) to be added) –
add_projection(projection=None, sender=None, receiver=None, feedback=False, name=None)

Adds a projection to the Composition, if it is not already added.

If a projection is not specified, then a default MappingProjection is created.

The sender and receiver of a particular Projection vertex within the Composition (the sender and receiver arguments of add_projection) must match the sender and receiver specified on the Projection object itself.

  • If the sender and/or receiver arguments are not specified, then the sender and/or receiver attributes of the Projection object set the missing value(s).
  • If the sender and/or receiver attributes of the Projection object are not specified, then the sender and/or receiver arguments set the missing value(s).
Parameters:
  • sender (Mechanism, Composition, or OutputState) – the sender of projection
  • projection (Projection, matrix) – the projection to add
  • receiver (Mechanism, Composition, or InputState) – the receiver of projection
  • feedback (Boolean) –

    When False (default) all Nodes within a cycle containing this Projection execute in parallel. This means that each Projections within the cycle actually passes to its receiver its sender’s value from the sender’s previous execution.

    When True, this Projection “breaks” the cycle, such that all Nodes execute in sequence, and only the Projection marked as ‘feedback’ passes to its receiver its sender’s value from the sender’s previous execution.

add_projections(projections=None)

Calls add_projection for each Projection in the projections list. Each Projection must have its sender and receiver already specified.

Parameters:projections (list of Projections) – list of Projections to be added to the Composition
add_reinforcement_learning_pathway(pathway, learning_rate=0.05, error_function=None)
Parameters:
  • pathway (List) – list containing either [Node1, Node2] or [Node1, MappingProjection, Node2]. If a projection is specified, that projection is the learned projection. Otherwise, a default MappingProjection is automatically generated for the learned projection.
  • learning_rate (float (default = 0.05)) – learning rate of the ReinforcementLearning function
  • error_function (function (default = LinearCombination) – function of the ComparatorMechanism
Returns:

  • A dictionary of components that were automatically generated and added to the Composition in order to
  • implement ReinforcementLearning along the pathway.
  • {LEARNING_MECHANISM (learning_mechanism,) – COMPARATOR_MECHANISM: comparator, TARGET_MECHANISM: target, LEARNED_PROJECTION: learned_projection}

default_external_input_values

Returns the default values of all external InputStates that belong to the Input CompositionInterfaceMechanism

evaluate(predicted_input=None, control_allocation=None, num_simulation_trials=None, runtime_params=None, base_execution_id=None, execution_id=None, context=None, execution_mode=False)

Runs a simulation of the Composition, with the specified control_allocation, excluding its controller in order to return the net_outcome of the Composition, according to its controller under that control_allocation. All values are reset to pre-simulation values at the end of the simulation.

execute(inputs=None, autodiff_stimuli=None, scheduler_processing=None, scheduler_learning=None, termination_processing=None, termination_learning=None, call_before_time_step=None, call_before_pass=None, call_after_time_step=None, call_after_pass=None, execution_id=None, base_execution_id=None, clamp_input='soft_clamp', targets=None, runtime_params=None, skip_initialization=False, bin_execute=False, context=None)

Passes inputs to any Nodes receiving inputs directly from the user (via the “inputs” argument) then coordinates with the Scheduler to execute sets of nodes that are eligible to execute until termination conditions are met.

Parameters:
  • inputs ({ Mechanism or Composition : list }) – a dictionary containing a key-value pair for each node in the composition that receives inputs from the user. For each pair, the key is the node (Mechanism or Composition) and the value is an input, the shape of which must match the node’s default variable.
  • scheduler_processing (Scheduler) – the scheduler object that owns the conditions that will instruct the non-learning execution of this Composition. If not specified, the Composition will use its automatically generated scheduler
  • scheduler_learning (Scheduler) – the scheduler object that owns the conditions that will instruct the Learning execution of this Composition. If not specified, the Composition will use its automatically generated scheduler
  • execution_id – execution_id will be set to self.default_execution_id if unspecified
  • base_execution_id – the execution_id corresponding to the execution context from which this execution will be initialized, if values currently do not exist for execution_id
  • call_before_time_step (callable) – called before each TIME_STEP is executed passed the current execution_id (but it is not necessary for your callable to take)
  • call_after_time_step (callable) – called after each TIME_STEP is executed passed the current execution_id (but it is not necessary for your callable to take)
  • call_before_pass (callable) – called before each PASS is executed passed the current execution_id (but it is not necessary for your callable to take)
  • call_after_pass (callable) – called after each PASS is executed passed the current execution_id (but it is not necessary for your callable to take)
Returns:

output value of the final Mechanism executed in the Composition

Return type:

various

external_input_states

Returns all external InputStates that belong to the Input CompositionInterfaceMechanism

external_input_values

Returns values of all external InputStates that belong to the Input CompositionInterfaceMechanism

get_nodes_by_role(role)

Returns a List of Composition Nodes in this Composition that have the role specified

Parameters:role (NodeRole) – the List of nodes having this role to return
Returns:
graph_processing

The Composition’s processing graph (contains only Mechanisms.

Getter:Returns the processing graph, and builds the graph if it needs updating since the last access.
input_state

Returns the index 0 InputState that belongs to the Input CompositionInterfaceMechanism

input_states

Returns all InputStates that belong to the Input CompositionInterfaceMechanism

input_values

Returns values of all InputStates that belong to the Input CompositionInterfaceMechanism

output_state

Returns the index 0 OutputState that belongs to the Output CompositionInterfaceMechanism

output_states

Returns all OutputStates that belong to the Output CompositionInterfaceMechanism

output_values

Returns values of all OutputStates that belong to the Output CompositionInterfaceMechanism

run(inputs=None, scheduler_processing=None, scheduler_learning=None, termination_processing=None, termination_learning=None, execution_id=None, base_execution_id=None, num_trials=None, call_before_time_step=None, call_after_time_step=None, call_before_pass=None, call_after_pass=None, call_before_trial=None, call_after_trial=None, clamp_input='soft_clamp', targets=None, bin_execute=False, initial_values=None, reinitialize_values=None, runtime_params=None, retain_old_simulation_data=False, context=None)

Passes inputs to compositions, then executes to receive and execute sets of nodes that are eligible to run until termination conditions are met.

Parameters:
  • inputs ({ Mechanism : list } or { Composition : list }) – a dictionary containing a key-value pair for each Node in the composition that receives inputs from the user. For each pair, the key is the Node and the value is a list of inputs. Each input in the list corresponds to a certain TRIAL.
  • scheduler_processing (Scheduler) – the scheduler object that owns the conditions that will instruct the non-learning execution of this Composition. If not specified, the Composition will use its automatically generated scheduler.
  • scheduler_learning (Scheduler) – the scheduler object that owns the conditions that will instruct the Learning execution of this Composition. If not specified, the Composition will use its automatically generated scheduler.
  • execution_id – execution_id will be set to self.default_execution_id if unspecified
  • base_execution_id – the execution_id corresponding to the execution context from which this execution will be initialized, if values currently do not exist for execution_id
  • num_trials (int) – typically, the composition will infer the number of trials from the length of its input specification. To reuse the same inputs across many trials, you may specify an input dictionary with lists of length 1, or use default inputs, and select a number of trials with num_trials.
  • call_before_time_step (callable) – will be called before each TIME_STEP is executed.
  • call_after_time_step (callable) – will be called after each TIME_STEP is executed.
  • call_before_pass (callable) – will be called before each PASS is executed.
  • call_after_pass (callable) – will be called after each PASS is executed.
  • call_before_trial (callable) – will be called before each TRIAL is executed.
  • call_after_trial (callable) – will be called after each TRIAL is executed.
  • initial_values (Dict[Node: Node Value]) – sets the values of nodes before the start of the run. This is useful in cases where a node’s value is used before that node executes for the first time (usually due to recurrence or control).
  • runtime_params (Dict[Node: Dict[Parameter: Tuple(Value, Condition)]]) –

    nested dictionary of (value, Condition) tuples for parameters of Nodes (Mechanisms or Compositions of the Composition; specifies alternate parameter values to be used only during this Run when the specified Condition is met.

    Outer dictionary:
    • key - Node
    • value - Runtime Parameter Specification Dictionary
    Runtime Parameter Specification Dictionary:
    • key - keyword corresponding to a parameter of the Node
    • value - tuple in which the index 0 item is the runtime parameter value, and the index 1 item is a Condition

    See Runtime Parameters for more details and examples of valid dictionaries.

  • retain_old_simulation_data (bool) – if True, all Parameter values generated during simulations will be saved for later inspection; if False, simulation values will be deleted unless otherwise specified by individual Parameters
Returns:

output value of the final Node executed in the composition

Return type:

various

scheduler_learning

A default Scheduler automatically generated by the Composition, used for the learning phase of execution.

Getter:Returns the default learning scheduler, and builds it if it needs updating since the last access.
scheduler_processing

A default Scheduler automatically generated by the Composition, used for the (processing phase of execution.

Getter:Returns the default processing scheduler, and builds it if it needs updating since the last access.
show_graph(show_controller=False, show_dimensions=False, show_node_structure=False, show_cim=False, show_headers=True, show_projection_labels=False, show_nested=False, direction='BT', active_items=None, active_color='bold', input_color='green', output_color='red', input_and_output_color='brown', controller_color='blue', composition_color='pink', output_fmt='pdf', execution_id=NotImplemented, **kwargs)

Note

This method relies on graphviz, which must be installed and imported (standard with PsyNeuLink pip install)

See Visualizing a Composition for details and examples.

Parameters:
  • show_node_structure (bool, VALUES, LABELS, FUNCTIONS, MECH_FUNCTION_PARAMS, STATE_FUNCTION_PARAMS, ROLES, or ALL : default False) –

    show a detailed representation of each Mechanisms in the graph, including its States; can have any of the following settings alone or in a list:

    • True – show States of Mechanism, but not information about the value or function of the Mechanism or its States.
    • VALUES – show the value of the Mechanism and the value of each of its States.
    • LABELS – show the value of the Mechanism and the value of each of its States, using any labels for the values of InputStates and OutputStates specified in the Mechanism’s input_labels_dict and output_labels_dict, respectively.
    • FUNCTIONS – show the function of the Mechanism and the function of its InputStates and OutputStates.
    • MECH_FUNCTION_PARAMS_ – show the parameters of the function for each Mechanism in the Composition (only applies if FUNCTIONS is True).
    • STATE_FUNCTION_PARAMS_ – show the parameters of the function for each State of each Mechanism in the Composition (only applies if FUNCTIONS is True).
    • ROLES – show the role of the Mechanism in the Composition (but not any of the other information; use ALL to show ROLES with other information).
    • ALL – shows the role, function, and value of the Mechanisms in the Composition and their States (using labels for the values, if specified – see above), including parameters for all functions.
  • show_projection_labels (bool : default False) – specifies whether or not to show names of projections.
  • show_headers (bool : default True) – specifies whether or not to show headers in the subfields of a Mechanism’s node; only takes effect if show_node_structure is specified (see above).
  • show_nested (bool : default False) – specifies whether nested Compositions are shown in details as inset graphs
  • show_cim (bool : default False) – specifies whether or not to show the Composition’s input and out CompositionInterfaceMechanisms (CIMs)
  • show_controller (bool : default False) – specifies whether or not to show the Composition’s controller and associated ObjectiveMechanism; these are displayed in the color specified for controller_color.
  • direction (keyword : default 'BT') – ‘BT’: bottom to top; ‘TB’: top to bottom; ‘LR’: left to right; and ‘RL`: right to left.
  • active_items (List[Component] : default None) – specifies one or more items in the graph to display in the color specified by active_color*.
  • active_color (keyword : default 'yellow') – specifies how to highlight the item(s) specified in active_items*: either a color recognized by GraphViz, or the keyword BOLD.
  • input_color (keyword : default 'green',) – specifies the display color for INPUT Nodes in the Composition
  • output_color (keyword : default 'red',) – specifies the display color for OUTPUT Nodes in the Composition
  • input_and_output_color (keyword : default 'brown') – specifies the display color of nodes that are both an INPUT and an OUTPUT Node in the Composition
  • input_and_output_color – specifies the display color of nodes that represented nested Compositions.
  • cim_shape (default 'square') – specifies the display color input_CIM and output_CIM nodes
  • controller_color (keyword : default blue) – specifies the color in which the controller components are displayed
  • output_fmt (keyword : default 'pdf') – ‘pdf’: generate and open a pdf with the visualization; ‘jupyter’: return the object (ideal for working in jupyter/ipython notebooks).
Returns:

display of Composition – ‘pdf’ (placed in current directory) if output_fmt arg is ‘pdf’; Graphviz graph object if output_fmt arg is ‘jupyter’.

Return type:

pdf or Graphviz graph object

stateful_nodes

List of all nodes in the system that are currently marked as stateful. For Mechanisms, statefulness is determined by checking whether node.has_initializers is True. For Compositions, statefulness is determined by checking whether any of its nodes are stateful.

Returns:all stateful nodes in the system
Return type:List[Nodes]