Doc/lib/libcmath.tex

   1 \section{\module{cmath} ---
   2          Mathematical functions for complex numbers}
   3
   4 \declaremodule{builtin}{cmath}
   5 \modulesynopsis{Mathematical functions for complex numbers.}
   6
   7 This module is always available.  It provides access to mathematical
   8 functions for complex numbers.  The functions are:
   9
  10 \begin{funcdesc}{acos}{x}
  11 Return the arc cosine of \var{x}.
  12 There are two branch cuts:
  13 One extends right from 1 along the real axis to \infinity, continuous
  14 from below.
  15 The other extends left from -1 along the real axis to -\infinity,
  16 continuous from above.
  17 \end{funcdesc}
  18
  19 \begin{funcdesc}{acosh}{x}
  20 Return the hyperbolic arc cosine of \var{x}.
  21 There is one branch cut, extending left from 1 along the real axis
  22 to -\infinity, continuous from above.
  23 \end{funcdesc}
  24
  25 \begin{funcdesc}{asin}{x}
  26 Return the arc sine of \var{x}.
  27 This has the same branch cuts as \function{acos()}.
  28 \end{funcdesc}
  29
  30 \begin{funcdesc}{asinh}{x}
  31 Return the hyperbolic arc sine of \var{x}.
  32 There are two branch cuts, extending left from \plusminus\code{1j} to
  33 \plusminus-\infinity\code{j}, both continuous from above.
  34 These branch cuts should be considered a bug to be corrected in a
  35 future release.
  36 The correct branch cuts should extend along the imaginary axis,
  37 one from \code{1j} up to \infinity\code{j} and continuous from the
  38 right, and one from -\code{1j} down to -\infinity\code{j} and
  39 continuous from the left.
  40 \end{funcdesc}
  41
  42 \begin{funcdesc}{atan}{x}
  43 Return the arc tangent of \var{x}.
  44 There are two branch cuts:
  45 One extends from \code{1j} along the imaginary axis to
  46 \infinity\code{j}, continuous from the left.
  47 The other extends from -\code{1j} along the imaginary axis to
  48 -\infinity\code{j}, continuous from the left.
  49 (This should probably be changed so the upper cut becomes continuous
  50 from the other side.)
  51 \end{funcdesc}
  52
  53 \begin{funcdesc}{atanh}{x}
  54 Return the hyperbolic arc tangent of \var{x}.
  55 There are two branch cuts:
  56 One extends from 1 along the real axis to \infinity, continuous
  57 from above.
  58 The other extends from -1 along the real axis to -\infinity,
  59 continuous from above.
  60 (This should probably be changed so the right cut becomes continuous from
  61 the other side.)
  62 \end{funcdesc}
  63
  64 \begin{funcdesc}{cos}{x}
  65 Return the cosine of \var{x}.
  66 \end{funcdesc}
  67
  68 \begin{funcdesc}{cosh}{x}
  69 Return the hyperbolic cosine of \var{x}.
  70 \end{funcdesc}
  71
  72 \begin{funcdesc}{exp}{x}
  73 Return the exponential value \code{e**\var{x}}.
  74 \end{funcdesc}
  75
  76 \begin{funcdesc}{log}{x\optional{, base}}
  77 Returns the logarithm of \var{x} to the given \var{base}.
  78 If the \var{base} is not specified, returns the natural logarithm of \var{x}.
  79 There is one branch cut, from 0 along the negative real axis to
  80 -\infinity, continuous from above.
  81 \versionchanged[\var{base} argument added]{2.4}
  82 \end{funcdesc}
  83
  84 \begin{funcdesc}{log10}{x}
  85 Return the base-10 logarithm of \var{x}.
  86 This has the same branch cut as \function{log()}.
  87 \end{funcdesc}
  88
  89 \begin{funcdesc}{sin}{x}
  90 Return the sine of \var{x}.
  91 \end{funcdesc}
  92
  93 \begin{funcdesc}{sinh}{x}
  94 Return the hyperbolic sine of \var{x}.
  95 \end{funcdesc}
  96
  97 \begin{funcdesc}{sqrt}{x}
  98 Return the square root of \var{x}.
  99 This has the same branch cut as \function{log()}.
 100 \end{funcdesc}
 101
 102 \begin{funcdesc}{tan}{x}
 103 Return the tangent of \var{x}.
 104 \end{funcdesc}
 105
 106 \begin{funcdesc}{tanh}{x}
 107 Return the hyperbolic tangent of \var{x}.
 108 \end{funcdesc}
 109
 110 The module also defines two mathematical constants:
 111
 112 \begin{datadesc}{pi}
 113 The mathematical constant \emph{pi}, as a real.
 114 \end{datadesc}
 115
 116 \begin{datadesc}{e}
 117 The mathematical constant \emph{e}, as a real.
 118 \end{datadesc}
 119
 120 Note that the selection of functions is similar, but not identical, to
 121 that in module \refmodule{math}\refbimodindex{math}.  The reason for having
 122 two modules is that some users aren't interested in complex numbers,
 123 and perhaps don't even know what they are.  They would rather have
 124 \code{math.sqrt(-1)} raise an exception than return a complex number.
 125 Also note that the functions defined in \module{cmath} always return a
 126 complex number, even if the answer can be expressed as a real number
 127 (in which case the complex number has an imaginary part of zero).
 128
 129 A note on branch cuts: They are curves along which the given function
 130 fails to be continuous.  They are a necessary feature of many complex
 131 functions.  It is assumed that if you need to compute with complex
 132 functions, you will understand about branch cuts.  Consult almost any
 133 (not too elementary) book on complex variables for enlightenment.  For
 134 information of the proper choice of branch cuts for numerical
 135 purposes, a good reference should be the following:
 136
 137 \begin{seealso}
 138   \seetext{Kahan, W:  Branch cuts for complex elementary functions;
 139            or, Much ado about nothing's sign bit.  In Iserles, A.,
 140            and Powell, M. (eds.), \citetitle{The state of the art in
 141            numerical analysis}. Clarendon Press (1987) pp165-211.}
 142 \end{seealso}