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}{exp}{x}
  51 Return \code{e**\var{x}}.
  52 \end{funcdesc}
  53
  54 \begin{funcdesc}{fabs}{x}
  55 Return the absolute value of the floating point number \var{x}.
  56 \end{funcdesc}
  57
  58 \begin{funcdesc}{floor}{x}
  59 Return the floor of \var{x} as a float.
  60 \end{funcdesc}
  61
  62 \begin{funcdesc}{fmod}{x, y}
  63 Return \code{fmod(\var{x}, \var{y})}, as defined by the platform C library.
  64 Note that the Python expression \code{\var{x} \%\ \var{y}} may not return
  65 the same result.
  66 \end{funcdesc}
  67
  68 \begin{funcdesc}{frexp}{x}
  69 % Blessed by Tim.
  70 Return the mantissa and exponent of \var{x} as the pair
  71 \code{(\var{m}, \var{e})}.  \var{m} is a float and \var{e} is an
  72 integer such that \code{\var{x} == \var{m} * 2**\var{e}}.
  73 If \var{x} is zero, returns \code{(0.0, 0)}, otherwise
  74 \code{0.5 <= abs(\var{m}) < 1}.
  75 \end{funcdesc}
  76
  77 \begin{funcdesc}{hypot}{x, y}
  78 Return the Euclidean distance, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}.
  79 \end{funcdesc}
  80
  81 \begin{funcdesc}{ldexp}{x, i}
  82 Return \code{\var{x} * (2**\var{i})}.
  83 \end{funcdesc}
  84
  85 \begin{funcdesc}{log}{x}
  86 Return the natural logarithm of \var{x}.
  87 \end{funcdesc}
  88
  89 \begin{funcdesc}{log10}{x}
  90 Return the base-10 logarithm of \var{x}.
  91 \end{funcdesc}
  92
  93 \begin{funcdesc}{modf}{x}
  94 Return the fractional and integer parts of \var{x}.  Both results
  95 carry the sign of \var{x}.  The integer part is returned as a float.
  96 \end{funcdesc}
  97
  98 \begin{funcdesc}{pow}{x, y}
  99 Return \code{\var{x}**\var{y}}.
 100 \end{funcdesc}
 101
 102 \begin{funcdesc}{sin}{x}
 103 Return the sine of \var{x}.
 104 \end{funcdesc}
 105
 106 \begin{funcdesc}{sinh}{x}
 107 Return the hyperbolic sine of \var{x}.
 108 \end{funcdesc}
 109
 110 \begin{funcdesc}{sqrt}{x}
 111 Return the square root of \var{x}.
 112 \end{funcdesc}
 113
 114 \begin{funcdesc}{tan}{x}
 115 Return the tangent of \var{x}.
 116 \end{funcdesc}
 117
 118 \begin{funcdesc}{tanh}{x}
 119 Return the hyperbolic tangent of \var{x}.
 120 \end{funcdesc}
 121
 122 Note that \function{frexp()} and \function{modf()} have a different
 123 call/return pattern than their C equivalents: they take a single
 124 argument and return a pair of values, rather than returning their
 125 second return value through an `output parameter' (there is no such
 126 thing in Python).
 127
 128 The module also defines two mathematical constants:
 129
 130 \begin{datadesc}{pi}
 131 The mathematical constant \emph{pi}.
 132 \end{datadesc}
 133
 134 \begin{datadesc}{e}
 135 The mathematical constant \emph{e}.
 136 \end{datadesc}
 137
 138 \begin{seealso}
 139   \seemodule{cmath}{Complex number versions of many of these functions.}
 140 \end{seealso}