System

Overview

A System is a Composition that is a collection of Processes all of which are executed together. Executing a System executes all of the Mechanisms in its Processes in a structured order. Projections between Mechanisms in different Processes within the System are permitted, as are recurrent Projections, but Projections from Mechanisms in other Systems are ignored (PsyNeuLink does not support ESP). A System can also be assigned a ControlMechanism as its controller, that can be used to control parameters of other Mechanisms (or their functions in the System.

Creating a System

Systems are created by instantiating the System class. If no arguments are provided, a System with a single Process containing a single default_mechanism is created. More commonly, a System is created from one or more Processes that are specified in the processes argument of the System class, and listed in its processes attribute.

Note

At present, only Processes can be assigned to a System; Mechanisms cannot be assigned directly to a System. They must be assigned to the pathway of a Process, and then that Process must be included in the processes argument of the System class.

Specifying Control

A controller can also be specified for the System, in the controller argument of the System. This can be an existing Control Mechanism, a constructor for one, or a class of ControlMechanism in which case a default instance of that class will be created. If an existing ControlMechanism or the constructor for one is used, then the OutputStates it monitors and the parameters it controls can be specified using its objective_mechanism and control_signals attributes, respectively. In addition, these can be specified in the monitor_for_control and control_signal arguments of the System, as described below.

  • monitor_for_control argument – used to specify OutputStates of Mechanisms in the System that should be monitored by the ObjectiveMechanism associated with the System’s controller (see ObjectiveMechanism); these are used in addition to any specified for the ControlMechanism or its ObjectiveMechanism. These can be specified in the monitor_for_control argument of the System using any of the ways used to specify the monitored_output_states for an ObjectiveMechanism (see Monitored OutputStates). In addition, the monitor_for_control argument supports two other forms of specification:


    • MonitoredOutputStatesOption – must be a value of MonitoredOutputStatesOption, and must appear alone or as a single item in the list specifying the monitor_for_control argument; any other specification(s) included in the list will take precedence. The MonitoredOutputStatesOption applies to all of the Mechanisms in the System except its controller and LearningMechanisms. The PRIMARY_OUTPUT_STATES value specifies that the primary OutputState of every Mechanism be monitored, whereas ALL_OUTPUT_STATES specifies that every OutputState of every Mechanism be monitored.

    The default for the monitor_for_control argument is MonitoredOutputStatesOption.PRIMARY_OUTPUT_STATES. The OutputStates specified in the monitor_for_control argument are added to any already specified for the ControlMechanism’s objective_mechanism, and the full set is listed in the ControlMechanism’s monitored_output_states attribute, and its ObjectiveMechanism’s monitored_output_states attribute).

  • control_signals argument – used to specify the parameters of Components in the System to be controlled. These can be specified in any of the ways used to specify ControlSignals in the control_signals argument of a ControlMechanism. These are added to any ControlSignals that have already been specified for the controller (listed in its control_signals attribute), and any parameters that have directly been specified for control within the System (see Control below for additional details).

Structure

The Components of a System are shown in the figure below and summarized in the sections that follow.

Overview of major PsyNeuLink components

Two Processes are shown, both belonging to the same System. Each Process has a series of ProcessingMechanisms linked by MappingProjections, that converge on a common final ProcessingMechanism. Each ProcessingMechanism is labeled with its designation in the System. The TERMINAL Mechanism for both Processes projects to an ObjectiveMechanism that is used to drive learning in Process B. It also projects to a separate ObjectiveMechanism that is used for control of ProcessingMechanisms in both Processes A and B. Note that the Mechanisms and Projections responsible for learning and control belong to the System and can monitor and/or control Mechanisms belonging to more than one Process (as shown for control in this figure).

Mechanisms

The Mechanisms in a System are assigned designations based on the position they occupy in the graph and/or the role they play in a System:

