Number-theoretic and representation functions¶

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.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 theexpression(1+x)**n.

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

New in version 3.8.

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

Return the absolute value ofx.

math.factorial(x)¶

Returnx factorial as an integer. RaisesValueError ifx is not integral oris negative.

Deprecated since version 3.9:Accepting floats with integral values (like5.0) is deprecated.

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.fmod(x,y)¶

Returnfmod(x,y), as defined by the platform C library. 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.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.

math.fsum(iterable)¶

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

>>>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

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.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.

New in version 3.5.

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

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.

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 greater than zero.

abs_tol is the minimum absolute tolerance – useful for comparisons nearzero.abs_tol must be at least zero.

If no errors occur, the result will be:abs(a-b)<=max(rel_tol*max(abs(a),abs(b)),abs_tol).

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.

New 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.)

New 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.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).

New 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.

New in version 3.9.

math.ldexp(x,i)¶

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

math.modf(x)¶

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

math.nextafter(x,y)¶

Return the next floating-point value afterx towardsy.

Ifx is equal toy, returny.

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

New 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 is None, thenk defaults tonand the function returnsn!.

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

New in version 3.8.

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.

New in version 3.8.

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.

New 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.

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.

New in version 3.9.

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

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.

Power and logarithmic functions¶

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.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

New 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).

New 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 followAnnex ‘F’ of the C99 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.

math.sqrt(x)¶

Return the square root ofx.

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.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)))

New in version 3.8.

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.

math.sin(x)¶

Return the sine ofx radians.

math.tan(x)¶

Return the tangent ofx radians.

Angular conversion¶

math.degrees(x)¶

Convert anglex from radians to degrees.

math.radians(x)¶

Convert anglex from degrees to 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

New 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.

New in version 3.2.

math.gamma(x)¶

Return theGamma function atx.

New in version 3.2.

math.lgamma(x)¶

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

New 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!

New in version 3.6.

math.inf¶

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

New 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

New in version 3.5.