"math" --- 數學函式
*******************

======================================================================

此模組提供對 C 標準中定義的數學相關函式的存取。

這些函式不支援複數；若你需要計算複數，請使用 "cmath" 模組的同名函式。
這是因為大多數的使用者並不想學習那麼多理解複數所需的數學概念，所以根據
支援複數與否分為兩種函式。收到一個例外而非複數回傳值，有助於程式設計師
提早察覺參數中包含非預期的複數，進而從源頭查出導致此情況的原因。

此模組提供下列函式。除非特意註明，否則回傳值皆為浮點數。


數論與表現函式
==============

math.ceil(x)

   回傳 *x* 經上取整的值，即大於或等於 *x* 的最小整數。若 *x* 並非浮點
   數，此函式將委派給 "x.__ceil__"，並回傳 "Integral" 型別的值。

math.comb(n, k)

   回傳從 *n* 個物品中不重複且不考慮排序地取出 *k* 個物品的方法數。

   當 "k <= n" 時其值為 "n! / (k! * (n - k)!)"，否則其值為 "0"。

   因為此值等同於 "(1 + x)ⁿ" 進行多項式展開後第 k 項的係數，所以又稱為
   二項式係數。

   當任一參數非整數型別時會引發 "TypeError"。當任一參數為負數時會引發
   "ValueError"。

   在 3.8 版被加入.

math.copysign(x, y)

   回傳與 *x* 相同長度（絕對值）且與 *y* 同號的浮點數。在支援帶符號零
   的平臺上，"copysign(1.0, -0.0)" 回傳 *-1.0*。

math.fabs(x)

   回傳 *x* 的絕對值。

math.factorial(n)

   以整數回傳 *n* 的階乘。若 *n* 非整數型別或其值為負會引發
   "ValueError"。

   在 3.9 版之後被棄用: 允許傳入其值為整數的浮點數（如："5.0"）已被棄
   用。

math.floor(x)

   回傳 *x* 經下取整的值，即小於或等於 *x* 的最大整數。若 *x* 並非浮點
   數，此函式將委派給 "x.__floor__"，並回傳 "Integral" 型別的值。

math.fmod(x, y)

   Return the floating-point remainder of "x / y", as defined by the
   platform C library function "fmod(x, y)". Note that the Python
   expression "x % y" may not return the same result.  The intent of
   the C standard is that "fmod(x, y)" be exactly (mathematically; to
   infinite precision) equal to "x - n*y" for some integer *n* such
   that the result has the same sign as *x* and magnitude less than
   "abs(y)".  Python's "x % y" returns a result with the sign of *y*
   instead, and may not be exactly computable for float arguments. For
   example, "fmod(-1e-100, 1e100)" is "-1e-100", but the result of
   Python's "-1e-100 % 1e100" is "1e100-1e-100", which cannot be
   represented exactly as a float, and rounds to the surprising
   "1e100".  For this reason, function "fmod()" is generally preferred
   when working with floats, while Python's "x % y" is preferred when
   working with integers.

math.frexp(x)

   以 "(m, e)" 對的格式回傳 *x* 的尾數 *m* 及指數 *e*。*m* 是浮點數而
   *e* 是整數，且兩者精確地使 "x == m * 2**e"。若 *x* 為零，回傳
   "(0.0, 0)"，否則令 "0.5 <= abs(m) < 1"。此函式用於以可攜的方式「分
   割」浮點數內部表示法。

math.fsum(iterable)

   回傳可疊代物件（iterable）中所有值的精確浮點數和。透過追蹤過程中多
   個部分和（partial sum）以避免精確度損失。

   此演算法準確性奠基於保證 IEEE-754 浮點標準及典型奇進偶捨（half-even
   ）模式。於有些非 Windows 平台建置時，底層 C 函式庫使用延伸精度加法
   運算，而可能導致對過程中同一部分和重複捨入，並使其最低有效位不如預
   期。

   更深入的討論及兩種替代做法請參閱 ASPN cookbook recipes 精準的浮點數
   總和。

