Contexts

context() creates a new context. set_context() will set the active context. get_context() will return a reference to the active context. Note that contexts are mutable: modifying the reference returned by get_context() will modify the active context until a new context is enabled with set_context(). The context.copy() method will return a copy of the context. Contexts that implement the standard single, double, and quadruple precision floating-point types can be created using ieee().

Context Type

class gmpy2.context(**kwargs)

class gmpy2.context(ctx, /, **kwargs)

Return a new context for controlling gmpy2 arithmetic, based either on the default context or on a given by ctx value. Context options additionally can be overridden by keyword arguments.

abs(x, /)

Return abs(x), the context is applied to the result.

acos(x, /)

Return inverse cosine of x; result in radians.

acosh(x, /)

Return inverse hyperbolic cosine of x.

add(x, y, /)

Return x + y.

agm(x, y, /)

Return arithmetic-geometric mean of x and y.

ai(x, /)

Return Airy function of x.

asin(x, /)

Return inverse sine of x; result in radians.

asinh(x, /)

Return inverse hyperbolic sine of x.

atan(x, /)

Return inverse tangent of x; result in radians.

atan2(y, x, /)

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

atanh(x, /)

Return inverse hyperbolic tanget of x.

cbrt(x, /)

Return the cube root of x.

ceil(x, /)

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

check_range(x, /)

Return a new mpfr with exponent that lies within the range of emin and emax specified by context.

clear_flags()

Clear all MPFR exception flags.

const_catalan()

Return the catalan constant using the context’s precision.

const_euler()

Return the euler constant using the context’s precision.

const_log2()

Return the log2 constant using the context’s precision.

const_pi()

Return the constant pi using the context’s precision.

copy()

Return a copy of a context.

cos(x, /)

Return cosine of x; x in radians.

cosh(x, /)

Return hyperbolic cosine of x.

cot(x, /)

Return cotangent of x; x in radians.

coth(x, /)

Return hyperbolic cotangent of x.

csc(x, /)

Return cosecant of x; x in radians.

csch(x, /)

Return hyperbolic cosecant of x.

degrees(x, /)

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

digamma(x, /)

Return digamma of x.

div(x, y, /)

Return x / y; uses true division.

div_2exp(x, n, /)

Return mpfr or mpc divided by 2**n.

divmod(x, y, /)

Return divmod(x, y).

Note: overflow, underflow, and inexact exceptions are not supported for mpfr arguments.

eint(x, /)

Return exponential integral of x.

erf(x, /)

Return error function of x.

erfc(x, /)

Return complementary error function of x.

exp(x, /)

Return the exponential of x.

exp10(x, /)

Return 10**x.

exp2(x, /)

Return 2**x.

expm1(x, /)

Return exp(x) - 1.

factorial(n, /)

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

See fac() to get the exact integer result.

floor(x, /)

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

floor_div(x, y, /)

Return x // y; uses floor division.

fma(x, y, z, /)

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

fmma(x, y, z, t, /)

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

fmms(x, y, z, t, /)

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

fmod(x, y, /)

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

fms(x, y, z, /)

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

frac(x, /)

Return fractional part of x.

frexp(x, /)

Return a tuple containing the exponent and mantissa of x.

fsum(iterable, /)

Return an accurate sum of the values in the iterable.

gamma(x, /)

Return gamma of x.

gamma_inc(a, x, /)

Return (upper) incomplete gamma of a and x.

hypot(x, y, /)

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

is_finite(x, /)

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(x, /)

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(x, /)

Return True if x is an integer; False otherwise.

is_nan(x, /)

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

is_regular(x, /)

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

is_signed(x, /)

Return True if the sign bit of x is set.

is_zero(x, /)

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.

j0(x, /)

Return first kind Bessel function of order 0 of x.

j1(x, /)

Return first kind Bessel function of order 1 of x.

jn(n, x, /)

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

lgamma(x, /)

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

li2(x, /)

Return real part of dilogarithm of x.

lngamma(x, /)

