9.3. "cmath" --- 複素数のための数学関数
***************************************

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

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


9.3.1. 極座標変換
=================

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.1415926535897931
      >>> phase(complex(-1.0, -0.0))
      -3.1415926535897931

   バージョン 2.6 で追加.

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

cmath.polar(x)

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

   バージョン 2.6 で追加.

cmath.rect(r, phi)

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

   バージョン 2.6 で追加.


9.3.2. 指数関数と対数関数
=========================

cmath.exp(x)

   指数 "e**x" を返します。

cmath.log(x[, base])

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

   バージョン 2.4 で変更: 引数 *base* を追加

cmath.log10(x)

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

cmath.sqrt(x)

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


9.3.3. 三角関数
===============

cmath.acos(x)

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

cmath.asin(x)

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

cmath.atan(x)

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

   バージョン 2.6 で変更: 上側の分割での連続な方向が逆転しました。

cmath.cos(x)

   *x* の余弦を返します。

cmath.sin(x)

   *x* の正弦を返します。

cmath.tan(x)

   *x* の正接を返します。


9.3.4. 双曲線関数
=================

cmath.acosh(x)

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

cmath.asinh(x)

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

   バージョン 2.6 で変更: 分枝切断が C99 標準で推奨されたものに合わせ
   て動かされました。

cmath.atanh(x)

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

   バージョン 2.6 で変更: 右側の分割での連続な方向が逆転しました。

cmath.cosh(x)

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

cmath.sinh(x)

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

cmath.tanh(x)

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


9.3.5. 類別関数
===============

cmath.isinf(x)

   *x* の実数部または虚数部が正または負の無限大であれば "True" を返し
   ます。

   バージョン 2.6 で追加.

cmath.isnan(x)

   *x* の実数部または虚数部が非数 (NaN) であれば "True" を返します。

   バージョン 2.6 で追加.


9.3.6. 定数
===========

cmath.pi

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

cmath.e

   定数 *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.
