Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{cmath} --- |
Fred Drake | 8307e21 | 1999-04-21 16:29:18 +0000 | [diff] [blame] | 2 | Mathematical functions for complex numbers} |
| 3 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 4 | \declaremodule{builtin}{cmath} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 5 | \modulesynopsis{Mathematical functions for complex numbers.} |
| 6 | |
Fred Drake | 8307e21 | 1999-04-21 16:29:18 +0000 | [diff] [blame] | 7 | This module is always available. It provides access to mathematical |
| 8 | functions for complex numbers. The functions are: |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 9 | |
Guido van Rossum | 14a8024 | 1997-07-17 16:13:45 +0000 | [diff] [blame] | 10 | \begin{funcdesc}{acos}{x} |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 11 | Return the arc cosine of \var{x}. |
Fred Drake | 8058bfa | 2001-06-23 03:16:29 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 14a8024 | 1997-07-17 16:13:45 +0000 | [diff] [blame] | 17 | \end{funcdesc} |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 18 | |
| 19 | \begin{funcdesc}{acosh}{x} |
| 20 | Return the hyperbolic arc cosine of \var{x}. |
Fred Drake | 8058bfa | 2001-06-23 03:16:29 +0000 | [diff] [blame] | 21 | There is one branch cut, extending left from 1 along the real axis |
| 22 | to -\infinity, continuous from above. |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 23 | \end{funcdesc} |
| 24 | |
| 25 | \begin{funcdesc}{asin}{x} |
| 26 | Return the arc sine of \var{x}. |
Fred Drake | 8058bfa | 2001-06-23 03:16:29 +0000 | [diff] [blame] | 27 | This has the same branch cuts as \function{acos()}. |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 28 | \end{funcdesc} |
| 29 | |
| 30 | \begin{funcdesc}{asinh}{x} |
| 31 | Return the hyperbolic arc sine of \var{x}. |
Fred Drake | 8058bfa | 2001-06-23 03:16:29 +0000 | [diff] [blame] | 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. |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 40 | \end{funcdesc} |
| 41 | |
| 42 | \begin{funcdesc}{atan}{x} |
| 43 | Return the arc tangent of \var{x}. |
Fred Drake | 8058bfa | 2001-06-23 03:16:29 +0000 | [diff] [blame] | 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.) |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 51 | \end{funcdesc} |
| 52 | |
| 53 | \begin{funcdesc}{atanh}{x} |
| 54 | Return the hyperbolic arc tangent of \var{x}. |
Fred Drake | 8058bfa | 2001-06-23 03:16:29 +0000 | [diff] [blame] | 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.) |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 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} |
Guido van Rossum | c57aff2 | 1998-02-11 22:33:28 +0000 | [diff] [blame] | 73 | Return the exponential value \code{e**\var{x}}. |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 74 | \end{funcdesc} |
| 75 | |
Raymond Hettinger | b67ad7e | 2004-06-14 07:40:10 +0000 | [diff] [blame] | 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}. |
Fred Drake | 8058bfa | 2001-06-23 03:16:29 +0000 | [diff] [blame] | 79 | There is one branch cut, from 0 along the negative real axis to |
| 80 | -\infinity, continuous from above. |
Raymond Hettinger | b67ad7e | 2004-06-14 07:40:10 +0000 | [diff] [blame] | 81 | \versionchanged[\var{base} argument added]{2.4} |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 82 | \end{funcdesc} |
| 83 | |
| 84 | \begin{funcdesc}{log10}{x} |
| 85 | Return the base-10 logarithm of \var{x}. |
Fred Drake | 8058bfa | 2001-06-23 03:16:29 +0000 | [diff] [blame] | 86 | This has the same branch cut as \function{log()}. |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 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}. |
Fred Drake | 8058bfa | 2001-06-23 03:16:29 +0000 | [diff] [blame] | 99 | This has the same branch cut as \function{log()}. |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 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} |
Guido van Rossum | 14a8024 | 1997-07-17 16:13:45 +0000 | [diff] [blame] | 109 | |
| 110 | The module also defines two mathematical constants: |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 111 | |
Guido van Rossum | 14a8024 | 1997-07-17 16:13:45 +0000 | [diff] [blame] | 112 | \begin{datadesc}{pi} |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 113 | The mathematical constant \emph{pi}, as a real. |
Guido van Rossum | 14a8024 | 1997-07-17 16:13:45 +0000 | [diff] [blame] | 114 | \end{datadesc} |
Fred Drake | 1b914b3 | 1997-09-30 20:14:50 +0000 | [diff] [blame] | 115 | |
| 116 | \begin{datadesc}{e} |
| 117 | The mathematical constant \emph{e}, as a real. |
| 118 | \end{datadesc} |
Guido van Rossum | 14a8024 | 1997-07-17 16:13:45 +0000 | [diff] [blame] | 119 | |
| 120 | Note that the selection of functions is similar, but not identical, to |
Fred Drake | 8307e21 | 1999-04-21 16:29:18 +0000 | [diff] [blame] | 121 | that in module \refmodule{math}\refbimodindex{math}. The reason for having |
Fred Drake | 9118f7c | 1999-06-29 15:53:52 +0000 | [diff] [blame] | 122 | two modules is that some users aren't interested in complex numbers, |
Fred Drake | aa5dba0 | 1998-01-09 21:30:03 +0000 | [diff] [blame] | 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. |
Fred Drake | 8307e21 | 1999-04-21 16:29:18 +0000 | [diff] [blame] | 125 | Also note that the functions defined in \module{cmath} always return a |
Fred Drake | aa5dba0 | 1998-01-09 21:30:03 +0000 | [diff] [blame] | 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). |
Fred Drake | 8058bfa | 2001-06-23 03:16:29 +0000 | [diff] [blame] | 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; |
Raymond Hettinger | 6880431 | 2005-01-01 00:28:46 +0000 | [diff] [blame] | 139 | or, Much ado about nothing's sign bit. In Iserles, A., |
Fred Drake | 8058bfa | 2001-06-23 03:16:29 +0000 | [diff] [blame] | 140 | and Powell, M. (eds.), \citetitle{The state of the art in |
| 141 | numerical analysis}. Clarendon Press (1987) pp165-211.} |
| 142 | \end{seealso} |