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 specify different precision and rounding modes for both the real and imaginary components of an `mpc`.

```>>> import gmpy2
>>> from gmpy2 import mpc
>>> gmpy2.set_context(gmpy2.context())
>>> gmpy2.sqrt(mpc("1+2j"))
mpc('1.272019649514069+0.78615137775742328j')
>>> gmpy2.set_context(gmpy2.context(real_prec=60,imag_prec=70))
>>> gmpy2.get_context()
context(precision=53, real_prec=60, imag_prec=70,
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=False,
trap_erange=False, erange=False,
trap_divzero=False, divzero=False,
allow_complex=False,
rational_division=False,
allow_release_gil=False)
>>> gmpy2.sqrt(mpc("1+2j"))
mpc('1.272019649514068965+0.78615137775742328606947j',(60,70))
>>> gmpy2.set_context(gmpy2.context())
```

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
>>> gmpy2.sqrt(-4)
mpc('0.0+2.0j')
```

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

```>>> 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   '
```

mpc Type

class gmpy2.mpc(c=0, /, precision=0)
class gmpy2.mpc(c=0, /, precision, context)
class gmpy2.mpc(real, /, imag=0, precision=0)
class gmpy2.mpc(real, /, imag, precision, context)
class gmpy2.mpc(s, /, precision=0, base=10)
class gmpy2.mpc(s, /, precision, base, context)

Return a complex floating-point number constructed from a numeric value c or from a pair of two non-complex numbers real and imag or from a string s made of digits in the given base.

A string can be possibly with real-part and/or imaginary-part (that have ‘j’ as a suffix), separated by ‘+’ and parsed the same as the `mpfr` constructor does (but the base must be up to 36).

The precision can be specified by either a single number that is used for both the real and imaginary components, or as a pair of different precisions for the real and imaginary components. For every component, the meaning of its precision value is the same as in the `mpfr` type constructor.

__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

‘+’ -> 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

The default format is ‘f’.

conjugate() mpc

Returns the conjugate of x.

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

Returns up to ‘prec’ digits in the given base. If ‘prec’ is 0, as many digits that are available given c’s precision are returned. ‘base’ must be between 2 and 62. The result consists of 2 three-element tuples that contain the mantissa, exponent, and number of bits of precision of the real and imaginary components.

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_nan() bool

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

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

mpc Functions

gmpy2.acos(x, /)

Return inverse cosine of x; result in radians.

gmpy2.acosh(x, /)

Return inverse hyperbolic cosine of x.

gmpy2.asin(x, /)

Return inverse sine of x; result in radians.

gmpy2.asinh(x, /)

Return inverse hyperbolic sine of x.

gmpy2.atan(x, /)

Return inverse tangent of x; result in radians.

gmpy2.atanh(x, /)

Return inverse hyperbolic tangent of x.

gmpy2.cos(x, /)

Return cosine of x; x in radians.

gmpy2.cosh(x, /)

Return hyperbolic cosine of x.

gmpy2.div_2exp(x, n, /)

Return x divided by 2**n.

gmpy2.exp(x, /)

Return the exponential of x.

gmpy2.is_nan(x, /) bool

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

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

gmpy2.log(x, /)

Return the natural logarithm of x.

gmpy2.log10(x, /)

Return the base-10 logarithm of x.

gmpy2.mpc_random(random_state, /) mpc

Return uniformly distributed number in the unit square [0,1]x[0,1].

gmpy2.mul_2exp(x, n, /)

Return x multiplied by 2**n.

gmpy2.norm(x, /) mpfr

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).

gmpy2.phase(x, /) mpfr

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

gmpy2.polar(x, /)

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

gmpy2.proj(x, /) mpc

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

gmpy2.rect(r, phi, /) mpc

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

gmpy2.root_of_unity(n, k, /) mpc

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

gmpy2.sin(x, /)

Return sine of x; x in radians.

gmpy2.sin_cos(x, /) tuple[mpfr | mpc, mpfr | mpc]

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

gmpy2.sinh(x, /)

Return hyperbolic sine of x.

gmpy2.sqrt(x, /)

Return the square root of x.

gmpy2.tan(x, /)

Return tangent of x; x in radians.

gmpy2.tanh(x, /)

Return hyperbolic tangent of x.