[Python-checkins] CVS: python/dist/src/Doc/lib libcmath.tex,1.12,1.13

[Fred L. Drake]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv21334/lib

Modified Files:
	libcmath.tex 
Log Message:

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.


Index: libcmath.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libcmath.tex,v
retrieving revision 1.12
retrieving revision 1.13
diff -C2 -r1.12 -r1.13
*** libcmath.tex	1999/06/29 15:53:52	1.12
--- libcmath.tex	2001/06/23 03:16:29	1.13
***************
*** 10,33 ****
--- 10,63 ----
  \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}
  
***************
*** 46,53 ****
--- 76,86 ----
  \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}
  
***************
*** 62,65 ****
--- 95,99 ----
  \begin{funcdesc}{sqrt}{x}
  Return the square root of \var{x}.
+ This has the same branch cut as \function{log()}.
  \end{funcdesc}
  
***************
*** 90,91 ****
--- 124,140 ----
  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}