# Multiple-precision Reals

## mpfr Type

class gmpy2.mpfr(n=0, /, precision=0)
class gmpy2.mpfr(n, /, precision, context)
class gmpy2.mpfr(s, /, precision=0, base=0)
class gmpy2.mpfr(s, /, precision, base, context)

  Return a floating-point number after converting a numeric value n or a string s made of digits in the given base.

  A string can be with fraction-part (with a period as a separator) and/or exponent-part with an exponent marker 'e' or 'E' for bases up to 10, else '@' in any base. In bases 2 and 16, the exponent prefix can also be 'p' or 'P', in which case the exponent indicates a multiplication by a power of 2 instead of the base. The value of an exponent is always written in base 10. The fractional-part digits are parsed the same as the `mpz` type constructor does and both the whole number and exponent-part optionally can be preceded by ‘+’ or ‘-’. Every input, accepted by the `float` type constructor or the `float.fromhex` method is also accepted.

  If a precision greater than or equal to 2 is specified, then it is used. A precision of 0 (the default) implies the precision of either the specified context or the current context is used. A precision of 1 minimizes the loss of precision by following these rules:

  > 1. If n is a radix-2 floating point number, then the full precision of n is retained.

  > 2. If n is an integer, then the precision is the bit length of the integer.

  __format__(fmt) → str

    Return a Python string by formatting 'x' using the format string 'fmt'. A valid format string consists of:

    > optional alignment code:

    > > '<' -> left shifted in field '>' -> right shifted in field '^' -> centered in field

    > optional leading sign code

    > > '+' -> always display leading sign '-' -> only display minus for negative values ' ' -> minus for negative values, space for positive values

    > optional width.precision

    > optional rounding mode:

    > > 'U' -> round toward plus Infinity 'D' -> round toward minus Infinity 'Y' -> round away from zero 'Z' -> round toward zero 'N' -> round to nearest

    > optional conversion code:

    > > 'a','A' -> hex format 'b' -> binary format 'e','E' -> scientific format 'f','F' -> fixed point format 'g','G' -> fixed or float format

    The default format is '.6f'.

  as_integer_ratio() → tuple[mpz, mpz]

    Return the exact rational equivalent of an `mpfr`. Value is a `tuple` for compatibility with Python's `float.as_integer_ratio`.

  as_mantissa_exp() → tuple[mpz, mpz]

    Return the mantissa and exponent of an `mpfr`.

  as_simple_fraction(precision=0) → mpq

    Return a simple rational approximation to x. The result will be accurate to 'precision' bits. If 'precision' is 0, the precision of 'x' will be used.

  conjugate() → mpz

    Return the conjugate of x (which is just a new reference to x since x is not a complex number).

  digits(base=10, prec=0, /) → tuple[str, int, int]

    Returns up to 'prec' digits in the given base. If 'prec' is 0, as many digits that are available are returned. No more digits than available given x's precision are returned. 'base' must be between 2 and 62, inclusive. The result is a three element `tuple` containing the mantissa, the exponent, and the number of bits of precision.

  is_finite() → bool

    Return `True` if x is an actual number (i.e. non NaN or Infinity). If x is an `mpc`, return `True` if both x.real and x.imag are finite.

  is_infinite() → bool

    Return `True` if x is +Infinity or -Infinity. If x is an `mpc`, return `True` if either x.real or x.imag is infinite. Otherwise return `False`.

  is_integer() → bool

    Return `True` if x is an integer; `False` otherwise.

  is_nan() → bool

    Return `True` if x is NaN (Not-A-Number) else `False`.

  is_regular() → bool

    Return `True` if x is not zero, NaN, or Infinity; `False` otherwise.

  is_signed() → bool

    Return `True` if the sign bit of x is set.

  is_zero() → bool

    Return `True` if x is equal to 0. If x is an `mpc`, return `True` if both x.real and x.imag are equal to 0.

  imag

    imaginary component

  precision

    precision in bits

  rc

    return code

  real

    real component

