"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.
