Contributed updates from Harald Hanche-Olsen, giving details of the branch
cuts for the complex math functions. Includes a brief description of
what branch cuts are.
diff --git a/Doc/lib/libcmath.tex b/Doc/lib/libcmath.tex
index 3a11870..77496bf 100644
--- a/Doc/lib/libcmath.tex
+++ b/Doc/lib/libcmath.tex
@@ -9,26 +9,56 @@
\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}
@@ -45,10 +75,13 @@
\begin{funcdesc}{log}{x}
Return the natural logarithm of \var{x}.
+There is one branch cut, from 0 along the negative real axis to
+-\infinity, continuous from above.
\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}
@@ -61,6 +94,7 @@
\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}
@@ -89,3 +123,18 @@
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 nothings'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}