SymPy Core¶
sympify¶
sympify¶

sympy.core.sympify.
sympify
(a, locals=None, convert_xor=True, strict=False, rational=False, evaluate=None)[source]¶ Converts an arbitrary expression to a type that can be used inside SymPy.
For example, it will convert Python ints into instances of sympy.Integer, floats into instances of sympy.Float, etc. It is also able to coerce symbolic expressions which inherit from Basic. This can be useful in cooperation with SAGE.
 It currently accepts as arguments:
 any object defined in sympy
 standard numeric python types: int, long, float, Decimal
 strings (like “0.09” or “2e19”)
 booleans, including
None
(will leaveNone
unchanged)  lists, sets or tuples containing any of the above
Warning
Note that this function uses
eval
, and thus shouldn’t be used on unsanitized input.If the argument is already a type that SymPy understands, it will do nothing but return that value. This can be used at the beginning of a function to ensure you are working with the correct type.
>>> from sympy import sympify
>>> sympify(2).is_integer True >>> sympify(2).is_real True
>>> sympify(2.0).is_real True >>> sympify("2.0").is_real True >>> sympify("2e45").is_real True
If the expression could not be converted, a SympifyError is raised.
>>> sympify("x***2") Traceback (most recent call last): ... SympifyError: SympifyError: "could not parse u'x***2'"
Locals
The sympification happens with access to everything that is loaded by
from sympy import *
; anything used in a string that is not defined by that import will be converted to a symbol. In the following, thebitcount
function is treated as a symbol and theO
is interpreted as the Order object (used with series) and it raises an error when used improperly:>>> s = 'bitcount(42)' >>> sympify(s) bitcount(42) >>> sympify("O(x)") O(x) >>> sympify("O + 1") Traceback (most recent call last): ... TypeError: unbound method...
In order to have
bitcount
be recognized it can be imported into a namespace dictionary and passed as locals:>>> from sympy.core.compatibility import exec_ >>> ns = {} >>> exec_('from sympy.core.evalf import bitcount', ns) >>> sympify(s, locals=ns) 6
In order to have the
O
interpreted as a Symbol, identify it as such in the namespace dictionary. This can be done in a variety of ways; all three of the following are possibilities:>>> from sympy import Symbol >>> ns["O"] = Symbol("O") # method 1 >>> exec_('from sympy.abc import O', ns) # method 2 >>> ns.update(dict(O=Symbol("O"))) # method 3 >>> sympify("O + 1", locals=ns) O + 1
If you want all singleletter and Greekletter variables to be symbols then you can use the clashingsymbols dictionaries that have been defined there as private variables: _clash1 (singleletter variables), _clash2 (the multiletter Greek names) or _clash (both single and multiletter names that are defined in abc).
>>> from sympy.abc import _clash1 >>> _clash1 {'C': C, 'E': E, 'I': I, 'N': N, 'O': O, 'Q': Q, 'S': S} >>> sympify('I & Q', _clash1) I & Q
Strict
If the option
strict
is set toTrue
, only the types for which an explicit conversion has been defined are converted. In the other cases, a SympifyError is raised.>>> print(sympify(None)) None >>> sympify(None, strict=True) Traceback (most recent call last): ... SympifyError: SympifyError: None
Evaluation
If the option
evaluate
is set toFalse
, then arithmetic and operators will be converted into their SymPy equivalents and theevaluate=False
option will be added. NestedAdd
orMul
will be denested first. This is done via an AST transformation that replaces operators with their SymPy equivalents, so if an operand redefines any of those operations, the redefined operators will not be used.>>> sympify('2**2 / 3 + 5') 19/3 >>> sympify('2**2 / 3 + 5', evaluate=False) 2**2/3 + 5
Extending
To extend
sympify
to convert custom objects (not derived fromBasic
), just define a_sympy_
method to your class. You can do that even to classes that you do not own by subclassing or adding the method at runtime.>>> from sympy import Matrix >>> class MyList1(object): ... def __iter__(self): ... yield 1 ... yield 2 ... return ... def __getitem__(self, i): return list(self)[i] ... def _sympy_(self): return Matrix(self) >>> sympify(MyList1()) Matrix([ [1], [2]])
If you do not have control over the class definition you could also use the
converter
global dictionary. The key is the class and the value is a function that takes a single argument and returns the desired SymPy object, e.g.converter[MyList] = lambda x: Matrix(x)
.>>> class MyList2(object): # XXX Do not do this if you control the class! ... def __iter__(self): # Use _sympy_! ... yield 1 ... yield 2 ... return ... def __getitem__(self, i): return list(self)[i] >>> from sympy.core.sympify import converter >>> converter[MyList2] = lambda x: Matrix(x) >>> sympify(MyList2()) Matrix([ [1], [2]])
Notes
Sometimes autosimplification during sympification results in expressions that are very different in structure than what was entered. Until such autosimplification is no longer done, the
kernS
function might be of some use. In the example below you can see how an expression reduces to 1 by autosimplification, but does not do so whenkernS
is used.>>> from sympy.core.sympify import kernS >>> from sympy.abc import x >>> 2*((x + 1/x)/(x*(x  1/x)**2)  1/(x*(x  1/x)))  1 1 >>> s = '2*((x + 1/x)/(x*(x  1/x)**2)  1/(x*(x  1/x)))  1' >>> sympify(s) 1 >>> kernS(s) 2*((x + 1/x)/(x*(x  1/x)**2)  1/(x*(x  1/x)))  1
assumptions¶
This module contains the machinery handling assumptions.
All symbolic objects have assumption attributes that can be accessed via .is_<assumption name> attribute.
Assumptions determine certain properties of symbolic objects and can have 3 possible values: True, False, None. True is returned if the object has the property and False is returned if it doesn’t or can’t (i.e. doesn’t make sense):
>>> from sympy import I
>>> I.is_algebraic
True
>>> I.is_real
False
>>> I.is_prime
False
When the property cannot be determined (or when a method is not implemented) None will be returned, e.g. a generic symbol, x, may or may not be positive so a value of None is returned for x.is_positive.
By default, all symbolic values are in the largest set in the given context without specifying the property. For example, a symbol that has a property being integer, is also real, complex, etc.
Here follows a list of possible assumption names:
 commutative
 object commutes with any other object with respect to multiplication operation.
 complex
 object can have only values from the set of complex numbers.
 imaginary
 object value is a number that can be written as a real
number multiplied by the imaginary unit
I
. See [R74]. Please note, that0
is not considered to be an imaginary number, see issue #7649.  real
 object can have only values from the set of real numbers.
 integer
 object can have only values from the set of integers.
 odd
 even
 object can have only values from the set of odd (even) integers [R73].
 prime
 object is a natural number greater than
1
that has no positive divisors other than1
and itself. See [R77].  composite
 object is a positive integer that has at least one positive
divisor other than
1
or the number itself. See [R75].  zero
 object has the value of
0
.  nonzero
 object is a real number that is not zero.
 rational
 object can have only values from the set of rationals.
 algebraic
 object can have only values from the set of algebraic numbers [11].
 transcendental
 object can have only values from the set of transcendental numbers [10].
 irrational
 object value cannot be represented exactly by Rational, see [R76].
 finite
 infinite
 object absolute value is bounded (arbitrarily large). See [R78], [R79], [R80].
 negative
 nonnegative
 object can have only negative (nonnegative) values [R72].
 positive
 nonpositive
 object can have only positive (only nonpositive) values.
 hermitian
 antihermitian
 object belongs to the field of hermitian (antihermitian) operators.
Examples¶
>>> from sympy import Symbol
>>> x = Symbol('x', real=True); x
x
>>> x.is_real
True
>>> x.is_complex
True
See Also¶
Notes¶
Assumption values are stored in obj._assumptions dictionary or are returned by getter methods (with property decorators) or are attributes of objects/classes.
References¶
[R72]  https://en.wikipedia.org/wiki/Negative_number 
[R73]  https://en.wikipedia.org/wiki/Parity_%28mathematics%29 
[R74]  https://en.wikipedia.org/wiki/Imaginary_number 
[R75]  https://en.wikipedia.org/wiki/Composite_number 
[R76]  https://en.wikipedia.org/wiki/Irrational_number 
[R77]  https://en.wikipedia.org/wiki/Prime_number 
[R78]  https://en.wikipedia.org/wiki/Finite 
[R79]  https://docs.python.org/3/library/math.html#math.isfinite 
[R80]  http://docs.scipy.org/doc/numpy/reference/generated/numpy.isfinite.html 
[10]  https://en.wikipedia.org/wiki/Transcendental_number 
[11]  https://en.wikipedia.org/wiki/Algebraic_number 
basic¶
Basic¶

class
sympy.core.basic.
Basic
[source]¶ Base class for all objects in SymPy.
Conventions:
Always use
.args
, when accessing parameters of some instance:>>> from sympy import cot >>> from sympy.abc import x, y
>>> cot(x).args (x,)
>>> cot(x).args[0] x
>>> (x*y).args (x, y)
>>> (x*y).args[1] y
Never use internal methods or variables (the ones prefixed with
_
):>>> cot(x)._args # do not use this, use cot(x).args instead (x,)

args
¶ Returns a tuple of arguments of ‘self’.
Examples
>>> from sympy import cot >>> from sympy.abc import x, y
>>> cot(x).args (x,)
>>> cot(x).args[0] x
>>> (x*y).args (x, y)
>>> (x*y).args[1] y
Notes
Never use self._args, always use self.args. Only use _args in __new__ when creating a new function. Don’t override .args() from Basic (so that it’s easy to change the interface in the future if needed).

as_content_primitive
(radical=False, clear=True)[source]¶ A stub to allow Basic args (like Tuple) to be skipped when computing the content and primitive components of an expression.

as_dummy
()[source]¶ Return the expression with any objects having structurally bound symbols replaced with unique, canonical symbols within the object in which they appear and having only the default assumption for commutativity being True.
Examples
>>> from sympy import Integral, Symbol >>> from sympy.abc import x, y >>> r = Symbol('r', real=True) >>> Integral(r, (r, x)).as_dummy() Integral(_0, (_0, x)) >>> _.variables[0].is_real is None True
Notes
Any object that has structural dummy variables should have a property, \(bound_symbols\) that returns a list of structural dummy symbols of the object itself.
Lambda and Subs have bound symbols, but because of how they are cached, they already compare the same regardless of their bound symbols:
>>> from sympy import Lambda >>> Lambda(x, x + 1) == Lambda(y, y + 1) True

as_poly
(*gens, **args)[source]¶ Converts
self
to a polynomial or returnsNone
.>>> from sympy import sin >>> from sympy.abc import x, y
>>> print((x**2 + x*y).as_poly()) Poly(x**2 + x*y, x, y, domain='ZZ')
>>> print((x**2 + x*y).as_poly(x, y)) Poly(x**2 + x*y, x, y, domain='ZZ')
>>> print((x**2 + sin(y)).as_poly(x, y)) None

assumptions0
¶ Return object \(type\) assumptions.
For example:
Symbol(‘x’, real=True) Symbol(‘x’, integer=True)are different objects. In other words, besides Python type (Symbol in this case), the initial assumptions are also forming their typeinfo.
Examples
>>> from sympy import Symbol >>> from sympy.abc import x >>> x.assumptions0 {'commutative': True} >>> x = Symbol("x", positive=True) >>> x.assumptions0 {'commutative': True, 'complex': True, 'hermitian': True, 'imaginary': False, 'negative': False, 'nonnegative': True, 'nonpositive': False, 'nonzero': True, 'positive': True, 'real': True, 'zero': False}

atoms
(*types)[source]¶ Returns the atoms that form the current object.
By default, only objects that are truly atomic and can’t be divided into smaller pieces are returned: symbols, numbers, and number symbols like I and pi. It is possible to request atoms of any type, however, as demonstrated below.
Examples
>>> from sympy import I, pi, sin >>> from sympy.abc import x, y >>> (1 + x + 2*sin(y + I*pi)).atoms() {1, 2, I, pi, x, y}
If one or more types are given, the results will contain only those types of atoms.
>>> from sympy import Number, NumberSymbol, Symbol >>> (1 + x + 2*sin(y + I*pi)).atoms(Symbol) {x, y}
>>> (1 + x + 2*sin(y + I*pi)).atoms(Number) {1, 2}
>>> (1 + x + 2*sin(y + I*pi)).atoms(Number, NumberSymbol) {1, 2, pi}
>>> (1 + x + 2*sin(y + I*pi)).atoms(Number, NumberSymbol, I) {1, 2, I, pi}
Note that I (imaginary unit) and zoo (complex infinity) are special types of number symbols and are not part of the NumberSymbol class.
The type can be given implicitly, too:
>>> (1 + x + 2*sin(y + I*pi)).atoms(x) # x is a Symbol {x, y}
Be careful to check your assumptions when using the implicit option since
S(1).is_Integer = True
buttype(S(1))
isOne
, a special type of sympy atom, whiletype(S(2))
is typeInteger
and will find all integers in an expression:>>> from sympy import S >>> (1 + x + 2*sin(y + I*pi)).atoms(S(1)) {1}
>>> (1 + x + 2*sin(y + I*pi)).atoms(S(2)) {1, 2}
Finally, arguments to atoms() can select more than atomic atoms: any sympy type (loaded in core/__init__.py) can be listed as an argument and those types of “atoms” as found in scanning the arguments of the expression recursively:
>>> from sympy import Function, Mul >>> from sympy.core.function import AppliedUndef >>> f = Function('f') >>> (1 + f(x) + 2*sin(y + I*pi)).atoms(Function) {f(x), sin(y + I*pi)} >>> (1 + f(x) + 2*sin(y + I*pi)).atoms(AppliedUndef) {f(x)}
>>> (1 + x + 2*sin(y + I*pi)).atoms(Mul) {I*pi, 2*sin(y + I*pi)}

canonical_variables
¶ Return a dictionary mapping any variable defined in
self.bound_symbols
to Symbols that do not clash with any existing symbol in the expression.Examples
>>> from sympy import Lambda >>> from sympy.abc import x >>> Lambda(x, 2*x).canonical_variables {x: _0}

compare
(other)[source]¶ Return 1, 0, 1 if the object is smaller, equal, or greater than other.
Not in the mathematical sense. If the object is of a different type from the “other” then their classes are ordered according to the sorted_classes list.
Examples
>>> from sympy.abc import x, y >>> x.compare(y) 1 >>> x.compare(x) 0 >>> y.compare(x) 1

doit
(**hints)[source]¶ Evaluate objects that are not evaluated by default like limits, integrals, sums and products. All objects of this kind will be evaluated recursively, unless some species were excluded via ‘hints’ or unless the ‘deep’ hint was set to ‘False’.
>>> from sympy import Integral >>> from sympy.abc import x
>>> 2*Integral(x, x) 2*Integral(x, x)
>>> (2*Integral(x, x)).doit() x**2
>>> (2*Integral(x, x)).doit(deep=False) 2*Integral(x, x)

dummy_eq
(other, symbol=None)[source]¶ Compare two expressions and handle dummy symbols.
Examples
>>> from sympy import Dummy >>> from sympy.abc import x, y
>>> u = Dummy('u')
>>> (u**2 + 1).dummy_eq(x**2 + 1) True >>> (u**2 + 1) == (x**2 + 1) False
>>> (u**2 + y).dummy_eq(x**2 + y, x) True >>> (u**2 + y).dummy_eq(x**2 + y, y) False

free_symbols
¶ Return from the atoms of self those which are free symbols.
For most expressions, all symbols are free symbols. For some classes this is not true. e.g. Integrals use Symbols for the dummy variables which are bound variables, so Integral has a method to return all symbols except those. Derivative keeps track of symbols with respect to which it will perform a derivative; those are bound variables, too, so it has its own free_symbols method.
Any other method that uses bound variables should implement a free_symbols method.

classmethod
fromiter
(args, **assumptions)[source]¶ Create a new object from an iterable.
This is a convenience function that allows one to create objects from any iterable, without having to convert to a list or tuple first.
Examples
>>> from sympy import Tuple >>> Tuple.fromiter(i for i in range(5)) (0, 1, 2, 3, 4)

func
¶ The toplevel function in an expression.
The following should hold for all objects:
>> x == x.func(*x.args)
Examples
>>> from sympy.abc import x >>> a = 2*x >>> a.func <class 'sympy.core.mul.Mul'> >>> a.args (2, x) >>> a.func(*a.args) 2*x >>> a == a.func(*a.args) True

has
(*patterns)[source]¶ Test whether any subexpression matches any of the patterns.
Examples
>>> from sympy import sin >>> from sympy.abc import x, y, z >>> (x**2 + sin(x*y)).has(z) False >>> (x**2 + sin(x*y)).has(x, y, z) True >>> x.has(x) True
Note
has
is a structural algorithm with no knowledge of mathematics. Consider the following halfopen interval:>>> from sympy.sets import Interval >>> i = Interval.Lopen(0, 5); i Interval.Lopen(0, 5) >>> i.args (0, 5, True, False) >>> i.has(4) # there is no "4" in the arguments False >>> i.has(0) # there *is* a "0" in the arguments True
Instead, use
contains
to determine whether a number is in the interval or not:>>> i.contains(4) True >>> i.contains(0) False
Note that
expr.has(*patterns)
is exactly equivalent toany(expr.has(p) for p in patterns)
. In particular,False
is returned when the list of patterns is empty.>>> x.has() False

is_comparable
¶ Return True if self can be computed to a real number (or already is a real number) with precision, else False.
Examples
>>> from sympy import exp_polar, pi, I >>> (I*exp_polar(I*pi/2)).is_comparable True >>> (I*exp_polar(I*pi*2)).is_comparable False
A False result does not mean that \(self\) cannot be rewritten into a form that would be comparable. For example, the difference computed below is zero but without simplification it does not evaluate to a zero with precision:
>>> e = 2**pi*(1 + 2**pi) >>> dif = e  e.expand() >>> dif.is_comparable False >>> dif.n(2)._prec 1

match
(pattern, old=False)[source]¶ Pattern matching.
Wild symbols match all.
Return
None
when expression (self) does not match with pattern. Otherwise return a dictionary such that:pattern.xreplace(self.match(pattern)) == self
Examples
>>> from sympy import Wild >>> from sympy.abc import x, y >>> p = Wild("p") >>> q = Wild("q") >>> r = Wild("r") >>> e = (x+y)**(x+y) >>> e.match(p**p) {p_: x + y} >>> e.match(p**q) {p_: x + y, q_: x + y} >>> e = (2*x)**2 >>> e.match(p*q**r) {p_: 4, q_: x, r_: 2} >>> (p*q**r).xreplace(e.match(p*q**r)) 4*x**2
The
old
flag will give the oldstyle pattern matching where expressions and patterns are essentially solved to give the match. Both of the following give None unlessold=True
:>>> (x  2).match(p  x, old=True) {p_: 2*x  2} >>> (2/x).match(p*x, old=True) {p_: 2/x**2}

matches
(expr, repl_dict={}, old=False)[source]¶ Helper method for match() that looks for a match between Wild symbols in self and expressions in expr.
Examples
>>> from sympy import symbols, Wild, Basic >>> a, b, c = symbols('a b c') >>> x = Wild('x') >>> Basic(a + x, x).matches(Basic(a + b, c)) is None True >>> Basic(a + x, x).matches(Basic(a + b + c, b + c)) {x_: b + c}

rcall
(*args)[source]¶ Apply on the argument recursively through the expression tree.
This method is used to simulate a common abuse of notation for operators. For instance in SymPy the the following will not work:
(x+Lambda(y, 2*y))(z) == x+2*z
,however you can use
>>> from sympy import Lambda >>> from sympy.abc import x, y, z >>> (x + Lambda(y, 2*y)).rcall(z) x + 2*z

replace
(query, value, map=False, simultaneous=True, exact=False)[source]¶ Replace matching subexpressions of
self
withvalue
.If
map = True
then also return the mapping {old: new} whereold
was a subexpression found with query andnew
is the replacement value for it. If the expression itself doesn’t match the query, then the returned value will beself.xreplace(map)
otherwise it should beself.subs(ordered(map.items()))
.Traverses an expression tree and performs replacement of matching subexpressions from the bottom to the top of the tree. The default approach is to do the replacement in a simultaneous fashion so changes made are targeted only once. If this is not desired or causes problems,
simultaneous
can be set to False. In addition, if an expression containing more than one Wild symbol is being used to match subexpressions and theexact
flag is True, then the match will only succeed if nonzero values are received for each Wild that appears in the match pattern.The list of possible combinations of queries and replacement values is listed below:
Examples
Initial setup
>>> from sympy import log, sin, cos, tan, Wild, Mul, Add >>> from sympy.abc import x, y >>> f = log(sin(x)) + tan(sin(x**2))
 1.1. type > type
obj.replace(type, newtype)
When object of type
type
is found, replace it with the result of passing its argument(s) tonewtype
.>>> f.replace(sin, cos) log(cos(x)) + tan(cos(x**2)) >>> sin(x).replace(sin, cos, map=True) (cos(x), {sin(x): cos(x)}) >>> (x*y).replace(Mul, Add) x + y
 1.2. type > func
obj.replace(type, func)
When object of type
type
is found, applyfunc
to its argument(s).func
must be written to handle the number of arguments oftype
.>>> f.replace(sin, lambda arg: sin(2*arg)) log(sin(2*x)) + tan(sin(2*x**2)) >>> (x*y).replace(Mul, lambda *args: sin(2*Mul(*args))) sin(2*x*y)
 2.1. pattern > expr
