Eigen  5.0.1
 
Loading...
Searching...
No Matches
Catalog of coefficient-wise math functions
Dense matrix and array manipulation

This table presents a catalog of the coefficient-wise math functions supported by Eigen. In this table, a, b, refer to Array objects or expressions, and m refers to a linear algebra Matrix/Vector object. Standard scalar types are abbreviated as follows:

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: m.array().

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. For instance, some simply calls the respective function of the STL while preserving argument-dependent lookup for custom types. The following:

using std::foo;
foo(a[i]);

means that the STL's function 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).

APIDescriptionDefault scalar implementationSIMD
Basic operations
a.abs();
abs(a);
m.cwiseAbs(); 		absolute value ( \( |a_i| \)) using std::abs;
abs(a[i]); 		SSE2, AVX (i32,f,d)
a.inverse();
inverse(a);
m.cwiseInverse(); 		inverse value ( \( 1/a_i \)) 1/a[i]; All engines (f,d,fc,fd)
a.conjugate();
conj(a);
m.conjugate(); 		complex conjugate ( \( \bar{a_i} \)),
no-op for real 		using std::conj;
conj(a[i]); 		All engines (fc,fd)
a.arg();
arg(a);
m.cwiseArg(); 		phase angle of complex number using std::arg;
arg(a[i]); 		All engines (fc,fd)
Exponential functions
a.exp();
exp(a); 		\( e \) raised to the given power ( \( e^{a_i} \)) using std::exp;
exp(a[i]); 		SSE2, AVX (f,d)
a.log();
log(a); 		natural (base \( e \)) logarithm ( \( \ln({a_i}) \)) using std::log;
log(a[i]); 		SSE2, AVX (f)
a.log1p();
log1p(a); 		natural (base \( e \)) logarithm of 1 plus
the given number ( \( \ln({1+a_i}) \)) 		built-in generic implementation based on log,
plus using std::log1p
a.log10();
log10(a); 		base 10 logarithm ( \( \log_{10}({a_i}) \)) using std::log10;
log10(a[i]);
a.ldexp(e);
ldexp(a,e); 		multiplies each coefficient by \( 2^{e} \) for an integer e ( \( a_i \cdot 2^{e} \));
exact — the floating-point exponent is adjusted directly, so the result
is correct (including denormals) even when \( 2^{e} \) itself is not representable 		using std::ldexp;
ldexp(a[i],e); 		SSE2, AVX (f,d)
Power functions

a.pow(b);
pow(a,b);

raises a number to the given power ( \( a_i ^ {b_i} \))
a and b can be either an array or scalar. 		using std::pow;
pow(a[i],b[i]);
(plus builtin for integer types)
a.sqrt();
sqrt(a);
m.cwiseSqrt(); 		computes square root ( \( \sqrt a_i \)) using std::sqrt;
sqrt(a[i]); 		SSE2, AVX (f,d)
a.cbrt();
cbrt(a);
m.cwiseCbrt(); 		computes cube root ( \( \sqrt[3]{ a_i }\)) using std::cbrt;
cbrt(a[i]);
a.rsqrt();
rsqrt(a); 		reciprocal square root ( \( 1/{\sqrt a_i} \)) using std::sqrt;
1/sqrt(a[i]);
SSE2, AVX, AltiVec, ZVector (f,d)
(approx + 1 Newton iteration)
a.square();
square(a); 		computes square power ( \( a_i^2 \)) a[i]*a[i] All (i32,f,d,cf,cd)
a.cube();
cube(a); 		computes cubic power ( \( a_i^3 \)) a[i]*a[i]*a[i] All (i32,f,d,cf,cd)
a.abs2();
abs2(a);
m.cwiseAbs2(); 		computes the squared absolute value ( \( |a_i|^2 \)) real: a[i]*a[i]
complex: real(a[i])*real(a[i])
       + imag(a[i])*imag(a[i]) 		All (i32,f,d)
