4.6. Math

VTK‑m comes with several math functions that tend to be useful for visualization algorithms. The implementation of basic math operations can vary subtly on different accelerators, and these functions provide cross platform support.

All math functions are located in the vtkm package. The functions are most useful in the execution environment, but they can also be used in the control environment when needed.

4.6.1. Basic Math

The vtkm/Math.h header file contains several math functions that replicate the behavior of the basic POSIX math functions as well as related functionality.

Did You Know?

When writing worklets, you should favor using these math functions provided by VTK‑m over the standard math functions in vtkm/Math.h. VTK‑m’s implementation manages several compiling and efficiency issues when porting.

4.6.1.1. Exponentials

inline vtkm::Float32 vtkm::Exp(vtkm::Float32 x)

Computes e^x, the base-e exponential of x.

inline vtkm::Float64 vtkm::Exp(vtkm::Float64 x)

Computes e^x, the base-e exponential of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Exp(const T &x)

Computes e^x, the base-e exponential of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Exp(const vtkm::Vec<T, N> &x)

Computes e^x, the base-e exponential of x.

static inline vtkm::Float32 vtkm::Exp10(vtkm::Float32 x)

Computes 10^x, the base-10 exponential of x.

static inline vtkm::Float64 vtkm::Exp10(vtkm::Float64 x)

Computes 10^x, the base-10 exponential of x.

template<typename T>
static inline vtkm::Float64 vtkm::Exp10(T x)

Computes 10^x, the base-10 exponential of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Exp10(const vtkm::Vec<T, N> &x)

Computes 10^x, the base-10 exponential of x.

inline vtkm::Float32 vtkm::Exp2(vtkm::Float32 x)

Computes 2^x, the base-2 exponential of x.

inline vtkm::Float64 vtkm::Exp2(vtkm::Float64 x)

Computes 2^x, the base-2 exponential of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Exp2(const T &x)

Computes 2^x, the base-2 exponential of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Exp2(const vtkm::Vec<T, N> &x)

Computes 2^x, the base-2 exponential of x.

inline vtkm::Float32 vtkm::ExpM1(vtkm::Float32 x)

Computes (e^x) - 1, the of base-e exponental of x then minus 1. The accuracy of this function is good even for very small values of x.

inline vtkm::Float64 vtkm::ExpM1(vtkm::Float64 x)

Computes (e^x) - 1, the of base-e exponental of x then minus 1. The accuracy of this function is good even for very small values of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::ExpM1(const T &x)

Computes (e^x) - 1, the of base-e exponental of x then minus 1. The accuracy of this function is good even for very small values of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::ExpM1(const vtkm::Vec<T, N> &x)

Computes (e^x) - 1, the of base-e exponental of x then minus 1. The accuracy of this function is good even for very small values of x.

inline vtkm::Float32 vtkm::Log(vtkm::Float32 x)

Computes the natural logarithm of x.

inline vtkm::Float64 vtkm::Log(vtkm::Float64 x)

Computes the natural logarithm of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Log(const T &x)

Computes the natural logarithm of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Log(const vtkm::Vec<T, N> &x)

Computes the natural logarithm of x.

inline vtkm::Float32 vtkm::Log10(vtkm::Float32 x)

Computes the logarithm base 10 of x.

inline vtkm::Float64 vtkm::Log10(vtkm::Float64 x)

Computes the logarithm base 10 of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Log10(const T &x)

Computes the logarithm base 10 of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Log10(const vtkm::Vec<T, N> &x)

Computes the logarithm base 10 of x.

inline vtkm::Float32 vtkm::Log1P(vtkm::Float32 x)

Computes the value of log(1+x). This method is more accurate for very small values of x than the vtkm::Log function.

inline vtkm::Float64 vtkm::Log1P(vtkm::Float64 x)

Computes the value of log(1+x). This method is more accurate for very small values of x than the vtkm::Log function.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Log1P(const T &x)

Computes the value of log(1+x). This method is more accurate for very small values of x than the vtkm::Log function.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Log1P(const vtkm::Vec<T, N> &x)

Computes the value of log(1+x). This method is more accurate for very small values of x than the vtkm::Log function.

inline vtkm::Float32 vtkm::Log2(vtkm::Float32 x)

Computes the logarithm base 2 of x.

inline vtkm::Float64 vtkm::Log2(vtkm::Float64 x)

Computes the logarithm base 2 of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Log2(const T &x)

Computes the logarithm base 2 of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Log2(const vtkm::Vec<T, N> &x)

Computes the logarithm base 2 of x.

static inline vtkm::Float32 vtkm::Pow(vtkm::Float32 x, vtkm::Float32 y)

Computes x raised to the power of y.

static inline vtkm::Float64 vtkm::Pow(vtkm::Float64 x, vtkm::Float64 y)

Computes x raised to the power of y.

4.6.1.2. Non-finites

template<typename T>
static inline T vtkm::Infinity()

Returns the representation for infinity. The result is greater than any other number except another infinity or NaN. When comparing two infinities or infinity to NaN, neither is greater than, less than, nor equal to the other. The Infinity() function is templated to specify either a 32 or 64 bit floating point number. The convenience functions Infinity32() andInfinity64() are non-templated versions that return the precision for a particular precision.

static inline vtkm::Float32 vtkm::Infinity32()

Returns the representation for infinity. The result is greater than any other number except another infinity or NaN. When comparing two infinities or infinity to NaN, neither is greater than, less than, nor equal to the other. The Infinity() function is templated to specify either a 32 or 64 bit floating point number. The convenience functions Infinity32() andInfinity64() are non-templated versions that return the precision for a particular precision.

