Detailed Description

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

An OutputPort belongs to a System and represents the properties of one of that System's output ports.

OutputPort objects are assigned OutputPortIndex values in the order they are declared; these are unique within a single System.

An output port can be considered a "window" into a System that permits controlled exposure of one of the values contained in that System's Context at run time. Input ports of other subsystems may be connected to an output port to construct system diagrams with carefully managed interdependencies.

The exposed value may be the result of an output computation, or it may simply expose some other value contained in the Context, such as the values of state variables. The Context handles caching of output port values and tracks dependencies to ensure that the values are valid with respect to their prerequisites. Leaf systems provide for the production of output port values, by computation or forwarding from other values within the associated leaf context. A diagram's output ports, on the other hand, are exported from output ports of its contained subsystems.

An output port's value is always stored as an AbstractValue, but we also provide special handling for output ports known to have numeric (vector) values. Vector-valued ports may specify a particular vector length, or may leave that to be determined at runtime.

OutputPort objects support three important operations:

Allocate() returns an object that can hold the port's value.
Calc() unconditionally computes the port's value.
Eval() updates a cached value if necessary.

Template Parameters

T	The scalar type, which must be one of the default scalars.

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

Public Member Functions
	~OutputPort () override=default

template<typename ValueType = VectorX<T>>
const ValueType &	Eval (const Context< T > &context) const
	Returns a reference to the up-to-date value of this output port contained in the given Context. More...

std::unique_ptr< AbstractValue >	Allocate () const
	Allocates a concrete object suitable for holding the value to be exposed by this output port, and returns that as an AbstractValue. More...

void	Calc (const Context< T > &context, AbstractValue *value) const
	Unconditionally computes the value of this output port with respect to the given context, into an already-allocated AbstractValue object whose concrete type must be exactly the same as the type returned by this port's allocator. More...

const System< T > &	get_system () const
	Returns a reference to the System that owns this output port. More...

const std::string &	get_name () const
	Get port name. More...

std::string	GetFullDescription () const
	Returns a verbose human-readable description of port. More...

OutputPortIndex	get_index () const
	Returns the index of this output port within the owning System. More...

PortDataType	get_data_type () const
	Returns the port data type. More...

int	size () const
	Returns the fixed size expected for a vector-valued port. More...

DependencyTicket	ticket () const
	(Advanced.) Returns the DependencyTicket for this port within the owning System. More...

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

OutputPort &	operator= (const OutputPort &)=delete

	OutputPort (OutputPort &&)=delete

OutputPort &	operator= (OutputPort &&)=delete

Public Member Functions inherited from OutputPortBase
	~OutputPortBase () override

OutputPortIndex	get_index () const
	Returns the index of this output port within the owning System. More...

const std::string &	get_name () const
	Get port name. More...

std::string	GetFullDescription () const
	Returns a verbose human-readable description of port. More...

PortDataType	get_data_type () const
	Returns the port data type. More...

int	size () const
	Returns the fixed size expected for a vector-valued port. More...

DependencyTicket	ticket () const
	(Advanced.) Returns the DependencyTicket for this port within the owning System. More...

	OutputPortBase (const OutputPortBase &)=delete

OutputPortBase &	operator= (const OutputPortBase &)=delete

	OutputPortBase (OutputPortBase &&)=delete

OutputPortBase &	operator= (OutputPortBase &&)=delete

Public Member Functions inherited from PortBase
virtual	~PortBase ()

const std::string &	get_name () const
	Get port name. More...

std::string	GetFullDescription () const
	Returns a verbose human-readable description of port. More...

PortDataType	get_data_type () const
	Returns the port data type. More...

int	size () const
	Returns the fixed size expected for a vector-valued port. More...

const std::optional< std::string > &	get_deprecation () const
	When this port is deprecated, returns non-null with a (possibly empty) deprecation message; when this port is not deprecated, returns null. More...

void	set_deprecation (std::optional< std::string > deprecation)
	Sets whether this port is deprecated (and if so, the message). More...

DependencyTicket	ticket () const
	(Advanced.) Returns the DependencyTicket for this port within the owning System. More...

	PortBase (const PortBase &)=delete

PortBase &	operator= (const PortBase &)=delete

	PortBase (PortBase &&)=delete

PortBase &	operator= (PortBase &&)=delete

Protected Member Functions
	OutputPort (const System< T > system, internal::SystemMessageInterface system_interface, internal::SystemId system_id, std::string name, OutputPortIndex index, DependencyTicket ticket, PortDataType data_type, int size)
	Provides derived classes the ability to set the base class members at construction. More...

virtual std::unique_ptr< AbstractValue >	DoAllocate () const =0
	A concrete OutputPort must provide a way to allocate a suitable object for holding the runtime value of this output port. More...

virtual void	DoCalc (const Context< T > &context, AbstractValue *value) const =0
	A concrete OutputPort must implement this method to calculate the value this output port should have, given the supplied Context. More...

virtual const AbstractValue &	DoEval (const Context< T > &context) const =0
	A concrete OutputPort must provide access to the current value of this output port stored within the given Context. More...

virtual void	ThrowIfInvalidPortValueType (const Context< T > &context, const AbstractValue &proposed_value) const =0
	Check that an AbstractValue provided to Calc() is suitable for this port. More...

Protected Member Functions inherited from OutputPortBase
	OutputPortBase (internal::SystemMessageInterface *owning_system, internal::SystemId owning_system_id, std::string name, OutputPortIndex index, DependencyTicket ticket, PortDataType data_type, int size)
	Provides derived classes the ability to set the base class members at construction. More...

virtual internal::OutputPortPrerequisite	DoGetPrerequisite () const =0
	Concrete output ports must implement this to return the prerequisite dependency ticket for this port, which may be in the current System or one of its immediate child subsystems. More...

Protected Member Functions inherited from PortBase
	PortBase (const char kind_string, internal::SystemMessageInterface owning_system, internal::SystemId owning_system_id, std::string name, int index, DependencyTicket ticket, PortDataType data_type, int size)
	Provides derived classes the ability to set the base class members at construction. More...

int	get_int_index () const
	Returns the index of this port within the owning System (i.e., an InputPortIndex or OutputPortIndex, but as a bare integer). More...

const internal::SystemMessageInterface &	get_system_interface () const
	Returns a reference to the system that owns this port. More...

internal::SystemMessageInterface &	get_mutable_system_interface ()
	Returns get_system_interface(), but without the const. More...

void	ValidateSystemId (internal::SystemId id) const
	(Internal use only) Checks whether the given id (nominally obtained from a Context passed to this port) was created for the system that owns this port. More...

void	ThrowValidateContextMismatch () const
	(Internal use only) Throws std::exception with a message that the sanity check(s) related to ValidateContext have failed. More...

template<typename ValueType >
const ValueType &	PortEvalCast (const AbstractValue &abstract) const
	Pull a value of a given type from an abstract value or issue a nice message if the type is not correct. More...

template<typename ValueType , typename T >
const ValueType &	PortEvalCast (const BasicVector< T > &basic) const
	Downcast a basic vector to a more specific subclass, or else issue a nice message if the type is not correct. More...

template<typename ValueType >
const ValueType &	ThrowBadCast (const AbstractValue &abstract) const
	Reports that the user provided a bad ValueType argument to Eval. More...

template<typename ValueType , typename T >
const ValueType &	ThrowBadCast (const BasicVector< T > &basic) const
	Reports that the user provided a bad ValueType argument to Eval. More...

void	ThrowBadCast (const std::string &value_typename, const std::string &eval_typename) const
	Reports that the user provided a bad ValueType argument to Eval. More...

Static Protected Member Functions
static void	ThrowIfInvalidPortValueType (const OutputPort< T > &port, const Context< T > &context, const AbstractValue &proposed_value)
	Static method allows DiagramOutputPort to call this recursively. More...

Constructor & Destructor Documentation

◆ OutputPort() [1/3]

OutputPort ( const OutputPort< T > & )

delete

◆ OutputPort() [2/3]

OutputPort ( OutputPort< T > && )

delete

◆ ~OutputPort()

~OutputPort ( )

overridedefault

◆ OutputPort() [3/3]

OutputPort	(	const System< T > *	system,
		internal::SystemMessageInterface *	system_interface,
		internal::SystemId	system_id,
		std::string	name,
		OutputPortIndex	index,
		DependencyTicket	ticket,
		PortDataType	data_type,
		int	size
	)

protected

Provides derived classes the ability to set the base class members at construction.

See OutputPortBase::OutputPortBase() for the meaning of these parameters.

Precondition: The name must not be empty.; The system parameter must be the same object as the system_interface parameter.

Member Function Documentation

◆ Allocate()

std::unique_ptr<AbstractValue> Allocate ( ) const

Allocates a concrete object suitable for holding the value to be exposed by this output port, and returns that as an AbstractValue.

The returned object will never be null. If Drake assertions are enabled (typically only in Debug builds), validates for a vector-valued port that the returned AbstractValue is actually a BasicVector-derived type and that it has an acceptable size.

Note: If this is a vector-valued port, the underlying type is Value<BasicVector<T>>; downcast to BasicVector<T> before downcasting to the specific BasicVector subclass.

◆ Calc()

void Calc	(	const Context< T > &	context,
		AbstractValue *	value
	)		const

Unconditionally computes the value of this output port with respect to the given context, into an already-allocated AbstractValue object whose concrete type must be exactly the same as the type returned by this port's allocator.

If Drake assertions are enabled (typically only in Debug builds), validates that the given value has exactly the same concrete type as is returned by the Allocate() method.

◆ DoAllocate()

virtual std::unique_ptr<AbstractValue> DoAllocate ( ) const

protectedpure virtual

A concrete OutputPort must provide a way to allocate a suitable object for holding the runtime value of this output port.

The particulars may depend on values and types of objects in the given Context.

Returns: A unique_ptr to the new value-holding object as an AbstractValue.

◆ DoCalc()

virtual void DoCalc	(	const Context< T > &	context,
		AbstractValue *	value
	)		const

protectedpure virtual

A concrete OutputPort must implement this method to calculate the value this output port should have, given the supplied Context.

The value may be determined by computation or by copying from a source value in the Context.

Parameters

context	A Context that has already been validated as compatible with the System whose output port this is.
value	A pointer that has already be validated as non-null and pointing to an object of the right type to hold a value of this output port.

◆ DoEval()

virtual const AbstractValue& DoEval ( const Context< T > & context ) const

protectedpure virtual

A concrete OutputPort must provide access to the current value of this output port stored within the given Context.

If the value is already up to date with respect to its prerequisites in context, no computation should be performed. Otherwise, the implementation should arrange for the value to be computed, typically but not necessarily by invoking DoCalc().

Parameters

context A Context that has already been validated as compatible with the System whose output port this is.

◆ Eval()

const ValueType& Eval ( const Context< T > & context ) const

Returns a reference to the up-to-date value of this output port contained in the given Context.

This is the preferred way to obtain an output port's value since it will not be recalculated once up to date.

If the value is not already up to date with respect to its prerequisites, it will recalculate an up-to-date value before the reference is returned. The recalculation may be arbitrarily expensive, but Eval() is constant time and very fast if the value is already up to date.

Template Parameters

ValueType The type of the const-reference returned by this method. When omitted, the return type is const VectorX<T>& (this is only valid when this is a vector-valued port). For abstract ports, the ValueType either can be the declared type of the port (e.g., lcmt_iiwa_status), or else in advanced use cases can be AbstractValue to get the type-erased value.

Returns: reference to the up-to-date value; if a ValueType is provided, the return type is const ValueType&; if a ValueType is omitted, the return type is const VectorX<T>&.

Exceptions

std::exception if the port is not connected.

Precondition: The output port is vector-valued (when no ValueType is provided).; The output port is of type ValueType (when ValueType is provided).

◆ get_data_type()

PortDataType get_data_type

Returns the port data type.

◆ get_index()

OutputPortIndex get_index

Returns the index of this output port within the owning System.

For a Diagram, this will be the index within the Diagram, not the index within the LeafSystem whose output port was forwarded.

◆ get_name()

const std::string& get_name

Get port name.

◆ get_system()

const System<T>& get_system ( ) const

Returns a reference to the System that owns this output port.

Note that for a diagram output port this will be the diagram, not the leaf system whose output port was forwarded.

◆ GetFullDescription()

std::string GetFullDescription

Returns a verbose human-readable description of port.

This is useful for error messages or debugging.

◆ operator=() [1/2]

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

delete

◆ operator=() [2/2]

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

delete

◆ size()

int size

Returns the fixed size expected for a vector-valued port.

Not meaningful for abstract-valued ports.

◆ ThrowIfInvalidPortValueType() [1/2]

virtual void ThrowIfInvalidPortValueType	(	const Context< T > &	context,
		const AbstractValue &	proposed_value
	)		const

protectedpure virtual

Check that an AbstractValue provided to Calc() is suitable for this port.

Derived classes should throw a helpful message if not (see LeafOutputPort for an example). It is OK for this to be an expensive check because we will only call it in Debug builds.

◆ ThrowIfInvalidPortValueType() [2/2]

static void ThrowIfInvalidPortValueType	(	const OutputPort< T > &	port,
		const Context< T > &	context,
		const AbstractValue &	proposed_value
	)

staticprotected

Static method allows DiagramOutputPort to call this recursively.

◆ ticket()

DependencyTicket ticket

(Advanced.) Returns the DependencyTicket for this port within the owning System.

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

drake/systems/framework/output_port.h

Detailed Description

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

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Constructor & Destructor Documentation

◆ OutputPort() [1/3]

◆ OutputPort() [2/3]

◆ ~OutputPort()

◆ OutputPort() [3/3]

Member Function Documentation

◆ Allocate()

◆ Calc()

◆ DoAllocate()

◆ DoCalc()

◆ DoEval()

◆ Eval()

◆ get_data_type()

◆ get_index()

◆ get_name()

◆ get_system()

◆ GetFullDescription()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ size()

◆ ThrowIfInvalidPortValueType() [1/2]

◆ ThrowIfInvalidPortValueType() [2/2]

◆ ticket()

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