"cmath" --- 複數的數學函式
**************************

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

本模組提供一些適用於複數的數學函式。本模組中的函式接受整數、浮點數或複
數作為引數。它們也接受任何具有 "__complex__()" 或 "__float__()" 方法的
Python 物件：這些方法分別用於將物件轉換為複數或浮點數，然後再將函式應
用於轉換後的結果。

備註:

  對於涉及分枝切割 (branch cut) 的函式，我們面臨的問題是決定如何定義在
  切割本身上的這些函式。遵循 Kahan 的論文 "Branch cuts for complex
  elementary functions"，以及 C99 的附錄 G 和後來的 C 標準，我們使用零
  符號來區分分枝切割的兩側：對於沿著（一部分）實數軸的分枝切割，我們查
  看虛部的符號，而對於沿虛軸的分枝切割，我們則查看實部的符號。例如
  "cmath.sqrt()" 函式具有一條沿負實軸的分枝切割。 引數 "complex(-2.0,
  -0.0)" 被視為位於分枝切割 *下方* 處理，因此給出的結果在負虛軸上：

     >>> cmath.sqrt(complex(-2.0, -0.0))
     -1.4142135623730951j

  但是引數 "complex(-2.0, 0.0)" 會被當成位於分枝切割上方處理：

     >>> cmath.sqrt(complex(-2.0, 0.0))
     1.4142135623730951j

+------------------------------------------------------+--------------------------------------------------------------------+
| **Conversions to and from polar coordinates**                                                                             |
+------------------------------------------------------+--------------------------------------------------------------------+
| "phase(z)"                                           | Return the phase of *z*                                            |
+------------------------------------------------------+--------------------------------------------------------------------+
| "polar(z)"                                           | Return the representation of *z* in polar coordinates              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "rect(r, phi)"                                       | Return the complex number *z* with polar coordinates *r* and *phi* |
+------------------------------------------------------+--------------------------------------------------------------------+
| **Power and logarithmic functions**                                                                                       |
+------------------------------------------------------+--------------------------------------------------------------------+
| "exp(z)"                                             | Return *e* raised to the power *z*                                 |
+------------------------------------------------------+--------------------------------------------------------------------+
| "log(z[, base])"                                     | Return the logarithm of *z* to the given *base* (*e* by default)   |
+------------------------------------------------------+--------------------------------------------------------------------+
| "log10(z)"                                           | Return the base-10 logarithm of *z*                                |
+------------------------------------------------------+--------------------------------------------------------------------+
| "sqrt(z)"                                            | Return the square root of *z*                                      |
+------------------------------------------------------+--------------------------------------------------------------------+
| **Trigonometric functions**                                                                                               |
+------------------------------------------------------+--------------------------------------------------------------------+
| "acos(z)"                                            | Return the arc cosine of *z*                                       |
+------------------------------------------------------+--------------------------------------------------------------------+
| "asin(z)"                                            | Return the arc sine of *z*                                         |
+------------------------------------------------------+--------------------------------------------------------------------+
| "atan(z)"                                            | Return the arc tangent of *z*                                      |
+------------------------------------------------------+--------------------------------------------------------------------+
| "cos(z)"                                             | Return the cosine of *z*                                           |
+------------------------------------------------------+--------------------------------------------------------------------+
| "sin(z)"                                             | Return the sine of *z*                                             |
+------------------------------------------------------+--------------------------------------------------------------------+
| "tan(z)"                                             | Return the tangent of *z*                                          |
+------------------------------------------------------+--------------------------------------------------------------------+
| **Hyperbolic functions**                                                                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "acosh(z)"                                           | Return the inverse hyperbolic cosine of *z*                        |
+------------------------------------------------------+--------------------------------------------------------------------+
| "asinh(z)"                                           | Return the inverse hyperbolic sine of *z*                          |
+------------------------------------------------------+--------------------------------------------------------------------+
| "atanh(z)"                                           | Return the inverse hyperbolic tangent of *z*                       |
+------------------------------------------------------+--------------------------------------------------------------------+
| "cosh(z)"                                            | Return the hyperbolic cosine of *z*                                |
+------------------------------------------------------+--------------------------------------------------------------------+
| "sinh(z)"                                            | Return the hyperbolic sine of *z*                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "tanh(z)"                                            | Return the hyperbolic tangent of *z*                               |
+------------------------------------------------------+--------------------------------------------------------------------+
| **Classification functions**                                                                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "isfinite(z)"                                        | Check if all components of *z* are finite                          |
+------------------------------------------------------+--------------------------------------------------------------------+
| "isinf(z)"                                           | Check if any component of *z* is infinite                          |
+------------------------------------------------------+--------------------------------------------------------------------+
| "isnan(z)"                                           | Check if any component of *z* is a NaN                             |
+------------------------------------------------------+--------------------------------------------------------------------+
| "isclose(a, b, *, rel_tol, abs_tol)"                 | Check if the values *a* and *b* are close to each other            |
+------------------------------------------------------+--------------------------------------------------------------------+
| **Constants**                                                                                                             |
+------------------------------------------------------+--------------------------------------------------------------------+
| "pi"                                                 | *π* = 3.141592...                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "e"                                                  | *e* = 2.718281...                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "tau"                                                | *τ* = 2*π* = 6.283185...                                           |
+------------------------------------------------------+--------------------------------------------------------------------+
| "inf"                                                | Positive infinity                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "infj"                                               | Pure imaginary infinity                                            |
+------------------------------------------------------+--------------------------------------------------------------------+
| "nan"                                                | "Not a number" (NaN)                                               |
+------------------------------------------------------+--------------------------------------------------------------------+
| "nanj"                                               | Pure imaginary NaN                                                 |
+------------------------------------------------------+--------------------------------------------------------------------+