math.gcd(*integers)

   回傳指定整數引數的最大公因數。若存在任一非零引數，回傳值為所有引數
   共有因數中最大的正整數。若所有引數皆為零，則回傳值為 "0"。"gcd()"
   若未傳入任何引數也將回傳 "0"。

   在 3.5 版被加入.

   在 3.9 版的變更: 新增支援任意數量的引數。先前僅支援兩個引數。

math.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)

   若 *a* 及 *b* 兩值足夠接近便回傳 "True"，否則回傳 "False"。

   Whether or not two values are considered close is determined
   according to given absolute and relative tolerances.  If no errors
   occur, the result will be: "abs(a-b) <= max(rel_tol * max(abs(a),
   abs(b)), abs_tol)".

   *rel_tol* is the relative tolerance -- it is the maximum allowed
   difference between *a* and *b*, relative to the larger absolute
   value of *a* or *b*. For example, to set a tolerance of 5%, pass
   "rel_tol=0.05".  The default tolerance is "1e-09", which assures
   that the two values are the same within about 9 decimal digits.
   *rel_tol* must be nonnegative and less than "1.0".

   *abs_tol* is the absolute tolerance; it defaults to "0.0" and it
   must be nonnegative.  When comparing "x" to "0.0", "isclose(x, 0)"
   is computed as "abs(x) <= rel_tol  * abs(x)", which is "False" for
   any nonzero "x" and *rel_tol* less than "1.0".  So add an
   appropriate positive *abs_tol* argument to the call.

   定義於 IEEE 754 浮點標準中的特殊值 "NaN"、"inf" 和 "-inf" 會根據該
   標準處理。更明確地說，"NaN" 不會與包含自身在內的任何數字足夠接近，
   而 "inf" 及 "-inf" 皆只與自身接近。

   在 3.5 版被加入.

   也參考: **PEP 485** ── 用於測試近似相等的函式

math.isfinite(x)

   若 *x* 不是無限值或 "NaN" 便回傳 "True"，否則回傳 "False"。（注意
   "0.0" 被視為有限數。）

   在 3.2 版被加入.

math.isinf(x)

   若 *x* 是正無限值或負無限值便回傳 "True"，否則回傳 "False"。

math.isnan(x)

   若 *x* 是 "NaN" ── 即非數字（NaN, not a number）── 便回傳 "True"，
   否則回傳 "False"。

math.isqrt(n)

   回傳非負整數 *n* 的整數平方根。此值為 *n* 精確平方根經下取整的值，
   亦等同於滿足 *a*² ≤ *n* 的最大整數值 *a*。

   於有些應用程式中，取得滿足 *n* ≤ *a*² 的最小整數值 *a* ── 或者說
   *n* 精確平方根經上取整的值 ── 會更加方便。對正數 *n*，此值可使用 "a
   = 1 + isqrt(n - 1)" 計算。

   在 3.8 版被加入.

math.lcm(*integers)

   回傳指定整數引數的最小公倍數。若所有引數值皆非零，回傳值為所有引數
   共有倍數中最小的正整數。若存在任一引數值為零，則回傳值為 "0"。
   "lcm()" 若未傳入任何引數將回傳 "1"。

   在 3.9 版被加入.

math.ldexp(x, i)

   回傳 "x * (2**i)"。此函式本質上為 "frexp()" 的反函式。

math.modf(x)

   Return the fractional and integer parts of *x*.  Both results carry
   the sign of *x* and are floats.

math.nextafter(x, y, steps=1)

   Return the floating-point value *steps* steps after *x* towards
   *y*.

   If *x* is equal to *y*, return *y*, unless *steps* is zero.

   範例：

   * "math.nextafter(x, math.inf)" goes up: towards positive infinity.

   * "math.nextafter(x, -math.inf)" goes down: towards minus infinity.

   * "math.nextafter(x, 0.0)" goes towards zero.

   * "math.nextafter(x, math.copysign(math.inf, x))" goes away from
     zero.

   另請參閱 "math.ulp()"。

   在 3.9 版被加入.

   在 3.12 版的變更: 新增 *steps* 引數。

