Elementary

This module implements elementary functions, as well as functions like Abs, Max, etc.

Abs

Returns the absolute value of the argument.

Examples:

>>> from sympy.functions import Abs
>>> Abs(-1)
1

class sympy.functions.elementary.complexes.Abs

Return the absolute value of the argument.

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

See also

sign, conjugate

Examples

>>> from sympy import Abs, Symbol, S
>>> 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)

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.

fdiff(argindex=1)

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

Examples

>>> from sympy.abc import x
>>> from sympy.functions import Abs
>>> Abs(-x).fdiff()
sign(x)

acos

class sympy.functions.elementary.trigonometric.acos

See also

asin, atan, cos

Notes

• acos(x) will evaluate automatically in the cases oo, -oo, 0, 1, -1

Examples

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

inverse(argindex=1)

Returns the inverse of this function.

acosh

class sympy.functions.elementary.hyperbolic.acosh

The inverse hyperbolic cosine function.

• acosh(x) -> Returns the inverse hyperbolic cosine of x

See also

asinh, atanh, cosh

inverse(argindex=1)

Returns the inverse of this function.

acot

class sympy.functions.elementary.trigonometric.acot

inverse(argindex=1)

Returns the inverse of this function.

acoth

class sympy.functions.elementary.hyperbolic.acoth

The inverse hyperbolic cotangent function.

• acoth(x) -> Returns the inverse hyperbolic cotangent of x

inverse(argindex=1)

Returns the inverse of this function.

arg

Returns the argument (in radians) of a complex number. For a real number, the argument is always 0.

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

class sympy.functions.elementary.complexes.arg

Returns the argument (in radians) of a complex number

asin

class sympy.functions.elementary.trigonometric.asin

See also

acos, atan, sin

Notes

• asin(x) will evaluate automatically in the cases oo, -oo, 0, 1, -1

Examples

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

inverse(argindex=1)

Returns the inverse of this function.

asinh

class sympy.functions.elementary.hyperbolic.asinh

The inverse hyperbolic sine function.

• asinh(x) -> Returns the inverse hyperbolic sine of x

See also

acosh, atanh, sinh

inverse(argindex=1)

Returns the inverse of this function.

atan

class sympy.functions.elementary.trigonometric.atan

See also

acos, asin, tan

Notes

• atan(x) will evaluate automatically in the cases oo, -oo, 0, 1, -1

Examples

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

inverse(argindex=1)

Returns the inverse of this function.

atan2

This function is like \(\operatorname{atan}\), but considers the sign of both arguments in order to correctly determine the quadrant of its result.

class sympy.functions.elementary.trigonometric.atan2

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.

See also

sin, cos, sec, csc, tan, cot, asin, acos, atan

References

[R75]

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

[R76]

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

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)
2*atan(y/(x + sqrt(x**2 + y**2)))

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

atanh

class sympy.functions.elementary.hyperbolic.atanh

The inverse hyperbolic tangent function.

• atanh(x) -> Returns the inverse hyperbolic tangent of x

See also

asinh, acosh, tanh

inverse(argindex=1)

Returns the inverse of this function.

ceiling

class sympy.functions.elementary.integers.ceiling

Ceiling is a univariate function which returns the smallest integer value not less than its argument. Ceiling function is generalized in this implementation to complex numbers.

More information can be found in “Concrete mathematics” by Graham, pp. 87 or visit http://mathworld.wolfram.com/CeilingFunction.html.

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

See also

floor

conjugate

Returns the complex conjugate 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\)

Examples:

>>> from sympy.functions import conjugate
>>> from sympy import I
>>> conjugate(2)
2
>>> conjugate(I)
-I

class sympy.functions.elementary.complexes.conjugate

Changes the sign of the imaginary part of a complex number.

See also

sign, Abs

Examples

>>> from sympy import conjugate, I

>>> conjugate(1 + I)
1 - I

cos

class sympy.functions.elementary.trigonometric.cos

The cosine function.

• cos(x) -> Returns the cosine of x (measured in radians)

See also

sin, tan, acos

Notes

• cos(x) will evaluate automatically in the case x is a multiple of pi, pi/2, pi/3, pi/4 and pi/6.

References

[R77]

http://planetmath.org/encyclopedia/DefinitionsInTrigonometry.html

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

