reports_system.py

reports_system.py

Utility functions related to the reporting system which generates reports by default for all runs.

class openmdao.utils.reports_system.Report(name, description='')[source]

Bases: object

A class to manage the resistration of hooks associated with a particular named report.

Parameters
namestr

The name of the corresponding report.

descriptionstr

The description displayed when reports are listed using the list_reports command.

Attributes
namestr

The name of the corresponding report.

descriptionstr

The description displayed when reports are listed using the list_reports command.

hookslist

List of (args, kwargs) to be passed to the register_hook function when the report corresponding to this instance is activated.

__init__(name, description='')[source]

Initialize attributes.

register_hook_args(*args, **kwargs)[source]

Store positional and named args to be passed to the register_hook function.

This will only happen if the report corresponding to this instance is activated.

Parameters
*argslist

The positional args to be passed to register_hook.

**kwargsdict

The named args to be passed to register_hook.

register_hooks(instance)[source]

Register the hook(s) associated with the report corresponding with this instance.

Parameters
instanceobject

The instance where hooks may be registered.

unregister_hooks(instance=None)[source]

Unregister hooks associated with this report.

Parameters
instanceobject or None

If not None, only unregister reports for this instance.

openmdao.utils.reports_system.activate_report(name, instance=None)[source]

Activate a report that has been registered with the reporting system.

Parameters
namestr

Name of report. Report names must be unique across all reports.

instanceobject or None

If not None, report will be activated only for this instance, assuming the instance in the reports_registry is either None or matching.

openmdao.utils.reports_system.activate_reports(reports, instance)[source]

Activate any matching reports.

Parameters
reportslist of str

List of report names that should be active. These names come down from the Problem and some may refer to Problem reports while others may refer to Driver reports.

instanceobject

The reports will be activated for this instance.

openmdao.utils.reports_system.clear_report_registry()[source]

Clear all of the reports from the registry.

openmdao.utils.reports_system.clear_reports(instance=None)[source]

Clear all of the currently active reports.

Parameters
instanceobject or None

If not None, only clear reports for this instance.

openmdao.utils.reports_system.gen_index_file(reports_dir, level, to_match)[source]

Generate an index.html file that will have links to all of the reports.

Parameters
reports_dirstr

The top directory containing the reports.

levelint

Expand the reports directory tree to this level.

to_matchset

Set of subdirectory names to show.

openmdao.utils.reports_system.get_reports_dir()[source]

Get the path to the top level reports directory. Defaults to ‘./reports’.

Returns
str

Path to the top level reports directory.

openmdao.utils.reports_system.get_reports_to_activate(reports=UNDEFINED)[source]

Get the list of names of reports that should be activated.

Parameters
reportsstr, list of str, _UNDEFINED, or None

Indicates which report(s) are to be activated.

Returns
list of str

List of report names.

openmdao.utils.reports_system.list_reports(default=False, outfile=None, max_width=80)[source]

Write table of information about reports currently registered in the reporting system.

Parameters
defaultbool

If True, list only the default reports.

outfilestr or None

Where to send report info. None will result in output to stdout.

max_widthint

Maximum width of the table. Defaults to 80.

openmdao.utils.reports_system.register_report(name, func, desc, class_name, method, pre_or_post, inst_id=None, **kwargs)[source]

Register a report with the reporting system.

Parameters
namestr

Name of report. Report names must be unique across all reports.

funcfunction

A function to do the reporting. Expects the first argument to be an instance of class_name.

descstr

A description of the report.

class_namestr

The name of the class owning the method where the report will be run.

methodstr

In which method of class_name should this be run.

pre_or_poststr

Valid values are ‘pre’ and ‘post’. Indicates when to run the report in the method.

inst_idstr or None

Either the instance ID of an OpenMDAO object (e.g. Problem, Driver) or None. If None, then this report will be run for all objects of type class_name.

**kwargsdict

Keyword args passed to the report function.

openmdao.utils.reports_system.register_report_hook(name, fname, class_name, inst_id=None, pre=None, post=None, description='', **kwargs)[source]

Register a hook with a specific report name in the reporting system.

By calling this multiple times, multiple hooks can be registered for the same report. This is sometimes necessary to get the correct behavior when setup errors occur prior to report creation.

Parameters
namestr

Name of report. Report names must be unique across all reports.

fnamestr

The name of the function where the pre and/or post hook will be applied.

class_namestr

The name of the class owning the method where the hook will be applied.

inst_idstr or None

The name of the instance owning the method where the hook will be applied.

prefunction (None)

If not None, this hook will run before the function named by fname runs.

postfunction (None)

If not None, this hook will run after the function named by fname runs.

descriptionstr

A description of the report.

**kwargsdict of keyword arguments

Keyword arguments that will be passed to the hook function.

openmdao.utils.reports_system.report_function(x)
openmdao.utils.reports_system.reports_active()[source]

Return True if reports are active globally.

Returns
bool

Return True if reports are active.

openmdao.utils.reports_system.run_n2_report(x)
openmdao.utils.reports_system.set_default_reports_dir(reports_dir_path)

Set the path to the top level reports directory. Defaults to ‘./reports’.

Parameters
reports_dir_pathstr

Path to the top level reports directory.

openmdao.utils.reports_system.set_reports_dir(reports_dir_path)[source]

Set the path to the top level reports directory. Defaults to ‘./reports’.

Parameters
reports_dir_pathstr

Path to the top level reports directory.

openmdao.utils.reports_system.setup_default_reports()
openmdao.utils.reports_system.unregister_report(name)[source]

Unregister a report with the reporting system.

Parameters
namestr

Name of report. Report names must be unique across all reports.

openmdao.utils.reports_system.view_reports(probnames=None, level=2)[source]

Pop up a browser to view specified reports.

Parameters
probnamesstr, iter of str, or None

If not None, view only reports for the specified Problem(s), else view all reports.

levelint

Expand the reports directory tree to this level. Default is 2.