math.perm(n, k=None)

   Return the number of ways to choose *k* items from *n* items
   without repetition and with order.

   Evaluates to "n! / (n - k)!" when "k <= n" and evaluates to zero
   when "k > n".

   If *k* is not specified or is "None", then *k* defaults to *n* and
   the function returns "n!".

   當任一參數非整數型別時會引發 "TypeError"。當任一參數為負數時會引發
   "ValueError"。

   在 3.8 版被加入.

math.prod(iterable, *, start=1)

   Calculate the product of all the elements in the input *iterable*.
   The default *start* value for the product is "1".

   When the iterable is empty, return the start value.  This function
   is intended specifically for use with numeric values and may reject
   non-numeric types.

   在 3.8 版被加入.

math.remainder(x, y)

   Return the IEEE 754-style remainder of *x* with respect to *y*.
   For finite *x* and finite nonzero *y*, this is the difference "x -
   n*y", where "n" is the closest integer to the exact value of the
   quotient "x / y".  If "x / y" is exactly halfway between two
   consecutive integers, the nearest *even* integer is used for "n".
   The remainder "r = remainder(x, y)" thus always satisfies "abs(r)
   <= 0.5 * abs(y)".

   Special cases follow IEEE 754: in particular, "remainder(x,
   math.inf)" is *x* for any finite *x*, and "remainder(x, 0)" and
   "remainder(math.inf, x)" raise "ValueError" for any non-NaN *x*. If
   the result of the remainder operation is zero, that zero will have
   the same sign as *x*.

   On platforms using IEEE 754 binary floating point, the result of
   this operation is always exactly representable: no rounding error
   is introduced.

   在 3.7 版被加入.

math.sumprod(p, q)

   Return the sum of products of values from two iterables *p* and
   *q*.

   Raises "ValueError" if the inputs do not have the same length.

   Roughly equivalent to:

      sum(itertools.starmap(operator.mul, zip(p, q, strict=True)))

   For float and mixed int/float inputs, the intermediate products and
   sums are computed with extended precision.

   在 3.12 版被加入.

math.trunc(x)

   Return *x* with the fractional part removed, leaving the integer
   part.  This rounds toward 0: "trunc()" is equivalent to "floor()"
   for positive *x*, and equivalent to "ceil()" for negative *x*. If
   *x* is not a float, delegates to "x.__trunc__", which should return
   an "Integral" value.

math.ulp(x)

   Return the value of the least significant bit of the float *x*:

   * If *x* is a NaN (not a number), return *x*.

   * If *x* is negative, return "ulp(-x)".

   * If *x* is a positive infinity, return *x*.

   * If *x* is equal to zero, return the smallest positive
     *denormalized* representable float (smaller than the minimum
     positive *normalized* float, "sys.float_info.min").

   * If *x* is equal to the largest positive representable float,
     return the value of the least significant bit of *x*, such that
     the first float smaller than *x* is "x - ulp(x)".

   * Otherwise (*x* is a positive finite number), return the value of
     the least significant bit of *x*, such that the first float
     bigger than *x* is "x + ulp(x)".

   ULP stands for "Unit in the Last Place".

   See also "math.nextafter()" and "sys.float_info.epsilon".

   在 3.9 版被加入.

Note that "frexp()" and "modf()" have a different call/return pattern
than their C equivalents: they take a single argument and return a
pair of values, rather than returning their second return value
through an 'output parameter' (there is no such thing in Python).

For the "ceil()", "floor()", and "modf()" functions, note that *all*
floating-point numbers of sufficiently large magnitude are exact
integers. Python floats typically carry no more than 53 bits of
precision (the same as the platform C double type), in which case any
float *x* with "abs(x) >= 2**52" necessarily has no fractional bits.


Power and logarithmic functions
===============================

math.cbrt(x)

   Return the cube root of *x*.

   在 3.11 版被加入.

math.exp(x)

   Return *e* raised to the power *x*, where *e* = 2.718281... is the
   base of natural logarithms.  This is usually more accurate than
   "math.e ** x" or "pow(math.e, x)".