Return natural logarithm of gamma(x).

log(x, /)

Return the natural logarithm of x.

log10(x, /)

Return the base-10 logarithm of x.

log1p(x, /)

Return natural logarithm of (1+x).

log2(x, /)

Return base-2 logarithm of x.

maxnum(x, y, /)

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 specified context. If only one of x or y is a number, then that number is returned.

minnum(x, y, /)

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 specified context. If only one of x or y is a number, then that number is returned.

minus(x, /)

Return -x. The context is applied to the result.

mod(x, y, /)

Return mod(x, y). Note: overflow, underflow, and inexact exceptions are not supported for mpfr arguments.

modf(x, /)

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

mul(x, y, /)

Return x * y.

mul_2exp(x, n, /)

Return mpfr or mpc multiplied by 2**n.

next_above(x, /)

Return the next mpfr from x toward +Infinity.

next_below(x, /)

Return the next mpfr from x toward -Infinity.

next_toward(x, y, /)

Return the next mpfr from x in the direction of y. The result has the same precision as x.

norm(x, /)

Return the norm of a complex x. The norm(x) is defined as x.real**2 + x.imag**2. abs(x) is the square root of norm(x).

phase(x, /)

Return the phase angle, also known as argument, of a complex x.

plus(x, /)

Return +x, the context is applied to the result.

polar(x, /)

Return the polar coordinate form of a complex x that is in rectangular form.

pow(x, y, /)

Return x ** y.

proj(x, /)

Returns the projection of a complex x on to the Riemann sphere.

radians(x, /)

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

rec_sqrt(x, /)

Return the reciprocal of the square root of x.

rect(r, phi, /)

Return the rectangular coordinate form of a complex number that is given in polar form.

reldiff(x, y, /)

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

remainder(x, y, /)

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

remquo(x, y, /)

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

rint(x, /)

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

rint_ceil(x, /)

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

rint_floor(x, /)

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

rint_round(x, /)

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

rint_trunc(x, /)

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

root(x, n, /)

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 context.rootn().

root_of_unity(n, k, /)

Return the n-th root of mpc(1) raised to the k-th power..

rootn(x, n, /)

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

round2(x, n=0, /)

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

round_away(x, /)

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

sec(x, /)

Return secant of x; x in radians.

sech(x, /)

Return hyperbolic secant of x.

sin(x, /)

Return sine of x; x in radians.

sin_cos(x, /)

Return a tuple containing the sine and cosine of x; x in radians.

sinh(x, /)

Return hyperbolic sine of x.

sinh_cosh(x, /)

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

sqrt(x, /)

Return the square root of x.

square(x, /)

Return x * x.

sub(x, y, /)

Return x - y.

tan(x, /)

Return tangent of x; x in radians.

tanh(x, /)

Return hyperbolic tangent of x.

trunc(x, /)

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

y0(x, /)

Return second kind Bessel function of order 0 of x.

y1(x, /)

Return second kind Bessel function of order 1 of x.

yn(n, x, /)

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

zeta(x, /)

Return Riemann zeta of x.

allow_complex

This attribute controls whether or not an mpc result can be returned if an mpfr result would normally not be possible.

allow_release_gil

If set to True, many mpz and mpq computations will release the GIL.

This is considered an experimental feature.

divzero

This flag is not user controllable. It is automatically set if a division by zero occurred and NaN result was returned.

emax

This attribute controls the maximum allowed exponent of an mpfr result, the largest positive value of floating-point variable is (1 - ε)*2**emax, where ε depends on precision of the variable. The maximum exponent is platform dependent and can be retrieved with get_emax_max().

emin

This attribute controls the minimum allowed exponent of an mpfr result, the smallest positive value of a floating-point variable is 0.5*2**emin. The minimum exponent is platform dependent and can be retrieved with get_emin_min().

erange

This flag is not user controllable. It is automatically set if an erange error occurred.

imag_prec

This attribute controls the precision of the imaginary part of an mpc result. If the value is Default, then the value of real_prec is used.