Trigonometric functions
a.sin();
sin(a); 		computes sine using std::sin;
sin(a[i]); 		SSE2, AVX (f)
a.cos();
cos(a); 		computes cosine using std::cos;
cos(a[i]); 		SSE2, AVX (f)
a.tan();
tan(a); 		computes tangent using std::tan;
tan(a[i]);
a.asin();
asin(a); 		computes arc sine ( \( \sin^{-1} a_i \)) using std::asin;
asin(a[i]);
a.acos();
acos(a); 		computes arc cosine ( \( \cos^{-1} a_i \)) using std::acos;
acos(a[i]);
a.atan();
atan(a); 		computes arc tangent ( \( \tan^{-1} a_i \)) using std::atan;
atan(a[i]);
Hyperbolic functions
a.sinh();
sinh(a); 		computes hyperbolic sine using std::sinh;
sinh(a[i]);
a.cohs();
cosh(a); 		computes hyperbolic cosine using std::cosh;
cosh(a[i]);
a.tanh();
tanh(a); 		computes hyperbolic tangent using std::tanh;
tanh(a[i]);
a.asinh();
asinh(a); 		computes inverse hyperbolic sine using std::asinh;
asinh(a[i]);
a.cohs();
acosh(a); 		computes hyperbolic cosine using std::acosh;
acosh(a[i]);
a.atanh();
atanh(a); 		computes hyperbolic tangent using std::atanh;
atanh(a[i]);
Nearest integer floating point operations
a.ceil();
ceil(a); 		nearest integer not less than the given value using std::ceil;
ceil(a[i]); 		SSE4,AVX,ZVector (f,d)
a.floor();
floor(a); 		nearest integer not greater than the given value using std::floor;
floor(a[i]); 		SSE4,AVX,ZVector (f,d)
a.round();
round(a); 		nearest integer,
rounding away from zero in halfway cases 		built-in generic implementation
based on floor and ceil,
plus using std::round 		SSE4,AVX,ZVector (f,d)
a.rint();
rint(a); 		nearest integer,
rounding to nearest even in halfway cases 		built-in generic implementation using std::rint or rintf ; SSE4,AVX (f,d)
Floating point manipulation functions
Classification and comparison
a.isFinite();
isfinite(a); 		checks if the given number has finite value built-in generic implementation,
plus using std::isfinite
a.isInf();
isinf(a); 		checks if the given number is infinite built-in generic implementation,
plus using std::isinf
a.isNaN();
isnan(a); 		checks if the given number is not a number built-in generic implementation,
plus using std::isnan
a.operator<(b);
a.operator<(s); 		coefficient-wise less than comparison ( \( a_i \lt b_i \)).
a and b can be either an array or scalar. 		a[i] < b[i];
a.operator<=(b);
a.operator<=(s); 		coefficient-wise less than or equal comparison ( \( a_i \le b_i \)).
a and b can be either an array or scalar. 		a[i] <= b[i];
a.operator>(b);
a.operator>(s); 		coefficient-wise greater than comparison ( \( a_i \gt b_i \)).
a and b can be either an array or scalar. 		a[i] > b[i];
a.operator>=(b);
a.operator>=(s); 		coefficient-wise greater than or equal comparison ( \( a_i \ge b_i \)).
a and b can be either an array or scalar. 		a[i] >= b[i];
a.operator==(b);
a.operator==(s); 		coefficient-wise equality comparison ( \( a_i = b_i \)).
a and b can be either an array or scalar.
Warning
Performs exact comparison; prefer isApprox() for floating-point types.
a[i] == b[i];
a.operator!=(b);
a.operator!=(s); 		coefficient-wise not-equal comparison ( \( a_i \ne b_i \)).
a and b can be either an array or scalar.
Warning
Performs exact comparison; prefer isApprox() for floating-point types.
a[i] != b[i];
Error and gamma functions
Require #include <contrib/Eigen/SpecialFunctions>
a.erf();
erf(a); 		error function using std::erf
erf(a[i]);
a.erfc();
erfc(a); 		complementary error function using std::erfc
erfc(a[i]);
a.lgamma();
lgamma(a); 		natural logarithm of the gamma function using std::lgamma
lgamma(a[i]);
a.digamma();
digamma(a); 		logarithmic derivative of the gamma function built-in for float and double
igamma(a,x); lower incomplete gamma integral
\( \gamma(a_i,x_i)= \frac{1}{|a_i|} \int_{0}^{x_i}e^{\text{-}t} t^{a_i-1} \mathrm{d} t \) 		built-in for float and double,
built-in generic fallback
igammac(a,x); upper incomplete gamma integral
\( \Gamma(a_i,x_i) = \frac{1}{|a_i|} \int_{x_i}^{\infty}e^{\text{-}t} t^{a_i-1} \mathrm{d} t \) 		built-in for float and double,
built-in generic fallback
Special functions
Require #include <contrib/Eigen/SpecialFunctions>
polygamma(n,x); n-th derivative of digamma at x built-in generic based on
lgamma , digamma and zeta .
betainc(a,b,x); regularized incomplete beta function built-in for float and double,
built-in generic fallback
zeta(a,b);
a.zeta(b); 		Hurwitz zeta function
\( \zeta(a_i,b_i)=\sum_{k=0}^{\infty}(b_i+k)^{\text{-}a_i} \) 		built-in for float and double
a.ndtri();
ndtri(a); 		Inverse of the CDF of the Normal distribution function built-in for float and double


