From fd057f86b3071706bc5768a79f3107fe21f71eb3 Mon Sep 17 00:00:00 2001 From: Gael Guennebaud Date: Wed, 20 Jul 2016 12:14:10 +0200 Subject: [PATCH] Complete the coeff-wise math function table. --- Eigen/src/plugins/ArrayCwiseUnaryOps.h | 50 +-- Eigen/src/plugins/CommonCwiseUnaryOps.h | 2 +- doc/CoeffwiseMathFunctionsTable.dox | 392 +++++++++++++++++++++++- 3 files changed, 406 insertions(+), 38 deletions(-) diff --git a/Eigen/src/plugins/ArrayCwiseUnaryOps.h b/Eigen/src/plugins/ArrayCwiseUnaryOps.h index db02e299c..ebaa3f192 100644 --- a/Eigen/src/plugins/ArrayCwiseUnaryOps.h +++ b/Eigen/src/plugins/ArrayCwiseUnaryOps.h @@ -36,7 +36,7 @@ typedef CwiseUnaryOp, const Derived> IsFini * Example: \include Cwise_abs.cpp * Output: \verbinclude Cwise_abs.out * - * \sa abs2() + * \sa Math functions, abs2() */ EIGEN_DEVICE_FUNC EIGEN_STRONG_INLINE const AbsReturnType @@ -64,7 +64,7 @@ arg() const * Example: \include Cwise_abs2.cpp * Output: \verbinclude Cwise_abs2.out * - * \sa abs(), square() + * \sa Math functions, abs(), square() */ EIGEN_DEVICE_FUNC EIGEN_STRONG_INLINE const Abs2ReturnType @@ -81,7 +81,7 @@ abs2() const * Example: \include Cwise_exp.cpp * Output: \verbinclude Cwise_exp.out * - * \sa pow(), log(), sin(), cos() + * \sa Math functions, pow(), log(), sin(), cos() */ EIGEN_DEVICE_FUNC inline const ExpReturnType @@ -98,7 +98,7 @@ exp() const * Example: \include Cwise_log.cpp * Output: \verbinclude Cwise_log.out * - * \sa exp() + * \sa Math functions, exp() */ EIGEN_DEVICE_FUNC inline const LogReturnType @@ -112,7 +112,7 @@ log() const * In exact arithmetic, \c x.log() is equivalent to \c (x+1).log(), * however, with finite precision, this function is much more accurate when \c x is close to zero. * - * \sa log() + * \sa Math functions, log() */ EIGEN_DEVICE_FUNC inline const Log1pReturnType @@ -128,7 +128,7 @@ log1p() const * Example: \include Cwise_log10.cpp * Output: \verbinclude Cwise_log10.out * - * \sa log() + * \sa Math functions, log() */ EIGEN_DEVICE_FUNC inline const Log10ReturnType @@ -145,7 +145,7 @@ log10() const * Example: \include Cwise_sqrt.cpp * Output: \verbinclude Cwise_sqrt.out * - * \sa pow(), square() + * \sa Math functions, pow(), square() */ EIGEN_DEVICE_FUNC inline const SqrtReturnType @@ -195,7 +195,7 @@ sign() const * Example: \include Cwise_cos.cpp * Output: \verbinclude Cwise_cos.out * - * \sa sin(), acos() + * \sa Math functions, sin(), acos() */ EIGEN_DEVICE_FUNC inline const CosReturnType @@ -213,7 +213,7 @@ cos() const * Example: \include Cwise_sin.cpp * Output: \verbinclude Cwise_sin.out * - * \sa cos(), asin() + * \sa Math functions, cos(), asin() */ EIGEN_DEVICE_FUNC inline const SinReturnType @@ -227,7 +227,7 @@ sin() const * Example: \include Cwise_tan.cpp * Output: \verbinclude Cwise_tan.out * - * \sa cos(), sin() + * \sa Math functions, cos(), sin() */ EIGEN_DEVICE_FUNC inline const TanReturnType @@ -241,7 +241,7 @@ tan() const * Example: \include Cwise_atan.cpp * Output: \verbinclude Cwise_atan.out * - * \sa tan(), asin(), acos() + * \sa Math functions, tan(), asin(), acos() */ EIGEN_DEVICE_FUNC inline const AtanReturnType @@ -255,7 +255,7 @@ atan() const * Example: \include Cwise_acos.cpp * Output: \verbinclude Cwise_acos.out * - * \sa cos(), asin() + * \sa Math functions, cos(), asin() */ EIGEN_DEVICE_FUNC inline const AcosReturnType @@ -269,7 +269,7 @@ acos() const * Example: \include Cwise_asin.cpp * Output: \verbinclude Cwise_asin.out * - * \sa sin(), acos() + * \sa Math functions, sin(), acos() */ EIGEN_DEVICE_FUNC inline const AsinReturnType @@ -283,7 +283,7 @@ asin() const * Example: \include Cwise_tanh.cpp * Output: \verbinclude Cwise_tanh.out * - * \sa tan(), sinh(), cosh() + * \sa Math functions, tan(), sinh(), cosh() */ EIGEN_DEVICE_FUNC inline const TanhReturnType @@ -297,7 +297,7 @@ tanh() const * Example: \include Cwise_sinh.cpp * Output: \verbinclude Cwise_sinh.out * - * \sa sin(), tanh(), cosh() + * \sa Math functions, sin(), tanh(), cosh() */ EIGEN_DEVICE_FUNC inline const SinhReturnType @@ -311,7 +311,7 @@ sinh() const * Example: \include Cwise_cosh.cpp * Output: \verbinclude Cwise_cosh.out * - * \sa tan(), sinh(), cosh() + * \sa Math functions, tan(), sinh(), cosh() */ EIGEN_DEVICE_FUNC inline const CoshReturnType @@ -339,7 +339,7 @@ inverse() const * Example: \include Cwise_square.cpp * Output: \verbinclude Cwise_square.out * - * \sa operator/(), operator*(), abs2() + * \sa Math functions, abs2(), cube(), pow() */ EIGEN_DEVICE_FUNC inline const SquareReturnType @@ -353,7 +353,7 @@ square() const * Example: \include Cwise_cube.cpp * Output: \verbinclude Cwise_cube.out * - * \sa square(), pow() + * \sa Math functions, square(), pow() */ EIGEN_DEVICE_FUNC inline const CubeReturnType @@ -367,7 +367,7 @@ cube() const * Example: \include Cwise_round.cpp * Output: \verbinclude Cwise_round.out * - * \sa ceil(), floor() + * \sa Math functions, ceil(), floor() */ EIGEN_DEVICE_FUNC inline const RoundReturnType @@ -381,7 +381,7 @@ round() const * Example: \include Cwise_floor.cpp * Output: \verbinclude Cwise_floor.out * - * \sa ceil(), round() + * \sa Math functions, ceil(), round() */ EIGEN_DEVICE_FUNC inline const FloorReturnType @@ -395,7 +395,7 @@ floor() const * Example: \include Cwise_ceil.cpp * Output: \verbinclude Cwise_ceil.out * - * \sa floor(), round() + * \sa Math functions, floor(), round() */ EIGEN_DEVICE_FUNC inline const CeilReturnType @@ -483,7 +483,7 @@ typedef CwiseUnaryOp, const Derived> ErfcReturn * or float/double in non c++11 mode, the user has to provide implementations of lgamma(T) for any scalar * type T to be supported. * - * \sa digamma() + * \sa Math functions, digamma() */ EIGEN_DEVICE_FUNC inline const LgammaReturnType @@ -500,7 +500,7 @@ lgamma() const * the user has to provide implementations of digamma(T) for any scalar * type T to be supported. * - * \sa Eigen::digamma(), Eigen::polygamma(), lgamma() + * \sa Math functions, Eigen::digamma(), Eigen::polygamma(), lgamma() */ EIGEN_DEVICE_FUNC inline const DigammaReturnType @@ -521,7 +521,7 @@ digamma() const * or float/double in non c++11 mode, the user has to provide implementations of erf(T) for any scalar * type T to be supported. * - * \sa erfc() + * \sa Math functions, erfc() */ EIGEN_DEVICE_FUNC inline const ErfReturnType @@ -542,7 +542,7 @@ erf() const * or float/double in non c++11 mode, the user has to provide implementations of erfc(T) for any scalar * type T to be supported. * - * \sa erf() + * \sa Math functions, erf() */ EIGEN_DEVICE_FUNC inline const ErfcReturnType diff --git a/Eigen/src/plugins/CommonCwiseUnaryOps.h b/Eigen/src/plugins/CommonCwiseUnaryOps.h index 6cd5479a0..5719c6b10 100644 --- a/Eigen/src/plugins/CommonCwiseUnaryOps.h +++ b/Eigen/src/plugins/CommonCwiseUnaryOps.h @@ -62,7 +62,7 @@ cast() const /** \returns an expression of the complex conjugate of \c *this. * - * \sa adjoint() */ + * \sa Math functions, MatrixBase::adjoint() */ EIGEN_DEVICE_FUNC inline ConjugateReturnType conjugate() const diff --git a/doc/CoeffwiseMathFunctionsTable.dox b/doc/CoeffwiseMathFunctionsTable.dox index c466c14c8..ac6e0bd31 100644 --- a/doc/CoeffwiseMathFunctionsTable.dox +++ b/doc/CoeffwiseMathFunctionsTable.dox @@ -3,11 +3,11 @@ namespace Eigen { /** \eigenManualPage CoeffwiseMathFunctions Catalog of coefficient-wise math functions -!WORK IN PROGRESS! + This table presents a catalog of the coefficient-wise math functions supported by %Eigen. In this table, \c a, \c b, refer to Array objects or expressions, and \c m refers to a linear algebra Matrix/Vector object. Standard scalar types are abbreviated as follows: - - \c int: \c ui32 + - \c int: \c i32 - \c float: \c f - \c double: \c d - \c std::complex: \c cf @@ -43,7 +43,35 @@ This also means that, unless specified, if the function \c std::foo is available using std::abs; \n abs(a[i]); - SSE2, AVX (ui32,f,d) + SSE2, AVX (i32,f,d) + + + + \anchor cwisetable_inverse + a.\link ArrayBase::inverse inverse\endlink(); \n + \link Eigen::inverse inverse\endlink(a); \n + m.\link MatrixBase::cwiseInverse cwiseInverse\endlink(); + + inverse value (\f$ 1/a_i \f$) + + 1/a[i]; + + All engines (f,d,fc,fd) + + + + \anchor cwisetable_conj + a.\link ArrayBase::conjugate conjugate\endlink(); \n + \link Eigen::conj conj\endlink(a); \n + m.\link MatrixBase::conjugate conjugate(); + + complex conjugate (\f$ \bar{a_i} \f$),\n + no-op for real + + using std::conj; \n + conj(a[i]); + + All engines (fc,fd) Exponential functions @@ -67,12 +95,12 @@ This also means that, unless specified, if the function \c std::foo is available a.\link ArrayBase::log log\endlink(); \n \link Eigen::log log\endlink(a); - natural (base \f$ e \f$) logarithm (\f$ ln({a_i}) \f$) + natural (base \f$ e \f$) logarithm (\f$ \ln({a_i}) \f$) using std::log; \n log(a[i]); - SSE2, AVX (f,d) + SSE2, AVX (f) @@ -80,23 +108,298 @@ This also means that, unless specified, if the function \c std::foo is available a.\link ArrayBase::log1p log1p\endlink(); \n \link Eigen::log1p log1p\endlink(a); - natural (base \f$ e \f$) logarithm of 1 plus \n the given number (\f$ ln({1+a_i}) \f$) + natural (base \f$ e \f$) logarithm of 1 plus \n the given number (\f$ \ln({1+a_i}) \f$) built-in generic implementation based on \c log,\n plus \c using \c std::log1p ; \cpp11 + + + \anchor cwisetable_log10 + a.\link ArrayBase::log10 log10\endlink(); \n + \link Eigen::log10 log10\endlink(a); + + base 10 logarithm (\f$ \log_{10}({a_i}) \f$) + + using std::log10; \n + log10(a[i]); + + + Power functions + + + \anchor cwisetable_pow + a.\link ArrayBase::pow pow\endlink(b); \n + \link Eigen::pow pow\endlink(a,b); + + raises a number to the given power (\f$ a_i ^ {b_i} \f$) \n \c a and \c b can be either an array or scalar. + + using std::pow; \n + pow(a[i],b[i]);\n + (plus builtin for integer types) + + + + + \anchor cwisetable_sqrt + a.\link ArrayBase::sqrt sqrt\endlink(); \n + \link Eigen::sqrt sqrt\endlink(a);\n + m.\link MatrixBase::cwiseSqrt cwiseSqrt\endlink(); + + computes square root (\f$ \sqrt a_i \f$) + + using std::sqrt; \n + sqrt(a[i]); + SSE2, AVX (f,d) + + + + \anchor cwisetable_rsqrt + a.\link ArrayBase::rsqrt rsqrt\endlink(); \n + \link Eigen::rsqrt rsqrt\endlink(a); + + reciprocal square root (\f$ 1/{\sqrt a_i} \f$) + + using std::sqrt; \n + 1/sqrt(a[i]); \n + + SSE2, AVX, AltiVec, ZVector (f,d)\n + (approx + 1 Newton iteration) + + + + \anchor cwisetable_square + a.\link ArrayBase::square square\endlink(); \n + \link Eigen::square square\endlink(a); + + computes square power (\f$ a_i^2 \f$) + + a[i]*a[i] + All (i32,f,d,cf,cd) + + + + \anchor cwisetable_cube + a.\link ArrayBase::cube cube\endlink(); \n + \link Eigen::cube cube\endlink(a); + + computes cubic power (\f$ a_i^3 \f$) + + a[i]*a[i]*a[i] + All (i32,f,d,cf,cd) + + + + \anchor cwisetable_abs2 + a.\link ArrayBase::abs2 abs2\endlink(); \n + \link Eigen::abs2 abs2\endlink(a);\n + m.\link MatrixBase::cwiseAbs2 cwiseAbs2\endlink(); + + computes the squared absolute value (\f$ |a_i|^2 \f$) + + real: a[i]*a[i] \n + complex: real(a[i])*real(a[i]) \n +        + imag(a[i])*imag(a[i]) + All (i32,f,d) + Trigonometric functions + + + \anchor cwisetable_sin + a.\link ArrayBase::sin sin\endlink(); \n + \link Eigen::sin sin\endlink(a); + + computes sine + + using std::sin; \n + sin(a[i]); + SSE2, AVX (f) + + + + \anchor cwisetable_cos + a.\link ArrayBase::cos cos\endlink(); \n + \link Eigen::cos cos\endlink(a); + + computes cosine + + using std::cos; \n + cos(a[i]); + SSE2, AVX (f) + + + + \anchor cwisetable_tan + a.\link ArrayBase::tan tan\endlink(); \n + \link Eigen::tan tan\endlink(a); + + computes tangent + + using std::tan; \n + tan(a[i]); + + + + + \anchor cwisetable_asin + a.\link ArrayBase::asin asin\endlink(); \n + \link Eigen::asin asin\endlink(a); + + computes arc sine (\f$ \sin^{-1} a_i \f$) + + using std::asin; \n + asin(a[i]); + + + + + \anchor cwisetable_acos + a.\link ArrayBase::acos acos\endlink(); \n + \link Eigen::acos acos\endlink(a); + + computes arc cosine (\f$ \cos^{-1} a_i \f$) + + using std::acos; \n + acos(a[i]); + + + + + \anchor cwisetable_atan + a.\link ArrayBase::atan tan\endlink(); \n + \link Eigen::atan atan\endlink(a); + + computes arc tangent (\f$ \tan^{-1} a_i \f$) + + using std::atan; \n + atan(a[i]); + + Hyperbolic functions + + + \anchor cwisetable_sinh + a.\link ArrayBase::sinh sinh\endlink(); \n + \link Eigen::sinh sinh\endlink(a); + + computes hyperbolic sine + + using std::sinh; \n + sinh(a[i]); + + + + + \anchor cwisetable_cosh + a.\link ArrayBase::cosh cohs\endlink(); \n + \link Eigen::cosh cosh\endlink(a); + + computes hyperbolic cosine + + using std::cosh; \n + cosh(a[i]); + + + + + \anchor cwisetable_tanh + a.\link ArrayBase::tanh tanh\endlink(); \n + \link Eigen::tanh tanh\endlink(a); + + computes hyperbolic tangent + + using std::tanh; \n + tanh(a[i]); + + + +Nearest integer floating point operations + + + + \anchor cwisetable_ceil + a.\link ArrayBase::ceil ceil\endlink(); \n + \link Eigen::ceil ceil\endlink(a); + + nearest integer not less than the given value + + using std::ceil; \n + ceil(a[i]); + SSE4,AVX,ZVector (f,d) + + + + \anchor cwisetable_floor + a.\link ArrayBase::floor floor\endlink(); \n + \link Eigen::floor floor\endlink(a); + + nearest integer not greater than the given value + + using std::floor; \n + floor(a[i]); + SSE4,AVX,ZVector (f,d) + + + + \anchor cwisetable_round + a.\link ArrayBase::round round\endlink(); \n + \link Eigen::round round\endlink(a); + + nearest integer, \n rounding away from zero in halfway cases + built-in generic implementation \n based on \c floor and \c ceil,\n + plus \c using \c std::round ; \cpp11 + SSE4,AVX,ZVector (f,d) + + +Floating point manipulation functions + + +Classification and comparison + + + + \anchor cwisetable_isfinite + a.\link ArrayBase::isfinite isfinite\endlink(); \n + \link Eigen::isfinite isfinite\endlink(a); + + checks if the given number has finite value + built-in generic implementation,\n + plus \c using \c std::isfinite ; \cpp11 + + + + + \anchor cwisetable_isinf + a.\link ArrayBase::isinf isinf\endlink(); \n + \link Eigen::isinf isinf\endlink(a); + + checks if the given number is infinite + built-in generic implementation,\n + plus \c using \c std::isinf ; \cpp11 + + + + + \anchor cwisetable_isnan + a.\link ArrayBase::isnan isnan\endlink(); \n + \link Eigen::isnan isnan\endlink(a); + + checks if the given number is not a number + built-in generic implementation,\n + plus \c using \c std::isnan ; \cpp11 + + Error and gamma functions + Require \c #include \c \anchor cwisetable_erf @@ -124,24 +427,89 @@ This also means that, unless specified, if the function \c std::foo is available -Nearest integer floating point operations + + \anchor cwisetable_lgamma + a.\link ArrayBase::lgamma lgamma\endlink(); \n + \link Eigen::lgamma lgamma\endlink(a); + + natural logarithm of the gamma function + + using std::lgamma; \cpp11 \n + lgamma(a[i]); + + -Floating point manipulation functions + + \anchor cwisetable_digamma + a.\link ArrayBase::digamma digamma\endlink(); \n + \link Eigen::digamma digamma\endlink(a); + + logarithmic derivative of the gamma function + + built-in for float and double + + -Classification and comparison + + \anchor cwisetable_igamma + \link Eigen::igamma igamma\endlink(a,x); + + lower incomplete gamma integral + \n \f$ \gamma(a_i,x_i)= \frac{1}{|a_i|} \int_{0}^{x_i}e^{\text{-}t} t^{a_i-1} \mathrm{d} t \f$ + + built-in for float and double,\n but requires \cpp11 + + -Miscellaneous + + \anchor cwisetable_igammac + \link Eigen::igammac igammac\endlink(a,x); + + upper incomplete gamma integral + \n \f$ \Gamma(a_i,x_i) = \frac{1}{|a_i|} \int_{x_i}^{\infty}e^{\text{-}t} t^{a_i-1} \mathrm{d} t \f$ + + built-in for float and double,\n but requires \cpp11 + + + + +Special functions + + Require \c #include \c + + + \anchor cwisetable_polygamma + \link Eigen::polygamma polygamma\endlink(n,x); + + n-th derivative of digamma at x + + built-in generic based on\n \c lgamma , + \c digamma + and \c zeta . + + + + + + \anchor cwisetable_betainc + \link Eigen::betainc betainc\endlink(a,b,x); + + Incomplete beta function + + built-in for float and double,\n but requires \cpp11 + + \anchor cwisetable_zeta - a.\link ArrayBase::zeta zeta\endlink(b); \n \link Eigen::zeta zeta\endlink(a,b); - Hurwitz zeta function \n \f$ \zeta(a_i,b_i)=\sum_{k=0}^{\infty}(b_i+k)^{\text{-}a_i} \f$ + Hurwitz zeta function + \n \f$ \zeta(a_i,b_i)=\sum_{k=0}^{\infty}(b_i+k)^{\text{-}a_i} \f$ built-in for float and double