Arbitrary Precision Complex Numbers using GNU MPC

Arbitrary Precision Complex Numbers using GNU MPC

This is a binding for the MPC arbitrary-precision floating point library. It is adaptated from real_mpfr.pyx and complex_number.pyx.

We define a class MPComplexField, where each instance of MPComplexField 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.
  • 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.

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

Bases: sage.categories.map.Map

INPUT:

There can be one or two arguments of this init method. If it is one argument, it must be a hom space. If it is two arguments, it must be two parent structures that will be domain and codomain of the map-to-be-created.

TESTS:

sage: from sage.categories.map import Map

Using a hom space:

sage: Map(Hom(QQ, ZZ, Rings()))
Generic map:
  From: Rational Field
  To:   Integer Ring

Using domain and codomain:

sage: Map(QQ['x'], SymmetricGroup(6))
Generic map:
  From: Univariate Polynomial Ring in x over Rational Field
  To:   Symmetric group of order 6! as a permutation group
class sage.rings.complex_mpc.INTEGERtoMPC

Bases: sage.categories.map.Map

INPUT:

There can be one or two arguments of this init method. If it is one argument, it must be a hom space. If it is two arguments, it must be two parent structures that will be domain and codomain of the map-to-be-created.

TESTS:

sage: from sage.categories.map import Map

Using a hom space:

sage: Map(Hom(QQ, ZZ, Rings()))
Generic map:
  From: Rational Field
  To:   Integer Ring

Using domain and codomain:

sage: Map(QQ['x'], SymmetricGroup(6))
Generic map:
  From: Univariate Polynomial Ring in x over Rational Field
  To:   Symmetric group of order 6! as a permutation group
sage.rings.complex_mpc.MPComplexField(prec=53, rnd='RNDNN', names=None)

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

Bases: sage.rings.ring.Field

Initialize self.

INPUT:

  • prec – (integer) precision; default = 53

    prec is the number of bits used to represent the matissa of both the real and imaginary part of complex floating-point number.

  • rnd – (string) the rounding mode; default = 'RNDNN'

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

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

EXAMPLES:

sage: MPComplexField(42).characteristic()
0
gen(n=0)

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

EXAMPLES:

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

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

EXAMPLES:

sage: MPComplexField(42).is_exact()
False
is_finite()

Return False, since the field of complex numbers is not finite.

EXAMPLES:

sage: MPComplexField(17).is_finite()
False
name()

Return the name of the complex field.

EXAMPLES:

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

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

EXAMPLES:

sage: MPComplexField(34).ngens()
1
prec()

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)

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

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

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

EXAMPLES:

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

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

Bases: sage.structure.element.FieldElement

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

agm(right, algorithm='optimal')

Returns the algebraic geometrc 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
algebraic_dependancy(n, **kwds)

Returns a polynomial of degree at most \(n\) which is approximately satisfied by this complex number. Note that the returned polynomial need not be irreducible, and indeed usually won’t be if \(z\) is a good approximation to an algebraic number of degree less than \(n\).

ALGORITHM: Uses the PARI C-library algdep command.

INPUT: Type algdep? at the top level prompt. All additional parameters are passed onto the top-level algdep 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.factor()
(x + 1) * (x^2 - x + 1)^2
sage: z^2 - z + 1
1.11022302462516e-16
algebraic_dependency(n, **kwds)

Returns a polynomial of degree at most \(n\) which is approximately satisfied by this complex number. Note that the returned polynomial need not be irreducible, and indeed usually won’t be if \(z\) is a good approximation to an algebraic number of degree less than \(n\).

ALGORITHM: Uses the PARI C-library algdep command.

INPUT: Type algdep? at the top level prompt. All additional parameters are passed onto the top-level algdep 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.factor()
(x + 1) * (x^2 - x + 1)^2
sage: z^2 - z + 1
1.11022302462516e-16
arccos()

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

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

Return the hyperbolic arccotangent of this complex number.

EXAMPLES:

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

Return the hyperbolic arcsine of this complex number.

EXAMPLES:

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

Return the hyperbolic arcsecant of this complex number.

EXAMPLES:

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

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

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

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

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

The argument (angle) of the complex number, normalized so that \(-\pi < \theta \leq \pi\).

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

Return the complex conjugate of this complex number:

\[\mathrm{conjugate}(a + ib) = a - ib.\]

