:mod:`math` --- 数学関数
========================

.. module:: math
   :synopsis: 数学関数(sin() など)。


このモジュールはいつでも利用できます。
標準 C で定義されている数学関数にアクセスすることができます。

これらの関数で複素数を使うことはできません。
複素数に対応する必要があるならば、
:mod:`cmath` モジュールにある同じ名前の関数を使ってください。
ほとんどのユーザーは複素数を理解するのに必要なだけの数学を勉強したくないので、複素数に対応した関数と対応していない関数の区別がされています。
これらの関数では複素数が利用できないため、引数に複素数を渡されると、複素数の結果が返るのではなく例外が発生します。
その結果、プログラマは、そもそもどういった理由で例外がスローされたのかに早い段階で気づく事ができます。 [#]_

このモジュールでは次の関数を提供しています。
明示的な注記のない限り、戻り値は全て浮動小数点数になります。

数論および数表現にまつわる関数です
-----------------------------------

.. function:: ceil(x)

   *x* の天井値 (ceil)、すなわち *x* 以上の最も小さい整数を float 型で返します。


.. function:: copysign(x, y)

   *x* に *y* の符号を付けて返します。 ``copysign`` は IEEE 754 float の
   符号ビットをコピーします。たとえば ``copysign(1, -0.0)`` は *-1.0* になります。

   .. versionadded:: 2.6


.. function:: fabs(x)

   *x* の絶対値を返します。


.. function:: factorial(x)

   *x* の階乗を返します。 *x* が整数値でなかったり負であったりするときは、
   :exc:`ValueError` を送出します。

   .. versionadded:: 2.6


.. function:: floor(x)

   *x* の床値 (floor)、すなわち *x* 以下の最も大きい整数を float型で返します。

   .. versionchanged:: 2.6
      :meth:`__floor__` への委譲が追加されました。


.. function:: fmod(x, y)

   プラットフォームの C ライブラリで定義されている ``fmod(x, y)`` を返します。 Python の ``x % y``
   という式は必ずしも同じ結果を返さないということに注意してください。 C 標準の要求では、 :cfunc:`fmod` は除算の結果が *x* と同じ符号に
   なり、大きさが ``abs(y)`` より小さくなるような整数 *n* については ``fmod(x, y)`` が厳密に (数学的に、つまり限りなく高い精度で)
   ``x - n*y``  と等価であるよう求めています。
   Python の ``x % y`` は、 *y* と同じ符号の結果を返し、
   浮動小数点の引数に対して厳密な解を出せないことがあります。
   例えば、 ``fmod(-1e-100, 1e100)`` は ``-1e-100``
   ですが、 Python の ``-1e-100 % 1e100`` は ``1e100-1e-100`` になり、
   浮動小数点型で厳密に表現できず、ややこしいことに ``1e100`` に丸められます。
   このため、一般には浮動小数点の場合には関数 :func:`fmod` 、
   整数の場合には ``x % y`` を使う方がよいでしょう。


.. function:: frexp(x)

   *x* の仮数と指数を ``(m, e)`` のペアとして返します。
   *m* はfloat型で、 *e* は厳密に ``x == m * 2**e``
   であるような整数型です。
   *x* がゼロの場合は、 ``(0.0, 0)`` を返し、それ以外の場合は、 ``0.5 <= abs(m) < 1``
   を返します。これは浮動小数点型の内部表現を可搬性を保ったまま
   "分解 (pick apart)" するためです。


.. function:: fsum(iterable)

   iterable 中の値の浮動小数点数の正確な和を返します。複数の部分和を追跡することで
   桁落ちを防ぎます::

        >>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
        0.99999999999999989
        >>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
        1.0

   アルゴリズムの正確性は IEEE-754 演算の保証と丸めモードが偶数丸め (half-even)
   である典型的な場合に依存します。
   Windows以外の幾つかのビルドでは、依存するCライブラリが、拡張精度の加算と
   時々時々合計の中間値を double 型へ丸めを行ってしまい、最下位ビットの
   消失が発生します。

   より詳しい議論と代替となる二つのアプローチについては、 `ASPN cookbook
   recipes for accurate floating point summation
   <http://code.activestate.com/recipes/393090/>`_ をご覧下さい。

   .. versionadded:: 2.6


.. function:: isinf(x)

   浮動小数点数 *x* が正または負の無限大であるかチェックします。

   .. versionadded:: 2.6


.. function:: isnan(x)

   浮動小数点数 *x* が NaN (not a number) であるかチェックします。
   NaN は IEEE 754 標準の一部です。 ``inf * 0`` 、 ``inf / inf``
   のような演算(に限りませんが)や NaN を含む演算、たとえば
   ``nan * 1`` 、は NaN を返します。

   .. versionadded:: 2.6


.. function:: ldexp(x, i)

   ``x * (2**i)`` を返します。


.. function:: modf(x)

   *x* の小数部分と整数部分を返します。
   両方の結果は *x* の符号を受け継ぎます。整数部はfloat型で返されます。


.. function:: trunc(x)

   *x* の :class:`Integral` (たいてい長整数)へ切り捨てられた :class:`Real`
   値を返します。 ``x.__trunc__()`` に委譲されます。

   .. versionadded:: 2.6


:func:`frexp` と :func:`modf` は C のものとは異なった呼び出し/返し
パターンを持っていることに注意してください。引数を1つだけ受け取り、1組のペアになった値を返すので、2つ目の戻り値を '出力用の引数'
経由で返したりはしません (Python には出力用の引数はありません)。

:func:`ceil` 、 :func:`floor` 、および :func:`modf` 関数については、
非常に大きな浮動小数点数が *全て* 整数そのものになるということに注意してください。
通常、Python の浮動小数点型は 53 ビット以上の精度をもたない (プラットフォームにおける C
double 型と同じ) ので、結果的に ``abs(x) >= 2**52`` であるような浮動小数点型 *x* は小数部分を持たなくなるのです。

指数および対数関数
------------------

.. function:: exp(x)

   ``e**x`` を返します。


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

   *base* を底とした *x* の対数を返します。
   *base* を省略した場合 *x* の自然対数を返します。

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


.. function:: log1p(x)

   *1+x* の自然対数(つまり底 *e* の対数)を返します。
   結果はゼロに近い *x* に対して正確になるような方法で計算されます。

   .. versionadded:: 2.6


.. function:: log10(x)

   *x* の10を底とした対数(常用対数)を返します。


.. function:: pow(x, y)

   ``x`` の ``y`` 乗を返します。例外的な場合については、
   C99 標準の付録 'F' に可能な限り従います。特に、
   ``pow(1.0, x)`` と ``pow(x, 0.0)`` は、たとえ ``x`` が零や NaN でも、
   常に ``1.0`` を返します。もし ``x`` と ``y`` の両方が有限の値で、
   ``x`` が負、 ``y`` が整数でない場合、 ``pow(x, y)`` は未定義で、
   :exc:`ValueError` を送出します。

   .. versionchanged:: 2.6
      以前は ``1**nan`` や ``nan**0`` の結果は未定義でした。


.. function:: sqrt(x)

   *x* の平方根を返します。


三角関数
--------

.. function:: acos(x)

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


.. function:: asin(x)

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


.. function:: atan(x)

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


.. function:: atan2(y, x)

   ``y / x`` の逆正接をラジアンで返します。
   戻り値は ``-pi`` から ``pi`` の間になります。この角度は、
   極座標平面において原点から ``(x, y)`` へのベクトルが X 軸の正の方向となす角です。
   :func:`atan2` のポイントは、入力 *x*,
   *y* の両方の符号が既知であるために、位相角の正しい象限を計算できることにあります。
   例えば、 ``atan(1)`` と ``atan2(1,1)``
   はいずれも ``pi/4`` ですが、 ``atan2(-1, -1)`` は ``-3*pi/4`` になります。


.. function:: cos(x)

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


.. function:: hypot(x, y)

   ユークリッド距離(``sqrt(x*x + y*y)``)を返します。


.. function:: sin(x)

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


.. function:: tan(x)

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


角度に関する関数
----------------

.. function:: degrees(x)

   角 *x* をラジアンから度に変換します。


.. function:: radians(x)

   角 *x* を度からラジアンに変換します。


双曲線関数
----------

.. function:: acosh(x)

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

   .. versionadded:: 2.6


.. function:: asinh(x)

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

   .. versionadded:: 2.6


.. function:: atanh(x)

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

   .. versionadded:: 2.6


.. function:: cosh(x)

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


.. function:: sinh(x)

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


.. function:: tanh(x)

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


定数
----

.. data:: pi

   定数 *π* (円周率)。


.. data:: e

   定数 *e* (自然対数の底)。


.. note::

   :mod:`math` モジュールは、ほとんどが実行プラットフォームにおける C
   言語の数学ライブラリ関数に対する薄いラッパでできています。例外的な場合での挙動は、
   C 言語標準ではおおさっぱにしか定義されておらず、さらに
   Python は数学関数におけるエラー報告機能の挙動をプラットフォームの
   C 実装から受け継いでいます。その結果として、エラーの際
   (およびなんらかの引数がとにかく例外的であると考えられる場合)
   に送出される特定の例外については、
   プラットフォーム間やリリースバージョン間を通じて一貫性のある定義となっていません。
   例えば、 ``math.log(0)`` が ``-Inf`` を返すか :exc:`ValueError`
   または :exc:`OverflowError` を送出するかは不定であり、
   ``math.log(0)`` が :exc:`OverflowError` を送出する場合において
   ``math.log(0L)`` が :exc:`ValueError` を送出するときもあります。

   すべての関数は引数の少なくとも一つが *NaN* であれば黙って *NaN* を返します。
   *NaN* が発生すると例外が引き起こされます。例外の型は依然としてプラットフォームとその
   libm 実装に依存しています。大抵は、 *EDOM* に対しては :exc:`ValueError` 、
   *ERANGE* に対しては :exc:`OverflowError` が対応します。

   .. versionchanged:: 2.6
      以前のバージョンの Python では入力に NaN を受け取ったときの演算結果がプラットフォームと libm 実装依存でした。

.. seealso::

   Module :mod:`cmath`
      これらの多くの関数の複素数版。

.. rubric:: Footnotes

.. [#] 訳注：例外が発生しないで、計算結果が返ってしまうと、計算結果がおかしい事から、
   原因が複素数を渡したせいである事にプログラマが気づくのが遅れる可能性があります。
