Elementary

This module implements elementary functions such as trigonometric, hyperbolic, and sqrt, as well as functions like Abs, Max, Min etc.

sympy.functions.elementary.complexes

re

class sympy.functions.elementary.complexes.re(arg)[source]

Returns real part of expression. This function performs only elementary analysis and so it will fail to decompose properly more complicated expressions. If completely simplified result is needed then use Basic.as_real_imag() or perform complex expansion on instance of this function.

Parameters

arg : Expr

Real or complex expression.

Returns

expr : Expr

Real part of expression.

Examples

>>> from sympy import re, im, I, E, symbols
>>> x, y = symbols('x y', real=True)
>>> re(2*E)
2*E
>>> re(2*I + 17)
17
>>> re(2*I)
0
>>> re(im(x) + x*I + 2)
2
>>> re(5 + I + 2)
7

See also

im

as_real_imag(deep=True, **hints)[source]

Returns the real number with a zero imaginary part.

im

class sympy.functions.elementary.complexes.im(arg)[source]

Returns imaginary part of expression. This function performs only elementary analysis and so it will fail to decompose properly more complicated expressions. If completely simplified result is needed then use Basic.as_real_imag() or perform complex expansion on instance of this function.

Parameters

arg : Expr

Real or complex expression.

Returns

expr : Expr

Imaginary part of expression.

Examples

>>> from sympy import re, im, E, I
>>> from sympy.abc import x, y
>>> im(2*E)
0
>>> im(2*I + 17)
2
>>> im(x*I)
re(x)
>>> im(re(x) + y)
im(y)
>>> im(2 + 3*I)
3

See also

re

as_real_imag(deep=True, **hints)[source]

Return the imaginary part with a zero real part.

sign

class sympy.functions.elementary.complexes.sign(arg)[source]

Returns the complex sign of an expression:

Parameters

arg : Expr

Real or imaginary expression.

Returns

expr : Expr

Complex sign of expression.

Explanation

If the expression is real the sign will be:

  • 1 if expression is positive

  • 0 if expression is equal to zero

  • -1 if expression is negative

If the expression is imaginary the sign will be:

  • I if im(expression) is positive

  • -I if im(expression) is negative

Otherwise an unevaluated expression will be returned. When evaluated, the result (in general) will be cos(arg(expr)) + I*sin(arg(expr)).

Examples

>>> from sympy.functions import sign
>>> from sympy.core.numbers import I
>>> sign(-1)
-1
>>> sign(0)
0
>>> sign(-3*I)
-I
>>> sign(1 + I)
sign(1 + I)
>>> _.evalf()
0.707106781186548 + 0.707106781186548*I

See also

Abs, conjugate

Abs

class sympy.functions.elementary.complexes.Abs(arg)[source]

Return the absolute value of the argument.

Parameters

arg : Expr

Real or complex expression.

Returns

expr : Expr

Absolute value returned can be an expression or integer depending on input arg.

Explanation

This is an extension of the built-in function abs() to accept symbolic values. If you pass a SymPy expression to the built-in abs(), it will pass it automatically to Abs().

Examples

>>> from sympy import Abs, Symbol, S, I
>>> Abs(-1)
1
>>> x = Symbol('x', real=True)
>>> Abs(-x)
Abs(x)
>>> Abs(x**2)
x**2
>>> abs(-x) # The Python built-in
Abs(x)
>>> Abs(3*x + 2*I)
sqrt(9*x**2 + 4)
>>> Abs(8*I)
8

Note that the Python built-in will return either an Expr or int depending on the argument:

>>> type(abs(-1))
<... 'int'>
>>> type(abs(S.NegativeOne))
<class 'sympy.core.numbers.One'>

Abs will always return a sympy object.

See also

sign, conjugate

fdiff(argindex=1)[source]

Get the first derivative of the argument to Abs().

arg

class sympy.functions.elementary.complexes.arg(arg)[source]

returns the argument (in radians) of a complex number. The argument is evaluated in consistent convention with atan2 where the branch-cut is taken along the negative real axis and arg(z) is in the interval (-pi,pi]. For a positive number, the argument is always 0.

Parameters

arg : Expr

Real or complex expression.

Returns

value : Expr

Returns arc tangent of arg measured in radians.

Examples

>>> from sympy.functions import arg
>>> from sympy import I, sqrt
>>> arg(2.0)
0
>>> arg(I)
pi/2
>>> arg(sqrt(2) + I*sqrt(2))
pi/4
>>> arg(sqrt(3)/2 + I/2)
pi/6
>>> arg(4 + 3*I)
atan(3/4)
>>> arg(0.8 + 0.6*I)
0.643501108793284

conjugate

class sympy.functions.elementary.complexes.conjugate(arg)[source]

Returns the \(complex conjugate\) Ref[1] of an argument. In mathematics, the complex conjugate of a complex number is given by changing the sign of the imaginary part.

Thus, the conjugate of the complex number \(a + ib\) (where a and b are real numbers) is \(a - ib\)

Parameters

arg : Expr

Real or complex expression.

Returns

arg : Expr

Complex conjugate of arg as real, imaginary or mixed expression.

Examples

>>> from sympy import conjugate, I
>>> conjugate(2)
2
>>> conjugate(I)
-I
>>> conjugate(3 + 2*I)
3 - 2*I
>>> conjugate(5 - I)
5 + I

See also

sign, Abs

References

R225

https://en.wikipedia.org/wiki/Complex_conjugation

polar_lift

class sympy.functions.elementary.complexes.polar_lift(arg)[source]

Lift argument to the Riemann surface of the logarithm, using the standard branch.

Parameters

arg : Expr

Real or complex expression.

Examples

>>> from sympy import Symbol, polar_lift, I
>>> p = Symbol('p', polar=True)
>>> x = Symbol('x')
>>> polar_lift(4)
4*exp_polar(0)
>>> polar_lift(-4)
4*exp_polar(I*pi)
>>> polar_lift(-I)
exp_polar(-I*pi/2)
>>> polar_lift(I + 2)
polar_lift(2 + I)
>>> polar_lift(4*x)
4*polar_lift(x)
>>> polar_lift(4*p)
4*p

periodic_argument

class sympy.functions.elementary.complexes.periodic_argument(ar, period)[source]

Represent the argument on a quotient of the Riemann surface of the logarithm. That is, given a period \(P\), always return a value in (-P/2, P/2], by using exp(P*I) == 1.

Parameters

ar : Expr

A polar number.

