Next: Input and Output Functions, Previous: Comparison Functions, Up: MPFR Interface [Index]

### 5.7 Special Functions

All those functions, except explicitly stated (for example `mpfr_sin_cos`), return a ternary value, i.e., 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 (even more with correct rounding) is expensive, even for small precision, for example the trigonometric and Bessel functions for large argument. For some functions, the memory usage might depend not only on the output precision: it is the case of the `mpfr_rootn_ui` function where the memory usage is also linear in the argument k, and of the incomplete Gamma function (dependence on the precision of op).

Function: int mpfr_log (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_log_ui (mpfr_t rop, unsigned long op, mpfr_rnd_t rnd)
Function: int mpfr_log2 (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_log10 (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)

  Set rop to the natural logarithm of op, log2(op) or log10(op), respectively, rounded in the direction rnd. Set rop to +0 if op is 1 (in all rounding modes), for consistency with the ISO C99 and IEEE 754-2008 standards. Set rop to −Inf if op is ±0 (i.e., the sign of the zero has no influence on the result).

Function: int mpfr_log1p (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)

  Set rop to the logarithm of one plus op, rounded in the direction rnd. Set rop to −Inf if op is −1.

Function: int mpfr_exp (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_exp2 (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_exp10 (mpfr_t rop, mpfr_t op, mpfr_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_expm1 (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)

  Set rop to the exponential of op followed by a subtraction by one, rounded in the direction rnd.

Function: int mpfr_cos (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_sin (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_tan (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)

  Set rop to the cosine of op, sine of op, tangent of op, rounded in the direction rnd.

Function: int mpfr_sin_cos (mpfr_t sop, mpfr_t cop, mpfr_t op, mpfr_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, more precisely it returns s+4c where s=0 if sop is exact, s=1 if sop is larger than the sine of op, s=2 if sop is smaller than the sine of op, and similarly for c and the cosine of op.

Function: int mpfr_sec (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_csc (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_cot (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)

  Set rop to the secant of op, cosecant of op, cotangent of op, rounded in the direction rnd.

Function: int mpfr_acos (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_asin (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_atan (mpfr_t rop, mpfr_t op, mpfr_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)` or for `atan(op)` with large op and small precision of rop.

Function: int mpfr_atan2 (mpfr_t rop, mpfr_t y, mpfr_t x, mpfr_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)))`, thus a number from -Pi to Pi. 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 handled as described in the ISO C99 and IEEE 754-2008 standards for the `atan2` function:

  - `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, mpfr_rnd_t rnd)
Function: int mpfr_sinh (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_tanh (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)

  Set rop to the hyperbolic cosine, sine or tangent of op, rounded in the direction rnd.

Function: int mpfr_sinh_cosh (mpfr_t sop, mpfr_t cop, mpfr_t op, mpfr_rnd_t rnd)

  Set simultaneously sop to the hyperbolic sine of op and cop to the hyperbolic cosine of op, rounded in the direction rnd with the corresponding precision of sop and cop, which must be different variables. Return 0 iff both results are exact (see `mpfr_sin_cos` for a more detailed description of the return value).

Function: int mpfr_sech (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_csch (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_coth (mpfr_t rop, mpfr_t op, mpfr_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, mpfr_rnd_t rnd)
Function: int mpfr_asinh (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_atanh (mpfr_t rop, mpfr_t op, mpfr_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, mpfr_rnd_t rnd)

  Set rop to the factorial of op, rounded in the direction rnd.

Function: int mpfr_eint (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)

  Set rop to the exponential integral of op, rounded in the direction rnd. This is the sum of Euler’s constant, of the logarithm of the absolute value of op, and of the sum for k from 1 to infinity of op to the power k, divided by k and factorial(k). For positive op, it corresponds to the Ei function at op (see formula 5.1.10 from the Handbook of Mathematical Functions from Abramowitz and Stegun), and for negative op, to the opposite of the E1 function (sometimes called eint1) at −op (formula 5.1.1 from the same reference).

Function: int mpfr_li2 (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)

  Set rop to real part of the dilogarithm of op, rounded in the direction rnd. MPFR defines the dilogarithm function as the integral of -log(1-t)/t from 0 to op.

Function: int mpfr_gamma (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_gamma_inc (mpfr_t rop, mpfr_t op, mpfr_t op2, mpfr_rnd_t rnd)

  Set rop to the value of the Gamma function on op, resp. the incomplete Gamma function on op and op2, rounded in the direction rnd. (In the literature, `mpfr_gamma_inc` is called upper incomplete Gamma function, or sometimes complementary incomplete Gamma function.) For `mpfr_gamma` (and `mpfr_gamma_inc` when op2 is zero), when op is a negative integer, rop is set to NaN.

  Note: the current implementation of `mpfr_gamma_inc` is slow for large values of rop or op, in which case some internal overflow might also occur.

Function: int mpfr_lngamma (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)

  Set rop to the value of the logarithm of the Gamma function on op, rounded in the direction rnd. When op is 1 or 2, set rop to +0 (in all rounding modes). When op is an infinity or a nonpositive integer, set rop to +Inf, following the general rules on special values. When −2k−1 < op < −2k, k being a nonnegative integer, set rop to NaN. See also `mpfr_lgamma`.

Function: int mpfr_lgamma (mpfr_t rop, int *signp, mpfr_t op, mpfr_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 1 or 2, set rop to +0 (in all rounding modes). When op is an infinity or a nonpositive integer, set rop to +Inf. 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_digamma (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)

  Set rop to the value of the Digamma (sometimes also called Psi) function on op, rounded in the direction rnd. When op is a negative integer, set rop to NaN.

Function: int mpfr_beta (mpfr_t rop, mpfr_t op1, mpfr_t op2, mpfr_rnd_t rnd)

  Set rop to the value of the Beta function at arguments op1 and op2. Note: the current code does not try to avoid internal overflow or underflow, and might use a huge internal precision in some cases.

Function: int mpfr_zeta (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_zeta_ui (mpfr_t rop, unsigned long op, mpfr_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, mpfr_rnd_t rnd)
Function: int mpfr_erfc (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)

  Set rop to the value of the error function on op (resp. the complementary error function on op) rounded in the direction rnd.

Function: int mpfr_j0 (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_j1 (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_jn (mpfr_t rop, long n, mpfr_t op, mpfr_rnd_t rnd)

  Set rop to the value of the first kind Bessel function of order 0, (resp. 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 set to +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, mpfr_rnd_t rnd)
Function: int mpfr_y1 (mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)
Function: int mpfr_yn (mpfr_t rop, long n, mpfr_t op, mpfr_rnd_t rnd)

  Set rop to the value of the second kind Bessel function of order 0 (resp. 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 set to +0. When op is zero, rop is set to +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, mpfr_rnd_t rnd)
Function: int mpfr_fms (mpfr_t rop, mpfr_t op1, mpfr_t op2, mpfr_t op3, mpfr_rnd_t rnd)

  Set rop to (op1 times op2) + op3 (resp. (op1 times op2) - op3) rounded in the direction rnd. Concerning special values (signed zeros, infinities, NaN), these functions behave like a multiplication followed by a separate addition or subtraction. That is, the fused operation matters only for rounding.

Function: int mpfr_fmma (mpfr_t rop, mpfr_t op1, mpfr_t op2, mpfr_t op3, mpfr_t op4, mpfr_rnd_t rnd)
Function: int mpfr_fmms (mpfr_t rop, mpfr_t op1, mpfr_t op2, mpfr_t op3, mpfr_t op4, mpfr_rnd_t rnd)

  Set rop to (op1 times op2) + (op3 times op4) (resp. (op1 times op2) - (op3 times op4)) rounded in the direction rnd. In case the computation of op1 times op2 overflows or underflows (or that of op3 times op4), the result rop is computed as if the two intermediate products were computed with rounding toward zero.

Function: int mpfr_agm (mpfr_t rop, mpfr_t op1, mpfr_t op2, mpfr_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 and the other one is not zero, set rop to NaN. If any operand is zero and the other one is finite (resp. infinite), set rop to +0 (resp. NaN).

Function: int mpfr_hypot (mpfr_t rop, mpfr_t x, mpfr_t y, mpfr_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 handled as described in the ISO C99 (Section F.9.4.3) and IEEE 754-2008 (Section 9.2.1) standards: If x or y is an infinity, then +Inf is returned in rop, even if the other number is NaN.

Function: int mpfr_ai (mpfr_t rop, mpfr_t x, mpfr_rnd_t rnd)

  Set rop to the value of the Airy function Ai on x, rounded in the direction rnd. When x is NaN, rop is always set to NaN. When x is +Inf or −Inf, rop is +0. The current implementation is not intended to be used with large arguments. It works with abs(x) typically smaller than 500. For larger arguments, other methods should be used and will be implemented in a future version.

Function: int mpfr_const_log2 (mpfr_t rop, mpfr_rnd_t rnd)
Function: int mpfr_const_pi (mpfr_t rop, mpfr_rnd_t rnd)
Function: int mpfr_const_euler (mpfr_t rop, mpfr_rnd_t rnd)
Function: int mpfr_const_catalan (mpfr_t rop, mpfr_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` or `mpfr_free_cache2`.

Function: void mpfr_free_cache (void)

  Free all caches and pools used by MPFR internally (thoses local to the current thread and those shared by all threads). You should call this function before terminating a thread, even if you did not call `mpfr_const_*` functions directly (they could have been called internally).

Function: void mpfr_free_cache2 (mpfr_free_cache_t way)

  Free various caches and pools used by MPFR internally, as specified by way, which is a set of flags:

  - those local to the current thread if flag `MPFR_FREE_LOCAL_CACHE` is set;
  - those shared by all threads if flag `MPFR_FREE_GLOBAL_CACHE` is set.

  The other bits of way are currently ignored and are reserved for future use; they should be zero.

  Note: `mpfr_free_cache2(MPFR_FREE_LOCAL_CACHE|MPFR_FREE_GLOBAL_CACHE)` is currently equivalent to `mpfr_free_cache()`.

Function: void mpfr_free_pool (void)

  Free the pools used by MPFR internally. Note: This function is automatically called after the thread-local caches are freed (with `mpfr_free_cache` or `mpfr_free_cache2`).

Function: int mpfr_mp_memory_cleanup (void)

  This function should be called before calling `mp_set_memory_functions`. See Memory Handling, for more information. Zero is returned in case of success, non-zero in case of error. Errors are currently not possible, but checking the return value is recommended for future compatibility.

Function: int mpfr_sum (mpfr_t rop, const mpfr_ptr tab[], unsigned long int n, mpfr_rnd_t rnd)

  Set rop to the sum of all elements of tab, whose size is n, correctly rounded in the direction rnd. Warning: for efficiency reasons, tab is an array of pointers to `mpfr_t`, not an array of `mpfr_t`. If n = 0, then the result is +0, and if n = 1, then the function is equivalent to `mpfr_set`. For the special exact cases, the result is the same as the one obtained with a succession of additions (`mpfr_add`) in infinite precision. In particular, if the result is an exact zero and n >= 1:

  - if all the inputs have the same sign (i.e., all +0 or all −0), then the result has the same sign as the inputs;
  - otherwise, either because all inputs are zeros with at least a +0 and a −0, or because some inputs are non-zero (but they globally cancel), the result is +0, except for the `MPFR_RNDD` rounding mode, where it is −0.

Next: Input and Output Functions, Previous: Comparison Functions, Up: MPFR Interface [Index]