math --- 数学関数

---

このモジュールは、C 標準で定義されたものを含む、一般的な数学関数と定数を提供します。

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

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

Number-theoretic functions
comb(n, k)	n 個から k 個を、重複なく順序を付けずに選ぶ方法の数
factorial(n)	n の階乗
gcd(*integers)	整数引数の最大公約数
isqrt(n)	非負整数 n の整数平方根
lcm(*integers)	整数引数の最小公倍数
perm(n, k)	n 個から k 個を、重複なく順序を付けて選ぶ方法の数
浮動小数点演算
ceil(x)	x の天井、つまり x 以上の最小の整数
fabs(x)	x の絶対値
floor(x)	x の床、つまり x 以下の最大の整数
fma(x, y, z)	融合積和演算: (x * y) + z
fmod(x, y)	x / y の剰余
modf(x)	x の小数部と整数部
remainder(x, y)	x を y で割った剰余
trunc(x)	x の整数部
浮動小数点数の操作関数
copysign(x, y)	x の大きさ (絶対値) に y の符号を付けた値
frexp(x)	x の仮数部と指数部
isclose(a, b, rel_tol, abs_tol)	a と b が互いに近い値かを調べる
isfinite(x)	x が無限大でも NaN でもないかを調べる
isinf(x)	Check if x is a positive or negative infinity
isnan(x)	x が NaN (非数) かを調べる
ldexp(x, i)	x * (2**i)。 frexp() の逆関数
nextafter(x, y, steps)	x から y に向かって steps ステップ進んだ浮動小数点値
ulp(x)	x の最下位ビットの値
べき乗関数、指数関数、対数関数
cbrt(x)	x の立方根
exp(x)	e の x 乗
exp2(x)	2 の x 乗
expm1(x)	e の x 乗から 1 を引いた値
log(x, base)	指定した底 (デフォルトは e) に対する x の対数
log1p(x)	1+x の自然対数 (底は e)
log2(x)	2を底とする x の対数
log10(x)	10を底とする x の対数
pow(x, y)	x の y 乗
sqrt(x)	x の平方根
総和と積の関数
dist(p, q)	座標のイテラブルとして与えられる 2 点 p と q のユークリッド距離
fsum(iterable)	入力 iterable 内の値の和
hypot(*coordinates)	座標のイテラブルのユークリッドノルム
prod(iterable, start)	start を初期値とする、入力 iterable 内の要素の積
sumprod(p, q)	2 つのイテラブル p と q の値の積の総和
角度変換
degrees(x)	角度 x をラジアンから度に変換する
radians(x)	角度 x を度からラジアンに変換する
三角関数
acos(x)	x の逆余弦
asin(x)	x の逆正弦
atan(x)	x の逆正接
atan2(y, x)	atan(y / x)
cos(x)	x の余弦
sin(x)	x の正弦
tan(x)	x の正接
双曲線関数
acosh(x)	x の逆双曲線余弦
asinh(x)	x の逆双曲線正弦
atanh(x)	x の逆双曲線正接
cosh(x)	x の双曲線余弦
sinh(x)	x の双曲線正弦
tanh(x)	x の双曲線正接
特殊関数
erf(x)	x における 誤差関数 の値
erfc(x)	x における 相補誤差関数 の値
gamma(x)	x における ガンマ関数 の値
lgamma(x)	x における ガンマ関数 の絶対値の自然対数
定数
pi	π = 3.141592...
e	e = 2.718281...
tau	τ = 2π = 6.283185...
inf	正の無限大
nan	非数 "Not a number" (NaN)

数論関数

math.comb(n, k)

Return the number of ways to choose k items from n items without repetition and without order.

Evaluates to n! / (k! * (n - k)!) when k <= n and evaluates to zero when k > n.

Also called the binomial coefficient because it is equivalent to the coefficient of k-th term in polynomial expansion of (1 + x)ⁿ.

Raises TypeError if either of the arguments are not integers. Raises ValueError if either of the arguments are negative.

Added in version 3.8.

math.factorial(n)

Return factorial of the nonnegative integer n.

バージョン 3.10 で変更: Floats with integral values (like 5.0) are no longer accepted.

math.gcd(*integers)

Return the greatest common divisor of the specified integer arguments. If any of the arguments is nonzero, then the returned value is the largest positive integer that is a divisor of all arguments. If all arguments are zero, then the returned value is 0. gcd() without arguments returns 0.

Added in version 3.5.

バージョン 3.9 で変更: Added support for an arbitrary number of arguments. Formerly, only two arguments were supported.

math.isqrt(n)

Return the integer square root of the nonnegative integer n. This is the floor of the exact square root of n, or equivalently the greatest integer a such that a² ≤ n.

