Detailed Description

template<typename T>
class drake::systems::DiagramBuilder< T >

DiagramBuilder is a factory class for Diagram.

It is single use: after calling Build or BuildInto, DiagramBuilder gives up ownership of the constituent systems, and should therefore be discarded; all member functions will throw an exception after this point.

When a Diagram (or DiagramBuilder) that owns systems is destroyed, the systems will be destroyed in the reverse of the order they were added.

A system must be added to the DiagramBuilder with AddSystem or AddNamedSystem before it can be wired up in any way. Every system must have a unique, non-empty name.

Building large Diagrams

When building large Diagrams with many added systems and input-output port connections, the runtime performance of DiagramBuilder::Build() might become relevant.

As part of its correctness checks, the DiagramBuilder::Build() function performs a graph search of the diagram's dependencies. In the graph, the nodes are the child systems that have been added to the diagram, and the edges are the diagram connections from one child's output port to another child's input port(s). The builder must confirm that the graph is acyclic; a cycle would imply an infinite loop in an output calculation function. With a large graph, this check can be computationally expensive. To speed it up, ensure that your output ports do not gratuitously depend on irrelevant input ports.

The dependencies are supplied via the prerequisites_of_calc argument to DeclareOutputPort family of functions. If the default value is used (i.e., when no prerequisites are provided), the default is to assume the output port value is dependent on all possible sources.

Refer to the Direct feedthrough documentation for additional details and examples. In particular, the SystemBase::all_sources_except_input_ports_ticket() is a convenient shortcut for outputs that do not depend on any inputs.

#include <drake/systems/framework/diagram_builder.h>

Public Types
using	InputPortLocator = typename Diagram< T >::InputPortLocator
	A designator for a "system + input port" pair, to uniquely refer to some input port on one of this builder's subsystems. More...

using	OutputPortLocator = typename Diagram< T >::OutputPortLocator
	A designator for a "system + output port" pair, to uniquely refer to some output port on one of this builder's subsystems. More...

Public Member Functions
	DiagramBuilder ()

virtual	~DiagramBuilder ()

template<class S >
S *	AddSystem (std::unique_ptr< S > system)
	Takes ownership of `system` and adds it to the builder. More...

template<class S , typename... Args>
S *	AddSystem (Args &&... args)
	Constructs a new system with the given `args`, and adds it to the builder, which retains ownership. More...

template<template< typename Scalar > class S, typename... Args>
S< T > *	AddSystem (Args &&... args)
	Constructs a new system with the given `args`, and adds it to the builder, which retains ownership. More...

template<class S >
S *	AddNamedSystem (const std::string &name, std::unique_ptr< S > system)
	Takes ownership of `system`, applies `name` to it, and adds it to the builder. More...

template<class S , typename... Args>
S *	AddNamedSystem (const std::string &name, Args &&... args)
	Constructs a new system with the given `args`, applies `name` to it, and adds it to the builder, which retains ownership. More...

template<template< typename Scalar > class S, typename... Args>
S< T > *	AddNamedSystem (const std::string &name, Args &&... args)
	Constructs a new system with the given `args`, applies `name` to it, and adds it to the builder, which retains ownership. More...

void	RemoveSystem (const System< T > &system)
	Removes the given system from this builder and disconnects any connections or exported ports associated with it. More...

bool	empty () const
	Returns whether any Systems have been added yet. More...

bool	already_built () const
	Returns true iff Build() or BuildInto() has been called on this Builder, in which case it's an error to call any member function other than the the destructor. More...

std::vector< const System< T > * >	GetSystems () const
	Returns the list of contained Systems. More...

std::vector< System< T > * >	GetMutableSystems ()
	Returns the list of contained Systems. More...

bool	HasSubsystemNamed (std::string_view name) const
	Returns true iff this contains a subsystem with the given name. More...

const System< T > &	GetSubsystemByName (std::string_view name) const
	Retrieves a const reference to the subsystem with name `name` returned by get_name(). More...

System< T > &	GetMutableSubsystemByName (std::string_view name)
	Retrieves a mutable reference to the subsystem with name `name` returned by get_name(). More...

template<template< typename > class MySystem>
const MySystem< T > &	GetDowncastSubsystemByName (std::string_view name) const
	Retrieves a const reference to the subsystem with name `name` returned by get_name(), downcast to the type provided as a template argument. More...

