26.5 Arbitrary Precision Complex Numbers

Module: sage.rings.complex_number

Arbitrary Precision Complex Numbers

Author Log:

Module-level Functions

create_ComplexNumber( )

Return the complex number defined by the strings s_real and s_imag as an element of ComplexField(prec=n), where n potentially has slightly more (controlled by pad) bits than given by s.

Input:

s_real
- a string that defines a real number (or something whose string representation defines a number)
s_imag
- a string that defines a real number (or something whose string representation defines a number)
pad
- an integer >= 0.
min_prec
- number will have at least this many bits of precision, no matter what.

sage: ComplexNumber('2.3')
2.30000000000000
sage: ComplexNumber('2.3','1.1')
2.30000000000000 + 1.10000000000000*I
sage: ComplexNumber(10)
10.0000000000000
sage: ComplexNumber(10,10)
10.0000000000000 + 10.0000000000000*I
sage: ComplexNumber(1.000000000000000000000000000,2)
1.000000000000000000000000000 + 2.000000000000000000000000000*I
sage: ComplexNumber(1,2.000000000000000000000)
1.000000000000000000000 + 2.000000000000000000000*I

sage: sage.rings.complex_number.create_ComplexNumber(s_real=2,s_imag=1)
2.00000000000000 + 1.00000000000000*I

is_ComplexNumber( )

Returns True if x is a complex number. In particular, if x is of the ComplexNumber type.

sage: a = ComplexNumber(1,2); a
1.00000000000000 + 2.00000000000000*I
sage: is_ComplexNumber(a)
True
sage: b = ComplexNumber(1); b
1.00000000000000
sage: is_ComplexNumber(b)
True

Note that the global element I is of type SymbolicConstant. However, elements of the class ComplexField_class are of type ComplexNumber:

sage: c = 1 + 2*I
sage: is_ComplexNumber(c)
False
sage: d = CC(1 + 2*I)
sage: is_ComplexNumber(d)
True

make_ComplexNumber0( )

set_global_complex_round_mode( )

Class: ComplexNumber

class ComplexNumber
A floating point approximation to a complex number using any specified precision. Answers derived from calculations with such approximations may differ from what they would be if those calculations were performed with true complex numbers. This is due to the rounding errors inherent to finite precision calculations.

sage: I = CC.0
sage: b = 1.5 + 2.5*I
sage: loads(b.dumps()) == b
True

Functions: additive_order,$ \,$ agm,$ \,$ algdep,$ \,$ algebraic_dependancy,$ \,$ arccos,$ \,$ arccosh,$ \,$ arcsin,$ \,$ arcsinh,$ \,$ arctan,$ \,$ arctanh,$ \,$ arg,$ \,$ argument,$ \,$ conjugate,$ \,$ cos,$ \,$ cosh,$ \,$ cotan,$ \,$ coth,$ \,$ csch,$ \,$ dilog,$ \,$ eta,$ \,$ exp,$ \,$ gamma,$ \,$ gamma_inc,$ \,$ imag,$ \,$ is_square,$ \,$ log,$ \,$ multiplicative_order,$ \,$ norm,$ \,$ nth_root,$ \,$ prec,$ \,$ real,$ \,$ sech,$ \,$ sin,$ \,$ sinh,$ \,$ sqrt,$ \,$ str,$ \,$ tan,$ \,$ tanh,$ \,$ zeta

additive_order( )

sage: CC(0).additive_order()
1
sage: CC.gen().additive_order()
+Infinity

agm( )

sage: (1+CC(I)).agm(2-I)
1.62780548487271 + 0.136827548397369*I

algdep( )

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.

sage: C = ComplexField()
sage: z = (1/2)*(1 + sqrt(3.0) *C.0); z
0.500000000000000 + 0.866025403784439*I
sage: p = z.algdep(5); p
x^5 + x^2
sage: p.factor()
(x + 1) * x^2 * (x^2 - x + 1)
sage: z^2 - z + 1
1.11022302462516e-16

algebraic_dependancy( )

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.