math.exp2(x)

   Return *2* raised to the power *x*.

   在 3.11 版被加入.

math.expm1(x)

   Return *e* raised to the power *x*, minus 1.  Here *e* is the base
   of natural logarithms.  For small floats *x*, the subtraction in
   "exp(x) - 1" can result in a significant loss of precision; the
   "expm1()" function provides a way to compute this quantity to full
   precision:

   >>> from math import exp, expm1
   >>> exp(1e-5) - 1  # gives result accurate to 11 places
   1.0000050000069649e-05
   >>> expm1(1e-5)    # result accurate to full precision
   1.0000050000166668e-05

   在 3.2 版被加入.

math.log(x[, base])

   With one argument, return the natural logarithm of *x* (to base
   *e*).

   With two arguments, return the logarithm of *x* to the given
   *base*, calculated as "log(x)/log(base)".

math.log1p(x)

   Return the natural logarithm of *1+x* (base *e*). The result is
   calculated in a way which is accurate for *x* near zero.

math.log2(x)

   Return the base-2 logarithm of *x*. This is usually more accurate
   than "log(x, 2)".

   在 3.3 版被加入.

   也參考:

     "int.bit_length()" returns the number of bits necessary to
     represent an integer in binary, excluding the sign and leading
     zeros.

math.log10(x)

   Return the base-10 logarithm of *x*.  This is usually more accurate
   than "log(x, 10)".

math.pow(x, y)

   Return "x" raised to the power "y".  Exceptional cases follow the
   IEEE 754 standard as far as possible.  In particular, "pow(1.0, x)"
   and "pow(x, 0.0)" always return "1.0", even when "x" is a zero or a
   NaN.  If both "x" and "y" are finite, "x" is negative, and "y" is
   not an integer then "pow(x, y)" is undefined, and raises
   "ValueError".

   Unlike the built-in "**" operator, "math.pow()" converts both its
   arguments to type "float".  Use "**" or the built-in "pow()"
   function for computing exact integer powers.

   在 3.11 版的變更: The special cases "pow(0.0, -inf)" and "pow(-0.0,
   -inf)" were changed to return "inf" instead of raising
   "ValueError", for consistency with IEEE 754.

math.sqrt(x)

   Return the square root of *x*.


Trigonometric functions
=======================

math.acos(x)

   Return the arc cosine of *x*, in radians. The result is between "0"
   and "pi".

math.asin(x)

   Return the arc sine of *x*, in radians. The result is between
   "-pi/2" and "pi/2".

math.atan(x)

   Return the arc tangent of *x*, in radians. The result is between
   "-pi/2" and "pi/2".

math.atan2(y, x)

   Return "atan(y / x)", in radians. The result is between "-pi" and
   "pi". The vector in the plane from the origin to point "(x, y)"
   makes this angle with the positive X axis. The point of "atan2()"
   is that the signs of both inputs are known to it, so it can compute
   the correct quadrant for the angle. For example, "atan(1)" and
   "atan2(1, 1)" are both "pi/4", but "atan2(-1, -1)" is "-3*pi/4".

math.cos(x)

   Return the cosine of *x* radians.

math.dist(p, q)

   Return the Euclidean distance between two points *p* and *q*, each
   given as a sequence (or iterable) of coordinates.  The two points
   must have the same dimension.

   Roughly equivalent to:

      sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))

   在 3.8 版被加入.

math.hypot(*coordinates)

   Return the Euclidean norm, "sqrt(sum(x**2 for x in coordinates))".
   This is the length of the vector from the origin to the point given
   by the coordinates.

   For a two dimensional point "(x, y)", this is equivalent to
   computing the hypotenuse of a right triangle using the Pythagorean
   theorem, "sqrt(x*x + y*y)".

   在 3.8 版的變更: Added support for n-dimensional points. Formerly,
   only the two dimensional case was supported.

   在 3.10 版的變更: Improved the algorithm's accuracy so that the
   maximum error is under 1 ulp (unit in the last place).  More
   typically, the result is almost always correctly rounded to within
   1/2 ulp.

