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='')

Bases: object

A class to manage the registration 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='')

Initialize attributes.

register_hook_args(*args, **kwargs)

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)

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)

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)

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)

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()

Clear all of the reports from the registry.

openmdao.utils.reports_system.clear_reports(instance=None)

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_reports_index_file(start_dir, level, to_match)

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

Parameters:

start_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()

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)

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)

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, predicate=None, **kwargs)

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.

predicatefunction or None

If not None, this function will be called to determine if the report’s hook function should run. The predicate function should take the class instance as its only argument and return True if the report should run. Note that returning False does not disable the hook, it just prevents the hook from running at that time.

**kwargsdict

Keyword args passed to the report function.

Returns:

Report

The registered report object.

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

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()

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)

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)

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)

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.