period : ExprT

The period \(P\).

Examples

>>> from sympy import exp_polar, periodic_argument
>>> from sympy import I, pi
>>> periodic_argument(exp_polar(10*I*pi), 2*pi)
0
>>> periodic_argument(exp_polar(5*I*pi), 4*pi)
pi
>>> from sympy import exp_polar, periodic_argument
>>> from sympy import I, pi
>>> periodic_argument(exp_polar(5*I*pi), 2*pi)
pi
>>> periodic_argument(exp_polar(5*I*pi), 3*pi)
-pi
>>> periodic_argument(exp_polar(5*I*pi), pi)
0

See also

sympy.functions.elementary.exponential.exp_polar

polar_lift

Lift argument to the Riemann surface of the logarithm

principal_branch

principal_branch

class sympy.functions.elementary.complexes.principal_branch(x, period)[source]

Represent a polar number reduced to its principal branch on a quotient of the Riemann surface of the logarithm.

Parameters

x : Expr

A polar number.

period : Expr

Positive real number or infinity.

Explanation

This is a function of two arguments. The first argument is a polar number \(z\), and the second one a positive real number or infinity, \(p\). The result is “z mod exp_polar(I*p)”.

Examples

>>> from sympy import exp_polar, principal_branch, oo, I, pi
>>> from sympy.abc import z
>>> principal_branch(z, oo)
z
>>> principal_branch(exp_polar(2*pi*I)*3, 2*pi)
3*exp_polar(0)
>>> principal_branch(exp_polar(2*pi*I)*3*z, 2*pi)
3*principal_branch(z, 2*pi)

See also

sympy.functions.elementary.exponential.exp_polar

polar_lift

Lift argument to the Riemann surface of the logarithm

periodic_argument

sympy.functions.elementary.trigonometric

Trigonometric Functions

sin

class sympy.functions.elementary.trigonometric.sin(arg)[source]

The sine function.

Returns the sine of x (measured in radians).

Explanation

This function will evaluate automatically in the case x/pi is some rational number [R229]. For example, if x is a multiple of pi, pi/2, pi/3, pi/4 and pi/6.

Examples

>>> from sympy import sin, pi
>>> from sympy.abc import x
>>> sin(x**2).diff(x)
2*x*cos(x**2)
>>> sin(1).diff(x)
0
>>> sin(pi)
0
>>> sin(pi/2)
1
>>> sin(pi/6)
1/2
>>> sin(pi/12)
-sqrt(2)/4 + sqrt(6)/4

See also

csc, cos, sec, tan, cot, asin, acsc, acos, asec, atan, acot, atan2

References

R226

https://en.wikipedia.org/wiki/Trigonometric_functions

R227

http://dlmf.nist.gov/4.14

R228

http://functions.wolfram.com/ElementaryFunctions/Sin

R229(1,2)

http://mathworld.wolfram.com/TrigonometryAngles.html

cos

class sympy.functions.elementary.trigonometric.cos(arg)[source]

The cosine function.

Returns the cosine of x (measured in radians).

Explanation

See sin() for notes about automatic evaluation.

Examples

>>> from sympy import cos, pi
>>> from sympy.abc import x
>>> cos(x**2).diff(x)
-2*x*sin(x**2)
>>> cos(1).diff(x)
0
>>> cos(pi)
-1
>>> cos(pi/2)
0
>>> cos(2*pi/3)
-1/2
>>> cos(pi/12)
sqrt(2)/4 + sqrt(6)/4

See also

sin, csc, sec, tan, cot, asin, acsc, acos, asec, atan, acot, atan2

References

R230

https://en.wikipedia.org/wiki/Trigonometric_functions

R231

http://dlmf.nist.gov/4.14

R232

http://functions.wolfram.com/ElementaryFunctions/Cos

tan

class sympy.functions.elementary.trigonometric.tan(arg)[source]

The tangent function.

Returns the tangent of x (measured in radians).

Explanation

See sin() for notes about automatic evaluation.

Examples

>>> from sympy import tan, pi
>>> from sympy.abc import x
>>> tan(x**2).diff(x)
2*x*(tan(x**2)**2 + 1)
>>> tan(1).diff(x)
0
>>> tan(pi/8).expand()
-1 + sqrt(2)

See also

sin, csc, cos, sec, cot, asin, acsc, acos, asec, atan, acot, atan2

References

R233

https://en.wikipedia.org/wiki/Trigonometric_functions

R234

http://dlmf.nist.gov/4.14

R235

http://functions.wolfram.com/ElementaryFunctions/Tan

inverse(argindex=1)[source]

Returns the inverse of this function.

cot

class sympy.functions.elementary.trigonometric.cot(arg)[source]

The cotangent function.

Returns the cotangent of x (measured in radians).

Explanation

See sin() for notes about automatic evaluation.

Examples

>>> from sympy import cot, pi
>>> from sympy.abc import x
>>> cot(x**2).diff(x)
2*x*(-cot(x**2)**2 - 1)
>>> cot(1).diff(x)
0
>>> cot(pi/12)
sqrt(3) + 2

See also

sin, csc, cos, sec, tan, asin, acsc, acos, asec, atan, acot, atan2

References

R236

https://en.wikipedia.org/wiki/Trigonometric_functions

R237

http://dlmf.nist.gov/4.14

R238

http://functions.wolfram.com/ElementaryFunctions/Cot

inverse(argindex=1)[source]

Returns the inverse of this function.

sec

class sympy.functions.elementary.trigonometric.sec(arg)[source]

The secant function.

Returns the secant of x (measured in radians).

Explanation

See sin() for notes about automatic evaluation.

Examples

>>> from sympy import sec
>>> from sympy.abc import x
>>> sec(x**2).diff(x)
2*x*tan(x**2)*sec(x**2)
>>> sec(1).diff(x)
0

See also

sin, csc, cos, tan, cot, asin, acsc, acos, asec, atan, acot, atan2

References

R239

https://en.wikipedia.org/wiki/Trigonometric_functions

R240

http://dlmf.nist.gov/4.14

R241

http://functions.wolfram.com/ElementaryFunctions/Sec

csc

class sympy.functions.elementary.trigonometric.csc(arg)[source]

The cosecant function.

Returns the cosecant of x (measured in radians).

Explanation

See sin() for notes about automatic evaluation.

Examples

>>> from sympy import csc
>>> from sympy.abc import x
>>> csc(x**2).diff(x)
-2*x*cot(x**2)*csc(x**2)
>>> csc(1).diff(x)
0

