Arbitrary precision floating point complex numbers using GNU MPC¶

This is a binding for the arbitrary-precision floating point library GNU MPC.

We define a class MPComplexField, each instance of which specifies a field of floating-point complex numbers with a specified precision shared by the real and imaginary part and a rounding mode stating the rounding mode directions specific to real and imaginary parts.

Individual floating-point numbers are of class MPComplexNumber.

For floating-point representation and rounding mode description see the documentation for the sage.rings.real_mpfr.

AUTHORS:

Philippe Theveny (2008-10-13): initial version, adapted from sage.rings.real_mpfr and sage.rings.complex_mpfr.
Alex Ghitza (2008-11): cache, generators, random element, and many doctests.
Yann Laigle-Chapuy (2010-01): improves compatibility with CC, updates.
Jeroen Demeyer (2012-02): reformat documentation, make MPC a standard package.
Travis Scrimshaw (2012-10-18): Added doctests for full coverage.
Vincent Klein (2017-11-15) : add __mpc__() to class MPComplexNumber. MPComplexNumber constructor support gmpy2.mpz, gmpy2.mpq, gmpy2.mpfr and gmpy2.mpc parameters.

EXAMPLES:

sage: MPC = MPComplexField(42)
sage: a = MPC(12, '15.64E+32'); a
12.0000000000 + 1.56400000000e33*I
sage: a *a *a *a
5.98338564121e132 - 1.83633318912e101*I
sage: a + 1
13.0000000000 + 1.56400000000e33*I
sage: a / 3
4.00000000000 + 5.21333333333e32*I
sage: MPC("infinity + NaN *I")
+infinity + NaN*I

class sage.rings.complex_mpc.CCtoMPC[source]¶: Bases: Map

class sage.rings.complex_mpc.INTEGERtoMPC[source]¶: Bases: Map

sage.rings.complex_mpc.MPComplexField(prec=53, rnd='RNDNN', names=None)[source]¶

Return the complex field with real and imaginary parts having prec bits of precision.

EXAMPLES:

sage: MPComplexField()
Complex Field with 53 bits of precision
sage: MPComplexField(100)
Complex Field with 100 bits of precision
sage: MPComplexField(100).base_ring()
Real Field with 100 bits of precision
sage: i = MPComplexField(200).gen()
sage: i^2
-1.0000000000000000000000000000000000000000000000000000000000

class sage.rings.complex_mpc.MPComplexField_class[source]¶

Bases: Field

Initialize self.

INPUT:

prec – integer (default: 53); precision

prec is the number of bits used to represent the mantissa of both the real and imaginary part of complex floating-point number.
rnd – string (default: 'RNDNN'); the rounding mode

Rounding mode is of the form 'RNDxy' where x and y are the rounding mode for respectively the real and imaginary parts and are one of:
- 'N' for rounding to nearest
- 'Z' for rounding towards zero
- 'U' for rounding towards plus infinity
- 'D' for rounding towards minus infinity
For example, 'RNDZU' indicates to round the real part towards zero, and the imaginary part towards plus infinity.

EXAMPLES:

sage: MPComplexField(17)
Complex Field with 17 bits of precision
sage: MPComplexField()
Complex Field with 53 bits of precision
sage: MPComplexField(1042,'RNDDZ')
Complex Field with 1042 bits of precision and rounding RNDDZ

ALGORITHMS: Computations are done using the MPC library.

characteristic()[source]¶

Return 0, since the field of complex numbers has characteristic 0.

EXAMPLES:

sage: MPComplexField(42).characteristic()
0

gen(n=0)[source]¶

Return the generator of this complex field over its real subfield.

EXAMPLES:

sage: MPComplexField(34).gen()
1.00000000*I

is_exact()[source]¶

Return whether or not this field is exact, which is always False.

EXAMPLES:

sage: MPComplexField(42).is_exact()
False

name()[source]¶

Return the name of the complex field.

EXAMPLES:

sage: C = MPComplexField(10, 'RNDNZ'); C.name()
'MPComplexField10_RNDNZ'

ngens()[source]¶

Return 1, the number of generators of this complex field over its real subfield.

EXAMPLES:

sage: MPComplexField(34).ngens()
1

