diagram_watcher

Submodules

Classes

class brom_drake.watchers.diagram_watcher.diagram_watcher.DiagramWatcher(subject: DiagramBuilder, targets: List[DiagramTarget] = None, options: DiagramWatcherOptions = DiagramWatcherOptions(base_directory='./brom/watcher', plotting_options=PortWatcherPlottingOptions(plot_arrangement=<PortFigureArrangement.OnePlotPerPort: 1>, plot_dpi=300, save_to_file=True, file_format='png', figure_naming_convention=<FigureNamingConvention.kFlat: 0>), raw_data_options=PortWatcherRawDataOptions(save_to_file=True, file_format='npy'), hide_messages=SuppressDiagramWatcherRules(during_port_watcher_connection=False)))

Description

An object that will iterate through all elements of a partially built Drake Diagram (via the DiagramBuilder) and add PortWatchers to the specified targets.

Parameters

subject: DiagramBuilder

We will search through the subject (a diagram builder) to find all the systems that we want to monitor.

targets: List[DiagramTarget], optional

The targets that we want to monitor, by default this tries to monitor all systems in the diagram. (i.e., when this value is None, we will monitor all systems).

options: DiagramWatcherOptions, optional

The options that configure the DiagramWatcher, by default DiagramWatcherOptions()

get_all_port_watchers_for_system(system_name: str) → Dict[str, PortWatcher]

Description

Gets all the PortWatcher objects for a given system name.

Parameters

system_namestr

The name of the system.

Returns port_watchers : Dict[str, PortWatcher]

A dictionary of port name to PortWatcher object for the given system name.

get_port_watcher(system_name: str, port_name: str) → PortWatcher

Description

Gets the PortWatcher object for a given system name and port name.

Parameters

system_namestr

The name of the system.

port_namestr

The name of the port.

Returns

port_watcherPortWatcher

The PortWatcher object for the given system name and port name.

property port_watchers: Dict[str, Dict[str, PortWatcher]]

Description

Returns the internal dictionary of port watchers.

Deprecated since version Use: get_all_port_watchers_for_system() or get_port_watcher() instead.

Returns

port_watchersDict[str, Dict[str, PortWatcher]]

A nested dictionary of system names to port names to PortWatcher objects.

class brom_drake.watchers.diagram_watcher.diagram_watcher_options.DiagramWatcherOptions(base_directory: str = './brom/watcher', plotting_options: PortWatcherPlottingOptions = (PortFigureArrangement.OnePlotPerPort, 300, True, 'png', FigureNamingConvention.kFlat), raw_data_options: PortWatcherRawDataOptions = (True, 'npy'), hide_messages: SuppressDiagramWatcherRules = SuppressDiagramWatcherRules(during_port_watcher_connection=False))

Description

This class contains the options that configure the following properties of the DiagramWatcher: - Where it saves its data (plots, raw data, etc.) - the format that it uses to save its data/plots - what types of messages to suppress during its operation

Tip

The DiagramWatcherOptions class has useful defaults defined for ALL of its attributes, so in most cases, the user will not need to modify any of them. You can simply create a DiagramWatcherOptions object with no arguments and it will work out of the box. (e.g., options = DiagramWatcherOptions())

Attributes

base_directory: str, optional

The base directory where the watcher will save any data (e.g., plots, or dataframes) during its operation as well as logs.

plotting_options: PortWatcherPlottingOptions, optional

The options that configure how the PortWatcher will save its plots.

raw_data_options: PortWatcherRawDataOptions, optional

The options that configure how the PortWatcher will save its raw data.

hide_messages: SuppressDiagramWatcherRules, optional

The rules that define which types of messages to suppress during the operation of the DiagramWatcher.

to_port_watcher_options() → PortWatcherOptions

Description

This function converts the DiagramWatcherOptions to a PortWatcherOptions object.

Returns

PortWatcherOptions

The PortWatcherOptions object.

class brom_drake.watchers.diagram_watcher.diagram_watcher_options.SuppressDiagramWatcherRules(during_port_watcher_connection: bool = False)

Description

A signal that defines which types of messages to suppress when using the DiagramWatcher.

Attributes

during_port_watcher_connection: bool

If True, suppress log messages that occur during the connection of PortWatchers to the DiagramWatcher.

class brom_drake.watchers.diagram_watcher.errors.PortIsNotBeingWatchedError(target: DiagramTarget, port_reference: int | str, port_names: List[str] = None)

Description

Raised when someone requests a port’s information from the DiagramWatcher and that port is not being watched.

class brom_drake.watchers.diagram_watcher.errors.PortIsNotFoundInDiagramError(target: DiagramTarget, port_reference: int | str, port_names: List[str] = None)

Description

Raised when the DiagramWatcher is attempting to add a port to its tracking but does not find it in the Diagram.

class brom_drake.watchers.diagram_watcher.errors.SystemIsNotBeingWatchedError(target: DiagramTarget, system_names: List[str] = None)

Description

Raised when someone requests a system’s information from the DiagramWatcher and that system is not being watched.

class brom_drake.watchers.diagram_watcher.errors.SystemIsNotFoundInDiagramError(target: DiagramTarget, system_names: List[str] = None)

Description

Raised when the DiagramWatcher is attempting to add a system to its tracking but does not find it in the Diagram.

Functions