ORIGIN: receives input to the System (provided in the execute or run from any other ProcessingMechanisms.

TERMINAL: provides output from the System, and does not send Projections to any other ProcessingMechanisms.

SINGLETON: both an ORIGIN and a TERMINAL Mechanism.

INITIALIZE_CYCLE: sends a Projection that closes a recurrent loop; can be assigned an initial value.

CYCLE: receives a Projection that closes a recurrent loop.

CONTROL: monitors the value of another Mechanism for use in controlling parameter values.

LEARNING: monitors the value of another Mechanism for use in learning.

TARGET: ComparatorMechanism that monitors a TERMINAL Mechanism of a Process and compares it to a corresponding value provided in the execute or run method.

INTERNAL: ProcessingMechanism that does not fall into any of the categories above.

Note

Any ORIGIN and TERMINAL Mechanisms of a System must be, respectively, the ORIGIN or TERMINAL of any Process(es) to which they belong. However, it is not necessarily the case that the ORIGIN and/or TERMINAL Mechanism of a Process is also the ORIGIN and/or TERMINAL of a System to which the Process belongs (see example).

Graph

When a System is created, a graph is constructed that describes the Projections (edges) among its Mechanisms (nodes). The graph is assigned to the System’s graph attribute. A System’s graph can be displayed using its System.show_graph method. The graph is stored as a dictionary of dependencies that can be passed to graph theoretical tools for analysis. A System can have recurrent Processing pathways, such as feedback loops; that is, the System’s graph to determine the order in which its Mechanisms are executed. To do so in an orderly manner, however, the graph must be acyclic. To address this, PsyNeuLink constructs an execution_graph from the System’s graph. If the System is acyclic, these are the same. If the System is cyclic, then the execution_graph is a subset of the graph in which the dependencies (edges) associated with Projections that close a loop have been removed. Note that this only impacts the order of execution; the Projections themselves remain in effect, and will be fully functional during the execution of the Mechanisms to and from which they project (see Execution below for a more detailed description).

Scheduler

Every System has two Schedulers, one that handles the ordering of execution of its Components for processing (assigned to its scheduler_processing attribute), and one that does the same for learning (assigned to its scheduler_learning attribute). The scheduler_processing can be assigned in the scheduler argument of the System’s constructor; if it is not specified, a default Scheduler is created automatically. The scheduler_learning is always assigned automatically. The System’s Schedulers base the ordering of execution of its Components based on the order in which they are listed in the pathways of the Processes used to construct the System, constrained by any Conditions that have been created for individual Components and assigned to the System’s Schedulers (see Scheduler, Condition, Processing, and Learning for additional details). Both schedulers maintain a Clock that can be used to access their current time.

Control

A System can be assigned a Control Mechanism as its controller, that can be used to control parameters of other Mechanisms in the System. Although any number of ControlMechanism can be assigned to and executed within a System, a System can have only one controller, that is executed after all of the other Components in the System have been executed, including any other ControlMechanisms (see System Execution). When a ControlMechanism is assigned to or created by a System, it inherits specifications made for the System as follows:

See Specifying Control above, ControlMechanism and Modulation for details of how control operates, and Control below for a description of how it is engaged when a System is executed. The control Components of a System can be displayed using the System’s show_graph method with its show_control argument assigned as True.

Learning

A System cannot itself be specified for learning. However, if learning has been specified for any of its processes, then it will be implemented and executed as part of the System. Note, however, that for the learning Components of a Process to be implemented by a System, learning must be specified for the entire Process. The learning Components of a System can be displayed using the System’s System.show_graph method with its show_learning argument assigned as True or ALL.

Execution

A System can be executed by calling either its execute or run methods. execute executes the System once; that is, it executes a single TRIAL. run allows a series of TRIALs to be executed, one for each input in the inputs argument of the call to run. For each TRIAL, it makes a series of calls to the run method of the relevant Scheduler (see Processing and Learning below), and executes the Components returned by that Scheduler (constituting a TIME_STEP of execution), until every Component in the System has been executed at least once, or another termination condition is met. The execution of each TRIAL occurs in four phases: initialization, processing, learning, and control, each of which is described below.

Input and Initialization

The input to a System is specified in the input argument of either its execute or run method. In both cases, the input for a single TRIAL must be a list or ndarray of values, each of which is an appropriate input for the corresponding ORIGIN Mechanism (listed in the System’s origin_mechanisms attribute). If the execute method is used, input for only a single TRIAL is provided, and only a single TRIAL is executed. The run method can be used for a sequence of TRIALs, by providing it with a list or ndarray of inputs, one for each TRIAL. In both cases, two other types of input can be provided in corresponding arguments of the run method: a list or ndarray of initial_values, and a list or ndarray of target values. The initial_values are assigned at the start of a TRIAL as input to Mechanisms that close recurrent loops (designated as INITIALIZE_CYCLE, and listed in the System’s recurrent_init_mechanisms attribute), and target values are assigned as the TARGET input of the System’s TARGET Mechanisms (see Learning below; also, see Run for additional details of formatting input specifications).

Processing

Once the relevant inputs have been assigned, the ProcessingMechanisms of the System are executed in the order they are listed in the Processes used to construct the System. When a Mechanism is executed, it receives input from any other Mechanisms that project to it within the System, but not from any Mechanisms outside the System (PsyNeuLink does not support ESP). The order of execution is determined by the System’s execution_graph attribute, which is a subset of the System’s graph that has been “pruned” to be acyclic (i.e., devoid of recurrent loops (see Graph above). While the execution_graph is acyclic, all recurrent Projections in the System remain intact during execution and can be initialized at the start of execution. The order in which Components are executed can also be customized, using the System’s Scheduler in combination with Condition specifications for individual Components, to execute different Components at different time scales, or to introduce dependencies among them (e.g., require that a recurrent Mechanism settle before another one execute – see example).

Learning

A System executes learning if it is specified for one or more Processes in the System. The System’s learning attribute indicates whether learning is enabled for the System. Learning is executed for any Components (individual Projections or Processes) for which it is specified after the processing of each TRIAL has completed, but before the controller.

The learning Components of a System can be displayed using the System’s show_graph method with its show_learning argument assigned True or ALL. The target values used for learning can be specified in either of two formats: dictionary or function, which are described in the Run module (see Targets). Both formats require that a target value be provided for each TARGET Mechanism of the System (listed in its target_mechanisms attribute).

Note

A TARGET Mechanism of a Process is not necessarily one of the TARGET Mechanisms of the System to which it belongs (see TARGET Mechanisms). Also, the changes to a System induced by learning are not applied until the Mechanisms that receive the Projections being learned are next executed; see Lazy Evaluation for an explanation of “lazy” updating).

Control

The System’s controller is executed in the last phase of execution in a TRIAL, after all other Mechanisms in the System have executed. Although a System may have more than one Control Mechanism, only one can be assigned as its controller; all other ControlMechanisms are executed during the processing `System_Execution_Processing phase of the TRIAL like any other Mechanism. The controller uses its objective_mechanism to monitor and evaluate the OutputState(s) of Mechanisms in the System; based on the information it receives from that ObjectiveMechanism, it modulates the value of the parameters of Components in the System that have been specified for control, which then take effect in the next TRIAL (see Control for additional information about control). The control Components of a System can be displayed using the System’s show_graph`method with its **show_control** argument assigned `True.

Examples

Specifying Control for a System

The following example specifies an EVCControlMechanism as the controller for a System with two Processes that include two Mechanisms (not shown):

my_system = System(processes=[TaskExecutionProcess, RewardProcess],
                   controller=EVCControlMechanism(objective_mechanism=
                                               ObjectiveMechanism(
                                                   monitored_output_states=[
                                                       Reward,
                                                       Decision.output_states[PROBABILITY_UPPER_THRESHOLD],
                                                       (Decision.output_states[RESPONSE_TIME], -1, 1)]))
                                                   function=LinearCombination(operation=PRODUCT))

A constructor is used to specify the EVCControlMechanism that includes a constructor specifying its objective_mechanism; the monitored_output_states argument of the ObjectiveMechanism’s constructor is used to specify that it should monitor the primary OutputState of the Reward Mechanism and the PROBABILITY_UPPER_THRESHOLD and RESPONSE_TIME and, specifying how it should combine them (see the example under ControlMechanism for an explanation). Note that the function argument for the ObjectiveMechanism’s constructor is also specified; this is because an ObjectiveMechanism uses SUM as the default for the operation of its LinearCombination function, whereas as the EVCControlMechanism requires PRODUCT – in this case, to properly use the weight and exponents specified for the RESPONSE_TIME OutputState of Decision (see note in EVCControlMechanism for a more complete explanation). Note that both the EVCControlMechanism and/or the ObjectiveMechanism could have been constructed separately, and then referenced in the controller argument of my_system and objective_mechanism argument of the EVCControlMechanism, respectively.

The same configuration can be specified in a more concise, though less “transparent” form, as follows:

my_system = System(processes=[TaskExecutionProcess, RewardProcess],
                   controller=EVCControlMechanism(objective_mechanism=[
                                                         Reward,
                                                         Decision.output_states[PROBABILITY_UPPER_THRESHOLD],
                                                         (Decision.output_states[RESPONSE_TIME], -1, 1)])))

Here, the constructor for the ObjectiveMechanism is elided, and the objective_mechanism argument for the EVCControlMechanism is specified as a list of OutputStates (see ObjectiveMechanism).

The specification can be made even simpler, but with some additional considerations that must be kept in mind, as follows:

my_system = System(processes=[TaskExecutionProcess, RewardProcess],
                   controller=EVCControlMechanism,
                   monitor_for_control=[Reward,
                                        PROBABILITY_UPPER_THRESHOLD,
                                        RESPONSE_TIME, 1, -1)],

Here, the controller* for my_system is specified as the EVCControlMechanism, which will created a default EVCControlMechanism. The OutputStates to be monitored are specified in the monitor_for_control argument for my_system. Note that here they can be referenced simply by name; when my_system is created, it will search all of its Mechanisms for OutputStates with those names, and assign them to the monitored_output_states attribute of the EVCControlMechanism’s objective_mechanism (see Specifying Control for a more detailed explanation of how OutputStates are assigned to be monitored by a System’s controller). While this form of the specification is much simpler, it less flexible (i.e., it can’t be used to customize the ObjectiveMechanism used by the EVCControlMechanism or its function.

Class Reference

psyneulink.components.system.sys(*args, **kwargs)

Factory method

args can be Mechanisms, Projections and/or lists containing either, but must conform to the format for the specification of the pathway argument of a Process. If none of the args is a list, then all are treated as a single Process (i.e., pathway specification). If any args are lists, each is treated as a pathway specification for a Process; any other args not in a list must be Mechanisms (i.e., none can be Projections), and each is used to create a singleton Process.

kwargs can be any arguments of the System constructor.

class psyneulink.components.system.System(default_variable=None, size=None, processes=None, initial_values=None, controller=None, enable_controller=:keyword:`False`, monitor_for_control=None, control_signals=None, learning_rate=None, targets=None, reinitialize_mechanisms_when=AtTimeStep(0), scheduler=None, params=None, name=None, prefs=None)

Base class for System.

componentType

SYSTEM

processes

list of Process objects – list of Processes in the System specified by the processes argument of the constructor.

controller

ControlMechanism : default SystemDefaultControlMechanism – the ControlMechanism used to monitor the value of the OutputState(s) and/or Mechanisms specified in the monitor_for_control argument, and that controls the parameters specified in the control_signals argument of the System’s constructor.

enable_controller

bool : default False – determines whether the controller is executed during System execution.

learning

bool : default False – indicates whether learning is enabled for the System; is set to True if learning is specified for any Processes in the System.

learning_rate

float : default None – determines the learning_rate for all LearningMechanisms in the System. This overrides any values set for the function of individual LearningMechanisms or LearningSignals, and persists for all subsequent executions of the System. If it is set to None, then the learning_rate is determined by last value assigned to each LearningMechanism (either directly, or following the execution of any Process or System to which the LearningMechanism belongs and for which a learning_rate was set).

targets

2d nparray – used as template for the values of the System’s target_input_states, and to represent the targets specified in the targets argument of System’s execute and run methods.

graph

OrderedDict – contains a graph of all of the Components in the System. Each entry specifies a set of <Receiver>: {sender, sender…} dependencies. The key of each entry is a receiver Component, and the value is a set of Mechanisms that send Projections to that receiver. If a key (receiver) has no dependents, its value is an empty set.

execution_graph

OrderedDict – contains an acyclic subset of the System’s graph, hierarchically organized by a toposort. Used to specify the order in which Components are executed.

execution_sets

list of sets – contains a list of Component sets. Each set contains Components to be executed at the same time. The sets are ordered in the sequence with which they should be executed.

execution_list

list of Mechanisms and/or Projections – contains a list of Components in the order in which they are executed. The list is a random sample of the permissible orders constrained by the execution_graph and produced by the toposort.

mechanisms

list of Mechanism objects – contains a list of all Mechanisms in the System.

mechanismsDict

Dict[Mechanism: Process] – contains a dictionary of all Mechanisms in the System, listing the Processes to which they belong. The key of each entry is a Mechanism object, and the value of each entry is a list of Processes.

origin_mechanisms

MechanismList – all ORIGIN Mechanisms in the System (i.e., that don’t receive Projections from any other Mechanisms, listed in origin_mechanisms.data.

terminalMechanisms

MechanismList – all TERMINAL Mechanisms in the System (i.e., that don’t project to any other ProcessingMechanisms), listed in terminalMechanisms.data.

recurrent_init_mechanisms

MechanismListMechanisms with recurrent Projections that are candidates for initialization, listed in recurrent_init_mechanisms.data.

learning_mechanisms

MechanismList – all LearningMechanisms in the System, listed in learning_mechanisms.data.

target_mechanisms

MechanismList – all TARGET Mechanisms in the System (used for learning), listed in target_mechanisms.data.

target_input_states

List[SystemInputState] – one item for each TARGET Mechanism in the System (listed in its target_mechanisms attribute). Used to represent the values specified in the targets argument of the System’s execute and run methods, and to provide thoese values to the the TARGET InputState of each TARGET Mechanism during execution.

value : 3D ndarray
contains an array of 2D arrays, each of which is the output_values of a TERMINAL Mechanism in the System.
initial_values : list or ndarray of values
values used to initialize Mechanisms that close recurrent loops (designated as INITIALIZE_CYCLE). Length must equal the number of INITIALIZE_CYCLE Mechanisms listed in the System’s recurrent_init_mechanisms attribute.
results : List[OutputState.value]
list of return values from the sequence of executions. Each item is a 1d array containing the value of each TERMINAL Mechanism of the System for a given execution. Excludes simulated runs.
simulation_results : List[OutputState.value]
list of return values from the sequence of executions in simulation run(s) of the System; requires recordSimulationPref to be True. Each item is a 1d array containing the value of each OutputState of each TERMINAL Mechanism in the System for a given execution in the simulation. Excludes values from non-simulation runs.
name : str
the name of the System; if it is not specified in the name argument of the constructor, a default is assigned by SystemRegistry (see Naming for conventions used for default and duplicate names).
prefs : PreferenceSet or specification dict
the PreferenceSet for the System; 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).
initialize()

Assign initial_values to mechanisms designated as INITIALIZE_CYCLE nd contained in recurrent_init_mechanisms.

execute(input=None, target=None, execution_id=None, termination_processing=None, termination_learning=None, runtime_params=None, context=None)

Execute mechanisms in System at specified phases in order specified by the execution_graph attribute.

Assign items of input to ORIGIN mechanisms

Execute any learning components specified at the appropriate phase.

Execute controller after all mechanisms have been executed (after each numPhases)

Parameters:
Returns:

output values of System – Each item is a 2d array that contains arrays for each OutputState.value of each TERMINAL Mechanism

Return type:

3d ndarray

run(inputs=None, num_trials=None, initialize=False, initial_values=None, targets=None, learning=None, call_before_trial=None, call_after_trial=None, call_before_time_step=None, call_after_time_step=None, termination_processing=None, termination_learning=None, runtime_params=None, reinitialize_values=None, context=None)

Run a sequence of executions

Call execute method for each execution in a sequence specified by inputs. See Run for details of formatting input specifications.

Parameters:
  • inputs (List[input] or ndarray(input) : default default_variable for a single execution) – the input for each in a sequence of executions (see Run for detailed description of formatting requirements and options).
  • initialize (bool default False) – if True, calls the initialize method of the System before a sequence of executions.
  • initial_values (Dict[Mechanism: List[input] or np.ndarray(input)] : default None) – the initial values assigned to Mechanisms designated as INITIALIZE_CYCLE.
  • targets (List[input] or np.ndarray(input) : default None) – the target values for the LearningMechanisms of the System for each execution. The length (of the outermost level if a nested list, or lowest axis if an ndarray) must be equal to that of inputs.
  • learning (bool : default None) – enables or disables learning during execution. If it is not specified, the current state is left intact. If it is True, learning is forced on; if it is False, learning is forced off.
  • call_before_trial (Function : default None) – called before each trial in the sequence is executed.
  • call_after_trial (Function : default None) – called after each trial in the sequence is executed.
  • call_before_time_step (Function : default None) – called before each time_step of each trial is executed.
  • call_after_time_step (Function : default None) – called after each time_step of each trial is executed.
  • termination_processing (Dict[TimeScale: Condition]) – a dictionary containing Conditions that signal the end of the associated TimeScale within the processing phase of execution
  • termination_learning (Dict[TimeScale: Condition]) – a dictionary containing Conditions that signal the end of the associated TimeScale within the learning phase of execution
  • reinitialize_values (Dict[Mechanism: List[reinitialization values] or np.ndarray(reinitialization values)) – a dictionary containing Mechanism: value pairs. Each Mechanism in the dictionary calls its reinitialize method at the start of the Run. The Mechanism’s value in the reinitialize_values dictionary is passed into its reinitialize method. See the reinitialize method of the function or integrator_function of the Mechanism for details on which values must be passed in as arguments. Keep in mind that only stateful Mechanisms may be reinitialized, and that Mechanisms in reinitialize_values will reinitialize regardless of whether their reinitialize_when Condition is satisfied.
Returns:

<System>.results – list of the OutputValue for each TERMINAL Mechanism of the System returned for each execution.

Return type:

List[Mechanism.OutputValue]

show(options=None)

Print execution_sets, execution_list, ORIGIN, TERMINAL Mechanisms, TARGET Mechanisms, outputs and their labels for the System.

Parameters:options (InspectionOptions) – [TBI]
inspect()

Return dictionary with system attributes and values

Diciontary contains entries for the following attributes and values:

PROCESSES: list of Processes in system;

MECHANISMS: list of all Mechanisms in the system;

ORIGIN_MECHANISMS: list of ORIGIN Mechanisms;

INPUT_ARRAY: ndarray of the inputs to the ORIGIN Mechanisms;

RECURRENT_MECHANISMS: list of INITALIZE_CYCLE Mechanisms;

RECURRENT_INIT_ARRAY: ndarray of initial_values;

TERMINAL_MECHANISMS: list of TERMINAL Mechanisms;

OUTPUT_STATE_NAMES: list of OutputState names corresponding to 1D arrays in output_value_array;

OUTPUT_VALUE_ARRAY: 3D ndarray of 2D arrays of output.value arrays of OutputStates for all TERMINAL Mechanisms;

NUM_PHASES_PER_TRIAL: number of phases required to execute all Mechanisms in the system;

LEARNING_MECHANISMS: list of LearningMechanisms;

TARGET: list of TARGET Mechanisms;

LEARNING_PROJECTION_RECEIVERS: list of MappingProjections that receive learning projections;

CONTROL_MECHANISM: ControlMechanism of the System;

CONTROL_PROJECTION_RECEIVERS: list of ParameterStates that receive learning projections.

Returns:Dictionary of System attributes and values
Return type:dict
mechanisms

List of all mechanisms in the system

Returns:all mechanisms in the system
Return type:List[Mechanism]
stateful_mechanisms

List of all mechanisms in the system that are currently marked as stateful (mechanism.has_initializers = True)

Returns:all stateful mechanisms in the system
Return type:List[Mechanism]
numPhases

Number of phases required to execute all ProcessingMechanisms in the system

Equals maximum phase value of ProcessingMechanisms in the system + 1

Returns:number of phases in system
Return type:int
show_graph(show_processes=False, show_learning=False, show_control=False, show_roles=False, show_dimensions=False, show_mechanism_structure=False, show_headers=True, show_projection_labels=False, direction='BT', active_item=None, active_color='yellow', origin_color='green', terminal_color='red', origin_and_terminal_color='brown', learning_color='orange', control_color='blue', prediction_mechanism_color='pink', system_color='purple', output_fmt='pdf')

Generate a display of the graph structure of Mechanisms and Projections in the System.

Note

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

Displays a graph showing the structure of the System (based on the System's graph). By default, only the primary processing Components are shown, and Mechanisms are displayed as simple nodes. However, the show_mechanism_structure argument can be used to display more detailed information about each Mechanism, including its States and, optionally, the function and value of the Mechanism and each of its States (using the show_functions and show_values arguments, respectively). The show_dimension argument can be used to display the dimensions of each Mechanism and Projection. The show_processes argument arranges Mechanisms and Projections into the Processes to which they belong. The show_learning and show_control arguments can be used to show the Components associated with learning and those associated with the System’s controller.

Mechanisms are always displayed as nodes. If show_mechanism_structure is True, Mechanism nodes are subdivided into sections for its States with information about each determined by the show_values and show_functions specifications. Otherwise, Mechanism nodes are simple ovals. ORIGIN and TERMINAL Mechanisms of the System are displayed with thicker borders in a colors specified for each. Projections are displayed as labelled arrows, unless show_learning is specified, in which case MappingProjections as labelled arrows that point to them.

Note

There are two unresolved anomalies associated with show_graph (it is uncertain whether they are bugs in PsyNeuLink, Graphviz, or an interaction between the two):

  1. When both show_mechanism_structure and show_processes are specified together with show_learning and/or show_control, under some arcane conditions Projection arrows can be distorted and/or orphaned. We have confirmed that this does not reflect a corruption of the underlying graph structure, and the System should execute normally.
  2. Specifying show_processes but not setting show_headers to False raises a GraphViz exception; to deal with this, if show_processes is specified, show_headers is automatically set to False.

Examples

The figure below shows different renderings of the following System that can be generated using its show_graph method:

import psyneulink as pnl
mech_1 = pnl.TransferMechanism(name='Mech 1', size=3, output_states=[pnl.RESULTS, pnl.MEAN])
mech_2 = pnl.TransferMechanism(name='Mech 2', size=5)
mech_3 = pnl.TransferMechanism(name='Mech 3', size=2, function=pnl.Logistic(gain=pnl.CONTROL))
my_process_A = pnl.Process(pathway=[mech_1, mech_3], learning=pnl.ENABLED)
my_process_B = pnl.Process(pathway=[mech_2, mech_3])
my_system = pnl.System(processes=[my_process_A, my_process_B],
                       controller=pnl.ControlMechanism(name='my_system Controller'),
                       monitor_for_control=[(pnl.MEAN, mech_1)],
                       enable_controller=True)

Output of show_graph using different options

System graph examples

Examples of renderings generated by the show_graph method with different options specified, and the call to the show_graph method used to generate each rendering shown below each example. Panel A shows the simplest rendering, with just Processing Components displayed; ORIGIN Mechanisms are shown in red, and the TERMINAL Mechanism in green. Panel B shows the same graph with MappingProjection names and Component dimensions displayed. Panel C shows the learning Components of the System displayed (in orange). Panel D shows the control Components of the System displayed (in blue). Panel E shows both learning and control Components; the learning components are shown with all LearningProjections shown (by specifying show_learning=pnl.ALL). Panel F shows a detailed view of the Processing Components, using the show_mechanism_structure option, that includes Component labels and values. Panel G show a simpler rendering using the show_mechanism_structure, that only shows Component names, but includes the control Components (using the show_control option).

Parameters:
  • show_processes (bool : False) – specifies whether to organize the ProcessingMechanisms into the Processes to which they belong, with each Process shown in its own box. If a Component belongs to more than one Process, it is shown in a separate box along with any others that belong to the same combination of Processes; these represent intersections of Processes within the System.
  • show_mechanism_structure (bool, VALUES, FUNCTIONS or ALL : default False) –

    specifies whether or not to show a detailed representation of each Mechanisms in the graph, including its States; can have the following settings:

    • True – shows States of Mechanism, but not information about the value or function of the Mechanism or its States.
    • VALUES – shows the value of the Mechanism and the value of each of its States.
    • LABELS – shows 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 – shows the function of the Mechanism and the function of its InputStates and OutputStates.
    • ROLES – shows the role of the Mechanism in the System in square brackets (but not any of the other information; use ALL to show ROLES with other information).
    • ALL – shows both value and function of the Mechanism and its States (using labels for the values, if specified; see above).

    Any combination of the settings above can also be specified in a list that is assigned to show_mechanism_structure

  • show_headers (bool : default False) – specifies whether or not to show headers in the subfields of a Mechanism’s node; only takes effect if show_mechanism_structure is specified (see above).
  • show_projection_labels (bool : default False) – specifies whether or not to show names of projections.
  • show_learning (bool or ALL : default False) – specifies whether or not to show the learning components of the system; they will all be displayed in the color specified for learning_color. Projections that receive a LearningProjection will be shown as a diamond-shaped node. if set to ALL, all Projections associated with learning will be shown: the LearningProjections as well as from ProcessingMechanisms to LearningMechanisms that convey error and activation information; if set to True, only the LearningPojections are shown.
  • show_control (bool : default False) – specifies whether or not to show the control components of the system; they will all be displayed in the color specified for control_color.
  • show_roles (bool : default False) – specifies whether or not to include the role that each Mechanism plays in the System (enclosed by square brackets); ‘ORIGIN’ and ‘TERMINAL’ Mechanisms are also displayed in a color specified by the origin_color, terminal_color and origin_and_terminal_color arguments (see below).
  • show_dimensions (bool, MECHANISMS, PROJECTIONS or ALL : default False) –

    specifies whether or not to show dimensions of Mechanisms (and/or MappingProjections when show_learning is True); can have the following settings:

    • MECHANISMS – shows Mechanisms input and output dimensions. Input dimensions are shown in parentheses below the name of the Mechanism; each number represents the dimension of the variable for each InputState of the Mechanism; Output dimensions are shown above the name of the Mechanism; each number represents the dimension for value of each of OutputState of the Mechanism.
    • PROJECTIONS – shows MappingProjection matrix dimensions. Each is shown in (<dim>x<dim>…) format; for standard 2x2 “weight” matrix, the first entry is the number of rows (input dimension) and the second the number of columns (output dimension).
    • ALL – eqivalent to True; shows dimensions for both Mechanisms and Projections (see above for formats).
  • direction (keyword : default 'BT') – ‘BT’: bottom to top; ‘TB’: top to bottom; ‘LR’: left to right; and ‘RL`: right to left.
  • active_item (Component : default None) – specifies the item in the graph to display in the color specified by active_color*.
  • active_color (keyword : default 'yellow') – specifies the color in which to display the item specified in active_item*.
  • origin_color (keyword : default 'green',) – specifies the color in which the ORIGIN Mechanisms of the System are displayed.
  • terminal_color (keyword : default 'red',) – specifies the color in which the TERMINAL Mechanisms of the System are displayed.
  • origin_and_terminal_color (keyword : default 'brown') – specifies the color in which Mechanisms that are both an ORIGIN and a TERMINAL of the System are displayed.
  • learning_color (keyword : default green) – specifies the color in which the learning components are displayed.
  • control_color (keyword : default blue) – specifies the color in which the learning components are displayed (note: if the System’s controller is an EVCControlMechanism, then a link is shown in pink from the prediction Mechanisms it creates to the corresponding ORIGIN Mechanisms of the System, to indicate that although no projection are created for these, the prediction Mechanisms determine the input to the ORIGIN Mechanisms when the EVCControlMechanism simulates execution of the System).
  • prediction_mechanism_color (keyword : default pink) – specifies the color in which the prediction_mechanisms are displayed for a System using an EVCControlMechanism
  • system_color (keyword : default purple) – specifies the color in which the node representing input from the System is 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 system – ‘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

class psyneulink.components.system.SystemInputState(owner=None, variable=None, name=None, prefs=None, context=None)

Represents inputs and targets specified in a call to the System’s execute and run methods.

A SystemInputState is created for each InputState of each ORIGIN Mechanism in origin_mechanisms, and for the TARGET InputState of each ComparatorMechanism listed in target_mechanisms. A MappingProjection is created that projects to each of these InputStates from the corresponding SystemInputState. When the System’s execute or run method is called, each item of its inputs and targets arguments is assigned as the value of a SystemInputState, which is then conveyed to the corresponding InputState of the origin_mechanisms and terminal_mechanisms. See Mechanisms and Execution for additional details.