cosh

class sympy.functions.elementary.hyperbolic.cosh

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

• cosh(x) -> Returns the hyperbolic cosine of x

See also

sinh, tanh, acosh

cot

class sympy.functions.elementary.trigonometric.cot

inverse(argindex=1)

Returns the inverse of this function.

coth

class sympy.functions.elementary.hyperbolic.coth

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

• coth(x) -> Returns the hyperbolic cotangent of x

inverse(argindex=1)

Returns the inverse of this function.

exp

class sympy.functions.elementary.exponential.exp

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

See also

log

as_real_imag(deep=True, **hints)

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

See also

sympy.functions.elementary.complexes.re, sympy.functions.elementary.complexes.im

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

base

Returns the base of the exponential function.

fdiff(argindex=1)

Returns the first derivative of this function.

static taylor_term(*args, **kw_args)

Calculates the next term in the Taylor series expansion.

See also

classes sympy.functions.elementary.exponential.log

ExprCondPair

class sympy.functions.elementary.piecewise.ExprCondPair

Represents an expression, condition pair.

cond

Returns the condition of this pair.

expr

Returns the expression of this pair.

free_symbols

Return the free symbols of this pair.

floor

class sympy.functions.elementary.integers.floor

Floor is a univariate function which returns the largest integer value not greater than its argument. However this implementation generalizes floor to complex numbers.

More information can be found in “Concrete mathematics” by Graham, pp. 87 or visit http://mathworld.wolfram.com/FloorFunction.html.

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

See also

ceiling

HyperbolicFunction

class sympy.functions.elementary.hyperbolic.HyperbolicFunction

Base class for hyperbolic functions.

See also

sinh, cosh, tanh, coth

IdentityFunction

class sympy.functions.elementary.miscellaneous.IdentityFunction

The identity function

Examples

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

im

Returns the imaginary part of an expression.

Examples:

>>> from sympy.functions import im
>>> from sympy import I
>>> im(2+3*I)
3

See also

sympy.functions.elementary.complexes.re

LambertW

class sympy.functions.elementary.exponential.LambertW

Lambert W function, defined as the inverse function of x*exp(x). This function represents the principal branch of this inverse function, which like the natural logarithm is multivalued.

For more information, see: http://en.wikipedia.org/wiki/Lambert_W_function

fdiff(argindex=1)

Return the first derivative of this function.

log

class sympy.functions.elementary.exponential.log

The natural logarithm function \(\ln(x)\) or \(\log(x)\). 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).

See also

exp

as_base_exp()

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

as_real_imag(deep=True, **hints)

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)

Returns the first derivative of the function.

inverse(argindex=1)

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

static taylor_term(*args, **kw_args)

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

See also

classes sympy.functions.elementary.exponential.exp

Min

Returns the minimum of two (comparable) expressions.

Examples:

>>> from sympy.functions import Min
>>> Min(1,2)
1
>>> from sympy.abc import x
>>> Min(1, x)
Min(1, x)

It is named Min and not min to avoid conflicts with the built-in function min.

class sympy.functions.elementary.miscellaneous.Min

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

See also

Max

find maximum values

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(x, -2)

>>> 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(n, -7)

Max

Returns the maximum of two (comparable) expressions

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

class sympy.functions.elementary.miscellaneous.Max

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.

See also

Min

find minimum values

References

[R78]

(1, 2) http://en.wikipedia.org/wiki/Directed_complete_partial_order

[R79]

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

Examples

>>> from sympy import Max, Symbol, oo
>>> from sympy.abc import x, y
>>> p = Symbol('p', positive=True)
>>> n = Symbol('n', negative=True)

>>> Max(x, -2)                  
Max(x, -2)

>>> 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 [R78].

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

Piecewise

class sympy.functions.elementary.piecewise.Piecewise

Represents a piecewise function.

Usage:

Piecewise( (expr,cond), (expr,cond), ... )

• Each argument is a 2-tuple defining a 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, a ValueError exception will be raised.
• Pairs where the cond is explicitly False, will be removed.

See also

piecewise_fold

Examples

>>> from sympy import Piecewise, log
>>> from sympy.abc import x
>>> 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)

doit(**hints)

Evaluate this piecewise function.

