math --- 数学関数¶
このモジュールは、 C 標準で定義された数学関数へのアクセスを提供します。
これらの関数で複素数を使うことはできません。複素数に対応する必要があるならば、 cmath モジュールにある同じ名前の関数を使ってください。ほとんどのユーザーは複素数を理解するのに必要なだけの数学を勉強したくないので、複素数に対応した関数と対応していない関数の区別がされています。これらの関数では複素数が利用できないため、引数に複素数を渡されると、複素数の結果が返るのではなく例外が発生します。その結果、どういった理由で例外が送出されたかに早い段階で気づく事ができます。
このモジュールでは次の関数を提供しています。明示的な注記のない限り、戻り値は全て浮動小数点数になります。
数論および数表現の関数¶
-
math.ceil(x)¶ x の「天井」 (x 以上の最小の整数) を返します。 x が浮動小数点数でなければ、内部的に
x.__ceil__が実行され、Integral値が返されます。
-
math.comb(n, k)¶ n 個の中から k 個を重複無く順序をつけずに選ぶ方法の数を返します。
k <= nのときn! / (k! * (n - k)!)と評価し、k > nのとき 0 と評価します。Also called the binomial coefficient because it is equivalent to the coefficient of k-th term in polynomial expansion of the expression
(1 + x) ** n.いずれかの引数が整数でないなら
TypeErrorを送出します。いずれかの引数が負であればValueErrorを送出します。バージョン 3.8 で追加.
-
math.copysign(x, y)¶ x の大きさ (絶対値) で y と同じ符号の浮動小数点数を返します。符号付きのゼロをサポートしているプラットフォームでは、
copysign(1.0, -0.0)は -1.0 を返します。
-
math.fabs(x)¶ x の絶対値を返します。
-
math.factorial(x)¶ x の階乗を整数で返します。 x が整数でないか、負の数の場合は、
ValueErrorを送出します。バージョン 3.9 で非推奨: (
5.0のような) 整数値を持つ浮動小数点数を受け取るのは非推奨です。
-
math.floor(x)¶ x の「床」 (x 以下の最大の整数) を返します。 x が浮動小数点数でなければ、内部的に
x.__floor__が実行され、Integral値が返されます。
-
math.fmod(x, y)¶ プラットフォームの C ライブラリで定義されている
fmod(x, y)を返します。 Python のx % yという式は必ずしも同じ結果を返さないということに注意してください。 C 標準の要求では、fmod(x, y)は厳密に (数学的に、つまり無限の精度で)x - n*yと等価であるよう求めています。n は結果が x と同じ符号とabs(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(*integers)¶ 指定された整数引数の最大公約数を返します。0 でない引数があれば、返される値は全ての引数の約数である最大の正の整数です。全ての引数が 0 なら、返される値は
0です。引数の無いgcd()は0を返します。バージョン 3.5 で追加.
バージョン 3.9 で変更: 任意の数の引数のサポートが追加されました。以前は、二つの引数のみがサポートされていました。
-
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.isqrt(n)¶ 非負整数 n の整数平方根を返します。これは n の正確な平方根の床であり、 a² ≤ n を満たす最大の整数 a と等価です。
少し応用すれば、n ≤ a² を満たす最小の整数 a 、言い換えれば n の正確な平方根の天井を効率的に得られます。正の n に対して、これは
a = 1 + isqrt(n - 1)を使って計算できます。バージョン 3.8 で追加.
-
math.lcm(*integers)¶ 指定された整数引数の最小公倍数を返します。全ての引数が 0 でなければ、返される値は全ての引数の倍数である最小の正の整数です。引数に 0 があれば、返される値は
0です。引数の無いlcm()は1を返します。バージョン 3.9 で追加.
-
math.modf(x)¶ x の小数部分と整数部分を返します。両方の結果は x の符号を受け継ぎます。整数部はfloat型で返されます。
-
math.nextafter(x, y)¶ Return the next floating-point value after x towards y.
x が y に等しければ、y を返します。
例:
math.nextafter(x, math.inf)goes up: towards positive infinity.math.nextafter(x, -math.inf)goes down: towards minus infinity.math.nextafter(x, 0.0)は 0 に近づきます。math.nextafter(x, math.copysign(math.inf, x))は 0 から遠ざかります。
math.ulp()を参照してください。バージョン 3.9 で追加.
-
math.perm(n, k=None)¶ n 個の中から k 個を重複無く順序をつけて選ぶ方法の数を返します。
k <= nのときn! / (n - k)!と評価し、k > nのとき 0 と評価します。k が指定されていないか None であれば、k はデフォルトで n となりこの関数は
n!を返します。いずれかの引数が整数でないなら
TypeErrorを送出します。いずれかの引数が負であればValueErrorを送出します。バージョン 3.8 で追加.
-
math.prod(iterable, *, start=1)¶ 入力 iterable の全ての要素の積を計算します。積のデフォルト start 値は
1です。イテラブルが空のとき、初期値を返します。この関数は特に数値に使うことを意図されており、非数値を受け付けないことがあります。
バージョン 3.8 で追加.
-
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)、および任意の非 NaN の x に対するremainder(x, 0)とremainder(math.inf, x)はValueErrorを送出します。 剰余演算の結果がゼロの場合、そのゼロは x と同じ符号を持ちます。IEEE 754 の二進浮動小数点数を使用しているプラットフォームでは、この演算の結果は常に厳密に表現可能です。丸め誤差は発生しません。
バージョン 3.7 で追加.
-
math.trunc(x)¶ x の小数部を取り除き、残った整数部を返します。これは 0 に向かって丸められます:
trunc()は正の x に対してはfloor()に等しく、負の x に対してはceil()に等しいです。x が浮動小数点数でなければ、内部的にx.__trunc__が実行され、Integral値が返されます。
-
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も参照してください。バージョン 3.9 で追加.
frexp() と modf() は C のものとは異なった呼び出し/返しパターンを持っていることに注意してください。引数を1つだけ受け取り、1組のペアになった値を返すので、2つ目の戻り値を '出力用の引数' 経由で返したりはしません (Python には出力用の引数はありません)。
ceil() 、 floor() 、および modf() 関数については、非常に大きな浮動小数点数が 全て 整数そのものになるということに注意してください。通常、Python の浮動小数点型は 53 ビット以上の精度をもたない (プラットフォームにおける C double 型と同じ) ので、結果的に abs(x) >= 2**52 であるような浮動小数点型 x は小数部分を持たなくなるのです。
指数関数と対数関数¶
-
math.exp(x)¶ e = 2.718281... を自然対数の底として、 e の x 乗を返します。 この値は、通常は
math.e ** xやpow(math.e, x)よりも精度が高いです。
-
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
バージョン 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 の平方根を返します。
三角関数¶
-
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.dist(p, q)¶ それぞれ座標のシーケンス (またはイテラブル) として与えられる点 p と q の間のユークリッド距離を返します。二点の次元は同じでなければなりません。
およそ次と等価です:
sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))
バージョン 3.8 で追加.
-
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.sin(x)¶ x ラジアンの正弦を返します。
-
math.tan(x)¶ x ラジアンの正接を返します。
角度変換¶
-
math.degrees(x)¶ 角 x をラジアンから度に変換します。
-
math.radians(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): '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.lgamma(x)¶ x のガンマ関数の絶対値の自然対数を返します。
バージョン 3.2 で追加.
定数¶
-
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')の出力と等価です。IEEE-754 standard の要求により、math.nanおよびfloat('nan')はそれ自身も含めた他のいかなる数値とも等しいとはみなされません。数が NaN であるかを確認するには、isや==ではなく、NaN を判定するisnan()関数を使ってください。例:>>> import math >>> math.nan == math.nan False >>> float('nan') == float('nan') False >>> math.isnan(math.nan) True >>> math.isnan(float('nan')) True
バージョン 3.5 で追加.
CPython 実装の詳細: 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モジュールこれらの多くの関数の複素数版。