## mpfr Functions

gmpy2.agm(x, y, /) → mpfr

  Return arithmetic-geometric mean of x and y.

gmpy2.ai(x, /) → mpfr

  Return Airy function of x.

gmpy2.atan2(y, x, /) → mpfr

  Return arc-tangent of (y/x); result in radians.

gmpy2.cbrt(x, /) → mpfr

  Return the cube root of x.

gmpy2.ceil(x, /) → mpfr

  Return an 'mpfr' that is the smallest integer >= x.

gmpy2.check_range(x, /) → mpfr

  Return a new `mpfr` with exponent that lies within the current range of emin and emax.

gmpy2.cmp(x, y, /) → int

  Return -1 if x < y; 0 if x = y; or 1 if x > y. Both x and y must be integer, rational or real. Note: 0 is returned (and exception flag set) if either argument is NaN.

gmpy2.const_catalan(precision=0) → mpfr

  Return the catalan constant using the specified precision. If no precision is specified, the default precision is used.

gmpy2.const_euler(precision=0) → mpfr

  Return the euler constant using the specified precision. If no precision is specified, the default precision is used.

gmpy2.const_log2(precision=0) → mpfr

  Return the log2 constant using the specified precision. If no precision is specified, the default precision is used.

gmpy2.const_pi(precision=0) → mpfr

  Return the constant pi using the specified precision. If no precision is specified, the default precision is used.

gmpy2.cot(x, /) → mpfr

  Return cotangent of x; x in radians.

gmpy2.coth(x, /) → mpfr

  Return hyperbolic cotangent of x.

gmpy2.csc(x, /) → mpfr

  Return cosecant of x; x in radians.

gmpy2.csch(x, /) → mpfr

  Return hyperbolic cosecant of x.

gmpy2.degrees(x, /) → mpfr

  Convert angle x from radians to degrees. Note: In rare cases the result may not be correctly rounded.

gmpy2.digamma(x, /) → mpfr

  Return digamma of x.

gmpy2.eint(x, /) → mpfr

  Return exponential integral of x.

gmpy2.erf(x, /) → mpfr

  Return error function of x.

gmpy2.erfc(x, /) → mpfr

  Return complementary error function of x.

gmpy2.exp10(x, /) → mpfr

  Return 10**x.

gmpy2.exp2(x, /) → mpfr

  Return 2**x.

gmpy2.expm1(x, /) → mpfr

  Return exp(x) - 1.

gmpy2.factorial(n, /) → mpfr

  Return the floating-point approximation to the factorial of n.

  See `fac()` to get the exact integer result.

gmpy2.floor(x, /) → mpfr

  Return an `mpfr` that is the largest integer <= x.

gmpy2.fmma(x, y, z, t, /) → mpfr

  Return correctly rounded result of (x * y) + (z + t).

gmpy2.fmms(x, y, z, t, /) → mpfr

  Return correctly rounded result of (x * y) - (z + t).

gmpy2.fmod(x, y, /) → mpfr

  Return x - n*y where n is the integer quotient of x/y, rounded to 0.

gmpy2.frac(x, /) → mpfr

  Return fractional part of x.

gmpy2.frexp(x, /) → tuple[int, mpfr]

  Return a `tuple` containing the exponent and mantissa of x.

gmpy2.fsum(iterable, /) → mpfr

  Return an accurate sum of the values in the iterable.

gmpy2.gamma(x, /) → mpfr

  Return gamma of x.

gmpy2.gamma_inc(a, x, /) → mpfr

  Return (upper) incomplete gamma of a and x.

gmpy2.get_exp(x, /) → int

  Return the exponent of x. Returns 0 for NaN or Infinity and sets the `context.erange` flag of the current context and will raise an exception if `context.trap_erange` is set.

gmpy2.hypot(x, y, /) → mpfr

  Return square root of (x**2 + y**2).

