Multiple-precision Complex

gmpy2 adds a multiple-precision complex type called mpc that is based on the MPC library. The context manager settings for mpfr arithmetic are applied to mpc arithmetic by default. It is possible to specifiy different precision and rounding modes for both the real and imaginary components of an mpc.

>>> import gmpy2
>>> from gmpy2 import mpc
>>> gmpy2.sqrt(mpc("1+2j"))
mpc('1.272019649514069+0.78615137775742328j')
>>> gmpy2.get_context(real_prec=100,imag_prec=200)
context(precision=53, real_prec=100, imag_prec=200,
        round=RoundToNearest, real_round=Default, imag_round=Default,
        emax=1073741823, emin=-1073741823,
        subnormalize=False,
        trap_underflow=False, underflow=False,
        trap_overflow=False, overflow=False,
        trap_inexact=False, inexact=True,
        trap_invalid=False, invalid=False,
        trap_erange=False, erange=False,
        trap_divzero=False, divzero=False,
        trap_expbound=False,
        allow_complex=False)
>>> gmpy2.sqrt(mpc("1+2j"))
mpc('1.2720196495140689642524224617376+0.78615137775742328606955858584295892952312205783772323766490213j',(100,200))

Exceptions are normally raised in Python when the result of a real operation is not defined over the reals; for example, sqrt(-4) will raise an exception. The default context in gmpy2 implements the same behavior but by setting allow_complex to True, complex results will be returned.

>>> import gmpy2
>>> from gmpy2 import mpc
>>> gmpy2.sqrt(-4)
mpfr('nan')
>>> gmpy2.get_context(allow_complex=True)
context(precision=53, real_prec=Default, imag_prec=Default,
        round=RoundToNearest, real_round=Default, imag_round=Default,
        emax=1073741823, emin=-1073741823,
        subnormalize=False,
        trap_underflow=False, underflow=False,
        trap_overflow=False, overflow=False,
        trap_inexact=False, inexact=False,
        trap_invalid=False, invalid=True,
        trap_erange=False, erange=False,
        trap_divzero=False, divzero=False,
        trap_expbound=False,
        allow_complex=True)
>>> gmpy2.sqrt(-4)
mpc('0.0+2.0j')

mpc Methods

conjugate()
Returns the complex conjugate.
digits()
Returns a two element tuple where each element represents the real and imaginary components as a 3-tuple containing the mantissa, the exponent, and the number of bits of precision. The mantissa is represented as a string in the specified base with up to ‘prec’ digits. 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.

mpc Attributes

imag
Returns the imaginary component.
precision
Returns a 2-tuple containing the the precision of the real and imaginary components.
rc
Returns a 2-tuple containing the ternary value of the real and imaginary components. The ternary value is 0 if the value of the component is exactly equal to the exact, infinite precision value. If the result code is 1, then the value of the component is greater than the exact value. If the result code is -1, then the value of the component is less than the exact, infinite precision value.
real
Returns the real component.

mpc Functions

acos(...)
acos(x) returns the arc-cosine of x.
acosh(...)
acosh(x) returns the inverse hyperbolic cosine of x.
add(...)
add(x, y) returns x + y. The type of the result is based on the types of the arguments.
asin(...)
asin(x) returns the arc-sine of x.
asinh(...)
asinh(x) return the inverse hyperbolic sine of x.
atan(...)
atan(x) returns the arc-tangent of x.
atanh(...)
atanh(x) returns the inverse hyperbolic tangent of x.
cos(...)
cos(x) seturns the cosine of x.
cosh(...)
cosh(x) returns the hyperbolic cosine of x.
div(...)
div(x, y) returns x / y. The type of the result is based on the types of the arguments.
div_2exp(...)
div_2exp(x, n) returns an ‘mpfr’ or ‘mpc’ divided by 2**n.
exp(...)
exp(x) returns e**x.
fma(...)
fma(x, y, z) returns correctly rounded result of (x * y) + z.
fms(...)
fms(x, y, z) returns correctly rounded result of (x * y) - z.
is_inf(...)
is_inf(x) returns True if either the real or imaginary component of x is Infinity or -Infinity.
is_nan(...)
is_nan(x) returns True if either the real or imaginary component of x is NaN (Not-A-Number).
is_zero(...)
is_zero(x) returns True if x is zero.
log(...)
log(x) returns the natural logarithm of x.
log10(...)
log10(x) returns the base-10 logarithm of x.
mpc(...)