sage: C = ComplexField()
sage: z = (1/2)*(1 + sqrt(3.0) *C.0); z
0.500000000000000 + 0.866025403784439*I
sage: p = z.algebraic_dependancy(5); p
x^5 + x^2
sage: p.factor()
(x + 1) * x^2 * (x^2 - x + 1)
sage: z^2 - z + 1
1.11022302462516e-16

arccos( )

sage: (1+CC(I)).arccos()
0.904556894302381 - 1.06127506190504*I

arccosh( )

sage: (1+CC(I)).arccosh()
1.06127506190504 + 0.904556894302381*I

arcsin( )

sage: (1+CC(I)).arcsin()
0.666239432492515 + 1.06127506190504*I

arcsinh( )

sage: (1+CC(I)).arcsinh()
1.06127506190504 + 0.666239432492515*I

arctan( )

sage: (1+CC(I)).arctan()
1.01722196789785 + 0.402359478108525*I

arctanh( )

sage: (1+CC(I)).arctanh()
0.402359478108525 + 1.01722196789785*I

arg( )

Same as argument.

sage: i = CC.0
sage: (i^2).arg()
3.14159265358979

argument( )

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

sage: i = CC.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.

sage: i = CC.0
sage: (1+i).conjugate()
1.00000000000000 - 1.00000000000000*I

cos( )

sage: (1+CC(I)).cos()
0.833730025131149 - 0.988897705762865*I

cosh( )

sage: (1+CC(I)).cosh()
0.833730025131149 + 0.988897705762865*I

cotan( )

sage: (1+CC(I)).cotan()
0.217621561854403 - 0.868014142895925*I
sage: i = ComplexField(200).0
sage: (1+i).cotan()
0.21762156185440268136513424360523807352075436916785404091068 -
0.86801414289592494863584920891627388827343874994609327121115*I    
sage: i = ComplexField(220).0
sage: (1+i).cotan()
0.21762156185440268136513424360523807352075436916785404091068124239 -
0.86801414289592494863584920891627388827343874994609327121115071646*I

coth( )

sage: ComplexField(100)(1,1).coth()
0.86801414289592494863584920892 - 0.21762156185440268136513424361*I

csch( )

sage: ComplexField(100)(1,1).csch()
0.30393100162842645033448560451 - 0.62151801717042842123490780586*I

dilog( )

Returns the complex dilogarithm of self. The complex dilogarithm, or Spence's function, is defined by

$ Li_2(z) = - \int_0^z \frac{\log\vert 1-\zeta\vert}{\zeta} d(\zeta)$

$ = \sum_{k=1}^\infty \frac{z^k}{k}$

Note that the series definition can only be used for $ \vert z\vert < 1$

sage: a = ComplexNumber(1,0)
sage: a.dilog()
1.64493406684823
sage: float(pi^2/6)
1.6449340668482264

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

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

eta( )

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

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

The $ \eta$ function is

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

ALGORITHM: Uses the PARI C library.

First we compute $ \eta(1+i)$

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

We compute eta to low precision directly from the definition.

sage: z = 1 + i; z.eta()
0.742048775836565 + 0.198831370229911*I
sage: pi = CC(pi)        # otherwise we will get a symbolic result.
sage: exp(pi * i * z / 12) * prod([1-exp(2*pi*i*n*z) for n in range(1,10)])
0.742048775836565 + 0.198831370229911*I

The optional argument allows us to omit the fractional part:

       sage: z = 1 + i
       sage: z.eta(omit_frac=True)
       0.998129069925959 - 8.12769318938911e-22*I              # 32-bit
       0.998129069925959 - 8.12769318781740e-22*I              # 64-bit
       sage: prod([1-exp(2*pi*i*n*z) for n in range(1,10)])
0.998129069925958 + 4.58475021379830e-19*I              # 32-bit
       0.998129069925958 + 4.58475021314468e-19*I              # 64-bit

We illustrate what happens when $ z$ is not in the upper half plane.

sage: z = CC(1)
sage: z.eta()
Traceback (most recent call last):
...
ValueError: value must be in the upper half plane

