Drake
Drake C++ Documentation
Default Scalars

Detailed Description

Similar to the Eigen library, many classes in Drake use a template argument to specify the numeric scalar type to use for computation.

We typically name that template argument <T>. For an example, see the class drake::math::RigidTransform.

Most scalar-templated classes in Drake only support a small, fixed set of scalar types:

When Drake documentation refers to "default scalars", it means all three of the types above.

Alternatively, reference to "default nonsymbolic scalars" means all except drake::symbolic::Expression.

For code within Drake, we offer Doxygen custom commands to document the <T> template parameter in the conventional cases:

All three commands assume that the template parameter is named T. When possible, prefer to use these commands instead of writing out a @tparam line manually.

Class template instantiation macros

These macros either declare or define class template instantiations for Drake's supported scalar types (see Default Scalars), either "default scalars" or "default nonsymbolic scalars".

Use the DECLARE macros only in .h files; use the DEFINE macros only in .cc files.

Parameters
SomeTypethe template typename to instantiate, including the leading class or struct keyword, but excluding the template argument for the scalar type.

Example my_system.h:

namespace sample {
template <typename T>
class MySystem final : public drake::systems::LeafSystem<T> {
...
};
} // namespace sample
class ::sample::MySystem)

Example my_system.cc:

#include "my_system.h"
class ::sample::MySystem)

See also System Scalar Conversion.

#define DRAKE_DEFINE_CLASS_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_SCALARS(SomeType)
 Defines template instantiations for Drake's default scalars. More...
 
#define DRAKE_DEFINE_CLASS_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_NONSYMBOLIC_SCALARS(SomeType)
 Defines template instantiations for Drake's default nonsymbolic scalars. More...
 
#define DRAKE_DECLARE_CLASS_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_SCALARS( SomeType)
 Declares that template instantiations exist for Drake's default scalars. More...
 
#define DRAKE_DECLARE_CLASS_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_NONSYMBOLIC_SCALARS(SomeType)
 Declares that template instantiations exist for Drake's default nonsymbolic scalars. More...
 

Function template instantiation macros

These macros define template function instantiations for Drake's supported scalar types (see Default Scalars), either "default scalars" or "default nonsymbolic scalars".

Use the DEFINE macros only in .cc files.

Parameters
FunctionPointersTuplea parenthesized, comma-separated list of functions to instantiate (provided as function pointers), including the template argument(s) for the scalar type. The template arguments T and U will be provided by the macro; the function will be instantiated for all combinations of T and U over the default scalars.

Example example.h:

namespace sample {
template <typename T>
double Func1(const T&);
template <typename T, typename U>
double Func2(const T&, const U&);
template <typename T>
class SomeClass {
...
template <typename U>
SomeClass cast() const;
...
};
} // namespace sample

Example example.cc:

#include "example.h"
namespace sample {
template <typename T>
double Func1(const T&) {
...
}
template <typename T, typename U>
double Func2(const T&, const U&) {
...
}
template <typename T>
template <typename U>
SomeClass<T>::SomeClass::cast() const {
...
};
// N.B. Place the macro invocation inside the functions' namespace.
&Func1<T>,
&Func2<T, U>,
&SomeClass<T>::template cast<U>
))
} // namespace sample
Note
In the case of an overloaded function, the &FunctionName<T> syntax is ambiguous. To resolve the ambiguity, you will need a static_cast.
#define DRAKE_DEFINE_FUNCTION_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_SCALARS(FunctionPointersTuple)
 Defines template instantiations for Drake's default scalars. More...
 
#define DRAKE_DEFINE_FUNCTION_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_NONSYMBOLIC_SCALARS(FunctionPointersTuple)
 Defines template instantiations for Drake's default nonsymbolic scalars. More...
 

Macro Definition Documentation

◆ DRAKE_DECLARE_CLASS_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_NONSYMBOLIC_SCALARS

#define DRAKE_DECLARE_CLASS_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_NONSYMBOLIC_SCALARS (   SomeType)
Value:
extern template SomeType<double>; \
extern template SomeType<::drake::AutoDiffXd>;