See also

sin, cos, sec, tan, cot, asin, acsc, acos, asec, atan, acot, atan2

References

R242

https://en.wikipedia.org/wiki/Trigonometric_functions

R243

http://dlmf.nist.gov/4.14

R244

http://functions.wolfram.com/ElementaryFunctions/Csc

sinc

class sympy.functions.elementary.trigonometric.sinc(arg)[source]

Represents an unnormalized sinc function:

\[\begin{split}\operatorname{sinc}(x) = \begin{cases} \frac{\sin x}{x} & \qquad x \neq 0 \\ 1 & \qquad x = 0 \end{cases}\end{split}\]

Examples

>>> from sympy import sinc, oo, jn
>>> from sympy.abc import x
>>> sinc(x)
sinc(x)
  • Automated Evaluation

>>> sinc(0)
1
>>> sinc(oo)
0
  • Differentiation

>>> sinc(x).diff()
cos(x)/x - sin(x)/x**2
  • Series Expansion

>>> sinc(x).series()
1 - x**2/6 + x**4/120 + O(x**6)
  • As zero’th order spherical Bessel Function

>>> sinc(x).rewrite(jn)
jn(0, x)

See also

sin

References

R245

https://en.wikipedia.org/wiki/Sinc_function

Trigonometric Inverses

asin

class sympy.functions.elementary.trigonometric.asin(arg)[source]

The inverse sine function.

Returns the arcsine of x in radians.

Explanation

asin(x) will evaluate automatically in the cases oo, -oo, 0, 1, -1 and for some instances when the result is a rational multiple of pi (see the eval class method).

A purely imaginary argument will lead to an asinh expression.

Examples

>>> from sympy import asin, oo
>>> asin(1)
pi/2
>>> asin(-1)
-pi/2
>>> asin(-oo)
oo*I
>>> asin(oo)
-oo*I

See also

sin, csc, cos, sec, tan, cot, acsc, acos, asec, atan, acot, atan2

References

R246

https://en.wikipedia.org/wiki/Inverse_trigonometric_functions

R247

http://dlmf.nist.gov/4.23

R248

http://functions.wolfram.com/ElementaryFunctions/ArcSin

inverse(argindex=1)[source]

Returns the inverse of this function.

acos

class sympy.functions.elementary.trigonometric.acos(arg)[source]

The inverse cosine function.

Returns the arc cosine of x (measured in radians).

Examples

>>> from sympy import acos, oo
>>> acos(1)
0
>>> acos(0)
pi/2
>>> acos(oo)
oo*I

See also

sin, csc, cos, sec, tan, cot, asin, acsc, asec, atan, acot, atan2

References

R249

https://en.wikipedia.org/wiki/Inverse_trigonometric_functions

R250

http://dlmf.nist.gov/4.23

R251

http://functions.wolfram.com/ElementaryFunctions/ArcCos

inverse(argindex=1)[source]

Returns the inverse of this function.

atan

class sympy.functions.elementary.trigonometric.atan(arg)[source]

The inverse tangent function.

Returns the arc tangent of x (measured in radians).

Explanation

atan(x) will evaluate automatically in the cases oo, -oo, 0, 1, -1 and for some instances when the result is a rational multiple of pi (see the eval class method).

Examples

>>> from sympy import atan, oo
>>> atan(0)
0
>>> atan(1)
pi/4
>>> atan(oo)
pi/2

See also

sin, csc, cos, sec, tan, cot, asin, acsc, acos, asec, acot, atan2

References

R252

https://en.wikipedia.org/wiki/Inverse_trigonometric_functions

R253

http://dlmf.nist.gov/4.23

R254

http://functions.wolfram.com/ElementaryFunctions/ArcTan

inverse(argindex=1)[source]

Returns the inverse of this function.

acot

class sympy.functions.elementary.trigonometric.acot(arg)[source]

The inverse cotangent function.

Returns the arc cotangent of x (measured in radians).

Explanation

acot(x) will evaluate automatically in the cases oo, -oo, zoo, 0, 1, -1 and for some instances when the result is a rational multiple of pi (see the eval class method).

A purely imaginary argument will lead to an acoth expression.

acot(x) has a branch cut along \((-i, i)\), hence it is discontinuous at 0. Its range for real x is \((-\frac{\pi}{2}, \frac{\pi}{2}]\).

Examples

>>> from sympy import acot, sqrt
>>> acot(0)
pi/2
>>> acot(1)
pi/4
>>> acot(sqrt(3) - 2)
-5*pi/12

See also

sin, csc, cos, sec, tan, cot, asin, acsc, acos, asec, atan, atan2

References

R255

http://dlmf.nist.gov/4.23

R256

http://functions.wolfram.com/ElementaryFunctions/ArcCot

inverse(argindex=1)[source]

Returns the inverse of this function.

asec

class sympy.functions.elementary.trigonometric.asec(arg)[source]

The inverse secant function.

Returns the arc secant of x (measured in radians).

Explanation

asec(x) will evaluate automatically in the cases oo, -oo, 0, 1, -1 and for some instances when the result is a rational multiple of pi (see the eval class method).

asec(x) has branch cut in the interval [-1, 1]. For complex arguments, it can be defined [R260] as

\[\operatorname{sec^{-1}}(z) = -i\frac{\log\left(\sqrt{1 - z^2} + 1\right)}{z}\]

At x = 0, for positive branch cut, the limit evaluates to zoo. For negative branch cut, the limit

\[\lim_{z \to 0}-i\frac{\log\left(-\sqrt{1 - z^2} + 1\right)}{z}\]

simplifies to \(-i\log\left(z/2 + O\left(z^3\right)\right)\) which ultimately evaluates to zoo.

As acos(x) = asec(1/x), a similar argument can be given for acos(x).

Examples

>>> from sympy import asec, oo
>>> asec(1)
0
>>> asec(-1)
pi
>>> asec(0)
zoo
>>> asec(-oo)
pi/2

See also

sin, csc, cos, sec, tan, cot, asin, acsc, acos, atan, acot, atan2

References

R257

https://en.wikipedia.org/wiki/Inverse_trigonometric_functions

R258

http://dlmf.nist.gov/4.23

R259

http://functions.wolfram.com/ElementaryFunctions/ArcSec

R260(1,2)

http://reference.wolfram.com/language/ref/ArcSec.html

inverse(argindex=1)[source]

Returns the inverse of this function.

acsc