You can also use functional notation.

sage: eta(1+CC(I))
0.742048775836565 + 0.198831370229911*I

exp( )

Compute exp(z).

sage: i = ComplexField(300).0
sage: z = 1 + i
sage: z.exp()
1.4686939399158851571389675973266042613269567366290087227976756763109369658
5951213872272450 + 2.287355287178842391208171906700501808955586256668355680
93865811410364716018934540926734485*I

gamma( )

Return the Gamma function evaluated at this complex number.

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

TESTS:

sage: CC(0).gamma()
Infinity

sage: CC(-1).gamma()
Infinity

gamma_inc( )

Return the incomplete Gamma function evaluated at this complex number.

sage: C, i = ComplexField(30).objgen()
sage: (1+i).gamma_inc(2 + 3*i)
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
sage: gamma_inc(2, 1 + i)    
0.70709210 - 0.42035364*I
sage: gamma_inc(2, 5)
0.0404276819945128

imag( )

Return imaginary part of self.

sage: i = ComplexField(100).0
sage: z = 2 + 3*i
sage: x = z.imag(); x
3.0000000000000000000000000000
sage: x.parent()
Real Field with 100 bits of precision

is_square( )

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

sage: a = ComplexNumber(2,1)
sage: a.is_square()
True

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

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

log( )

Complex logarithm of z with branch chosen as follows: Write z = rho*exp(i*theta) with -pi <= theta < pi. Then log(z) = log(rho) + i*theta.

WARNING: Currently the real log is computed using floats, so there is potential precision loss.

sage: a = ComplexNumber(2,1)
sage: a.log()
0.804718956217050 + 0.463647609000806*I
sage: log(a.abs())
0.804718956217050
sage: a.argument()
0.463647609000806

sage: b = ComplexNumber(float(exp(42)),0)
sage: b.log()
41.99999999999971

multiplicative_order( )

Return the multiplicative order of this complex number, if known, or raise a NotImplementedError.

sage: C.<i> = ComplexField()
sage: i.multiplicative_order()
4
sage: C(1).multiplicative_order()
1
sage: C(-1).multiplicative_order()
2
sage: C(i^2).multiplicative_order()
2
sage: C(-i).multiplicative_order()
4
sage: C(2).multiplicative_order()
+Infinity
sage: w = (1+sqrt(-3.0))/2; w
0.500000000000000 + 0.866025403784439*I
sage: abs(w)
1.00000000000000
sage: w.multiplicative_order()
Traceback (most recent call last):
...
NotImplementedError: order of element not known

norm( )

Returns the norm of self.

$ norm(a + bi) = a^2 + b^2$

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

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

nth_root( )

The n-th root function.

Input:

all
- bool (default: False); if True, return a list of all n-th roots.

sage: a = CC(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]
sage: a = ComplexField(20)(2,1)
sage: [r^7 for r in a.nth_root(7, all=True)]
[2.0000 + 1.0000*I, 2.0000 + 1.0000*I, 2.0000 + 1.0000*I, 2.0000 +
1.0000*I, 2.0000 + 1.0000*I, 2.0000 + 1.0000*I, 2.0000 + 1.0000*I]

prec( )

Return precision of this complex number.

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

real( )

Return real part of self.

sage: i = ComplexField(100).0
sage: z = 2 + 3*i
sage: x = z.real(); x
2.0000000000000000000000000000
sage: x.parent()
Real Field with 100 bits of precision

sech( )

sage: ComplexField(100)(1,1).sech()
0.49833703055518678521380589177 - 0.59108384172104504805039169297*I

sin( )

sage: (1+CC(I)).sin()
1.29845758141598 + 0.634963914784736*I

sinh( )

sage: (1+CC(I)).sinh()
0.634963914784736 + 1.29845758141598*I

sqrt( )

The square root function.

Input:

all
- bool (default: False); if True, return a list of all square roots.

