info mpfr

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.7 Special Functions

All those functions, except explicitly stated, return zero for an exact return value, a positive value for a return value larger than the exact result, and a negative value otherwise.

Important note: in some domains, computing special functions (either with correct or incorrect rounding) is expensive, even for small precision, for example the trigonometric and Bessel functions for large argument.

Function: int mpfr_log (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_log2 (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_log10 (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the natural logarithm of op, log2(op) or log10(op), respectively, rounded in the direction rnd. Return -Inf if op is -0 (i.e. the sign of the zero has no influence on the result).

Function: int mpfr_exp (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_exp2 (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_exp10 (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the exponential of op, to 2 power of op or to 10 power of op, respectively, rounded in the direction rnd.

Function: int mpfr_cos (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_sin (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_tan (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the cosine of op, sine of op, tangent of op, rounded in the direction rnd.

Function: int mpfr_sec (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_csc (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_cot (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the secant of op, cosecant of op, cotangent of op, rounded in the direction rnd.

Function: int mpfr_sin_cos (mpfr_t sop, mpfr_t cop, mpfr_t op, mp_rnd_t rnd): Set simultaneously sop to the sine of op and cop to the cosine of op, rounded in the direction rnd with the corresponding precisions of sop and cop, which must be different variables. Return 0 iff both results are exact.

Function: int mpfr_acos (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_asin (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_atan (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the arc-cosine, arc-sine or arc-tangent of op, rounded in the direction rnd. Note that since acos(-1) returns the floating-point number closest to Pi according to the given rounding mode, this number might not be in the output range 0 <= rop < \pi of the arc-cosine function; still, the result lies in the image of the output range by the rounding function. The same holds for asin(-1), asin(1), atan(-Inf), atan(+Inf).

Function: int mpfr_atan2 (mpfr_t rop, mpfr_t y, mpfr_t x, mp_rnd_t rnd)

Set rop to the arc-tangent2 of y and x, rounded in the direction rnd: if x > 0, atan2(y, x) = atan (y/x); if x < 0, atan2(y, x) = sign(y)*(Pi - atan (abs(y/x))). As for atan, in case the exact mathematical result is +Pi or -Pi, its rounded result might be outside the function output range.

atan2(y, 0) does not raise any floating-point exception. Special values are currently handled as described in the ISO C99 standard for the atan2 function (note this may change in future versions):

atan2(+0, -0) returns +Pi.
atan2(-0, -0) returns -Pi.
atan2(+0, +0) returns +0.
atan2(-0, +0) returns -0.
atan2(+0, x) returns +Pi for x < 0.
atan2(-0, x) returns -Pi for x < 0.
atan2(+0, x) returns +0 for x > 0.
atan2(-0, x) returns -0 for x > 0.
atan2(y, 0) returns -Pi/2 for y < 0.
atan2(y, 0) returns +Pi/2 for y > 0.
atan2(+Inf, -Inf) returns +3*Pi/4.
atan2(-Inf, -Inf) returns -3*Pi/4.
atan2(+Inf, +Inf) returns +Pi/4.
atan2(-Inf, +Inf) returns -Pi/4.
atan2(+Inf, x) returns +Pi/2 for finite x.
atan2(-Inf, x) returns -Pi/2 for finite x.
atan2(y, -Inf) returns +Pi for finite y > 0.
atan2(y, -Inf) returns -Pi for finite y < 0.
atan2(y, +Inf) returns +0 for finite y > 0.
atan2(y, +Inf) returns -0 for finite y < 0.

Function: int mpfr_cosh (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_sinh (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_tanh (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the hyperbolic cosine, sine or tangent of op, rounded in the direction rnd.

Function: int mpfr_sech (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_csch (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_coth (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the hyperbolic secant of op, cosecant of op, cotangent of op, rounded in the direction rnd.

Function: int mpfr_acosh (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_asinh (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_atanh (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the inverse hyperbolic cosine, sine or tangent of op, rounded in the direction rnd.

Function: int mpfr_fac_ui (mpfr_t rop, unsigned long int op, mp_rnd_t rnd): Set rop to the factorial of the unsigned long int op, rounded in the direction rnd.

Function: int mpfr_log1p (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the logarithm of one plus op, rounded in the direction rnd.

Function: int mpfr_expm1 (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the exponential of op minus one, rounded in the direction rnd.

Function: int mpfr_eint (mpfr_t y, mpfr_t x, mp_rnd_t rnd): Set y to the exponential integral of x, rounded in the direction rnd. For positive x, the exponential integral is the sum of Euler's constant, of the logarithm of x, and of the sum for k from 1 to infinity of x to the power k, divided by k and factorial(k). For negative x, the returned value is NaN.

Function: int mpfr_gamma (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the value of the Gamma function on op, rounded in the direction rnd. When op is a negative integer, NaN is returned.

Function: int mpfr_lngamma (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the value of the logarithm of the Gamma function on op, rounded in the direction rnd. When -2k-1 <= x <= -2k, k being a non-negative integer, NaN is returned. See also mpfr_lgamma.

Function: int mpfr_lgamma (mpfr_t rop, int *signp, mpfr_t op, mp_rnd_t rnd): Set rop to the value of the logarithm of the absolute value of the Gamma function on op, rounded in the direction rnd. The sign (1 or -1) of Gamma(op) is returned in the object pointed to by signp. When op is an infinity or a non-positive integer, +Inf is returned. When op is NaN, -Inf or a negative integer, *signp is undefined, and when op is �0, *signp is the sign of the zero.

Function: int mpfr_zeta (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_zeta_ui (mpfr_t rop, unsigned long op, mp_rnd_t rnd): Set rop to the value of the Riemann Zeta function on op, rounded in the direction rnd.

Function: int mpfr_erf (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the value of the error function on op, rounded in the direction rnd.

Function: int mpfr_erfc (mpfr_t rop, mpfr_t op, mp_rnd_t rnd): Set rop to the value of the complementary error function on op, rounded in the direction rnd.

Function: int mpfr_j0 (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_j1 (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_jn (mpfr_t rop, long n, mpfr_t op, mp_rnd_t rnd): Set rop to the value of the first order Bessel function of order 0, 1 and n on op, rounded in the direction rnd. When op is NaN, rop is always set to NaN. When op is plus or minus Infinity, rop is set to +0. When op is zero, and n is not zero, rop is +0 or -0 depending on the parity and sign of n, and the sign of op.

Function: int mpfr_y0 (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_y1 (mpfr_t rop, mpfr_t op, mp_rnd_t rnd)
Function: int mpfr_yn (mpfr_t rop, long n, mpfr_t op, mp_rnd_t rnd): Set rop to the value of the second order Bessel function of order 0, 1 and n on op, rounded in the direction rnd. When op is NaN or negative, rop is always set to NaN. When op is +Inf, rop is +0. When op is zero, rop is +Inf or -Inf depending on the parity and sign of n.

Function: int mpfr_fma (mpfr_t rop, mpfr_t op1, mpfr_t op2, mpfr_t op3, mp_rnd_t rnd): Set rop to (op1 times op2) + op3, rounded in the direction rnd.

Function: int mpfr_fms (mpfr_t rop, mpfr_t op1, mpfr_t op2, mpfr_t op3, mp_rnd_t rnd): Set rop to (op1 times op2) - op3, rounded in the direction rnd.

Function: int mpfr_agm (mpfr_t rop, mpfr_t op1, mpfr_t op2, mp_rnd_t rnd): Set rop to the arithmetic-geometric mean of op1 and op2, rounded in the direction rnd. The arithmetic-geometric mean is the common limit of the sequences u[n] and v[n], where u[0]=op1, v[0]=op2, u[n+1] is the arithmetic mean of u[n] and v[n], and v[n+1] is the geometric mean of u[n] and v[n]. If any operand is negative, the return value is NaN.

Function: int mpfr_hypot (mpfr_t rop, mpfr_t x, mpfr_t y, mp_rnd_t rnd): Set rop to the Euclidean norm of x and y, i.e. the square root of the sum of the squares of x and y, rounded in the direction rnd. Special values are currently handled as described in Section F.9.4.3 of the ISO C99 standard, for the hypot function (note this may change in future versions): If x or y is an infinity, then plus infinity is returned in rop, even if the other number is NaN.

Function: int mpfr_const_log2 (mpfr_t rop, mp_rnd_t rnd)
Function: int mpfr_const_pi (mpfr_t rop, mp_rnd_t rnd)
Function: int mpfr_const_euler (mpfr_t rop, mp_rnd_t rnd)
Function: int mpfr_const_catalan (mpfr_t rop, mp_rnd_t rnd): Set rop to the logarithm of 2, the value of Pi, of Euler's constant 0.577…, of Catalan's constant 0.915…, respectively, rounded in the direction rnd. These functions cache the computed values to avoid other calculations if a lower or equal precision is requested. To free these caches, use mpfr_free_cache.

Function: void mpfr_free_cache (void): Free various caches used by MPFR internally, in particular the caches used by the functions computing constants (currently mpfr_const_log2, mpfr_const_pi, mpfr_const_euler and mpfr_const_catalan). You should call this function before terminating a thread, even if you did not call these functions directly (they could have been called internally).

Function: int mpfr_sum (mpfr_t rop, mpfr_ptr const tab[], unsigned long n, mp_rnd_t rnd): Set ret to the sum of all elements of tab whose size is n, rounded in the direction rnd. Warning, tab is a table of pointers to mpfr_t, not a table of mpfr_t (preliminary interface). The returned int value is zero when the computed value is the exact value, and non-zero when this cannot be guaranteed, without giving the direction of the error as the other functions do.