Transcendental Functions (GNU MPFR 4.2.2)
Description: How to install and use GNU MPFR, a library for reliable multiple precision floating-point arithmetic, version 4.2.2.

### 5.7 Transcendental 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 transcendental functions (even more with correct rounding) is expensive, even in small precision, for example the trigonometric and Bessel functions with a large argument. For some functions, the algorithm complexity and memory usage does not depend only on the output precision: for instance, the memory usage of `mpfr_rootn_ui` is also linear in the argument k, and the memory usage of the incomplete Gamma function also depends on the precision of the input op. It is also theoretically possible that some functions on some particular inputs might be very hard to round (i.e. the Table Maker’s Dilemma occurs in much larger precisions than normally expected from the context), meaning that the internal precision needs to be increased even more; but it is conjectured that the needed precision has a reasonable bound (and in particular, that potentially exact cases are known and can be detected efficiently).

Function: `int` mpfr_log `(mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_log_ui `(mpfr_t rop, unsigned long int 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 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)` ¶
Function: `int` mpfr_log2p1 `(mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_log10p1 `(mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)` ¶

  Set rop to the logarithm of one plus op (in radix two for `mpfr_log2p1`, and in radix ten for `mpfr_log10p1`), 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)` ¶
Function: `int` mpfr_exp2m1 `(mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_exp10m1 `(mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)` ¶

  Set rop to the exponential of op followed by a subtraction by one (resp. 2 power of op followed by a subtraction by one, and 10 power of op followed by a subtraction by one), rounded in the direction rnd.

Function: `int` mpfr_pow `(mpfr_t rop, mpfr_t op1, mpfr_t op2, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_powr `(mpfr_t rop, mpfr_t op1, mpfr_t op2, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_pow_ui `(mpfr_t rop, mpfr_t op1, unsigned long int op2, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_pow_si `(mpfr_t rop, mpfr_t op1, long int op2, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_pow_uj `(mpfr_t rop, mpfr_t op1, uintmax_t op2, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_pow_sj `(mpfr_t rop, mpfr_t op1, intmax_t op2, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_pown `(mpfr_t rop, mpfr_t op1, intmax_t op2, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_pow_z `(mpfr_t rop, mpfr_t op1, mpz_t op2, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_ui_pow_ui `(mpfr_t rop, unsigned long int op1, unsigned long int op2, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_ui_pow `(mpfr_t rop, unsigned long int op1, mpfr_t op2, mpfr_rnd_t rnd)` ¶

  Set rop to op1 raised to op2, rounded in the direction rnd. The `mpfr_powr` function corresponds to the `powr` function from IEEE 754, i.e., it computes the exponential of op2 multiplied by the logarithm of op1. The `mpfr_pown` function is just an alias for `mpfr_pow_sj` (defined with `#define mpfr_pown mpfr_pow_sj`), to follow the C2x function `pown`. Special values are handled as described in the ISO C99 and IEEE 754 standards for the `pow` function:

  - `pow(±0, y)` returns ±Inf for y a negative odd integer.
  - `pow(±0, y)` returns +Inf for y negative and not an odd integer.
  - `pow(±0, y)` returns ±0 for y a positive odd integer.
  - `pow(±0, y)` returns +0 for y positive and not an odd integer.
  - `pow(-1, ±Inf)` returns 1.
  - `pow(+1, y)` returns 1 for any y, even a NaN.
  - `pow(x, ±0)` returns 1 for any x, even a NaN.
  - `pow(x, y)` returns NaN for finite negative x and finite non-integer y.
  - `pow(x, -Inf)` returns +Inf for 0 < abs(x) < 1, and +0 for abs(x) > 1.
  - `pow(x, +Inf)` returns +0 for 0 < abs(x) < 1, and +Inf for abs(x) > 1.
  - `pow(-Inf, y)` returns −0 for y a negative odd integer.
  - `pow(-Inf, y)` returns +0 for y negative and not an odd integer.
  - `pow(-Inf, y)` returns −Inf for y a positive odd integer.
  - `pow(-Inf, y)` returns +Inf for y positive and not an odd integer.
  - `pow(+Inf, y)` returns +0 for y negative, and +Inf for y positive.

  Note: When 0 is of integer type, it is regarded as +0 by these functions. We do not use the usual limit rules in this case, as these rules are not used for `pow`.

Function: `int` mpfr_compound_si `(mpfr_t rop, mpfr_t op, long int n, mpfr_rnd_t rnd)` ¶

  Set rop to the power n of one plus op, following IEEE 754 for the special cases and exceptions. In particular:

  - When op < −1, rop is set to NaN.
  - When n is zero and op is NaN (like any value greater or equal to −1), rop is set to 1.
  - When op = −1, rop is set to +Inf for n < 0, and to +0 for n > 0.

  The other special cases follow the usual rules.

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_cosu `(mpfr_t rop, mpfr_t op, unsigned long int u, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_sinu `(mpfr_t rop, mpfr_t op, unsigned long int u, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_tanu `(mpfr_t rop, mpfr_t op, unsigned long int u, mpfr_rnd_t rnd)` ¶

  Set rop to the cosine (resp. sine and tangent) of op multiplied by 2 Pi and divided by u. For example, if u equals 360, one gets the cosine (resp. sine and tangent) for op in degrees. For `mpfr_cosu`, when op multiplied by 2 and divided by u is a half-integer, the result is +0, following IEEE 754 (cosPi), so that the function is even. For `mpfr_sinu`, when op multiplied by 2 and divided by u is an integer, the result is zero with the same sign as op, following IEEE 754 (sinPi), so that the function is odd. Similarly, the function `mpfr_tanu` follows IEEE 754 (tanPi).

Function: `int` mpfr_cospi `(mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_sinpi `(mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_tanpi `(mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)` ¶

  Set rop to the cosine (resp. sine and tangent) of op multiplied by Pi. See the description of `mpfr_sinu`, `mpfr_cosu` and `mpfr_tanu` for special values.

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_acosu `(mpfr_t rop, mpfr_t op, unsigned long int u, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_asinu `(mpfr_t rop, mpfr_t op, unsigned long int u, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_atanu `(mpfr_t rop, mpfr_t op, unsigned long int u, mpfr_rnd_t rnd)` ¶

  Set rop to a multiplied by u and divided by 2 Pi, where a is the arc-cosine (resp. arc-sine and arc-tangent) of op. For example, if u equals 360, `mpfr_acosu` yields the arc-cosine in degrees.

Function: `int` mpfr_acospi `(mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_asinpi `(mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_atanpi `(mpfr_t rop, mpfr_t op, mpfr_rnd_t rnd)` ¶

  Set rop to `acos(op)` (resp. `asin(op)` and `atan(op)`) divided by Pi.

Function: `int` mpfr_atan2 `(mpfr_t rop, mpfr_t y, mpfr_t x, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_atan2u `(mpfr_t rop, mpfr_t y, mpfr_t x, unsigned long int u, mpfr_rnd_t rnd)` ¶
Function: `int` mpfr_atan2pi `(mpfr_t rop, mpfr_t y, mpfr_t x, mpfr_rnd_t rnd)` ¶

  For `mpfr_atan2`, set rop to the arc-tangent2 of y and x, rounded in the direction rnd: if x > 0, then `atan2(y, x)` returns atan(y/x); if x < 0, then `atan2(y, x)` returns the sign of y multiplied by 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. The function `mpfr_atan2u` behaves similarly, except the result is multiplied by u and divided by 2 Pi; and `mpfr_atan2pi` is the same as `mpfr_atan2u` with u = 2. For example, if u equals 360, `mpfr_atan2u` returns the arc-tangent in degrees, with values from −180 to 180.

  `atan2(y, 0)` does not raise any floating-point exception. Special values are handled as described in the ISO C99 and IEEE 754 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_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 the factorial of 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 non-positive integer, set rop to +Inf, following the general rules on special values. When −2k − 1 < op < −2k, k being a non-negative 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 non-positive 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 int 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 int 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 positive or negative 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 int 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_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_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`.