math --- Mathematical functions

---

Ce module fournit l'accès aux fonctions mathématiques définies par la norme C.

Ces fonctions ne peuvent pas être utilisées avec les nombres complexes ; si vous avez besoin de la prise en charge des nombres complexes, utilisez les fonctions du même nom du module cmath. La séparation entre les fonctions qui gèrent les nombres complexes et les autres vient du constat que tous les utilisateurs ne souhaitent pas acquérir le niveau mathématique nécessaire à la compréhension des nombres complexes. Recevoir une exception plutôt qu'un nombre complexe en retour d'une fonction permet au programmeur de déterminer immédiatement comment et pourquoi ce nombre a été généré, avant que celui-ci ne soit passé involontairement en paramètre d'une autre fonction.

Les fonctions suivantes sont fournies dans ce module. Sauf mention contraire explicite, toutes les valeurs de retour sont des flottants.

Number-theoretic functions
comb(n, k)	Number of ways to choose k items from n items without repetition and without order
factorial(n)	n factorial
gcd(*integers)	Greatest common divisor of the integer arguments
isqrt(n)	Integer square root of a nonnegative integer n
lcm(*integers)	Least common multiple of the integer arguments
perm(n, k)	Number of ways to choose k items from n items without repetition and with order
Floating point arithmetic
ceil(x)	Ceiling of x, the smallest integer greater than or equal to x
fabs(x)	Absolute value of x
floor(x)	Floor of x, the largest integer less than or equal to x
fma(x, y, z)	Fused multiply-add operation: (x * y) + z
fmod(x, y)	Remainder of division x / y
modf(x)	Fractional and integer parts of x
remainder(x, y)	Remainder of x with respect to y
trunc(x)	Integer part of x
Floating point manipulation functions
copysign(x, y)	Magnitude (absolute value) of x with the sign of y
frexp(x)	Mantissa and exponent of x
isclose(a, b, rel_tol, abs_tol)	Check if the values a and b are close to each other
isfinite(x)	Check if x is neither an infinity nor a NaN
isinf(x)	Check if x is a positive or negative infinity
isnan(x)	Check if x is a NaN (not a number)
ldexp(x, i)	x * (2**i), inverse of function frexp()
nextafter(x, y, steps)	Floating-point value steps steps after x towards y
ulp(x)	Value of the least significant bit of x
Power, exponential and logarithmic functions
cbrt(x)	Cube root of x
exp(x)	e raised to the power x
exp2(x)	2 raised to the power x
expm1(x)	e raised to the power x, minus 1
log(x, base)	Logarithm of x to the given base (e by default)
log1p(x)	Natural logarithm of 1+x (base e)
log2(x)	Base-2 logarithm of x
log10(x)	Base-10 logarithm of x
pow(x, y)	x raised to the power y
sqrt(x)	Square root of x
Summation and product functions
dist(p, q)	Euclidean distance between two points p and q given as an iterable of coordinates
fsum(iterable)	Sum of values in the input iterable
hypot(*coordinates)	Euclidean norm of an iterable of coordinates
prod(iterable, start)	Product of elements in the input iterable with a start value
sumprod(p, q)	Sum of products from two iterables p and q
Angular conversion
degrees(x)	Convert angle x from radians to degrees
radians(x)	Convert angle x from degrees to radians
Trigonometric functions
acos(x)	Arc cosine of x
asin(x)	Arc sine of x
atan(x)	Arc tangent of x
atan2(y, x)	atan(y / x)
cos(x)	Cosine of x
sin(x)	Sine of x
tan(x)	Tangent of x
Hyperbolic functions
acosh(x)	Inverse hyperbolic cosine of x
asinh(x)	Inverse hyperbolic sine of x
atanh(x)	Inverse hyperbolic tangent of x
cosh(x)	Hyperbolic cosine of x
sinh(x)	Hyperbolic sine of x
tanh(x)	Hyperbolic tangent of x
Special functions
erf(x)	Error function at x
erfc(x)	Complementary error function at x
gamma(x)	Gamma function at x
lgamma(x)	Natural logarithm of the absolute value of the Gamma function at x
Constants
pi	π = 3.141592...
e	e = 2.718281...
tau	τ = 2π = 6.283185...
inf	Positive infinity
nan	"Not a number" (NaN)

Number-theoretic functions

math.comb(n, k)

Renvoie le nombre de façons de choisir k éléments parmi n de manière non-ordonnée et sans répétition.

Vaut n! / (k! * (n - k)!) quand k <= n et zéro quand k > n.

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