obj.replace(pattern(wild), expr(wild))
Replace subexpressions matching
pattern
with the expression written in terms of the Wild symbols inpattern
.>>> a = Wild('a') >>> f.replace(sin(a), tan(a)) log(tan(x)) + tan(tan(x**2)) >>> f.replace(sin(a), tan(a/2)) log(tan(x/2)) + tan(tan(x**2/2)) >>> f.replace(sin(a), a) log(x) + tan(x**2) >>> (x*y).replace(a*x, a) y
When the default value of False is used with patterns that have more than one Wild symbol, nonintuitive results may be obtained:
>>> b = Wild('b') >>> (2*x).replace(a*x + b, b  a) 2/x
For this reason, the
exact
option can be used to make the replacement only when the match gives nonzero values for all Wild symbols:>>> (2*x + y).replace(a*x + b, b  a, exact=True) y  2 >>> (2*x).replace(a*x + b, b  a, exact=True) 2*x
 2.2. pattern > func
obj.replace(pattern(wild), lambda wild: expr(wild))
All behavior is the same as in 2.1 but now a function in terms of pattern variables is used rather than an expression:
>>> f.replace(sin(a), lambda a: sin(2*a)) log(sin(2*x)) + tan(sin(2*x**2))
 3.1. func > func
obj.replace(filter, func)
Replace subexpression
e
withfunc(e)
iffilter(e)
is True.>>> g = 2*sin(x**3) >>> g.replace(lambda expr: expr.is_Number, lambda expr: expr**2) 4*sin(x**9)
The expression itself is also targeted by the query but is done in such a fashion that changes are not made twice.
>>> e = x*(x*y + 1) >>> e.replace(lambda x: x.is_Mul, lambda x: 2*x) 2*x*(2*x*y + 1)

rewrite
(*args, **hints)[source]¶ Rewrite functions in terms of other functions.
Rewrites expression containing applications of functions of one kind in terms of functions of different kind. For example you can rewrite trigonometric functions as complex exponentials or combinatorial functions as gamma function.
As a pattern this function accepts a list of functions to to rewrite (instances of DefinedFunction class). As rule you can use string or a destination function instance (in this case rewrite() will use the str() function).
There is also the possibility to pass hints on how to rewrite the given expressions. For now there is only one such hint defined called ‘deep’. When ‘deep’ is set to False it will forbid functions to rewrite their contents.
Examples
>>> from sympy import sin, exp >>> from sympy.abc import x
Unspecified pattern:
>>> sin(x).rewrite(exp) I*(exp(I*x)  exp(I*x))/2
Pattern as a single function:
>>> sin(x).rewrite(sin, exp) I*(exp(I*x)  exp(I*x))/2
Pattern as a list of functions:
>>> sin(x).rewrite([sin, ], exp) I*(exp(I*x)  exp(I*x))/2

sort_key
(order=None)[source]¶ Return a sort key.
Examples
>>> from sympy.core import S, I
>>> sorted([S(1)/2, I, I], key=lambda x: x.sort_key()) [1/2, I, I]
>>> S("[x, 1/x, 1/x**2, x**2, x**(1/2), x**(1/4), x**(3/2)]") [x, 1/x, x**(2), x**2, sqrt(x), x**(1/4), x**(3/2)] >>> sorted(_, key=lambda x: x.sort_key()) [x**(2), 1/x, x**(1/4), sqrt(x), x, x**(3/2), x**2]

subs
(*args, **kwargs)[source]¶ Substitutes old for new in an expression after sympifying args.
 \(args\) is either:
 two arguments, e.g. foo.subs(old, new)
 one iterable argument, e.g. foo.subs(iterable). The iterable may be
 o an iterable container with (old, new) pairs. In this case the
 replacements are processed in the order given with successive patterns possibly affecting replacements already made.
 o a dict or set whose key/value items correspond to old/new pairs.
 In this case the old/new pairs will be sorted by op count and in case of a tie, by number of args and the default_sort_key. The resulting sorted list is then processed as an iterable container (see previous).
If the keyword
simultaneous
is True, the subexpressions will not be evaluated until all the substitutions have been made.Examples
>>> from sympy import pi, exp, limit, oo >>> from sympy.abc import x, y >>> (1 + x*y).subs(x, pi) pi*y + 1 >>> (1 + x*y).subs({x:pi, y:2}) 1 + 2*pi >>> (1 + x*y).subs([(x, pi), (y, 2)]) 1 + 2*pi >>> reps = [(y, x**2), (x, 2)] >>> (x + y).subs(reps) 6 >>> (x + y).subs(reversed(reps)) x**2 + 2
>>> (x**2 + x**4).subs(x**2, y) y**2 + y
To replace only the x**2 but not the x**4, use xreplace:
>>> (x**2 + x**4).xreplace({x**2: y}) x**4 + y
To delay evaluation until all substitutions have been made, set the keyword
simultaneous
to True:>>> (x/y).subs([(x, 0), (y, 0)]) 0 >>> (x/y).subs([(x, 0), (y, 0)], simultaneous=True) nan
This has the added feature of not allowing subsequent substitutions to affect those already made:
>>> ((x + y)/y).subs({x + y: y, y: x + y}) 1 >>> ((x + y)/y).subs({x + y: y, y: x + y}, simultaneous=True) y/(x + y)
In order to obtain a canonical result, unordered iterables are sorted by count_op length, number of arguments and by the default_sort_key to break any ties. All other iterables are left unsorted.
>>> from sympy import sqrt, sin, cos >>> from sympy.abc import a, b, c, d, e
>>> A = (sqrt(sin(2*x)), a) >>> B = (sin(2*x), b) >>> C = (cos(2*x), c) >>> D = (x, d) >>> E = (exp(x), e)
>>> expr = sqrt(sin(2*x))*sin(exp(x)*x)*cos(2*x) + sin(2*x)
>>> expr.subs(dict([A, B, C, D, E])) a*c*sin(d*e) + b
The resulting expression represents a literal replacement of the old arguments with the new arguments. This may not reflect the limiting behavior of the expression:
>>> (x**3  3*x).subs({x: oo}) nan
>>> limit(x**3  3*x, x, oo) oo
If the substitution will be followed by numerical evaluation, it is better to pass the substitution to evalf as
>>> (1/x).evalf(subs={x: 3.0}, n=21) 0.333333333333333333333
rather than
>>> (1/x).subs({x: 3.0}).evalf(21) 0.333333333333333314830
as the former will ensure that the desired level of precision is obtained.

xreplace
(rule)[source]¶ Replace occurrences of objects within the expression.
Parameters: rule : dictlike
Expresses a replacement rule
Returns: xreplace : the result of the replacement
Examples
>>> from sympy import symbols, pi, exp >>> x, y, z = symbols('x y z') >>> (1 + x*y).xreplace({x: pi}) pi*y + 1 >>> (1 + x*y).xreplace({x: pi, y: 2}) 1 + 2*pi
Replacements occur only if an entire node in the expression tree is matched:
>>> (x*y + z).xreplace({x*y: pi}) z + pi >>> (x*y*z).xreplace({x*y: pi}) x*y*z >>> (2*x).xreplace({2*x: y, x: z}) y >>> (2*2*x).xreplace({2*x: y, x: z}) 4*z >>> (x + y + 2).xreplace({x + y: 2}) x + y + 2 >>> (x + 2 + exp(x + 2)).xreplace({x + 2: y}) x + exp(y) + 2
xreplace doesn’t differentiate between free and bound symbols. In the following, subs(x, y) would not change x since it is a bound symbol, but xreplace does:
>>> from sympy import Integral >>> Integral(x, (x, 1, 2*x)).xreplace({x: y}) Integral(y, (y, 1, 2*y))
Trying to replace x with an expression raises an error:
>>> Integral(x, (x, 1, 2*x)).xreplace({x: 2*y}) # doctest: +SKIP ValueError: Invalid limits given: ((2*y, 1, 4*y),)
core¶
singleton¶
S¶

class
sympy.core.singleton.
SingletonRegistry
[source]¶ The registry for the singleton classes (accessible as
S
).This class serves as two separate things.
The first thing it is is the
SingletonRegistry
. Several classes in SymPy appear so often that they are singletonized, that is, using some metaprogramming they are made so that they can only be instantiated once (see thesympy.core.singleton.Singleton
class for details). For instance, every time you createInteger(0)
, this will return the same instance,sympy.core.numbers.Zero
. All singleton instances are attributes of theS
object, soInteger(0)
can also be accessed asS.Zero
.Singletonization offers two advantages: it saves memory, and it allows fast comparison. It saves memory because no matter how many times the singletonized objects appear in expressions in memory, they all point to the same single instance in memory. The fast comparison comes from the fact that you can use
is
to compare exact instances in Python (usually, you need to use==
to compare things).is
compares objects by memory address, and is very fast. For instance>>> from sympy import S, Integer >>> a = Integer(0) >>> a is S.Zero True
For the most part, the fact that certain objects are singletonized is an implementation detail that users shouldn’t need to worry about. In SymPy library code,
is
comparison is often used for performance purposes The primary advantage ofS
for end users is the convenient access to certain instances that are otherwise difficult to type, likeS.Half
(instead ofRational(1, 2)
).When using
is
comparison, make sure the argument is sympified. For instance,>>> 0 is S.Zero False
This problem is not an issue when using
==
, which is recommended for most usecases:>>> 0 == S.Zero True
The second thing
S
is is a shortcut forsympy.core.sympify.sympify()
.sympy.core.sympify.sympify()
is the function that converts Python objects such asint(1)
into SymPy objects such asInteger(1)
. It also converts the string form of an expression into a SymPy expression, likesympify("x**2")
>Symbol("x")**2
.S(1)
is the same thing assympify(1)
(basically,S.__call__
has been defined to callsympify
).This is for convenience, since
S
is a single letter. It’s mostly useful for defining rational numbers. Consider an expression likex + 1/2
. If you enter this directly in Python, it will evaluate the1/2
and give0.5
(or just0
in Python 2, because of integer division), because both arguments are ints (see also Two Final Notes: ^ and /). However, in SymPy, you usually want the quotient of two integers to give an exact rational number. The way Python’s evaluation works, at least one side of an operator needs to be a SymPy object for the SymPy evaluation to take over. You could write this asx + Rational(1, 2)
, but this is a lot more typing. A shorter version isx + S(1)/2
. SinceS(1)
returnsInteger(1)
, the division will return aRational
type, since it will callInteger.__div__
, which knows how to return aRational
.
expr¶
Expr¶

class
sympy.core.expr.
Expr
[source]¶ Base class for algebraic expressions.
Everything that requires arithmetic operations to be defined should subclass this class, instead of Basic (which should be used only for argument storage and expression manipulation, i.e. pattern matching, substitutions, etc).
See also

args_cnc
(cset=False, warn=True, split_1=True)[source]¶ Return [commutative factors, noncommutative factors] of self.
self is treated as a Mul and the ordering of the factors is maintained. If
cset
is True the commutative factors will be returned in a set. If there were repeated factors (as may happen with an unevaluated Mul) then an error will be raised unless it is explicitly suppressed by settingwarn
to False.Note: 1 is always separated from a Number unless split_1 is False.
>>> from sympy import symbols, oo >>> A, B = symbols('A B', commutative=0) >>> x, y = symbols('x y') >>> (2*x*y).args_cnc() [[1, 2, x, y], []] >>> (2.5*x).args_cnc() [[1, 2.5, x], []] >>> (2*x*A*B*y).args_cnc() [[1, 2, x, y], [A, B]] >>> (2*x*A*B*y).args_cnc(split_1=False) [[2, x, y], [A, B]] >>> (2*x*y).args_cnc(cset=True) [{1, 2, x, y}, []]
The arg is always treated as a Mul:
>>> (2 + x + A).args_cnc() [[], [x  2 + A]] >>> (oo).args_cnc() # oo is a singleton [[1, oo], []]

as_coeff_add
(*deps)[source]¶ Return the tuple (c, args) where self is written as an Add,
a
.c should be a Rational added to any terms of the Add that are independent of deps.
args should be a tuple of all other terms of
a
; args is empty if self is a Number or if self is independent of deps (when given).This should be used when you don’t know if self is an Add or not but you want to treat self as an Add or if you want to process the individual arguments of the tail of self as an Add.
 if you know self is an Add and want only the head, use self.args[0];
 if you don’t want to process the arguments of the tail but need the tail then use self.as_two_terms() which gives the head and tail.
 if you want to split self into an independent and dependent parts
use
self.as_independent(*deps)
>>> from sympy import S >>> from sympy.abc import x, y >>> (S(3)).as_coeff_add() (3, ()) >>> (3 + x).as_coeff_add() (3, (x,)) >>> (3 + x + y).as_coeff_add(x) (y + 3, (x,)) >>> (3 + y).as_coeff_add(x) (y + 3, ())

as_coeff_mul
(*deps, **kwargs)[source]¶ Return the tuple (c, args) where self is written as a Mul,
m
.c should be a Rational multiplied by any factors of the Mul that are independent of deps.
args should be a tuple of all other factors of m; args is empty if self is a Number or if self is independent of deps (when given).
This should be used when you don’t know if self is a Mul or not but you want to treat self as a Mul or if you want to process the individual arguments of the tail of self as a Mul.
 if you know self is a Mul and want only the head, use self.args[0];
 if you don’t want to process the arguments of the tail but need the tail then use self.as_two_terms() which gives the head and tail;
 if you want to split self into an independent and dependent parts
use
self.as_independent(*deps)
>>> from sympy import S >>> from sympy.abc import x, y >>> (S(3)).as_coeff_mul() (3, ()) >>> (3*x*y).as_coeff_mul() (3, (x, y)) >>> (3*x*y).as_coeff_mul(x) (3*y, (x,)) >>> (3*y).as_coeff_mul(x) (3*y, ())

as_coefficient
(expr)[source]¶ Extracts symbolic coefficient at the given expression. In other words, this functions separates ‘self’ into the product of ‘expr’ and ‘expr’free coefficient. If such separation is not possible it will return None.
Examples
>>> from sympy import E, pi, sin, I, Poly >>> from sympy.abc import x
>>> E.as_coefficient(E) 1 >>> (2*E).as_coefficient(E) 2 >>> (2*sin(E)*E).as_coefficient(E)
Two terms have E in them so a sum is returned. (If one were desiring the coefficient of the term exactly matching E then the constant from the returned expression could be selected. Or, for greater precision, a method of Poly can be used to indicate the desired term from which the coefficient is desired.)
>>> (2*E + x*E).as_coefficient(E) x + 2 >>> _.args[0] # just want the exact match 2 >>> p = Poly(2*E + x*E); p Poly(x*E + 2*E, x, E, domain='ZZ') >>> p.coeff_monomial(E) 2 >>> p.nth(0, 1) 2
Since the following cannot be written as a product containing E as a factor, None is returned. (If the coefficient
2*x
is desired then thecoeff
method should be used.)>>> (2*E*x + x).as_coefficient(E) >>> (2*E*x + x).coeff(E) 2*x
>>> (E*(x + 1) + x).as_coefficient(E)
>>> (2*pi*I).as_coefficient(pi*I) 2 >>> (2*I).as_coefficient(pi*I)
See also
coeff
 return sum of terms have a given factor
as_coeff_Add
 separate the additive constant from an expression
as_coeff_Mul
 separate the multiplicative constant from an expression
as_independent
 separate xdependent terms/factors from others
sympy.polys.polytools.coeff_monomial
 efficiently find the single coefficient of a monomial in Poly
sympy.polys.polytools.nth
 like coeff_monomial but powers of monomial terms are used

as_coefficients_dict
()[source]¶ Return a dictionary mapping terms to their Rational coefficient. Since the dictionary is a defaultdict, inquiries about terms which were not present will return a coefficient of 0. If an expression is not an Add it is considered to have a single term.
Examples
>>> from sympy.abc import a, x >>> (3*x + a*x + 4).as_coefficients_dict() {1: 4, x: 3, a*x: 1} >>> _[a] 0 >>> (3*a*x).as_coefficients_dict() {a*x: 3}

as_content_primitive
(radical=False, clear=True)[source]¶ This method should recursively remove a Rational from all arguments and return that (content) and the new self (primitive). The content should always be positive and
Mul(*foo.as_content_primitive()) == foo
. The primitive need not be in canonical form and should try to preserve the underlying structure if possible (i.e. expand_mul should not be applied to self).Examples
>>> from sympy import sqrt >>> from sympy.abc import x, y, z
>>> eq = 2 + 2*x + 2*y*(3 + 3*y)
The as_content_primitive function is recursive and retains structure:
>>> eq.as_content_primitive() (2, x + 3*y*(y + 1) + 1)
Integer powers will have Rationals extracted from the base:
>>> ((2 + 6*x)**2).as_content_primitive() (4, (3*x + 1)**2) >>> ((2 + 6*x)**(2*y)).as_content_primitive() (1, (2*(3*x + 1))**(2*y))
Terms may end up joining once their as_content_primitives are added:
>>> ((5*(x*(1 + y)) + 2*x*(3 + 3*y))).as_content_primitive() (11, x*(y + 1)) >>> ((3*(x*(1 + y)) + 2*x*(3 + 3*y))).as_content_primitive() (9, x*(y + 1)) >>> ((3*(z*(1 + y)) + 2.0*x*(3 + 3*y))).as_content_primitive() (1, 6.0*x*(y + 1) + 3*z*(y + 1)) >>> ((5*(x*(1 + y)) + 2*x*(3 + 3*y))**2).as_content_primitive() (121, x**2*(y + 1)**2) >>> ((5*(x*(1 + y)) + 2.0*x*(3 + 3*y))**2).as_content_primitive() (1, 121.0*x**2*(y + 1)**2)
Radical content can also be factored out of the primitive:
>>> (2*sqrt(2) + 4*sqrt(10)).as_content_primitive(radical=True) (2, sqrt(2)*(1 + 2*sqrt(5)))
If clear=False (default is True) then content will not be removed from an Add if it can be distributed to leave one or more terms with integer coefficients.
>>> (x/2 + y).as_content_primitive() (1/2, x + 2*y) >>> (x/2 + y).as_content_primitive(clear=False) (1, x/2 + y)

as_expr
(*gens)[source]¶ Convert a polynomial to a SymPy expression.
Examples
>>> from sympy import sin >>> from sympy.abc import x, y
>>> f = (x**2 + x*y).as_poly(x, y) >>> f.as_expr() x**2 + x*y
>>> sin(x).as_expr() sin(x)

as_independent
(*deps, **hint)[source]¶ A mostly naive separation of a Mul or Add into arguments that are not are dependent on deps. To obtain as complete a separation of variables as possible, use a separation method first, e.g.:
 separatevars() to change Mul, Add and Pow (including exp) into Mul
 .expand(mul=True) to change Add or Mul into Add
 .expand(log=True) to change log expr into an Add
The only nonnaive thing that is done here is to respect noncommutative ordering of variables and to always return (0, 0) for \(self\) of zero regardless of hints.
For nonzero \(self\), the returned tuple (i, d) has the following interpretation:
 i will has no variable that appears in deps
 d will either have terms that contain variables that are in deps, or be equal to 0 (when self is an Add) or 1 (when self is a Mul)
 if self is an Add then self = i + d
 if self is a Mul then self = i*d
 otherwise (self, S.One) or (S.One, self) is returned.
To force the expression to be treated as an Add, use the hint as_Add=True
Examples
– self is an Add
>>> from sympy import sin, cos, exp >>> from sympy.abc import x, y, z
>>> (x + x*y).as_independent(x) (0, x*y + x) >>> (x + x*y).as_independent(y) (x, x*y) >>> (2*x*sin(x) + y + x + z).as_independent(x) (y + z, 2*x*sin(x) + x) >>> (2*x*sin(x) + y + x + z).as_independent(x, y) (z, 2*x*sin(x) + x + y)
– self is a Mul
>>> (x*sin(x)*cos(y)).as_independent(x) (cos(y), x*sin(x))
noncommutative terms cannot always be separated out when self is a Mul
>>> from sympy import symbols >>> n1, n2, n3 = symbols('n1 n2 n3', commutative=False) >>> (n1 + n1*n2).as_independent(n2) (n1, n1*n2) >>> (n2*n1 + n1*n2).as_independent(n2) (0, n1*n2 + n2*n1) >>> (n1*n2*n3).as_independent(n1) (1, n1*n2*n3) >>> (n1*n2*n3).as_independent(n2) (n1, n2*n3) >>> ((xn1)*(xy)).as_independent(x) (1, (x  y)*(x  n1))
– self is anything else:
>>> (sin(x)).as_independent(x) (1, sin(x)) >>> (sin(x)).as_independent(y) (sin(x), 1) >>> exp(x+y).as_independent(x) (1, exp(x + y))
– force self to be treated as an Add:
>>> (3*x).as_independent(x, as_Add=True) (0, 3*x)
– force self to be treated as a Mul:
>>> (3+x).as_independent(x, as_Add=False) (1, x + 3) >>> (3+x).as_independent(x, as_Add=False) (1, x  3)
Note how the below differs from the above in making the constant on the dep term positive.
>>> (y*(3+x)).as_independent(x) (y, x  3)
 – use .as_independent() for true independence testing instead
 of .has(). The former considers only symbols in the free symbols while the latter considers all symbols
