Number-theoretic functions¶

math.comb(n,k)¶

Return the number of ways to choosek items fromn items without repetitionand without order.

Evaluates ton!/(k!*(n-k)!) whenk<=n and evaluatesto zero whenk>n.

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

RaisesTypeError if either of the arguments are not integers.RaisesValueError if either of the arguments are negative.

Added in version 3.8.

math.factorial(n)¶

Returnn factorial as an integer. RaisesValueError ifn is not integral oris negative.

Changed in version 3.10:Floats with integral values (like5.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 largestpositive integer that is a divisor of all arguments. If all argumentsare zero, then the returned value is0.gcd() without argumentsreturns0.

Added in version 3.5.

Changed in version 3.9:Added support for an arbitrary number of arguments. Formerly, only twoarguments were supported.

math.isqrt(n)¶

Return the integer square root of the nonnegative integern. This is thefloor of the exact square root ofn, or equivalently the greatest integera such thata² ≤ n.

For some applications, it may be more convenient to have the least integera such thatn ≤ a², or in other words the ceiling ofthe exact square root ofn. For positiven, this can be computed usinga=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 smallestpositive integer that is a multiple of all arguments. If any of the argumentsis zero, then the returned value is0.lcm() without argumentsreturns1.

Added in version 3.9.

math.perm(n,k=None)¶

Return the number of ways to choosek items fromn itemswithout repetition and with order.

Evaluates ton!/(n-k)! whenk<=n and evaluatesto zero whenk>n.

Ifk is not specified or isNone, thenk defaults tonand the function returnsn!.

RaisesTypeError if either of the arguments are not integers.RaisesValueError if either of the arguments are negative.

Added in version 3.8.

Floating point arithmetic¶

math.ceil(x)¶

Return the ceiling ofx, the smallest integer greater than or equal tox.Ifx is not a float, delegates tox.__ceil__,which should return anIntegral value.

math.fabs(x)¶

Return the absolute value ofx.

math.floor(x)¶

Return the floor ofx, the largest integer less than or equal tox. Ifx is not a float, delegates tox.__floor__, whichshould return anIntegral value.

math.fma(x,y,z)¶

Fused multiply-add operation. Return(x*y)+z, computed as though withinfinite precision and range followed by a single round to thefloatformat. This operation often provides better accuracy than the directexpression(x*y)+z.

This function follows the specification of the fusedMultiplyAdd operationdescribed in the IEEE 754 standard. The standard leaves one caseimplementation-defined, namely the result offma(0,inf,nan)andfma(inf,0,nan). In these cases,math.fma returns a NaN,and does not raise any exception.

Added in version 3.13.

math.fmod(x,y)¶

Return the floating-point remainder ofx/y,as defined by the platform C library functionfmod(x,y). Note that thePython expressionx%y may not return the same result. The intent of the Cstandard is thatfmod(x,y) be exactly (mathematically; to infiniteprecision) equal tox-n*y for some integern such that the result hasthe same sign asx and magnitude less thanabs(y). Python’sx%yreturns a result with the sign ofy instead, and may not be exactly computablefor float arguments. For example,fmod(-1e-100,1e100) is-1e-100, butthe result of Python’s-1e-100%1e100 is1e100-1e-100, which cannot berepresented exactly as a float, and rounds to the surprising1e100. Forthis reason, functionfmod() is generally preferred when working withfloats, while Python’sx%y is preferred when working with integers.

math.modf(x)¶

Return the fractional and integer parts ofx. Both results carry the signofx and are floats.

Note thatmodf() has a different call/return patternthan its C equivalents: it takes a single argument and return a pair ofvalues, rather than returning its second return value through an ‘outputparameter’ (there is no such thing in Python).

math.remainder(x,y)¶

Return the IEEE 754-style remainder ofx with respect toy. Forfinitex and finite nonzeroy, this is the differencex-n*y,wheren is the closest integer to the exact value of the quotientx/y. Ifx/y is exactly halfway between two consecutive integers, thenearesteven integer is used forn. The remainderr=remainder(x,y) thus always satisfiesabs(r)<=0.5*abs(y).

Special cases follow IEEE 754: in particular,remainder(x,math.inf) isx for any finitex, andremainder(x,0) andremainder(math.inf,x) raiseValueError for any non-NaNx.If the result of the remainder operation is zero, that zero will havethe same sign asx.

On platforms using IEEE 754 binary floating point, the result of thisoperation is always exactly representable: no rounding error is introduced.

Added in version 3.7.

math.trunc(x)¶

Returnx with the fractional partremoved, leaving the integer part. This rounds toward 0:trunc() isequivalent tofloor() for positivex, and equivalent toceil()for negativex. Ifx is not a float, delegates tox.__trunc__, which should return anIntegral value.

For theceil(),floor(), andmodf() functions, note thatallfloating-point numbers of sufficiently large magnitude are exact integers.Python floats typically carry no more than 53 bits of precision (the same as theplatform C double type), in which case any floatx withabs(x)>=2**52necessarily has no fractional bits.

Floating point manipulation functions¶

math.copysign(x,y)¶

Return a float with the magnitude (absolute value) ofx but the sign ofy. On platforms that support signed zeros,copysign(1.0,-0.0)returns-1.0.

math.frexp(x)¶

Return the mantissa and exponent ofx as the pair(m,e).m is a floatande is an integer such thatx==m*2**e exactly. Ifx is zero,returns(0.0,0), otherwise0.5<=abs(m)<1. This is used to “pickapart” the internal representation of a float in a portable way.

Note thatfrexp() has a different call/return patternthan its C equivalents: it takes a single argument and return a pair ofvalues, rather than returning its second return value through an ‘outputparameter’ (there is no such thing in Python).

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

ReturnTrue if the valuesa andb are close to each other andFalse otherwise.

Whether or not two values are considered close is determined according togiven absolute and relative tolerances. If no errors occur, the result willbe:abs(a-b)<=max(rel_tol*max(abs(a),abs(b)),abs_tol).

rel_tol is the relative tolerance – it is the maximum allowed differencebetweena andb, relative to the larger absolute value ofa orb.For example, to set a tolerance of 5%, passrel_tol=0.05. The defaulttolerance is1e-09, which assures that the two values are the samewithin about 9 decimal digits.rel_tol must be nonnegative and lessthan1.0.

abs_tol is the absolute tolerance; it defaults to0.0 and it must benonnegative. When comparingx to0.0,isclose(x,0) is computedasabs(x)<=rel_tol *abs(x), which isFalse for any nonzerox andrel_tol less than1.0. So add an appropriate positiveabs_tol argumentto the call.

The IEEE 754 special values ofNaN,inf, and-inf will behandled according to IEEE rules. Specifically,NaN is not consideredclose to any other value, includingNaN.inf and-inf are onlyconsidered close to themselves.

Added in version 3.5.

See also

PEP 485 – A function for testing approximate equality

math.isfinite(x)¶

ReturnTrue ifx is neither an infinity nor a NaN, andFalse otherwise. (Note that0.0is considered finite.)

Added in version 3.2.

math.isinf(x)¶

ReturnTrue ifx is a positive or negative infinity, andFalse otherwise.

math.isnan(x)¶

ReturnTrue ifx is a NaN (not a number), andFalse otherwise.

math.ldexp(x,i)¶

Returnx*(2**i). This is essentially the inverse of functionfrexp().

math.nextafter(x,y,steps=1)¶

Return the floating-point valuesteps steps afterx towardsy.

Ifx is equal toy, returny, unlesssteps is zero.

Examples:

• 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) goes towards zero.