Lève une TypeError si un des paramètres n'est pas un entier. Lève une ValueError si un des paramètres est négatif.

Ajouté dans la version 3.8.

math.factorial(n)

Return n factorial as an integer. Raises ValueError if n is not integral or is negative.

Modifié dans la version 3.10: Floats with integral values (like 5.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 largest positive integer that is a divisor of all arguments. If all arguments are zero, then the returned value is 0. gcd() without arguments returns 0.

Ajouté dans la version 3.5.

Modifié dans la version 3.9: Added support for an arbitrary number of arguments. Formerly, only two arguments were supported.

math.isqrt(n)

Renvoie la racine carrée entière du nombre positif n. C'est la partie entière de la valeur exacte de la racine carrée de n ou, de manière équivalente, le plus grand entier a tel que a*² ≤ n.

Pour certaines applications, il est plus pratique d'avoir le plus petit entier a tel que n ≤ a² ou, en d'autres termes, la partie entière de la valeur exacte de la racine carrée de n. Pour n positif, on peut le calculer avec a = 1 + isqrt(n - 1).

Ajouté dans la 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 smallest positive integer that is a multiple of all arguments. If any of the arguments is zero, then the returned value is 0. lcm() without arguments returns 1.

Ajouté dans la version 3.9.

math.perm(n, k=None)

Renvoie le nombre de façons de choisir k éléments parmi n de manière ordonnée sans répétition.

Vaut n! / (n - k)! quand k <= n et vaut zéro quand k > n.

If k is not specified or is None, then k defaults to n and the function returns n!.

Lève une TypeError si un des paramètres n'est pas un entier. Lève une ValueError si un des paramètres est négatif.

Ajouté dans la version 3.8.

Floating point arithmetic

math.ceil(x)

Return the ceiling of x, the smallest integer greater than or equal to x. If x is not a float, delegates to x.__ceil__, which should return an Integral value.

math.fabs(x)

Renvoie la valeur absolue de x.

math.floor(x)

Return the floor of x, the largest integer less than or equal to x. If x is not a float, delegates to x.__floor__, which should return an Integral value.

math.fma(x, y, z)

Fused multiply-add operation. Return (x * y) + z, computed as though with infinite precision and range followed by a single round to the float format. This operation often provides better accuracy than the direct expression (x * y) + z.

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

Ajouté dans la version 3.13.

math.fmod(x, y)

Renvoie fmod(x, y), tel que défini par la bibliothèque C de la plate-forme. Notez que l'expression Python x % y peut ne pas renvoyer le même résultat. Le sens du standard C pour fmod(x, y) est d'être exactement (mathématiquement, à une précision infinie) égal à x - n*y pour un entier n tel que le résultat a le signe de x et une magnitude inférieure à abs(y). L'expression Python x % y renvoie un résultat avec le signe de y, et peut ne pas être calculable exactement pour des arguments flottants. Par exemple : fmod(-1e-100, 1e100) est -1e-100, mais le résultat de l'expression Python -1e-100 % 1e100 est 1e100-1e-100, qui ne peut pas être représenté exactement par un flottant et donc qui est arrondi à 1e100. Pour cette raison, la fonction fmod() est généralement privilégiée quand des flottants sont manipulés, alors que l'expression Python x % y est privilégiée quand des entiers sont manipulés.

math.modf(x)

Renvoie les parties entière et fractionnelle de x. Les deux résultats ont le signe de x et sont flottants.

Note that modf() has a different call/return pattern than its C equivalents: it takes a single argument and return a pair of values, rather than returning its second return value through an 'output parameter' (there is no such thing in Python).

math.remainder(x, y)

Renvoie le reste selon la norme IEEE 754 de x par rapport à y. Pour x fini et y fini non nul, il s'agit de la différence x - n*y, où n est l'entier le plus proche de la valeur exacte du quotient x / y. Si x / y est exactement à mi-chemin de deux entiers consécutifs, le plus proche entier pair est utilisé pour n. Ainsi, le reste r = remainder(x, y) vérifie toujours abs(r) <= 0.5 * abs(y).

Les cas spéciaux suivent la norme IEEE 754 : en particulier, remainder(x, math.inf) vaut x pour tout x fini, et remainder(x, 0) et remainder(math.inf, x) lèvent ValueError pour tout x non-NaN. Si le résultat de l'opération remainder est zéro, alors ce zéro aura le même signe que x.

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

Ajouté dans la version 3.7.

math.trunc(x)

Return x with the fractional part removed, leaving the integer part. This rounds toward 0: trunc() is equivalent to floor() for positive x, and equivalent to ceil() for negative x. If x is not a float, delegates to x.__trunc__, which should return an Integral value.

Pour les fonctions ceil(), floor(), et modf(), notez que tous les nombres flottants de magnitude suffisamment grande sont des entiers exacts. Les flottants de Python n'ont généralement pas plus de 53 bits de précision (tels que le type C double de la plate-forme), en quel cas tout flottant x tel que abs(x) >= 2**52 n'a aucun bit fractionnel.

Floating point manipulation functions

math.copysign(x, y)

Renvoie un flottant contenant la magnitude (valeur absolue) de x mais avec le signe de y. Sur les plates-formes prenant en charge les zéros signés, copysign(1.0, -0.0) renvoie -1.0.

math.frexp(x)

Renvoie la mantisse et l'exposant de x dans un couple (m, e). m est un flottant et e est un entier tels que x == m * 2**e exactement. Si x vaut zéro, renvoie (0, 0), sinon 0.5 <= abs(m) < 1. Ceci est utilisé pour « extraire » la représentation interne d'un flottant de manière portable.

Note that frexp() has a different call/return pattern than its C equivalents: it takes a single argument and return a pair of values, rather than returning its second return value through an 'output parameter' (there is no such thing in Python).

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

Renvoie True si les valeurs a et b sont proches l'une de l'autre, et False sinon.

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

rel_tol is the relative tolerance -- it is the maximum allowed difference between a and b, relative to the larger absolute value of a or b. For example, to set a tolerance of 5%, pass rel_tol=0.05. The default tolerance is 1e-09, which assures that the two values are the same within about 9 decimal digits. rel_tol must be nonnegative and less than 1.0.

abs_tol is the absolute tolerance; it defaults to 0.0 and it must be nonnegative. When comparing x to 0.0, isclose(x, 0) is computed as abs(x) <= rel_tol  * abs(x), which is False for any x and rel_tol less than 1.0. So add an appropriate positive abs_tol argument to the call.

Les valeurs spécifiques suivantes : NaN, inf, et -inf définies dans la norme IEEE 754 seront manipulées selon les règles du standard IEEE. En particulier, NaN n'est considéré proche d'aucune autre valeur, NaN inclus. inf et -inf ne sont considérées proches que d'elles-mêmes.

Ajouté dans la version 3.5.

Voir aussi

PEP 485 — Une fonction pour tester des quasi-égalités

math.isfinite(x)

Renvoie True si n n'est ni infini, ni NaN, et False sinon. (Notez que 0.0 est considéré comme fini.)

Ajouté dans la version 3.2.

math.isinf(x)

Renvoie True si x vaut l'infini positif ou négatif, et False sinon.

math.isnan(x)

Renvoie True si x est NaN (Not a Number, ou Pas un Nombre en français), et False sinon.

math.ldexp(x, i)

Renvoie x * (2**i). C'est essentiellement l'inverse de la fonction frexp().

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

Return the floating-point value steps steps after x towards y.

If x is equal to y, return y, unless steps is zero.

Exemples :

• math.nextafter(x, math.inf) augmente de valeur : vers l'infini positif.

• math.nextafter(x, -math.inf) baisse de valeur : vers l'infini négatif.

• math.nextafter(x, 0.0) augmente ou baisse de valeur, vers zéro.

• math.nextafter(x, math.copysign(math.inf, x)) augmente ou baisse de valeur, en s'éloignant de zéro.

Voir aussi : math.ulp().

Ajouté dans la version 3.9.

Modifié dans la version 3.12: Added the steps argument.

math.ulp(x)

Return the value of the least significant bit of the float x:

• If x is a NaN (not a number), return x.

• If x is negative, return ulp(-x).

• If x is a positive infinity, return x.

• If x is equal to zero, return the smallest positive denormalized representable float (smaller than the minimum positive normalized float, sys.float_info.min).

• If x is equal to the largest positive representable float, return the value of the least significant bit of x, such that the first float smaller than x is x - ulp(x).

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

ULP stands for "Unit in the Last Place".

See also math.nextafter() and sys.float_info.epsilon.

Ajouté dans la version 3.9.

Power, exponential and logarithmic functions

math.cbrt(x)

Return the cube root of x.

Ajouté dans la version 3.11.

math.exp(x)

Renvoie e à la puissance x, où e = 2.718281… est la base des logarithmes naturels. Cela est en général plus précis que math.e ** x ou pow(math.e, x).

math.exp2(x)

Return 2 raised to the power x.

Ajouté dans la version 3.11.

math.expm1(x)

Return e raised to the power x, minus 1. Here e is the base of natural logarithms. For small floats x, the subtraction in exp(x) - 1 can result in a significant loss of precision; the expm1() function provides a way to compute this quantity to full precision:

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

Ajouté dans la version 3.2.

math.log(x[, base])

Avec un argument, renvoie le logarithme naturel de x (en base e).

Avec deux arguments, renvoie le logarithme de x en la base donnée, calculé par log(x)/log(base).

math.log1p(x)

Renvoie le logarithme naturel de 1+x (en base e). Le résultat est calculé par un moyen qui reste exact pour x proche de zéro.

math.log2(x)

Renvoie le logarithme en base 2 de x. C'est en général plus précis que log(x, 2).

Ajouté dans la version 3.3.

Voir aussi

int.bit_length() renvoie le nombre de bits nécessaires pour représenter un entier en binaire, en excluant le signe et les zéros de début.

math.log10(x)

Renvoie le logarithme de x en base 10. C'est habituellement plus exact que log(x, 10).

math.pow(x, y)

Return x raised to the power y. Exceptional cases follow the IEEE 754 standard as far as possible. In particular, pow(1.0, x) and pow(x, 0.0) always return 1.0, even when x is a zero or a NaN. If both x and y are finite, x is negative, and y is not an integer then pow(x, y) is undefined, and raises ValueError.

À l'inverse de l'opérateur interne **, la fonction math.pow() convertit ses deux arguments en float. Utilisez ** ou la primitive pow() pour calculer des puissances exactes d'entiers.

Modifié dans la version 3.11: The special cases pow(0.0, -inf) and pow(-0.0, -inf) were changed to return inf instead of raising ValueError, for consistency with IEEE 754.

math.sqrt(x)

Renvoie la racine carrée de x.

Summation and product functions

math.dist(p, q)

Renvoie la distance Euclienne entre deux points p et q, passés comme des séquences (ou des itérables) de coordonnées. Les deux points doivent avoir la même dimension.

À peu près équivalent à :

sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))

Ajouté dans la version 3.8.

math.fsum(iterable)

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

La précision de cet algorithme dépend des garanties arithmétiques de IEEE-754 et des cas standards où le mode d'arrondi est half-even. Sur certaines versions non Windows, la bibliothèque C sous-jacente utilise une addition par précision étendue et peut occasionnellement effectuer un double-arrondi sur une somme intermédiaire causant la prise d'une mauvaise valeur du bit de poids faible.

For further discussion and two alternative approaches, see the ASPN cookbook recipes for accurate floating-point summation.

math.hypot(*coordinates)

Renvoie la norme Euclidienne, sqrt(sum(x**2 for x in coordinates)). C'est la norme du vecteur entre l'origine et le point donné par les coordonnées.

Pour un point bi-dimensionnel (x, y), c'est équivalent à calculer la valeur de l’hypoténuse d'un triangle rectangle en utilisant le théorème de Pythagore, sqrt(x*x + y*y).

Modifié dans la version 3.8: Ajout de la gestion des points à n-dimensions. Auparavant seuls les points bi-dimensionnels étaient gérés.

Modifié dans la version 3.10: Improved the algorithm's accuracy so that the maximum error is under 1 ulp (unit in the last place). More typically, the result is almost always correctly rounded to within 1/2 ulp.

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

Calcule le produit de tous les éléments passés dans l'entrée iterable. La valeur de départ par défaut du produit vaut 1.

Quand l'itérable est vide, renvoie la valeur de départ. Cette fonction ne doit être utilisée qu'avec des valeurs numériques et peut rejeter les types non-numériques.

Ajouté dans la version 3.8.

math.sumprod(p, q)

Return the sum of products of values from two iterables p and q.

Raises ValueError if the inputs do not have the same length.

À peu près équivalent à :

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

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

Ajouté dans la version 3.12.

Conversion angulaire

math.degrees(x)

Convertit l'angle x de radians en degrés.

math.radians(x)

Convertit l'ange x de degrés en radians.

Fonctions trigonométriques

math.acos(x)

Return the arc cosine of x, in radians. The result is between 0 and pi.

math.asin(x)

Return the arc sine of x, in radians. The result is between -pi/2 and pi/2.

math.atan(x)

Return the arc tangent of x, in radians. The result is between -pi/2 and pi/2.

math.atan2(y, x)

Renvoie atan(y / x), en radians. Le résultat est entre -pi et pi. Le vecteur du plan allant de l'origine vers le point (x, y) forme cet angle avec l'axe X positif. L'intérêt de atan2() est que le signe des deux entrées est connu. Donc elle peut calculer le bon quadrant pour l'angle. par exemple atan(1) et atan2(1, 1) donnent tous deux pi/4, mais atan2(-1, -1) donne -3*pi/4.

