Doc/lib/libmath.tex

   1 \section{\module{math} ---
   2          Mathematical functions}
   3
   4 \declaremodule{builtin}{math}
   5 \modulesynopsis{Mathematical functions (\function{sin()} etc.).}
   6
   7 This module is always available.  It provides access to the
   8 mathematical functions defined by the C standard.
   9
  10 These functions cannot be used with complex numbers; use the functions
  11 of the same name from the \refmodule{cmath} module if you require
  12 support for complex numbers.  The distinction between functions which
  13 support complex numbers and those which don't is made since most users
  14 do not want to learn quite as much mathematics as required to
  15 understand complex numbers.  Receiving an exception instead of a
  16 complex result allows earlier detection of the unexpected complex
  17 number used as a parameter, so that the programmer can determine how
  18 and why it was generated in the first place.
  19
  20 The following functions provided by this module:
  21
  22 \begin{funcdesc}{acos}{x}
  23 Return the arc cosine of \var{x}.
  24 \end{funcdesc}
  25
  26 \begin{funcdesc}{asin}{x}
  27 Return the arc sine of \var{x}.
  28 \end{funcdesc}
  29
  30 \begin{funcdesc}{atan}{x}
  31 Return the arc tangent of \var{x}.
  32 \end{funcdesc}
  33
  34 \begin{funcdesc}{atan2}{y, x}
  35 Return \code{atan(\var{y} / \var{x})}.
  36 \end{funcdesc}
  37
  38 \begin{funcdesc}{ceil}{x}
  39 Return the ceiling of \var{x} as a float.
  40 \end{funcdesc}
  41
  42 \begin{funcdesc}{cos}{x}
  43 Return the cosine of \var{x}.
  44 \end{funcdesc}
  45
  46 \begin{funcdesc}{cosh}{x}
  47 Return the hyperbolic cosine of \var{x}.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{degrees}{x}
  51 Converts angle \var{x} from radians to degrees.
  52 \end{funcdesc}
  53
  54 \begin{funcdesc}{exp}{x}
  55 Return \code{e**\var{x}}.
  56 \end{funcdesc}
  57
  58 \begin{funcdesc}{fabs}{x}
  59 Return the absolute value of the floating point number \var{x}.
  60 \end{funcdesc}
  61
  62 \begin{funcdesc}{floor}{x}
  63 Return the floor of \var{x} as a float.
  64 \end{funcdesc}
  65
  66 \begin{funcdesc}{fmod}{x, y}
  67 Return \code{fmod(\var{x}, \var{y})}, as defined by the platform C library.
  68 Note that the Python expression \code{\var{x} \%\ \var{y}} may not return
  69 the same result.
  70 \end{funcdesc}
  71
  72 \begin{funcdesc}{frexp}{x}
  73 % Blessed by Tim.
  74 Return the mantissa and exponent of \var{x} as the pair
  75 \code{(\var{m}, \var{e})}.  \var{m} is a float and \var{e} is an
  76 integer such that \code{\var{x} == \var{m} * 2**\var{e}}.
  77 If \var{x} is zero, returns \code{(0.0, 0)}, otherwise
  78 \code{0.5 <= abs(\var{m}) < 1}.
  79 \end{funcdesc}
  80
  81 \begin{funcdesc}{hypot}{x, y}
  82 Return the Euclidean distance, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}.
  83 \end{funcdesc}
  84
  85 \begin{funcdesc}{ldexp}{x, i}
  86 Return \code{\var{x} * (2**\var{i})}.
  87 \end{funcdesc}
  88
  89 \begin{funcdesc}{log}{x\optional{, base}}
  90 Returns the logarithm of \var{x} to the given \var{base}.
  91 If the \var{base} is not specified, returns the natural logarithm of \var{x}.
  92 \versionchanged[\var{base} argument added]{2.3}
  93 \end{funcdesc}
  94
  95 \begin{funcdesc}{log10}{x}
  96 Return the base-10 logarithm of \var{x}.
  97 \end{funcdesc}
  98
  99 \begin{funcdesc}{modf}{x}
 100 Return the fractional and integer parts of \var{x}.  Both results
 101 carry the sign of \var{x}.  The integer part is returned as a float.
 102 \end{funcdesc}
 103
 104 \begin{funcdesc}{pow}{x, y}
 105 Return \code{\var{x}**\var{y}}.
 106 \end{funcdesc}
 107
 108 \begin{funcdesc}{radians}{x}
 109 Converts angle \var{x} from degrees to radians.
 110 \end{funcdesc}
 111
 112 \begin{funcdesc}{sin}{x}
 113 Return the sine of \var{x}.
 114 \end{funcdesc}
 115
 116 \begin{funcdesc}{sinh}{x}
 117 Return the hyperbolic sine of \var{x}.
 118 \end{funcdesc}
 119
 120 \begin{funcdesc}{sqrt}{x}
 121 Return the square root of \var{x}.
 122 \end{funcdesc}
 123
 124 \begin{funcdesc}{tan}{x}
 125 Return the tangent of \var{x}.
 126 \end{funcdesc}
 127
 128 \begin{funcdesc}{tanh}{x}
 129 Return the hyperbolic tangent of \var{x}.
 130 \end{funcdesc}
 131
 132 Note that \function{frexp()} and \function{modf()} have a different
 133 call/return pattern than their C equivalents: they take a single
 134 argument and return a pair of values, rather than returning their
 135 second return value through an `output parameter' (there is no such
 136 thing in Python).
 137
 138 The module also defines two mathematical constants:
 139
 140 \begin{datadesc}{pi}
 141 The mathematical constant \emph{pi}.
 142 \end{datadesc}
 143
 144 \begin{datadesc}{e}
 145 The mathematical constant \emph{e}.
 146 \end{datadesc}
 147
 148 \begin{seealso}
 149   \seemodule{cmath}{Complex number versions of many of these functions.}
 150 \end{seealso}