sympy.functions.elementary.piecewise.piecewise_fold(expr)

Takes an expression containing a piecewise function and returns the expression in piecewise form.

See also

Piecewise

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, 1 <= x))

re

Return the real part of an expression.

Examples:

>>> from sympy.functions import re
>>> from sympy import I
>>> re(2+3*I)
2

class sympy.functions.elementary.complexes.re

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.

>>> from sympy import re, im, I, E
>>> from sympy.abc import x, y

>>> re(2*E)
2*E

>>> re(2*I + 17)
17

>>> re(2*I)
0

>>> re(im(x) + x*I + 2)
2

See also

im

as_real_imag(deep=True, **hints)

Returns the real number with a zero complex part.

See also

sympy.functions.elementary.complexes.im

root

sympy.functions.elementary.miscellaneous.root(arg, n)

The n-th root function (a shortcut for arg**(1/n))

root(x, n) -> Returns the principal n-th root of x.

See also

sympy.polys.rootoftools.RootOf, sympy.core.power.integer_nthroot, sqrt, real_root

References

• http://en.wikipedia.org/wiki/Square_root
• http://en.wikipedia.org/wiki/real_root
• http://en.wikipedia.org/wiki/Root_of_unity
• http://en.wikipedia.org/wiki/Principal_value
• http://mathworld.wolfram.com/CubeRoot.html

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

>>> [ RootOf(x**2-1,i) for i in (0,1) ]
[-1, 1]

>>> [ RootOf(x**3-1,i) for i in (0,1,2) ]
[1, -1/2 - sqrt(3)*I/2, -1/2 + sqrt(3)*I/2]

>>> [ RootOf(x**4-1,i) for i in (0,1,2,3) ]
[-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 such a result real or simply return the real root in the first place:

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

RoundFunction

class sympy.functions.elementary.integers.RoundFunction

The base class for rounding functions.

sin

class sympy.functions.elementary.trigonometric.sin

The sine function.

• sin(x) -> Returns the sine of x (measured in radians)

See also

cos, tan, asin

Notes

• sin(x) will evaluate automatically in the case x is a multiple of pi, pi/2, pi/3, pi/4 and pi/6.

References

[R80]

http://planetmath.org/encyclopedia/DefinitionsInTrigonometry.html

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

sinh

class sympy.functions.elementary.hyperbolic.sinh

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

• sinh(x) -> Returns the hyperbolic sine of x

See also

cosh, tanh, asinh

as_real_imag(deep=True, **hints)

Returns this function as a complex coordinate.

fdiff(argindex=1)

Returns the first derivative of this function.

inverse(argindex=1)

Returns the inverse of this function.

static taylor_term(*args, **kw_args)

Returns the next term in the Taylor series expansion.

sqrt

Returns the square root of an expression. It is equivalent to raise to Rational(1,2).

>>> from sympy.functions import sqrt
>>> from sympy import Rational
>>> sqrt(2) == 2**Rational(1,2)
True

class sympy.functions.elementary.miscellaneous.sqrt

The square root function

sqrt(x) -> Returns the principal square root of x.

See also

sympy.polys.rootoftools.RootOf, root, real_root

References

• http://en.wikipedia.org/wiki/Square_root
• http://en.wikipedia.org/wiki/Principal_value

Examples

>>> from sympy import sqrt, Symbol
>>> 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)]

sign

class sympy.functions.elementary.complexes.sign

Returns the sign of an expression, that is:

• 1 if expression is positive
• 0 if expression is equal to zero
• -1 if expression is negative

See also

Abs, conjugate

Examples

>>> from sympy.functions import sign
>>> sign(-1)
-1
>>> sign(0)
0

tan

class sympy.functions.elementary.trigonometric.tan

See also

sin, cos, atan

Notes

• tan(x) will evaluate automatically in the case x is a multiple of pi.

References

[R81]

http://planetmath.org/encyclopedia/DefinitionsInTrigonometry.html

Examples

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

inverse(argindex=1)

Returns the inverse of this function.

tanh

class sympy.functions.elementary.hyperbolic.tanh

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

• tanh(x) -> Returns the hyperbolic tangent of x

See also

sinh, cosh, atanh

inverse(argindex=1)

Returns the inverse of this function.