static inline vtkm::Float64 vtkm::Infinity64()

Returns the representation for infinity. The result is greater than any other number except another infinity or NaN. When comparing two infinities or infinity to NaN, neither is greater than, less than, nor equal to the other. The Infinity() function is templated to specify either a 32 or 64 bit floating point number. The convenience functions Infinity32() andInfinity64() are non-templated versions that return the precision for a particular precision.

template<typename T>
static inline bool vtkm::IsFinite(T x)

Returns true if x is a normal number (not NaN or infinite).

template<typename T>
static inline bool vtkm::IsInf(T x)

Returns true if x is positive or negative infinity.

template<typename T>
static inline bool vtkm::IsNan(T x)

Returns true if x is not a number.

static inline bool vtkm::IsNegative(vtkm::Float32 x)

Returns true if x is less than zero, false otherwise.

static inline bool vtkm::IsNegative(vtkm::Float64 x)

Returns true if x is less than zero, false otherwise.

template<typename T>
static inline T vtkm::Nan()

Returns the representation for infinity. The result is greater than any other number except another infinity or NaN. When comparing two infinities or infinity to NaN, neither is greater than, less than, nor equal to the other. The Nan() function is templated to specify either a 32 or 64 bit floating point number. The convenience functions Nan32() and Nan64() are non-templated versions that return the precision for a particular precision.

static inline vtkm::Float32 vtkm::Nan32()

Returns the representation for infinity. The result is greater than any other number except another infinity or NaN. When comparing two infinities or infinity to NaN, neither is greater than, less than, nor equal to the other. The Nan() function is templated to specify either a 32 or 64 bit floating point number. The convenience functions Nan32() and Nan64() are non-templated versions that return the precision for a particular precision.

static inline vtkm::Float64 vtkm::Nan64()

Returns the representation for infinity. The result is greater than any other number except another infinity or NaN. When comparing two infinities or infinity to NaN, neither is greater than, less than, nor equal to the other. The Nan() function is templated to specify either a 32 or 64 bit floating point number. The convenience functions Nan32() and Nan64() are non-templated versions that return the precision for a particular precision.

template<typename T>
static inline T vtkm::NegativeInfinity()

Returns the representation for negative infinity. The result is less than any other number except another negative infinity or NaN. When comparing two negative infinities or negative infinity to NaN, neither is greater than, less than, nor equal to the other. The NegativeInfinity() function is templated to specify either a 32 or 64 bit floating point number. The convenience functions NegativeInfinity32() andNegativeInfinity64() are non-templated versions that return the precision for a particular precision.

static inline vtkm::Float32 vtkm::NegativeInfinity32()

Returns the representation for negative infinity. The result is less than any other number except another negative infinity or NaN. When comparing two negative infinities or negative infinity to NaN, neither is greater than, less than, nor equal to the other. The NegativeInfinity() function is templated to specify either a 32 or 64 bit floating point number. The convenience functions NegativeInfinity32() andNegativeInfinity64() are non-templated versions that return the precision for a particular precision.

static inline vtkm::Float64 vtkm::NegativeInfinity64()

Returns the representation for negative infinity. The result is less than any other number except another negative infinity or NaN. When comparing two negative infinities or negative infinity to NaN, neither is greater than, less than, nor equal to the other. The NegativeInfinity() function is templated to specify either a 32 or 64 bit floating point number. The convenience functions NegativeInfinity32() andNegativeInfinity64() are non-templated versions that return the precision for a particular precision.

4.6.1.3. Polynomials

inline vtkm::Float32 vtkm::Cbrt(vtkm::Float32 x)

Compute the cube root of x.

inline vtkm::Float64 vtkm::Cbrt(vtkm::Float64 x)

Compute the cube root of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Cbrt(const T &x)

Compute the cube root of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Cbrt(const vtkm::Vec<T, N> &x)

Compute the cube root of x.

template<typename T>
inline vtkm::Vec<T, 2> vtkm::QuadraticRoots(T a, T b, T c)

Solves ax² + bx + c = 0.

Only returns the real roots. If there are real roots, the first element of the pair is less than or equal to the second. If there are no real roots, both elements are NaNs. If VTK-m is compiled with FMA support, each root is accurate to 3 ulps; otherwise the discriminant is prone to catastrophic subtractive cancellation and no accuracy guarantees can be provided.

static inline vtkm::Float32 vtkm::RCbrt(vtkm::Float32 x)

Compute the reciprocal cube root of x. The result of this function is equivalent to 1/Cbrt(x). However, on some devices it is faster to compute the reciprocal cube root than the regular cube root. Thus, you should use this function whenever dividing by the cube root.

static inline vtkm::Float64 vtkm::RCbrt(vtkm::Float64 x)

Compute the reciprocal cube root of x. The result of this function is equivalent to 1/Cbrt(x). However, on some devices it is faster to compute the reciprocal cube root than the regular cube root. Thus, you should use this function whenever dividing by the cube root.

template<typename T>
static inline vtkm::Float64 vtkm::RCbrt(T x)

Compute the reciprocal cube root of x. The result of this function is equivalent to 1/Cbrt(x). However, on some devices it is faster to compute the reciprocal cube root than the regular cube root. Thus, you should use this function whenever dividing by the cube root.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::RCbrt(const vtkm::Vec<T, N> &x)

Compute the reciprocal cube root of x. The result of this function is equivalent to 1/Cbrt(x). However, on some devices it is faster to compute the reciprocal cube root than the regular cube root. Thus, you should use this function whenever dividing by the cube root.

static inline vtkm::Float32 vtkm::RSqrt(vtkm::Float32 x)

Compute the reciprocal square root of x. The result of this function is equivalent to 1/Sqrt(x). However, on some devices it is faster to compute the reciprocal square root than the regular square root. Thus, you should use this function whenever dividing by the square root.

static inline vtkm::Float64 vtkm::RSqrt(vtkm::Float64 x)

Compute the reciprocal square root of x. The result of this function is equivalent to 1/Sqrt(x). However, on some devices it is faster to compute the reciprocal square root than the regular square root. Thus, you should use this function whenever dividing by the square root.

template<typename T>
static inline vtkm::Float64 vtkm::RSqrt(T x)

Compute the reciprocal square root of x. The result of this function is equivalent to 1/Sqrt(x). However, on some devices it is faster to compute the reciprocal square root than the regular square root. Thus, you should use this function whenever dividing by the square root.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::RSqrt(const vtkm::Vec<T, N> &x)

Compute the reciprocal square root of x. The result of this function is equivalent to 1/Sqrt(x). However, on some devices it is faster to compute the reciprocal square root than the regular square root. Thus, you should use this function whenever dividing by the square root.

inline vtkm::Float32 vtkm::Sqrt(vtkm::Float32 x)

Compute the square root of x. On some hardware it is faster to find the reciprocal square root, so RSqrt should be used if you actually plan to divide by the square root.

inline vtkm::Float64 vtkm::Sqrt(vtkm::Float64 x)

Compute the square root of x. On some hardware it is faster to find the reciprocal square root, so RSqrt should be used if you actually plan to divide by the square root.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Sqrt(const T &x)

Compute the square root of x. On some hardware it is faster to find the reciprocal square root, so RSqrt should be used if you actually plan to divide by the square root.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Sqrt(const vtkm::Vec<T, N> &x)

Compute the square root of x. On some hardware it is faster to find the reciprocal square root, so RSqrt should be used if you actually plan to divide by the square root.

4.6.1.4. Remainders and Quotient

static inline vtkm::Float32 vtkm::ModF(vtkm::Float32 x, vtkm::Float32 &integral)

Gets the integral and fractional parts of x. The return value is the fractional part and integral is set to the integral part.

static inline vtkm::Float64 vtkm::ModF(vtkm::Float64 x, vtkm::Float64 &integral)

Gets the integral and fractional parts of x. The return value is the fractional part and integral is set to the integral part.

static inline vtkm::Float32 vtkm::Remainder(vtkm::Float32 x, vtkm::Float32 y)

Computes the remainder on division of 2 floating point numbers. The return value is numerator - n denominator, where n is the quotient of numerator divided by denominator rounded towards the nearest integer (instead of toward zero like FMod). For example, FMod(6.5, 2.3) returns -0.4, which is 6.5 - 3*2.3.

static inline vtkm::Float64 vtkm::Remainder(vtkm::Float64 x, vtkm::Float64 y)

Computes the remainder on division of 2 floating point numbers. The return value is numerator - n denominator, where n is the quotient of numerator divided by denominator rounded towards the nearest integer (instead of toward zero like FMod). For example, FMod(6.5, 2.3) returns -0.4, which is 6.5 - 3*2.3.

template<typename QType>
static inline vtkm::Float32 vtkm::RemainderQuotient(vtkm::Float32 numerator, vtkm::Float32 denominator, QType &quotient)

Returns the remainder on division of 2 floating point numbers just like Remainder. In addition, this function also returns the quotient used to get that remainder.

template<typename QType>
static inline vtkm::Float64 vtkm::RemainderQuotient(vtkm::Float64 numerator, vtkm::Float64 denominator, QType &quotient)

Returns the remainder on division of 2 floating point numbers just like Remainder. In addition, this function also returns the quotient used to get that remainder.

4.6.1.5. Rounding and Precision

inline vtkm::Float32 vtkm::Ceil(vtkm::Float32 x)

Round x to the smallest integer value not less than x.

inline vtkm::Float64 vtkm::Ceil(vtkm::Float64 x)

Round x to the smallest integer value not less than x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Ceil(const T &x)

Round x to the smallest integer value not less than x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Ceil(const vtkm::Vec<T, N> &x)

Round x to the smallest integer value not less than x.

static inline vtkm::Float32 vtkm::CopySign(vtkm::Float32 x, vtkm::Float32 y)

Copies the sign of y onto x. If y is positive, returns Abs(x). If y is negative, returns -Abs(x).

static inline vtkm::Float64 vtkm::CopySign(vtkm::Float64 x, vtkm::Float64 y)

Copies the sign of y onto x. If y is positive, returns Abs(x). If y is negative, returns -Abs(x).

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<T, N> vtkm::CopySign(const vtkm::Vec<T, N> &x, const vtkm::Vec<T, N> &y)

Copies the sign of y onto x. If y is positive, returns Abs(x). If y is negative, returns -Abs(x).

template<typename T>
static inline T vtkm::Epsilon()

Returns the difference between 1 and the least value greater than 1 that is representable by a floating point number. Epsilon is useful for specifying the tolerance one should have when considering numerical error. The Epsilon() function is templated to specify either a 32 or 64 bit floating point number. The convenience functions Epsilon32() andEpsilon64() are non-templated versions that return the precision for a particular precision.