轉換到極座標和從極座標做轉換
============================

Python 複數 "z" 是用 *直角坐標* 或 *笛卡爾坐標* 儲存在內部的。它完全是
由其 *實部* "z.real" 和 *虛部* "z.imag" 所決定。

*極座標* 提供了另一種表示複數的方法。在極座標中，複數 *z* 由絕對值
(modulus) *r* 和相位角 (phase) *phi* 定義。絕對值 *r* 是從 *z* 到原點
的距離，而相位角 *phi* 是從正 x 軸到連接原點到 *z* 的線段的逆時針角度
（以弧度為單位）。

以下的函式可用於原始直角座標與極座標之間的相互轉換。

cmath.phase(z)

   Return the phase of *z* (also known as the *argument* of *z*), as a
   float. "phase(z)" is equivalent to "math.atan2(z.imag, z.real)".
   The result lies in the range [-*π*, *π*], and the branch cut for
   this operation lies along the negative real axis.  The sign of the
   result is the same as the sign of "z.imag", even when "z.imag" is
   zero:

      >>> phase(complex(-1.0, 0.0))
      3.141592653589793
      >>> phase(complex(-1.0, -0.0))
      -3.141592653589793

備註:

  The modulus (absolute value) of a complex number *z* can be computed
  using the built-in "abs()" function.  There is no separate "cmath"
  module function for this operation.

cmath.polar(z)

   Return the representation of *z* in polar coordinates.  Returns a
   pair "(r, phi)" where *r* is the modulus of *z* and *phi* is the
   phase of *z*.  "polar(z)" is equivalent to "(abs(z), phase(z))".

cmath.rect(r, phi)

   Return the complex number *z* with polar coordinates *r* and *phi*.
   Equivalent to "complex(r * math.cos(phi), r * math.sin(phi))".


冪函數和對數函數
================

cmath.exp(z)

   Return *e* raised to the power *z*, where *e* is the base of
   natural logarithms.

cmath.log(z[, base])

   Return the logarithm of *z* to the given *base*. If the *base* is
   not specified, returns the natural logarithm of *z*. There is one
   branch cut, from 0 along the negative real axis to -∞.

cmath.log10(z)

   Return the base-10 logarithm of *z*. This has the same branch cut
   as "log()".

cmath.sqrt(z)

   Return the square root of *z*. This has the same branch cut as
   "log()".


三角函數
========

cmath.acos(z)

   Return the arc cosine of *z*. There are two branch cuts: One
   extends right from 1 along the real axis to ∞. The other extends
   left from -1 along the real axis to -∞.

