Home | History | Annotate | Download | only in doc
      1 namespace Eigen {
      2 
      3 /** \eigenManualPage CoeffwiseMathFunctions Catalog of coefficient-wise math functions
      4 
      5 
      6 <!-- <span style="font-size:300%; color:red; font-weight: 900;">!WORK IN PROGRESS!</span> -->
      7 
      8 This table presents a catalog of the coefficient-wise math functions supported by %Eigen.
      9 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:
     10   - \c int: \c i32
     11   - \c float: \c f
     12   - \c double: \c d
     13   - \c std::complex<float>: \c cf
     14   - \c std::complex<double>: \c cd
     15 
     16 For each row, the first column list the equivalent calls for arrays, and matrices when supported. Of course, all functions are available for matrices by first casting it as an array: \c m.array().
     17 
     18 The third column gives some hints in the underlying scalar implementation. In most cases, %Eigen does not implement itself the math function but relies on the STL for standard scalar types, or user-provided functions for custom scalar types.
     19 For instance, some simply calls the respective function of the STL while preserving <a href="http://en.cppreference.com/w/cpp/language/adl">argument-dependent lookup</a> for custom types.
     20 The following:
     21 \code
     22 using std::foo;
     23 foo(a[i]);
     24 \endcode
     25 means that the STL's function \c std::foo will be potentially called if it is compatible with the underlying scalar type. If not, then the user must ensure that an overload of the function foo is available for the given scalar type (usually defined in the same namespace as the given scalar type).
     26 This also means that, unless specified, if the function \c std::foo is available only in some recent c++ versions (e.g., c++11), then the respective %Eigen's function/method will be usable on standard types only if the compiler support the required c++ version.
     27 
     28 <table class="manual-hl">
     29 <tr>
     30 <th>API</th><th>Description</th><th>Default scalar implementation</th><th>SIMD</th>
     31 </tr>
     32 <tr><td colspan="4"></td></tr>
     33 <tr><th colspan="4">Basic operations</th></tr>
     34 <tr>
     35   <td class="code">
     36   \anchor cwisetable_abs
     37   a.\link ArrayBase::abs abs\endlink(); \n
     38   \link Eigen::abs abs\endlink(a); \n
     39   m.\link MatrixBase::cwiseAbs cwiseAbs\endlink();
     40   </td>
     41   <td>absolute value (\f$ |a_i| \f$) </td>
     42   <td class="code">
     43   using <a href="http://en.cppreference.com/w/cpp/numeric/math/fabs">std::abs</a>; \n
     44   abs(a[i]);
     45   </td>
     46   <td>SSE2, AVX (i32,f,d)</td>
     47 </tr>
     48 <tr>
     49   <td class="code">
     50   \anchor cwisetable_inverse
     51   a.\link ArrayBase::inverse inverse\endlink(); \n
     52   \link Eigen::inverse inverse\endlink(a); \n
     53   m.\link MatrixBase::cwiseInverse cwiseInverse\endlink();
     54   </td>
     55   <td>inverse value (\f$ 1/a_i \f$) </td>
     56   <td class="code">
     57   1/a[i];
     58   </td>
     59   <td>All engines (f,d,fc,fd)</td>
     60 </tr>
     61 <tr>
     62   <td class="code">
     63   \anchor cwisetable_conj
     64   a.\link ArrayBase::conjugate conjugate\endlink(); \n
     65   \link Eigen::conj conj\endlink(a); \n
     66   m.\link MatrixBase::conjugate conjugate();
     67   </td>
     68   <td><a href="https://en.wikipedia.org/wiki/Complex_conjugate">complex conjugate</a> (\f$ \bar{a_i} \f$),\n
     69   no-op for real </td>
     70   <td class="code">
     71   using <a href="http://en.cppreference.com/w/cpp/numeric/complex/conj">std::conj</a>; \n
     72   conj(a[i]);
     73   </td>
     74   <td>All engines (fc,fd)</td>
     75 </tr>
     76 <tr>
     77 <th colspan="4">Exponential functions</th>
     78 </tr>
     79 <tr>
     80   <td class="code">
     81   \anchor cwisetable_exp
     82   a.\link ArrayBase::exp exp\endlink(); \n
     83   \link Eigen::exp exp\endlink(a);
     84   </td>
     85   <td>\f$ e \f$ raised to the given power (\f$ e^{a_i} \f$) </td>
     86   <td class="code">
     87   using <a href="http://en.cppreference.com/w/cpp/numeric/math/exp">std::exp</a>; \n
     88   exp(a[i]);
     89   </td>
     90   <td>SSE2, AVX (f,d)</td>
     91 </tr>
     92 <tr>
     93   <td class="code">
     94   \anchor cwisetable_log
     95   a.\link ArrayBase::log log\endlink(); \n
     96   \link Eigen::log log\endlink(a);
     97   </td>
     98   <td>natural (base \f$ e \f$) logarithm (\f$ \ln({a_i}) \f$)</td>
     99   <td class="code">
    100   using <a href="http://en.cppreference.com/w/cpp/numeric/math/log">std::log</a>; \n
    101   log(a[i]);
    102   </td>
    103   <td>SSE2, AVX (f)</td>
    104 </tr>
    105 <tr>
    106   <td class="code">
    107   \anchor cwisetable_log1p
    108   a.\link ArrayBase::log1p log1p\endlink(); \n
    109   \link Eigen::log1p log1p\endlink(a);
    110   </td>
    111   <td>natural (base \f$ e \f$) logarithm of 1 plus \n the given number (\f$ \ln({1+a_i}) \f$)</td>
    112   <td>built-in generic implementation based on \c log,\n
    113   plus \c using <a href="http://en.cppreference.com/w/cpp/numeric/math/log1p">\c std::log1p </a>; \cpp11</td>
    114   <td></td>
    115 </tr>
    116 <tr>
    117   <td class="code">
    118   \anchor cwisetable_log10
    119   a.\link ArrayBase::log10 log10\endlink(); \n
    120   \link Eigen::log10 log10\endlink(a);
    121   </td>
    122   <td>base 10 logarithm (\f$ \log_{10}({a_i}) \f$)</td>
    123   <td class="code">
    124   using <a href="http://en.cppreference.com/w/cpp/numeric/math/log10">std::log10</a>; \n
    125   log10(a[i]);
    126   </td>
    127   <td></td>
    128 </tr>
    129 <tr>
    130 <th colspan="4">Power functions</th>
    131 </tr>
    132 <tr>
    133   <td class="code">
    134   \anchor cwisetable_pow
    135   a.\link ArrayBase::pow pow\endlink(b); \n
    136   \link Eigen::pow pow\endlink(a,b);
    137   </td>
    138   <td>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.</td>
    139   <td class="code">
    140   using <a href="http://en.cppreference.com/w/cpp/numeric/math/pow">std::pow</a>; \n
    141   pow(a[i],b[i]);\n
    142   (plus builtin for integer types)</td>
    143   <td></td>
    144 </tr>
    145 <tr>
    146   <td class="code">
    147   \anchor cwisetable_sqrt
    148   a.\link ArrayBase::sqrt sqrt\endlink(); \n
    149   \link Eigen::sqrt sqrt\endlink(a);\n
    150   m.\link MatrixBase::cwiseSqrt cwiseSqrt\endlink();
    151   </td>
    152   <td>computes square root (\f$ \sqrt a_i \f$)</td>
    153   <td class="code">
    154   using <a href="http://en.cppreference.com/w/cpp/numeric/math/sqrt">std::sqrt</a>; \n
    155   sqrt(a[i]);</td>
    156   <td>SSE2, AVX (f,d)</td>
    157 </tr>
    158 <tr>
    159   <td class="code">
    160   \anchor cwisetable_rsqrt
    161   a.\link ArrayBase::rsqrt rsqrt\endlink(); \n
    162   \link Eigen::rsqrt rsqrt\endlink(a);
    163   </td>
    164   <td><a href="https://en.wikipedia.org/wiki/Fast_inverse_square_root">reciprocal square root</a> (\f$ 1/{\sqrt a_i} \f$)</td>
    165   <td class="code">
    166   using <a href="http://en.cppreference.com/w/cpp/numeric/math/sqrt">std::sqrt</a>; \n
    167   1/sqrt(a[i]); \n
    168   </td>
    169   <td>SSE2, AVX, AltiVec, ZVector (f,d)\n
    170   (approx + 1 Newton iteration)</td>
    171 </tr>
    172 <tr>
    173   <td class="code">
    174   \anchor cwisetable_square
    175   a.\link ArrayBase::square square\endlink(); \n
    176   \link Eigen::square square\endlink(a);
    177   </td>
    178   <td>computes square power (\f$ a_i^2 \f$)</td>
    179   <td class="code">
    180   a[i]*a[i]</td>
    181   <td>All (i32,f,d,cf,cd)</td>
    182 </tr>
    183 <tr>
    184   <td class="code">
    185   \anchor cwisetable_cube
    186   a.\link ArrayBase::cube cube\endlink(); \n
    187   \link Eigen::cube cube\endlink(a);
    188   </td>
    189   <td>computes cubic power (\f$ a_i^3 \f$)</td>
    190   <td class="code">
    191   a[i]*a[i]*a[i]</td>
    192   <td>All (i32,f,d,cf,cd)</td>
    193 </tr>
    194 <tr>
    195   <td class="code">
    196   \anchor cwisetable_abs2
    197   a.\link ArrayBase::abs2 abs2\endlink(); \n
    198   \link Eigen::abs2 abs2\endlink(a);\n
    199   m.\link MatrixBase::cwiseAbs2 cwiseAbs2\endlink();
    200   </td>
    201   <td>computes the squared absolute value (\f$ |a_i|^2 \f$)</td>
    202   <td class="code">
    203   real:    a[i]*a[i] \n
    204   complex:  real(a[i])*real(a[i]) \n
    205   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; + imag(a[i])*imag(a[i])</td>
    206   <td>All (i32,f,d)</td>
    207 </tr>
    208 <tr>
    209 <th colspan="4">Trigonometric functions</th>
    210 </tr>
    211 <tr>
    212   <td class="code">
    213   \anchor cwisetable_sin
    214   a.\link ArrayBase::sin sin\endlink(); \n
    215   \link Eigen::sin sin\endlink(a);
    216   </td>
    217   <td>computes sine</td>
    218   <td class="code">
    219   using <a href="http://en.cppreference.com/w/cpp/numeric/math/sin">std::sin</a>; \n
    220   sin(a[i]);</td>
    221   <td>SSE2, AVX (f)</td>
    222 </tr>
    223 <tr>
    224   <td class="code">
    225   \anchor cwisetable_cos
    226   a.\link ArrayBase::cos cos\endlink(); \n
    227   \link Eigen::cos cos\endlink(a);
    228   </td>
    229   <td>computes cosine</td>
    230   <td class="code">
    231   using <a href="http://en.cppreference.com/w/cpp/numeric/math/cos">std::cos</a>; \n
    232   cos(a[i]);</td>
    233   <td>SSE2, AVX (f)</td>
    234 </tr>
    235 <tr>
    236   <td class="code">
    237   \anchor cwisetable_tan
    238   a.\link ArrayBase::tan tan\endlink(); \n
    239   \link Eigen::tan tan\endlink(a);
    240   </td>
    241   <td>computes tangent</td>
    242   <td class="code">
    243   using <a href="http://en.cppreference.com/w/cpp/numeric/math/tan">std::tan</a>; \n
    244   tan(a[i]);</td>
    245   <td></td>
    246 </tr>
    247 <tr>
    248   <td class="code">
    249   \anchor cwisetable_asin
    250   a.\link ArrayBase::asin asin\endlink(); \n
    251   \link Eigen::asin asin\endlink(a);
    252   </td>
    253   <td>computes arc sine (\f$ \sin^{-1} a_i \f$)</td>
    254   <td class="code">
    255   using <a href="http://en.cppreference.com/w/cpp/numeric/math/asin">std::asin</a>; \n
    256   asin(a[i]);</td>
    257   <td></td>
    258 </tr>
    259 <tr>
    260   <td class="code">
    261   \anchor cwisetable_acos
    262   a.\link ArrayBase::acos acos\endlink(); \n
    263   \link Eigen::acos acos\endlink(a);
    264   </td>
    265   <td>computes arc cosine  (\f$ \cos^{-1} a_i \f$)</td>
    266   <td class="code">
    267   using <a href="http://en.cppreference.com/w/cpp/numeric/math/acos">std::acos</a>; \n
    268   acos(a[i]);</td>
    269   <td></td>
    270 </tr>
    271 <tr>
    272   <td class="code">
    273   \anchor cwisetable_atan
    274   a.\link ArrayBase::atan tan\endlink(); \n
    275   \link Eigen::atan atan\endlink(a);
    276   </td>
    277   <td>computes arc tangent (\f$ \tan^{-1} a_i \f$)</td>
    278   <td class="code">
    279   using <a href="http://en.cppreference.com/w/cpp/numeric/math/atan">std::atan</a>; \n
    280   atan(a[i]);</td>
    281   <td></td>
    282 </tr>
    283 <tr>
    284 <th colspan="4">Hyperbolic functions</th>
    285 </tr>
    286 <tr>
    287   <td class="code">
    288   \anchor cwisetable_sinh
    289   a.\link ArrayBase::sinh sinh\endlink(); \n
    290   \link Eigen::sinh sinh\endlink(a);
    291   </td>
    292   <td>computes hyperbolic sine</td>
    293   <td class="code">
    294   using <a href="http://en.cppreference.com/w/cpp/numeric/math/sinh">std::sinh</a>; \n
    295   sinh(a[i]);</td>
    296   <td></td>
    297 </tr>
    298 <tr>
    299   <td class="code">
    300   \anchor cwisetable_cosh
    301   a.\link ArrayBase::cosh cohs\endlink(); \n
    302   \link Eigen::cosh cosh\endlink(a);
    303   </td>
    304   <td>computes hyperbolic cosine</td>
    305   <td class="code">
    306   using <a href="http://en.cppreference.com/w/cpp/numeric/math/cosh">std::cosh</a>; \n
    307   cosh(a[i]);</td>
    308   <td></td>
    309 </tr>
    310 <tr>
    311   <td class="code">
    312   \anchor cwisetable_tanh
    313   a.\link ArrayBase::tanh tanh\endlink(); \n
    314   \link Eigen::tanh tanh\endlink(a);
    315   </td>
    316   <td>computes hyperbolic tangent</td>
    317   <td class="code">
    318   using <a href="http://en.cppreference.com/w/cpp/numeric/math/tanh">std::tanh</a>; \n
    319   tanh(a[i]);</td>
    320   <td></td>
    321 </tr>
    322 <tr>
    323 <th colspan="4">Nearest integer floating point operations</th>
    324 </tr>
    325 <tr>
    326   <td class="code">
    327   \anchor cwisetable_ceil
    328   a.\link ArrayBase::ceil ceil\endlink(); \n
    329   \link Eigen::ceil ceil\endlink(a);
    330   </td>
    331   <td>nearest integer not less than the given value</td>
    332   <td class="code">
    333   using <a href="http://en.cppreference.com/w/cpp/numeric/math/ceil">std::ceil</a>; \n
    334   ceil(a[i]);</td>
    335   <td>SSE4,AVX,ZVector (f,d)</td>
    336 </tr>
    337 <tr>
    338   <td class="code">
    339   \anchor cwisetable_floor
    340   a.\link ArrayBase::floor floor\endlink(); \n
    341   \link Eigen::floor floor\endlink(a);
    342   </td>
    343   <td>nearest integer not greater than the given value</td>
    344   <td class="code">
    345   using <a href="http://en.cppreference.com/w/cpp/numeric/math/floor">std::floor</a>; \n
    346   floor(a[i]);</td>
    347   <td>SSE4,AVX,ZVector (f,d)</td>
    348 </tr>
    349 <tr>
    350   <td class="code">
    351   \anchor cwisetable_round
    352   a.\link ArrayBase::round round\endlink(); \n
    353   \link Eigen::round round\endlink(a);
    354   </td>
    355   <td>nearest integer, \n rounding away from zero in halfway cases</td>
    356   <td>built-in generic implementation \n based on \c floor and \c ceil,\n
    357   plus \c using <a href="http://en.cppreference.com/w/cpp/numeric/math/round">\c std::round </a>; \cpp11</td>
    358   <td>SSE4,AVX,ZVector (f,d)</td>
    359 </tr>
    360 <tr>
    361 <th colspan="4">Floating point manipulation functions</th>
    362 </tr>
    363 <tr>
    364 <th colspan="4">Classification and comparison</th>
    365 </tr>
    366 <tr>
    367   <td class="code">
    368   \anchor cwisetable_isfinite
    369   a.\link ArrayBase::isFinite isFinite\endlink(); \n
    370   \link Eigen::isfinite isfinite\endlink(a);
    371   </td>
    372   <td>checks if the given number has finite value</td>
    373   <td>built-in generic implementation,\n
    374   plus \c using <a href="http://en.cppreference.com/w/cpp/numeric/math/isfinite">\c std::isfinite </a>; \cpp11</td>
    375   <td></td>
    376 </tr>
    377 <tr>
    378   <td class="code">
    379   \anchor cwisetable_isinf
    380   a.\link ArrayBase::isInf isInf\endlink(); \n
    381   \link Eigen::isinf isinf\endlink(a);
    382   </td>
    383   <td>checks if the given number is infinite</td>
    384   <td>built-in generic implementation,\n
    385   plus \c using <a href="http://en.cppreference.com/w/cpp/numeric/math/isinf">\c std::isinf </a>; \cpp11</td>
    386   <td></td>
    387 </tr>
    388 <tr>
    389   <td class="code">
    390   \anchor cwisetable_isnan
    391   a.\link ArrayBase::isNaN isNaN\endlink(); \n
    392   \link Eigen::isnan isnan\endlink(a);
    393   </td>
    394   <td>checks if the given number is not a number</td>
    395   <td>built-in generic implementation,\n
    396   plus \c using <a href="http://en.cppreference.com/w/cpp/numeric/math/isnan">\c std::isnan </a>; \cpp11</td>
    397   <td></td>
    398 </tr>
    399 <tr>
    400 <th colspan="4">Error and gamma functions</th>
    401 </tr>
    402 <tr> <td colspan="4">  Require \c \#include \c <unsupported/Eigen/SpecialFunctions> </td></tr>
    403 <tr>
    404   <td class="code">
    405   \anchor cwisetable_erf
    406   a.\link ArrayBase::erf erf\endlink(); \n
    407   \link Eigen::erf erf\endlink(a);
    408   </td>
    409   <td>error function</td>
    410   <td class="code">
    411   using <a href="http://en.cppreference.com/w/cpp/numeric/math/erf">std::erf</a>; \cpp11 \n
    412   erf(a[i]);
    413   </td>
    414   <td></td>
    415 </tr>
    416 <tr>
    417   <td class="code">
    418   \anchor cwisetable_erfc
    419   a.\link ArrayBase::erfc erfc\endlink(); \n
    420   \link Eigen::erfc erfc\endlink(a);
    421   </td>
    422   <td>complementary error function</td>
    423   <td class="code">
    424   using <a href="http://en.cppreference.com/w/cpp/numeric/math/erfc">std::erfc</a>; \cpp11 \n
    425   erfc(a[i]);
    426   </td>
    427   <td></td>
    428 </tr>
    429 <tr>
    430   <td class="code">
    431   \anchor cwisetable_lgamma
    432   a.\link ArrayBase::lgamma lgamma\endlink(); \n
    433   \link Eigen::lgamma lgamma\endlink(a);
    434   </td>
    435   <td>natural logarithm of the gamma function</td>
    436   <td class="code">
    437   using <a href="http://en.cppreference.com/w/cpp/numeric/math/lgamma">std::lgamma</a>; \cpp11 \n
    438   lgamma(a[i]);
    439   </td>
    440   <td></td>
    441 </tr>
    442 <tr>
    443   <td class="code">
    444   \anchor cwisetable_digamma
    445   a.\link ArrayBase::digamma digamma\endlink(); \n
    446   \link Eigen::digamma digamma\endlink(a);
    447   </td>
    448   <td><a href="https://en.wikipedia.org/wiki/Digamma_function">logarithmic derivative of the gamma function</a></td>
    449   <td>
    450   built-in for float and double
    451   </td>
    452   <td></td>
    453 </tr>
    454 <tr>
    455   <td class="code">
    456   \anchor cwisetable_igamma
    457   \link Eigen::igamma igamma\endlink(a,x);
    458   </td>
    459   <td><a href="https://en.wikipedia.org/wiki/Incomplete_gamma_function">lower incomplete gamma integral</a>
    460   \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$</td>
    461   <td>
    462   built-in for float and double,\n but requires \cpp11
    463   </td>
    464   <td></td>
    465 </tr>
    466 <tr>
    467   <td class="code">
    468   \anchor cwisetable_igammac
    469   \link Eigen::igammac igammac\endlink(a,x);
    470   </td>
    471   <td><a href="https://en.wikipedia.org/wiki/Incomplete_gamma_function">upper incomplete gamma integral</a>
    472   \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$</td>
    473   <td>
    474   built-in for float and double,\n but requires \cpp11
    475   </td>
    476   <td></td>
    477 </tr>
    478 <tr>
    479 <th colspan="4">Special functions</th>
    480 </tr>
    481 <tr> <td colspan="4">  Require \c \#include \c <unsupported/Eigen/SpecialFunctions> </td></tr>
    482 <tr>
    483   <td class="code">
    484   \anchor cwisetable_polygamma
    485   \link Eigen::polygamma polygamma\endlink(n,x);
    486   </td>
    487   <td><a href="https://en.wikipedia.org/wiki/Polygamma_function">n-th derivative of digamma at x</a></td>
    488   <td>
    489   built-in generic based on\n <a href="#cwisetable_lgamma">\c lgamma </a>,
    490   <a href="#cwisetable_digamma"> \c digamma </a>
    491   and <a href="#cwisetable_zeta">\c zeta </a>.
    492   </td>
    493   <td></td>
    494 </tr>
    495 <tr>
    496   <td class="code">
    497   \anchor cwisetable_betainc
    498   \link Eigen::betainc betainc\endlink(a,b,x);
    499   </td>
    500   <td><a href="https://en.wikipedia.org/wiki/Beta_function#Incomplete_beta_function">Incomplete beta function</a></td>
    501   <td>
    502   built-in for float and double,\n but requires \cpp11
    503   </td>
    504   <td></td>
    505 </tr>
    506 <tr>
    507   <td class="code">
    508   \anchor cwisetable_zeta
    509   \link Eigen::zeta zeta\endlink(a,b);
    510   </td>
    511   <td><a href="https://en.wikipedia.org/wiki/Hurwitz_zeta_function">Hurwitz zeta function</a>
    512   \n \f$ \zeta(a_i,b_i)=\sum_{k=0}^{\infty}(b_i+k)^{\text{-}a_i} \f$</td>
    513   <td>
    514   built-in for float and double
    515   </td>
    516   <td></td>
    517 </tr>
    518 <tr><td colspan="4"></td></tr>
    519 </table>
    520 
    521 \n
    522 
    523 */
    524 
    525 }
    526