
:mod:`cmath` --- 複素数のための数学関数
=======================================

.. module:: cmath
   :synopsis: 複素数のための数学関数です。


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

.. note::

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


複素数の座標
-------------------

複素数を表現する二つの重要な座標系があります。
Python の :class:`complex` 型は直交座標を用いており、
複素数平面上の数は実数部と虚数部という二つの浮動小数点数で定義されます。

定義::

   z = x + 1j * y

   x := real(z)
   y := imag(z)

工学においては複素数を表すのに極座標を用いるのが一般的です。
極座標では複素数は半径 *r* と位相角 *phi* で定義されます。
半径 *r* はその複素数の絶対値、あるいは (0, 0) からの距離と見なせるものです。
半径 *r* はいつでも 0 または正の浮動小数点数です。
位相角 *phi* は x 軸からの反時計回りの角度で、
たとえば *1* の角度は *0* で、 *1j* の角度は *π/2* そして *-1* では *-π* です。

.. note::
   :func:`phase` と :func:`polar` は負の実数に対し *+π* を返す一方で、
   非常に小さな負の虚数部をもつ *-1-1E-300j* のような複素数に対しては *-π* を返します。


定義::

   z = r * exp(1j * phi)
   z = r * cis(phi)

   r := abs(z) := sqrt(real(z)**2 + imag(z)**2)
   phi := phase(z) := atan2(imag(z), real(z))
   cis(phi) := cos(phi) + 1j * sin(phi)


.. function:: phase(x)

   複素数の位相角 (偏角とも呼ぶ) を返します。

   .. versionadded:: 2.6


.. function:: polar(x)

   複素数を直交座標から極座標に変換します。
   この関数は二つの要素 *r* および *phi* から成るタプルを返します。
   *r* は 0 からの距離で *phi* は位相角です。

   .. versionadded:: 2.6


.. function:: rect(r, phi)

   極座標から直交座標に変換し、 :class:`complex` オブジェクトを返します。

   .. versionadded:: 2.6



cmath 関数
---------------

.. function:: acos(x)

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


.. function:: acosh(x)

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


.. function:: asin(x)

   *x* の逆正弦を返します。 :func:`acos` と同じ分枝切断を持ちます。


.. function:: asinh(x)

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

   .. versionchanged:: 2.6
      分枝切断が C99 標準で推奨されたものに合わせて動かされました。

.. function:: atan(x)

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

   .. versionchanged:: 2.6
      上側の分割での連続な方向が逆転しました。

.. function:: atanh(x)

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

   .. versionchanged:: 2.6
      右側の分割での連続な方向が逆転しました。

.. function:: cos(x)

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


.. function:: cosh(x)

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


.. function:: exp(x)

   指数値 ``e**x`` を返します。


.. function:: isinf(x)

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

   .. versionadded:: 2.6


.. function:: isnan(x)

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

   .. versionadded:: 2.6


.. function:: log(x[, base])

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

   .. versionchanged:: 2.4
      引数 *base* が追加されました。


.. function:: log10(x)

   *x* の底 10 対数を返します。 :func:`log` と同じ分枝切断を持ちます。


.. function:: sin(x)

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


.. function:: sinh(x)

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


.. function:: sqrt(x)

   *x* の平方根を返します。 :func:`log` と同じ分枝切断を持ちます。


.. function:: tan(x)

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


.. function:: tanh(x)

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


このモジュールではまた、以下の数学定数も定義しています:

.. data:: pi

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


.. data:: e

   定数 *e* (自然対数の底)で、浮動小数点数です。

.. index:: module: math

:mod:`math` と同じような関数が選ばれていますが、全く同じではないので注意してください。
機能を二つのモジュールに分けているのは、複素数に興味がなかったり、もしかすると複素数とは何かすら知らないようなユーザがいるからです。
そういった人たちはむしろ、 ``math.sqrt(-1)`` が複素数を返すよりも例外を送出してほしいと考えます。
また、 :mod:`cmath` で定義されている関数は、
たとえ結果が実数で表現可能な場合 (虚数部がゼロの複素数) でも、
常に複素数を返すので注意してください。

分枝切断(branch cut)に関する注釈:
分枝切断をもつ曲線上では、与えられた関数は連続でありえなくなります。
これらは多くの複素関数における必然的な特性です。
複素関数を計算する必要がある場合、これらの分枝に関して理解しているものと仮定しています。
悟りに至るために何らかの(到底基礎的とはいえない)複素数に関する書をひもといてください。
数値計算を目的とした分枝切断の正しい選択方法についての情報としては、
以下がよい参考文献となります:

.. seealso::

   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.