prec()[source]¶

Return the precision of this field of complex numbers.

EXAMPLES:

sage: MPComplexField().prec()
53
sage: MPComplexField(22).prec()
22

random_element(min=0, max=1)[source]¶

Return a random complex number, uniformly distributed with real and imaginary parts between min and max (default 0 to 1).

EXAMPLES:

sage: MPComplexField(100).random_element(-5, 10)  # random
1.9305310520925994224072377281 + 0.94745292506956219710477444855*I
sage: MPComplexField(10).random_element()  # random
0.12 + 0.23*I

rounding_mode()[source]¶

Return rounding modes used for each part of a complex number.

EXAMPLES:

sage: MPComplexField().rounding_mode()
'RNDNN'
sage: MPComplexField(rnd='RNDZU').rounding_mode()
'RNDZU'

rounding_mode_imag()[source]¶

Return rounding mode used for the imaginary part of complex number.

EXAMPLES:

sage: MPComplexField(rnd='RNDZU').rounding_mode_imag()
'RNDU'

rounding_mode_real()[source]¶

Return rounding mode used for the real part of complex number.

EXAMPLES:

sage: MPComplexField(rnd='RNDZU').rounding_mode_real()
'RNDZ'

class sage.rings.complex_mpc.MPComplexNumber[source]¶

Bases: FieldElement

A floating point approximation to a complex number using any specified precision common to both real and imaginary part.

agm(right, algorithm='optimal')[source]¶

Return the algebro-geometric mean of self and right.

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(1, 4)
sage: v = MPC(-2,5)
sage: u.agm(v, algorithm='pari')
-0.410522769709397 + 4.60061063922097*I
sage: u.agm(v, algorithm='principal')
1.24010691168158 - 0.472193567796433*I
sage: u.agm(v, algorithm='optimal')
-0.410522769709397 + 4.60061063922097*I

algdep(n, **kwds)[source]¶: alias of algebraic_dependency().

algebraic_dependency(n, **kwds)[source]¶

Return an irreducible polynomial of degree at most $n$ which is approximately satisfied by this complex number.

ALGORITHM: Uses the PARI C-library pari:algdep command.

INPUT: Type algebraic_dependency? at the top level prompt.

All additional parameters are passed onto the top-level algebraic_dependency command.

EXAMPLES:

sage: MPC = MPComplexField()
sage: z = (1/2)*(1 + sqrt(3.0) * MPC.0); z
0.500000000000000 + 0.866025403784439*I
sage: p = z.algebraic_dependency(5)
sage: p
x^2 - x + 1
sage: p(z)
1.11022302462516e-16

arccos()[source]¶

Return the arccosine of this complex number.

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(2, 4)
sage: arccos(u)
1.11692611683177 - 2.19857302792094*I

arccosh()[source]¶

Return the hyperbolic arccos of this complex number.

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(2, 4)
sage: arccosh(u)
2.19857302792094 + 1.11692611683177*I

arccoth()[source]¶

Return the hyperbolic arccotangent of this complex number.

EXAMPLES:

sage: MPC = MPComplexField(100)
sage: MPC(1,1).arccoth()
0.40235947810852509365018983331 - 0.55357435889704525150853273009*I

arccsch()[source]¶

Return the hyperbolic arcsine of this complex number.

EXAMPLES:

sage: MPC = MPComplexField(100)
sage: MPC(1,1).arccsch()
0.53063753095251782601650945811 - 0.45227844715119068206365839783*I

arcsech()[source]¶

Return the hyperbolic arcsecant of this complex number.

EXAMPLES:

sage: MPC = MPComplexField(100)
sage: MPC(1,1).arcsech()
0.53063753095251782601650945811 - 1.1185178796437059371676632938*I

arcsin()[source]¶

Return the arcsine of this complex number.

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(2, 4)
sage: arcsin(u)
0.453870209963122 + 2.19857302792094*I

arcsinh()[source]¶

Return the hyperbolic arcsine of this complex number.

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(2, 4)
sage: arcsinh(u)
2.18358521656456 + 1.09692154883014*I

arctan()[source]¶

Return the arctangent of this complex number.

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(-2, 4)
sage: arctan(u)
-1.46704821357730 + 0.200586618131234*I

