Drake
SystemScalarConverter Class Reference

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
Sis the System subclass that this object will convert from and to.
Uthe source scalar type (to convert from), which must be one of the default scalars.
Tthe 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 <drake/systems/framework/system_scalar_converter.h>

Public Types

enum  GuaranteedSubtypePreservation { kEnabled, kDisabled }
 
template<typename T , typename U >
using ConverterFunction = std::function< std::unique_ptr< System< T > >(const System< U > &)>
 

Public Member Functions

 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...
 
template<template< typename > class S>
 SystemScalarConverter (SystemTypeTag< S >, GuaranteedSubtypePreservation sub)
 (Deprecated.) More...
 
bool empty () const
 Returns true iff no conversions are supported. More...
 
template<typename T , typename U >
void Add (const ConverterFunction< T, U > &)
 (Deprecated.) More...
 
template<template< typename > class S, typename T , typename U >
void AddIfSupported ()
 (Deprecated.) More...
 
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...
 
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
 SystemScalarConverter (const SystemScalarConverter &)=default
 
SystemScalarConverteroperator= (const SystemScalarConverter &)=default
 
 SystemScalarConverter (SystemScalarConverter &&)=default
 
SystemScalarConverteroperator= (SystemScalarConverter &&)=default
 

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

◆ ConverterFunction

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

Member Enumeration Documentation

◆ GuaranteedSubtypePreservation

Enumerator
kEnabled 

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

kDisabled 

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.

Constructor & Destructor Documentation

◆ SystemScalarConverter() [1/5]

◆ SystemScalarConverter() [2/5]

◆ SystemScalarConverter() [3/5]

(Advanced) Creates a converter that supports no conversions.

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

◆ SystemScalarConverter() [4/5]

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() [5/5]

(Deprecated.)

Deprecated:
"Use MakeWithoutSubtypeChecking instead of kDisabled."
This will be removed from Drake on or after "2021-11-01" .

Member Function Documentation

◆ Add()

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

(Deprecated.)

Deprecated:
"Only scalar-converting copy constructors are supported."
This will be removed from Drake on or after "2021-10-01" .

◆ AddIfSupported()

void AddIfSupported ( )

(Deprecated.)

Deprecated:
"User-defined scalar types cannot be added."
This will be removed from Drake on or after "2021-10-01" .

◆ 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.

◆ empty()

bool empty ( ) const

Returns true iff no conversions are supported.

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

◆ IsConvertible()

bool IsConvertible ( ) const

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.

◆ operator=() [1/2]

SystemScalarConverter& operator= ( SystemScalarConverter &&  )
default

◆ operator=() [2/2]

SystemScalarConverter& operator= ( const SystemScalarConverter )
default

◆ 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 file: