9.2.1. 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.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. RaisesValueError ifx is not integral oris negative.

math.floor(x)¶

Return the floor ofx, the largest integer less than or equal tox.Ifx is not a float, delegates tox.__floor__(), which should 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(a,b)¶

Return the greatest common divisor of the integersa andb. If eithera orb is nonzero, then the value ofgcd(a,b) is the largestpositive integer that divides botha andb.gcd(0,0) returns0.

New in version 3.5.

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

Return theReal valuex truncated to anIntegral (usually an integer). Delegates tox.__trunc__().

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.

9.2.2. Power and logarithmic functions¶

math.exp(x)¶

Returne**x.

math.expm1(x)¶

Returne**x-1. 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.

9.2.3. Trigonometric functions¶

math.acos(x)¶

Return the arc cosine ofx, in radians.

math.asin(x)¶

Return the arc sine ofx, in radians.

math.atan(x)¶

Return the arc tangent ofx, in radians.

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

Return the Euclidean norm,sqrt(x*x+y*y). This is the length of the vectorfrom the origin to point(x,y).

math.sin(x)¶

Return the sine ofx radians.

math.tan(x)¶

Return the tangent ofx radians.

9.2.4. Angular conversion¶

math.degrees(x)¶

Convert anglex from radians to degrees.

math.radians(x)¶

Convert anglex from degrees to radians.

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

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

9.2.7. Constants¶

math.pi¶

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

math.e¶

The mathematical constant e = 2.718281…, to available precision.

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

New in version 3.5.