150 lines
5.1 KiB
TeX
150 lines
5.1 KiB
TeX
\section{\module{cmath} ---
|
|
Mathematical functions for complex numbers}
|
|
|
|
\declaremodule{builtin}{cmath}
|
|
\modulesynopsis{Mathematical functions for complex numbers.}
|
|
|
|
This module is always available. It provides access to mathematical
|
|
functions for complex numbers. The functions in this module accept
|
|
integers, floating-point numbers or complex numbers as arguments.
|
|
They will also accept any Python object that has either a
|
|
\method{__complex__} or a \method{__float__} method: these methods are
|
|
used to convert the object to a complex or floating-point number, respectively, and
|
|
the function is then applied to the result of the conversion.
|
|
|
|
The functions are:
|
|
|
|
\begin{funcdesc}{acos}{x}
|
|
Return the arc cosine of \var{x}.
|
|
There are two branch cuts:
|
|
One extends right from 1 along the real axis to \infinity, continuous
|
|
from below.
|
|
The other extends left from -1 along the real axis to -\infinity,
|
|
continuous from above.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{acosh}{x}
|
|
Return the hyperbolic arc cosine of \var{x}.
|
|
There is one branch cut, extending left from 1 along the real axis
|
|
to -\infinity, continuous from above.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{asin}{x}
|
|
Return the arc sine of \var{x}.
|
|
This has the same branch cuts as \function{acos()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{asinh}{x}
|
|
Return the hyperbolic arc sine of \var{x}.
|
|
There are two branch cuts, extending left from \plusminus\code{1j} to
|
|
\plusminus-\infinity\code{j}, both continuous from above.
|
|
These branch cuts should be considered a bug to be corrected in a
|
|
future release.
|
|
The correct branch cuts should extend along the imaginary axis,
|
|
one from \code{1j} up to \infinity\code{j} and continuous from the
|
|
right, and one from -\code{1j} down to -\infinity\code{j} and
|
|
continuous from the left.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{atan}{x}
|
|
Return the arc tangent of \var{x}.
|
|
There are two branch cuts:
|
|
One extends from \code{1j} along the imaginary axis to
|
|
\infinity\code{j}, continuous from the left.
|
|
The other extends from -\code{1j} along the imaginary axis to
|
|
-\infinity\code{j}, continuous from the left.
|
|
(This should probably be changed so the upper cut becomes continuous
|
|
from the other side.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{atanh}{x}
|
|
Return the hyperbolic arc tangent of \var{x}.
|
|
There are two branch cuts:
|
|
One extends from 1 along the real axis to \infinity, continuous
|
|
from above.
|
|
The other extends from -1 along the real axis to -\infinity,
|
|
continuous from above.
|
|
(This should probably be changed so the right cut becomes continuous from
|
|
the other side.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{cos}{x}
|
|
Return the cosine of \var{x}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{cosh}{x}
|
|
Return the hyperbolic cosine of \var{x}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{exp}{x}
|
|
Return the exponential value \code{e**\var{x}}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{log}{x\optional{, base}}
|
|
Returns the logarithm of \var{x} to the given \var{base}.
|
|
If the \var{base} is not specified, returns the natural logarithm of \var{x}.
|
|
There is one branch cut, from 0 along the negative real axis to
|
|
-\infinity, continuous from above.
|
|
\versionchanged[\var{base} argument added]{2.4}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{log10}{x}
|
|
Return the base-10 logarithm of \var{x}.
|
|
This has the same branch cut as \function{log()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{sin}{x}
|
|
Return the sine of \var{x}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{sinh}{x}
|
|
Return the hyperbolic sine of \var{x}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{sqrt}{x}
|
|
Return the square root of \var{x}.
|
|
This has the same branch cut as \function{log()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tan}{x}
|
|
Return the tangent of \var{x}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tanh}{x}
|
|
Return the hyperbolic tangent of \var{x}.
|
|
\end{funcdesc}
|
|
|
|
The module also defines two mathematical constants:
|
|
|
|
\begin{datadesc}{pi}
|
|
The mathematical constant \emph{pi}, as a real.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{e}
|
|
The mathematical constant \emph{e}, as a real.
|
|
\end{datadesc}
|
|
|
|
Note that the selection of functions is similar, but not identical, to
|
|
that in module \refmodule{math}\refbimodindex{math}. The reason for having
|
|
two modules is that some users aren't interested in complex numbers,
|
|
and perhaps don't even know what they are. They would rather have
|
|
\code{math.sqrt(-1)} raise an exception than return a complex number.
|
|
Also note that the functions defined in \module{cmath} always return a
|
|
complex number, even if the answer can be expressed as a real number
|
|
(in which case the complex number has an imaginary part of zero).
|
|
|
|
A note on branch cuts: They are curves along which the given function
|
|
fails to be continuous. They are a necessary feature of many complex
|
|
functions. It is assumed that if you need to compute with complex
|
|
functions, you will understand about branch cuts. Consult almost any
|
|
(not too elementary) book on complex variables for enlightenment. For
|
|
information of the proper choice of branch cuts for numerical
|
|
purposes, a good reference should be the following:
|
|
|
|
\begin{seealso}
|
|
\seetext{Kahan, W: Branch cuts for complex elementary functions;
|
|
or, Much ado about nothing's sign bit. In Iserles, A.,
|
|
and Powell, M. (eds.), \citetitle{The state of the art in
|
|
numerical analysis}. Clarendon Press (1987) pp165-211.}
|
|
\end{seealso}
|