Declares that template instantiations exist for Drake's default nonsymbolic scalars.

This should only be used in .h files, never in .cc files.

◆ DRAKE_DECLARE_CLASS_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_SCALARS

#define DRAKE_DECLARE_CLASS_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_SCALARS (   SomeType)
Value:
extern template SomeType<double>; \
extern template SomeType<::drake::AutoDiffXd>; \
extern template SomeType<::drake::symbolic::Expression>;

Declares that template instantiations exist for Drake's default scalars.

This should only be used in .h files, never in .cc files.

◆ DRAKE_DEFINE_CLASS_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_NONSYMBOLIC_SCALARS

#define DRAKE_DEFINE_CLASS_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_NONSYMBOLIC_SCALARS (   SomeType)
Value:
template SomeType<double>; \
template SomeType<::drake::AutoDiffXd>;

Defines template instantiations for Drake's default nonsymbolic scalars.

This should only be used in .cc files, never in .h files.

◆ DRAKE_DEFINE_CLASS_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_SCALARS

#define DRAKE_DEFINE_CLASS_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_SCALARS (   SomeType)
Value:
template SomeType<double>; \
template SomeType<::drake::AutoDiffXd>; \
template SomeType<::drake::symbolic::Expression>;

Defines template instantiations for Drake's default scalars.

This should only be used in .cc files, never in .h files.

◆ DRAKE_DEFINE_FUNCTION_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_NONSYMBOLIC_SCALARS

#define DRAKE_DEFINE_FUNCTION_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_NONSYMBOLIC_SCALARS (   FunctionPointersTuple)
Value:
template<typename T, typename U> \
constexpr auto Make_Function_Pointers_Nonsym() { \
return std::make_tuple FunctionPointersTuple ; \
} \
template<typename T, typename... Us> \
constexpr auto Make_Function_Pointers_Nonsym_Pack2() { \
return std::tuple_cat(Make_Function_Pointers_Nonsym<T, Us>()...); \
} \
template<typename... Ts> \
constexpr auto Make_Function_Pointers_Nonsym_Pack1() { \
return std::tuple_cat(Make_Function_Pointers_Nonsym_Pack2<Ts, Ts...>()...); \
} \
static constexpr auto Function_Templates_Nonsym __attribute__((used)) = \
Make_Function_Pointers_Nonsym_Pack1< \
double, \
Eigen::AutoDiffScalar< Eigen::VectorXd > AutoDiffXd
An autodiff variable with a dynamic number of partials.
Definition: eigen_autodiff_types.h:22

Defines template instantiations for Drake's default nonsymbolic scalars.

This should only be used in .cc files, never in .h files.

◆ DRAKE_DEFINE_FUNCTION_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_SCALARS

#define DRAKE_DEFINE_FUNCTION_TEMPLATE_INSTANTIATIONS_ON_DEFAULT_SCALARS (   FunctionPointersTuple)
Value:
template<typename T, typename U> \
constexpr auto Make_Function_Pointers() { \
return std::make_tuple FunctionPointersTuple ; \
} \
template<typename T, typename... Us> \
constexpr auto Make_Function_Pointers_Pack2() { \
return std::tuple_cat(Make_Function_Pointers<T, Us>()...); \
} \
template<typename... Ts> \
constexpr auto Make_Function_Pointers_Pack1() { \
return std::tuple_cat(Make_Function_Pointers_Pack2<Ts, Ts...>()...); \
} \
static constexpr auto Function_Femplates __attribute__((used)) = \
Make_Function_Pointers_Pack1< \
double, \
Eigen::AutoDiffScalar< Eigen::VectorXd > AutoDiffXd
An autodiff variable with a dynamic number of partials.
Definition: eigen_autodiff_types.h:22
Represents a symbolic form of an expression.
Definition: expression.h:161

Defines template instantiations for Drake's default scalars.

This should only be used in .cc files, never in .h files.