class sympy.functions.elementary.trigonometric.acsc(arg)[source]

The inverse cosecant function.

Returns the arc cosecant of x (measured in radians).

Explanation

acsc(x) will evaluate automatically in the cases oo, -oo, 0, 1, -1 and for some instances when the result is a rational multiple of pi (see the eval class method).

Examples

>>> from sympy import acsc, oo
>>> acsc(1)
pi/2
>>> acsc(-1)
-pi/2
>>> acsc(oo)
0
>>> acsc(-oo) == acsc(oo)
True
>>> acsc(0)
zoo

See also

sin, csc, cos, sec, tan, cot, asin, acos, asec, atan, acot, atan2

References

R261

https://en.wikipedia.org/wiki/Inverse_trigonometric_functions

R262

http://dlmf.nist.gov/4.23

R263

http://functions.wolfram.com/ElementaryFunctions/ArcCsc

inverse(argindex=1)[source]

Returns the inverse of this function.

atan2

class sympy.functions.elementary.trigonometric.atan2(y, x)[source]

The function atan2(y, x) computes \(\operatorname{atan}(y/x)\) taking two arguments \(y\) and \(x\). Signs of both \(y\) and \(x\) are considered to determine the appropriate quadrant of \(\operatorname{atan}(y/x)\). The range is \((-\pi, \pi]\). The complete definition reads as follows:

\[\begin{split}\operatorname{atan2}(y, x) = \begin{cases} \arctan\left(\frac y x\right) & \qquad x > 0 \\ \arctan\left(\frac y x\right) + \pi& \qquad y \ge 0 , x < 0 \\ \arctan\left(\frac y x\right) - \pi& \qquad y < 0 , x < 0 \\ +\frac{\pi}{2} & \qquad y > 0 , x = 0 \\ -\frac{\pi}{2} & \qquad y < 0 , x = 0 \\ \text{undefined} & \qquad y = 0, x = 0 \end{cases}\end{split}\]

Attention: Note the role reversal of both arguments. The \(y\)-coordinate is the first argument and the \(x\)-coordinate the second.

If either \(x\) or \(y\) is complex:

\[\operatorname{atan2}(y, x) = -i\log\left(\frac{x + iy}{\sqrt{x**2 + y**2}}\right)\]

Examples

Going counter-clock wise around the origin we find the following angles:

>>> from sympy import atan2
>>> atan2(0, 1)
0
>>> atan2(1, 1)
pi/4
>>> atan2(1, 0)
pi/2
>>> atan2(1, -1)
3*pi/4
>>> atan2(0, -1)
pi
>>> atan2(-1, -1)
-3*pi/4
>>> atan2(-1, 0)
-pi/2
>>> atan2(-1, 1)
-pi/4

which are all correct. Compare this to the results of the ordinary \(\operatorname{atan}\) function for the point \((x, y) = (-1, 1)\)

>>> from sympy import atan, S
>>> atan(S(1)/-1)
-pi/4
>>> atan2(1, -1)
3*pi/4

where only the \(\operatorname{atan2}\) function reurns what we expect. We can differentiate the function with respect to both arguments:

>>> from sympy import diff
>>> from sympy.abc import x, y
>>> diff(atan2(y, x), x)
-y/(x**2 + y**2)
>>> diff(atan2(y, x), y)
x/(x**2 + y**2)

We can express the \(\operatorname{atan2}\) function in terms of complex logarithms:

>>> from sympy import log
>>> atan2(y, x).rewrite(log)
-I*log((x + I*y)/sqrt(x**2 + y**2))

and in terms of \(\operatorname(atan)\):

>>> from sympy import atan
>>> atan2(y, x).rewrite(atan)
Piecewise((2*atan(y/(x + sqrt(x**2 + y**2))), Ne(y, 0)), (pi, re(x) < 0), (0, Ne(x, 0)), (nan, True))

but note that this form is undefined on the negative real axis.

See also

sin, csc, cos, sec, tan, cot, asin, acsc, acos, asec, atan, acot

References

R264

https://en.wikipedia.org/wiki/Inverse_trigonometric_functions

R265

https://en.wikipedia.org/wiki/Atan2

R266

http://functions.wolfram.com/ElementaryFunctions/ArcTan2

sympy.functions.elementary.hyperbolic

Hyperbolic Functions

HyperbolicFunction

class sympy.functions.elementary.hyperbolic.HyperbolicFunction(*args)[source]

Base class for hyperbolic functions.

See also

sinh, cosh, tanh, coth

sinh

class sympy.functions.elementary.hyperbolic.sinh(arg)[source]

sinh(x) is the hyperbolic sine of x.

The hyperbolic sine function is \(\frac{e^x - e^{-x}}{2}\).

Examples

>>> from sympy import sinh
>>> from sympy.abc import x
>>> sinh(x)
sinh(x)

See also

cosh, tanh, asinh

as_real_imag(deep=True, **hints)[source]

Returns this function as a complex coordinate.

fdiff(argindex=1)[source]

Returns the first derivative of this function.

inverse(argindex=1)[source]

Returns the inverse of this function.

static taylor_term(n, x, *previous_terms)[source]

Returns the next term in the Taylor series expansion.

cosh

class sympy.functions.elementary.hyperbolic.cosh(arg)[source]

cosh(x) is the hyperbolic cosine of x.

The hyperbolic cosine function is \(\frac{e^x + e^{-x}}{2}\).

Examples

>>> from sympy import cosh
>>> from sympy.abc import x
>>> cosh(x)
cosh(x)

See also

sinh, tanh, acosh

tanh

class sympy.functions.elementary.hyperbolic.tanh(arg)[source]

tanh(x) is the hyperbolic tangent of x.

The hyperbolic tangent function is \(\frac{\sinh(x)}{\cosh(x)}\).

Examples

>>> from sympy import tanh
>>> from sympy.abc import x
>>> tanh(x)
tanh(x)

See also

sinh, cosh, atanh

inverse(argindex=1)[source]

Returns the inverse of this function.

coth

class sympy.functions.elementary.hyperbolic.coth(arg)[source]

coth(x) is the hyperbolic cotangent of x.

The hyperbolic cotangent function is \(\frac{\cosh(x)}{\sinh(x)}\).

Examples

>>> from sympy import coth
>>> from sympy.abc import x
>>> coth(x)
coth(x)

See also

sinh, cosh, acoth

inverse(argindex=1)[source]

Returns the inverse of this function.

sech

class sympy.functions.elementary.hyperbolic.sech(arg)[source]

