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

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


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

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

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

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

.. function:: ceil(x)

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


.. function:: copysign(x, y)

   *x* に *y* の符号を付けて返します。符号付きのゼロをサポートしている
   プラットフォームでは、 ``copysign(1.0, -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型で返します。


.. function:: fmod(x, y)

   プラットフォームの C ライブラリで定義されている ``fmod(x, y)`` を返します。 Python の ``x % y``
   という式は必ずしも同じ結果を返さないということに注意してください。 C 標準の要求では、 :c:func:`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.9999999999999999
        >>> 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 標準を参照してください。

   .. versionadded:: 2.6


.. function:: ldexp(x, i)

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


.. function:: modf(x)

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


.. function:: trunc(x)

   *x* の :class:`Integral` (たいてい長整数)へ切り捨てられた :class:`Real`
   値を返します。 ``__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:: expm1(x)

   ``e**x - 1`` を返します。 *x* が小さい float の場合は、 ``exp(x) - 1``
   の減算は桁落ちを発生させるかもしれません。
   :func:`expm1` 関数はこの計算を完全な精度で実行します。 ::

      >>> from math import exp, expm1
      >>> exp(1e-5) - 1  # gives result accurate to 11 places
      1.0000050000069649e-05
      >>> expm1(1e-5)    # result accurate to full precision
      1.0000050000166668e-05

   .. versionadded:: 2.7


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

   引数が1つの場合、 *x* の (*e* を底とする)自然対数を返します。

   引数が2つの場合、 ``log(x)/log(base)`` として求められる *base* を底とした *x*
   の対数を返します。

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


.. function:: log1p(x)

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

   .. versionadded:: 2.6


.. function:: log10(x)

   *x* の10を底とした対数(常用対数)を返します。
   この関数は通常、 ``log(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* の双曲線正接を返します。


.. Special functions

特殊な関数
-----------------

.. function:: erf(x)

   *x* の誤差関数を返します。

   .. versionadded:: 2.7


.. function:: erfc(x)

   *x* の相補誤差関数を返します。

   .. versionadded:: 2.7


.. function:: gamma(x)

   *x* のガンマ関数を返します。

   .. versionadded:: 2.7


.. function:: lgamma(x)

   *x* のガンマ関数の絶対値の自然対数を返します。

   .. versionadded:: 2.7


定数
----

.. data:: pi

   利用可能な精度の、数学定数 π = 3.141592... (円周率)


.. data:: e

   利用可能な精度の、数学定数 *e* = 2.718281... (自然対数の底)


.. impl-detail::

   :mod:`math` モジュールは、ほとんどが実行プラットフォームにおける C
   言語の数学ライブラリ関数に対する薄いラッパでできています。
   例外的な場合での挙動は、適切である限り C99 標準の Annex F に従います。
   現在の実装では、(C99 Annex F でゼロ除算か不正な演算やゼロ除算を通知する
   ことが推奨されている) ``sqrt(-1.0)`` や ``log(0.0)`` といった不正な操作
   に対して :exc:`ValueError` を発生させ、(例えば ``exp(1000.0)`` のような)
   演算結果がオーバーフローする場合には :exc:`OverflowError` を発生させます。
   上記の関数群は、1つ以上の引数が NaN であった場合を除いて、 NaN を返しません。
   引数に NaN が与えられた場合は、殆どの関数は NaN を返しますが、 (C99 Annex
   F に従って) 別の動作をする場合があります。例えば、 ``pow(float('nan'), 0.0)``
   や ``hypot(float('nan'), float('inf'))`` といった場合です。

   Python は signaling NaN と quiet NaN を区別せず、 signaling NaN に対する
   挙動は未定義とされていることに注意してください。典型的な挙動は、全ての NaN
   を quiet NaN として扱うことです。

   .. versionchanged:: 2.6

      特別なケースにおける挙動は、 C99 Annex F に従うことを意図するようになりました。
      以前のバージョンの Python では、特別なケースでの挙動は曖昧にしか定義されていませんでした。

.. seealso::

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

.. rubric:: 注記

.. [#] 訳注：例外が発生せずに結果が返ると、計算結果がおかしくなった原因が
       複素数を渡したためだということに気づくのが遅れる可能性があります。