brom_drake.watchers.diagram_watcher.add_watcher.add_watcher(builder: DiagramBuilder, targets: List[str | Tuple[str, int] | Tuple[int, int] | Tuple[str, str] | Tuple[str, List[int]] | Tuple[int, List[int]] | Tuple[str, List[str]]] = None, watcher_dir: str = './brom/watcher', plot_arrangement: PortFigureArrangement = PortFigureArrangement.OnePlotPerPort, figure_naming_convention: FigureNamingConvention = FigureNamingConvention.kFlat, file_format: str = 'png') → DiagramWatcher

Description

This function adds a DiagramWatcher to a Drake Diagram. The diagram is not finalized yet and so it is accessible via the builder argument. The watcher will insert LogVectorSink systems to log the output ports of the systems specified in the targets argument.

Importantly, this function does NOT build the diagram.

Parameters

builderDiagramBuilder

The diagram builder to which we want to add the watcher.

targetsList[Tuple[Union[str, int]]]

The targets that we want to watch.

watcher_dirstr, optional

The directory in which we will store the data collected by the DiagramWatcher. By default, DEFAULT_WATCHER_DIR.

plot_arrangementPortFigureArrangement, optional

The arrangement of the plots. By default, PortFigureArrangement.OnePlotPerPort.

figure_naming_conventionFigureNamingConvention, optional

The naming convention for the figures. By default, FigureNamingConvention.kFlat.

file_formatstr, optional

The file format for the figures. By default, “png”.

Example Usage

The simplest way to use this function is to just pass in the diagram builder:

watcher = add_watcher(builder)

You can also specify which systems and ports to watch by passing in a list of targets. Each target can be specified as either:

• A string representing the name of the system to watch (all ports will be watched), or

• A tuple of (system_name: str, port_index: int) to watch a specific port of a system, or

• A tuple of (system_index: int, port_index: int) to watch a specific port of a system by its index.

Here are some examples of how to specify targets:

watcher = add_watcher(builder, [("plant", 0), ("controller", 0)])

Returns

watcherDiagramWatcher

The watcher that we have added to the diagram builder.

brom_drake.watchers.diagram_watcher.add_watcher.add_watcher_and_build(builder: DiagramBuilder, targets: List[str | Tuple[str, int] | Tuple[int, int] | Tuple[str, str] | Tuple[str, List[int]] | Tuple[int, List[int]] | Tuple[str, List[str]]] = None, watcher_dir: str = './brom/watcher', plot_arrangement: PortFigureArrangement = PortFigureArrangement.OnePlotPerPort, figure_naming_convention: FigureNamingConvention = FigureNamingConvention.kFlat, file_format: str = 'png') → Tuple[DiagramWatcher, Diagram, Context]

Description

This function adds a DiagramWatcher to a Drake Diagram. The diagram is not finalized yet and so it is accessible via the builder argument. The watcher will insert LogVectorSink systems to log the output ports of the systems specified in the targets argument.

Once all of the LogVectorSink systems have been added, the diagram is built and a reference to the built diagram and its default context is added to the DiagramWatcher object.

Example Usage:

watcher = add_watcher_and_build(builder)

In addition, one can specify which systems to watch:

watcher = add_watcher_and_build(builder, targets=[("plant",)])

The DiagramWatcher will then watch all supported ports of the “plant” system that it can find.

Furthermore, to specify which systems and specific ports to watch:

watcher = add_watcher_and_build(builder, targets=[("plant", 0), ("controller", 0)])

This will watch output port 0 of both the “plant” and “controller” systems, if possible.

Parameters

builder: DiagramBuilder

The diagram builder to which we want to add the watcher.

targets: List[Tuple[Union[str, int]]]

The targets that we want to watch.

watcher_dir: str

The directory in which we will store the data collected by the DiagramWatcher.

plot_arrangement: PortFigureArrangement

The arrangement of the plots. (Can be PortFigureArrangement.OnePlotPerPort OR PortFigureArrangement.OnePlotPerDim)

figure_naming_convention: FigureNamingConvention

The naming convention for the figures. (Can be FigureNamingConvention.kFlat OR FigureNamingConvention.kHierarchical)

file_format: str

The file format for the figures.

Returns

watcher: DiagramWatcher

The watcher that we have added to the diagram builder.

diagram: Diagram

The built diagram.

diagram_context: Context

The default context for the built diagram.

brom_drake.watchers.diagram_watcher.add_watcher.parse_list_of_simplified_targets(builder: DiagramBuilder, targets: List[str | Tuple[str, int] | Tuple[int, int] | Tuple[str, str] | Tuple[str, List[int]] | Tuple[int, List[int]] | Tuple[str, List[str]]]) → List[DiagramTarget]

Description

This function takes a list of simplified targets and converts them to the full form.

Example Usage

targets = [("plant", 0), ("controller", 0)]
parsed_targets = parse_list_of_simplified_targets(targets)

Parameters

builderDiagramBuilder

The diagram builder to which we want to add the watcher.

targetsList[Tuple[Union[str, int]]

The list of simplified targets.

Returns

parsed_targets: List[DiagramTarget]

A list of all the targets that we want to watch.

Variables

brom_drake.watchers.diagram_watcher.all.INELIGIBLE_SYSTEM_TYPES = [<class 'pydrake.geometry.SceneGraph'>, <class 'pydrake.systems.primitives.VectorLogSink'>, <class 'pydrake.systems.primitives.ConstantVectorSource'>]

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

brom_drake.watchers.diagram_watcher.constants.INELIGIBLE_SYSTEM_TYPES = [<class 'pydrake.geometry.SceneGraph'>, <class 'pydrake.systems.primitives.VectorLogSink'>, <class 'pydrake.systems.primitives.ConstantVectorSource'>]

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.