sech(x) is the hyperbolic secant of x.

The hyperbolic secant function is \(\frac{2}{e^x + e^{-x}}\)

Examples

>>> from sympy import sech
>>> from sympy.abc import x
>>> sech(x)
sech(x)

See also

sinh, cosh, tanh, coth, csch, asinh, acosh

csch

class sympy.functions.elementary.hyperbolic.csch(arg)[source]

csch(x) is the hyperbolic cosecant of x.

The hyperbolic cosecant function is \(\frac{2}{e^x - e^{-x}}\)

Examples

>>> from sympy import csch
>>> from sympy.abc import x
>>> csch(x)
csch(x)

See also

sinh, cosh, tanh, sech, asinh, acosh

fdiff(argindex=1)[source]

Returns the first derivative of this function

static taylor_term(n, x, *previous_terms)[source]

Returns the next term in the Taylor series expansion

Hyperbolic Inverses

asinh

class sympy.functions.elementary.hyperbolic.asinh(arg)[source]

asinh(x) is the inverse hyperbolic sine of x.

The inverse hyperbolic sine function.

Examples

>>> from sympy import asinh
>>> from sympy.abc import x
>>> asinh(x).diff(x)
1/sqrt(x**2 + 1)
>>> asinh(1)
log(1 + sqrt(2))

See also

acosh, atanh, sinh

inverse(argindex=1)[source]

Returns the inverse of this function.

acosh

class sympy.functions.elementary.hyperbolic.acosh(arg)[source]

acosh(x) is the inverse hyperbolic cosine of x.

The inverse hyperbolic cosine function.

Examples

>>> from sympy import acosh
>>> from sympy.abc import x
>>> acosh(x).diff(x)
1/sqrt(x**2 - 1)
>>> acosh(1)
0

See also

asinh, atanh, cosh

inverse(argindex=1)[source]

Returns the inverse of this function.

atanh

class sympy.functions.elementary.hyperbolic.atanh(arg)[source]

atanh(x) is the inverse hyperbolic tangent of x.

The inverse hyperbolic tangent function.

Examples

>>> from sympy import atanh
>>> from sympy.abc import x
>>> atanh(x).diff(x)
1/(1 - x**2)

See also

asinh, acosh, tanh

inverse(argindex=1)[source]

Returns the inverse of this function.

acoth

class sympy.functions.elementary.hyperbolic.acoth(arg)[source]

acoth(x) is the inverse hyperbolic cotangent of x.

The inverse hyperbolic cotangent function.

Examples

>>> from sympy import acoth
>>> from sympy.abc import x
>>> acoth(x).diff(x)
1/(1 - x**2)

See also

asinh, acosh, coth

inverse(argindex=1)[source]

Returns the inverse of this function.

asech

class sympy.functions.elementary.hyperbolic.asech(arg)[source]

asech(x) is the inverse hyperbolic secant of x.

The inverse hyperbolic secant function.

Examples

>>> from sympy import asech, sqrt, S
>>> from sympy.abc import x
>>> asech(x).diff(x)
-1/(x*sqrt(1 - x**2))
>>> asech(1).diff(x)
0
>>> asech(1)
0
>>> asech(S(2))
I*pi/3
>>> asech(-sqrt(2))
3*I*pi/4
>>> asech((sqrt(6) - sqrt(2)))
I*pi/12

See also

asinh, atanh, cosh, acoth

References

R267

https://en.wikipedia.org/wiki/Hyperbolic_function

R268

http://dlmf.nist.gov/4.37

R269

http://functions.wolfram.com/ElementaryFunctions/ArcSech/

inverse(argindex=1)[source]

Returns the inverse of this function.

acsch

class sympy.functions.elementary.hyperbolic.acsch(arg)[source]

acsch(x) is the inverse hyperbolic cosecant of x.

The inverse hyperbolic cosecant function.

Examples

>>> from sympy import acsch, sqrt, S
>>> from sympy.abc import x
>>> acsch(x).diff(x)
-1/(x**2*sqrt(1 + x**(-2)))
>>> acsch(1).diff(x)
0
>>> acsch(1)
log(1 + sqrt(2))
>>> acsch(S.ImaginaryUnit)
-I*pi/2
>>> acsch(-2*S.ImaginaryUnit)
I*pi/6
>>> acsch(S.ImaginaryUnit*(sqrt(6) - sqrt(2)))
-5*I*pi/12

See also

asinh

References

R270

https://en.wikipedia.org/wiki/Hyperbolic_function

R271

http://dlmf.nist.gov/4.37

R272

http://functions.wolfram.com/ElementaryFunctions/ArcCsch/

inverse(argindex=1)[source]

Returns the inverse of this function.

sympy.functions.elementary.integers

ceiling

class sympy.functions.elementary.integers.ceiling(arg)[source]

Ceiling is a univariate function which returns the smallest integer value not less than its argument. This implementation generalizes ceiling to complex numbers by taking the ceiling of the real and imaginary parts separately.

Examples

>>> from sympy import ceiling, E, I, S, Float, Rational
>>> ceiling(17)
17
>>> ceiling(Rational(23, 10))
3
>>> ceiling(2*E)
6
>>> ceiling(-Float(0.567))
0
>>> ceiling(I/2)
I
>>> ceiling(S(5)/2 + 5*I/2)
3 + 3*I

References

R273

“Concrete mathematics” by Graham, pp. 87

R274

http://mathworld.wolfram.com/CeilingFunction.html

floor

class sympy.functions.elementary.integers.floor(arg)[source]

Floor is a univariate function which returns the largest integer value not greater than its argument. This implementation generalizes floor to complex numbers by taking the floor of the real and imaginary parts separately.

Examples

>>> from sympy import floor, E, I, S, Float, Rational
>>> floor(17)
17
>>> floor(Rational(23, 10))
2
>>> floor(2*E)
5
>>> floor(-Float(0.567))
-1
>>> floor(-I/2)
-I
>>> floor(S(5)/2 + 5*I/2)
2 + 2*I

References

R275

“Concrete mathematics” by Graham, pp. 87

R276

http://mathworld.wolfram.com/FloorFunction.html

RoundFunction

class sympy.functions.elementary.integers.RoundFunction(arg)[source]

The base class for rounding functions.

frac

class sympy.functions.elementary.integers.frac(arg)[source]

Represents the fractional part of x

For real numbers it is defined [R277] as

\[x - \left\lfloor{x}\right\rfloor\]

Examples