sage: C, i = ComplexField(30).objgen()
sage: i.sqrt()
0.70710678 + 0.70710678*I
sage: (1+i).sqrt()
1.0986841 + 0.45508986*I
sage: (C(-1)).sqrt()
1.0000000*I
sage: i = ComplexField(200).0
sage: i.sqrt()
0.70710678118654752440084436210484903928483593768847403658834 +
0.70710678118654752440084436210484903928483593768847403658834*I

str( )

Return a string representation of this number.

INPUTS: base - The base to use for printing (default 10) truncate - (default: True) Whether to print fewer digits than are available, to mask errors in the last bits.

sage: a = CC(pi + I*e)
sage: a.str()
'3.14159265358979 + 2.71828182845905*I'
sage: a.str(truncate=False)
'3.1415926535897931 + 2.7182818284590451*I'
sage: a.str(base=2)
'11.001001000011111101101010100010001000010110100011000 +
10.101101111110000101010001011000101000101011101101001*I'
sage: CC(0.5 + 0.625*I).str(base=2)
'0.10000000000000000000000000000000000000000000000000000 +
0.10100000000000000000000000000000000000000000000000000*I'
sage: a.str(base=16)
'3.243f6a8885a30 + 2.b7e151628aed2*I'
sage: a.str(base=36)
'3.53i5ab8p5fc + 2.puw5nggjf8f*I'

tan( )

sage: (1+CC(I)).tan()
0.271752585319512 + 1.08392332733869*I

tanh( )

sage: (1+CC(I)).tanh()
1.08392332733869 + 0.271752585319512*I

zeta( )

Return the Riemann zeta function evaluated at this complex number.

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

Special Functions: __abs__,$ \,$ __complex__,$ \,$ __eq__,$ \,$ __float__,$ \,$ __ge__,$ \,$ __getitem__,$ \,$ __gt__,$ \,$ __init__,$ \,$ __int__,$ \,$ __invert__,$ \,$ __le__,$ \,$ __long__,$ \,$ __lt__,$ \,$ __ne__,$ \,$ __neg__,$ \,$ __pos__,$ \,$ __pow__,$ \,$ __rdiv__,$ \,$ __reduce__,$ \,$ __rpow__,$ \,$ _interface_init_,$ \,$ _latex_,$ \,$ _pari_,$ \,$ _repr_,$ \,$ _set_multiplicative_order

__abs__( )

Method for computing the absolute value or modulus of self

$ \vert a + bi\vert = sqrt(a^2 + b^2)$

Note that the absolute value of a complex number with imaginary component equal to zero is the absolute value of the real component.

sage: a = ComplexNumber(2,1)
sage: abs(a)
2.23606797749979
sage: a.__abs__()
2.23606797749979
sage: float(sqrt(2^2 + 1^1))
2.2360679774997898

sage: b = ComplexNumber(42,0)
sage: abs(b)
42.0000000000000
sage: b.__abs__()
42.0000000000000
sage: b
42.0000000000000

__complex__( )

Method for converting self to type complex. Called by the complex function.

sage: a = ComplexNumber(2,1)
sage: complex(a)
(2+1j)
sage: type(complex(a))
<type 'complex'>
sage: a.__complex__()
(2+1j)

__float__( )

Method for converting self to type float. Called by the float funtion. Note that calling this method returns an error since, in general, complex numbers cannot be coerced into floats.

sage: a = ComplexNumber(2,1)
sage: float(a)
Traceback (most recent call last):
...
TypeError: can't convert complex to float; use abs(z)
sage: a.__float__()
Traceback (most recent call last):
...
TypeError: can't convert complex to float; use abs(z)

__getitem__( )

Returns either the real of imaginary component of self depending on the choice of i: real (i=0), imaginary (i=1)

INPUTS: i - i=0 will return the real component of self i=1 will return the imaginary component of self

sage: a = ComplexNumber(2,1)
sage: a.__getitem__(0)
2.00000000000000
sage: a.__getitem__(1)
1.00000000000000

sage: b = CC(42,0)
sage: b
42.0000000000000
sage: b.__getitem__(1)
0.000000000000000

__int__( )