arctanh()[source]¶

Return the hyperbolic arctangent of this complex number.

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(2, 4)
sage: arctanh(u)
0.0964156202029962 + 1.37153510396169*I

argument()[source]¶

The argument (angle) of the complex number, normalized so that $- π < θ \leq π$ .

EXAMPLES:

sage: MPC = MPComplexField()
sage: i = MPC.0
sage: (i^2).argument()
3.14159265358979
sage: (1+i).argument()
0.785398163397448
sage: i.argument()
1.57079632679490
sage: (-i).argument()
-1.57079632679490
sage: (RR('-0.001') - i).argument()
-1.57179632646156

conjugate()[source]¶

Return the complex conjugate of this complex number:

conjugate (a + i b) = a - i b .

EXAMPLES:

sage: MPC = MPComplexField()
sage: i = MPC(0, 1)
sage: (1+i).conjugate()
1.00000000000000 - 1.00000000000000*I

cos()[source]¶

Return the cosine of this complex number:

\cos (a + i b) = \cos a \cosh b - i \sin a \sinh b .

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(2, 4)
sage: cos(u)
-11.3642347064011 - 24.8146514856342*I

cosh()[source]¶

Return the hyperbolic cosine of this complex number:

\cosh (a + i b) = \cosh a \cos b + i \sinh a \sin b .

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(2, 4)
sage: cosh(u)
-2.45913521391738 - 2.74481700679215*I

cot()[source]¶

Return the cotangent of this complex number.

EXAMPLES:

sage: MPC = MPComplexField(53)
sage: (1+MPC(I)).cot()
0.217621561854403 - 0.868014142895925*I
sage: i = MPComplexField(200).0
sage: (1+i).cot()
0.21762156185440268136513424360523807352075436916785404091068 - 0.86801414289592494863584920891627388827343874994609327121115*I
sage: i = MPComplexField(220).0
sage: (1+i).cot()
0.21762156185440268136513424360523807352075436916785404091068124239 - 0.86801414289592494863584920891627388827343874994609327121115071646*I

coth()[source]¶

Return the hyperbolic cotangent of this complex number.

EXAMPLES:

sage: MPC = MPComplexField(100)
sage: MPC(1,1).coth()
0.86801414289592494863584920892 - 0.21762156185440268136513424361*I

csc()[source]¶

Return the cosecant of this complex number.

EXAMPLES:

sage: MPC = MPComplexField(100)
sage: MPC(1,1).csc()
0.62151801717042842123490780586 - 0.30393100162842645033448560451*I

csch()[source]¶

Return the hyperbolic cosecant of this complex number.

EXAMPLES:

sage: MPC = MPComplexField(100)
sage: MPC(1,1).csch()
0.30393100162842645033448560451 - 0.62151801717042842123490780586*I

dilog()[source]¶

Return the complex dilogarithm of self.

The complex dilogarithm, or Spence’s function, is defined by

L i_{2} (z) = - \int_{0}^{z} \frac{\log | 1 - ζ |}{ζ} d (ζ) = \sum_{k = 1}^{\infty} \frac{z^{k}}{k^{2}} .

Note that the series definition can only be used for $| z | < 1$ .

EXAMPLES:

sage: MPC = MPComplexField()
sage: a = MPC(1,0)
sage: a.dilog()
1.64493406684823
sage: float(pi^2/6)                                                         # needs sage.symbolic
1.6449340668482262

sage: b = MPC(0,1)
sage: b.dilog()
-0.205616758356028 + 0.915965594177219*I

sage: c = MPC(0,0)
sage: c.dilog()
0

eta(omit_frac=False)[source]¶

Return the value of the Dedekind $η$ function on self, intelligently computed using $SL (2, Z)$ transformations.

The $η$ function is

η (z) = e^{π i z / 12} \prod_{n = 1}^{\infty} (1 - e^{2 π i n z})

INPUT:

self – element of the upper half plane (if not, raises a ValueError)
omit_frac – – boolean (default: False); if True, omit the $e^{π i z / 12}$ factor

OUTPUT: a complex number

ALGORITHM: Uses the PARI C library.

EXAMPLES:

