9.2. Fonctions mathématiques — "math"
*************************************

Ce module est toujours disponible. Il fournit l’accès aux fonctions
mathématiques définies par le standard C.

Ces fonctions ne peuvent être utilisées avec les nombres complexes,
utilisez les fonctions du même nom du module "cmath" si vous souhaitez
un support des nombres complexes. La distinction entre les fonctions
supportant les nombres complexes et celles ne les supportant pas set
née du fait que tous les utilisateurs ne désirent pas acquérir le
niveau mathématique suffisant pour comprendre les nombres complexes.
Recevoir une exception à la place d’un nombre complexe permet de
détecter un nombre complexe non désiré en paramètre, ainsi le
programmeur peut déterminer comment et pourquoi il a été généré.

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


9.2.1. Fonctions arithmétiques et de représentation
===================================================

math.ceil(x)

   Return the ceiling of *x* as a float, the smallest integer value
   greater than or equal to *x*.

math.copysign(x, y)

   Return *x* with the sign of *y*.  On a platform that supports
   signed zeros, "copysign(1.0, -0.0)" returns *-1.0*.

   Nouveau dans la version 2.6.

math.fabs(x)

   Renvoie la valeur absolue de *x*.

math.factorial(x)

   Renvoie la factorielle de *x*. Lève une "ValueError" si *x* n’est
   pas entier ou s’il est négatif.

   Nouveau dans la version 2.6.

math.floor(x)

   Return the floor of *x* as a float, the largest integer value less
   than or equal to *x*.

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 préférée quand des flottants sont manipulés, alors que
   l’expression Python "x % y" est préféré quand des entiers sont
   manipulés.

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.

math.fsum(iterable)

   Renvoie une somme flottante exacte des valeurs dans l’itérable.
   Évite la perte de précision en gardant plusieurs sommes partielles
   intermédiaires :

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

   L’exactitude de cet algorithme dépend des garanties arithmétiques
   de IEEE-754 et des cas typiques 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.

   Pour de plus amples discussions et deux approches alternatives,
   voir ASPN cookbook recipes for accurate floating point summation.

   Nouveau dans la version 2.6.

math.isinf(x)

   Check if the float *x* is positive or negative infinity.

   Nouveau dans la version 2.6.

math.isnan(x)

   Check if the float *x* is a NaN (not a number).  For more
   information on NaNs, see the IEEE 754 standards.

   Nouveau dans la version 2.6.

math.ldexp(x, i)

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

math.modf(x)

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

math.trunc(x)

   Return the "Real" value *x* truncated to an "Integral" (usually a
   long integer).  Uses the "__trunc__" method.

   Nouveau dans la version 2.6.

Notez que les fonctions "frexp()" et "modf()" ont un système d’appel
différent de leur homologue C : elles prennent un simple argument et
renvoient une paire de valeurs au lieu de renvoyer leur seconde valeur
de retour dans un “paramètre de sortie” (il n’y a pas de telle
possibilité en Python).

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


9.2.2. Fonctions logarithme et exponentielle
============================================

math.exp(x)

   Renvoie "e**x".

math.expm1(x)

   Return "e**x - 1".  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

   Nouveau dans la version 2.7.

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

   Modifié dans la version 2.3: *base* argument added.

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.

   Nouveau dans la version 2.6.

math.log10(x)

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

math.pow(x, y)

   Renvoie "x" élevé à la puissance "y". Les cas exceptionnels suivent
   l’annexe “F” du standard C99 autant que possible. En particulier,
   "pow(1.0, x)" et "pow(x, 0.0)" renvoient toujours "1.0", même si
   "x" est zéro ou NaN. Si à la fois "x" *et* "y" sont finis, "x" est
   négatif et "y" n’est pas entier, alors "pow(x, y)" est non défini
   et lève une "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 2.6: The outcome of "1**nan" and "nan**0"
   was undefined.

math.sqrt(x)

   Renvoie la racine carrée de *x*.


9.2.3. Fonctions trigonométriques
=================================

math.acos(x)

   Renvoie l’arc cosinus de *x*, en radians.

math.asin(x)

   Renvoie l’arc sinus de *x*, en radians.

math.atan(x)

   Renvoie l’arc tangente de *x*, en radians.

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

   Renvoie la norme euclidienne "sqrt(x*x + y*y)". C’est la longueur
   du vecteur allant de l’origine au point "(x, y)".

math.sin(x)

   Renvoie le sinus de*x* radians.

math.tan(x)

   Renvoie la tangente de *x* radians.


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


9.2.5. Fonctions hyperboliques
==============================

math.acosh(x)

   Renvoie l’arc cosinus hyperbolique de *x*.

   Nouveau dans la version 2.6.

math.asinh(x)

   Renvoie l’arc sinus hyperbolique de *x*.

   Nouveau dans la version 2.6.

math.atanh(x)

   Renvoie l’arc tangente hyperbolique de *x*.

   Nouveau dans la version 2.6.

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


9.2.6. Fonctions spéciales
==========================

math.erf(x)

   Return the error function at *x*.

   Nouveau dans la version 2.7.

math.erfc(x)

   Return the complementary error function at *x*.

   Nouveau dans la version 2.7.

math.gamma(x)

   Return the Gamma function at *x*.

   Nouveau dans la version 2.7.

math.lgamma(x)

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

   Nouveau dans la version 2.7.


9.2.7. Constantes
=================

math.pi

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

math.e

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

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 toute les 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 typique est de traiter
tous les NaNs comme s’ils étaient silencieux.

Modifié dans la version 2.6: Behavior in special cases now aims to
follow C99 Annex F.  In earlier versions of Python the behavior in
special cases was loosely specified.

Voir aussi:

  Module "cmath"
     Version complexe de beaucoup de ces fonctions.