• math.nextafter(x,math.copysign(math.inf,x)) goes away from zero.

See alsomath.ulp().

Added in version 3.9.

Changed in version 3.12:Added thesteps argument.

math.ulp(x)¶

Return the value of the least significant bit of the floatx:

• Ifx is a NaN (not a number), returnx.

• Ifx is negative, returnulp(-x).

• Ifx is a positive infinity, returnx.

• Ifx is equal to zero, return the smallest positivedenormalized representable float (smaller than the minimum positivenormalized float,sys.float_info.min).

• Ifx is equal to the largest positive representable float,return the value of the least significant bit ofx, such that the firstfloat smaller thanx isx-ulp(x).

• Otherwise (x is a positive finite number), return the value of the leastsignificant bit ofx, such that the first float bigger thanxisx+ulp(x).

ULP stands for “Unit in the Last Place”.

See alsomath.nextafter() andsys.float_info.epsilon.

Added in version 3.9.

Power, exponential and logarithmic functions¶

math.cbrt(x)¶

Return the cube root ofx.

Added in version 3.11.

math.exp(x)¶

Returne raised to the powerx, wheree = 2.718281… is the baseof natural logarithms. This is usually more accurate thanmath.e**xorpow(math.e,x).

math.exp2(x)¶

Return2 raised to the powerx.