sage: MPC = MPComplexField()
sage: i = MPC.0
sage: z = 1+i; z.eta()
0.742048775836565 + 0.198831370229911*I

exp()[source]¶

Return the exponential of this complex number:

\exp (a + i b) = \exp (a) (\cos b + i \sin b) .

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(2, 4)
sage: exp(u)
-4.82980938326939 - 5.59205609364098*I

gamma()[source]¶

Return the Gamma function evaluated at this complex number.

EXAMPLES:

sage: MPC = MPComplexField(30)
sage: i = MPC.0
sage: (1+i).gamma()
0.49801567 - 0.15494983*I

gamma_inc(t)[source]¶

Return the incomplete Gamma function evaluated at this complex number.

EXAMPLES:

sage: C, i = MPComplexField(30).objgen()
sage: (1+i).gamma_inc(2 + 3*i)  # abs tol 2e-10
0.0020969149 - 0.059981914*I
sage: (1+i).gamma_inc(5)
-0.0013781309 + 0.0065198200*I
sage: C(2).gamma_inc(1 + i)
0.70709210 - 0.42035364*I

imag()[source]¶

Return imaginary part of self.

EXAMPLES:

sage: C = MPComplexField(100)
sage: z = C(2, 3)
sage: x = z.imag(); x
3.0000000000000000000000000000
sage: x.parent()
Real Field with 100 bits of precision

is_imaginary()[source]¶

Return True if self is imaginary, i.e. has real part zero.

EXAMPLES:

sage: C200 = MPComplexField(200)
sage: C200(1.23*i).is_imaginary()
True
sage: C200(1+i).is_imaginary()
False

is_real()[source]¶

Return True if self is real, i.e. has imaginary part zero.

EXAMPLES:

sage: C200 = MPComplexField(200)
sage: C200(1.23).is_real()
True
sage: C200(1+i).is_real()
False

is_square()[source]¶

This function always returns true as $C$ is algebraically closed.

EXAMPLES:

sage: C200 = MPComplexField(200)
sage: a = C200(2,1)
sage: a.is_square()
True

$C$ is algebraically closed, hence every element is a square:

sage: b = C200(5)
sage: b.is_square()
True

log()[source]¶

Return the logarithm of this complex number with the branch cut on the negative real axis:

\log (z) = \log | z | + i \arg (z) .

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(2, 4)
sage: log(u)
1.49786613677700 + 1.10714871779409*I

norm()[source]¶

Return the norm of a complex number, rounded with the rounding mode of the real part. The norm is the square of the absolute value:

norm (a + i b) = a^{2} + b^{2} .

OUTPUT:

A floating-point number in the real field of the real part (same precision, same rounding mode).

EXAMPLES:

This indeed acts as the square function when the imaginary component of self is equal to zero:

sage: MPC = MPComplexField()
sage: a = MPC(2,1)
sage: a.norm()
5.00000000000000
sage: b = MPC(4.2,0)
sage: b.norm()
17.6400000000000
sage: b^2
17.6400000000000

nth_root(n, all=False)[source]¶

The $n$ -th root function.

INPUT:

all – boolean (default: False); if True, return a list of all $n$ -th roots

EXAMPLES:

sage: MPC = MPComplexField()
sage: a = MPC(27)
sage: a.nth_root(3)
3.00000000000000
sage: a.nth_root(3, all=True)
[3.00000000000000, -1.50000000000000 + 2.59807621135332*I, -1.50000000000000 - 2.59807621135332*I]

prec()[source]¶

Return precision of this complex number.

EXAMPLES:

sage: i = MPComplexField(2000).0
sage: i.prec()
2000

real()[source]¶

Return the real part of self.

EXAMPLES:

sage: C = MPComplexField(100)
sage: z = C(2, 3)
sage: x = z.real(); x
2.0000000000000000000000000000
sage: x.parent()
Real Field with 100 bits of precision

sec()[source]¶

Return the secant of this complex number.

EXAMPLES:

sage: MPC = MPComplexField(100)
sage: MPC(1,1).sec()
0.49833703055518678521380589177 + 0.59108384172104504805039169297*I

sech()[source]¶

Return the hyperbolic secant of this complex number.

EXAMPLES:

sage: MPC = MPComplexField(100)
sage: MPC(1,1).sech()
0.49833703055518678521380589177 - 0.59108384172104504805039169297*I

sin()[source]¶

Return the sine of this complex number:

\sin (a + i b) = \sin a \cosh b + i \cos x \sinh b .

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(2, 4)
sage: sin(u)
24.8313058489464 - 11.3566127112182*I

sinh()[source]¶

Return the hyperbolic sine of this complex number:

\sinh (a + i b) = \sinh a \cos b + i \cosh a \sin b .

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(2, 4)
sage: sinh(u)
-2.37067416935200 - 2.84723908684883*I

sqr()[source]¶

Return the square of a complex number:

(a + i b)^{2} = (a^{2} - b^{2}) + 2 i a b .

EXAMPLES:

sage: C = MPComplexField()
sage: a = C(5, 1)
sage: a.sqr()
24.0000000000000 + 10.0000000000000*I

sqrt()[source]¶

Return the square root, taking the branch cut to be the negative real axis:

\sqrt{z} = \sqrt{| z |} (\cos (\arg (z) / 2) + i \sin (\arg (z) / 2)) .

EXAMPLES:

sage: C = MPComplexField()
sage: a = C(24, 10)
sage: a.sqrt()
5.00000000000000 + 1.00000000000000*I

str(base=10, **kwds)[source]¶

Return a string of self.

INPUT:

base – (default: 10) base for output
**kwds – other arguments to pass to the str() method of the real numbers in the real and imaginary parts

EXAMPLES:

sage: MPC = MPComplexField(64)
sage: z = MPC(-4, 3)/7
sage: z.str()
'-0.571428571428571428564 + 0.428571428571428571436*I'
sage: z.str(16)
'-0.92492492492492490 + 0.6db6db6db6db6db70*I'
sage: z.str(truncate=True)
'-0.571428571428571429 + 0.428571428571428571*I'
sage: z.str(2)
'-0.1001001001001001001001001001001001001001001001001001001001001001 + 0.01101101101101101101101101101101101101101101101101101101101101110*I'

tan()[source]¶

Return the tangent of this complex number:

\tan (a + i b) = (\sin 2 a + i \sinh 2 b) / (\cos 2 a + \cosh 2 b) .

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(-2, 4)
sage: tan(u)
0.000507980623470039 + 1.00043851320205*I

tanh()[source]¶

Return the hyperbolic tangent of this complex number:

\tanh (a + i b) = (\sinh 2 a + i \sin 2 b) / (\cosh 2 a + \cos 2 b) .

EXAMPLES:

sage: MPC = MPComplexField()
sage: u = MPC(2, 4)
sage: tanh(u)
1.00468231219024 + 0.0364233692474037*I

zeta()[source]¶

Return the Riemann zeta function evaluated at this complex number.

EXAMPLES:

sage: i = MPComplexField(30).gen()
sage: z = 1 + i
sage: z.zeta()
0.58215806 - 0.92684856*I

class sage.rings.complex_mpc.MPCtoMPC[source]¶

Bases: Map

section()[source]¶

EXAMPLES:

sage: from sage.rings.complex_mpc import *
sage: C10 = MPComplexField(10)
sage: C100 = MPComplexField(100)
sage: f = MPCtoMPC(C100, C10)
sage: f.section()
Generic map:
  From: Complex Field with 10 bits of precision
  To:   Complex Field with 100 bits of precision

class sage.rings.complex_mpc.MPFRtoMPC[source]¶: Bases: Map

sage.rings.complex_mpc.late_import()[source]¶: Import the objects/modules after build (when needed).

sage.rings.complex_mpc.split_complex_string(string, base=10)[source]¶

Split and return in that order the real and imaginary parts of a complex in a string.

This is an internal function.

EXAMPLES:

sage: sage.rings.complex_mpc.split_complex_string('123.456e789')
('123.456e789', None)
sage: sage.rings.complex_mpc.split_complex_string('123.456e789*I')
(None, '123.456e789')
sage: sage.rings.complex_mpc.split_complex_string('123.+456e789*I')
('123.', '+456e789')
sage: sage.rings.complex_mpc.split_complex_string('123.456e789', base=2)
(None, None)