imag_round

This attribute controls the rounding mode for the imaginary part of an mpc result. If the value is Default, then the value of the real_round attribute is used. Note: RoundAwayZero is not a valid rounding mode for mpc.

inexact

This flag is not user controllable. It is automatically set if an inexact result is returned.

invalid

This flag is not user controllable. It is automatically set if an invalid (Not-A-Number) result is returned.

overflow

This flag is not user controllable. It is automatically set if a result overflowed to +/-Infinity and trap_overflow is False.

precision

This attribute controls the precision of an mpfr result. The precision is specified in bits, not decimal digits. The maximum precision that can be specified is platform dependent and can be retrieved with get_max_precision().

Note: Specifying a value for precision that is too close to the maximum precision will cause the MPFR library to fail.

rational_division

If set to True, mpz / mpz will return an mpq instead of an mpfr.

real_prec

This attribute controls the precision of the real part of an mpc result. If the value is Default, then the value of the precision attribute is used.

real_round

This attribute controls the rounding mode for the real part of an mpc result. If the value is Default, then the value of the round attribute is used. Note: RoundAwayZero is not a valid rounding mode for mpc.

round

There are five rounding modes available to mpfr type:

• RoundAwayZero - The result is rounded away from 0.0.

• RoundDown - The result is rounded towards -Infinity.

• RoundToNearest - Round to the nearest value; ties are rounded to an even value.

• RoundToZero - The result is rounded towards 0.0.

• RoundUp - The result is rounded towards +Infinity.

subnormalize

The usual IEEE-754 floating-point representation supports gradual underflow when the minimum exponent is reached. The MFPR library does not enable gradual underflow by default but it can be enabled to precisely mimic the results of IEEE-754 floating-point operations.

trap_divzero

This attribute controls whether or not a DivisionByZeroError exception is raised if division by 0 occurs. The DivisionByZeroError is a sub-class of Python’s ZeroDivisionError.

trap_erange

This attribute controls whether or not a RangeError exception is raised when certain operations are performed on NaN and/or Infinity values. Setting trap_erange to True can be used to raise an exception if comparisons are attempted with a NaN.

trap_inexact

This attribute controls whether or not an InexactResultError exception is raised if an inexact result is returned. To check if the result is greater or less than the exact result, check the rc attribute of the mpfr result.

trap_invalid

This attribute controls whether or not an InvalidOperationError exception is raised if a numerical result is not defined. A special NaN (Not-A-Number) value will be returned if an exception is not raised. The InvalidOperationError is a sub-class of Python’s ValueError.

For example, gmpy2.sqrt(-2) will normally return mpfr(‘nan’). However, if allow_complex is set to True, then an mpc result will be returned.

trap_overflow

If set to False, a result that is larger than the largest possible mpfr given the current exponent range will be replaced by +/-Infinity. If set to True, an OverflowResultError exception is raised.

trap_underflow

If set to False, a result that is smaller than the smallest possible mpfr given the current exponent range will be replaced by +/-0.0. If set to True, an UnderflowResultError exception is raised.

underflow

This flag is not user controllable. It is automatically set if a result underflowed to +/-0.0 and trap_underflow is False.

Context Functions

gmpy2.get_context()

Return a reference to the current context.

gmpy2.ieee(size, /, subnormalize=True)

Return a new context corresponding to a standard IEEE floating-point format. The supported sizes are 16, 32, 64, 128, and multiples of 32 greater than 128.

Note that context.emax/context.emin of the IEEE contexts have different meaning wrt the IEEE 754 standard: emax = e + 1 and emin = 4 - emax - precision, where e - maximum exponent in IEEE terms.

gmpy2.local_context(**kwargs) → context

gmpy2.local_context(context, /, **kwargs) → context

Return a new context for controlling gmpy2 arithmetic, based either on the current context or on a ctx value. Context options additionally can be overridden by keyword arguments.

gmpy2.set_context(context, /)

Activate a context object controlling gmpy2 arithmetic.