Ce document est relatif à une vieille version de Python qui n'est plus soutenue. Mettez à jour votre version et lisez Bienvenue sur la documentation de la version stable actuelle de Python.

# Fonctions mathématiques pour nombres complexes — `cmath`

Ce module fournit l'accès aux fonctions mathématiques pour les nombres complexes. Les fonctions de ce module acceptent les entiers, les nombres flottants ou les nombres complexes comme arguments. Elles acceptent également tout objet Python ayant une méthode `__complex__()` (respectivement `__float__()`) : cette méthode est utilisée pour convertir l’objet en nombre complexe (respectivement un nombre flottant) et la fonction est ensuite appliquée sur le résultat de la conversion.

Note

Sur les plate-formes avec un support système et matériel des zéros signés, les fonctions incluant une coupure complexe sont continues de chaque côté de la coupure : le signe du zéro distingue les deux extrémités de la coupure. Sur les plate-formes ne supportant pas les zéros signés, la continuité est spécifiée en-dessous.

## Conversion vers et à partir de coordonnées polaires

Un nombre complexe Python `z` est stocké de manière interne en coordonnées cartésiennes. Il est entièrement défini par sa partie réelle `z.real` et sa partie complexe `z.imag`. En d'autres termes :

    z == z.real + z.imag*1j

Les coordonnées polaires donnent une manière alternative de représenter un nombre complexe. En coordonnées polaires, un nombre complexe z est défini par son module r et par son argument (angle de phase) phi. Le module r est la distance entre z et l'origine, alors que l'argument phi est l'angle (dans le sens inverse des aiguilles d'une montre, ou sens trigonométrique), mesuré en radians, à partir de l'axe X positif, et vers le segment de droite joignant z à l'origine.

Les fonctions suivantes peuvent être utilisées pour convertir à partir des coordonnées rectangulaires natives vers les coordonnées polaires, et vice-versa.

`cmath.``phase`(x)

  Renvoie l'argument de x, dans un nombre flottant. `phase(x)` est équivalent à `math.atan2(x.imag, x.real)`. Le résultat se situe dans l'intervalle [-π, π], et la coupure par cette opération se situe sur la partie négative de l'axe des réels, continue par au-dessus. Sur les systèmes supportant les zéros signés (ce qui inclut la plupart des systèmes utilisés actuellement), cela signifie que le signe du résultat est le même que `x.imag` même quand `x.imag` vaut zéro :

      >>> phase(complex(-1.0, 0.0))
      3.141592653589793
      >>> phase(complex(-1.0, -0.0))
      -3.141592653589793

Note

Le module (valeur absolue) d'un nombre complexe x peut être calculé en utilisant la primitive `abs()`. Il n'y a pas de fonction spéciale du module `cmath` pour cette opération.

`cmath.``polar`(x)

  Renvoie la représentation de x en coordonnées polaires. Renvoie une paire `(r, phi)` où r est le module de x et phi est l'argument de x. `polar(x)` est équivalent à `(abs(x), phase(x))`.

`cmath.``rect`(r, phi)

  Renvoie le nombre complexe x dont les coordonnées polaires sont r et phi. Équivalent à `r * (math.cos(phi) + math.sin(phi)*1j)`.

## Fonctions logarithme et exponentielle

`cmath.``exp`(x)

  Renvoie e élevé à la puissance x, où e est la base des logarithmes naturels.

`cmath.``log`(x[, base])

  Renvoie le logarithme de x dans la base précisée. Si la base n'est pas spécifiée, le logarithme naturel (népérien) de x est renvoyé. Il y a une coupure, partant de 0 sur l'axe réel négatif et vers `-∞`, continue par au-dessus.

`cmath.``log10`(x)

  Renvoie le logarithme en base 10 de x. Elle a la même coupure que `log()`.

`cmath.``sqrt`(x)

  Renvoie la racine carrée de x. Elle a la même coupure que `log()`.

## Fonctions trigonométriques

`cmath.``acos`(x)

  Renvoie l'arc cosinus de x. Il y a deux coupures : une allant de 1 sur l'axe réel vers ∞, continue par en-dessous ; l'autre allant de `-1` sur l'axe réel vers `-∞`, continue par au-dessus.

`cmath.``asin`(x)

  Renvoie l'arc sinus de x. Elle a les mêmes coupures que `acos()`.

`cmath.``atan`(x)

  Renvoie la tangente de x. l y a deux coupures : une allant de `1j` sur l'axe imaginaire vers `∞j`, continue par la droite ; l'autre allant de `-1j` sur l'axe imaginaire vers `-∞j`, continue par la gauche.

`cmath.``cos`(x)

  Renvoie le cosinus de x.

`cmath.``sin`(x)

  Renvoie le sinus de x.