>>> from sympy import Integral >>> I = Integral(x, (x, 1, 2)) >>> I.has(x) True >>> x in I.free_symbols False >>> I.as_independent(x) == (I, 1) True >>> (I + x).as_independent(x) == (I, x) True
Note: when trying to get independent terms, a separation method might need to be used first. In this case, it is important to keep track of what you send to this routine so you know how to interpret the returned values
>>> from sympy import separatevars, log >>> separatevars(exp(x+y)).as_independent(x) (exp(y), exp(x)) >>> (x + x*y).as_independent(y) (x, x*y) >>> separatevars(x + x*y).as_independent(y) (x, y + 1) >>> (x*(1 + y)).as_independent(y) (x, y + 1) >>> (x*(1 + y)).expand(mul=True).as_independent(y) (x, x*y) >>> a, b=symbols('a b', positive=True) >>> (log(a*b).expand(log=True)).as_independent(b) (log(a), log(b))
See also
separatevars
,expand
,Add.as_two_terms
,Mul.as_two_terms
,as_coeff_add
,as_coeff_mul

as_leading_term
(*symbols)[source]¶ Returns the leading (nonzero) term of the series expansion of self.
The _eval_as_leading_term routines are used to do this, and they must always return a nonzero value.
Examples
>>> from sympy.abc import x >>> (1 + x + x**2).as_leading_term(x) 1 >>> (1/x**2 + x + x**2).as_leading_term(x) x**(2)

as_numer_denom
()[source]¶ expression > a/b > a, b
This is just a stub that should be defined by an object’s class methods to get anything else.
See also
normal
 return a/b instead of a, b

as_ordered_terms
(order=None, data=False)[source]¶ Transform an expression to an ordered list of terms.
Examples
>>> from sympy import sin, cos >>> from sympy.abc import x
>>> (sin(x)**2*cos(x) + sin(x)**2 + 1).as_ordered_terms() [sin(x)**2*cos(x), sin(x)**2, 1]

as_powers_dict
()[source]¶ Return self as a dictionary of factors with each factor being treated as a power. The keys are the bases of the factors and the values, the corresponding exponents. The resulting dictionary should be used with caution if the expression is a Mul and contains non commutative factors since the order that they appeared will be lost in the dictionary.
See also
as_ordered_factors
 An alternative for noncommutative applications, returning an ordered list of factors.
args_cnc
 Similar to as_ordered_factors, but guarantees separation of commutative and noncommutative factors.

as_real_imag
(deep=True, **hints)[source]¶ Performs complex expansion on ‘self’ and returns a tuple containing collected both real and imaginary parts. This method can’t be confused with re() and im() functions, which does not perform complex expansion at evaluation.
However it is possible to expand both re() and im() functions and get exactly the same results as with a single call to this function.
>>> from sympy import symbols, I
>>> x, y = symbols('x,y', real=True)
>>> (x + y*I).as_real_imag() (x, y)
>>> from sympy.abc import z, w
>>> (z + w*I).as_real_imag() (re(z)  im(w), re(w) + im(z))

coeff
(x, n=1, right=False)[source]¶ Returns the coefficient from the term(s) containing
x**n
. Ifn
is zero then all terms independent ofx
will be returned.When
x
is noncommutative, the coefficient to the left (default) or right ofx
can be returned. The keyword ‘right’ is ignored whenx
is commutative.Examples
>>> from sympy import symbols >>> from sympy.abc import x, y, z
You can select terms that have an explicit negative in front of them:
>>> (x + 2*y).coeff(1) x >>> (x  2*y).coeff(1) 2*y
You can select terms with no Rational coefficient:
>>> (x + 2*y).coeff(1) x >>> (3 + 2*x + 4*x**2).coeff(1) 0
You can select terms independent of x by making n=0; in this case expr.as_independent(x)[0] is returned (and 0 will be returned instead of None):
>>> (3 + 2*x + 4*x**2).coeff(x, 0) 3 >>> eq = ((x + 1)**3).expand() + 1 >>> eq x**3 + 3*x**2 + 3*x + 2 >>> [eq.coeff(x, i) for i in reversed(range(4))] [1, 3, 3, 2] >>> eq = 2 >>> [eq.coeff(x, i) for i in reversed(range(4))] [1, 3, 3, 0]
You can select terms that have a numerical term in front of them:
>>> (x  2*y).coeff(2) y >>> from sympy import sqrt >>> (x + sqrt(2)*x).coeff(sqrt(2)) x
The matching is exact:
>>> (3 + 2*x + 4*x**2).coeff(x) 2 >>> (3 + 2*x + 4*x**2).coeff(x**2) 4 >>> (3 + 2*x + 4*x**2).coeff(x**3) 0 >>> (z*(x + y)**2).coeff((x + y)**2) z >>> (z*(x + y)**2).coeff(x + y) 0
In addition, no factoring is done, so 1 + z*(1 + y) is not obtained from the following:
>>> (x + z*(x + x*y)).coeff(x) 1
If such factoring is desired, factor_terms can be used first:
>>> from sympy import factor_terms >>> factor_terms(x + z*(x + x*y)).coeff(x) z*(y + 1) + 1
>>> n, m, o = symbols('n m o', commutative=False) >>> n.coeff(n) 1 >>> (3*n).coeff(n) 3 >>> (n*m + m*n*m).coeff(n) # = (1 + m)*n*m 1 + m >>> (n*m + m*n*m).coeff(n, right=True) # = (1 + m)*n*m m
If there is more than one possible coefficient 0 is returned:
>>> (n*m + m*n).coeff(n) 0
If there is only one possible coefficient, it is returned:
>>> (n*m + x*m*n).coeff(m*n) x >>> (n*m + x*m*n).coeff(m*n, right=1) 1
See also
as_coefficient
 separate the expression into a coefficient and factor
as_coeff_Add
 separate the additive constant from an expression
as_coeff_Mul
 separate the multiplicative constant from an expression
as_independent
 separate xdependent terms/factors from others
sympy.polys.polytools.coeff_monomial
 efficiently find the single coefficient of a monomial in Poly
sympy.polys.polytools.nth
 like coeff_monomial but powers of monomial terms are used

collect
(syms, func=None, evaluate=True, exact=False, distribute_order_term=True)[source]¶ See the collect function in sympy.simplify

compute_leading_term
(x, logx=None)[source]¶ as_leading_term is only allowed for results of .series() This is a wrapper to compute a series first.

could_extract_minus_sign
()[source]¶ Return True if self is not in a canonical form with respect to its sign.
For most expressions, e, there will be a difference in e and e. When there is, True will be returned for one and False for the other; False will be returned if there is no difference.
Examples
>>> from sympy.abc import x, y >>> e = x  y >>> {i.could_extract_minus_sign() for i in (e, e)} {False, True}

equals
(other, failing_expression=False)[source]¶ Return True if self == other, False if it doesn’t, or None. If failing_expression is True then the expression which did not simplify to a 0 will be returned instead of None.
If
self
is a Number (or complex number) that is not zero, then the result is False.If
self
is a number and has not evaluated to zero, evalf will be used to test whether the expression evaluates to zero. If it does so and the result has significance (i.e. the precision is either 1, for a Rational result, or is greater than 1) then the evalf value will be used to return True or False.

expand
(deep=True, modulus=None, power_base=True, power_exp=True, mul=True, log=True, multinomial=True, basic=True, **hints)[source]¶ Expand an expression using hints.
See the docstring of the expand() function in sympy.core.function for more information.

expr_free_symbols
¶ Like
free_symbols
, but returns the free symbols only if they are contained in an expression node.Examples
>>> from sympy.abc import x, y >>> (x + y).expr_free_symbols {x, y}
If the expression is contained in a nonexpression object, don’t return the free symbols. Compare:
>>> from sympy import Tuple >>> t = Tuple(x + y) >>> t.expr_free_symbols set() >>> t.free_symbols {x, y}

extract_additively
(c)[source]¶ Return self  c if it’s possible to subtract c from self and make all matching coefficients move towards zero, else return None.
Examples
>>> from sympy.abc import x, y >>> e = 2*x + 3 >>> e.extract_additively(x + 1) x + 2 >>> e.extract_additively(3*x) >>> e.extract_additively(4) >>> (y*(x + 1)).extract_additively(x + 1) >>> ((x + 1)*(x + 2*y + 1) + 3).extract_additively(x + 1) (x + 1)*(x + 2*y) + 3
Sometimes autoexpansion will return a less simplified result than desired; gcd_terms might be used in such cases:
>>> from sympy import gcd_terms >>> (4*x*(y + 1) + y).extract_additively(x) 4*x*(y + 1) + x*(4*y + 3)  x*(4*y + 4) + y >>> gcd_terms(_) x*(4*y + 3) + y
See also

extract_branch_factor
(allow_half=False)[source]¶ Try to write self as
exp_polar(2*pi*I*n)*z
in a nice way. Return (z, n).>>> from sympy import exp_polar, I, pi >>> from sympy.abc import x, y >>> exp_polar(I*pi).extract_branch_factor() (exp_polar(I*pi), 0) >>> exp_polar(2*I*pi).extract_branch_factor() (1, 1) >>> exp_polar(pi*I).extract_branch_factor() (exp_polar(I*pi), 1) >>> exp_polar(3*pi*I + x).extract_branch_factor() (exp_polar(x + I*pi), 1) >>> (y*exp_polar(5*pi*I)*exp_polar(3*pi*I + 2*pi*x)).extract_branch_factor() (y*exp_polar(2*pi*x), 1) >>> exp_polar(I*pi/2).extract_branch_factor() (exp_polar(I*pi/2), 0)
If allow_half is True, also extract exp_polar(I*pi):
>>> exp_polar(I*pi).extract_branch_factor(allow_half=True) (1, 1/2) >>> exp_polar(2*I*pi).extract_branch_factor(allow_half=True) (1, 1) >>> exp_polar(3*I*pi).extract_branch_factor(allow_half=True) (1, 3/2) >>> exp_polar(I*pi).extract_branch_factor(allow_half=True) (1, 1/2)

extract_multiplicatively
(c)[source]¶ Return None if it’s not possible to make self in the form c * something in a nice way, i.e. preserving the properties of arguments of self.
Examples
>>> from sympy import symbols, Rational
>>> x, y = symbols('x,y', real=True)
>>> ((x*y)**3).extract_multiplicatively(x**2 * y) x*y**2
>>> ((x*y)**3).extract_multiplicatively(x**4 * y)
>>> (2*x).extract_multiplicatively(2) x
>>> (2*x).extract_multiplicatively(3)
>>> (Rational(1, 2)*x).extract_multiplicatively(3) x/6

fourier_series
(limits=None)[source]¶ Compute fourier sine/cosine series of self.
See the docstring of the
fourier_series()
in sympy.series.fourier for more information.

fps
(x=None, x0=0, dir=1, hyper=True, order=4, rational=True, full=False)[source]¶ Compute formal power power series of self.
See the docstring of the
fps()
function in sympy.series.formal for more information.

getn
()[source]¶ Returns the order of the expression.
The order is determined either from the O(…) term. If there is no O(…) term, it returns None.
Examples
>>> from sympy import O >>> from sympy.abc import x >>> (1 + x + O(x**2)).getn() 2 >>> (1 + x).getn()

invert
(g, *gens, **args)[source]¶ Return the multiplicative inverse of
self
modg
whereself
(andg
) may be symbolic expressions).See also
sympy.core.numbers.mod_inverse
,sympy.polys.polytools.invert

is_algebraic_expr
(*syms)[source]¶ This tests whether a given expression is algebraic or not, in the given symbols, syms. When syms is not given, all free symbols will be used. The rational function does not have to be in expanded or in any kind of canonical form.
This function returns False for expressions that are “algebraic expressions” with symbolic exponents. This is a simple extension to the is_rational_function, including rational exponentiation.
Examples
>>> from sympy import Symbol, sqrt >>> x = Symbol('x', real=True) >>> sqrt(1 + x).is_rational_function() False >>> sqrt(1 + x).is_algebraic_expr() True
This function does not attempt any nontrivial simplifications that may result in an expression that does not appear to be an algebraic expression to become one.
>>> from sympy import exp, factor >>> a = sqrt(exp(x)**2 + 2*exp(x) + 1)/(exp(x) + 1) >>> a.is_algebraic_expr(x) False >>> factor(a).is_algebraic_expr() True
See also
References

is_constant
(*wrt, **flags)[source]¶ Return True if self is constant, False if not, or None if the constancy could not be determined conclusively.
If an expression has no free symbols then it is a constant. If there are free symbols it is possible that the expression is a constant, perhaps (but not necessarily) zero. To test such expressions, two strategies are tried:
1) numerical evaluation at two random points. If two such evaluations give two different values and the values have a precision greater than 1 then self is not constant. If the evaluations agree or could not be obtained with any precision, no decision is made. The numerical testing is done only if
wrt
is different than the free symbols.2) differentiation with respect to variables in ‘wrt’ (or all free symbols if omitted) to see if the expression is constant or not. This will not always lead to an expression that is zero even though an expression is constant (see added test in test_expr.py). If all derivatives are zero then self is constant with respect to the given symbols.
If neither evaluation nor differentiation can prove the expression is constant, None is returned unless two numerical values happened to be the same and the flag
failing_number
is True – in that case the numerical value will be returned.If flag simplify=False is passed, self will not be simplified; the default is True since self should be simplified before testing.
Examples
>>> from sympy import cos, sin, Sum, S, pi >>> from sympy.abc import a, n, x, y >>> x.is_constant() False >>> S(2).is_constant() True >>> Sum(x, (x, 1, 10)).is_constant() True >>> Sum(x, (x, 1, n)).is_constant() False >>> Sum(x, (x, 1, n)).is_constant(y) True >>> Sum(x, (x, 1, n)).is_constant(n) False >>> Sum(x, (x, 1, n)).is_constant(x) True >>> eq = a*cos(x)**2 + a*sin(x)**2  a >>> eq.is_constant() True >>> eq.subs({x: pi, a: 2}) == eq.subs({x: pi, a: 3}) == 0 True
>>> (0**x).is_constant() False >>> x.is_constant() False >>> (x**x).is_constant() False >>> one = cos(x)**2 + sin(x)**2 >>> one.is_constant() True >>> ((one  1)**(x + 1)).is_constant() in (True, False) # could be 0 or 1 True

is_number
¶ Returns True if
self
has no free symbols and no undefined functions (AppliedUndef, to be precise). It will be faster thanif not self.free_symbols
, however, sinceis_number
will fail as soon as it hits a free symbol or undefined function.Examples
>>> from sympy import log, Integral, cos, sin, pi >>> from sympy.core.function import Function >>> from sympy.abc import x >>> f = Function('f')
>>> x.is_number False >>> f(1).is_number False >>> (2*x).is_number False >>> (2 + Integral(2, x)).is_number False >>> (2 + Integral(2, (x, 1, 2))).is_number True
Not all numbers are Numbers in the SymPy sense:
>>> pi.is_number, pi.is_Number (True, False)
If something is a number it should evaluate to a number with real and imaginary parts that are Numbers; the result may not be comparable, however, since the real and/or imaginary part of the result may not have precision.
>>> cos(1).is_number and cos(1).is_comparable True
>>> z = cos(1)**2 + sin(1)**2  1 >>> z.is_number True >>> z.is_comparable False
See also
sympy.core.basic.is_comparable

is_polynomial
(*syms)[source]¶ Return True if self is a polynomial in syms and False otherwise.
This checks if self is an exact polynomial in syms. This function returns False for expressions that are “polynomials” with symbolic exponents. Thus, you should be able to apply polynomial algorithms to expressions for which this returns True, and Poly(expr, *syms) should work if and only if expr.is_polynomial(*syms) returns True. The polynomial does not have to be in expanded form. If no symbols are given, all free symbols in the expression will be used.
This is not part of the assumptions system. You cannot do Symbol(‘z’, polynomial=True).
Examples
>>> from sympy import Symbol >>> x = Symbol('x') >>> ((x**2 + 1)**4).is_polynomial(x) True >>> ((x**2 + 1)**4).is_polynomial() True >>> (2**x + 1).is_polynomial(x) False
>>> n = Symbol('n', nonnegative=True, integer=True) >>> (x**n + 1).is_polynomial(x) False
This function does not attempt any nontrivial simplifications that may result in an expression that does not appear to be a polynomial to become one.
>>> from sympy import sqrt, factor, cancel >>> y = Symbol('y', positive=True) >>> a = sqrt(y**2 + 2*y + 1) >>> a.is_polynomial(y) False >>> factor(a) y + 1 >>> factor(a).is_polynomial(y) True
>>> b = (y**2 + 2*y + 1)/(y + 1) >>> b.is_polynomial(y) False >>> cancel(b) y + 1 >>> cancel(b).is_polynomial(y) True
See also .is_rational_function()

is_rational_function
(*syms)[source]¶ Test whether function is a ratio of two polynomials in the given symbols, syms. When syms is not given, all free symbols will be used. The rational function does not have to be in expanded or in any kind of canonical form.
This function returns False for expressions that are “rational functions” with symbolic exponents. Thus, you should be able to call .as_numer_denom() and apply polynomial algorithms to the result for expressions for which this returns True.
This is not part of the assumptions system. You cannot do Symbol(‘z’, rational_function=True).
Examples
>>> from sympy import Symbol, sin >>> from sympy.abc import x, y
>>> (x/y).is_rational_function() True
>>> (x**2).is_rational_function() True
>>> (x/sin(y)).is_rational_function(y) False
>>> n = Symbol('n', integer=True) >>> (x**n + 1).is_rational_function(x) False
This function does not attempt any nontrivial simplifications that may result in an expression that does not appear to be a rational function to become one.
>>> from sympy import sqrt, factor >>> y = Symbol('y', positive=True) >>> a = sqrt(y**2 + 2*y + 1)/y >>> a.is_rational_function(y) False >>> factor(a) (y + 1)/y >>> factor(a).is_rational_function(y) True
See also is_algebraic_expr().

leadterm
(x)[source]¶ Returns the leading term a*x**b as a tuple (a, b).
Examples
>>> from sympy.abc import x >>> (1+x+x**2).leadterm(x) (1, 0) >>> (1/x**2+x+x**2).leadterm(x) (1, 2)

lseries
(x=None, x0=0, dir='+', logx=None)[source]¶ Wrapper for series yielding an iterator of the terms of the series.
Note: an infinite series will yield an infinite iterator. The following, for exaxmple, will never terminate. It will just keep printing terms of the sin(x) series:
for term in sin(x).lseries(x): print term
The advantage of lseries() over nseries() is that many times you are just interested in the next term in the series (i.e. the first term for example), but you don’t know how many you should ask for in nseries() using the “n” parameter.
See also nseries().

nseries
(x=None, x0=0, n=6, dir='+', logx=None)[source]¶ Wrapper to _eval_nseries if assumptions allow, else to series.
If x is given, x0 is 0, dir=’+’, and self has x, then _eval_nseries is called. This calculates “n” terms in the innermost expressions and then builds up the final series just by “crossmultiplying” everything out.
The optional
logx
parameter can be used to replace any log(x) in the returned series with a symbolic value to avoid evaluating log(x) at 0. A symbol to use in place of log(x) should be provided.Advantage – it’s fast, because we don’t have to determine how many terms we need to calculate in advance.
Disadvantage – you may end up with less terms than you may have expected, but the O(x**n) term appended will always be correct and so the result, though perhaps shorter, will also be correct.
If any of those assumptions is not met, this is treated like a wrapper to series which will try harder to return the correct number of terms.
See also lseries().
Examples
>>> from sympy import sin, log, Symbol >>> from sympy.abc import x, y >>> sin(x).nseries(x, 0, 6) x  x**3/6 + x**5/120 + O(x**6) >>> log(x+1).nseries(x, 0, 5) x  x**2/2 + x**3/3  x**4/4 + O(x**5)
Handling of the
logx
parameter — in the following example the expansion fails sincesin
does not have an asymptotic expansion at oo (the limit of log(x) as x approaches 0):>>> e = sin(log(x)) >>> e.nseries(x, 0, 6) Traceback (most recent call last): ... PoleError: ... ... >>> logx = Symbol('logx') >>> e.nseries(x, 0, 6, logx=logx) sin(logx)
In the following example, the expansion works but gives only an Order term unless the
logx
parameter is used:>>> e = x**y >>> e.nseries(x, 0, 2) O(log(x)**2) >>> e.nseries(x, 0, 2, logx=logx) exp(logx*y)

nsimplify
(constants=[], tolerance=None, full=False)[source]¶ See the nsimplify function in sympy.simplify

primitive
()[source]¶ Return the positive Rational that can be extracted nonrecursively from every term of self (i.e., self is treated like an Add). This is like the as_coeff_Mul() method but primitive always extracts a positive Rational (never a negative or a Float).
Examples
>>> from sympy.abc import x >>> (3*(x + 1)**2).primitive() (3, (x + 1)**2) >>> a = (6*x + 2); a.primitive() (2, 3*x + 1) >>> b = (x/2 + 3); b.primitive() (1/2, x + 6) >>> (a*b).primitive() == (1, a*b) True