static inline vtkm::Float32 vtkm::Epsilon32()

Returns the difference between 1 and the least value greater than 1 that is representable by a floating point number. Epsilon is useful for specifying the tolerance one should have when considering numerical error. The Epsilon() function is templated to specify either a 32 or 64 bit floating point number. The convenience functions Epsilon32() andEpsilon64() are non-templated versions that return the precision for a particular precision.

static inline vtkm::Float64 vtkm::Epsilon64()

Returns the difference between 1 and the least value greater than 1 that is representable by a floating point number. Epsilon is useful for specifying the tolerance one should have when considering numerical error. The Epsilon() function is templated to specify either a 32 or 64 bit floating point number. The convenience functions Epsilon32() andEpsilon64() are non-templated versions that return the precision for a particular precision.

static inline vtkm::Float32 vtkm::FMod(vtkm::Float32 x, vtkm::Float32 y)

Computes the remainder on division of 2 floating point numbers. The return value is numerator - n denominator, where n is the quotient of numerator divided by denominator rounded towards zero to an integer. For example, FMod(6.5, 2.3) returns 1.9, which is 6.5 - 2*2.3.

static inline vtkm::Float64 vtkm::FMod(vtkm::Float64 x, vtkm::Float64 y)

Computes the remainder on division of 2 floating point numbers. The return value is numerator - n denominator, where n is the quotient of numerator divided by denominator rounded towards zero to an integer. For example, FMod(6.5, 2.3) returns 1.9, which is 6.5 - 2*2.3.

inline vtkm::Float32 vtkm::Round(vtkm::Float32 x)

Round x to the nearest integral value.

inline vtkm::Float64 vtkm::Round(vtkm::Float64 x)

Round x to the nearest integral value.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Round(const T &x)

Round x to the nearest integral value.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Round(const vtkm::Vec<T, N> &x)

Round x to the nearest integral value.

4.6.1.6. Sign

static inline vtkm::Int32 vtkm::Abs(vtkm::Int32 x)

Return the absolute value of x. That is, return x if it is positive or -x if it is negative.

static inline vtkm::Int64 vtkm::Abs(vtkm::Int64 x)

Return the absolute value of x. That is, return x if it is positive or -x if it is negative.

static inline vtkm::Float32 vtkm::Abs(vtkm::Float32 x)

Return the absolute value of x. That is, return x if it is positive or -x if it is negative.

static inline vtkm::Float64 vtkm::Abs(vtkm::Float64 x)

Return the absolute value of x. That is, return x if it is positive or -x if it is negative.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Abs(T x)

Return the absolute value of x. That is, return x if it is positive or -x if it is negative.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<T, N> vtkm::Abs(const vtkm::Vec<T, N> &x)

Return the absolute value of x. That is, return x if it is positive or -x if it is negative.

inline vtkm::Float32 vtkm::Floor(vtkm::Float32 x)

Round x to the largest integer value not greater than x.

inline vtkm::Float64 vtkm::Floor(vtkm::Float64 x)

Round x to the largest integer value not greater than x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Floor(const T &x)

Round x to the largest integer value not greater than x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Floor(const vtkm::Vec<T, N> &x)

Round x to the largest integer value not greater than x.

static inline vtkm::Int32 vtkm::SignBit(vtkm::Float32 x)

Returns a nonzero value if x is negative.

static inline vtkm::Int32 vtkm::SignBit(vtkm::Float64 x)

Returns a nonzero value if x is negative.

4.6.1.7. Trigonometry

inline vtkm::Float32 vtkm::ACos(vtkm::Float32 x)

Compute the arc cosine of x.

inline vtkm::Float64 vtkm::ACos(vtkm::Float64 x)

Compute the arc cosine of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::ACos(const T &x)

Compute the arc cosine of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::ACos(const vtkm::Vec<T, N> &x)

Compute the arc cosine of x.

inline vtkm::Float32 vtkm::ACosH(vtkm::Float32 x)

Compute the hyperbolic arc cosine of x.

inline vtkm::Float64 vtkm::ACosH(vtkm::Float64 x)

Compute the hyperbolic arc cosine of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::ACosH(const T &x)

Compute the hyperbolic arc cosine of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::ACosH(const vtkm::Vec<T, N> &x)

Compute the hyperbolic arc cosine of x.

inline vtkm::Float32 vtkm::ASin(vtkm::Float32 x)

Compute the arc sine of x.

inline vtkm::Float64 vtkm::ASin(vtkm::Float64 x)

Compute the arc sine of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::ASin(const T &x)

Compute the arc sine of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::ASin(const vtkm::Vec<T, N> &x)

Compute the arc sine of x.

inline vtkm::Float32 vtkm::ASinH(vtkm::Float32 x)

Compute the hyperbolic arc sine of x.

inline vtkm::Float64 vtkm::ASinH(vtkm::Float64 x)

Compute the hyperbolic arc sine of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::ASinH(const T &x)

Compute the hyperbolic arc sine of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::ASinH(const vtkm::Vec<T, N> &x)

Compute the hyperbolic arc sine of x.

inline vtkm::Float32 vtkm::ATan(vtkm::Float32 x)

Compute the arc tangent of x.

inline vtkm::Float64 vtkm::ATan(vtkm::Float64 x)

Compute the arc tangent of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::ATan(const T &x)

Compute the arc tangent of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::ATan(const vtkm::Vec<T, N> &x)