>>> from sympy import Symbol, frac, Rational, floor, I
>>> frac(Rational(4, 3))
1/3
>>> frac(-Rational(4, 3))
2/3

returns zero for integer arguments

>>> n = Symbol('n', integer=True)
>>> frac(n)
0

rewrite as floor

>>> x = Symbol('x')
>>> frac(x).rewrite(floor)
x - floor(x)

for complex arguments

>>> r = Symbol('r', real=True)
>>> t = Symbol('t', real=True)
>>> frac(t + I*r)
I*frac(r) + frac(t)

References

R277(1,2)

https://en.wikipedia.org/wiki/Fractional_part

R278

http://mathworld.wolfram.com/FractionalPart.html

sympy.functions.elementary.exponential

exp

class sympy.functions.elementary.exponential.exp(arg)[source]

The exponential function, \(e^x\).

Parameters

arg : Expr

Examples

>>> from sympy.functions import exp
>>> from sympy.abc import x
>>> from sympy import I, pi
>>> exp(x)
exp(x)
>>> exp(x).diff(x)
exp(x)
>>> exp(I*pi)
-1

See also

log

as_real_imag(deep=True, **hints)[source]

Returns this function as a 2-tuple representing a complex number.

Examples

>>> from sympy import I
>>> from sympy.abc import x
>>> from sympy.functions import exp
>>> exp(x).as_real_imag()
(exp(re(x))*cos(im(x)), exp(re(x))*sin(im(x)))
>>> exp(1).as_real_imag()
(E, 0)
>>> exp(I).as_real_imag()
(cos(1), sin(1))
>>> exp(1+I).as_real_imag()
(E*cos(1), E*sin(1))
property base

Returns the base of the exponential function.

fdiff(argindex=1)[source]

Returns the first derivative of this function.

static taylor_term(n, x, *previous_terms)[source]

Calculates the next term in the Taylor series expansion.

LambertW

class sympy.functions.elementary.exponential.LambertW(x, k=None)[source]

The Lambert W function \(W(z)\) is defined as the inverse function of \(w \exp(w)\) [R279].

Explanation

In other words, the value of \(W(z)\) is such that \(z = W(z) \exp(W(z))\) for any complex number \(z\). The Lambert W function is a multivalued function with infinitely many branches \(W_k(z)\), indexed by \(k \in \mathbb{Z}\). Each branch gives a different solution \(w\) of the equation \(z = w \exp(w)\).

The Lambert W function has two partially real branches: the principal branch (\(k = 0\)) is real for real \(z > -1/e\), and the \(k = -1\) branch is real for \(-1/e < z < 0\). All branches except \(k = 0\) have a logarithmic singularity at \(z = 0\).

Examples

>>> from sympy import LambertW
>>> LambertW(1.2)
0.635564016364870
>>> LambertW(1.2, -1).n()
-1.34747534407696 - 4.41624341514535*I
>>> LambertW(-1).is_real
False

References

R279(1,2)

https://en.wikipedia.org/wiki/Lambert_W_function

fdiff(argindex=1)[source]

Return the first derivative of this function.

log

class sympy.functions.elementary.exponential.log(arg, base=None)[source]

The natural logarithm function \(\ln(x)\) or \(\log(x)\).

Explanation

Logarithms are taken with the natural base, \(e\). To get a logarithm of a different base b, use log(x, b), which is essentially short-hand for log(x)/log(b).

log represents the principal branch of the natural logarithm. As such it has a branch cut along the negative real axis and returns values having a complex argument in \((-\pi, \pi]\).

Examples

>>> from sympy import log, sqrt, S, I
>>> log(8, 2)
3
>>> log(S(8)/3, 2)
-log(3)/log(2) + 3
>>> log(-1 + I*sqrt(3))
log(2) + 2*I*pi/3

See also

exp

as_base_exp()[source]

Returns this function in the form (base, exponent).

as_real_imag(deep=True, **hints)[source]

Returns this function as a complex coordinate.

Examples

>>> from sympy import I
>>> from sympy.abc import x
>>> from sympy.functions import log
>>> log(x).as_real_imag()
(log(Abs(x)), arg(x))
>>> log(I).as_real_imag()
(0, pi/2)
>>> log(1 + I).as_real_imag()
(log(sqrt(2)), pi/4)
>>> log(I*x).as_real_imag()
(log(Abs(x)), arg(I*x))
fdiff(argindex=1)[source]

Returns the first derivative of the function.

inverse(argindex=1)[source]

Returns \(e^x\), the inverse function of \(\log(x)\).

static taylor_term(n, x, *previous_terms)[source]

Returns the next term in the Taylor series expansion of \(\log(1+x)\).

exp_polar

class sympy.functions.elementary.exponential.exp_polar(*args)[source]

Represent a ‘polar number’ (see g-function Sphinx documentation).

Explanation

exp_polar represents the function \(Exp: \mathbb{C} \rightarrow \mathcal{S}\), sending the complex number \(z = a + bi\) to the polar number \(r = exp(a), \theta = b\). It is one of the main functions to construct polar numbers.

Examples

>>> from sympy import exp_polar, pi, I, exp

The main difference is that polar numbers don’t “wrap around” at \(2 \pi\):

>>> exp(2*pi*I)
1
>>> exp_polar(2*pi*I)
exp_polar(2*I*pi)

apart from that they behave mostly like classical complex numbers:

>>> exp_polar(2)*exp_polar(3)
exp_polar(5)

sympy.functions.elementary.piecewise

ExprCondPair

class sympy.functions.elementary.piecewise.ExprCondPair(expr, cond)[source]

Represents an expression, condition pair.

property cond

Returns the condition of this pair.

property expr

Returns the expression of this pair.

Piecewise

class sympy.functions.elementary.piecewise.Piecewise(*_args)[source]

Represents a piecewise function.

Usage:

Piecewise( (expr,cond), (expr,cond), … )
  • Each argument is a 2-tuple defining an expression and condition

  • The conds are evaluated in turn returning the first that is True. If any of the evaluated conds are not determined explicitly False, e.g. x < 1, the function is returned in symbolic form.

  • If the function is evaluated at a place where all conditions are False, nan will be returned.

  • Pairs where the cond is explicitly False, will be removed.

Examples

>>> from sympy import Piecewise, log, piecewise_fold
>>> from sympy.abc import x, y
>>> f = x**2
>>> g = log(x)
>>> p = Piecewise((0, x < -1), (f, x <= 1), (g, True))
>>> p.subs(x,1)
1
>>> p.subs(x,5)
log(5)

