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

---

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

注釈

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

For example, the cmath.sqrt() function has a branch cut along the negative real axis. An argument of complex(-2.0, -0.0) is treated as though it lies below the branch cut, and so gives a result on the negative imaginary axis:

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

But an argument of complex(-2.0, 0.0) is treated as though it lies above the branch cut:

>>> cmath.sqrt(complex(-2.0, 0.0))
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(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)

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 で、2 つの値がおよそ 10 進 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 は IEEE の規則に従って処理されます。 具体的には、NaN は自身を含めたあらゆる値に近いとは見なされません。 inf と -inf は自身とのみ近いと見なされます。

Added in version 3.5.

参考

PEP 485 -- A function for testing approximate equality

定数

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

A floating-point "not a number" (NaN) value. Equivalent to float('nan'). See also math.nan.

Added in version 3.6.

cmath.nanj

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

Added in version 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.