# `cmath` --- 複素数のための数学関数

このモジュールは、複素数を扱う数学関数へのアクセスを提供しています。 このモジュール中の関数は整数、浮動小数点数または複素数を引数にとります。 また、 `__complex__()` または `__float__()` どちらかのメソッドを提供している Python オブジェクトも受け付けます。 これらのメソッドはそのオブジェクトを複素数または浮動小数点数に変換するのにそれぞれ使われ、呼び出された関数はそうして変換された結果を利用します。

注釈

ハードウェア及びシステムレベルでの符号付きゼロのサポートがあるプラットフォームでは、分枝切断 (branch cut) の関わる関数において切断された 両側 の分枝で連続になります。ゼロの符号でどちらの分枝であるかを区別するのです。符号付きゼロがサポートされないプラットフォームでは連続性は以下の仕様で述べるようになります。

## 極座標変換

Python の複素数 `z` は内部的には 直交座標 もしくは デカルト座標 と呼ばれる座標を使って格納されています。この座標はその複素数の 実部 `z.real` と 虚部 `z.imag` で決まります。言い換えると:

    z == z.real + z.imag*1j

極座標 は複素数を表現する別の方法です。極座標では、複素数 z は半径 r と位相角 phi で定義されます。半径 r は z から原点までの距離です。位相 phi は x 軸の正の部分から原点と z を結んだ線分までの角度を反時計回りにラジアンで測った値です。

次の関数はネイティブの直交座標を極座標に変換したりその逆を行うのに使えます。

`cmath.``phase`(x)

  x の位相 (x の 偏角 とも呼びます) を浮動小数点数で返します。`phase(x)` は `math.atan2(x.imag, x.real)` と同等です。返り値は [-π, π] の範囲にあり、この演算の分枝切断は負の実軸に沿って延びていて、上から連続です。(現在のほとんどのシステムはそうですが) 符号付きゼロをサポートしているシステムでは、結果の符号は `x.imag` がゼロであってさえ `x.imag` の符号と等しくなります:

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

注釈

複素数 x のモジュラス (絶対値) は組み込みの `abs()` 関数で計算できます。この演算を行う `cmath` モジュールの関数はありません。

`cmath.``polar`(x)

  x の極座標表現を返します。x の半径 r と x の位相 phi の組 `(r, phi)` を返します。`polar(x)` は `(abs(x), phase(x))` に等しいです。

`cmath.``rect`(r, phi)

  極座標 r, phi を持つ複素数 x を返します。値は `r * (math.cos(phi) + math.sin(phi)*1j)` に等しいです。

## 指数関数と対数関数

`cmath.``exp`(x)

  e を自然対数の底として、 e の x 乗を返します。

`cmath.``log`(x[, base])

  base を底とする x の対数を返します。もし base が指定されていない場合には、x の自然対数を返します。分枝切断を一つもち、`0` から負の実数軸に沿って `-∞` へと延びており、上から連続しています。

`cmath.``log10`(x)

  x の底を 10 とする対数を返します。 `log()` と同じ分枝切断を持ちます。

`cmath.``sqrt`(x)

  x の平方根を返します。 `log()` と同じ分枝切断を持ちます。

## 三角関数

`cmath.``acos`(x)

  x の逆余弦を返します。この関数には二つの分枝切断 (branch cut) があります: 一つは 1 から右側に実数軸に沿って∞へと延びていて、下から連続しています。もう一つは -1 から左側に実数軸に沿って -∞へと延びていて、上から連続しています。

`cmath.``asin`(x)

  x の逆正弦を返します。 `acos()` と同じ分枝切断を持ちます。

`cmath.``atan`(x)

  x の逆正接を返します。二つの分枝切断があります: 一つは `1j` から虚数軸に沿って `∞j` へと延びており、右から連続です。もう一つは `-1j` から虚数軸に沿って `-∞j` へと延びており、左から連続です。

`cmath.``cos`(x)

  x の余弦を返します。

`cmath.``sin`(x)

  x の正弦を返します。

`cmath.``tan`(x)

  x の正接を返します。

## 双曲線関数

`cmath.``acosh`(x)

  x の逆双曲線余弦を返します。分枝切断が一つあり、1 の左側に実数軸に沿って -∞へと延びていて、上から連続しています。

`cmath.``asinh`(x)

  x の逆双曲線正弦を返します。二つの分枝切断があります: 一つは `1j` から虚数軸に沿って `∞j` へと延びており、右から連続です。もう一つは `-1j` から虚数軸に沿って `-∞j` へと延びており、左から連続です。

`cmath.``atanh`(x)

  x の逆双曲線正接を返します。二つの分枝切断があります: 一つは `1` から実数軸に沿って `∞` へと延びており、下から連続です。もう一つは `-1` から実数軸に沿って `-∞` へと延びており、上から連続です。

`cmath.``cosh`(x)

  x の双曲線余弦を返します。

`cmath.``sinh`(x)

  x の双曲線正弦を返します。

`cmath.``tanh`(x)

  x の双曲線正接を返します。

## 類別関数

`cmath.``isfinite`(x)

  x の実部、虚部ともに有限であれば `True` を返し、それ以外の場合 `False` を返します。

  バージョン 3.2 で追加.

`cmath.``isinf`(x)

  x の実数部または虚数部が正または負の無限大であれば `True` を、そうでなければ `False` を返します。

`cmath.``isnan`(x)

  x の実部と虚部のどちらかが NaN のとき `True` を返し、それ以外の場合 `False` を返します。

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

  値 a と b が互いに近い場合 `True` を、そうでない場合は `False` を返します。

  2値が近いと見なされるかどうかは与えられた絶対または相対許容差により決定されます。

  rel_tol は相対許容差、すなわち a と b の絶対値の大きい方に対する a と b の許容される最大の差です。 例えば許容差を 5% に設定する場合 `rel_tol=0.05` を渡します。 デフォルトの許容差は `1e-09` で、2値が9桁同じことを保証します。 rel_tol は0より大きくなければなりません。

  abs_tol は最小の絶対許容差です。0に近い値を比較するのに有用です。abs_tol は0より大きくなければなりません。

  エラーが起こらなければ結果は `abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)` です。

  IEEE 754 特殊値 `NaN`、`inf`、`-inf` は IEEE の規則に従って処理されます。 具体的には、`NaN` は自身を含めたあらゆる値に近いとは見なされません。 `inf` と `-inf` は自身とのみ近いと見なされます。

  バージョン 3.5 で追加.

  参考

  PEP 485 -- A function for testing approximate equality

## 定数

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

  浮動小数点数の非数 "not a number" (NaN) です。`float('nan')` と等価です。

  バージョン 3.6 で追加.

`cmath.``nanj`

  実部がゼロ、虚部が NaN の複素数です。`complex(0.0, float('nan'))` と等価です。

  バージョン 3.6 で追加.

`math` と同じような関数が選ばれていますが、全く同じではないので注意してください。機能を二つのモジュールに分けているのは、複素数に興味がなかったり、もしかすると複素数とは何かすら知らないようなユーザがいるからです。そういった人たちはむしろ、 `math.sqrt(-1)` が複素数を返すよりも例外を送出してほしいと考えます。また、 `cmath` で定義されている関数は、たとえ結果が実数で表現可能な場合 (虚数部がゼロの複素数) でも、常に複素数を返すので注意してください。

分枝切断 (branch cut) に関する注釈: 分枝切断を持つ曲線上では、与えられた関数は連続ではなくなります。これらは多くの複素関数における必然的な特性です。複素関数を計算する必要がある場合、これらの分枝に関して理解しているものと仮定しています。悟りに至るために何らかの (到底基礎的とはいえない) 複素数に関する書をひもといてください。数値計算を目的とした分枝切断の正しい選択方法についての情報としては、以下がよい参考文献となります:

参考

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