math.cos(x)

Renvoie le cosinus de x radians.

math.sin(x)

Renvoie le sinus de x radians.

math.tan(x)

Renvoie la tangente de x radians.

Fonctions hyperboliques

Hyperbolic functions are analogs of trigonometric functions that are based on hyperbolas instead of circles.

math.acosh(x)

Renvoie l'arc cosinus hyperbolique de x.

math.asinh(x)

Renvoie l'arc sinus hyperbolique de x.

math.atanh(x)

Renvoie l'arc tangente hyperbolique de x.

math.cosh(x)

Renvoie le cosinus hyperbolique de x.

math.sinh(x)

Renvoie le sinus hyperbolique de x.

math.tanh(x)

Renvoie la tangente hyperbolique de x.

Fonctions spéciales

math.erf(x)

Renvoie la fonction d'erreur en x.

The erf() function can be used to compute traditional statistical functions such as the cumulative standard normal distribution:

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

Ajouté dans la version 3.2.

math.erfc(x)

Renvoie la fonction d'erreur complémentaire en x. La fonction d'erreur complémentaire est définie par 1.0 - erf(x). Elle est utilisée pour les grandes valeurs de x, où la soustraction en partant de 1,0 entraînerait une perte de précision.

Ajouté dans la version 3.2.

math.gamma(x)

Renvoie la fonction Gamma en x.

Ajouté dans la version 3.2.

math.lgamma(x)

Renvoie le logarithme naturel de la valeur absolue de la fonction gamma en x.

Ajouté dans la version 3.2.

Constantes

math.pi

La constante mathématique π = 3.141592…, à la précision disponible.

math.e

La constante mathématique e = 2.718281…, à la précision disponible.

math.tau

La constante mathématique τ = 6.283185…, à la précision disponible. Tau est une constante du cercle égale à 2 *π*, le rapport de la circonférence d'un cercle à son rayon. Pour en apprendre plus sur Tau, regardez la vidéo de Vi Hart, Pi is (still) Wrong, et profitez-en pour célébrer le Jour de Tau en bavardant comme deux pies !

Ajouté dans la version 3.6.

math.inf

Un flottant positif infini. (Pour un infini négatif, utilisez -math.inf.) Équivalent au résultat de float('inf').

Ajouté dans la version 3.5.

math.nan

A floating-point "not a number" (NaN) value. Equivalent to the output of float('nan'). Due to the requirements of the IEEE-754 standard, math.nan and float('nan') are not considered to equal to any other numeric value, including themselves. To check whether a number is a NaN, use the isnan() function to test for NaNs instead of is or ==. Example:

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

Ajouté dans la version 3.5.

Modifié dans la version 3.11: It is now always available.

Particularité de l'implémentation CPython : Le module math consiste majoritairement en un conteneur pour les fonctions mathématiques de la bibliothèque C de la plate-forme. Le comportement dans les cas spéciaux suit l'annexe 'F' du standard C99 quand c'est approprié. L'implémentation actuelle lève une ValueError pour les opérations invalides telles que sqrt(-1.0) ou log(0.0) (où le standard C99 recommande de signaler que l'opération est invalide ou qu'il y a division par zéro), et une OverflowError pour les résultats qui débordent (par exemple exp(1000.0)). NaN ne sera renvoyé pour aucune des fonctions ci-dessus, sauf si au moins un des arguments de la fonction vaut NaN. Dans ce cas, la plupart des fonctions renvoient NaN, mais (à nouveau, selon l'annexe 'F' du standard C99) il y a quelques exceptions à cette règle, par exemple pow(float('nan'), 0.0) ou hypot(float('nan'), float('inf')).

Notez que Python ne fait aucun effort pour distinguer les NaNs signalétiques des NaNs silencieux, et le comportement de signalement des NaNs reste non-spécifié. Le comportement standard est de traiter tous les NaNs comme s'ils étaient silencieux.

Voir aussi

Module cmath

Version complexe de beaucoup de ces fonctions.