Drake
Drake C++ Documentation
DiagramBuilder< T > Class Template Reference

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
 
DiagramBuilderoperator= (const DiagramBuilder &)=delete
 
 DiagramBuilder (DiagramBuilder &&)=delete
 
DiagramBuilderoperator= (DiagramBuilder &&)=delete
 

Member Typedef Documentation

◆ InputPortLocator

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

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

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
SThe 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
SThe 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
SA 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
SThe 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
SThe 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
SA 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::exceptionif 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::exceptionif 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::exceptionif 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::exceptionif 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
MySystemis the downcast type, e.g., drake::systems::Adder
Exceptions
std::exceptionif 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
MySystemis the downcast type, e.g., drake::systems::Adder
Exceptions
std::exceptionif 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::exceptionif 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::exceptionif 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: