Detailed Description

Helper class to convert a System into a System<T>, intended for internal use by the System framework, not directly by users.

For user-facing documentation see System Scalar Conversion.

Because it is not templated on a System subclass, this class can be used by LeafSystem without any direct knowledge of the subtypes being converted. In other words, it enables a runtime flavor of the CRTP.

Throughout this class, the following template naming convention applies:

Template Parameters

S	is the System subclass that this object will convert from and to.
U	the source scalar type (to convert from), which must be one of the default scalars.
T	the resulting scalar type (to convert into), which must be one of the default scalars.

Note: Conversions where T and U types are the same are not supported. Template functions such as IsConvertible<T, U>() are still callable, but will always return false, null, etc.

#include <src/maliput/drake/systems/framework/system_scalar_converter.h>

Public Types
using	supported = std::function< std::unique_ptr< System< T > >(const System< U > &)>

Public Member Functions
	DRAKE_DEFAULT_COPY_AND_MOVE_AND_ASSIGN (SystemScalarConverter)

	SystemScalarConverter ()
	(Advanced) Creates a converter that supports no conversions. More...

template<template< typename > class S>
	SystemScalarConverter (SystemTypeTag< S >)
	Creates a converter that uses S's scalar-converting copy constructor to perform system scalar conversion. More...

enum	DRAKE_DEPRECATED ("2021-11-01", "Use MakeWithoutSubtypeChecking instead of kDisabled.") GuaranteedSubtypePreservation

template<template< typename > class S>
	SystemScalarConverter (SystemTypeTag< S >, GuaranteedSubtypePreservation sub)

bool	empty () const
	Returns true iff no conversions are supported. More...

template<typename T , typename U >
void	Add (const ConverterFunction< T, U > &)

template<template< typename > class S, typename T , typename U >
void	AddIfSupported ()

void	RemoveUnlessAlsoSupportedBy (const SystemScalarConverter &other)
	Removes from this converter all pairs where `other.IsConvertible<T, U>` is false. More...

template<typename T , typename U >
void	Remove ()
	Removes from this converter the ability to convert from System to System<T>. More...

template<typename T , typename U >
bool	IsConvertible () const
	Returns true iff this object can convert a System into a System<T>, i.e., whether Convert() will return non-null. More...

template<typename T , typename U >
std::unique_ptr< System< T > >	Convert (const System< U > &other) const
	Converts a System into a System<T>. More...

Static Public Member Functions
template<template< typename > class S>
static SystemScalarConverter	MakeWithoutSubtypeChecking ()
	(Advanced) Creates a converter similar to the single-argument constructor, with the built-in checks for guaranteed subtype preservation of the System turned off. More...

Member Typedef Documentation

◆ supported

using supported = std::function<std::unique_ptr<System<T> >(const System<U>&)>

Constructor & Destructor Documentation

◆ SystemScalarConverter() [1/3]

SystemScalarConverter ( )

default

(Advanced) Creates a converter that supports no conversions.

The single- argument constructor below is the overload intended for users.

◆ SystemScalarConverter() [2/3]

SystemScalarConverter ( SystemTypeTag< S > )

Creates a converter that uses S's scalar-converting copy constructor to perform system scalar conversion.

That constructor takes the form of:

template <typename T>
class FooSystem final : public LeafSystem<T> {
  template <typename U>
  explicit FooSystem(const FooSystem<U>& other);
};

By default, the converter supports conversions to and from all of the default scalars, but systems may specialize the scalar_conversion::Traits to disable support for some or all of these conversions. Conversions where T and U types are the same are not supported.

This an implicit conversion constructor (not marked explicit), in order to make calling code substantially more readable, with relatively little risk of an unwanted accidental conversion happening.

See System Scalar Conversion for additional overview documentation.

◆ SystemScalarConverter() [3/3]

SystemScalarConverter	(	SystemTypeTag< S >	,
		GuaranteedSubtypePreservation	sub
	)

Member Function Documentation

◆ Add()

void Add ( const ConverterFunction< T, U > & func )

◆ AddIfSupported()

void AddIfSupported ( )

◆ Convert()

std::unique_ptr< System< T > > Convert ( const System< U > & other ) const

Converts a System into a System<T>.

This is the API that LeafSystem uses to provide a default implementation of DoToAutoDiffXd, etc.

◆ DRAKE_DEFAULT_COPY_AND_MOVE_AND_ASSIGN()

DRAKE_DEFAULT_COPY_AND_MOVE_AND_ASSIGN ( SystemScalarConverter )

◆ DRAKE_DEPRECATED()

enum DRAKE_DEPRECATED	(	"2021-11-01"	,
		"Use MakeWithoutSubtypeChecking instead of kDisabled."
	)

strong

The argument to Convert must be of the exact type S that was used to populate the SystemScalarConverter.

The argument to Convert need not be the exact type S that was used to populate the SystemScalarConverter – it can be either exactly that S, or a subtype of that S. This permits subtype information to be lost across conversion.

◆ empty()

bool empty ( ) const

Returns true iff no conversions are supported.

(In other words, whether this is a default-constructed object.)

◆ IsConvertible()

bool IsConvertible

Returns true iff this object can convert a System into a System<T>, i.e., whether Convert() will return non-null.

◆ MakeWithoutSubtypeChecking()

static SystemScalarConverter MakeWithoutSubtypeChecking ( )

static

(Advanced) Creates a converter similar to the single-argument constructor, with the built-in checks for guaranteed subtype preservation of the System turned off.

In general, subtype preservation is an important invariant of scalar conversion, so be extremely cautious about disabling it.

◆ Remove()

void Remove

Removes from this converter the ability to convert from System to System<T>.

◆ RemoveUnlessAlsoSupportedBy()

void RemoveUnlessAlsoSupportedBy ( const SystemScalarConverter & other )

Removes from this converter all pairs where other.IsConvertible<T, U> is false.

The subtype S need not be the same between this and other.

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