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. In otherwords:

z==z.real+z.imag*1j

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

Return the phase ofx (also known as theargument ofx), as afloat.phase(x) is equivalent tomath.atan2(x.imag,x.real). The result lies in the range [-π,π], and the branchcut for this operation lies along the negative real axis,continuous from above. On systems with support for signed zeros(which includes most systems in current use), this means that thesign of the result is the same as the sign ofx.imag, even whenx.imag is zero:

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

cmath.polar(x)¶

Return the representation ofx in polar coordinates. Returns apair(r,phi) wherer is the modulus ofx and phi is thephase ofx.polar(x) is equivalent to(abs(x),phase(x)).

cmath.rect(r,phi)¶

Return the complex numberx with polar coordinatesr andphi.Equivalent tor*(math.cos(phi)+math.sin(phi)*1j).

Power and logarithmic functions¶

cmath.exp(x)¶

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

cmath.log(x[,base])¶

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

cmath.log10(x)¶

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

cmath.sqrt(x)¶

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

Trigonometric functions¶

cmath.acos(x)¶

Return the arc cosine ofx. There are two branch cuts: One extends right from1 along the real axis to ∞, continuous from below. The other extends left from-1 along the real axis to -∞, continuous from above.

cmath.asin(x)¶

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

cmath.atan(x)¶

Return the arc tangent ofx. There are two branch cuts: One extends from1j along the imaginary axis to∞j, continuous from the right. Theother extends from-1j along the imaginary axis to-∞j, continuousfrom the left.

cmath.cos(x)¶

Return the cosine ofx.

cmath.sin(x)¶

Return the sine ofx.

cmath.tan(x)¶

Return the tangent ofx.

Hyperbolic functions¶

cmath.acosh(x)¶

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

cmath.asinh(x)¶

Return the inverse hyperbolic sine ofx. There are two branch cuts:One extends from1j along the imaginary axis to∞j,continuous from the right. The other extends from-1j alongthe imaginary axis to-∞j, continuous from the left.

cmath.atanh(x)¶

Return the inverse hyperbolic tangent ofx. There are two branch cuts: Oneextends from1 along the real axis to∞, continuous from below. Theother extends from-1 along the real axis to-∞, continuous fromabove.

cmath.cosh(x)¶

Return the hyperbolic cosine ofx.

cmath.sinh(x)¶

Return the hyperbolic sine ofx.

cmath.tanh(x)¶

Return the hyperbolic tangent ofx.

Classification functions¶

cmath.isfinite(x)¶

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

New in version 3.2.

cmath.isinf(x)¶

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

cmath.isnan(x)¶

ReturnTrue if either the real or the imaginary part ofx 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.

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 greater than zero.

abs_tol is the minimum absolute tolerance – useful for comparisons nearzero.abs_tol must be at least zero.

If no errors occur, the result will be:abs(a-b)<=max(rel_tol*max(abs(a),abs(b)),abs_tol).

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.

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

New in version 3.6.

cmath.inf¶

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

New in version 3.6.

cmath.infj¶

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

New in version 3.6.

cmath.nan¶

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

New in version 3.6.

cmath.nanj¶

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

New 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: