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.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)" に等しいです。


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

cmath.exp(x)

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

cmath.log(x[, base])

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

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" へと延びており、左から連続です。

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" へと延びており、左から連続です。

cmath.atanh(x)

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

cmath.cosh(x)

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

cmath.sinh(x)

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

cmath.tanh(x)

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


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

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


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

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.