round
(p=0)[source]¶ Return x rounded to the given decimal place.
If a complex number would results, apply round to the real and imaginary components of the number.
Examples
>>> from sympy import pi, E, I, S, Add, Mul, Number >>> S(10.5).round() 11. >>> pi.round() 3. >>> pi.round(2) 3.14 >>> (2*pi + E*I).round() 6. + 3.*I
The round method has a chopping effect:
>>> (2*pi + I/10).round() 6. >>> (pi/10 + 2*I).round() 2.*I >>> (pi/10 + E*I).round(2) 0.31 + 2.72*I
Notes
Do not confuse the Python builtin function, round, with the SymPy method of the same name. The former always returns a float (or raises an error if applied to a complex value) while the latter returns either a Number or a complex number:
>>> isinstance(round(S(123), 2), Number) False >>> isinstance(S(123).round(2), Number) True >>> isinstance((3*I).round(), Mul) True >>> isinstance((1 + 3*I).round(), Add) True

series
(x=None, x0=0, n=6, dir='+', logx=None)[source]¶ Series expansion of “self” around
x = x0
yielding either terms of the series one by one (the lazy series given when n=None), else all the terms at once when n != None.Returns the series expansion of “self” around the point
x = x0
with respect tox
up toO((x  x0)**n, x, x0)
(default n is 6).If
x=None
andself
is univariate, the univariate symbol will be supplied, otherwise an error will be raised.>>> from sympy import cos, exp >>> from sympy.abc import x, y >>> cos(x).series() 1  x**2/2 + x**4/24 + O(x**6) >>> cos(x).series(n=4) 1  x**2/2 + O(x**4) >>> cos(x).series(x, x0=1, n=2) cos(1)  (x  1)*sin(1) + O((x  1)**2, (x, 1)) >>> e = cos(x + exp(y)) >>> e.series(y, n=2) cos(x + 1)  y*sin(x + 1) + O(y**2) >>> e.series(x, n=2) cos(exp(y))  x*sin(exp(y)) + O(x**2)
If
n=None
then a generator of the series terms will be returned.>>> term=cos(x).series(n=None) >>> [next(term) for i in range(2)] [1, x**2/2]
For
dir=+
(default) the series is calculated from the right and fordir=
the series from the left. For smooth functions this flag will not alter the results.>>> abs(x).series(dir="+") x >>> abs(x).series(dir="") x

simplify
(ratio=1.7, measure=None, rational=False, inverse=False)[source]¶ See the simplify function in sympy.simplify

UnevaluatedExpr¶
AtomicExpr¶
symbol¶
Symbol¶

class
sympy.core.symbol.
Symbol
[source]¶  Assumptions:
 commutative = True
You can override the default assumptions in the constructor:
>>> from sympy import symbols >>> A,B = symbols('A,B', commutative = False) >>> bool(A*B != B*A) True >>> bool(A*B*2 == 2*A*B) == True # multiplication by scalars is commutative True
Wild¶

class
sympy.core.symbol.
Wild
[source]¶ A Wild symbol matches anything, or anything without whatever is explicitly excluded.
Parameters: name : str
Name of the Wild instance.
exclude : iterable, optional
Instances in
exclude
will not be matched.properties : iterable of functions, optional
Functions, each taking an expressions as input and returns a
bool
. All functions inproperties
need to returnTrue
in order for the Wild instance to match the expression.Examples
>>> from sympy import Wild, WildFunction, cos, pi >>> from sympy.abc import x, y, z >>> a = Wild('a') >>> x.match(a) {a_: x} >>> pi.match(a) {a_: pi} >>> (3*x**2).match(a*x) {a_: 3*x} >>> cos(x).match(a) {a_: cos(x)} >>> b = Wild('b', exclude=[x]) >>> (3*x**2).match(b*x) >>> b.match(a) {a_: b_} >>> A = WildFunction('A') >>> A.match(a) {a_: A_}
Tips
When using Wild, be sure to use the exclude keyword to make the pattern more precise. Without the exclude pattern, you may get matches that are technically correct, but not what you wanted. For example, using the above without exclude:
>>> from sympy import symbols >>> a, b = symbols('a b', cls=Wild) >>> (2 + 3*y).match(a*x + b*y) {a_: 2/x, b_: 3}
This is technically correct, because (2/x)*x + 3*y == 2 + 3*y, but you probably wanted it to not match at all. The issue is that you really didn’t want a and b to include x and y, and the exclude parameter lets you specify exactly this. With the exclude parameter, the pattern will not match.
>>> a = Wild('a', exclude=[x, y]) >>> b = Wild('b', exclude=[x, y]) >>> (2 + 3*y).match(a*x + b*y)
Exclude also helps remove ambiguity from matches.
>>> E = 2*x**3*y*z >>> a, b = symbols('a b', cls=Wild) >>> E.match(a*b) {a_: 2*y*z, b_: x**3} >>> a = Wild('a', exclude=[x, y]) >>> E.match(a*b) {a_: z, b_: 2*x**3*y} >>> a = Wild('a', exclude=[x, y, z]) >>> E.match(a*b) {a_: 2, b_: x**3*y*z}
Wild also accepts a
properties
parameter:>>> a = Wild('a', properties=[lambda k: k.is_Integer]) >>> E.match(a*b) {a_: 2, b_: x**3*y*z}
Dummy¶

class
sympy.core.symbol.
Dummy
[source]¶ Dummy symbols are each unique, even if they have the same name:
>>> from sympy import Dummy >>> Dummy("x") == Dummy("x") False
If a name is not supplied then a string value of an internal count will be used. This is useful when a temporary variable is needed and the name of the variable used in the expression is not important.
>>> Dummy() #doctest: +SKIP _Dummy_10
symbols¶

sympy.core.symbol.
symbols
(names, **args)[source]¶ Transform strings into instances of
Symbol
class.symbols()
function returns a sequence of symbols with names taken fromnames
argument, which can be a comma or whitespace delimited string, or a sequence of strings:>>> from sympy import symbols, Function >>> x, y, z = symbols('x,y,z') >>> a, b, c = symbols('a b c')
The type of output is dependent on the properties of input arguments:
>>> symbols('x') x >>> symbols('x,') (x,) >>> symbols('x,y') (x, y) >>> symbols(('a', 'b', 'c')) (a, b, c) >>> symbols(['a', 'b', 'c']) [a, b, c] >>> symbols({'a', 'b', 'c'}) {a, b, c}
If an iterable container is needed for a single symbol, set the
seq
argument toTrue
or terminate the symbol name with a comma:>>> symbols('x', seq=True) (x,)
To reduce typing, range syntax is supported to create indexed symbols. Ranges are indicated by a colon and the type of range is determined by the character to the right of the colon. If the character is a digit then all contiguous digits to the left are taken as the nonnegative starting value (or 0 if there is no digit left of the colon) and all contiguous digits to the right are taken as 1 greater than the ending value:
>>> symbols('x:10') (x0, x1, x2, x3, x4, x5, x6, x7, x8, x9) >>> symbols('x5:10') (x5, x6, x7, x8, x9) >>> symbols('x5(:2)') (x50, x51) >>> symbols('x5:10,y:5') (x5, x6, x7, x8, x9, y0, y1, y2, y3, y4) >>> symbols(('x5:10', 'y:5')) ((x5, x6, x7, x8, x9), (y0, y1, y2, y3, y4))
If the character to the right of the colon is a letter, then the single letter to the left (or ‘a’ if there is none) is taken as the start and all characters in the lexicographic range through the letter to the right are used as the range:
>>> symbols('x:z') (x, y, z) >>> symbols('x:c') # null range () >>> symbols('x(:c)') (xa, xb, xc) >>> symbols(':c') (a, b, c) >>> symbols('a:d, x:z') (a, b, c, d, x, y, z) >>> symbols(('a:d', 'x:z')) ((a, b, c, d), (x, y, z))
Multiple ranges are supported; contiguous numerical ranges should be separated by parentheses to disambiguate the ending number of one range from the starting number of the next:
>>> symbols('x:2(1:3)') (x01, x02, x11, x12) >>> symbols(':3:2') # parsing is from left to right (00, 01, 10, 11, 20, 21)
Only one pair of parentheses surrounding ranges are removed, so to include parentheses around ranges, double them. And to include spaces, commas, or colons, escape them with a backslash:
>>> symbols('x((a:b))') (x(a), x(b)) >>> symbols(r'x(:1\,:2)') # or r'x((:1)\,(:2))' (x(0,0), x(0,1))
All newly created symbols have assumptions set according to
args
:>>> a = symbols('a', integer=True) >>> a.is_integer True >>> x, y, z = symbols('x,y,z', real=True) >>> x.is_real and y.is_real and z.is_real True
Despite its name,
symbols()
can create symbollike objects like instances of Function or Wild classes. To achieve this, setcls
keyword argument to the desired type:>>> symbols('f,g,h', cls=Function) (f, g, h) >>> type(_[0]) <class 'sympy.core.function.UndefinedFunction'>
var¶

sympy.core.symbol.
var
(names, **args)[source]¶ Create symbols and inject them into the global namespace.
This calls
symbols()
with the same arguments and puts the results into the global namespace. It’s recommended not to usevar()
in library code, wheresymbols()
has to be used:.. rubric:: Examples
>>> from sympy import var
>>> var('x') x >>> x x
>>> var('a,ab,abc') (a, ab, abc) >>> abc abc
>>> var('x,y', real=True) (x, y) >>> x.is_real and y.is_real True
See
symbol()
documentation for more details on what kinds of arguments can be passed tovar()
.
numbers¶
Number¶

class
sympy.core.numbers.
Number
[source]¶ Represents atomic numbers in SymPy.
Floating point numbers are represented by the Float class. Rational numbers (of any size) are represented by the Rational class. Integer numbers (of any size) are represented by the Integer class. Float and Rational are subclasses of Number; Integer is a subclass of Rational.
For example,
2/3
is represented asRational(2, 3)
which is a different object from the floating point number obtained with Python division2/3
. Even for numbers that are exactly represented in binary, there is a difference between how two forms, such asRational(1, 2)
andFloat(0.5)
, are used in SymPy. The rational form is to be preferred in symbolic computations.Other kinds of numbers, such as algebraic numbers
sqrt(2)
or complex numbers3 + 4*I
, are not instances of Number class as they are not atomic.
Float¶

class
sympy.core.numbers.
Float
[source]¶ Represent a floatingpoint number of arbitrary precision.
Examples
>>> from sympy import Float >>> Float(3.5) 3.50000000000000 >>> Float(3) 3.00000000000000
Creating Floats from strings (and Python
int
andlong
types) will give a minimum precision of 15 digits, but the precision will automatically increase to capture all digits entered.>>> Float(1) 1.00000000000000 >>> Float(10**20) 100000000000000000000. >>> Float('1e20') 100000000000000000000.
However, floatingpoint numbers (Python
float
types) retain only 15 digits of precision:>>> Float(1e20) 1.00000000000000e+20 >>> Float(1.23456789123456789) 1.23456789123457
It may be preferable to enter highprecision decimal numbers as strings:
Float(‘1.23456789123456789’) 1.23456789123456789
The desired number of digits can also be specified:
>>> Float('1e3', 3) 0.00100 >>> Float(100, 4) 100.0
Float can automatically count significant figures if a null string is sent for the precision; space are also allowed in the string. (Auto counting is only allowed for strings, ints and longs).
>>> Float('123 456 789 . 123 456', '') 123456789.123456 >>> Float('12e3', '') 0.012 >>> Float(3, '') 3.
If a number is written in scientific notation, only the digits before the exponent are considered significant if a decimal appears, otherwise the “e” signifies only how to move the decimal:
>>> Float('60.e2', '') # 2 digits significant 6.0e+3 >>> Float('60e2', '') # 4 digits significant 6000. >>> Float('600e2', '') # 3 digits significant 6.00
Notes
Floats are inexact by their nature unless their value is a binaryexact value.
>>> approx, exact = Float(.1, 1), Float(.125, 1)
For calculation purposes, evalf needs to be able to change the precision but this will not increase the accuracy of the inexact value. The following is the most accurate 5digit approximation of a value of 0.1 that had only 1 digit of precision:
>>> approx.evalf(5) 0.099609
By contrast, 0.125 is exact in binary (as it is in base 10) and so it can be passed to Float or evalf to obtain an arbitrary precision with matching accuracy:
>>> Float(exact, 5) 0.12500 >>> exact.evalf(20) 0.12500000000000000000
Trying to make a highprecision Float from a float is not disallowed, but one must keep in mind that the underlying float (not the apparent decimal value) is being obtained with high precision. For example, 0.3 does not have a finite binary representation. The closest rational is the fraction 5404319552844595/2**54. So if you try to obtain a Float of 0.3 to 20 digits of precision you will not see the same thing as 0.3 followed by 19 zeros:
>>> Float(0.3, 20) 0.29999999999999998890
If you want a 20digit value of the decimal 0.3 (not the floating point approximation of 0.3) you should send the 0.3 as a string. The underlying representation is still binary but a higher precision than Python’s float is used:
>>> Float('0.3', 20) 0.30000000000000000000
Although you can increase the precision of an existing Float using Float it will not increase the accuracy – the underlying value is not changed:
>>> def show(f): # binary rep of Float ... from sympy import Mul, Pow ... s, m, e, b = f._mpf_ ... v = Mul(int(m), Pow(2, int(e), evaluate=False), evaluate=False) ... print('%s at prec=%s' % (v, f._prec)) ... >>> t = Float('0.3', 3) >>> show(t) 4915/2**14 at prec=13 >>> show(Float(t, 20)) # higher prec, not higher accuracy 4915/2**14 at prec=70 >>> show(Float(t, 2)) # lower prec 307/2**10 at prec=10
The same thing happens when evalf is used on a Float:
>>> show(t.evalf(20)) 4915/2**14 at prec=70 >>> show(t.evalf(2)) 307/2**10 at prec=10
Finally, Floats can be instantiated with an mpf tuple (n, c, p) to produce the number (1)**n*c*2**p:
>>> n, c, p = 1, 5, 0 >>> (1)**n*c*2**p 5 >>> Float((1, 5, 0)) 5.00000000000000
An actual mpf tuple also contains the number of bits in c as the last element of the tuple:
>>> _._mpf_ (1, 5, 0, 3)
This is not needed for instantiation and is not the same thing as the precision. The mpf tuple and the precision are two separate quantities that Float tracks.
Attributes
is_irrational is_rational
Rational¶

class
sympy.core.numbers.
Rational
[source]¶ Represents rational numbers (p/q) of any size.
Examples
>>> from sympy import Rational, nsimplify, S, pi >>> Rational(1, 2) 1/2
Rational is unprejudiced in accepting input. If a float is passed, the underlying value of the binary representation will be returned:
>>> Rational(.5) 1/2 >>> Rational(.2) 3602879701896397/18014398509481984
If the simpler representation of the float is desired then consider limiting the denominator to the desired value or convert the float to a string (which is roughly equivalent to limiting the denominator to 10**12):
>>> Rational(str(.2)) 1/5 >>> Rational(.2).limit_denominator(10**12) 1/5
An arbitrarily precise Rational is obtained when a string literal is passed:
>>> Rational("1.23") 123/100 >>> Rational('1e2') 1/100 >>> Rational(".1") 1/10 >>> Rational('1e2/3.2') 1/320
The conversion of other types of strings can be handled by the sympify() function, and conversion of floats to expressions or simple fractions can be handled with nsimplify:
>>> S('.[3]') # repeating digits in brackets 1/3 >>> S('3**2/10') # general expressions 9/10 >>> nsimplify(.3) # numbers that have a simple form 3/10
But if the input does not reduce to a literal Rational, an error will be raised:
>>> Rational(pi) Traceback (most recent call last): ... TypeError: invalid input: pi
Lowlevel
Access numerator and denominator as .p and .q:
>>> r = Rational(3, 4) >>> r 3/4 >>> r.p 3 >>> r.q 4
Note that p and q return integers (not SymPy Integers) so some care is needed when using them in expressions:
>>> r.p/r.q 0.75
See also
sympify
,sympy.simplify.simplify.nsimplify

as_content_primitive
(radical=False, clear=True)[source]¶ Return the tuple (R, self/R) where R is the positive Rational extracted from self.
Examples
>>> from sympy import S >>> (S(3)/2).as_content_primitive() (3/2, 1)
See docstring of Expr.as_content_primitive for more examples.

Integer¶

class
sympy.core.numbers.
Integer
[source]¶ Represents integer numbers of any size.
Examples
>>> from sympy import Integer >>> Integer(3) 3
If a float or a rational is passed to Integer, the fractional part will be discarded; the effect is of rounding toward zero.
>>> Integer(3.8) 3 >>> Integer(3.8) 3
A string is acceptable input if it can be parsed as an integer:
>>> Integer("9" * 20) 99999999999999999999
It is rarely needed to explicitly instantiate an Integer, because Python integers are automatically converted to Integer when they are used in SymPy expressions.
NumberSymbol¶
RealNumber¶

sympy.core.numbers.
RealNumber
¶ alias of
sympy.core.numbers.Float
igcd¶

sympy.core.numbers.
igcd
()[source]¶ Computes nonnegative integer greatest common divisor.
The algorithm is based on the well known Euclid’s algorithm. To improve speed, igcd() has its own caching mechanism implemented.
Examples
>>> from sympy.core.numbers import igcd >>> igcd(2, 4) 2 >>> igcd(5, 10, 15) 5
ilcm¶
seterr¶
Zero¶

class
sympy.core.numbers.
Zero
[source]¶ The number zero.
Zero is a singleton, and can be accessed by
S.Zero
Examples
>>> from sympy import S, Integer, zoo >>> Integer(0) is S.Zero True >>> 1/S.Zero zoo
References
[R81] https://en.wikipedia.org/wiki/Zero
One¶

class
sympy.core.numbers.
One
[source]¶ The number one.
One is a singleton, and can be accessed by
S.One
.Examples
>>> from sympy import S, Integer >>> Integer(1) is S.One True
References
[R82] https://en.wikipedia.org/wiki/1_%28number%29
NegativeOne¶

class
sympy.core.numbers.
NegativeOne
[source]¶ The number negative one.
NegativeOne is a singleton, and can be accessed by
S.NegativeOne
.Examples
>>> from sympy import S, Integer >>> Integer(1) is S.NegativeOne True
See also
References
[R83] https://en.wikipedia.org/wiki/%E2%88%921_%28number%29
Half¶

class
sympy.core.numbers.
Half
[source]¶ The rational number 1/2.
Half is a singleton, and can be accessed by
S.Half
.Examples
>>> from sympy import S, Rational >>> Rational(1, 2) is S.Half True
References
[R84] https://en.wikipedia.org/wiki/One_half
NaN¶