math.sin(x)

   Return the sine of *x* radians.

math.tan(x)

   Return the tangent of *x* radians.


Angular conversion
==================

math.degrees(x)

   Convert angle *x* from radians to degrees.

math.radians(x)

   Convert angle *x* from degrees to radians.


Hyperbolic functions
====================

Hyperbolic functions are analogs of trigonometric functions that are
based on hyperbolas instead of circles.

math.acosh(x)

   Return the inverse hyperbolic cosine of *x*.

math.asinh(x)

   Return the inverse hyperbolic sine of *x*.

math.atanh(x)

   Return the inverse hyperbolic tangent of *x*.

math.cosh(x)

   Return the hyperbolic cosine of *x*.

math.sinh(x)

   Return the hyperbolic sine of *x*.

math.tanh(x)

   Return the hyperbolic tangent of *x*.


Special functions
=================

math.erf(x)

   Return the error function at *x*.

   The "erf()" function can be used to compute traditional statistical
   functions such as the cumulative standard normal distribution:

      def phi(x):
          'Cumulative distribution function for the standard normal distribution'
          return (1.0 + erf(x / sqrt(2.0))) / 2.0

   在 3.2 版被加入.

math.erfc(x)

   Return the complementary error function at *x*.  The complementary
   error function is defined as "1.0 - erf(x)".  It is used for large
   values of *x* where a subtraction from one would cause a loss of
   significance.

   在 3.2 版被加入.

math.gamma(x)

   Return the Gamma function at *x*.

   在 3.2 版被加入.

math.lgamma(x)

   Return the natural logarithm of the absolute value of the Gamma
   function at *x*.

   在 3.2 版被加入.


常數
====

math.pi

   The mathematical constant *π* = 3.141592..., to available
   precision.

math.e

   The mathematical constant *e* = 2.718281..., to available
   precision.

math.tau

   The mathematical constant *τ* = 6.283185..., to available
   precision. Tau is a circle constant equal to 2*π*, the ratio of a
   circle's circumference to its radius. To learn more about Tau,
   check out Vi Hart's video Pi is (still) Wrong, and start
   celebrating Tau day by eating twice as much pie!

   在 3.6 版被加入.

math.inf

   A floating-point positive infinity.  (For negative infinity, use
   "-math.inf".)  Equivalent to the output of "float('inf')".

   在 3.5 版被加入.

math.nan

   A floating-point "not a number" (NaN) value. Equivalent to the
   output of "float('nan')". Due to the requirements of the IEEE-754
   standard, "math.nan" and "float('nan')" are not considered to equal
   to any other numeric value, including themselves. To check whether
   a number is a NaN, use the "isnan()" function to test for NaNs
   instead of "is" or "==". Example:

   >>> import math
   >>> math.nan == math.nan
   False
   >>> float('nan') == float('nan')
   False
   >>> math.isnan(math.nan)
   True
   >>> math.isnan(float('nan'))
   True

   在 3.5 版被加入.

   在 3.11 版的變更: It is now always available.

**CPython 實作細節：** The "math" module consists mostly of thin
wrappers around the platform C math library functions.  Behavior in
exceptional cases follows Annex F of the C99 standard where
appropriate.  The current implementation will raise "ValueError" for
invalid operations like "sqrt(-1.0)" or "log(0.0)" (where C99 Annex F
recommends signaling invalid operation or divide-by-zero), and
"OverflowError" for results that overflow (for example,
"exp(1000.0)").  A NaN will not be returned from any of the functions
above unless one or more of the input arguments was a NaN; in that
case, most functions will return a NaN, but (again following C99 Annex
F) there are some exceptions to this rule, for example
"pow(float('nan'), 0.0)" or "hypot(float('nan'), float('inf'))".

Note that Python makes no effort to distinguish signaling NaNs from
quiet NaNs, and behavior for signaling NaNs remains unspecified.
Typical behavior is to treat all NaNs as though they were quiet.

也參考:

  "cmath" 模組
     Complex number versions of many of these functions.