Compute the arc tangent of x.

static inline vtkm::Float32 vtkm::ATan2(vtkm::Float32 x, vtkm::Float32 y)

Compute the arc tangent of x / y using the signs of both arguments to determine the quadrant of the return value.

static inline vtkm::Float64 vtkm::ATan2(vtkm::Float64 x, vtkm::Float64 y)

Compute the arc tangent of x / y using the signs of both arguments to determine the quadrant of the return value.

inline vtkm::Float32 vtkm::ATanH(vtkm::Float32 x)

Compute the hyperbolic arc tangent of x.

inline vtkm::Float64 vtkm::ATanH(vtkm::Float64 x)

Compute the hyperbolic arc tangent of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::ATanH(const T &x)

Compute the hyperbolic arc tangent of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::ATanH(const vtkm::Vec<T, N> &x)

Compute the hyperbolic arc tangent of x.

inline vtkm::Float32 vtkm::Cos(vtkm::Float32 x)

Compute the cosine of x.

inline vtkm::Float64 vtkm::Cos(vtkm::Float64 x)

Compute the cosine of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Cos(const T &x)

Compute the cosine of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Cos(const vtkm::Vec<T, N> &x)

Compute the cosine of x.

inline vtkm::Float32 vtkm::CosH(vtkm::Float32 x)

Compute the hyperbolic cosine of x.

inline vtkm::Float64 vtkm::CosH(vtkm::Float64 x)

Compute the hyperbolic cosine of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::CosH(const T &x)

Compute the hyperbolic cosine of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::CosH(const vtkm::Vec<T, N> &x)

Compute the hyperbolic cosine of x.

template<typename T = vtkm::Float64>
static inline constexpr detail::FloatingPointReturnType<T>::Type vtkm::Pi()

Returns the constant Pi.

template<typename T = vtkm::Float64>
static inline constexpr detail::FloatingPointReturnType<T>::Type vtkm::Pi_2()

Returns the constant Pi halves.

template<typename T = vtkm::Float64>
static inline constexpr detail::FloatingPointReturnType<T>::Type vtkm::Pi_3()

Returns the constant Pi thirds.

template<typename T = vtkm::Float64>
static inline constexpr detail::FloatingPointReturnType<T>::Type vtkm::Pi_4()

Returns the constant Pi fourths.

template<typename T = vtkm::Float64>
static inline constexpr detail::FloatingPointReturnType<T>::Type vtkm::Pi_180()

Returns the constant Pi one hundred and eightieth.

inline vtkm::Float32 vtkm::Sin(vtkm::Float32 x)

Compute the sine of x.

inline vtkm::Float64 vtkm::Sin(vtkm::Float64 x)

Compute the sine of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Sin(const T &x)

Compute the sine of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Sin(const vtkm::Vec<T, N> &x)

Compute the sine of x.

inline vtkm::Float32 vtkm::SinH(vtkm::Float32 x)

Compute the hyperbolic sine of x.

inline vtkm::Float64 vtkm::SinH(vtkm::Float64 x)

Compute the hyperbolic sine of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::SinH(const T &x)

Compute the hyperbolic sine of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::SinH(const vtkm::Vec<T, N> &x)

Compute the hyperbolic sine of x.

inline vtkm::Float32 vtkm::Tan(vtkm::Float32 x)

Compute the tangent of x.

inline vtkm::Float64 vtkm::Tan(vtkm::Float64 x)

Compute the tangent of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::Tan(const T &x)

Compute the tangent of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::Tan(const vtkm::Vec<T, N> &x)

Compute the tangent of x.

inline vtkm::Float32 vtkm::TanH(vtkm::Float32 x)

Compute the hyperbolic tangent of x.

inline vtkm::Float64 vtkm::TanH(vtkm::Float64 x)

Compute the hyperbolic tangent of x.

template<typename T>
static inline detail::FloatingPointReturnType<T>::Type vtkm::TanH(const T &x)

Compute the hyperbolic tangent of x.

template<typename T, vtkm::IdComponent N>
static inline vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, N> vtkm::TanH(const vtkm::Vec<T, N> &x)

Compute the hyperbolic tangent of x.

template<typename T = vtkm::Float64>
static inline constexpr detail::FloatingPointReturnType<T>::Type vtkm::TwoPi()

Returns the constant 2 times Pi.

4.6.1.8. Miscellaneous

inline vtkm::UInt64 vtkm::FloatDistance(vtkm::Float64 x, vtkm::Float64 y)

Computes the number of representables between two floating point numbers.

This function is non-negative and symmetric in its arguments. If either argument is non-finite, the value returned is the maximum value allowed by 64-bit unsigned integers: 2^64-1.

inline vtkm::UInt64 vtkm::FloatDistance(vtkm::Float32 x, vtkm::Float32 y)

Computes the number of representables between two floating point numbers.

This function is non-negative and symmetric in its arguments. If either argument is non-finite, the value returned is the maximum value allowed by 64-bit unsigned integers: 2^64-1.

template<typename T>
static inline T vtkm::Max(const T &x, const T &y)

Returns x or y, whichever is larger.

Returns x or y, whichever is larger.

template<typename T>
static inline T vtkm::Min(const T &x, const T &y)

Returns x or y, whichever is smaller.

Returns x or y, whichever is smaller.

4.6.2. Vector Analysis

Visualization and computational geometry algorithms often perform vector analysis operations. The vtkm/VectorAnalysis.h header file provides functions that perform the basic common vector analysis operations.