Accuracy of vectorized math functions

The following tables summarize the accuracy of Eigen's vectorized implementations measured in units of ULP (Unit in the Last Place) on an x86-64 system (Intel Xeon, GCC) with SSE2 SIMD target. The reference values were computed using MPFR at 128-bit precision. Float results are exhaustive over all ~4.28 billion finite representable values. Double results sample ~2.88 billion values using a geometric stepping factor of 10-6.

These numbers may differ for other SIMD targets (AVX, AVX512, NEON, SVE, etc.) since each has its own packet math implementations. Functions marked "delegates to std" do not have a custom vectorized implementation for the tested SIMD target — they call the standard library function element-by-element.

The full histograms for each function can be generated with the ulp_accuracy tool in test/ulp_accuracy/.

Float precision

FunctionMax |ULP|Mean |ULP|% ExactNotes
Trigonometric
sin 2 0.087 91.3% 1
cos 2 0.088 91.2% 1
tan 5 0.238 77.3% 1
asin 4 0.726 51.3%
acos 4 0.057 95.0%
atan 4 0.061 94.0%
Hyperbolic
sinh 2 0.017 98.3%
cosh 2 0.004 99.6%
tanh 6 0.030 97.2%
asinh 2 0.145 85.5%
acosh 2 0.057 94.3%
atanh 2 0.004 99.6%
Exponential / Logarithmic
exp 1 0.018 98.2%
exp2 6 0.034 97.3%
expm1 5 0.060 94.6%
log 3 0.120 88.0%
log1p 5 0.134 87.5%
log10 2 0.007 99.3%
log2 5 0.005 99.5%
Error / Special
erf 7 0.332 67.5%
erfc 8 0.010 99.2%
lgamma delegates to std 3
Other
logistic 7 0.040 97.0%
sqrt 0 0.000 100% Uses hardware sqrt
cbrt 2 0.552 49.1%
rsqrt ∞ 0.114 88.2% 4

Double precision

FunctionMax |ULP|Mean |ULP|% ExactNotes
Trigonometric
sin 13,879,755 0.093 93.2% 1
cos 2,024,130 0.043 98.2% 1
tan 13,879,755 0.128 92.7% 1
asin 1 <0.001 >99.9%
acos 1 <0.001 100%
atan 5 0.013 98.8%
Hyperbolic
sinh 2 0.004 99.6%
cosh 2 0.001 99.9%
tanh 8 0.008 99.3%
asinh 2 0.098 90.2%
acosh 2 0.047 95.3%
atanh 2 <0.001 >99.9%
Exponential / Logarithmic
exp 2 0.001 99.9%
exp2 214 0.107 99.6% 2
expm1 3 0.010 99.1%
log 2 0.147 85.3%
log1p 3 0.097 90.6%
log10 2 0.001 99.9%
log2 2 <0.001 99.9%
Error / Special
erf ∞ 0.050 70.5% 5
erfc 11 0.002 99.9%
lgamma delegates to std 3
Other
logistic 3 0.008 99.2%
sqrt 0 0.000 100% Uses hardware sqrt
cbrt 2 0.119 88.1%
rsqrt ∞ 0.135 86.5% 4

Notes

1. sin/cos/tan argument reduction: Eigen's vectorized sin, cos, and tan use a Cody-Waite argument reduction scheme that subtracts multiples of π/2 from the input. For very large arguments (|x| > ~104 in float, |x| > ~10 in double), this reduction loses precision, producing occasional large ULP errors. The mean error remains low because most representable values are small. Applications that need high accuracy for large arguments should perform argument reduction in user code before calling these functions.

2. exp2 double precision: The exp2 implementation for double shows a max error of 214 ULP near the overflow boundary (x ≈ 1022). The mean error is still low (0.107 ULP, 99.6% exact), so the large max error affects only inputs very close to overflow.

3. lgamma: The vectorized lgamma delegates to the standard library function std::lgamma for this SIMD target (SSE2) and therefore has the same accuracy as the platform's C math library.

4. rsqrt max=∞: The infinite max ULP is due to a sign disagreement at a single subnormal input: rsqrt(-0) returns -∞ in Eigen but the MPFR reference produces NaN (rsqrt of a negative value). Ignoring this edge case, the implementation is accurate (< 2 ULP) everywhere else. For float, 16.8 million subnormal negative inputs (0.4%) also produce ±∞ vs NaN. The mean error excluding these outliers is well below 1 ULP.

5. erf double ∞: The vectorized erf for double returns NaN for ±∞ instead of the correct ±1. This produces an infinite max ULP error at a single input value. Excluding ±∞, the max error is 3 ULP and the mean is 0.050 ULP.