template<template< typename > class MySystem>
MySystem< T > &	GetMutableDowncastSubsystemByName (std::string_view name)
	Retrieves a mutable reference to the subsystem with name `name` returned by get_name(), downcast to the type provided as a template argument. More...

const std::map< InputPortLocator, OutputPortLocator > &	connection_map () const
	(Advanced) Returns a reference to the map of connections between Systems. More...

void	Connect (const OutputPort< T > &src, const InputPort< T > &dest)
	Declares that input port `dest` is connected to output port `src`. More...

void	Connect (const System< T > &src, const System< T > &dest)
	Declares that sole input port on the `dest` system is connected to sole output port on the `src` system. More...

void	Cascade (const System< T > &src, const System< T > &dest)
	Cascades `src` and `dest`. More...

InputPortIndex	ExportInput (const InputPort< T > &input, std::variant< std::string, UseDefaultName > name=kUseDefaultName)
	Declares that the given `input` port of a constituent system is connected to a new input to the entire Diagram. More...

void	ConnectInput (std::string_view diagram_port_name, const InputPort< T > &input)
	Connects an input to the entire Diagram, indicated by `diagram_port_name`, to the given `input` port of a constituent system. More...

void	ConnectInput (InputPortIndex diagram_port_index, const InputPort< T > &input)
	Connects an input to the entire Diagram, indicated by `diagram_port_index`, to the given `input` port of a constituent system. More...

bool	ConnectToSame (const InputPort< T > &exemplar, const InputPort< T > &dest)
	Connects `dest` to the same source as `exemplar` is connected to. More...

OutputPortIndex	ExportOutput (const OutputPort< T > &output, std::variant< std::string, UseDefaultName > name=kUseDefaultName)
	Declares that the given `output` port of a constituent system is an output of the entire diagram. More...

std::unique_ptr< Diagram< T > >	Build ()
	Builds the Diagram that has been described by the calls to Connect, ExportInput, and ExportOutput. More...

void	BuildInto (Diagram< T > *target)
	Configures `target` to have the topology that has been described by the calls to Connect, ExportInput, and ExportOutput. More...

bool	IsConnectedOrExported (const InputPort< T > &port) const
	Returns true iff the given input `port` of a constituent system is either connected to another constituent system or exported as a diagram input. More...

int	num_input_ports () const
	Returns the current number of diagram input ports. More...

int	num_output_ports () const
	Returns the current number of diagram output outputs. More...

Does not allow copy, move, or assignment
	DiagramBuilder (const DiagramBuilder &)=delete

DiagramBuilder &	operator= (const DiagramBuilder &)=delete

	DiagramBuilder (DiagramBuilder &&)=delete

DiagramBuilder &	operator= (DiagramBuilder &&)=delete

Member Typedef Documentation

◆ InputPortLocator

using InputPortLocator = typename Diagram<T>::InputPortLocator

A designator for a "system + input port" pair, to uniquely refer to some input port on one of this builder's subsystems.

◆ OutputPortLocator

using OutputPortLocator = typename Diagram<T>::OutputPortLocator

A designator for a "system + output port" pair, to uniquely refer to some output port on one of this builder's subsystems.

Constructor & Destructor Documentation

◆ DiagramBuilder() [1/3]

DiagramBuilder ( const DiagramBuilder< T > & )

delete

◆ DiagramBuilder() [2/3]

DiagramBuilder ( DiagramBuilder< T > && )

delete

◆ DiagramBuilder() [3/3]

DiagramBuilder ( )

◆ ~DiagramBuilder()

virtual ~DiagramBuilder ( )

virtual

Member Function Documentation

◆ AddNamedSystem() [1/3]

S* AddNamedSystem	(	const std::string &	name,
		std::unique_ptr< S >	system
	)

Takes ownership of system, applies name to it, and adds it to the builder.

Returns a bare pointer to the System, which will remain valid for the lifetime of the Diagram built by this builder.

DiagramBuilder<T> builder;

auto bar = builder.AddNamedSystem("bar", std::make_unique<Bar<T>>());

Template Parameters

S	The type of system to add.

Postcondition: The system's name is name.

◆ AddNamedSystem() [2/3]

S* AddNamedSystem	(	const std::string &	name,
		Args &&...	args
	)