template<typename T>
vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, 3> vtkm::Cross(const vtkm::Vec<T, 3> &x, const vtkm::Vec<T, 3> &y)

Find the cross product of two vectors.

If VTK-m is compiled with FMA support, it uses Kahan’s difference of products algorithm to achieve a maximum error of 1.5 ulps in each component.

template<typename ValueType, typename WeightType>
inline ValueType vtkm::Lerp(const ValueType &value0, const ValueType &value1, const WeightType &weight)

Returns the linear interpolation of two values based on weight.

Lerp returns the linear interpolation of two values based on a weight. If weight is outside [0,1] then Lerp extrapolates. If weight=0 then value0 is returned. If weight=1 then value1 is returned.

template<typename T>
detail::FloatingPointReturnType<T>::Type vtkm::Magnitude(const T &x)

Returns the magnitude of a vector.

It is usually much faster to compute MagnitudeSquared, so that should be substituted when possible (unless you are just going to take the square root, which would be besides the point). On some hardware it is also faster to find the reciprocal magnitude, so RMagnitude should be used if you actually plan to divide by the magnitude.

template<typename T>
detail::FloatingPointReturnType<T>::Type vtkm::MagnitudeSquared(const T &x)

Returns the square of the magnitude of a vector.

It is usually much faster to compute the square of the magnitude than the magnitude, so you should use this function in place of Magnitude or RMagnitude when possible.

template<typename T>
T vtkm::Normal(const T &x)

Returns a normalized version of the given vector.

The resulting vector points in the same direction but has unit length.

template<typename T>
void vtkm::Normalize(T &x)

Changes a vector to be normal.

The given vector is scaled to be unit length.

template<typename T, int N>
int vtkm::Orthonormalize(const vtkm::Vec<vtkm::Vec<T, N>, N> &inputs, vtkm::Vec<vtkm::Vec<T, N>, N> &outputs, T tol = static_cast<T>(1e-6))

Convert a set of vectors to an orthonormal basis.

This function performs Gram-Schmidt orthonormalization for 3-D vectors. The first output vector will always be parallel to the first input vector. The remaining output vectors will be orthogonal and unit length and have the same handedness as their corresponding input vectors.

This method is geometric. It does not require a matrix solver. However, unlike the algebraic eigensolver techniques which do use matrix inversion, this method may return zero-length output vectors if some input vectors are collinear. The number of non-zero (to within the specified tolerance, tol) output vectors is the return value.

See https://en.wikipedia.org/wiki/Gram%E2%80%93Schmidt_process for details.

template<typename T, int N>
vtkm::Vec<T, N> vtkm::Project(const vtkm::Vec<T, N> &v, const vtkm::Vec<T, N> &u)

Project a vector onto another vector.

This method computes the orthogonal projection of the vector v onto u; that is, it projects its first argument onto its second.

Note that if the vector u has zero length, the output vector will have all its entries equal to NaN.

template<typename T, int N>
T vtkm::ProjectedDistance(const vtkm::Vec<T, N> &v, const vtkm::Vec<T, N> &u)

Project a vector onto another vector, returning only the projected distance.

This method computes the orthogonal projection of the vector v onto u; that is, it projects its first argument onto its second.

Note that if the vector u has zero length, the output will be NaN.

template<typename T>
detail::FloatingPointReturnType<T>::Type vtkm::RMagnitude(const T &x)

Returns the reciprocal magnitude of a vector.

On some hardware RMagnitude is faster than Magnitude, but neither is as fast as MagnitudeSquared. This function works on scalars as well as vectors, in which case it just returns the reciprocal of the scalar.

template<typename T>
vtkm::Vec<typename detail::FloatingPointReturnType<T>::Type, 3> vtkm::TriangleNormal(const vtkm::Vec<T, 3> &a, const vtkm::Vec<T, 3> &b, const vtkm::Vec<T, 3> &c)

Find the normal of a triangle.

Given three coordinates in space, which, unless degenerate, uniquely define a triangle and the plane the triangle is on, returns a vector perpendicular to that triangle/plane.

Note that the returned vector might not be a unit vector. In fact, the length is equal to twice the area of the triangle. If you want a unit vector, send the result through the vtkm::Normal() or vtkm::Normalize() function.

4.6.3. Matrices

Linear algebra operations on small matrices that are done on a single thread are located in vtkm/Matrix.h.

This header defines the vtkm::Matrix templated class. The template parameters are first the type of component, then the number of rows, then the number of columns. The overloaded parentheses operator can be used to retrieve values based on row and column indices. Likewise, the bracket operators can be used to reference the vtkm::Matrix as a 2D array (indexed by row first).

template<typename T, vtkm::IdComponent NumRow, vtkm::IdComponent NumCol>
class Matrix

Basic Matrix type.

The Matrix class holds a small two dimensional array for simple linear algebra and vector operations. VTK-m provides several Matrix-based operations to assist in visualization computations.

A Matrix is not intended to hold very large arrays. Rather, they are a per-thread data structure to hold information like geometric transforms and tensors.

Public Functions

inline Matrix()

Creates an uninitialized matrix. The values in the matrix are not determined.

inline explicit Matrix(const ComponentType &value)

Creates a matrix initialized with all values set to the provided value.

inline const vtkm::Vec<ComponentType, NUM_COLUMNS> &operator[](vtkm::IdComponent rowIndex) const

Brackets are used to reference a matrix like a 2D array (i.e.

matrix[row][column]).

