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

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

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

備註:

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

     >>> cmath.sqrt(-2-0j)
     -1.4142135623730951j

  但是引數 "-2+0j" 會被當成位於分枝切割上方處理：

     >>> cmath.sqrt(-2+0j)
     1.4142135623730951j

+------------------------------------------------------+--------------------------------------------------------------------+
| **轉換到極座標和從極座標做轉換**                                                                                          |
+------------------------------------------------------+--------------------------------------------------------------------+
| "phase(z)"                                           | 回傳 *z* 的相位角。                                                |
+------------------------------------------------------+--------------------------------------------------------------------+
| "polar(z)"                                           | 回傳 *z* 在極座標中的表達方式。                                    |
+------------------------------------------------------+--------------------------------------------------------------------+
| "rect(r, phi)"                                       | 透過極座標 *r* 和 *phi* 回傳複數 *z*。                             |
+------------------------------------------------------+--------------------------------------------------------------------+
| **冪函數和對數函數**                                                                                                      |
+------------------------------------------------------+--------------------------------------------------------------------+
| "exp(z)"                                             | 回傳 *e* 的 *z* 次方。                                             |
+------------------------------------------------------+--------------------------------------------------------------------+
| "log(z[, base])"                                     | 回傳 *z* 以給定 *base* 為底（預設為 *e*）的對數。                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "log10(z)"                                           | 回傳 *z* 以 10 為底的對數。                                        |
+------------------------------------------------------+--------------------------------------------------------------------+
| "sqrt(z)"                                            | 回傳 *z* 的平方根。                                                |
+------------------------------------------------------+--------------------------------------------------------------------+
| **三角函數**                                                                                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "acos(z)"                                            | 回傳 *z* 的反餘弦值。                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "asin(z)"                                            | 回傳 *z* 的反正弦值。                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "atan(z)"                                            | 回傳 *z* 的反正切值。                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "cos(z)"                                             | 回傳 *z* 的餘弦值。                                                |
+------------------------------------------------------+--------------------------------------------------------------------+
| "sin(z)"                                             | 回傳 *z* 的正弦值。                                                |
+------------------------------------------------------+--------------------------------------------------------------------+
| "tan(z)"                                             | 回傳 *z* 的正切值。                                                |
+------------------------------------------------------+--------------------------------------------------------------------+
| **雙曲函數**                                                                                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "acosh(z)"                                           | 回傳 *z* 的反雙曲餘弦值。                                          |
+------------------------------------------------------+--------------------------------------------------------------------+
| "asinh(z)"                                           | 回傳 *z* 的反雙曲正弦值。                                          |
+------------------------------------------------------+--------------------------------------------------------------------+
| "atanh(z)"                                           | 回傳 *z* 的反雙曲正切值。                                          |
+------------------------------------------------------+--------------------------------------------------------------------+
| "cosh(z)"                                            | 回傳 *z* 的雙曲餘弦值。                                            |
+------------------------------------------------------+--------------------------------------------------------------------+
| "sinh(z)"                                            | 回傳 *z* 的雙曲正弦值。                                            |
+------------------------------------------------------+--------------------------------------------------------------------+
| "tanh(z)"                                            | 回傳 *z* 的雙曲正切值。                                            |
+------------------------------------------------------+--------------------------------------------------------------------+
| **分類函數**                                                                                                              |
+------------------------------------------------------+--------------------------------------------------------------------+
| "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)"                 | 檢查 *a* 和 *b* 的值是否接近                                       |
+------------------------------------------------------+--------------------------------------------------------------------+
| **常數**                                                                                                                  |
+------------------------------------------------------+--------------------------------------------------------------------+
| "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)

   以浮點數的形式回傳 *z* 的相位角（也稱為 *z* 的 *引數* ）。
   "phase(z)" 等價於 "math.atan2(z.imag, z.real)"。結果將位於 [-*π*,
   *π*] 的範圍內，且此操作的分枝切割將位於負實軸上。結果的符號會與
   "z.imag" 的符號相同，即使 "z.imag" 為零：

      >>> phase(-1+0j)
      3.141592653589793
      >>> phase(-1-0j)
      -3.141592653589793