Constructs a new system with the given args, applies name to it, and adds it to the builder, which retains ownership.

Returns a bare pointer to the System, which will remain valid for the lifetime of the Diagram built by this builder.

DiagramBuilder<double> builder;

auto bar = builder.AddNamedSystem<Bar<double>>("bar", 3.14);

Note that for dependent names you must use the template keyword:

DiagramBuilder<T> builder;

auto bar = builder.template AddNamedSystem<Bar<T>>("bar", 3.14);

You may prefer the unique_ptr variant instead.

Template Parameters

S	The type of System to construct. Must subclass System<T>.

Postcondition: The newly constructed system's name is name.

◆ AddNamedSystem() [3/3]

S<T>* AddNamedSystem	(	const std::string &	name,
		Args &&...	args
	)

Constructs a new system with the given args, applies name to it, and adds it to the builder, which retains ownership.

Returns a bare pointer to the System, which will remain valid for the lifetime of the Diagram built by this builder.

DiagramBuilder<double> builder;
// Bar must be a template.
auto bar = builder.AddNamedSystem<Bar>("bar", 3.14);

Note that for dependent names you must use the template keyword:

DiagramBuilder<T> builder;

auto bar = builder.template AddNamedSystem<Bar>("bar", 3.14);

You may prefer the unique_ptr variant instead.

Template Parameters

S	A template for the type of System to construct. The template will be specialized on the scalar type T of this builder.

Postcondition: The newly constructed system's name is name.

◆ AddSystem() [1/3]

S* AddSystem ( std::unique_ptr< S > system )

Takes ownership of system and adds it to the builder.

Returns a bare pointer to the System, which will remain valid for the lifetime of the Diagram built by this builder.

If the system's name is unset, sets it to System::GetMemoryObjectName() as a default in order to have unique names within the diagram.

DiagramBuilder<T> builder;

auto foo = builder.AddSystem(std::make_unique<Foo<T>>());

Template Parameters

S	The type of system to add.

◆ AddSystem() [2/3]

S* AddSystem ( Args &&... args )

Constructs a new system with the given args, and adds it to the builder, which retains ownership.

Returns a bare pointer to the System, which will remain valid for the lifetime of the Diagram built by this builder.

DiagramBuilder<double> builder;

auto foo = builder.AddSystem<Foo<double>>("name", 3.14);

Note that for dependent names you must use the template keyword:

DiagramBuilder<T> builder;

auto foo = builder.template AddSystem<Foo<T>>("name", 3.14);

You may prefer the unique_ptr variant instead.

Template Parameters

S	The type of System to construct. Must subclass System<T>.

◆ AddSystem() [3/3]

S<T>* AddSystem ( Args &&... args )

Constructs a new system with the given args, and adds it to the builder, which retains ownership.

Returns a bare pointer to the System, which will remain valid for the lifetime of the Diagram built by this builder.

DiagramBuilder<double> builder;
// Foo must be a template.
auto foo = builder.AddSystem<Foo>("name", 3.14);

Note that for dependent names you must use the template keyword:

DiagramBuilder<T> builder;

auto foo = builder.template AddSystem<Foo>("name", 3.14);

You may prefer the unique_ptr variant instead.

Template Parameters

S	A template for the type of System to construct. The template will be specialized on the scalar type T of this builder.

◆ already_built()

bool already_built ( ) const

Returns true iff Build() or BuildInto() has been called on this Builder, in which case it's an error to call any member function other than the the destructor.

◆ Build()

std::unique_ptr<Diagram<T> > Build ( )

Builds the Diagram that has been described by the calls to Connect, ExportInput, and ExportOutput.

Exceptions

std::exception if the graph is not buildable.

See Building large Diagrams for tips on improving runtime performance of this function.

◆ BuildInto()

void BuildInto ( Diagram< T > * target )

Configures target to have the topology that has been described by the calls to Connect, ExportInput, and ExportOutput.

Exceptions

std::exception if the graph is not buildable.

Only Diagram subclasses should call this method. The target must not already be initialized.

◆ Cascade()

void Cascade	(	const System< T > &	src,
		const System< T > &	dest
	)

Cascades src and dest.

The sole input port on the dest system is connected to sole output port on the src system.

Exceptions

std::exception if the sole-port precondition is not met (i.e., if dest has no input ports, or dest has more than one input port, or src has no output ports, or src has more than one output port).

