このモジュールは常に利用できます。提供しているのは複素数を扱う数学関数へのアクセス手段です。このモジュール中の関数は整数、浮動小数点数または複素数を引数にとります。また、 __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 を結んだ線分までの角度を反時計回りにラジアンで測った値です。
次の関数はネイティブの直交座標を極座標に変換したりその逆を行うのに使えます。
x の位相 (x の 偏角 とも呼びます) を浮動小数点数で返します。 phase(x) は math.atan2(x.imag, x.real) と同等です。返り値は [-π, π] の範囲にあり、この演算の分枝切断は負の実軸に沿って延びていて、上から連続です。 (現在のほとんどのシステムはそうですが) 符号付きゼロをサポートしているシステムでは、返り値の符号は x.imag がゼロであってもその符号と等しくなります:
>>> phase(complex(-1.0, 0.0))
3.1415926535897931
>>> phase(complex(-1.0, -0.0))
-3.1415926535897931
バージョン 2.6 で追加.
x の極座標表現を返します。 x の半径 r と x の位相 phi の組 (r, phi) を返します。 polar(x) は (abs(x), phase(x)) に等しいです。
バージョン 2.6 で追加.
極座標 r, phi を持つ複素数 x を返します。値は r * (math.cos(phi) + math.sin(phi)*1j) に等しいです。
バージョン 2.6 で追加.
指数 e**x を返します。
base を底とする x の対数を返します。もし base が指定されていない場合には、 x の自然対数を返します。分枝切断を一つもち、 0 から負の実数軸に沿って -∞ へと延びており、上から連続しています。
バージョン 2.4 で変更: base 引数が追加されました。
x の逆余弦を返します。この関数には二つの分枝切断(branch cut)があります: 一つは 1 から右側に実数軸に沿って∞へと延びていて、下から連続しています。もう一つは -1 から左側に実数軸に沿って -∞へと延びていて、上から連続しています。
x の逆正接を返します。二つの分枝切断があります: 一つは 1j から虚数軸に沿って ∞j へと延びており、右から連続です。もう一つは -1j から虚数軸に沿って -∞j へと延びており、左から連続です。
バージョン 2.6 で変更: 上側の分割での連続な方向が逆転しました。
x の余弦を返します。
x の正弦を返します。
x の正接を返します。
x の逆双曲線余弦を返します。分枝切断が一つあり、1 の左側に実数軸に沿って -∞へと延びていて、上から連続しています。
x の逆双曲線正弦を返します。二つの分枝切断があります:一つは 1j から虚数軸に沿って ∞j へと延びており、右から連続です。もう一つは -1j から虚数軸に沿って -∞j へと延びており、左から連続です。
バージョン 2.6 で変更: 分枝切断が C99 標準で推奨されたものに合わせて動かされました。
x の逆双曲線正接を返します。二つの分枝切断があります: 一つは 1 から実数軸に沿って ∞ へと延びており、下から連続です。もう一つは -1 から実数軸に沿って -∞ へと延びており、上から連続です。
バージョン 2.6 で変更: 右側の分割での連続な方向が逆転しました。
x の双曲線余弦を返します。
x の双曲線正弦を返します。
x の双曲線正接を返します。
x の実数部または虚数部が正または負の無限大であれば True を返します。
バージョン 2.6 で追加.
x の実数部または虚数部が非数 (NaN) であれば True を返します。
バージョン 2.6 で追加.
定数 π (円周率)で、浮動小数点数です。
定数 e (自然対数の底)で、浮動小数点数です。
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.