class
sympy.core.numbers.
NaN
[source]¶ Not a Number.
This serves as a place holder for numeric values that are indeterminate. Most operations on NaN, produce another NaN. Most indeterminate forms, such as
0/0
oroo  oo` produce NaN. Two exceptions are ``0**0
andoo**0
, which all produce1
(this is consistent with Python’s float).NaN is loosely related to floating point nan, which is defined in the IEEE 754 floating point standard, and corresponds to the Python
float('nan')
. Differences are noted below.NaN is mathematically not equal to anything else, even NaN itself. This explains the initially counterintuitive results with
Eq
and==
in the examples below.NaN is not comparable so inequalities raise a TypeError. This is in constrast with floating point nan where all inequalities are false.
NaN is a singleton, and can be accessed by
S.NaN
, or can be imported asnan
.Examples
>>> from sympy import nan, S, oo, Eq >>> nan is S.NaN True >>> oo  oo nan >>> nan + 1 nan >>> Eq(nan, nan) # mathematical equality False >>> nan == nan # structural equality True
References
[R85] https://en.wikipedia.org/wiki/NaN Attributes
is_algebraic is_finite is_integer is_negative is_positive is_prime is_rational is_real is_transcendental is_zero
Infinity¶

class
sympy.core.numbers.
Infinity
[source]¶ Positive infinite quantity.
In real analysis the symbol \(\infty\) denotes an unbounded limit: \(x\to\infty\) means that \(x\) grows without bound.
Infinity is often used not only to define a limit but as a value in the affinely extended real number system. Points labeled \(+\infty\) and \(\infty\) can be added to the topological space of the real numbers, producing the twopoint compactification of the real numbers. Adding algebraic properties to this gives us the extended real numbers.
Infinity is a singleton, and can be accessed by
S.Infinity
, or can be imported asoo
.Examples
>>> from sympy import oo, exp, limit, Symbol >>> 1 + oo oo >>> 42/oo 0 >>> x = Symbol('x') >>> limit(exp(x), x, oo) oo
See also
References
[R86] https://en.wikipedia.org/wiki/Infinity
NegativeInfinity¶
ComplexInfinity¶

class
sympy.core.numbers.
ComplexInfinity
[source]¶ Complex infinity.
In complex analysis the symbol \(\tilde\infty\), called “complex infinity”, represents a quantity with infinite magnitude, but undetermined complex phase.
ComplexInfinity is a singleton, and can be accessed by
S.ComplexInfinity
, or can be imported aszoo
.Examples
>>> from sympy import zoo, oo >>> zoo + 42 zoo >>> 42/zoo 0 >>> zoo + zoo nan >>> zoo*zoo zoo
See also
Exp1¶

class
sympy.core.numbers.
Exp1
[source]¶ The \(e\) constant.
The transcendental number \(e = 2.718281828\ldots\) is the base of the natural logarithm and of the exponential function, \(e = \exp(1)\). Sometimes called Euler’s number or Napier’s constant.
Exp1 is a singleton, and can be accessed by
S.Exp1
, or can be imported asE
.Examples
>>> from sympy import exp, log, E >>> E is exp(1) True >>> log(E) 1
References
[R87] https://en.wikipedia.org/wiki/E_%28mathematical_constant%29
ImaginaryUnit¶

class
sympy.core.numbers.
ImaginaryUnit
[source]¶ The imaginary unit, \(i = \sqrt{1}\).
I is a singleton, and can be accessed by
S.I
, or can be imported asI
.Examples
>>> from sympy import I, sqrt >>> sqrt(1) I >>> I*I 1 >>> 1/I I
References
[R88] https://en.wikipedia.org/wiki/Imaginary_unit
Pi¶

class
sympy.core.numbers.
Pi
[source]¶ The \(\pi\) constant.
The transcendental number \(\pi = 3.141592654\ldots\) represents the ratio of a circle’s circumference to its diameter, the area of the unit circle, the halfperiod of trigonometric functions, and many other things in mathematics.
Pi is a singleton, and can be accessed by
S.Pi
, or can be imported aspi
.Examples
>>> from sympy import S, pi, oo, sin, exp, integrate, Symbol >>> S.Pi pi >>> pi > 3 True >>> pi.is_irrational True >>> x = Symbol('x') >>> sin(x + 2*pi) sin(x) >>> integrate(exp(x**2), (x, oo, oo)) sqrt(pi)
References
[R89] https://en.wikipedia.org/wiki/Pi
EulerGamma¶

class
sympy.core.numbers.
EulerGamma
[source]¶ The EulerMascheroni constant.
\(\gamma = 0.5772157\ldots\) (also called Euler’s constant) is a mathematical constant recurring in analysis and number theory. It is defined as the limiting difference between the harmonic series and the natural logarithm:
\[\gamma = \lim\limits_{n\to\infty} \left(\sum\limits_{k=1}^n\frac{1}{k}  \ln n\right)\]EulerGamma is a singleton, and can be accessed by
S.EulerGamma
.Examples
>>> from sympy import S >>> S.EulerGamma.is_irrational >>> S.EulerGamma > 0 True >>> S.EulerGamma > 1 False
References
[R90] https://en.wikipedia.org/wiki/Euler%E2%80%93Mascheroni_constant Attributes
is_irrational
Catalan¶

class
sympy.core.numbers.
Catalan
[source]¶ Catalan’s constant.
\(K = 0.91596559\ldots\) is given by the infinite series
\[K = \sum_{k=0}^{\infty} \frac{(1)^k}{(2k+1)^2}\]Catalan is a singleton, and can be accessed by
S.Catalan
.Examples
>>> from sympy import S >>> S.Catalan.is_irrational >>> S.Catalan > 0 True >>> S.Catalan > 1 False
References
[R91] https://en.wikipedia.org/wiki/Catalan%27s_constant Attributes
is_irrational
GoldenRatio¶

class
sympy.core.numbers.
GoldenRatio
[source]¶ The golden ratio, \(\phi\).
\(\phi = \frac{1 + \sqrt{5}}{2}\) is algebraic number. Two quantities are in the golden ratio if their ratio is the same as the ratio of their sum to the larger of the two quantities, i.e. their maximum.
GoldenRatio is a singleton, and can be accessed by
S.GoldenRatio
.Examples
>>> from sympy import S >>> S.GoldenRatio > 1 True >>> S.GoldenRatio.expand(func=True) 1/2 + sqrt(5)/2 >>> S.GoldenRatio.is_irrational True
References
[R92] https://en.wikipedia.org/wiki/Golden_ratio
TribonacciConstant¶

class
sympy.core.numbers.
TribonacciConstant
[source]¶ The tribonacci constant.
The tribonacci numbers are like the Fibonacci numbers, but instead of starting with two predetermined terms, the sequence starts with three predetermined terms and each term afterwards is the sum of the preceding three terms.
The tribonacci constant is the ratio toward which adjacent tribonacci numbers tend. It is a root of the polynomial \(x^3  x^2  x  1 = 0\), and also satisfies the equation \(x + x^{3} = 2\).
TribonacciConstant is a singleton, and can be accessed by
S.TribonacciConstant
.Examples
>>> from sympy import S >>> S.TribonacciConstant > 1 True >>> S.TribonacciConstant.expand(func=True) 1/3 + (3*sqrt(33) + 19)**(1/3)/3 + (3*sqrt(33) + 19)**(1/3)/3 >>> S.TribonacciConstant.is_irrational True >>> S.TribonacciConstant.n(20) 1.8392867552141611326
References
[R93] https://en.wikipedia.org/wiki/Generalizations_of_Fibonacci_numbers#Tribonacci_numbers
power¶
Pow¶

class
sympy.core.power.
Pow
[source]¶ Defines the expression x**y as “x raised to a power y”
Singleton definitions involving (0, 1, 1, oo, oo, I, I):
expr value reason z**0 1 Although arguments over 0**0 exist, see [2]. z**1 z (oo)**(1) 0 (1)**1 1 S.Zero**1 zoo This is not strictly true, as 0**1 may be undefined, but is convenient in some contexts where the base is assumed to be positive. 1**1 1 oo**1 0 0**oo 0 Because for all complex numbers z near 0, z**oo > 0. 0**oo zoo This is not strictly true, as 0**oo may be oscillating between positive and negative values or rotating in the complex plane. It is convenient, however, when the base is positive. 1**oo 1**oo nan Because there are various cases where lim(x(t),t)=1, lim(y(t),t)=oo (or oo), but lim( x(t)**y(t), t) != 1. See [3]. b**zoo nan Because b**z has no limit as z > zoo (1)**oo (1)**(oo) nan Because of oscillations in the limit. oo**oo oo oo**oo 0 (oo)**oo (oo)**oo nan oo**I (oo)**I nan oo**e could probably be best thought of as the limit of x**e for real x as x tends to oo. If e is I, then the limit does not exist and nan is used to indicate that. oo**(1+I) (oo)**(1+I) zoo If the real part of e is positive, then the limit of abs(x**e) is oo. So the limit value is zoo. oo**(1+I) oo**(1+I) 0 If the real part of e is negative, then the limit is 0. Because symbolic computations are more flexible that floating point calculations and we prefer to never return an incorrect answer, we choose not to conform to all IEEE 754 conventions. This helps us avoid extra testcase code in the calculation of limits.
References
[R94] https://en.wikipedia.org/wiki/Exponentiation [R95] https://en.wikipedia.org/wiki/Exponentiation#Zero_to_the_power_of_zero [R96] https://en.wikipedia.org/wiki/Indeterminate_forms 
as_base_exp
()[source]¶ Return base and exp of self.
If base is 1/Integer, then return Integer, exp. If this extra processing is not needed, the base and exp properties will give the raw arguments
Examples
>>> from sympy import Pow, S >>> p = Pow(S.Half, 2, evaluate=False) >>> p.as_base_exp() (2, 2) >>> p.args (1/2, 2)

as_content_primitive
(radical=False, clear=True)[source]¶ Return the tuple (R, self/R) where R is the positive Rational extracted from self.
Examples
>>> from sympy import sqrt >>> sqrt(4 + 4*sqrt(2)).as_content_primitive() (2, sqrt(1 + sqrt(2))) >>> sqrt(3 + 3*sqrt(2)).as_content_primitive() (1, sqrt(3)*sqrt(1 + sqrt(2)))
>>> from sympy import expand_power_base, powsimp, Mul >>> from sympy.abc import x, y
>>> ((2*x + 2)**2).as_content_primitive() (4, (x + 1)**2) >>> (4**((1 + y)/2)).as_content_primitive() (2, 4**(y/2)) >>> (3**((1 + y)/2)).as_content_primitive() (1, 3**((y + 1)/2)) >>> (3**((5 + y)/2)).as_content_primitive() (9, 3**((y + 1)/2)) >>> eq = 3**(2 + 2*x) >>> powsimp(eq) == eq True >>> eq.as_content_primitive() (9, 3**(2*x)) >>> powsimp(Mul(*_)) 3**(2*x + 2)
>>> eq = (2 + 2*x)**y >>> s = expand_power_base(eq); s.is_Mul, s (False, (2*x + 2)**y) >>> eq.as_content_primitive() (1, (2*(x + 1))**y) >>> s = expand_power_base(_[1]); s.is_Mul, s (True, 2**y*(x + 1)**y)
See docstring of Expr.as_content_primitive for more examples.

integer_nthroot¶

sympy.core.power.
integer_nthroot
(y, n)[source]¶ Return a tuple containing x = floor(y**(1/n)) and a boolean indicating whether the result is exact (that is, whether x**n == y).
Examples
>>> from sympy import integer_nthroot >>> integer_nthroot(16, 2) (4, True) >>> integer_nthroot(26, 2) (5, False)
To simply determine if a number is a perfect square, the is_square function should be used:
>>> from sympy.ntheory.primetest import is_square >>> is_square(26) False
See also
sympy.ntheory.primetest.is_square
,integer_log
mul¶
Mul¶

class
sympy.core.mul.
Mul
[source]¶ 

as_coefficients_dict
()[source]¶ Return a dictionary mapping terms to their coefficient. Since the dictionary is a defaultdict, inquiries about terms which were not present will return a coefficient of 0. The dictionary is considered to have a single term.
Examples
>>> from sympy.abc import a, x >>> (3*a*x).as_coefficients_dict() {a*x: 3} >>> _[a] 0

as_content_primitive
(radical=False, clear=True)[source]¶ Return the tuple (R, self/R) where R is the positive Rational extracted from self.
Examples
>>> from sympy import sqrt >>> (3*sqrt(2)*(2  2*sqrt(2))).as_content_primitive() (6, sqrt(2)*(sqrt(2) + 1))
See docstring of Expr.as_content_primitive for more examples.

as_ordered_factors
(order=None)[source]¶ Transform an expression into an ordered list of factors.
Examples
>>> from sympy import sin, cos >>> from sympy.abc import x, y
>>> (2*x*y*sin(x)*cos(x)).as_ordered_factors() [2, x, y, sin(x), cos(x)]

as_two_terms
()[source]¶ Return head and tail of self.
This is the most efficient way to get the head and tail of an expression.
 if you want only the head, use self.args[0];
 if you want to process the arguments of the tail then use self.as_coef_mul() which gives the head and a tuple containing the arguments of the tail when treated as a Mul.
 if you want the coefficient when self is treated as an Add then use self.as_coeff_add()[0]
>>> from sympy.abc import x, y >>> (3*x*y).as_two_terms() (3, x*y)

classmethod
flatten
(seq)[source]¶ Return commutative, noncommutative and order arguments by combining related terms.
Notes
In an expression like
a*b*c
, python process this through sympy asMul(Mul(a, b), c)
. This can have undesirable consequences. Sometimes terms are not combined as one would like: {c.f. https://github.com/sympy/sympy/issues/4596}
>>> from sympy import Mul, sqrt >>> from sympy.abc import x, y, z >>> 2*(x + 1) # this is the 2arg Mul behavior 2*x + 2 >>> y*(x + 1)*2 2*y*(x + 1) >>> 2*(x + 1)*y # 2arg result will be obtained first y*(2*x + 2) >>> Mul(2, x + 1, y) # all 3 args simultaneously processed 2*y*(x + 1) >>> 2*((x + 1)*y) # parentheses can control this behavior 2*y*(x + 1)
Powers with compound bases may not find a single base to combine with unless all arguments are processed at once. Postprocessing may be necessary in such cases. {c.f. https://github.com/sympy/sympy/issues/5728}
>>> a = sqrt(x*sqrt(y)) >>> a**3 (x*sqrt(y))**(3/2) >>> Mul(a,a,a) (x*sqrt(y))**(3/2) >>> a*a*a x*sqrt(y)*sqrt(x*sqrt(y)) >>> _.subs(a.base, z).subs(z, a.base) (x*sqrt(y))**(3/2)
If more than two terms are being multiplied then all the previous terms will be reprocessed for each new argument. So if each of
a
,b
andc
wereMul
expression, thena*b*c
(or building up the product with*=
) will process all the arguments ofa
andb
twice: once whena*b
is computed and again whenc
is multiplied.Using
Mul(a, b, c)
will process all arguments once.
The results of Mul are cached according to arguments, so flatten will only be called once for
Mul(a, b, c)
. If you can structure a calculation so the arguments are most likely to be repeats then this can save time in computing the answer. For example, say you had a Mul, M, that you wished to divide byd[i]
and multiply byn[i]
and you suspect there are many repeats inn
. It would be better to computeM*n[i]/d[i]
rather thanM/d[i]*n[i]
since every time n[i] is a repeat, the product,M*n[i]
will be returned without flattening – the cached value will be returned. If you divide by thed[i]
first (and those are more unique than then[i]
) then that will create a new Mul,M/d[i]
the args of which will be traversed again when it is multiplied byn[i]
.{c.f. https://github.com/sympy/sympy/issues/5706}
This consideration is moot if the cache is turned off.
Nb
The validity of the above notes depends on the implementation details of Mul and flatten which may change at any time. Therefore, you should only consider them when your code is highly performance sensitive.
Removal of 1 from the sequence is already handled by AssocOp.__new__.

prod¶

sympy.core.mul.
prod
(a, start=1)[source]¶  Return product of elements of a. Start with int 1 so if only
 ints are included then an int result is returned.
Examples
>>> from sympy import prod, S >>> prod(range(3)) 0 >>> type(_) is int True >>> prod([S(2), 3]) 6 >>> _.is_Integer True
You can start the product at something other than 1:
>>> prod([1, 2], 3) 6
add¶
Add¶

class
sympy.core.add.
Add
[source]¶ 

as_coeff_add
(*deps)[source]¶ Returns a tuple (coeff, args) where self is treated as an Add and coeff is the Number term and args is a tuple of all other terms.
Examples
>>> from sympy.abc import x >>> (7 + 3*x).as_coeff_add() (7, (3*x,)) >>> (7*x).as_coeff_add() (0, (7*x,))

as_coefficients_dict
()[source]¶ Return a dictionary mapping terms to their Rational coefficient. Since the dictionary is a defaultdict, inquiries about terms which were not present will return a coefficient of 0. If an expression is not an Add it is considered to have a single term.
Examples
>>> from sympy.abc import a, x >>> (3*x + a*x + 4).as_coefficients_dict() {1: 4, x: 3, a*x: 1} >>> _[a] 0 >>> (3*a*x).as_coefficients_dict() {a*x: 3}

as_content_primitive
(radical=False, clear=True)[source]¶ Return the tuple (R, self/R) where R is the positive Rational extracted from self. If radical is True (default is False) then common radicals will be removed and included as a factor of the primitive expression.
Examples
>>> from sympy import sqrt >>> (3 + 3*sqrt(2)).as_content_primitive() (3, 1 + sqrt(2))
Radical content can also be factored out of the primitive:
>>> (2*sqrt(2) + 4*sqrt(10)).as_content_primitive(radical=True) (2, sqrt(2)*(1 + 2*sqrt(5)))
See docstring of Expr.as_content_primitive for more examples.

as_real_imag
(deep=True, **hints)[source]¶ returns a tuple representing a complex number
Examples
>>> from sympy import I >>> (7 + 9*I).as_real_imag() (7, 9) >>> ((1 + I)/(1  I)).as_real_imag() (0, 1) >>> ((1 + 2*I)*(1 + 3*I)).as_real_imag() (5, 5)

as_two_terms
()[source]¶ Return head and tail of self.
This is the most efficient way to get the head and tail of an expression.
 if you want only the head, use self.args[0];
 if you want to process the arguments of the tail then use self.as_coef_add() which gives the head and a tuple containing the arguments of the tail when treated as an Add.
 if you want the coefficient when self is treated as a Mul then use self.as_coeff_mul()[0]
>>> from sympy.abc import x, y >>> (3*x  2*y + 5).as_two_terms() (5, 3*x  2*y)

extract_leading_order
(symbols, point=None)[source]¶ Returns the leading term and its order.
Examples
>>> from sympy.abc import x >>> (x + 1 + 1/x**5).extract_leading_order(x) ((x**(5), O(x**(5))),) >>> (1 + x).extract_leading_order(x) ((1, O(1)),) >>> (x + x**2).extract_leading_order(x) ((x, O(x)),)

classmethod
flatten
(seq)[source]¶ Takes the sequence “seq” of nested Adds and returns a flatten list.
Returns: (commutative_part, noncommutative_part, order_symbols)
Applies associativity, all terms are commutable with respect to addition.
NB: the removal of 0 is already handled by AssocOp.__new__
See also

primitive
()[source]¶ Return
(R, self/R)
whereR`
is the Rational GCD ofself`
.R
is collected only from the leading coefficient of each term.Examples
>>> from sympy.abc import x, y
>>> (2*x + 4*y).primitive() (2, x + 2*y)
>>> (2*x/3 + 4*y/9).primitive() (2/9, 3*x + 2*y)
>>> (2*x/3 + 4.2*y).primitive() (1/3, 2*x + 12.6*y)
No subprocessing of term factors is performed:
>>> ((2 + 2*x)*x + 2).primitive() (1, x*(2*x + 2) + 2)
Recursive processing can be done with the
as_content_primitive()
method:>>> ((2 + 2*x)*x + 2).as_content_primitive() (2, x*(x + 1) + 1)
See also: primitive() function in polytools.py

mod¶
Mod¶

class
sympy.core.mod.
Mod
[source]¶ Represents a modulo operation on symbolic expressions.
Receives two arguments, dividend p and divisor q.
The convention used is the same as Python’s: the remainder always has the same sign as the divisor.
Examples
>>> from sympy.abc import x, y >>> x**2 % y Mod(x**2, y) >>> _.subs({x: 5, y: 6}) 1
relational¶
Eq¶

sympy.core.relational.
Eq
¶ alias of
sympy.core.relational.Equality
Ne¶

sympy.core.relational.
Ne
¶ alias of
sympy.core.relational.Unequality
Lt¶

sympy.core.relational.
Lt
¶ alias of
sympy.core.relational.StrictLessThan
Le¶

sympy.core.relational.
Le
¶ alias of
sympy.core.relational.LessThan
Ge¶

sympy.core.relational.
Ge
¶ alias of
sympy.core.relational.GreaterThan
Equality¶

class
sympy.core.relational.
Equality
[source]¶ An equal relation between two objects.
Represents that two objects are equal. If they can be easily shown to be definitively equal (or unequal), this will reduce to True (or False). Otherwise, the relation is maintained as an unevaluated Equality object. Use the
simplify
function on this object for more nontrivial evaluation of the equality relation.As usual, the keyword argument
evaluate=False
can be used to prevent any evaluation.Examples
>>> from sympy import Eq, simplify, exp, cos >>> from sympy.abc import x, y >>> Eq(y, x + x**2) Eq(y, x**2 + x) >>> Eq(2, 5) False >>> Eq(2, 5, evaluate=False) Eq(2, 5) >>> _.doit() False >>> Eq(exp(x), exp(x).rewrite(cos)) Eq(exp(x), sinh(x) + cosh(x)) >>> simplify(_) True
Notes
This class is not the same as the == operator. The == operator tests for exact structural equality between two expressions; this class compares expressions mathematically.
If either object defines an \(_eval_Eq\) method, it can be used in place of the default algorithm. If \(lhs._eval_Eq(rhs)\) or \(rhs._eval_Eq(lhs)\) returns anything other than None, that return value will be substituted for the Equality. If None is returned by \(_eval_Eq\), an Equality object will be created as usual.
Since this object is already an expression, it does not respond to the method \(as_expr\) if one tries to create \(x  y\) from Eq(x, y). This can be done with the \(rewrite(Add)\) method.
See also
sympy.logic.boolalg.Equivalent
 for representing equality between two boolean expressions
GreaterThan¶

class
sympy.core.relational.
GreaterThan
[source]¶ Class representations of inequalities.
The
*Than
classes represent inequal relationships, where the lefthand side is generally bigger or smaller than the righthand side. For example, the GreaterThan class represents an inequal relationship where the lefthand side is at least as big as the right side, if not bigger. In mathematical notation:lhs >= rhs
In total, there are four
*Than
classes, to represent the four inequalities:Class Name Symbol GreaterThan (>=) LessThan (<=) StrictGreaterThan (>) StrictLessThan (<) All classes take two arguments, lhs and rhs.
Signature Example Math equivalent GreaterThan(lhs, rhs) lhs >= rhs LessThan(lhs, rhs) lhs <= rhs StrictGreaterThan(lhs, rhs) lhs > rhs StrictLessThan(lhs, rhs) lhs < rhs In addition to the normal .lhs and .rhs of Relations,
*Than
inequality objects also have the .lts and .gts properties, which represent the “less than side” and “greater than side” of the operator. Use of .lts and .gts in an algorithm rather than .lhs and .rhs as an assumption of inequality direction will make more explicit the intent of a certain section of code, and will make it similarly more robust to client code changes:>>> from sympy import GreaterThan, StrictGreaterThan >>> from sympy import LessThan, StrictLessThan >>> from sympy import And, Ge, Gt, Le, Lt, Rel, S >>> from sympy.abc import x, y, z >>> from sympy.core.relational import Relational
>>> e = GreaterThan(x, 1) >>> e x >= 1 >>> '%s >= %s is the same as %s <= %s' % (e.gts, e.lts, e.lts, e.gts) 'x >= 1 is the same as 1 <= x'
Examples
One generally does not instantiate these classes directly, but uses various convenience methods:
>>> for f in [Ge, Gt, Le, Lt]: # convenience wrappers ... print(f(x, 2)) x >= 2 x > 2 x <= 2 x < 2
Another option is to use the Python inequality operators (>=, >, <=, <) directly. Their main advantage over the Ge, Gt, Le, and Lt counterparts, is that one can write a more “mathematical looking” statement rather than littering the math with oddball function calls. However there are certain (minor) caveats of which to be aware (search for ‘gotcha’, below).
>>> x >= 2 x >= 2 >>> _ == Ge(x, 2) True
However, it is also perfectly valid to instantiate a
*Than
class less succinctly and less conveniently:>>> Rel(x, 1, ">") x > 1 >>> Relational(x, 1, ">") x > 1
>>> StrictGreaterThan(x, 1) x > 1 >>> GreaterThan(x, 1) x >= 1 >>> LessThan(x, 1) x <= 1 >>> StrictLessThan(x, 1) x < 1
Notes
There are a couple of “gotchas” to be aware of when using Python’s operators.
The first is that what your write is not always what you get:
>>> 1 < x x > 1
Due to the order that Python parses a statement, it may not immediately find two objects comparable. When “1 < x” is evaluated, Python recognizes that the number 1 is a native number and that x is not. Because a native Python number does not know how to compare itself with a SymPy object Python will try the reflective operation, “x > 1” and that is the form that gets evaluated, hence returned.
If the order of the statement is important (for visual output to the console, perhaps), one can work around this annoyance in a couple ways:
 “sympify” the literal before comparison
>>> S(1) < x 1 < x
(2) use one of the wrappers or less succinct methods described above
>>> Lt(1, x) 1 < x >>> Relational(1, x, "<") 1 < x
The second gotcha involves writing equality tests between relationals when one or both sides of the test involve a literal relational:
>>> e = x < 1; e x < 1 >>> e == e # neither side is a literal True >>> e == x < 1 # expecting True, too False >>> e != x < 1 # expecting False x < 1 >>> x < 1 != x < 1 # expecting False or the same thing as before Traceback (most recent call last): ... TypeError: cannot determine truth value of Relational
The solution for this case is to wrap literal relationals in parentheses:
>>> e == (x < 1) True >>> e != (x < 1) False >>> (x < 1) != (x < 1) False
The third gotcha involves chained inequalities not involving ‘==’ or ‘!=’. Occasionally, one may be tempted to write:
>>> e = x < y < z Traceback (most recent call last): ... TypeError: symbolic boolean expression has no truth value.
Due to an implementation detail or decision of Python [R97], there is no way for SymPy to create a chained inequality with that syntax so one must use And:
>>> e = And(x < y, y < z) >>> type( e ) And >>> e (x < y) & (y < z)
Although this can also be done with the ‘&’ operator, it cannot be done with the ‘and’ operarator:
>>> (x < y) & (y < z) (x < y) & (y < z) >>> (x < y) and (y < z) Traceback (most recent call last): ... TypeError: cannot determine truth value of Relational
[R97] This implementation detail is that Python provides no reliable method to determine that a chained inequality is being built. Chained comparison operators are evaluated pairwise, using “and” logic (see http://docs.python.org/2/reference/expressions.html#notin). This is done in an efficient way, so that each object being compared is only evaluated once and the comparison can shortcircuit. For example,
1 > 2 > 3
is evaluated by Python as(1 > 2) and (2 > 3)
. Theand
operator coerces each side into a bool, returning the object itself when it shortcircuits. The bool of the –Than operators will raise TypeError on purpose, because SymPy cannot determine the mathematical ordering of symbolic expressions. Thus, if we were to computex > y > z
, withx
,y
, andz
being Symbols, Python converts the statement (roughly) into these steps: x > y > z
 (x > y) and (y > z)
 (GreaterThanObject) and (y > z)
 (GreaterThanObject.__nonzero__()) and (y > z)
 TypeError
Because of the “and” added at step 2, the statement gets turned into a weak ternary statement, and the first object’s __nonzero__ method will raise TypeError. Thus, creating a chained inequality is not possible.
In Python, there is no way to override theand
operator, or to control how it short circuits, so it is impossible to make something likex > y > z
work. There was a PEP to change this, PEP 335, but it was officially closed in March, 2012.
LessThan¶

class
sympy.core.relational.
LessThan
[source]¶ Class representations of inequalities.
The
*Than
classes represent inequal relationships, where the lefthand side is generally bigger or smaller than the righthand side. For example, the GreaterThan class represents an inequal relationship where the lefthand side is at least as big as the right side, if not bigger. In mathematical notation:lhs >= rhs
In total, there are four
*Than
classes, to represent the four inequalities:Class Name Symbol GreaterThan (>=) LessThan (<=) StrictGreaterThan (>) StrictLessThan (<) All classes take two arguments, lhs and rhs.
Signature Example Math equivalent GreaterThan(lhs, rhs) lhs >= rhs LessThan(lhs, rhs) lhs <= rhs StrictGreaterThan(lhs, rhs) lhs > rhs StrictLessThan(lhs, rhs) lhs < rhs In addition to the normal .lhs and .rhs of Relations,
*Than
inequality objects also have the .lts and .gts properties, which represent the “less than side” and “greater than side” of the operator. Use of .lts and .gts in an algorithm rather than .lhs and .rhs as an assumption of inequality direction will make more explicit the intent of a certain section of code, and will make it similarly more robust to client code changes:>>> from sympy import GreaterThan, StrictGreaterThan >>> from sympy import LessThan, StrictLessThan >>> from sympy import And, Ge, Gt, Le, Lt, Rel, S >>> from sympy.abc import x, y, z >>> from sympy.core.relational import Relational
>>> e = GreaterThan(x, 1) >>> e x >= 1 >>> '%s >= %s is the same as %s <= %s' % (e.gts, e.lts, e.lts, e.gts) 'x >= 1 is the same as 1 <= x'
Examples
One generally does not instantiate these classes directly, but uses various convenience methods:
>>> for f in [Ge, Gt, Le, Lt]: # convenience wrappers ... print(f(x, 2)) x >= 2 x > 2 x <= 2 x < 2
Another option is to use the Python inequality operators (>=, >, <=, <) directly. Their main advantage over the Ge, Gt, Le, and Lt counterparts, is that one can write a more “mathematical looking” statement rather than littering the math with oddball function calls. However there are certain (minor) caveats of which to be aware (search for ‘gotcha’, below).
>>> x >= 2 x >= 2 >>> _ == Ge(x, 2) True
However, it is also perfectly valid to instantiate a
*Than
class less succinctly and less conveniently:>>> Rel(x, 1, ">") x > 1 >>> Relational(x, 1, ">") x > 1
>>> StrictGreaterThan(x, 1) x > 1 >>> GreaterThan(x, 1) x >= 1 >>> LessThan(x, 1) x <= 1 >>> StrictLessThan(x, 1) x < 1
Notes
There are a couple of “gotchas” to be aware of when using Python’s operators.
The first is that what your write is not always what you get:
>>> 1 < x x > 1
Due to the order that Python parses a statement, it may not immediately find two objects comparable. When “1 < x” is evaluated, Python recognizes that the number 1 is a native number and that x is not. Because a native Python number does not know how to compare itself with a SymPy object Python will try the reflective operation, “x > 1” and that is the form that gets evaluated, hence returned.
If the order of the statement is important (for visual output to the console, perhaps), one can work around this annoyance in a couple ways:
 “sympify” the literal before comparison
>>> S(1) < x 1 < x
(2) use one of the wrappers or less succinct methods described above
>>> Lt(1, x) 1 < x >>> Relational(1, x, "<") 1 < x
The second gotcha involves writing equality tests between relationals when one or both sides of the test involve a literal relational:
>>> e = x < 1; e x < 1 >>> e == e # neither side is a literal True >>> e == x < 1 # expecting True, too False >>> e != x < 1 # expecting False x < 1 >>> x < 1 != x < 1 # expecting False or the same thing as before Traceback (most recent call last): ... TypeError: cannot determine truth value of Relational
The solution for this case is to wrap literal relationals in parentheses:
>>> e == (x < 1) True >>> e != (x < 1) False >>> (x < 1) != (x < 1) False
The third gotcha involves chained inequalities not involving ‘==’ or ‘!=’. Occasionally, one may be tempted to write:
>>> e = x < y < z Traceback (most recent call last): ... TypeError: symbolic boolean expression has no truth value.
Due to an implementation detail or decision of Python [R98], there is no way for SymPy to create a chained inequality with that syntax so one must use And:
>>> e = And(x < y, y < z) >>> type( e ) And >>> e (x < y) & (y < z)
Although this can also be done with the ‘&’ operator, it cannot be done with the ‘and’ operarator:
>>> (x < y) & (y < z) (x < y) & (y < z) >>> (x < y) and (y < z) Traceback (most recent call last): ... TypeError: cannot determine truth value of Relational
[R98] This implementation detail is that Python provides no reliable method to determine that a chained inequality is being built. Chained comparison operators are evaluated pairwise, using “and” logic (see http://docs.python.org/2/reference/expressions.html#notin). This is done in an efficient way, so that each object being compared is only evaluated once and the comparison can shortcircuit. For example,
1 > 2 > 3
is evaluated by Python as(1 > 2) and (2 > 3)
. Theand
operator coerces each side into a bool, returning the object itself when it shortcircuits. The bool of the –Than operators will raise TypeError on purpose, because SymPy cannot determine the mathematical ordering of symbolic expressions. Thus, if we were to computex > y > z
, withx
,y
, andz
being Symbols, Python converts the statement (roughly) into these steps: x > y > z
 (x > y) and (y > z)
 (GreaterThanObject) and (y > z)
 (GreaterThanObject.__nonzero__()) and (y > z)
 TypeError
Because of the “and” added at step 2, the statement gets turned into a weak ternary statement, and the first object’s __nonzero__ method will raise TypeError. Thus, creating a chained inequality is not possible.
In Python, there is no way to override theand
operator, or to control how it short circuits, so it is impossible to make something likex > y > z
work. There was a PEP to change this, PEP 335, but it was officially closed in March, 2012.
Unequality¶

class
sympy.core.relational.
Unequality
[source]¶ An unequal relation between two objects.
Represents that two objects are not equal. If they can be shown to be definitively equal, this will reduce to False; if definitively unequal, this will reduce to True. Otherwise, the relation is maintained as an Unequality object.
Examples
>>> from sympy import Ne >>> from sympy.abc import x, y >>> Ne(y, x+x**2) Ne(y, x**2 + x)
Notes
This class is not the same as the != operator. The != operator tests for exact structural equality between two expressions; this class compares expressions mathematically.
This class is effectively the inverse of Equality. As such, it uses the same algorithms, including any available \(_eval_Eq\) methods.
See also
StrictGreaterThan¶

class
sympy.core.relational.
StrictGreaterThan
[source]¶ Class representations of inequalities.
The
*Than
classes represent inequal relationships, where the lefthand side is generally bigger or smaller than the righthand side. For example, the GreaterThan class represents an inequal relationship where the lefthand side is at least as big as the right side, if not bigger. In mathematical notation:lhs >= rhs
In total, there are four
*Than
classes, to represent the four inequalities:Class Name Symbol GreaterThan (>=) LessThan (<=) StrictGreaterThan (>) StrictLessThan (<) All classes take two arguments, lhs and rhs.
Signature Example Math equivalent GreaterThan(lhs, rhs) lhs >= rhs LessThan(lhs, rhs) lhs <= rhs StrictGreaterThan(lhs, rhs) lhs > rhs StrictLessThan(lhs, rhs) lhs < rhs In addition to the normal .lhs and .rhs of Relations,
*Than
inequality objects also have the .lts and .gts properties, which represent the “less than side” and “greater than side” of the operator. Use of .lts and .gts in an algorithm rather than .lhs and .rhs as an assumption of inequality direction will make more explicit the intent of a certain section of code, and will make it similarly more robust to client code changes:>>> from sympy import GreaterThan, StrictGreaterThan >>> from sympy import LessThan, StrictLessThan >>> from sympy import And, Ge, Gt, Le, Lt, Rel, S >>> from sympy.abc import x, y, z >>> from sympy.core.relational import Relational
>>> e = GreaterThan(x, 1) >>> e x >= 1 >>> '%s >= %s is the same as %s <= %s' % (e.gts, e.lts, e.lts, e.gts) 'x >= 1 is the same as 1 <= x'
Examples
One generally does not instantiate these classes directly, but uses various convenience methods:
>>> for f in [Ge, Gt, Le, Lt]: # convenience wrappers ... print(f(x, 2)) x >= 2 x > 2 x <= 2 x < 2
Another option is to use the Python inequality operators (>=, >, <=, <) directly. Their main advantage over the Ge, Gt, Le, and Lt counterparts, is that one can write a more “mathematical looking” statement rather than littering the math with oddball function calls. However there are certain (minor) caveats of which to be aware (search for ‘gotcha’, below).
>>> x >= 2 x >= 2 >>> _ == Ge(x, 2) True
However, it is also perfectly valid to instantiate a
*Than
class less succinctly and less conveniently:>>> Rel(x, 1, ">") x > 1 >>> Relational(x, 1, ">") x > 1
>>> StrictGreaterThan(x, 1) x > 1 >>> GreaterThan(x, 1) x >= 1 >>> LessThan(x, 1) x <= 1 >>> StrictLessThan(x, 1) x < 1
Notes
There are a couple of “gotchas” to be aware of when using Python’s operators.
The first is that what your write is not always what you get:
>>> 1 < x x > 1
Due to the order that Python parses a statement, it may not immediately find two objects comparable. When “1 < x” is evaluated, Python recognizes that the number 1 is a native number and that x is not. Because a native Python number does not know how to compare itself with a SymPy object Python will try the reflective operation, “x > 1” and that is the form that gets evaluated, hence returned.
If the order of the statement is important (for visual output to the console, perhaps), one can work around this annoyance in a couple ways:
 “sympify” the literal before comparison
>>> S(1) < x 1 < x
(2) use one of the wrappers or less succinct methods described above
>>> Lt(1, x) 1 < x >>> Relational(1, x, "<") 1 < x
The second gotcha involves writing equality tests between relationals when one or both sides of the test involve a literal relational:
>>> e = x < 1; e x < 1 >>> e == e # neither side is a literal True >>> e == x < 1 # expecting True, too False >>> e != x < 1 # expecting False x < 1 >>> x < 1 != x < 1 # expecting False or the same thing as before Traceback (most recent call last): ... TypeError: cannot determine truth value of Relational
The solution for this case is to wrap literal relationals in parentheses:
>>> e == (x < 1) True >>> e != (x < 1) False >>> (x < 1) != (x < 1) False
The third gotcha involves chained inequalities not involving ‘==’ or ‘!=’. Occasionally, one may be tempted to write:
>>> e = x < y < z Traceback (most recent call last): ... TypeError: symbolic boolean expression has no truth value.
Due to an implementation detail or decision of Python [R99], there is no way for SymPy to create a chained inequality with that syntax so one must use And:
>>> e = And(x < y, y < z) >>> type( e ) And >>> e (x < y) & (y < z)
Although this can also be done with the ‘&’ operator, it cannot be done with the ‘and’ operarator:
>>> (x < y) & (y < z) (x < y) & (y < z) >>> (x < y) and (y < z) Traceback (most recent call last): ... TypeError: cannot determine truth value of Relational
[R99] This implementation detail is that Python provides no reliable method to determine that a chained inequality is being built. Chained comparison operators are evaluated pairwise, using “and” logic (see http://docs.python.org/2/reference/expressions.html#notin). This is done in an efficient way, so that each object being compared is only evaluated once and the comparison can shortcircuit. For example,
1 > 2 > 3
is evaluated by Python as(1 > 2) and (2 > 3)
. Theand
operator coerces each side into a bool, returning the object itself when it shortcircuits. The bool of the –Than operators will raise TypeError on purpose, because SymPy cannot determine the mathematical ordering of symbolic expressions. Thus, if we were to computex > y > z
, withx
,y
, andz
being Symbols, Python converts the statement (roughly) into these steps: x > y > z
 (x > y) and (y > z)
 (GreaterThanObject) and (y > z)
 (GreaterThanObject.__nonzero__()) and (y > z)
 TypeError
Because of the “and” added at step 2, the statement gets turned into a weak ternary statement, and the first object’s __nonzero__ method will raise TypeError. Thus, creating a chained inequality is not possible.
In Python, there is no way to override theand
operator, or to control how it short circuits, so it is impossible to make something likex > y > z
work. There was a PEP to change this, PEP 335, but it was officially closed in March, 2012.
StrictLessThan¶

class
sympy.core.relational.
StrictLessThan
[source]¶ Class representations of inequalities.
The
*Than
classes represent inequal relationships, where the lefthand side is generally bigger or smaller than the righthand side. For example, the GreaterThan class represents an inequal relationship where the lefthand side is at least as big as the right side, if not bigger. In mathematical notation:lhs >= rhs
In total, there are four
*Than
classes, to represent the four inequalities:Class Name Symbol GreaterThan (>=) LessThan (<=) StrictGreaterThan (>) StrictLessThan (<) All classes take two arguments, lhs and rhs.
Signature Example Math equivalent GreaterThan(lhs, rhs) lhs >= rhs LessThan(lhs, rhs) lhs <= rhs StrictGreaterThan(lhs, rhs) lhs > rhs StrictLessThan(lhs, rhs) lhs < rhs In addition to the normal .lhs and .rhs of Relations,
*Than
inequality objects also have the .lts and .gts properties, which represent the “less than side” and “greater than side” of the operator. Use of .lts and .gts in an algorithm rather than .lhs and .rhs as an assumption of inequality direction will make more explicit the intent of a certain section of code, and will make it similarly more robust to client code changes:>>> from sympy import GreaterThan, StrictGreaterThan >>> from sympy import LessThan, StrictLessThan >>> from sympy import And, Ge, Gt, Le, Lt, Rel, S >>> from sympy.abc import x, y, z >>> from sympy.core.relational import Relational
>>> e = GreaterThan(x, 1) >>> e x >= 1 >>> '%s >= %s is the same as %s <= %s' % (e.gts, e.lts, e.lts, e.gts) 'x >= 1 is the same as 1 <= x'
Examples
One generally does not instantiate these classes directly, but uses various convenience methods:
>>> for f in [Ge, Gt, Le, Lt]: # convenience wrappers ... print(f(x, 2)) x >= 2 x > 2 x <= 2 x < 2
Another option is to use the Python inequality operators (>=, >, <=, <) directly. Their main advantage over the Ge, Gt, Le, and Lt counterparts, is that one can write a more “mathematical looking” statement rather than littering the math with oddball function calls. However there are certain (minor) caveats of which to be aware (search for ‘gotcha’, below).
>>> x >= 2 x >= 2 >>> _ == Ge(x, 2) True
However, it is also perfectly valid to instantiate a
*Than
class less succinctly and less conveniently:>>> Rel(x, 1, ">") x > 1 >>> Relational(x, 1, ">") x > 1
>>> StrictGreaterThan(x, 1) x > 1 >>> GreaterThan(x, 1) x >= 1 >>> LessThan(x, 1) x <= 1 >>> StrictLessThan(x, 1) x < 1
Notes
There are a couple of “gotchas” to be aware of when using Python’s operators.
The first is that what your write is not always what you get:
>>> 1 < x x > 1
Due to the order that Python parses a statement, it may not immediately find two objects comparable. When “1 < x” is evaluated, Python recognizes that the number 1 is a native number and that x is not. Because a native Python number does not know how to compare itself with a SymPy object Python will try the reflective operation, “x > 1” and that is the form that gets evaluated, hence returned.
If the order of the statement is important (for visual output to the console, perhaps), one can work around this annoyance in a couple ways:
 “sympify” the literal before comparison
>>> S(1) < x 1 < x
(2) use one of the wrappers or less succinct methods described above
>>> Lt(1, x) 1 < x >>> Relational(1, x, "<") 1 < x
The second gotcha involves writing equality tests between relationals when one or both sides of the test involve a literal relational:
>>> e = x < 1; e x < 1 >>> e == e # neither side is a literal True >>> e == x < 1 # expecting True, too False >>> e != x < 1 # expecting False x < 1 >>> x < 1 != x < 1 # expecting False or the same thing as before Traceback (most recent call last): ... TypeError: cannot determine truth value of Relational
The solution for this case is to wrap literal relationals in parentheses:
>>> e == (x < 1) True >>> e != (x < 1) False >>> (x < 1) != (x < 1) False
The third gotcha involves chained inequalities not involving ‘==’ or ‘!=’. Occasionally, one may be tempted to write:
>>> e = x < y < z Traceback (most recent call last): ... TypeError: symbolic boolean expression has no truth value.
Due to an implementation detail or decision of Python [R100], there is no way for SymPy to create a chained inequality with that syntax so one must use And:
>>> e = And(x < y, y < z) >>> type( e ) And >>> e (x < y) & (y < z)
Although this can also be done with the ‘&’ operator, it cannot be done with the ‘and’ operarator:
>>> (x < y) & (y < z) (x < y) & (y < z) >>> (x < y) and (y < z) Traceback (most recent call last): ... TypeError: cannot determine truth value of Relational
[R100] This implementation detail is that Python provides no reliable method to determine that a chained inequality is being built. Chained comparison operators are evaluated pairwise, using “and” logic (see http://docs.python.org/2/reference/expressions.html#notin). This is done in an efficient way, so that each object being compared is only evaluated once and the comparison can shortcircuit. For example,
1 > 2 > 3
is evaluated by Python as(1 > 2) and (2 > 3)
. Theand
operator coerces each side into a bool, returning the object itself when it shortcircuits. The bool of the –Than operators will raise TypeError on purpose, because SymPy cannot determine the mathematical ordering of symbolic expressions. Thus, if we were to computex > y > z
, withx
,y
, andz
being Symbols, Python converts the statement (roughly) into these steps: x > y > z
 (x > y) and (y > z)
 (GreaterThanObject) and (y > z)
 (GreaterThanObject.__nonzero__()) and (y > z)
 TypeError
Because of the “and” added at step 2, the statement gets turned into a weak ternary statement, and the first object’s __nonzero__ method will raise TypeError. Thus, creating a chained inequality is not possible.
In Python, there is no way to override theand
operator, or to control how it short circuits, so it is impossible to make something likex > y > z
work. There was a PEP to change this, PEP 335, but it was officially closed in March, 2012.
multidimensional¶
vectorize¶

class
sympy.core.multidimensional.
vectorize
(*mdargs)[source]¶ Generalizes a function taking scalars to accept multidimensional arguments.
For example
>>> from sympy import diff, sin, symbols, Function >>> from sympy.core.multidimensional import vectorize >>> x, y, z = symbols('x y z') >>> f, g, h = list(map(Function, 'fgh'))
>>> @vectorize(0) ... def vsin(x): ... return sin(x)
>>> vsin([1, x, y]) [sin(1), sin(x), sin(y)]
>>> @vectorize(0, 1) ... def vdiff(f, y): ... return diff(f, y)
>>> vdiff([f(x, y, z), g(x, y, z), h(x, y, z)], [x, y, z]) [[Derivative(f(x, y, z), x), Derivative(f(x, y, z), y), Derivative(f(x, y, z), z)], [Derivative(g(x, y, z), x), Derivative(g(x, y, z), y), Derivative(g(x, y, z), z)], [Derivative(h(x, y, z), x), Derivative(h(x, y, z), y), Derivative(h(x, y, z), z)]]
function¶
Lambda¶

class
sympy.core.function.
Lambda
[source]¶ Lambda(x, expr) represents a lambda function similar to Python’s ‘lambda x: expr’. A function of several variables is written as Lambda((x, y, …), expr).
A simple example:
>>> from sympy import Lambda >>> from sympy.abc import x >>> f = Lambda(x, x**2) >>> f(4) 16
For multivariate functions, use:
>>> from sympy.abc import y, z, t >>> f2 = Lambda((x, y, z, t), x + y**z + t**z) >>> f2(1, 2, 3, 4) 73
A handy shortcut for lots of arguments:
>>> p = x, y, z >>> f = Lambda(p, x + y*z) >>> f(*p) x + y*z

bound_symbols
¶ The variables used in the internal representation of the function

expr
¶ The return value of the function

is_identity
¶ Return
True
if thisLambda
is an identity function.

variables
¶ The variables used in the internal representation of the function

WildFunction¶

class
sympy.core.function.
WildFunction
(name, **assumptions)[source]¶ A WildFunction function matches any function (with its arguments).
Examples
>>> from sympy import WildFunction, Function, cos >>> from sympy.abc import x, y >>> F = WildFunction('F') >>> f = Function('f') >>> F.nargs Naturals0 >>> x.match(F) >>> F.match(F) {F_: F_} >>> f(x).match(F) {F_: f(x)} >>> cos(x).match(F) {F_: cos(x)} >>> f(x, y).match(F) {F_: f(x, y)}
To match functions with a given number of arguments, set
nargs
to the desired value at instantiation:>>> F = WildFunction('F', nargs=2) >>> F.nargs {2} >>> f(x).match(F) >>> f(x, y).match(F) {F_: f(x, y)}
To match functions with a range of arguments, set
nargs
to a tuple containing the desired number of arguments, e.g. ifnargs = (1, 2)
then functions with 1 or 2 arguments will be matched.>>> F = WildFunction('F', nargs=(1, 2)) >>> F.nargs {1, 2} >>> f(x).match(F) {F_: f(x)} >>> f(x, y).match(F) {F_: f(x, y)} >>> f(x, y, 1).match(F)
Derivative¶

class
sympy.core.function.
Derivative
[source]¶ Carries out differentiation of the given expression with respect to symbols.
Examples
>>> from sympy import Derivative, Function, symbols, Subs >>> from sympy.abc import x, y >>> f, g = symbols('f g', cls=Function)
>>> Derivative(x**2, x, evaluate=True) 2*x
Denesting of derivatives retains the ordering of variables:
>>> Derivative(Derivative(f(x, y), y), x) Derivative(f(x, y), y, x)
Contiguously identical symbols are merged into a tuple giving the symbol and the count:
>>> Derivative(f(x), x, x, y, x) Derivative(f(x), (x, 2), y, x)
If the derivative cannot be performed, and evaluate is True, the order of the variables of differentiation will be made canonical:
>>> Derivative(f(x, y), y, x, evaluate=True) Derivative(f(x, y), x, y)
Derivatives with respect to undefined functions can be calculated:
>>> Derivative(f(x)**2, f(x), evaluate=True) 2*f(x)
Such derivatives will show up when the chain rule is used to evalulate a derivative:
>>> f(g(x)).diff(x) Derivative(f(g(x)), g(x))*Derivative(g(x), x)
Substitution is used to represent derivatives of functions with arguments that are not symbols or functions:
>>> f(2*x + 3).diff(x) == 2*Subs(f(y).diff(y), y, 2*x + 3) True
Notes
Simplification of highorder derivatives:
Because there can be a significant amount of simplification that can be done when multiple differentiations are performed, results will be automatically simplified in a fairly conservative fashion unless the keyword
simplify
is set to False.>>> from sympy import cos, sin, sqrt, diff, Function, symbols >>> from sympy.abc import x, y, z >>> f, g = symbols('f,g', cls=Function)
>>> e = sqrt((x + 1)**2 + x) >>> diff(e, (x, 5), simplify=False).count_ops() 136 >>> diff(e, (x, 5)).count_ops() 30
Ordering of variables:
If evaluate is set to True and the expression cannot be evaluated, the list of differentiation symbols will be sorted, that is, the expression is assumed to have continuous derivatives up to the order asked.
Derivative wrt nonSymbols:
For the most part, one may not differentiate wrt nonsymbols. For example, we do not allow differentiation wrt \(x*y\) because there are multiple ways of structurally defining where x*y appears in an expression: a very strict definition would make (x*y*z).diff(x*y) == 0. Derivatives wrt defined functions (like cos(x)) are not allowed, either:
>>> (x*y*z).diff(x*y) Traceback (most recent call last): ... ValueError: Can't calculate derivative wrt x*y.
To make it easier to work with variational calculus, however, derivatives wrt AppliedUndef and Derivatives are allowed. For example, in the EulerLagrange method one may write F(t, u, v) where u = f(t) and v = f’(t). These variables can be written explicity as functions of time:
>>> from sympy.abc import t >>> F = Function('F') >>> U = f(t) >>> V = U.diff(t)
The derivative wrt f(t) can be obtained directly:
>>> direct = F(t, U, V).diff(U)
When differentiation wrt a nonSymbol is attempted, the nonSymbol is temporarily converted to a Symbol while the differentiation is performed and the same answer is obtained:
>>> indirect = F(t, U, V).subs(U, x).diff(x).subs(x, U) >>> assert direct == indirect
The implication of this nonsymbol replacement is that all functions are treated as independent of other functions and the symbols are independent of the functions that contain them:
>>> x.diff(f(x)) 0 >>> g(x).diff(f(x)) 0
It also means that derivatives are assumed to depend only on the variables of differentiation, not on anything contained within the expression being differentiated:
>>> F = f(x) >>> Fx = F.diff(x) >>> Fx.diff(F) # derivative depends on x, not F 0 >>> Fxx = Fx.diff(x) >>> Fxx.diff(Fx) # derivative depends on x, not Fx 0
The last example can be made explicit by showing the replacement of Fx in Fxx with y:
>>> Fxx.subs(Fx, y) Derivative(y, x)
Since that in itself will evaluate to zero, differentiating wrt Fx will also be zero:
>>> _.doit() 0
Replacing undefined functions with concrete expressions
One must be careful to replace undefined functions with expressions that contain variables consistent with the function definition and the variables of differentiation or else insconsistent result will be obtained. Consider the following example:
>>> eq = f(x)*g(y) >>> eq.subs(f(x), x*y).diff(x, y).doit() y*Derivative(g(y), y) + g(y) >>> eq.diff(x, y).subs(f(x), x*y).doit() y*Derivative(g(y), y)
The results differ because \(f(x)\) was replaced with an expression that involved both variables of differentiation. In the abstract case, differentiation of \(f(x)\) by \(y\) is 0; in the concrete case, the presence of \(y\) made that derivative nonvanishing and produced the extra \(g(y)\) term.
Defining differentiation for an object
An object must define ._eval_derivative(symbol) method that returns the differentiation result. This function only needs to consider the nontrivial case where expr contains symbol and it should call the diff() method internally (not _eval_derivative); Derivative should be the only one to call _eval_derivative.
Any class can allow derivatives to be taken with respect to itself (while indicating its scalar nature). See the docstring of Expr._diff_wrt.
See also
_sort_variable_count

as_finite_difference
(points=1, x0=None, wrt=None)[source]¶ Expresses a Derivative instance as a finite difference.
Parameters: points : sequence or coefficient, optional
If sequence: discrete values (length >= order+1) of the independent variable used for generating the finite difference weights. If it is a coefficient, it will be used as the stepsize for generating an equidistant sequence of length order+1 centered around
x0
. Default: 1 (stepsize 1)x0 : number or Symbol, optional
the value of the independent variable (
wrt
) at which the derivative is to be approximated. Default: same aswrt
.wrt : Symbol, optional
“with respect to” the variable for which the (partial) derivative is to be approximated for. If not provided it is required that the derivative is ordinary. Default:
None
.Examples
>>> from sympy import symbols, Function, exp, sqrt, Symbol >>> x, h = symbols('x h') >>> f = Function('f') >>> f(x).diff(x).as_finite_difference() f(x  1/2) + f(x + 1/2)
The default step size and number of points are 1 and
order + 1
respectively. We can change the step size by passing a symbol as a parameter:>>> f(x).diff(x).as_finite_difference(h) f(h/2 + x)/h + f(h/2 + x)/h
We can also specify the discretized values to be used in a sequence:
>>> f(x).diff(x).as_finite_difference([x, x+h, x+2*h]) 3*f(x)/(2*h) + 2*f(h + x)/h  f(2*h + x)/(2*h)
The algorithm is not restricted to use equidistant spacing, nor do we need to make the approximation around
x0
, but we can get an expression estimating the derivative at an offset:>>> e, sq2 = exp(1), sqrt(2) >>> xl = [xh, x+h, x+e*h] >>> f(x).diff(x, 1).as_finite_difference(xl, x+h*sq2) # doctest: +ELLIPSIS 2*h*((h + sqrt(2)*h)/(2*h)  (sqrt(2)*h + h)/(2*h))*f(E*h + x)/...
Partial derivatives are also supported:
>>> y = Symbol('y') >>> d2fdxdy=f(x,y).diff(x,y) >>> d2fdxdy.as_finite_difference(wrt=x) Derivative(f(x  1/2, y), y) + Derivative(f(x + 1/2, y), y)
We can apply
as_finite_difference
toDerivative
instances in compound expressions usingreplace
:>>> (1 + 42**f(x).diff(x)).replace(lambda arg: arg.is_Derivative, ... lambda arg: arg.as_finite_difference()) 42**(f(x  1/2) + f(x + 1/2)) + 1

diff¶

sympy.core.function.
diff
(f, *symbols, **kwargs)[source]¶ Differentiate f with respect to symbols.
This is just a wrapper to unify .diff() and the Derivative class; its interface is similar to that of integrate(). You can use the same shortcuts for multiple variables as with Derivative. For example, diff(f(x), x, x, x) and diff(f(x), x, 3) both return the third derivative of f(x).
You can pass evaluate=False to get an unevaluated Derivative class. Note that if there are 0 symbols (such as diff(f(x), x, 0), then the result will be the function (the zeroth derivative), even if evaluate=False.
Examples
>>> from sympy import sin, cos, Function, diff >>> from sympy.abc import x, y >>> f = Function('f')
>>> diff(sin(x), x) cos(x) >>> diff(f(x), x, x, x) Derivative(f(x), (x, 3)) >>> diff(f(x), x, 3) Derivative(f(x), (x, 3)) >>> diff(sin(x)*cos(y), x, 2, y, 2) sin(x)*cos(y)
>>> type(diff(sin(x), x)) cos >>> type(diff(sin(x), x, evaluate=False)) <class 'sympy.core.function.Derivative'> >>> type(diff(sin(x), x, 0)) sin >>> type(diff(sin(x), x, 0, evaluate=False)) sin
>>> diff(sin(x)) cos(x) >>> diff(sin(x*y)) Traceback (most recent call last): ... ValueError: specify differentiation variables to differentiate sin(x*y)
Note that
diff(sin(x))
syntax is meant only for convenience in interactive sessions and should be avoided in library code.References
http://reference.wolfram.com/legacy/v5_2/BuiltinFunctions/AlgebraicComputation/Calculus/D.html
FunctionClass¶

class
sympy.core.function.
FunctionClass
(*args, **kwargs)[source]¶ Base class for function classes. FunctionClass is a subclass of type.
Use Function(‘<function name>’ [ , signature ]) to create undefined function classes.

nargs
¶ Return a set of the allowed number of arguments for the function.
Examples
>>> from sympy.core.function import Function >>> from sympy.abc import x, y >>> f = Function('f')
If the function can take any number of arguments, the set of whole numbers is returned:
>>> Function('f').nargs Naturals0
If the function was initialized to accept one or more arguments, a corresponding set will be returned:
>>> Function('f', nargs=1).nargs {1} >>> Function('f', nargs=(2, 1)).nargs {1, 2}
The undefined function, after application, also has the nargs attribute; the actual number of arguments is always available by checking the
args
attribute:>>> f = Function('f') >>> f(1).nargs Naturals0 >>> len(f(1).args) 1

Function¶

class
sympy.core.function.
Function
[source]¶ Base class for applied mathematical functions.
It also serves as a constructor for undefined function classes.
Examples
First example shows how to use Function as a constructor for undefined function classes:
>>> from sympy import Function, Symbol >>> x = Symbol('x') >>> f = Function('f') >>> g = Function('g')(x) >>> f f >>> f(x) f(x) >>> g g(x) >>> f(x).diff(x) Derivative(f(x), x) >>> g.diff(x) Derivative(g(x), x)
Assumptions can be passed to Function.
>>> f_real = Function('f', real=True) >>> f_real(x).is_real True
Note that assumptions on a function are unrelated to the assumptions on the variable it is called on. If you want to add a relationship, subclass Function and define the appropriate
_eval_is_assumption
methods.In the following example Function is used as a base class for
my_func
that represents a mathematical function my_func. Suppose that it is well known, that my_func(0) is 1 and my_func at infinity goes to 0, so we want those two simplifications to occur automatically. Suppose also that my_func(x) is real exactly when x is real. Here is an implementation that honours those requirements:>>> from sympy import Function, S, oo, I, sin >>> class my_func(Function): ... ... @classmethod ... def eval(cls, x): ... if x.is_Number: ... if x is S.Zero: ... return S.One ... elif x is S.Infinity: ... return S.Zero ... ... def _eval_is_real(self): ... return self.args[0].is_real ... >>> x = S('x') >>> my_func(0) + sin(0) 1 >>> my_func(oo) 0 >>> my_func(3.54).n() # Not yet implemented for my_func. my_func(3.54) >>> my_func(I).is_real False
In order for
my_func
to become useful, several other methods would need to be implemented. See source code of some of the already implemented functions for more complete examples.Also, if the function can take more than one argument, then
nargs
must be defined, e.g. ifmy_func
can take one or two arguments then,>>> class my_func(Function): ... nargs = (1, 2) ... >>>

is_commutative
¶ Returns whether the function is commutative.

Note
Not all functions are the same
SymPy defines many functions (like cos
and factorial
). It also
allows the user to create generic functions which act as argument
holders. Such functions are created just like symbols:
>>> from sympy import Function, cos
>>> from sympy.abc import x
>>> f = Function('f')
>>> f(2) + f(x)
f(2) + f(x)
If you want to see which functions appear in an expression you can use the atoms method:
>>> e = (f(x) + cos(x) + 2)
>>> e.atoms(Function)
{f(x), cos(x)}
If you just want the function you defined, not SymPy functions, the thing to search for is AppliedUndef:
>>> from sympy.core.function import AppliedUndef
>>> e.atoms(AppliedUndef)
{f(x)}
Subs¶

class
sympy.core.function.
Subs
[source]¶ Represents unevaluated substitutions of an expression.
Subs(expr, x, x0)
receives 3 arguments: an expression, a variable or list of distinct variables and a point or list of evaluation points corresponding to those variables.Subs
objects are generally useful to represent unevaluated derivatives calculated at a point.The variables may be expressions, but they are subjected to the limitations of subs(), so it is usually a good practice to use only symbols for variables, since in that case there can be no ambiguity.
There’s no automatic expansion  use the method .doit() to effect all possible substitutions of the object and also of objects inside the expression.
When evaluating derivatives at a point that is not a symbol, a Subs object is returned. One is also able to calculate derivatives of Subs objects  in this case the expression is always expanded (for the unevaluated form, use Derivative()).
Examples
>>> from sympy import Subs, Function, sin, cos >>> from sympy.abc import x, y, z >>> f = Function('f')
Subs are created when a particular substitution cannot be made. The x in the derivative cannot be replaced with 0 because 0 is not a valid variables of differentiation:
>>> f(x).diff(x).subs(x, 0) Subs(Derivative(f(x), x), x, 0)
Once f is known, the derivative and evaluation at 0 can be done:
>>> _.subs(f, sin).doit() == sin(x).diff(x).subs(x, 0) == cos(0) True
Subs can also be created directly with one or more variables:
>>> Subs(f(x)*sin(y) + z, (x, y), (0, 1)) Subs(z + f(x)*sin(y), (x, y), (0, 1)) >>> _.doit() z + f(0)*sin(1)
Notes
In order to allow expressions to combine before doit is done, a representation of the Subs expression is used internally to make expressions that are superficially different compare the same:
>>> a, b = Subs(x, x, 0), Subs(y, y, 0) >>> a + b 2*Subs(x, x, 0)
This can lead to unexpected consequences when using methods like \(has\) that are cached:
>>> s = Subs(x, x, 0) >>> s.has(x), s.has(y) (True, False) >>> ss = s.subs(x, y) >>> ss.has(x), ss.has(y) (True, False) >>> s, ss (Subs(x, x, 0), Subs(y, y, 0))

bound_symbols
¶ The variables to be evaluated

expr
¶ The expression on which the substitution operates

point
¶ The values for which the variables are to be substituted

variables
¶ The variables to be evaluated

expand¶

sympy.core.function.
expand
(e, deep=True, modulus=None, power_base=True, power_exp=True, mul=True, log=True, multinomial=True, basic=True, **hints)[source]¶ Expand an expression using methods given as hints.
Hints evaluated unless explicitly set to False are:
basic
,log
,multinomial
,mul
,power_base
, andpower_exp
The following hints are supported but not applied unless set to True:complex
,func
, andtrig
. In addition, the following metahints are supported by some or all of the other hints:frac
,numer
,denom
,modulus
, andforce
.deep
is supported by all hints. Additionally, subclasses of Expr may define their own hints or metahints.The
basic
hint is used for any special rewriting of an object that should be done automatically (along with the other hints likemul
) when expand is called. This is a catchall hint to handle any sort of expansion that may not be described by the existing hint names. To use this hint an object should override the_eval_expand_basic
method. Objects may also define their own expand methods, which are not run by default. See the API section below.If
deep
is set toTrue
(the default), things like arguments of functions are recursively expanded. Usedeep=False
to only expand on the top level.If the
force
hint is used, assumptions about variables will be ignored in making the expansion.Hints
These hints are run by default
Mul
Distributes multiplication over addition:
>>> from sympy import cos, exp, sin >>> from sympy.abc import x, y, z >>> (y*(x + z)).expand(mul=True) x*y + y*z
Multinomial
Expand (x + y + …)**n where n is a positive integer.
>>> ((x + y + z)**2).expand(multinomial=True) x**2 + 2*x*y + 2*x*z + y**2 + 2*y*z + z**2
Power_exp
Expand addition in exponents into multiplied bases.
>>> exp(x + y).expand(power_exp=True) exp(x)*exp(y) >>> (2**(x + y)).expand(power_exp=True) 2**x*2**y
Power_base
Split powers of multiplied bases.
This only happens by default if assumptions allow, or if the
force
metahint is used:>>> ((x*y)**z).expand(power_base=True) (x*y)**z >>> ((x*y)**z).expand(power_base=True, force=True) x**z*y**z >>> ((2*y)**z).expand(power_base=True) 2**z*y**z
Note that in some cases where this expansion always holds, SymPy performs it automatically:
>>> (x*y)**2 x**2*y**2
Log
Pull out power of an argument as a coefficient and split logs products into sums of logs.
Note that these only work if the arguments of the log function have the proper assumptions–the arguments must be positive and the exponents must be real–or else the
force
hint must be True:>>> from sympy import log, symbols >>> log(x**2*y).expand(log=True) log(x**2*y) >>> log(x**2*y).expand(log=True, force=True) 2*log(x) + log(y) >>> x, y = symbols('x,y', positive=True) >>> log(x**2*y).expand(log=True) 2*log(x) + log(y)
Basic
This hint is intended primarily as a way for custom subclasses to enable expansion by default.
These hints are not run by default:
Complex
Split an expression into real and imaginary parts.
>>> x, y = symbols('x,y') >>> (x + y).expand(complex=True) re(x) + re(y) + I*im(x) + I*im(y) >>> cos(x).expand(complex=True) I*sin(re(x))*sinh(im(x)) + cos(re(x))*cosh(im(x))
Note that this is just a wrapper around
as_real_imag()
. Most objects that wish to redefine_eval_expand_complex()
should consider redefiningas_real_imag()
instead.Func
Expand other functions.
>>> from sympy import gamma >>> gamma(x + 1).expand(func=True) x*gamma(x)
Trig
Do trigonometric expansions.
>>> cos(x + y).expand(trig=True) sin(x)*sin(y) + cos(x)*cos(y) >>> sin(2*x).expand(trig=True) 2*sin(x)*cos(x)
Note that the forms of
sin(n*x)
andcos(n*x)
in terms ofsin(x)
andcos(x)
are not unique, due to the identity \(\sin^2(x) + \cos^2(x) = 1\). The current implementation uses the form obtained from Chebyshev polynomials, but this may change. See this MathWorld article for more information.Notes
You can shut off unwanted methods:
>>> (exp(x + y)*(x + y)).expand() x*exp(x)*exp(y) + y*exp(x)*exp(y) >>> (exp(x + y)*(x + y)).expand(power_exp=False) x*exp(x + y) + y*exp(x + y) >>> (exp(x + y)*(x + y)).expand(mul=False) (x + y)*exp(x)*exp(y)
Use deep=False to only expand on the top level:
>>> exp(x + exp(x + y)).expand() exp(x)*exp(exp(x)*exp(y)) >>> exp(x + exp(x + y)).expand(deep=False) exp(x)*exp(exp(x + y))
Hints are applied in an arbitrary, but consistent order (in the current implementation, they are applied in alphabetical order, except multinomial comes before mul, but this may change). Because of this, some hints may prevent expansion by other hints if they are applied first. For example,
mul
may distribute multiplications and preventlog
andpower_base
from expanding them. Also, ifmul
is applied beforemultinomial`, the expression might not be fully distributed. The solution is to use the various ``expand_hint
helper functions or to usehint=False
to this function to finely control which hints are applied. Here are some examples:>>> from sympy import expand, expand_mul, expand_power_base >>> x, y, z = symbols('x,y,z', positive=True) >>> expand(log(x*(y + z))) log(x) + log(y + z)
Here, we see that
log
was applied beforemul
. To get the mul expanded form, either of the following will work:>>> expand_mul(log(x*(y + z))) log(x*y + x*z) >>> expand(log(x*(y + z)), log=False) log(x*y + x*z)
A similar thing can happen with the
power_base
hint:>>> expand((x*(y + z))**x) (x*y + x*z)**x
To get the
power_base
expanded form, either of the following will work:>>> expand((x*(y + z))**x, mul=False) x**x*(y + z)**x >>> expand_power_base((x*(y + z))**x) x**x*(y + z)**x >>> expand((x + y)*y/x) y + y**2/x
The parts of a rational expression can be targeted:
>>> expand((x + y)*y/x/(x + 1), frac=True) (x*y + y**2)/(x**2 + x) >>> expand((x + y)*y/x/(x + 1), numer=True) (x*y + y**2)/(x*(x + 1)) >>> expand((x + y)*y/x/(x + 1), denom=True) y*(x + y)/(x**2 + x)
The
modulus
metahint can be used to reduce the coefficients of an expression postexpansion:>>> expand((3*x + 1)**2) 9*x**2 + 6*x + 1 >>> expand((3*x + 1)**2, modulus=5) 4*x**2 + x + 1
Either
expand()
the function or.expand()
the method can be used. Both are equivalent:>>> expand((x + 1)**2) x**2 + 2*x + 1 >>> ((x + 1)**2).expand() x**2 + 2*x + 1
Api
Objects can define their own expand hints by defining
_eval_expand_hint()
. The function should take the form:def _eval_expand_hint(self, **hints): # Only apply the method to the toplevel expression ...
See also the example below. Objects should define
_eval_expand_hint()
methods only ifhint
applies to that specific object. The generic_eval_expand_hint()
method defined in Expr will handle the noop case.Each hint should be responsible for expanding that hint only. Furthermore, the expansion should be applied to the toplevel expression only.
expand()
takes care of the recursion that happens whendeep=True
.You should only call
_eval_expand_hint()
methods directly if you are 100% sure that the object has the method, as otherwise you are liable to get unexpectedAttributeError``s. Note, again, that you do not need to recursively apply the hint to args of your object: this is handled automatically by ``expand()
._eval_expand_hint()
should generally not be used at all outside of an_eval_expand_hint()
method. If you want to apply a specific expansion from within another method, use the publicexpand()
function, method, orexpand_hint()
functions.In order for expand to work, objects must be rebuildable by their args, i.e.,
obj.func(*obj.args) == obj
must hold.Expand methods are passed
**hints
so that expand hints may use ‘metahints’–hints that control how different expand methods are applied. For example, theforce=True
hint described above that causesexpand(log=True)
to ignore assumptions is such a metahint. Thedeep
metahint is handled exclusively byexpand()
and is not passed to_eval_expand_hint()
methods.Note that expansion hints should generally be methods that perform some kind of ‘expansion’. For hints that simply rewrite an expression, use the .rewrite() API.
Examples
>>> from sympy import Expr, sympify >>> class MyClass(Expr): ... def __new__(cls, *args): ... args = sympify(args) ... return Expr.__new__(cls, *args) ... ... def _eval_expand_double(self, **hints): ... ''' ... Doubles the args of MyClass. ... ... If there more than four args, doubling is not performed, ... unless force=True is also used (False by default). ... ''' ... force = hints.pop('force', False) ... if not force and len(self.args) > 4: ... return self ... return self.func(*(self.args + self.args)) ... >>> a = MyClass(1, 2, MyClass(3, 4)) >>> a MyClass(1, 2, MyClass(3, 4)) >>> a.expand(double=True) MyClass(1, 2, MyClass(3, 4, 3, 4), 1, 2, MyClass(3, 4, 3, 4)) >>> a.expand(double=True, deep=False) MyClass(1, 2, MyClass(3, 4), 1, 2, MyClass(3, 4))
>>> b = MyClass(1, 2, 3, 4, 5) >>> b.expand(double=True) MyClass(1, 2, 3, 4, 5) >>> b.expand(double=True, force=True) MyClass(1, 2, 3, 4, 5, 1, 2, 3, 4, 5)
See also
expand_log
,expand_mul
,expand_multinomial
,expand_complex
,expand_trig
,expand_power_base
,expand_power_exp
,expand_func
,hyperexpand
count_ops¶