◆ Connect() [1/2]

void Connect	(	const OutputPort< T > &	src,
		const InputPort< T > &	dest
	)

Declares that input port dest is connected to output port src.

Note: The connection created between src and dest via a call to this method can be effectively overridden by any subsequent call to InputPort::FixValue(). That is, calling InputPort::FixValue() on an already connected input port causes the resultant FixedInputPortValue to override any other value present on that port.

◆ Connect() [2/2]

void Connect	(	const System< T > &	src,
		const System< T > &	dest
	)

Declares that sole input port on the dest system is connected to sole output port on the src system.

This function ignores deprecated ports, unless there is only one port in which case it will use the deprecated port.

Note: The connection created between src and dest via a call to this method can be effectively overridden by any subsequent call to InputPort::FixValue(). That is, calling InputPort::FixValue() on an already connected input port causes the resultant FixedInputPortValue to override any other value present on that port.

Exceptions

std::exception if the sole-port precondition is not met (i.e., if dest has no input ports, or dest has more than one input port, or src has no output ports, or src has more than one output port).

◆ ConnectInput() [1/2]

void ConnectInput	(	std::string_view	diagram_port_name,
		const InputPort< T > &	input
	)

Connects an input to the entire Diagram, indicated by diagram_port_name, to the given input port of a constituent system.

Precondition: The Diagram input indicated by diagram_port_name must have been previously built via ExportInput().

Postcondition: input is connected to the indicated Diagram input port.

◆ ConnectInput() [2/2]

void ConnectInput	(	InputPortIndex	diagram_port_index,
		const InputPort< T > &	input
	)

Connects an input to the entire Diagram, indicated by diagram_port_index, to the given input port of a constituent system.

Precondition: The Diagram input indicated by diagram_port_index must have been previously built via ExportInput().

Postcondition: input is connected to the indicated Diagram input port.

◆ connection_map()

const std::map<InputPortLocator, OutputPortLocator>& connection_map ( ) const

(Advanced) Returns a reference to the map of connections between Systems.

The reference becomes invalid upon any call to Build or BuildInto.

◆ ConnectToSame()

bool ConnectToSame	(	const InputPort< T > &	exemplar,
		const InputPort< T > &	dest
	)

Connects dest to the same source as exemplar is connected to.

If exemplar was connected to an output port, then dest is connected to that same output. Or, if exemplar was exported as an input of this diagram, then dest will be connected to that same diagram input. Or, if exemplar was neither connected or exported, then this function is a no-op.

Both exemplar and dest must be ports of constituent systems that have already been added to this diagram.

Returns: True iff any connection or was made; or false when a no-op.

◆ empty()

bool empty ( ) const

Returns whether any Systems have been added yet.

◆ ExportInput()

InputPortIndex ExportInput	(	const InputPort< T > &	input,
		std::variant< std::string, UseDefaultName >	name = `kUseDefaultName`
	)

Declares that the given input port of a constituent system is connected to a new input to the entire Diagram.

name is an optional name for the new input port; if it is unspecified, then a default name will be provided.

Precondition: If supplied at all, name must not be empty.; A port indicated by the resolution of name must not exist.

Postcondition: input is connected to the new exported input port.

Returns: The index of the exported input port of the entire diagram.

◆ ExportOutput()

OutputPortIndex ExportOutput	(	const OutputPort< T > &	output,
		std::variant< std::string, UseDefaultName >	name = `kUseDefaultName`
	)

Declares that the given output port of a constituent system is an output of the entire diagram.

name is an optional name for the output port; if it is unspecified, then a default name will be provided.

Precondition: If supplied at all, name must not be empty.

Returns: The index of the exported output port of the entire diagram.

◆ GetDowncastSubsystemByName()

const MySystem<T>& GetDowncastSubsystemByName ( std::string_view name ) const

Retrieves a const reference to the subsystem with name name returned by get_name(), downcast to the type provided as a template argument.

Template Parameters

MySystem is the downcast type, e.g., drake::systems::Adder

Exceptions

std::exception if a unique match cannot be found.

See also: GetMutableDowncastSubsystemByName(); GetSubsystemByName()

◆ GetMutableDowncastSubsystemByName()

MySystem<T>& GetMutableDowncastSubsystemByName ( std::string_view name )