Booleans can contain Piecewise elements:

>>> cond = (x < y).subs(x, Piecewise((2, x < 0), (3, True))); cond
Piecewise((2, x < 0), (3, True)) < y

The folded version of this results in a Piecewise whose expressions are Booleans:

>>> folded_cond = piecewise_fold(cond); folded_cond
Piecewise((2 < y, x < 0), (3 < y, True))

When a Boolean containing Piecewise (like cond) or a Piecewise with Boolean expressions (like folded_cond) is used as a condition, it is converted to an equivalent ITE object:

>>> Piecewise((1, folded_cond))
Piecewise((1, ITE(x < 0, y > 2, y > 3)))

When a condition is an ITE, it will be converted to a simplified Boolean expression:

>>> piecewise_fold(_)
Piecewise((1, ((x >= 0) | (y > 2)) & ((y > 3) | (x < 0))))

See also

piecewise_fold, ITE

_eval_integral(x, _first=True, **kwargs)[source]

Return the indefinite integral of the Piecewise such that subsequent substitution of x with a value will give the value of the integral (not including the constant of integration) up to that point. To only integrate the individual parts of Piecewise, use the \(piecewise_integrate\) method.

Examples

>>> from sympy import Piecewise
>>> from sympy.abc import x
>>> p = Piecewise((0, x < 0), (1, x < 1), (2, True))
>>> p.integrate(x)
Piecewise((0, x < 0), (x, x < 1), (2*x - 1, True))
>>> p.piecewise_integrate(x)
Piecewise((0, x < 0), (x, x < 1), (2*x, True))
as_expr_set_pairs(domain=None)[source]

Return tuples for each argument of self that give the expression and the interval in which it is valid which is contained within the given domain. If a condition cannot be converted to a set, an error will be raised. The variable of the conditions is assumed to be real; sets of real values are returned.

Examples

>>> from sympy import Piecewise, Interval
>>> from sympy.abc import x
>>> p = Piecewise(
...     (1, x < 2),
...     (2,(x > 0) & (x < 4)),
...     (3, True))
>>> p.as_expr_set_pairs()
[(1, Interval.open(-oo, 2)),
 (2, Interval.Ropen(2, 4)),
 (3, Interval(4, oo))]
>>> p.as_expr_set_pairs(Interval(0, 3))
[(1, Interval.Ropen(0, 2)),
 (2, Interval(2, 3))]
doit(**hints)[source]

Evaluate this piecewise function.

classmethod eval(*_args)[source]

Either return a modified version of the args or, if no modifications were made, return None.

Modifications that are made here: 1) relationals are made canonical 2) any False conditions are dropped 3) any repeat of a previous condition is ignored 3) any args past one with a true condition are dropped

If there are no args left, nan will be returned. If there is a single arg with a True condition, its corresponding expression will be returned.

piecewise_integrate(x, **kwargs)[source]

Return the Piecewise with each expression being replaced with its antiderivative. To obtain a continuous antiderivative, use the \(integrate\) function or method.

Examples

>>> from sympy import Piecewise
>>> from sympy.abc import x
>>> p = Piecewise((0, x < 0), (1, x < 1), (2, True))
>>> p.piecewise_integrate(x)
Piecewise((0, x < 0), (x, x < 1), (2*x, True))

Note that this does not give a continuous function, e.g. at x = 1 the 3rd condition applies and the antiderivative there is 2*x so the value of the antiderivative is 2:

>>> anti = _
>>> anti.subs(x, 1)
2

The continuous derivative accounts for the integral up to the point of interest, however:

>>> p.integrate(x)
Piecewise((0, x < 0), (x, x < 1), (2*x - 1, True))
>>> _.subs(x, 1)
1
sympy.functions.elementary.piecewise.piecewise_fold(expr)[source]

Takes an expression containing a piecewise function and returns the expression in piecewise form. In addition, any ITE conditions are rewritten in negation normal form and simplified.

Examples

>>> from sympy import Piecewise, piecewise_fold, sympify as S
>>> from sympy.abc import x
>>> p = Piecewise((x, x < 1), (1, S(1) <= x))
>>> piecewise_fold(x*p)
Piecewise((x**2, x < 1), (x, True))

See also

Piecewise

sympy.functions.elementary.miscellaneous

IdentityFunction

class sympy.functions.elementary.miscellaneous.IdentityFunction[source]

The identity function

Examples

>>> from sympy import Id, Symbol
>>> x = Symbol('x')
>>> Id(x)
x

Min

class sympy.functions.elementary.miscellaneous.Min(*args)[source]

Return, if possible, the minimum value of the list. It is named Min and not min to avoid conflicts with the built-in function min.

Examples

>>> from sympy import Min, Symbol, oo
>>> from sympy.abc import x, y
>>> p = Symbol('p', positive=True)
>>> n = Symbol('n', negative=True)
>>> Min(x, -2)
Min(-2, x)
>>> Min(x, -2).subs(x, 3)
-2
>>> Min(p, -3)
-3
>>> Min(x, y)
Min(x, y)
>>> Min(n, 8, p, -7, p, oo)
Min(-7, n)

See also

Max

find maximum values

Max

class sympy.functions.elementary.miscellaneous.Max(*args)[source]

Return, if possible, the maximum value of the list.

When number of arguments is equal one, then return this argument.

When number of arguments is equal two, then return, if possible, the value from (a, b) that is >= the other.

In common case, when the length of list greater than 2, the task is more complicated. Return only the arguments, which are greater than others, if it is possible to determine directional relation.

If is not possible to determine such a relation, return a partially evaluated result.

Assumptions are used to make the decision too.

Also, only comparable arguments are permitted.

It is named Max and not max to avoid conflicts with the built-in function max.

Examples

>>> from sympy import Max, Symbol, oo
>>> from sympy.abc import x, y, z
>>> p = Symbol('p', positive=True)
>>> n = Symbol('n', negative=True)
>>> Max(x, -2)
Max(-2, x)
>>> Max(x, -2).subs(x, 3)
3
>>> Max(p, -2)
p
>>> Max(x, y)
Max(x, y)
>>> Max(x, y) == Max(y, x)
True
>>> Max(x, Max(y, z))
Max(x, y, z)
>>> Max(n, 8, p, 7, -oo)
Max(8, p)
>>> Max (1, x, oo)
oo
  • Algorithm

The task can be considered as searching of supremums in the directed complete partial orders [R280].