For some applications, it may be more convenient to have the least integer a such that n ≤ a², or in other words the ceiling of the exact square root of n. For positive n, this can be computed using a = 1 + isqrt(n - 1).

Added in version 3.8.

math.lcm(*integers)

Return the least common multiple of the specified integer arguments. If all arguments are nonzero, then the returned value is the smallest positive integer that is a multiple of all arguments. If any of the arguments is zero, then the returned value is 0. lcm() without arguments returns 1.

Added in version 3.9.

math.perm(n, k=None)

Return the number of ways to choose k items from n items without repetition and with order.

Evaluates to n! / (n - k)! when k <= n and evaluates to zero when k > n.

If k is not specified or is None, then k defaults to n and the function returns n!.

Raises TypeError if either of the arguments are not integers. Raises ValueError if either of the arguments are negative.

Added in version 3.8.

浮動小数点演算

math.ceil(x)

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

math.fabs(x)

x の絶対値を返します。

math.floor(x)

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

math.fma(x, y, z)

融合積和演算です。 (x * y) + z を、無限の精度と範囲で計算してから float 形式に 1 回だけ丸めたかのように計算して返します。 この演算は、式 (x * y) + z を直接計算するより高い精度を得られることがよくあります。

この関数は、IEEE 754 標準に記載された fusedMultiplyAdd 演算の仕様に従います。 標準では、fma(0, inf, nan) と fma(inf, 0, nan) の結果という 1 つのケースを実装依存としています。 これらの場合、math.fma は NaN を返し、例外を送出しません。

Added in version 3.13.

math.fmod(x, y)

プラットフォームの C ライブラリ関数 fmod(x, y) が定義する、x / y の浮動小数点の剰余を返します。 Python の式 x % y は同じ結果を返すとは限りません。 C 標準の意図では、fmod(x, y) は、結果が x と同じ符号で、絶対値が abs(y) より小さくなるような整数 n を使った x - n*y と、数学的に無限の精度で正確に一致します。 一方、Python の x % y は y と同じ符号の結果を返し、浮動小数点の引数では正確に計算できない場合があります。 例えば、fmod(-1e-100, 1e100) は -1e-100 ですが、Python の -1e-100 % 1e100 の結果は 1e100-1e-100 です。 これは浮動小数点数として正確に表せないため、意外にも 1e100 に丸められます。 このため、一般に浮動小数点数には fmod() を、整数には Python の x % y を使う方が適しています。

math.modf(x)

x の小数部と整数部を返します。 どちらも x と同じ符号を持つ浮動小数点数です。

modf() の呼び出し方と戻り値は C の同等の関数と異なります。 C のように 2 番目の戻り値を「出力用引数」(Python にはありません) で返すのではなく、1 つの引数を取り、2 つの値のペアを返します。

math.remainder(x, y)

IEEE 754 標準方式の x を y で割った剰余を返します。 有限な x とゼロでない有限な y では、分数 x / y の厳密な値に最も近い整数を n として、 x - n*y がこの返り値となります。 x / y が隣り合う 2 つの整数のちょうど真ん中だった場合は、最も近い 偶数 が n として使われます。 従って、剰余 r = remainder(x, y) は常に abs(r) <= 0.5 * abs(y) を満たします。

特殊な場合は IEEE 754 に従います。 特に、有限な x に対して remainder(x, math.inf) は x を返します。 一方、NaN でない x に対して remainder(x, 0) と remainder(math.inf, x) は ValueError を送出します。 剰余演算の結果がゼロなら、そのゼロの符号は x と同じになります。

IEEE 754 の二進浮動小数点を使うプラットフォームでは、この演算の結果は常に正確に表現でき、丸め誤差は生じません。

Added in version 3.7.

math.trunc(x)

x の小数部を取り除き、残った整数部を返します。これは 0 に向かって丸められます: trunc() は正の x に対しては floor() に等しく、負の x に対しては ceil() に等しいです。x が浮動小数点数でなければ、内部的に x.__trunc__ が実行され、 Integral 値が返されます。

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

浮動小数点数の操作関数

math.copysign(x, y)

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

math.frexp(x)

x の仮数部と指数部をペア (m, e) として返します。 x が有限でゼロでない数の場合、m は 0.5 <= abs(m) < 1.0 を満たす浮動小数点数で、e は x == m * 2**e が正確に成り立つ整数です。 それ以外の場合は (x, 0) を返します。 浮動小数点数の内部表現を、移植性のある方法で「分解する」ために使います。

frexp() の呼び出し方と戻り値は C の同等の関数と異なります。 C のように 2 番目の戻り値を「出力用引数」(Python にはありません) で返すのではなく、1 つの引数を取り、2 つの値のペアを返します。

math.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)

値 a と b が互いに近い場合 True を、そうでない場合は False を返します。

2 つの値が近いとみなされるかは、指定された絶対許容誤差と相対許容誤差で決まります。 エラーが起きなければ、結果は abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol) です。

rel_tol は相対許容誤差です。 a と b の絶対値の大きい方に対する、両者の差の許容最大比率を表します。 例えば、5% の誤差を許容するには rel_tol=0.05 を渡します。 デフォルトの許容誤差は 1e-09 で、2 つの値がおよそ 10 進 9 桁の精度で等しいことを保証します。 rel_tol は非負で 1.0 未満でなければなりません。

abs_tol は絶対許容誤差で、デフォルトは 0.0 です。 非負でなければなりません。 x と 0.0 を比較するとき、isclose(x, 0) は abs(x) <= rel_tol  * abs(x) として計算されます。 x がゼロでなく rel_tol が 1.0 未満なら、これは False です。 そのため、適切な正の abs_tol 引数を指定してください。

IEEE 754 特殊値 NaN、inf、-inf は IEEE の規則に従って処理されます。 具体的には、NaN は自身を含めたあらゆる値に近いとは見なされません。 inf と -inf は自身とのみ近いと見なされます。

Added in version 3.5.

参考

PEP 485 -- A function for testing approximate equality

math.isfinite(x)

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

Added in version 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.nextafter(x, y, steps=1)

x から y に向かって steps ステップ進んだ浮動小数点値を返します。

x と y が等しい場合、steps がゼロでなければ y を返します。

例:

• math.nextafter(x, math.inf) は増加する方向、つまり正の無限大に向かって進みます。

• math.nextafter(x, -math.inf) は減少する方向、つまり負の無限大に向かって進みます。

• math.nextafter(x, 0.0) は 0 に近づきます。

• math.nextafter(x, math.copysign(math.inf, x)) は 0 から遠ざかります。

math.ulp() を参照してください。

Added in version 3.9.

バージョン 3.12 で変更: steps 引数を追加しました。

math.ulp(x)

浮動小数点数 x の最下位ビットの値を返します:

• x が NaN (非数) なら、x を返します。

• x が負なら、ulp(-x) を返します。

• x が正の無限大なら、x を返します。

• x が 0 に等しければ、(最小の正の 正規化 浮動小数点数 sys.float_info.min よりも小さい) 最小の正の表現可能な 非正規化 浮動小数点数を返します。

• x が表現可能な最大の正の浮動小数点数に等しいなら、x より小さい最初の浮動小数点数が x - ulp(x) であるような、x の最下位ビットの値を返します。

• それ以外 (x が正の有限な数) なら、x より大きい最初の浮動小数点数が x + ulp(x) であるような、x の最下位ビットの値を返します。

ULP は "Unit in the Last Place" の略です。

math.nextafter() および sys.float_info.epsilon も参照してください。

Added in version 3.9.

べき乗関数、指数関数、対数関数

math.cbrt(x)

x の立方根を返します。

Added in version 3.11.

math.exp(x)

e = 2.718281... を自然対数の底として、 e の x 乗を返します。 この値は、通常は math.e ** x や pow(math.e, x) よりも精度が高いです。

math.exp2(x)

2 の x 乗を返します。

Added in version 3.11.

math.expm1(x)

e の x 乗から 1 を引いた値を返します。 ここで e は自然対数の底です。 浮動小数点数 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

Added in version 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) よりも正確な値を返します。

Added in version 3.3.

参考

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

math.log10(x)

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

math.pow(x, y)

x の y 乗を返します。 特殊なケースでは、可能な限り IEEE 754 標準に従います。 特に pow(1.0, x) と pow(x, 0.0) は、x がゼロや NaN でも常に 1.0 を返します。 x と y がともに有限で、x が負、y が整数でない場合、pow(x, y) は未定義であり ValueError を送出します。

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

バージョン 3.11 で変更: IEEE 754 との一貫性のため、特殊な例である pow(0.0, -inf) および pow(-0.0, -inf) は ValueError を送出する代わりに inf を返すように変更されました。

math.sqrt(x)

x の平方根を返します。

総和と積の関数

math.dist(p, q)

それぞれ座標のシーケンス (またはイテラブル) として与えられる点 p と q の間のユークリッド距離を返します。二点の次元は同じでなければなりません。

およそ次と等価です:

sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))

Added in version 3.8.

math.fsum(iterable)

iterable 内の値の正確な浮動小数点の総和を返します。 複数の中間部分和を保持することで精度の低下を防ぎます。