sympy.core.function.
count_ops
(expr, visual=False)[source]¶ Return a representation (integer or expression) of the operations in expr.
If
visual
isFalse
(default) then the sum of the coefficients of the visual expression will be returned.If
visual
isTrue
then the number of each type of operation is shown with the core class types (or their virtual equivalent) multiplied by the number of times they occur.If expr is an iterable, the sum of the op counts of the items will be returned.
Examples
>>> from sympy.abc import a, b, x, y >>> from sympy import sin, count_ops
Although there isn’t a SUB object, minus signs are interpreted as either negations or subtractions:
>>> (x  y).count_ops(visual=True) SUB >>> (x).count_ops(visual=True) NEG
Here, there are two Adds and a Pow:
>>> (1 + a + b**2).count_ops(visual=True) 2*ADD + POW
In the following, an Add, Mul, Pow and two functions:
>>> (sin(x)*x + sin(x)**2).count_ops(visual=True) ADD + MUL + POW + 2*SIN
for a total of 5:
>>> (sin(x)*x + sin(x)**2).count_ops(visual=False) 5
Note that “what you type” is not always what you get. The expression 1/x/y is translated by sympy into 1/(x*y) so it gives a DIV and MUL rather than two DIVs:
>>> (1/x/y).count_ops(visual=True) DIV + MUL
The visual option can be used to demonstrate the difference in operations for expressions in different forms. Here, the Horner representation is compared with the expanded form of a polynomial:
>>> eq=x*(1 + x*(2 + x*(3 + x))) >>> count_ops(eq.expand(), visual=True)  count_ops(eq, visual=True) MUL + 3*POW
The count_ops function also handles iterables:
>>> count_ops([x, sin(x), None, True, x + 2], visual=False) 2 >>> count_ops([x, sin(x), None, True, x + 2], visual=True) ADD + SIN >>> count_ops({x: sin(x), x + 2: y + 1}, visual=True) 2*ADD + SIN
expand_mul¶