The source values are sequentially allocated by the isolated subsets in which supremums are searched and result as Max arguments.

If the resulted supremum is single, then it is returned.

The isolated subsets are the sets of values which are only the comparable with each other in the current set. E.g. natural numbers are comparable with each other, but not comparable with the \(x\) symbol. Another example: the symbol \(x\) with negative assumption is comparable with a natural number.

Also there are “least” elements, which are comparable with all others, and have a zero property (maximum or minimum for all elements). E.g. \(oo\). In case of it the allocation operation is terminated and only this value is returned.

Assumption:
  • if A > B > C then A > C

  • if A == B then B can be removed

See also

Min

find minimum values

References

R280(1,2)

https://en.wikipedia.org/wiki/Directed_complete_partial_order

R281

https://en.wikipedia.org/wiki/Lattice_%28order%29

root

sympy.functions.elementary.miscellaneous.root(arg, n, k=0, evaluate=None)[source]

Returns the k-th n-th root of arg.

Parameters

k : int, optional

Should be an integer in \(\{0, 1, ..., n-1\}\). Defaults to the principal root if \(0\).

evaluate : bool, optional

The parameter determines if the expression should be evaluated. If None, its value is taken from global_parameters.evaluate.

Examples

>>> from sympy import root, Rational
>>> from sympy.abc import x, n
>>> root(x, 2)
sqrt(x)
>>> root(x, 3)
x**(1/3)
>>> root(x, n)
x**(1/n)
>>> root(x, -Rational(2, 3))
x**(-3/2)

To get the k-th n-th root, specify k:

>>> root(-2, 3, 2)
-(-1)**(2/3)*2**(1/3)

To get all n n-th roots you can use the rootof function. The following examples show the roots of unity for n equal 2, 3 and 4:

>>> from sympy import rootof
>>> [rootof(x**2 - 1, i) for i in range(2)]
[-1, 1]
>>> [rootof(x**3 - 1,i) for i in range(3)]
[1, -1/2 - sqrt(3)*I/2, -1/2 + sqrt(3)*I/2]
>>> [rootof(x**4 - 1,i) for i in range(4)]
[-1, 1, -I, I]

SymPy, like other symbolic algebra systems, returns the complex root of negative numbers. This is the principal root and differs from the text-book result that one might be expecting. For example, the cube root of -8 does not come back as -2:

>>> root(-8, 3)
2*(-1)**(1/3)

The real_root function can be used to either make the principal result real (or simply to return the real root directly):

>>> from sympy import real_root
>>> real_root(_)
-2
>>> real_root(-32, 5)
-2

Alternatively, the n//2-th n-th root of a negative number can be computed with root:

>>> root(-32, 5, 5//2)
-2

References

sqrt

sympy.functions.elementary.miscellaneous.sqrt(arg, evaluate=None)[source]

Returns the principal square root.

Parameters

evaluate : bool, optional

The parameter determines if the expression should be evaluated. If None, its value is taken from global_parameters.evaluate.

Examples

>>> from sympy import sqrt, Symbol, S
>>> x = Symbol('x')
>>> sqrt(x)
sqrt(x)
>>> sqrt(x)**2
x

Note that sqrt(x**2) does not simplify to x.

>>> sqrt(x**2)
sqrt(x**2)

This is because the two are not equal to each other in general. For example, consider x == -1:

>>> from sympy import Eq
>>> Eq(sqrt(x**2), x).subs(x, -1)
False

This is because sqrt computes the principal square root, so the square may put the argument in a different branch. This identity does hold if x is positive:

>>> y = Symbol('y', positive=True)
>>> sqrt(y**2)
y

You can force this simplification by using the powdenest() function with the force option set to True:

>>> from sympy import powdenest
>>> sqrt(x**2)
sqrt(x**2)
>>> powdenest(sqrt(x**2), force=True)
x

To get both branches of the square root you can use the rootof function:

>>> from sympy import rootof
>>> [rootof(x**2-3,i) for i in (0,1)]
[-sqrt(3), sqrt(3)]

Although sqrt is printed, there is no sqrt function so looking for sqrt in an expression will fail:

>>> from sympy.utilities.misc import func_name
>>> func_name(sqrt(x))
'Pow'
>>> sqrt(x).has(sqrt)
Traceback (most recent call last):
  ...
sympy.core.sympify.SympifyError: SympifyError: <function sqrt at 0x10e8900d0>

To find sqrt look for Pow with an exponent of 1/2:

>>> (x + 1/sqrt(x)).find(lambda i: i.is_Pow and abs(i.exp) is S.Half)
{1/sqrt(x)}

References

R282

https://en.wikipedia.org/wiki/Square_root

R283

https://en.wikipedia.org/wiki/Principal_value

cbrt

sympy.functions.elementary.miscellaneous.cbrt(arg, evaluate=None)[source]

Returns the principal cube root.

Parameters

evaluate : bool, optional

The parameter determines if the expression should be evaluated. If None, its value is taken from global_parameters.evaluate.

Examples

>>> from sympy import cbrt, Symbol
>>> x = Symbol('x')
>>> cbrt(x)
x**(1/3)
>>> cbrt(x)**3
x

Note that cbrt(x**3) does not simplify to x.

>>> cbrt(x**3)
(x**3)**(1/3)

This is because the two are not equal to each other in general. For example, consider \(x == -1\):

>>> from sympy import Eq
>>> Eq(cbrt(x**3), x).subs(x, -1)
False

This is because cbrt computes the principal cube root, this identity does hold if \(x\) is positive:

>>> y = Symbol('y', positive=True)
>>> cbrt(y**3)
y

References

real_root

sympy.functions.elementary.miscellaneous.real_root(arg, n=None, evaluate=None)[source]

Return the real n’th-root of arg if possible.

Parameters

n : int or None, optional

If n is None, then all instances of (-n)**(1/odd) will be changed to -n**(1/odd). This will only create a real root of a principal root. The presence of other factors may cause the result to not be real.

evaluate : bool, optional

The parameter determines if the expression should be evaluated. If None, its value is taken from global_parameters.evaluate.

Examples

>>> from sympy import root, real_root
>>> real_root(-8, 3)
-2
>>> root(-8, 3)
2*(-1)**(1/3)
>>> real_root(_)
-2

If one creates a non-principal root and applies real_root, the result will not be real (so use with caution):

>>> root(-8, 3, 2)
-2*(-1)**(2/3)
>>> real_root(_)
-2*(-1)**(2/3)