gmpy2.inf(n, /) → mpfr

  Return an `mpfr` initialized to Infinity with the same sign as n. If n is not given, +Infinity is returned.

gmpy2.is_finite(x, /) → bool

  Return `True` if x is an actual number (i.e. non NaN or Infinity). If x is an `mpc`, return `True` if both x.real and x.imag are finite.

gmpy2.is_infinite(x, /) → bool

  Return `True` if x is +Infinity or -Infinity. If x is an `mpc`, return `True` if either x.real or x.imag is infinite. Otherwise return `False`.

gmpy2.is_regular(x, /) → bool

  Return `True` if x is not zero, NaN, or Infinity; `False` otherwise.

gmpy2.is_signed(x, /) → bool

  Return `True` if the sign bit of x is set.

gmpy2.is_unordered(x, y, /) → bool

  Return `True` if either x and/or y is NaN.

gmpy2.j0(x, /) → mpfr

  Return first kind Bessel function of order 0 of x.

gmpy2.j1(x, /) → mpfr

  Return first kind Bessel function of order 1 of x.

gmpy2.jn(n, x, /) → mpfr

  Return the first kind Bessel function of order n of x. Note: the order of the arguments changed in gmpy2 2.2.0a2

gmpy2.lgamma(x, /) → tuple[mpfr, int]

  Return a `tuple` containing the logarithm of the absolute value of gamma(x) and the sign of gamma(x)

gmpy2.li2(x, /) → mpfr

  Return real part of dilogarithm of x.

gmpy2.lngamma(x, /) → mpfr

  Return natural logarithm of gamma(x).

gmpy2.log1p(x, /) → mpfr

  Return natural logarithm of (1+x).

gmpy2.log2(x, /) → mpfr

  Return base-2 logarithm of x.

gmpy2.maxnum(x, y, /) → mpfr

  Return the maximum number of x and y. If x and y are not `mpfr`, they are converted to `mpfr`. The result is rounded to match the current context. If only one of x or y is a number, then that number is returned.

gmpy2.minnum(x, y, /) → mpfr

  Return the minimum number of x and y. If x and y are not `mpfr`, they are converted to `mpfr`. The result is rounded to match the current context. If only one of x or y is a number, then that number is returned.

gmpy2.modf(x, /) → tuple[mpfr, mpfr]

  Return a `tuple` containing the integer and fractional portions of x.

gmpy2.mpfr_from_old_binary(string, /) → mpfr

  Return an `mpfr` from a GMPY 1.x binary mpf format.

gmpy2.mpfr_grandom(random_state, /) → tuple[mpfr, mpfr]

  Return two random numbers with gaussian distribution.

gmpy2.mpfr_nrandom(random_state, /)

  Return a random number with gaussian distribution.

gmpy2.mpfr_random(random_state, /) → mpfr

  Return uniformly distributed number between [0,1].

gmpy2.nan() → mpfr

  Return an `mpfr` initialized to NaN (Not-A-Number).

gmpy2.next_above(x, /) → mpfr

  Return the next `mpfr` from x toward +Infinity.

gmpy2.next_below(x, /) → mpfr

  Return the next `mpfr` from x toward -Infinity.

gmpy2.radians(x, /) → mpfr

  Convert angle x from degrees to radians. Note: In rare cases the result may not be correctly rounded.

gmpy2.rec_sqrt(x, /) → mpfr

  Return the reciprocal of the square root of x.

gmpy2.reldiff(x, y, /) → mpfr

  Return the relative difference between x and y. Result is equal to abs(x-y)/x.

gmpy2.remainder(x, y, /) → mpfr

  Return x - n*y where n is the integer quotient of x/y, rounded to the nearest integer and ties rounded to even.

gmpy2.remquo(x, y, /) → tuple[mpfr, int]

  Return a `tuple` containing the remainder(x,y) and the low bits of the quotient.

gmpy2.rint(x, /) → mpfr

  Return x rounded to the nearest integer using the current rounding mode.

