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}
  90 Return the natural logarithm of \var{x}.
  91 \end{funcdesc}
  92
  93 \begin{funcdesc}{log10}{x}
  94 Return the base-10 logarithm of \var{x}.
  95 \end{funcdesc}
  96
  97 \begin{funcdesc}{modf}{x}
  98 Return the fractional and integer parts of \var{x}.  Both results
  99 carry the sign of \var{x}.  The integer part is returned as a float.
 100 \end{funcdesc}
 101
 102 \begin{funcdesc}{pow}{x, y}
 103 Return \code{\var{x}**\var{y}}.
 104 \end{funcdesc}
 105
 106 \begin{funcdesc}{radians}{x}
 107 Converts angle \var{x} from degrees to radians.
 108 \end{funcdesc}
 109
 110 \begin{funcdesc}{sin}{x}
 111 Return the sine of \var{x}.
 112 \end{funcdesc}
 113
 114 \begin{funcdesc}{sinh}{x}
 115 Return the hyperbolic sine of \var{x}.
 116 \end{funcdesc}
 117
 118 \begin{funcdesc}{sqrt}{x}
 119 Return the square root of \var{x}.
 120 \end{funcdesc}
 121
 122 \begin{funcdesc}{tan}{x}
 123 Return the tangent of \var{x}.
 124 \end{funcdesc}
 125
 126 \begin{funcdesc}{tanh}{x}
 127 Return the hyperbolic tangent of \var{x}.
 128 \end{funcdesc}
 129
 130 Note that \function{frexp()} and \function{modf()} have a different
 131 call/return pattern than their C equivalents: they take a single
 132 argument and return a pair of values, rather than returning their
 133 second return value through an `output parameter' (there is no such
 134 thing in Python).
 135
 136 The module also defines two mathematical constants:
 137
 138 \begin{datadesc}{pi}
 139 The mathematical constant \emph{pi}.
 140 \end{datadesc}
 141
 142 \begin{datadesc}{e}
 143 The mathematical constant \emph{e}.
 144 \end{datadesc}
 145
 146 \begin{seealso}
 147   \seemodule{cmath}{Complex number versions of many of these functions.}
 148 \end{seealso}