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)

Return the Real value x truncated to an Integral (usually an integer). Delegates to 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.inf

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

バージョン 3.5 で追加.

math.nan

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

バージョン 3.5 で追加.

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 モジュール
これらの多くの関数の複素数版。