Conversions to and from polar coordinates¶

A Python complex numberz is stored internally usingrectangularorCartesian coordinates. It is completely determined by itsrealpartz.real and itsimaginary partz.imag.

Polar coordinates give an alternative way to represent a complexnumber. In polar coordinates, a complex numberz is defined by themodulusr and the phase anglephi. The modulusr is the distancefromz to the origin, while the phasephi is the counterclockwiseangle, measured in radians, from the positive x-axis to the linesegment that joins the origin toz.

The following functions can be used to convert from the nativerectangular coordinates to polar coordinates and back.

cmath.phase(z)¶

Return the phase ofz (also known as theargument ofz), as a float.phase(z) is equivalent tomath.atan2(z.imag,z.real). The resultlies in the range [-π,π], and the branch cut for this operation liesalong the negative real axis. The sign of the result is the same as thesign ofz.imag, even whenz.imag is zero:

>>>phase(complex(-1.0,0.0))3.141592653589793>>>phase(complex(-1.0,-0.0))-3.141592653589793

cmath.polar(z)¶

Return the representation ofz in polar coordinates. Returns apair(r,phi) wherer is the modulus ofz andphi is thephase ofz.polar(z) is equivalent to(abs(z),phase(z)).

cmath.rect(r,phi)¶

Return the complex numberz with polar coordinatesr andphi.Equivalent tocomplex(r*math.cos(phi),r*math.sin(phi)).

Power and logarithmic functions¶

cmath.exp(z)¶

Returne raised to the powerz, wheree is the base of naturallogarithms.

cmath.log(z[,base])¶

Return the logarithm ofz to the givenbase. If thebase is notspecified, returns the natural logarithm ofz. There is one branch cut,from 0 along the negative real axis to -∞.

cmath.log10(z)¶

Return the base-10 logarithm ofz. This has the same branch cut aslog().

cmath.sqrt(z)¶

Return the square root ofz. This has the same branch cut aslog().

Trigonometric functions¶

cmath.acos(z)¶

Return the arc cosine ofz. There are two branch cuts: One extends rightfrom 1 along the real axis to ∞. The other extends left from -1 along thereal axis to -∞.

cmath.asin(z)¶

Return the arc sine ofz. This has the same branch cuts asacos().

cmath.atan(z)¶

Return the arc tangent ofz. There are two branch cuts: One extends from1j along the imaginary axis to∞j. The other extends from-1jalong the imaginary axis to-∞j.

cmath.cos(z)¶

Return the cosine ofz.

cmath.sin(z)¶

Return the sine ofz.

cmath.tan(z)¶

Return the tangent ofz.

Hyperbolic functions¶

cmath.acosh(z)¶

Return the inverse hyperbolic cosine ofz. There is one branch cut,extending left from 1 along the real axis to -∞.

cmath.asinh(z)¶

Return the inverse hyperbolic sine ofz. There are two branch cuts:One extends from1j along the imaginary axis to∞j. The otherextends from-1j along the imaginary axis to-∞j.

cmath.atanh(z)¶

Return the inverse hyperbolic tangent ofz. There are two branch cuts: Oneextends from1 along the real axis to∞. The other extends from-1 along the real axis to-∞.

cmath.cosh(z)¶

Return the hyperbolic cosine ofz.

cmath.sinh(z)¶

Return the hyperbolic sine ofz.

cmath.tanh(z)¶

Return the hyperbolic tangent ofz.

Classification functions¶

cmath.isfinite(z)¶

ReturnTrue if both the real and imaginary parts ofz are finite, andFalse otherwise.

Added in version 3.2.

cmath.isinf(z)¶

ReturnTrue if either the real or the imaginary part ofz is aninfinity, andFalse otherwise.

cmath.isnan(z)¶

ReturnTrue if either the real or the imaginary part ofz is a NaN,andFalse otherwise.

cmath.isclose(a,b,*,rel_tol=1e-09,abs_tol=0.0)¶

ReturnTrue if the valuesa andb are close to each other andFalse otherwise.

Whether or not two values are considered close is determined according togiven absolute and relative tolerances. If no errors occur, the result willbe:abs(a-b)<=max(rel_tol*max(abs(a),abs(b)),abs_tol).

rel_tol is the relative tolerance – it is the maximum allowed differencebetweena andb, relative to the larger absolute value ofa orb.For example, to set a tolerance of 5%, passrel_tol=0.05. The defaulttolerance is1e-09, which assures that the two values are the samewithin about 9 decimal digits.rel_tol must be nonnegative and lessthan1.0.

abs_tol is the absolute tolerance; it defaults to0.0 and it must benonnegative. When comparingx to0.0,isclose(x,0) is computedasabs(x)<=rel_tol *abs(x), which isFalse for anyx andrel_tol less than1.0. So add an appropriate positive abs_tol argumentto the call.

The IEEE 754 special values ofNaN,inf, and-inf will behandled according to IEEE rules. Specifically,NaN is not consideredclose to any other value, includingNaN.inf and-inf are onlyconsidered close to themselves.

Added in version 3.5.

See also

PEP 485 – A function for testing approximate equality

Constants¶

cmath.pi¶

The mathematical constantπ, as a float.

cmath.e¶

The mathematical constante, as a float.

cmath.tau¶

The mathematical constantτ, as a float.

Added in version 3.6.

cmath.inf¶

Floating-point positive infinity. Equivalent tofloat('inf').

Added in version 3.6.

cmath.infj¶

Complex number with zero real part and positive infinity imaginarypart. Equivalent tocomplex(0.0,float('inf')).

Added in version 3.6.

cmath.nan¶

A floating-point “not a number” (NaN) value. Equivalent tofloat('nan').

Added in version 3.6.

cmath.nanj¶

Complex number with zero real part and NaN imaginary part. Equivalent tocomplex(0.0,float('nan')).

Added in version 3.6.

Note that the selection of functions is similar, but not identical, to that inmodulemath. The reason for having two modules is that some users aren’tinterested in complex numbers, and perhaps don’t even know what they are. Theywould rather havemath.sqrt(-1) raise an exception than return a complexnumber. Also note that the functions defined incmath always return acomplex number, even if the answer can be expressed as a real number (in whichcase the complex number has an imaginary part of zero).

A note on branch cuts: They are curves along which the given function fails tobe continuous. They are a necessary feature of many complex functions. It isassumed that if you need to compute with complex functions, you will understandabout branch cuts. Consult almost any (not too elementary) book on complexvariables for enlightenment. For information of the proper choice of branchcuts for numerical purposes, a good reference should be the following: