Rasmus Munk LarsenandRasmus Munk Larsen
11a02f2908
libeigen/eigen!2839 Co-authored-by: Rasmus Munk Larsen <rmlarsen@gmail.com>
69 lines
3.8 KiB
Plaintext
69 lines
3.8 KiB
Plaintext
namespace Eigen {
|
|
|
|
/** \page TopicScalarTypes Scalar types
|
|
|
|
The \c Scalar template parameter of Matrix, Array, SparseMatrix, and the other %Eigen containers
|
|
determines the type of the coefficients. This page lists the scalar types that work out of the box
|
|
and points to the mechanism for adding new ones.
|
|
|
|
\eigenAutoToc
|
|
|
|
\section TopicScalarTypesBuiltin Supported scalar types
|
|
|
|
The following types are supported without any additional work:
|
|
|
|
- the standard floating-point types \c float, \c double, and <tt>long double</tt>;
|
|
- <tt>std::complex</tt> of any of those, most commonly <tt>std::complex<float></tt> and
|
|
<tt>std::complex<double></tt>;
|
|
- all standard integer types, signed and unsigned (e.g. \c int, <tt>unsigned int</tt>,
|
|
\c short, <tt>std::int64_t</tt>, ...);
|
|
- \c bool, with the arithmetic operators interpreted in the Boolean semiring
|
|
(see \ref TopicPitfalls_matrix_bool);
|
|
- the reduced-precision floating-point types \c Eigen::half (IEEE binary16) and
|
|
\c Eigen::bfloat16, which %Eigen provides itself in Eigen/Core.
|
|
|
|
A few practical notes:
|
|
|
|
- <b>Convenience typedefs</b> such as \c MatrixXd or \c Vector4i exist for \c float, \c double,
|
|
\c int, and the two standard complex types; for every other scalar type simply spell out
|
|
<tt>Matrix<Scalar, Rows, Cols></tt> or define your own typedef.
|
|
- <b>Mixing scalar types</b> in one expression is not done implicitly: adding a \c float matrix
|
|
to a \c double matrix is a compile-time error. Convert explicitly with
|
|
<tt>.cast<NewScalar>()</tt>. The exceptions are the documented
|
|
real-times-complex combinations, e.g. multiplying a real matrix by a complex scalar.
|
|
- <b>Integer scalars</b> use exact arithmetic, with the usual C++ caveats: overflow wraps or is
|
|
undefined depending on signedness, and division truncates. Decompositions and other
|
|
algorithms that require field operations are meant for floating-point (or rational custom)
|
|
scalars, not for integer types.
|
|
- <b><tt>long double</tt></b> follows the platform's definition (80-bit extended precision on
|
|
x86 Linux, 128-bit on some platforms, plain \c double on MSVC). It is never vectorized.
|
|
- <b>\c Eigen::half and \c Eigen::bfloat16</b> are primarily storage and interchange formats:
|
|
on hardware without native arithmetic, operations are emulated by converting to \c float and
|
|
back. Both are vectorized on instruction sets with hardware support (see
|
|
\ref TopicVectorization).
|
|
|
|
The scalar types with vectorized kernels for a given instruction set are listed on the
|
|
\ref TopicVectorization "vectorization page"; every supported scalar type also works through the
|
|
scalar code paths.
|
|
|
|
\section TopicScalarTypesTraits NumTraits
|
|
|
|
The properties of a scalar type are centralized in the NumTraits class template: whether the type
|
|
is integer, signed, or complex, the corresponding real type (e.g. \c float for
|
|
<tt>std::complex<float></tt>), machine epsilon, and the tolerances used by the fuzzy comparison
|
|
functions such as isApprox(). Generic code should query NumTraits and use the math functions from
|
|
the \c Eigen::numext namespace (numext::sqrt, numext::abs2, ...) rather than hard-coding
|
|
properties of \c float or \c double, so that it keeps working for every supported scalar type.
|
|
|
|
\section TopicScalarTypesCustom Custom scalar types
|
|
|
|
Any user-defined type with the usual arithmetic operators can be used as a scalar type after
|
|
specializing NumTraits for it and providing the math functions that make sense for the type. The
|
|
full recipe, with complete examples (an automatic-differentiation type and a GMP rational type),
|
|
is given in \ref TopicCustomizing_CustomScalar. Ready-made support for the MPFR arbitrary-precision
|
|
type is available in the unsupported module <a href="unsupported/group__MPRealSupport__Module.html">MPRealSupport</a>.
|
|
|
|
*/
|
|
|
|
}
|