EXAMPLES:

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

Return the cosine of this complex number:

\[\cos(a + ib) = \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()

Return the hyperbolic cosine of this complex number:

\[\cosh(a + ib) = \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
cotan()

Return the cotangent of this complex number.

EXAMPLES:

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

Return the hyperbolic cotangent of this complex number.

EXAMPLES:

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

Return the cosecent of this complex number.

EXAMPLES:

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

Return the hyperbolic cosecent of this complex number.

EXAMPLES:

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

Return the complex dilogarithm of self.

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

\[Li_2(z) = - \int_0^z \frac{\log|1-\zeta|}{\zeta} d(\zeta) = \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)
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)

Return the value of the Dedekind \(\eta\) function on self, intelligently computed using \(\mathbb{SL}(2,\ZZ)\) transformations.

The \(\eta\) function is

\[\eta(z) = e^{\pi i z / 12} \prod_{n=1}^{\infty}(1-e^{2\pi inz})\]

INPUT:

  • self - element of the upper half plane (if not, raises a ValueError).
  • omit_frac - (bool, default: False), if True, omit the \(e^{\pi 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()

Return the exponential of this complex number:

\[\exp(a + ib) = \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()

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

TESTS:

sage: MPC(0).gamma()
Infinity
sage: MPC(-1).gamma()
Infinity
gamma_inc(t)

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

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

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

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

This function always returns true as \(\CC\) is algebraically closed.

EXAMPLES:

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

\(\CC\) is algebraically closed, hence every element is a square:

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

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

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:

\[\mathrm{norm}(a + ib) = 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)

The \(n\)-th root function.

INPUT:

  • all - bool (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]
parent()

Return the complex field containing the number.

EXAMPLES:

sage: C = MPComplexField()
sage: a = C(1.2456, 987.654)
sage: a.parent()
Complex Field with 53 bits of precision
prec()

Return precision of this complex number.

EXAMPLES:

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

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

Return the secant of this complex number.

EXAMPLES:

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

Return the hyperbolic secant of this complex number.

EXAMPLES:

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

Return the sine of this complex number:

\[\sin(a + ib) = \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()

Return the hyperbolic sine of this complex number:

\[\sinh(a + ib) = \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()

Return the square of a complex number:

\[(a + ib)^2 = (a^2 - b^2) + 2iab.\]

EXAMPLES:

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

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, truncate=True)

Return a string of self.

INPUT:

  • base – base for output
  • truncate – if True, round off the last digits in printing to lessen confusing base-2 roundoff issues.

EXAMPLES:

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

Return the tangent of this complex number:

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

EXAMPLES:

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

Return the hyperbolic tangent of this complex number:

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

EXAMPLES:

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

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

Bases: sage.categories.map.Map

INPUT:

There can be one or two arguments of this init method. If it is one argument, it must be a hom space. If it is two arguments, it must be two parent structures that will be domain and codomain of the map-to-be-created.

TESTS:

sage: from sage.categories.map import Map

Using a hom space:

sage: Map(Hom(QQ, ZZ, Rings()))
Generic map:
  From: Rational Field
  To:   Integer Ring

Using domain and codomain:

sage: Map(QQ['x'], SymmetricGroup(6))
Generic map:
  From: Univariate Polynomial Ring in x over Rational Field
  To:   Symmetric group of order 6! as a permutation group
section()

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

Bases: sage.categories.map.Map

INPUT:

There can be one or two arguments of this init method. If it is one argument, it must be a hom space. If it is two arguments, it must be two parent structures that will be domain and codomain of the map-to-be-created.

TESTS:

sage: from sage.categories.map import Map

Using a hom space:

sage: Map(Hom(QQ, ZZ, Rings()))
Generic map:
  From: Rational Field
  To:   Integer Ring

Using domain and codomain:

sage: Map(QQ['x'], SymmetricGroup(6))
Generic map:
  From: Univariate Polynomial Ring in x over Rational Field
  To:   Symmetric group of order 6! as a permutation group
sage.rings.complex_mpc.late_import()

Import the objects/modules after build (when needed).

TESTS:

sage: sage.rings.complex_mpc.late_import()
sage.rings.complex_mpc.split_complex_string(string, base=10)

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)

Previous topic

Arbitrary Precision Complex Numbers

Next topic

Field of Arbitrary Precision Complex Intervals

This Page