cmath — Mathematical functions for complex numbers

This module provides access to mathematical functions for complex numbers. Thefunctions in this module accept integers, floating-point numbers or complexnumbers as arguments. They will also accept any Python object that has either a__complex__() or a__float__() method: these methods are used toconvert the object to a complex or floating-point number, respectively, andthe function is then applied to the result of the conversion.

Note

For functions involving branch cuts, we have the problem of deciding how todefine those functions on the cut itself. Following Kahan’s “Branch cuts forcomplex elementary functions” paper, as well as Annex G of C99 and later Cstandards, we use the sign of zero to distinguish one side of the branch cutfrom the other: for a branch cut along (a portion of) the real axis we lookat the sign of the imaginary part, while for a branch cut along theimaginary axis we look at the sign of the real part.

For example, thecmath.sqrt() function has a branch cut along thenegative real axis. An argument ofcomplex(-2.0,-0.0) is treated asthough it liesbelow the branch cut, and so gives a result on the negativeimaginary axis:

>>>cmath.sqrt(complex(-2.0,-0.0))-1.4142135623730951j

But an argument ofcomplex(-2.0,0.0) is treated as though it lies abovethe branch cut:

>>>cmath.sqrt(complex(-2.0,0.0))1.4142135623730951j

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 a float.phase(x) is equivalent tomath.atan2(x.imag,x.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 ofx.imag, even whenx.imag is zero:

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

Note

The modulus (absolute value) of a complex numberx can becomputed using the built-inabs() function. There is noseparatecmath module function for this operation.

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 0 along the negative real axis to -∞.

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 rightfrom 1 along the real axis to ∞. The other extends left from -1 along thereal axis to -∞.

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. The other extends from-1jalong the imaginary axis to-∞j.

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

cmath.asinh(x)

Return the inverse hyperbolic sine ofx. 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(x)

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

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:

See also

Kahan, W: Branch cuts for complex elementary functions; or, Much ado aboutnothing’s sign bit. In Iserles, A., and Powell, M. (eds.), The state of the artin numerical analysis. Clarendon Press (1987) pp165–211.