cmath --- 複素数用の数学関数

---

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

注釈

分枝切断を持つ関数では、切断そのものの上で関数をどう定義するかが問題になります。 Kahan の論文 "Branch cuts for complex elementary functions" と、C99 以降の C 規格の附属書 G に従い、ゼロの符号で分枝切断のどちら側かを区別します。 実軸の一部に沿った分枝切断では虚部の符号を使い、虚軸に沿った分枝切断では実部の符号を使います。

例えば 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])	base (デフォルトは e) を底とする z の対数を返します
log10(z)	10 を底とする z の対数を返します
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)	z の実部と虚部が両方とも有限かどうかを調べます
isinf(z)	z の実部または虚部が無限大かどうかを調べます
isnan(z)	z の実部または虚部が NaN かどうかを調べます
isclose(a, b, *, rel_tol, abs_tol)	a と b の値が互いに近いかどうかを調べます
定数
pi	π = 3.141592...
e	e = 2.718281...
tau	τ = 2π = 6.283185...
inf	正の無限大
infj	虚部が無限大の純虚数
nan	非数 "Not a number" (NaN)
nanj	虚部が NaN の純虚数

極座標変換

Python の複素数 z は、内部では 直交座標 (デカルト座標) で保持されます。 実部 z.real と 虚部 z.imag によって完全に定まります。

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

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

cmath.phase(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 乗を返します。

cmath.log(z[, base])

base を底とする z の対数を返します。 base を指定しない場合は z の自然対数を返します。 分枝切断は 1 つで、0 から負の実軸に沿って -∞ まで延びています。

cmath.log10(z)

10 を底とする z の対数を返します。 分枝切断は log() と同じです。

cmath.sqrt(z)

z の平方根を返します。 分枝切断は log() と同じです。

三角関数

cmath.acos(z)

z の逆余弦を返します。 分枝切断は 2 つあります。 一方は 1 から実軸に沿って右に ∞ まで、もう一方は -1 から実軸に沿って左に -∞ まで延びています。

cmath.asin(z)

z の逆正弦を返します。 分枝切断は acos() と同じです。

cmath.atan(z)

z の逆正接を返します。 分枝切断は 2 つあります。 一方は 1j から虚軸に沿って ∞j まで、もう一方は -1j から虚軸に沿って -∞j まで延びています。

cmath.cos(z)

z の余弦を返します。

cmath.sin(z)

z の正弦を返します。

cmath.tan(z)

z の正接を返します。

双曲線関数

cmath.acosh(z)

z の逆双曲線余弦を返します。 分枝切断は 1 つで、1 から実軸に沿って左に -∞ まで延びています。

cmath.asinh(z)

z の逆双曲線正弦を返します。 分枝切断は 2 つあります。 一方は 1j から虚軸に沿って ∞j まで、もう一方は -1j から虚軸に沿って -∞j まで延びています。

cmath.atanh(z)

z の逆双曲線正接を返します。 分枝切断は 2 つあります。 一方は 1 から実軸に沿って ∞ まで、もう一方は -1 から実軸に沿って -∞ まで延びています。

cmath.cosh(z)

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

cmath.sinh(z)

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

cmath.tanh(z)

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

類別関数

cmath.isfinite(z)

z の実部と虚部が両方とも有限なら True、それ以外は False を返します。

Added in version 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 を返します。

2 つの値が近いかどうかは、指定された絶対許容誤差と相対許容誤差で判定します。 エラーが発生しなければ、結果は abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol) です。

rel_tol は相対許容誤差です。 a と b の絶対値の大きい方に対する、許容する差の最大の割合を指定します。 例えば許容誤差を 5% にするには rel_tol=0.05 を渡します。 デフォルトの許容誤差は 1e-09 で、およそ 10 進 9 桁の範囲で 2 つの値が一致することを保証します。 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 は IEEE の規則に従って処理されます。 具体的には、NaN は自身を含めたあらゆる値に近いとは見なされません。 inf と -inf は自身とのみ近いと見なされます。

Added in version 3.5.

参考

PEP 485 -- 近似的に等しいことを調べる関数

定数

cmath.pi

定数 π (円周率)で、浮動小数点数です。

cmath.e

定数 e (自然対数の底)で、浮動小数点数です。

cmath.tau

数学定数 τ で、浮動小数点数です。

Added in version 3.6.

cmath.inf

浮動小数点数の正の無限大です。float('inf') と等価です。

Added in version 3.6.

cmath.infj

実部がゼロ、虚部が正の無限大の複素数です。complex(0.0, float('inf')) と等価です。

Added in version 3.6.

cmath.nan

浮動小数点数の非数 (NaN) です。 float('nan') と同じです。 math.nan も参照してください。

Added in version 3.6.

cmath.nanj

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

Added in version 3.6.

Note that the selection of functions is similar, but not identical, to that in module math. The reason for having two modules is that some users aren't interested in complex numbers, and perhaps don't even know what they are. They would rather have math.sqrt(-1) raise an exception than return a complex number. Also note that the functions defined in cmath always return a complex number, even if the answer can be expressed as a real number (in which case the complex number has an imaginary part of zero).

分枝切断 (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.