Retrieves a mutable reference to the subsystem with name name returned by get_name(), downcast to the type provided as a template argument.

Template Parameters

MySystem is the downcast type, e.g., drake::systems::Adder

Exceptions

std::exception if a unique match cannot be found.

See also: GetDowncastSubsystemByName(); GetMutableSubsystemByName()

◆ GetMutableSubsystemByName()

System<T>& GetMutableSubsystemByName ( std::string_view name )

Retrieves a mutable reference to the subsystem with name name returned by get_name().

Exceptions

std::exception if a unique match cannot be found.

See also: System<T>::get_name(); GetSubsystemByName(); GetMutableDowncastSubsystemByName()

◆ GetMutableSystems()

std::vector<System<T>*> GetMutableSystems ( )

Returns the list of contained Systems.

See also: GetMutableSubsystemByName(); GetSystems()

◆ GetSubsystemByName()

const System<T>& GetSubsystemByName ( std::string_view name ) const

Retrieves a const reference to the subsystem with name name returned by get_name().

Exceptions

std::exception if a unique match cannot be found.

See also: System<T>::get_name(); GetMutableSubsystemByName(); GetDowncastSubsystemByName()

◆ GetSystems()

std::vector<const System<T>*> GetSystems ( ) const

Returns the list of contained Systems.

See also: GetSubsystemByName(); GetMutableSystems()

◆ HasSubsystemNamed()

bool HasSubsystemNamed ( std::string_view name ) const

Returns true iff this contains a subsystem with the given name.

See also: GetSubsystemByName()

◆ IsConnectedOrExported()

bool IsConnectedOrExported ( const InputPort< T > & port ) const

Returns true iff the given input port of a constituent system is either connected to another constituent system or exported as a diagram input.

◆ num_input_ports()

int num_input_ports ( ) const

Returns the current number of diagram input ports.

The count may change as more ports are exported.

◆ num_output_ports()

int num_output_ports ( ) const

Returns the current number of diagram output outputs.

The count may change as more ports are exported.

◆ operator=() [1/2]

DiagramBuilder& operator= ( const DiagramBuilder< T > & )

delete

◆ operator=() [2/2]

DiagramBuilder& operator= ( DiagramBuilder< T > && )

delete

◆ RemoveSystem()

void RemoveSystem ( const System< T > & system )

Removes the given system from this builder and disconnects any connections or exported ports associated with it.

Note that un-exporting this system's ports might have a ripple effect on other exported port index assignments. The relative order will remain intact, but any "holes" created by this removal will be filled in by decrementing the indices of all higher-numbered ports that remain.

Warning: Because a DiagramBuilder owns the objects it contains, the system will be deleted.

The documentation for this class was generated from the following files:

drake/systems/framework/diagram.h
drake/systems/framework/diagram_builder.h

Detailed Description

template<typename T> class drake::systems::DiagramBuilder< T >

Building large Diagrams

Public Types

Public Member Functions

Member Typedef Documentation

◆ InputPortLocator

◆ OutputPortLocator

Constructor & Destructor Documentation

◆ DiagramBuilder() [1/3]

◆ DiagramBuilder() [2/3]

◆ DiagramBuilder() [3/3]

◆ ~DiagramBuilder()

Member Function Documentation

◆ AddNamedSystem() [1/3]

◆ AddNamedSystem() [2/3]

◆ AddNamedSystem() [3/3]

◆ AddSystem() [1/3]

◆ AddSystem() [2/3]

◆ AddSystem() [3/3]

◆ already_built()

◆ Build()

◆ BuildInto()

◆ Cascade()

◆ Connect() [1/2]

◆ Connect() [2/2]

◆ ConnectInput() [1/2]

◆ ConnectInput() [2/2]

◆ connection_map()

◆ ConnectToSame()

◆ empty()

◆ ExportInput()

◆ ExportOutput()

◆ GetDowncastSubsystemByName()

◆ GetMutableDowncastSubsystemByName()

◆ GetMutableSubsystemByName()

◆ GetMutableSystems()

◆ GetSubsystemByName()

◆ GetSystems()

◆ HasSubsystemNamed()

◆ IsConnectedOrExported()

◆ num_input_ports()

◆ num_output_ports()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ RemoveSystem()

template<typename T>
class drake::systems::DiagramBuilder< T >