doc/TopicScalarTypes.dox

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). A matrix-matrix product of two \c half or two \c bfloat16 matrices
    that runs on the general matrix-matrix kernel sums in \c float over the whole depth and rounds
    each result coefficient once; products small enough for the coefficient-based path, products
    with a vector operand or result, and triangular and self-adjoint products still round in the
    operand type. On hardware with native \c half arithmetic, such as Armv8.2-A with FP16, this
    makes a \c half product about twice as slow as the native \c half kernel it replaces. To keep a
    \c float result, write <tt>A.cast<float>() * B.cast<float>()</tt>: the kernel converts the
    operands while it reads them, without first copying them to \c float, except with
    \c EIGEN_USE_BLAS and on SME, where the casts are materialized.

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 contrib module <a href="contrib/group__MPRealSupport__Module.html">MPRealSupport</a>.

*/

}