Functions Module

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

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))
<type 'int'>
>>> type(abs(S.NegativeOne))
<class 'sympy.core.numbers.One'>

Abs will always return a sympy object.

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

conjugate

Returns the ‘complex conjugate <http://en.wikipedia.org/wiki/Complex_conjugation>’_ 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.

>>> from sympy import conjugate, I
>>> conjugate(1 + I)
1 - I

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.

>>> 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() : find maximum values

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.

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

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

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

[1] http://en.wikipedia.org/wiki/Directed_complete_partial_order [2] http://en.wikipedia.org/wiki/Lattice_(order)

Min() : find minimum values

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

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

sign

Returns the sign of an expression, that is:
-1 if expr is negative

0 if expr is zero 1 if expr is positive

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

Return the sign of an expression, that is: -1 if expr < 0

0 if expr == 0 1 if expr > 0

Combinatorial

This module implements various combinatorial functions.

Binomial

class sympy.functions.combinatorial.factorials.binomial

Implementation of the binomial coefficient. It can be defined in two ways depending on its desired interpretation:

C(n,k) = n!/(k!(n-k)!) or C(n, k) = ff(n, k)/k!

First, in a strict combinatorial sense it defines the number of ways we can choose ‘k’ elements from a set of ‘n’ elements. In this case both arguments are nonnegative integers and binomial is computed using an efficient algorithm based on prime factorization.

The other definition is generalization for arbitrary ‘n’, however ‘k’ must also be nonnegative. This case is very useful when evaluating summations.

For the sake of convenience for negative ‘k’ this function will return zero no matter what valued is the other argument.

>>> from sympy import Symbol, Rational, binomial
>>> n = Symbol('n', integer=True)
>>> binomial(15, 8)
6435
>>> binomial(n, -1)
0
>>> [ binomial(0, i) for i in range(1)]
[1]
>>> [ binomial(1, i) for i in range(2)]
[1, 1]
>>> [ binomial(2, i) for i in range(3)]
[1, 2, 1]
>>> [ binomial(3, i) for i in range(4)]
[1, 3, 3, 1]
>>> [ binomial(4, i) for i in range(5)]
[1, 4, 6, 4, 1]
>>> binomial(Rational(5,4), 3)
-5/128
>>> binomial(n, 3)
n*(n - 2)*(n - 1)/6

Factorial

class sympy.functions.combinatorial.factorials.factorial

Implementation of factorial function over nonnegative integers. For the sake of convenience and simplicity of procedures using this function it is defined for negative integers and returns zero in this case.

The factorial is very important in combinatorics where it gives the number of ways in which ‘n’ objects can be permuted. It also arises in calculus, probability, number theory etc.

There is strict relation of factorial with gamma function. In fact n! = gamma(n+1) for nonnegative integers. Rewrite of this kind is very useful in case of combinatorial simplification.

Computation of the factorial is done using two algorithms. For small arguments naive product is evaluated. However for bigger input algorithm Prime-Swing is used. It is the fastest algorithm known and computes n! via prime factorization of special class of numbers, called here the ‘Swing Numbers’.

>>> from sympy import Symbol, factorial
>>> n = Symbol('n', integer=True)
>>> factorial(-2)
0
>>> factorial(0)
1
>>> factorial(7)
5040
>>> factorial(n)
n!
>>> factorial(2*n)
(2*n)!

FallingFactorial

class sympy.functions.combinatorial.factorials.FallingFactorial

Falling factorial (related to rising factorial) is a double valued function arising in concrete mathematics, hypergeometric functions and series expansions. It is defined by

ff(x, k) = x * (x-1) * ... * (x - k+1)

where ‘x’ can be arbitrary expression and ‘k’ is an integer. For more information check “Concrete mathematics” by Graham, pp. 66 or visit http://mathworld.wolfram.com/FallingFactorial.html page.

>>> from sympy import ff
>>> from sympy.abc import x
>>> ff(x, 0)
1
>>> ff(5, 5)
120
>>> ff(x, 5) == x*(x-1)*(x-2)*(x-3)*(x-4)
True

MultiFactorial

class sympy.functions.combinatorial.factorials.MultiFactorial

RisingFactorial

class sympy.functions.combinatorial.factorials.RisingFactorial

Rising factorial (also called Pochhammer symbol) is a double valued function arising in concrete mathematics, hypergeometric functions and series expansions. It is defined by

rf(x, k) = x * (x+1) * ... * (x + k-1)

where ‘x’ can be arbitrary expression and ‘k’ is an integer. For more information check “Concrete mathematics” by Graham, pp. 66 or visit http://mathworld.wolfram.com/RisingFactorial.html page.

>>> from sympy import rf
>>> from sympy.abc import x
>>> rf(x, 0)
1
>>> rf(1, 5)
120
>>> rf(x, 5) == x*(1 + x)*(2 + x)*(3 + x)*(4 + x)
True

Special

DiracDelta

class sympy.functions.special.delta_functions.DiracDelta

DiracDelta function, and the derivatives. DiracDelta function has the following properties: 1) diff(Heaviside(x),x) = DiracDelta(x) 2) integrate(DiracDelta(x-a)*f(x),(x,-oo,oo)) = f(a)

integrate(DiracDelta(x-a)*f(x),(x,a-e,a+e)) = f(a)
  1. DiracDelta(x) = 0, for all x != 0
  2. DiracDelta(g(x)) = Sum_i(DiracDelta(x-xi)/abs(g’(xi))) Where xis are the roots of g

Derivatives of k order of DiracDelta have the following property: 5) DiracDelta(x,k) = 0, for all x!=0

For more information, see: http://mathworld.wolfram.com/DeltaFunction.html

Heaviside

class sympy.functions.special.delta_functions.Heaviside

Heaviside Piecewise function. Heaviside function has the following properties: 1) diff(Heaviside(x),x) = DiracDelta(x)

( 0, if x<0
  1. Heaviside(x) = < [*] 1/2 if x==0

    ( 1, if x>0

[*]Regarding to the value at 0, Mathematica adopt the value H(0)=1, and Maple H(0)=undefined

I think is better to have H(0)=1/2, due to the following: integrate(DiracDelta(x),x) = Heaviside(x) integrate(DiracDelta(x),(x,-oo,oo)) = 1

and since DiracDelta is a symmetric function, integrate(DiracDelta(x),(x,0,oo)) should be 1/2 in fact, that is what maple returns.

If we take Heaviside(0)=1/2, we would have integrate(DiracDelta(x),(x,0,oo)) = Heaviside(oo)-Heaviside(0)=1-1/2= 1/2 and integrate(DiracDelta(x),(x,-oo,0)) = Heaviside(0)-Heaviside(-oo)=1/2-0= 1/2

If we consider, instead Heaviside(0)=1, we would have integrate(DiracDelta(x),(x,0,oo)) = Heaviside(oo)-Heaviside(0) = 0 and integrate(DiracDelta(x),(x,-oo,0)) = Heaviside(0)-Heaviside(-oo) = 1

For more information, see: http://mathworld.wolfram.com/HeavisideStepFunction.html

gamma

class sympy.functions.special.gamma_functions.gamma

The gamma function returns a function which passes through the integral values of the factorial function, i.e. though defined in the complex plane, when n is an integer, gamma(n) = (n - 1)!

Reference:
http://en.wikipedia.org/wiki/Gamma_function

loggamma

class sympy.functions.special.gamma_functions.loggamma

polygamma

class sympy.functions.special.gamma_functions.polygamma

The function polygamma(n, z) returns log(gamma(z)).diff(n + 1)

Reference:
http://en.wikipedia.org/wiki/Polygamma_function

uppergamma

class sympy.functions.special.gamma_functions.uppergamma

Upper incomplete gamma function