Added in version 3.11.

math.expm1(x)¶

Returne raised to the powerx, minus 1. Heree is the base of naturallogarithms. For small floatsx, the subtraction inexp(x)-1can result in asignificant loss of precision; theexpm1()function provides a way to compute this quantity to full precision:

>>>frommathimportexp,expm1>>>exp(1e-5)-1# gives result accurate to 11 places1.0000050000069649e-05>>>expm1(1e-5)# result accurate to full precision1.0000050000166668e-05

Added in version 3.2.

math.log(x[,base])¶

With one argument, return the natural logarithm ofx (to basee).

With two arguments, return the logarithm ofx to the givenbase,calculated aslog(x)/log(base).

math.log1p(x)¶

Return the natural logarithm of1+x (basee). Theresult is calculated in a way which is accurate forx near zero.

math.log2(x)¶

Return the base-2 logarithm ofx. This is usually more accurate thanlog(x,2).

Added in version 3.3.

See also

int.bit_length() returns the number of bits necessary to representan integer in binary, excluding the sign and leading zeros.

math.log10(x)¶

Return the base-10 logarithm ofx. This is usually more accuratethanlog(x,10).

math.pow(x,y)¶

Returnx raised to the powery. Exceptional cases followthe IEEE 754 standard as far as possible. In particular,pow(1.0,x) andpow(x,0.0) always return1.0, evenwhenx is a zero or a NaN. If bothx andy are finite,x is negative, andy is not an integer thenpow(x,y)is undefined, and raisesValueError.

Unlike the built-in** operator,math.pow() converts bothits arguments to typefloat. Use** or the built-inpow() function for computing exact integer powers.

Changed in version 3.11:The special casespow(0.0,-inf) andpow(-0.0,-inf) werechanged to returninf instead of raisingValueError,for consistency with IEEE 754.

math.sqrt(x)¶

Return the square root ofx.

Summation and product functions¶

math.dist(p,q)¶

Return the Euclidean distance between two pointsp andq, eachgiven as a sequence (or iterable) of coordinates. The two pointsmust have the same dimension.

Roughly equivalent to:

sqrt(sum((px-qx)**2.0forpx,qxinzip(p,q)))

Added in version 3.8.

math.fsum(iterable)¶

Return an accurate floating-point sum of values in the iterable. Avoidsloss of precision by tracking multiple intermediate partial sums.

The algorithm’s accuracy depends on IEEE-754 arithmetic guarantees and thetypical case where the rounding mode is half-even. On some non-Windowsbuilds, the underlying C library uses extended precision addition and mayoccasionally double-round an intermediate sum causing it to be off in itsleast significant bit.

For further discussion and two alternative approaches, see theASPN cookbookrecipes for accurate floating-point summation.

math.hypot(*coordinates)¶

Return the Euclidean norm,sqrt(sum(x**2forxincoordinates)).This is the length of the vector from the origin to the pointgiven by the coordinates.

For a two dimensional point(x,y), this is equivalent to computingthe hypotenuse of a right triangle using the Pythagorean theorem,sqrt(x*x+y*y).