gmpy2.rint_ceil(x, /) → mpfr

  Return x rounded to the nearest integer by first rounding to the next higher or equal integer and then, if needed, using the current rounding mode.

gmpy2.rint_floor(x, /) → mpfr

  Return x rounded to the nearest integer by first rounding to the next lower or equal integer and then, if needed, using the current rounding mode.

gmpy2.rint_round(x, /) → mpfr

  Return x rounded to the nearest integer by first rounding to the nearest integer (ties away from 0) and then, if needed, using the current rounding mode.

gmpy2.rint_trunc(x, /) → mpfr

  Return x rounded to the nearest integer by first rounding towards zero and then, if needed, using the current rounding mode.

gmpy2.root(x, n, /) → mpfr

  Return n-th root of x. The result always an `mpfr`. Note: not IEEE 754-2008 compliant; result differs when x = -0 and n is even. See `rootn()`.

gmpy2.rootn(x, n, /) → mpfr

  Return n-th root of x. The result always an `mpfr`. Note: this is IEEE 754-2008 compliant version of `root()`.

gmpy2.round2(x, n=0, /) → mpfr

  Return x rounded to n bits. Uses default precision if n is not specified. See `round_away()` to access the mpfr_round() function of the MPFR.

gmpy2.round_away(x, /) → mpfr

  Return an `mpfr` that is x rounded to the nearest integer, with ties rounded away from 0.

gmpy2.sec(x, /) → mpfr

  Return secant of x; x in radians.

gmpy2.sech(x, /) → mpfr

  Return hyperbolic secant of x.

gmpy2.set_exp(x, n, /) → mpfr

  Set the exponent of x to n. If n is outside the range of valid exponents, `set_exp()` will set the `context.erange` flag of the current context and either return the original value or raise an exception if `context.trap_erange` is set.

gmpy2.set_sign(x, s, /) → mpfr

  If s is `True`, then return x with the sign bit set.

gmpy2.sign(x, /) → int

  Return -1 if x < 0, 0 if x == 0, or +1 if x >0.

gmpy2.sinh_cosh(x, /) → tuple[mpfr, mpfr]

  Return a `tuple` containing the hyperbolic sine and cosine of x.

gmpy2.trunc(x, /) → mpfr

  Return an `mpfr` that is x truncated towards 0. Same as x.floor() if x>=0 or x.ceil() if x<0.

gmpy2.y0(x, /) → mpfr

  Return second kind Bessel function of order 0 of x.

gmpy2.y1(x, /) → mpfr

  Return second kind Bessel function of order 1 of x.

gmpy2.yn(n, x, /) → mpfr

  Return the second kind Bessel function of order n of x. Note: the order of the arguments changed in gmpy2 2.2.0a2

gmpy2.zero(n, /) → mpfr

  Return an `mpfr` initialized to 0.0 with the same sign as n. If n is not given, +0.0 is returned.

gmpy2.zeta(x, /) → mpfr

  Return Riemann zeta of x.

gmpy2.get_max_precision() → int

  Return the maximum bits of precision that can be used for calculations. Note: to allow extra precision for intermediate calculations, avoid setting precision close the maximum precision.

gmpy2.get_emax_max() → int

  Return the maximum possible exponent that can be set for `mpfr`.

gmpy2.get_emin_min() → int

  Return the minimum possible exponent that can be set for `mpfr`.

gmpy2.copy_sign(x, y, /) → mpfr

  Return an `mpfr` composed of x with the sign of y.

gmpy2.can_round(b, err, rnd1, rnd2, prec, /) → bool

  Let b be an approximation to an unknown number x that is rounded according to rnd1. Assume the b has an error at most two to the power of E(b)-err where E(b) is the exponent of b. Then return `True` if x can be rounded correctly to prec bits with rounding mode rnd2.

gmpy2.free_cache() → None

  Free the internal cache of constants maintained by MPFR.