sympy.core.function.
expand_mul
(expr, deep=True)[source]¶ Wrapper around expand that only uses the mul hint. See the expand docstring for more information.
Examples
>>> from sympy import symbols, expand_mul, exp, log >>> x, y = symbols('x,y', positive=True) >>> expand_mul(exp(x+y)*(x+y)*log(x*y**2)) x*exp(x + y)*log(x*y**2) + y*exp(x + y)*log(x*y**2)
expand_log¶

sympy.core.function.
expand_log
(expr, deep=True, force=False)[source]¶ Wrapper around expand that only uses the log hint. See the expand docstring for more information.
Examples
>>> from sympy import symbols, expand_log, exp, log >>> x, y = symbols('x,y', positive=True) >>> expand_log(exp(x+y)*(x+y)*log(x*y**2)) (x + y)*(log(x) + 2*log(y))*exp(x + y)
expand_func¶
expand_trig¶

sympy.core.function.
expand_trig
(expr, deep=True)[source]¶ Wrapper around expand that only uses the trig hint. See the expand docstring for more information.
Examples
>>> from sympy import expand_trig, sin >>> from sympy.abc import x, y >>> expand_trig(sin(x+y)*(x+y)) (x + y)*(sin(x)*cos(y) + sin(y)*cos(x))
expand_complex¶