Changed in version 3.8:Added support for n-dimensional points. Formerly, only the twodimensional case was supported.

Changed in version 3.10:Improved the algorithm’s accuracy so that the maximum error isunder 1 ulp (unit in the last place). More typically, the resultis almost always correctly rounded to within 1/2 ulp.

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

Calculate the product of all the elements in the inputiterable.The defaultstart value for the product is1.

When the iterable is empty, return the start value. This function isintended specifically for use with numeric values and may rejectnon-numeric types.

Added in version 3.8.

math.sumprod(p,q)¶

Return the sum of products of values from two iterablesp andq.

RaisesValueError if the inputs do not have the same length.

Roughly equivalent to:

sum(itertools.starmap(operator.mul,zip(p,q,strict=True)))

For float and mixed int/float inputs, the intermediate productsand sums are computed with extended precision.

Added in version 3.12.

Angular conversion¶

math.degrees(x)¶

Convert anglex from radians to degrees.

math.radians(x)¶

Convert anglex from degrees to radians.

Trigonometric functions¶

math.acos(x)¶

Return the arc cosine ofx, in radians. The result is between0 andpi.

math.asin(x)¶

Return the arc sine ofx, in radians. The result is between-pi/2 andpi/2.

math.atan(x)¶

Return the arc tangent ofx, in radians. The result is between-pi/2 andpi/2.

math.atan2(y,x)¶

Returnatan(y/x), in radians. The result is between-pi andpi.The vector in the plane from the origin to point(x,y) makes this anglewith the positive X axis. The point ofatan2() is that the signs of bothinputs are known to it, so it can compute the correct quadrant for the angle.For example,atan(1) andatan2(1,1) are bothpi/4, butatan2(-1,-1) is-3*pi/4.

math.cos(x)¶

Return the cosine ofx radians.

math.sin(x)¶

Return the sine ofx radians.

math.tan(x)¶

Return the tangent ofx radians.

Hyperbolic functions¶

Hyperbolic functionsare analogs of trigonometric functions that are based on hyperbolasinstead of circles.

math.acosh(x)¶

Return the inverse hyperbolic cosine ofx.

math.asinh(x)¶

Return the inverse hyperbolic sine ofx.

math.atanh(x)¶

Return the inverse hyperbolic tangent ofx.

math.cosh(x)¶

Return the hyperbolic cosine ofx.

math.sinh(x)¶

Return the hyperbolic sine ofx.

math.tanh(x)¶

Return the hyperbolic tangent ofx.

Special functions¶

math.erf(x)¶

Return theerror function atx.

Theerf() function can be used to compute traditional statisticalfunctions such as thecumulative standard normal distribution:

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

Added in version 3.2.

math.erfc(x)¶

Return the complementary error function atx. Thecomplementary errorfunction is defined as1.0-erf(x). It is used for large values ofx where a subtractionfrom one would cause aloss of significance.

Added in version 3.2.

math.gamma(x)¶

Return theGamma function atx.

Added in version 3.2.

math.lgamma(x)¶

Return the natural logarithm of the absolute value of the Gammafunction atx.

Added in version 3.2.

Constants¶

math.pi¶

The mathematical constantπ = 3.141592…, to available precision.

math.e¶

The mathematical constante = 2.718281…, to available precision.

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 toits radius. To learn more about Tau, check out Vi Hart’s videoPi is (still)Wrong, and start celebratingTau day by eating twice as much pie!

Added in version 3.6.

math.inf¶

A floating-point positive infinity. (For negative infinity, use-math.inf.) Equivalent to the output offloat('inf').

Added in version 3.5.

math.nan¶

A floating-point “not a number” (NaN) value. Equivalent to the output offloat('nan'). Due to the requirements of theIEEE-754 standard,math.nan andfloat('nan') arenot considered to equal to any other numeric value, including themselves. To checkwhether a number is a NaN, use theisnan() function to testfor NaNs instead ofis or==.Example:

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

Added in version 3.5.

Changed in version 3.11:It is now always available.