9.2. "math" --- 数学関数
************************

======================================================================

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

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

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


9.2.1. 数論および数表現の関数
=============================

math.ceil(x)

   *x* の「天井」 (*x* 以上の最小の整数) を返します。 *x* が浮動小数点
   数でなければ、内部的に "x.__ceil__()" が実行され、 "Integral" 値が
   返されます。

math.copysign(x, y)

   *x* の大きさ (絶対値) で *y* と同じ符号の浮動小数点数を返します。符
   号付きのゼロをサポートしているプラットフォームでは、"copysign(1.0,
   -0.0)" は *-1.0* を返します。

math.fabs(x)

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

math.factorial(x)

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

math.floor(x)

   *x* の「床」 (*x* 以下の最大の整数) を返します。 *x* が浮動小数点数
   でなければ、内部的に "x.__floor__()" が実行され、 "Integral" 値が返
   されます。

math.fmod(x, y)

   プラットフォームの C ライブラリで定義されている "fmod(x, y)" を返し
   ます。 Python の "x % y" という式は必ずしも同じ結果を返さないという
   ことに注意してください。 C 標準の要求では、 "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" に丸められます。
   このため、一般には浮動小数点の場合には関数 "fmod()" 、整数の場合に
   は "x % y" を使う方がよいでしょう。

math.frexp(x)

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

math.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 をご覧下さい。

math.gcd(a, b)

   整数 *a* と *b* の最大公約数を返します。*a* と *b* のいずれかがゼロ
   でない場合、"gcd(a, b)" の値は *a* と *b* の両方を割り切ることので
   きる、最も大きな正の整数です。"gcd(0, 0)" は "0" を返します。

   バージョン 3.5 で追加.

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

math.isfinite(x)

   *x* が無限でも NaN でもない場合に "True" を返します。それ以外の時に
   は "False" を返します。 (注意: "0.0" は有限数と扱われます。)

   バージョン 3.2 で追加.

math.isinf(x)

   *x* が正ないし負の無限数ならば "True" を返します。それ以外の時には
   "False" を返します。

math.isnan(x)

   *x* がNaN (not a number、非数) の時に "True" を返します。それ以外の
   場合には "False" を返します。

math.ldexp(x, i)

   "x * (2**i)" を返します。これは本質的に "frexp()" の逆関数です。

math.modf(x)

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

math.trunc(x)

   *x* の "Integral" 値 (たいていは整数) へ切り捨てられた "Real" 値を
   返します。 "x.__trunc__()" に処理を委譲します。

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

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


9.2.2. 指数関数と対数関数
=========================

math.exp(x)

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

math.expm1(x)

   "e**x - 1" を返します。小さな浮動小数点数 *x* について "exp(x) - 1"
   を計算すると、引き算により 桁落ち する可能性がありますが、この
   "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

   バージョン 3.2 で追加.

math.log(x[, base])

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

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

math.log1p(x)

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

math.log2(x)

   2を底とする *x* の対数を返します。この関数は、一般に "log(x, 2)" よ
   りも正確な値を返します。

   バージョン 3.3 で追加.

   参考:

     "int.bit_length()" は、その整数を二進法で表すのに何ビット必要かを
     返す関数です。符号と先頭のゼロは無視されます。

math.log10(x)

   *x* の10を底とした対数(常用対数)を返します。この関数は通常、"log(x,
   10)" よりも高精度です。

math.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)" は未定義で、 "ValueError" を送出します。

   組み込みの "**" 演算子と違って、 "math.pow()" は両方の引数を
   "float" 型に変換します。正確な整数の冪乗を計算するには "**" もしく
   は組み込みの "pow()" 関数を使ってください。

math.sqrt(x)

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


9.2.3. 三角関数
===============

math.acos(x)

   *x* の逆余弦を、ラジアンで返します。

math.asin(x)

   *x* の逆正弦を、ラジアンで返します。

math.atan(x)

   *x* の逆正接を、ラジアンで返します。

math.atan2(y, x)

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

math.cos(x)

   *x* ラジアンの余弦を返します。

math.hypot(x, y)

   ユークリッドノルム("sqrt(x*x + y*y)")を返します。これは原点から点
   "(x, y)" のベクトルの長さです。

math.sin(x)

   *x* ラジアンの正弦を返します。

math.tan(x)

   *x* ラジアンの正接を返します。


9.2.4. 角度変換
===============

math.degrees(x)

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

math.radians(x)

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


9.2.5. 双曲線関数
=================

双曲線関数 は円ではなく双曲線を元にした三角関数のようなものです。

math.acosh(x)

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

math.asinh(x)

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

math.atanh(x)

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

math.cosh(x)

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

math.sinh(x)

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

math.tanh(x)

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


9.2.6. 特殊関数
===============

math.erf(x)

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

   "erf()" 関数は、伝統的な統計関数を計算するのに使うことができます。
   例えば、 累積標準正規分布 を計算する関数は次のように定義できます:

      def phi(x):
          'Cumulative distribution function for the standard normal distribution'
          return (1.0 + erf(x / sqrt(2.0))) / 2.0

   バージョン 3.2 で追加.

math.erfc(x)

   *x* の相補誤差関数を返します。相補誤差関数 は "1.0 - erf(x)" と定義
   されます。この関数は、1との引き算では 桁落ち をするような大きな *x*
   に対し使われます。

   バージョン 3.2 で追加.

math.gamma(x)

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

   バージョン 3.2 で追加.

math.lgamma(x)

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

   バージョン 3.2 で追加.


9.2.7. 定数
===========

math.pi

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

math.e

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

math.tau

   数学定数 τ = 6.283185... (利用可能な精度まで) です。タウは2πに等し
   い円定数で、円周と半径の比です。タウについて学ぶには Vi Hart のビデ
   オ Pi is (still) Wrong をチェックして、パイを二倍食べて Tau day を
   祝い始めましょう！

   バージョン 3.6 で追加.

math.inf

   浮動小数の正の無限大です。(負の無限大には "-math.inf" を使います。)
   "float('inf')" の出力と等価です。

   バージョン 3.5 で追加.

math.nan

   浮動小数の非数 "not a number" (NaN) です。"float('nan')" の出力と等
   価です。

   バージョン 3.5 で追加.

**CPython implementation detail:** "math" モジュールは、ほとんどが実行
プラットフォームにおける C 言語の数学ライブラリ関数に対する薄いラッパ
でできています。 例外時の挙動は、適切である限り C99 標準の Annex F に
従います。 現在の実装では、"sqrt(-1.0)" や "log(0.0)" といった (C99
Annex F で不正な演算やゼロ除算を通知することが推奨されている) 不正な操
作に対して "ValueError" を送出し、(例えば "exp(1000.0)" のような) 演算
結果がオーバーフローする場合には "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 として扱うことです。

参考:

  "cmath" モジュール
     これらの多くの関数の複素数版。