Method for converting self to type int. Called by the int funtion. Note that calling this method returns an error since, in general, complex numbers cannot be coerced into integers.

sage: a = ComplexNumber(2,1)
sage: int(a)
Traceback (most recent call last):
...
TypeError: can't convert complex to int; use int(abs(z))
sage: a.__int__()
Traceback (most recent call last):
...
TypeError: can't convert complex to int; use int(abs(z))

__invert__( )

Return the multiplicative inverse.

sage: I = CC.0
sage: a = ~(5+I)
sage: a * (5+I)
1.00000000000000

__long__( )

Method for converting self to type long. Called by the long funtion. Note that calling this method returns an error since, in general, complex numbers cannot be coerced into integers.

sage: a = ComplexNumber(2,1)
sage: long(a)
Traceback (most recent call last):
...
TypeError: can't convert complex to long; use long(abs(z))
sage: a.__long__()
Traceback (most recent call last):
...
TypeError: can't convert complex to long; use long(abs(z))

__neg__( )

Method for computing the negative of self.

-(a + bi) = -a - bi

sage: a = ComplexNumber(2,1)
sage: -a
-2.00000000000000 - 1.00000000000000*I
sage: a.__neg__()
-2.00000000000000 - 1.00000000000000*I

__pos__( )

Method for computing the "positive" of self.

sage: a = ComplexNumber(2,1)
sage: +a
2.00000000000000 + 1.00000000000000*I
sage: a.__pos__()
2.00000000000000 + 1.00000000000000*I

__rdiv__( )

Reutrns the quotient of left with self, that is:

left/self

as a complex number.

INPUTS: left - a complex number to divide by self

sage: a = ComplexNumber(2,0)
sage: a.__rdiv__(CC(1))
0.500000000000000
sage: CC(1)/a
0.500000000000000

__reduce__( )

Pickling support

sage: a = CC(1 + I)
sage: loads(dumps(a)) == a
True

_interface_init_( )

Returns self formatted as a string, suitable as input to another computer algebra system. (This is the default function used for exporting to other computer algebra systems.)

sage: s1 = CC(exp(I)); s1
0.540302305868140 + 0.841470984807897*I
sage: s1._interface_init_()
'0.54030230586813977 + 0.84147098480789650*I'
sage: s1 == CC(gp(s1))
True

_latex_( )

Method for converting self to a string with latex formatting. Called by the global function latex.

sage: a = ComplexNumber(2,1)
sage: a
2.00000000000000 + 1.00000000000000*I
sage: latex(a)
2.00000000000000 + 1.00000000000000i
sage: a._latex_()
'2.00000000000000 + 1.00000000000000i'

sage: b = ComplexNumber(7,4,min_prec=16)
sage: b
7.000 + 4.000*I
sage: latex(b)
7.000 + 4.000i
sage: b._latex_()
'7.000 + 4.000i'

_pari_( )

Coerces self into a Pari complex object.

Coerce the object using the pari function:

sage: a = ComplexNumber(2,1)
sage: pari(a)
2.000000000000000000 + 1.0000000000000000000*I
sage: type(pari(a))
<type 'sage.libs.pari.gen.gen'>
sage: a._pari_()
2.000000000000000000 + 1.0000000000000000000*I
sage: type(a._pari_())
<type 'sage.libs.pari.gen.gen'>

_repr_( )

Returns self formatted as a string.

sage: a = ComplexNumber(2,1); a
2.00000000000000 + 1.00000000000000*I
sage: a._repr_()
'2.00000000000000 + 1.00000000000000*I'

_set_multiplicative_order( )

Function for setting the ComplexNumber class attribute multiplicative_order of self.

INPUTS: n - an integer which will define the multiplicative order of self

Note that it is not advised to explicity call _set_multiplicative_order for explicity declared complex numbers.

sage: a = ComplexNumber(2,1)
sage: a.multiplicative_order()
+Infinity
sage: a._set_multiplicative_order(5)
sage: a.multiplicative_order()
5
sage: a^5
-38.0000000000000 + 41.0000000000000*I

See About this document... for information on suggesting changes.