備註:

  複數 *z* 的絕對值可以使用內建的 "abs()" 函式計算。沒有單獨的 "cmath"
  模組函式適用於此操作。

cmath.polar(z)

   回傳 *z* 在極座標中的表達方式。回傳一組數對 "(r, phi)"， *r* 是 *z*
   的絕對值， *phi* 是 *z* 的相位角。 "polar(z)" 相當於 "(abs(z),
   phase(z))"。

cmath.rect(r, phi)

   透過極座標 *r* 和 *phi* 回傳複數 *z*。相當於 "complex(r *
   math.cos(phi), r * math.sin(phi))"。


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

cmath.exp(z)

   回傳 *e* 的 *z* 次方，其中 *e* 是自然對數的底數。

cmath.log(z[, base])

   回傳 *z* 給定 *base* 的對數。如果未指定 *base*，則傳回 *z* 的自然對
   數。存在一條分枝切割，從 0 沿負實數軸到 -∞。

cmath.log10(z)

   回傳 *z* 以 10 為底的對數。它與 "log()" 具有相同的分枝切割。

cmath.sqrt(z)

   回傳 *z* 的平方根。它與 "log()" 具有相同的分枝切割。


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

cmath.acos(z)

   回傳 *z* 的反餘弦值。存在兩條分枝切割：一條是從 1 沿著實數軸向右延
   伸到 ∞。另一條從 -1 沿實數軸向左延伸到 -∞。

cmath.asin(z)

   回傳 *z* 的反正弦值。它與 "acos()" 具有相同的分枝切割。

cmath.atan(z)

   回傳 *z* 的反正切值。有兩條分枝切割：一條是從 "1j" 沿著虛軸延伸到
   "∞j"。另一條從 "-1j" 沿著虛軸延伸到 "-∞j"。

cmath.cos(z)

   回傳 *z* 的餘弦值。

cmath.sin(z)

   回傳 *z* 的正弦值。

cmath.tan(z)

   回傳 *z* 的正切值。


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

cmath.acosh(z)

   回傳 *z* 的反雙曲餘弦值。存在一條分枝切割，從 1 沿實數軸向左延伸到
   -∞。

cmath.asinh(z)

   回傳 *z* 的反雙曲正弦值。存在兩條分枝切割：一條是從 "1j" 沿著虛軸延
   伸到 "∞j"。另一條從 "-1j" 沿著虛軸延伸到 "-∞j"。

cmath.atanh(z)

   回傳 *z* 的反雙曲正切值。存在兩條分枝切割：一條是從 "1" 沿著實數軸
   延伸到 "∞"。另一條從 "-1" 沿著實數軸延伸到 "-∞"。

cmath.cosh(z)

   回傳 *z* 的反雙曲餘弦值。

cmath.sinh(z)

   回傳 *z* 的反雙曲正弦值。

cmath.tanh(z)

   回傳 *z* 的反雙曲正切值。


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

cmath.isfinite(z)

   如果 *z* 的實部和虛部都是有限的，則回傳 "True"，否則回傳 "False"。

   在 3.2 版被加入.

cmath.isinf(z)

   如果 *z* 的實部或虛部是無窮大，則回傳 "True"，否則回傳 "False"。

cmath.isnan(z)

   如果 *z* 的實部或虛部為 NaN，則回傳 "True"，否則回傳 "False"。

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

   如果 *a* 和 *b* 的值相互接近，則回傳 "True"，否則回傳 "False"。

   兩數是否足夠接近取決於給定的絕對及相對容許偏差 (tolerance)。如果沒
   有錯誤發生，結果將為："abs(a-b) <= max(rel_tol * max(abs(a),
   abs(b)), abs_tol)"。

   *rel_tol* 為相對容許偏差 ── *a* 與 *b* 兩數差的最大容許值，與 *a*
   及 *b* 兩數的絕對值中較大者相關。例如欲設置 5% 的容許偏差，則傳入
   "rel_tol=0.05"。其預設值為 "1e-09"，該值可確保兩數於大約 9 個十進數
   位內相同。*rel_tol* 須不為負且小於 "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" 會根據該
   標準處理。更明確地說，"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')"。另請參閱 "math.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.