sympy.core.function.
expand_complex
(expr, deep=True)[source]¶ Wrapper around expand that only uses the complex hint. See the expand docstring for more information.
Examples
>>> from sympy import expand_complex, exp, sqrt, I >>> from sympy.abc import z >>> expand_complex(exp(z)) I*exp(re(z))*sin(im(z)) + exp(re(z))*cos(im(z)) >>> expand_complex(sqrt(I)) sqrt(2)/2 + sqrt(2)*I/2
See also
Expr.as_real_imag
expand_multinomial¶

sympy.core.function.
expand_multinomial
(expr, deep=True)[source]¶ Wrapper around expand that only uses the multinomial hint. See the expand docstring for more information.
Examples
>>> from sympy import symbols, expand_multinomial, exp >>> x, y = symbols('x y', positive=True) >>> expand_multinomial((x + exp(x + 1))**2) x**2 + 2*x*exp(x + 1) + exp(2*x + 2)
expand_power_exp¶
expand_power_base¶

sympy.core.function.
expand_power_base
(expr, deep=True, force=False)[source]¶ Wrapper around expand that only uses the power_base hint.
See the expand docstring for more information.
A wrapper to expand(power_base=True) which separates a power with a base that is a Mul into a product of powers, without performing any other expansions, provided that assumptions about the power’s base and exponent allow.
deep=False (default is True) will only apply to the toplevel expression.
force=True (default is False) will cause the expansion to ignore assumptions about the base and exponent. When False, the expansion will only happen if the base is nonnegative or the exponent is an integer.
>>> from sympy.abc import x, y, z >>> from sympy import expand_power_base, sin, cos, exp
>>> (x*y)**2 x**2*y**2
>>> (2*x)**y (2*x)**y >>> expand_power_base(_) 2**y*x**y
>>> expand_power_base((x*y)**z) (x*y)**z >>> expand_power_base((x*y)**z, force=True) x**z*y**z >>> expand_power_base(sin((x*y)**z), deep=False) sin((x*y)**z) >>> expand_power_base(sin((x*y)**z), force=True) sin(x**z*y**z)
>>> expand_power_base((2*sin(x))**y + (2*cos(x))**y) 2**y*sin(x)**y + 2**y*cos(x)**y
>>> expand_power_base((2*exp(y))**x) 2**x*exp(y)**x
>>> expand_power_base((2*cos(x))**y) 2**y*cos(x)**y
Notice that sums are left untouched. If this is not the desired behavior, apply full
expand()
to the expression:>>> expand_power_base(((x+y)*z)**2) z**2*(x + y)**2 >>> (((x+y)*z)**2).expand() x**2*z**2 + 2*x*y*z**2 + y**2*z**2
>>> expand_power_base((2*y)**(1+z)) 2**(z + 1)*y**(z + 1) >>> ((2*y)**(1+z)).expand() 2*2**z*y*y**z
nfloat¶

sympy.core.function.
nfloat
(expr, n=15, exponent=False)[source]¶ Make all Rationals in expr Floats except those in exponents (unless the exponents flag is set to True).
Examples
>>> from sympy.core.function import nfloat >>> from sympy.abc import x, y >>> from sympy import cos, pi, sqrt >>> nfloat(x**4 + x/2 + cos(pi/3) + 1 + sqrt(y)) x**4 + 0.5*x + sqrt(y) + 1.5 >>> nfloat(x**4 + sqrt(y), exponent=True) x**4.0 + y**0.5
evalf¶
N¶

sympy.core.evalf.
N
(x, n=15, **options)[source]¶ Calls x.evalf(n, **options).
Both .n() and N() are equivalent to .evalf(); use the one that you like better. See also the docstring of .evalf() for information on the options.
Examples
>>> from sympy import Sum, oo, N >>> from sympy.abc import k >>> Sum(1/k**k, (k, 1, oo)) Sum(k**(k), (k, 1, oo)) >>> N(_, 4) 1.291
containers¶
Tuple¶

class
sympy.core.containers.
Tuple
[source]¶ Wrapper around the builtin tuple object
The Tuple is a subclass of Basic, so that it works well in the SymPy framework. The wrapped tuple is available as self.args, but you can also access elements or slices with [:] syntax.
Parameters: sympify : bool
If
False
,sympify
is not called onargs
. This can be used for speedups for very large tuples where the elements are known to already be sympy objects.Example
>>> from sympy import symbols >>> from sympy.core.containers import Tuple >>> a, b, c, d = symbols('a b c d') >>> Tuple(a, b, c)[1:] (b, c) >>> Tuple(a, b, c).subs(a, d) (d, b, c)
Dict¶

class
sympy.core.containers.
Dict
[source]¶ Wrapper around the builtin dict object
The Dict is a subclass of Basic, so that it works well in the SymPy framework. Because it is immutable, it may be included in sets, but its values must all be given at instantiation and cannot be changed afterwards. Otherwise it behaves identically to the Python dict.
>>> from sympy.core.containers import Dict
>>> D = Dict({1: 'one', 2: 'two'}) >>> for key in D: ... if key == 1: ... print('%s %s' % (key, D[key])) 1 one
The args are sympified so the 1 and 2 are Integers and the values are Symbols. Queries automatically sympify args so the following work:
>>> 1 in D True >>> D.has('one') # searches keys and values True >>> 'one' in D # not in the keys False >>> D[1] one
compatibility¶
iterable¶

sympy.core.compatibility.
iterable
(i, exclude=((<class 'str'>, ), <class 'dict'>, <class 'sympy.core.compatibility.NotIterable'>))[source]¶ Return a boolean indicating whether
i
is SymPy iterable. True also indicates that the iterator is finite, i.e. you e.g. call list(…) on the instance.When SymPy is working with iterables, it is almost always assuming that the iterable is not a string or a mapping, so those are excluded by default. If you want a pure Python definition, make exclude=None. To exclude multiple items, pass them as a tuple.
You can also set the _iterable attribute to True or False on your class, which will override the checks here, including the exclude test.
As a rule of thumb, some SymPy functions use this to check if they should recursively map over an object. If an object is technically iterable in the Python sense but does not desire this behavior (e.g., because its iteration is not finite, or because iteration might induce an unwanted computation), it should disable it by setting the _iterable attribute to False.
See also: is_sequence
Examples
>>> from sympy.utilities.iterables import iterable >>> from sympy import Tuple >>> things = [[1], (1,), set([1]), Tuple(1), (j for j in [1, 2]), {1:2}, '1', 1] >>> for i in things: ... print('%s %s' % (iterable(i), type(i))) True <... 'list'> True <... 'tuple'> True <... 'set'> True <class 'sympy.core.containers.Tuple'> True <... 'generator'> False <... 'dict'> False <... 'str'> False <... 'int'>
>>> iterable({}, exclude=None) True >>> iterable({}, exclude=str) True >>> iterable("no", exclude=str) False
is_sequence¶

sympy.core.compatibility.
is_sequence
(i, include=None)[source]¶ Return a boolean indicating whether
i
is a sequence in the SymPy sense. If anything that fails the test below should be included as being a sequence for your application, set ‘include’ to that object’s type; multiple types should be passed as a tuple of types.Note: although generators can generate a sequence, they often need special handling to make sure their elements are captured before the generator is exhausted, so these are not included by default in the definition of a sequence.
See also: iterable
Examples
>>> from sympy.utilities.iterables import is_sequence >>> from types import GeneratorType >>> is_sequence([]) True >>> is_sequence(set()) False >>> is_sequence('abc') False >>> is_sequence('abc', include=str) True >>> generator = (c for c in 'abc') >>> is_sequence(generator) False >>> is_sequence(generator, include=(str, GeneratorType)) True
as_int¶

sympy.core.compatibility.
as_int
(n)[source]¶ Convert the argument to a builtin integer.
The return value is guaranteed to be equal to the input. ValueError is raised if the input has a nonintegral value.
Examples
>>> from sympy.core.compatibility import as_int >>> from sympy import sqrt >>> 3.0 3.0 >>> as_int(3.0) # convert to int and test for equality 3 >>> int(sqrt(10)) 3 >>> as_int(sqrt(10)) Traceback (most recent call last): ... ValueError: ... is not an integer
exprtools¶
gcd_terms¶

sympy.core.exprtools.
gcd_terms
(terms, isprimitive=False, clear=True, fraction=True)[source]¶ Compute the GCD of
terms
and put them together.terms
can be an expression or a nonBasic sequence of expressions which will be handled as though they are terms from a sum.If
isprimitive
is True the _gcd_terms will not run the primitive method on the terms.clear
controls the removal of integers from the denominator of an Add expression. When True (default), all numerical denominator will be cleared; when False the denominators will be cleared only if all terms had numerical denominators other than 1.fraction
, when True (default), will put the expression over a common denominator.Examples
>>> from sympy.core import gcd_terms >>> from sympy.abc import x, y
>>> gcd_terms((x + 1)**2*y + (x + 1)*y**2) y*(x + 1)*(x + y + 1) >>> gcd_terms(x/2 + 1) (x + 2)/2 >>> gcd_terms(x/2 + 1, clear=False) x/2 + 1 >>> gcd_terms(x/2 + y/2, clear=False) (x + y)/2 >>> gcd_terms(x/2 + 1/x) (x**2 + 2)/(2*x) >>> gcd_terms(x/2 + 1/x, fraction=False) (x + 2/x)/2 >>> gcd_terms(x/2 + 1/x, fraction=False, clear=False) x/2 + 1/x
>>> gcd_terms(x/2/y + 1/x/y) (x**2 + 2)/(2*x*y) >>> gcd_terms(x/2/y + 1/x/y, clear=False) (x**2/2 + 1)/(x*y) >>> gcd_terms(x/2/y + 1/x/y, clear=False, fraction=False) (x/2 + 1/x)/y
The
clear
flag was ignored in this case because the returned expression was a rational expression, not a simple sum.See also
factor_terms¶

sympy.core.exprtools.
factor_terms
(expr, radical=False, clear=False, fraction=False, sign=True)[source]¶ Remove common factors from terms in all arguments without changing the underlying structure of the expr. No expansion or simplification (and no processing of noncommutatives) is performed.
If radical=True then a radical common to all terms will be factored out of any Add subexpressions of the expr.
If clear=False (default) then coefficients will not be separated from a single Add if they can be distributed to leave one or more terms with integer coefficients.
If fraction=True (default is False) then a common denominator will be constructed for the expression.
If sign=True (default) then even if the only factor in common is a 1, it will be factored out of the expression.
Examples
>>> from sympy import factor_terms, Symbol >>> from sympy.abc import x, y >>> factor_terms(x + x*(2 + 4*y)**3) x*(8*(2*y + 1)**3 + 1) >>> A = Symbol('A', commutative=False) >>> factor_terms(x*A + x*A + x*y*A) x*(y*A + 2*A)
When
clear
is False, a rational will only be factored out of an Add expression if all terms of the Add have coefficients that are fractions:>>> factor_terms(x/2 + 1, clear=False) x/2 + 1 >>> factor_terms(x/2 + 1, clear=True) (x + 2)/2
If a 1 is all that can be factored out, to not factor it out, the flag
sign
must be False:>>> factor_terms(x  y) (x + y) >>> factor_terms(x  y, sign=False) x  y >>> factor_terms(2*x  2*y, sign=False) 2*(x + y)
See also