このアルゴリズムの精度は、IEEE-754 演算の保証と、丸めモードが通常は偶数丸め (half-even) であることに依存します。 Windows 以外の一部のビルドでは、下層の C ライブラリが拡張精度で加算するため、中間の和に二重丸めが起き、最下位ビットに誤差が生じることがあります。

詳しい議論と 2 つの代替方法については、正確な浮動小数点の総和を求める ASPN クックブックのレシピ を参照してください。

math.hypot(*coordinates)

ユークリッドノルム sqrt(sum(x**2 for x in coordinates)) を返します。これは原点から座標で与えられる点までのベクトルの長さです。

二次元の点 (x, y) では、これは直角三角形の斜辺をピタゴラスの定理 sqrt(x*x + y*y) を用いて計算することと等価です。

バージョン 3.8 で変更: n 次元の点のサポートが追加されました。以前は、二次元の場合しかサポートされていませんでした。

バージョン 3.10 で変更: アルゴリズムの精度を改良し、最大の誤差が 1 ulp (最終桁単位) 未満になりました。より一般的には、結果はほとんどの場合に 1/2 ulp 以内に正しく丸められます。

math.prod(iterable, *, start=1)

入力 iterable の全ての要素の積を計算します。積のデフォルト start 値は 1 です。

イテラブルが空のとき、初期値を返します。この関数は特に数値に使うことを意図されており、非数値を受け付けないことがあります。

Added in version 3.8.

math.sumprod(p, q)

2 つのイテラブル p と q の値の積の総和を返します。

入力の長さが同じでない場合、ValueError を送出します。

およそ次と等価です:

sum(map(operator.mul, p, q, strict=True))

float の入力、または int と float が混在する入力では、中間の積と和を拡張精度で計算します。

Added in version 3.12.

角度変換

math.degrees(x)

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

math.radians(x)

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

三角関数

math.acos(x)

x の逆余弦を、ラジアンで返します。結果は 0 と pi の間です。

math.asin(x)

x の逆正弦を、ラジアンで返します。結果は -pi/2 と pi/2 の間です。

math.atan(x)

x の逆正接を、ラジアンで返します。結果は -pi/2 と pi/2 の間です。

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.sin(x)

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

math.tan(x)

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

双曲線関数

双曲線関数 は、円の代わりに双曲線に基づく、三角関数に対応する関数です。

math.acosh(x)

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

math.asinh(x)

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

math.atanh(x)

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

math.cosh(x)

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

math.sinh(x)

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

math.tanh(x)

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

特殊関数

math.erf(x)

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

erf() 関数を使うと、標準正規分布の累積分布関数 など、一般的な統計関数を計算できます。

def phi(x):
    '標準正規分布の累積分布関数'
    return (1.0 + erf(x / sqrt(2.0))) / 2.0

Added in version 3.2.

math.erfc(x)

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

Added in version 3.2.

math.gamma(x)

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

Added in version 3.2.

math.lgamma(x)

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

Added in version 3.2.

定数

math.pi

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

math.e

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

math.tau

数学定数 τ = 6.283185... を、利用可能な精度で表した値です。 タウは 2π に等しい円の定数で、円周と半径の比を表します。 詳しくは Vi Hart の動画 Pi is (still) Wrong を見て、パイを 2 倍食べて タウの日 を祝いましょう！

Added in version 3.6.

math.inf

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

Added in version 3.5.

math.nan

浮動小数点の非数 (NaN) です。 float('nan') の出力と等価です。 IEEE-754 標準 の要件により、math.nan と float('nan') は、自分自身を含むどの数値とも等しいとはみなされません。 数値が NaN かを調べるには、is や == の代わりに isnan() を使ってください。 使用例:

>>> import math
>>> math.nan == math.nan
False
>>> float('nan') == float('nan')
False
>>> math.isnan(math.nan)
True
>>> math.isnan(float('nan'))
True

Added in version 3.5.

バージョン 3.11 で変更: 常に利用出来るようになりました。

math モジュールの大部分は、プラットフォームの C 数学ライブラリ関数への薄いラッパーです。 特殊なケースの動作は、適切な場合には C99 標準の附属書 F に従います。 現在の実装は、sqrt(-1.0) や log(0.0) のような無効な演算 (C99 附属書 F が無効な演算やゼロ除算の通知を推奨する場合) には ValueError を送出します。 結果がオーバーフローする場合 (exp(1000.0) など) は OverflowError を送出します。 上記の関数は、入力引数の少なくとも 1 つが NaN でない限り NaN を返しません。 入力に NaN があれば、ほとんどの関数は NaN を返しますが、これにも C99 附属書 F に従う例外があります。 例えば pow(float('nan'), 0.0) や hypot(float('nan'), float('inf')) です。

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

参考

cmath モジュール

これらの多くの関数の複素数版。