math
— Mathematical functions¶
Este módulo proporciona acceso a las funciones matemáticas definidas en el estándar de C.
Estas funciones no pueden ser usadas con números complejos; usa las funciones con el mismo nombre del módulo cmath
si requieres soporte para números complejos. La distinción entre las funciones que admiten números complejos y las que no se hace debido a que la mayoría de los usuarios no quieren aprender tantas matemáticas como se requiere para comprender los números complejos. Recibir una excepción en lugar de un resultado complejo permite la detección temprana del número complejo inesperado utilizado como parámetro, de modo que el programador pueda determinar cómo y porqué se generó en primer lugar.
Este módulo proporciona las funciones descritas a continuación. Excepto cuando se indique lo contrario explícitamente, todos los valores retornados son flotantes.
Teoría de números y funciones de representación¶
- math.ceil(x)¶
Retorna el «techo» de x, el número entero más pequeño que es mayor o igual que x. Si x no es un flotante, delega en
x.__ceil__
, que debería retornar un valorIntegral
.
- math.comb(n, k)¶
Retorna el número de formas posibles de elegir k elementos de n, de forma ordenada y sin repetición.
Se evalúa como
n! / (k! * (n - k)!)
cuandok <= n
y como cero cuandok > n
.También llamado coeficiente binomial porque es equivalente al coeficiente del k-ésimo término en la expansión polinomial de
(1 + x)ⁿ
.Lanza una excepción
TypeError
si alguno de los argumentos no es un entero. Lanza una excepciónValueError
si alguno de los argumentos es negativo.Added in version 3.8.
- math.copysign(x, y)¶
Retorna un flotante con la magnitud (valor absoluto) de x pero el signo de y. En plataformas que admiten ceros con signo,
copysign(1.0, -0.0)
retorna -1.0.
- math.fabs(x)¶
Retorna el valor absoluto de x.
- math.factorial(n)¶
Retorna el factorial de n como un número entero. Lanza una excepción
ValueError
si n no es un entero o negativo.Obsoleto desde la versión 3.9: Aceptar flotantes con valores integrales (como
5.0
) está obsoleto.
- math.floor(x)¶
Retorna el «suelo» de x, el primer número entero menor o igual que x. Si x no es un flotante, delega en
x.__floor__
, que debería retornar un valorIntegral
.
- math.fmod(x, y)¶
Retorna
fmod(x, y)
, tal como se define en la biblioteca de C de la plataforma. Ten en cuenta que la expresiónx % y
de Python puede no retornar el mismo resultado. La intención del estándar de C es quefmod(x, y)
sea exactamente (matemáticamente; con precisión infinita) igual ax - n*y
para algún número entero n tal que el resultado tenga el mismo signo que x y magnitud menor queabs(y)
. La expresiónx % y
de Python retorna un resultado con el signo de y en su lugar, y es posible que no pueda calcularse con exactitud para argumentos flotantes. Por ejemplo,fmod(-1e-100, 1e100)
es-1e-100
, pero el resultado de-1e-100 % 1e100
en Python es1e100-1e-100
, que no se puede representar exactamente como un flotante, y se redondea sorprendentemente a1e100
. Por esta razón, generalmente se prefiere la funciónfmod()
cuando se trabaja con flotantes, mientras que se prefiere el uso dex % y
de Python cuando se trabaja con enteros.
- math.frexp(x)¶
Retorna la mantisa y el exponente de x como el par
(m, e)
. m es un flotante y e es un número entero tal quex == m * 2**e
exactamente. Si x es cero, retorna(0.0, 0)
, y retorna0.5 <= abs(m) < 1
en caso contrario. Se utiliza como una forma portable de «extraer» la representación interna de un flotante.
- 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 precisión del algoritmo depende de las garantías aritméticas de IEEE-754 y del caso típico en el que se usa el «medio redondo a par» (half-even) como método de redondeo. En algunas compilaciones que no son de Windows, la biblioteca de C subyacente utiliza la adición de precisión extendida y, ocasionalmente, puede realizar un doble redondeo en una suma intermedia, haciendo que el bit menos significativo tome el valor incorrecto.
For further discussion and two alternative approaches, see the ASPN cookbook recipes for accurate floating-point summation.
- math.gcd(*integers)¶
Retorna el máximo común divisor de los argumentos enteros. Si cualquiera de los argumentos no es cero, entonces el valor retornado es el entero positivo más grande que divide a todos los argumentos. Si todos los argumentos son cero, entonces el valor retornado es
0
.gcd()
sin argumentos retorna0
.Added in version 3.5.
Distinto en la versión 3.9: Agregado soporte para un número arbitrario de argumentos. Anteriormente sólo se soportaba dos argumentos.
- math.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)¶
Retorna
True
si los valores a y b están cerca el uno del otro yFalse
en caso contrario.Que dos valores se consideren cercanos o no, se determina de acuerdo con las tolerancias absolutas y relativas dadas.
rel_tol es la tolerancia relativa: esta es la diferencia máxima permitida entre a y b, en relación con el valor absoluto mayor de a o b. Por ejemplo, para establecer una tolerancia del 5%, pasa
rel_tol=0.05
. La tolerancia predeterminada es1e-09
, lo que garantiza que los dos valores sean iguales considerando 9 dígitos decimales aproximadamente. rel_tol debe ser mayor que cero.abs_tol es la tolerancia absoluta mínima, útil para las comparaciones cercanas a cero. abs_tol debe valer al menos cero.
Si no se encuentran errores, el resultado será:
abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)
.Los valores especiales de IEEE 754
NaN
,inf
e-inf
se manejarán de acuerdo con las reglas del IEEE. Concretamente,NaN
no se considera cercano a ningún otro valor, incluidoNaN
. Por su parte,inf
e-inf
solo se consideran cercanos a sí mismos.Added in version 3.5.
Ver también
PEP 485 – Una función para comprobar la igualdad aproximada
- math.isfinite(x)¶
Retorna
True
si x no es infinito ni NaN, oFalse
en caso contrario. (Ten en cuenta que0.0
es considerado finito.)Added in version 3.2.
- math.isinf(x)¶
Retorna
True
si x es infinito positivo o negativo, oFalse
en caso contrario.
- math.isnan(x)¶
Retorna
True
si x es NaN (not a number, en español: no es un número), oFalse
en caso contrario.
- math.isqrt(n)¶
Retorna la raíz cuadrada del número entero no negativo n. Es el resultado de aplicar la función suelo al valor exacto de la raíz cuadrada de n, o de forma equivalente, el mayor entero a tal que a² ≤ n.
Para algunas aplicaciones, puede ser más conveniente tener el menor número entero a tal que n ≤ a², en otras palabras, el resultado de aplicar la función techo a la raíz cuadrada exacta de n. Para n positivo, esto se puede calcular usando
a = 1 + isqrt(n - 1)
.Added in version 3.8.
- math.lcm(*integers)¶
Retorna el mínimo común múltiplo de los argumentos enteros. Si todos los argumentos no son cero, entonces el valor retornado es el entero positivo más pequeño que es un múltiplo de todos los argumentos. Si cualquiera de los argumentos es cero, entonces el valor retornado es
0
.lcm()
sin argumentos retorna1
.Added in version 3.9.
- math.modf(x)¶
Retorna la parte fraccionaria y entera de x. Ambos resultados son flotantes y tienen el mismo signo que x .
- math.nextafter(x, y, steps=1)¶
Retorna el valor en coma flotante steps pasos después x hacia y.
Si x es igual a y, retorna y, a menos que steps sea cero.
Ejemplos:
math.nextafter(x, math.inf)
va hacia el infinito positivo.math.nextafter(x, -math.inf)
va hacia el infinito negativo.math.nextafter(x, 0.0)
va hacia cero.math.nextafter(x, math.copysign(math.inf, x))
se aleja de cero.
Ver también
math.ulp()
.Added in version 3.9.
Distinto en la versión 3.12: Añadido el argumento steps.
- math.perm(n, k=None)¶
Retorna el número de formas posibles de elegir k elementos de n elementos, sin repetición y en orden.
Se evalúa como
n! / (n - k)!
cuandok <= n
y como cero cuandok > n
.If k is not specified or is
None
, then k defaults to n and the function returnsn!
.Lanza una excepción
TypeError
si alguno de los argumentos no es un entero. Lanza una excepciónValueError
si alguno de los argumentos es negativo.Added in version 3.8.
- math.prod(iterable, *, start=1)¶
Calcula el producto de todos los elementos en la entrada iterable. El valor start predeterminado para el producto es
1
.Cuando el iterable está vacío, retorna el valor inicial. Esta función está diseñada específicamente para su uso con valores numéricos y puede rechazar tipos no numéricos.
Added in version 3.8.
- math.remainder(x, y)¶
Retorna el resto o residuo según la norma IEEE 754 de x con respecto a y. Para un valor x finito y un valor y finito distinto de cero, es la diferencia
x - n * y
, donden
es el número entero más cercano al valor exacto del cocientex / y
. Six / y
está exactamente en mitad de dos enteros consecutivos, el entero par más cercano se utiliza paran
. Por lo tanto, el residuor = remainder(x, y)
siempre satisfaceabs(r) <= 0.5 * abs(y)
.Los casos especiales siguen el estándar IEEE 754: en particular,
remainder(x, math.inf)
es x para todo x finito, yremainder(x, 0)
junto aremainder(math.inf, x)
lanzan una excepciónValueError
para todo x que no sea NaN. Si el resultado de la operación residuo es cero, este cero tendrá el mismo signo que x.On platforms using IEEE 754 binary floating point, the result of this operation is always exactly representable: no rounding error is introduced.
Added in version 3.7.
- math.sumprod(p, q)¶
Retorna la suma de productos de valores de dos iterables p y q.
Lanza
ValueError
si las entradas no tienen la misma longitud.Aproximadamente equivalente a:
sum(itertools.starmap(operator.mul, zip(p, q, strict=True)))
Para entradas flotantes y mixtas int/float, los productos intermedios y las sumas se calculan con precisión ampliada.
Added in version 3.12.
- math.trunc(x)¶
Retorna x con la parte fraccionaria eliminada, dejando la parte entera.Esto redondea hacia 0:
trunc()
es equivalente afloor()
para x positivo y equivalente aceil()
para x negativo. Si x no es un flotante, delega ax.__trunc__
, que debería retornar un valorIntegral
.
- math.ulp(x)¶
Retorna el valor del bit menos significativo del flotante x:
Si x es un NaN (not a number), retorna x.
Si x es negativo, retorna
ulp(-x)
.Si x es un infinito positivo, retorna x.
Si x es igual a cero, retorna el flotante representable desnormalizado positivo más pequeño (menor que el flotante normalizado positivo mínimo,
sys.float_info.min
).Si x es igual al flotante representable positivo más pequeño, retorna el bit menos significativo de x, de tal manera que el primer flotante menor que x es
x - ulp(x)
.De lo contrario (x es un número finito positivo), retorna el valor del bit menos significativo de x , de tal forma que el primer flotante mayor a x es
x + ulp(x)
.
ULP significa Unit in the Last Place (unidad en el último lugar).
Ver también
math.nextafter()
ysys.float_info.epsilon
.Added in version 3.9.
Ten en cuenta que frexp()
y modf()
tienen un patrón de llamada/retorno diferente al de sus equivalentes en C: toman un solo argumento y retornan un par de valores, en lugar de retornar su segundo valor de retorno a través de un parámetro de salida (no existe tal cosa en Python).
Para las funciones ceil()
, floor()
y modf()
, ten en cuenta que todos los números de coma flotante de magnitud suficientemente grande son enteros exactos. Los flotantes de Python normalmente no tienen más de 53 bits de precisión (lo mismo que el tipo double de C en la plataforma), en cuyo caso cualquier flotante x con abs(x) >= 2**52
no necesariamente tiene bits fraccionarios.
Funciones logarítmicas y exponenciales¶
- math.cbrt(x)¶
Retorna la raíz cúbica de x.
Added in version 3.11.
- math.exp(x)¶
Retorna e elevado a la x potencia, dónde e = 2.718281… es la base de los logaritmos naturales. Esto generalmente es más preciso que
math.e ** x
opow(math.e, x)
.
- math.exp2(x)¶
Retorna 2 elevado a la potencia x.
Added in version 3.11.
- math.expm1(x)¶
Retorna e elevado a la x potencia, menos 1. Aquí e es la base de los logaritmos naturales. Para flotantes x pequeños, la resta en
exp(x) - 1
puede resultar en una pérdida significativa de precisión; la funciónexpm1()
proporciona una forma de calcular este valor con una precisión total:>>> 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
Added in version 3.2.
- math.log(x[, base])¶
Con un argumento, retorna el logaritmo natural de x (en base e).
Con dos argumentos, retorna el logaritmo de x en la base dada, calculado como
log(x)/log(base)
.
- math.log1p(x)¶
Retorna el logaritmo natural de 1+x (base e). El resultado se calcula de forma precisa para x cercano a cero.
- math.log2(x)¶
Retorna el logaritmo en base 2 de x. Esto suele ser más preciso que
log(x, 2)
.Added in version 3.3.
Ver también
int.bit_length()
retorna el número de bits necesarios para representar un entero en binario, excluyendo el signo y los ceros iniciales.
- math.log10(x)¶
Retorna el logaritmo en base 10 de x. Esto suele ser más preciso que
log(x, 10)
.
- math.pow(x, y)¶
Retorna
x
elevado a la potenciay
. Los casos excepcionales siguen el estándar IEEE 754 en la medida de lo posible. En particular,pow(1.0, x)
ypow(x, 0.0)
siempre retornan1.0
, incluso cuandox
es cero o NaN. Si tantox
comoy
son finitos,x
es negativo ey
no es un número entero, entoncespow(x, y)
no está definido y se lanza una excepciónValueError
.A diferencia del operador incorporado
**
,math.pow()
convierte ambos argumentos al tipofloat
. Utiliza**
o la función incorporadapow()
para calcular potencias enteras exactas.Distinto en la versión 3.11: Los casos especiales
pow(0.0, -inf)
ypow(-0.0, -inf)
se cambiaron para devolverinf
en lugar de generarValueError
, por consistencia con IEEE 754.
- math.sqrt(x)¶
Retorna la raíz cuadrada de x.
Funciones trigonométricas¶
- math.acos(x)¶
Retorna el arcocoseno de x, en radianes. El resultado está entre
0
ypi
.
- math.asin(x)¶
Retorna el arcoseno de x, en radianes. El resultado está entre
-pi/2
ypi/2
.
- math.atan(x)¶
Retorna la arcotangente de x, en radianes. El resultado está entre
-pi/2
ypi/2
.
- math.atan2(y, x)¶
Retorna
atan(y / x)
, en radianes. El resultado está entre-pi
ypi
. El vector del plano que va del origen al punto(x, y)
, forma este ángulo con el eje X positivo. La ventaja deatan2()
es que el signo de ambas entradas es conocido, por lo que se puede calcular el cuadrante correcto para el ángulo. Por ejemplo,atan(1)
yatan2(1, 1)
son ambaspi/4
, peroatan2(-1, -1)
es-3*pi/4
.
- math.cos(x)¶
Retorna el coseno de x radianes.
- math.dist(p, q)¶
Retorna la distancia euclidiana entre dos puntos p y q, cada uno de ellos dado como una secuencia (o iterable) de coordenadas. Los dos puntos deben tener la misma dimensión.
Aproximadamente equivalente a:
sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))
Added in version 3.8.
- math.hypot(*coordinates)¶
Retorna la norma euclidiana,
sqrt(sum(x**2 for x in coordinates))
. Esta es la longitud del vector que va desde el origen hasta el punto dado por las coordenadas.Para un punto bidimensional
(x, y)
, esto equivale a calcular la hipotenusa de un triángulo rectángulo usando el teorema de Pitágoras,sqrt(x*x + y*y)
.Distinto en la versión 3.8: Agregado soporte para puntos n-dimensionales. Anteriormente, solo se admitía el caso bidimensional.
Distinto en la versión 3.10: Se mejoró la precisión del algoritmo para que el error máximo sea inferior a 1 ulp (unidad en último lugar). Más típicamente, el resultado casi siempre se redondea correctamente dentro de 1/2 ulp.
- math.sin(x)¶
Retorna el seno de x radianes.
- math.tan(x)¶
Retorna la tangente de x radianes.
Conversión angular¶
- math.degrees(x)¶
Convierte el ángulo x de radianes a grados.
- math.radians(x)¶
Convierte el ángulo x de grados a radianes.
Funciones hiperbólicas¶
Las funciones hiperbólicas son análogas a las funciones trigonométricas que están basadas en hipérbolas en lugar de círculos.
- math.acosh(x)¶
Retorna el coseno hiperbólico inverso de x.
- math.asinh(x)¶
Retorna el seno hiperbólico inverso de x.
- math.atanh(x)¶
Retorna la tangente hiperbólica inversa de x.
- math.cosh(x)¶
Retorna el coseno hiperbólico de x.
- math.sinh(x)¶
Retorna el seno hiperbólico de x.
- math.tanh(x)¶
Retorna la tangente hiperbólica de x.
Funciones especiales¶
- math.erf(x)¶
Retorna la función error 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
Added in version 3.2.
- math.erfc(x)¶
Retorna la función error complementaria en x. La función error complementaria se define como
1.0 - erf(x)
. Se usa para valores grandes de x donde una resta de 1 causaría una pérdida de presición.Added in version 3.2.
- math.gamma(x)¶
Retorna la función gamma en x.
Added in version 3.2.
- math.lgamma(x)¶
Retorna el logaritmo natural del valor absoluto de la función gamma en x.
Added in version 3.2.
Constantes¶
- math.pi¶
La constante matemática π = 3.141592…, hasta la precisión disponible.
- math.e¶
La constante matemática e = 2.718281…, hasta la precisión disponible.
- math.tau¶
La constante matemática τ = 6.283185…, hasta la precisión disponible. Tau es una constante del círculo igual a 2π, la razón entre la circunferencia de un círculo y su radio. Para obtener más información sobre Tau, consulta el video de Vi Hart, Pi is (still) Wrong, y comienza a celebrar el el día de Tau ¡comiendo el doble de tarta!
Added in version 3.6.
- math.inf¶
Un valor infinito positivo en punto flotante. (Para un valor infinito negativo, usa
-math.inf
.) Equivalente a la salida defloat('inf')
.Added in version 3.5.
- math.nan¶
Un valor de coma flotante «no es un número» (NaN). Equivalente a la salida de
float('nan')
. Debido a los requisitos del estándar IEEE-754,math.nan
yfloat('nan')
no se consideran iguales a ningún otro valor numérico, incluidos ellos mismos. Para verificar si un número es NaN, use la funciónisnan()
para probar NaN en lugar deis
o==
. Ejemplo:>>> import math >>> math.nan == math.nan False >>> float('nan') == float('nan') False >>> math.isnan(math.nan) True >>> math.isnan(float('nan')) True
Added in version 3.5.
Distinto en la versión 3.11: Ahora está siempre disponible.
Detalles de implementación de CPython: El módulo math
consiste principalmente en delgados envoltorios alrededor de las funciones matemáticas de la biblioteca de C de la plataforma. El comportamiento en casos excepcionales sigue el Anexo F del estándar C99 cuando corresponda. La implementación actual lanzará un ValueError
para operaciones no válidas como sqrt(-1.0)
o log(0.0)
(donde el estándar C99 recomienda señalar que la operación no es válida o que hay división entre cero), y un OverflowError
para aquellos resultados de desbordamiento (por ejemplo, exp(1000.0)
). No se retornará NaN para ninguna de las funciones anteriores, a no ser que al menos uno de los argumentos de la función sea NaN. En este caso, la mayoría de las funciones retornan NaN, pero de nuevo (de acuerdo con el apéndice F del estándar C99) hay algunas excepciones a esta regla, por ejemplo pow(float('nan'), 0.0)
o hypot(float('nan'), float('inf'))
.
Ten en cuenta que Python no hace ningún esfuerzo por distinguir los NaN de señalización de los NaN silenciosos, y el comportamiento de señalización de los NaN permanece sin especificar. El comportamiento estándar es tratar a todos los NaN como silenciosos.
Ver también
- Módulo
cmath
Versiones de muchas de estas funciones para números complejos.