Multiple-precision Reals

The mpfr type is based on the MPFR library. The new mpfr type supports correct rounding, selectable rounding modes, and many trigonometric, exponential, and special functions. A context manager is used to control precision, rounding modes, and the behavior of exceptions.

The default precision of an mpfr is 53 bits - the same precision as Python’s float type. If the precision is changed, then mpfr(float('1.2')) differs from mpfr('1.2'). To take advantage of the higher precision provided by the mpfr type, always pass constants as strings.

>>> import gmpy2
>>> from gmpy2 import mpfr
>>> gmpy2.set_context(gmpy2.context())
>>> mpfr('1.2')
mpfr('1.2')
>>> mpfr(float('1.2'))
mpfr('1.2')
>>> gmpy2.get_context().precision=100
>>> mpfr('1.2')
mpfr('1.2000000000000000000000000000006',100)
>>> mpfr(float('1.2'))
mpfr('1.1999999999999999555910790149937',100)

The mpfr type supports the __format__() special method to allow custom output formatting.

>>> from gmpy2 import mpfr
>>> a=mpfr("1.23456")
>>> "{0:15.3f}".format(a)
'          1.235'
>>> "{0:15.3Uf}".format(a)
'          1.235'
>>> "{0:15.3Df}".format(a)
'          1.234'
>>> "{0:.3Df}".format(a)
'1.234'
>>> "{0:+.3Df}".format(a)
'+1.234'

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’ for base<=10, else ‘@’), where 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 ‘-’.

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:

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

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(x, n, /) → mpfr: Return the first kind Bessel function of order n of x.

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_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(x, n, /) → mpfr: Return the second kind Bessel function of order n of x.

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.