# `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.