math --- 数学関数

---

This module provides access to common mathematical functions and constants, including those defined by the C standard.

これらの関数で複素数を使うことはできません。複素数に対応する必要があるならば、 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)

n 個の中から k 個を重複無く順序をつけずに選ぶ方法の数を返します。

k <= n のとき n! / (k! * (n - k)!) と評価し、k > n のとき 0 と評価します。

これは (1 + x)ⁿ の多項式展開における第 k 項の係数と等しいので、二項係数とも呼ばれます。

いずれかの引数が整数でないなら TypeError を送出します。いずれかの引数が負であれば ValueError を送出します。

Added in version 3.8.

math.factorial(n)

非負整数 n の階乗を返します。

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

math.gcd(*integers)

指定された整数引数の最大公約数を返します。0 でない引数があれば、返される値は全ての引数の約数である最大の正の整数です。全ての引数が 0 なら、返される値は 0 です。引数の無い gcd() は 0 を返します。

Added in version 3.5.

バージョン 3.9 で変更: 任意の数の引数のサポートが追加されました。以前は、二つの引数のみがサポートされていました。

math.isqrt(n)

非負整数 n の整数平方根を返します。これは n の正確な平方根の床であり、 a² ≤ n を満たす最大の整数 a と等価です。

用途によっては、n ≤ a² を満たす最小の整数 a、つまり n の正確な平方根の天井を求める方が便利な場合があります。 正の n に対しては、a = 1 + isqrt(n - 1) で計算できます。

Added in version 3.8.

math.lcm(*integers)

指定された整数引数の最小公倍数を返します。全ての引数が 0 でなければ、返される値は全ての引数の倍数である最小の正の整数です。引数に 0 があれば、返される値は 0 です。引数の無い lcm() は 1 を返します。

Added in version 3.9.

math.perm(n, k=None)

n 個の中から k 個を重複無く順序をつけて選ぶ方法の数を返します。

k <= n のとき n! / (n - k)! と評価し、k > n のとき 0 と評価します。

k を指定しない場合や None の場合、k のデフォルト値は n となり、関数は n! を返します。

いずれかの引数が整数でないなら TypeError を送出します。いずれかの引数が負であれば ValueError を送出します。

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)

Return the mantissa and exponent of x as the pair (m, e). If x is a finite nonzero number, then m is a float with 0.5 <= abs(m) < 1.0 and an integer e is such that x == m * 2**e exactly. Else, return (x, 0). This is used to "pick apart" the internal representation of a float in a portable way.

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(itertools.starmap(operator.mul, zip(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

The mathematical constant τ = 6.283185..., to available precision. Tau is a circle constant equal to 2π, the ratio of a circle's circumference to its radius. To learn more about Tau, check out Vi Hart's video Pi is (still) Wrong, and start celebrating Tau day by eating twice as much pie!

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 標準の 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 モジュール

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