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.

1 files changed, 49 insertions, 0 deletions

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 @@ functions for complex numbers.  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}
@@ -45,10 +75,13 @@ Return the exponential value \code{e**\var{x}}.
 
 \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 @@ Return the hyperbolic sine of \var{x}.
 
 \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 @@ and perhaps don't even know what they are.  They would rather have
 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}