`cmath.``tan`(x)

  Renvoie la tangente de x.

## Fonctions hyperboliques

`cmath.``acosh`(x)

  Renvoie l'arc cosinus hyperbolique de x. Il y a une coupure, allant de 1 sur l'axe réel vers `-∞`, continue par au-dessus.

`cmath.``asinh`(x)

  Renvoie l'arc sinus hyperbolique de x. Il y a deux coupures : une allant de `1j` sur l'axe imaginaire vers `∞j`, continue par la droite ; l'autre allant de `-1j` sur l'axe imaginaire vers `∞j`, continue par la gauche.

`cmath.``atanh`(x)

  Renvoie l'arc tangente hyperbolique de x. Il y a deux coupures : une allant de `1` sur l'axe réel allant vers `∞`, continue par en-dessous ; l'autre allant de `-1` sur l'axe réel vers `-∞`, continue par au-dessus.

`cmath.``cosh`(x)

  Renvoie le cosinus hyperbolique de x.

`cmath.``sinh`(x)

  Renvoie le sinus hyperbolique de x.

`cmath.``tanh`(x)

  Renvoie la tangente hyperbolique de x.

## Fonctions de classifications

`cmath.``isfinite`(x)

  Renvoie `True` si la partie réelle et la partie imaginaire de x sont finies, et `False` sinon.

  Nouveau dans la version 3.2.

`cmath.``isinf`(x)

  Renvoie `True` si soit la partie réelle ou la partie imaginaire de x est infinie, et `False` sinon.

`cmath.``isnan`(x)

  Renvoie `True` si soit la partie réelle ou la partie imaginaire de x est NaN, et `False` sinon.

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

  Déterminer si deux valeurs sont proches se fait à l'aide des tolérances absolues et relatives données en paramètres.

  rel_tol est la tolérance relative -- c'est la différence maximale permise entre a et b, relativement à la plus grande valeur de a ou de b. Par exemple, pour définir une tolérance de 5%,, précisez `rel_tol=0.05`. La tolérance par défaut est `1e-09`, ce qui assure que deux valeurs sont les mêmes à partir de la 9e décimale. rel_tol doit être supérieur à zéro.

  abs_tol est la tolérance absolue minimale -- utile pour les comparaisons proches de zéro. abs_tol doit valoir au moins zéro.

  Si aucune erreur n'est rencontrée, le résultat sera : `abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)`.

  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és proches que d'eux-mêmes.

  Nouveau dans la version 3.5.

  Voir aussi

  PEP 485 -- Une fonction pour tester des égalités approximées

## Constantes

`cmath.``pi`

  La constante mathématique π, en tant que flottant.

`cmath.``e`

  La constante mathématique e, en tant que flottant.

`cmath.``tau`

  La constante mathématique τ, sous forme de flottant.

  Nouveau dans la version 3.6.

`cmath.``inf`

  Nombre à virgule flottante positif infini. Équivaut à `float('inf')`.

  Nouveau dans la version 3.6.

`cmath.``infj`

  Nombre complexe dont la partie réelle vaut zéro et la partie imaginaire un infini positif. Équivalent à `complex(0.0, float('inf'))`.

  Nouveau dans la version 3.6.

`cmath.``nan`

  Un nombre à virgule flottante NaN (Not a number). Équivalent à `float('nan')`.

  Nouveau dans la version 3.6.

`cmath.``nanj`

  Nombre complexe dont la partie réelle vaut zéro et la partie imaginaire vaut un NaN. Équivalent à `complex(0.0, float('nan'))`.

  Nouveau dans la version 3.6.

Notez que la sélection de fonctions est similaire, mais pas identique, à celles du module `math`. La raison d'avoir deux modules est que certains utilisateurs ne sont pas intéressés par les nombres complexes, et peut-être ne savent même pas ce qu'ils sont. Ils préféreraient alors que `math.sqrt(-1)` lève une exception au lieu de renvoyer un nombre complexe. Également, notez que les fonctions définies dans `cmath` renvoient toujours un nombre complexe, même si le résultat peut être exprimé à l'aide d'un nombre réel (en quel cas la partie imaginaire du complexe vaut zéro).

Une note sur les coupures : ce sont des courbes sur lesquelles la fonction n'est pas continue. Ce sont des caractéristiques nécessaires de beaucoup de fonctions complexes. Il est supposé que si vous avez besoin d'utiliser des fonctions complexes, vous comprendrez ce que sont les coupures. Consultez n'importe quel livre (pas trop élémentaire) sur les variables complexes pour plus d'informations. Pour des informations sur les choix des coupures à des fins numériques, voici une bonne référence :

Voir aussi

Kahan, W: Branch cuts for complex elementary functions; or, Much ado about nothing's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the art in numerical analysis. Clarendon Press (1987) pp165--211.