inline vtkm::Vec<ComponentType, NUM_COLUMNS> &operator[](vtkm::IdComponent rowIndex)

Brackets are used to referens a matrix like a 2D array i.e.

matrix[row][column].

inline const ComponentType &operator()(vtkm::IdComponent rowIndex, vtkm::IdComponent colIndex) const

Parentheses are used to reference a matrix using mathematical tuple notation i.e.

matrix(row,column).

inline ComponentType &operator()(vtkm::IdComponent rowIndex, vtkm::IdComponent colIndex)

Parentheses are used to reference a matrix using mathematical tuple notation i.e.

matrix(row,column).

The following example builds a vtkm::Matrix that contains the values

\[\begin{split}\left| \begin{array}{ccc} 0 & 1 & 2 \\ 10 & 11 & 12 \end{array} \right|\end{split}\]

Example 4.64 Creating a vtkm::Matrix.

  vtkm::Matrix<vtkm::Float32, 2, 3> matrix;

  // Using parenthesis notation.
  matrix(0, 0) = 0.0f;
  matrix(0, 1) = 1.0f;
  matrix(0, 2) = 2.0f;

  // Using bracket notation.
  matrix[1][0] = 10.0f;
  matrix[1][1] = 11.0f;
  matrix[1][2] = 12.0f;

The vtkm/Matrix.h header also defines the following functions that operate on matrices.

template<typename T, vtkm::IdComponent Size>
T vtkm::MatrixDeterminant(const vtkm::Matrix<T, Size, Size> &A)

Compute the determinant of a matrix.

template<typename T, vtkm::IdComponent NumRow, vtkm::IdComponent NumCol>
vtkm::Vec<T, NumRow> vtkm::MatrixGetColumn(const vtkm::Matrix<T, NumRow, NumCol> &matrix, vtkm::IdComponent columnIndex)

Returns a tuple containing the given column (indexed from 0) of the given matrix.

Might not be as efficient as the MatrixGetRow() function.

template<typename T, vtkm::IdComponent NumRow, vtkm::IdComponent NumCol>
const vtkm::Vec<T, NumCol> &vtkm::MatrixGetRow(const vtkm::Matrix<T, NumRow, NumCol> &matrix, vtkm::IdComponent rowIndex)

Returns a tuple containing the given row (indexed from 0) of the given matrix.

template<typename T, vtkm::IdComponent Size>
vtkm::Matrix<T, Size, Size> vtkm::MatrixIdentity()

Returns the identity matrix.

template<typename T, vtkm::IdComponent Size>
void vtkm::MatrixIdentity(vtkm::Matrix<T, Size, Size> &matrix)

Fills the given matrix with the identity matrix.

template<typename T, vtkm::IdComponent Size>
vtkm::Matrix<T, Size, Size> vtkm::MatrixInverse(const vtkm::Matrix<T, Size, Size> &A, bool &valid)

Find and return the inverse of the given matrix.

If the matrix is singular, the inverse will not be correct and valid will be set to false.

template<typename T, vtkm::IdComponent NumRow, vtkm::IdComponent NumCol, vtkm::IdComponent NumInternal>
vtkm::Matrix<T, NumRow, NumCol> vtkm::MatrixMultiply(const vtkm::Matrix<T, NumRow, NumInternal> &leftFactor, const vtkm::Matrix<T, NumInternal, NumCol> &rightFactor)

Standard matrix multiplication.

template<typename T, vtkm::IdComponent NumRow, vtkm::IdComponent NumCol>
vtkm::Vec<T, NumRow> vtkm::MatrixMultiply(const vtkm::Matrix<T, NumRow, NumCol> &leftFactor, const vtkm::Vec<T, NumCol> &rightFactor)

Standard matrix-vector multiplication.

template<typename T, vtkm::IdComponent NumRow, vtkm::IdComponent NumCol>
vtkm::Vec<T, NumCol> vtkm::MatrixMultiply(const vtkm::Vec<T, NumRow> &leftFactor, const vtkm::Matrix<T, NumRow, NumCol> &rightFactor)

Standard vector-matrix multiplication.

template<typename T, vtkm::IdComponent NumRow, vtkm::IdComponent NumCol>
void vtkm::MatrixSetColumn(vtkm::Matrix<T, NumRow, NumCol> &matrix, vtkm::IdComponent columnIndex, const vtkm::Vec<T, NumRow> &columnValues)

Convenience function for setting a column of a matrix.

template<typename T, vtkm::IdComponent NumRow, vtkm::IdComponent NumCol>
void vtkm::MatrixSetRow(vtkm::Matrix<T, NumRow, NumCol> &matrix, vtkm::IdComponent rowIndex, const vtkm::Vec<T, NumCol> &rowValues)

Convenience function for setting a row of a matrix.

template<typename T, vtkm::IdComponent NumRows, vtkm::IdComponent NumCols>
vtkm::Matrix<T, NumCols, NumRows> vtkm::MatrixTranspose(const vtkm::Matrix<T, NumRows, NumCols> &matrix)

Returns the transpose of the given matrix.

template<typename T, vtkm::IdComponent Size>
vtkm::Vec<T, Size> vtkm::SolveLinearSystem(const vtkm::Matrix<T, Size, Size> &A, const vtkm::Vec<T, Size> &b, bool &valid)

Solve the linear system Ax = b for x.

If a single solution is found, valid is set to true, false otherwise.

4.6.4. Newton’s Method