cmath.asin(z)

   Return the arc sine of *z*. This has the same branch cuts as
   "acos()".

cmath.atan(z)

   Return the arc tangent of *z*. There are two branch cuts: One
   extends from "1j" along the imaginary axis to "∞j". The other
   extends from "-1j" along the imaginary axis to "-∞j".

cmath.cos(z)

   Return the cosine of *z*.

cmath.sin(z)

   Return the sine of *z*.

cmath.tan(z)

   Return the tangent of *z*.


雙曲函數
========

cmath.acosh(z)

   Return the inverse hyperbolic cosine of *z*. There is one branch
   cut, extending left from 1 along the real axis to -∞.

cmath.asinh(z)

   Return the inverse hyperbolic sine of *z*. There are two branch
   cuts: One extends from "1j" along the imaginary axis to "∞j".  The
   other extends from "-1j" along the imaginary axis to "-∞j".

cmath.atanh(z)

   Return the inverse hyperbolic tangent of *z*. There are two branch
   cuts: One extends from "1" along the real axis to "∞". The other
   extends from "-1" along the real axis to "-∞".

cmath.cosh(z)

   Return the hyperbolic cosine of *z*.

cmath.sinh(z)

   Return the hyperbolic sine of *z*.

cmath.tanh(z)

   Return the hyperbolic tangent of *z*.


分類函式
========

cmath.isfinite(z)

   Return "True" if both the real and imaginary parts of *z* are
   finite, and "False" otherwise.

   在 3.2 版被加入.

cmath.isinf(z)

   Return "True" if either the real or the imaginary part of *z* is an
   infinity, and "False" otherwise.

cmath.isnan(z)

   Return "True" if either the real or the imaginary part of *z* is a
   NaN, and "False" otherwise.

cmath.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 "x" and rel_tol less than "1.0".  So add an appropriate
   positive abs_tol argument to the call.

   IEEE 754 特殊值 "NaN" 、 "inf" 和 "-inf" 將會根據 IEEE 規則進行處理
   。具體來說， "NaN" 不被認為接近任何其他值，包括 "NaN"。 "inf" 和
   "-inf" 只被認為是接近它們自己的。

   在 3.5 版被加入.

   也參考: **PEP 485** -- 一個用來測試近似相等的函式


常數
====

cmath.pi

   數學常數 *π*，作為一個浮點數。

cmath.e

   數學常數 *e*，作為一個浮點數。

cmath.tau

   數學常數 *τ*，作為一個浮點數。

   在 3.6 版被加入.

cmath.inf

   正無窮大的浮點數。相當於 "float('inf')"。

   在 3.6 版被加入.

cmath.infj

   實部為零和虛部為正無窮的複數。相當於 "complex(0.0, float('inf'))"。

   在 3.6 版被加入.

cmath.nan

   浮點「非數字」 (NaN) 值。相當於 "float('nan')"。

   在 3.6 版被加入.

cmath.nanj

   實部為零和虛部為 NaN 的複數。相當於 "complex(0.0, float('nan'))"。

   在 3.6 版被加入.

請注意，函式的選擇與模組 "math" 的類似，但並不完全相同。擁有兩個模組的
原因是有些用戶對複數不感興趣，甚至根本就不知道它們是什麼。他們寧願讓
"math.sqrt(-1)" 引發異常，也不願它回傳複數。另請注意， "cmath" 中所定
義的函式始終都會回傳複數，即使答案可以表示為實數（在這種情況下，複數的
虛部為零）。

關於分枝切割的註釋：它們是沿著給定的不連續函式的曲線。它們是許多複變函
數的必要特徵。假設你需要使用複變函數進行計算，你將會了解分枝切割的概念
。請參閱幾乎所有關於複變函數的（不是太初級的）書籍以獲得啟發。對於如何
正確地基於數值目的選擇分枝切割的相關訊息，以下內容應該是一個很好的參考
：

也參考:

  Kahan, W:  Branch cuts for complex elementary functions; or, Much
  ado about nothing's sign bit.  In Iserles, A., and Powell, M.
  (eds.), The state of the art in numerical analysis. Clarendon Press
  (1987) pp165--211.