mpc() returns an mpc object set to 0.0+0.0j.

mpc(c[, precision=0]) returns a new ‘mpc’ object from an existing complex number (either a Python complex object or another ‘mpc’ object). If the precision is not specified, then the precision is taken from the current context. The rounding mode is always taken from the current context.

mpc(r[, i=0[, precision=0]]) returns a new ‘mpc’ object by converting two non-complex numbers into the real and imaginary components of an ‘mpc’ object. If the precision is not specified, then the precision is taken from the current context. The rounding mode is always taken from the current context.

mpc(s[, [precision=0[, base=10]]) returns a new ‘mpc’ object by converting a string s into a complex number. If base is omitted, then a base-10 representation is assumed otherwise a base between 2 and 36 can be specified. If the precision is not specified, then the precision is taken from the current context. The rounding mode is always taken from the current context.

In addition to the standard Python string representation of a complex number: "1+2j", the string representation used by the MPC library: "(1 2)" is also supported.

Note

The precision can be specified either a single number that is used for both the real and imaginary components, or as a 2-tuple that can specify different precisions for the real and imaginary components.

mpc_random(...)
mpfc_random(random_state) returns a uniformly distributed number in the unit square [0,1]x[0,1]. The parameter random_state must be created by random_state() first.
mul(...)
mul(x, y) returns x * y. The type of the result is based on the types of the arguments.
mul_2exp(...)
mul_2exp(x, n) returns ‘mpfr’ or ‘mpc’ multiplied by 2**n.
norm(...)
norm(x) returns 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(...)
phase(x) returns the phase angle, also known as argument, of a complex x.
polar(...)
polar(x) returns the polar coordinate form of a complex x that is in rectangular form.
proj(...)
proj(x) returns the projection of a complex x on to the Riemann sphere.
rect(...)
rect(x) returns the polar coordinate form of a complex x that is in rectangular form.
sin(...)
sin(x) returns the sine of x.
sinh(...)
sinh(x) returns the hyberbolic sine of x.
sqrt(...)
sqrt(x) returns the square root of x. If x is integer, rational, or real, then an mpfr will be returned. If x is complex, then an mpc will be returned. If context.allow_complex is True, negative values of x will return an mpc.
square(...)
square(x) returns x * x. The type of the result is based on the types of the arguments.
sub(...)
sub(x, y) returns x - y. The type of the result is based on the types of the arguments.
tan(...)
tan(x) returns the tangent of x. x is measured in radians.
tanh(...)
tanh(x) returns the hyperbolic tangent of x.

mpc Formatting

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

__format__(...)

x.__format__(fmt) returns 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.real_precision.imag_precision
optional rounding mode:
‘U’ -> round toward plus infinity
‘D’ -> round toward minus infinity
‘Z’ -> round toward zero
‘N’ -> round to nearest
optional output style:
‘P’ -> Python style, 1+2j, (default)
‘M’ -> MPC style, (1 2)
optional conversion code:
‘a’,’A’ -> hex format
‘b’ -> binary format
‘e’,’E’ -> scientific format
‘f’,’F’ -> fixed point format
‘g’,’G’ -> fixed or scientific format

Note

The formatting codes must be specified in the order shown above.

>>> import gmpy2
>>> from gmpy2 import mpc
>>> a=gmpy2.sqrt(mpc("1+2j"))
>>> a
mpc('1.272019649514069+0.78615137775742328j')
>>> "{0:.4.4Mf}".format(a)
'(1.2720 0.7862)'
>>> "{0:.4.4f}".format(a)
'1.2720+0.7862j'
>>> "{0:^20.4.4U}".format(a)
'   1.2721+0.7862j   '
>>> "{0:^20.4.4D}".format(a)
'   1.2720+0.7861j   '