VTK‑m’s matrix methods (documented in Section 4.6.3 (Matrices)) provide a method to solve a small linear system of equations. However, sometimes it is necessary to solve a small nonlinear system of equations. This can be done with the vtkm::NewtonsMethod() function defined in the vtkm/NewtonsMethod.h header.

The vtkm::NewtonsMethod() function assumes that the number of variables equals the number of equations. Newton’s method operates on an iterative evaluate and search. Evaluations are performed using the functors passed into the vtkm::NewtonsMethod().

template<typename ScalarType, vtkm::IdComponent Size, typename JacobianFunctor, typename FunctionFunctor>
NewtonsMethodResult<ScalarType, Size> vtkm::NewtonsMethod(JacobianFunctor jacobianEvaluator, FunctionFunctor functionEvaluator, vtkm::Vec<ScalarType, Size> desiredFunctionOutput, vtkm::Vec<ScalarType, Size> initialGuess = vtkm::Vec<ScalarType, Size>(ScalarType(0)), ScalarType convergeDifference = ScalarType(1e-3), vtkm::IdComponent maxIterations = 10)

Uses Newton’s method (a.k.a.

Newton-Raphson method) to solve a nonlinear system of equations. This function assumes that the number of variables equals the number of equations. Newton’s method operates on an iterative evaluate and search. Evaluations are performed using the functors passed into the NewtonsMethod. The first functor returns the NxN matrix of the Jacobian at a given input point. The second functor returns the N tuple that is the function evaluation at the given input point. The input point that evaluates to the desired output, or the closest point found, is returned.

Parameters:

• jacobianEvaluator – [in] A functor whose operation takes a vtkm::Vec and returns a vtkm::Matrix containing the math function’s Jacobian vector at that point.

• functionEvaluator – [in] A functor whose operation takes a vtkm::Vec and returns the evaluation of the math function at that point as another vtkm::Vec.

• desiredFunctionOutput – [in] The desired output of the function.

• initialGuess – [in] The initial guess to search from. If not specified, the origin is used.

• convergeDifference – [in] The convergence distance. If the iterative method changes all values less than this amount. Once all values change less, it considers the solution found. If not specified, set to 0.001.

• maxIterations – [in] The maximum amount of iterations to run before giving up and returning the best solution found. If not specified, set to 10.

Returns:

A vtkm::NewtonsMethodResult containing the best found result and state about its validity.

The vtkm::NewtonsMethod() function returns a vtkm{NewtonsMethodResult} object. textidentifier{NewtonsMethodResult} is a textcode{struct} templated on the type and number of input values of the nonlinear system. textidentifier{NewtonsMethodResult} contains the following items.

template<typename ScalarType, vtkm::IdComponent Size>
struct NewtonsMethodResult

An object returned from NewtonsMethod() that contains the result and other information about the final state.

Public Members

bool Valid

True if Newton’s method ran into a singularity.

bool Converged

True if Newton’s method converted to below the convergence value.

vtkm::Vec<ScalarType, Size> Solution

The solution found by Newton’s method.

If Converged is false, then this value is likely inaccurate. If Valid is false, then this value is undefined.

Example 4.65 Using vtkm::NewtonsMethod() to solve a small system of nonlinear equations.

// A functor for the mathematical function f(x) = [dot(x,x),x[0]*x[1]]
struct FunctionFunctor
{
  template<typename T>
  VTKM_EXEC_CONT vtkm::Vec<T, 2> operator()(const vtkm::Vec<T, 2>& x) const
  {
    return vtkm::make_Vec(vtkm::Dot(x, x), x[0] * x[1]);
  }
};

// A functor for the Jacobian of the mathematical function
// f(x) = [dot(x,x),x[0]*x[1]], which is
//   | 2*x[0] 2*x[1] |
//   |   x[1]   x[0] |
struct JacobianFunctor
{
  template<typename T>
  VTKM_EXEC_CONT vtkm::Matrix<T, 2, 2> operator()(const vtkm::Vec<T, 2>& x) const
  {
    vtkm::Matrix<T, 2, 2> jacobian;
    jacobian(0, 0) = 2 * x[0];
    jacobian(0, 1) = 2 * x[1];
    jacobian(1, 0) = x[1];
    jacobian(1, 1) = x[0];

    return jacobian;
  }
};

VTKM_EXEC
void SolveNonlinear()
{
  // Use Newton's method to solve the nonlinear system of equations:
  //
  //    x^2 + y^2 = 2
  //    x*y = 1
  //
  // There are two possible solutions, which are (x=1,y=1) and (x=-1,y=-1).
  // The one found depends on the starting value.
  vtkm::NewtonsMethodResult<vtkm::Float32, 2> answer1 =
    vtkm::NewtonsMethod(JacobianFunctor(),
                        FunctionFunctor(),
                        vtkm::make_Vec(2.0f, 1.0f),
                        vtkm::make_Vec(1.0f, 0.0f));
  if (!answer1.Valid || !answer1.Converged)
  {
    // Failed to find solution
  }
  // answer1.Solution is [1,1]

  vtkm::NewtonsMethodResult<vtkm::Float32, 2> answer2 =
    vtkm::NewtonsMethod(JacobianFunctor(),
                        FunctionFunctor(),
                        vtkm::make_Vec(2.0f, 1.0f),
                        vtkm::make_Vec(0.0f, -2.0f));
  if (!answer2.Valid || !answer2.Converged)
  {
    // Failed to find solution
  }
  // answer2 is [-1,-1]
}