Reporting¶

Reporting is enabled by specifying the reporting arguments of a Composition's execution methods or the execute method of a Mechanism. There are two types of reporting that can be generated: output reporting and progress reporting. These can be directed to the python console or other devices, as described below.

Output Reporting¶

Output reporting provides information about the input and output to a Mechanism or to a Composition and its Nodes as they execute. Options can be specified using a value of ReportOutput in the reportOutputPref of a Component, or the report_output argument of a Mechanism’s execute method or any of a Composition’s execution methods. If USE_PREFS or TERSE is used, reporting is generated as execution of each Component occurs; if FULL is used, then the information is reported at the end of each TRIAL executed. This always includes the input and output to a Mechanism or a Composition and its Nodes, and can also include the values of their Parameters, depending on the specification of the report_params argument (using ReportParams options and/or the reportOutputPref settings of individual Mechanisms). The output for a nested Composition is indented relative to the output for the Composition within which it is nested. Whether simulations executed by a Composition’s controller are reported is determined by the report_simulations argument, using a ReportSimulations option and, if displayed, is indented relative to the controller that executed the simulations. Output is reported to the devices specified in the report_to_devices argument using the ReportDevices options (the Python console by default).

Progress Reporting¶

Progress reporting provides information about the status of execution of a Composition’s run or learn methods. It can be enabled/disabled by specifying a ReportProgress option in the report_progress argument of either of those methods. If enabled, progress is reported at the end of each TRIAL of a Composition's execution, showing the number of TRIALS that have been executed and a progress bar. If the number TRIALS to be executed is determinable (e.g., the num_trials of a Composition’s run or learn method is specified), estimated time remaining is displayed; if the number of trials is not determinable (e.g., if inputs argument is specified using a generator), then a “spinner” is displayed during execution and the the total number of TRIALS executed is displayed once complete. Whether simulations executed by an a Composition’s controller are included is determined by the report_simulations argument using a ReportSimulations option. Progress is reported to the devices specified in the report_to_devices argument using the ReportDevices options.

Progress reporting is generated and displayed using a rich Progress Display object.

Simulations¶

Output and progress reporting can include execution in simulations of a Composition’s controller), by specifying a ReportSimulations option in the report_simulations argument of a Composition’s run or learn methods.

Learning¶

Output and progress reporting can be enabled during learning by specifying a ReportOutput and/or ReportProgress option in, repsectively, the report_output and/or report_progress argument(s) of the Composition’s learn method. For learning using a standard Composition, reporting occurs after every TRIAL is executed; for learning using an AutodiffComposition, which uses either direct compilation or translation to Pytorch, reporting occurs just before learning begins and once it ends.

Devices¶

The device(s) to which reporting is sent can be specified using the report_to_device argument of a Mechanism’s execute method or any of a Composition’s execution methods; this can be used to store reports in a Composition’s recorded_reports attribute; see ReportDevices for options.

Reporting Options¶

class psyneulink.core.compositions.report.ReportOutput(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Options used in the report_output argument of a Composition’s execution methods or the execute method of a Mechanism, to enable and determine the type of output generated by reporting (Output Reporting for additional information).

Use of these options is expected in the report_output constructor for the Reporting object, and are used as the values of its _report_output attribute.

OFF¶: suppress output reporting.

USE_PREFS¶: use the reportOutputPref of each Composition and/or Mechanism executed to determine whether and in what format to report its execution.

TERSE(aka ON)¶: enforce reporting execution of all Compositions and/or Mechanisms as they are executed, irrespective of their reportOutputPref settings, using a simple line-by-line format to report each.

FULL¶: enforce formatted reporting execution of all Compositions and/or Mechanisms at the end of each TRIAL of execution, including the input and output of each, irrespective of their reportOutputPref settings.

Output is formatted using rich Panel objects.

class psyneulink.core.compositions.report.ReportParams(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Options used in the report_params argument of a Composition’s execution methods, to specify the scope of reporting for values of it Parameters and those of its Nodes (see Output Reporting for additional details).

Use of these options is expected in the report_output constructor for the Reporting object, and are used as the values of its _report_params attribute.

OFF¶: suppress reporting of parameter values.

USE_PREFS¶: defers to reportOutputPref settings of individual Components.

CONTROLLED(aka MODULATED)¶: report all Parameters that are being controlled (i.e., modulated) by a ControlMechanism within the Composition (that is, those for which the corresponding ParameterPort receives a ControlProjection from a ControlSignal).

MODULATED(aka CONTROLLED)¶: this is identical to ReportParams.CONTROLLED.

MONITORED¶: report the value of any Mechanism that is being monitored by a ControlMechanism or ObjectiveMechanism.

LOGGED¶: report all Parameters that are specified to be logged with LogCondition.EXECUTION; see Log for additional details.

ALL¶: enforce reporting of all Parameters of a Composition and its Nodes.

class psyneulink.core.compositions.report.ReportProgress(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Options used in the report_progress argument of a Composition’s run and learn methods, to enable/disable progress reporting during execution of a Composition; see Progress Reporting for additional details (see Progress Reporting for additional information).

Use of these options is expected in the report_progress constructor for the Reporting object, and are used as the values of its _report_progress attribute.

OFF¶: suppress progress reporting.

ON¶: enable progress reporting for executions of a Composition.

class psyneulink.core.compositions.report.ReportDevices(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Options used in the report_to_devices argument of a Composition’s execution methods or the execute method of a Mechanism, to determine the devices to which reporting is directed (see Report_To_Device for additional information).

Use of these options is expected in the report_to_devices constructor for the Reporting object, and are used as the values of its _report_to_devices attribute.

CONSOLE¶: direct reporting to the console in which PsyNeuLink is running

output is rendered using the Console markup by a rich Progress object stored in _instance._rich_progress.

RECORD¶: capture reporting in _recorded_reports; specifying this option on its own replaces and suppresses reporting to the console; to continue to generate console output, explicitly include CONSOLE along with RECORD in the argument specification.

.. technical_note::

DIVERT: capture reporting otherwise directed to the rich Console in a UDF-8 formatted string and stores it in _rich_diverted_reports. This option suppresses console output and is cumulative (that is, it records the sequences of updates sent to the console after each TRIAL) and is intended primarily for unit testing. The RECORD option should be used for recording output, as it can be used with console output if desired, and reflects the final state of the display after execution is complete.

PNL_VIEW¶: direct reporting to the PsyNeuLinkView graphical interface [UNDER DEVELOPMENT].

class psyneulink.core.compositions.report.ReportSimulations(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Options used in the report_simulations argument of a Composition’s run and learn methods, to specify whether simulations executed by an a Composition’s controller are included in output and progress reporting (see Simulations for additional information).

Use of these options is expected in the report_progress constructor for the Reporting object, and are used as the values of its _report_simulations attribute.

OFF¶: suppress output and progress of simulations.

ON¶: enable output and progress reporting of simulations.