Kokkos Core Kernels Package
Version of the Day
|
Traits class for arithmetic on type T. More...
#include <Kokkos_ArithTraits.hpp>
Public Types | |
typedef T | val_type |
A type that acts like T and works with Kokkos. More... | |
typedef T | mag_type |
The type of the magnitude (absolute value) of T. More... | |
Static Public Member Functions | |
static KOKKOS_FORCEINLINE_FUNCTION bool | isInf (const T &x) |
Whether x is Inf. More... | |
static KOKKOS_FORCEINLINE_FUNCTION bool | isNan (const T &x) |
Whether x is NaN (not a number). More... | |
static KOKKOS_FORCEINLINE_FUNCTION mag_type | abs (const T &x) |
The absolute value (magnitude) of x. More... | |
static KOKKOS_FORCEINLINE_FUNCTION T | zero () |
The zero value of T; the arithmetic identity. More... | |
static KOKKOS_FORCEINLINE_FUNCTION T | one () |
The one value of T; the multiplicative identity. More... | |
static KOKKOS_FORCEINLINE_FUNCTION T | min () |
The minimum possible value of T. More... | |
static KOKKOS_FORCEINLINE_FUNCTION T | max () |
The maximum possible value of T. More... | |
static KOKKOS_FORCEINLINE_FUNCTION mag_type | real (const T &x) |
The real part of x. More... | |
static KOKKOS_FORCEINLINE_FUNCTION mag_type | imag (const T &) |
The imaginary part of x. More... | |
static KOKKOS_FORCEINLINE_FUNCTION T | conj (const T &) |
The complex conjugate of x. More... | |
static KOKKOS_FORCEINLINE_FUNCTION T | pow (const T &x, const T &y) |
x raised to the power y. More... | |
static KOKKOS_FORCEINLINE_FUNCTION T | sqrt (const T &x) |
The square root of x. More... | |
static KOKKOS_FORCEINLINE_FUNCTION T | log (const T &x) |
The natural (base e) logarithm of x. More... | |
static KOKKOS_FORCEINLINE_FUNCTION T | log10 (const T &x) |
The base ten logarithm of the input. More... | |
static KOKKOS_FORCEINLINE_FUNCTION T | nan () |
Return a silent NaN, if appropriate for T. More... | |
static KOKKOS_FORCEINLINE_FUNCTION mag_type | epsilon () |
Machine epsilon. More... | |
Static Public Attributes | |
static const bool | is_specialized = false |
Whether ArithTraits has a specialization for T. More... | |
static const bool | is_signed = false |
Whether T is a signed type (has negative values). More... | |
static const bool | is_integer = false |
Whether T is an integer type. More... | |
static const bool | is_exact = false |
Whether T "uses exact representations.". More... | |
static const bool | is_complex = false |
Whether T is a complex-valued type. More... | |
Traits defined for backwards compatibility with Teuchos::ScalarTraits | |
All of the typedefs, | |
typedef T | magnitudeType |
Same as mag_type; the type of the absolute value (magnitude) of T. More... | |
typedef T | halfPrecision |
The type with "half the precision" of T. More... | |
typedef T | doublePrecision |
The type with "twice the the precision" of T. More... | |
static const bool | isComplex = false |
static const bool | isOrdinal = false |
static const bool | isComparable = false |
static const bool | hasMachineParameters = false |
True if this type T has floating-point parameters. More... | |
static KOKKOS_FORCEINLINE_FUNCTION mag_type | eps () |
Return relative machine precision. More... | |
static KOKKOS_FORCEINLINE_FUNCTION mag_type | sfmin () |
Return safe minimum (sfmin), such that 1/sfmin does not overflow. More... | |
static KOKKOS_FORCEINLINE_FUNCTION int | base () |
Return the base of the scalar type T. More... | |
static KOKKOS_FORCEINLINE_FUNCTION mag_type | prec () |
Return eps*base . More... | |
static KOKKOS_FORCEINLINE_FUNCTION int | t () |
Returns the number of (base) digits in the significand. More... | |
static KOKKOS_FORCEINLINE_FUNCTION mag_type | rnd () |
1.0 when rounding occurs in addition, else 0.0. More... | |
static KOKKOS_FORCEINLINE_FUNCTION int | emin () |
Returns the minimum exponent before (gradual) underflow. More... | |
static KOKKOS_FORCEINLINE_FUNCTION mag_type | rmin () |
Returns the underflow threshold: base^(emin-1) More... | |
static KOKKOS_FORCEINLINE_FUNCTION int | emax () |
Returns the largest exponent before overflow. More... | |
static KOKKOS_FORCEINLINE_FUNCTION mag_type | rmax () |
Overflow theshold: (base^emax)*(1-eps) More... | |
static KOKKOS_FORCEINLINE_FUNCTION magnitudeType | magnitude (const T &x) |
Same as abs(); return the magnitude of x. More... | |
static KOKKOS_FORCEINLINE_FUNCTION T | conjugate (const T &x) |
Same as conj(); return the complex conjugate of x. More... | |
static KOKKOS_FORCEINLINE_FUNCTION bool | isnaninf (const T &x) |
Whether x is (silent) NaN or Inf. More... | |
static std::string | name () |
The string name of T. More... | |
static KOKKOS_FORCEINLINE_FUNCTION T | squareroot (const T &x) |
Same as sqrt(x); the square root of x. More... | |
Traits class for arithmetic on type T.
T | "Scalar" type of interest |
This is a traits class for the "arithmetic" type T. "Arithmetic types" include built-in signed and unsigned integer types, floating-point types, complex-valued types, and anything else that looks like these. This class is useful for implementing numerical algorithms that are generic on the data type. You may also use this class to query attributes of T, like whether it is signed or complex, or its precision.
We really did not want to implement this class or expose it to users. It would be much better to use existing traits classes like std::numeric_limits. We decided to implement and expose this class for the following reasons:
All class methods must be suitable for parallel kernels, if the type T itself is suitable for parallel kernels. In particular, specializations for types T that make sense to use on a CUDA device must mark all class methods as device (and host) functions, using the KOKKOS_FORCEINLINE_FUNCTION macro. All class methods must be callable both inside and outside a parallel kernel (for CUDA, this means they must be marked as both device and host functions).
Whenever possible, class methods in ArithTraits use the same names as their equivalents in the C++ Standard Library. If this was not possible, for example with isInf and isNan, we explain why in their documentation.
This class has redundant typedefs and methods in order to maintain backwards compatibility with Teuchos::ScalarTraits, while preferring forwards (partial) compatibility with std::numeric_limits. Users should prefer typedefs, bool
constants, and class methods compatible with std::numeric_limits, to those from Teuchos::ScalarTraits. The latter may go away at any time. Furthermore, Teuchos::ScalarTraits contains methods that do not make sense for use as parallel device functions, in particular those relating to pseudorandom number generation that refer to hidden state, so we will never include all class methods from Teuchos::ScalarTraits in ArithTraits.
CUDA does not support long double or std::complex<T> in device functions. ArithTraits does have specializations for these types, but the class methods therein are not marked as device functions.
C99 and C++11 include typedefs int${N}_t and uint${N}_t, where N is the number of bits in the integer. These typedefs are useful because they make the length of the type explicit. Users are welcome to use these types as the template parameter of ArithTraits.
We chose not to use these types when defining full specializations of ArithTraits. This is because the C99 integer types are typedefs, not types in themselves. This makes it impossible to avoid duplicate or missing full specializations of ArithTraits. For example, on my Mac, for CUDA 5.5, gcc 4.2.1, and Clang 3.2, int64_t
is a typedef of long long
, but long long
and long
are separate types, even though they have the same length (64 bits). In contrast, on Windows (even Win64), long
is a 32-bit type (but a distinct type from int
), and long long
is a 64-bit type. Thus, if we define full specializations of ArithTraits using only the C99 integer types, we will be missing a specialization for long
on at least one platform.
Rather than trouble ourselves with trying to figure this out for each platform, we decided to provide specializations only for the integer types in the C89 and C++03 language standards. This includes signed and unsigned versions of char
, short
, int
, and long
. We also include long long
if your platform supports it. We may thus have left out some C99 integer type, but this is only possible if the C89 / C++03 integer types do not have complete coverage of all powers of two bits from 8 up to the longest provided length (e.g., 64 on a 64-bit system). On all platforms I have encountered, char
has 8 bits and short
has 16 bits, so I am not worried about missing specializations for int16_t
or uint16_t
. If you should find that either of these specializations are missing, though, please let us know.
Note that char
, signed char
, and unsigned char
are distinct types, whether char
is signed or unsigned. (The language standards do not specify whether char
is signed or unsigned.) That is, char
is not a typedef of signed char
or unsigned char
. This is why we provide full specializations of ArithTraits for each of these types. Interestingly enough, on my system, char
and int8_t
are different types, but signed char
and int8_t
are the same.
This section contains notes to developers who which to add a partial specialization of this class for a new type T. If you decide to write a default templated implementation, it must not declare any methods as device functions. This ensures correct behavior for arbitrary T, but does require specializations for common types like T = float and double, as well as for other types T that make sense to use on a CUDA device.
Definition at line 328 of file Kokkos_ArithTraits.hpp.
typedef T Kokkos::Details::ArithTraits< T >::val_type |
A type that acts like T and works with Kokkos.
This is usually just an alias for T. However, some types T do not work well with Kokkos. In that case, we use a mostly equivalent type here. For example, ArithTraits<std::complex<R> >::val_type is Kokkos::complex<R>.
Definition at line 336 of file Kokkos_ArithTraits.hpp.
typedef T Kokkos::Details::ArithTraits< T >::mag_type |
The type of the magnitude (absolute value) of T.
We define this as the type returned by abs() in this class. If T is real (not complex), then val_type
and mag_type
are usually the same. If T is std::complex<R>
for some R, then R and mag_type
are usually the same.
Definition at line 343 of file Kokkos_ArithTraits.hpp.
typedef T Kokkos::Details::ArithTraits< T >::magnitudeType |
Same as mag_type; the type of the absolute value (magnitude) of T.
Definition at line 481 of file Kokkos_ArithTraits.hpp.
typedef T Kokkos::Details::ArithTraits< T >::halfPrecision |
The type with "half the precision" of T.
This typedef only makes sense if T is a floating-point type.
Definition at line 486 of file Kokkos_ArithTraits.hpp.
typedef T Kokkos::Details::ArithTraits< T >::doublePrecision |
The type with "twice the the precision" of T.
This typedef only makes sense if T is a floating-point type.
Definition at line 491 of file Kokkos_ArithTraits.hpp.
|
static |
Whether x is Inf.
This can only be true for floating-point types T that support Inf. If T is a complex type, we say that a T instance x is Inf if and only if isinf(real(x)) || isinf(imag(x))
.
Unfortunately we can't call this "isinf" (the equivalent C99 function), because CUDA appears to implement that function using a macro, rather than using a function (as C++11 requires).
|
static |
Whether x is NaN (not a number).
This can only be true for floating-point types T that support NaN. If T is a complex type, we say that a T instance x is NaN if and only if isNan(real(x)) || isNan(imag(x))
.
Unfortunately we can't call this "isnan" (the equivalent C99 function), because CUDA appears to implement that function using a macro, rather than using a function (as C++11 requires).
|
static |
The absolute value (magnitude) of x.
|
static |
The zero value of T; the arithmetic identity.
|
static |
The one value of T; the multiplicative identity.
|
static |
The minimum possible value of T.
If T is a real floating-point type, then this is the minimum positive value, as with std::numeric_limits<T>::min().
|
static |
The maximum possible value of T.
|
static |
The real part of x.
If is_complex
is false, then this just returns x.
|
static |
The imaginary part of x.
If is_complex
is false, then this just returns zero().
|
static |
The complex conjugate of x.
If is_complex
is false, then this just returns x.
|
static |
x raised to the power y.
|
static |
The square root of x.
If T is an integer type, this is the floor of the square root. If T is a complex-valued type, then this method returns the principal branch of the square root.
If T is real-valued and x is negative, the result of the square root is undefined in general. (CUDA does not allow throwing exceptions in device functions.) Implementations should return NaN if the type T supports this. Of course, in that case, the square of the result will not equal x.
|
static |
The natural (base e) logarithm of x.
If T is an integer type, this is the floor of the logarithm. If T is a complex-valued type, then this method returns the principal branch of the logarithm.
If T is real-valued and x is negative, the result of the logarithm is undefined in general. (CUDA does not allow throwing exceptions in device functions.) Implementations should return NaN if the type T supports this. Of course, in that case, if y is the result, will not equal x.
|
static |
The base ten logarithm of the input.
If T is an integer type, this is the floor of the logarithm. If T is a complex-valued type, then this method returns the principal branch of the logarithm.
If T is real-valued and x is negative, the result of the logarithm is undefined in general. (CUDA does not allow throwing exceptions in device functions.) Implementations should return NaN if the type T supports this. Of course, in that case, if y is the result, will not equal x.
|
static |
Return a silent NaN, if appropriate for T.
If T does not implement a silent NaN, the return value is undefined, but calling this method is still allowed.
|
static |
Machine epsilon.
If T is an integer type (std::numeric_traits<T>::is_exact is true), then epsilon() returns 0. Otherwise, if T is a floating-point type, it returns machine epsilon that T.
|
static |
Return relative machine precision.
|
static |
Return safe minimum (sfmin), such that 1/sfmin does not overflow.
|
static |
Return the base of the scalar type T.
|
static |
Return eps*base
.
|
static |
Returns the number of (base) digits in the significand.
|
static |
1.0 when rounding occurs in addition, else 0.0.
|
static |
Returns the minimum exponent before (gradual) underflow.
|
static |
Returns the underflow threshold: base^(emin-1)
|
static |
Returns the largest exponent before overflow.
|
static |
Overflow theshold: (base^emax)*(1-eps)
|
static |
Same as abs(); return the magnitude of x.
|
static |
Same as conj(); return the complex conjugate of x.
|
static |
Whether x is (silent) NaN or Inf.
This is the same as isNan(x) || isInf(x)
.
|
static |
The string name of T.
Note that this is not a device function.
|
static |
Same as sqrt(x); the square root of x.
|
static |
Whether ArithTraits has a specialization for T.
Definition at line 346 of file Kokkos_ArithTraits.hpp.
|
static |
Whether T is a signed type (has negative values).
Definition at line 348 of file Kokkos_ArithTraits.hpp.
|
static |
Whether T is an integer type.
Definition at line 350 of file Kokkos_ArithTraits.hpp.
|
static |
Whether T "uses exact representations.".
The opposite of is_exact is "is approximate," that is, "may commit rounding error."
Definition at line 355 of file Kokkos_ArithTraits.hpp.
|
static |
Whether T is a complex-valued type.
Definition at line 357 of file Kokkos_ArithTraits.hpp.
|
static |
True if this type T has floating-point parameters.
This is true if and only if this specialization of ArithTraits has "machine-specific" parameters eps(), sfmin(), base(), prec(), t(), rnd(), emin(), rmin(), emax(), and rmax(), relating to floating-point types.
Definition at line 503 of file Kokkos_ArithTraits.hpp.